Add toc-navigation community preset to catalog and README by Quratulain-bilal · Pull Request #2080 · github/spec-kit

Quratulain-bilal · 2026-04-03T14:21:47Z

Summary

Add exemplar TOC sections to structure templates (spec-template.md, plan-template.md,
tasks-template.md)
Add TOC generation instructions to command templates (specify.md, plan.md, tasks.md)
Only ##-level headings included to keep TOC concise

Closes #1970

Changes

File	Change
`templates/spec-template.md`	Added TOC with links to User Scenarios, Requirements, Success
Criteria, Assumptions
`templates/plan-template.md`	Added TOC with links to Summary, Technical Context, Constitution
Check, Project Structure, Complexity Tracking
`templates/tasks-template.md`	Added TOC with links to Phase 1, Phase 2, Phase 3, Dependencies,
Implementation Strategy
`templates/commands/specify.md`	Instruction in step 5 to generate TOC with anchor links
`templates/commands/plan.md`	Instruction in step 3 to generate TOC with anchor links
`templates/commands/tasks.md`	Instruction in step 4 to generate TOC with anchor links

Design decisions

Pure template change — no Python code or test changes needed
Standard GitHub anchor format (lowercase, spaces to hyphens, strip special chars)
Skipped small documents (checklist, constitution) — too short to need TOC

Copilot

Pull request overview

Adds Table of Contents (TOC) guidance to the Speckit command templates so generated spec.md, plan.md, and tasks.md include a concise TOC linking to ##-level sections.

Changes:

Instruct /speckit.specify to include a TOC after the document header and before the first content section.
Instruct /speckit.plan to include a TOC after the document header and before the Summary section.
Instruct /speckit.tasks to include a TOC after the document header and before the first phase.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
templates/commands/specify.md	Adds instruction to generate a `##`-heading TOC with GitHub-style anchors.
templates/commands/plan.md	Adds instruction to generate a `##`-heading TOC before Summary.
templates/commands/tasks.md	Adds instruction to generate a `##`-heading TOC before phases.

Comments suppressed due to low confidence (1)

templates/commands/specify.md:123

PR description mentions adding exemplar TOC sections to templates/spec-template.md, templates/plan-template.md, and templates/tasks-template.md, but those files currently contain no “Table of Contents” section (verified via search). Either update the structure templates as described, or adjust the PR description/scope so it matches what’s actually changed.

5. Write the specification to SPEC_FILE using the template structure, replacing placeholders with concrete details derived from the feature description (arguments) while preserving section order and headings. Include a **Table of Contents** section immediately after the header metadata block and before the first content section. The TOC must list all `##`-level headings as markdown anchor links (lowercase, spaces to hyphens, strip special characters). Example: `- [User Scenarios & Testing](#user-scenarios--testing)`. Only include sections that actually appear in the final document.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

templates/commands/specify.md

templates/commands/plan.md

templates/commands/tasks.md

mnriem

Please address Copilot feedback. If not applicable, please explain why

Quratulain-bilal · 2026-04-03T16:08:07Z

Addressed all 3 Copilot comments replaced ambiguous 'header metadata block' wording with
template-accurate descriptions in all three command files.

Copilot

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

templates/commands/specify.md

templates/commands/tasks.md

mnriem · 2026-04-03T16:19:24Z

Please address Copilot feedback. If not applicable, please explain why

Copilot

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

templates/tasks-template.md

templates/plan-template.md

Copilot

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

templates/spec-template.md

mnriem · 2026-04-03T16:41:33Z

Please address Copilot feedback. If not applicable please explain why!

Quratulain-bilal · 2026-04-03T16:47:48Z

Addressed Copilot feedback — fixed TOC anchors in spec-template.md to include the -mandatory suffix matching the actual heading IDs.

Copilot

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

templates/tasks-template.md

mnriem · 2026-04-03T16:52:29Z

Please address Copilot feedback. Hopefully that will be the last round

Copilot

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

templates/plan-template.md

mnriem · 2026-04-03T16:59:52Z

Address the last nit from Copilot and I think we are ready :)

Copilot

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

templates/tasks-template.md

mnriem · 2026-04-03T17:07:41Z

Looks like there is more critical Copilot feedback

…line in

…ks-template

… exemplars

Pivots from core template changes to a preset approach per reviewer request. Adds presets/toc-navigation/ with 3 template overrides and 3 command overrides that add Table of Contents sections to generated spec.md, plan.md, and tasks.md documents. Addresses all 8 impact concerns from review: - Templates use anchor links (not plain text) matching command instructions - All 12 tasks-template headings accounted for (dynamic phases as plain text) - spec-template anchors include -mandatory suffix - TOC placed after Note paragraph in plan-template - Self-reference exclusion explicit in all commands - Clarify stale TOC instruction in specify command - Implement misparse warning in tasks command Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Move preset to standalone repository per maintainer guidance: https://github.com/Quratulain-bilal/spec-kit-preset-toc-navigation - Remove presets/toc-navigation/ from core repo - Add toc-navigation entry to catalog.community.json Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

mnriem · 2026-04-07T12:03:31Z

@Quratulain-bilal Please add it to the main README as well

Adds Table of Contents Navigation entry (alphabetically between Pirate Speak and VS Code Ask Questions) to the community presets table in README.md as requested by maintainer.

Quratulain-bilal · 2026-04-07T16:47:25Z

Added toc-navigation preset to the main README's Community Presets table as requested. Entry placed
alphabetically between Pirate Speak and VS Code Ask Questions, with 3 templates, 3 commands, and link to the preset repository.

Copilot

Pull request overview

This PR appears to add a new community preset entry that provides Table of Contents navigation for generated spec.md, plan.md, and tasks.md, by updating the community preset catalog and documenting it in the README.

Changes:

Added “Table of Contents Navigation” to the community presets list in README.md.
Added a new toc-navigation preset entry to presets/catalog.community.json (including download URL, version, and tags).

Show a summary per file

File	Description
README.md	Documents the new community preset in the Community Presets table.
presets/catalog.community.json	Registers the new `toc-navigation` preset in the community catalog so it can be discovered/installed.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Files reviewed: 2/2 changed files
Comments generated: 1

README.md

mnriem · 2026-04-07T18:08:49Z

Please address Copilot feedback

Quratulain-bilal · 2026-04-07T18:33:03Z

Updated PR title and description to clarify this is a community preset catalog entry, not core template
changes. The TOC functionality is delivered as a standalone preset in a separate
repository per maintainer guidance.
This PR only registers it in the catalog and README.

Copilot

Pull request overview

Adds a new community preset (“toc-navigation”) to Spec Kit’s discovery surfaces so users can find/install the preset that generates a navigable TOC for spec/plan/tasks docs.

Changes:

Add “Table of Contents Navigation” row to the Community Presets table in README.md.
Add a toc-navigation entry (metadata + download URL + requirements/tags) to presets/catalog.community.json.

Show a summary per file

File	Description
README.md	Documents the new community preset in the Community Presets table.
presets/catalog.community.json	Registers the new `toc-navigation` preset in the community catalog for discovery/install.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Files reviewed: 2/2 changed files
Comments generated: 1

README.md

mnriem · 2026-04-07T18:44:38Z

Thank you!

Copilot

Pull request overview

Adds a new community preset entry (“toc-navigation”) to the project’s community preset discovery surfaces (README + community preset catalog), making it discoverable alongside other presets.

Changes:

Added “Table of Contents Navigation” to the Community Presets table in README.md.
Added a toc-navigation entry to presets/catalog.community.json with metadata (name, version, URLs, requires/provides, tags).

Show a summary per file

File	Description
README.md	Adds the new preset to the human-readable Community Presets list.
presets/catalog.community.json	Registers the new preset in the machine-readable community catalog for discovery/search.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Files reviewed: 2/2 changed files
Comments generated: 2

Copilot · 2026-04-07T18:47:19Z

presets/catalog.community.json

+    "toc-navigation": {
+      "name": "Table of Contents Navigation",
+      "id": "toc-navigation",
+      "version": "1.0.0",
+      "description": "Adds a navigable Table of Contents to generated spec.md, plan.md, and tasks.md documents",
+      "author": "Quratulain-bilal",
+      "repository": "https://github.com/Quratulain-bilal/spec-kit-preset-toc-navigation",
+      "download_url": "https://github.com/Quratulain-bilal/spec-kit-preset-toc-navigation/archive/refs/tags/v1.0.0.zip",
+      "homepage": "https://github.com/Quratulain-bilal/spec-kit-preset-toc-navigation",
+      "documentation": "https://github.com/Quratulain-bilal/spec-kit-preset-toc-navigation/blob/main/README.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.4.0"
+      },
+      "provides": {


The preset catalog entry is missing the per-preset created_at and updated_at fields shown in the Preset Publishing Guide’s recommended catalog.community.json format. Adding those timestamps (and bumping the top-level catalog updated_at to reflect this change) would keep the catalog metadata consistent and make updates easier to track over time.

Copilot · 2026-04-07T18:47:19Z

presets/catalog.community.json

+      "name": "Table of Contents Navigation",
+      "id": "toc-navigation",
+      "version": "1.0.0",
+      "description": "Adds a navigable Table of Contents to generated spec.md, plan.md, and tasks.md documents",


Minor consistency: other preset descriptions in this file end with a period, but this new description does not. Consider adding the trailing period to match the surrounding entries.

Suggested change

"description": "Adds a navigable Table of Contents to generated spec.md, plan.md, and tasks.md documents",

"description": "Adds a navigable Table of Contents to generated spec.md, plan.md, and tasks.md documents.",

Quratulain-bilal requested a review from mnriem as a code owner April 3, 2026 14:21

mnriem requested a review from Copilot April 3, 2026 14:26

Copilot started reviewing on behalf of mnriem April 3, 2026 14:26 View session