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.

What changed

Added new core command template: templates/commands/converge.md
Registered converge across CLI/integration core-command registries and ordering
Updated post-init guidance to include converge after implement
Updated integration test expectations across markdown/toml/yaml/skills/Copilot/generic integrations
Added /speckit.converge to the README Core Commands table

Key behavior

Append-only: only appends a new ## Phase N — Convergence section to tasks.md; does not rewrite existing tasks
Converged no-op: if nothing remains, reports converged and leaves tasks.md unchanged
Prerequisite guard: stops with actionable messaging when required artifacts are missing
Traceability: appended tasks include source reference + gap type (missing, partial, contradicts, unrequested)
Hook support: supports before_converge and after_converge hook discovery

Testing

Automated

uv run python -m pytest tests/test_agent_config_consistency.py tests/integrations -q
Result: 2410 passed, 1 skipped
markdownlint on changed markdown (templates/commands/converge.md, README.md)

Behavioral

Validated both positive and negative converge flows on a sample feature:

gap found → convergence tasks appended with correct phase/id format
converged state → no changes to tasks.md
missing prerequisites → command exits with clear guidance

AI Disclosure

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

Authored with GitHub Copilot on behalf of @BenBtg, who reviewed the changes.

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

Copilot

Copilot's findings

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

Copilot

Copilot's findings

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

Copilot

Copilot's findings

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

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.

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

Two upgrade-path bugs surfaced during converge E2E validation: - copilot upgrade stale-deleted .vscode/settings.json because setup() only tracks the file when it creates it; on upgrade the pre-existing file is merged and left untracked, so Phase 2 stale cleanup removed it. Add an integration-level stale_cleanup_exclusions() hook (CopilotIntegration returns {.vscode/settings.json}) and subtract it from stale_keys. - shared .specify/scripts/*.sh lost their execute bit because the managed refresh rewrites them with the bundled source mode (often 0o644) and nothing restored perms. Call ensure_executable_scripts() after the managed-refresh block (POSIX only). Add regression tests in TestIntegrationUpgrade covering both fixes (validated to fail without the fixes).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Remove .specify state files that are per-project runtime artifacts: - feature.json, init-options.json, integration.json - manifest files, extension registry, bug artifacts These are generated by 'specify init' and should not be committed. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Add speckit.converge Copilot agent and prompt files (github#3003) - Add regression test for Claude argument hints (github#3005) - Remove invalid converge entry from Claude argument hints - Fix documentation removing branch-prefix fallback claims Supersedes: github#3003, github#3005 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

BenBtg · 2026-06-17T13:48:11Z

PR Stack Consolidation Summary

This PR now contains the complete, clean converge command implementation. Changes from side PRs #3003 and #3005 have been folded in, and those PRs are closed as superseded.

Folded from #3003

Added missing Copilot converge artifacts (.github/agents/speckit.converge.agent.md, .github/prompts/speckit.converge.prompt.md)
Fixed documentation removing incorrect branch-prefix fallback claims (implementation only supports SPECIFY_FEATURE_DIRECTORY and .specify/feature.json)
Excluded: manifest hash churn and generated state files (runtime artifacts)

Folded from #3005

Added regression test ensuring Claude does not advertise unsupported argument hints for converge
Removed invalid converge entry from Claude argument hints in src/specify_cli/integrations/claude/__init__.py

Cleanup

Removed .specify runtime state files that should not be committed: feature.json, init-options.json, integration.json, install manifests, .registry, and bugs/ artifacts
Rebased on main and resolved conflicts
Fixed markdownlint errors

Validation

All 2384 integration tests pass (1 skipped)
Markdownlint clean

Posted on behalf of @BenBtg by GitHub Copilot (model: Claude Opus 4.6).

Copilot

Copilot's findings

Files reviewed: 80/80 changed files
Comments generated: 11

Remove .specify/ artifacts, non-converge .github/agents and prompts, and copilot-instructions.md that were generated by 'specify init' and are not part of the converge command feature. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Copilot's findings

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

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

Copilot

Copilot's findings

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

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

Copilot

Copilot's findings

Files reviewed: 13/13 changed files
Comments generated: 0 new

Copilot

Copilot's findings

Files reviewed: 13/13 changed files
Comments generated: 0 new

Copilot

Copilot's findings

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

- Use (colon) for consistency with tasks template - Clarify appended task IDs must be zero-padded ( style) - Update checklist example to a concrete zero-padded ID () Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

BenBtg

Ready for human review

Copilot

Copilot's findings

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

mnriem

Please address Copilot feedback

Use consistently in converge.md (including the append-only contract section) to match Step 7 and tasks template style. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Copilot's findings

Files reviewed: 13/13 changed files
Comments generated: 0 new

mnriem · 2026-06-17T19:47:11Z

Thank you!

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 Outdated

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

Closed

Copilot AI reviewed Jun 16, 2026

View reviewed changes

Comment thread specs/001-converge-command/contracts/command-interface.md Outdated

Comment thread src/specify_cli/integrations/claude/__init__.py

Comment thread templates/commands/converge.md

Comment thread specs/001-converge-command/research.md Outdated

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

Closed

Copilot AI reviewed Jun 16, 2026

View reviewed changes

BenBtg requested a review from Copilot June 17, 2026 13:29

Copilot started reviewing on behalf of BenBtg June 17, 2026 13:29 View session

Copilot AI reviewed Jun 17, 2026

View reviewed changes

Comment thread templates/commands/converge.md

Comment thread templates/commands/converge.md

Comment thread specs/001-converge-command/research.md Outdated

Comment thread .specify/integration.json Outdated

BenBtg and others added 10 commits June 17, 2026 14:42

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

1ad02bb

Potential fix for pull request finding

f612a1e

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

Potential fix for pull request finding

25fdb07

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

fix: resolve markdownlint errors in PR files

dce9c7e

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings June 17, 2026 13:46

BenBtg force-pushed the benbtg/feat-converge branch from 678d4d4 to 353c0cb Compare June 17, 2026 13:46

Copilot started reviewing on behalf of BenBtg June 17, 2026 13:47 View session

Copilot AI reviewed Jun 17, 2026

View reviewed changes

Copilot started reviewing on behalf of BenBtg June 17, 2026 16:57 View session

Copilot AI reviewed Jun 17, 2026

View reviewed changes

Comment thread templates/commands/converge.md Outdated

BenBtg requested a review from Copilot June 17, 2026 17:07

Copilot started reviewing on behalf of BenBtg June 17, 2026 17:08 View session

Clarification of usage

234929f

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

Copilot AI reviewed Jun 17, 2026

View reviewed changes

Comment thread templates/commands/converge.md Outdated

Potential fix for pull request finding

d732546

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

Copilot AI review requested due to automatic review settings June 17, 2026 17:13

Copilot started reviewing on behalf of BenBtg June 17, 2026 17:13 View session

Copilot AI reviewed Jun 17, 2026

View reviewed changes

BenBtg requested a review from Copilot June 17, 2026 17:35

Copilot started reviewing on behalf of BenBtg June 17, 2026 17:36 View session

Copilot AI reviewed Jun 17, 2026

View reviewed changes

BenBtg requested a review from Copilot June 17, 2026 18:31

Copilot started reviewing on behalf of BenBtg June 17, 2026 18:31 View session

Copilot AI reviewed Jun 17, 2026

View reviewed changes

Comment thread templates/commands/converge.md Outdated

Comment thread templates/commands/converge.md Outdated

Comment thread templates/commands/converge.md

Comment thread templates/commands/converge.md

BenBtg requested a review from Copilot June 17, 2026 18:47

Copilot started reviewing on behalf of BenBtg June 17, 2026 18:48 View session

BenBtg commented Jun 17, 2026

View reviewed changes

Copilot AI reviewed Jun 17, 2026

View reviewed changes

Comment thread templates/commands/converge.md Outdated

mnriem requested changes Jun 17, 2026

View reviewed changes

docs: standardize converge phase heading format

e347188

Use consistently in converge.md (including the append-only contract section) to match Step 7 and tasks template style. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

mnriem requested a review from Copilot June 17, 2026 19:29

Copilot started reviewing on behalf of mnriem June 17, 2026 19:29 View session

Copilot AI reviewed Jun 17, 2026

View reviewed changes

mnriem self-requested a review June 17, 2026 19:46

mnriem approved these changes Jun 17, 2026

View reviewed changes

mnriem merged commit 0c29d89 into github:main Jun 17, 2026
11 checks passed

Conversation

BenBtg commented Jun 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

What changed

Key behavior

Testing

Automated

Behavioral

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!

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!

Uh oh!

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!

Uh oh!

Uh oh!

BenBtg commented Jun 17, 2026

PR Stack Consolidation Summary

Folded from #3003

Folded from #3005

Cleanup

Validation

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot's findings

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot's findings

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot's findings

Uh oh!

Copilot AI left a comment

BenBtg commented Jun 16, 2026 •

edited

Loading