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>

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!

#3287) `_load_core_command_names()` computed its candidate command dirs with bespoke `Path(__file__)` arithmetic. The #3014 move of this module from `specify_cli/extensions.py` to `specify_cli/extensions/__init__.py` pushed the file one directory deeper but left the `.parent` counts unchanged, so both candidates resolved to non-existent paths: wheel -> specify_cli/extensions/core_pack/commands (real: specify_cli/core_pack/commands) source -> src/templates/commands (real: repo-root templates/commands) Neither exists, so every call silently fell through to `_FALLBACK_CORE_COMMAND_NAMES`. Discovery is latent-dead: the fallback happens to equal the real stems today, but the shadowing guard (#1994) that depends on it now relies on someone hand-editing the fallback on every core-command add/remove (as already happened for `converge`, #3001). Delegate path resolution to the canonical `_locate_core_pack` / `_repo_root` resolvers in `_assets` — the same ones the presets and bundle loaders use. They are anchored to the package root, so discovery survives future module moves. Add regression tests that point the resolvers at a temp tree with *different* command names, proving discovery reads from disk rather than returning the fallback (they fail on the pre-fix code). Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

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

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

This was referenced Jun 30, 2026

Bug: extensions core-command discovery is dead — off-by-one paths after the #3014 module move #3274

Closed

fix(extensions): restore core-command discovery broken by #3014 module move #3275

Closed

Noor-ul-ain001 mentioned this pull request Jul 1, 2026

fix(extensions): resolve core-command dirs via _assets helpers (#3274) #3287

Merged

This was referenced Jul 1, 2026

fix(extensions): restore core-command discovery broken by #3014 module move #3292

Open

Bug: extensions core-command discovery is dead — off-by-one paths after the #3014 module move #3294

Open

Uh oh!

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

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

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!

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!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot's findings

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

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!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot's findings

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot's findings

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot's findings

Uh oh!

Uh oh!

Uh oh!

Uh oh!

BenBtg left a comment

Choose a reason for hiding this comment

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot's findings

Uh oh!

mnriem left a comment

Choose a reason for hiding this comment

BenBtg commented Jun 16, 2026 •

edited

Loading