[Feature]: Add milestone-level issue tracking without task-per-issue conversion

Start by reading the bundled GitHub extension and its speckit.github.taskstoissues command, then compare the related proposals #4370, #4421, and #4423. The issue leaves the packaging choice open and calls for validation, previews, confirmation, idempotency, conflict handling, documentation, and representative tests. Done means an opt-in workflow meets the listed acceptance criteria without mirroring task and issue state.

Problem Statement

The bundled github extension currently offers speckit.github.taskstoissues, which creates one GitHub issue for every T### entry in tasks.md. That is useful for task-level issue tracking, but it does not fit teams that deliberately keep fine-grained execution state in tasks.md and use a smaller number of GitHub issues for bounded delivery milestones, blockers, pull requests, and durable acceptance evidence.

Without a supported bridge, these teams must either create an issue per task, duplicate task checklists and acceptance criteria in GitHub, or maintain an ad hoc mapping that can drift from spec.md, plan.md, and tasks.md.

This is distinct from #4370. That proposal retains one issue per task and groups those issues into native GitHub Milestones. This proposal avoids task issues and maps many requirements/design sections/tasks to one delivery issue.

Proposed Solution

Provide an opt-in milestone-level tracking workflow for the GitHub integration, either as a new namespaced command or as an officially documented preset if that is the preferred extension boundary.

The workflow would maintain a versioned tracking.md in the active feature directory. Each stable, anchored milestone entry would map:

• a bounded delivery outcome;
• requirement IDs or anchors from spec.md;
• design sections from plan.md;
• explicit task IDs or ranges from tasks.md; and
• the actual GitHub issue URL returned after creation.

An epic issue would link to tracking.md as the feature index. Each delivery issue would link back to its stable mapping anchor and the underlying Spec Kit artifacts. Implementation pull requests would link the delivery issue and name the task IDs they complete.

The separation of authority is important:

• spec.md owns normative requirements and acceptance criteria;
• plan.md owns technical design;
• tasks.md owns fine-grained implementation state;
• GitHub delivery issues own coordination state, blockers, pull requests, and durable acceptance evidence.

The workflow should not copy task checkboxes or acceptance criteria into issue bodies and should not mirror state automatically. A checked task does not prove milestone acceptance, and closing an issue must not rewrite tasks.md.

Before external writes, the command should preview the intended epic and delivery issues and require explicit confirmation. Repeated execution should be idempotent, use a feature-qualified milestone identity rather than bare M1/T001 identifiers, read back real URLs, and fail on ambiguous or conflicting mappings.

Projects should choose either task-per-issue conversion or milestone-level tracking for a feature. Running both should require an explicit override or be rejected to prevent duplicate tracking systems.

Alternatives Considered

• Use speckit.github.taskstoissues: Creates substantially more issues and duplicates the fine-grained ledger already maintained in tasks.md.
• Use #4370's native GitHub Milestone grouping: Improves organization but still creates one issue per task; native GitHub Milestones also remain repository-scoped.
• Maintain the mapping entirely outside Spec Kit: Works locally, but every team must recreate feature resolution, idempotency, validation, and safe GitHub mutation behavior.
• Automatic bidirectional state synchronization: Rejected because task completion and delivery acceptance are different claims and cannot be inferred safely from one another.

Component

Agent integrations (command files, workflows)

AI Agent (if applicable)

All agents

Use Cases

1. A feature has 40 implementation tasks but only four independently reviewable delivery milestones.
2. A migration needs milestone issues for blockers, rollback evidence, and qualification while implementation progress remains in tasks.md.
3. A refactoring spans interfaces and compatibility guarantees but does not benefit from dozens of GitHub task issues.
4. A team needs durable traceability from requirements through design and tasks to GitHub coordination without copying normative content.

Acceptance Criteria

• The workflow is opt-in and does not change the provider-neutral core SDD flow.
• It resolves the active feature's spec.md, plan.md, and tasks.md and validates referenced IDs/anchors before any GitHub write.
• It can generate or validate a versioned tracking map with stable milestone anchors.
• It previews all intended external writes and requires explicit confirmation.
• It creates or reuses one epic and one issue per mapped delivery milestone, then records the real returned URLs.
• Repeated execution is idempotent and feature-qualified identifiers cannot collide across features.
• Issue bodies link to repository artifacts without copying task checkboxes or normative acceptance criteria.
• No automatic state mirroring treats task completion as milestone acceptance or issue closure as task completion.
• The workflow detects or rejects simultaneous task-per-issue and milestone-level tracking for the same feature.
• Documentation explains the authority boundaries, comparison with taskstoissues, and whether the supported packaging is a GitHub-extension command or preset.
• Representative positive and counter-tests cover ambiguous mappings, stale issue URLs, duplicate execution, and partial acceptance.

Additional Context

The concept has been captured locally as a generic tracking template and process rule so it can be tested in real projects before an implementation PR. The newly created fork is available at https://github.com/metaneutrons/spec-kit for future development.

Related work:

• #4370: task issues grouped into native GitHub Milestones
• #4421: bundled GitHub extension
• #4423: removal of the former core taskstoissues command

AI Disclosure

OpenAI Codex using a GPT-5-based model in interactive, human-supervised agent mode; the reasoning-effort setting was not exposed. AI assistance covered reviewing the current extension documentation and related issues, comparing the proposals, and drafting this issue. Fabian Schmieder determined the intended tracking model and authorized the fork and submission.