- check_modified() no longer calls _validate_rel_path (which resolves
symlinks); uses lexical checks (is_absolute, '..' in parts) instead
- is_symlink() checked before is_file() so symlinks to files are still
treated as modified
- Fixed templates_dir() docstring to match actual behavior
- uninstall() wraps path.unlink() in try/except OSError to avoid
partial cleanup on race conditions or permission errors
- setup() raises ValueError on missing config or folder instead of
silently returning empty
- Added 3 tests: symlink in check_modified, symlink skip/force in
uninstall (47 total)
- Broken symlinks now removable (lexists check via is_symlink fallback)
- Symlinks never hashed (avoids following to external targets)
- Symlinks only removed with force=True, otherwise skipped
- uninstall() now uses os.path.normpath for lexical containment check
instead of resolve(), so in-project symlinks pointing outside are
still properly removed
- setup() asserts manifest.project_root matches the passed project_root
to prevent path mismatches between file operations and manifest
recording
- uninstall() now uses non-resolved path for deletion so symlinks
themselves are removed, not their targets; resolve only for
containment validation
- setup() keeps unresolved dst_file for copy; resolves separately
for project-root validation
- load() catches json.JSONDecodeError and re-raises as ValueError
with the manifest path for clearer diagnostics
- Added test for invalid JSON manifest loading
- Store manifest file keys using as_posix() after resolving relative
to project root, ensuring cross-platform portable manifests
- Type the manifest parameter as IntegrationManifest (via TYPE_CHECKING
import) instead of Any in IntegrationBase methods
Add the integrations package with:
- IntegrationBase ABC and MarkdownIntegration base class
- IntegrationOption dataclass for per-integration CLI options
- IntegrationManifest with SHA-256 hash-tracked install/uninstall
- INTEGRATION_REGISTRY (empty, populated in later stages)
- 34 tests at 98% coverage
Purely additive — no existing code modified.
Part of #1924
* docs: correct specify extension add syntax to require extension name
The specify extension add command requires the extension name as a positional argument. Many documentation files incorrectly demonstrated using the --from flag without specifying the extension name first.
* feat: add superb extension to community catalog
Orchestrates obra/superpowers skills within the spec-kit SDD workflow.
* fix: link superb extension docs
* feat(scripts): add --allow-existing-branch flag to create-new-feature
Add an --allow-existing-branch / -AllowExistingBranch flag to both
bash and PowerShell create-new-feature scripts. When the target branch
already exists, the script switches to it instead of failing. The spec
directory and template are still created if missing, but existing
spec.md files are not overwritten (prevents data loss on re-runs).
The flag is opt-in, so existing behavior is completely unchanged
without it. This enables worktree-based workflows and CI/CD pipelines
that create branches externally before running speckit.specify.
Relates to #1931. Also addresses #1680, #841, #1921.
Assisted-By: 🤖 Claude Code
* fix: address PR review feedback for allow-existing-branch
- Make checkout failure fatal instead of suppressing with || true (bash)
- Check $LASTEXITCODE after git checkout in PowerShell
- Use Test-Path -PathType Leaf for spec file existence check (PS)
- Add PowerShell static assertion test for -AllowExistingBranch flag
Assisted-By: 🤖 Claude Code
* Fix Claude Code CLI detection for npm-local installs
`specify check` reports "Claude Code CLI (not found)" for users who
installed Claude Code via npm-local (the default installer path, common
with nvm). The binary lives at ~/.claude/local/node_modules/.bin/claude
which was not checked. Add CLAUDE_NPM_LOCAL_PATH as a second well-known
location alongside the existing migrate-installer path.
Fixes https://github.com/github/spec-kit/issues/550
* Address Copilot review feedback
- Remove unused pytest import from test_check_tool.py
- Use tmp_path instead of hardcoded /nonexistent/claude for hermetic tests
- Simplify redundant exists() + is_file() to just is_file()
AI-assisted: Changes applied with Claude Code.
* Update tests/test_check_tool.py
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
* Update tests/test_check_tool.py
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---------
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Rename the Normalize-List parameter in create-release-packages.ps1 to avoid conflicting with PowerShell's automatic $input variable. This fixes Windows offline scaffolding when -Agents and -Scripts are passed.
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)
Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
* feat: add MAQA extension suite to community catalog and README
Adds 7 extensions forming the MAQA (Multi-Agent & Quality Assurance)
suite to catalog.community.json in correct alphabetical order (after
'learn', before 'onboard') and to the README community extensions table:
- maqa — coordinator/feature/QA workflow, board auto-detection
- maqa-azure-devops — Azure DevOps Boards integration
- maqa-ci — CI/CD gate (GitHub Actions/CircleCI/GitLab/Bitbucket)
- maqa-github-projects — GitHub Projects v2 integration
- maqa-jira — Jira integration
- maqa-linear — Linear integration
- maqa-trello — Trello integration
All entries placed alphabetically. maqa v0.1.3 bumped to reflect
multi-board auto-detection added in this release.
* fix: set catalog updated_at to match latest entry timestamp
Top-level updated_at was 00:00:00Z while plan-review-gate entries
had 08:22:30Z, making metadata inconsistent for freshness consumers.
Updated to 2026-03-27T08:22:30Z (>= all entry timestamps).
- Extension ID: plan-review-gate
- Version: 1.0.0
- Author: luno
- Catalog entries sorted alphabetically by ID
- README table row inserted alphabetically by name
Co-authored-by: Ed Harrod <your-real-email@luno.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
The `?.` (null-conditional member access) operator requires PowerShell 7.1+,
but Windows ships with PowerShell 5.1 by default. When AI agents invoke .ps1
scripts on Windows, they typically use the system-associated handler (5.1),
causing a ParseException: Unexpected token '?.Path'.
Replace the single `?.` usage with a 5.1-compatible two-step pattern that
preserves the same null-safety behavior.
Fixes#1972
* chore: bump version to 0.4.2
* chore: clean up CHANGELOG and fix release workflow
---------
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
* docs: add manual testing guide for slash command validation
Adds a top-level TESTING.md that describes the manual test process PR
submitters must follow when their changes affect slash commands.
Includes:
- Process overview (identify affected commands, setup, run, report)
- Local setup instructions using editable install
- Reporting template for PR submissions
- Agent prompt that analyzes changed files and determines which
commands need testing, including transitive script dependencies
and extension hook mappings
* Update TESTING.md
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
* Update TESTING.md
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---------
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
* Add AIDE, Extensify, and Presetify to community extensions
Add three extensions from the mnriem/spec-kit-extensions repository:
- AI-Driven Engineering (AIDE): structured 7-step workflow for building
new projects from scratch with AI assistants
- Extensify: create and validate extensions and extension catalogs
- Presetify: create and validate presets and preset catalogs
Updates both the README community extensions table and
catalog.community.json with entries in alphabetical order.
* fix(tests): isolate preset search test from community catalog growth
Mock get_active_catalogs to return only the default catalog entry so
the test uses only its own cached data and won't break as the
community preset catalog grows.
- Add 🎨 Community Presets section between Community Extensions and Community Walkthroughs
- Add ToC entry for the new section
- Populate presets/catalog.community.json with pirate and aide-in-place presets
- Entries alphabetized: catalog by id, README table by name
- Add 🧩 Community Extensions section to README.md before Community Walkthroughs
- Add table of contents entry for the new section
- Replace extensions/README.md table with a link back to the main README
- Update EXTENSION-PUBLISHING-GUIDE.md references to point to README.md
- Update EXTENSION-DEVELOPMENT-GUIDE.md references to point to README.md
* docs(readme): consolidate Community Friends sections and fix ToC anchors
- Merge duplicate 🤝 Community Friends section (table format near bottom) into
the existing 🛠️ Community Friends section (bullet list)
- Add cc-sdd entry alongside Spec Kit Assistant
- Update intro text to 'Community projects that extend, visualize, or build on Spec Kit'
- Fix ToC anchors for Video Overview and Community Friends (remove variation selector from fragment)
* docs(readme): remove stale ToC entry for deleted Community Friends section
* 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
* Add Community Friends section with cc-sdd
Adds a new "Community Friends" section to the README for projects that
extend or build on Spec Kit. Starts with cc-sdd, a Claude Code plugin
that layers composable traits (quality gates, worktree isolation, agent
teams) on top of Spec Kit's core workflow.
Suggested by @mnriem in discussion #1889.
Assisted-By: 🤖 Claude Code
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* Update cc-sdd repo URL after rename
Assisted-By: 🤖 Claude Code
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* Mention Superpowers explicitly in cc-sdd description
Assisted-By: 🤖 Claude Code
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(scripts): prioritize .specify over git for repo root detection
When spec-kit is initialized in a subdirectory that doesn't have its
own .git, but a parent directory does, spec-kit was incorrectly using
the parent's git repository root. This caused specs to be created in
the wrong location.
The fix changes repo root detection to prioritize .specify directory
over git rev-parse, ensuring spec-kit respects its own initialization
boundary rather than inheriting a parent git repo.
Fixes#1932
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix: address code review feedback
- Normalize paths in find_specify_root to prevent infinite loop with relative paths
- Use -PathType Container in PowerShell to only match .specify directories
- Improve has_git/Test-HasGit to check git command availability and validate work tree
- Handle git worktrees/submodules where .git can be a file
- Remove dead fallback code in create-new-feature scripts
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix: check .specify before termination in find_specify_root
Fixes edge case where project root is at filesystem root (common in
containers). The loop now checks for .specify before checking the
termination condition.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix: scope git operations to spec-kit root & remove unused helpers
- get_current_branch now uses has_git check and runs git with -C to
prevent using parent git repo branch names in .specify-only projects
- Same fix applied to PowerShell Get-CurrentBranch
- Removed unused find_repo_root() from create-new-feature.sh
- Removed unused Find-RepositoryRoot from create-new-feature.ps1
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix: use cd -- to handle paths starting with dash
Prevents cd from interpreting directory names like -P or -L as options.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix: check git command exists before calling get_repo_root in has_git
Avoids unnecessary work when git isn't installed since get_repo_root
may internally call git rev-parse.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix(powershell): use LiteralPath and check git before Get-RepoRoot
- Use -LiteralPath in Find-SpecifyRoot to handle paths with wildcard
characters ([, ], *, ?)
- Check Get-Command git before calling Get-RepoRoot in Test-HasGit to
avoid unnecessary work when git isn't installed
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix(powershell): use LiteralPath for .git check in Test-HasGit
Prevents Test-Path from treating wildcard characters in paths as globs.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix(powershell): use LiteralPath in Get-RepoRoot fallback
Prevents Resolve-Path from treating wildcard characters as patterns.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---------
Co-authored-by: iamaeroplane <michal.bachorik@gmail.com>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Add the AIDE extension demo to the community projects section,
showcasing a Spring Boot + React project that uses a custom
extension with an alternative spec-driven workflow featuring
a 7-step iterative lifecycle.
None of the yaml.dump() calls specify allow_unicode=True, causing
non-ASCII characters in extension descriptions to be escaped to
\uXXXX sequences in generated .agent.md frontmatter and config files.
Add allow_unicode=True to all 6 yaml.dump() call sites, and
encoding="utf-8" to all corresponding write_text() and read_text()
calls to ensure consistent UTF-8 handling across platforms.
* feat(cli): embed core pack in wheel + offline-first init (#1711, #1752)
Bundle templates, commands, and scripts inside the specify-cli wheel so
that `specify init` works without any network access by default.
Changes:
- pyproject.toml: add hatchling force-include for core_pack assets; bump
version to 0.2.1
- __init__.py: add _locate_core_pack(), _generate_agent_commands() (Python
port of generate_commands() shell function), and scaffold_from_core_pack();
modify init() to scaffold from bundled assets by default; add --from-github
flag to opt back in to the GitHub download path
- release.yml: build wheel during CI release job
- create-github-release.sh: attach .whl as a release asset
- docs/installation.md: add Enterprise/Air-Gapped Installation section
- README.md: add Option 3 enterprise install with accurate offline story
Closes#1711
Addresses #1752
* fix(tests): update kiro alias test for offline-first scaffold path
* feat(cli): invoke bundled release script at runtime for offline scaffold
- Embed release scripts (bash + PowerShell) in wheel via pyproject.toml
- Replace Python _generate_agent_commands() with subprocess invocation of
the canonical create-release-packages.sh, guaranteeing byte-for-byte
parity between 'specify init --offline' and GitHub release ZIPs
- Fix macOS bash 3.2 compat in release script: replace cp --parents,
local -n (nameref), and mapfile with POSIX-safe alternatives
- Fix _TOML_AGENTS: remove qwen (uses markdown per release script)
- Rename --from-github to --offline (opt-in to bundled assets)
- Add _locate_release_script() for cross-platform script discovery
- Update tests: remove bash 4+/GNU coreutils requirements, handle
Kimi directory-per-skill layout, 576 tests passing
- Update CHANGELOG and docs/installation.md
* Potential fix for pull request finding
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
* fix(offline): error out if --offline fails instead of falling back to network
- _locate_core_pack() docstring now accurately describes that it only
finds wheel-bundled core_pack/; source-checkout fallback lives in callers
- init() --offline + no bundled assets now exits with a clear error
(previously printed a warning and silently fell back to GitHub download)
- init() scaffold failure under --offline now exits with an error
instead of retrying via download_and_extract_template
Addresses reviewer comment: https://github.com/github/spec-kit/pull/1803
* fix(offline): address PR review comments
- fix(shell): harden validate_subset against glob injection in case patterns
- fix(shell): make GENRELEASES_DIR overridable via env var for test isolation
- fix(cli): probe pwsh then powershell on Windows instead of hardcoding pwsh
- fix(cli): remove unreachable fallback branch when --offline fails
- fix(cli): improve --offline error message with common failure causes
- fix(release): move wheel build step after create-release-packages.sh
- fix(docs): add --offline to installation.md air-gapped example
- fix(tests): remove unused genreleases_dir param from _run_release_script
- fix(tests): rewrite parity test to run one agent at a time with isolated
temp dirs, preventing cross-agent interference from rm -rf
* fix(offline): address second round of review comments
- fix(shell): replace case-pattern membership with explicit loop + == check
for unambiguous glob-safety in validate_subset()
- fix(cli): require pwsh (PowerShell 7) only; drop powershell (PS5) fallback
since the bundled script uses #requires -Version 7.0
- fix(cli): add bash and zip preflight checks in scaffold_from_core_pack()
with clear error messages if either is missing
- fix(build): list individual template files in pyproject.toml force-include
to avoid duplicating templates/commands/ in the wheel
* fix(offline): address third round of review comments
- Add 120s timeout to subprocess.run in scaffold_from_core_pack to prevent
indefinite hangs during offline scaffolding
- Add test_pyproject_force_include_covers_all_templates to catch missing
template files in wheel bundling
- Tighten kiro alias test to assert specific scaffold path (download vs offline)
* fix(offline): address Copilot review round 4
- fix(offline): use handle_vscode_settings() merge for --here --offline
to prevent data loss on existing .vscode/settings.json
- fix(release): glob wheel filename in create-github-release.sh instead
of hardcoding version, preventing upload failures on version mismatch
- docs(release): add comment noting pyproject.toml version is synced by
release-trigger.yml before the tag is pushed
* fix(offline): address review round 5 + offline bundle ZIP
- fix(offline): pwsh-only, no powershell.exe fallback; clarify error message
- fix(offline): tighten _has_bundled to check scripts dir for source checkouts
- feat(release): build specify-bundle-v*.zip with all deps at release time
- feat(release): attach offline bundle ZIP to GitHub release assets
- docs: simplify air-gapped install to single ZIP download from releases
- docs: add Windows PowerShell 7+ (pwsh) requirement note
* fix(tests): session-scoped scaffold cache + timeout + dead code removal
- Add timeout=300 and returncode check to _run_release_script() to fail
fast with clear output on script hangs or failures
- Remove unused import specify_cli, _SOURCE_TEMPLATES, bundled_project fixture
- Add session-scoped scaffolded_sh/scaffolded_ps fixtures that scaffold
once per agent and reuse the output directory across all invariant tests
- Reduces test_core_pack_scaffold runtime from ~175s to ~51s (3.4x faster)
- Parity tests still scaffold independently for isolation
* fix(offline): remove wheel from release, update air-gapped docs to use pip download
* fix(tests): handle codex skills layout and iflow agent in scaffold tests
Codex now uses create_skills() with hyphenated separator (speckit-plan/SKILL.md)
instead of generate_commands(). Update _SKILL_AGENTS, _expected_ext, and
_list_command_files to handle both codex ('-') and kimi ('.') skill agents.
Also picks up iflow as a new testable agent automatically via AGENT_CONFIG.
* fix(offline): require wheel core_pack for --offline, remove source-checkout fallback
--offline now strictly requires _locate_core_pack() to find the wheel's
bundled core_pack/ directory. Source-checkout fallbacks are no longer
accepted at the init() level — if core_pack/ is missing, the CLI errors
out with a clear message pointing to the installation docs.
scaffold_from_core_pack() retains its internal source-checkout fallbacks
so parity tests can call it directly from a source checkout.
* fix(offline): remove stale [Unreleased] CHANGELOG section, scope httpx.Client to download path
- Remove entire [Unreleased] section — CHANGELOG is auto-generated at release
- Move httpx.Client into use_github branch with context manager so --offline
path doesn't allocate an unused network client
* fix(offline): remove dead --from-github flag, fix typer.Exit handling, add page templates validation
- Remove unused --from-github CLI option and docstring example
- Add (typer.Exit, SystemExit) re-raise before broad except Exception
to prevent duplicate error panel on offline scaffold failure
- Validate page templates directory exists in scaffold_from_core_pack()
to fail fast on incomplete wheel installs
- Fix ruff lint: remove unused shutil import, remove f-prefix on
strings without placeholders in test_core_pack_scaffold.py
* docs(offline): add v0.6.0 deprecation notice with rationale
- Help text: note bundled assets become default in v0.6.0
- Docstring: explain why GitHub download is being retired (no network
dependency, no proxy/firewall issues, guaranteed version match)
- Runtime nudge: when bundled assets are available but user takes the
GitHub download path, suggest --offline with rationale
- docs/installation.md: add deprecation notice with full rationale
* fix(offline): allow --offline in source checkouts, fix CHANGELOG truncation
- Simplify use_github logic: use_github = not offline (let
scaffold_from_core_pack handle fallback to source-checkout paths)
- Remove hard-fail when core_pack/ is absent — scaffold_from_core_pack
already falls back to repo-root templates/scripts/commands
- Fix truncated 'skill…' → 'skills' in CHANGELOG.md
* fix(offline): sandbox GENRELEASES_DIR and clean up on failure
- Pin GENRELEASES_DIR to temp dir in scaffold_from_core_pack() so a
user-exported value cannot redirect output or cause rm -rf outside
the sandbox
- Clean up partial project directory on --offline scaffold failure
(same behavior as the GitHub-download failure path)
* fix(tests): use shutil.which for bash discovery, add ps parity tests
- _find_bash() now tries shutil.which('bash') first so non-standard
install locations (Nix, custom CI images) are found
- Parametrize parity test over both 'sh' and 'ps' script types to
ensure PowerShell variant stays byte-for-byte identical to release
script output (353 scaffold tests, 810 total)
* fix(tests): parse pyproject.toml with tomllib, remove unused fixture
- Use tomllib to parse force-include keys from the actual TOML table
instead of raw substring search (avoids false positives)
- Remove unused source_template_stems fixture from
test_scaffold_command_dir_location
* fix: guard GENRELEASES_DIR against unsafe values, update docstring
- Add safety check in create-release-packages.sh: reject empty, '/',
'.', '..' values for GENRELEASES_DIR before rm -rf
- Strip trailing slash to avoid path surprises
- Update scaffold_from_core_pack() docstring to accurately describe
all failure modes (not just 'assets not found')
* fix: harden GENRELEASES_DIR guard, cache parity tests, safe iterdir
- Reject '..' path segments in GENRELEASES_DIR to prevent traversal
- Session-cache both scaffold and release-script results in parity
tests — runtime drops from ~74s to ~45s (40% faster)
- Guard cmd_dir.iterdir() in assertion message against missing dirs
* fix(tests): exclude YAML frontmatter source metadata from path rewrite check
The codex and kimi SKILL.md files have 'source: templates/commands/...'
in their YAML frontmatter — this is provenance metadata, not a runtime
path that needs rewriting. Strip frontmatter before checking for bare
scripts/ and templates/ paths.
* fix(offline): surface scaffold failure detail in error output
When --offline scaffold fails, look up the tracker's 'scaffold' step
detail and print it alongside the generic error message so users see
the specific root cause (e.g. missing zip/pwsh, script stderr).
---------
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
* docs: update publishing guide with Category and Effect columns
The README table now has Category and Effect columns (added in #1897),
but the publishing guide template still showed the old 3-column format.
Update to match so extension authors know to include both fields.
Made-with: Cursor
* docs: copilot comments
