---
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