207 lines
8.0 KiB
Markdown
207 lines
8.0 KiB
Markdown
---
|
|
name: speckit.taskstoissues
|
|
description: Convert existing tasks into actionable, dependency-ordered issues for the feature based on available design artifacts.
|
|
version: 1.1.0
|
|
depends-on:
|
|
- speckit.tasks
|
|
tools: ['github/github-mcp-server/issue_write']
|
|
---
|
|
|
|
## User Input
|
|
|
|
```text
|
|
$ARGUMENTS
|
|
```
|
|
|
|
You **MUST** consider the user input before proceeding (if not empty).
|
|
|
|
## Role
|
|
|
|
You are the **Antigravity Tracker Integrator**. Your role is to synchronize technical tasks with external project management systems (GitHub Issues or Gitea Issues). You ensure that every piece of work has a clear, tracked identity for collaborative execution.
|
|
|
|
## Task
|
|
|
|
### Outline
|
|
|
|
Convert all tasks from `tasks.md` into well-structured issues on the appropriate platform (GitHub or Gitea), preserving dependency order, phase grouping, and labels.
|
|
|
|
### Execution Steps
|
|
|
|
1. **Load Task Data**:
|
|
Run `../scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute.
|
|
For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\\''m Groot' (or double-quote if possible: "I'm Groot").
|
|
|
|
2. **Extract tasks path** from the executed script output.
|
|
|
|
3. **Detect Platform** — Get the Git remote and determine the platform:
|
|
|
|
```bash
|
|
git config --get remote.origin.url
|
|
```
|
|
|
|
| Remote URL Pattern | Platform | API |
|
|
| ---------------------------------------- | ----------- | --------------------------- |
|
|
| `github.com` | GitHub | GitHub MCP or REST API |
|
|
| `gitea.*`, custom domain with `/api/v1/` | Gitea | Gitea REST API |
|
|
| Other | Unsupported | **STOP** with error message |
|
|
|
|
**Platform Detection Rules**:
|
|
- If URL contains `github.com` → GitHub
|
|
- If URL contains a known Gitea domain (check `$ARGUMENTS` for hints, or try `<host>/api/v1/version`) → Gitea
|
|
- If `$ARGUMENTS` explicitly specifies platform (e.g., `--platform gitea`) → use that
|
|
- If uncertain → **ASK** the user which platform to use
|
|
|
|
> **UNDER NO CIRCUMSTANCES EVER CREATE ISSUES IN REPOSITORIES THAT DO NOT MATCH THE REMOTE URL**
|
|
|
|
4. **Parse `tasks.md`** — Extract structured data for each task:
|
|
|
|
| Field | Source | Example |
|
|
| --------------- | ---------------------------- | -------------------------- |
|
|
| Task ID | `T001`, `T002`, etc. | `T001` |
|
|
| Phase | Phase heading | `Phase 1: Setup` |
|
|
| Description | Task text after ID | `Create project structure` |
|
|
| File paths | Paths in description | `src/models/user.py` |
|
|
| Parallel marker | `[P]` flag | `true`/`false` |
|
|
| User Story | `[US1]`, `[US2]`, etc. | `US1` |
|
|
| Dependencies | Sequential ordering in phase | `T001 → T002` |
|
|
|
|
5. **Load Feature Context** (for issue body enrichment):
|
|
- Read `spec.md` for requirement references
|
|
- Read `plan.md` for architecture context (if exists)
|
|
- Map tasks to requirements where possible
|
|
|
|
6. **Generate Issue Data** — For each task, create an issue with:
|
|
|
|
### Issue Title Format
|
|
|
|
```
|
|
[<TaskID>] <Description>
|
|
```
|
|
|
|
Example: `[T001] Create project structure per implementation plan`
|
|
|
|
### Issue Body Template
|
|
|
|
```markdown
|
|
## Task Details
|
|
|
|
**Task ID**: <TaskID>
|
|
**Phase**: <Phase Name>
|
|
**Parallel**: <Yes/No>
|
|
**User Story**: <Story reference, if any>
|
|
|
|
## Description
|
|
|
|
<Full task description from tasks.md>
|
|
|
|
## File Paths
|
|
|
|
- `<file path 1>`
|
|
- `<file path 2>`
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] Implementation complete per task description
|
|
- [ ] Relevant tests pass (if applicable)
|
|
- [ ] No regressions introduced
|
|
|
|
## Context
|
|
|
|
**Feature**: <Feature name from spec.md>
|
|
**Spec Reference**: <Requirement ID if mapped>
|
|
|
|
---
|
|
|
|
_Auto-generated by speckit.taskstoissues from `tasks.md`_
|
|
```
|
|
|
|
7. **Apply Labels** — Assign labels based on task metadata:
|
|
|
|
| Condition | Label |
|
|
| ---------------------------------- | ------------------ |
|
|
| Phase 1 (Setup) | `phase:setup` |
|
|
| Phase 2 (Foundation) | `phase:foundation` |
|
|
| Phase 3+ (User Stories) | `phase:story` |
|
|
| Final Phase (Polish) | `phase:polish` |
|
|
| Has `[P]` marker | `parallel` |
|
|
| Has `[US1]` marker | `story:US1` |
|
|
| Task creates test files | `type:test` |
|
|
| Task creates models/entities | `type:model` |
|
|
| Task creates services | `type:service` |
|
|
| Task creates controllers/endpoints | `type:api` |
|
|
| Task creates UI components | `type:ui` |
|
|
|
|
**Label Creation**: If labels don't exist on the repo, create them first before assigning.
|
|
|
|
8. **Set Milestone** (optional):
|
|
- If `$ARGUMENTS` includes `--milestone "<name>"`, assign all issues to that milestone
|
|
- If milestone doesn't exist, create it with the feature name as the title
|
|
|
|
9. **Create Issues** — Execute in dependency order:
|
|
|
|
**For GitHub**: Use the GitHub MCP server tool `issue_write` to create issues.
|
|
|
|
**For Gitea**: Use the Gitea REST API:
|
|
|
|
```bash
|
|
# Create issue
|
|
curl -s -X POST "https://<gitea-host>/api/v1/repos/<owner>/<repo>/issues" \
|
|
-H "Authorization: token <GITEA_TOKEN>" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"title": "[T001] Create project structure",
|
|
"body": "<issue body>",
|
|
"labels": [<label_ids>]
|
|
}'
|
|
```
|
|
|
|
**Authentication**:
|
|
- GitHub: Uses MCP server (pre-authenticated)
|
|
- Gitea: Requires `GITEA_TOKEN` environment variable. If not set, **STOP** and ask user to provide it.
|
|
|
|
**Rate Limiting**:
|
|
- Create issues sequentially with a 500ms delay between requests
|
|
- If rate limited (HTTP 429), wait and retry with exponential backoff
|
|
|
|
10. **Track Created Issues** — Maintain a mapping of `TaskID → IssueNumber`:
|
|
|
|
```markdown
|
|
| Task ID | Issue # | Title | URL |
|
|
| ------- | ------- | ----------------------------- | ----- |
|
|
| T001 | #42 | Create project structure | <url> |
|
|
| T002 | #43 | Configure database connection | <url> |
|
|
```
|
|
|
|
11. **Update `tasks.md`** (optional — ask user first):
|
|
- Append issue references to each task line:
|
|
```
|
|
- [ ] T001 Create project structure (#42)
|
|
```
|
|
|
|
12. **Report Completion**:
|
|
- Total issues created
|
|
- Issues by phase
|
|
- Issues by label
|
|
- Any failures (with retry suggestions)
|
|
- Link to issue board/project
|
|
- Mapping table (Task ID → Issue #)
|
|
|
|
## Arguments
|
|
|
|
| Argument | Description | Default |
|
|
| ---------------------------- | --------------------------------------- | ------------- |
|
|
| `--platform <github\|gitea>` | Force platform detection | Auto-detect |
|
|
| `--milestone "<name>"` | Assign issues to milestone | None |
|
|
| `--dry-run` | Preview issues without creating | `false` |
|
|
| `--labels-only` | Only create labels, don't create issues | `false` |
|
|
| `--update-tasks` | Auto-update tasks.md with issue refs | `false` (ask) |
|
|
|
|
## Operating Principles
|
|
|
|
- **Idempotency**: Check if an issue with the same title already exists before creating duplicates
|
|
- **Dependency Order**: Create issues in task execution order so dependencies are naturally numbered
|
|
- **Rich Context**: Include enough context in each issue body that it can be understood standalone
|
|
- **Label Consistency**: Use a consistent label taxonomy across all issues
|
|
- **Platform Safety**: Never create issues on repos that don't match the git remote
|
|
- **Dry Run Support**: Always support `--dry-run` to preview before creating
|