From d3af40f28f88b083fb81594b2ca590dac5edf734 Mon Sep 17 00:00:00 2001 From: Dyan Galih Date: Fri, 26 Jun 2026 01:54:12 +0000 Subject: [PATCH 1/2] docs: document /speckit.converge command --- docs/guides/evolving-specs.md | 2 ++ docs/installation.md | 9 ++++++++- docs/quickstart.md | 12 ++++++++++-- 3 files changed, 20 insertions(+), 3 deletions(-) diff --git a/docs/guides/evolving-specs.md b/docs/guides/evolving-specs.md index feb2c88706..37125e8943 100644 --- a/docs/guides/evolving-specs.md +++ b/docs/guides/evolving-specs.md @@ -26,6 +26,7 @@ through the standard flow: 2. Run `/speckit.plan` to define the implementation approach. 3. Run `/speckit.tasks` to derive the work breakdown. 4. Run `/speckit.implement` and review the resulting code and artifact diffs. +5. Run `/speckit.converge` to verify completeness and generate tasks for remaining gaps. The previous feature directory remains intact for audit, comparison, or explaining how the project reached its current state. Use clear feature names or @@ -50,6 +51,7 @@ spec: 5. Run `/speckit.analyze` before implementation resumes to catch gaps between the spec, plan, and tasks. 6. Run `/speckit.implement`, then review the code and artifact diffs together. +7. Run `/speckit.converge` to assess completion and append any remaining work to `tasks.md`. Preserve important implementation rationale before replacing derived artifacts. If a plan or task list contains decisions that still matter, carry them forward diff --git a/docs/installation.md b/docs/installation.md index 0f4c9124ec..12708dc5d6 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -94,8 +94,15 @@ This helps verify you are running the official Spec Kit build from GitHub, not a After initialization, you should see the following commands available in your coding agent: - `/speckit.specify` - Create specifications -- `/speckit.plan` - Generate implementation plans +- `/speckit.plan` - Generate implementation plans - `/speckit.tasks` - Break down into actionable tasks +- `/speckit.implement` - Execute implementation tasks +- `/speckit.analyze` - Validate cross-artifact consistency +- `/speckit.clarify` - Identify and resolve ambiguities +- `/speckit.checklist` - Generate quality checklists +- `/speckit.constitution` - Create or update project principles +- `/speckit.converge` - Assess codebase against artifacts and append remaining tasks +- `/speckit.taskstoissues` - Convert tasks to issues Scripts are installed into a variant subdirectory matching the chosen script type: diff --git a/docs/quickstart.md b/docs/quickstart.md index 964c1f1da4..6008d98281 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -13,10 +13,10 @@ This guide will help you get started with Spec-Driven Development using Spec Kit After installing Spec Kit and defining your project constitution, quick experiments can use the lean feature path: `/speckit.specify` -> `/speckit.plan` -> `/speckit.tasks` -> `/speckit.implement`. For production features or any work with meaningful ambiguity, treat `/speckit.clarify`, `/speckit.checklist`, and `/speckit.analyze` as regular quality gates: ```text -/speckit.constitution -> /speckit.specify -> /speckit.clarify -> /speckit.plan -> /speckit.checklist -> /speckit.tasks -> /speckit.analyze -> /speckit.implement +/speckit.constitution -> /speckit.specify -> /speckit.clarify -> /speckit.plan -> /speckit.checklist -> /speckit.tasks -> /speckit.analyze -> /speckit.implement -> /speckit.converge ``` -Use `/speckit.clarify` to reduce requirement ambiguity before planning, `/speckit.checklist` (after `/speckit.plan`) to generate quality checklists that validate requirements completeness, clarity, and consistency, and `/speckit.analyze` to check spec/plan/task consistency before implementation starts. You can repeat `/speckit.analyze` after implementation as an extra review, but keep the first analysis before `/speckit.implement` so gaps are caught while the plan and tasks can still be adjusted. +Use `/speckit.clarify` to reduce requirement ambiguity before planning, `/speckit.checklist` (after `/speckit.plan`) to generate quality checklists that validate requirements completeness, clarity, and consistency, and `/speckit.analyze` to check spec/plan/task consistency before implementation starts. You can repeat `/speckit.analyze` after implementation as an extra review, but keep the first analysis before `/speckit.implement` so gaps are caught while the plan and tasks can still be adjusted. Finally, run `/speckit.converge` after implementation to verify all planned work is complete and generate tasks for any remaining gaps. ### Step 1: Install Specify @@ -188,6 +188,14 @@ Finally, implement the solution: /speckit.implement ``` +### Step 8: Converge + +Run the `/speckit.converge` command after implementation to assess the current codebase against the feature's artifacts and append any remaining unbuilt work as new tasks to `tasks.md`. + +```bash +/speckit.converge +``` + > [!TIP] > **Phased Implementation**: For large projects like Taskify, consider implementing in phases (e.g., Phase 1: Basic project/task structure, Phase 2: Kanban functionality, Phase 3: Comments and assignments). This prevents context saturation and allows for validation at each stage. From fdba6a594be082c778c2461432c044d9cf0fb6d4 Mon Sep 17 00:00:00 2001 From: Dyan Galih Date: Fri, 26 Jun 2026 02:01:42 +0000 Subject: [PATCH 2/2] docs: clarify converge and implement loop --- docs/guides/evolving-specs.md | 4 ++-- docs/quickstart.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/guides/evolving-specs.md b/docs/guides/evolving-specs.md index 37125e8943..e2941f08b3 100644 --- a/docs/guides/evolving-specs.md +++ b/docs/guides/evolving-specs.md @@ -26,7 +26,7 @@ through the standard flow: 2. Run `/speckit.plan` to define the implementation approach. 3. Run `/speckit.tasks` to derive the work breakdown. 4. Run `/speckit.implement` and review the resulting code and artifact diffs. -5. Run `/speckit.converge` to verify completeness and generate tasks for remaining gaps. +5. Run `/speckit.converge` to verify completeness and generate tasks for remaining gaps. If tasks are appended, repeat `/speckit.implement` and `/speckit.converge` until the feature is fully complete. The previous feature directory remains intact for audit, comparison, or explaining how the project reached its current state. Use clear feature names or @@ -51,7 +51,7 @@ spec: 5. Run `/speckit.analyze` before implementation resumes to catch gaps between the spec, plan, and tasks. 6. Run `/speckit.implement`, then review the code and artifact diffs together. -7. Run `/speckit.converge` to assess completion and append any remaining work to `tasks.md`. +7. Run `/speckit.converge` to assess completion and append any remaining work to `tasks.md`. If tasks are appended, repeat `/speckit.implement` and `/speckit.converge` until the feature is fully complete. Preserve important implementation rationale before replacing derived artifacts. If a plan or task list contains decisions that still matter, carry them forward diff --git a/docs/quickstart.md b/docs/quickstart.md index 6008d98281..d03808da5b 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -16,7 +16,7 @@ After installing Spec Kit and defining your project constitution, quick experime /speckit.constitution -> /speckit.specify -> /speckit.clarify -> /speckit.plan -> /speckit.checklist -> /speckit.tasks -> /speckit.analyze -> /speckit.implement -> /speckit.converge ``` -Use `/speckit.clarify` to reduce requirement ambiguity before planning, `/speckit.checklist` (after `/speckit.plan`) to generate quality checklists that validate requirements completeness, clarity, and consistency, and `/speckit.analyze` to check spec/plan/task consistency before implementation starts. You can repeat `/speckit.analyze` after implementation as an extra review, but keep the first analysis before `/speckit.implement` so gaps are caught while the plan and tasks can still be adjusted. Finally, run `/speckit.converge` after implementation to verify all planned work is complete and generate tasks for any remaining gaps. +Use `/speckit.clarify` to reduce requirement ambiguity before planning, `/speckit.checklist` (after `/speckit.plan`) to generate quality checklists that validate requirements completeness, clarity, and consistency, and `/speckit.analyze` to check spec/plan/task consistency before implementation starts. You can repeat `/speckit.analyze` after implementation as an extra review, but keep the first analysis before `/speckit.implement` so gaps are caught while the plan and tasks can still be adjusted. Finally, run `/speckit.converge` after implementation to verify all planned work is complete and generate tasks for any remaining gaps. If `/speckit.converge` appends new tasks, run `/speckit.implement` again (and converge again) until it reports that the feature has converged. ### Step 1: Install Specify @@ -190,7 +190,7 @@ Finally, implement the solution: ### Step 8: Converge -Run the `/speckit.converge` command after implementation to assess the current codebase against the feature's artifacts and append any remaining unbuilt work as new tasks to `tasks.md`. +Run the `/speckit.converge` command after implementation to assess the current codebase against the feature's artifacts and append any remaining unbuilt work as new tasks to `tasks.md`. If the command appends new tasks, run `/speckit.implement` again to complete them, and repeat the converge step until the feature is fully complete. ```bash /speckit.converge