* docs: add Spec Kit spec for agent-context full opt-in
Use Spec Kit's own specify workflow to author the spec that makes the
agent-context extension a full opt-in, removing all agent-context
configuration/support from the Python codebase and removing the
deprecation message. Force-added despite specs/ being gitignored; the
generated artifact will be purged prior to merge.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* docs: add Spec Kit plan artifacts for agent-context full opt-in
Phase 0/1 of the SDD plan workflow: plan.md, research.md, data-model.md,
quickstart.md, and contracts/cli-behavior.md. Constitution Check is a
documented no-op (repo has no ratified constitution). Force-added despite
specs/ being gitignored; generated artifacts will be purged prior to merge.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* docs: correct Constitution Check against ratified v1.0.0
Earlier draft wrongly treated the gate as a no-op; the fork's main is 16
commits behind upstream/main, which carries .specify/memory/constitution.md.
Re-evaluate the feature against Principles I-V (all PASS) and note that
Principle I mandates keeping context_file as a declared class attribute,
validating the R1 metadata decision.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* docs: refresh plan artifacts against synced upstream/main
After syncing fork main to upstream and rebasing, re-scan the current
agent-context surface. Upstream generalized the single context_file into a
plural context_files concept with new resolver helpers
(_resolve_context_files, _resolve_context_file_values,
_format_context_file_values) and upsert/remove now loop over multiple
files. Update research.md, data-model.md, contracts, quickstart grep
guards, and the plan summary to cover the expanded removal scope.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* docs: add Spec Kit tasks for agent-context full opt-in
Phase 2 of SDD: dependency-ordered tasks.md (30 tasks) organized by the
three user stories, with mandatory test tasks (Constitution Principle II)
and a foundational phase decoupling __CONTEXT_FILE__ resolution from the
extension config. Includes the extension self-seeding task (T015) and a
static guard test (T002) enforcing zero agent-context references in the CLI.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* feat!: remove agent-context lifecycle from the Specify CLI
Make the agent-context extension a full opt-in. The CLI no longer
installs the extension during init, writes agent-context-config.yml,
or creates/updates/removes the managed Spec Kit section in agent
context files. Context-section upsert/remove, marker resolution,
extension-enabled gating, the config helpers, and the obsolete inline
deprecation warning are all removed. Integration context_file stays as
inert metadata; __CONTEXT_FILE__ now resolves from registry metadata.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* feat(agent-context): self-seed context file from the active integration
When agent-context-config.yml has no context_file/context_files, the
bundled bash and PowerShell update scripts now resolve the context file
from the active integration in .specify/init-options.json via the
integration registry, so the extension no longer depends on the CLI
writing its config.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* test+docs: update suite and docs for agent-context opt-in
Update integration/extension tests to expect no agent-context install,
config, or context-section writes during init. Add a static guard test
(test_agent_context_cli_free.py) asserting the CLI source is free of
agent-context lifecycle symbols, plus backward-compatibility tests for
legacy projects. Refresh AGENTS.md, the extension README, and add a
CHANGELOG entry describing the opt-in behavior change.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* fix(agent-context): warn on self-seed failure, correct docs, speed up guard test
Address PR review feedback:
- Self-seed scripts (bash + PowerShell) now emit an actionable warning when
an active integration is configured but specify_cli cannot be imported by
the chosen Python (e.g. pipx installs), or when the integration declares no
context file, instead of silently falling through to 'nothing to do'.
- Correct the extension README disable note: command rendering never reads the
extension config; __CONTEXT_FILE__ is always substituted from integration
metadata, so a stale context_files value cannot affect rendering.
- Cache CLI source reads in the static guard test via a module-scoped fixture
so the directory walk happens once instead of once per forbidden symbol.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* feat(agent-context): ship self-owned per-agent context-file defaults
The extension now bundles agent-context-defaults.json (key→context_file
map) and self-seeds from it, dropping any dependency on the Specify CLI
registry. Both the bash and PowerShell update scripts read the bundled
JSON map keyed by the active integration from init-options.json.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* feat!: remove all agent-context state from the Specify CLI
Strip every context_file reference from the CLI: the field on all 35
integration classes, the IntegrationBase plumbing (process_template
param/step, _context_file_display, docstrings), the __CONTEXT_FILE__
resolution in agents.py, the legacy context_file/context_markers
popping in _helpers.py, and the context_file template in
integration_scaffold.py. Also drop the Agent context update step and
__CONTEXT_FILE__ placeholder from templates/commands/plan.md.
The agent-context extension now solely owns all context-file knowledge,
including the per-agent default mapping.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* test: drop context_file coverage and guard against CLI reintroduction
Remove CONTEXT_FILE attrs and context_file assertions across the base
mixins, all 35 per-integration test files, shared integration tests, and
conftest stubs. Rewrite the base-mixin context tests to assert no managed
section is written and no __CONTEXT_FILE__ placeholder survives. Extend
the CLI-free static guard to forbid context_file, __CONTEXT_FILE__, and
_context_file_display in src/specify_cli, and have the extension tests
copy the bundled defaults JSON so self-seed runs without the CLI.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* docs: reflect full removal of agent-context state from the CLI
Update AGENTS.md (integration examples, required-fields table, context
behavior section, pitfalls), CHANGELOG, and the SDD spec artifacts
(FR-007, SC-002, data-model) to state that the CLI carries no
context_file and the extension fully owns the per-agent default mapping
via agent-context-defaults.json.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* docs: align SDD artifacts with full context_file removal
Update research.md (R1, R2, R4, summary table), contracts/cli-behavior.md
(C3, C5), tasks.md (Phase 2, T026, notes), plan.md (Principle I, source
map), and checklists/requirements.md so the spec artifacts reflect the
implemented decision: the CLI carries no context_file attribute or
__CONTEXT_FILE__ resolution, and the per-agent defaults map lives in the
extension. Resolves PR review #4548130110.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* docs: scrub stale context-file mentions from CLI docstrings
Update the multi_install_safe docstring (drop the removed "context file"
invariant), the RovoDev setup docstring (no longer upserts a context
section), the Copilot module docstring (drop the context-file line), and
tighten the _update_init_options_for_integration note. Pure docstring
changes — no behavioral impact. Resolves PR review #4548237085.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* test+docs: harden agent-context test helper and fix stale docs
- base.py: document multi_install_safe as an optional subclass attribute
in the IntegrationBase docstring.
- test_cli.py: clarify the init-options assertion is guarding against
leftover legacy agent-context keys, not relocation.
- test_extension_agent_context.py: _install_agent_context_config now
asserts the bundled agent-context-defaults.json exists and always
copies it, so self-seeding tests fail loudly instead of silently
skipping when the map is missing.
- test_integration_cursor_agent.py: drop Path/IntegrationManifest imports
left unused after removing the context-section frontmatter tests.
Resolves PR review #4548293116.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* chore: remove gitignored SDD artifacts from specs/
The specs/001-agent-context-full-optin/ artifacts were force-added for
dogfooding visibility, but specs/ is gitignored and these were always
intended to be purged before merge. Remove them so merging does not add
an intentionally-untracked directory to repo history.
Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous)
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* chore: keep CHANGELOG.md identical to upstream
CHANGELOG.md is auto-generated at release time, so the branch should not
carry a manual entry. Restore it to match upstream/main exactly.
Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous)
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* fix: preserve Cursor .mdc frontmatter in agent-context updater scripts
The bundled agent-context updater scripts wrote the managed section as
plain text. For Cursor-style `.mdc` targets this dropped the required
`---\nalwaysApply: true\n---` frontmatter, reintroducing the rule-loading
bug originally fixed in #1699. Port the `_ensure_mdc_frontmatter` logic
into both the bash and PowerShell updaters: prepend frontmatter when
missing, repair `alwaysApply` when set to the wrong value, and leave
non-`.mdc` targets untouched. Add regression tests covering both shells.
Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous)
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* test: scope CLI-free guard to agent-context-specific symbols
Drop the bare "context_file" substring from FORBIDDEN_SYMBOLS so the
guard no longer fails on unrelated future CLI fields named context_file.
The list still covers agent-context-specific identifiers (__CONTEXT_FILE__,
_context_file_display, _resolve_context_files, _resolve_context_file_values).
Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous)
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* fix: harden agent-context bash self-seed against malformed init JSON
Two robustness fixes in the embedded Python self-seed logic:
- Coerce the integration value from init-options.json to a string only when
it is actually a string; otherwise treat it as unset so a corrupted
dict/list value degrades to the existing nothing-to-do behavior instead of
breaking the agents-map lookup.
- Normalize agent-context-defaults.json: only use 'agents' when both the JSON
root and the 'agents' value are dicts, so a wrong-shaped (but valid) JSON
falls back to the warning path instead of raising on .get.
Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous)
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* fix: correct PowerShell hyphenated key lookup and regex replace count
- Self-seed now reads the defaults mapping via
$defaults.agents.PSObject.Properties[$integrationKey].Value instead of
member access ($defaults.agents.$integrationKey), which parsed hyphenated
keys like 'cursor-agent'/'kiro-cli' as subtraction and failed to resolve.
- Replace the static [regex]::Replace(..., 1) call, whose trailing 1 was
interpreted as RegexOptions.IgnoreCase rather than a replacement count, with
an instance Regex whose Replace(input, replacement, 1) limits to the first
match as intended.
Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous)
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* fix: make bash .mdc frontmatter guard case-insensitive
The bash updater only injected Cursor .mdc frontmatter when ctx_path ended
in lowercase '.mdc', so a mixed/upper-case extension (e.g. specify-rules.MDC)
was skipped and Cursor would not auto-load the rule file. Compare against the
casefolded path. The PowerShell variant already uses -match, which is
case-insensitive by default, so no change is needed there.
Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous)
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* docs: document separator-agnostic agent-context update invocation
The README hard-coded the dot-notation slash command
(/speckit.agent-context.update), which hyphen-separator agents like Forge and
Cline do not recognize. Document the canonical command ID plus both slash
invocations so users copy the form their agent accepts.
Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous)
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
In agent-direct invocations nothing watches agent output for the
EXECUTE_COMMAND: directive, so a mandatory hook that is only emitted
never runs and the failure is silent (#2730). Add one line after each
mandatory-hook block instructing the agent to actually invoke the hook
and wait for it before continuing.
The instruction tells the agent to run the hook the way it would run
the command itself in the current agent/session, and notes the
invocation may differ from the literal {command} id shown in the block
(e.g. skills-mode agents run it as /skill:speckit-... or $speckit-...),
so it stays correct outside the default slash-command form.
Fixes#2730
* fix(taskstoissues): skip tasks that already have a GitHub issue
Re-running /speckit-taskstoissues created a duplicate issue for every
task because the command never checked for existing ones. Add a
deduplication step before issue creation: list the repo's issues
(state all) via the GitHub MCP server, collect the task IDs already
present in issue titles, and skip any task that already has a matching
issue. Issue titles are now prefixed with the task ID (e.g. T001:) so
they can be matched on later runs, and list_issues is added to the
command's MCP tools.
Fixes#2968
* fix(taskstoissues): correct list_issues usage and issue title format
Address Copilot review:
- list_issues has no 'all' state; omitting state returns both open and
closed issues. Use cursor-based pagination (after/endCursor) to fetch
every page before building the dedup set.
- task lines already start with their ID, so reuse the task text as the
issue title instead of prefixing the ID again (which produced
'T001: T001 ...').
* fix(taskstoissues): match task IDs anywhere in titles and define one canonical title
Address follow-up Copilot review:
- task lines start with a markdown checkbox (- [ ] T001 ...), so the
creation step now strips the checkbox and [P]/[US#] markers and writes
a single canonical title 'T001: <description>'.
- dedup now scans each issue title for a T<digits> token anywhere in the
title, so existing issues titled 'T001 ...', 'T001: ...' or '[T001] ...'
are all matched.
* fix(taskstoissues): use word-boundary task ID match and request perPage 100
Address Copilot review:
- match issue titles against \bT\d{3}\b so tokens like ST001 or T0010
are not matched by mistake (task IDs are T + 3 digits).
- request perPage: 100 on list_issues to reduce pagination calls.
* fix(taskstoissues): bound issue pagination to the tasks being processed
Address Copilot review: extract the task IDs from tasks.md first, then
paginate list_issues only until every task ID has been matched (or pages
run out), instead of fetching the repo's entire issue history. Keeps the
call count bounded on repos with large issue backlogs.
* Add /speckit.converge SDD artifacts and project scaffolding
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.
* Implement /speckit.converge command
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.
* Record quickstart validation results for /speckit.converge (T025)
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.
* Record 2026-06-16 re-verification results for /speckit.converge (T025)
* Potential fix for pull request finding
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
* Potential fix for pull request finding
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
* Fix integration upgrade deleting settings.json and dropping script +x
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).
* fix: resolve markdownlint errors in PR files
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* chore: clean up runtime state files from PR
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>
* feat: fold converge artifacts from #3003 and #3005
- Add speckit.converge Copilot agent and prompt files (#3003)
- Add regression test for Claude argument hints (#3005)
- Remove invalid converge entry from Claude argument hints
- Fix documentation removing branch-prefix fallback claims
Supersedes: #3003, #3005
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* chore: remove non-converge specify scaffolding from PR
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>
* chore: remove SDD spec artifacts from PR
Remove specs/001-converge-command/ — the spec/plan/tasks/research SDD
artifacts produced while building this feature. spec-kit does not track
a specs/ directory on main (those are outputs of running the workflow on
the repo, not part of the shipped tool).
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* chore: remove generated Copilot converge command files
Remove .github/agents/speckit.converge.agent.md and
.github/prompts/speckit.converge.prompt.md — these are generated by
'specify init --integration copilot' from templates/commands/converge.md
(all __SPECKIT_COMMAND_*__/{SCRIPT} tokens are resolved). main tracks no
.github/agents or .github/prompts files; the template is the source of truth.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* chore: split out unrelated integration-upgrade fix
Move the stale_cleanup_exclusions / executable-bit upgrade fix
(base.py, copilot, _migrate_commands.py, test_integration_subcommand.py)
out of this PR into its own change. This PR is now scoped purely to the
/speckit.converge command.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* fix: add converge to core command template ordering
converge is a core command in SKILL_DESCRIPTIONS but was missing from
_CORE_COMMAND_TEMPLATE_ORDER, so it sorted with the fallback rank. Add it
after 'implement' to keep core-command ordering consistent across
integrations.
Addresses review feedback on #3001.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* docs: make converge findings example neutral
Replace the self-referential sample evidence text in the Convergence
Findings table with a neutral placeholder so agents are less likely to copy
nonsensical template-specific findings into real output.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Potential fix for pull request finding
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
* docs: clarify converge scope and hook outcome wording
- Remove FR-specific parenthetical from code-scope rule so it doesn't imply
a hard FR-001 reference exists in every feature
- Replace unsupported 'pass outcome to hook context' instruction with explicit
in-session outcome reporting before hook listing
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* docs: align converge task example with tasks format
Use (no colon) in the convergence task example so it
matches tasks-template formatting and downstream expectations.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Clarification of usage
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
* Potential fix for pull request finding
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
* docs: align converge phase/task-id format with tasks template
- 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>
* docs: standardize converge phase heading format
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>
---------
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* feat(init)!: make git extension opt-in and remove --no-git at v0.10.0
- Remove --no-git parameter from specify init command
- Remove git extension auto-installation from init flow
- Git repository initialization (git init) still runs when git is available
- Remove --no-git from all test invocations across the test suite
- Update docs to reflect opt-in git extension behavior
- Replace TestGitExtensionAutoInstall with TestGitExtensionOptIn tests
BREAKING CHANGE: specify init no longer auto-installs the git extension.
Use `specify extension add git` to install it explicitly.
The --no-git flag has been removed.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* refactor(scripts): remove git operations from core scripts
Git functionality is now entirely managed by the git extension.
Core scripts only handle directory-based feature creation and numbering.
- Remove has_git(), check_feature_branch(), git branch creation from core
- Simplify number detection to use only spec directory scanning
- Remove HAS_GIT output from get_feature_paths()
- Remove git remote fetching and branch querying
- Keep BRANCH_NAME output key for backward compatibility
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* refactor: remove all git operations from core
- Remove is_git_repo() and init_git_repo() dead code from _utils.py
- Remove --branch-numbering from init command
- Remove git from 'specify check' (now extension-only)
- Update docs: git is optional prerequisite, check command description
- Fix tests to reflect no-git-in-core reality (fallback to main)
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* refactor(scripts): remove directory scanning and branch fallback from core
Core scripts now resolve feature context exclusively from:
1. SPECIFY_FEATURE env var (set by git extension)
2. .specify/feature.json (persisted by specify command)
Removed find_feature_dir_by_prefix() and directory scanning heuristics —
these are the git extension's responsibility. Scripts error clearly when
no feature context is available.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* feat: introduce feature_numbering, deprecate branch_numbering in init-options
- specify command template now reads feature_numbering (preferred) with
fallback to branch_numbering (deprecated) from init-options.json
- Git extension reads git-config.yml > feature_numbering > branch_numbering
- init now writes feature_numbering: sequential to init-options.json
- Deprecation warning emitted when branch_numbering is used as fallback
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* fix: remove trailing whitespace in common.ps1
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* feat(scripts): persist SPECIFY_FEATURE_DIRECTORY env var to feature.json
When SPECIFY_FEATURE_DIRECTORY is set, get_feature_paths() now writes the
value to .specify/feature.json so future sessions without the env var can
still resolve the feature directory. The write is idempotent — it skips
when the file already contains the same value.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* fix: address review feedback — error messages and docs
- Update error messages in common.sh and common.ps1 to reference
SPECIFY_FEATURE_DIRECTORY instead of SPECIFY_FEATURE (which no longer
resolves feature directories)
- Fix get_current_branch comment (returns empty string, not error)
- Update upgrade.md to reference SPECIFY_FEATURE_DIRECTORY with correct
example paths
- Update local-development.md troubleshooting: replace stale 'Git step
skipped' row with actionable git extension guidance
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* fix(scripts): harden feature.json persistence
- Use json_escape in printf fallback when jq is unavailable (common.sh)
- Replace utf8NoBOM encoding with UTF8Encoding($false) for PowerShell
5.1 compatibility (common.ps1)
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* refactor(scripts): remove dead feature_json_matches_feature_dir functions
These guards are no longer needed since the branch-name validation they
protected against has been removed from check-prerequisites.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* refactor(git-ext): rename create-new-feature to create-new-feature-branch
The git extension's script only creates the git branch — rename it to
reflect that responsibility. The core create-new-feature.sh/.ps1 handles
feature directory creation and feature.json persistence.
Also includes fixes from review feedback:
- common.sh: _persist_feature_json uses json_escape fallback
- common.ps1: Save-FeatureJson uses UTF8Encoding for PS 5.1 compat
- common.ps1: case-sensitive path stripping on non-Windows
- create-new-feature.sh/ps1: output both SPECIFY_FEATURE and
SPECIFY_FEATURE_DIRECTORY
- setup-tasks.sh: fix stale 'Validate branch' comment
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* fix(tests): update references to renamed git extension scripts
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* fix(tests): remove duplicate EXT_CREATE_FEATURE assignments
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---------
Co-authored-by: Manfred Riem <mnriem@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Initial plan
* Extract agent context updates into bundled agent-context extension
* Potential fix for pull request finding 'Unused import'
Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com>
* Potential fix for pull request finding 'Unused import'
Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com>
* fix: address review comments on agent-context extension
- bash: parse init-options.json with a single python3 invocation instead
of three separate read_json_field calls, for parity with the PowerShell
ConvertFrom-Json approach and to avoid divergent error semantics
- bash: use parameter expansion to strip PROJECT_ROOT prefix from plan
path instead of sed interpolation, avoiding special-character fragility
- powershell: limit Get-ChildItem to -Depth 1 so plan.md discovery matches
the bash glob specs/*/plan.md (one level deep) — fixes cross-platform
inconsistency with nested plan.md files
- powershell: replace Substring+Length relative-path with
[System.IO.Path]::GetRelativePath for robustness across case/PSDrive
differences
- __init__.py: move agent-context extension install to after
save_init_options so init-options.json is present when hooks run
- __init__.py: seed context_markers in init-options only when
context_file is truthy; avoids noise for integrations without a context
file
- integrations/base.py: narrow blanket except Exception in
_resolve_context_markers to ImportError / (OSError, ValueError) so
unexpected bugs surface instead of being silently swallowed
* fix: gate context_markers in _update_init_options_for_integration on context_file
Apply the same gating logic used during `specify init`: only write
context_markers to init-options.json when the integration actually has a
context_file set. When switching to an integration without a context file
the stale markers are removed, keeping the two init paths consistent.
* fix: move context_file/context_markers from init-options.json to agent-context extension config
* Potential fix for pull request finding 'Unused global variable'
Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com>
* fix: clarify local import comment in agents.py
* Fix remaining agent-context review findings
* Fix follow-up agent-context review issues
* Address review feedback: narrow except, improve PyYAML messaging, surface config-written note
* Fix double-space in PyYAML install hint message
* Potential fix for pull request finding 'Empty except'
Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com>
* Potential fix for pull request finding 'Empty except'
Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com>
* Address latest agent-context review feedback
* Harden bash config parse output handling
* Clarify ImportError-only fallback comment
* Apply review feedback: drop dead try/except, guard ext-config creation, explicit ConvertFrom-Yaml check
* Remove redundant $Options = $null in PS1 catch block
* Add constitution directives, deprecation warning, agent-context auto-install, and init flow fix
- Add constitution-loading directive to specify, clarify, tasks, checklist, taskstoissues commands
- Add deprecation warning (v0.12.0) in upsert_context_section()
- Auto-install agent-context extension during specify init
- Move context_file from init-options.json to agent-context extension config
- Add tests: deprecation warning, corrupt config, constitution directives
- Update file inventories across all integration tests
* Address review: fix init ordering, test coverage, and hermes inventory
- Move agent-context extension install after init-options.json is saved
so skill registration can read ai_skills + integration key
- Write extension config after install (avoids template overwriting context_file)
- Fix test_defaults_when_markers_field_missing to truly test missing markers key
- Update hermes tests to allow extension-installed agent-context skill
* Address review: chmod ordering, preserve markers, PS1 Python check, YAML key order
- Move ensure_executable_scripts after agent-context extension install
so extension scripts get execute bits set
- Use preserve_markers=True on reinit to keep user-customized markers
- Add Python 3 version check in PowerShell fallback (matching bash behavior)
- Add sort_keys=False to yaml.safe_dump for stable config output
* Address review: path traversal guards and docstring fix
- Reject absolute paths and '..' segments in context_file in both bash and
PowerShell scripts to prevent writes outside the project root
- Fix docstring in _update_init_options_for_integration to accurately
describe marker preservation behavior
* Address review: strict enabled check, docstring, segment-level path traversal
- Use 'is not False' for enabled check so only literal False disables
- Update upsert_context_section docstring to mention disabled-extension return
- Fix path traversal guards to check actual path segments, not substrings
(allows filenames like 'notes..md' while rejecting '../' traversal)
* Address review: UnicodeError handling, missing extension warning
- Add UnicodeError to exception tuples in _load_agent_context_config and
_resolve_context_markers so garbled UTF-8 config files fall back to defaults
- Emit error (with reinstall command) instead of silent skip when bundled
agent-context extension is not found during init
* Address review: bash backslash traversal guard, wheel packaging
- Reject backslash separators and Windows drive-letter paths in bash
context_file validation (prevents traversal on Git-Bash/Windows)
- Add extensions/agent-context to pyproject.toml force-include so the
bundled extension is included in wheel builds
* Address review: write extension config before init-options.json
- Reorder writes in _update_init_options_for_integration so the
agent-context extension config is updated first; if it fails,
init-options.json remains consistent with the previous state
---------
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Manfred Riem <15701806+mnriem@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com>
* Re-validate spec quality checklist after clarify updates spec
After clarify modifies spec.md, the existing checklists/requirements.md
(generated by specify) can become stale. Items like 'No [NEEDS
CLARIFICATION] markers remain' may now pass, and newly added requirements
aren't reflected in the checklist evaluation.
Add step 8 to the clarify command that re-validates the spec quality
checklist against the updated spec after each clarification session:
- Check/uncheck items based on current spec state
- Report before/after pass counts in the completion report
- Skip silently if no checklist exists
Fixes#2693
* Address review: scope to checkbox lines, use FEATURE_DIR path
- Constrain re-validation to GitHub task-list checkbox lines only
(- [ ] / - [x] outside code fences), ignoring headings, notes,
and non-checkbox content
- Define pass counts as checked/total checkbox items
- Use FEATURE_DIR/checklists/requirements.md in Done When for
consistency with the rest of the template
* Address review: handle regressions in checklist revalidation
- Clarify that each checkbox is set based solely on current spec state,
regardless of prior marker (checked->unchecked is possible)
- Completion report now lists both newly passing items and regressions
(checked->unchecked) so users see what became non-compliant
* Address review: case-insensitive checkboxes, preserve file verbatim
- Accept [x], [X], and leading whitespace for nested task items
- Explicitly state only the [ ]/[x] marker is toggled; all other
file content (headings, metadata, notes, ordering, whitespace)
must remain unchanged to avoid noisy diffs
* Address review: track per-item state, preserve marker case
- Add explicit before-snapshot step to capture each item's prior
marker state before re-evaluation
- Compute three lists for the report: newly passing, regressions,
and still unchecked
- Only toggle markers whose checked/unchecked state actually changes;
preserve existing case ([x]/[X]) when state is unchanged to avoid
cosmetic diffs
* fix: promote post-execution hook dispatch to H2 with directive language
Restructure the after_* hook dispatch in all five core command templates
(specify, clarify, implement, plan, tasks) to make hook execution
structurally unmissable by LLMs during interactive slash-command flows.
Changes applied consistently across all five templates:
1. Promote hook block from a final numbered step to a top-level
'## Mandatory Post-Execution Hooks' H2, placed before the completion
report. An H2 boundary is salient in a way that a numbered sub-step
buried after 'Report completion' is not.
2. Use directive language for mandatory hooks: 'You MUST emit
EXECUTE_COMMAND: for each mandatory hook' and 'You MUST complete this
section before reporting completion to the user.' The previous
conditional framing ('check if', 'based on its optional flag') buried
the mandatory cases.
3. List mandatory hooks before optional hooks in the dispatch block, so
the required action appears first.
4. Add a terminal '## Done When' verification checklist at the end of
each template, including 'Extension hooks dispatched' as an explicit
completion criterion. This gives the model a structured opportunity to
verify completion before exiting.
5. Extract the completion report into its own '## Completion Report' H2
section, clearly separated from the hook dispatch.
These changes preserve the interactive-vs-workflow distinction and do not
introduce auto-run. They raise the reliability of the existing
best-effort dispatch mechanism.
Fixes#2688
* fix: address review — narrow Done When wording and move to end of templates
- Narrow the hooks checklist item from a broad condition to 'dispatched
or skipped according to the rules in Mandatory Post-Execution Hooks
above' so it does not contradict the filtering rules for disabled
hooks or hooks with non-empty conditions.
- Move the Done When section to the actual end of specify.md, plan.md,
and tasks.md so it does not signal premature completion before the
agent reads required guidance sections (Quick Guidelines, Phases/Key
rules, Task Generation Rules).
* fix: update stale step 8 reference in specify.md validation flow
The old 'proceed to step 8' pointed to the completion report step that
was renumbered when hook dispatch was promoted to its own H2 section.
Update the reference to point to 'Mandatory Post-Execution Hooks'.
* fix: resolve command references per integration type (dot vs hyphen)
Replace hardcoded /speckit.<cmd> references in templates with
__SPECKIT_COMMAND_<NAME>__ placeholders that are resolved at
setup time based on the integration type:
- Markdown/TOML/YAML agents: separator='.' → /speckit.plan
- Skills agents: separator='-' → /speckit-plan
Changes:
- Add resolve_command_refs() static method to IntegrationBase
- Add invoke_separator class attribute (. for base, - for skills)
- Wire into process_template() as step 8
- Update _install_shared_infra() to process page templates
- Replace /speckit.* in 5 command templates and 3 page templates
- Add unit tests for resolve_command_refs (positive + negative)
- Add integration tests verifying on-disk content for all agents
- Add end-to-end CLI tests for Claude (skills) and Copilot (markdown)
Fixes#2347
* review: use effective_invoke_separator() for Copilot skills mode
Address PR review feedback: instead of bleeding _skills_mode
knowledge into the CLI layer, add effective_invoke_separator()
method to IntegrationBase that accepts parsed_options.
CopilotIntegration overrides it to return "-" when skills
mode is requested. The CLI layer simply asks the integration
for its separator — no hasattr or _skills_mode coupling.
Also adds tests for the new method on both base and Copilot,
plus an end-to-end test for 'specify init --integration copilot
--integration-options --skills' verifying page templates get
hyphen refs.
* fix: build_command_invocation preserves full suffix for extension commands
Previously rsplit('.', 1)[-1] on 'speckit.git.commit' yielded
just 'commit', producing /speckit.commit instead of
/speckit.git.commit (or /speckit-git-commit for skills).
Fix: strip only the 'speckit.' prefix when present, then join
remaining segments with the appropriate separator.
Updated in IntegrationBase, SkillsIntegration, and
CopilotIntegration. Added tests for extension commands in
build_command_invocation across all three.
* fix: Copilot dispatch_command() preserves full extension command suffix
dispatch_command() had the same rsplit('.', 1)[-1] bug as
build_command_invocation() — speckit.git.commit would dispatch
as /speckit-commit instead of /speckit-git-commit in skills
mode, or --agent speckit.commit instead of speckit.git.commit
in default mode.
* Replace shell-based context updates with marker-based upsert
Replace ~3500 lines of bash/PowerShell agent context update scripts
with a Python-based approach using <!-- SPECKIT START/END --> markers.
IntegrationBase now manages the agent context file directly:
- upsert_context_section(): creates or updates the marked section at
init/install/switch time with a directive to read the current plan
- remove_context_section(): removes the section at uninstall, deleting
the file only if it becomes empty
- __CONTEXT_FILE__ placeholder in command templates is resolved per
integration so the plan command references the correct agent file
- context_file is persisted in init-options.json for extension access
The plan command template instructs the LLM to update the plan
reference between the markers in the agent context file.
Removed:
- scripts/bash/update-agent-context.sh (857 lines)
- scripts/powershell/update-agent-context.ps1 (515 lines)
- 56 integration wrapper scripts (update-context.sh/.ps1)
- templates/agent-file-template.md
- agent_scripts frontmatter key and {AGENT_SCRIPT} replacement logic
- update-context reference from integration.json
- tests/test_cursor_frontmatter.py (tested deleted scripts)
Added:
- upsert/remove context section methods on IntegrationBase
- __CONTEXT_FILE__ placeholder support in process_template()
- context_file field in init-options.json (init/switch/uninstall)
- Per-integration tests: context file correctness, plan reference,
init-options persistence (78 new context_file tests)
- End-to-end CLI validation across all 28 integrations
* fix: search for end marker after start marker in context section methods
Address Copilot review: content.find(CONTEXT_MARKER_END) searched from
the start of the file rather than after the located start marker. If
the file contained a stray end marker before the start marker, the
wrong slice could be replaced.
Now both upsert_context_section() and remove_context_section() pass
start_idx as the second argument to find() and validate end_idx >
start_idx before performing the replacement.
* fix: address Copilot review feedback on context section handling
1. Fix grammar in _build_context_section() directive text — add commas
for a complete sentence.
2. Resolve __CONTEXT_FILE__ in resolve_skill_placeholders() — skills
generated via extensions/presets for codex/kimi now replace the
placeholder using the context_file value from init-options.json.
3. Handle Cursor .mdc frontmatter — when creating a new .mdc context
file, prepend alwaysApply: true YAML frontmatter so Cursor
auto-loads the rules.
4. Fix empty-file leading newline — when the context file exists but
is empty, write the section directly instead of prepending a blank
line.
* fix: address second round of Copilot review feedback
1. Ensure .mdc frontmatter on existing files — upsert_context_section()
now checks for missing YAML frontmatter on .mdc files during updates
(not just creation), so pre-existing Cursor files get alwaysApply.
2. Guard against context_file=None — use 'or ""' instead of a default
arg so explicit null values in init-options.json don't cause a
TypeError in str.replace().
3. Clean up .mdc files on removal — remove_context_section() treats
files containing only the Speckit-generated frontmatter block as
empty, deleting them rather than leaving orphaned frontmatter.
* fix: address third round of Copilot review feedback
1. CRLF-safe .mdc frontmatter check — use lstrip().startswith('---')
instead of startswith('---\n') so CRLF files don't get duplicate
frontmatter.
2. CRLF-safe .mdc removal check — normalize line endings before
comparing against the sentinel frontmatter string.
3. Call remove_context_section() during integration_uninstall() — the
manifest-only uninstall was leaving the managed SPECKIT markers
behind in the agent context file.
4. Fix stale docstring — remove 'agent_scripts' mention from
test_lean_commands_have_no_scripts().
* fix: address fourth round of Copilot review feedback
1. Remove unused script_type parameter from _write_integration_json()
and all 3 call sites — the parameter was no longer referenced after
the update-context script removal.
2. Fix _build_context_section() docstring — correct example path from
'.specify/plans/plan.md' to 'specs/<feature>/plan.md'.
3. Improve .mdc frontmatter-only detection in remove_context_section()
— use regex to match any YAML frontmatter block (not just the exact
Speckit-generated one), so .mdc files with additional frontmatter
keys are also cleaned up when no body content remains.
* fix: handle corrupted markers and parse .mdc frontmatter robustly
1. Handle partial/corrupted markers in upsert_context_section() —
if only the START marker exists (no END), replace from START
through EOF. If only the END marker exists, replace from BOF
through END. This keeps upsert idempotent even when a user
accidentally deletes one marker.
2. Parse .mdc YAML frontmatter properly — new _ensure_mdc_frontmatter()
helper parses existing frontmatter and ensures alwaysApply: true is
set, rather than just checking for the --- delimiter. Handles
missing frontmatter, existing frontmatter without alwaysApply, and
already-correct frontmatter.
* fix: preserve .mdc frontmatter, add tests, clean up on switch
1. Rewrite _ensure_mdc_frontmatter() with regex — preserves comments,
formatting, and custom keys in existing frontmatter instead of
destructively re-serializing via yaml.safe_dump(). Inserts or
fixes alwaysApply: true in place.
2. Add 6 focused .mdc frontmatter tests to cursor-agent test file:
new file creation, missing frontmatter, preserved custom keys,
wrong alwaysApply value, idempotent upserts, removal cleanup.
3. Call remove_context_section() during integration switch Phase 1 —
prevents stale SPECKIT markers from being left in the old
integration's context file. Also clear context_file from
init-options during the metadata reset.
* fix: remove unused MDC_FRONTMATTER, preserve inline comments, normalize bare CR
1. Remove unused MDC_FRONTMATTER class variable — dead code after
_ensure_mdc_frontmatter() was rewritten with regex.
2. Preserve inline comments when fixing alwaysApply — the regex
substitution now captures trailing '# comment' text and keeps it.
3. Normalize bare CR in upsert_context_section() — match the
behavior of remove_context_section() which already normalizes
both CRLF and bare CR.
4. Clarify .mdc removal comment — 'treat frontmatter-only as empty'
instead of misleading 'strip frontmatter'.
* fix: handle corrupted markers in remove, CRLF-safe end-marker consumption
1. Handle corrupted markers in remove_context_section() — mirror
upsert's behavior: start-only removes start→EOF, end-only removes
BOF→end. Previously bailed out leaving partial markers behind.
2. CRLF-safe end-marker consumption — both upsert and remove now
handle \r\n after the end marker, not just \n. Prevents extra
blank lines at replacement boundaries in CRLF files.
3. Clarify path rule in plan template — distinguish filesystem
operations (absolute paths) from documentation/agent context
references (project-relative paths).
* fix: only remove context section when both markers are well-ordered
remove_context_section() previously treated mismatched markers as
corruption and aggressively removed from BOF→end-marker or
start-marker→EOF, which could delete user-authored content if only
one marker remained. Now it only removes when both START and END
markers exist and are properly ordered, returning False otherwise.
* feat: Git extension stage 2 — GIT_BRANCH_NAME override, --force for existing dirs, auto-install tests (#1940)
- Add GIT_BRANCH_NAME env var override to create-new-feature.sh/.ps1
for exact branch naming (bypasses all prefix/suffix generation)
- Fix --force flag for 'specify init <dir>' into existing directories
- Add TestGitExtensionAutoInstall tests (auto-install, --no-git skip,
commands registered)
- Add TestFeatureDirectoryResolution tests (env var, feature.json,
priority, branch fallback)
- Document GIT_BRANCH_NAME in speckit.git.feature.md and specify.md
* fix: remove unused Tuple import (ruff F401)
* fix: address Copilot review feedback (#2117)
- Fix timestamp regex ordering: check YYYYMMDD-HHMMSS before generic
numeric prefix in both bash and PowerShell
- Set BRANCH_SUFFIX in GIT_BRANCH_NAME override path so 244-byte
truncation logic works correctly
- Add 244-byte length check for GIT_BRANCH_NAME in PowerShell
- Use existing_items for non-empty dir warning with --force
- Skip git extension install if already installed (idempotent --force)
- Wrap PowerShell feature.json parsing in try/catch for malformed JSON
- Fix PS comment: 'prefix lookup' -> 'exact mapping via Get-FeatureDir'
- Remove non-functional SPECIFY_SPEC_DIRECTORY from specify.md template
* fix: address second round of Copilot review feedback (#2117)
- Guard shutil.rmtree on init failure: skip cleanup when --force merged
into a pre-existing directory (prevents data loss)
- Bash: error on GIT_BRANCH_NAME >244 bytes instead of broken truncation
- Fix malformed numbered list in specify.md (restore missing step 1)
- Add claude_skills.exists() assert before iterdir() in test
* fix: use UTF-8 byte count for 244-byte branch name limit (#2117)
- Bash: use LC_ALL=C wc -c for byte length instead of ${#VAR}
- PowerShell: use [System.Text.Encoding]::UTF8.GetByteCount() instead
of .Length (UTF-16 code units)
* fix: address third round of review feedback (#2117)
- Update --dry-run help text in bash and PowerShell (branch name only)
- Fix specify.md JSON example: use concrete path, not literal variable
- Add TestForceExistingDirectory tests (merge + error without --force)
- Add PowerShell Get-FeaturePathsEnv tests (env var + feature.json)
* fix: normalize relative paths and fix Test-HasGit compat (#2117)
- Bash common.sh: normalize SPECIFY_FEATURE_DIRECTORY and feature.json
relative paths to absolute under repo root
- PowerShell common.ps1: same normalization using IsPathRooted + Join-Path
- PowerShell create-new-feature.ps1: call Test-HasGit without -RepoRoot
for compatibility with core common.ps1 (no param) and git-common.ps1
(optional param with default)
* test: add GIT_BRANCH_NAME automated tests for bash and PowerShell (#2117)
- TestGitBranchNameOverrideBash: 5 tests (exact name, sequential prefix,
timestamp prefix, overlong rejection, dry-run)
- TestGitBranchNameOverridePowerShell: 4 tests (exact name, sequential
prefix, timestamp prefix, overlong rejection)
- Tests use extension scripts (not core) via new ext_git_repo and
ext_ps_git_repo fixtures
* fix: restore git init during specify init + review fixes (#2117)
- Restore is_git_repo() and init_git_repo() functions removed in stage 2
- specify init now runs git init AND installs git extension (not just
extension install alone)
- Add is_dir() guard for non-here path to prevent uncontrolled error
when target exists but is a file
- Add python3 JSON fallback in common.sh for multi-line feature.json
(grep pipeline fails on pretty-printed JSON without jq)
* fix: use init_git_repo error_msg in failure output (#2117)
* fix: ensure_executable_scripts also covers .specify/extensions/ (#2117)
Extension .sh scripts (e.g. create-new-feature.sh, initialize-repo.sh)
may lack execute bits after install. Scan both .specify/scripts/ and
.specify/extensions/ for permission fixing.
* fix: move chmod after extension install + sanitize error_msg (#2117)
- ensure_executable_scripts() now runs after git extension install so
extension .sh files get execute bits in the same init run
- Sanitize init_git_repo error_msg to single line (replace newlines,
truncate to 120 chars) to prevent garbled StepTracker output
* fix: use tracker.error for git init/extension failures (#2117)
Git init failure and extension install failure were reported as
tracker.complete (showing green) even on error. Now track a
git_has_error flag and call tracker.error when any step fails,
so the UI correctly reflects the failure state.
* fix: sanitize ext_err in git step tracker for consistent rendering (#2117)
* feat: add git extension with hooks on all core commands
- Create extensions/git/ with 5 commands: initialize, feature,
validate, remote, commit
- 18 hooks covering before/after for all 9 core commands
- Scripts: create-new-feature, initialize-repo, auto-commit,
git-common (bash + powershell)
- Configurable: branch_numbering, init_commit_message,
per-command auto-commit with custom messages
- Add hooks to analyze, checklist, clarify, constitution,
taskstoissues command templates
- Allow hooks-only extensions (no commands required)
- Bundle extension in wheel via pyproject.toml force-include
- Resolve bundled extensions locally before catalog lookup
- Remove planned-but-unimplemented before/after_commit hook refs
- Update extension docs (API ref, dev guide, user guide)
- 37 new tests covering manifest, install, all scripts (bash+pwsh),
config reading, graceful degradation
Stage 1: opt-in via 'specify extension add git'. No auto-install,
no changes to specify.md or core git init code.
Refs: #841, #1382, #1066, #1791, #1191
* fix: set git identity env vars in extension tests for CI runners
* fix: address PR review comments
- Fix commands property KeyError for hooks-only extensions
- Fix has_git() operator precedence in git-common.sh
- Align default commit message to '[Spec Kit] Initial commit' across
config-template, extension.yml defaults, and both init scripts
- Update README to reflect all 5 commands and 18 hooks
* fix: address second round of PR review comments
- Add type validation for provides.commands (must be list) and hooks
(must be dict) in manifest _validate()
- Tighten malformed timestamp detection in git-common.sh to catch
7-digit dates without trailing slug (e.g. 2026031-143022)
- Pass REPO_ROOT to has_git/Test-HasGit in create-new-feature scripts
- Fix initialize command docs: surface errors on git failures, only
skip when git is not installed
- Fix commit command docs: 'skips with a warning' not 'silently'
- Add tests for commands:null and hooks:list rejection
* fix: address third round of PR review comments
- Remove scripts frontmatter from command files (CommandRegistrar
rewrites ../../scripts/ to .specify/scripts/ which points at core
scripts, not extension scripts)
- Update speckit.git.commit command to derive event name from hook
context rather than using a static example
- Clarify that hook argument passthrough works via AI agent context
(the agent carries conversation state including user's original
feature description)
* fix: address fourth round of PR review comments
- Validate extension_id against ^[a-z0-9-]+$ in _locate_bundled_extension
to prevent path traversal (security fix)
- Move defaults under config.defaults in extension.yml to match
ConfigManager._get_extension_defaults() schema
- Ship git-config.yml in extension directory so it's copied during
install (provides.config template isn't materialized by ExtensionManager)
- Condition handling in hook templates: intentionally matches existing
pattern from specify/plan/tasks/implement templates (not a new issue)
* fix: add --allow-empty to git commit in initialize-repo scripts
Ensures git init succeeds even on empty repos where nothing has been
staged yet.
* fix: resolve display names to bundled extensions before catalog download
When 'specify extension add "Git Branching Workflow"' is used with a
display name instead of the ID, the catalog resolver now runs first to
map the name to an ID, then checks bundled extensions again with the
resolved ID before falling back to network download.
Also noted: EXECUTE_COMMAND_INVOCATION and condition handling match the
existing pattern in specify/plan/tasks/implement templates (pre-existing,
not introduced by this PR).
* fix: handle before_/after_ prefixes in auto-commit message derivation
- Strip both before_ and after_ prefixes when deriving command name
(fixes misleading 'Auto-commit after before_plan' messages)
- Include phase (before/after) in default commit messages
- Clarify README config example is an override, not default behavior
* fix: use portable grep -qw for word boundary in create-new-feature.sh
BSD grep (macOS) doesn't support \b as a word boundary. Replace with
grep -qw which is POSIX-portable.
* fix: validate hook values, numeric --number, and PS warning routing
- Validate each hook value is a dict with a 'command' field during
manifest _validate() (prevents crash at install time)
- Validate --number is a non-negative integer in bash create-new-feature
(clear error instead of cryptic shell arithmetic failure)
- Route PowerShell no-git warning to stderr in JSON mode so stdout
stays valid JSON
---------
Co-authored-by: Manfred Riem <15701806+mnriem@users.noreply.github.com>
* fix(commands): rename NFR references to success criteria in analyze and clarify
* fix(analyze): align Success Criteria description and inventory keys with spec template
- Reword "non-functional targets" to "measurable outcomes" to match the spec template's broader scope (performance, user success, business impact)
- Use explicit FR-/SC- identifiers as primary stable keys in the requirements inventory instead of derived slugs alone
* feat(commands): wire before/after hook events into specify and plan templates
Replicates the hook evaluation pattern from tasks.md and implement.md
(introduced in PR #1702) into the specify and plan command templates.
This completes the hook lifecycle across all SDD phases.
Changes:
- specify.md: Add before_specify/after_specify hook blocks
- plan.md: Add before_plan/after_plan hook blocks
- EXTENSION-API-REFERENCE.md: Document new hook events
- EXTENSION-USER-GUIDE.md: List all available hook events
Fixes#1788
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* Mark before_commit/after_commit as planned in extension docs
These hook events are defined in the API reference but not yet wired
into any core command template. Marking them as planned rather than
removing them, since the infrastructure supports them.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* Fix hook enablement to default true when field is absent
Matches HookExecutor.get_hooks_for_event() semantics where
hooks without an explicit enabled field are treated as enabled.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(docs): mark commit hooks as planned in user guide config example
The yaml config comment listed before_commit/after_commit as
"Available events" but they are not yet wired into core templates.
Moved them to a separate "Planned" line, consistent with the
API reference.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(commands): align enabled-filtering semantics across all hook templates
tasks.md and implement.md previously said "Filter to only hooks where
enabled: true", which would skip hooks that omit the enabled field.
Updated to match specify.md/plan.md and HookExecutor's h.get('enabled', True)
behavior: filter out only hooks where enabled is explicitly false.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* fix: remove per-short-name number detection from specify prompt
The specify.md prompt instructed the AI to search for existing branches
filtered by the exact short-name, causing every new feature to start at
001 since no branches matched the new short-name. The underlying
create-new-feature.sh script already has correct global numbering logic
via check_existing_branches() that searches ALL branches and spec
directories.
The fix removes the AI's flawed number-detection steps and tells it to
NOT pass --number, letting the script auto-detect the next globally
available number.
Closes#1744Closes#1468🤖 Generated with [Claude Code](https://claude.com/code)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: clarify --json flag requirement per Copilot review
- Rephrased step 2 to mention both --short-name and --json flags
- Added explicit note to always include the JSON flag for reliable output parsing
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* fix: wire after_tasks and after_implement hook events into command templates (#1701)
The HookExecutor backend in extensions.py was fully implemented but
check_hooks_for_event() was never called by anything — the core command
templates had no instructions to check .specify/extensions.yml.
Add a final step to templates/commands/tasks.md (step 6, after_tasks) and
templates/commands/implement.md (step 10, after_implement) that instructs
the AI agent to:
- Read .specify/extensions.yml if it exists
- Filter hooks.{event} to enabled: true entries
- Evaluate any condition fields and skip non-matching hooks
- Output the RFC-specified hook message format, including
EXECUTE_COMMAND: markers for mandatory (optional: false) hooks
Bumps version to 0.1.7.
* fix: clarify hook condition handling and add YAML error guidance in templates
- Replace ambiguous "evaluate any condition value" instruction with explicit
guidance to skip hooks with non-empty conditions, deferring evaluation to
HookExecutor
- Add instruction to skip hook checking silently if extensions.yml cannot
be parsed or is invalid
* Fix/extension hooks not triggered (#1)
* feat(templates): implement before-hooks check as pre-execution phase
* test(hooks): create scenario for LLMs/Agents on hooks
---------
Co-authored-by: Dhilip <s.dhilipkumar@gmail.com>
* fix(implement): remove Makefile from C ignore patterns
Makefile is typically source-controlled and should not be in .gitignore.
Replaced with proper autotools-generated files (autom4te.cache/, config.status).
Co-authored-by: Augment Agent <noreply@augmentcode.com>
* fix(implement): restore config.log in C ignore patterns
---------
Co-authored-by: Augment Agent <noreply@augmentcode.com>
* fix(checklist): clarify file handling behavior for append vs create
Resolves contradictory instructions in checklist.md lines 97-99 where the
template stated both 'append to existing file' and 'creates a NEW file'.
Changes:
- Clarified that if file doesn't exist, create new with CHK001
- If file exists, append new items continuing from last CHK ID
- Emphasized preservation of existing content (never delete/replace)
Co-authored-by: Augment Agent <noreply@augmentcode.com>
* fix(checklist): align report language with append behavior
---------
Co-authored-by: Augment Agent <noreply@augmentcode.com>
Resolves inconsistency where line 92 stated 'Maximum of 10 total questions'
while all other references (lines 2, 91, 100, 134, 158, 178) consistently
specify a maximum of 5 questions.
Co-authored-by: Augment Agent <noreply@augmentcode.com>
Moves constitution template from memory/ to templates/ to prevent
overwrites when spec-kit is reinitialized with a different AI agent.
Changes:
- Move memory/constitution.md to templates/constitution-template.md
- Update CLI to copy template to memory/ only on first initialization
- Update constitution command to reference correct paths with .specify/ prefix
- Preserve existing constitution.md when reinitializing project
The CLI now checks if .specify/memory/constitution.md exists:
- If it exists: preserve it (no overwrite)
- If it doesn't exist: copy from .specify/templates/constitution-template.md
This allows users to customize their constitution without losing changes
when adding support for additional AI agents or reinitializing.
Fixes#1541
Co-authored-by: jjoung1128 <jinwoong.joung@gmail.com>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
- Use git ls-remote for more reliable remote branch detection
- Check remote branches, local branches, AND specs directories
- Match exact short-name pattern to avoid false positives
- Ensures no duplicate numbers across all sources
- Add --number parameter to create-new-feature scripts (bash & PowerShell)
- Add check_existing_branches() function to fetch and scan remote branches
- Update branch numbering logic to check remotes before creating new branches
- Update /speckit.specify command to document remote branch checking workflow
- Prevents duplicate branch numbers when branches exist on remotes but not locally
- Maintains backward compatibility with existing workflows
- Falls back to local directory scanning when Git is not available
