From 840f042a38a840c3f2cd5abe42770c1d0735ccb3 Mon Sep 17 00:00:00 2001 From: Quratulain-bilal Date: Fri, 3 Apr 2026 19:18:41 +0500 Subject: [PATCH 01/16] feat: add Table of Contents to generated markdown documents (#1970) --- templates/commands/plan.md | 1 + templates/commands/specify.md | 2 +- templates/commands/tasks.md | 1 + 3 files changed, 3 insertions(+), 1 deletion(-) diff --git a/templates/commands/plan.md b/templates/commands/plan.md index 4f1e9ed295..3ea3280f5f 100644 --- a/templates/commands/plan.md +++ b/templates/commands/plan.md @@ -65,6 +65,7 @@ You **MUST** consider the user input before proceeding (if not empty). 2. **Load context**: Read FEATURE_SPEC and `/memory/constitution.md`. Load IMPL_PLAN template (already copied). 3. **Execute plan workflow**: Follow the structure in IMPL_PLAN template to: + - Include a **Table of Contents** section immediately after the header metadata block and before the Summary. List all `##`-level headings as markdown anchor links (lowercase, spaces to hyphens, strip special characters). Only include sections that actually appear in the final document. - Fill Technical Context (mark unknowns as "NEEDS CLARIFICATION") - Fill Constitution Check section from constitution - Evaluate gates (ERROR if violations unjustified) diff --git a/templates/commands/specify.md b/templates/commands/specify.md index a81b8f12f1..8e2b2287fc 100644 --- a/templates/commands/specify.md +++ b/templates/commands/specify.md @@ -120,7 +120,7 @@ Given that feature description, do this: 7. Identify Key Entities (if data involved) 8. Return: SUCCESS (spec ready for planning) -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. +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. 6. **Specification Quality Validation**: After writing the initial spec, validate it against quality criteria: diff --git a/templates/commands/tasks.md b/templates/commands/tasks.md index 4e204abc1b..3d9b89bb14 100644 --- a/templates/commands/tasks.md +++ b/templates/commands/tasks.md @@ -77,6 +77,7 @@ You **MUST** consider the user input before proceeding (if not empty). - Validate task completeness (each user story has all needed tasks, independently testable) 4. **Generate tasks.md**: Use `templates/tasks-template.md` as structure, fill with: + - A **Table of Contents** section immediately after the header metadata block and before the first phase. List all `##`-level headings as markdown anchor links (lowercase, spaces to hyphens, strip special characters). Only include sections that actually appear in the final document. - Correct feature name from plan.md - Phase 1: Setup tasks (project initialization) - Phase 2: Foundational tasks (blocking prerequisites for all user stories) From 07068d86d1dc168bda175c75ce8804b2e11b0b51 Mon Sep 17 00:00:00 2001 From: Quratulain-bilal Date: Fri, 3 Apr 2026 21:07:19 +0500 Subject: [PATCH 02/16] fix: address Copilot review - clarify TOC placement wording --- templates/commands/plan.md | 2 +- templates/commands/specify.md | 2 +- templates/commands/tasks.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/templates/commands/plan.md b/templates/commands/plan.md index 3ea3280f5f..01ff42b906 100644 --- a/templates/commands/plan.md +++ b/templates/commands/plan.md @@ -65,7 +65,7 @@ You **MUST** consider the user input before proceeding (if not empty). 2. **Load context**: Read FEATURE_SPEC and `/memory/constitution.md`. Load IMPL_PLAN template (already copied). 3. **Execute plan workflow**: Follow the structure in IMPL_PLAN template to: - - Include a **Table of Contents** section immediately after the header metadata block and before the Summary. List all `##`-level headings as markdown anchor links (lowercase, spaces to hyphens, strip special characters). Only include sections that actually appear in the final document. + - Include a **Table of Contents** section immediately after the title and header details, and before the Summary. List all `##`-level headings as markdown anchor links (lowercase, spaces to hyphens, strip special characters). Only include sections that actually appear in the final document. - Fill Technical Context (mark unknowns as "NEEDS CLARIFICATION") - Fill Constitution Check section from constitution - Evaluate gates (ERROR if violations unjustified) diff --git a/templates/commands/specify.md b/templates/commands/specify.md index 8e2b2287fc..c30bf80077 100644 --- a/templates/commands/specify.md +++ b/templates/commands/specify.md @@ -120,7 +120,7 @@ Given that feature description, do this: 7. Identify Key Entities (if data involved) 8. Return: SUCCESS (spec ready for planning) -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. +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 title and initial metadata lines at the top of the file, 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. 6. **Specification Quality Validation**: After writing the initial spec, validate it against quality criteria: diff --git a/templates/commands/tasks.md b/templates/commands/tasks.md index 3d9b89bb14..9e6d1186cf 100644 --- a/templates/commands/tasks.md +++ b/templates/commands/tasks.md @@ -77,7 +77,7 @@ You **MUST** consider the user input before proceeding (if not empty). - Validate task completeness (each user story has all needed tasks, independently testable) 4. **Generate tasks.md**: Use `templates/tasks-template.md` as structure, fill with: - - A **Table of Contents** section immediately after the header metadata block and before the first phase. List all `##`-level headings as markdown anchor links (lowercase, spaces to hyphens, strip special characters). Only include sections that actually appear in the final document. + - A **Table of Contents** section before the first phase. List all `##`-level headings as markdown anchor links (lowercase, spaces to hyphens, strip special characters). Only include sections that actually appear in the final document. - Correct feature name from plan.md - Phase 1: Setup tasks (project initialization) - Phase 2: Foundational tasks (blocking prerequisites for all user stories) From 24db1adfb24a0210cdbd3479ccee742fb8070884 Mon Sep 17 00:00:00 2001 From: Quratulain-bilal Date: Fri, 3 Apr 2026 21:26:45 +0500 Subject: [PATCH 03/16] fix: include TOC sections in structure templates --- templates/plan-template.md | 9 +++++++++ templates/spec-template.md | 7 +++++++ templates/tasks-template.md | 8 ++++++++ 3 files changed, 24 insertions(+) diff --git a/templates/plan-template.md b/templates/plan-template.md index 5a2fafebe3..ed6722d9be 100644 --- a/templates/plan-template.md +++ b/templates/plan-template.md @@ -1,8 +1,17 @@ + # Implementation Plan: [FEATURE] **Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link] **Input**: Feature specification from `/specs/[###-feature-name]/spec.md` +## Table of Contents + +- [Summary](#summary) +- [Technical Context](#technical-context) +- [Constitution Check](#constitution-check) +- [Project Structure](#project-structure) +- [Complexity Tracking](#complexity-tracking) + **Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/plan-template.md` for the execution workflow. ## Summary diff --git a/templates/spec-template.md b/templates/spec-template.md index 4581e40529..dd329adab5 100644 --- a/templates/spec-template.md +++ b/templates/spec-template.md @@ -5,6 +5,13 @@ **Status**: Draft **Input**: User description: "$ARGUMENTS" +## Table of Contents + +- [User Scenarios & Testing](#user-scenarios--testing) +- [Requirements](#requirements) +- [Success Criteria](#success-criteria) +- [Assumptions](#assumptions) + ## User Scenarios & Testing *(mandatory)* + - [Format](#format-id-p-story-description) - [Path Conventions](#path-conventions) -- [Phase 1: Setup (Shared Infrastructure)](#phase-1-setup-shared-infrastructure) -- [Phase 2: Foundational (Blocking Prerequisites)](#phase-2-foundational-blocking-prerequisites) -- [Phase 3: User Story 1](#phase-3-user-story-1---title-priority-p1--mvp) -- [Phase 4: User Story 2](#phase-4-user-story-2---title-priority-p2) -- [Phase 5: User Story 3](#phase-5-user-story-3---title-priority-p3) -- [Phase N: Polish & Cross-Cutting Concerns](#phase-n-polish--cross-cutting-concerns) +- Phase 1: Setup (Shared Infrastructure) +- Phase 2: Foundational (Blocking Prerequisites) +- Phase 3+: User Story phases (generated from spec.md priorities) +- Phase N: Polish & Cross-Cutting Concerns - [Dependencies & Execution Order](#dependencies--execution-order) -- [Parallel Example: User Story 1](#parallel-example-user-story-1) - [Implementation Strategy](#implementation-strategy) - [Notes](#notes) From 06963de5ba4f0bf7b73bd474ebe6db486f04771c Mon Sep 17 00:00:00 2001 From: Quratulain-bilal Date: Fri, 3 Apr 2026 22:37:52 +0500 Subject: [PATCH 10/16] fix: remove hardcoded anchor links from template TOCs, use plain text exemplars --- templates/plan-template.md | 13 ++++++++----- templates/spec-template.md | 11 +++++++---- templates/tasks-template.md | 12 ++++++------ 3 files changed, 21 insertions(+), 15 deletions(-) diff --git a/templates/plan-template.md b/templates/plan-template.md index ed57fbc203..130f31791f 100644 --- a/templates/plan-template.md +++ b/templates/plan-template.md @@ -5,11 +5,14 @@ ## Table of Contents -- [Summary](#summary) -- [Technical Context](#technical-context) -- [Constitution Check](#constitution-check) -- [Project Structure](#project-structure) -- [Complexity Tracking](#complexity-tracking) + + +- Summary +- Technical Context +- Constitution Check +- Project Structure +- Complexity Tracking **Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/plan-template.md` for the execution workflow. diff --git a/templates/spec-template.md b/templates/spec-template.md index cb751b1d24..464ee8637e 100644 --- a/templates/spec-template.md +++ b/templates/spec-template.md @@ -7,10 +7,13 @@ ## Table of Contents -- [User Scenarios & Testing](#user-scenarios--testing-mandatory) -- [Requirements](#requirements-mandatory) -- [Success Criteria](#success-criteria-mandatory) -- [Assumptions](#assumptions) + + +- User Scenarios & Testing +- Requirements +- Success Criteria +- Assumptions ## User Scenarios & Testing *(mandatory)* diff --git a/templates/tasks-template.md b/templates/tasks-template.md index fe1e20953d..3cbd664bf2 100644 --- a/templates/tasks-template.md +++ b/templates/tasks-template.md @@ -15,17 +15,17 @@ description: "Task list template for feature implementation" ## Table of Contents + this list with proper anchor links from the actual ## headings. --> -- [Format](#format-id-p-story-description) -- [Path Conventions](#path-conventions) +- Format +- Path Conventions - Phase 1: Setup (Shared Infrastructure) - Phase 2: Foundational (Blocking Prerequisites) - Phase 3+: User Story phases (generated from spec.md priorities) - Phase N: Polish & Cross-Cutting Concerns -- [Dependencies & Execution Order](#dependencies--execution-order) -- [Implementation Strategy](#implementation-strategy) -- [Notes](#notes) +- Dependencies & Execution Order +- Implementation Strategy +- Notes ## Format: `[ID] [P?] [Story] Description` From 1543cdef2f16ff62662edf078fafbb25098284ca Mon Sep 17 00:00:00 2001 From: Quratulain-bilal Date: Fri, 3 Apr 2026 23:43:34 +0500 Subject: [PATCH 11/16] fix: remove HTML comments from template TOCs --- templates/plan-template.md | 3 --- templates/spec-template.md | 3 --- templates/tasks-template.md | 3 --- 3 files changed, 9 deletions(-) diff --git a/templates/plan-template.md b/templates/plan-template.md index 130f31791f..1ab5970859 100644 --- a/templates/plan-template.md +++ b/templates/plan-template.md @@ -5,9 +5,6 @@ ## Table of Contents - - - Summary - Technical Context - Constitution Check diff --git a/templates/spec-template.md b/templates/spec-template.md index 464ee8637e..8e8fb69960 100644 --- a/templates/spec-template.md +++ b/templates/spec-template.md @@ -7,9 +7,6 @@ ## Table of Contents - - - User Scenarios & Testing - Requirements - Success Criteria diff --git a/templates/tasks-template.md b/templates/tasks-template.md index 3cbd664bf2..ed8325ba3f 100644 --- a/templates/tasks-template.md +++ b/templates/tasks-template.md @@ -14,9 +14,6 @@ description: "Task list template for feature implementation" ## Table of Contents - - - Format - Path Conventions - Phase 1: Setup (Shared Infrastructure) From 1c6792da3fe132dc27a0494ca695a034c7a3191c Mon Sep 17 00:00:00 2001 From: Quratulain-bilal Date: Sat, 4 Apr 2026 00:02:11 +0500 Subject: [PATCH 12/16] fix: add missing Parallel Example heading to tasks-template TOC --- templates/tasks-template.md | 1 + 1 file changed, 1 insertion(+) diff --git a/templates/tasks-template.md b/templates/tasks-template.md index ed8325ba3f..155d9f5a32 100644 --- a/templates/tasks-template.md +++ b/templates/tasks-template.md @@ -21,6 +21,7 @@ description: "Task list template for feature implementation" - Phase 3+: User Story phases (generated from spec.md priorities) - Phase N: Polish & Cross-Cutting Concerns - Dependencies & Execution Order +- Parallel Example: User Story 1 - Implementation Strategy - Notes From 760d638390e4511e40c987ed1d8c7d23091097f3 Mon Sep 17 00:00:00 2001 From: Quratulain-bilal Date: Sat, 4 Apr 2026 01:03:56 +0500 Subject: [PATCH 13/16] revert: remove all core template changes, pivot to preset approach --- templates/commands/plan.md | 1 - templates/commands/specify.md | 2 +- templates/commands/tasks.md | 1 - templates/plan-template.md | 8 -------- templates/spec-template.md | 7 ------- templates/tasks-template.md | 13 ------------- 6 files changed, 1 insertion(+), 31 deletions(-) diff --git a/templates/commands/plan.md b/templates/commands/plan.md index 01ff42b906..4f1e9ed295 100644 --- a/templates/commands/plan.md +++ b/templates/commands/plan.md @@ -65,7 +65,6 @@ You **MUST** consider the user input before proceeding (if not empty). 2. **Load context**: Read FEATURE_SPEC and `/memory/constitution.md`. Load IMPL_PLAN template (already copied). 3. **Execute plan workflow**: Follow the structure in IMPL_PLAN template to: - - Include a **Table of Contents** section immediately after the title and header details, and before the Summary. List all `##`-level headings as markdown anchor links (lowercase, spaces to hyphens, strip special characters). Only include sections that actually appear in the final document. - Fill Technical Context (mark unknowns as "NEEDS CLARIFICATION") - Fill Constitution Check section from constitution - Evaluate gates (ERROR if violations unjustified) diff --git a/templates/commands/specify.md b/templates/commands/specify.md index c30bf80077..a81b8f12f1 100644 --- a/templates/commands/specify.md +++ b/templates/commands/specify.md @@ -120,7 +120,7 @@ Given that feature description, do this: 7. Identify Key Entities (if data involved) 8. Return: SUCCESS (spec ready for planning) -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 title and initial metadata lines at the top of the file, 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. +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. 6. **Specification Quality Validation**: After writing the initial spec, validate it against quality criteria: diff --git a/templates/commands/tasks.md b/templates/commands/tasks.md index a119db0d2a..4e204abc1b 100644 --- a/templates/commands/tasks.md +++ b/templates/commands/tasks.md @@ -77,7 +77,6 @@ You **MUST** consider the user input before proceeding (if not empty). - Validate task completeness (each user story has all needed tasks, independently testable) 4. **Generate tasks.md**: Use `templates/tasks-template.md` as structure, fill with: - - A **Table of Contents** section immediately after the title and metadata lines, and before the first `##` section. List all `##`-level headings as markdown anchor links (lowercase, spaces to hyphens, strip special characters). Only include sections that actually appear in the final document. - Correct feature name from plan.md - Phase 1: Setup tasks (project initialization) - Phase 2: Foundational tasks (blocking prerequisites for all user stories) diff --git a/templates/plan-template.md b/templates/plan-template.md index 1ab5970859..5a2fafebe3 100644 --- a/templates/plan-template.md +++ b/templates/plan-template.md @@ -3,14 +3,6 @@ **Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link] **Input**: Feature specification from `/specs/[###-feature-name]/spec.md` -## Table of Contents - -- Summary -- Technical Context -- Constitution Check -- Project Structure -- Complexity Tracking - **Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/plan-template.md` for the execution workflow. ## Summary diff --git a/templates/spec-template.md b/templates/spec-template.md index 8e8fb69960..4581e40529 100644 --- a/templates/spec-template.md +++ b/templates/spec-template.md @@ -5,13 +5,6 @@ **Status**: Draft **Input**: User description: "$ARGUMENTS" -## Table of Contents - -- User Scenarios & Testing -- Requirements -- Success Criteria -- Assumptions - ## User Scenarios & Testing *(mandatory)* + +**Language/Version**: [e.g., Python 3.11, Swift 5.9, Rust 1.75 or NEEDS CLARIFICATION] +**Primary Dependencies**: [e.g., FastAPI, UIKit, LLVM or NEEDS CLARIFICATION] +**Storage**: [if applicable, e.g., PostgreSQL, CoreData, files or N/A] +**Testing**: [e.g., pytest, XCTest, cargo test or NEEDS CLARIFICATION] +**Target Platform**: [e.g., Linux server, iOS 15+, WASM or NEEDS CLARIFICATION] +**Project Type**: [e.g., library/cli/web-service/mobile-app/compiler/desktop-app or NEEDS CLARIFICATION] +**Performance Goals**: [domain-specific, e.g., 1000 req/s, 10k lines/sec, 60 fps or NEEDS CLARIFICATION] +**Constraints**: [domain-specific, e.g., <200ms p95, <100MB memory, offline-capable or NEEDS CLARIFICATION] +**Scale/Scope**: [domain-specific, e.g., 10k users, 1M LOC, 50 screens or NEEDS CLARIFICATION] + +## Constitution Check + +*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.* + +[Gates determined based on constitution file] + +## Project Structure + +### Documentation (this feature) + +```text +specs/[###-feature]/ +├── plan.md # This file (/speckit.plan command output) +├── research.md # Phase 0 output (/speckit.plan command) +├── data-model.md # Phase 1 output (/speckit.plan command) +├── quickstart.md # Phase 1 output (/speckit.plan command) +├── contracts/ # Phase 1 output (/speckit.plan command) +└── tasks.md # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan) +``` + +### Source Code (repository root) + + +```text +# [REMOVE IF UNUSED] Option 1: Single project (DEFAULT) +src/ +├── models/ +├── services/ +├── cli/ +└── lib/ + +tests/ +├── contract/ +├── integration/ +└── unit/ + +# [REMOVE IF UNUSED] Option 2: Web application (when "frontend" + "backend" detected) +backend/ +├── src/ +│ ├── models/ +│ ├── services/ +│ └── api/ +└── tests/ + +frontend/ +├── src/ +│ ├── components/ +│ ├── pages/ +│ └── services/ +└── tests/ + +# [REMOVE IF UNUSED] Option 3: Mobile + API (when "iOS/Android" detected) +api/ +└── [same as backend above] + +ios/ or android/ +└── [platform-specific structure: feature modules, UI flows, platform tests] +``` + +**Structure Decision**: [Document the selected structure and reference the real +directories captured above] + +## Complexity Tracking + +> **Fill ONLY if Constitution Check has violations that must be justified** + +| Violation | Why Needed | Simpler Alternative Rejected Because | +|-----------|------------|-------------------------------------| +| [e.g., 4th project] | [current need] | [why 3 projects insufficient] | +| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient] | diff --git a/presets/toc-navigation/templates/spec-template.md b/presets/toc-navigation/templates/spec-template.md new file mode 100644 index 0000000000..cb751b1d24 --- /dev/null +++ b/presets/toc-navigation/templates/spec-template.md @@ -0,0 +1,135 @@ +# Feature Specification: [FEATURE NAME] + +**Feature Branch**: `[###-feature-name]` +**Created**: [DATE] +**Status**: Draft +**Input**: User description: "$ARGUMENTS" + +## Table of Contents + +- [User Scenarios & Testing](#user-scenarios--testing-mandatory) +- [Requirements](#requirements-mandatory) +- [Success Criteria](#success-criteria-mandatory) +- [Assumptions](#assumptions) + +## User Scenarios & Testing *(mandatory)* + + + +### User Story 1 - [Brief Title] (Priority: P1) + +[Describe this user journey in plain language] + +**Why this priority**: [Explain the value and why it has this priority level] + +**Independent Test**: [Describe how this can be tested independently - e.g., "Can be fully tested by [specific action] and delivers [specific value]"] + +**Acceptance Scenarios**: + +1. **Given** [initial state], **When** [action], **Then** [expected outcome] +2. **Given** [initial state], **When** [action], **Then** [expected outcome] + +--- + +### User Story 2 - [Brief Title] (Priority: P2) + +[Describe this user journey in plain language] + +**Why this priority**: [Explain the value and why it has this priority level] + +**Independent Test**: [Describe how this can be tested independently] + +**Acceptance Scenarios**: + +1. **Given** [initial state], **When** [action], **Then** [expected outcome] + +--- + +### User Story 3 - [Brief Title] (Priority: P3) + +[Describe this user journey in plain language] + +**Why this priority**: [Explain the value and why it has this priority level] + +**Independent Test**: [Describe how this can be tested independently] + +**Acceptance Scenarios**: + +1. **Given** [initial state], **When** [action], **Then** [expected outcome] + +--- + +[Add more user stories as needed, each with an assigned priority] + +### Edge Cases + + + +- What happens when [boundary condition]? +- How does system handle [error scenario]? + +## Requirements *(mandatory)* + + + +### Functional Requirements + +- **FR-001**: System MUST [specific capability, e.g., "allow users to create accounts"] +- **FR-002**: System MUST [specific capability, e.g., "validate email addresses"] +- **FR-003**: Users MUST be able to [key interaction, e.g., "reset their password"] +- **FR-004**: System MUST [data requirement, e.g., "persist user preferences"] +- **FR-005**: System MUST [behavior, e.g., "log all security events"] + +*Example of marking unclear requirements:* + +- **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?] +- **FR-007**: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified] + +### Key Entities *(include if feature involves data)* + +- **[Entity 1]**: [What it represents, key attributes without implementation] +- **[Entity 2]**: [What it represents, relationships to other entities] + +## Success Criteria *(mandatory)* + + + +### Measurable Outcomes + +- **SC-001**: [Measurable metric, e.g., "Users can complete account creation in under 2 minutes"] +- **SC-002**: [Measurable metric, e.g., "System handles 1000 concurrent users without degradation"] +- **SC-003**: [User satisfaction metric, e.g., "90% of users successfully complete primary task on first attempt"] +- **SC-004**: [Business metric, e.g., "Reduce support tickets related to [X] by 50%"] + +## Assumptions + + + +- [Assumption about target users, e.g., "Users have stable internet connectivity"] +- [Assumption about scope boundaries, e.g., "Mobile support is out of scope for v1"] +- [Assumption about data/environment, e.g., "Existing authentication system will be reused"] +- [Dependency on existing system/service, e.g., "Requires access to the existing user profile API"] diff --git a/presets/toc-navigation/templates/tasks-template.md b/presets/toc-navigation/templates/tasks-template.md new file mode 100644 index 0000000000..494e858a0f --- /dev/null +++ b/presets/toc-navigation/templates/tasks-template.md @@ -0,0 +1,266 @@ +--- + +description: "Task list template for feature implementation" +--- + +# Tasks: [FEATURE NAME] + +**Input**: Design documents from `/specs/[###-feature-name]/` +**Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/ + +**Tests**: The examples below include test tasks. Tests are OPTIONAL - only include them if explicitly requested in the feature specification. + +**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story. + +## Table of Contents + +- [Format](#format-id-p-story-description) +- [Path Conventions](#path-conventions) +- [Phase 1: Setup (Shared Infrastructure)](#phase-1-setup-shared-infrastructure) +- [Phase 2: Foundational (Blocking Prerequisites)](#phase-2-foundational-blocking-prerequisites) +- Phase 3: User Story 1 (generated from spec.md) +- Phase 4: User Story 2 (generated from spec.md) +- Phase 5: User Story 3 (generated from spec.md) +- [Phase N: Polish & Cross-Cutting Concerns](#phase-n-polish--cross-cutting-concerns) +- [Dependencies & Execution Order](#dependencies--execution-order) +- [Parallel Example: User Story 1](#parallel-example-user-story-1) +- [Implementation Strategy](#implementation-strategy) +- [Notes](#notes) + +## Format: `[ID] [P?] [Story] Description` + +- **[P]**: Can run in parallel (different files, no dependencies) +- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3) +- Include exact file paths in descriptions + +## Path Conventions + +- **Single project**: `src/`, `tests/` at repository root +- **Web app**: `backend/src/`, `frontend/src/` +- **Mobile**: `api/src/`, `ios/src/` or `android/src/` +- Paths shown below assume single project - adjust based on plan.md structure + + + +## Phase 1: Setup (Shared Infrastructure) + +**Purpose**: Project initialization and basic structure + +- [ ] T001 Create project structure per implementation plan +- [ ] T002 Initialize [language] project with [framework] dependencies +- [ ] T003 [P] Configure linting and formatting tools + +--- + +## Phase 2: Foundational (Blocking Prerequisites) + +**Purpose**: Core infrastructure that MUST be complete before ANY user story can be implemented + +**⚠️ CRITICAL**: No user story work can begin until this phase is complete + +Examples of foundational tasks (adjust based on your project): + +- [ ] T004 Setup database schema and migrations framework +- [ ] T005 [P] Implement authentication/authorization framework +- [ ] T006 [P] Setup API routing and middleware structure +- [ ] T007 Create base models/entities that all stories depend on +- [ ] T008 Configure error handling and logging infrastructure +- [ ] T009 Setup environment configuration management + +**Checkpoint**: Foundation ready - user story implementation can now begin in parallel + +--- + +## Phase 3: User Story 1 - [Title] (Priority: P1) 🎯 MVP + +**Goal**: [Brief description of what this story delivers] + +**Independent Test**: [How to verify this story works on its own] + +### Tests for User Story 1 (OPTIONAL - only if tests requested) ⚠️ + +> **NOTE: Write these tests FIRST, ensure they FAIL before implementation** + +- [ ] T010 [P] [US1] Contract test for [endpoint] in tests/contract/test_[name].py +- [ ] T011 [P] [US1] Integration test for [user journey] in tests/integration/test_[name].py + +### Implementation for User Story 1 + +- [ ] T012 [P] [US1] Create [Entity1] model in src/models/[entity1].py +- [ ] T013 [P] [US1] Create [Entity2] model in src/models/[entity2].py +- [ ] T014 [US1] Implement [Service] in src/services/[service].py (depends on T012, T013) +- [ ] T015 [US1] Implement [endpoint/feature] in src/[location]/[file].py +- [ ] T016 [US1] Add validation and error handling +- [ ] T017 [US1] Add logging for user story 1 operations + +**Checkpoint**: At this point, User Story 1 should be fully functional and testable independently + +--- + +## Phase 4: User Story 2 - [Title] (Priority: P2) + +**Goal**: [Brief description of what this story delivers] + +**Independent Test**: [How to verify this story works on its own] + +### Tests for User Story 2 (OPTIONAL - only if tests requested) ⚠️ + +- [ ] T018 [P] [US2] Contract test for [endpoint] in tests/contract/test_[name].py +- [ ] T019 [P] [US2] Integration test for [user journey] in tests/integration/test_[name].py + +### Implementation for User Story 2 + +- [ ] T020 [P] [US2] Create [Entity] model in src/models/[entity].py +- [ ] T021 [US2] Implement [Service] in src/services/[service].py +- [ ] T022 [US2] Implement [endpoint/feature] in src/[location]/[file].py +- [ ] T023 [US2] Integrate with User Story 1 components (if needed) + +**Checkpoint**: At this point, User Stories 1 AND 2 should both work independently + +--- + +## Phase 5: User Story 3 - [Title] (Priority: P3) + +**Goal**: [Brief description of what this story delivers] + +**Independent Test**: [How to verify this story works on its own] + +### Tests for User Story 3 (OPTIONAL - only if tests requested) ⚠️ + +- [ ] T024 [P] [US3] Contract test for [endpoint] in tests/contract/test_[name].py +- [ ] T025 [P] [US3] Integration test for [user journey] in tests/integration/test_[name].py + +### Implementation for User Story 3 + +- [ ] T026 [P] [US3] Create [Entity] model in src/models/[entity].py +- [ ] T027 [US3] Implement [Service] in src/services/[service].py +- [ ] T028 [US3] Implement [endpoint/feature] in src/[location]/[file].py + +**Checkpoint**: All user stories should now be independently functional + +--- + +[Add more user story phases as needed, following the same pattern] + +--- + +## Phase N: Polish & Cross-Cutting Concerns + +**Purpose**: Improvements that affect multiple user stories + +- [ ] TXXX [P] Documentation updates in docs/ +- [ ] TXXX Code cleanup and refactoring +- [ ] TXXX Performance optimization across all stories +- [ ] TXXX [P] Additional unit tests (if requested) in tests/unit/ +- [ ] TXXX Security hardening +- [ ] TXXX Run quickstart.md validation + +--- + +## Dependencies & Execution Order + +### Phase Dependencies + +- **Setup (Phase 1)**: No dependencies - can start immediately +- **Foundational (Phase 2)**: Depends on Setup completion - BLOCKS all user stories +- **User Stories (Phase 3+)**: All depend on Foundational phase completion + - User stories can then proceed in parallel (if staffed) + - Or sequentially in priority order (P1 → P2 → P3) +- **Polish (Final Phase)**: Depends on all desired user stories being complete + +### User Story Dependencies + +- **User Story 1 (P1)**: Can start after Foundational (Phase 2) - No dependencies on other stories +- **User Story 2 (P2)**: Can start after Foundational (Phase 2) - May integrate with US1 but should be independently testable +- **User Story 3 (P3)**: Can start after Foundational (Phase 2) - May integrate with US1/US2 but should be independently testable + +### Within Each User Story + +- Tests (if included) MUST be written and FAIL before implementation +- Models before services +- Services before endpoints +- Core implementation before integration +- Story complete before moving to next priority + +### Parallel Opportunities + +- All Setup tasks marked [P] can run in parallel +- All Foundational tasks marked [P] can run in parallel (within Phase 2) +- Once Foundational phase completes, all user stories can start in parallel (if team capacity allows) +- All tests for a user story marked [P] can run in parallel +- Models within a story marked [P] can run in parallel +- Different user stories can be worked on in parallel by different team members + +--- + +## Parallel Example: User Story 1 + +```bash +# Launch all tests for User Story 1 together (if tests requested): +Task: "Contract test for [endpoint] in tests/contract/test_[name].py" +Task: "Integration test for [user journey] in tests/integration/test_[name].py" + +# Launch all models for User Story 1 together: +Task: "Create [Entity1] model in src/models/[entity1].py" +Task: "Create [Entity2] model in src/models/[entity2].py" +``` + +--- + +## Implementation Strategy + +### MVP First (User Story 1 Only) + +1. Complete Phase 1: Setup +2. Complete Phase 2: Foundational (CRITICAL - blocks all stories) +3. Complete Phase 3: User Story 1 +4. **STOP and VALIDATE**: Test User Story 1 independently +5. Deploy/demo if ready + +### Incremental Delivery + +1. Complete Setup + Foundational → Foundation ready +2. Add User Story 1 → Test independently → Deploy/Demo (MVP!) +3. Add User Story 2 → Test independently → Deploy/Demo +4. Add User Story 3 → Test independently → Deploy/Demo +5. Each story adds value without breaking previous stories + +### Parallel Team Strategy + +With multiple developers: + +1. Team completes Setup + Foundational together +2. Once Foundational is done: + - Developer A: User Story 1 + - Developer B: User Story 2 + - Developer C: User Story 3 +3. Stories complete and integrate independently + +--- + +## Notes + +- [P] tasks = different files, no dependencies +- [Story] label maps task to specific user story for traceability +- Each user story should be independently completable and testable +- Verify tests fail before implementing +- Commit after each task or logical group +- Stop at any checkpoint to validate story independently +- Avoid: vague tasks, same file conflicts, cross-story dependencies that break independence From 00187d947d093fad628c3f26a3e99cd4d50a0e5d Mon Sep 17 00:00:00 2001 From: Quratulain-bilal Date: Tue, 7 Apr 2026 00:24:17 +0500 Subject: [PATCH 15/16] feat: publish toc-navigation preset to community catalog (#1970) 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 --- presets/catalog.community.json | 24 ++ .../toc-navigation/commands/speckit.plan.md | 160 --------- .../commands/speckit.specify.md | 316 ------------------ .../toc-navigation/commands/speckit.tasks.md | 204 ----------- presets/toc-navigation/preset.yml | 56 ---- .../toc-navigation/templates/plan-template.md | 112 ------- .../toc-navigation/templates/spec-template.md | 135 -------- .../templates/tasks-template.md | 266 --------------- 8 files changed, 24 insertions(+), 1249 deletions(-) delete mode 100644 presets/toc-navigation/commands/speckit.plan.md delete mode 100644 presets/toc-navigation/commands/speckit.specify.md delete mode 100644 presets/toc-navigation/commands/speckit.tasks.md delete mode 100644 presets/toc-navigation/preset.yml delete mode 100644 presets/toc-navigation/templates/plan-template.md delete mode 100644 presets/toc-navigation/templates/spec-template.md delete mode 100644 presets/toc-navigation/templates/tasks-template.md diff --git a/presets/catalog.community.json b/presets/catalog.community.json index 53616c2d71..73a022cfd1 100644 --- a/presets/catalog.community.json +++ b/presets/catalog.community.json @@ -78,6 +78,30 @@ "experimental" ] }, + "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": { + "templates": 3, + "commands": 3 + }, + "tags": [ + "navigation", + "toc", + "documentation" + ] + }, "vscode-ask-questions": { "name": "VS Code Ask Questions", "id": "vscode-ask-questions", diff --git a/presets/toc-navigation/commands/speckit.plan.md b/presets/toc-navigation/commands/speckit.plan.md deleted file mode 100644 index c9a40da592..0000000000 --- a/presets/toc-navigation/commands/speckit.plan.md +++ /dev/null @@ -1,160 +0,0 @@ ---- -description: Execute the implementation planning workflow using the plan template to generate design artifacts. -handoffs: - - label: Create Tasks - agent: speckit.tasks - prompt: Break the plan into tasks - send: true - - label: Create Checklist - agent: speckit.checklist - prompt: Create a checklist for the following domain... -scripts: - sh: scripts/bash/setup-plan.sh --json - ps: scripts/powershell/setup-plan.ps1 -Json -agent_scripts: - sh: scripts/bash/update-agent-context.sh __AGENT__ - ps: scripts/powershell/update-agent-context.ps1 -AgentType __AGENT__ ---- - -## User Input - -```text -$ARGUMENTS -``` - -You **MUST** consider the user input before proceeding (if not empty). - -## Pre-Execution Checks - -**Check for extension hooks (before planning)**: -- Check if `.specify/extensions.yml` exists in the project root. -- If it exists, read it and look for entries under the `hooks.before_plan` key -- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally -- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default. -- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions: - - If the hook has no `condition` field, or it is null/empty, treat the hook as executable - - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation -- For each executable hook, output the following based on its `optional` flag: - - **Optional hook** (`optional: true`): - ``` - ## Extension Hooks - - **Optional Pre-Hook**: {extension} - Command: `/{command}` - Description: {description} - - Prompt: {prompt} - To execute: `/{command}` - ``` - - **Mandatory hook** (`optional: false`): - ``` - ## Extension Hooks - - **Automatic Pre-Hook**: {extension} - Executing: `/{command}` - EXECUTE_COMMAND: {command} - - Wait for the result of the hook command before proceeding to the Outline. - ``` -- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently - -## Outline - -1. **Setup**: Run `{SCRIPT}` from repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. 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. **Load context**: Read FEATURE_SPEC and `/memory/constitution.md`. Load IMPL_PLAN template (already copied). - -3. **Execute plan workflow**: Follow the structure in IMPL_PLAN template to: - - Include a `## Table of Contents` section immediately after the title and initial metadata lines (Branch, Date, Spec, Input, Note) and before the `## Summary` section. List every `##`-level heading in the final document as a markdown anchor link using GitHub-style anchors (lowercase, spaces to hyphens, strip special characters). Do **not** include a self-referencing entry for `## Table of Contents` itself. Only include headings that actually appear in the final document. - - Fill Technical Context (mark unknowns as "NEEDS CLARIFICATION") - - Fill Constitution Check section from constitution - - Evaluate gates (ERROR if violations unjustified) - - Phase 0: Generate research.md (resolve all NEEDS CLARIFICATION) - - Phase 1: Generate data-model.md, contracts/, quickstart.md - - Phase 1: Update agent context by running the agent script - - Re-evaluate Constitution Check post-design - -4. **Stop and report**: Command ends after Phase 2 planning. Report branch, IMPL_PLAN path, and generated artifacts. - -5. **Check for extension hooks**: After reporting, check if `.specify/extensions.yml` exists in the project root. - - If it exists, read it and look for entries under the `hooks.after_plan` key - - If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally - - Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default. - - For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions: - - If the hook has no `condition` field, or it is null/empty, treat the hook as executable - - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation - - For each executable hook, output the following based on its `optional` flag: - - **Optional hook** (`optional: true`): - ``` - ## Extension Hooks - - **Optional Hook**: {extension} - Command: `/{command}` - Description: {description} - - Prompt: {prompt} - To execute: `/{command}` - ``` - - **Mandatory hook** (`optional: false`): - ``` - ## Extension Hooks - - **Automatic Hook**: {extension} - Executing: `/{command}` - EXECUTE_COMMAND: {command} - ``` - - If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently - -## Phases - -### Phase 0: Outline & Research - -1. **Extract unknowns from Technical Context** above: - - For each NEEDS CLARIFICATION → research task - - For each dependency → best practices task - - For each integration → patterns task - -2. **Generate and dispatch research agents**: - - ```text - For each unknown in Technical Context: - Task: "Research {unknown} for {feature context}" - For each technology choice: - Task: "Find best practices for {tech} in {domain}" - ``` - -3. **Consolidate findings** in `research.md` using format: - - Decision: [what was chosen] - - Rationale: [why chosen] - - Alternatives considered: [what else evaluated] - -**Output**: research.md with all NEEDS CLARIFICATION resolved - -### Phase 1: Design & Contracts - -**Prerequisites:** `research.md` complete - -1. **Extract entities from feature spec** → `data-model.md`: - - Entity name, fields, relationships - - Validation rules from requirements - - State transitions if applicable - -2. **Define interface contracts** (if project has external interfaces) → `/contracts/`: - - Identify what interfaces the project exposes to users or other systems - - Document the contract format appropriate for the project type - - Examples: public APIs for libraries, command schemas for CLI tools, endpoints for web services, grammars for parsers, UI contracts for applications - - Skip if project is purely internal (build scripts, one-off tools, etc.) - -3. **Agent context update**: - - Run `{AGENT_SCRIPT}` - - These scripts detect which AI agent is in use - - Update the appropriate agent-specific context file - - Add only new technology from current plan - - Preserve manual additions between markers - -**Output**: data-model.md, /contracts/*, quickstart.md, agent-specific file - -## Key rules - -- Use absolute paths -- ERROR on gate failures or unresolved clarifications diff --git a/presets/toc-navigation/commands/speckit.specify.md b/presets/toc-navigation/commands/speckit.specify.md deleted file mode 100644 index 55eeff54ae..0000000000 --- a/presets/toc-navigation/commands/speckit.specify.md +++ /dev/null @@ -1,316 +0,0 @@ ---- -description: Create or update the feature specification from a natural language feature description. -handoffs: - - label: Build Technical Plan - agent: speckit.plan - prompt: Create a plan for the spec. I am building with... - - label: Clarify Spec Requirements - agent: speckit.clarify - prompt: Clarify specification requirements - send: true -scripts: - sh: scripts/bash/create-new-feature.sh "{ARGS}" - ps: scripts/powershell/create-new-feature.ps1 "{ARGS}" ---- - -## User Input - -```text -$ARGUMENTS -``` - -You **MUST** consider the user input before proceeding (if not empty). - -## Pre-Execution Checks - -**Check for extension hooks (before specification)**: -- Check if `.specify/extensions.yml` exists in the project root. -- If it exists, read it and look for entries under the `hooks.before_specify` key -- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally -- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default. -- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions: - - If the hook has no `condition` field, or it is null/empty, treat the hook as executable - - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation -- For each executable hook, output the following based on its `optional` flag: - - **Optional hook** (`optional: true`): - ``` - ## Extension Hooks - - **Optional Pre-Hook**: {extension} - Command: `/{command}` - Description: {description} - - Prompt: {prompt} - To execute: `/{command}` - ``` - - **Mandatory hook** (`optional: false`): - ``` - ## Extension Hooks - - **Automatic Pre-Hook**: {extension} - Executing: `/{command}` - EXECUTE_COMMAND: {command} - - Wait for the result of the hook command before proceeding to the Outline. - ``` -- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently - -## Outline - -The text the user typed after `/speckit.specify` in the triggering message **is** the feature description. Assume you always have it available in this conversation even if `{ARGS}` appears literally below. Do not ask the user to repeat it unless they provided an empty command. - -Given that feature description, do this: - -1. **Generate a concise short name** (2-4 words) for the branch: - - Analyze the feature description and extract the most meaningful keywords - - Create a 2-4 word short name that captures the essence of the feature - - Use action-noun format when possible (e.g., "add-user-auth", "fix-payment-bug") - - Preserve technical terms and acronyms (OAuth2, API, JWT, etc.) - - Keep it concise but descriptive enough to understand the feature at a glance - - Examples: - - "I want to add user authentication" → "user-auth" - - "Implement OAuth2 integration for the API" → "oauth2-api-integration" - - "Create a dashboard for analytics" → "analytics-dashboard" - - "Fix payment processing timeout bug" → "fix-payment-timeout" - -2. **Create the feature branch** by running the script with `--short-name` (and `--json`). In sequential mode, do NOT pass `--number` — the script auto-detects the next available number. In timestamp mode, the script generates a `YYYYMMDD-HHMMSS` prefix automatically: - - **Branch numbering mode**: Before running the script, check if `.specify/init-options.json` exists and read the `branch_numbering` value. - - If `"timestamp"`, add `--timestamp` (Bash) or `-Timestamp` (PowerShell) to the script invocation - - If `"sequential"` or absent, do not add any extra flag (default behavior) - - - Bash example: `{SCRIPT} --json --short-name "user-auth" "Add user authentication"` - - Bash (timestamp): `{SCRIPT} --json --timestamp --short-name "user-auth" "Add user authentication"` - - PowerShell example: `{SCRIPT} -Json -ShortName "user-auth" "Add user authentication"` - - PowerShell (timestamp): `{SCRIPT} -Json -Timestamp -ShortName "user-auth" "Add user authentication"` - - **IMPORTANT**: - - Do NOT pass `--number` — the script determines the correct next number automatically - - Always include the JSON flag (`--json` for Bash, `-Json` for PowerShell) so the output can be parsed reliably - - You must only ever run this script once per feature - - The JSON is provided in the terminal as output - always refer to it to get the actual content you're looking for - - The JSON output will contain BRANCH_NAME and SPEC_FILE paths - - 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") - -3. Load `templates/spec-template.md` to understand required sections. - -4. Follow this execution flow: - - 1. Parse user description from Input - If empty: ERROR "No feature description provided" - 2. Extract key concepts from description - Identify: actors, actions, data, constraints - 3. For unclear aspects: - - Make informed guesses based on context and industry standards - - Only mark with [NEEDS CLARIFICATION: specific question] if: - - The choice significantly impacts feature scope or user experience - - Multiple reasonable interpretations exist with different implications - - No reasonable default exists - - **LIMIT: Maximum 3 [NEEDS CLARIFICATION] markers total** - - Prioritize clarifications by impact: scope > security/privacy > user experience > technical details - 4. Fill User Scenarios & Testing section - If no clear user flow: ERROR "Cannot determine user scenarios" - 5. Generate Functional Requirements - Each requirement must be testable - Use reasonable defaults for unspecified details (document assumptions in Assumptions section) - 6. Define Success Criteria - Create measurable, technology-agnostic outcomes - Include both quantitative metrics (time, performance, volume) and qualitative measures (user satisfaction, task completion) - Each criterion must be verifiable without implementation details - 7. Identify Key Entities (if data involved) - 8. Return: SUCCESS (spec ready for planning) - -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. - - **Table of Contents**: Include a `## Table of Contents` section immediately after the title and initial metadata lines (Feature Branch, Created, Status, Input) and before the first content section. The TOC must: - - List every `##`-level heading in the final document as a markdown anchor link - - Use GitHub-style anchors: lowercase, spaces to hyphens, strip `*`, `(`, `)`, and other special characters. Example: `## Requirements *(mandatory)*` becomes `- [Requirements](#requirements-mandatory)` - - Do **not** include a self-referencing entry for `## Table of Contents` itself - - Only include headings that actually appear in the final document - - If the `/speckit.clarify` command later rewrites the spec, it must regenerate the TOC to reflect any added or removed sections - -6. **Specification Quality Validation**: After writing the initial spec, validate it against quality criteria: - - a. **Create Spec Quality Checklist**: Generate a checklist file at `FEATURE_DIR/checklists/requirements.md` using the checklist template structure with these validation items: - - ```markdown - # Specification Quality Checklist: [FEATURE NAME] - - **Purpose**: Validate specification completeness and quality before proceeding to planning - **Created**: [DATE] - **Feature**: [Link to spec.md] - - ## Content Quality - - - [ ] No implementation details (languages, frameworks, APIs) - - [ ] Focused on user value and business needs - - [ ] Written for non-technical stakeholders - - [ ] All mandatory sections completed - - ## Requirement Completeness - - - [ ] No [NEEDS CLARIFICATION] markers remain - - [ ] Requirements are testable and unambiguous - - [ ] Success criteria are measurable - - [ ] Success criteria are technology-agnostic (no implementation details) - - [ ] All acceptance scenarios are defined - - [ ] Edge cases are identified - - [ ] Scope is clearly bounded - - [ ] Dependencies and assumptions identified - - ## Feature Readiness - - - [ ] All functional requirements have clear acceptance criteria - - [ ] User scenarios cover primary flows - - [ ] Feature meets measurable outcomes defined in Success Criteria - - [ ] No implementation details leak into specification - - ## Notes - - - Items marked incomplete require spec updates before `/speckit.clarify` or `/speckit.plan` - ``` - - b. **Run Validation Check**: Review the spec against each checklist item: - - For each item, determine if it passes or fails - - Document specific issues found (quote relevant spec sections) - - c. **Handle Validation Results**: - - - **If all items pass**: Mark checklist complete and proceed to step 7 - - - **If items fail (excluding [NEEDS CLARIFICATION])**: - 1. List the failing items and specific issues - 2. Update the spec to address each issue - 3. Re-run validation until all items pass (max 3 iterations) - 4. If still failing after 3 iterations, document remaining issues in checklist notes and warn user - - - **If [NEEDS CLARIFICATION] markers remain**: - 1. Extract all [NEEDS CLARIFICATION: ...] markers from the spec - 2. **LIMIT CHECK**: If more than 3 markers exist, keep only the 3 most critical (by scope/security/UX impact) and make informed guesses for the rest - 3. For each clarification needed (max 3), present options to user in this format: - - ```markdown - ## Question [N]: [Topic] - - **Context**: [Quote relevant spec section] - - **What we need to know**: [Specific question from NEEDS CLARIFICATION marker] - - **Suggested Answers**: - - | Option | Answer | Implications | - |--------|--------|--------------| - | A | [First suggested answer] | [What this means for the feature] | - | B | [Second suggested answer] | [What this means for the feature] | - | C | [Third suggested answer] | [What this means for the feature] | - | Custom | Provide your own answer | [Explain how to provide custom input] | - - **Your choice**: _[Wait for user response]_ - ``` - - 4. **CRITICAL - Table Formatting**: Ensure markdown tables are properly formatted: - - Use consistent spacing with pipes aligned - - Each cell should have spaces around content: `| Content |` not `|Content|` - - Header separator must have at least 3 dashes: `|--------|` - - Test that the table renders correctly in markdown preview - 5. Number questions sequentially (Q1, Q2, Q3 - max 3 total) - 6. Present all questions together before waiting for responses - 7. Wait for user to respond with their choices for all questions (e.g., "Q1: A, Q2: Custom - [details], Q3: B") - 8. Update the spec by replacing each [NEEDS CLARIFICATION] marker with the user's selected or provided answer - 9. Re-run validation after all clarifications are resolved - - d. **Update Checklist**: After each validation iteration, update the checklist file with current pass/fail status - -7. Report completion with branch name, spec file path, checklist results, and readiness for the next phase (`/speckit.clarify` or `/speckit.plan`). - -8. **Check for extension hooks**: After reporting completion, check if `.specify/extensions.yml` exists in the project root. - - If it exists, read it and look for entries under the `hooks.after_specify` key - - If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally - - Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default. - - For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions: - - If the hook has no `condition` field, or it is null/empty, treat the hook as executable - - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation - - For each executable hook, output the following based on its `optional` flag: - - **Optional hook** (`optional: true`): - ``` - ## Extension Hooks - - **Optional Hook**: {extension} - Command: `/{command}` - Description: {description} - - Prompt: {prompt} - To execute: `/{command}` - ``` - - **Mandatory hook** (`optional: false`): - ``` - ## Extension Hooks - - **Automatic Hook**: {extension} - Executing: `/{command}` - EXECUTE_COMMAND: {command} - ``` - - If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently - -**NOTE:** The script creates and checks out the new branch and initializes the spec file before writing. - -## Quick Guidelines - -- Focus on **WHAT** users need and **WHY**. -- Avoid HOW to implement (no tech stack, APIs, code structure). -- Written for business stakeholders, not developers. -- DO NOT create any checklists that are embedded in the spec. That will be a separate command. - -### Section Requirements - -- **Mandatory sections**: Must be completed for every feature -- **Optional sections**: Include only when relevant to the feature -- When a section doesn't apply, remove it entirely (don't leave as "N/A") - -### For AI Generation - -When creating this spec from a user prompt: - -1. **Make informed guesses**: Use context, industry standards, and common patterns to fill gaps -2. **Document assumptions**: Record reasonable defaults in the Assumptions section -3. **Limit clarifications**: Maximum 3 [NEEDS CLARIFICATION] markers - use only for critical decisions that: - - Significantly impact feature scope or user experience - - Have multiple reasonable interpretations with different implications - - Lack any reasonable default -4. **Prioritize clarifications**: scope > security/privacy > user experience > technical details -5. **Think like a tester**: Every vague requirement should fail the "testable and unambiguous" checklist item -6. **Common areas needing clarification** (only if no reasonable default exists): - - Feature scope and boundaries (include/exclude specific use cases) - - User types and permissions (if multiple conflicting interpretations possible) - - Security/compliance requirements (when legally/financially significant) - -**Examples of reasonable defaults** (don't ask about these): - -- Data retention: Industry-standard practices for the domain -- Performance targets: Standard web/mobile app expectations unless specified -- Error handling: User-friendly messages with appropriate fallbacks -- Authentication method: Standard session-based or OAuth2 for web apps -- Integration patterns: Use project-appropriate patterns (REST/GraphQL for web services, function calls for libraries, CLI args for tools, etc.) - -### Success Criteria Guidelines - -Success criteria must be: - -1. **Measurable**: Include specific metrics (time, percentage, count, rate) -2. **Technology-agnostic**: No mention of frameworks, languages, databases, or tools -3. **User-focused**: Describe outcomes from user/business perspective, not system internals -4. **Verifiable**: Can be tested/validated without knowing implementation details - -**Good examples**: - -- "Users can complete checkout in under 3 minutes" -- "System supports 10,000 concurrent users" -- "95% of searches return results in under 1 second" -- "Task completion rate improves by 40%" - -**Bad examples** (implementation-focused): - -- "API response time is under 200ms" (too technical, use "Users see results instantly") -- "Database can handle 1000 TPS" (implementation detail, use user-facing metric) -- "React components render efficiently" (framework-specific) -- "Redis cache hit rate above 80%" (technology-specific) diff --git a/presets/toc-navigation/commands/speckit.tasks.md b/presets/toc-navigation/commands/speckit.tasks.md deleted file mode 100644 index 7d03f8c053..0000000000 --- a/presets/toc-navigation/commands/speckit.tasks.md +++ /dev/null @@ -1,204 +0,0 @@ ---- -description: Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts. -handoffs: - - label: Analyze For Consistency - agent: speckit.analyze - prompt: Run a project analysis for consistency - send: true - - label: Implement Project - agent: speckit.implement - prompt: Start the implementation in phases - send: true -scripts: - sh: scripts/bash/check-prerequisites.sh --json - ps: scripts/powershell/check-prerequisites.ps1 -Json ---- - -## User Input - -```text -$ARGUMENTS -``` - -You **MUST** consider the user input before proceeding (if not empty). - -## Pre-Execution Checks - -**Check for extension hooks (before tasks generation)**: -- Check if `.specify/extensions.yml` exists in the project root. -- If it exists, read it and look for entries under the `hooks.before_tasks` key -- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally -- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default. -- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions: - - If the hook has no `condition` field, or it is null/empty, treat the hook as executable - - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation -- For each executable hook, output the following based on its `optional` flag: - - **Optional hook** (`optional: true`): - ``` - ## Extension Hooks - - **Optional Pre-Hook**: {extension} - Command: `/{command}` - Description: {description} - - Prompt: {prompt} - To execute: `/{command}` - ``` - - **Mandatory hook** (`optional: false`): - ``` - ## Extension Hooks - - **Automatic Pre-Hook**: {extension} - Executing: `/{command}` - EXECUTE_COMMAND: {command} - - Wait for the result of the hook command before proceeding to the Outline. - ``` -- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently - -## Outline - -1. **Setup**: Run `{SCRIPT}` 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. **Load design documents**: Read from FEATURE_DIR: - - **Required**: plan.md (tech stack, libraries, structure), spec.md (user stories with priorities) - - **Optional**: data-model.md (entities), contracts/ (interface contracts), research.md (decisions), quickstart.md (test scenarios) - - Note: Not all projects have all documents. Generate tasks based on what's available. - -3. **Execute task generation workflow**: - - Load plan.md and extract tech stack, libraries, project structure - - Load spec.md and extract user stories with their priorities (P1, P2, P3, etc.) - - If data-model.md exists: Extract entities and map to user stories - - If contracts/ exists: Map interface contracts to user stories - - If research.md exists: Extract decisions for setup tasks - - Generate tasks organized by user story (see Task Generation Rules below) - - Generate dependency graph showing user story completion order - - Create parallel execution examples per user story - - Validate task completeness (each user story has all needed tasks, independently testable) - -4. **Generate tasks.md**: Use `templates/tasks-template.md` as structure, fill with: - - A `## Table of Contents` section immediately after the title and initial metadata lines (Input, Prerequisites, Tests, Organization) and before the first phase. List every `##`-level heading in the final document as a markdown anchor link using GitHub-style anchors (lowercase, spaces to hyphens, strip special characters). Do **not** include a self-referencing entry for `## Table of Contents` itself. Only include headings that actually appear in the final document. Note: the `## Table of Contents` section is navigational only — downstream consumers like `/speckit.implement` must not treat it as a phase or task group. - - Correct feature name from plan.md - - Phase 1: Setup tasks (project initialization) - - Phase 2: Foundational tasks (blocking prerequisites for all user stories) - - Phase 3+: One phase per user story (in priority order from spec.md) - - Each phase includes: story goal, independent test criteria, tests (if requested), implementation tasks - - Final Phase: Polish & cross-cutting concerns - - All tasks must follow the strict checklist format (see Task Generation Rules below) - - Clear file paths for each task - - Dependencies section showing story completion order - - Parallel execution examples per story - - Implementation strategy section (MVP first, incremental delivery) - -5. **Report**: Output path to generated tasks.md and summary: - - Total task count - - Task count per user story - - Parallel opportunities identified - - Independent test criteria for each story - - Suggested MVP scope (typically just User Story 1) - - Format validation: Confirm ALL tasks follow the checklist format (checkbox, ID, labels, file paths) - -6. **Check for extension hooks**: After tasks.md is generated, check if `.specify/extensions.yml` exists in the project root. - - If it exists, read it and look for entries under the `hooks.after_tasks` key - - If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally - - Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default. - - For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions: - - If the hook has no `condition` field, or it is null/empty, treat the hook as executable - - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation - - For each executable hook, output the following based on its `optional` flag: - - **Optional hook** (`optional: true`): - ``` - ## Extension Hooks - - **Optional Hook**: {extension} - Command: `/{command}` - Description: {description} - - Prompt: {prompt} - To execute: `/{command}` - ``` - - **Mandatory hook** (`optional: false`): - ``` - ## Extension Hooks - - **Automatic Hook**: {extension} - Executing: `/{command}` - EXECUTE_COMMAND: {command} - ``` - - If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently - -Context for task generation: {ARGS} - -The tasks.md should be immediately executable - each task must be specific enough that an LLM can complete it without additional context. - -## Task Generation Rules - -**CRITICAL**: Tasks MUST be organized by user story to enable independent implementation and testing. - -**Tests are OPTIONAL**: Only generate test tasks if explicitly requested in the feature specification or if user requests TDD approach. - -### Checklist Format (REQUIRED) - -Every task MUST strictly follow this format: - -```text -- [ ] [TaskID] [P?] [Story?] Description with file path -``` - -**Format Components**: - -1. **Checkbox**: ALWAYS start with `- [ ]` (markdown checkbox) -2. **Task ID**: Sequential number (T001, T002, T003...) in execution order -3. **[P] marker**: Include ONLY if task is parallelizable (different files, no dependencies on incomplete tasks) -4. **[Story] label**: REQUIRED for user story phase tasks only - - Format: [US1], [US2], [US3], etc. (maps to user stories from spec.md) - - Setup phase: NO story label - - Foundational phase: NO story label - - User Story phases: MUST have story label - - Polish phase: NO story label -5. **Description**: Clear action with exact file path - -**Examples**: - -- ✅ CORRECT: `- [ ] T001 Create project structure per implementation plan` -- ✅ CORRECT: `- [ ] T005 [P] Implement authentication middleware in src/middleware/auth.py` -- ✅ CORRECT: `- [ ] T012 [P] [US1] Create User model in src/models/user.py` -- ✅ CORRECT: `- [ ] T014 [US1] Implement UserService in src/services/user_service.py` -- ❌ WRONG: `- [ ] Create User model` (missing ID and Story label) -- ❌ WRONG: `T001 [US1] Create model` (missing checkbox) -- ❌ WRONG: `- [ ] [US1] Create User model` (missing Task ID) -- ❌ WRONG: `- [ ] T001 [US1] Create model` (missing file path) - -### Task Organization - -1. **From User Stories (spec.md)** - PRIMARY ORGANIZATION: - - Each user story (P1, P2, P3...) gets its own phase - - Map all related components to their story: - - Models needed for that story - - Services needed for that story - - Interfaces/UI needed for that story - - If tests requested: Tests specific to that story - - Mark story dependencies (most stories should be independent) - -2. **From Contracts**: - - Map each interface contract → to the user story it serves - - If tests requested: Each interface contract → contract test task [P] before implementation in that story's phase - -3. **From Data Model**: - - Map each entity to the user story(ies) that need it - - If entity serves multiple stories: Put in earliest story or Setup phase - - Relationships → service layer tasks in appropriate story phase - -4. **From Setup/Infrastructure**: - - Shared infrastructure → Setup phase (Phase 1) - - Foundational/blocking tasks → Foundational phase (Phase 2) - - Story-specific setup → within that story's phase - -### Phase Structure - -- **Phase 1**: Setup (project initialization) -- **Phase 2**: Foundational (blocking prerequisites - MUST complete before user stories) -- **Phase 3+**: User Stories in priority order (P1, P2, P3...) - - Within each story: Tests (if requested) → Models → Services → Endpoints → Integration - - Each phase should be a complete, independently testable increment -- **Final Phase**: Polish & Cross-Cutting Concerns diff --git a/presets/toc-navigation/preset.yml b/presets/toc-navigation/preset.yml deleted file mode 100644 index 306b1ddd6d..0000000000 --- a/presets/toc-navigation/preset.yml +++ /dev/null @@ -1,56 +0,0 @@ -schema_version: "1.0" - -preset: - id: "toc-navigation" - name: "Table of Contents 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/github/spec-kit" - license: "MIT" - -requires: - speckit_version: ">=0.4.0" - -provides: - templates: - - type: "template" - name: "spec-template" - file: "templates/spec-template.md" - description: "Spec template with Table of Contents section" - replaces: "spec-template" - - - type: "template" - name: "plan-template" - file: "templates/plan-template.md" - description: "Plan template with Table of Contents section" - replaces: "plan-template" - - - type: "template" - name: "tasks-template" - file: "templates/tasks-template.md" - description: "Tasks template with Table of Contents section" - replaces: "tasks-template" - - - type: "command" - name: "speckit.specify" - file: "commands/speckit.specify.md" - description: "Specify command with TOC generation instructions" - replaces: "speckit.specify" - - - type: "command" - name: "speckit.plan" - file: "commands/speckit.plan.md" - description: "Plan command with TOC generation instructions" - replaces: "speckit.plan" - - - type: "command" - name: "speckit.tasks" - file: "commands/speckit.tasks.md" - description: "Tasks command with TOC generation instructions" - replaces: "speckit.tasks" - -tags: - - "navigation" - - "toc" - - "documentation" diff --git a/presets/toc-navigation/templates/plan-template.md b/presets/toc-navigation/templates/plan-template.md deleted file mode 100644 index dd98ae7848..0000000000 --- a/presets/toc-navigation/templates/plan-template.md +++ /dev/null @@ -1,112 +0,0 @@ -# Implementation Plan: [FEATURE] - -**Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link] -**Input**: Feature specification from `/specs/[###-feature-name]/spec.md` - -**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/plan-template.md` for the execution workflow. - -## Table of Contents - -- [Summary](#summary) -- [Technical Context](#technical-context) -- [Constitution Check](#constitution-check) -- [Project Structure](#project-structure) -- [Complexity Tracking](#complexity-tracking) - -## Summary - -[Extract from feature spec: primary requirement + technical approach from research] - -## Technical Context - - - -**Language/Version**: [e.g., Python 3.11, Swift 5.9, Rust 1.75 or NEEDS CLARIFICATION] -**Primary Dependencies**: [e.g., FastAPI, UIKit, LLVM or NEEDS CLARIFICATION] -**Storage**: [if applicable, e.g., PostgreSQL, CoreData, files or N/A] -**Testing**: [e.g., pytest, XCTest, cargo test or NEEDS CLARIFICATION] -**Target Platform**: [e.g., Linux server, iOS 15+, WASM or NEEDS CLARIFICATION] -**Project Type**: [e.g., library/cli/web-service/mobile-app/compiler/desktop-app or NEEDS CLARIFICATION] -**Performance Goals**: [domain-specific, e.g., 1000 req/s, 10k lines/sec, 60 fps or NEEDS CLARIFICATION] -**Constraints**: [domain-specific, e.g., <200ms p95, <100MB memory, offline-capable or NEEDS CLARIFICATION] -**Scale/Scope**: [domain-specific, e.g., 10k users, 1M LOC, 50 screens or NEEDS CLARIFICATION] - -## Constitution Check - -*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.* - -[Gates determined based on constitution file] - -## Project Structure - -### Documentation (this feature) - -```text -specs/[###-feature]/ -├── plan.md # This file (/speckit.plan command output) -├── research.md # Phase 0 output (/speckit.plan command) -├── data-model.md # Phase 1 output (/speckit.plan command) -├── quickstart.md # Phase 1 output (/speckit.plan command) -├── contracts/ # Phase 1 output (/speckit.plan command) -└── tasks.md # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan) -``` - -### Source Code (repository root) - - -```text -# [REMOVE IF UNUSED] Option 1: Single project (DEFAULT) -src/ -├── models/ -├── services/ -├── cli/ -└── lib/ - -tests/ -├── contract/ -├── integration/ -└── unit/ - -# [REMOVE IF UNUSED] Option 2: Web application (when "frontend" + "backend" detected) -backend/ -├── src/ -│ ├── models/ -│ ├── services/ -│ └── api/ -└── tests/ - -frontend/ -├── src/ -│ ├── components/ -│ ├── pages/ -│ └── services/ -└── tests/ - -# [REMOVE IF UNUSED] Option 3: Mobile + API (when "iOS/Android" detected) -api/ -└── [same as backend above] - -ios/ or android/ -└── [platform-specific structure: feature modules, UI flows, platform tests] -``` - -**Structure Decision**: [Document the selected structure and reference the real -directories captured above] - -## Complexity Tracking - -> **Fill ONLY if Constitution Check has violations that must be justified** - -| Violation | Why Needed | Simpler Alternative Rejected Because | -|-----------|------------|-------------------------------------| -| [e.g., 4th project] | [current need] | [why 3 projects insufficient] | -| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient] | diff --git a/presets/toc-navigation/templates/spec-template.md b/presets/toc-navigation/templates/spec-template.md deleted file mode 100644 index cb751b1d24..0000000000 --- a/presets/toc-navigation/templates/spec-template.md +++ /dev/null @@ -1,135 +0,0 @@ -# Feature Specification: [FEATURE NAME] - -**Feature Branch**: `[###-feature-name]` -**Created**: [DATE] -**Status**: Draft -**Input**: User description: "$ARGUMENTS" - -## Table of Contents - -- [User Scenarios & Testing](#user-scenarios--testing-mandatory) -- [Requirements](#requirements-mandatory) -- [Success Criteria](#success-criteria-mandatory) -- [Assumptions](#assumptions) - -## User Scenarios & Testing *(mandatory)* - - - -### User Story 1 - [Brief Title] (Priority: P1) - -[Describe this user journey in plain language] - -**Why this priority**: [Explain the value and why it has this priority level] - -**Independent Test**: [Describe how this can be tested independently - e.g., "Can be fully tested by [specific action] and delivers [specific value]"] - -**Acceptance Scenarios**: - -1. **Given** [initial state], **When** [action], **Then** [expected outcome] -2. **Given** [initial state], **When** [action], **Then** [expected outcome] - ---- - -### User Story 2 - [Brief Title] (Priority: P2) - -[Describe this user journey in plain language] - -**Why this priority**: [Explain the value and why it has this priority level] - -**Independent Test**: [Describe how this can be tested independently] - -**Acceptance Scenarios**: - -1. **Given** [initial state], **When** [action], **Then** [expected outcome] - ---- - -### User Story 3 - [Brief Title] (Priority: P3) - -[Describe this user journey in plain language] - -**Why this priority**: [Explain the value and why it has this priority level] - -**Independent Test**: [Describe how this can be tested independently] - -**Acceptance Scenarios**: - -1. **Given** [initial state], **When** [action], **Then** [expected outcome] - ---- - -[Add more user stories as needed, each with an assigned priority] - -### Edge Cases - - - -- What happens when [boundary condition]? -- How does system handle [error scenario]? - -## Requirements *(mandatory)* - - - -### Functional Requirements - -- **FR-001**: System MUST [specific capability, e.g., "allow users to create accounts"] -- **FR-002**: System MUST [specific capability, e.g., "validate email addresses"] -- **FR-003**: Users MUST be able to [key interaction, e.g., "reset their password"] -- **FR-004**: System MUST [data requirement, e.g., "persist user preferences"] -- **FR-005**: System MUST [behavior, e.g., "log all security events"] - -*Example of marking unclear requirements:* - -- **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?] -- **FR-007**: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified] - -### Key Entities *(include if feature involves data)* - -- **[Entity 1]**: [What it represents, key attributes without implementation] -- **[Entity 2]**: [What it represents, relationships to other entities] - -## Success Criteria *(mandatory)* - - - -### Measurable Outcomes - -- **SC-001**: [Measurable metric, e.g., "Users can complete account creation in under 2 minutes"] -- **SC-002**: [Measurable metric, e.g., "System handles 1000 concurrent users without degradation"] -- **SC-003**: [User satisfaction metric, e.g., "90% of users successfully complete primary task on first attempt"] -- **SC-004**: [Business metric, e.g., "Reduce support tickets related to [X] by 50%"] - -## Assumptions - - - -- [Assumption about target users, e.g., "Users have stable internet connectivity"] -- [Assumption about scope boundaries, e.g., "Mobile support is out of scope for v1"] -- [Assumption about data/environment, e.g., "Existing authentication system will be reused"] -- [Dependency on existing system/service, e.g., "Requires access to the existing user profile API"] diff --git a/presets/toc-navigation/templates/tasks-template.md b/presets/toc-navigation/templates/tasks-template.md deleted file mode 100644 index 494e858a0f..0000000000 --- a/presets/toc-navigation/templates/tasks-template.md +++ /dev/null @@ -1,266 +0,0 @@ ---- - -description: "Task list template for feature implementation" ---- - -# Tasks: [FEATURE NAME] - -**Input**: Design documents from `/specs/[###-feature-name]/` -**Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/ - -**Tests**: The examples below include test tasks. Tests are OPTIONAL - only include them if explicitly requested in the feature specification. - -**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story. - -## Table of Contents - -- [Format](#format-id-p-story-description) -- [Path Conventions](#path-conventions) -- [Phase 1: Setup (Shared Infrastructure)](#phase-1-setup-shared-infrastructure) -- [Phase 2: Foundational (Blocking Prerequisites)](#phase-2-foundational-blocking-prerequisites) -- Phase 3: User Story 1 (generated from spec.md) -- Phase 4: User Story 2 (generated from spec.md) -- Phase 5: User Story 3 (generated from spec.md) -- [Phase N: Polish & Cross-Cutting Concerns](#phase-n-polish--cross-cutting-concerns) -- [Dependencies & Execution Order](#dependencies--execution-order) -- [Parallel Example: User Story 1](#parallel-example-user-story-1) -- [Implementation Strategy](#implementation-strategy) -- [Notes](#notes) - -## Format: `[ID] [P?] [Story] Description` - -- **[P]**: Can run in parallel (different files, no dependencies) -- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3) -- Include exact file paths in descriptions - -## Path Conventions - -- **Single project**: `src/`, `tests/` at repository root -- **Web app**: `backend/src/`, `frontend/src/` -- **Mobile**: `api/src/`, `ios/src/` or `android/src/` -- Paths shown below assume single project - adjust based on plan.md structure - - - -## Phase 1: Setup (Shared Infrastructure) - -**Purpose**: Project initialization and basic structure - -- [ ] T001 Create project structure per implementation plan -- [ ] T002 Initialize [language] project with [framework] dependencies -- [ ] T003 [P] Configure linting and formatting tools - ---- - -## Phase 2: Foundational (Blocking Prerequisites) - -**Purpose**: Core infrastructure that MUST be complete before ANY user story can be implemented - -**⚠️ CRITICAL**: No user story work can begin until this phase is complete - -Examples of foundational tasks (adjust based on your project): - -- [ ] T004 Setup database schema and migrations framework -- [ ] T005 [P] Implement authentication/authorization framework -- [ ] T006 [P] Setup API routing and middleware structure -- [ ] T007 Create base models/entities that all stories depend on -- [ ] T008 Configure error handling and logging infrastructure -- [ ] T009 Setup environment configuration management - -**Checkpoint**: Foundation ready - user story implementation can now begin in parallel - ---- - -## Phase 3: User Story 1 - [Title] (Priority: P1) 🎯 MVP - -**Goal**: [Brief description of what this story delivers] - -**Independent Test**: [How to verify this story works on its own] - -### Tests for User Story 1 (OPTIONAL - only if tests requested) ⚠️ - -> **NOTE: Write these tests FIRST, ensure they FAIL before implementation** - -- [ ] T010 [P] [US1] Contract test for [endpoint] in tests/contract/test_[name].py -- [ ] T011 [P] [US1] Integration test for [user journey] in tests/integration/test_[name].py - -### Implementation for User Story 1 - -- [ ] T012 [P] [US1] Create [Entity1] model in src/models/[entity1].py -- [ ] T013 [P] [US1] Create [Entity2] model in src/models/[entity2].py -- [ ] T014 [US1] Implement [Service] in src/services/[service].py (depends on T012, T013) -- [ ] T015 [US1] Implement [endpoint/feature] in src/[location]/[file].py -- [ ] T016 [US1] Add validation and error handling -- [ ] T017 [US1] Add logging for user story 1 operations - -**Checkpoint**: At this point, User Story 1 should be fully functional and testable independently - ---- - -## Phase 4: User Story 2 - [Title] (Priority: P2) - -**Goal**: [Brief description of what this story delivers] - -**Independent Test**: [How to verify this story works on its own] - -### Tests for User Story 2 (OPTIONAL - only if tests requested) ⚠️ - -- [ ] T018 [P] [US2] Contract test for [endpoint] in tests/contract/test_[name].py -- [ ] T019 [P] [US2] Integration test for [user journey] in tests/integration/test_[name].py - -### Implementation for User Story 2 - -- [ ] T020 [P] [US2] Create [Entity] model in src/models/[entity].py -- [ ] T021 [US2] Implement [Service] in src/services/[service].py -- [ ] T022 [US2] Implement [endpoint/feature] in src/[location]/[file].py -- [ ] T023 [US2] Integrate with User Story 1 components (if needed) - -**Checkpoint**: At this point, User Stories 1 AND 2 should both work independently - ---- - -## Phase 5: User Story 3 - [Title] (Priority: P3) - -**Goal**: [Brief description of what this story delivers] - -**Independent Test**: [How to verify this story works on its own] - -### Tests for User Story 3 (OPTIONAL - only if tests requested) ⚠️ - -- [ ] T024 [P] [US3] Contract test for [endpoint] in tests/contract/test_[name].py -- [ ] T025 [P] [US3] Integration test for [user journey] in tests/integration/test_[name].py - -### Implementation for User Story 3 - -- [ ] T026 [P] [US3] Create [Entity] model in src/models/[entity].py -- [ ] T027 [US3] Implement [Service] in src/services/[service].py -- [ ] T028 [US3] Implement [endpoint/feature] in src/[location]/[file].py - -**Checkpoint**: All user stories should now be independently functional - ---- - -[Add more user story phases as needed, following the same pattern] - ---- - -## Phase N: Polish & Cross-Cutting Concerns - -**Purpose**: Improvements that affect multiple user stories - -- [ ] TXXX [P] Documentation updates in docs/ -- [ ] TXXX Code cleanup and refactoring -- [ ] TXXX Performance optimization across all stories -- [ ] TXXX [P] Additional unit tests (if requested) in tests/unit/ -- [ ] TXXX Security hardening -- [ ] TXXX Run quickstart.md validation - ---- - -## Dependencies & Execution Order - -### Phase Dependencies - -- **Setup (Phase 1)**: No dependencies - can start immediately -- **Foundational (Phase 2)**: Depends on Setup completion - BLOCKS all user stories -- **User Stories (Phase 3+)**: All depend on Foundational phase completion - - User stories can then proceed in parallel (if staffed) - - Or sequentially in priority order (P1 → P2 → P3) -- **Polish (Final Phase)**: Depends on all desired user stories being complete - -### User Story Dependencies - -- **User Story 1 (P1)**: Can start after Foundational (Phase 2) - No dependencies on other stories -- **User Story 2 (P2)**: Can start after Foundational (Phase 2) - May integrate with US1 but should be independently testable -- **User Story 3 (P3)**: Can start after Foundational (Phase 2) - May integrate with US1/US2 but should be independently testable - -### Within Each User Story - -- Tests (if included) MUST be written and FAIL before implementation -- Models before services -- Services before endpoints -- Core implementation before integration -- Story complete before moving to next priority - -### Parallel Opportunities - -- All Setup tasks marked [P] can run in parallel -- All Foundational tasks marked [P] can run in parallel (within Phase 2) -- Once Foundational phase completes, all user stories can start in parallel (if team capacity allows) -- All tests for a user story marked [P] can run in parallel -- Models within a story marked [P] can run in parallel -- Different user stories can be worked on in parallel by different team members - ---- - -## Parallel Example: User Story 1 - -```bash -# Launch all tests for User Story 1 together (if tests requested): -Task: "Contract test for [endpoint] in tests/contract/test_[name].py" -Task: "Integration test for [user journey] in tests/integration/test_[name].py" - -# Launch all models for User Story 1 together: -Task: "Create [Entity1] model in src/models/[entity1].py" -Task: "Create [Entity2] model in src/models/[entity2].py" -``` - ---- - -## Implementation Strategy - -### MVP First (User Story 1 Only) - -1. Complete Phase 1: Setup -2. Complete Phase 2: Foundational (CRITICAL - blocks all stories) -3. Complete Phase 3: User Story 1 -4. **STOP and VALIDATE**: Test User Story 1 independently -5. Deploy/demo if ready - -### Incremental Delivery - -1. Complete Setup + Foundational → Foundation ready -2. Add User Story 1 → Test independently → Deploy/Demo (MVP!) -3. Add User Story 2 → Test independently → Deploy/Demo -4. Add User Story 3 → Test independently → Deploy/Demo -5. Each story adds value without breaking previous stories - -### Parallel Team Strategy - -With multiple developers: - -1. Team completes Setup + Foundational together -2. Once Foundational is done: - - Developer A: User Story 1 - - Developer B: User Story 2 - - Developer C: User Story 3 -3. Stories complete and integrate independently - ---- - -## Notes - -- [P] tasks = different files, no dependencies -- [Story] label maps task to specific user story for traceability -- Each user story should be independently completable and testable -- Verify tests fail before implementing -- Commit after each task or logical group -- Stop at any checkpoint to validate story independently -- Avoid: vague tasks, same file conflicts, cross-story dependencies that break independence From 263e5ae2a10d29242708e9d64694cb47103038cd Mon Sep 17 00:00:00 2001 From: Quratulain-bilal Date: Tue, 7 Apr 2026 21:46:05 +0500 Subject: [PATCH 16/16] Add toc-navigation preset to main README community presets table 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. --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 45f6bb91bc..be83ee9684 100644 --- a/README.md +++ b/README.md @@ -244,6 +244,7 @@ The following community-contributed presets customize how Spec Kit behaves — o | AIDE In-Place Migration | Adapts the AIDE extension workflow for in-place technology migrations (X → Y pattern) — adds migration objectives, verification gates, knowledge documents, and behavioral equivalence criteria | 2 templates, 8 commands | AIDE extension | [spec-kit-presets](https://github.com/mnriem/spec-kit-presets) | | Canon Core | Adapts original Spec Kit workflow to work together with Canon extension | 2 templates, 8 commands | — | [spec-kit-canon](https://github.com/maximiliamus/spec-kit-canon) | | Pirate Speak (Full) | Transforms all Spec Kit output into pirate speak — specs become "Voyage Manifests", plans become "Battle Plans", tasks become "Crew Assignments" | 6 templates, 9 commands | — | [spec-kit-presets](https://github.com/mnriem/spec-kit-presets) | +| Table of Contents Navigation | Adds a navigable Table of Contents to generated spec.md, plan.md, and tasks.md documents | 3 templates, 3 commands | — | [spec-kit-preset-toc-navigation](https://github.com/Quratulain-bilal/spec-kit-preset-toc-navigation) | | VS Code Ask Questions | Enhances the clarify command to use `vscode/askQuestions` for batched interactive questioning. | 1 command | — | [spec-kit-presets](https://github.com/fdcastel/spec-kit-presets) | To build and publish your own preset, see the [Presets Publishing Guide](presets/PUBLISHING.md).