feat: add /speckit.converge command by BenBtg · Pull Request #3001 · github/spec-kit

BenBtg · 2026-06-16T14:46:20Z

Description

Adds a built-in /speckit.converge command — an implementation-convergence step that runs after /speckit.implement. It reads a feature's spec.md, plan.md, and tasks.md as the sole source of intent (with the constitution as governing constraints), assesses the current codebase, and appends remaining unbuilt work as new, traceable tasks to tasks.md so /speckit.implement can complete it.

It is needed to close the gap between what a feature specifies and what the implementation pass actually built, expressed as actionable tasks the existing workflow can consume — without a manual review step.

The command is delivered as a Markdown command template (templates/commands/converge.md) plus registration of the new core command across the integration registries, integration tests, post-init guidance, and the README Core Commands table.

Key behaviours

Append-only: never modifies spec.md, plan.md, existing tasks, or application code. The only write is a new ## Phase N — Convergence section in tasks.md.
Traceable findings: each appended task names its source-ref (e.g. FR-003, SC-002, US1/AC2, Constitution II) and a gap-type label (missing / partial / contradicts / unrequested).
Clean converged state: when nothing remains, reports a converged result with summary counts and leaves tasks.md byte-for-byte unchanged.
Prerequisite guard: stops with an actionable message when plan.md or tasks.md is missing.
Cross-integration: installs and is invocable across all supported agents; appears in post-init guidance as the step after implement. Hooks: before_converge / after_converge (the latter receives the converged vs tasks_appended outcome).

Built through the spec-driven workflow — see specs/001-converge-command/ (spec.md, plan.md, tasks.md, research.md, data-model.md, contracts/, quickstart.md).

Note: A new core command is a material change that, for the upstream project, warrants maintainer agreement before merge. This PR targets the fork's main for review; retarget the base to github/spec-kit:main when ready to propose upstream.

Testing

Tested locally with uv run specify --help
Ran existing tests with uv sync && uv run pytest
Tested with a sample project (if applicable)

Details:

Automated: uv run python -m pytest tests/test_agent_config_consistency.py tests/integrations -q → 2343 passed (the suites that enumerate the core command set, now including converge).
Sample projects: scaffolded with uv run specify init … --integration copilot and --integration gemini; verified converge is installed and discoverable in post-init guidance.
Template tokens: process_template for copilot + gemini × sh + ps resolves with no leftover {SCRIPT} / __SPECKIT_COMMAND_*__.
Manual quickstart (Constitution IV) — re-verified 2026-06-16, GitHub Copilot + Gemini, macOS/zsh (prior pass 2026-06-10, Copilot):
- S1 gap → appended traceable (missing) task ✅
- S2 implement closes gap, re-converge finds 0 ✅
- S3 converged → tasks.md unchanged ✅
- S4 read-only boundaries (spec/plan/code untouched) ✅
- S5 missing-prerequisite guard ✅
- S6 cross-integration install + post-init guidance ✅

Full per-scenario results are recorded in T025 of specs/001-converge-command/tasks.md.

AI Disclosure

I did not use AI assistance for this contribution
I did use AI assistance (describe below)

The command template, core-command registration edits, and SDD artifacts were authored with GitHub Copilot (model: Claude Opus 4.8) on behalf of @BenBtg, who reviewed the changes. The feature was itself built using the Spec Kit spec-driven workflow (specify → plan → tasks → implement); the agent also ran the automated test suite and the manual quickstart validation.

Dogfood the converge feature through Spec Kit's own workflow: - spec.md, plan.md, tasks.md, research, data-model, contracts, quickstart - requirements checklist for the feature - ratified constitution v1.0.0 (.specify/memory) - Specify project scaffolding (.specify/, .github agent + prompt files) Defines a built-in /speckit.converge command that assesses spec/plan/tasks against the codebase and appends remaining work as new tasks (no git, no change tracking, append-only). Implementation not yet started. Excludes unrelated working-tree changes to agents.py, extensions.py, test_extensions.py, catalog.community.json, and README.md.

Add the built-in converge command that assesses the codebase against a feature's spec.md, plan.md, and tasks.md and appends remaining unbuilt work as new traceable tasks to tasks.md (append-only; no git, no change tracking). - templates/commands/converge.md: full command body (load artifacts, assess code, classify findings missing/partial/contradicts/unrequested, append '## Phase N — Convergence' tasks with source-ref + gap-type, read-only guardrails, converged branch, handoff, before/after_converge hooks) - Register converge as a core command across all enumeration sites (SKILL_DESCRIPTIONS, _FALLBACK_CORE_COMMAND_NAMES, ARGUMENT_HINTS, and the integration test command lists incl. copilot/generic file inventories) - init.py Next Steps panel + README Core Commands table - tasks.md: T001-T024 complete (T025 manual quickstart pending) Full suite green: 2343 passed.

All six quickstart scenarios validated (GitHub Copilot agent, macOS/zsh): S1 gap->appended traceable task, S2 implement+re-converge, S3 converged leaves tasks.md unchanged, S4 read-only boundaries, S5 missing-prereq stop, S6 cross- integration install (copilot + windsurf). Automated suite: 2343 passed.

Copilot

Pull request overview

Adds a new core /speckit.converge command template intended to run after /speckit.implement, and wires it into the CLI’s core-command registries, onboarding guidance, and integration test matrices. The PR also includes full spec-driven design artifacts for the converge feature and updates several bundled Spec Kit workflow/extension assets.

Changes:

Add templates/commands/converge.md defining the converge command’s hook handling, intent inventory, findings classification, and append-only tasks contract.
Register converge across core-command enumerations, onboarding “Next Steps”, and integration tests for markdown/toml/yaml/skills and Copilot.
Add SDD artifacts under specs/001-converge-command/ plus bundled .specify/ workflow/extension materials and related agent/prompt files.

Show a summary per file

File	Description
tests/integrations/test_integration_generic.py	Updates generic integration expectations to include `converge`.
tests/integrations/test_integration_copilot.py	Updates Copilot integration tests to include `converge` in core command inventories.
tests/integrations/test_integration_base_yaml.py	Adds `converge` to YAML integration command expectations.
tests/integrations/test_integration_base_toml.py	Adds `converge` to TOML integration command expectations.
tests/integrations/test_integration_base_skills.py	Adds `converge` to skills-based integration command expectations.
tests/integrations/test_integration_base_markdown.py	Adds `converge` to markdown integration command expectations.
templates/commands/converge.md	New converge command template defining append-only convergence behavior and hooks.
src/specify_cli/integrations/claude/init.py	Adds a Claude argument hint for the `converge` command.
src/specify_cli/extensions.py	Extends fallback core command name set to include `converge`.
src/specify_cli/commands/init.py	Adds converge to post-init “Next Steps” guidance after implement.
src/specify_cli/init.py	Adds `converge` to `SKILL_DESCRIPTIONS`.
specs/001-converge-command/spec.md	New converge feature specification.
specs/001-converge-command/research.md	Research decisions/rationale for converge design.
specs/001-converge-command/quickstart.md	Manual validation quickstart for converge scenarios.
specs/001-converge-command/plan.md	Implementation plan for converge feature rollout.
specs/001-converge-command/data-model.md	Conceptual entities for converge findings/tasks/results.
specs/001-converge-command/contracts/tasks-output.md	Contract for append format in `tasks.md`.
specs/001-converge-command/contracts/hooks.md	Contract for `before_converge` / `after_converge` hooks.
specs/001-converge-command/contracts/command-interface.md	Invocation/precondition/output contract for `/speckit.converge`.
specs/001-converge-command/checklists/requirements.md	Spec quality checklist for the converge feature spec.
README.md	Adds `/speckit.converge` to Core Commands table.
.specify/workflows/workflow-registry.json	Adds/records bundled workflow registry metadata.
.specify/workflows/speckit/workflow.yml	Adds/records bundled “Full SDD Cycle” workflow definition.
.specify/templates/tasks-template.md	Adds bundled tasks template content.
.specify/templates/spec-template.md	Adds bundled spec template content.
.specify/templates/plan-template.md	Adds bundled plan template content.
.specify/templates/constitution-template.md	Adds bundled constitution template content.
.specify/templates/checklist-template.md	Adds bundled checklist template content.
.specify/scripts/bash/setup-tasks.sh	Adds bundled script for resolving task template + available docs.
.specify/scripts/bash/setup-plan.sh	Adds bundled plan setup script.
.specify/scripts/bash/create-new-feature.sh	Adds bundled feature directory/branch naming script.
.specify/scripts/bash/check-prerequisites.sh	Adds bundled prerequisite/path resolution script.
.specify/memory/constitution.md	Adds a ratified Spec Kit constitution for governance constraints.
.specify/integrations/speckit.manifest.json	Adds/updates speckit integration manifest tracking managed files.
.specify/integrations/copilot.manifest.json	Adds/updates copilot integration manifest tracking managed files.
.specify/integration.json	Adds/updates repo integration state metadata.
.specify/init-options.json	Adds/updates repo init-options metadata.
.specify/feature.json	Adds/updates active feature pointer metadata.
.specify/extensions/bug/README.md	Adds bundled “bug triage workflow” extension documentation.
.specify/extensions/bug/extension.yml	Adds bundled “bug” extension manifest.
.specify/extensions/bug/commands/speckit.bug.test.md	Adds bundled `speckit.bug.test` extension command template.
.specify/extensions/bug/commands/speckit.bug.fix.md	Adds bundled `speckit.bug.fix` extension command template.
.specify/extensions/bug/commands/speckit.bug.assess.md	Adds bundled `speckit.bug.assess` extension command template.
.specify/extensions/agent-context/scripts/powershell/update-agent-context.ps1	Adds/updates bundled PowerShell context upsert script.
.specify/extensions/agent-context/scripts/bash/update-agent-context.sh	Adds/updates bundled Bash context upsert script.
.specify/extensions/agent-context/README.md	Adds bundled “agent-context” extension documentation.
.specify/extensions/agent-context/extension.yml	Adds bundled “agent-context” extension manifest.
.specify/extensions/agent-context/commands/speckit.agent-context.update.md	Adds bundled `speckit.agent-context.update` command template.
.specify/extensions/agent-context/agent-context-config.yml	Adds bundled agent-context configuration.
.specify/extensions/.registry	Adds/updates bundled extension registry state.
.specify/extensions.yml	Adds/updates bundled extensions configuration.
.specify/bugs/integration-key-cli-check/test.md	Adds bug workflow verification report artifact.
.specify/bugs/integration-key-cli-check/fix.md	Adds bug workflow fix report artifact.
.specify/bugs/integration-key-cli-check/assessment.md	Adds bug workflow assessment report artifact.
.github/prompts/speckit.taskstoissues.prompt.md	Adds/updates Copilot prompt stub for taskstoissues agent.
.github/prompts/speckit.tasks.prompt.md	Adds/updates Copilot prompt stub for tasks agent.
.github/prompts/speckit.specify.prompt.md	Adds/updates Copilot prompt stub for specify agent.
.github/prompts/speckit.plan.prompt.md	Adds/updates Copilot prompt stub for plan agent.
.github/prompts/speckit.implement.prompt.md	Adds/updates Copilot prompt stub for implement agent.
.github/prompts/speckit.constitution.prompt.md	Adds/updates Copilot prompt stub for constitution agent.
.github/prompts/speckit.clarify.prompt.md	Adds/updates Copilot prompt stub for clarify agent.
.github/prompts/speckit.checklist.prompt.md	Adds/updates Copilot prompt stub for checklist agent.
.github/prompts/speckit.bug.test.prompt.md	Adds/updates Copilot prompt stub for bug.test agent.
.github/prompts/speckit.bug.fix.prompt.md	Adds/updates Copilot prompt stub for bug.fix agent.
.github/prompts/speckit.bug.assess.prompt.md	Adds/updates Copilot prompt stub for bug.assess agent.
.github/prompts/speckit.analyze.prompt.md	Adds/updates Copilot prompt stub for analyze agent.
.github/prompts/speckit.agent-context.update.prompt.md	Adds/updates Copilot prompt stub for agent-context.update agent.
.github/copilot-instructions.md	Adds/updates managed Spec Kit context section for Copilot instructions.
.github/agents/speckit.taskstoissues.agent.md	Adds/updates Copilot agent command for taskstoissues.
.github/agents/speckit.tasks.agent.md	Adds/updates Copilot agent command for tasks.
.github/agents/speckit.plan.agent.md	Adds/updates Copilot agent command for plan.
.github/agents/speckit.implement.agent.md	Adds/updates Copilot agent command for implement.
.github/agents/speckit.constitution.agent.md	Adds/updates Copilot agent command for constitution.
.github/agents/speckit.bug.test.agent.md	Adds/updates Copilot agent command for bug.test.
.github/agents/speckit.bug.fix.agent.md	Adds/updates Copilot agent command for bug.fix.
.github/agents/speckit.bug.assess.agent.md	Adds/updates Copilot agent command for bug.assess.
.github/agents/speckit.analyze.agent.md	Adds/updates Copilot agent command for analyze.
.github/agents/speckit.agent-context.update.agent.md	Adds/updates Copilot agent command for agent-context.update.

Copilot's findings

Tip

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

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

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot

Copilot's findings

Files reviewed: 83/83 changed files
Comments generated: 4

    "specify": "Describe the feature you want to specify",
    "plan": "Optional guidance for the planning phase",
    "tasks": "Optional task generation constraints",
    "implement": "Optional implementation guidance or task filter",
+    "converge": "Optional feature name to converge",
    "analyze": "Optional focus areas for analysis",
    "clarify": "Optional areas to clarify in the spec",


+- **Rationale**: This is the same mechanism `analyze` and `implement` use. It already
+  resolves the feature directory via `SPECIFY_FEATURE_DIRECTORY` → `.specify/feature.json`
+  → branch-prefix fallback, so it works with or without git (Constitution Principle II).
+  No new script is introduced, preserving cross-platform parity by construction.


Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot

Copilot's findings

Files reviewed: 83/83 changed files
Comments generated: 6

+{
+  "version": "0.10.1.dev0",
+  "integration_state_schema": 1,
+  "installed_integrations": [
+    "copilot"


+{
+  "ai": "copilot",
+  "feature_numbering": "sequential",
+  "here": true,
+  "integration": "copilot",
+  "script": "sh",
+  "speckit_version": "0.10.1.dev0"
+}


+{
+  "integration": "copilot",
+  "version": "0.10.1.dev0",
+  "installed_at": "2026-06-09T16:21:58.529654+00:00",
+  "files": {
+    ".github/agents/speckit.analyze.agent.md": "699032fdd49afe31d23c7191f3fe7bcb1d14b081fbc94c2287e6ba3a57574fda",


+{
+  "schema_version": "1.0",
+  "extensions": {
+    "agent-context": {
+      "version": "1.0.0",
+      "source": "local",
+      "manifest_hash": "sha256:9a1dc02d2d0139bb03860392ecacef79183be2c442feda2f9ccaa4e5907b1e47",
+      "enabled": true,
+      "priority": 10,
+      "registered_commands": {
+        "copilot": [
+          "speckit.agent-context.update"
+        ]
+      },
+      "registered_skills": [],
+      "installed_at": "2026-06-09T16:21:58.811646+00:00"
+    },


+<!-- SPECKIT START -->
+For additional context about technologies to be used, project structure,
+shell commands, and other important information, read the current plan at
+specs/001-converge-command/plan.md
+<!-- SPECKIT END -->


+# Bug Assessment: Extension SKILL Frontmatter Drops argument-hint
+
+- **Slug**: integration-key-cli-check
+- **Created**: 2026-06-09T00:00:00Z
+- **Source**: https://github.com/github/spec-kit/issues/2903
+- **Verdict**: valid
+- **Severity**: medium
+


BenBtg added 4 commits June 16, 2026 14:50

Record 2026-06-16 re-verification results for /speckit.converge (T025)

06a2846

Copilot AI review requested due to automatic review settings June 16, 2026 14:46

Copilot started reviewing on behalf of BenBtg June 16, 2026 14:46 View session

Copilot AI reviewed Jun 16, 2026

View reviewed changes

Comment thread templates/commands/converge.md Outdated

Comment thread .specify/integrations/copilot.manifest.json

Potential fix for pull request finding

eb81505

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings June 16, 2026 15:11

Copilot started reviewing on behalf of BenBtg June 16, 2026 15:12 View session

Copilot AI mentioned this pull request Jun 16, 2026

Track /speckit.converge outputs in Copilot integration manifest #3003

Open

Copilot AI reviewed Jun 16, 2026

View reviewed changes

Potential fix for pull request finding

3715e90

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings June 16, 2026 15:25

Copilot started reviewing on behalf of BenBtg June 16, 2026 15:25 View session

Copilot AI mentioned this pull request Jun 16, 2026

Guard Claude converge skill against unsupported argument hints #3005

Draft

Copilot AI reviewed Jun 16, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add /speckit.converge command#3001

feat: add /speckit.converge command#3001
BenBtg wants to merge 6 commits into
github:mainfrom
BenBtg:benbtg/feat-converge

BenBtg commented Jun 16, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

BenBtg commented Jun 16, 2026

Description

Testing

AI Disclosure

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Copilot's findings

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot's findings

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot's findings

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants