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

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 Feature Request: Milestone grouping extension for taskstoissues #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

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

Acceptance Criteria

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:

Feature Request: Milestone grouping extension for taskstoissues #4370: task issues grouped into native GitHub Milestones
[Feature]: Add a bundled github extension for taskstoissues #4421: bundled GitHub extension
[Feature]: Remove taskstoissues from the core command set #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.

Feature assessment — milestone-issue-tracking · Stage 1/5: Intake

Idea Intake: Milestone-level issue tracking

Slug: milestone-issue-tracking
Created: 2026-11-06T14:06:00Z
Source: [Feature]: Add milestone-level issue tracking without task-per-issue conversion #5284
Type: improvement

Idea (as captured)

“Provide an opt-in milestone-level tracking workflow for the GitHub integration ... [that] avoids task issues and maps many requirements/design sections/tasks to one delivery issue.”

The proposal asks for a versioned tracking.md in the active feature directory, a feature-index epic, one issue per delivery milestone (not one per task), explicit preview-before-write confirmation, idempotent reruns, and clear authority boundaries: spec.md for requirements, plan.md for design, tasks.md for execution state, GitHub issues for coordination evidence.

It explicitly distinguishes itself from #4370 (which still keeps one issue per task and groups them via GitHub Milestones).

Restated

The request is to add an opt-in GitHub workflow that tracks delivery at milestone level instead of task level, while preserving task-level state in tasks.md. It aims to maintain traceability from Spec Kit artifacts to fewer, bounded GitHub delivery issues without duplicating normative content or mirroring state automatically.

Origin & Context

Raised by: metaneutrons (issue [Feature]: Add milestone-level issue tracking without task-per-issue conversion #5284)
Trigger: Existing speckit.github.taskstoissues is useful for task-level issue creation, but teams using tasks.md as the fine-grained ledger want a smaller issue surface for milestone coordination and acceptance evidence.

First-Glance Unknowns

[NEEDS CLARIFICATION: Should this ship as a new command in the bundled github extension, or as an officially supported preset/workflow composition?]
[NEEDS CLARIFICATION: What is the canonical milestone identifier format in tracking.md to guarantee feature-qualified uniqueness across repositories and reruns?]
[NEEDS CLARIFICATION: How should stale or deleted mapped GitHub issue URLs be detected and reconciled on rerun?]
[NEEDS CLARIFICATION: What compatibility behavior is expected when a project already used task-per-issue conversion for the same feature?]

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for #5284 · copilot · gpt53codex · 51.2 AIC · ⌖ 0.766 AIC · ⊞ 26.4K · ◷

Feature assessment — milestone-issue-tracking · Stage 2/5: Research

Idea Research: Milestone-level issue tracking

Slug: milestone-issue-tracking
Created: 2026-11-06T14:07:00Z
Evidence confidence (overall): medium

Users & Demand

Teams with many implementation tasks but few reviewable delivery outcomes report a mismatch with one-issue-per-task conversion and want milestone-level GitHub coordination instead — [source: [Feature]: Add milestone-level issue tracking without task-per-issue conversion #5284] (confidence: medium)
Prior feature requests around task-to-issues and milestone grouping indicate recurring demand for GitHub coordination models beyond flat issue lists — [source: Feature Request: Milestone grouping extension for taskstoissues #4370, [Feature]: Add a bundled github extension for taskstoissues #4421, [Feature]: Remove taskstoissues from the core command set #4423] (confidence: medium)
Broad user-segment size in this repository is not quantified in telemetry in the provided artifacts — [source: ASSUMPTION] (confidence: low)

Prior Art

The bundled GitHub extension already owns provider-specific issue-tracker behavior and explicitly positions itself as opt-in, making extension-local expansion a consistent architectural path — [source: extensions/github/README.md] (confidence: high)
speckit.github.taskstoissues establishes existing patterns for feature resolution, GitHub remote validation, deduplication/idempotency expectations, and hook-based integration points — [source: extensions/github/commands/speckit.github.taskstoissues.md] (confidence: high)
Feature Request: Milestone grouping extension for taskstoissues #4370 proposed milestone grouping while still creating one issue per task; it was closed not planned. The current request narrows to a different model (milestone-level issues replacing task issues for a feature), which addresses a distinct tracking philosophy but overlaps in naming and user expectations — [source: Feature Request: Milestone grouping extension for taskstoissues #4370, [Feature]: Add milestone-level issue tracking without task-per-issue conversion #5284] (confidence: medium)

Market & Context

The project has already moved GitHub issue conversion out of core into a bundled opt-in extension, reinforcing a direction where repository-tracker workflows are pluggable rather than mandatory core behavior — [source: CHANGELOG.md (1.3.0 entry “feat!: remove taskstoissues from core”), extensions/github/README.md] (confidence: high)
Doing nothing preserves a simple, proven taskstoissues path but keeps a gap for teams that need lower issue cardinality with explicit milestone acceptance evidence — [source: [Feature]: Add milestone-level issue tracking without task-per-issue conversion #5284] (confidence: medium)

Data & Constraints

Existing extension tests emphasize migration safety, command registration across integrations, deduplication behavior, and hook contract continuity; any new workflow must match this quality bar — [source: tests/extensions/github/test_github_extension.py] (confidence: high)
Proposal constraints explicitly reject automatic bidirectional state mirroring between tasks and issues; this reduces accidental authority conflicts but requires clear operator discipline and documentation — [source: [Feature]: Add milestone-level issue tracking without task-per-issue conversion #5284] (confidence: high)
The request references an external fork URL in additional context. No independent validation of that fork’s implementation quality was performed in this run — [source: [Feature]: Add milestone-level issue tracking without task-per-issue conversion #5284; ASSUMPTION] (confidence: low)

Evidence Against the Idea

Added workflow complexity (tracking map lifecycle, conflict detection, stale URL handling, dual-mode safeguards) may increase maintenance cost compared with the current single conversion command — [source: extensions/github/commands/speckit.github.taskstoissues.md, tests/extensions/github/test_github_extension.py; ASSUMPTION] (confidence: medium)
The repository already has one established path (taskstoissues); introducing a second tracking model can fragment guidance and increase support load if boundaries are not strict — [source: extensions/github/README.md; ASSUMPTION] (confidence: medium)
Direct quantitative evidence of multi-team demand is limited in the provided artifacts (few cited issues, no usage telemetry) — [source: [Feature]: Add milestone-level issue tracking without task-per-issue conversion #5284, Feature Request: Milestone grouping extension for taskstoissues #4370, [Feature]: Add a bundled github extension for taskstoissues #4421, [Feature]: Remove taskstoissues from the core command set #4423] (confidence: medium)

Gaps & Open Questions

[NEEDS CLARIFICATION: Minimum supported schema for tracking.md anchors and ID validation rules.]
[NEEDS CLARIFICATION: Whether milestone-level tracking should be a first-party command, a preset recipe, or both with one canonical implementation owner.]
[NEEDS CLARIFICATION: How reruns behave when mapped issues are manually edited/closed/deleted.]
[NEEDS CLARIFICATION: Test matrix expectations for conflicting task-per-issue and milestone-level modes in the same feature.]

Sources

[Feature]: Add milestone-level issue tracking without task-per-issue conversion #5284 (host: github.com, policy: allowlisted)
Feature Request: Milestone grouping extension for taskstoissues #4370 (host: github.com, policy: allowlisted)
[Feature]: Add a bundled github extension for taskstoissues #4421 (host: github.com, policy: allowlisted)
[Feature]: Remove taskstoissues from the core command set #4423 (host: github.com, policy: allowlisted)
Repository file: extensions/github/README.md
Repository file: extensions/github/commands/speckit.github.taskstoissues.md
Repository file: tests/extensions/github/test_github_extension.py
Repository file: CHANGELOG.md

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for #5284 · copilot · gpt53codex · 51.2 AIC · ⌖ 0.766 AIC · ⊞ 26.4K · ◷

Feature assessment — milestone-issue-tracking · Stage 3/5: Problem

Problem Definition: Delivery tracking granularity mismatch

Slug: milestone-issue-tracking
Created: 2026-11-06T14:08:00Z
Inputs used: intake.md | research.md

Problem Statement

Teams that intentionally keep fine-grained execution state in tasks.md currently lack a supported way to represent delivery-level coordination in GitHub without creating one issue per task. This mismatch creates either issue sprawl or duplicated/fragile manual mappings, reducing traceability quality and increasing coordination overhead.

Affected Users & Stakeholders

Users: Maintainers and feature owners running Spec Kit with GitHub issue tracking — they must choose between high issue volume and ad hoc milestone mapping.
Users: Contributors and reviewers — they need bounded delivery issues for blockers, PR linkage, and acceptance evidence that are not equivalent to task checkboxes.
Stakeholders: Project maintainers/release leads — they need durable, auditable linkage from requirements/design/tasks to delivery outcomes.

Goals

Provide an opt-in workflow that tracks delivery at milestone granularity without forcing task-per-issue conversion.
Preserve authority boundaries between spec.md, plan.md, tasks.md, and GitHub issues.
Keep reruns safe and idempotent with deterministic mapping and conflict detection.

Non-Goals

Automatic mirroring of task checkbox state into issue state.
Treating issue closure as proof of task completion.
Replacing provider-neutral core SDD flow with GitHub-specific behavior.

Success Metrics

Feature adopters can create/reuse one epic and one issue per mapped delivery milestone with stable back-links to artifacts (baseline: unsupported today).
Reruns of the workflow do not duplicate issues for the same feature-qualified milestone identity (baseline: N/A for this model).
Mapping validation fails fast on ambiguous/conflicting references before external writes (baseline: no first-party milestone-map validator).
Documentation clearly differentiates milestone-level tracking from taskstoissues and explains when each should be used (baseline: only task-to-issues workflow documented).

Cost of Inaction

Teams needing milestone-level coordination continue using either high-cardinality task issues or unofficial manual mapping files/processes. That increases drift risk between planning artifacts and GitHub coordination state, weakens auditability of delivery acceptance, and raises maintenance burden per team.

Open Questions

[NEEDS CLARIFICATION: Canonical tracking-map schema, including anchor identity and versioning strategy.]
[NEEDS CLARIFICATION: Packaging boundary (new extension command vs documented preset) and long-term ownership.]
[NEEDS CLARIFICATION: Reconciliation behavior for stale/deleted mapped issue URLs.]
[NEEDS CLARIFICATION: Explicit conflict policy when task-per-issue and milestone-level workflows are both invoked for one feature.]

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for #5284 · copilot · gpt53codex · 51.2 AIC · ⌖ 0.766 AIC · ⊞ 26.4K · ◷

Feature assessment — milestone-issue-tracking · Stage 4/5: Concept

Concept: Milestone-level GitHub delivery mapping

Slug: milestone-issue-tracking
Created: 2026-11-06T14:09:00Z
Recommended option: Option A — First-party milestone-map command in github extension

Options

Option A — First-party milestone-map command in `github` extension

Sketch: Add an opt-in command alongside speckit.github.taskstoissues that validates a feature-scoped tracking.md, previews epic/milestone issue writes, creates or reuses mapped delivery issues, and records returned issue URLs back into the tracking map without copying task checklists or normative acceptance text.
Appetite: medium
Trade-offs: Strongest consistency with existing extension architecture and quality standards; highest implementation surface (schema validation, reconciliation, idempotency guards, documentation, test coverage).
Rabbit holes: Stable identifier design, stale URL reconciliation semantics, and robust conflict detection when both tracking modes are attempted.

Option B — Preset/workflow-only orchestration over existing commands

Sketch: Publish an official preset/process that keeps tracking.md and guides maintainers through manual or semi-automated GitHub issue creation, reusing existing commands where possible.
Appetite: small
Trade-offs: Fastest to deliver and lowest code burden; weaker guarantees for idempotency/validation and more room for drift because enforcement is procedural rather than command-driven.
Rabbit holes: Cross-agent consistency, manual step variance, and difficult regression testing for operator behavior.

Option C — Keep current task-per-issue model only

Sketch: Retain speckit.github.taskstoissues as the sole first-party model and document milestone-level coordination as out of scope.
Appetite: small
Trade-offs: Minimal maintenance and clear single-path guidance; does not solve the core request for teams that intentionally avoid task-per-issue conversion.
Rabbit holes: Continued ad hoc external mappings and repeated feature requests for lower issue cardinality.

Recommendation

Recommend Option A. It best aligns with existing extension boundaries (GitHub-specific behavior remains opt-in and out of core), addresses the requested traceability model directly, and can enforce safe/idempotent external writes in a testable way. Option B is viable as interim guidance but does not provide the reliability guarantees requested in #5284.

Out of Scope (for the recommended option)

Bidirectional state synchronization between tasks and issues.
Automatic migration or rewrite of existing task-per-issue issue sets.
Detailed implementation design (API shape, parser internals, storage format beyond concept-level constraints).

Assumptions to Validate

Enough maintainers need milestone-level (not task-level) issue granularity to justify long-term maintenance.
A stable, feature-qualified milestone identity can be defined without excessive authoring friction.
Existing test and command infrastructure can cover failure modes (ambiguous mapping, stale URLs, repeated execution) without disproportionate complexity.

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for #5284 · copilot · gpt53codex · 51.2 AIC · ⌖ 0.766 AIC · ⊞ 26.4K · ◷

Feature assessment — milestone-issue-tracking · Stage 5/5: Decision — verdict go

Decision: Milestone-level issue tracking assessment

Slug: milestone-issue-tracking
Decided: 2026-11-06T14:10:00Z
Verdict: go
Artifacts reviewed: intake.md | research.md | problem.md | concept.md

Scorecard

Criterion	Rating	Justification
Problem validity	strong	The mismatch between task-level issue conversion and milestone-level coordination is clearly articulated with concrete usage scenarios in #5284.
Evidence strength	adequate	Evidence includes current extension behavior, migration history, related issues, and test surfaces; quantitative demand telemetry is limited but not absent.
Value vs. inaction	strong	Inaction preserves issue sprawl or ad hoc mapping drift for affected teams, with ongoing traceability and coordination costs.
Feasibility / appetite	adequate	A medium-appetite extension command is credible given existing extension architecture and command/test patterns.
Strategic fit	strong	Proposal keeps provider-specific behavior in the opt-in GitHub extension and preserves provider-neutral core SDD boundaries.
Risk posture	adequate	Major risks are identifiable (schema identity, stale URL reconciliation, dual-mode conflicts) and can be mitigated through validation, previews, and idempotency constraints.

Verdict & Rationale

Verdict: go. The assessed problem is real, strategically aligned with repository architecture, and supported by adequate evidence plus a credible concept path. While demand telemetry is not broad, the proposal’s bounded scope and explicit non-goals keep risk manageable. This should proceed to specification with strict requirements for idempotency, conflict handling, and authority-boundary documentation.

If needs-clarification

Blocking questions: N/A (go verdict)
Revisit stage: N/A

If go — Handoff to `/speckit-specify`

Problem: Teams need a first-party way to track delivery milestones in GitHub without forcing one-issue-per-task conversion or duplicating normative planning artifacts.
Chosen approach: Add an opt-in milestone-level mapping workflow/command in the bundled github extension (Option A), centered on a validated tracking.md, preview-before-write flow, and idempotent issue mapping.
In scope / out of scope: In scope: map requirements/design/task references to milestone delivery issues and persist real URLs. Out of scope: automatic bidirectional state mirroring and task-state/issue-state equivalence.
Success metrics: Deterministic mapping validation before writes, no duplicate milestone issues on rerun, stable feature-qualified milestone identities, and clear docs differentiating this model from taskstoissues.
Carried-forward open questions:
- [NEEDS CLARIFICATION: Exact tracking.md schema and anchor rules.]
- [NEEDS CLARIFICATION: Reconciliation behavior for stale/deleted issue URLs.]
- [NEEDS CLARIFICATION: Enforcement policy when both tracking models are invoked for one feature.]

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for #5284 · copilot · gpt53codex · 51.2 AIC · ⌖ 0.766 AIC · ⊞ 26.4K · ◷

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

Description

Problem Statement

Proposed Solution

Alternatives Considered

Component

AI Agent (if applicable)

Use Cases

Acceptance Criteria

Additional Context

AI Disclosure

Activity

github-actions commented on Nov 6, 2026

Idea Intake: Milestone-level issue tracking

Idea (as captured)

Restated

Origin & Context

First-Glance Unknowns

github-actions commented on Nov 6, 2026

Idea Research: Milestone-level issue tracking

Users & Demand

Prior Art

Market & Context

Data & Constraints

Evidence Against the Idea

Gaps & Open Questions

Sources

github-actions commented on Nov 6, 2026

Problem Definition: Delivery tracking granularity mismatch

Problem Statement

Affected Users & Stakeholders

Goals

Non-Goals

Success Metrics

Cost of Inaction

Open Questions

github-actions commented on Nov 6, 2026

Concept: Milestone-level GitHub delivery mapping

Options

Option A — First-party milestone-map command in github extension

Option B — Preset/workflow-only orchestration over existing commands

Option C — Keep current task-per-issue model only

Recommendation

Out of Scope (for the recommended option)

Assumptions to Validate

github-actions commented on Nov 6, 2026

Decision: Milestone-level issue tracking assessment

Scorecard

Verdict & Rationale

If needs-clarification

If go — Handoff to /speckit-specify

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Option A — First-party milestone-map command in `github` extension

If go — Handoff to `/speckit-specify`