Stage 2: Copilot integration — proof of concept with shared template primitives (#2035)

* feat: Stage 2a — CopilotIntegration with shared template primitives

- base.py: added granular primitives (shared_commands_dir,
  shared_templates_dir, list_command_templates, command_filename,
  commands_dest, copy_command_to_directory, record_file_in_manifest,
  write_file_and_record, process_template)
- CopilotIntegration: uses primitives to produce .agent.md commands,
  companion .prompt.md files, and .vscode/settings.json
- Verified byte-for-byte parity with old release script output
- Copilot auto-registered in INTEGRATION_REGISTRY
- 70 tests (22 new: base primitives + copilot integration)

Part of #1924

* feat: Stage 2b — --integration flag, routing, agent.json, shared infra

- Added --integration flag to init() (mutually exclusive with --ai)
- --ai copilot auto-promotes to integration path with migration nudge
- Integration setup writes .specify/agent.json with integration key
- _install_shared_infra() copies scripts and templates to .specify/
- init-options.json records 'integration' key when used
- 4 new CLI tests: mutual exclusivity, unknown rejection, copilot
  end-to-end, auto-promote (74 total integration tests)

Part of #1924

* feat: Stage 2 completion — integration scripts, integration.json, shared manifest

- Added copilot/scripts/update-context.sh and .ps1 (thin wrappers
  that delegate to the shared update-agent-context script)
- CopilotIntegration.setup() installs integration scripts to
  .specify/integrations/copilot/scripts/
- Renamed agent.json → integration.json with script paths
- _install_shared_infra() now tracks files in
  integration-shared.manifest.json
- Updated tests: scripts installed, integration.json has script paths,
  shared manifest recorded (74 tests)

Part of #1924

* refactor: rename shared manifest to speckit.manifest.json

Cleaner naming — the shared infrastructure (scripts, templates)
belongs to spec-kit itself, not to any specific integration.

* fix: copilot update-context scripts reflect target architecture

Scripts now source shared functions (via SPECKIT_SOURCE_ONLY=1) and
call update_agent_file directly with .github/copilot-instructions.md,
rather than delegating back to the shared case statement.

* fix: simplify copilot scripts — dispatcher sources common functions

Integration scripts now contain only copilot-specific logic (target
path + agent name). The dispatcher is responsible for sourcing shared
functions before calling the integration script.

* fix: copilot update-context scripts are self-contained implementations

These scripts ARE the implementation — the dispatcher calls them.
They source common.sh + update-agent-context functions, gather
feature/plan data, then call update_agent_file with the copilot
target path (.github/copilot-instructions.md).

* docs: add Stage 7 activation note to copilot update-context scripts

* test: add complete file inventory test for copilot integration

Validates every single file (37 total) produced by
specify init --integration copilot --script sh --no-git.

* test: add PowerShell file inventory test for copilot integration

Validates all 37 files produced by --script ps variant, including
.specify/scripts/powershell/ instead of bash.

* refactor: split test_integrations.py into tests/integrations/ directory

- test_base.py: IntegrationOption, IntegrationBase, MarkdownIntegration, primitives
- test_manifest.py: IntegrationManifest, path traversal, persistence, validation
- test_registry.py: INTEGRATION_REGISTRY
- test_copilot.py: CopilotIntegration unit tests
- test_cli.py: --integration flag, auto-promote, file inventories (sh + ps)
- conftest.py: shared StubIntegration helper

76 integration tests + 48 consistency tests = 124 total, all passing.

* refactor: move file inventory tests from test_cli to test_copilot

File inventories are copilot-specific. test_cli.py now only tests
CLI flag mechanics (mutual exclusivity, unknown rejection, auto-promote).

* fix: skip JSONC merge to preserve user settings, fix docstring

- _merge_vscode_settings() now returns early (skips merge) when
  existing settings.json can't be parsed (e.g. JSONC with comments),
  instead of overwriting with empty settings
- Updated _install_shared_infra() docstring to match implementation
  (scripts + templates, speckit.manifest.json)

* fix: warn user when JSONC settings merge is skipped

* fix: show template content when JSONC merge is skipped

User now sees the exact settings they should add manually.

* fix: document process_template requirement, merge scripts without rmtree

- base.py setup() docstring now explicitly states raw copy behavior
  and directs to CopilotIntegration for process_template example
- _install_shared_infra() uses merge/overwrite instead of rmtree to
  preserve user-added files under .specify/scripts/

* fix: don't overwrite pre-existing shared scripts or templates

Only write files that don't already exist — preserves any user
modifications to shared scripts (common.sh etc.) and templates.

* fix: warn user about skipped pre-existing shared files

Lists all shared scripts and templates that were not copied because
they already existed in the project.

* test: add test for shared infra skip behavior on pre-existing files

Verifies that _install_shared_infra() preserves user-modified scripts
and templates while still installing missing ones.

* fix: address review — containment check, deterministic prompts, manifest accuracy

- CopilotIntegration.setup() adds dest containment check (relative_to)
- Companion prompts generated from templates list, not directory glob
- _install_shared_infra() only records files actually copied (not pre-existing)
- VS Code settings tests made unconditional (assert template exists)
- Inventory tests use .as_posix() for cross-platform paths

* fix: correct PS1 function names, document SPECKIT_SOURCE_ONLY prerequisite

- Fixed Get-FeaturePaths → Get-FeaturePathsEnv, Read-PlanData → Parse-PlanData
- Documented that shared scripts must guard Main with SPECKIT_SOURCE_ONLY
  before these integration scripts can be activated (Stage 7)

* fix: add dict type check for settings merge, simplify PS1 to subprocess

- _merge_vscode_settings() skips merge with warning if parsed JSON
  is not a dict (array, null, etc.)
- PS1 update-context.ps1 uses & invocation instead of dot-sourcing
  since the shared script runs Main unconditionally

* fix: skip-write on no-op merge, bash subprocess, dynamic integration list

- _merge_vscode_settings() only writes when keys were actually added
- update-context.sh uses exec subprocess like PS1 version
- Unknown integration error lists available integrations dynamically

* fix: align path rewriting with release script, add .specify/.specify/ fix

Path rewrite regex matches the release script's rewrite_paths()
exactly (verified byte-identical output). Added .specify/.specify/
double-prefix fix for additional safety.

.devcontainer/post-create.sh

@@ -51,6 +51,14 @@ echo -e "\n🤖 Installing OpenCode CLI..."
 run_command "npm install -g opencode-ai@latest"
 echo "✅ Done"
 
+echo -e "\n🤖 Installing Junie CLI..."
+run_command "npm install -g @jetbrains/junie-cli@latest"
+echo "✅ Done"
+
+echo -e "\n🤖 Installing Pi Coding Agent..."
+run_command "npm install -g @mariozechner/pi-coding-agent@latest"
+echo "✅ Done"
+
 echo -e "\n🤖 Installing Kiro CLI..."
 # https://kiro.dev/docs/cli/
 KIRO_INSTALLER_URL="https://kiro.dev/install.sh"

.github/ISSUE_TEMPLATE/agent_request.yml

@@ -8,7 +8,7 @@ body:
       value: |
         Thanks for requesting a new agent! Before submitting, please check if the agent is already supported.
         
-        **Currently supported agents**: Claude Code, Gemini CLI, GitHub Copilot, Cursor, Qwen Code, opencode, Codex CLI, Windsurf, Kilo Code, Auggie CLI, Roo Code, CodeBuddy, Qoder CLI, Kiro CLI, Amp, SHAI, IBM Bob, Antigravity
+        **Currently supported agents**: Claude Code, Gemini CLI, GitHub Copilot, Cursor, Qwen Code, opencode, Codex CLI, Windsurf, Kilo Code, Auggie CLI, Roo Code, CodeBuddy, Qoder CLI, Kiro CLI, Amp, SHAI, Tabnine CLI, Antigravity, IBM Bob, Mistral Vibe, Kimi Code, Trae, Pi Coding Agent, iFlow CLI
 
   - type: input
     id: agent-name

.github/ISSUE_TEMPLATE/config.yml

@@ -7,7 +7,7 @@ contact_links:
     url: https://github.com/github/spec-kit/blob/main/README.md
     about: Read the Spec Kit documentation and guides
   - name: 🛠️ Extension Development Guide
-    url: https://github.com/manfredseee/spec-kit/blob/main/extensions/EXTENSION-DEVELOPMENT-GUIDE.md
+    url: https://github.com/github/spec-kit/blob/main/extensions/EXTENSION-DEVELOPMENT-GUIDE.md
     about: Learn how to develop and publish Spec Kit extensions
   - name: 🤝 Contributing Guide
     url: https://github.com/github/spec-kit/blob/main/CONTRIBUTING.md

.github/ISSUE_TEMPLATE/extension_submission.yml

@@ -12,7 +12,7 @@ body:
         - Review the [Extension Publishing Guide](https://github.com/github/spec-kit/blob/main/extensions/EXTENSION-PUBLISHING-GUIDE.md)
         - Ensure your extension has a valid `extension.yml` manifest
         - Create a GitHub release with a version tag (e.g., v1.0.0)
-        - Test installation: `specify extension add --from <your-release-url>`
+        - Test installation: `specify extension add <extension-name> --from <your-release-url>`
 
   - type: input
     id: extension-id
@@ -229,7 +229,7 @@ body:
       placeholder: |
         ```bash
         # Install extension
-        specify extension add --from https://github.com/your-org/spec-kit-your-extension/archive/refs/tags/v1.0.0.zip
+        specify extension add <extension-name> --from https://github.com/your-org/spec-kit-your-extension/archive/refs/tags/v1.0.0.zip
         
         # Use a command
         /speckit.your-extension.command-name arg1 arg2

.github/ISSUE_TEMPLATE/preset_submission.yml

@@ -0,0 +1,169 @@
+name: Preset Submission
+description: Submit your preset to the Spec Kit preset catalog
+title: "[Preset]: Add "
+labels: ["preset-submission", "enhancement", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for contributing a preset! This template helps you submit your preset to the community catalog.
+        
+        **Before submitting:**
+        - Review the [Preset Publishing Guide](https://github.com/github/spec-kit/blob/main/presets/PUBLISHING.md)
+        - Ensure your preset has a valid `preset.yml` manifest
+        - Create a GitHub release with a version tag (e.g., v1.0.0)
+        - Test installation from the release archive: `specify preset add --from <download-url>`
+
+  - type: input
+    id: preset-id
+    attributes:
+      label: Preset ID
+      description: Unique preset identifier (lowercase with hyphens only)
+      placeholder: "e.g., healthcare-compliance"
+    validations:
+      required: true
+
+  - type: input
+    id: preset-name
+    attributes:
+      label: Preset Name
+      description: Human-readable preset name
+      placeholder: "e.g., Healthcare Compliance"
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      description: Semantic version number
+      placeholder: "e.g., 1.0.0"
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: Brief description of what your preset does (under 200 characters)
+      placeholder: Enforces HIPAA-compliant spec workflows with audit templates and compliance checklists
+    validations:
+      required: true
+
+  - type: input
+    id: author
+    attributes:
+      label: Author
+      description: Your name or organization
+      placeholder: "e.g., John Doe or Acme Corp"
+    validations:
+      required: true
+
+  - type: input
+    id: repository
+    attributes:
+      label: Repository URL
+      description: GitHub repository URL for your preset
+      placeholder: "https://github.com/your-org/spec-kit-your-preset"
+    validations:
+      required: true
+
+  - type: input
+    id: download-url
+    attributes:
+      label: Download URL
+      description: URL to the GitHub release archive for your preset (e.g., https://github.com/your-org/spec-kit-preset-your-preset/archive/refs/tags/v1.0.0.zip)
+      placeholder: "https://github.com/your-org/spec-kit-preset-your-preset/archive/refs/tags/v1.0.0.zip"
+    validations:
+      required: true
+
+  - type: input
+    id: license
+    attributes:
+      label: License
+      description: Open source license type
+      placeholder: "e.g., MIT, Apache-2.0"
+    validations:
+      required: true
+
+  - type: input
+    id: speckit-version
+    attributes:
+      label: Required Spec Kit Version
+      description: Minimum Spec Kit version required
+      placeholder: "e.g., >=0.3.0"
+    validations:
+      required: true
+
+  - type: textarea
+    id: templates-provided
+    attributes:
+      label: Templates Provided
+      description: List the template overrides your preset provides
+      placeholder: |
+        - spec-template.md — adds compliance section
+        - plan-template.md — includes audit checkpoints
+        - checklist-template.md — HIPAA compliance checklist
+    validations:
+      required: true
+
+  - type: textarea
+    id: commands-provided
+    attributes:
+      label: Commands Provided (optional)
+      description: List any command overrides your preset provides
+      placeholder: |
+        - speckit.specify.md — customized for compliance workflows
+
+  - type: textarea
+    id: tags
+    attributes:
+      label: Tags
+      description: 2-5 relevant tags (lowercase, separated by commas)
+      placeholder: "compliance, healthcare, hipaa, audit"
+    validations:
+      required: true
+
+  - type: textarea
+    id: features
+    attributes:
+      label: Key Features
+      description: List the main features and capabilities of your preset
+      placeholder: |
+        - HIPAA-compliant spec templates
+        - Audit trail checklists
+        - Compliance review workflow
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: testing
+    attributes:
+      label: Testing Checklist
+      description: Confirm that your preset has been tested
+      options:
+        - label: Preset installs successfully via `specify preset add`
+          required: true
+        - label: Template resolution works correctly after installation
+          required: true
+        - label: Documentation is complete and accurate
+          required: true
+        - label: Tested on at least one real project
+          required: true
+
+  - type: checkboxes
+    id: requirements
+    attributes:
+      label: Submission Requirements
+      description: Verify your preset meets all requirements
+      options:
+        - label: Valid `preset.yml` manifest included
+          required: true
+        - label: README.md with description and usage instructions
+          required: true
+        - label: LICENSE file included
+          required: true
+        - label: GitHub release created with version tag
+          required: true
+        - label: Preset ID follows naming conventions (lowercase-with-hyphens)
+          required: true

.github/workflows/docs.yml

@@ -64,5 +64,5 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v5
 

.github/workflows/lint.yml

@@ -15,7 +15,7 @@ jobs:
         uses: actions/checkout@v6
 
       - name: Run markdownlint-cli2
-        uses: DavidAnson/markdownlint-cli2-action@v19
+        uses: DavidAnson/markdownlint-cli2-action@ce4853d43830c74c1753b39f3cf40f71c2031eb9 # v23
         with:
           globs: |
             '**/*.md'

.github/workflows/release-trigger.yml

@@ -86,8 +86,10 @@ jobs:
           if [ -f "CHANGELOG.md" ]; then
             DATE=$(date +%Y-%m-%d)
 
-            # Get the previous tag to compare commits
-            PREVIOUS_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
+            # Get the previous tag by sorting all version tags numerically
+            # (git describe --tags only finds tags reachable from HEAD,
+            #  which misses tags on unmerged release branches)
+            PREVIOUS_TAG=$(git tag -l 'v*' --sort=-version:refname | head -n 1)
 
             echo "Generating changelog from commits..."
             if [[ -n "$PREVIOUS_TAG" ]]; then
@@ -98,18 +100,16 @@ jobs:
               COMMITS="- Initial release"
             fi
 
-            # Create new changelog entry
-            {
-              head -n 8 CHANGELOG.md
-              echo ""
-              echo "## [${{ steps.version.outputs.version }}] - $DATE"
-              echo ""
-              echo "### Changed"
-              echo ""
-              echo "$COMMITS"
-              echo ""
-              tail -n +9 CHANGELOG.md
-            } > CHANGELOG.md.tmp
+            # Create new changelog entry — insert after the marker comment
+            NEW_ENTRY=$(printf '%s\n' \
+              "" \
+              "## [${{ steps.version.outputs.version }}] - $DATE" \
+              "" \
+              "### Changed" \
+              "" \
+              "$COMMITS")
+
+            awk -v entry="$NEW_ENTRY" '/<!-- insert new changelog below this comment -->/ { print; print entry; next } {print}' CHANGELOG.md > CHANGELOG.md.tmp
             mv CHANGELOG.md.tmp CHANGELOG.md
 
             echo "✅ Updated CHANGELOG.md with commits since $PREVIOUS_TAG"
@@ -139,6 +139,22 @@ jobs:
           git push origin "${{ steps.version.outputs.tag }}"
           echo "Branch ${{ env.branch }} and tag ${{ steps.version.outputs.tag }} pushed"
 
+      - name: Bump to dev version
+        id: dev_version
+        run: |
+          IFS='.' read -r MAJOR MINOR PATCH <<< "${{ steps.version.outputs.version }}"
+          NEXT_DEV="$MAJOR.$MINOR.$((PATCH + 1)).dev0"
+          echo "dev_version=$NEXT_DEV" >> $GITHUB_OUTPUT
+          sed -i "s/version = \".*\"/version = \"$NEXT_DEV\"/" pyproject.toml
+          git add pyproject.toml
+          if git diff --cached --quiet; then
+            echo "No dev version changes to commit"
+          else
+            git commit -m "chore: begin $NEXT_DEV development"
+            git push origin "${{ env.branch }}"
+            echo "Bumped to dev version $NEXT_DEV"
+          fi
+
       - name: Open pull request
         env:
           GITHUB_TOKEN: ${{ secrets.RELEASE_PAT }}
@@ -146,16 +162,17 @@ jobs:
           gh pr create \
             --base main \
             --head "${{ env.branch }}" \
-            --title "chore: bump version to ${{ steps.version.outputs.version }}" \
-            --body "Automated version bump to ${{ steps.version.outputs.version }}.
+            --title "chore: release ${{ steps.version.outputs.version }}, begin ${{ steps.dev_version.outputs.dev_version }} development" \
+            --body "Automated release of ${{ steps.version.outputs.version }}.
 
           This PR was created by the Release Trigger workflow. The git tag \`${{ steps.version.outputs.tag }}\` has already been pushed and the release artifacts are being built.
 
-          Merge this PR to record the version bump and changelog update on \`main\`."
+          Merging this PR will set \`main\` to \`${{ steps.dev_version.outputs.dev_version }}\` so that development installs are clearly marked as pre-release."
 
       - name: Summary
         run: |
           echo "✅ Version bumped to ${{ steps.version.outputs.version }}"
           echo "✅ Tag ${{ steps.version.outputs.tag }} created and pushed"
+          echo "✅ Dev version set to ${{ steps.dev_version.outputs.dev_version }}"
           echo "✅ PR opened to merge version bump into main"
           echo "🚀 Release workflow is building artifacts from the tag"

.github/workflows/scripts/create-github-release.sh

@@ -30,6 +30,8 @@ gh release create "$VERSION" \
   .genreleases/spec-kit-template-qwen-ps-"$VERSION".zip \
   .genreleases/spec-kit-template-windsurf-sh-"$VERSION".zip \
   .genreleases/spec-kit-template-windsurf-ps-"$VERSION".zip \
+  .genreleases/spec-kit-template-junie-sh-"$VERSION".zip \
+  .genreleases/spec-kit-template-junie-ps-"$VERSION".zip \
   .genreleases/spec-kit-template-codex-sh-"$VERSION".zip \
   .genreleases/spec-kit-template-codex-ps-"$VERSION".zip \
   .genreleases/spec-kit-template-kilocode-sh-"$VERSION".zip \
@@ -58,6 +60,12 @@ gh release create "$VERSION" \
   .genreleases/spec-kit-template-vibe-ps-"$VERSION".zip \
   .genreleases/spec-kit-template-kimi-sh-"$VERSION".zip \
   .genreleases/spec-kit-template-kimi-ps-"$VERSION".zip \
+  .genreleases/spec-kit-template-trae-sh-"$VERSION".zip \
+  .genreleases/spec-kit-template-trae-ps-"$VERSION".zip \
+  .genreleases/spec-kit-template-pi-sh-"$VERSION".zip \
+  .genreleases/spec-kit-template-pi-ps-"$VERSION".zip \
+  .genreleases/spec-kit-template-iflow-sh-"$VERSION".zip \
+  .genreleases/spec-kit-template-iflow-ps-"$VERSION".zip \
   .genreleases/spec-kit-template-generic-sh-"$VERSION".zip \
   .genreleases/spec-kit-template-generic-ps-"$VERSION".zip \
   --title "Spec Kit Templates - $VERSION_NO_V" \

.github/workflows/scripts/create-release-packages.ps1

@@ -14,7 +14,7 @@
 
 .PARAMETER Agents
     Comma or space separated subset of agents to build (default: all)
-    Valid agents: claude, gemini, copilot, cursor-agent, qwen, opencode, windsurf, codex, kilocode, auggie, roo, codebuddy, amp, kiro-cli, bob, qodercli, shai, tabnine, agy, vibe, kimi, generic
+    Valid agents: claude, gemini, copilot, cursor-agent, qwen, opencode, windsurf, junie, codex, kilocode, auggie, roo, codebuddy, amp, kiro-cli, bob, qodercli, shai, tabnine, agy, vibe, kimi, trae, pi, iflow, generic
 
 .PARAMETER Scripts
     Comma or space separated subset of script types to build (default: both)
@@ -201,20 +201,25 @@ agent: $basename
     }
 }
 
-# Create Kimi Code skills in .kimi/skills/<name>/SKILL.md format.
-# Kimi CLI discovers skills as directories containing a SKILL.md file,
-# invoked with /skill:<name> (e.g. /skill:speckit.specify).
-function New-KimiSkills {
+# Create skills in <skills_dir>\<name>\SKILL.md format.
+# Skills use hyphenated names (e.g. speckit-plan).
+#
+# Technical debt note:
+# Keep SKILL.md frontmatter aligned with `install_ai_skills()` and extension
+# overrides (at minimum: name/description/compatibility/metadata.{author,source}).
+function New-Skills {
     param(
         [string]$SkillsDir,
-        [string]$ScriptVariant
+        [string]$ScriptVariant,
+        [string]$AgentName,
+        [string]$Separator = '-'
     )
 
     $templates = Get-ChildItem -Path "templates/commands/*.md" -File -ErrorAction SilentlyContinue
 
     foreach ($template in $templates) {
         $name = [System.IO.Path]::GetFileNameWithoutExtension($template.Name)
-        $skillName = "speckit.$name"
+        $skillName = "speckit${Separator}$name"
         $skillDir = Join-Path $SkillsDir $skillName
         New-Item -ItemType Directory -Force -Path $skillDir | Out-Null
 
@@ -267,7 +272,7 @@ function New-KimiSkills {
 
         $body = $outputLines -join "`n"
         $body = $body -replace '\{ARGS\}', '$ARGUMENTS'
-        $body = $body -replace '__AGENT__', 'kimi'
+        $body = $body -replace '__AGENT__', $AgentName
         $body = Rewrite-Paths -Content $body
 
         # Strip existing frontmatter, keep only body
@@ -283,7 +288,7 @@ function New-KimiSkills {
             if ($inBody) { $templateBody += "$line`n" }
         }
 
-        $skillContent = "---`nname: `"$skillName`"`ndescription: `"$description`"`n---`n`n$templateBody"
+        $skillContent = "---`nname: `"$skillName`"`ndescription: `"$description`"`ncompatibility: `"Requires spec-kit project structure with .specify/ directory`"`nmetadata:`n  author: `"github-spec-kit`"`n  source: `"templates/commands/$name.md`"`n---`n`n$templateBody"
         Set-Content -Path (Join-Path $skillDir "SKILL.md") -Value $skillContent -NoNewline
     }
 }
@@ -395,9 +400,14 @@ function Build-Variant {
             $cmdDir = Join-Path $baseDir ".windsurf/workflows"
             Generate-Commands -Agent 'windsurf' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script
         }
+        'junie' {
+            $cmdDir = Join-Path $baseDir ".junie/commands"
+            Generate-Commands -Agent 'junie' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script
+        }
         'codex' {
-            $cmdDir = Join-Path $baseDir ".codex/prompts"
-            Generate-Commands -Agent 'codex' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script
+            $skillsDir = Join-Path $baseDir ".agents/skills"
+            New-Item -ItemType Directory -Force -Path $skillsDir | Out-Null
+            New-Skills -SkillsDir $skillsDir -ScriptVariant $Script -AgentName 'codex' -Separator '-'
         }
         'kilocode' {
             $cmdDir = Join-Path $baseDir ".kilocode/workflows"
@@ -452,7 +462,20 @@ function Build-Variant {
         'kimi' {
             $skillsDir = Join-Path $baseDir ".kimi/skills"
             New-Item -ItemType Directory -Force -Path $skillsDir | Out-Null
-            New-KimiSkills -SkillsDir $skillsDir -ScriptVariant $Script
+            New-Skills -SkillsDir $skillsDir -ScriptVariant $Script -AgentName 'kimi'
+        }
+        'trae' {
+            $rulesDir = Join-Path $baseDir ".trae/rules"
+            New-Item -ItemType Directory -Force -Path $rulesDir | Out-Null
+            Generate-Commands -Agent 'trae' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $rulesDir -ScriptVariant $Script
+        }
+        'pi' {
+            $cmdDir = Join-Path $baseDir ".pi/prompts"
+            Generate-Commands -Agent 'pi' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script
+        }
+        'iflow' {
+            $cmdDir = Join-Path $baseDir ".iflow/commands"
+            Generate-Commands -Agent 'iflow' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script
         }
         'generic' {
             $cmdDir = Join-Path $baseDir ".speckit/commands"
@@ -470,17 +493,17 @@ function Build-Variant {
 }
 
 # Define all agents and scripts
-$AllAgents = @('claude', 'gemini', 'copilot', 'cursor-agent', 'qwen', 'opencode', 'windsurf', 'codex', 'kilocode', 'auggie', 'roo', 'codebuddy', 'amp', 'kiro-cli', 'bob', 'qodercli', 'shai', 'tabnine', 'agy', 'vibe', 'kimi', 'generic')
+$AllAgents = @('claude', 'gemini', 'copilot', 'cursor-agent', 'qwen', 'opencode', 'windsurf', 'junie', 'codex', 'kilocode', 'auggie', 'roo', 'codebuddy', 'amp', 'kiro-cli', 'bob', 'qodercli', 'shai', 'tabnine', 'agy', 'vibe', 'kimi', 'trae', 'pi', 'iflow', 'generic')
 $AllScripts = @('sh', 'ps')
 
 function Normalize-List {
-    param([string]$Input)
+    param([string]$Value)
 
-    if ([string]::IsNullOrEmpty($Input)) {
+    if ([string]::IsNullOrEmpty($Value)) {
         return @()
     }
 
-    $items = $Input -split '[,\s]+' | Where-Object { $_ } | Select-Object -Unique
+    $items = $Value -split '[,\s]+' | Where-Object { $_ } | Select-Object -Unique
     return $items
 }
 
@@ -503,7 +526,7 @@ function Validate-Subset {
 
 # Determine agent list
 if (-not [string]::IsNullOrEmpty($Agents)) {
-    $AgentList = Normalize-List -Input $Agents
+    $AgentList = Normalize-List -Value $Agents
     if (-not (Validate-Subset -Type 'agent' -Allowed $AllAgents -Items $AgentList)) {
         exit 1
     }
@@ -513,7 +536,7 @@ if (-not [string]::IsNullOrEmpty($Agents)) {
 
 # Determine script list
 if (-not [string]::IsNullOrEmpty($Scripts)) {
-    $ScriptList = Normalize-List -Input $Scripts
+    $ScriptList = Normalize-List -Value $Scripts
     if (-not (Validate-Subset -Type 'script' -Allowed $AllScripts -Items $ScriptList)) {
         exit 1
     }

.github/workflows/scripts/create-release-packages.sh

@@ -6,7 +6,7 @@ set -euo pipefail
 # Usage: .github/workflows/scripts/create-release-packages.sh <version>
 #   Version argument should include leading 'v'.
 #   Optionally set AGENTS and/or SCRIPTS env vars to limit what gets built.
-#     AGENTS  : space or comma separated subset of: claude gemini copilot cursor-agent qwen opencode windsurf codex kilocode auggie roo codebuddy amp shai tabnine kiro-cli agy bob vibe qodercli kimi generic (default: all)
+#     AGENTS  : space or comma separated subset of: claude gemini copilot cursor-agent qwen opencode windsurf junie codex kilocode auggie roo codebuddy amp shai tabnine kiro-cli agy bob vibe qodercli kimi trae pi iflow generic (default: all)
 #     SCRIPTS : space or comma separated subset of: sh ps (default: both)
 #   Examples:
 #     AGENTS=claude SCRIPTS=sh $0 v0.2.0
@@ -26,9 +26,27 @@ fi
 echo "Building release packages for $NEW_VERSION"
 
 # Create and use .genreleases directory for all build artifacts
-GENRELEASES_DIR=".genreleases"
+# Override via GENRELEASES_DIR env var (e.g. for tests writing to a temp dir)
+GENRELEASES_DIR="${GENRELEASES_DIR:-.genreleases}"
+
+# Guard against unsafe GENRELEASES_DIR values before cleaning
+if [[ -z "$GENRELEASES_DIR" ]]; then
+  echo "GENRELEASES_DIR must not be empty" >&2
+  exit 1
+fi
+case "$GENRELEASES_DIR" in
+  '/'|'.'|'..')
+    echo "Refusing to use unsafe GENRELEASES_DIR value: $GENRELEASES_DIR" >&2
+    exit 1
+    ;;
+esac
+if [[ "$GENRELEASES_DIR" == *".."* ]]; then
+  echo "Refusing to use GENRELEASES_DIR containing '..' path segments: $GENRELEASES_DIR" >&2
+  exit 1
+fi
+
 mkdir -p "$GENRELEASES_DIR"
-rm -rf "$GENRELEASES_DIR"/* || true
+rm -rf "${GENRELEASES_DIR%/}/"* || true
 
 rewrite_paths() {
   sed -E \
@@ -121,18 +139,23 @@ EOF
   done
 }
 
-# Create Kimi Code skills in .kimi/skills/<name>/SKILL.md format.
-# Kimi CLI discovers skills as directories containing a SKILL.md file,
-# invoked with /skill:<name> (e.g. /skill:speckit.specify).
-create_kimi_skills() {
+# Create skills in <skills_dir>/<name>/SKILL.md format.
+# Skills use hyphenated names (e.g. speckit-plan).
+#
+# Technical debt note:
+# Keep SKILL.md frontmatter aligned with `install_ai_skills()` and extension
+# overrides (at minimum: name/description/compatibility/metadata.{author,source}).
+create_skills() {
   local skills_dir="$1"
   local script_variant="$2"
+  local agent_name="$3"
+  local separator="${4:-"-"}"
 
   for template in templates/commands/*.md; do
     [[ -f "$template" ]] || continue
     local name
     name=$(basename "$template" .md)
-    local skill_name="speckit.${name}"
+    local skill_name="speckit${separator}${name}"
     local skill_dir="${skills_dir}/${skill_name}"
     mkdir -p "$skill_dir"
 
@@ -175,9 +198,9 @@ create_kimi_skills() {
       in_frontmatter && skip_scripts && /^[[:space:]]/ { next }
       { print }
     ')
-    body=$(printf '%s\n' "$body" | sed 's/{ARGS}/\$ARGUMENTS/g' | sed 's/__AGENT__/kimi/g' | rewrite_paths)
+    body=$(printf '%s\n' "$body" | sed 's/{ARGS}/\$ARGUMENTS/g' | sed "s/__AGENT__/$agent_name/g" | rewrite_paths)
 
-    # Strip existing frontmatter and prepend Kimi frontmatter
+    # Strip existing frontmatter and prepend skills frontmatter.
     local template_body
     template_body=$(printf '%s\n' "$body" | awk '/^---/{p++; if(p==2){found=1; next}} found')
 
@@ -185,6 +208,10 @@ create_kimi_skills() {
       printf -- '---\n'
       printf 'name: "%s"\n' "$skill_name"
       printf 'description: "%s"\n' "$description"
+      printf 'compatibility: "%s"\n' "Requires spec-kit project structure with .specify/ directory"
+      printf -- 'metadata:\n'
+      printf '  author: "%s"\n' "github-spec-kit"
+      printf '  source: "%s"\n' "templates/commands/${name}.md"
       printf -- '---\n\n'
       printf '%s\n' "$template_body"
     } > "$skill_dir/SKILL.md"
@@ -218,7 +245,7 @@ build_variant() {
     esac
   fi
 
-  [[ -d templates ]] && { mkdir -p "$SPEC_DIR/templates"; find templates -type f -not -path "templates/commands/*" -not -name "vscode-settings.json" -exec cp --parents {} "$SPEC_DIR"/ \; ; echo "Copied templates -> .specify/templates"; }
+  [[ -d templates ]] && { mkdir -p "$SPEC_DIR/templates"; find templates -type f -not -path "templates/commands/*" -not -name "vscode-settings.json" | while IFS= read -r f; do d="$SPEC_DIR/$(dirname "$f")"; mkdir -p "$d"; cp "$f" "$d/"; done; echo "Copied templates -> .specify/templates"; }
 
   case $agent in
     claude)
@@ -248,9 +275,12 @@ build_variant() {
     windsurf)
       mkdir -p "$base_dir/.windsurf/workflows"
       generate_commands windsurf md "\$ARGUMENTS" "$base_dir/.windsurf/workflows" "$script" ;;
+    junie)
+      mkdir -p "$base_dir/.junie/commands"
+      generate_commands junie md "\$ARGUMENTS" "$base_dir/.junie/commands" "$script" ;;
     codex)
-      mkdir -p "$base_dir/.codex/prompts"
-      generate_commands codex md "\$ARGUMENTS" "$base_dir/.codex/prompts" "$script" ;;
+      mkdir -p "$base_dir/.agents/skills"
+      create_skills "$base_dir/.agents/skills" "$script" "codex" "-" ;;
     kilocode)
       mkdir -p "$base_dir/.kilocode/workflows"
       generate_commands kilocode md "\$ARGUMENTS" "$base_dir/.kilocode/workflows" "$script" ;;
@@ -290,7 +320,16 @@ build_variant() {
       generate_commands vibe md "\$ARGUMENTS" "$base_dir/.vibe/prompts" "$script" ;;
     kimi)
       mkdir -p "$base_dir/.kimi/skills"
-      create_kimi_skills "$base_dir/.kimi/skills" "$script" ;;
+      create_skills "$base_dir/.kimi/skills" "$script" "kimi" ;;
+    trae)
+      mkdir -p "$base_dir/.trae/rules"
+      generate_commands trae md "\$ARGUMENTS" "$base_dir/.trae/rules" "$script" ;;
+    pi)
+      mkdir -p "$base_dir/.pi/prompts"
+      generate_commands pi md "\$ARGUMENTS" "$base_dir/.pi/prompts" "$script" ;;
+    iflow)
+      mkdir -p "$base_dir/.iflow/commands"
+      generate_commands iflow md "\$ARGUMENTS" "$base_dir/.iflow/commands" "$script" ;;
     generic)
       mkdir -p "$base_dir/.speckit/commands"
       generate_commands generic md "\$ARGUMENTS" "$base_dir/.speckit/commands" "$script" ;;
@@ -300,37 +339,38 @@ build_variant() {
 }
 
 # Determine agent list
-ALL_AGENTS=(claude gemini copilot cursor-agent qwen opencode windsurf codex kilocode auggie roo codebuddy amp shai tabnine kiro-cli agy bob vibe qodercli kimi generic)
+ALL_AGENTS=(claude gemini copilot cursor-agent qwen opencode windsurf junie codex kilocode auggie roo codebuddy amp shai tabnine kiro-cli agy bob vibe qodercli kimi trae pi iflow generic)
 ALL_SCRIPTS=(sh ps)
 
-norm_list() {
-  tr ',\n' '  ' | awk '{for(i=1;i<=NF;i++){if(!seen[$i]++){printf((out?"\n":"") $i);out=1}}}END{printf("\n")}'
-}
-
 validate_subset() {
-  local type=$1; shift; local -n allowed=$1; shift; local items=("$@")
+  local type=$1; shift
+  local allowed_str="$1"; shift
   local invalid=0
-  for it in "${items[@]}"; do
+  for it in "$@"; do
     local found=0
-    for a in "${allowed[@]}"; do [[ $it == "$a" ]] && { found=1; break; }; done
+    for a in $allowed_str; do
+      if [[ "$it" == "$a" ]]; then found=1; break; fi
+    done
     if [[ $found -eq 0 ]]; then
-      echo "Error: unknown $type '$it' (allowed: ${allowed[*]})" >&2
+      echo "Error: unknown $type '$it' (allowed: $allowed_str)" >&2
       invalid=1
     fi
   done
   return $invalid
 }
 
+read_list() { tr ',\n' '  ' | awk '{for(i=1;i<=NF;i++){if(!seen[$i]++){printf((out?" ":"") $i);out=1}}}END{printf("\n")}'; }
+
 if [[ -n ${AGENTS:-} ]]; then
-  mapfile -t AGENT_LIST < <(printf '%s' "$AGENTS" | norm_list)
-  validate_subset agent ALL_AGENTS "${AGENT_LIST[@]}" || exit 1
+  read -ra AGENT_LIST <<< "$(printf '%s' "$AGENTS" | read_list)"
+  validate_subset agent "${ALL_AGENTS[*]}" "${AGENT_LIST[@]}" || exit 1
 else
   AGENT_LIST=("${ALL_AGENTS[@]}")
 fi
 
 if [[ -n ${SCRIPTS:-} ]]; then
-  mapfile -t SCRIPT_LIST < <(printf '%s' "$SCRIPTS" | norm_list)
-  validate_subset script ALL_SCRIPTS "${SCRIPT_LIST[@]}" || exit 1
+  read -ra SCRIPT_LIST <<< "$(printf '%s' "$SCRIPTS" | read_list)"
+  validate_subset script "${ALL_SCRIPTS[*]}" "${SCRIPT_LIST[@]}" || exit 1
 else
   SCRIPT_LIST=("${ALL_SCRIPTS[@]}")
 fi

.github/workflows/stale.yml

@@ -39,4 +39,4 @@ jobs:
           any-of-labels: ''
           
           # Operations per run (helps avoid rate limits)
-          operations-per-run: 100
+          operations-per-run: 250

.github/workflows/test.yml

@@ -16,7 +16,7 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
 
       - name: Set up Python
         uses: actions/setup-python@v6
@@ -36,7 +36,7 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
 
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v6

AGENTS.md

@@ -30,14 +30,15 @@ Specify supports multiple AI agents by generating agent-specific command files a
 | **Claude Code**            | `.claude/commands/`    | Markdown | `claude`        | Anthropic's Claude Code CLI |
 | **Gemini CLI**             | `.gemini/commands/`    | TOML     | `gemini`        | Google's Gemini CLI         |
 | **GitHub Copilot**         | `.github/agents/`      | Markdown | N/A (IDE-based) | GitHub Copilot in VS Code   |
-| **Cursor**                 | `.cursor/commands/`    | Markdown | `cursor-agent`  | Cursor CLI                  |
+| **Cursor**                 | `.cursor/commands/`    | Markdown | N/A (IDE-based) | Cursor IDE (`--ai cursor-agent`) |
 | **Qwen Code**              | `.qwen/commands/`      | Markdown | `qwen`          | Alibaba's Qwen Code CLI     |
 | **opencode**               | `.opencode/command/`   | Markdown | `opencode`      | opencode CLI                |
-| **Codex CLI**              | `.codex/commands/`     | Markdown | `codex`         | Codex CLI                   |
+| **Codex CLI**              | `.agents/skills/`      | Markdown | `codex`         | Codex CLI (`--ai codex --ai-skills`) |
 | **Windsurf**               | `.windsurf/workflows/` | Markdown | N/A (IDE-based) | Windsurf IDE workflows      |
-| **Kilo Code**              | `.kilocode/rules/`     | Markdown | N/A (IDE-based) | Kilo Code IDE               |
-| **Auggie CLI**             | `.augment/rules/`      | Markdown | `auggie`        | Auggie CLI                  |
-| **Roo Code**               | `.roo/rules/`          | Markdown | N/A (IDE-based) | Roo Code IDE                |
+| **Junie**                  | `.junie/commands/`     | Markdown | `junie`         | Junie by JetBrains          |
+| **Kilo Code**              | `.kilocode/workflows/` | Markdown | N/A (IDE-based) | Kilo Code IDE               |
+| **Auggie CLI**             | `.augment/commands/`   | Markdown | `auggie`        | Auggie CLI                  |
+| **Roo Code**               | `.roo/commands/`       | Markdown | N/A (IDE-based) | Roo Code IDE                |
 | **CodeBuddy CLI**          | `.codebuddy/commands/` | Markdown | `codebuddy`     | CodeBuddy CLI               |
 | **Qoder CLI**              | `.qoder/commands/`     | Markdown | `qodercli`      | Qoder CLI                   |
 | **Kiro CLI**               | `.kiro/prompts/`       | Markdown | `kiro-cli`      | Kiro CLI                    |
@@ -45,7 +46,12 @@ Specify supports multiple AI agents by generating agent-specific command files a
 | **SHAI**                   | `.shai/commands/`      | Markdown | `shai`          | SHAI CLI                    |
 | **Tabnine CLI**            | `.tabnine/agent/commands/` | TOML | `tabnine`       | Tabnine CLI                 |
 | **Kimi Code**              | `.kimi/skills/`        | Markdown | `kimi`          | Kimi Code CLI (Moonshot AI) |
+| **Pi Coding Agent**        | `.pi/prompts/`         | Markdown | `pi`            | Pi terminal coding agent    |
+| **iFlow CLI**              | `.iflow/commands/`     | Markdown | `iflow`         | iFlow CLI (iflow-ai)        |
 | **IBM Bob**                | `.bob/commands/`       | Markdown | N/A (IDE-based) | IBM Bob IDE                 |
+| **Trae**                   | `.trae/rules/`         | Markdown | N/A (IDE-based) | Trae IDE                    |
+| **Antigravity**            | `.agent/commands/`     | Markdown | N/A (IDE-based) | Antigravity IDE (`--ai agy --ai-skills`) |
+| **Mistral Vibe**           | `.vibe/prompts/`       | Markdown | `vibe`          | Mistral Vibe CLI            |
 | **Generic**                | User-specified via `--ai-commands-dir` | Markdown | N/A | Bring your own agent        |
 
 ### Step-by-Step Integration Guide
@@ -84,7 +90,7 @@ This eliminates the need for special-case mappings throughout the codebase.
 - `folder`: Directory where agent-specific files are stored (relative to project root)
 - `commands_subdir`: Subdirectory name within the agent folder where command/prompt files are stored (default: `"commands"`)
   - Most agents use `"commands"` (e.g., `.claude/commands/`)
-  - Some agents use alternative names: `"agents"` (copilot), `"workflows"` (windsurf, kilocode), `"prompts"` (codex, kiro-cli), `"command"` (opencode - singular)
+  - Some agents use alternative names: `"agents"` (copilot), `"workflows"` (windsurf, kilocode), `"prompts"` (codex, kiro-cli, pi), `"command"` (opencode - singular)
   - This field enables `--ai-skills` to locate command templates correctly for skill generation
 - `install_url`: Installation documentation URL (set to `None` for IDE-based agents)
 - `requires_cli`: Whether the agent requires a CLI tool check during initialization
@@ -312,30 +318,40 @@ Require a command-line tool to be installed:
 
 - **Claude Code**: `claude` CLI
 - **Gemini CLI**: `gemini` CLI
-- **Cursor**: `cursor-agent` CLI
 - **Qwen Code**: `qwen` CLI
 - **opencode**: `opencode` CLI
-- **Kiro CLI**: `kiro-cli` CLI
+- **Codex CLI**: `codex` CLI (requires `--ai-skills`)
+- **Junie**: `junie` CLI
+- **Auggie CLI**: `auggie` CLI
 - **CodeBuddy CLI**: `codebuddy` CLI
 - **Qoder CLI**: `qodercli` CLI
+- **Kiro CLI**: `kiro-cli` CLI
 - **Amp**: `amp` CLI
 - **SHAI**: `shai` CLI
 - **Tabnine CLI**: `tabnine` CLI
 - **Kimi Code**: `kimi` CLI
+- **Mistral Vibe**: `vibe` CLI
+- **Pi Coding Agent**: `pi` CLI
+- **iFlow CLI**: `iflow` CLI
 
 ### IDE-Based Agents
 
 Work within integrated development environments:
 
 - **GitHub Copilot**: Built into VS Code/compatible editors
+- **Cursor**: Built into Cursor IDE (`--ai cursor-agent`)
 - **Windsurf**: Built into Windsurf IDE
+- **Kilo Code**: Built into Kilo Code IDE
+- **Roo Code**: Built into Roo Code IDE
 - **IBM Bob**: Built into IBM Bob IDE
+- **Trae**: Built into Trae IDE
+- **Antigravity**: Built into Antigravity IDE (`--ai agy --ai-skills`)
 
 ## Command File Formats
 
 ### Markdown Format
 
-Used by: Claude, Cursor, opencode, Windsurf, Kiro CLI, Amp, SHAI, IBM Bob, Kimi Code, Qwen
+Used by: Claude, Cursor, GitHub Copilot, opencode, Windsurf, Junie, Kiro CLI, Amp, SHAI, IBM Bob, Kimi Code, Qwen, Pi, Codex, Auggie, CodeBuddy, Qoder, Roo Code, Kilo Code, Trae, Antigravity, Mistral Vibe, iFlow
 
 **Standard format:**
 
@@ -373,10 +389,29 @@ Command content with {SCRIPT} and {{args}} placeholders.
 ## Directory Conventions
 
 - **CLI agents**: Usually `.<agent-name>/commands/`
+- **Singular command exception**:
+  - opencode: `.opencode/command/` (singular `command`, not `commands`)
+- **Nested path exception**:
+  - Tabnine: `.tabnine/agent/commands/` (extra `agent/` segment)
+- **Shared `.agents/` folder**:
+  - Amp: `.agents/commands/` (shared folder, not `.amp/`)
+  - Codex: `.agents/skills/` (shared folder; requires `--ai-skills`; invoked as `$speckit-<command>`)
+- **Skills-based exceptions**:
+  - Kimi Code: `.kimi/skills/` (skills, invoked as `/skill:speckit-<command>`)
+- **Prompt-based exceptions**:
+  - Kiro CLI: `.kiro/prompts/`
+  - Pi: `.pi/prompts/`
+  - Mistral Vibe: `.vibe/prompts/`
+- **Rules-based exceptions**:
+  - Trae: `.trae/rules/`
 - **IDE agents**: Follow IDE-specific patterns:
   - Copilot: `.github/agents/`
   - Cursor: `.cursor/commands/`
   - Windsurf: `.windsurf/workflows/`
+  - Kilo Code: `.kilocode/workflows/`
+  - Roo Code: `.roo/commands/`
+  - IBM Bob: `.bob/commands/`
+  - Antigravity: `.agent/skills/` (`--ai-skills` required; `.agent/commands/` is deprecated)
 
 ## Argument Patterns
 

CONTRIBUTING.md

@@ -36,7 +36,7 @@ On [GitHub Codespaces](https://github.com/features/codespaces) it's even simpler
 > If your pull request introduces a large change that materially impacts the work of the CLI or the rest of the repository (e.g., you're introducing new templates, arguments, or otherwise major changes), make sure that it was **discussed and agreed upon** by the project maintainers. Pull requests with large changes that did not have a prior conversation and agreement will be closed.
 
 1. Fork and clone the repository
-1. Configure and install the dependencies: `uv sync`
+1. Configure and install the dependencies: `uv sync --extra test`
 1. Make sure the CLI works on your machine: `uv run specify --help`
 1. Create a new branch: `git checkout -b my-branch-name`
 1. Make your change, add tests, and make sure everything still works
@@ -44,6 +44,9 @@ On [GitHub Codespaces](https://github.com/features/codespaces) it's even simpler
 1. Push to your fork and submit a pull request
 1. Wait for your pull request to be reviewed and merged.
 
+For the detailed test workflow, command-selection prompt, and PR reporting template, see [`TESTING.md`](./TESTING.md).
+Activate the project virtual environment (see the Setup block in [`TESTING.md`](./TESTING.md)), then install the CLI from your working tree (`uv pip install -e .` after `uv sync --extra test`) or otherwise ensure the shell uses the local `specify` binary before running the manual slash-command tests described below.
+
 Here are a few things you can do that will increase the likelihood of your pull request being accepted:
 
 - Follow the project's coding conventions.
@@ -62,6 +65,14 @@ When working on spec-kit:
 3. Test script functionality in the `scripts/` directory
 4. Ensure memory files (`memory/constitution.md`) are updated if major process changes are made
 
+### Recommended validation flow
+
+For the smoothest review experience, validate changes in this order:
+
+1. **Run focused automated checks first** — use the quick verification commands in [`TESTING.md`](./TESTING.md) to catch packaging, scaffolding, and configuration regressions early.
+2. **Run manual workflow tests second** — if your change affects slash commands or the developer workflow, follow [`TESTING.md`](./TESTING.md) to choose the right commands, run them in an agent, and capture results for your PR.
+3. **Use local release packages when debugging packaged output** — if you need to inspect the exact files CI-style packaging produces, generate local release packages as described below.
+
 ### Testing template and command changes locally
 
 Running `uv run specify init` pulls released packages, which won’t include your local changes.  
@@ -85,6 +96,8 @@ To test your templates, commands, and other changes locally, follow these steps:
 
    Navigate to your test project folder and open the agent to verify your implementation.
 
+If you only need to validate generated file structure and content before doing manual agent testing, start with the focused automated checks in [`TESTING.md`](./TESTING.md). Keep this section for the cases where you need to inspect the exact packaged output locally.
+
 ## AI contributions in Spec Kit
 
 > [!IMPORTANT]

README.md

@@ -9,7 +9,7 @@
 </p>
 
 <p align="center">
-    <a href="https://github.com/github/spec-kit/actions/workflows/release.yml"><img src="https://github.com/github/spec-kit/actions/workflows/release.yml/badge.svg" alt="Release"/></a>
+    <a href="https://github.com/github/spec-kit/releases/latest"><img src="https://img.shields.io/github/v/release/github/spec-kit" alt="Latest Release"/></a>
     <a href="https://github.com/github/spec-kit/stargazers"><img src="https://img.shields.io/github/stars/github/spec-kit?style=social" alt="GitHub stars"/></a>
     <a href="https://github.com/github/spec-kit/blob/main/LICENSE"><img src="https://img.shields.io/github/license/github/spec-kit" alt="License"/></a>
     <a href="https://github.github.io/spec-kit/"><img src="https://img.shields.io/badge/docs-GitHub_Pages-blue" alt="Documentation"/></a>
@@ -22,9 +22,13 @@
 - [🤔 What is Spec-Driven Development?](#-what-is-spec-driven-development)
 - [⚡ Get Started](#-get-started)
 - [📽️ Video Overview](#️-video-overview)
+- [🧩 Community Extensions](#-community-extensions)
+- [🎨 Community Presets](#-community-presets)
 - [🚶 Community Walkthroughs](#-community-walkthroughs)
+- [🛠️ Community Friends](#️-community-friends)
 - [🤖 Supported AI Agents](#-supported-ai-agents)
 - [🔧 Specify CLI Reference](#-specify-cli-reference)
+- [🧩 Making Spec Kit Your Own: Extensions & Presets](#-making-spec-kit-your-own-extensions--presets)
 - [📚 Core Philosophy](#-core-philosophy)
 - [🌟 Development Phases](#-development-phases)
 - [🎯 Experimental Goals](#-experimental-goals)
@@ -48,9 +52,13 @@ Choose your preferred installation method:
 
 #### Option 1: Persistent Installation (Recommended)
 
-Install once and use everywhere:
+Install once and use everywhere. Pin a specific release tag for stability (check [Releases](https://github.com/github/spec-kit/releases) for the latest):
 
 ```bash
+# Install a specific stable release (recommended — replace vX.Y.Z with the latest tag)
+uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z
+
+# Or install latest from main (may include unreleased changes)
 uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
 ```
 
@@ -72,7 +80,7 @@ specify check
 To upgrade Specify, see the [Upgrade Guide](./docs/upgrade.md) for detailed instructions. Quick upgrade:
 
 ```bash
-uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git
+uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git@vX.Y.Z
 ```
 
 #### Option 2: One-time Usage
@@ -80,13 +88,13 @@ uv tool install specify-cli --force --from git+https://github.com/github/spec-ki
 Run directly without installing:
 
 ```bash
-# Create new project
-uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>
+# Create new project (pinned to a stable release — replace vX.Y.Z with the latest tag)
+uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <PROJECT_NAME>
 
 # Or initialize in existing project
-uvx --from git+https://github.com/github/spec-kit.git specify init . --ai claude
+uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init . --ai claude
 # or
-uvx --from git+https://github.com/github/spec-kit.git specify init --here --ai claude
+uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --here --ai claude
 ```
 
 **Benefits of persistent installation:**
@@ -96,9 +104,13 @@ uvx --from git+https://github.com/github/spec-kit.git specify init --here --ai c
 - Better tool management with `uv tool list`, `uv tool upgrade`, `uv tool uninstall`
 - Cleaner shell configuration
 
+#### Option 3: Enterprise / Air-Gapped Installation
+
+If your environment blocks access to PyPI or GitHub, see the [Enterprise / Air-Gapped Installation](./docs/installation.md#enterprise--air-gapped-installation) guide for step-by-step instructions on using `pip download` to create portable, OS-specific wheel bundles on a connected machine.
+
 ### 2. Establish project principles
 
-Launch your AI assistant in the project directory. The `/speckit.*` commands are available in the assistant.
+Launch your AI assistant in the project directory. Most agents expose spec-kit as `/speckit.*` slash commands; Codex CLI in skills mode uses `$speckit-*` instead.
 
 Use the **`/speckit.constitution`** command to create your project's governing principles and development guidelines that will guide all subsequent development.
 
@@ -146,6 +158,76 @@ Want to see Spec Kit in action? Watch our [video overview](https://www.youtube.c
 
 [![Spec Kit video header](/media/spec-kit-video-header.jpg)](https://www.youtube.com/watch?v=a9eR1xsfvHg&pp=0gcJCckJAYcqIYzv)
 
+## 🧩 Community Extensions
+
+The following community-contributed extensions are available in [`catalog.community.json`](extensions/catalog.community.json):
+
+**Categories:**
+
+- `docs` — reads, validates, or generates spec artifacts
+- `code` — reviews, validates, or modifies source code
+- `process` — orchestrates workflow across phases
+- `integration` — syncs with external platforms
+- `visibility` — reports on project health or progress
+
+**Effect:**
+
+- `Read-only` — produces reports without modifying files
+- `Read+Write` — modifies files, creates artifacts, or updates specs
+
+| Extension | Purpose | Category | Effect | URL |
+|-----------|---------|----------|--------|-----|
+| AI-Driven Engineering (AIDE) | A structured 7-step workflow for building new projects from scratch with AI assistants — from vision through implementation | `process` | Read+Write | [aide](https://github.com/mnriem/spec-kit-extensions/tree/main/aide) |
+| Archive Extension | Archive merged features into main project memory. | `docs` | Read+Write | [spec-kit-archive](https://github.com/stn1slv/spec-kit-archive) |
+| Azure DevOps Integration | Sync user stories and tasks to Azure DevOps work items using OAuth authentication | `integration` | Read+Write | [spec-kit-azure-devops](https://github.com/pragya247/spec-kit-azure-devops) |
+| Checkpoint Extension | Commit the changes made during the middle of the implementation, so you don't end up with just one very large commit at the end | `code` | Read+Write | [spec-kit-checkpoint](https://github.com/aaronrsun/spec-kit-checkpoint) |
+| Cleanup Extension | Post-implementation quality gate that reviews changes, fixes small issues (scout rule), creates tasks for medium issues, and generates analysis for large issues | `code` | Read+Write | [spec-kit-cleanup](https://github.com/dsrednicki/spec-kit-cleanup) |
+| Cognitive Squad | Multi-agent cognitive system with Triadic Model: understanding, internalization, application — with quality gates, backpropagation verification, and self-healing | `docs` | Read+Write | [cognitive-squad](https://github.com/Testimonial/cognitive-squad) |
+| Conduct Extension | Orchestrates spec-kit phases via sub-agent delegation to reduce context pollution. | `process` | Read+Write | [spec-kit-conduct-ext](https://github.com/twbrandon7/spec-kit-conduct-ext) |
+| DocGuard — CDD Enforcement | Canonical-Driven Development enforcement. Validates, scores, and traces project documentation with automated checks, AI-driven workflows, and spec-kit hooks. Zero NPM runtime dependencies. | `docs` | Read+Write | [spec-kit-docguard](https://github.com/raccioly/docguard) |
+| Extensify | Create and validate extensions and extension catalogs | `process` | Read+Write | [extensify](https://github.com/mnriem/spec-kit-extensions/tree/main/extensify) |
+| Fleet Orchestrator | Orchestrate a full feature lifecycle with human-in-the-loop gates across all SpecKit phases | `process` | Read+Write | [spec-kit-fleet](https://github.com/sharathsatish/spec-kit-fleet) |
+| Iterate | Iterate on spec documents with a two-phase define-and-apply workflow — refine specs mid-implementation and go straight back to building | `docs` | Read+Write | [spec-kit-iterate](https://github.com/imviancagrace/spec-kit-iterate) |
+| Jira Integration | Create Jira Epics, Stories, and Issues from spec-kit specifications and task breakdowns with configurable hierarchy and custom field support | `integration` | Read+Write | [spec-kit-jira](https://github.com/mbachorik/spec-kit-jira) |
+| Learning Extension | Generate educational guides from implementations and enhance clarifications with mentoring context | `docs` | Read+Write | [spec-kit-learn](https://github.com/imviancagrace/spec-kit-learn) |
+| MAQA — Multi-Agent & Quality Assurance | Coordinator → feature → QA agent workflow with parallel worktree-based implementation. Language-agnostic. Auto-detects installed board plugins. Optional CI gate. | `process` | Read+Write | [spec-kit-maqa-ext](https://github.com/GenieRobot/spec-kit-maqa-ext) |
+| MAQA Azure DevOps Integration | Azure DevOps Boards integration for MAQA — syncs User Stories and Task children as features progress | `integration` | Read+Write | [spec-kit-maqa-azure-devops](https://github.com/GenieRobot/spec-kit-maqa-azure-devops) |
+| MAQA CI/CD Gate | Auto-detects GitHub Actions, CircleCI, GitLab CI, and Bitbucket Pipelines. Blocks QA handoff until pipeline is green. | `process` | Read+Write | [spec-kit-maqa-ci](https://github.com/GenieRobot/spec-kit-maqa-ci) |
+| MAQA GitHub Projects Integration | GitHub Projects v2 integration for MAQA — syncs draft issues and Status columns as features progress | `integration` | Read+Write | [spec-kit-maqa-github-projects](https://github.com/GenieRobot/spec-kit-maqa-github-projects) |
+| MAQA Jira Integration | Jira integration for MAQA — syncs Stories and Subtasks as features progress through the board | `integration` | Read+Write | [spec-kit-maqa-jira](https://github.com/GenieRobot/spec-kit-maqa-jira) |
+| MAQA Linear Integration | Linear integration for MAQA — syncs issues and sub-issues across workflow states as features progress | `integration` | Read+Write | [spec-kit-maqa-linear](https://github.com/GenieRobot/spec-kit-maqa-linear) |
+| MAQA Trello Integration | Trello board integration for MAQA — populates board from specs, moves cards, real-time checklist ticking | `integration` | Read+Write | [spec-kit-maqa-trello](https://github.com/GenieRobot/spec-kit-maqa-trello) |
+| Onboard | Contextual onboarding and progressive growth for developers new to spec-kit projects. Explains specs, maps dependencies, validates understanding, and guides the next step | `process` | Read+Write | [spec-kit-onboard](https://github.com/dmux/spec-kit-onboard) |
+| Plan Review Gate | Require spec.md and plan.md to be merged via MR/PR before allowing task generation | `process` | Read-only | [spec-kit-plan-review-gate](https://github.com/luno/spec-kit-plan-review-gate) |
+| Presetify | Create and validate presets and preset catalogs | `process` | Read+Write | [presetify](https://github.com/mnriem/spec-kit-extensions/tree/main/presetify) |
+| Product Forge | Full product lifecycle: research → product spec → SpecKit → implement → verify → test | `process` | Read+Write | [speckit-product-forge](https://github.com/VaiYav/speckit-product-forge) |
+| Project Health Check | Diagnose a Spec Kit project and report health issues across structure, agents, features, scripts, extensions, and git | `visibility` | Read-only | [spec-kit-doctor](https://github.com/KhawarHabibKhan/spec-kit-doctor) |
+| Project Status | Show current SDD workflow progress — active feature, artifact status, task completion, workflow phase, and extensions summary | `visibility` | Read-only | [spec-kit-status](https://github.com/KhawarHabibKhan/spec-kit-status) |
+| Ralph Loop | Autonomous implementation loop using AI agent CLI | `code` | Read+Write | [spec-kit-ralph](https://github.com/Rubiss/spec-kit-ralph) |
+| Reconcile Extension | Reconcile implementation drift by surgically updating feature artifacts. | `docs` | Read+Write | [spec-kit-reconcile](https://github.com/stn1slv/spec-kit-reconcile) |
+| Retrospective Extension | Post-implementation retrospective with spec adherence scoring, drift analysis, and human-gated spec updates | `docs` | Read+Write | [spec-kit-retrospective](https://github.com/emi-dm/spec-kit-retrospective) |
+| Review Extension | Post-implementation comprehensive code review with specialized agents for code quality, comments, tests, error handling, type design, and simplification | `code` | Read-only | [spec-kit-review](https://github.com/ismaelJimenez/spec-kit-review) |
+| SDD Utilities | Resume interrupted workflows, validate project health, and verify spec-to-task traceability | `process` | Read+Write | [speckit-utils](https://github.com/mvanhorn/speckit-utils) |
+| Superpowers Bridge | Orchestrates obra/superpowers skills within the spec-kit SDD workflow across the full lifecycle (clarification, TDD, review, verification, critique, debugging, branch completion) | `process` | Read+Write | [superpowers-bridge](https://github.com/RbBtSn0w/spec-kit-extensions/tree/main/superpowers-bridge) |
+| Spec Sync | Detect and resolve drift between specs and implementation. AI-assisted resolution with human approval | `docs` | Read+Write | [spec-kit-sync](https://github.com/bgervin/spec-kit-sync) |
+| Understanding | Automated requirements quality analysis — 31 deterministic metrics against IEEE/ISO standards with experimental energy-based ambiguity detection | `docs` | Read-only | [understanding](https://github.com/Testimonial/understanding) |
+| V-Model Extension Pack | Enforces V-Model paired generation of development specs and test specs with full traceability | `docs` | Read+Write | [spec-kit-v-model](https://github.com/leocamello/spec-kit-v-model) |
+| Verify Extension | Post-implementation quality gate that validates implemented code against specification artifacts | `code` | Read-only | [spec-kit-verify](https://github.com/ismaelJimenez/spec-kit-verify) |
+| Verify Tasks Extension | Detect phantom completions: tasks marked [X] in tasks.md with no real implementation | `code` | Read-only | [spec-kit-verify-tasks](https://github.com/datastone-inc/spec-kit-verify-tasks) |
+
+To submit your own extension, see the [Extension Publishing Guide](extensions/EXTENSION-PUBLISHING-GUIDE.md).
+
+## 🎨 Community Presets
+
+The following community-contributed presets customize how Spec Kit behaves — overriding templates, commands, and terminology without changing any tooling. Presets are available in [`catalog.community.json`](presets/catalog.community.json):
+
+| Preset | Purpose | Provides | Requires | URL |
+|--------|---------|----------|----------|-----|
+| AIDE In-Place Migration | Adapts the AIDE extension workflow for in-place technology migrations (X → Y pattern) — adds migration objectives, verification gates, knowledge documents, and behavioral equivalence criteria | 2 templates, 8 commands | AIDE extension | [spec-kit-presets](https://github.com/mnriem/spec-kit-presets) |
+| Pirate Speak (Full) | Transforms all Spec Kit output into pirate speak — specs become "Voyage Manifests", plans become "Battle Plans", tasks become "Crew Assignments" | 6 templates, 9 commands | — | [spec-kit-presets](https://github.com/mnriem/spec-kit-presets) |
+
+To build and publish your own preset, see the [Presets Publishing Guide](presets/PUBLISHING.md).
+
 ## 🚶 Community Walkthroughs
 
 See Spec-Driven Development in action across different scenarios with these community-contributed walkthroughs:
@@ -160,6 +242,18 @@ See Spec-Driven Development in action across different scenarios with these comm
 
 - **[Brownfield Go / React dashboard demo](https://github.com/mnriem/spec-kit-go-brownfield-demo)** — Demonstrates spec-kit driven entirely from the **terminal using GitHub Copilot CLI**. Extends NASA's open-source Hermes ground support system (Go) with a lightweight React-based web telemetry dashboard, showing that the full constitution → specify → plan → tasks → implement workflow works from the terminal.
 
+- **[Greenfield Spring Boot MVC with a custom preset](https://github.com/mnriem/spec-kit-pirate-speak-preset-demo)** — Builds a Spring Boot MVC application from scratch using a custom pirate-speak preset, demonstrating how presets can reshape the entire spec-kit experience: specifications become "Voyage Manifests," plans become "Battle Plans," and tasks become "Crew Assignments" — all generated in full pirate vernacular without changing any tooling.
+
+- **[Greenfield Spring Boot + React with a custom extension](https://github.com/mnriem/spec-kit-aide-extension-demo)** — Walks through the **AIDE extension**, a community extension that adds an alternative spec-driven workflow to spec-kit with high-level specs (vision) and low-level specs (work items) organized in a 7-step iterative lifecycle: vision → roadmap → progress tracking → work queue → work items → execution → feedback loops. Uses a family trading platform (Spring Boot 4, React 19, PostgreSQL, Docker Compose) as the scenario to illustrate how the extension mechanism lets you plug in a different style of spec-driven development without changing any core tooling — truly utilizing the "Kit" in Spec Kit.
+
+## 🛠️ Community Friends
+
+Community projects that extend, visualize, or build on Spec Kit:
+
+- **[cc-sdd](https://github.com/rhuss/cc-sdd)** - A Claude Code plugin that adds composable traits on top of Spec Kit with [Superpowers](https://github.com/obra/superpowers)-based quality gates, spec/code review, git worktree isolation, and parallel implementation via agent teams.
+
+- **[Spec Kit Assistant](https://marketplace.visualstudio.com/items?itemName=rfsales.speckit-assistant)** — A VS Code extension that provides a visual orchestrator for the full SDD workflow (constitution → specification → planning → tasks → implementation) with phase status visualization, an interactive task checklist, DAG visualization, and support for Claude, Gemini, GitHub Copilot, and OpenAI backends. Requires the `specify` CLI in your PATH.
+
 ## 🤖 Supported AI Agents
 
 | Agent                                                                                | Support | Notes                                                                                                                                     |
@@ -170,7 +264,7 @@ See Spec-Driven Development in action across different scenarios with these comm
 | [Auggie CLI](https://docs.augmentcode.com/cli/overview)                              | ✅      |                                                                                                                                           |
 | [Claude Code](https://www.anthropic.com/claude-code)                                 | ✅      |                                                                                                                                           |
 | [CodeBuddy CLI](https://www.codebuddy.ai/cli)                                        | ✅      |                                                                                                                                           |
-| [Codex CLI](https://github.com/openai/codex)                                         | ✅      |                                                                                                                                           |
+| [Codex CLI](https://github.com/openai/codex)                                         | ✅      | Requires `--ai-skills`. Codex recommends [skills](https://developers.openai.com/codex/skills) and treats [custom prompts](https://developers.openai.com/codex/custom-prompts) as deprecated. Spec-kit installs Codex skills into `.agents/skills` and invokes them as `$speckit-<command>`. |
 | [Cursor](https://cursor.sh/)                                                         | ✅      |                                                                                                                                           |
 | [Gemini CLI](https://github.com/google-gemini/gemini-cli)                            | ✅      |                                                                                                                                           |
 | [GitHub Copilot](https://code.visualstudio.com/)                                     | ✅      |                                                                                                                                           |
@@ -178,14 +272,18 @@ See Spec-Driven Development in action across different scenarios with these comm
 | [Jules](https://jules.google.com/)                                                   | ✅      |                                                                                                                                           |
 | [Kilo Code](https://github.com/Kilo-Org/kilocode)                                    | ✅      |                                                                                                                                           |
 | [opencode](https://opencode.ai/)                                                     | ✅      |                                                                                                                                           |
+| [Pi Coding Agent](https://pi.dev)                                                    | ✅      | Pi doesn't have MCP support out of the box, so `taskstoissues` won't work as intended. MCP support can be added via [extensions](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent#extensions) |
 | [Qwen Code](https://github.com/QwenLM/qwen-code)                                     | ✅      |                                                                                                                                           |
 | [Roo Code](https://roocode.com/)                                                     | ✅      |                                                                                                                                           |
 | [SHAI (OVHcloud)](https://github.com/ovh/shai)                                       | ✅      |                                                                                                                                           |
 | [Tabnine CLI](https://docs.tabnine.com/main/getting-started/tabnine-cli)             | ✅      |                                                                                                                                           |
 | [Mistral Vibe](https://github.com/mistralai/mistral-vibe)                            | ✅      |                                                                                                                                           |
 | [Kimi Code](https://code.kimi.com/)                                                  | ✅      |                                                                                                                                           |
+| [iFlow CLI](https://docs.iflow.cn/en/cli/quickstart)                                 | ✅      |                                                                                                                                           |
 | [Windsurf](https://windsurf.com/)                                                    | ✅      |                                                                                                                                           |
+| [Junie](https://junie.jetbrains.com/)                                                | ✅      |                                                                                                                                           |
 | [Antigravity (agy)](https://antigravity.google/)                                     | ✅      | Requires `--ai-skills` |
+| [Trae](https://www.trae.ai/)                                                         | ✅      |                                                                                                                                           |
 | Generic                                                                              | ✅      | Bring your own agent — use `--ai generic --ai-commands-dir <path>` for unsupported agents                                                 |
 
 ## 🔧 Specify CLI Reference
@@ -194,27 +292,28 @@ The `specify` command supports the following options:
 
 ### Commands
 
-| Command | Description                                                                                                                                             |
-| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `init`  | Initialize a new Specify project from the latest template                                                                                               |
-| `check` | Check for installed tools (`git`, `claude`, `gemini`, `code`/`code-insiders`, `cursor-agent`, `windsurf`, `qwen`, `opencode`, `codex`, `kiro-cli`, `shai`, `qodercli`, `vibe`, `kimi`) |
+| Command | Description                                                                                                                                                                                                                                                                              |
+| ------- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `init`  | Initialize a new Specify project from the latest template                                                                                                                                                                                                                                |
+| `check` | Check for installed tools: `git` plus all CLI-based agents configured in `AGENT_CONFIG` (for example: `claude`, `gemini`, `code`/`code-insiders`, `cursor-agent`, `windsurf`, `junie`, `qwen`, `opencode`, `codex`, `kiro-cli`, `shai`, `qodercli`, `vibe`, `kimi`, `iflow`, `pi`, etc.) |
 
 ### `specify init` Arguments & Options
 
-| Argument/Option        | Type     | Description                                                                                                                                                                                  |
-| ---------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `<project-name>`       | Argument | Name for your new project directory (optional if using `--here`, or use `.` for current directory)                                                                                           |
-| `--ai`                 | Option   | AI assistant to use: `claude`, `gemini`, `copilot`, `cursor-agent`, `qwen`, `opencode`, `codex`, `windsurf`, `kilocode`, `auggie`, `roo`, `codebuddy`, `amp`, `shai`, `kiro-cli` (`kiro` alias), `agy`, `bob`, `qodercli`, `vibe`, `kimi`, or `generic` (requires `--ai-commands-dir`) |
-| `--ai-commands-dir`    | Option   | Directory for agent command files (required with `--ai generic`, e.g. `.myagent/commands/`)                                                                                                  |
-| `--script`             | Option   | Script variant to use: `sh` (bash/zsh) or `ps` (PowerShell)                                                                                                                                  |
-| `--ignore-agent-tools` | Flag     | Skip checks for AI agent tools like Claude Code                                                                                                                                              |
-| `--no-git`             | Flag     | Skip git repository initialization                                                                                                                                                           |
-| `--here`               | Flag     | Initialize project in the current directory instead of creating a new one                                                                                                                    |
-| `--force`              | Flag     | Force merge/overwrite when initializing in current directory (skip confirmation)                                                                                                             |
-| `--skip-tls`           | Flag     | Skip SSL/TLS verification (not recommended)                                                                                                                                                  |
-| `--debug`              | Flag     | Enable detailed debug output for troubleshooting                                                                                                                                             |
-| `--github-token`       | Option   | GitHub token for API requests (or set GH_TOKEN/GITHUB_TOKEN env variable)                                                                                                                    |
-| `--ai-skills`          | Flag     | Install Prompt.MD templates as agent skills in agent-specific `skills/` directory (requires `--ai`)                                                                                          |
+| Argument/Option        | Type     | Description                                                                                                                                                                                                                                                                                                                                                                               |
+| ---------------------- | -------- |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `<project-name>`       | Argument | Name for your new project directory (optional if using `--here`, or use `.` for current directory)                                                                                                                                                                                                                                                                                        |
+| `--ai`                 | Option   | AI assistant to use (see `AGENT_CONFIG` for the full, up-to-date list). Common options include: `claude`, `gemini`, `copilot`, `cursor-agent`, `qwen`, `opencode`, `codex`, `windsurf`, `junie`, `kilocode`, `auggie`, `roo`, `codebuddy`, `amp`, `shai`, `kiro-cli` (`kiro` alias), `agy`, `bob`, `qodercli`, `vibe`, `kimi`, `iflow`, `pi`, or `generic` (requires `--ai-commands-dir`) |
+| `--ai-commands-dir`    | Option   | Directory for agent command files (required with `--ai generic`, e.g. `.myagent/commands/`)                                                                                                                                                                                                                                                                                               |
+| `--script`             | Option   | Script variant to use: `sh` (bash/zsh) or `ps` (PowerShell)                                                                                                                                                                                                                                                                                                                               |
+| `--ignore-agent-tools` | Flag     | Skip checks for AI agent tools like Claude Code                                                                                                                                                                                                                                                                                                                                           |
+| `--no-git`             | Flag     | Skip git repository initialization                                                                                                                                                                                                                                                                                                                                                        |
+| `--here`               | Flag     | Initialize project in the current directory instead of creating a new one                                                                                                                                                                                                                                                                                                                 |
+| `--force`              | Flag     | Force merge/overwrite when initializing in current directory (skip confirmation)                                                                                                                                                                                                                                                                                                          |
+| `--skip-tls`           | Flag     | Skip SSL/TLS verification (not recommended)                                                                                                                                                                                                                                                                                                                                               |
+| `--debug`              | Flag     | Enable detailed debug output for troubleshooting                                                                                                                                                                                                                                                                                                                                          |
+| `--github-token`       | Option   | GitHub token for API requests (or set GH_TOKEN/GITHUB_TOKEN env variable)                                                                                                                                                                                                                                                                                                                 |
+| `--ai-skills`          | Flag     | Install Prompt.MD templates as agent skills in agent-specific `skills/` directory (requires `--ai`). Extension commands are also auto-registered as skills when extensions are added later.                                                                                                                                                                                               |
+| `--branch-numbering`   | Option   | Branch numbering strategy: `sequential` (default — `001`, `002`, `003`) or `timestamp` (`YYYYMMDD-HHMMSS`). Timestamp mode is useful for distributed teams to avoid numbering conflicts                                                                                                                                                                                                  |
 
 ### Examples
 
@@ -249,6 +348,12 @@ specify init my-project --ai vibe
 # Initialize with IBM Bob support
 specify init my-project --ai bob
 
+# Initialize with Pi Coding Agent support
+specify init my-project --ai pi
+
+# Initialize with Codex CLI support
+specify init my-project --ai codex --ai-skills
+
 # Initialize with Antigravity support
 specify init my-project --ai agy --ai-skills
 
@@ -283,13 +388,18 @@ specify init my-project --ai claude --ai-skills
 # Initialize in current directory with agent skills
 specify init --here --ai gemini --ai-skills
 
+# Use timestamp-based branch numbering (useful for distributed teams)
+specify init my-project --ai claude --branch-numbering timestamp
+
 # Check system requirements
 specify check
 ```
 
 ### Available Slash Commands
 
-After running `specify init`, your AI coding agent will have access to these slash commands for structured development:
+After running `specify init`, your AI coding agent will have access to these slash commands for structured development.
+
+For Codex CLI, `--ai-skills` installs spec-kit as agent skills instead of slash-command prompt files. In Codex skills mode, invoke spec-kit as `$speckit-constitution`, `$speckit-specify`, `$speckit-plan`, `$speckit-tasks`, and `$speckit-implement`.
 
 #### Core Commands
 
@@ -319,6 +429,68 @@ Additional commands for enhanced quality and validation:
 | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `SPECIFY_FEATURE` | Override feature detection for non-Git repositories. Set to the feature directory name (e.g., `001-photo-albums`) to work on a specific feature when not using Git branches.<br/>\*\*Must be set in the context of the agent you're working with prior to using `/speckit.plan` or follow-up commands. |
 
+## 🧩 Making Spec Kit Your Own: Extensions & Presets
+
+Spec Kit can be tailored to your needs through two complementary systems — **extensions** and **presets** — plus project-local overrides for one-off adjustments:
+
+```mermaid
+block-beta
+    columns 1
+    overrides["⬆ Highest priority\nProject-Local Overrides\n.specify/templates/overrides/"]
+    presets["Presets — Customize core & extensions\n.specify/presets/<preset-id>/templates/"]
+    extensions["Extensions — Add new capabilities\n.specify/extensions/<ext-id>/templates/"]
+    core["Spec Kit Core — Built-in SDD commands & templates\n.specify/templates/\n⬇ Lowest priority"]
+
+    style overrides fill:transparent,stroke:#999
+    style presets fill:transparent,stroke:#4a9eda
+    style extensions fill:transparent,stroke:#4a9e4a
+    style core fill:transparent,stroke:#e6a817
+```
+
+**Templates** are resolved at **runtime** — Spec Kit walks the stack top-down and uses the first match. Project-local overrides (`.specify/templates/overrides/`) let you make one-off adjustments for a single project without creating a full preset. **Commands** are applied at **install time** — when you run `specify extension add` or `specify preset add`, command files are written into agent directories (e.g., `.claude/commands/`). If multiple presets or extensions provide the same command, the highest-priority version wins. On removal, the next-highest-priority version is restored automatically. If no overrides or customizations exist, Spec Kit uses its core defaults.
+
+### Extensions — Add New Capabilities
+
+Use **extensions** when you need functionality that goes beyond Spec Kit's core. Extensions introduce new commands and templates — for example, adding domain-specific workflows that are not covered by the built-in SDD commands, integrating with external tools, or adding entirely new development phases. They expand *what Spec Kit can do*.
+
+```bash
+# Search available extensions
+specify extension search
+
+# Install an extension
+specify extension add <extension-name>
+```
+
+For example, extensions could add Jira integration, post-implementation code review, V-Model test traceability, or project health diagnostics.
+
+See the [Extensions README](./extensions/README.md) for the full guide and how to build and publish your own. Browse the [community extensions](#-community-extensions) above for what's available.
+
+### Presets — Customize Existing Workflows
+
+Use **presets** when you want to change *how* Spec Kit works without adding new capabilities. Presets override the templates and commands that ship with the core *and* with installed extensions — for example, enforcing a compliance-oriented spec format, using domain-specific terminology, or applying organizational standards to plans and tasks. They customize the artifacts and instructions that Spec Kit and its extensions produce.
+
+```bash
+# Search available presets
+specify preset search
+
+# Install a preset
+specify preset add <preset-name>
+```
+
+For example, presets could restructure spec templates to require regulatory traceability, adapt the workflow to fit the methodology you use (e.g., Agile, Kanban, Waterfall, jobs-to-be-done, or domain-driven design), add mandatory security review gates to plans, enforce test-first task ordering, or localize the entire workflow to a different language. The [pirate-speak demo](https://github.com/mnriem/spec-kit-pirate-speak-preset-demo) shows just how deep the customization can go. Multiple presets can be stacked with priority ordering.
+
+See the [Presets README](./presets/README.md) for the full guide, including resolution order, priority, and how to create your own.
+
+### When to Use Which
+
+| Goal | Use |
+| --- | --- |
+| Add a brand-new command or workflow | Extension |
+| Customize the format of specs, plans, or tasks | Preset |
+| Integrate an external tool or service | Extension |
+| Enforce organizational or regulatory standards | Preset |
+| Ship reusable domain-specific templates | Either — presets for template overrides, extensions for templates bundled with new commands |
+
 ## 📚 Core Philosophy
 
 Spec-Driven Development is a structured process that emphasizes:
@@ -413,11 +585,11 @@ specify init <project_name> --ai copilot
 
 # Or in current directory:
 specify init . --ai claude
-specify init . --ai codex
+specify init . --ai codex --ai-skills
 
 # or use --here flag
 specify init --here --ai claude
-specify init --here --ai codex
+specify init --here --ai codex --ai-skills
 
 # Force merge into a non-empty current directory
 specify init . --force --ai claude
@@ -426,7 +598,7 @@ specify init . --force --ai claude
 specify init --here --force --ai claude
 ```
 
-The CLI will check if you have Claude Code, Gemini CLI, Cursor CLI, Qwen CLI, opencode, Codex CLI, Qoder CLI, Tabnine CLI, Kiro CLI, or Mistral Vibe installed. If you do not, or you prefer to get the templates without checking for the right tools, use `--ignore-agent-tools` with your command:
+The CLI will check if you have Claude Code, Gemini CLI, Cursor CLI, Qwen CLI, opencode, Codex CLI, Qoder CLI, Tabnine CLI, Kiro CLI, Pi, or Mistral Vibe installed. If you do not, or you prefer to get the templates without checking for the right tools, use `--ignore-agent-tools` with your command:
 
 ```bash
 specify init <project_name> --ai claude --ignore-agent-tools

SUPPORT.md

@@ -1,18 +1,17 @@
 # Support
 
-## How to file issues and get help
+## How to get help
 
-This project uses GitHub issues to track bugs and feature requests. Please search the existing issues before filing new issues to avoid duplicates. For new issues, file your bug or feature request as a new issue.
+Please search existing [issues](https://github.com/github/spec-kit/issues) and [discussions](https://github.com/github/spec-kit/discussions) before creating new ones to avoid duplicates.
 
-For help or questions about using this project, please:
-
-- Open a [GitHub issue](https://github.com/github/spec-kit/issues/new) for bug reports, feature requests, or questions about the Spec-Driven Development methodology
-- Check the [comprehensive guide](./spec-driven.md) for detailed documentation on the Spec-Driven Development process
 - Review the [README](./README.md) for getting started instructions and troubleshooting tips
+- Check the [comprehensive guide](./spec-driven.md) for detailed documentation on the Spec-Driven Development process
+- Ask in [GitHub Discussions](https://github.com/github/spec-kit/discussions) for questions about using Spec Kit or the Spec-Driven Development methodology
+- Open a [GitHub issue](https://github.com/github/spec-kit/issues/new) for bug reports and feature requests
 
 ## Project Status
 
-**Spec Kit** is under active development and maintained by GitHub staff **AND THE COMMUNITY**. We will do our best to respond to support, feature requests, and community questions in a timely manner.
+**Spec Kit** is under active development and maintained by GitHub staff and the community. We will do our best to respond to support, feature requests, and community questions as time permits.
 
 ## GitHub Support Policy
 

TESTING.md

@@ -0,0 +1,133 @@
+# Testing Guide
+
+This document is the detailed testing companion to [`CONTRIBUTING.md`](./CONTRIBUTING.md).
+
+Use it for three things:
+
+1. running quick automated checks before manual testing,
+2. manually testing affected slash commands through an AI agent, and
+3. capturing the results in a PR-friendly format.
+
+Any change that affects a slash command's behavior requires manually testing that command through an AI agent and submitting results with the PR.
+
+## Recommended order
+
+1. **Sync your environment** — install the project and test dependencies.
+2. **Run focused automated checks** — especially for packaging, scaffolding, agent config, and generated-file changes.
+3. **Run manual agent tests** — for any affected slash commands.
+4. **Paste results into your PR** — include both command-selection reasoning and manual test results.
+
+## Quick automated checks
+
+Run these before manual testing when your change affects packaging, scaffolding, templates, release artifacts, or agent wiring.
+
+### Environment setup
+
+```bash
+cd <spec-kit-repo>
+uv sync --extra test
+source .venv/bin/activate  # On Windows (CMD): .venv\Scripts\activate  |  (PowerShell): .venv\Scripts\Activate.ps1
+```
+
+### Generated package structure and content
+
+```bash
+uv run python -m pytest tests/test_core_pack_scaffold.py -q
+```
+
+This validates the generated files that CI-style packaging depends on, including directory layout, file names, frontmatter/TOML validity, placeholder replacement, `.specify/` path rewrites, and parity with `create-release-packages.sh`.
+
+### Agent configuration and release wiring consistency
+
+```bash
+uv run python -m pytest tests/test_agent_config_consistency.py -q
+```
+
+Run this when you change agent metadata, release scripts, context update scripts, or artifact naming.
+
+### Optional single-agent packaging spot check
+
+```bash
+AGENTS=copilot SCRIPTS=sh ./.github/workflows/scripts/create-release-packages.sh v1.0.0
+```
+
+Inspect `.genreleases/sdd-copilot-package-sh/` and the matching ZIP in `.genreleases/` when you want to review the exact packaged output for one agent/script combination.
+
+## Manual testing process
+
+1. **Identify affected commands** — use the [prompt below](#determining-which-tests-to-run) to have your agent analyze your changed files and determine which commands need testing.
+2. **Set up a test project** — scaffold from your local branch (see [Setup](#setup)).
+3. **Run each affected command** — invoke it in your agent, verify it completes successfully, and confirm it produces the expected output (files created, scripts executed, artifacts populated).
+4. **Run prerequisites first** — commands that depend on earlier commands (e.g., `/speckit.tasks` requires `/speckit.plan` which requires `/speckit.specify`) must be run in order.
+5. **Report results** — paste the [reporting template](#reporting-results) into your PR with pass/fail for each command tested.
+
+## Setup
+
+```bash
+# Install the project and test dependencies from your local branch
+cd <spec-kit-repo>
+uv sync --extra test
+source .venv/bin/activate  # On Windows (CMD): .venv\Scripts\activate  |  (PowerShell): .venv\Scripts\Activate.ps1
+uv pip install -e .
+# Ensure the `specify` binary in this environment points at your working tree so the agent runs the branch you're testing.
+
+# Initialize a test project using your local changes
+uv run specify init /tmp/speckit-test --ai <agent> --offline
+cd /tmp/speckit-test
+
+# Open in your agent
+```
+
+If you are testing the packaged output rather than the live source tree, create a local release package first as described in [`CONTRIBUTING.md`](./CONTRIBUTING.md).
+
+## Reporting results
+
+Paste this into your PR:
+
+~~~markdown
+## Manual test results
+
+**Agent**: [e.g., GitHub Copilot in VS Code]  |  **OS/Shell**: [e.g., macOS/zsh]
+
+| Command tested | Notes |
+|----------------|-------|
+| `/speckit.command` | |
+~~~
+
+## Determining which tests to run
+
+Copy this prompt into your agent. Include the agent's response (selected tests plus a brief explanation of the mapping) in your PR.
+
+~~~text
+Read TESTING.md, then run `git diff --name-only main` to get my changed files.
+For each changed file, determine which slash commands it affects by reading
+the command templates in templates/commands/ to understand what each command
+invokes. Use these mapping rules:
+
+- templates/commands/X.md → the command it defines
+- scripts/bash/Y.sh or scripts/powershell/Y.ps1 → every command that invokes that script (grep templates/commands/ for the script name). Also check transitive dependencies: if the changed script is sourced by other scripts (e.g., common.sh is sourced by create-new-feature.sh, check-prerequisites.sh, setup-plan.sh, update-agent-context.sh), then every command invoking those downstream scripts is also affected
+- templates/Z-template.md → every command that consumes that template during execution
+- src/specify_cli/*.py → CLI commands (`specify init`, `specify check`, `specify extension *`, `specify preset *`); test the affected CLI command and, for init/scaffolding changes, at minimum test /speckit.specify
+- extensions/X/commands/* → the extension command it defines
+- extensions/X/scripts/* → every extension command that invokes that script
+- extensions/X/extension.yml or config-template.yml → every command in that extension. Also check if the manifest defines hooks (look for `hooks:` entries like `before_specify`, `after_implement`, etc.) — if so, the core commands those hooks attach to are also affected
+- presets/*/* → test preset scaffolding via `specify init` with the preset
+- pyproject.toml → packaging/bundling; test `specify init` and verify bundled assets
+
+Include prerequisite tests (e.g., T5 requires T3 requires T1).
+
+Output in this format:
+
+### Test selection reasoning
+
+| Changed file | Affects | Test | Why |
+|---|---|---|---|
+| (path) | (command) | T# | (reason) |
+
+### Required tests
+
+Number each test sequentially (T1, T2, ...). List prerequisite tests first.
+
+- T1: /speckit.command — (reason)
+- T2: /speckit.command — (reason)
+~~~

docs/installation.md

@@ -3,7 +3,7 @@
 ## Prerequisites
 
 - **Linux/macOS** (or Windows; PowerShell scripts now supported without WSL)
-- AI coding agent: [Claude Code](https://www.anthropic.com/claude-code), [GitHub Copilot](https://code.visualstudio.com/), [Codebuddy CLI](https://www.codebuddy.ai/cli) or [Gemini CLI](https://github.com/google-gemini/gemini-cli)
+- AI coding agent: [Claude Code](https://www.anthropic.com/claude-code), [GitHub Copilot](https://code.visualstudio.com/), [Codebuddy CLI](https://www.codebuddy.ai/cli), [Gemini CLI](https://github.com/google-gemini/gemini-cli), or [Pi Coding Agent](https://pi.dev)
 - [uv](https://docs.astral.sh/uv/) for package management
 - [Python 3.11+](https://www.python.org/downloads/)
 - [Git](https://git-scm.com/downloads)
@@ -12,18 +12,22 @@
 
 ### Initialize a New Project
 
-The easiest way to get started is to initialize a new project:
+The easiest way to get started is to initialize a new project. Pin a specific release tag for stability (check [Releases](https://github.com/github/spec-kit/releases) for the latest):
 
 ```bash
+# Install from a specific stable release (recommended — replace vX.Y.Z with the latest tag)
+uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <PROJECT_NAME>
+
+# Or install latest from main (may include unreleased changes)
 uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>
 ```
 
 Or initialize in the current directory:
 
 ```bash
-uvx --from git+https://github.com/github/spec-kit.git specify init .
+uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init .
 # or use the --here flag
-uvx --from git+https://github.com/github/spec-kit.git specify init --here
+uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --here
 ```
 
 ### Specify AI Agent
@@ -31,10 +35,11 @@ uvx --from git+https://github.com/github/spec-kit.git specify init --here
 You can proactively specify your AI agent during initialization:
 
 ```bash
-uvx --from git+https://github.com/github/spec-kit.git specify init <project_name> --ai claude
-uvx --from git+https://github.com/github/spec-kit.git specify init <project_name> --ai gemini
-uvx --from git+https://github.com/github/spec-kit.git specify init <project_name> --ai copilot
-uvx --from git+https://github.com/github/spec-kit.git specify init <project_name> --ai codebuddy
+uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <project_name> --ai claude
+uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <project_name> --ai gemini
+uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <project_name> --ai copilot
+uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <project_name> --ai codebuddy
+uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <project_name> --ai pi
 ```
 
 ### Specify Script Type (Shell vs PowerShell)
@@ -50,8 +55,8 @@ Auto behavior:
 Force a specific script type:
 
 ```bash
-uvx --from git+https://github.com/github/spec-kit.git specify init <project_name> --script sh
-uvx --from git+https://github.com/github/spec-kit.git specify init <project_name> --script ps
+uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <project_name> --script sh
+uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <project_name> --script ps
 ```
 
 ### Ignore Agent Tools Check
@@ -59,7 +64,7 @@ uvx --from git+https://github.com/github/spec-kit.git specify init <project_name
 If you prefer to get the templates without checking for the right tools:
 
 ```bash
-uvx --from git+https://github.com/github/spec-kit.git specify init <project_name> --ai claude --ignore-agent-tools
+uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <project_name> --ai claude --ignore-agent-tools
 ```
 
 ## Verification
@@ -74,6 +79,52 @@ The `.specify/scripts` directory will contain both `.sh` and `.ps1` scripts.
 
 ## Troubleshooting
 
+### Enterprise / Air-Gapped Installation
+
+If your environment blocks access to PyPI (you see 403 errors when running `uv tool install` or `pip install`), you can create a portable wheel bundle on a connected machine and transfer it to the air-gapped target.
+
+**Step 1: Build the wheel on a connected machine (same OS and Python version as the target)**
+
+```bash
+# Clone the repository
+git clone https://github.com/github/spec-kit.git
+cd spec-kit
+
+# Build the wheel
+pip install build
+python -m build --wheel --outdir dist/
+
+# Download the wheel and all its runtime dependencies
+pip download -d dist/ dist/specify_cli-*.whl
+```
+
+> **Important:** `pip download` resolves platform-specific wheels (e.g., PyYAML includes native extensions). You must run this step on a machine with the **same OS and Python version** as the air-gapped target. If you need to support multiple platforms, repeat this step on each target OS (Linux, macOS, Windows) and Python version.
+
+**Step 2: Transfer the `dist/` directory to the air-gapped machine**
+
+Copy the entire `dist/` directory (which contains the `specify-cli` wheel and all dependency wheels) to the target machine via USB, network share, or other approved transfer method.
+
+**Step 3: Install on the air-gapped machine**
+
+```bash
+pip install --no-index --find-links=./dist specify-cli
+```
+
+**Step 4: Initialize a project (no network required)**
+
+```bash
+# Initialize a project — no GitHub access needed
+specify init my-project --ai claude --offline
+```
+
+The `--offline` flag tells the CLI to use the templates, commands, and scripts bundled inside the wheel instead of downloading from GitHub.
+
+> **Deprecation notice:** Starting with v0.6.0, `specify init` will use bundled assets by default and the `--offline` flag will be removed. The GitHub download path will be retired because bundled assets eliminate the need for network access, avoid proxy/firewall issues, and guarantee that templates always match the installed CLI version. No action will be needed — `specify init` will simply work without network access out of the box.
+
+> **Note:** Python 3.11+ is required.
+
+> **Windows note:** Offline scaffolding requires PowerShell 7+ (`pwsh`), not Windows PowerShell 5.x (`powershell.exe`). Install from https://aka.ms/powershell.
+
 ### Git Credential Manager on Linux
 
 If you're having issues with Git authentication on Linux, you can install Git Credential Manager:

docs/upgrade.md

@@ -8,7 +8,7 @@
 
 | What to Upgrade | Command | When to Use |
 |----------------|---------|-------------|
-| **CLI Tool Only** | `uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git` | Get latest CLI features without touching project files |
+| **CLI Tool Only** | `uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git@vX.Y.Z` | Get latest CLI features without touching project files |
 | **Project Files** | `specify init --here --force --ai <your-agent>` | Update slash commands, templates, and scripts in your project |
 | **Both** | Run CLI upgrade, then project update | Recommended for major version updates |
 
@@ -20,16 +20,18 @@ The CLI tool (`specify`) is separate from your project files. Upgrade it to get
 
 ### If you installed with `uv tool install`
 
+Upgrade to a specific release (check [Releases](https://github.com/github/spec-kit/releases) for the latest tag):
+
 ```bash
-uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git
+uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git@vX.Y.Z
 ```
 
 ### If you use one-shot `uvx` commands
 
-No upgrade needed—`uvx` always fetches the latest version. Just run your commands as normal:
+Specify the desired release tag:
 
 ```bash
-uvx --from git+https://github.com/github/spec-kit.git specify init --here --ai copilot
+uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --here --ai copilot
 ```
 
 ### Verify the upgrade
@@ -289,8 +291,9 @@ This tells Spec Kit which feature directory to use when creating specs, plans, a
 
    ```bash
    ls -la .claude/commands/      # Claude Code
-   ls -la .gemini/commands/       # Gemini
-   ls -la .cursor/commands/       # Cursor
+   ls -la .gemini/commands/      # Gemini
+   ls -la .cursor/commands/      # Cursor
+   ls -la .pi/prompts/           # Pi Coding Agent
    ```
 
 3. **Check agent-specific setup:**
@@ -398,7 +401,7 @@ The `specify` CLI tool is used for:
 - **Upgrades:** `specify init --here --force` to update templates and commands
 - **Diagnostics:** `specify check` to verify tool installation
 
-Once you've run `specify init`, the slash commands (like `/speckit.specify`, `/speckit.plan`, etc.) are **permanently installed** in your project's agent folder (`.claude/`, `.github/prompts/`, etc.). Your AI assistant reads these command files directly—no need to run `specify` again.
+Once you've run `specify init`, the slash commands (like `/speckit.specify`, `/speckit.plan`, etc.) are **permanently installed** in your project's agent folder (`.claude/`, `.github/prompts/`, `.pi/prompts/`, etc.). Your AI assistant reads these command files directly—no need to run `specify` again.
 
 **If your agent isn't recognizing slash commands:**
 
@@ -410,6 +413,9 @@ Once you've run `specify init`, the slash commands (like `/speckit.specify`, `/s
 
    # For Claude
    ls -la .claude/commands/
+
+   # For Pi
+   ls -la .pi/prompts/
    ```
 
 2. **Restart your IDE/editor completely** (not just reload window)

extensions/EXTENSION-API-REFERENCE.md

@@ -44,7 +44,7 @@ provides:
     - name: string       # Required, pattern: ^speckit\.[a-z0-9-]+\.[a-z0-9-]+$
       file: string       # Required, relative path to command file
       description: string # Required
-      aliases: [string]  # Optional, array of alternate names
+      aliases: [string]  # Optional, same pattern as name; namespace must match extension.id and must not shadow core or installed extension commands
 
   config:                # Optional, array of config files
     - name: string       # Config file name
@@ -53,7 +53,7 @@ provides:
       required: boolean  # Default: false
 
 hooks:                   # Optional, event hooks
-  event_name:            # e.g., "after_tasks", "after_implement"
+  event_name:            # e.g., "after_specify", "after_plan", "after_tasks", "after_implement"
     command: string      # Command to execute
     optional: boolean    # Default: true
     prompt: string       # Prompt text for optional hooks
@@ -108,7 +108,7 @@ defaults:                # Optional, default configuration values
 #### `hooks`
 
 - **Type**: object
-- **Keys**: Event names (e.g., `after_tasks`, `after_implement`, `before_commit`)
+- **Keys**: Event names (e.g., `after_specify`, `after_plan`, `after_tasks`, `after_implement`, `before_commit`)
 - **Description**: Hooks that execute at lifecycle events
 - **Events**: Defined by core spec-kit commands
 
@@ -551,10 +551,16 @@ hooks:
 
 Standard events (defined by core):
 
+- `before_specify` - Before specification generation
+- `after_specify` - After specification generation
+- `before_plan` - Before implementation planning
+- `after_plan` - After implementation planning
+- `before_tasks` - Before task generation
 - `after_tasks` - After task generation
+- `before_implement` - Before implementation
 - `after_implement` - After implementation
-- `before_commit` - Before git commit
-- `after_commit` - After git commit
+- `before_commit` - Before git commit *(planned - not yet wired into core templates)*
+- `after_commit` - After git commit *(planned - not yet wired into core templates)*
 
 ### Hook Configuration
 

extensions/EXTENSION-DEVELOPMENT-GUIDE.md

@@ -41,7 +41,7 @@ provides:
     - name: "speckit.my-ext.hello"      # Must follow pattern: speckit.{ext-id}.{cmd}
       file: "commands/hello.md"
       description: "Say hello"
-      aliases: ["speckit.hello"]        # Optional aliases
+      aliases: ["speckit.my-ext.hi"]    # Optional aliases, same pattern
 
   config:                               # Optional: Config files
     - name: "my-ext-config.yml"
@@ -186,7 +186,7 @@ What the extension provides.
 - `name`: Command name (must match `speckit.{ext-id}.{command}`)
 - `file`: Path to command file (relative to extension root)
 - `description`: Command description (optional)
-- `aliases`: Alternative command names (optional, array)
+- `aliases`: Alternative command names (optional, array; each must match `speckit.{ext-id}.{command}`)
 
 ### Optional Fields
 
@@ -514,7 +514,7 @@ zip -r spec-kit-my-ext-1.0.0.zip extension.yml commands/ scripts/ docs/
 Users install with:
 
 ```bash
-specify extension add --from https://github.com/.../spec-kit-my-ext-1.0.0.zip
+specify extension add <extension-name> --from https://github.com/.../spec-kit-my-ext-1.0.0.zip
 ```
 
 ### Option 3: Community Reference Catalog
@@ -523,7 +523,7 @@ Submit to the community catalog for public discovery:
 
 1. **Fork** spec-kit repository
 2. **Add entry** to `extensions/catalog.community.json`
-3. **Update** `extensions/README.md` with your extension
+3. **Update** the Community Extensions table in `README.md` with your extension
 4. **Create PR** following the [Extension Publishing Guide](EXTENSION-PUBLISHING-GUIDE.md)
 5. **After merge**, your extension becomes available:
    - Users can browse `catalog.community.json` to discover your extension

extensions/EXTENSION-PUBLISHING-GUIDE.md

@@ -122,7 +122,7 @@ Test that users can install from your release:
 specify extension add --dev /path/to/your-extension
 
 # Test from GitHub archive
-specify extension add --from https://github.com/your-org/spec-kit-your-extension/archive/refs/tags/v1.0.0.zip
+specify extension add <extension-name> --from https://github.com/your-org/spec-kit-your-extension/archive/refs/tags/v1.0.0.zip
 ```
 
 ---
@@ -204,14 +204,27 @@ Edit `extensions/catalog.community.json` and add your extension:
 - Use current timestamp for `created_at` and `updated_at`
 - Update the top-level `updated_at` to current time
 
-### 3. Update Extensions README
+### 3. Update Community Extensions Table
 
-Add your extension to the Available Extensions table in `extensions/README.md`:
+Add your extension to the Community Extensions table in the project root `README.md`:
 
 ```markdown
-| Your Extension Name | Brief description of what it does | [repo-name](https://github.com/your-org/spec-kit-your-extension) |
+| Your Extension Name | Brief description of what it does | `<category>` | <effect> | [repo-name](https://github.com/your-org/spec-kit-your-extension) |
 ```
 
+**(Table) Category** — pick the one that best fits your extension:
+
+- `docs` — reads, validates, or generates spec artifacts
+- `code` — reviews, validates, or modifies source code
+- `process` — orchestrates workflow across phases
+- `integration` — syncs with external platforms
+- `visibility` — reports on project health or progress
+
+**Effect** — choose one:
+
+- Read-only — produces reports without modifying files
+- Read+Write — modifies files, creates artifacts, or updates specs
+
 Insert your extension in alphabetical order in the table.
 
 ### 4. Submit Pull Request
@@ -221,7 +234,7 @@ Insert your extension in alphabetical order in the table.
 git checkout -b add-your-extension
 
 # Commit your changes
-git add extensions/catalog.community.json extensions/README.md
+git add extensions/catalog.community.json README.md
 git commit -m "Add your-extension to community catalog
 
 - Extension ID: your-extension
@@ -260,7 +273,7 @@ Brief description of what your extension does.
 - [x] All commands working
 - [x] No security vulnerabilities
 - [x] Added to extensions/catalog.community.json
-- [x] Added to extensions/README.md Available Extensions table
+- [x] Added to Community Extensions table in README.md
 
 ### Testing
 Tested on:

extensions/EXTENSION-USER-GUIDE.md

@@ -160,7 +160,7 @@ This will:
 
 ```bash
 # From GitHub release
-specify extension add --from https://github.com/org/spec-kit-ext/archive/refs/tags/v1.0.0.zip
+specify extension add <extension-name> --from https://github.com/org/spec-kit-ext/archive/refs/tags/v1.0.0.zip
 ```
 
 ### Install from Local Directory (Development)
@@ -187,6 +187,21 @@ Provided commands:
    Check: .specify/extensions/jira/
 ```
 
+### Automatic Agent Skill Registration
+
+If your project was initialized with `--ai-skills`, extension commands are **automatically registered as agent skills** during installation. This ensures that extensions are discoverable by agents that use the [agentskills.io](https://agentskills.io) skill specification.
+
+```text
+✓ Extension installed successfully!
+
+Jira Integration (v1.0.0)
+  ...
+
+✓ 3 agent skill(s) auto-registered
+```
+
+When an extension is removed, its corresponding skills are also cleaned up automatically. Pre-existing skills that were manually customized are never overwritten.
+
 ---
 
 ## Using Extensions
@@ -199,8 +214,8 @@ Extensions add commands that appear in your AI agent (Claude Code):
 # In Claude Code
 > /speckit.jira.specstoissues
 
-# Or use short alias (if provided)
-> /speckit.specstoissues
+# Or use a namespaced alias (if provided)
+> /speckit.jira.sync
 ```
 
 ### Extension Configuration
@@ -387,6 +402,9 @@ settings:
   auto_execute_hooks: true
 
 # Hook configuration
+# Available events: before_specify, after_specify, before_plan, after_plan,
+#                   before_tasks, after_tasks, before_implement, after_implement
+# Planned (not yet wired into core templates): before_commit, after_commit
 hooks:
   after_tasks:
     - extension: jira
@@ -719,7 +737,7 @@ You can still install extensions not in your catalog using `--from`:
 specify extension add jira
 
 # Direct URL (bypasses catalog)
-specify extension add --from https://github.com/someone/spec-kit-ext/archive/v1.0.0.zip
+specify extension add <extension-name> --from https://github.com/someone/spec-kit-ext/archive/v1.0.0.zip
 
 # Local development
 specify extension add --dev /path/to/extension
@@ -789,7 +807,7 @@ specify extension add --dev /path/to/extension
 2. Install older version of extension:
 
    ```bash
-   specify extension add --from https://github.com/org/ext/archive/v1.0.0.zip
+   specify extension add <extension-name> --from https://github.com/org/ext/archive/v1.0.0.zip
    ```
 
 ### MCP Tool Not Available

extensions/README.md

@@ -59,7 +59,7 @@ Populate your `catalog.json` with approved extensions:
 Skip catalog curation - team members install directly using URLs:
 
 ```bash
-specify extension add --from https://github.com/org/spec-kit-ext/archive/refs/tags/v1.0.0.zip
+specify extension add <extension-name> --from https://github.com/org/spec-kit-ext/archive/refs/tags/v1.0.0.zip
 ```
 
 **Benefits**: Quick for one-off testing or private extensions
@@ -68,27 +68,9 @@ specify extension add --from https://github.com/org/spec-kit-ext/archive/refs/ta
 
 ## Available Community Extensions
 
-The following community-contributed extensions are available in [`catalog.community.json`](catalog.community.json):
+See the [Community Extensions](../README.md#-community-extensions) section in the main README for the full list of available community-contributed extensions.
 
-| Extension | Purpose | URL |
-|-----------|---------|-----|
-| Archive Extension | Archive merged features into main project memory. | [spec-kit-archive](https://github.com/stn1slv/spec-kit-archive) |
-| Azure DevOps Integration | Sync user stories and tasks to Azure DevOps work items using OAuth authentication | [spec-kit-azure-devops](https://github.com/pragya247/spec-kit-azure-devops) |
-| Cleanup Extension | Post-implementation quality gate that reviews changes, fixes small issues (scout rule), creates tasks for medium issues, and generates analysis for large issues | [spec-kit-cleanup](https://github.com/dsrednicki/spec-kit-cleanup) |
-| Cognitive Squad | 19-function cognitive agent squad for autonomous pre-code analysis — 7 core agents, 7 specialists, 4 learning functions with feedback loop | [cognitive-squad](https://github.com/Testimonial/cognitive-squad) |
-| DocGuard — CDD Enforcement | Canonical-Driven Development enforcement. Validates, scores, and traces project documentation with automated checks, AI-driven workflows, and spec-kit hooks. Zero dependencies. | [spec-kit-docguard](https://github.com/raccioly/docguard) |
-| Fleet Orchestrator | Orchestrate a full feature lifecycle with human-in-the-loop gates across all SpecKit phases | [spec-kit-fleet](https://github.com/sharathsatish/spec-kit-fleet) |
-| Jira Integration | Create Jira Epics, Stories, and Issues from spec-kit specifications and task breakdowns with configurable hierarchy and custom field support | [spec-kit-jira](https://github.com/mbachorik/spec-kit-jira) |
-| Project Health Check | Diagnose a Spec Kit project and report health issues across structure, agents, features, scripts, extensions, and git | [spec-kit-doctor](https://github.com/KhawarHabibKhan/spec-kit-doctor) |
-| Project Status | Show current SDD workflow progress — active feature, artifact status, task completion, workflow phase, and extensions summary | [spec-kit-status](https://github.com/KhawarHabibKhan/spec-kit-status) |
-| Ralph Loop | Autonomous implementation loop using AI agent CLI | [spec-kit-ralph](https://github.com/Rubiss/spec-kit-ralph) |
-| Reconcile Extension | Reconcile implementation drift by surgically updating feature artifacts. | [spec-kit-reconcile](https://github.com/stn1slv/spec-kit-reconcile) |
-| Retrospective Extension | Post-implementation retrospective with spec adherence scoring, drift analysis, and human-gated spec updates | [spec-kit-retrospective](https://github.com/emi-dm/spec-kit-retrospective) |
-| Review Extension | Post-implementation comprehensive code review with specialized agents for code quality, comments, tests, error handling, type design, and simplification | [spec-kit-review](https://github.com/ismaelJimenez/spec-kit-review) |
-| Spec Sync | Detect and resolve drift between specs and implementation. AI-assisted resolution with human approval | [spec-kit-sync](https://github.com/bgervin/spec-kit-sync) |
-| Understanding | Automated requirements quality analysis — 31 deterministic metrics against IEEE/ISO standards with experimental energy-based ambiguity detection | [understanding](https://github.com/Testimonial/understanding) |
-| V-Model Extension Pack | Enforces V-Model paired generation of development specs and test specs with full traceability | [spec-kit-v-model](https://github.com/leocamello/spec-kit-v-model) |
-| Verify Extension | Post-implementation quality gate that validates implemented code against specification artifacts | [spec-kit-verify](https://github.com/ismaelJimenez/spec-kit-verify) |
+For the raw catalog data, see [`catalog.community.json`](catalog.community.json).
 
 
 ## Adding Your Extension
@@ -126,7 +108,7 @@ specify extension search                  # See what's in your catalog
 specify extension add <extension-name>    # Install by name
 
 # Direct from URL (bypasses catalog)
-specify extension add --from https://github.com/<org>/<repo>/archive/refs/tags/<version>.zip
+specify extension add <extension-name> --from https://github.com/<org>/<repo>/archive/refs/tags/<version>.zip
 
 # List installed extensions
 specify extension list

extensions/RFC-EXTENSION-SYSTEM.md

@@ -223,7 +223,7 @@ provides:
     - name: "speckit.jira.specstoissues"
       file: "commands/specstoissues.md"
       description: "Create Jira hierarchy from spec and tasks"
-      aliases: ["speckit.specstoissues"]  # Alternate names
+      aliases: ["speckit.jira.sync"]  # Alternate names
 
     - name: "speckit.jira.discover-fields"
       file: "commands/discover-fields.md"
@@ -359,12 +359,15 @@ specify extension add jira
       "installed_at": "2026-01-28T14:30:00Z",
       "source": "catalog",
       "manifest_hash": "sha256:abc123...",
-      "enabled": true
+      "enabled": true,
+      "priority": 10
     }
   }
 }
 ```
 
+**Priority Field**: Extensions are ordered by `priority` (lower = higher precedence). Default is 10. Used for template resolution when multiple extensions provide the same template.
+
 ### 3. Configuration
 
 ```bash
@@ -1084,11 +1087,15 @@ List installed extensions in current project.
 $ specify extension list
 
 Installed Extensions:
-  ✓ jira (v1.0.0) - Jira Integration
-    Commands: 3 | Hooks: 2 | Status: Enabled
+  ✓ Jira Integration (v1.0.0)
+     jira
+     Create Jira issues from spec-kit artifacts
+     Commands: 3 | Hooks: 2 | Priority: 10 | Status: Enabled
 
-  ✓ linear (v0.9.0) - Linear Integration
-    Commands: 1 | Hooks: 1 | Status: Enabled
+  ✓ Linear Integration (v0.9.0)
+     linear
+     Create Linear issues from spec-kit artifacts
+     Commands: 1 | Hooks: 1 | Priority: 10 | Status: Enabled
 ```
 
 **Options:**
@@ -1196,10 +1203,9 @@ Next steps:
 
 **Options:**
 
-- `--from URL`: Install from custom URL or Git repo
-- `--version VERSION`: Install specific version
-- `--dev PATH`: Install from local path (development mode)
-- `--no-register`: Skip command registration (manual setup)
+- `--from URL`: Install from a remote URL (archive). Does not accept Git repositories directly.
+- `--dev`: Install from a local path in development mode (the PATH is the positional `extension` argument).
+- `--priority NUMBER`: Set resolution priority (lower = higher precedence, default 10)
 
 #### `specify extension remove NAME`
 
@@ -1280,6 +1286,29 @@ $ specify extension disable jira
 To re-enable: specify extension enable jira
 ```
 
+#### `specify extension set-priority NAME PRIORITY`
+
+Change the resolution priority of an installed extension.
+
+```bash
+$ specify extension set-priority jira 5
+
+✓ Extension 'Jira Integration' priority changed: 10 → 5
+
+Lower priority = higher precedence in template resolution
+```
+
+**Priority Values:**
+
+- Lower numbers = higher precedence (checked first in resolution)
+- Default priority is 10
+- Must be a positive integer (1 or higher)
+
+**Use Cases:**
+
+- Ensure a critical extension's templates take precedence
+- Override default resolution order when multiple extensions provide similar templates
+
 ---
 
 ## Compatibility & Versioning
@@ -1488,7 +1517,7 @@ specify extension add github-projects
 /speckit.github.taskstoissues
 ```
 
-**Compatibility shim** (if needed):
+**Migration alias** (if needed):
 
 ```yaml
 # extension.yml
@@ -1496,10 +1525,10 @@ provides:
   commands:
     - name: "speckit.github.taskstoissues"
       file: "commands/taskstoissues.md"
-      aliases: ["speckit.taskstoissues"]  # Backward compatibility
+      aliases: ["speckit.github.sync-taskstoissues"]  # Alternate namespaced entry point
 ```
 
-AI agent registers both names, so old scripts work.
+AI agents register both names, so callers can migrate to the alternate alias without relying on deprecated global shortcuts like `/speckit.taskstoissues`.
 
 ---
 

extensions/catalog.community.json

@@ -1,8 +1,41 @@
 {
   "schema_version": "1.0",
-  "updated_at": "2026-03-16T00:00:00Z",
+  "updated_at": "2026-03-30T00:00:00Z",
   "catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.community.json",
   "extensions": {
+    "aide": {
+      "name": "AI-Driven Engineering (AIDE)",
+      "id": "aide",
+      "description": "A structured 7-step workflow for building new projects from scratch with AI assistants — from vision through implementation.",
+      "author": "mnriem",
+      "version": "1.0.0",
+      "download_url": "https://github.com/mnriem/spec-kit-extensions/releases/download/aide-v1.0.0/aide.zip",
+      "repository": "https://github.com/mnriem/spec-kit-extensions",
+      "homepage": "https://github.com/mnriem/spec-kit-extensions",
+      "documentation": "https://github.com/mnriem/spec-kit-extensions/blob/main/aide/README.md",
+      "changelog": "https://github.com/mnriem/spec-kit-extensions/blob/main/aide/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.2.0"
+      },
+      "provides": {
+        "commands": 7,
+        "hooks": 0
+      },
+      "tags": [
+        "workflow",
+        "project-management",
+        "ai-driven",
+        "new-project",
+        "planning",
+        "experimental"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-03-18T00:00:00Z",
+      "updated_at": "2026-03-18T00:00:00Z"
+    },
     "archive": {
       "name": "Archive Extension",
       "id": "archive",
@@ -73,6 +106,35 @@
       "created_at": "2026-03-03T00:00:00Z",
       "updated_at": "2026-03-03T00:00:00Z"
     },
+    "checkpoint": {
+      "name": "Checkpoint Extension",
+      "id": "checkpoint",
+      "description": "An extension to commit the changes made during the middle of the implementation, so you don't end up with just one very large commit at the end.",
+      "author": "aaronrsun",
+      "version": "1.0.0",
+      "download_url": "https://github.com/aaronrsun/spec-kit-checkpoint/archive/refs/tags/v1.0.0.zip",
+      "repository": "https://github.com/aaronrsun/spec-kit-checkpoint",
+      "homepage": "https://github.com/aaronrsun/spec-kit-checkpoint",
+      "documentation": "https://github.com/aaronrsun/spec-kit-checkpoint/blob/main/README.md",
+      "changelog": "https://github.com/aaronrsun/spec-kit-checkpoint/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.1.0"
+      },
+      "provides": {
+        "commands": 1,
+        "hooks": 0
+      },
+      "tags": [
+        "checkpoint",
+        "commit"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-03-22T00:00:00Z",
+      "updated_at": "2026-03-22T00:00:00Z"
+    },
     "cleanup": {
       "name": "Cleanup Extension",
       "id": "cleanup",
@@ -108,7 +170,7 @@
     "cognitive-squad": {
       "name": "Cognitive Squad",
       "id": "cognitive-squad",
-      "description": "19-function cognitive agent squad for autonomous pre-code analysis — 7 core agents, 7 specialists, 4 learning functions with feedback loop",
+      "description": "Multi-agent cognitive system with Triadic Model: understanding, internalization, application — with quality gates, backpropagation verification, and self-healing",
       "author": "Testimonial",
       "version": "0.1.0",
       "download_url": "https://github.com/Testimonial/cognitive-squad/archive/refs/tags/v0.1.0.zip",
@@ -133,29 +195,59 @@
         ]
       },
       "provides": {
-        "commands": 7,
+        "commands": 10,
         "hooks": 1
       },
       "tags": [
         "ai-agents",
         "cognitive",
-        "pre-code",
-        "analysis",
+        "full-lifecycle",
+        "verification",
         "multi-agent"
       ],
       "verified": false,
       "downloads": 0,
       "stars": 0,
       "created_at": "2026-03-16T00:00:00Z",
-      "updated_at": "2026-03-16T00:00:00Z"
+      "updated_at": "2026-03-18T00:00:00Z"
+    },
+    "conduct": {
+      "name": "Conduct Extension",
+      "id": "conduct",
+      "description": "Executes a single spec-kit phase via sub-agent delegation to reduce context pollution.",
+      "author": "twbrandon7",
+      "version": "1.0.0",
+      "download_url": "https://github.com/twbrandon7/spec-kit-conduct-ext/archive/refs/tags/v1.0.0.zip",
+      "repository": "https://github.com/twbrandon7/spec-kit-conduct-ext",
+      "homepage": "https://github.com/twbrandon7/spec-kit-conduct-ext",
+      "documentation": "https://github.com/twbrandon7/spec-kit-conduct-ext/blob/main/README.md",
+      "changelog": "https://github.com/twbrandon7/spec-kit-conduct-ext/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.3.1"
+      },
+      "provides": {
+        "commands": 1,
+        "hooks": 0
+      },
+      "tags": [
+        "conduct",
+        "workflow",
+        "automation"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-03-19T12:08:20Z",
+      "updated_at": "2026-03-19T12:08:20Z"
     },
     "docguard": {
-      "name": "DocGuard \u2014 CDD Enforcement",
+      "name": "DocGuard — CDD Enforcement",
       "id": "docguard",
-      "description": "Canonical-Driven Development enforcement. Validates, scores, and traces project documentation with automated checks, AI-driven workflows, and spec-kit hooks. Zero dependencies.",
+      "description": "Canonical-Driven Development enforcement. Validates, scores, and traces project documentation with automated checks, AI-driven workflows, and spec-kit hooks. Zero NPM runtime dependencies.",
       "author": "raccioly",
-      "version": "0.9.8",
-      "download_url": "https://github.com/raccioly/docguard/releases/download/v0.9.8/spec-kit-docguard-v0.9.8.zip",
+      "version": "0.9.11",
+      "download_url": "https://github.com/raccioly/docguard/releases/download/v0.9.11/spec-kit-docguard-v0.9.11.zip",
       "repository": "https://github.com/raccioly/docguard",
       "homepage": "https://www.npmjs.com/package/docguard-cli",
       "documentation": "https://github.com/raccioly/docguard/blob/main/extensions/spec-kit-docguard/README.md",
@@ -189,7 +281,7 @@
       "downloads": 0,
       "stars": 0,
       "created_at": "2026-03-13T00:00:00Z",
-      "updated_at": "2026-03-15T20:00:00Z"
+      "updated_at": "2026-03-18T18:53:31Z"
     },
     "doctor": {
       "name": "Project Health Check",
@@ -222,6 +314,37 @@
       "created_at": "2026-03-13T00:00:00Z",
       "updated_at": "2026-03-13T00:00:00Z"
     },
+    "extensify": {
+      "name": "Extensify",
+      "id": "extensify",
+      "description": "Create and validate extensions and extension catalogs.",
+      "author": "mnriem",
+      "version": "1.0.0",
+      "download_url": "https://github.com/mnriem/spec-kit-extensions/releases/download/extensify-v1.0.0/extensify.zip",
+      "repository": "https://github.com/mnriem/spec-kit-extensions",
+      "homepage": "https://github.com/mnriem/spec-kit-extensions",
+      "documentation": "https://github.com/mnriem/spec-kit-extensions/blob/main/extensify/README.md",
+      "changelog": "https://github.com/mnriem/spec-kit-extensions/blob/main/extensify/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.2.0"
+      },
+      "provides": {
+        "commands": 4,
+        "hooks": 0
+      },
+      "tags": [
+        "extensions",
+        "workflow",
+        "validation",
+        "experimental"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-03-18T00:00:00Z",
+      "updated_at": "2026-03-18T00:00:00Z"
+    },
     "fleet": {
       "name": "Fleet Orchestrator",
       "id": "fleet",
@@ -253,6 +376,36 @@
       "created_at": "2026-03-06T00:00:00Z",
       "updated_at": "2026-03-06T00:00:00Z"
     },
+    "iterate": {
+      "name": "Iterate",
+      "id": "iterate",
+      "description": "Iterate on spec documents with a two-phase define-and-apply workflow — refine specs mid-implementation and go straight back to building",
+      "author": "Vianca Martinez",
+      "version": "2.0.0",
+      "download_url": "https://github.com/imviancagrace/spec-kit-iterate/archive/refs/tags/v2.0.0.zip",
+      "repository": "https://github.com/imviancagrace/spec-kit-iterate",
+      "homepage": "https://github.com/imviancagrace/spec-kit-iterate",
+      "documentation": "https://github.com/imviancagrace/spec-kit-iterate/blob/main/README.md",
+      "changelog": "https://github.com/imviancagrace/spec-kit-iterate/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.1.0"
+      },
+      "provides": {
+        "commands": 2,
+        "hooks": 0
+      },
+      "tags": [
+        "iteration",
+        "change-management",
+        "spec-maintenance"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-03-17T00:00:00Z",
+      "updated_at": "2026-03-17T00:00:00Z"
+    },
     "jira": {
       "name": "Jira Integration",
       "id": "jira",
@@ -284,6 +437,390 @@
       "created_at": "2026-03-05T00:00:00Z",
       "updated_at": "2026-03-05T00:00:00Z"
     },
+    "learn": {
+      "name": "Learning Extension",
+      "id": "learn",
+      "description": "Generate educational guides from implementations and enhance clarifications with mentoring context.",
+      "author": "Vianca Martinez",
+      "version": "1.0.0",
+      "download_url": "https://github.com/imviancagrace/spec-kit-learn/archive/refs/tags/v1.0.0.zip",
+      "repository": "https://github.com/imviancagrace/spec-kit-learn",
+      "homepage": "https://github.com/imviancagrace/spec-kit-learn",
+      "documentation": "https://github.com/imviancagrace/spec-kit-learn/blob/main/README.md",
+      "changelog": "https://github.com/imviancagrace/spec-kit-learn/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.1.0"
+      },
+      "provides": {
+        "commands": 2,
+        "hooks": 1
+      },
+      "tags": [
+        "learning",
+        "education",
+        "mentoring",
+        "knowledge-transfer"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-03-17T00:00:00Z",
+      "updated_at": "2026-03-17T00:00:00Z"
+    },
+    "maqa": {
+      "name": "MAQA — Multi-Agent & Quality Assurance",
+      "id": "maqa",
+      "description": "Coordinator → feature → QA agent workflow with parallel worktree-based implementation. Language-agnostic. Auto-detects installed board plugins (Trello, Linear, GitHub Projects, Jira, Azure DevOps). Optional CI gate.",
+      "author": "GenieRobot",
+      "version": "0.1.3",
+      "download_url": "https://github.com/GenieRobot/spec-kit-maqa-ext/releases/download/maqa-v0.1.3/maqa.zip",
+      "repository": "https://github.com/GenieRobot/spec-kit-maqa-ext",
+      "homepage": "https://github.com/GenieRobot/spec-kit-maqa-ext",
+      "documentation": "https://github.com/GenieRobot/spec-kit-maqa-ext/blob/main/README.md",
+      "changelog": "https://github.com/GenieRobot/spec-kit-maqa-ext/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.3.0"
+      },
+      "provides": {
+        "commands": 4,
+        "hooks": 1
+      },
+      "tags": [
+        "multi-agent",
+        "orchestration",
+        "quality-assurance",
+        "workflow",
+        "parallel",
+        "tdd"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-03-26T00:00:00Z",
+      "updated_at": "2026-03-27T00:00:00Z"
+    },
+    "maqa-azure-devops": {
+      "name": "MAQA Azure DevOps Integration",
+      "id": "maqa-azure-devops",
+      "description": "Azure DevOps Boards integration for the MAQA extension. Populates work items from specs, moves User Stories across columns as features progress, real-time Task child ticking.",
+      "author": "GenieRobot",
+      "version": "0.1.0",
+      "download_url": "https://github.com/GenieRobot/spec-kit-maqa-azure-devops/releases/download/maqa-azure-devops-v0.1.0/maqa-azure-devops.zip",
+      "repository": "https://github.com/GenieRobot/spec-kit-maqa-azure-devops",
+      "homepage": "https://github.com/GenieRobot/spec-kit-maqa-azure-devops",
+      "documentation": "https://github.com/GenieRobot/spec-kit-maqa-azure-devops/blob/main/README.md",
+      "changelog": "https://github.com/GenieRobot/spec-kit-maqa-azure-devops/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.3.0"
+      },
+      "provides": {
+        "commands": 2,
+        "hooks": 0
+      },
+      "tags": [
+        "azure-devops",
+        "project-management",
+        "multi-agent",
+        "maqa",
+        "kanban"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-03-27T00:00:00Z",
+      "updated_at": "2026-03-27T00:00:00Z"
+    },
+    "maqa-ci": {
+      "name": "MAQA CI/CD Gate",
+      "id": "maqa-ci",
+      "description": "CI/CD pipeline gate for the MAQA extension. Auto-detects GitHub Actions, CircleCI, GitLab CI, and Bitbucket Pipelines. Blocks QA handoff until pipeline is green.",
+      "author": "GenieRobot",
+      "version": "0.1.0",
+      "download_url": "https://github.com/GenieRobot/spec-kit-maqa-ci/releases/download/maqa-ci-v0.1.0/maqa-ci.zip",
+      "repository": "https://github.com/GenieRobot/spec-kit-maqa-ci",
+      "homepage": "https://github.com/GenieRobot/spec-kit-maqa-ci",
+      "documentation": "https://github.com/GenieRobot/spec-kit-maqa-ci/blob/main/README.md",
+      "changelog": "https://github.com/GenieRobot/spec-kit-maqa-ci/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.3.0"
+      },
+      "provides": {
+        "commands": 2,
+        "hooks": 0
+      },
+      "tags": [
+        "ci-cd",
+        "github-actions",
+        "circleci",
+        "gitlab-ci",
+        "quality-gate",
+        "maqa"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-03-27T00:00:00Z",
+      "updated_at": "2026-03-27T00:00:00Z"
+    },
+    "maqa-github-projects": {
+      "name": "MAQA GitHub Projects Integration",
+      "id": "maqa-github-projects",
+      "description": "GitHub Projects v2 integration for the MAQA extension. Populates draft issues from specs, moves items across Status columns as features progress, real-time task list ticking.",
+      "author": "GenieRobot",
+      "version": "0.1.0",
+      "download_url": "https://github.com/GenieRobot/spec-kit-maqa-github-projects/releases/download/maqa-github-projects-v0.1.0/maqa-github-projects.zip",
+      "repository": "https://github.com/GenieRobot/spec-kit-maqa-github-projects",
+      "homepage": "https://github.com/GenieRobot/spec-kit-maqa-github-projects",
+      "documentation": "https://github.com/GenieRobot/spec-kit-maqa-github-projects/blob/main/README.md",
+      "changelog": "https://github.com/GenieRobot/spec-kit-maqa-github-projects/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.3.0"
+      },
+      "provides": {
+        "commands": 2,
+        "hooks": 0
+      },
+      "tags": [
+        "github-projects",
+        "project-management",
+        "multi-agent",
+        "maqa",
+        "kanban"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-03-27T00:00:00Z",
+      "updated_at": "2026-03-27T00:00:00Z"
+    },
+    "maqa-jira": {
+      "name": "MAQA Jira Integration",
+      "id": "maqa-jira",
+      "description": "Jira integration for the MAQA extension. Populates Stories from specs, moves issues across board columns as features progress, real-time Subtask ticking.",
+      "author": "GenieRobot",
+      "version": "0.1.0",
+      "download_url": "https://github.com/GenieRobot/spec-kit-maqa-jira/releases/download/maqa-jira-v0.1.0/maqa-jira.zip",
+      "repository": "https://github.com/GenieRobot/spec-kit-maqa-jira",
+      "homepage": "https://github.com/GenieRobot/spec-kit-maqa-jira",
+      "documentation": "https://github.com/GenieRobot/spec-kit-maqa-jira/blob/main/README.md",
+      "changelog": "https://github.com/GenieRobot/spec-kit-maqa-jira/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.3.0"
+      },
+      "provides": {
+        "commands": 2,
+        "hooks": 0
+      },
+      "tags": [
+        "jira",
+        "project-management",
+        "multi-agent",
+        "maqa",
+        "kanban"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-03-27T00:00:00Z",
+      "updated_at": "2026-03-27T00:00:00Z"
+    },
+    "maqa-linear": {
+      "name": "MAQA Linear Integration",
+      "id": "maqa-linear",
+      "description": "Linear integration for the MAQA extension. Populates issues from specs, moves items across workflow states as features progress, real-time sub-issue ticking.",
+      "author": "GenieRobot",
+      "version": "0.1.0",
+      "download_url": "https://github.com/GenieRobot/spec-kit-maqa-linear/releases/download/maqa-linear-v0.1.0/maqa-linear.zip",
+      "repository": "https://github.com/GenieRobot/spec-kit-maqa-linear",
+      "homepage": "https://github.com/GenieRobot/spec-kit-maqa-linear",
+      "documentation": "https://github.com/GenieRobot/spec-kit-maqa-linear/blob/main/README.md",
+      "changelog": "https://github.com/GenieRobot/spec-kit-maqa-linear/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.3.0"
+      },
+      "provides": {
+        "commands": 2,
+        "hooks": 0
+      },
+      "tags": [
+        "linear",
+        "project-management",
+        "multi-agent",
+        "maqa",
+        "kanban"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-03-27T00:00:00Z",
+      "updated_at": "2026-03-27T00:00:00Z"
+    },
+    "maqa-trello": {
+      "name": "MAQA Trello Integration",
+      "id": "maqa-trello",
+      "description": "Trello board integration for the MAQA extension. Populates board from specs, moves cards between lists as features progress, real-time checklist ticking.",
+      "author": "GenieRobot",
+      "version": "0.1.1",
+      "download_url": "https://github.com/GenieRobot/spec-kit-maqa-trello/releases/download/maqa-trello-v0.1.1/maqa-trello.zip",
+      "repository": "https://github.com/GenieRobot/spec-kit-maqa-trello",
+      "homepage": "https://github.com/GenieRobot/spec-kit-maqa-trello",
+      "documentation": "https://github.com/GenieRobot/spec-kit-maqa-trello/blob/main/README.md",
+      "changelog": "https://github.com/GenieRobot/spec-kit-maqa-trello/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.3.0"
+      },
+      "provides": {
+        "commands": 2,
+        "hooks": 0
+      },
+      "tags": [
+        "trello",
+        "project-management",
+        "multi-agent",
+        "maqa",
+        "kanban"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-03-26T00:00:00Z",
+      "updated_at": "2026-03-26T00:00:00Z"
+    },
+    "onboard": {
+      "name": "Onboard",
+      "id": "onboard",
+      "description": "Contextual onboarding and progressive growth for developers new to spec-kit projects. Explains specs, maps dependencies, validates understanding, and guides the next step.",
+      "author": "Rafael Sales",
+      "version": "2.1.0",
+      "download_url": "https://github.com/dmux/spec-kit-onboard/archive/refs/tags/v2.1.0.zip",
+      "repository": "https://github.com/dmux/spec-kit-onboard",
+      "homepage": "https://github.com/dmux/spec-kit-onboard",
+      "documentation": "https://github.com/dmux/spec-kit-onboard/blob/main/README.md",
+      "changelog": "https://github.com/dmux/spec-kit-onboard/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.1.0"
+      },
+      "provides": {
+        "commands": 7,
+        "hooks": 3
+      },
+      "tags": [
+        "onboarding",
+        "learning",
+        "mentoring",
+        "developer-experience",
+        "gamification",
+        "knowledge-transfer"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-03-26T00:00:00Z",
+      "updated_at": "2026-03-26T00:00:00Z"
+    },
+    "plan-review-gate": {
+      "name": "Plan Review Gate",
+      "id": "plan-review-gate",
+      "description": "Require spec.md and plan.md to be merged via MR/PR before allowing task generation",
+      "author": "luno",
+      "version": "1.0.0",
+      "download_url": "https://github.com/luno/spec-kit-plan-review-gate/archive/refs/tags/v1.0.0.zip",
+      "repository": "https://github.com/luno/spec-kit-plan-review-gate",
+      "homepage": "https://github.com/luno/spec-kit-plan-review-gate",
+      "documentation": "https://github.com/luno/spec-kit-plan-review-gate/blob/main/README.md",
+      "changelog": "https://github.com/luno/spec-kit-plan-review-gate/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.1.0"
+      },
+      "provides": {
+        "commands": 1,
+        "hooks": 1
+      },
+      "tags": [
+        "review",
+        "quality",
+        "workflow",
+        "gate"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-03-27T08:22:30Z",
+      "updated_at": "2026-03-27T08:22:30Z"
+    },
+    "presetify": {
+      "name": "Presetify",
+      "id": "presetify",
+      "description": "Create and validate presets and preset catalogs.",
+      "author": "mnriem",
+      "version": "1.0.0",
+      "download_url": "https://github.com/mnriem/spec-kit-extensions/releases/download/presetify-v1.0.0/presetify.zip",
+      "repository": "https://github.com/mnriem/spec-kit-extensions",
+      "homepage": "https://github.com/mnriem/spec-kit-extensions",
+      "documentation": "https://github.com/mnriem/spec-kit-extensions/blob/main/presetify/README.md",
+      "changelog": "https://github.com/mnriem/spec-kit-extensions/blob/main/presetify/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.2.0"
+      },
+      "provides": {
+        "commands": 4,
+        "hooks": 0
+      },
+      "tags": [
+        "presets",
+        "workflow",
+        "templates",
+        "experimental"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-03-18T00:00:00Z",
+      "updated_at": "2026-03-18T00:00:00Z"
+    },
+    "product-forge": {
+      "name": "Product Forge",
+      "id": "product-forge",
+      "description": "Full product lifecycle: research \u2192 product spec \u2192 SpecKit \u2192 implement \u2192 verify \u2192 test",
+      "author": "VaiYav",
+      "version": "1.1.1",
+      "download_url": "https://github.com/VaiYav/speckit-product-forge/archive/refs/tags/v1.1.1.zip",
+      "repository": "https://github.com/VaiYav/speckit-product-forge",
+      "homepage": "https://github.com/VaiYav/speckit-product-forge",
+      "documentation": "https://github.com/VaiYav/speckit-product-forge/blob/main/README.md",
+      "changelog": "https://github.com/VaiYav/speckit-product-forge/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.1.0"
+      },
+      "provides": {
+        "commands": 10,
+        "hooks": 0
+      },
+      "tags": [
+        "process",
+        "research",
+        "product-spec",
+        "lifecycle",
+        "testing"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-03-28T00:00:00Z",
+      "updated_at": "2026-03-28T00:00:00Z"
+    },
     "ralph": {
       "name": "Ralph Loop",
       "id": "ralph",
@@ -422,6 +959,113 @@
       "created_at": "2026-03-06T00:00:00Z",
       "updated_at": "2026-03-06T00:00:00Z"
     },
+    "speckit-utils": {
+      "name": "SDD Utilities",
+      "id": "speckit-utils",
+      "description": "Resume interrupted workflows, validate project health, and verify spec-to-task traceability.",
+      "author": "mvanhorn",
+      "version": "1.0.0",
+      "download_url": "https://github.com/mvanhorn/speckit-utils/archive/refs/tags/v1.0.0.zip",
+      "repository": "https://github.com/mvanhorn/speckit-utils",
+      "homepage": "https://github.com/mvanhorn/speckit-utils",
+      "documentation": "https://github.com/mvanhorn/speckit-utils/blob/main/README.md",
+      "changelog": "https://github.com/mvanhorn/speckit-utils/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.1.0"
+      },
+      "provides": {
+        "commands": 3,
+        "hooks": 2
+      },
+      "tags": [
+        "resume",
+        "doctor",
+        "validate",
+        "workflow",
+        "health-check"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-03-18T00:00:00Z",
+      "updated_at": "2026-03-18T00:00:00Z"
+    },
+    "status": {
+      "name": "Project Status",
+      "id": "status",
+      "description": "Show current SDD workflow progress — active feature, artifact status, task completion, workflow phase, and extensions summary.",
+      "author": "KhawarHabibKhan",
+      "version": "1.0.0",
+      "download_url": "https://github.com/KhawarHabibKhan/spec-kit-status/archive/refs/tags/v1.0.0.zip",
+      "repository": "https://github.com/KhawarHabibKhan/spec-kit-status",
+      "homepage": "https://github.com/KhawarHabibKhan/spec-kit-status",
+      "documentation": "https://github.com/KhawarHabibKhan/spec-kit-status/blob/main/README.md",
+      "changelog": "https://github.com/KhawarHabibKhan/spec-kit-status/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.1.0"
+      },
+      "provides": {
+        "commands": 1,
+        "hooks": 0
+      },
+      "tags": [
+        "status",
+        "workflow",
+        "progress",
+        "feature-tracking",
+        "task-progress"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-03-16T00:00:00Z",
+      "updated_at": "2026-03-16T00:00:00Z"
+    },
+    "superb": {
+      "name": "Superpowers Bridge",
+      "id": "superb",
+      "description": "Orchestrates obra/superpowers skills within the spec-kit SDD workflow. Thin bridge commands delegate to superpowers' authoritative SKILL.md files at runtime (with graceful fallback), while bridge-original commands provide spec-kit-native value. Eight commands cover the full lifecycle: intent clarification, TDD enforcement, task review, verification, critique, systematic debugging, branch completion, and review response. Hook-bound commands fire automatically; standalone commands are invoked when needed.",
+      "author": "rbbtsn0w",
+      "version": "1.0.0",
+      "download_url": "https://github.com/RbBtSn0w/spec-kit-extensions/releases/download/superpowers-bridge-v1.0.0/superpowers-bridge.zip",
+      "repository": "https://github.com/RbBtSn0w/spec-kit-extensions",
+      "homepage": "https://github.com/RbBtSn0w/spec-kit-extensions",
+      "documentation": "https://github.com/RbBtSn0w/spec-kit-extensions/blob/main/superpowers-bridge/README.md",
+      "changelog": "https://github.com/RbBtSn0w/spec-kit-extensions/blob/main/superpowers-bridge/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.4.3",
+        "tools": [
+          {
+            "name": "superpowers",
+            "version": ">=5.0.0",
+            "required": false
+          }
+        ]
+      },
+      "provides": {
+        "commands": 8,
+        "hooks": 4
+      },
+      "tags": [
+        "methodology",
+        "tdd",
+        "code-review",
+        "workflow",
+        "superpowers",
+        "brainstorming",
+        "verification",
+        "debugging",
+        "branch-management"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-03-30T00:00:00Z",
+      "updated_at": "2026-03-30T00:00:00Z"
+    },
     "sync": {
       "name": "Spec Sync",
       "id": "sync",
@@ -457,7 +1101,7 @@
     "understanding": {
       "name": "Understanding",
       "id": "understanding",
-      "description": "Automated requirements quality analysis \u2014 validates specs against IEEE/ISO standards using 31 deterministic metrics. Catches ambiguity, missing testability, and structural issues before they reach implementation. Includes experimental energy-based ambiguity detection using local LM token perplexity.",
+      "description": "Automated requirements quality analysis — validates specs against IEEE/ISO standards using 31 deterministic metrics. Catches ambiguity, missing testability, and structural issues before they reach implementation. Includes experimental energy-based ambiguity detection using local LM token perplexity.",
       "author": "Ladislav Bihari",
       "version": "3.4.0",
       "download_url": "https://github.com/Testimonial/understanding/archive/refs/tags/v3.4.0.zip",
@@ -495,38 +1139,6 @@
       "created_at": "2026-03-07T00:00:00Z",
       "updated_at": "2026-03-07T00:00:00Z"
     },
-    "status": {
-      "name": "Project Status",
-      "id": "status",
-      "description": "Show current SDD workflow progress — active feature, artifact status, task completion, workflow phase, and extensions summary.",
-      "author": "KhawarHabibKhan",
-      "version": "1.0.0",
-      "download_url": "https://github.com/KhawarHabibKhan/spec-kit-status/archive/refs/tags/v1.0.0.zip",
-      "repository": "https://github.com/KhawarHabibKhan/spec-kit-status",
-      "homepage": "https://github.com/KhawarHabibKhan/spec-kit-status",
-      "documentation": "https://github.com/KhawarHabibKhan/spec-kit-status/blob/main/README.md",
-      "changelog": "https://github.com/KhawarHabibKhan/spec-kit-status/blob/main/CHANGELOG.md",
-      "license": "MIT",
-      "requires": {
-        "speckit_version": ">=0.1.0"
-      },
-      "provides": {
-        "commands": 1,
-        "hooks": 0
-      },
-      "tags": [
-        "status",
-        "workflow",
-        "progress",
-        "feature-tracking",
-        "task-progress"
-      ],
-      "verified": false,
-      "downloads": 0,
-      "stars": 0,
-      "created_at": "2026-03-16T00:00:00Z",
-      "updated_at": "2026-03-16T00:00:00Z"
-    },
     "v-model": {
       "name": "V-Model Extension Pack",
       "id": "v-model",
@@ -590,6 +1202,37 @@
       "stars": 0,
       "created_at": "2026-03-03T00:00:00Z",
       "updated_at": "2026-03-03T00:00:00Z"
+    },
+    "verify-tasks": {
+      "name": "Verify Tasks Extension",
+      "id": "verify-tasks",
+      "description": "Detect phantom completions: tasks marked [X] in tasks.md with no real implementation.",
+      "author": "Dave Sharpe",
+      "version": "1.0.0",
+      "download_url": "https://github.com/datastone-inc/spec-kit-verify-tasks/archive/refs/tags/v1.0.0.zip",
+      "repository": "https://github.com/datastone-inc/spec-kit-verify-tasks",
+      "homepage": "https://github.com/datastone-inc/spec-kit-verify-tasks",
+      "documentation": "https://github.com/datastone-inc/spec-kit-verify-tasks/blob/main/README.md",
+      "changelog": "https://github.com/datastone-inc/spec-kit-verify-tasks/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.1.0"
+      },
+      "provides": {
+        "commands": 1,
+        "hooks": 1
+      },
+      "tags": [
+        "verification",
+        "quality",
+        "phantom-completion",
+        "tasks"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-03-16T00:00:00Z",
+      "updated_at": "2026-03-16T00:00:00Z"
     }
   }
 }

extensions/template/extension.yml

@@ -47,8 +47,8 @@ provides:
     - name: "speckit.my-extension.example"
       file: "commands/example.md"
       description: "Example command that demonstrates functionality"
-      # Optional: Add aliases for shorter command names
-      aliases: ["speckit.example"]
+      # Optional: Add aliases in the same namespaced format
+      aliases: ["speckit.my-extension.example-short"]
 
     # ADD MORE COMMANDS: Copy this block for each command
     # - name: "speckit.my-extension.another-command"

presets/README.md

@@ -13,13 +13,15 @@ When Spec Kit needs a template (e.g. `spec-template`), it walks a resolution sta
 
 If no preset is installed, core templates are used — exactly the same behavior as before presets existed.
 
+Template resolution happens **at runtime** — although preset files are copied into `.specify/presets/<id>/` during installation, Spec Kit walks the resolution stack on every template lookup rather than merging templates into a single location.
+
 For detailed resolution and command registration flows, see [ARCHITECTURE.md](ARCHITECTURE.md).
 
 ## Command Overrides
 
 Presets can also override the commands that guide the SDD workflow. Templates define *what* gets produced (specs, plans, constitutions); commands define *how* the LLM produces them (the step-by-step instructions).
 
-When a preset includes `type: "command"` entries, the commands are automatically registered into all detected agent directories (`.claude/commands/`, `.gemini/commands/`, etc.) in the correct format (Markdown or TOML with appropriate argument placeholders). When the preset is removed, the registered commands are cleaned up.
+Unlike templates, command overrides are applied **at install time**. When a preset includes `type: "command"` entries, the commands are registered into all detected agent directories (`.claude/commands/`, `.gemini/commands/`, etc.) in the correct format (Markdown or TOML with appropriate argument placeholders). When the preset is removed, the registered commands are cleaned up.
 
 ## Quick Start
 

presets/catalog.community.json

@@ -1,6 +1,58 @@
 {
   "schema_version": "1.0",
-  "updated_at": "2026-03-09T00:00:00Z",
+  "updated_at": "2026-03-24T00:00:00Z",
   "catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/presets/catalog.community.json",
-  "presets": {}
+  "presets": {
+    "aide-in-place": {
+      "name": "AIDE In-Place Migration",
+      "id": "aide-in-place",
+      "version": "1.0.0",
+      "description": "Adapts the AIDE workflow for in-place technology migrations (X → Y pattern). Overrides vision, roadmap, progress, and work item commands with migration-specific guidance.",
+      "author": "mnriem",
+      "repository": "https://github.com/mnriem/spec-kit-presets",
+      "download_url": "https://github.com/mnriem/spec-kit-presets/releases/download/aide-in-place-v1.0.0/aide-in-place.zip",
+      "homepage": "https://github.com/mnriem/spec-kit-presets",
+      "documentation": "https://github.com/mnriem/spec-kit-presets/blob/main/aide-in-place/README.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.2.0",
+        "extensions": ["aide"]
+      },
+      "provides": {
+        "templates": 2,
+        "commands": 8
+      },
+      "tags": [
+        "migration",
+        "in-place",
+        "brownfield",
+        "aide"
+      ]
+    },
+    "pirate": {
+      "name": "Pirate Speak (Full)",
+      "id": "pirate",
+      "version": "1.0.0",
+      "description": "Arrr! Transforms all Spec Kit output into pirate speak. Specs, plans, and tasks be written fer scallywags.",
+      "author": "mnriem",
+      "repository": "https://github.com/mnriem/spec-kit-presets",
+      "download_url": "https://github.com/mnriem/spec-kit-presets/releases/download/pirate-v1.0.0/pirate.zip",
+      "homepage": "https://github.com/mnriem/spec-kit-presets",
+      "documentation": "https://github.com/mnriem/spec-kit-presets/blob/main/pirate/README.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.1.0"
+      },
+      "provides": {
+        "templates": 6,
+        "commands": 9
+      },
+      "tags": [
+        "pirate",
+        "theme",
+        "fun",
+        "experimental"
+      ]
+    }
+  }
 }

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "specify-cli"
-version = "0.3.0"
+version = "0.4.4.dev0"
 description = "Specify CLI, part of GitHub Spec Kit. A tool to bootstrap your projects for Spec-Driven Development (SDD)."
 requires-python = ">=3.11"
 dependencies = [
@@ -14,6 +14,7 @@ dependencies = [
     "pyyaml>=6.0",
     "packaging>=23.0",
     "pathspec>=0.12.0",
+    "json5>=0.13.0",
 ]
 
 [project.scripts]
@@ -26,6 +27,23 @@ build-backend = "hatchling.build"
 [tool.hatch.build.targets.wheel]
 packages = ["src/specify_cli"]
 
+[tool.hatch.build.targets.wheel.force-include]
+# Bundle core assets so `specify init` works without network access (air-gapped / enterprise)
+# Page templates (exclude commands/ — bundled separately below to avoid duplication)
+"templates/agent-file-template.md" = "specify_cli/core_pack/templates/agent-file-template.md"
+"templates/checklist-template.md" = "specify_cli/core_pack/templates/checklist-template.md"
+"templates/constitution-template.md" = "specify_cli/core_pack/templates/constitution-template.md"
+"templates/plan-template.md" = "specify_cli/core_pack/templates/plan-template.md"
+"templates/spec-template.md" = "specify_cli/core_pack/templates/spec-template.md"
+"templates/tasks-template.md" = "specify_cli/core_pack/templates/tasks-template.md"
+"templates/vscode-settings.json" = "specify_cli/core_pack/templates/vscode-settings.json"
+# Command templates
+"templates/commands" = "specify_cli/core_pack/commands"
+"scripts/bash" = "specify_cli/core_pack/scripts/bash"
+"scripts/powershell" = "specify_cli/core_pack/scripts/powershell"
+".github/workflows/scripts/create-release-packages.sh" = "specify_cli/core_pack/release_scripts/create-release-packages.sh"
+".github/workflows/scripts/create-release-packages.ps1" = "specify_cli/core_pack/release_scripts/create-release-packages.ps1"
+
 [project.optional-dependencies]
 test = [
     "pytest>=7.0",

scripts/bash/common.sh

@@ -1,15 +1,48 @@
 #!/usr/bin/env bash
 # Common functions and variables for all scripts
 
-# Get repository root, with fallback for non-git repositories
+# Find repository root by searching upward for .specify directory
+# This is the primary marker for spec-kit projects
+find_specify_root() {
+    local dir="${1:-$(pwd)}"
+    # Normalize to absolute path to prevent infinite loop with relative paths
+    # Use -- to handle paths starting with - (e.g., -P, -L)
+    dir="$(cd -- "$dir" 2>/dev/null && pwd)" || return 1
+    local prev_dir=""
+    while true; do
+        if [ -d "$dir/.specify" ]; then
+            echo "$dir"
+            return 0
+        fi
+        # Stop if we've reached filesystem root or dirname stops changing
+        if [ "$dir" = "/" ] || [ "$dir" = "$prev_dir" ]; then
+            break
+        fi
+        prev_dir="$dir"
+        dir="$(dirname "$dir")"
+    done
+    return 1
+}
+
+# Get repository root, prioritizing .specify directory over git
+# This prevents using a parent git repo when spec-kit is initialized in a subdirectory
 get_repo_root() {
+    # First, look for .specify directory (spec-kit's own marker)
+    local specify_root
+    if specify_root=$(find_specify_root); then
+        echo "$specify_root"
+        return
+    fi
+
+    # Fallback to git if no .specify found
     if git rev-parse --show-toplevel >/dev/null 2>&1; then
         git rev-parse --show-toplevel
-    else
-        # Fall back to script location for non-git repos
-        local script_dir="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-        (cd "$script_dir/../../.." && pwd)
+        return
     fi
+
+    # Final fallback to script location for non-git repos
+    local script_dir="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    (cd "$script_dir/../../.." && pwd)
 }
 
 # Get current branch, with fallback for non-git repositories
@@ -20,29 +53,40 @@ get_current_branch() {
         return
     fi
 
-    # Then check git if available
-    if git rev-parse --abbrev-ref HEAD >/dev/null 2>&1; then
-        git rev-parse --abbrev-ref HEAD
+    # Then check git if available at the spec-kit root (not parent)
+    local repo_root=$(get_repo_root)
+    if has_git; then
+        git -C "$repo_root" rev-parse --abbrev-ref HEAD
         return
     fi
 
     # For non-git repos, try to find the latest feature directory
-    local repo_root=$(get_repo_root)
     local specs_dir="$repo_root/specs"
 
     if [[ -d "$specs_dir" ]]; then
         local latest_feature=""
         local highest=0
+        local latest_timestamp=""
 
         for dir in "$specs_dir"/*; do
             if [[ -d "$dir" ]]; then
                 local dirname=$(basename "$dir")
-                if [[ "$dirname" =~ ^([0-9]{3})- ]]; then
+                if [[ "$dirname" =~ ^([0-9]{8}-[0-9]{6})- ]]; then
+                    # Timestamp-based branch: compare lexicographically
+                    local ts="${BASH_REMATCH[1]}"
+                    if [[ "$ts" > "$latest_timestamp" ]]; then
+                        latest_timestamp="$ts"
+                        latest_feature=$dirname
+                    fi
+                elif [[ "$dirname" =~ ^([0-9]{3})- ]]; then
                     local number=${BASH_REMATCH[1]}
                     number=$((10#$number))
                     if [[ "$number" -gt "$highest" ]]; then
                         highest=$number
-                        latest_feature=$dirname
+                        # Only update if no timestamp branch found yet
+                        if [[ -z "$latest_timestamp" ]]; then
+                            latest_feature=$dirname
+                        fi
                     fi
                 fi
             fi
@@ -57,9 +101,17 @@ get_current_branch() {
     echo "main"  # Final fallback
 }
 
-# Check if we have git available
+# Check if we have git available at the spec-kit root level
+# Returns true only if git is installed and the repo root is inside a git work tree
+# Handles both regular repos (.git directory) and worktrees/submodules (.git file)
 has_git() {
-    git rev-parse --show-toplevel >/dev/null 2>&1
+    # First check if git command is available (before calling get_repo_root which may use git)
+    command -v git >/dev/null 2>&1 || return 1
+    local repo_root=$(get_repo_root)
+    # Check if .git exists (directory or file for worktrees/submodules)
+    [ -e "$repo_root/.git" ] || return 1
+    # Verify it's actually a valid git work tree
+    git -C "$repo_root" rev-parse --is-inside-work-tree >/dev/null 2>&1
 }
 
 check_feature_branch() {
@@ -72,9 +124,9 @@ check_feature_branch() {
         return 0
     fi
 
-    if [[ ! "$branch" =~ ^[0-9]{3}- ]]; then
+    if [[ ! "$branch" =~ ^[0-9]{3}- ]] && [[ ! "$branch" =~ ^[0-9]{8}-[0-9]{6}- ]]; then
         echo "ERROR: Not on a feature branch. Current branch: $branch" >&2
-        echo "Feature branches should be named like: 001-feature-name" >&2
+        echo "Feature branches should be named like: 001-feature-name or 20260319-143022-feature-name" >&2
         return 1
     fi
 
@@ -90,15 +142,18 @@ find_feature_dir_by_prefix() {
     local branch_name="$2"
     local specs_dir="$repo_root/specs"
 
-    # Extract numeric prefix from branch (e.g., "004" from "004-whatever")
-    if [[ ! "$branch_name" =~ ^([0-9]{3})- ]]; then
-        # If branch doesn't have numeric prefix, fall back to exact match
+    # Extract prefix from branch (e.g., "004" from "004-whatever" or "20260319-143022" from timestamp branches)
+    local prefix=""
+    if [[ "$branch_name" =~ ^([0-9]{8}-[0-9]{6})- ]]; then
+        prefix="${BASH_REMATCH[1]}"
+    elif [[ "$branch_name" =~ ^([0-9]{3})- ]]; then
+        prefix="${BASH_REMATCH[1]}"
+    else
+        # If branch doesn't have a recognized prefix, fall back to exact match
         echo "$specs_dir/$branch_name"
         return
     fi
 
-    local prefix="${BASH_REMATCH[1]}"
-
     # Search for directories in specs/ that start with this prefix
     local matches=()
     if [[ -d "$specs_dir" ]]; then
@@ -119,7 +174,7 @@ find_feature_dir_by_prefix() {
     else
         # Multiple matches - this shouldn't happen with proper naming convention
         echo "ERROR: Multiple spec directories found with prefix '$prefix': ${matches[*]}" >&2
-        echo "Please ensure only one spec directory exists per numeric prefix." >&2
+        echo "Please ensure only one spec directory exists per prefix." >&2
         return 1
     fi
 }
@@ -171,9 +226,21 @@ json_escape() {
     s="${s//$'\r'/\\r}"
     s="${s//$'\b'/\\b}"
     s="${s//$'\f'/\\f}"
-    # Strip remaining control characters (U+0000–U+001F) not individually escaped above
-    s=$(printf '%s' "$s" | tr -d '\000-\007\013\016-\037')
-    printf '%s' "$s"
+    # Escape any remaining U+0001-U+001F control characters as \uXXXX.
+    # (U+0000/NUL cannot appear in bash strings and is excluded.)
+    # LC_ALL=C ensures ${#s} counts bytes and ${s:$i:1} yields single bytes,
+    # so multi-byte UTF-8 sequences (first byte >= 0xC0) pass through intact.
+    local LC_ALL=C
+    local i char code
+    for (( i=0; i<${#s}; i++ )); do
+        char="${s:$i:1}"
+        printf -v code '%d' "'$char" 2>/dev/null || code=256
+        if (( code >= 1 && code <= 31 )); then
+            printf '\\u%04x' "$code"
+        else
+            printf '%s' "$char"
+        fi
+    done
 }
 
 check_file() { [[ -f "$1" ]] && echo "  ✓ $2" || echo "  ✗ $2"; }

scripts/bash/create-new-feature.sh

@@ -3,8 +3,10 @@
 set -e
 
 JSON_MODE=false
+ALLOW_EXISTING=false
 SHORT_NAME=""
 BRANCH_NUMBER=""
+USE_TIMESTAMP=false
 ARGS=()
 i=1
 while [ $i -le $# ]; do
@@ -13,6 +15,9 @@ while [ $i -le $# ]; do
         --json)
             JSON_MODE=true
             ;;
+        --allow-existing-branch)
+            ALLOW_EXISTING=true
+            ;;
         --short-name)
             if [ $((i + 1)) -gt $# ]; then
                 echo 'Error: --short-name requires a value' >&2
@@ -40,18 +45,24 @@ while [ $i -le $# ]; do
             fi
             BRANCH_NUMBER="$next_arg"
             ;;
+        --timestamp)
+            USE_TIMESTAMP=true
+            ;;
         --help|-h)
-            echo "Usage: $0 [--json] [--short-name <name>] [--number N] <feature_description>"
+            echo "Usage: $0 [--json] [--allow-existing-branch] [--short-name <name>] [--number N] [--timestamp] <feature_description>"
             echo ""
             echo "Options:"
             echo "  --json              Output in JSON format"
+            echo "  --allow-existing-branch  Switch to branch if it already exists instead of failing"
             echo "  --short-name <name> Provide a custom short name (2-4 words) for the branch"
             echo "  --number N          Specify branch number manually (overrides auto-detection)"
+            echo "  --timestamp         Use timestamp prefix (YYYYMMDD-HHMMSS) instead of sequential numbering"
             echo "  --help, -h          Show this help message"
             echo ""
             echo "Examples:"
             echo "  $0 'Add user authentication system' --short-name 'user-auth'"
             echo "  $0 'Implement OAuth2 integration for API' --number 5"
+            echo "  $0 --timestamp --short-name 'user-auth' 'Add user authentication'"
             exit 0
             ;;
         *)
@@ -63,7 +74,7 @@ done
 
 FEATURE_DESCRIPTION="${ARGS[*]}"
 if [ -z "$FEATURE_DESCRIPTION" ]; then
-    echo "Usage: $0 [--json] [--short-name <name>] [--number N] <feature_description>" >&2
+    echo "Usage: $0 [--json] [--allow-existing-branch] [--short-name <name>] [--number N] [--timestamp] <feature_description>" >&2
     exit 1
 fi
 
@@ -74,19 +85,6 @@ if [ -z "$FEATURE_DESCRIPTION" ]; then
     exit 1
 fi
 
-# Function to find the repository root by searching for existing project markers
-find_repo_root() {
-    local dir="$1"
-    while [ "$dir" != "/" ]; do
-        if [ -d "$dir/.git" ] || [ -d "$dir/.specify" ]; then
-            echo "$dir"
-            return 0
-        fi
-        dir="$(dirname "$dir")"
-    done
-    return 1
-}
-
 # Function to get highest number from specs directory
 get_highest_from_specs() {
     local specs_dir="$1"
@@ -96,10 +94,13 @@ get_highest_from_specs() {
         for dir in "$specs_dir"/*; do
             [ -d "$dir" ] || continue
             dirname=$(basename "$dir")
-            number=$(echo "$dirname" | grep -o '^[0-9]\+' || echo "0")
-            number=$((10#$number))
-            if [ "$number" -gt "$highest" ]; then
-                highest=$number
+            # Match sequential prefixes (>=3 digits), but skip timestamp dirs.
+            if echo "$dirname" | grep -Eq '^[0-9]{3,}-' && ! echo "$dirname" | grep -Eq '^[0-9]{8}-[0-9]{6}-'; then
+                number=$(echo "$dirname" | grep -Eo '^[0-9]+')
+                number=$((10#$number))
+                if [ "$number" -gt "$highest" ]; then
+                    highest=$number
+                fi
             fi
         done
     fi
@@ -119,9 +120,9 @@ get_highest_from_branches() {
             # Clean branch name: remove leading markers and remote prefixes
             clean_branch=$(echo "$branch" | sed 's/^[* ]*//; s|^remotes/[^/]*/||')
             
-            # Extract feature number if branch matches pattern ###-*
-            if echo "$clean_branch" | grep -q '^[0-9]\{3\}-'; then
-                number=$(echo "$clean_branch" | grep -o '^[0-9]\{3\}' || echo "0")
+            # Extract sequential feature number (>=3 digits), skip timestamp branches.
+            if echo "$clean_branch" | grep -Eq '^[0-9]{3,}-' && ! echo "$clean_branch" | grep -Eq '^[0-9]{8}-[0-9]{6}-'; then
+                number=$(echo "$clean_branch" | grep -Eo '^[0-9]+' || echo "0")
                 number=$((10#$number))
                 if [ "$number" -gt "$highest" ]; then
                     highest=$number
@@ -138,7 +139,7 @@ check_existing_branches() {
     local specs_dir="$1"
 
     # Fetch all remotes to get latest branch info (suppress errors if no remotes)
-    git fetch --all --prune 2>/dev/null || true
+    git fetch --all --prune >/dev/null 2>&1 || true
 
     # Get highest number from ALL branches (not just matching short name)
     local highest_branch=$(get_highest_from_branches)
@@ -162,21 +163,16 @@ clean_branch_name() {
     echo "$name" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/-\+/-/g' | sed 's/^-//' | sed 's/-$//'
 }
 
-# Resolve repository root. Prefer git information when available, but fall back
-# to searching for repository markers so the workflow still functions in repositories that
-# were initialised with --no-git.
+# Resolve repository root using common.sh functions which prioritize .specify over git
 SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/common.sh"
 
-if git rev-parse --show-toplevel >/dev/null 2>&1; then
-    REPO_ROOT=$(git rev-parse --show-toplevel)
+REPO_ROOT=$(get_repo_root)
+
+# Check if git is available at this repo root (not a parent)
+if has_git; then
     HAS_GIT=true
 else
-    REPO_ROOT="$(find_repo_root "$SCRIPT_DIR")"
-    if [ -z "$REPO_ROOT" ]; then
-        echo "Error: Could not determine repository root. Please run this script from within the repository." >&2
-        exit 1
-    fi
     HAS_GIT=false
 fi
 
@@ -242,29 +238,42 @@ else
     BRANCH_SUFFIX=$(generate_branch_name "$FEATURE_DESCRIPTION")
 fi
 
-# Determine branch number
-if [ -z "$BRANCH_NUMBER" ]; then
-    if [ "$HAS_GIT" = true ]; then
-        # Check existing branches on remotes
-        BRANCH_NUMBER=$(check_existing_branches "$SPECS_DIR")
-    else
-        # Fall back to local directory check
-        HIGHEST=$(get_highest_from_specs "$SPECS_DIR")
-        BRANCH_NUMBER=$((HIGHEST + 1))
-    fi
+# Warn if --number and --timestamp are both specified
+if [ "$USE_TIMESTAMP" = true ] && [ -n "$BRANCH_NUMBER" ]; then
+    >&2 echo "[specify] Warning: --number is ignored when --timestamp is used"
+    BRANCH_NUMBER=""
 fi
 
-# Force base-10 interpretation to prevent octal conversion (e.g., 010 → 8 in octal, but should be 10 in decimal)
-FEATURE_NUM=$(printf "%03d" "$((10#$BRANCH_NUMBER))")
-BRANCH_NAME="${FEATURE_NUM}-${BRANCH_SUFFIX}"
+# Determine branch prefix
+if [ "$USE_TIMESTAMP" = true ]; then
+    FEATURE_NUM=$(date +%Y%m%d-%H%M%S)
+    BRANCH_NAME="${FEATURE_NUM}-${BRANCH_SUFFIX}"
+else
+    # Determine branch number
+    if [ -z "$BRANCH_NUMBER" ]; then
+        if [ "$HAS_GIT" = true ]; then
+            # Check existing branches on remotes
+            BRANCH_NUMBER=$(check_existing_branches "$SPECS_DIR")
+        else
+            # Fall back to local directory check
+            HIGHEST=$(get_highest_from_specs "$SPECS_DIR")
+            BRANCH_NUMBER=$((HIGHEST + 1))
+        fi
+    fi
+
+    # Force base-10 interpretation to prevent octal conversion (e.g., 010 → 8 in octal, but should be 10 in decimal)
+    FEATURE_NUM=$(printf "%03d" "$((10#$BRANCH_NUMBER))")
+    BRANCH_NAME="${FEATURE_NUM}-${BRANCH_SUFFIX}"
+fi
 
 # GitHub enforces a 244-byte limit on branch names
 # Validate and truncate if necessary
 MAX_BRANCH_LENGTH=244
 if [ ${#BRANCH_NAME} -gt $MAX_BRANCH_LENGTH ]; then
     # Calculate how much we need to trim from suffix
-    # Account for: feature number (3) + hyphen (1) = 4 chars
-    MAX_SUFFIX_LENGTH=$((MAX_BRANCH_LENGTH - 4))
+    # Account for prefix length: timestamp (15) + hyphen (1) = 16, or sequential (3) + hyphen (1) = 4
+    PREFIX_LENGTH=$(( ${#FEATURE_NUM} + 1 ))
+    MAX_SUFFIX_LENGTH=$((MAX_BRANCH_LENGTH - PREFIX_LENGTH))
     
     # Truncate suffix at word boundary if possible
     TRUNCATED_SUFFIX=$(echo "$BRANCH_SUFFIX" | cut -c1-$MAX_SUFFIX_LENGTH)
@@ -283,8 +292,19 @@ if [ "$HAS_GIT" = true ]; then
     if ! git checkout -b "$BRANCH_NAME" 2>/dev/null; then
         # Check if branch already exists
         if git branch --list "$BRANCH_NAME" | grep -q .; then
-            >&2 echo "Error: Branch '$BRANCH_NAME' already exists. Please use a different feature name or specify a different number with --number."
-            exit 1
+            if [ "$ALLOW_EXISTING" = true ]; then
+                # Switch to the existing branch instead of failing
+                if ! git checkout "$BRANCH_NAME" 2>/dev/null; then
+                    >&2 echo "Error: Failed to switch to existing branch '$BRANCH_NAME'. Please resolve any local changes or conflicts and try again."
+                    exit 1
+                fi
+            elif [ "$USE_TIMESTAMP" = true ]; then
+                >&2 echo "Error: Branch '$BRANCH_NAME' already exists. Rerun to get a new timestamp or use a different --short-name."
+                exit 1
+            else
+                >&2 echo "Error: Branch '$BRANCH_NAME' already exists. Please use a different feature name or specify a different number with --number."
+                exit 1
+            fi
         else
             >&2 echo "Error: Failed to create git branch '$BRANCH_NAME'. Please check your git configuration and try again."
             exit 1
@@ -297,13 +317,15 @@ fi
 FEATURE_DIR="$SPECS_DIR/$BRANCH_NAME"
 mkdir -p "$FEATURE_DIR"
 
-TEMPLATE=$(resolve_template "spec-template" "$REPO_ROOT") || true
 SPEC_FILE="$FEATURE_DIR/spec.md"
-if [ -n "$TEMPLATE" ] && [ -f "$TEMPLATE" ]; then
-    cp "$TEMPLATE" "$SPEC_FILE"
-else
-    echo "Warning: Spec template not found; created empty spec file" >&2
-    touch "$SPEC_FILE"
+if [ ! -f "$SPEC_FILE" ]; then
+    TEMPLATE=$(resolve_template "spec-template" "$REPO_ROOT") || true
+    if [ -n "$TEMPLATE" ] && [ -f "$TEMPLATE" ]; then
+        cp "$TEMPLATE" "$SPEC_FILE"
+    else
+        echo "Warning: Spec template not found; created empty spec file" >&2
+        touch "$SPEC_FILE"
+    fi
 fi
 
 # Inform the user how to persist the feature variable in their own shell

scripts/bash/update-agent-context.sh

@@ -30,12 +30,12 @@
 #
 # 5. Multi-Agent Support
 #    - Handles agent-specific file paths and naming conventions
-#    - Supports: Claude, Gemini, Copilot, Cursor, Qwen, opencode, Codex, Windsurf, Kilo Code, Auggie CLI, Roo Code, CodeBuddy CLI, Qoder CLI, Amp, SHAI, Tabnine CLI, Kiro CLI, Mistral Vibe, Kimi Code, Antigravity or Generic
+#    - Supports: Claude, Gemini, Copilot, Cursor, Qwen, opencode, Codex, Windsurf, Junie, Kilo Code, Auggie CLI, Roo Code, CodeBuddy CLI, Qoder CLI, Amp, SHAI, Tabnine CLI, Kiro CLI, Mistral Vibe, Kimi Code, Pi Coding Agent, iFlow CLI, Antigravity or Generic
 #    - Can update single agents or all existing agent files
 #    - Creates default Claude file if no agent files exist
 #
 # Usage: ./update-agent-context.sh [agent_type]
-# Agent types: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|amp|shai|tabnine|kiro-cli|agy|bob|vibe|qodercli|kimi|generic
+# Agent types: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|junie|kilocode|auggie|roo|codebuddy|amp|shai|tabnine|kiro-cli|agy|bob|vibe|qodercli|kimi|trae|pi|iflow|generic
 # Leave empty to update all existing agent files
 
 set -e
@@ -63,17 +63,18 @@ AGENT_TYPE="${1:-}"
 # Agent-specific file paths  
 CLAUDE_FILE="$REPO_ROOT/CLAUDE.md"
 GEMINI_FILE="$REPO_ROOT/GEMINI.md"
-COPILOT_FILE="$REPO_ROOT/.github/agents/copilot-instructions.md"
+COPILOT_FILE="$REPO_ROOT/.github/copilot-instructions.md"
 CURSOR_FILE="$REPO_ROOT/.cursor/rules/specify-rules.mdc"
 QWEN_FILE="$REPO_ROOT/QWEN.md"
 AGENTS_FILE="$REPO_ROOT/AGENTS.md"
 WINDSURF_FILE="$REPO_ROOT/.windsurf/rules/specify-rules.md"
+JUNIE_FILE="$REPO_ROOT/.junie/AGENTS.md"
 KILOCODE_FILE="$REPO_ROOT/.kilocode/rules/specify-rules.md"
 AUGGIE_FILE="$REPO_ROOT/.augment/rules/specify-rules.md"
 ROO_FILE="$REPO_ROOT/.roo/rules/specify-rules.md"
 CODEBUDDY_FILE="$REPO_ROOT/CODEBUDDY.md"
 QODER_FILE="$REPO_ROOT/QODER.md"
-# AMP, Kiro CLI, and IBM Bob all share AGENTS.md — use AGENTS_FILE to avoid
+# Amp, Kiro CLI, IBM Bob, and Pi all share AGENTS.md — use AGENTS_FILE to avoid
 # updating the same file multiple times.
 AMP_FILE="$AGENTS_FILE"
 SHAI_FILE="$REPO_ROOT/SHAI.md"
@@ -83,6 +84,8 @@ AGY_FILE="$REPO_ROOT/.agent/rules/specify-rules.md"
 BOB_FILE="$AGENTS_FILE"
 VIBE_FILE="$REPO_ROOT/.vibe/agents/specify-agents.md"
 KIMI_FILE="$REPO_ROOT/KIMI.md"
+TRAE_FILE="$REPO_ROOT/.trae/rules/AGENTS.md"
+IFLOW_FILE="$REPO_ROOT/IFLOW.md"
 
 # Template file
 TEMPLATE_FILE="$REPO_ROOT/.specify/templates/agent-file-template.md"
@@ -636,6 +639,9 @@ update_specific_agent() {
         windsurf)
             update_agent_file "$WINDSURF_FILE" "Windsurf" || return 1
             ;;
+        junie)
+            update_agent_file "$JUNIE_FILE" "Junie" || return 1
+            ;;
         kilocode)
             update_agent_file "$KILOCODE_FILE" "Kilo Code" || return 1
             ;;
@@ -675,12 +681,21 @@ update_specific_agent() {
         kimi)
             update_agent_file "$KIMI_FILE" "Kimi Code" || return 1
             ;;
+        trae)
+            update_agent_file "$TRAE_FILE" "Trae" || return 1
+            ;;
+        pi)
+            update_agent_file "$AGENTS_FILE" "Pi Coding Agent" || return 1
+            ;;
+        iflow)
+            update_agent_file "$IFLOW_FILE" "iFlow CLI" || return 1
+            ;;
         generic)
             log_info "Generic agent: no predefined context file. Use the agent-specific update script for your agent."
             ;;
         *)
             log_error "Unknown agent type '$agent_type'"
-            log_error "Expected: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|amp|shai|tabnine|kiro-cli|agy|bob|vibe|qodercli|kimi|generic"
+            log_error "Expected: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|junie|kilocode|auggie|roo|codebuddy|amp|shai|tabnine|kiro-cli|agy|bob|vibe|qodercli|kimi|trae|pi|iflow|generic"
             exit 1
             ;;
     esac
@@ -729,6 +744,7 @@ update_all_existing_agents() {
     _update_if_new "$KIRO_FILE" "Kiro CLI"                 || _all_ok=false
     _update_if_new "$BOB_FILE" "IBM Bob"                   || _all_ok=false
     _update_if_new "$WINDSURF_FILE" "Windsurf"             || _all_ok=false
+    _update_if_new "$JUNIE_FILE" "Junie"                || _all_ok=false
     _update_if_new "$KILOCODE_FILE" "Kilo Code"            || _all_ok=false
     _update_if_new "$AUGGIE_FILE" "Auggie CLI"             || _all_ok=false
     _update_if_new "$ROO_FILE" "Roo Code"                  || _all_ok=false
@@ -739,6 +755,8 @@ update_all_existing_agents() {
     _update_if_new "$AGY_FILE" "Antigravity"               || _all_ok=false
     _update_if_new "$VIBE_FILE" "Mistral Vibe"             || _all_ok=false
     _update_if_new "$KIMI_FILE" "Kimi Code"                || _all_ok=false
+    _update_if_new "$TRAE_FILE" "Trae"                     || _all_ok=false
+    _update_if_new "$IFLOW_FILE" "iFlow CLI"               || _all_ok=false
 
     # If no agent files exist, create a default Claude file
     if [[ "$_found_agent" == false ]]; then
@@ -765,7 +783,7 @@ print_summary() {
     fi
     
     echo
-    log_info "Usage: $0 [claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|amp|shai|tabnine|kiro-cli|agy|bob|vibe|qodercli|kimi|generic]"
+    log_info "Usage: $0 [claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|junie|kilocode|auggie|roo|codebuddy|amp|shai|tabnine|kiro-cli|agy|bob|vibe|qodercli|kimi|trae|pi|iflow|generic]"
 }
 
 #==============================================================================

scripts/powershell/common.ps1

@@ -1,7 +1,39 @@
 #!/usr/bin/env pwsh
 # Common PowerShell functions analogous to common.sh
 
+# Find repository root by searching upward for .specify directory
+# This is the primary marker for spec-kit projects
+function Find-SpecifyRoot {
+    param([string]$StartDir = (Get-Location).Path)
+
+    # Normalize to absolute path to prevent issues with relative paths
+    # Use -LiteralPath to handle paths with wildcard characters ([, ], *, ?)
+    $resolved = Resolve-Path -LiteralPath $StartDir -ErrorAction SilentlyContinue
+    $current = if ($resolved) { $resolved.Path } else { $null }
+    if (-not $current) { return $null }
+
+    while ($true) {
+        if (Test-Path -LiteralPath (Join-Path $current ".specify") -PathType Container) {
+            return $current
+        }
+        $parent = Split-Path $current -Parent
+        if ([string]::IsNullOrEmpty($parent) -or $parent -eq $current) {
+            return $null
+        }
+        $current = $parent
+    }
+}
+
+# Get repository root, prioritizing .specify directory over git
+# This prevents using a parent git repo when spec-kit is initialized in a subdirectory
 function Get-RepoRoot {
+    # First, look for .specify directory (spec-kit's own marker)
+    $specifyRoot = Find-SpecifyRoot
+    if ($specifyRoot) {
+        return $specifyRoot
+    }
+
+    # Fallback to git if no .specify found
     try {
         $result = git rev-parse --show-toplevel 2>$null
         if ($LASTEXITCODE -eq 0) {
@@ -11,8 +43,9 @@ function Get-RepoRoot {
         # Git command failed
     }
 
-    # Fall back to script location for non-git repos
-    return (Resolve-Path (Join-Path $PSScriptRoot "../../..")).Path
+    # Final fallback to script location for non-git repos
+    # Use -LiteralPath to handle paths with wildcard characters
+    return (Resolve-Path -LiteralPath (Join-Path $PSScriptRoot "../../..")).Path
 }
 
 function Get-CurrentBranch {
@@ -21,30 +54,43 @@ function Get-CurrentBranch {
         return $env:SPECIFY_FEATURE
     }
 
-    # Then check git if available
-    try {
-        $result = git rev-parse --abbrev-ref HEAD 2>$null
-        if ($LASTEXITCODE -eq 0) {
-            return $result
+    # Then check git if available at the spec-kit root (not parent)
+    $repoRoot = Get-RepoRoot
+    if (Test-HasGit) {
+        try {
+            $result = git -C $repoRoot rev-parse --abbrev-ref HEAD 2>$null
+            if ($LASTEXITCODE -eq 0) {
+                return $result
+            }
+        } catch {
+            # Git command failed
         }
-    } catch {
-        # Git command failed
     }
 
     # For non-git repos, try to find the latest feature directory
-    $repoRoot = Get-RepoRoot
     $specsDir = Join-Path $repoRoot "specs"
     
     if (Test-Path $specsDir) {
         $latestFeature = ""
         $highest = 0
+        $latestTimestamp = ""
 
         Get-ChildItem -Path $specsDir -Directory | ForEach-Object {
-            if ($_.Name -match '^(\d{3})-') {
+            if ($_.Name -match '^(\d{8}-\d{6})-') {
+                # Timestamp-based branch: compare lexicographically
+                $ts = $matches[1]
+                if ($ts -gt $latestTimestamp) {
+                    $latestTimestamp = $ts
+                    $latestFeature = $_.Name
+                }
+            } elseif ($_.Name -match '^(\d{3})-') {
                 $num = [int]$matches[1]
                 if ($num -gt $highest) {
                     $highest = $num
-                    $latestFeature = $_.Name
+                    # Only update if no timestamp branch found yet
+                    if (-not $latestTimestamp) {
+                        $latestFeature = $_.Name
+                    }
                 }
             }
         }
@@ -58,9 +104,23 @@ function Get-CurrentBranch {
     return "main"
 }
 
+# Check if we have git available at the spec-kit root level
+# Returns true only if git is installed and the repo root is inside a git work tree
+# Handles both regular repos (.git directory) and worktrees/submodules (.git file)
 function Test-HasGit {
+    # First check if git command is available (before calling Get-RepoRoot which may use git)
+    if (-not (Get-Command git -ErrorAction SilentlyContinue)) {
+        return $false
+    }
+    $repoRoot = Get-RepoRoot
+    # Check if .git exists (directory or file for worktrees/submodules)
+    # Use -LiteralPath to handle paths with wildcard characters
+    if (-not (Test-Path -LiteralPath (Join-Path $repoRoot ".git"))) {
+        return $false
+    }
+    # Verify it's actually a valid git work tree
     try {
-        git rev-parse --show-toplevel 2>$null | Out-Null
+        $null = git -C $repoRoot rev-parse --is-inside-work-tree 2>$null
         return ($LASTEXITCODE -eq 0)
     } catch {
         return $false
@@ -79,9 +139,9 @@ function Test-FeatureBranch {
         return $true
     }
     
-    if ($Branch -notmatch '^[0-9]{3}-') {
+    if ($Branch -notmatch '^[0-9]{3}-' -and $Branch -notmatch '^\d{8}-\d{6}-') {
         Write-Output "ERROR: Not on a feature branch. Current branch: $Branch"
-        Write-Output "Feature branches should be named like: 001-feature-name"
+        Write-Output "Feature branches should be named like: 001-feature-name or 20260319-143022-feature-name"
         return $false
     }
     return $true

scripts/powershell/create-new-feature.ps1

@@ -3,33 +3,39 @@
 [CmdletBinding()]
 param(
     [switch]$Json,
+    [switch]$AllowExistingBranch,
     [string]$ShortName,
-    [int]$Number = 0,
+    [Parameter()]
+    [long]$Number = 0,
+    [switch]$Timestamp,
     [switch]$Help,
-    [Parameter(ValueFromRemainingArguments = $true)]
+    [Parameter(Position = 0, ValueFromRemainingArguments = $true)]
     [string[]]$FeatureDescription
 )
 $ErrorActionPreference = 'Stop'
 
 # Show help if requested
 if ($Help) {
-    Write-Host "Usage: ./create-new-feature.ps1 [-Json] [-ShortName <name>] [-Number N] <feature description>"
+    Write-Host "Usage: ./create-new-feature.ps1 [-Json] [-AllowExistingBranch] [-ShortName <name>] [-Number N] [-Timestamp] <feature description>"
     Write-Host ""
     Write-Host "Options:"
     Write-Host "  -Json               Output in JSON format"
+    Write-Host "  -AllowExistingBranch  Switch to branch if it already exists instead of failing"
     Write-Host "  -ShortName <name>   Provide a custom short name (2-4 words) for the branch"
     Write-Host "  -Number N           Specify branch number manually (overrides auto-detection)"
+    Write-Host "  -Timestamp          Use timestamp prefix (YYYYMMDD-HHMMSS) instead of sequential numbering"
     Write-Host "  -Help               Show this help message"
     Write-Host ""
     Write-Host "Examples:"
     Write-Host "  ./create-new-feature.ps1 'Add user authentication system' -ShortName 'user-auth'"
     Write-Host "  ./create-new-feature.ps1 'Implement OAuth2 integration for API'"
+    Write-Host "  ./create-new-feature.ps1 -Timestamp -ShortName 'user-auth' 'Add user authentication'"
     exit 0
 }
 
 # Check if feature description provided
 if (-not $FeatureDescription -or $FeatureDescription.Count -eq 0) {
-    Write-Error "Usage: ./create-new-feature.ps1 [-Json] [-ShortName <name>] <feature description>"
+    Write-Error "Usage: ./create-new-feature.ps1 [-Json] [-AllowExistingBranch] [-ShortName <name>] [-Number N] [-Timestamp] <feature description>"
     exit 1
 }
 
@@ -41,39 +47,18 @@ if ([string]::IsNullOrWhiteSpace($featureDesc)) {
     exit 1
 }
 
-# Resolve repository root. Prefer git information when available, but fall back
-# to searching for repository markers so the workflow still functions in repositories that
-# were initialized with --no-git.
-function Find-RepositoryRoot {
-    param(
-        [string]$StartDir,
-        [string[]]$Markers = @('.git', '.specify')
-    )
-    $current = Resolve-Path $StartDir
-    while ($true) {
-        foreach ($marker in $Markers) {
-            if (Test-Path (Join-Path $current $marker)) {
-                return $current
-            }
-        }
-        $parent = Split-Path $current -Parent
-        if ($parent -eq $current) {
-            # Reached filesystem root without finding markers
-            return $null
-        }
-        $current = $parent
-    }
-}
-
 function Get-HighestNumberFromSpecs {
     param([string]$SpecsDir)
     
-    $highest = 0
+    [long]$highest = 0
     if (Test-Path $SpecsDir) {
         Get-ChildItem -Path $SpecsDir -Directory | ForEach-Object {
-            if ($_.Name -match '^(\d+)') {
-                $num = [int]$matches[1]
-                if ($num -gt $highest) { $highest = $num }
+            # Match sequential prefixes (>=3 digits), but skip timestamp dirs.
+            if ($_.Name -match '^(\d{3,})-' -and $_.Name -notmatch '^\d{8}-\d{6}-') {
+                [long]$num = 0
+                if ([long]::TryParse($matches[1], [ref]$num) -and $num -gt $highest) {
+                    $highest = $num
+                }
             }
         }
     }
@@ -83,7 +68,7 @@ function Get-HighestNumberFromSpecs {
 function Get-HighestNumberFromBranches {
     param()
     
-    $highest = 0
+    [long]$highest = 0
     try {
         $branches = git branch -a 2>$null
         if ($LASTEXITCODE -eq 0) {
@@ -91,10 +76,12 @@ function Get-HighestNumberFromBranches {
                 # Clean branch name: remove leading markers and remote prefixes
                 $cleanBranch = $branch.Trim() -replace '^\*?\s+', '' -replace '^remotes/[^/]+/', ''
                 
-                # Extract feature number if branch matches pattern ###-*
-                if ($cleanBranch -match '^(\d+)-') {
-                    $num = [int]$matches[1]
-                    if ($num -gt $highest) { $highest = $num }
+                # Extract sequential feature number (>=3 digits), skip timestamp branches.
+                if ($cleanBranch -match '^(\d{3,})-' -and $cleanBranch -notmatch '^\d{8}-\d{6}-') {
+                    [long]$num = 0
+                    if ([long]::TryParse($matches[1], [ref]$num) -and $num -gt $highest) {
+                        $highest = $num
+                    }
                 }
             }
         }
@@ -135,26 +122,14 @@ function ConvertTo-CleanBranchName {
     
     return $Name.ToLower() -replace '[^a-z0-9]', '-' -replace '-{2,}', '-' -replace '^-', '' -replace '-$', ''
 }
-$fallbackRoot = (Find-RepositoryRoot -StartDir $PSScriptRoot)
-if (-not $fallbackRoot) {
-    Write-Error "Error: Could not determine repository root. Please run this script from within the repository."
-    exit 1
-}
-
-# Load common functions (includes Resolve-Template)
+# Load common functions (includes Get-RepoRoot, Test-HasGit, Resolve-Template)
 . "$PSScriptRoot/common.ps1"
 
-try {
-    $repoRoot = git rev-parse --show-toplevel 2>$null
-    if ($LASTEXITCODE -eq 0) {
-        $hasGit = $true
-    } else {
-        throw "Git not available"
-    }
-} catch {
-    $repoRoot = $fallbackRoot
-    $hasGit = $false
-}
+# Use common.ps1 functions which prioritize .specify over git
+$repoRoot = Get-RepoRoot
+
+# Check if git is available at this repo root (not a parent)
+$hasGit = Test-HasGit
 
 Set-Location $repoRoot
 
@@ -215,27 +190,40 @@ if ($ShortName) {
     $branchSuffix = Get-BranchName -Description $featureDesc
 }
 
-# Determine branch number
-if ($Number -eq 0) {
-    if ($hasGit) {
-        # Check existing branches on remotes
-        $Number = Get-NextBranchNumber -SpecsDir $specsDir
-    } else {
-        # Fall back to local directory check
-        $Number = (Get-HighestNumberFromSpecs -SpecsDir $specsDir) + 1
-    }
+# Warn if -Number and -Timestamp are both specified
+if ($Timestamp -and $Number -ne 0) {
+    Write-Warning "[specify] Warning: -Number is ignored when -Timestamp is used"
+    $Number = 0
 }
 
-$featureNum = ('{0:000}' -f $Number)
-$branchName = "$featureNum-$branchSuffix"
+# Determine branch prefix
+if ($Timestamp) {
+    $featureNum = Get-Date -Format 'yyyyMMdd-HHmmss'
+    $branchName = "$featureNum-$branchSuffix"
+} else {
+    # Determine branch number
+    if ($Number -eq 0) {
+        if ($hasGit) {
+            # Check existing branches on remotes
+            $Number = Get-NextBranchNumber -SpecsDir $specsDir
+        } else {
+            # Fall back to local directory check
+            $Number = (Get-HighestNumberFromSpecs -SpecsDir $specsDir) + 1
+        }
+    }
+
+    $featureNum = ('{0:000}' -f $Number)
+    $branchName = "$featureNum-$branchSuffix"
+}
 
 # GitHub enforces a 244-byte limit on branch names
 # Validate and truncate if necessary
 $maxBranchLength = 244
 if ($branchName.Length -gt $maxBranchLength) {
     # Calculate how much we need to trim from suffix
-    # Account for: feature number (3) + hyphen (1) = 4 chars
-    $maxSuffixLength = $maxBranchLength - 4
+    # Account for prefix length: timestamp (15) + hyphen (1) = 16, or sequential (3) + hyphen (1) = 4
+    $prefixLength = $featureNum.Length + 1
+    $maxSuffixLength = $maxBranchLength - $prefixLength
     
     # Truncate suffix
     $truncatedSuffix = $branchSuffix.Substring(0, [Math]::Min($branchSuffix.Length, $maxSuffixLength))
@@ -265,8 +253,20 @@ if ($hasGit) {
         # Check if branch already exists
         $existingBranch = git branch --list $branchName 2>$null
         if ($existingBranch) {
-            Write-Error "Error: Branch '$branchName' already exists. Please use a different feature name or specify a different number with -Number."
-            exit 1
+            if ($AllowExistingBranch) {
+                # Switch to the existing branch instead of failing
+                git checkout -q $branchName 2>$null | Out-Null
+                if ($LASTEXITCODE -ne 0) {
+                    Write-Error "Error: Branch '$branchName' exists but could not be checked out. Resolve any uncommitted changes or conflicts and try again."
+                    exit 1
+                }
+            } elseif ($Timestamp) {
+                Write-Error "Error: Branch '$branchName' already exists. Rerun to get a new timestamp or use a different -ShortName."
+                exit 1
+            } else {
+                Write-Error "Error: Branch '$branchName' already exists. Please use a different feature name or specify a different number with -Number."
+                exit 1
+            }
         } else {
             Write-Error "Error: Failed to create git branch '$branchName'. Please check your git configuration and try again."
             exit 1
@@ -279,12 +279,14 @@ if ($hasGit) {
 $featureDir = Join-Path $specsDir $branchName
 New-Item -ItemType Directory -Path $featureDir -Force | Out-Null
 
-$template = Resolve-Template -TemplateName 'spec-template' -RepoRoot $repoRoot
 $specFile = Join-Path $featureDir 'spec.md'
-if ($template -and (Test-Path $template)) { 
-    Copy-Item $template $specFile -Force 
-} else { 
-    New-Item -ItemType File -Path $specFile | Out-Null 
+if (-not (Test-Path -PathType Leaf $specFile)) {
+    $template = Resolve-Template -TemplateName 'spec-template' -RepoRoot $repoRoot
+    if ($template -and (Test-Path $template)) {
+        Copy-Item $template $specFile -Force
+    } else {
+        New-Item -ItemType File -Path $specFile | Out-Null
+    }
 }
 
 # Set the SPECIFY_FEATURE environment variable for the current session
@@ -305,4 +307,3 @@ if ($Json) {
     Write-Output "HAS_GIT: $hasGit"
     Write-Output "SPECIFY_FEATURE environment variable set to: $branchName"
 }
-

scripts/powershell/update-agent-context.ps1

@@ -9,7 +9,7 @@ Mirrors the behavior of scripts/bash/update-agent-context.sh:
  2. Plan Data Extraction
  3. Agent File Management (create from template or update existing)
  4. Content Generation (technology stack, recent changes, timestamp)
- 5. Multi-Agent Support (claude, gemini, copilot, cursor-agent, qwen, opencode, codex, windsurf, kilocode, auggie, roo, codebuddy, amp, shai, tabnine, kiro-cli, agy, bob, vibe, qodercli, kimi, generic)
+ 5. Multi-Agent Support (claude, gemini, copilot, cursor-agent, qwen, opencode, codex, windsurf, junie, kilocode, auggie, roo, codebuddy, amp, shai, tabnine, kiro-cli, agy, bob, vibe, qodercli, kimi, trae, pi, iflow, generic)
 
 .PARAMETER AgentType
 Optional agent key to update a single agent. If omitted, updates all existing agent files (creating a default Claude file if none exist).
@@ -25,7 +25,7 @@ Relies on common helper functions in common.ps1
 #>
 param(
     [Parameter(Position=0)]
-    [ValidateSet('claude','gemini','copilot','cursor-agent','qwen','opencode','codex','windsurf','kilocode','auggie','roo','codebuddy','amp','shai','tabnine','kiro-cli','agy','bob','qodercli','vibe','kimi','generic')]
+    [ValidateSet('claude','gemini','copilot','cursor-agent','qwen','opencode','codex','windsurf','junie','kilocode','auggie','roo','codebuddy','amp','shai','tabnine','kiro-cli','agy','bob','qodercli','vibe','kimi','trae','pi','iflow','generic')]
     [string]$AgentType
 )
 
@@ -46,11 +46,12 @@ $NEW_PLAN = $IMPL_PLAN
 # Agent file paths
 $CLAUDE_FILE   = Join-Path $REPO_ROOT 'CLAUDE.md'
 $GEMINI_FILE   = Join-Path $REPO_ROOT 'GEMINI.md'
-$COPILOT_FILE  = Join-Path $REPO_ROOT '.github/agents/copilot-instructions.md'
+$COPILOT_FILE  = Join-Path $REPO_ROOT '.github/copilot-instructions.md'
 $CURSOR_FILE   = Join-Path $REPO_ROOT '.cursor/rules/specify-rules.mdc'
 $QWEN_FILE     = Join-Path $REPO_ROOT 'QWEN.md'
 $AGENTS_FILE   = Join-Path $REPO_ROOT 'AGENTS.md'
 $WINDSURF_FILE = Join-Path $REPO_ROOT '.windsurf/rules/specify-rules.md'
+$JUNIE_FILE = Join-Path $REPO_ROOT '.junie/AGENTS.md'
 $KILOCODE_FILE = Join-Path $REPO_ROOT '.kilocode/rules/specify-rules.md'
 $AUGGIE_FILE   = Join-Path $REPO_ROOT '.augment/rules/specify-rules.md'
 $ROO_FILE      = Join-Path $REPO_ROOT '.roo/rules/specify-rules.md'
@@ -64,6 +65,8 @@ $AGY_FILE      = Join-Path $REPO_ROOT '.agent/rules/specify-rules.md'
 $BOB_FILE      = Join-Path $REPO_ROOT 'AGENTS.md'
 $VIBE_FILE     = Join-Path $REPO_ROOT '.vibe/agents/specify-agents.md'
 $KIMI_FILE     = Join-Path $REPO_ROOT 'KIMI.md'
+$TRAE_FILE     = Join-Path $REPO_ROOT '.trae/rules/AGENTS.md'
+$IFLOW_FILE    = Join-Path $REPO_ROOT 'IFLOW.md'
 
 $TEMPLATE_FILE = Join-Path $REPO_ROOT '.specify/templates/agent-file-template.md'
 
@@ -395,6 +398,7 @@ function Update-SpecificAgent {
         'opencode' { Update-AgentFile -TargetFile $AGENTS_FILE   -AgentName 'opencode' }
         'codex'    { Update-AgentFile -TargetFile $AGENTS_FILE   -AgentName 'Codex CLI' }
         'windsurf' { Update-AgentFile -TargetFile $WINDSURF_FILE -AgentName 'Windsurf' }
+        'junie'    { Update-AgentFile -TargetFile $JUNIE_FILE    -AgentName 'Junie' }
         'kilocode' { Update-AgentFile -TargetFile $KILOCODE_FILE -AgentName 'Kilo Code' }
         'auggie'   { Update-AgentFile -TargetFile $AUGGIE_FILE   -AgentName 'Auggie CLI' }
         'roo'      { Update-AgentFile -TargetFile $ROO_FILE      -AgentName 'Roo Code' }
@@ -408,8 +412,11 @@ function Update-SpecificAgent {
         'bob'      { Update-AgentFile -TargetFile $BOB_FILE      -AgentName 'IBM Bob' }
         'vibe'     { Update-AgentFile -TargetFile $VIBE_FILE     -AgentName 'Mistral Vibe' }
         'kimi'     { Update-AgentFile -TargetFile $KIMI_FILE     -AgentName 'Kimi Code' }
+        'trae'     { Update-AgentFile -TargetFile $TRAE_FILE     -AgentName 'Trae' }
+        'pi'       { Update-AgentFile -TargetFile $AGENTS_FILE   -AgentName 'Pi Coding Agent' }
+        'iflow'    { Update-AgentFile -TargetFile $IFLOW_FILE    -AgentName 'iFlow CLI' }
         'generic'  { Write-Info 'Generic agent: no predefined context file. Use the agent-specific update script for your agent.' }
-        default { Write-Err "Unknown agent type '$Type'"; Write-Err 'Expected: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|amp|shai|tabnine|kiro-cli|agy|bob|vibe|qodercli|kimi|generic'; return $false }
+        default { Write-Err "Unknown agent type '$Type'"; Write-Err 'Expected: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|junie|kilocode|auggie|roo|codebuddy|amp|shai|tabnine|kiro-cli|agy|bob|vibe|qodercli|kimi|trae|pi|iflow|generic'; return $false }
     }
 }
 
@@ -423,6 +430,7 @@ function Update-AllExistingAgents {
     if (Test-Path $QWEN_FILE)     { if (-not (Update-AgentFile -TargetFile $QWEN_FILE     -AgentName 'Qwen Code')) { $ok = $false }; $found = $true }
     if (Test-Path $AGENTS_FILE)   { if (-not (Update-AgentFile -TargetFile $AGENTS_FILE   -AgentName 'Codex/opencode')) { $ok = $false }; $found = $true }
     if (Test-Path $WINDSURF_FILE) { if (-not (Update-AgentFile -TargetFile $WINDSURF_FILE -AgentName 'Windsurf')) { $ok = $false }; $found = $true }
+    if (Test-Path $JUNIE_FILE)    { if (-not (Update-AgentFile -TargetFile $JUNIE_FILE    -AgentName 'Junie')) { $ok = $false }; $found = $true }
     if (Test-Path $KILOCODE_FILE) { if (-not (Update-AgentFile -TargetFile $KILOCODE_FILE -AgentName 'Kilo Code')) { $ok = $false }; $found = $true }
     if (Test-Path $AUGGIE_FILE)   { if (-not (Update-AgentFile -TargetFile $AUGGIE_FILE   -AgentName 'Auggie CLI')) { $ok = $false }; $found = $true }
     if (Test-Path $ROO_FILE)      { if (-not (Update-AgentFile -TargetFile $ROO_FILE      -AgentName 'Roo Code')) { $ok = $false }; $found = $true }
@@ -435,6 +443,8 @@ function Update-AllExistingAgents {
     if (Test-Path $BOB_FILE)      { if (-not (Update-AgentFile -TargetFile $BOB_FILE      -AgentName 'IBM Bob')) { $ok = $false }; $found = $true }
     if (Test-Path $VIBE_FILE)     { if (-not (Update-AgentFile -TargetFile $VIBE_FILE     -AgentName 'Mistral Vibe')) { $ok = $false }; $found = $true }
     if (Test-Path $KIMI_FILE)     { if (-not (Update-AgentFile -TargetFile $KIMI_FILE     -AgentName 'Kimi Code')) { $ok = $false }; $found = $true }
+    if (Test-Path $TRAE_FILE)     { if (-not (Update-AgentFile -TargetFile $TRAE_FILE     -AgentName 'Trae')) { $ok = $false }; $found = $true }
+    if (Test-Path $IFLOW_FILE)    { if (-not (Update-AgentFile -TargetFile $IFLOW_FILE    -AgentName 'iFlow CLI')) { $ok = $false }; $found = $true }
     if (-not $found) {
         Write-Info 'No existing agent files found, creating default Claude file...'
         if (-not (Update-AgentFile -TargetFile $CLAUDE_FILE -AgentName 'Claude Code')) { $ok = $false }
@@ -449,7 +459,7 @@ function Print-Summary {
     if ($NEW_FRAMEWORK) { Write-Host "  - Added framework: $NEW_FRAMEWORK" }
     if ($NEW_DB -and $NEW_DB -ne 'N/A') { Write-Host "  - Added database: $NEW_DB" }
     Write-Host ''
-    Write-Info 'Usage: ./update-agent-context.ps1 [-AgentType claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|amp|shai|tabnine|kiro-cli|agy|bob|vibe|qodercli|generic]'
+    Write-Info 'Usage: ./update-agent-context.ps1 [-AgentType claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|junie|kilocode|auggie|roo|codebuddy|amp|shai|tabnine|kiro-cli|agy|bob|vibe|qodercli|kimi|trae|pi|iflow|generic]'
 }
 
 function Main {

src/specify_cli/agents.py

@@ -9,6 +9,9 @@ command files into agent-specific directories in the correct format.
 from pathlib import Path
 from typing import Dict, List, Any
 
+import platform
+import re
+from copy import deepcopy
 import yaml
 
 
@@ -59,13 +62,19 @@ class CommandRegistrar:
             "extension": ".md"
         },
         "codex": {
-            "dir": ".codex/prompts",
+            "dir": ".agents/skills",
+            "format": "markdown",
+            "args": "$ARGUMENTS",
+            "extension": "/SKILL.md",
+        },
+        "windsurf": {
+            "dir": ".windsurf/workflows",
             "format": "markdown",
             "args": "$ARGUMENTS",
             "extension": ".md"
         },
-        "windsurf": {
-            "dir": ".windsurf/workflows",
+        "junie": {
+            "dir": ".junie/commands",
             "format": "markdown",
             "args": "$ARGUMENTS",
             "extension": ".md"
@@ -106,6 +115,12 @@ class CommandRegistrar:
             "args": "$ARGUMENTS",
             "extension": ".md"
         },
+        "pi": {
+            "dir": ".pi/prompts",
+            "format": "markdown",
+            "args": "$ARGUMENTS",
+            "extension": ".md"
+        },
         "amp": {
             "dir": ".agents/commands",
             "format": "markdown",
@@ -134,7 +149,19 @@ class CommandRegistrar:
             "dir": ".kimi/skills",
             "format": "markdown",
             "args": "$ARGUMENTS",
-            "extension": "/SKILL.md"
+            "extension": "/SKILL.md",
+        },
+        "trae": {
+            "dir": ".trae/rules",
+            "format": "markdown",
+            "args": "$ARGUMENTS",
+            "extension": ".md"
+        },
+        "iflow": {
+            "dir": ".iflow/commands",
+            "format": "markdown",
+            "args": "$ARGUMENTS",
+            "extension": ".md"
         }
     }
 
@@ -164,6 +191,9 @@ class CommandRegistrar:
         except yaml.YAMLError:
             frontmatter = {}
 
+        if not isinstance(frontmatter, dict):
+            frontmatter = {}
+
         return frontmatter, body
 
     @staticmethod
@@ -179,25 +209,56 @@ class CommandRegistrar:
         if not fm:
             return ""
 
-        yaml_str = yaml.dump(fm, default_flow_style=False, sort_keys=False)
+        yaml_str = yaml.dump(fm, default_flow_style=False, sort_keys=False, allow_unicode=True)
         return f"---\n{yaml_str}---\n"
 
     def _adjust_script_paths(self, frontmatter: dict) -> dict:
-        """Adjust script paths from extension-relative to repo-relative.
+        """Normalize script paths in frontmatter to generated project locations.
+
+        Rewrites known repo-relative and top-level script paths under the
+        `scripts` and `agent_scripts` keys (for example `../../scripts/`,
+        `../../templates/`, `../../memory/`, `scripts/`, `templates/`, and
+        `memory/`) to the `.specify/...` paths used in generated projects.
 
         Args:
             frontmatter: Frontmatter dictionary
 
         Returns:
-            Modified frontmatter with adjusted paths
+            Modified frontmatter with normalized project paths
         """
-        if "scripts" in frontmatter:
-            for key in frontmatter["scripts"]:
-                script_path = frontmatter["scripts"][key]
-                if script_path.startswith("../../scripts/"):
-                    frontmatter["scripts"][key] = f".specify/scripts/{script_path[14:]}"
+        frontmatter = deepcopy(frontmatter)
+
+        for script_key in ("scripts", "agent_scripts"):
+            scripts = frontmatter.get(script_key)
+            if not isinstance(scripts, dict):
+                continue
+
+            for key, script_path in scripts.items():
+                if isinstance(script_path, str):
+                    scripts[key] = self._rewrite_project_relative_paths(script_path)
         return frontmatter
 
+    @staticmethod
+    def _rewrite_project_relative_paths(text: str) -> str:
+        """Rewrite repo-relative paths to their generated project locations."""
+        if not isinstance(text, str) or not text:
+            return text
+
+        for old, new in (
+            ("../../memory/", ".specify/memory/"),
+            ("../../scripts/", ".specify/scripts/"),
+            ("../../templates/", ".specify/templates/"),
+        ):
+            text = text.replace(old, new)
+
+        # Only rewrite top-level style references so extension-local paths like
+        # ".specify/extensions/<ext>/scripts/..." remain intact.
+        text = re.sub(r'(^|[\s`"\'(])(?:\.?/)?memory/', r"\1.specify/memory/", text)
+        text = re.sub(r'(^|[\s`"\'(])(?:\.?/)?scripts/', r"\1.specify/scripts/", text)
+        text = re.sub(r'(^|[\s`"\'(])(?:\.?/)?templates/', r"\1.specify/templates/", text)
+
+        return text.replace(".specify/.specify/", ".specify/").replace(".specify.specify/", ".specify/")
+
     def render_markdown_command(
         self,
         frontmatter: dict,
@@ -246,12 +307,123 @@ class CommandRegistrar:
         toml_lines.append(f"# Source: {source_id}")
         toml_lines.append("")
 
-        toml_lines.append('prompt = """')
-        toml_lines.append(body)
-        toml_lines.append('"""')
+        # Keep TOML output valid even when body contains triple-quote delimiters.
+        # Prefer multiline forms, then fall back to escaped basic string.
+        if '"""' not in body:
+            toml_lines.append('prompt = """')
+            toml_lines.append(body)
+            toml_lines.append('"""')
+        elif "'''" not in body:
+            toml_lines.append("prompt = '''")
+            toml_lines.append(body)
+            toml_lines.append("'''")
+        else:
+            escaped_body = (
+                body.replace("\\", "\\\\")
+                .replace('"', '\\"')
+                .replace("\n", "\\n")
+                .replace("\r", "\\r")
+                .replace("\t", "\\t")
+            )
+            toml_lines.append(f'prompt = "{escaped_body}"')
 
         return "\n".join(toml_lines)
 
+    def render_skill_command(
+        self,
+        agent_name: str,
+        skill_name: str,
+        frontmatter: dict,
+        body: str,
+        source_id: str,
+        source_file: str,
+        project_root: Path,
+    ) -> str:
+        """Render a command override as a SKILL.md file.
+
+        SKILL-target agents should receive the same skills-oriented
+        frontmatter shape used elsewhere in the project instead of the
+        original command frontmatter.
+
+        Technical debt note:
+        Spec-kit currently has multiple SKILL.md generators (template packaging,
+        init-time conversion, and extension/preset overrides). Keep the skill
+        frontmatter keys aligned (name/description/compatibility/metadata, with
+        metadata.author and metadata.source subkeys) to avoid drift across agents.
+        """
+        if not isinstance(frontmatter, dict):
+            frontmatter = {}
+
+        if agent_name in {"codex", "kimi"}:
+            body = self.resolve_skill_placeholders(agent_name, frontmatter, body, project_root)
+
+        description = frontmatter.get("description", f"Spec-kit workflow command: {skill_name}")
+        skill_frontmatter = {
+            "name": skill_name,
+            "description": description,
+            "compatibility": "Requires spec-kit project structure with .specify/ directory",
+            "metadata": {
+                "author": "github-spec-kit",
+                "source": f"{source_id}:{source_file}",
+            },
+        }
+        return self.render_frontmatter(skill_frontmatter) + "\n" + body
+
+    @staticmethod
+    def resolve_skill_placeholders(agent_name: str, frontmatter: dict, body: str, project_root: Path) -> str:
+        """Resolve script placeholders for skills-backed agents."""
+        try:
+            from . import load_init_options
+        except ImportError:
+            return body
+
+        if not isinstance(frontmatter, dict):
+            frontmatter = {}
+
+        scripts = frontmatter.get("scripts", {}) or {}
+        agent_scripts = frontmatter.get("agent_scripts", {}) or {}
+        if not isinstance(scripts, dict):
+            scripts = {}
+        if not isinstance(agent_scripts, dict):
+            agent_scripts = {}
+
+        init_opts = load_init_options(project_root)
+        if not isinstance(init_opts, dict):
+            init_opts = {}
+
+        script_variant = init_opts.get("script")
+        if script_variant not in {"sh", "ps"}:
+            fallback_order = []
+            default_variant = "ps" if platform.system().lower().startswith("win") else "sh"
+            secondary_variant = "sh" if default_variant == "ps" else "ps"
+
+            if default_variant in scripts or default_variant in agent_scripts:
+                fallback_order.append(default_variant)
+            if secondary_variant in scripts or secondary_variant in agent_scripts:
+                fallback_order.append(secondary_variant)
+
+            for key in scripts:
+                if key not in fallback_order:
+                    fallback_order.append(key)
+            for key in agent_scripts:
+                if key not in fallback_order:
+                    fallback_order.append(key)
+
+            script_variant = fallback_order[0] if fallback_order else None
+
+        script_command = scripts.get(script_variant) if script_variant else None
+        if script_command:
+            script_command = script_command.replace("{ARGS}", "$ARGUMENTS")
+            body = body.replace("{SCRIPT}", script_command)
+
+        agent_script_command = agent_scripts.get(script_variant) if script_variant else None
+        if agent_script_command:
+            agent_script_command = agent_script_command.replace("{ARGS}", "$ARGUMENTS")
+            body = body.replace("{AGENT_SCRIPT}", agent_script_command)
+
+        body = body.replace("{ARGS}", "$ARGUMENTS").replace("__AGENT__", agent_name)
+        return CommandRegistrar._rewrite_project_relative_paths(body)
+
     def _convert_argument_placeholder(self, content: str, from_placeholder: str, to_placeholder: str) -> str:
         """Convert argument placeholder format.
 
@@ -265,6 +437,19 @@ class CommandRegistrar:
         """
         return content.replace(from_placeholder, to_placeholder)
 
+    @staticmethod
+    def _compute_output_name(agent_name: str, cmd_name: str, agent_config: Dict[str, Any]) -> str:
+        """Compute the on-disk command or skill name for an agent."""
+        if agent_config["extension"] != "/SKILL.md":
+            return cmd_name
+
+        short_name = cmd_name
+        if short_name.startswith("speckit."):
+            short_name = short_name[len("speckit."):]
+        short_name = short_name.replace(".", "-")
+
+        return f"speckit-{short_name}"
+
     def register_commands(
         self,
         agent_name: str,
@@ -316,14 +501,20 @@ class CommandRegistrar:
                 body, "$ARGUMENTS", agent_config["args"]
             )
 
-            if agent_config["format"] == "markdown":
+            output_name = self._compute_output_name(agent_name, cmd_name, agent_config)
+
+            if agent_config["extension"] == "/SKILL.md":
+                output = self.render_skill_command(
+                    agent_name, output_name, frontmatter, body, source_id, cmd_file, project_root
+                )
+            elif agent_config["format"] == "markdown":
                 output = self.render_markdown_command(frontmatter, body, source_id, context_note)
             elif agent_config["format"] == "toml":
                 output = self.render_toml_command(frontmatter, body, source_id)
             else:
                 raise ValueError(f"Unsupported format: {agent_config['format']}")
 
-            dest_file = commands_dir / f"{cmd_name}{agent_config['extension']}"
+            dest_file = commands_dir / f"{output_name}{agent_config['extension']}"
             dest_file.parent.mkdir(parents=True, exist_ok=True)
             dest_file.write_text(output, encoding="utf-8")
 
@@ -333,9 +524,15 @@ class CommandRegistrar:
             registered.append(cmd_name)
 
             for alias in cmd_info.get("aliases", []):
-                alias_file = commands_dir / f"{alias}{agent_config['extension']}"
+                alias_output_name = self._compute_output_name(agent_name, alias, agent_config)
+                alias_output = output
+                if agent_config["extension"] == "/SKILL.md":
+                    alias_output = self.render_skill_command(
+                        agent_name, alias_output_name, frontmatter, body, source_id, cmd_file, project_root
+                    )
+                alias_file = commands_dir / f"{alias_output_name}{agent_config['extension']}"
                 alias_file.parent.mkdir(parents=True, exist_ok=True)
-                alias_file.write_text(output, encoding="utf-8")
+                alias_file.write_text(alias_output, encoding="utf-8")
                 if agent_name == "copilot":
                     self.write_copilot_prompt(project_root, alias)
                 registered.append(alias)
@@ -378,7 +575,7 @@ class CommandRegistrar:
         results = {}
 
         for agent_name, agent_config in self.AGENT_CONFIGS.items():
-            agent_dir = project_root / agent_config["dir"].split("/")[0]
+            agent_dir = project_root / agent_config["dir"]
 
             if agent_dir.exists():
                 try:
@@ -412,7 +609,8 @@ class CommandRegistrar:
             commands_dir = project_root / agent_config["dir"]
 
             for cmd_name in cmd_names:
-                cmd_file = commands_dir / f"{cmd_name}{agent_config['extension']}"
+                output_name = self._compute_output_name(agent_name, cmd_name, agent_config)
+                cmd_file = commands_dir / f"{output_name}{agent_config['extension']}"
                 if cmd_file.exists():
                     cmd_file.unlink()
 

src/specify_cli/extensions.py

@@ -25,6 +25,49 @@ import yaml
 from packaging import version as pkg_version
 from packaging.specifiers import SpecifierSet, InvalidSpecifier
 
+_FALLBACK_CORE_COMMAND_NAMES = frozenset({
+    "analyze",
+    "checklist",
+    "clarify",
+    "constitution",
+    "implement",
+    "plan",
+    "specify",
+    "tasks",
+    "taskstoissues",
+})
+EXTENSION_COMMAND_NAME_PATTERN = re.compile(r"^speckit\.([a-z0-9-]+)\.([a-z0-9-]+)$")
+
+
+def _load_core_command_names() -> frozenset[str]:
+    """Discover bundled core command names from the packaged templates.
+
+    Prefer the wheel-time ``core_pack`` bundle when present, and fall back to
+    the source checkout when running from the repository. If neither is
+    available, use the baked-in fallback set so validation still works.
+    """
+    candidate_dirs = [
+        Path(__file__).parent / "core_pack" / "commands",
+        Path(__file__).resolve().parent.parent.parent / "templates" / "commands",
+    ]
+
+    for commands_dir in candidate_dirs:
+        if not commands_dir.is_dir():
+            continue
+
+        command_names = {
+            command_file.stem
+            for command_file in commands_dir.iterdir()
+            if command_file.is_file() and command_file.suffix == ".md"
+        }
+        if command_names:
+            return frozenset(command_names)
+
+    return _FALLBACK_CORE_COMMAND_NAMES
+
+
+CORE_COMMAND_NAMES = _load_core_command_names()
+
 
 class ExtensionError(Exception):
     """Base exception for extension-related errors."""
@@ -41,6 +84,26 @@ class CompatibilityError(ExtensionError):
     pass
 
 
+def normalize_priority(value: Any, default: int = 10) -> int:
+    """Normalize a stored priority value for sorting and display.
+
+    Corrupted registry data may contain missing, non-numeric, or non-positive
+    values. In those cases, fall back to the default priority.
+
+    Args:
+        value: Priority value to normalize (may be int, str, None, etc.)
+        default: Default priority to use for invalid values (default: 10)
+
+    Returns:
+        Normalized priority as positive integer (>= 1)
+    """
+    try:
+        priority = int(value)
+    except (TypeError, ValueError):
+        return default
+    return priority if priority >= 1 else default
+
+
 @dataclass
 class CatalogEntry:
     """Represents a single catalog entry in the catalog stack."""
@@ -129,7 +192,7 @@ class ExtensionManifest:
                 raise ValidationError("Command missing 'name' or 'file'")
 
             # Validate command name format
-            if not re.match(r'^speckit\.[a-z0-9-]+\.[a-z0-9-]+$', cmd["name"]):
+            if EXTENSION_COMMAND_NAME_PATTERN.match(cmd["name"]) is None:
                 raise ValidationError(
                     f"Invalid command name '{cmd['name']}': "
                     "must follow pattern 'speckit.{extension}.{command}'"
@@ -202,7 +265,17 @@ class ExtensionRegistry:
 
         try:
             with open(self.registry_path, 'r') as f:
-                return json.load(f)
+                data = json.load(f)
+            # Validate loaded data is a dict (handles corrupted registry files)
+            if not isinstance(data, dict):
+                return {
+                    "schema_version": self.SCHEMA_VERSION,
+                    "extensions": {}
+                }
+            # Normalize extensions field (handles corrupted extensions value)
+            if not isinstance(data.get("extensions"), dict):
+                data["extensions"] = {}
+            return data
         except (json.JSONDecodeError, FileNotFoundError):
             # Corrupted or missing registry, start fresh
             return {
@@ -224,7 +297,7 @@ class ExtensionRegistry:
             metadata: Extension metadata (version, source, etc.)
         """
         self.data["extensions"][extension_id] = {
-            **metadata,
+            **copy.deepcopy(metadata),
             "installed_at": datetime.now(timezone.utc).isoformat()
         }
         self._save()
@@ -247,12 +320,16 @@ class ExtensionRegistry:
         Raises:
             KeyError: If extension is not installed
         """
-        if extension_id not in self.data["extensions"]:
+        extensions = self.data.get("extensions")
+        if not isinstance(extensions, dict) or extension_id not in extensions:
             raise KeyError(f"Extension '{extension_id}' is not installed")
         # Merge new metadata with existing, preserving original installed_at
-        existing = self.data["extensions"][extension_id]
-        # Merge: existing fields preserved, new fields override
-        merged = {**existing, **metadata}
+        existing = extensions[extension_id]
+        # Handle corrupted registry entries (e.g., string/list instead of dict)
+        if not isinstance(existing, dict):
+            existing = {}
+        # Merge: existing fields preserved, new fields override (deep copy to prevent caller mutation)
+        merged = {**existing, **copy.deepcopy(metadata)}
         # Always preserve original installed_at based on key existence, not truthiness,
         # to handle cases where the field exists but may be falsy (legacy/corruption)
         if "installed_at" in existing:
@@ -260,7 +337,7 @@ class ExtensionRegistry:
         else:
             # If not present in existing, explicitly remove from merged if caller provided it
             merged.pop("installed_at", None)
-        self.data["extensions"][extension_id] = merged
+        extensions[extension_id] = merged
         self._save()
 
     def restore(self, extension_id: str, metadata: dict):
@@ -273,8 +350,16 @@ class ExtensionRegistry:
         Args:
             extension_id: Extension ID
             metadata: Complete extension metadata including installed_at
+
+        Raises:
+            ValueError: If metadata is None or not a dict
         """
-        self.data["extensions"][extension_id] = dict(metadata)
+        if metadata is None or not isinstance(metadata, dict):
+            raise ValueError(f"Cannot restore '{extension_id}': metadata must be a dict")
+        # Ensure extensions dict exists (handle corrupted registry)
+        if not isinstance(self.data.get("extensions"), dict):
+            self.data["extensions"] = {}
+        self.data["extensions"][extension_id] = copy.deepcopy(metadata)
         self._save()
 
     def remove(self, extension_id: str):
@@ -283,8 +368,11 @@ class ExtensionRegistry:
         Args:
             extension_id: Extension ID
         """
-        if extension_id in self.data["extensions"]:
-            del self.data["extensions"][extension_id]
+        extensions = self.data.get("extensions")
+        if not isinstance(extensions, dict):
+            return
+        if extension_id in extensions:
+            del extensions[extension_id]
             self._save()
 
     def get(self, extension_id: str) -> Optional[dict]:
@@ -297,21 +385,49 @@ class ExtensionRegistry:
             extension_id: Extension ID
 
         Returns:
-            Deep copy of extension metadata, or None if not found
+            Deep copy of extension metadata, or None if not found or corrupted
         """
-        entry = self.data["extensions"].get(extension_id)
-        return copy.deepcopy(entry) if entry is not None else None
+        extensions = self.data.get("extensions")
+        if not isinstance(extensions, dict):
+            return None
+        entry = extensions.get(extension_id)
+        # Return None for missing or corrupted (non-dict) entries
+        if entry is None or not isinstance(entry, dict):
+            return None
+        return copy.deepcopy(entry)
 
     def list(self) -> Dict[str, dict]:
-        """Get all installed extensions.
+        """Get all installed extensions with valid metadata.
 
-        Returns a deep copy of the extensions mapping to prevent callers
-        from accidentally mutating nested internal registry state.
+        Returns a deep copy of extensions with dict metadata only.
+        Corrupted entries (non-dict values) are filtered out.
 
         Returns:
-            Dictionary of extension_id -> metadata (deep copies)
+            Dictionary of extension_id -> metadata (deep copies), empty dict if corrupted
         """
-        return copy.deepcopy(self.data["extensions"])
+        extensions = self.data.get("extensions", {}) or {}
+        if not isinstance(extensions, dict):
+            return {}
+        # Filter to only valid dict entries to match type contract
+        return {
+            ext_id: copy.deepcopy(meta)
+            for ext_id, meta in extensions.items()
+            if isinstance(meta, dict)
+        }
+
+    def keys(self) -> set:
+        """Get all extension IDs including corrupted entries.
+
+        Lightweight method that returns IDs without deep-copying metadata.
+        Use this when you only need to check which extensions are tracked.
+
+        Returns:
+            Set of extension IDs (includes corrupted entries)
+        """
+        extensions = self.data.get("extensions", {}) or {}
+        if not isinstance(extensions, dict):
+            return set()
+        return set(extensions.keys())
 
     def is_installed(self, extension_id: str) -> bool:
         """Check if extension is installed.
@@ -320,9 +436,44 @@ class ExtensionRegistry:
             extension_id: Extension ID
 
         Returns:
-            True if extension is installed
+            True if extension is installed, False if not or registry corrupted
         """
-        return extension_id in self.data["extensions"]
+        extensions = self.data.get("extensions")
+        if not isinstance(extensions, dict):
+            return False
+        return extension_id in extensions
+
+    def list_by_priority(self, include_disabled: bool = False) -> List[tuple]:
+        """Get all installed extensions sorted by priority.
+
+        Lower priority number = higher precedence (checked first).
+        Extensions with equal priority are sorted alphabetically by ID
+        for deterministic ordering.
+
+        Args:
+            include_disabled: If True, include disabled extensions. Default False.
+
+        Returns:
+            List of (extension_id, metadata_copy) tuples sorted by priority.
+            Metadata is deep-copied to prevent accidental mutation.
+        """
+        extensions = self.data.get("extensions", {}) or {}
+        if not isinstance(extensions, dict):
+            extensions = {}
+        sortable_extensions = []
+        for ext_id, meta in extensions.items():
+            if not isinstance(meta, dict):
+                continue
+            # Skip disabled extensions unless explicitly requested
+            if not include_disabled and not meta.get("enabled", True):
+                continue
+            metadata_copy = copy.deepcopy(meta)
+            metadata_copy["priority"] = normalize_priority(metadata_copy.get("priority", 10))
+            sortable_extensions.append((ext_id, metadata_copy))
+        return sorted(
+            sortable_extensions,
+            key=lambda item: (item[1]["priority"], item[0]),
+        )
 
 
 class ExtensionManager:
@@ -338,6 +489,126 @@ class ExtensionManager:
         self.extensions_dir = project_root / ".specify" / "extensions"
         self.registry = ExtensionRegistry(self.extensions_dir)
 
+    @staticmethod
+    def _collect_manifest_command_names(manifest: ExtensionManifest) -> Dict[str, str]:
+        """Collect command and alias names declared by a manifest.
+
+        Performs install-time validation for extension-specific constraints:
+        - commands and aliases must use the canonical `speckit.{extension}.{command}` shape
+        - commands and aliases must use this extension's namespace
+        - command namespaces must not shadow core commands
+        - duplicate command/alias names inside one manifest are rejected
+
+        Args:
+            manifest: Parsed extension manifest
+
+        Returns:
+            Mapping of declared command/alias name -> kind ("command"/"alias")
+
+        Raises:
+            ValidationError: If any declared name is invalid
+        """
+        if manifest.id in CORE_COMMAND_NAMES:
+            raise ValidationError(
+                f"Extension ID '{manifest.id}' conflicts with core command namespace '{manifest.id}'"
+            )
+
+        declared_names: Dict[str, str] = {}
+
+        for cmd in manifest.commands:
+            primary_name = cmd["name"]
+            aliases = cmd.get("aliases", [])
+
+            if aliases is None:
+                aliases = []
+            if not isinstance(aliases, list):
+                raise ValidationError(
+                    f"Aliases for command '{primary_name}' must be a list"
+                )
+
+            for kind, name in [("command", primary_name)] + [
+                ("alias", alias) for alias in aliases
+            ]:
+                if not isinstance(name, str):
+                    raise ValidationError(
+                        f"{kind.capitalize()} for command '{primary_name}' must be a string"
+                    )
+
+                match = EXTENSION_COMMAND_NAME_PATTERN.match(name)
+                if match is None:
+                    raise ValidationError(
+                        f"Invalid {kind} '{name}': "
+                        "must follow pattern 'speckit.{extension}.{command}'"
+                    )
+
+                namespace = match.group(1)
+                if namespace != manifest.id:
+                    raise ValidationError(
+                        f"{kind.capitalize()} '{name}' must use extension namespace '{manifest.id}'"
+                    )
+
+                if namespace in CORE_COMMAND_NAMES:
+                    raise ValidationError(
+                        f"{kind.capitalize()} '{name}' conflicts with core command namespace '{namespace}'"
+                    )
+
+                if name in declared_names:
+                    raise ValidationError(
+                        f"Duplicate command or alias '{name}' in extension manifest"
+                    )
+
+                declared_names[name] = kind
+
+        return declared_names
+
+    def _get_installed_command_name_map(
+        self,
+        exclude_extension_id: Optional[str] = None,
+    ) -> Dict[str, str]:
+        """Return registered command and alias names for installed extensions."""
+        installed_names: Dict[str, str] = {}
+
+        for ext_id in self.registry.keys():
+            if ext_id == exclude_extension_id:
+                continue
+
+            manifest = self.get_extension(ext_id)
+            if manifest is None:
+                continue
+
+            for cmd in manifest.commands:
+                cmd_name = cmd.get("name")
+                if isinstance(cmd_name, str):
+                    installed_names.setdefault(cmd_name, ext_id)
+
+                aliases = cmd.get("aliases", [])
+                if not isinstance(aliases, list):
+                    continue
+
+                for alias in aliases:
+                    if isinstance(alias, str):
+                        installed_names.setdefault(alias, ext_id)
+
+        return installed_names
+
+    def _validate_install_conflicts(self, manifest: ExtensionManifest) -> None:
+        """Reject installs that would shadow core or installed extension commands."""
+        declared_names = self._collect_manifest_command_names(manifest)
+        installed_names = self._get_installed_command_name_map(
+            exclude_extension_id=manifest.id
+        )
+
+        collisions = [
+            f"{name} (already provided by extension '{installed_names[name]}')"
+            for name in sorted(declared_names)
+            if name in installed_names
+        ]
+        if collisions:
+            raise ValidationError(
+                "Extension commands conflict with installed extensions:\n- "
+                + "\n- ".join(collisions)
+            )
+
     @staticmethod
     def _load_extensionignore(source_dir: Path) -> Optional[Callable[[str, List[str]], Set[str]]]:
         """Load .extensionignore and return an ignore function for shutil.copytree.
@@ -402,6 +673,283 @@ class ExtensionManager:
 
         return _ignore
 
+    def _get_skills_dir(self) -> Optional[Path]:
+        """Return the active skills directory for extension skill registration.
+
+        Reads ``.specify/init-options.json`` to determine whether skills
+        are enabled and which agent was selected, then delegates to
+        the module-level ``_get_skills_dir()`` helper for the concrete path.
+
+        Kimi is treated as a native-skills agent: if ``ai == "kimi"`` and
+        ``.kimi/skills`` exists, extension installs should still propagate
+        command skills even when ``ai_skills`` is false.
+
+        Returns:
+            The skills directory ``Path``, or ``None`` if skills were not
+            enabled and no native-skills fallback applies.
+        """
+        from . import load_init_options, _get_skills_dir as resolve_skills_dir
+
+        opts = load_init_options(self.project_root)
+        if not isinstance(opts, dict):
+            opts = {}
+
+        agent = opts.get("ai")
+        if not isinstance(agent, str) or not agent:
+            return None
+
+        ai_skills_enabled = bool(opts.get("ai_skills"))
+        if not ai_skills_enabled and agent != "kimi":
+            return None
+
+        skills_dir = resolve_skills_dir(self.project_root, agent)
+        if not skills_dir.is_dir():
+            return None
+
+        return skills_dir
+
+    def _register_extension_skills(
+        self,
+        manifest: ExtensionManifest,
+        extension_dir: Path,
+    ) -> List[str]:
+        """Generate SKILL.md files for extension commands as agent skills.
+
+        For every command in the extension manifest, creates a SKILL.md
+        file in the agent's skills directory following the agentskills.io
+        specification.  This is only done when ``--ai-skills`` was used
+        during project initialisation.
+
+        Args:
+            manifest: Extension manifest.
+            extension_dir: Installed extension directory.
+
+        Returns:
+            List of skill names that were created (for registry storage).
+        """
+        skills_dir = self._get_skills_dir()
+        if not skills_dir:
+            return []
+
+        from . import load_init_options
+        from .agents import CommandRegistrar
+        import yaml
+
+        written: List[str] = []
+        opts = load_init_options(self.project_root)
+        if not isinstance(opts, dict):
+            opts = {}
+        selected_ai = opts.get("ai")
+        if not isinstance(selected_ai, str) or not selected_ai:
+            return []
+        registrar = CommandRegistrar()
+
+        for cmd_info in manifest.commands:
+            cmd_name = cmd_info["name"]
+            cmd_file_rel = cmd_info["file"]
+
+            # Guard against path traversal: reject absolute paths and ensure
+            # the resolved file stays within the extension directory.
+            cmd_path = Path(cmd_file_rel)
+            if cmd_path.is_absolute():
+                continue
+            try:
+                ext_root = extension_dir.resolve()
+                source_file = (ext_root / cmd_path).resolve()
+                source_file.relative_to(ext_root)  # raises ValueError if outside
+            except (OSError, ValueError):
+                continue
+
+            if not source_file.is_file():
+                continue
+
+            # Derive skill name from command name using the same hyphenated
+            # convention as hook rendering and preset skill registration.
+            short_name_raw = cmd_name
+            if short_name_raw.startswith("speckit."):
+                short_name_raw = short_name_raw[len("speckit."):]
+            skill_name = f"speckit-{short_name_raw.replace('.', '-')}"
+
+            # Check if skill already exists before creating the directory
+            skill_subdir = skills_dir / skill_name
+            skill_file = skill_subdir / "SKILL.md"
+            if skill_file.exists():
+                # Do not overwrite user-customized skills
+                continue
+
+            # Create skill directory; track whether we created it so we can clean
+            # up safely if reading the source file subsequently fails.
+            created_now = not skill_subdir.exists()
+            skill_subdir.mkdir(parents=True, exist_ok=True)
+
+            # Parse the command file — guard against IsADirectoryError / decode errors
+            try:
+                content = source_file.read_text(encoding="utf-8")
+            except (OSError, UnicodeDecodeError):
+                if created_now:
+                    try:
+                        skill_subdir.rmdir()  # undo the mkdir; dir is empty at this point
+                    except OSError:
+                        pass  # best-effort cleanup
+                continue
+            frontmatter, body = registrar.parse_frontmatter(content)
+            frontmatter = registrar._adjust_script_paths(frontmatter)
+            body = registrar.resolve_skill_placeholders(
+                selected_ai, frontmatter, body, self.project_root
+            )
+
+            original_desc = frontmatter.get("description", "")
+            description = original_desc or f"Extension command: {cmd_name}"
+
+            frontmatter_data = {
+                "name": skill_name,
+                "description": description,
+                "compatibility": "Requires spec-kit project structure with .specify/ directory",
+                "metadata": {
+                    "author": "github-spec-kit",
+                    "source": f"extension:{manifest.id}",
+                },
+            }
+            frontmatter_text = yaml.safe_dump(frontmatter_data, sort_keys=False).strip()
+
+            # Derive a human-friendly title from the command name
+            short_name = cmd_name
+            if short_name.startswith("speckit."):
+                short_name = short_name[len("speckit."):]
+            title_name = short_name.replace(".", " ").replace("-", " ").title()
+
+            skill_content = (
+                f"---\n"
+                f"{frontmatter_text}\n"
+                f"---\n\n"
+                f"# {title_name} Skill\n\n"
+                f"{body}\n"
+            )
+
+            skill_file.write_text(skill_content, encoding="utf-8")
+            written.append(skill_name)
+
+        return written
+
+    def _unregister_extension_skills(self, skill_names: List[str], extension_id: str) -> None:
+        """Remove SKILL.md directories for extension skills.
+
+        Called during extension removal to clean up skill files that
+        were created by ``_register_extension_skills()``.
+
+        If ``_get_skills_dir()`` returns ``None`` (e.g. the user removed
+        init-options.json or toggled ai_skills after installation), we
+        fall back to scanning all known agent skills directories so that
+        orphaned skill directories are still cleaned up.  In that case
+        each candidate directory is verified against the SKILL.md
+        ``metadata.source`` field before removal to avoid accidentally
+        deleting user-created skills with the same name.
+
+        Args:
+            skill_names: List of skill names to remove.
+            extension_id: Extension ID used to verify ownership during
+                fallback candidate scanning.
+        """
+        if not skill_names:
+            return
+
+        skills_dir = self._get_skills_dir()
+
+        if skills_dir:
+            # Fast path: we know the exact skills directory
+            for skill_name in skill_names:
+                # Guard against path traversal from a corrupted registry entry:
+                # reject names that are absolute, contain path separators, or
+                # resolve to a path outside the skills directory.
+                sn_path = Path(skill_name)
+                if sn_path.is_absolute() or len(sn_path.parts) != 1:
+                    continue
+                try:
+                    skill_subdir = (skills_dir / skill_name).resolve()
+                    skill_subdir.relative_to(skills_dir.resolve())  # raises if outside
+                except (OSError, ValueError):
+                    continue
+                if not skill_subdir.is_dir():
+                    continue
+                # Safety check: only delete if SKILL.md exists and its
+                # metadata.source matches exactly this extension — mirroring
+                # the fallback branch — so a corrupted registry entry cannot
+                # delete an unrelated user skill.
+                skill_md = skill_subdir / "SKILL.md"
+                if not skill_md.is_file():
+                    continue
+                try:
+                    import yaml as _yaml
+                    raw = skill_md.read_text(encoding="utf-8")
+                    source = ""
+                    if raw.startswith("---"):
+                        parts = raw.split("---", 2)
+                        if len(parts) >= 3:
+                            fm = _yaml.safe_load(parts[1]) or {}
+                            source = (
+                                fm.get("metadata", {}).get("source", "")
+                                if isinstance(fm, dict)
+                                else ""
+                            )
+                    if source != f"extension:{extension_id}":
+                        continue
+                except (OSError, UnicodeDecodeError, Exception):
+                    continue
+                shutil.rmtree(skill_subdir)
+        else:
+            # Fallback: scan all possible agent skills directories
+            from . import AGENT_CONFIG, DEFAULT_SKILLS_DIR
+
+            candidate_dirs: set[Path] = set()
+            for cfg in AGENT_CONFIG.values():
+                folder = cfg.get("folder", "")
+                if folder:
+                    candidate_dirs.add(self.project_root / folder.rstrip("/") / "skills")
+            candidate_dirs.add(self.project_root / DEFAULT_SKILLS_DIR)
+
+            for skills_candidate in candidate_dirs:
+                if not skills_candidate.is_dir():
+                    continue
+                for skill_name in skill_names:
+                    # Same path-traversal guard as the fast path above
+                    sn_path = Path(skill_name)
+                    if sn_path.is_absolute() or len(sn_path.parts) != 1:
+                        continue
+                    try:
+                        skill_subdir = (skills_candidate / skill_name).resolve()
+                        skill_subdir.relative_to(skills_candidate.resolve())  # raises if outside
+                    except (OSError, ValueError):
+                        continue
+                    if not skill_subdir.is_dir():
+                        continue
+                    # Safety check: only delete if SKILL.md exists and its
+                    # metadata.source matches exactly this extension.  If the
+                    # file is missing or unreadable we skip to avoid deleting
+                    # unrelated user-created directories.
+                    skill_md = skill_subdir / "SKILL.md"
+                    if not skill_md.is_file():
+                        continue
+                    try:
+                        import yaml as _yaml
+                        raw = skill_md.read_text(encoding="utf-8")
+                        source = ""
+                        if raw.startswith("---"):
+                            parts = raw.split("---", 2)
+                            if len(parts) >= 3:
+                                fm = _yaml.safe_load(parts[1]) or {}
+                                source = (
+                                    fm.get("metadata", {}).get("source", "")
+                                    if isinstance(fm, dict)
+                                    else ""
+                                )
+                        # Only remove skills explicitly created by this extension
+                        if source != f"extension:{extension_id}":
+                            continue
+                    except (OSError, UnicodeDecodeError, Exception):
+                        # If we can't verify, skip to avoid accidental deletion
+                        continue
+                    shutil.rmtree(skill_subdir)
+
     def check_compatibility(
         self,
         manifest: ExtensionManifest,
@@ -440,7 +988,8 @@ class ExtensionManager:
         self,
         source_dir: Path,
         speckit_version: str,
-        register_commands: bool = True
+        register_commands: bool = True,
+        priority: int = 10,
     ) -> ExtensionManifest:
         """Install extension from a local directory.
 
@@ -448,14 +997,19 @@ class ExtensionManager:
             source_dir: Path to extension directory
             speckit_version: Current spec-kit version
             register_commands: If True, register commands with AI agents
+            priority: Resolution priority (lower = higher precedence, default 10)
 
         Returns:
             Installed extension manifest
 
         Raises:
-            ValidationError: If manifest is invalid
+            ValidationError: If manifest is invalid or priority is invalid
             CompatibilityError: If extension is incompatible
         """
+        # Validate priority
+        if priority < 1:
+            raise ValidationError("Priority must be a positive integer (1 or higher)")
+
         # Load and validate manifest
         manifest_path = source_dir / "extension.yml"
         manifest = ExtensionManifest(manifest_path)
@@ -470,6 +1024,9 @@ class ExtensionManager:
                 f"Use 'specify extension remove {manifest.id}' first."
             )
 
+        # Reject manifests that would shadow core commands or installed extensions.
+        self._validate_install_conflicts(manifest)
+
         # Install extension
         dest_dir = self.extensions_dir / manifest.id
         if dest_dir.exists():
@@ -487,6 +1044,10 @@ class ExtensionManager:
                 manifest, dest_dir, self.project_root
             )
 
+        # Auto-register extension commands as agent skills when --ai-skills
+        # was used during project initialisation (feature parity).
+        registered_skills = self._register_extension_skills(manifest, dest_dir)
+
         # Register hooks
         hook_executor = HookExecutor(self.project_root)
         hook_executor.register_hooks(manifest)
@@ -497,7 +1058,9 @@ class ExtensionManager:
             "source": "local",
             "manifest_hash": manifest.get_hash(),
             "enabled": True,
-            "registered_commands": registered_commands
+            "priority": priority,
+            "registered_commands": registered_commands,
+            "registered_skills": registered_skills,
         })
 
         return manifest
@@ -505,21 +1068,27 @@ class ExtensionManager:
     def install_from_zip(
         self,
         zip_path: Path,
-        speckit_version: str
+        speckit_version: str,
+        priority: int = 10,
     ) -> ExtensionManifest:
         """Install extension from ZIP file.
 
         Args:
             zip_path: Path to extension ZIP file
             speckit_version: Current spec-kit version
+            priority: Resolution priority (lower = higher precedence, default 10)
 
         Returns:
             Installed extension manifest
 
         Raises:
-            ValidationError: If manifest is invalid
+            ValidationError: If manifest is invalid or priority is invalid
             CompatibilityError: If extension is incompatible
         """
+        # Validate priority early
+        if priority < 1:
+            raise ValidationError("Priority must be a positive integer (1 or higher)")
+
         with tempfile.TemporaryDirectory() as tmpdir:
             temp_path = Path(tmpdir)
 
@@ -554,7 +1123,7 @@ class ExtensionManager:
                 raise ValidationError("No extension.yml found in ZIP file")
 
             # Install from extracted directory
-            return self.install_from_directory(extension_dir, speckit_version)
+            return self.install_from_directory(extension_dir, speckit_version, priority=priority)
 
     def remove(self, extension_id: str, keep_config: bool = False) -> bool:
         """Remove an installed extension.
@@ -569,9 +1138,15 @@ class ExtensionManager:
         if not self.registry.is_installed(extension_id):
             return False
 
-        # Get registered commands before removal
+        # Get registered commands and skills before removal
         metadata = self.registry.get(extension_id)
-        registered_commands = metadata.get("registered_commands", {})
+        registered_commands = metadata.get("registered_commands", {}) if metadata else {}
+        raw_skills = metadata.get("registered_skills", []) if metadata else []
+        # Normalize: must be a list of plain strings to avoid corrupted-registry errors
+        if isinstance(raw_skills, list):
+            registered_skills = [s for s in raw_skills if isinstance(s, str)]
+        else:
+            registered_skills = []
 
         extension_dir = self.extensions_dir / extension_id
 
@@ -580,6 +1155,9 @@ class ExtensionManager:
             registrar = CommandRegistrar()
             registrar.unregister_commands(registered_commands, self.project_root)
 
+        # Unregister agent skills
+        self._unregister_extension_skills(registered_skills, extension_id)
+
         if keep_config:
             # Preserve config files, only remove non-config files
             if extension_dir.exists():
@@ -632,6 +1210,9 @@ class ExtensionManager:
         result = []
 
         for ext_id, metadata in self.registry.list().items():
+            # Ensure metadata is a dictionary to avoid AttributeError when using .get()
+            if not isinstance(metadata, dict):
+                metadata = {}
             ext_dir = self.extensions_dir / ext_id
             manifest_path = ext_dir / "extension.yml"
 
@@ -643,6 +1224,7 @@ class ExtensionManager:
                     "version": metadata.get("version", "unknown"),
                     "description": manifest.description,
                     "enabled": metadata.get("enabled", True),
+                    "priority": normalize_priority(metadata.get("priority")),
                     "installed_at": metadata.get("installed_at"),
                     "command_count": len(manifest.commands),
                     "hook_count": len(manifest.hooks)
@@ -655,6 +1237,7 @@ class ExtensionManager:
                     "version": metadata.get("version", "unknown"),
                     "description": "⚠️ Corrupted extension",
                     "enabled": False,
+                    "priority": normalize_priority(metadata.get("priority")),
                     "installed_at": metadata.get("installed_at"),
                     "command_count": 0,
                     "hook_count": 0
@@ -849,8 +1432,8 @@ class ExtensionCatalog:
         if not config_path.exists():
             return None
         try:
-            data = yaml.safe_load(config_path.read_text()) or {}
-        except (yaml.YAMLError, OSError) as e:
+            data = yaml.safe_load(config_path.read_text(encoding="utf-8")) or {}
+        except (yaml.YAMLError, OSError, UnicodeError) as e:
             raise ValidationError(
                 f"Failed to read catalog config {config_path}: {e}"
             )
@@ -1341,8 +1924,8 @@ class ConfigManager:
             return {}
 
         try:
-            return yaml.safe_load(file_path.read_text()) or {}
-        except (yaml.YAMLError, OSError):
+            return yaml.safe_load(file_path.read_text(encoding="utf-8")) or {}
+        except (yaml.YAMLError, OSError, UnicodeError):
             return {}
 
     def _get_extension_defaults(self) -> Dict[str, Any]:
@@ -1518,6 +2101,52 @@ class HookExecutor:
         self.project_root = project_root
         self.extensions_dir = project_root / ".specify" / "extensions"
         self.config_file = project_root / ".specify" / "extensions.yml"
+        self._init_options_cache: Optional[Dict[str, Any]] = None
+
+    def _load_init_options(self) -> Dict[str, Any]:
+        """Load persisted init options used to determine invocation style.
+
+        Uses the shared helper from specify_cli and caches values per executor
+        instance to avoid repeated filesystem reads during hook rendering.
+        """
+        if self._init_options_cache is None:
+            from . import load_init_options
+
+            payload = load_init_options(self.project_root)
+            self._init_options_cache = payload if isinstance(payload, dict) else {}
+        return self._init_options_cache
+
+    @staticmethod
+    def _skill_name_from_command(command: Any) -> str:
+        """Map a command id like speckit.plan to speckit-plan skill name."""
+        if not isinstance(command, str):
+            return ""
+        command_id = command.strip()
+        if not command_id.startswith("speckit."):
+            return ""
+        return f"speckit-{command_id[len('speckit.'):].replace('.', '-')}"
+
+    def _render_hook_invocation(self, command: Any) -> str:
+        """Render an agent-specific invocation string for a hook command."""
+        if not isinstance(command, str):
+            return ""
+
+        command_id = command.strip()
+        if not command_id:
+            return ""
+
+        init_options = self._load_init_options()
+        selected_ai = init_options.get("ai")
+        codex_skill_mode = selected_ai == "codex" and bool(init_options.get("ai_skills"))
+        kimi_skill_mode = selected_ai == "kimi"
+
+        skill_name = self._skill_name_from_command(command_id)
+        if codex_skill_mode and skill_name:
+            return f"${skill_name}"
+        if kimi_skill_mode and skill_name:
+            return f"/skill:{skill_name}"
+
+        return f"/{command_id}"
 
     def get_project_config(self) -> Dict[str, Any]:
         """Load project-level extension configuration.
@@ -1533,8 +2162,8 @@ class HookExecutor:
             }
 
         try:
-            return yaml.safe_load(self.config_file.read_text()) or {}
-        except (yaml.YAMLError, OSError):
+            return yaml.safe_load(self.config_file.read_text(encoding="utf-8")) or {}
+        except (yaml.YAMLError, OSError, UnicodeError):
             return {
                 "installed": [],
                 "settings": {"auto_execute_hooks": True},
@@ -1549,7 +2178,8 @@ class HookExecutor:
         """
         self.config_file.parent.mkdir(parents=True, exist_ok=True)
         self.config_file.write_text(
-            yaml.dump(config, default_flow_style=False, sort_keys=False)
+            yaml.dump(config, default_flow_style=False, sort_keys=False, allow_unicode=True),
+            encoding="utf-8",
         )
 
     def register_hooks(self, manifest: ExtensionManifest):
@@ -1760,21 +2390,27 @@ class HookExecutor:
         for hook in hooks:
             extension = hook.get("extension")
             command = hook.get("command")
+            invocation = self._render_hook_invocation(command)
+            command_text = command if isinstance(command, str) and command.strip() else "<missing command>"
+            display_invocation = invocation or (
+                f"/{command_text}" if command_text != "<missing command>" else "/<missing command>"
+            )
             optional = hook.get("optional", True)
             prompt = hook.get("prompt", "")
             description = hook.get("description", "")
 
             if optional:
                 lines.append(f"\n**Optional Hook**: {extension}")
-                lines.append(f"Command: `/{command}`")
+                lines.append(f"Command: `{display_invocation}`")
                 if description:
                     lines.append(f"Description: {description}")
                 lines.append(f"\nPrompt: {prompt}")
-                lines.append(f"To execute: `/{command}`")
+                lines.append(f"To execute: `{display_invocation}`")
             else:
                 lines.append(f"\n**Automatic Hook**: {extension}")
-                lines.append(f"Executing: `/{command}`")
-                lines.append(f"EXECUTE_COMMAND: {command}")
+                lines.append(f"Executing: `{display_invocation}`")
+                lines.append(f"EXECUTE_COMMAND: {command_text}")
+                lines.append(f"EXECUTE_COMMAND_INVOCATION: {display_invocation}")
 
         return "\n".join(lines)
 
@@ -1838,6 +2474,7 @@ class HookExecutor:
         """
         return {
             "command": hook.get("command"),
+            "invocation": self._render_hook_invocation(hook.get("command")),
             "extension": hook.get("extension"),
             "optional": hook.get("optional", True),
             "description": hook.get("description", ""),
@@ -1881,4 +2518,3 @@ class HookExecutor:
                     hook["enabled"] = False
 
         self.save_project_config(config)
-

src/specify_cli/integrations/__init__.py

@@ -0,0 +1,46 @@
+"""Integration registry for AI coding assistants.
+
+Each integration is a self-contained subpackage that handles setup/teardown
+for a specific AI assistant (Copilot, Claude, Gemini, etc.).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .base import IntegrationBase
+
+# Maps integration key → IntegrationBase instance.
+# Populated by later stages as integrations are migrated.
+INTEGRATION_REGISTRY: dict[str, IntegrationBase] = {}
+
+
+def _register(integration: IntegrationBase) -> None:
+    """Register an integration instance in the global registry.
+
+    Raises ``ValueError`` for falsy keys and ``KeyError`` for duplicates.
+    """
+    key = integration.key
+    if not key:
+        raise ValueError("Cannot register integration with an empty key.")
+    if key in INTEGRATION_REGISTRY:
+        raise KeyError(f"Integration with key {key!r} is already registered.")
+    INTEGRATION_REGISTRY[key] = integration
+
+
+def get_integration(key: str) -> IntegrationBase | None:
+    """Return the integration for *key*, or ``None`` if not registered."""
+    return INTEGRATION_REGISTRY.get(key)
+
+
+# -- Register built-in integrations --------------------------------------
+
+def _register_builtins() -> None:
+    """Register all built-in integrations."""
+    from .copilot import CopilotIntegration
+
+    _register(CopilotIntegration())
+
+
+_register_builtins()

src/specify_cli/integrations/base.py

@@ -0,0 +1,415 @@
+"""Base classes for AI-assistant integrations.
+
+Provides:
+- ``IntegrationOption`` — declares a CLI option an integration accepts.
+- ``IntegrationBase`` — abstract base every integration must implement.
+- ``MarkdownIntegration`` — concrete base for standard Markdown-format
+  integrations (the common case — subclass, set three class attrs, done).
+"""
+
+from __future__ import annotations
+
+import re
+import shutil
+from abc import ABC
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .manifest import IntegrationManifest
+
+
+# ---------------------------------------------------------------------------
+# IntegrationOption
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class IntegrationOption:
+    """Declares an option that an integration accepts via ``--integration-options``.
+
+    Attributes:
+        name:      The flag name (e.g. ``"--commands-dir"``).
+        is_flag:   ``True`` for boolean flags (``--skills``).
+        required:  ``True`` if the option must be supplied.
+        default:   Default value when not supplied (``None`` → no default).
+        help:      One-line description shown in ``specify integrate info``.
+    """
+
+    name: str
+    is_flag: bool = False
+    required: bool = False
+    default: Any = None
+    help: str = ""
+
+
+# ---------------------------------------------------------------------------
+# IntegrationBase — abstract base class
+# ---------------------------------------------------------------------------
+
+class IntegrationBase(ABC):
+    """Abstract base class every integration must implement.
+
+    Subclasses must set the following class-level attributes:
+
+    * ``key``              — unique identifier, matches actual CLI tool name
+    * ``config``           — dict compatible with ``AGENT_CONFIG`` entries
+    * ``registrar_config`` — dict compatible with ``CommandRegistrar.AGENT_CONFIGS``
+
+    And may optionally set:
+
+    * ``context_file``     — path (relative to project root) of the agent
+                             context/instructions file (e.g. ``"CLAUDE.md"``)
+    """
+
+    # -- Must be set by every subclass ------------------------------------
+
+    key: str = ""
+    """Unique integration key — should match the actual CLI tool name."""
+
+    config: dict[str, Any] | None = None
+    """Metadata dict matching the ``AGENT_CONFIG`` shape."""
+
+    registrar_config: dict[str, Any] | None = None
+    """Registration dict matching ``CommandRegistrar.AGENT_CONFIGS`` shape."""
+
+    # -- Optional ---------------------------------------------------------
+
+    context_file: str | None = None
+    """Relative path to the agent context file (e.g. ``CLAUDE.md``)."""
+
+    # -- Public API -------------------------------------------------------
+
+    @classmethod
+    def options(cls) -> list[IntegrationOption]:
+        """Return options this integration accepts. Default: none."""
+        return []
+
+    # -- Primitives — building blocks for setup() -------------------------
+
+    def shared_commands_dir(self) -> Path | None:
+        """Return path to the shared command templates directory.
+
+        Checks ``core_pack/commands/`` (wheel install) first, then
+        ``templates/commands/`` (source checkout).  Returns ``None``
+        if neither exists.
+        """
+        import inspect
+
+        pkg_dir = Path(inspect.getfile(IntegrationBase)).resolve().parent.parent
+        for candidate in [
+            pkg_dir / "core_pack" / "commands",
+            pkg_dir.parent.parent / "templates" / "commands",
+        ]:
+            if candidate.is_dir():
+                return candidate
+        return None
+
+    def shared_templates_dir(self) -> Path | None:
+        """Return path to the shared page templates directory.
+
+        Contains ``vscode-settings.json``, ``spec-template.md``, etc.
+        Checks ``core_pack/templates/`` then ``templates/``.
+        """
+        import inspect
+
+        pkg_dir = Path(inspect.getfile(IntegrationBase)).resolve().parent.parent
+        for candidate in [
+            pkg_dir / "core_pack" / "templates",
+            pkg_dir.parent.parent / "templates",
+        ]:
+            if candidate.is_dir():
+                return candidate
+        return None
+
+    def list_command_templates(self) -> list[Path]:
+        """Return sorted list of command template files from the shared directory."""
+        cmd_dir = self.shared_commands_dir()
+        if not cmd_dir or not cmd_dir.is_dir():
+            return []
+        return sorted(f for f in cmd_dir.iterdir() if f.is_file() and f.suffix == ".md")
+
+    def command_filename(self, template_name: str) -> str:
+        """Return the destination filename for a command template.
+
+        *template_name* is the stem of the source file (e.g. ``"plan"``).
+        Default: ``speckit.{template_name}.md``.  Subclasses override
+        to change the extension or naming convention.
+        """
+        return f"speckit.{template_name}.md"
+
+    def commands_dest(self, project_root: Path) -> Path:
+        """Return the absolute path to the commands output directory.
+
+        Derived from ``config["folder"]`` and ``config["commands_subdir"]``.
+        Raises ``ValueError`` if ``config`` or ``folder`` is missing.
+        """
+        if not self.config:
+            raise ValueError(
+                f"{type(self).__name__}.config is not set; integration "
+                "subclasses must define a non-empty 'config' mapping."
+            )
+        folder = self.config.get("folder")
+        if not folder:
+            raise ValueError(
+                f"{type(self).__name__}.config is missing required 'folder' entry."
+            )
+        subdir = self.config.get("commands_subdir", "commands")
+        return project_root / folder / subdir
+
+    # -- File operations — granular primitives for setup() ----------------
+
+    @staticmethod
+    def copy_command_to_directory(
+        src: Path,
+        dest_dir: Path,
+        filename: str,
+    ) -> Path:
+        """Copy a command template to *dest_dir* with the given *filename*.
+
+        Creates *dest_dir* if needed.  Returns the absolute path of the
+        written file.  The caller can post-process the file before
+        recording it in the manifest.
+        """
+        dest_dir.mkdir(parents=True, exist_ok=True)
+        dst = dest_dir / filename
+        shutil.copy2(src, dst)
+        return dst
+
+    @staticmethod
+    def record_file_in_manifest(
+        file_path: Path,
+        project_root: Path,
+        manifest: IntegrationManifest,
+    ) -> None:
+        """Hash *file_path* and record it in *manifest*.
+
+        *file_path* must be inside *project_root*.
+        """
+        rel = file_path.resolve().relative_to(project_root.resolve())
+        manifest.record_existing(rel)
+
+    @staticmethod
+    def write_file_and_record(
+        content: str,
+        dest: Path,
+        project_root: Path,
+        manifest: IntegrationManifest,
+    ) -> Path:
+        """Write *content* to *dest*, hash it, and record in *manifest*.
+
+        Creates parent directories as needed.  Returns *dest*.
+        """
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(content, encoding="utf-8")
+        rel = dest.resolve().relative_to(project_root.resolve())
+        manifest.record_existing(rel)
+        return dest
+
+    @staticmethod
+    def process_template(
+        content: str,
+        agent_name: str,
+        script_type: str,
+        arg_placeholder: str = "$ARGUMENTS",
+    ) -> str:
+        """Process a raw command template into agent-ready content.
+
+        Performs the same transformations as the release script:
+        1. Extract ``scripts.<script_type>`` value from YAML frontmatter
+        2. Replace ``{SCRIPT}`` with the extracted script command
+        3. Extract ``agent_scripts.<script_type>`` and replace ``{AGENT_SCRIPT}``
+        4. Strip ``scripts:`` and ``agent_scripts:`` sections from frontmatter
+        5. Replace ``{ARGS}`` with *arg_placeholder*
+        6. Replace ``__AGENT__`` with *agent_name*
+        7. Rewrite paths: ``scripts/`` → ``.specify/scripts/`` etc.
+        """
+        # 1. Extract script command from frontmatter
+        script_command = ""
+        script_pattern = re.compile(
+            rf"^\s*{re.escape(script_type)}:\s*(.+)$", re.MULTILINE
+        )
+        # Find the scripts: block
+        in_scripts = False
+        for line in content.splitlines():
+            if line.strip() == "scripts:":
+                in_scripts = True
+                continue
+            if in_scripts and line and not line[0].isspace():
+                in_scripts = False
+            if in_scripts:
+                m = script_pattern.match(line)
+                if m:
+                    script_command = m.group(1).strip()
+                    break
+
+        # 2. Replace {SCRIPT}
+        if script_command:
+            content = content.replace("{SCRIPT}", script_command)
+
+        # 3. Extract agent_script command
+        agent_script_command = ""
+        in_agent_scripts = False
+        for line in content.splitlines():
+            if line.strip() == "agent_scripts:":
+                in_agent_scripts = True
+                continue
+            if in_agent_scripts and line and not line[0].isspace():
+                in_agent_scripts = False
+            if in_agent_scripts:
+                m = script_pattern.match(line)
+                if m:
+                    agent_script_command = m.group(1).strip()
+                    break
+
+        if agent_script_command:
+            content = content.replace("{AGENT_SCRIPT}", agent_script_command)
+
+        # 4. Strip scripts: and agent_scripts: sections from frontmatter
+        lines = content.splitlines(keepends=True)
+        output_lines: list[str] = []
+        in_frontmatter = False
+        skip_section = False
+        dash_count = 0
+        for line in lines:
+            stripped = line.rstrip("\n\r")
+            if stripped == "---":
+                dash_count += 1
+                if dash_count == 1:
+                    in_frontmatter = True
+                else:
+                    in_frontmatter = False
+                skip_section = False
+                output_lines.append(line)
+                continue
+            if in_frontmatter:
+                if stripped in ("scripts:", "agent_scripts:"):
+                    skip_section = True
+                    continue
+                if skip_section:
+                    if line[0:1].isspace():
+                        continue  # skip indented content under scripts/agent_scripts
+                    skip_section = False
+            output_lines.append(line)
+        content = "".join(output_lines)
+
+        # 5. Replace {ARGS}
+        content = content.replace("{ARGS}", arg_placeholder)
+
+        # 6. Replace __AGENT__
+        content = content.replace("__AGENT__", agent_name)
+
+        # 7. Rewrite paths (matches release script's rewrite_paths())
+        content = re.sub(r"(/?)memory/", r".specify/memory/", content)
+        content = re.sub(r"(/?)scripts/", r".specify/scripts/", content)
+        content = re.sub(r"(/?)templates/", r".specify/templates/", content)
+        # Fix double-prefix (same as release script's .specify.specify/ fix)
+        content = content.replace(".specify.specify/", ".specify/")
+        content = content.replace(".specify/.specify/", ".specify/")
+
+        return content
+
+    def setup(
+        self,
+        project_root: Path,
+        manifest: IntegrationManifest,
+        parsed_options: dict[str, Any] | None = None,
+        **opts: Any,
+    ) -> list[Path]:
+        """Install integration command files into *project_root*.
+
+        Returns the list of files created.  Copies raw templates without
+        processing.  Integrations that need placeholder replacement
+        (e.g. ``{SCRIPT}``, ``__AGENT__``) should override ``setup()``
+        and call ``process_template()`` in their own loop — see
+        ``CopilotIntegration`` for an example.
+        """
+        templates = self.list_command_templates()
+        if not templates:
+            return []
+
+        project_root_resolved = project_root.resolve()
+        if manifest.project_root != project_root_resolved:
+            raise ValueError(
+                f"manifest.project_root ({manifest.project_root}) does not match "
+                f"project_root ({project_root_resolved})"
+            )
+
+        dest = self.commands_dest(project_root).resolve()
+        try:
+            dest.relative_to(project_root_resolved)
+        except ValueError as exc:
+            raise ValueError(
+                f"Integration destination {dest} escapes "
+                f"project root {project_root_resolved}"
+            ) from exc
+
+        created: list[Path] = []
+
+        for src_file in templates:
+            dst_name = self.command_filename(src_file.stem)
+            dst_file = self.copy_command_to_directory(src_file, dest, dst_name)
+            self.record_file_in_manifest(dst_file, project_root, manifest)
+            created.append(dst_file)
+
+        return created
+
+    def teardown(
+        self,
+        project_root: Path,
+        manifest: IntegrationManifest,
+        *,
+        force: bool = False,
+    ) -> tuple[list[Path], list[Path]]:
+        """Uninstall integration files from *project_root*.
+
+        Delegates to ``manifest.uninstall()`` which only removes files
+        whose hash still matches the recorded value (unless *force*).
+
+        Returns ``(removed, skipped)`` file lists.
+        """
+        return manifest.uninstall(project_root, force=force)
+
+    # -- Convenience helpers for subclasses -------------------------------
+
+    def install(
+        self,
+        project_root: Path,
+        manifest: IntegrationManifest,
+        parsed_options: dict[str, Any] | None = None,
+        **opts: Any,
+    ) -> list[Path]:
+        """High-level install — calls ``setup()`` and returns created files."""
+        return self.setup(
+            project_root, manifest, parsed_options=parsed_options, **opts
+        )
+
+    def uninstall(
+        self,
+        project_root: Path,
+        manifest: IntegrationManifest,
+        *,
+        force: bool = False,
+    ) -> tuple[list[Path], list[Path]]:
+        """High-level uninstall — calls ``teardown()``."""
+        return self.teardown(project_root, manifest, force=force)
+
+
+# ---------------------------------------------------------------------------
+# MarkdownIntegration — covers ~20 standard agents
+# ---------------------------------------------------------------------------
+
+class MarkdownIntegration(IntegrationBase):
+    """Concrete base for integrations that use standard Markdown commands.
+
+    Subclasses only need to set ``key``, ``config``, ``registrar_config``
+    (and optionally ``context_file``).  Everything else is inherited.
+
+    The default ``setup()`` from ``IntegrationBase`` copies templates
+    into the agent's commands directory — which is correct for the
+    standard Markdown case.
+    """
+
+    # MarkdownIntegration inherits IntegrationBase.setup() as-is.
+    # Future stages may add markdown-specific path rewriting here.
+    pass

src/specify_cli/integrations/copilot/__init__.py

@@ -0,0 +1,197 @@
+"""Copilot integration — GitHub Copilot in VS Code.
+
+Copilot has several unique behaviors compared to standard markdown agents:
+- Commands use ``.agent.md`` extension (not ``.md``)
+- Each command gets a companion ``.prompt.md`` file in ``.github/prompts/``
+- Installs ``.vscode/settings.json`` with prompt file recommendations
+- Context file lives at ``.github/copilot-instructions.md``
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+from pathlib import Path
+from typing import Any
+
+from ..base import IntegrationBase
+from ..manifest import IntegrationManifest
+
+
+class CopilotIntegration(IntegrationBase):
+    """Integration for GitHub Copilot in VS Code."""
+
+    key = "copilot"
+    config = {
+        "name": "GitHub Copilot",
+        "folder": ".github/",
+        "commands_subdir": "agents",
+        "install_url": None,
+        "requires_cli": False,
+    }
+    registrar_config = {
+        "dir": ".github/agents",
+        "format": "markdown",
+        "args": "$ARGUMENTS",
+        "extension": ".agent.md",
+    }
+    context_file = ".github/copilot-instructions.md"
+
+    def command_filename(self, template_name: str) -> str:
+        """Copilot commands use ``.agent.md`` extension."""
+        return f"speckit.{template_name}.agent.md"
+
+    def setup(
+        self,
+        project_root: Path,
+        manifest: IntegrationManifest,
+        parsed_options: dict[str, Any] | None = None,
+        **opts: Any,
+    ) -> list[Path]:
+        """Install copilot commands, companion prompts, and VS Code settings.
+
+        Uses base class primitives to: read templates, process them
+        (replace placeholders, strip script blocks, rewrite paths),
+        write as ``.agent.md``, then add companion prompts and VS Code settings.
+        """
+        project_root_resolved = project_root.resolve()
+        if manifest.project_root != project_root_resolved:
+            raise ValueError(
+                f"manifest.project_root ({manifest.project_root}) does not match "
+                f"project_root ({project_root_resolved})"
+            )
+
+        templates = self.list_command_templates()
+        if not templates:
+            return []
+
+        dest = self.commands_dest(project_root)
+        dest_resolved = dest.resolve()
+        try:
+            dest_resolved.relative_to(project_root_resolved)
+        except ValueError as exc:
+            raise ValueError(
+                f"Integration destination {dest_resolved} escapes "
+                f"project root {project_root_resolved}"
+            ) from exc
+        dest.mkdir(parents=True, exist_ok=True)
+        created: list[Path] = []
+
+        script_type = opts.get("script_type", "sh")
+        arg_placeholder = self.registrar_config.get("args", "$ARGUMENTS")
+
+        # 1. Process and write command files as .agent.md
+        for src_file in templates:
+            raw = src_file.read_text(encoding="utf-8")
+            processed = self.process_template(raw, self.key, script_type, arg_placeholder)
+            dst_name = self.command_filename(src_file.stem)
+            dst_file = self.write_file_and_record(
+                processed, dest / dst_name, project_root, manifest
+            )
+            created.append(dst_file)
+
+        # 2. Generate companion .prompt.md files from the templates we just wrote
+        prompts_dir = project_root / ".github" / "prompts"
+        for src_file in templates:
+            cmd_name = f"speckit.{src_file.stem}"
+            prompt_content = f"---\nagent: {cmd_name}\n---\n"
+            prompt_file = self.write_file_and_record(
+                prompt_content,
+                prompts_dir / f"{cmd_name}.prompt.md",
+                project_root,
+                manifest,
+            )
+            created.append(prompt_file)
+
+        # Write .vscode/settings.json
+        settings_src = self._vscode_settings_path()
+        if settings_src and settings_src.is_file():
+            dst_settings = project_root / ".vscode" / "settings.json"
+            dst_settings.parent.mkdir(parents=True, exist_ok=True)
+            if dst_settings.exists():
+                # Merge into existing — don't track since we can't safely
+                # remove the user's settings file on uninstall.
+                self._merge_vscode_settings(settings_src, dst_settings)
+            else:
+                shutil.copy2(settings_src, dst_settings)
+                self.record_file_in_manifest(dst_settings, project_root, manifest)
+                created.append(dst_settings)
+
+        # 4. Install integration-specific update-context scripts
+        scripts_src = Path(__file__).resolve().parent / "scripts"
+        if scripts_src.is_dir():
+            scripts_dest = project_root / ".specify" / "integrations" / "copilot" / "scripts"
+            scripts_dest.mkdir(parents=True, exist_ok=True)
+            for src_script in sorted(scripts_src.iterdir()):
+                if src_script.is_file():
+                    dst_script = scripts_dest / src_script.name
+                    shutil.copy2(src_script, dst_script)
+                    # Make shell scripts executable
+                    if dst_script.suffix == ".sh":
+                        dst_script.chmod(dst_script.stat().st_mode | 0o111)
+                    self.record_file_in_manifest(dst_script, project_root, manifest)
+                    created.append(dst_script)
+
+        return created
+
+    def _vscode_settings_path(self) -> Path | None:
+        """Return path to the bundled vscode-settings.json template."""
+        tpl_dir = self.shared_templates_dir()
+        if tpl_dir:
+            candidate = tpl_dir / "vscode-settings.json"
+            if candidate.is_file():
+                return candidate
+        return None
+
+    @staticmethod
+    def _merge_vscode_settings(src: Path, dst: Path) -> None:
+        """Merge settings from *src* into existing *dst* JSON file.
+
+        Top-level keys from *src* are added only if missing in *dst*.
+        For dict-valued keys, sub-keys are merged the same way.
+
+        If *dst* cannot be parsed (e.g. JSONC with comments), the merge
+        is skipped to avoid overwriting user settings.
+        """
+        try:
+            existing = json.loads(dst.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            # Cannot parse existing file (likely JSONC with comments).
+            # Skip merge to preserve the user's settings, but show
+            # what they should add manually.
+            import logging
+            template_content = src.read_text(encoding="utf-8")
+            logging.getLogger(__name__).warning(
+                "Could not parse %s (may contain JSONC comments). "
+                "Skipping settings merge to preserve existing file.\n"
+                "Please add the following settings manually:\n%s",
+                dst, template_content,
+            )
+            return
+
+        new_settings = json.loads(src.read_text(encoding="utf-8"))
+
+        if not isinstance(existing, dict) or not isinstance(new_settings, dict):
+            import logging
+            logging.getLogger(__name__).warning(
+                "Skipping settings merge: %s or template is not a JSON object.", dst
+            )
+            return
+
+        changed = False
+        for key, value in new_settings.items():
+            if key not in existing:
+                existing[key] = value
+                changed = True
+            elif isinstance(existing[key], dict) and isinstance(value, dict):
+                for sub_key, sub_value in value.items():
+                    if sub_key not in existing[key]:
+                        existing[key][sub_key] = sub_value
+                        changed = True
+
+        if not changed:
+            return
+
+        dst.write_text(
+            json.dumps(existing, indent=4) + "\n", encoding="utf-8"
+        )

src/specify_cli/integrations/copilot/scripts/update-context.ps1

@@ -0,0 +1,22 @@
+# update-context.ps1 — Copilot integration: create/update .github/copilot-instructions.md
+#
+# This is the copilot-specific implementation that produces the GitHub
+# Copilot instructions file. The shared dispatcher reads
+# .specify/integration.json and calls this script.
+#
+# NOTE: This script is not yet active. It will be activated in Stage 7
+# when the shared update-agent-context.ps1 replaces its switch statement
+# with integration.json-based dispatch. The shared script must also be
+# refactored to support SPECKIT_SOURCE_ONLY (guard the Main call) before
+# dot-sourcing will work.
+#
+# Until then, this delegates to the shared script as a subprocess.
+
+$ErrorActionPreference = 'Stop'
+
+$repoRoot = git rev-parse --show-toplevel 2>$null
+if (-not $repoRoot) { $repoRoot = $PWD.Path }
+
+# Invoke shared update-agent-context script as a separate process.
+# Dot-sourcing is unsafe until that script guards its Main call.
+& "$repoRoot/.specify/scripts/powershell/update-agent-context.ps1" -AgentType copilot

src/specify_cli/integrations/copilot/scripts/update-context.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# update-context.sh — Copilot integration: create/update .github/copilot-instructions.md
+#
+# This is the copilot-specific implementation that produces the GitHub
+# Copilot instructions file. The shared dispatcher reads
+# .specify/integration.json and calls this script.
+#
+# NOTE: This script is not yet active. It will be activated in Stage 7
+# when the shared update-agent-context.sh replaces its case statement
+# with integration.json-based dispatch. The shared script must also be
+# refactored to support SPECKIT_SOURCE_ONLY (guard the main logic)
+# before sourcing will work.
+#
+# Until then, this delegates to the shared script as a subprocess.
+
+set -euo pipefail
+
+REPO_ROOT="${REPO_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+
+# Invoke shared update-agent-context script as a separate process.
+# Sourcing is unsafe until that script guards its main logic.
+exec "$REPO_ROOT/.specify/scripts/bash/update-agent-context.sh" copilot

src/specify_cli/integrations/manifest.py

@@ -0,0 +1,265 @@
+"""Hash-tracked installation manifest for integrations.
+
+Each installed integration records the files it created together with
+their SHA-256 hashes.  On uninstall only files whose hash still matches
+the recorded value are removed — modified files are left in place and
+reported to the caller.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+def _sha256(path: Path) -> str:
+    """Return the hex SHA-256 digest of *path*."""
+    h = hashlib.sha256()
+    with open(path, "rb") as fh:
+        for chunk in iter(lambda: fh.read(8192), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def _validate_rel_path(rel: Path, root: Path) -> Path:
+    """Resolve *rel* against *root* and verify it stays within *root*.
+
+    Raises ``ValueError`` if *rel* is absolute, contains ``..`` segments
+    that escape *root*, or otherwise resolves outside the project root.
+    """
+    if rel.is_absolute():
+        raise ValueError(
+            f"Absolute paths are not allowed in manifests: {rel}"
+        )
+    resolved = (root / rel).resolve()
+    root_resolved = root.resolve()
+    try:
+        resolved.relative_to(root_resolved)
+    except ValueError:
+        raise ValueError(
+            f"Path {rel} resolves to {resolved} which is outside "
+            f"the project root {root_resolved}"
+        ) from None
+    return resolved
+
+
+class IntegrationManifest:
+    """Tracks files installed by a single integration.
+
+    Parameters:
+        key:          Integration identifier (e.g. ``"copilot"``).
+        project_root: Absolute path to the project directory.
+        version:      CLI version string recorded in the manifest.
+    """
+
+    def __init__(self, key: str, project_root: Path, version: str = "") -> None:
+        self.key = key
+        self.project_root = project_root.resolve()
+        self.version = version
+        self._files: dict[str, str] = {}  # rel_path → sha256 hex
+        self._installed_at: str = ""
+
+    # -- Manifest file location -------------------------------------------
+
+    @property
+    def manifest_path(self) -> Path:
+        """Path to the on-disk manifest JSON."""
+        return self.project_root / ".specify" / "integrations" / f"{self.key}.manifest.json"
+
+    # -- Recording files --------------------------------------------------
+
+    def record_file(self, rel_path: str | Path, content: bytes | str) -> Path:
+        """Write *content* to *rel_path* (relative to project root) and record its hash.
+
+        Creates parent directories as needed.  Returns the absolute path
+        of the written file.
+
+        Raises ``ValueError`` if *rel_path* resolves outside the project root.
+        """
+        rel = Path(rel_path)
+        abs_path = _validate_rel_path(rel, self.project_root)
+        abs_path.parent.mkdir(parents=True, exist_ok=True)
+
+        if isinstance(content, str):
+            content = content.encode("utf-8")
+        abs_path.write_bytes(content)
+
+        normalized = abs_path.relative_to(self.project_root).as_posix()
+        self._files[normalized] = hashlib.sha256(content).hexdigest()
+        return abs_path
+
+    def record_existing(self, rel_path: str | Path) -> None:
+        """Record the hash of an already-existing file at *rel_path*.
+
+        Raises ``ValueError`` if *rel_path* resolves outside the project root.
+        """
+        rel = Path(rel_path)
+        abs_path = _validate_rel_path(rel, self.project_root)
+        normalized = abs_path.relative_to(self.project_root).as_posix()
+        self._files[normalized] = _sha256(abs_path)
+
+    # -- Querying ---------------------------------------------------------
+
+    @property
+    def files(self) -> dict[str, str]:
+        """Return a copy of the ``{rel_path: sha256}`` mapping."""
+        return dict(self._files)
+
+    def check_modified(self) -> list[str]:
+        """Return relative paths of tracked files whose content changed on disk."""
+        modified: list[str] = []
+        for rel, expected_hash in self._files.items():
+            rel_path = Path(rel)
+            # Skip paths that are absolute or attempt to escape the project root
+            if rel_path.is_absolute() or ".." in rel_path.parts:
+                continue
+            abs_path = self.project_root / rel_path
+            if not abs_path.exists() and not abs_path.is_symlink():
+                continue
+            # Treat symlinks and non-regular-files as modified
+            if abs_path.is_symlink() or not abs_path.is_file():
+                modified.append(rel)
+                continue
+            if _sha256(abs_path) != expected_hash:
+                modified.append(rel)
+        return modified
+
+    # -- Uninstall --------------------------------------------------------
+
+    def uninstall(
+        self,
+        project_root: Path | None = None,
+        *,
+        force: bool = False,
+    ) -> tuple[list[Path], list[Path]]:
+        """Remove tracked files whose hash still matches.
+
+        Parameters:
+            project_root: Override for the project root.
+            force:        If ``True``, remove files even if modified.
+
+        Returns:
+            ``(removed, skipped)`` — absolute paths.
+        """
+        root = (project_root or self.project_root).resolve()
+        removed: list[Path] = []
+        skipped: list[Path] = []
+
+        for rel, expected_hash in self._files.items():
+            # Use non-resolved path for deletion so symlinks themselves
+            # are removed, not their targets.
+            path = root / rel
+            # Validate containment lexically (without following symlinks)
+            # by collapsing .. segments via Path resolution on the string parts.
+            try:
+                normed = Path(os.path.normpath(path))
+                normed.relative_to(root)
+            except (ValueError, OSError):
+                continue
+            if not path.exists() and not path.is_symlink():
+                continue
+            # Skip directories — manifest only tracks files
+            if not path.is_file() and not path.is_symlink():
+                skipped.append(path)
+                continue
+            # Never follow symlinks when comparing hashes. Only remove
+            # symlinks when forced, to avoid acting on tampered entries.
+            if path.is_symlink():
+                if not force:
+                    skipped.append(path)
+                    continue
+            else:
+                if not force and _sha256(path) != expected_hash:
+                    skipped.append(path)
+                    continue
+            try:
+                path.unlink()
+            except OSError:
+                skipped.append(path)
+                continue
+            removed.append(path)
+            # Clean up empty parent directories up to project root
+            parent = path.parent
+            while parent != root:
+                try:
+                    parent.rmdir()  # only succeeds if empty
+                except OSError:
+                    break
+                parent = parent.parent
+
+        # Remove the manifest file itself
+        manifest = root / ".specify" / "integrations" / f"{self.key}.manifest.json"
+        if manifest.exists():
+            manifest.unlink()
+            parent = manifest.parent
+            while parent != root:
+                try:
+                    parent.rmdir()
+                except OSError:
+                    break
+                parent = parent.parent
+
+        return removed, skipped
+
+    # -- Persistence ------------------------------------------------------
+
+    def save(self) -> Path:
+        """Write the manifest to disk.  Returns the manifest path."""
+        self._installed_at = self._installed_at or datetime.now(timezone.utc).isoformat()
+        data: dict[str, Any] = {
+            "integration": self.key,
+            "version": self.version,
+            "installed_at": self._installed_at,
+            "files": self._files,
+        }
+        path = self.manifest_path
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+        return path
+
+    @classmethod
+    def load(cls, key: str, project_root: Path) -> IntegrationManifest:
+        """Load an existing manifest from disk.
+
+        Raises ``FileNotFoundError`` if the manifest does not exist.
+        """
+        inst = cls(key, project_root)
+        path = inst.manifest_path
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except json.JSONDecodeError as exc:
+            raise ValueError(
+                f"Integration manifest at {path} contains invalid JSON"
+            ) from exc
+
+        if not isinstance(data, dict):
+            raise ValueError(
+                f"Integration manifest at {path} must be a JSON object, "
+                f"got {type(data).__name__}"
+            )
+
+        files = data.get("files", {})
+        if not isinstance(files, dict) or not all(
+            isinstance(k, str) and isinstance(v, str) for k, v in files.items()
+        ):
+            raise ValueError(
+                f"Integration manifest 'files' at {path} must be a "
+                "mapping of string paths to string hashes"
+            )
+
+        inst.version = data.get("version", "")
+        inst._installed_at = data.get("installed_at", "")
+        inst._files = files
+
+        stored_key = data.get("integration", "")
+        if stored_key and stored_key != key:
+            raise ValueError(
+                f"Manifest at {path} belongs to integration {stored_key!r}, "
+                f"not {key!r}"
+            )
+
+        return inst

src/specify_cli/presets.py

@@ -7,6 +7,7 @@ Presets are self-contained, versioned collections of templates
 customize the Spec-Driven Development workflow.
 """
 
+import copy
 import json
 import hashlib
 import os
@@ -23,6 +24,8 @@ import yaml
 from packaging import version as pkg_version
 from packaging.specifiers import SpecifierSet, InvalidSpecifier
 
+from .extensions import ExtensionRegistry, normalize_priority
+
 
 @dataclass
 class PresetCatalogEntry:
@@ -235,7 +238,17 @@ class PresetRegistry:
 
         try:
             with open(self.registry_path, 'r') as f:
-                return json.load(f)
+                data = json.load(f)
+            # Validate loaded data is a dict (handles corrupted registry files)
+            if not isinstance(data, dict):
+                return {
+                    "schema_version": self.SCHEMA_VERSION,
+                    "presets": {}
+                }
+            # Normalize presets field (handles corrupted presets value)
+            if not isinstance(data.get("presets"), dict):
+                data["presets"] = {}
+            return data
         except (json.JSONDecodeError, FileNotFoundError):
             return {
                 "schema_version": self.SCHEMA_VERSION,
@@ -256,7 +269,7 @@ class PresetRegistry:
             metadata: Pack metadata (version, source, etc.)
         """
         self.data["presets"][pack_id] = {
-            **metadata,
+            **copy.deepcopy(metadata),
             "installed_at": datetime.now(timezone.utc).isoformat()
         }
         self._save()
@@ -267,41 +280,152 @@ class PresetRegistry:
         Args:
             pack_id: Preset ID
         """
-        if pack_id in self.data["presets"]:
-            del self.data["presets"][pack_id]
+        packs = self.data.get("presets")
+        if not isinstance(packs, dict):
+            return
+        if pack_id in packs:
+            del packs[pack_id]
             self._save()
 
+    def update(self, pack_id: str, updates: dict):
+        """Update preset metadata in registry.
+
+        Merges the provided updates with the existing entry, preserving any
+        fields not specified. The installed_at timestamp is always preserved
+        from the original entry.
+
+        Args:
+            pack_id: Preset ID
+            updates: Partial metadata to merge into existing metadata
+
+        Raises:
+            KeyError: If preset is not installed
+        """
+        packs = self.data.get("presets")
+        if not isinstance(packs, dict) or pack_id not in packs:
+            raise KeyError(f"Preset '{pack_id}' not found in registry")
+        existing = packs[pack_id]
+        # Handle corrupted registry entries (e.g., string/list instead of dict)
+        if not isinstance(existing, dict):
+            existing = {}
+        # Merge: existing fields preserved, new fields override (deep copy to prevent caller mutation)
+        merged = {**existing, **copy.deepcopy(updates)}
+        # Always preserve original installed_at based on key existence, not truthiness,
+        # to handle cases where the field exists but may be falsy (legacy/corruption)
+        if "installed_at" in existing:
+            merged["installed_at"] = existing["installed_at"]
+        else:
+            # If not present in existing, explicitly remove from merged if caller provided it
+            merged.pop("installed_at", None)
+        packs[pack_id] = merged
+        self._save()
+
+    def restore(self, pack_id: str, metadata: dict):
+        """Restore preset metadata to registry without modifying timestamps.
+
+        Use this method for rollback scenarios where you have a complete backup
+        of the registry entry (including installed_at) and want to restore it
+        exactly as it was.
+
+        Args:
+            pack_id: Preset ID
+            metadata: Complete preset metadata including installed_at
+
+        Raises:
+            ValueError: If metadata is None or not a dict
+        """
+        if metadata is None or not isinstance(metadata, dict):
+            raise ValueError(f"Cannot restore '{pack_id}': metadata must be a dict")
+        # Ensure presets dict exists (handle corrupted registry)
+        if not isinstance(self.data.get("presets"), dict):
+            self.data["presets"] = {}
+        self.data["presets"][pack_id] = copy.deepcopy(metadata)
+        self._save()
+
     def get(self, pack_id: str) -> Optional[dict]:
         """Get preset metadata from registry.
 
+        Returns a deep copy to prevent callers from accidentally mutating
+        nested internal registry state without going through the write path.
+
         Args:
             pack_id: Preset ID
 
         Returns:
-            Pack metadata or None if not found
+            Deep copy of preset metadata, or None if not found or corrupted
         """
-        return self.data["presets"].get(pack_id)
+        packs = self.data.get("presets")
+        if not isinstance(packs, dict):
+            return None
+        entry = packs.get(pack_id)
+        # Return None for missing or corrupted (non-dict) entries
+        if entry is None or not isinstance(entry, dict):
+            return None
+        return copy.deepcopy(entry)
 
     def list(self) -> Dict[str, dict]:
-        """Get all installed presets.
+        """Get all installed presets with valid metadata.
+
+        Returns a deep copy of presets with dict metadata only.
+        Corrupted entries (non-dict values) are filtered out.
 
         Returns:
-            Dictionary of pack_id -> metadata
+            Dictionary of pack_id -> metadata (deep copies), empty dict if corrupted
         """
-        return self.data["presets"]
+        packs = self.data.get("presets", {}) or {}
+        if not isinstance(packs, dict):
+            return {}
+        # Filter to only valid dict entries to match type contract
+        return {
+            pack_id: copy.deepcopy(meta)
+            for pack_id, meta in packs.items()
+            if isinstance(meta, dict)
+        }
 
-    def list_by_priority(self) -> List[tuple]:
+    def keys(self) -> set:
+        """Get all preset IDs including corrupted entries.
+
+        Lightweight method that returns IDs without deep-copying metadata.
+        Use this when you only need to check which presets are tracked.
+
+        Returns:
+            Set of preset IDs (includes corrupted entries)
+        """
+        packs = self.data.get("presets", {}) or {}
+        if not isinstance(packs, dict):
+            return set()
+        return set(packs.keys())
+
+    def list_by_priority(self, include_disabled: bool = False) -> List[tuple]:
         """Get all installed presets sorted by priority.
 
         Lower priority number = higher precedence (checked first).
+        Presets with equal priority are sorted alphabetically by ID
+        for deterministic ordering.
+
+        Args:
+            include_disabled: If True, include disabled presets. Default False.
 
         Returns:
-            List of (pack_id, metadata) tuples sorted by priority
+            List of (pack_id, metadata_copy) tuples sorted by priority.
+            Metadata is deep-copied to prevent accidental mutation.
         """
-        packs = self.data["presets"]
+        packs = self.data.get("presets", {}) or {}
+        if not isinstance(packs, dict):
+            packs = {}
+        sortable_packs = []
+        for pack_id, meta in packs.items():
+            if not isinstance(meta, dict):
+                continue
+            # Skip disabled presets unless explicitly requested
+            if not include_disabled and not meta.get("enabled", True):
+                continue
+            metadata_copy = copy.deepcopy(meta)
+            metadata_copy["priority"] = normalize_priority(metadata_copy.get("priority", 10))
+            sortable_packs.append((pack_id, metadata_copy))
         return sorted(
-            packs.items(),
-            key=lambda item: item[1].get("priority", 10),
+            sortable_packs,
+            key=lambda item: (item[1]["priority"], item[0]),
         )
 
     def is_installed(self, pack_id: str) -> bool:
@@ -311,9 +435,12 @@ class PresetRegistry:
             pack_id: Preset ID
 
         Returns:
-            True if pack is installed
+            True if pack is installed, False if not or registry corrupted
         """
-        return pack_id in self.data["presets"]
+        packs = self.data.get("presets")
+        if not isinstance(packs, dict):
+            return False
+        return pack_id in packs
 
 
 class PresetManager:
@@ -429,24 +556,31 @@ class PresetManager:
         registrar.unregister_commands(registered_commands, self.project_root)
 
     def _get_skills_dir(self) -> Optional[Path]:
-        """Return the skills directory if ``--ai-skills`` was used during init.
+        """Return the active skills directory for preset skill overrides.
 
         Reads ``.specify/init-options.json`` to determine whether skills
         are enabled and which agent was selected, then delegates to
         the module-level ``_get_skills_dir()`` helper for the concrete path.
 
+        Kimi is treated as a native-skills agent: if ``ai == "kimi"`` and
+        ``.kimi/skills`` exists, presets should still propagate command
+        overrides to skills even when ``ai_skills`` is false.
+
         Returns:
             The skills directory ``Path``, or ``None`` if skills were not
-            enabled or the init-options file is missing.
+            enabled and no native-skills fallback applies.
         """
         from . import load_init_options, _get_skills_dir
 
         opts = load_init_options(self.project_root)
-        if not opts.get("ai_skills"):
+        if not isinstance(opts, dict):
+            opts = {}
+        agent = opts.get("ai")
+        if not isinstance(agent, str) or not agent:
             return None
 
-        agent = opts.get("ai")
-        if not agent:
+        ai_skills_enabled = bool(opts.get("ai_skills"))
+        if not ai_skills_enabled and agent != "kimi":
             return None
 
         skills_dir = _get_skills_dir(self.project_root, agent)
@@ -455,6 +589,76 @@ class PresetManager:
 
         return skills_dir
 
+    @staticmethod
+    def _skill_names_for_command(cmd_name: str) -> tuple[str, str]:
+        """Return the modern and legacy skill directory names for a command."""
+        raw_short_name = cmd_name
+        if raw_short_name.startswith("speckit."):
+            raw_short_name = raw_short_name[len("speckit."):]
+
+        modern_skill_name = f"speckit-{raw_short_name.replace('.', '-')}"
+        legacy_skill_name = f"speckit.{raw_short_name}"
+        return modern_skill_name, legacy_skill_name
+
+    @staticmethod
+    def _skill_title_from_command(cmd_name: str) -> str:
+        """Return a human-friendly title for a skill command name."""
+        title_name = cmd_name
+        if title_name.startswith("speckit."):
+            title_name = title_name[len("speckit."):]
+        return title_name.replace(".", " ").replace("-", " ").title()
+
+    def _build_extension_skill_restore_index(self) -> Dict[str, Dict[str, Any]]:
+        """Index extension-backed skill restore data by skill directory name."""
+        from .extensions import ExtensionManifest, ValidationError
+
+        resolver = PresetResolver(self.project_root)
+        extensions_dir = self.project_root / ".specify" / "extensions"
+        restore_index: Dict[str, Dict[str, Any]] = {}
+
+        for _priority, ext_id, _metadata in resolver._get_all_extensions_by_priority():
+            ext_dir = extensions_dir / ext_id
+            manifest_path = ext_dir / "extension.yml"
+            if not manifest_path.is_file():
+                continue
+
+            try:
+                manifest = ExtensionManifest(manifest_path)
+            except ValidationError:
+                continue
+
+            ext_root = ext_dir.resolve()
+            for cmd_info in manifest.commands:
+                cmd_name = cmd_info.get("name")
+                cmd_file_rel = cmd_info.get("file")
+                if not isinstance(cmd_name, str) or not isinstance(cmd_file_rel, str):
+                    continue
+
+                cmd_path = Path(cmd_file_rel)
+                if cmd_path.is_absolute():
+                    continue
+
+                try:
+                    source_file = (ext_root / cmd_path).resolve()
+                    source_file.relative_to(ext_root)
+                except (OSError, ValueError):
+                    continue
+
+                if not source_file.is_file():
+                    continue
+
+                restore_info = {
+                    "command_name": cmd_name,
+                    "source_file": source_file,
+                    "source": f"extension:{manifest.id}",
+                }
+                modern_skill_name, legacy_skill_name = self._skill_names_for_command(cmd_name)
+                restore_index.setdefault(modern_skill_name, restore_info)
+                if legacy_skill_name != modern_skill_name:
+                    restore_index.setdefault(legacy_skill_name, restore_info)
+
+        return restore_index
+
     def _register_skills(
         self,
         manifest: "PresetManifest",
@@ -502,9 +706,15 @@ class PresetManager:
             return []
 
         from . import SKILL_DESCRIPTIONS, load_init_options
+        from .agents import CommandRegistrar
 
-        opts = load_init_options(self.project_root)
-        selected_ai = opts.get("ai", "")
+        init_opts = load_init_options(self.project_root)
+        if not isinstance(init_opts, dict):
+            init_opts = {}
+        selected_ai = init_opts.get("ai")
+        if not isinstance(selected_ai, str):
+            return []
+        registrar = CommandRegistrar()
 
         written: List[str] = []
 
@@ -516,64 +726,61 @@ class PresetManager:
                 continue
 
             # Derive the short command name (e.g. "specify" from "speckit.specify")
-            short_name = cmd_name
-            if short_name.startswith("speckit."):
-                short_name = short_name[len("speckit."):]
-            # Kimi CLI discovers skills by directory name and invokes them as
-            # /skill:<name> — use dot separator to match packaging convention.
-            if selected_ai == "kimi":
-                skill_name = f"speckit.{short_name}"
-            else:
-                skill_name = f"speckit-{short_name}"
+            raw_short_name = cmd_name
+            if raw_short_name.startswith("speckit."):
+                raw_short_name = raw_short_name[len("speckit."):]
+            short_name = raw_short_name.replace(".", "-")
+            skill_name, legacy_skill_name = self._skill_names_for_command(cmd_name)
+            skill_title = self._skill_title_from_command(cmd_name)
 
-            # Only overwrite if the skill already exists (i.e. --ai-skills was used)
-            skill_subdir = skills_dir / skill_name
-            if not skill_subdir.exists():
+            # Only overwrite skills that already exist under skills_dir,
+            # including Kimi native skills when ai_skills is false.
+            # If both modern and legacy directories exist, update both.
+            target_skill_names: List[str] = []
+            if (skills_dir / skill_name).is_dir():
+                target_skill_names.append(skill_name)
+            if legacy_skill_name != skill_name and (skills_dir / legacy_skill_name).is_dir():
+                target_skill_names.append(legacy_skill_name)
+            if not target_skill_names:
                 continue
 
             # Parse the command file
             content = source_file.read_text(encoding="utf-8")
-            if content.startswith("---"):
-                parts = content.split("---", 2)
-                if len(parts) >= 3:
-                    frontmatter = yaml.safe_load(parts[1])
-                    if not isinstance(frontmatter, dict):
-                        frontmatter = {}
-                    body = parts[2].strip()
-                else:
-                    frontmatter = {}
-                    body = content
-            else:
-                frontmatter = {}
-                body = content
+            frontmatter, body = registrar.parse_frontmatter(content)
 
             original_desc = frontmatter.get("description", "")
             enhanced_desc = SKILL_DESCRIPTIONS.get(
                 short_name,
                 original_desc or f"Spec-kit workflow command: {short_name}",
             )
-
-            frontmatter_data = {
-                "name": skill_name,
-                "description": enhanced_desc,
-                "compatibility": "Requires spec-kit project structure with .specify/ directory",
-                "metadata": {
-                    "author": "github-spec-kit",
-                    "source": f"preset:{manifest.id}",
-                },
-            }
-            frontmatter_text = yaml.safe_dump(frontmatter_data, sort_keys=False).strip()
-            skill_content = (
-                f"---\n"
-                f"{frontmatter_text}\n"
-                f"---\n\n"
-                f"# Speckit {short_name.title()} Skill\n\n"
-                f"{body}\n"
+            frontmatter = dict(frontmatter)
+            frontmatter["description"] = enhanced_desc
+            body = registrar.resolve_skill_placeholders(
+                selected_ai, frontmatter, body, self.project_root
             )
 
-            skill_file = skill_subdir / "SKILL.md"
-            skill_file.write_text(skill_content, encoding="utf-8")
-            written.append(skill_name)
+            for target_skill_name in target_skill_names:
+                frontmatter_data = {
+                    "name": target_skill_name,
+                    "description": enhanced_desc,
+                    "compatibility": "Requires spec-kit project structure with .specify/ directory",
+                    "metadata": {
+                        "author": "github-spec-kit",
+                        "source": f"preset:{manifest.id}",
+                    },
+                }
+                frontmatter_text = yaml.safe_dump(frontmatter_data, sort_keys=False).strip()
+                skill_content = (
+                    f"---\n"
+                    f"{frontmatter_text}\n"
+                    f"---\n\n"
+                    f"# Speckit {skill_title} Skill\n\n"
+                    f"{body}\n"
+                )
+
+                skill_file = skills_dir / target_skill_name / "SKILL.md"
+                skill_file.write_text(skill_content, encoding="utf-8")
+                written.append(target_skill_name)
 
         return written
 
@@ -595,10 +802,17 @@ class PresetManager:
         if not skills_dir:
             return
 
-        from . import SKILL_DESCRIPTIONS
+        from . import SKILL_DESCRIPTIONS, load_init_options
+        from .agents import CommandRegistrar
 
         # Locate core command templates from the project's installed templates
         core_templates_dir = self.project_root / ".specify" / "templates" / "commands"
+        init_opts = load_init_options(self.project_root)
+        if not isinstance(init_opts, dict):
+            init_opts = {}
+        selected_ai = init_opts.get("ai")
+        registrar = CommandRegistrar()
+        extension_restore_index = self._build_extension_skill_restore_index()
 
         for skill_name in skill_names:
             # Derive command name from skill name (speckit-specify -> specify)
@@ -610,7 +824,10 @@ class PresetManager:
 
             skill_subdir = skills_dir / skill_name
             skill_file = skill_subdir / "SKILL.md"
-            if not skill_file.exists():
+            if not skill_subdir.is_dir():
+                continue
+            if not skill_file.is_file():
+                # Only manage directories that contain the expected skill entrypoint.
                 continue
 
             # Try to find the core command template
@@ -621,19 +838,11 @@ class PresetManager:
             if core_file:
                 # Restore from core template
                 content = core_file.read_text(encoding="utf-8")
-                if content.startswith("---"):
-                    parts = content.split("---", 2)
-                    if len(parts) >= 3:
-                        frontmatter = yaml.safe_load(parts[1])
-                        if not isinstance(frontmatter, dict):
-                            frontmatter = {}
-                        body = parts[2].strip()
-                    else:
-                        frontmatter = {}
-                        body = content
-                else:
-                    frontmatter = {}
-                    body = content
+                frontmatter, body = registrar.parse_frontmatter(content)
+                if isinstance(selected_ai, str):
+                    body = registrar.resolve_skill_placeholders(
+                        selected_ai, frontmatter, body, self.project_root
+                    )
 
                 original_desc = frontmatter.get("description", "")
                 enhanced_desc = SKILL_DESCRIPTIONS.get(
@@ -651,16 +860,49 @@ class PresetManager:
                     },
                 }
                 frontmatter_text = yaml.safe_dump(frontmatter_data, sort_keys=False).strip()
+                skill_title = self._skill_title_from_command(short_name)
                 skill_content = (
                     f"---\n"
                     f"{frontmatter_text}\n"
                     f"---\n\n"
-                    f"# Speckit {short_name.title()} Skill\n\n"
+                    f"# Speckit {skill_title} Skill\n\n"
+                    f"{body}\n"
+                )
+                skill_file.write_text(skill_content, encoding="utf-8")
+                continue
+
+            extension_restore = extension_restore_index.get(skill_name)
+            if extension_restore:
+                content = extension_restore["source_file"].read_text(encoding="utf-8")
+                frontmatter, body = registrar.parse_frontmatter(content)
+                if isinstance(selected_ai, str):
+                    body = registrar.resolve_skill_placeholders(
+                        selected_ai, frontmatter, body, self.project_root
+                    )
+
+                command_name = extension_restore["command_name"]
+                title_name = self._skill_title_from_command(command_name)
+
+                frontmatter_data = {
+                    "name": skill_name,
+                    "description": frontmatter.get("description", f"Extension command: {command_name}"),
+                    "compatibility": "Requires spec-kit project structure with .specify/ directory",
+                    "metadata": {
+                        "author": "github-spec-kit",
+                        "source": extension_restore["source"],
+                    },
+                }
+                frontmatter_text = yaml.safe_dump(frontmatter_data, sort_keys=False).strip()
+                skill_content = (
+                    f"---\n"
+                    f"{frontmatter_text}\n"
+                    f"---\n\n"
+                    f"# {title_name} Skill\n\n"
                     f"{body}\n"
                 )
                 skill_file.write_text(skill_content, encoding="utf-8")
             else:
-                # No core template — remove the skill entirely
+                # No core or extension template — remove the skill entirely
                 shutil.rmtree(skill_subdir)
 
     def install_from_directory(
@@ -680,9 +922,13 @@ class PresetManager:
             Installed preset manifest
 
         Raises:
-            PresetValidationError: If manifest is invalid
+            PresetValidationError: If manifest is invalid or priority is invalid
             PresetCompatibilityError: If pack is incompatible
         """
+        # Validate priority
+        if priority < 1:
+            raise PresetValidationError("Priority must be a positive integer (1 or higher)")
+
         manifest_path = source_dir / "preset.yml"
         manifest = PresetManifest(manifest_path)
 
@@ -729,14 +975,19 @@ class PresetManager:
         Args:
             zip_path: Path to preset ZIP file
             speckit_version: Current spec-kit version
+            priority: Resolution priority (lower = higher precedence, default 10)
 
         Returns:
             Installed preset manifest
 
         Raises:
-            PresetValidationError: If manifest is invalid
+            PresetValidationError: If manifest is invalid or priority is invalid
             PresetCompatibilityError: If pack is incompatible
         """
+        # Validate priority early
+        if priority < 1:
+            raise PresetValidationError("Priority must be a positive integer (1 or higher)")
+
         with tempfile.TemporaryDirectory() as tmpdir:
             temp_path = Path(tmpdir)
 
@@ -781,17 +1032,26 @@ class PresetManager:
         if not self.registry.is_installed(pack_id):
             return False
 
-        # Unregister commands from AI agents
         metadata = self.registry.get(pack_id)
-        registered_commands = metadata.get("registered_commands", {}) if metadata else {}
-        if registered_commands:
-            self._unregister_commands(registered_commands)
-
         # Restore original skills when preset is removed
         registered_skills = metadata.get("registered_skills", []) if metadata else []
+        registered_commands = metadata.get("registered_commands", {}) if metadata else {}
         pack_dir = self.presets_dir / pack_id
         if registered_skills:
             self._unregister_skills(registered_skills, pack_dir)
+            try:
+                from . import NATIVE_SKILLS_AGENTS
+            except ImportError:
+                NATIVE_SKILLS_AGENTS = set()
+            registered_commands = {
+                agent_name: cmd_names
+                for agent_name, cmd_names in registered_commands.items()
+                if agent_name not in NATIVE_SKILLS_AGENTS
+            }
+
+        # Unregister non-skill command files from AI agents.
+        if registered_commands:
+            self._unregister_commands(registered_commands)
 
         if pack_dir.exists():
             shutil.rmtree(pack_dir)
@@ -808,6 +1068,9 @@ class PresetManager:
         result = []
 
         for pack_id, metadata in self.registry.list().items():
+            # Ensure metadata is a dictionary to avoid AttributeError when using .get()
+            if not isinstance(metadata, dict):
+                metadata = {}
             pack_dir = self.presets_dir / pack_id
             manifest_path = pack_dir / "preset.yml"
 
@@ -816,13 +1079,13 @@ class PresetManager:
                 result.append({
                     "id": pack_id,
                     "name": manifest.name,
-                    "version": metadata["version"],
+                    "version": metadata.get("version", manifest.version),
                     "description": manifest.description,
                     "enabled": metadata.get("enabled", True),
                     "installed_at": metadata.get("installed_at"),
                     "template_count": len(manifest.templates),
                     "tags": manifest.tags,
-                    "priority": metadata.get("priority", 10),
+                    "priority": normalize_priority(metadata.get("priority")),
                 })
             except PresetValidationError:
                 result.append({
@@ -834,7 +1097,7 @@ class PresetManager:
                     "installed_at": metadata.get("installed_at"),
                     "template_count": 0,
                     "tags": [],
-                    "priority": metadata.get("priority", 10),
+                    "priority": normalize_priority(metadata.get("priority")),
                 })
 
         return result
@@ -925,8 +1188,8 @@ class PresetCatalog:
         if not config_path.exists():
             return None
         try:
-            data = yaml.safe_load(config_path.read_text()) or {}
-        except (yaml.YAMLError, OSError) as e:
+            data = yaml.safe_load(config_path.read_text(encoding="utf-8")) or {}
+        except (yaml.YAMLError, OSError, UnicodeError) as e:
             raise PresetValidationError(
                 f"Failed to read catalog config {config_path}: {e}"
             )
@@ -1393,6 +1656,48 @@ class PresetResolver:
         self.overrides_dir = self.templates_dir / "overrides"
         self.extensions_dir = project_root / ".specify" / "extensions"
 
+    def _get_all_extensions_by_priority(self) -> list[tuple[int, str, dict | None]]:
+        """Build unified list of registered and unregistered extensions sorted by priority.
+
+        Registered extensions use their stored priority; unregistered directories
+        get implicit priority=10. Results are sorted by (priority, ext_id) for
+        deterministic ordering.
+
+        Returns:
+            List of (priority, ext_id, metadata_or_none) tuples sorted by priority.
+        """
+        if not self.extensions_dir.exists():
+            return []
+
+        registry = ExtensionRegistry(self.extensions_dir)
+        # Use keys() to track ALL extensions (including corrupted entries) without deep copy
+        # This prevents corrupted entries from being picked up as "unregistered" dirs
+        registered_extension_ids = registry.keys()
+
+        # Get all registered extensions including disabled; we filter disabled manually below
+        all_registered = registry.list_by_priority(include_disabled=True)
+
+        all_extensions: list[tuple[int, str, dict | None]] = []
+
+        # Only include enabled extensions in the result
+        for ext_id, metadata in all_registered:
+            # Skip disabled extensions
+            if not metadata.get("enabled", True):
+                continue
+            priority = normalize_priority(metadata.get("priority") if metadata else None)
+            all_extensions.append((priority, ext_id, metadata))
+
+        # Add unregistered directories with implicit priority=10
+        for ext_dir in self.extensions_dir.iterdir():
+            if not ext_dir.is_dir() or ext_dir.name.startswith("."):
+                continue
+            if ext_dir.name not in registered_extension_ids:
+                all_extensions.append((10, ext_dir.name, None))
+
+        # Sort by (priority, ext_id) for deterministic ordering
+        all_extensions.sort(key=lambda x: (x[0], x[1]))
+        return all_extensions
+
     def resolve(
         self,
         template_name: str,
@@ -1445,18 +1750,18 @@ class PresetResolver:
                     if candidate.exists():
                         return candidate
 
-        # Priority 3: Extension-provided templates
-        if self.extensions_dir.exists():
-            for ext_dir in sorted(self.extensions_dir.iterdir()):
-                if not ext_dir.is_dir() or ext_dir.name.startswith("."):
-                    continue
-                for subdir in subdirs:
-                    if subdir:
-                        candidate = ext_dir / subdir / f"{template_name}{ext}"
-                    else:
-                        candidate = ext_dir / "templates" / f"{template_name}{ext}"
-                    if candidate.exists():
-                        return candidate
+        # Priority 3: Extension-provided templates (sorted by priority — lower number wins)
+        for _priority, ext_id, _metadata in self._get_all_extensions_by_priority():
+            ext_dir = self.extensions_dir / ext_id
+            if not ext_dir.is_dir():
+                continue
+            for subdir in subdirs:
+                if subdir:
+                    candidate = ext_dir / subdir / f"{template_name}{ext}"
+                else:
+                    candidate = ext_dir / f"{template_name}{ext}"
+                if candidate.exists():
+                    return candidate
 
         # Priority 4: Core templates
         if template_type == "template":
@@ -1514,17 +1819,24 @@ class PresetResolver:
                 except ValueError:
                     continue
 
-        if self.extensions_dir.exists():
-            for ext_dir in sorted(self.extensions_dir.iterdir()):
-                if not ext_dir.is_dir() or ext_dir.name.startswith("."):
-                    continue
-                try:
-                    resolved.relative_to(ext_dir)
+        for _priority, ext_id, ext_meta in self._get_all_extensions_by_priority():
+            ext_dir = self.extensions_dir / ext_id
+            if not ext_dir.is_dir():
+                continue
+            try:
+                resolved.relative_to(ext_dir)
+                if ext_meta:
+                    version = ext_meta.get("version", "?")
                     return {
                         "path": resolved_str,
-                        "source": f"extension:{ext_dir.name}",
+                        "source": f"extension:{ext_id} v{version}",
                     }
-                except ValueError:
-                    continue
+                else:
+                    return {
+                        "path": resolved_str,
+                        "source": f"extension:{ext_id} (unregistered)",
+                    }
+            except ValueError:
+                continue
 
         return {"path": resolved_str, "source": "core"}

templates/commands/analyze.md

@@ -44,7 +44,7 @@ Load only the minimal necessary context from each artifact:
 
 - Overview/Context
 - Functional Requirements
-- Non-Functional Requirements
+- Success Criteria (measurable outcomes — e.g., performance, security, availability, user success, business impact)
 - User Stories
 - Edge Cases (if present)
 
@@ -71,7 +71,7 @@ Load only the minimal necessary context from each artifact:
 
 Create internal representations (do not include raw artifacts in output):
 
-- **Requirements inventory**: Each functional + non-functional requirement with a stable key (derive slug based on imperative phrase; e.g., "User can upload file" → `user-can-upload-file`)
+- **Requirements inventory**: For each Functional Requirement (FR-###) and Success Criterion (SC-###), record a stable key. Use the explicit FR-/SC- identifier as the primary key when present, and optionally also derive an imperative-phrase slug for readability (e.g., "User can upload file" → `user-can-upload-file`). Include only Success Criteria items that require buildable work (e.g., load-testing infrastructure, security audit tooling), and exclude post-launch outcome metrics and business KPIs (e.g., "Reduce support tickets by 50%").
 - **User story/action inventory**: Discrete user actions with acceptance criteria
 - **Task coverage mapping**: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases)
 - **Constitution rule set**: Extract principle names and MUST/SHOULD normative statements
@@ -105,7 +105,7 @@ Focus on high-signal findings. Limit to 50 findings total; aggregate remainder i
 
 - Requirements with zero associated tasks
 - Tasks with no mapped requirement/story
-- Non-functional requirements not reflected in tasks (e.g., performance, security)
+- Success Criteria requiring buildable work (performance, security, availability) not reflected in tasks
 
 #### F. Inconsistency
 

templates/commands/clarify.md

@@ -145,7 +145,7 @@ Execution steps:
        - Functional ambiguity → Update or add a bullet in Functional Requirements.
        - User interaction / actor distinction → Update User Stories or Actors subsection (if present) with clarified role, constraint, or scenario.
        - Data shape / entities → Update Data Model (add fields, types, relationships) preserving ordering; note added constraints succinctly.
-       - Non-functional constraint → Add/modify measurable criteria in Non-Functional / Quality Attributes section (convert vague adjective to metric or explicit target).
+       - Non-functional constraint → Add/modify measurable criteria in Success Criteria > Measurable Outcomes (convert vague adjective to metric or explicit target).
        - Edge case / negative flow → Add a new bullet under Edge Cases / Error Handling (or create such subsection if template provides placeholder for it).
        - Terminology conflict → Normalize term across spec; retain original only if necessary by adding `(formerly referred to as "X")` once.
     - If the clarification invalidates an earlier ambiguous statement, replace that statement instead of duplicating; leave no obsolete contradictory text.

templates/commands/implement.md

@@ -19,7 +19,7 @@ You **MUST** consider the user input before proceeding (if not empty).
 - Check if `.specify/extensions.yml` exists in the project root.
 - If it exists, read it and look for entries under the `hooks.before_implement` key
 - If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
-- Filter to only hooks where `enabled: true`
+- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
 - For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
   - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
   - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
@@ -174,7 +174,7 @@ Note: This command assumes a complete task breakdown exists in tasks.md. If task
 10. **Check for extension hooks**: After completion validation, check if `.specify/extensions.yml` exists in the project root.
     - If it exists, read it and look for entries under the `hooks.after_implement` key
     - If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
-    - Filter to only hooks where `enabled: true`
+    - Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
     - For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
       - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
       - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation

templates/commands/plan.md

@@ -24,6 +24,40 @@ $ARGUMENTS
 
 You **MUST** consider the user input before proceeding (if not empty).
 
+## Pre-Execution Checks
+
+**Check for extension hooks (before planning)**:
+- Check if `.specify/extensions.yml` exists in the project root.
+- If it exists, read it and look for entries under the `hooks.before_plan` key
+- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+  - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+- For each executable hook, output the following based on its `optional` flag:
+  - **Optional hook** (`optional: true`):
+    ```
+    ## Extension Hooks
+
+    **Optional Pre-Hook**: {extension}
+    Command: `/{command}`
+    Description: {description}
+
+    Prompt: {prompt}
+    To execute: `/{command}`
+    ```
+  - **Mandatory hook** (`optional: false`):
+    ```
+    ## Extension Hooks
+
+    **Automatic Pre-Hook**: {extension}
+    Executing: `/{command}`
+    EXECUTE_COMMAND: {command}
+
+    Wait for the result of the hook command before proceeding to the Outline.
+    ```
+- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+
 ## Outline
 
 1. **Setup**: Run `{SCRIPT}` from repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
@@ -41,6 +75,35 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 4. **Stop and report**: Command ends after Phase 2 planning. Report branch, IMPL_PLAN path, and generated artifacts.
 
+5. **Check for extension hooks**: After reporting, check if `.specify/extensions.yml` exists in the project root.
+   - If it exists, read it and look for entries under the `hooks.after_plan` key
+   - If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+   - Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+   - For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+     - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+     - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+   - For each executable hook, output the following based on its `optional` flag:
+     - **Optional hook** (`optional: true`):
+       ```
+       ## Extension Hooks
+
+       **Optional Hook**: {extension}
+       Command: `/{command}`
+       Description: {description}
+
+       Prompt: {prompt}
+       To execute: `/{command}`
+       ```
+     - **Mandatory hook** (`optional: false`):
+       ```
+       ## Extension Hooks
+
+       **Automatic Hook**: {extension}
+       Executing: `/{command}`
+       EXECUTE_COMMAND: {command}
+       ```
+   - If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+
 ## Phases
 
 ### Phase 0: Outline & Research

templates/commands/specify.md

@@ -21,6 +21,40 @@ $ARGUMENTS
 
 You **MUST** consider the user input before proceeding (if not empty).
 
+## Pre-Execution Checks
+
+**Check for extension hooks (before specification)**:
+- Check if `.specify/extensions.yml` exists in the project root.
+- If it exists, read it and look for entries under the `hooks.before_specify` key
+- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+  - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+- For each executable hook, output the following based on its `optional` flag:
+  - **Optional hook** (`optional: true`):
+    ```
+    ## Extension Hooks
+
+    **Optional Pre-Hook**: {extension}
+    Command: `/{command}`
+    Description: {description}
+
+    Prompt: {prompt}
+    To execute: `/{command}`
+    ```
+  - **Mandatory hook** (`optional: false`):
+    ```
+    ## Extension Hooks
+
+    **Automatic Pre-Hook**: {extension}
+    Executing: `/{command}`
+    EXECUTE_COMMAND: {command}
+
+    Wait for the result of the hook command before proceeding to the Outline.
+    ```
+- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+
 ## Outline
 
 The text the user typed after `/speckit.specify` in the triggering message **is** the feature description. Assume you always have it available in this conversation even if `{ARGS}` appears literally below. Do not ask the user to repeat it unless they provided an empty command.
@@ -39,10 +73,16 @@ Given that feature description, do this:
      - "Create a dashboard for analytics" → "analytics-dashboard"
      - "Fix payment processing timeout bug" → "fix-payment-timeout"
 
-2. **Create the feature branch** by running the script with `--short-name` (and `--json`), and do NOT pass `--number` (the script auto-detects the next globally available number across all branches and spec directories):
+2. **Create the feature branch** by running the script with `--short-name` (and `--json`). In sequential mode, do NOT pass `--number` — the script auto-detects the next available number. In timestamp mode, the script generates a `YYYYMMDD-HHMMSS` prefix automatically:
+
+   **Branch numbering mode**: Before running the script, check if `.specify/init-options.json` exists and read the `branch_numbering` value.
+   - If `"timestamp"`, add `--timestamp` (Bash) or `-Timestamp` (PowerShell) to the script invocation
+   - If `"sequential"` or absent, do not add any extra flag (default behavior)
 
    - Bash example: `{SCRIPT} --json --short-name "user-auth" "Add user authentication"`
+   - Bash (timestamp): `{SCRIPT} --json --timestamp --short-name "user-auth" "Add user authentication"`
    - PowerShell example: `{SCRIPT} -Json -ShortName "user-auth" "Add user authentication"`
+   - PowerShell (timestamp): `{SCRIPT} -Json -Timestamp -ShortName "user-auth" "Add user authentication"`
 
    **IMPORTANT**:
    - Do NOT pass `--number` — the script determines the correct next number automatically
@@ -176,6 +216,35 @@ Given that feature description, do this:
 
 7. Report completion with branch name, spec file path, checklist results, and readiness for the next phase (`/speckit.clarify` or `/speckit.plan`).
 
+8. **Check for extension hooks**: After reporting completion, check if `.specify/extensions.yml` exists in the project root.
+   - If it exists, read it and look for entries under the `hooks.after_specify` key
+   - If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+   - Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+   - For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+     - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+     - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+   - For each executable hook, output the following based on its `optional` flag:
+     - **Optional hook** (`optional: true`):
+       ```
+       ## Extension Hooks
+
+       **Optional Hook**: {extension}
+       Command: `/{command}`
+       Description: {description}
+
+       Prompt: {prompt}
+       To execute: `/{command}`
+       ```
+     - **Mandatory hook** (`optional: false`):
+       ```
+       ## Extension Hooks
+
+       **Automatic Hook**: {extension}
+       Executing: `/{command}`
+       EXECUTE_COMMAND: {command}
+       ```
+   - If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+
 **NOTE:** The script creates and checks out the new branch and initializes the spec file before writing.
 
 ## Quick Guidelines

templates/commands/tasks.md

@@ -28,7 +28,7 @@ You **MUST** consider the user input before proceeding (if not empty).
 - Check if `.specify/extensions.yml` exists in the project root.
 - If it exists, read it and look for entries under the `hooks.before_tasks` key
 - If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
-- Filter to only hooks where `enabled: true`
+- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
 - For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
   - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
   - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
@@ -100,7 +100,7 @@ You **MUST** consider the user input before proceeding (if not empty).
 6. **Check for extension hooks**: After tasks.md is generated, check if `.specify/extensions.yml` exists in the project root.
    - If it exists, read it and look for entries under the `hooks.after_tasks` key
    - If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
-   - Filter to only hooks where `enabled: true`
+   - Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
    - For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
      - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
      - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation

templates/spec-template.md

@@ -113,3 +113,16 @@
 - **SC-002**: [Measurable metric, e.g., "System handles 1000 concurrent users without degradation"]
 - **SC-003**: [User satisfaction metric, e.g., "90% of users successfully complete primary task on first attempt"]
 - **SC-004**: [Business metric, e.g., "Reduce support tickets related to [X] by 50%"]
+
+## Assumptions
+
+<!--
+  ACTION REQUIRED: The content in this section represents placeholders.
+  Fill them out with the right assumptions based on reasonable defaults
+  chosen when the feature description did not specify certain details.
+-->
+
+- [Assumption about target users, e.g., "Users have stable internet connectivity"]
+- [Assumption about scope boundaries, e.g., "Mobile support is out of scope for v1"]
+- [Assumption about data/environment, e.g., "Existing authentication system will be reused"]
+- [Dependency on existing system/service, e.g., "Requires access to the existing user profile API"]

tests/integrations/conftest.py

@@ -0,0 +1,23 @@
+"""Shared test helpers for integration tests."""
+
+from specify_cli.integrations.base import MarkdownIntegration
+
+
+class StubIntegration(MarkdownIntegration):
+    """Minimal concrete integration for testing."""
+
+    key = "stub"
+    config = {
+        "name": "Stub Agent",
+        "folder": ".stub/",
+        "commands_subdir": "commands",
+        "install_url": None,
+        "requires_cli": False,
+    }
+    registrar_config = {
+        "dir": ".stub/commands",
+        "format": "markdown",
+        "args": "$ARGUMENTS",
+        "extension": ".md",
+    }
+    context_file = "STUB.md"

tests/integrations/test_base.py

@@ -0,0 +1,169 @@
+"""Tests for IntegrationOption, IntegrationBase, MarkdownIntegration, and primitives."""
+
+import pytest
+
+from specify_cli.integrations.base import (
+    IntegrationBase,
+    IntegrationOption,
+    MarkdownIntegration,
+)
+from specify_cli.integrations.manifest import IntegrationManifest
+from .conftest import StubIntegration
+
+
+class TestIntegrationOption:
+    def test_defaults(self):
+        opt = IntegrationOption(name="--flag")
+        assert opt.name == "--flag"
+        assert opt.is_flag is False
+        assert opt.required is False
+        assert opt.default is None
+        assert opt.help == ""
+
+    def test_flag_option(self):
+        opt = IntegrationOption(name="--skills", is_flag=True, default=True, help="Enable skills")
+        assert opt.is_flag is True
+        assert opt.default is True
+        assert opt.help == "Enable skills"
+
+    def test_required_option(self):
+        opt = IntegrationOption(name="--commands-dir", required=True, help="Dir path")
+        assert opt.required is True
+
+    def test_frozen(self):
+        opt = IntegrationOption(name="--x")
+        with pytest.raises(AttributeError):
+            opt.name = "--y"  # type: ignore[misc]
+
+
+class TestIntegrationBase:
+    def test_key_and_config(self):
+        i = StubIntegration()
+        assert i.key == "stub"
+        assert i.config["name"] == "Stub Agent"
+        assert i.registrar_config["format"] == "markdown"
+        assert i.context_file == "STUB.md"
+
+    def test_options_default_empty(self):
+        assert StubIntegration.options() == []
+
+    def test_shared_commands_dir(self):
+        i = StubIntegration()
+        cmd_dir = i.shared_commands_dir()
+        assert cmd_dir is not None
+        assert cmd_dir.is_dir()
+
+    def test_setup_uses_shared_templates(self, tmp_path):
+        i = StubIntegration()
+        manifest = IntegrationManifest("stub", tmp_path)
+        created = i.setup(tmp_path, manifest)
+        assert len(created) > 0
+        for f in created:
+            assert f.parent == tmp_path / ".stub" / "commands"
+            assert f.name.startswith("speckit.")
+            assert f.name.endswith(".md")
+
+    def test_setup_copies_templates(self, tmp_path, monkeypatch):
+        tpl = tmp_path / "_templates"
+        tpl.mkdir()
+        (tpl / "plan.md").write_text("plan content", encoding="utf-8")
+        (tpl / "specify.md").write_text("spec content", encoding="utf-8")
+
+        i = StubIntegration()
+        monkeypatch.setattr(type(i), "list_command_templates", lambda self: sorted(tpl.glob("*.md")))
+
+        project = tmp_path / "project"
+        project.mkdir()
+        created = i.setup(project, IntegrationManifest("stub", project))
+        assert len(created) == 2
+        assert (project / ".stub" / "commands" / "speckit.plan.md").exists()
+        assert (project / ".stub" / "commands" / "speckit.specify.md").exists()
+
+    def test_install_delegates_to_setup(self, tmp_path):
+        i = StubIntegration()
+        manifest = IntegrationManifest("stub", tmp_path)
+        result = i.install(tmp_path, manifest)
+        assert len(result) > 0
+
+    def test_uninstall_delegates_to_teardown(self, tmp_path):
+        i = StubIntegration()
+        manifest = IntegrationManifest("stub", tmp_path)
+        removed, skipped = i.uninstall(tmp_path, manifest)
+        assert removed == []
+        assert skipped == []
+
+
+class TestMarkdownIntegration:
+    def test_is_subclass_of_base(self):
+        assert issubclass(MarkdownIntegration, IntegrationBase)
+
+    def test_stub_is_markdown(self):
+        assert isinstance(StubIntegration(), MarkdownIntegration)
+
+
+class TestBasePrimitives:
+    def test_shared_commands_dir_returns_path(self):
+        i = StubIntegration()
+        cmd_dir = i.shared_commands_dir()
+        assert cmd_dir is not None
+        assert cmd_dir.is_dir()
+
+    def test_shared_templates_dir_returns_path(self):
+        i = StubIntegration()
+        tpl_dir = i.shared_templates_dir()
+        assert tpl_dir is not None
+        assert tpl_dir.is_dir()
+
+    def test_list_command_templates_returns_md_files(self):
+        i = StubIntegration()
+        templates = i.list_command_templates()
+        assert len(templates) > 0
+        assert all(t.suffix == ".md" for t in templates)
+
+    def test_command_filename_default(self):
+        i = StubIntegration()
+        assert i.command_filename("plan") == "speckit.plan.md"
+
+    def test_commands_dest(self, tmp_path):
+        i = StubIntegration()
+        dest = i.commands_dest(tmp_path)
+        assert dest == tmp_path / ".stub" / "commands"
+
+    def test_commands_dest_no_config_raises(self, tmp_path):
+        class NoConfig(MarkdownIntegration):
+            key = "noconfig"
+        with pytest.raises(ValueError, match="config is not set"):
+            NoConfig().commands_dest(tmp_path)
+
+    def test_copy_command_to_directory(self, tmp_path):
+        src = tmp_path / "source.md"
+        src.write_text("content", encoding="utf-8")
+        dest_dir = tmp_path / "output"
+        result = IntegrationBase.copy_command_to_directory(src, dest_dir, "speckit.plan.md")
+        assert result == dest_dir / "speckit.plan.md"
+        assert result.read_text(encoding="utf-8") == "content"
+
+    def test_record_file_in_manifest(self, tmp_path):
+        f = tmp_path / "f.txt"
+        f.write_text("hello", encoding="utf-8")
+        m = IntegrationManifest("test", tmp_path)
+        IntegrationBase.record_file_in_manifest(f, tmp_path, m)
+        assert "f.txt" in m.files
+
+    def test_write_file_and_record(self, tmp_path):
+        m = IntegrationManifest("test", tmp_path)
+        dest = tmp_path / "sub" / "f.txt"
+        result = IntegrationBase.write_file_and_record("content", dest, tmp_path, m)
+        assert result == dest
+        assert dest.read_text(encoding="utf-8") == "content"
+        assert "sub/f.txt" in m.files
+
+    def test_setup_copies_shared_templates(self, tmp_path):
+        i = StubIntegration()
+        m = IntegrationManifest("stub", tmp_path)
+        created = i.setup(tmp_path, m)
+        assert len(created) > 0
+        for f in created:
+            assert f.parent.name == "commands"
+            assert f.name.startswith("speckit.")
+            assert f.name.endswith(".md")

tests/integrations/test_cli.py

@@ -0,0 +1,122 @@
+"""Tests for --integration flag on specify init (CLI-level)."""
+
+import json
+import os
+
+import pytest
+
+
+class TestInitIntegrationFlag:
+    def test_integration_and_ai_mutually_exclusive(self):
+        from typer.testing import CliRunner
+        from specify_cli import app
+        runner = CliRunner()
+        result = runner.invoke(app, [
+            "init", "test-project", "--ai", "claude", "--integration", "copilot",
+        ])
+        assert result.exit_code != 0
+        assert "mutually exclusive" in result.output
+
+    def test_unknown_integration_rejected(self):
+        from typer.testing import CliRunner
+        from specify_cli import app
+        runner = CliRunner()
+        result = runner.invoke(app, [
+            "init", "test-project", "--integration", "nonexistent",
+        ])
+        assert result.exit_code != 0
+        assert "Unknown integration" in result.output
+
+    def test_integration_copilot_creates_files(self, tmp_path):
+        from typer.testing import CliRunner
+        from specify_cli import app
+        runner = CliRunner()
+        project = tmp_path / "int-test"
+        project.mkdir()
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(project)
+            result = runner.invoke(app, [
+                "init", "--here", "--integration", "copilot", "--script", "sh", "--no-git",
+            ], catch_exceptions=False)
+        finally:
+            os.chdir(old_cwd)
+        assert result.exit_code == 0, f"init failed: {result.output}"
+        assert (project / ".github" / "agents" / "speckit.plan.agent.md").exists()
+        assert (project / ".github" / "prompts" / "speckit.plan.prompt.md").exists()
+        assert (project / ".specify" / "scripts" / "bash" / "common.sh").exists()
+
+        data = json.loads((project / ".specify" / "integration.json").read_text(encoding="utf-8"))
+        assert data["integration"] == "copilot"
+        assert "scripts" in data
+        assert "update-context" in data["scripts"]
+
+        opts = json.loads((project / ".specify" / "init-options.json").read_text(encoding="utf-8"))
+        assert opts["integration"] == "copilot"
+
+        assert (project / ".specify" / "integrations" / "copilot.manifest.json").exists()
+        assert (project / ".specify" / "integrations" / "copilot" / "scripts" / "update-context.sh").exists()
+
+        shared_manifest = project / ".specify" / "integrations" / "speckit.manifest.json"
+        assert shared_manifest.exists()
+
+    def test_ai_copilot_auto_promotes(self, tmp_path):
+        from typer.testing import CliRunner
+        from specify_cli import app
+        project = tmp_path / "promote-test"
+        project.mkdir()
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(project)
+            runner = CliRunner()
+            result = runner.invoke(app, [
+                "init", "--here", "--ai", "copilot", "--script", "sh", "--no-git",
+            ], catch_exceptions=False)
+        finally:
+            os.chdir(old_cwd)
+        assert result.exit_code == 0
+        assert "--integration copilot" in result.output
+        assert (project / ".github" / "agents" / "speckit.plan.agent.md").exists()
+
+    def test_shared_infra_skips_existing_files(self, tmp_path):
+        """Pre-existing shared files are not overwritten by _install_shared_infra."""
+        from typer.testing import CliRunner
+        from specify_cli import app
+
+        project = tmp_path / "skip-test"
+        project.mkdir()
+
+        # Pre-create a shared script with custom content
+        scripts_dir = project / ".specify" / "scripts" / "bash"
+        scripts_dir.mkdir(parents=True)
+        custom_content = "# user-modified common.sh\n"
+        (scripts_dir / "common.sh").write_text(custom_content, encoding="utf-8")
+
+        # Pre-create a shared template with custom content
+        templates_dir = project / ".specify" / "templates"
+        templates_dir.mkdir(parents=True)
+        custom_template = "# user-modified spec-template\n"
+        (templates_dir / "spec-template.md").write_text(custom_template, encoding="utf-8")
+
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(project)
+            runner = CliRunner()
+            result = runner.invoke(app, [
+                "init", "--here", "--force",
+                "--integration", "copilot",
+                "--script", "sh",
+                "--no-git",
+            ], catch_exceptions=False)
+        finally:
+            os.chdir(old_cwd)
+
+        assert result.exit_code == 0
+
+        # User's files should be preserved
+        assert (scripts_dir / "common.sh").read_text(encoding="utf-8") == custom_content
+        assert (templates_dir / "spec-template.md").read_text(encoding="utf-8") == custom_template
+
+        # Other shared files should still be installed
+        assert (scripts_dir / "setup-plan.sh").exists()
+        assert (templates_dir / "plan-template.md").exists()

tests/integrations/test_copilot.py

@@ -0,0 +1,266 @@
+"""Tests for CopilotIntegration."""
+
+import json
+import os
+
+from specify_cli.integrations import get_integration
+from specify_cli.integrations.manifest import IntegrationManifest
+
+
+class TestCopilotIntegration:
+    def test_copilot_key_and_config(self):
+        copilot = get_integration("copilot")
+        assert copilot is not None
+        assert copilot.key == "copilot"
+        assert copilot.config["folder"] == ".github/"
+        assert copilot.config["commands_subdir"] == "agents"
+        assert copilot.registrar_config["extension"] == ".agent.md"
+        assert copilot.context_file == ".github/copilot-instructions.md"
+
+    def test_command_filename_agent_md(self):
+        copilot = get_integration("copilot")
+        assert copilot.command_filename("plan") == "speckit.plan.agent.md"
+
+    def test_setup_creates_agent_md_files(self, tmp_path):
+        from specify_cli.integrations.copilot import CopilotIntegration
+        copilot = CopilotIntegration()
+        m = IntegrationManifest("copilot", tmp_path)
+        created = copilot.setup(tmp_path, m)
+        assert len(created) > 0
+        agent_files = [f for f in created if ".agent." in f.name]
+        assert len(agent_files) > 0
+        for f in agent_files:
+            assert f.parent == tmp_path / ".github" / "agents"
+            assert f.name.endswith(".agent.md")
+
+    def test_setup_creates_companion_prompts(self, tmp_path):
+        from specify_cli.integrations.copilot import CopilotIntegration
+        copilot = CopilotIntegration()
+        m = IntegrationManifest("copilot", tmp_path)
+        created = copilot.setup(tmp_path, m)
+        prompt_files = [f for f in created if f.parent.name == "prompts"]
+        assert len(prompt_files) > 0
+        for f in prompt_files:
+            assert f.name.endswith(".prompt.md")
+            content = f.read_text(encoding="utf-8")
+            assert content.startswith("---\nagent: speckit.")
+
+    def test_agent_and_prompt_counts_match(self, tmp_path):
+        from specify_cli.integrations.copilot import CopilotIntegration
+        copilot = CopilotIntegration()
+        m = IntegrationManifest("copilot", tmp_path)
+        created = copilot.setup(tmp_path, m)
+        agents = [f for f in created if ".agent.md" in f.name]
+        prompts = [f for f in created if ".prompt.md" in f.name]
+        assert len(agents) == len(prompts)
+
+    def test_setup_creates_vscode_settings_new(self, tmp_path):
+        from specify_cli.integrations.copilot import CopilotIntegration
+        copilot = CopilotIntegration()
+        assert copilot._vscode_settings_path() is not None
+        m = IntegrationManifest("copilot", tmp_path)
+        created = copilot.setup(tmp_path, m)
+        settings = tmp_path / ".vscode" / "settings.json"
+        assert settings.exists()
+        assert settings in created
+        assert any("settings.json" in k for k in m.files)
+
+    def test_setup_merges_existing_vscode_settings(self, tmp_path):
+        from specify_cli.integrations.copilot import CopilotIntegration
+        copilot = CopilotIntegration()
+        vscode_dir = tmp_path / ".vscode"
+        vscode_dir.mkdir(parents=True)
+        existing = {"editor.fontSize": 14, "custom.setting": True}
+        (vscode_dir / "settings.json").write_text(json.dumps(existing, indent=4), encoding="utf-8")
+        m = IntegrationManifest("copilot", tmp_path)
+        created = copilot.setup(tmp_path, m)
+        settings = tmp_path / ".vscode" / "settings.json"
+        data = json.loads(settings.read_text(encoding="utf-8"))
+        assert data["editor.fontSize"] == 14
+        assert data["custom.setting"] is True
+        assert settings not in created
+        assert not any("settings.json" in k for k in m.files)
+
+    def test_all_created_files_tracked_in_manifest(self, tmp_path):
+        from specify_cli.integrations.copilot import CopilotIntegration
+        copilot = CopilotIntegration()
+        m = IntegrationManifest("copilot", tmp_path)
+        created = copilot.setup(tmp_path, m)
+        for f in created:
+            rel = f.resolve().relative_to(tmp_path.resolve()).as_posix()
+            assert rel in m.files, f"Created file {rel} not tracked in manifest"
+
+    def test_install_uninstall_roundtrip(self, tmp_path):
+        from specify_cli.integrations.copilot import CopilotIntegration
+        copilot = CopilotIntegration()
+        m = IntegrationManifest("copilot", tmp_path)
+        created = copilot.install(tmp_path, m)
+        assert len(created) > 0
+        m.save()
+        for f in created:
+            assert f.exists()
+        removed, skipped = copilot.uninstall(tmp_path, m)
+        assert len(removed) == len(created)
+        assert skipped == []
+
+    def test_modified_file_survives_uninstall(self, tmp_path):
+        from specify_cli.integrations.copilot import CopilotIntegration
+        copilot = CopilotIntegration()
+        m = IntegrationManifest("copilot", tmp_path)
+        created = copilot.install(tmp_path, m)
+        m.save()
+        modified_file = created[0]
+        modified_file.write_text("user modified this", encoding="utf-8")
+        removed, skipped = copilot.uninstall(tmp_path, m)
+        assert modified_file.exists()
+        assert modified_file in skipped
+
+    def test_directory_structure(self, tmp_path):
+        from specify_cli.integrations.copilot import CopilotIntegration
+        copilot = CopilotIntegration()
+        m = IntegrationManifest("copilot", tmp_path)
+        copilot.setup(tmp_path, m)
+        agents_dir = tmp_path / ".github" / "agents"
+        assert agents_dir.is_dir()
+        agent_files = sorted(agents_dir.glob("speckit.*.agent.md"))
+        assert len(agent_files) == 9
+        expected_commands = {
+            "analyze", "checklist", "clarify", "constitution",
+            "implement", "plan", "specify", "tasks", "taskstoissues",
+        }
+        actual_commands = {f.name.removeprefix("speckit.").removesuffix(".agent.md") for f in agent_files}
+        assert actual_commands == expected_commands
+
+    def test_templates_are_processed(self, tmp_path):
+        from specify_cli.integrations.copilot import CopilotIntegration
+        copilot = CopilotIntegration()
+        m = IntegrationManifest("copilot", tmp_path)
+        copilot.setup(tmp_path, m)
+        agents_dir = tmp_path / ".github" / "agents"
+        for agent_file in agents_dir.glob("speckit.*.agent.md"):
+            content = agent_file.read_text(encoding="utf-8")
+            assert "{SCRIPT}" not in content, f"{agent_file.name} has unprocessed {{SCRIPT}}"
+            assert "__AGENT__" not in content, f"{agent_file.name} has unprocessed __AGENT__"
+            assert "{ARGS}" not in content, f"{agent_file.name} has unprocessed {{ARGS}}"
+            assert "\nscripts:\n" not in content
+            assert "\nagent_scripts:\n" not in content
+
+    def test_complete_file_inventory_sh(self, tmp_path):
+        """Every file produced by specify init --integration copilot --script sh."""
+        from typer.testing import CliRunner
+        from specify_cli import app
+        project = tmp_path / "inventory-sh"
+        project.mkdir()
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(project)
+            result = CliRunner().invoke(app, [
+                "init", "--here", "--integration", "copilot", "--script", "sh", "--no-git",
+            ], catch_exceptions=False)
+        finally:
+            os.chdir(old_cwd)
+        assert result.exit_code == 0
+        actual = sorted(p.relative_to(project).as_posix() for p in project.rglob("*") if p.is_file())
+        expected = sorted([
+            ".github/agents/speckit.analyze.agent.md",
+            ".github/agents/speckit.checklist.agent.md",
+            ".github/agents/speckit.clarify.agent.md",
+            ".github/agents/speckit.constitution.agent.md",
+            ".github/agents/speckit.implement.agent.md",
+            ".github/agents/speckit.plan.agent.md",
+            ".github/agents/speckit.specify.agent.md",
+            ".github/agents/speckit.tasks.agent.md",
+            ".github/agents/speckit.taskstoissues.agent.md",
+            ".github/prompts/speckit.analyze.prompt.md",
+            ".github/prompts/speckit.checklist.prompt.md",
+            ".github/prompts/speckit.clarify.prompt.md",
+            ".github/prompts/speckit.constitution.prompt.md",
+            ".github/prompts/speckit.implement.prompt.md",
+            ".github/prompts/speckit.plan.prompt.md",
+            ".github/prompts/speckit.specify.prompt.md",
+            ".github/prompts/speckit.tasks.prompt.md",
+            ".github/prompts/speckit.taskstoissues.prompt.md",
+            ".vscode/settings.json",
+            ".specify/integration.json",
+            ".specify/init-options.json",
+            ".specify/integrations/copilot.manifest.json",
+            ".specify/integrations/speckit.manifest.json",
+            ".specify/integrations/copilot/scripts/update-context.ps1",
+            ".specify/integrations/copilot/scripts/update-context.sh",
+            ".specify/scripts/bash/check-prerequisites.sh",
+            ".specify/scripts/bash/common.sh",
+            ".specify/scripts/bash/create-new-feature.sh",
+            ".specify/scripts/bash/setup-plan.sh",
+            ".specify/scripts/bash/update-agent-context.sh",
+            ".specify/templates/agent-file-template.md",
+            ".specify/templates/checklist-template.md",
+            ".specify/templates/constitution-template.md",
+            ".specify/templates/plan-template.md",
+            ".specify/templates/spec-template.md",
+            ".specify/templates/tasks-template.md",
+            ".specify/memory/constitution.md",
+        ])
+        assert actual == expected, (
+            f"Missing: {sorted(set(expected) - set(actual))}\n"
+            f"Extra: {sorted(set(actual) - set(expected))}"
+        )
+
+    def test_complete_file_inventory_ps(self, tmp_path):
+        """Every file produced by specify init --integration copilot --script ps."""
+        from typer.testing import CliRunner
+        from specify_cli import app
+        project = tmp_path / "inventory-ps"
+        project.mkdir()
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(project)
+            result = CliRunner().invoke(app, [
+                "init", "--here", "--integration", "copilot", "--script", "ps", "--no-git",
+            ], catch_exceptions=False)
+        finally:
+            os.chdir(old_cwd)
+        assert result.exit_code == 0
+        actual = sorted(p.relative_to(project).as_posix() for p in project.rglob("*") if p.is_file())
+        expected = sorted([
+            ".github/agents/speckit.analyze.agent.md",
+            ".github/agents/speckit.checklist.agent.md",
+            ".github/agents/speckit.clarify.agent.md",
+            ".github/agents/speckit.constitution.agent.md",
+            ".github/agents/speckit.implement.agent.md",
+            ".github/agents/speckit.plan.agent.md",
+            ".github/agents/speckit.specify.agent.md",
+            ".github/agents/speckit.tasks.agent.md",
+            ".github/agents/speckit.taskstoissues.agent.md",
+            ".github/prompts/speckit.analyze.prompt.md",
+            ".github/prompts/speckit.checklist.prompt.md",
+            ".github/prompts/speckit.clarify.prompt.md",
+            ".github/prompts/speckit.constitution.prompt.md",
+            ".github/prompts/speckit.implement.prompt.md",
+            ".github/prompts/speckit.plan.prompt.md",
+            ".github/prompts/speckit.specify.prompt.md",
+            ".github/prompts/speckit.tasks.prompt.md",
+            ".github/prompts/speckit.taskstoissues.prompt.md",
+            ".vscode/settings.json",
+            ".specify/integration.json",
+            ".specify/init-options.json",
+            ".specify/integrations/copilot.manifest.json",
+            ".specify/integrations/speckit.manifest.json",
+            ".specify/integrations/copilot/scripts/update-context.ps1",
+            ".specify/integrations/copilot/scripts/update-context.sh",
+            ".specify/scripts/powershell/check-prerequisites.ps1",
+            ".specify/scripts/powershell/common.ps1",
+            ".specify/scripts/powershell/create-new-feature.ps1",
+            ".specify/scripts/powershell/setup-plan.ps1",
+            ".specify/scripts/powershell/update-agent-context.ps1",
+            ".specify/templates/agent-file-template.md",
+            ".specify/templates/checklist-template.md",
+            ".specify/templates/constitution-template.md",
+            ".specify/templates/plan-template.md",
+            ".specify/templates/spec-template.md",
+            ".specify/templates/tasks-template.md",
+            ".specify/memory/constitution.md",
+        ])
+        assert actual == expected, (
+            f"Missing: {sorted(set(expected) - set(actual))}\n"
+            f"Extra: {sorted(set(actual) - set(expected))}"
+        )

tests/integrations/test_manifest.py

@@ -0,0 +1,245 @@
+"""Tests for IntegrationManifest — record, hash, save, load, uninstall, modified detection."""
+
+import hashlib
+import json
+
+import pytest
+
+from specify_cli.integrations.manifest import IntegrationManifest, _sha256
+
+
+class TestManifestRecordFile:
+    def test_record_file_writes_and_hashes(self, tmp_path):
+        m = IntegrationManifest("test", tmp_path)
+        content = "hello world"
+        abs_path = m.record_file("a/b.txt", content)
+        assert abs_path == tmp_path / "a" / "b.txt"
+        assert abs_path.read_text(encoding="utf-8") == content
+        expected_hash = hashlib.sha256(content.encode()).hexdigest()
+        assert m.files["a/b.txt"] == expected_hash
+
+    def test_record_file_bytes(self, tmp_path):
+        m = IntegrationManifest("test", tmp_path)
+        data = b"\x00\x01\x02"
+        abs_path = m.record_file("bin.dat", data)
+        assert abs_path.read_bytes() == data
+        assert m.files["bin.dat"] == hashlib.sha256(data).hexdigest()
+
+    def test_record_existing(self, tmp_path):
+        f = tmp_path / "existing.txt"
+        f.write_text("content", encoding="utf-8")
+        m = IntegrationManifest("test", tmp_path)
+        m.record_existing("existing.txt")
+        assert m.files["existing.txt"] == _sha256(f)
+
+
+class TestManifestPathTraversal:
+    def test_record_file_rejects_parent_traversal(self, tmp_path):
+        m = IntegrationManifest("test", tmp_path)
+        with pytest.raises(ValueError, match="outside"):
+            m.record_file("../escape.txt", "bad")
+
+    def test_record_file_rejects_absolute_path(self, tmp_path):
+        m = IntegrationManifest("test", tmp_path)
+        with pytest.raises(ValueError, match="Absolute paths"):
+            m.record_file("/tmp/escape.txt", "bad")
+
+    def test_record_existing_rejects_parent_traversal(self, tmp_path):
+        escape = tmp_path.parent / "escape.txt"
+        escape.write_text("evil", encoding="utf-8")
+        try:
+            m = IntegrationManifest("test", tmp_path)
+            with pytest.raises(ValueError, match="outside"):
+                m.record_existing("../escape.txt")
+        finally:
+            escape.unlink(missing_ok=True)
+
+    def test_uninstall_skips_traversal_paths(self, tmp_path):
+        m = IntegrationManifest("test", tmp_path)
+        m.record_file("safe.txt", "good")
+        m._files["../outside.txt"] = "fakehash"
+        m.save()
+        removed, skipped = m.uninstall()
+        assert len(removed) == 1
+        assert removed[0].name == "safe.txt"
+
+
+class TestManifestCheckModified:
+    def test_unmodified_file(self, tmp_path):
+        m = IntegrationManifest("test", tmp_path)
+        m.record_file("f.txt", "original")
+        assert m.check_modified() == []
+
+    def test_modified_file(self, tmp_path):
+        m = IntegrationManifest("test", tmp_path)
+        m.record_file("f.txt", "original")
+        (tmp_path / "f.txt").write_text("changed", encoding="utf-8")
+        assert m.check_modified() == ["f.txt"]
+
+    def test_deleted_file_not_reported(self, tmp_path):
+        m = IntegrationManifest("test", tmp_path)
+        m.record_file("f.txt", "original")
+        (tmp_path / "f.txt").unlink()
+        assert m.check_modified() == []
+
+    def test_symlink_treated_as_modified(self, tmp_path):
+        m = IntegrationManifest("test", tmp_path)
+        m.record_file("f.txt", "original")
+        target = tmp_path / "target.txt"
+        target.write_text("target", encoding="utf-8")
+        (tmp_path / "f.txt").unlink()
+        (tmp_path / "f.txt").symlink_to(target)
+        assert m.check_modified() == ["f.txt"]
+
+
+class TestManifestUninstall:
+    def test_removes_unmodified(self, tmp_path):
+        m = IntegrationManifest("test", tmp_path)
+        m.record_file("d/f.txt", "content")
+        m.save()
+        removed, skipped = m.uninstall()
+        assert len(removed) == 1
+        assert not (tmp_path / "d" / "f.txt").exists()
+        assert not (tmp_path / "d").exists()
+        assert skipped == []
+
+    def test_skips_modified(self, tmp_path):
+        m = IntegrationManifest("test", tmp_path)
+        m.record_file("f.txt", "original")
+        m.save()
+        (tmp_path / "f.txt").write_text("modified", encoding="utf-8")
+        removed, skipped = m.uninstall()
+        assert removed == []
+        assert len(skipped) == 1
+        assert (tmp_path / "f.txt").exists()
+
+    def test_force_removes_modified(self, tmp_path):
+        m = IntegrationManifest("test", tmp_path)
+        m.record_file("f.txt", "original")
+        m.save()
+        (tmp_path / "f.txt").write_text("modified", encoding="utf-8")
+        removed, skipped = m.uninstall(force=True)
+        assert len(removed) == 1
+        assert skipped == []
+
+    def test_already_deleted_file(self, tmp_path):
+        m = IntegrationManifest("test", tmp_path)
+        m.record_file("f.txt", "content")
+        m.save()
+        (tmp_path / "f.txt").unlink()
+        removed, skipped = m.uninstall()
+        assert removed == []
+        assert skipped == []
+
+    def test_removes_manifest_file(self, tmp_path):
+        m = IntegrationManifest("test", tmp_path, version="1.0")
+        m.record_file("f.txt", "content")
+        m.save()
+        assert m.manifest_path.exists()
+        m.uninstall()
+        assert not m.manifest_path.exists()
+
+    def test_cleans_empty_parent_dirs(self, tmp_path):
+        m = IntegrationManifest("test", tmp_path)
+        m.record_file("a/b/c/f.txt", "content")
+        m.save()
+        m.uninstall()
+        assert not (tmp_path / "a").exists()
+
+    def test_preserves_nonempty_parent_dirs(self, tmp_path):
+        m = IntegrationManifest("test", tmp_path)
+        m.record_file("a/b/tracked.txt", "content")
+        (tmp_path / "a" / "b" / "other.txt").write_text("keep", encoding="utf-8")
+        m.save()
+        m.uninstall()
+        assert not (tmp_path / "a" / "b" / "tracked.txt").exists()
+        assert (tmp_path / "a" / "b" / "other.txt").exists()
+
+    def test_symlink_skipped_without_force(self, tmp_path):
+        m = IntegrationManifest("test", tmp_path)
+        m.record_file("f.txt", "original")
+        m.save()
+        target = tmp_path / "target.txt"
+        target.write_text("target", encoding="utf-8")
+        (tmp_path / "f.txt").unlink()
+        (tmp_path / "f.txt").symlink_to(target)
+        removed, skipped = m.uninstall()
+        assert removed == []
+        assert len(skipped) == 1
+
+    def test_symlink_removed_with_force(self, tmp_path):
+        m = IntegrationManifest("test", tmp_path)
+        m.record_file("f.txt", "original")
+        m.save()
+        target = tmp_path / "target.txt"
+        target.write_text("target", encoding="utf-8")
+        (tmp_path / "f.txt").unlink()
+        (tmp_path / "f.txt").symlink_to(target)
+        removed, skipped = m.uninstall(force=True)
+        assert len(removed) == 1
+        assert target.exists()
+
+
+class TestManifestPersistence:
+    def test_save_and_load_roundtrip(self, tmp_path):
+        m = IntegrationManifest("myagent", tmp_path, version="2.0.1")
+        m.record_file("dir/file.md", "# Hello")
+        m.save()
+        loaded = IntegrationManifest.load("myagent", tmp_path)
+        assert loaded.key == "myagent"
+        assert loaded.version == "2.0.1"
+        assert loaded.files == m.files
+
+    def test_manifest_path(self, tmp_path):
+        m = IntegrationManifest("copilot", tmp_path)
+        assert m.manifest_path == tmp_path / ".specify" / "integrations" / "copilot.manifest.json"
+
+    def test_load_missing_raises(self, tmp_path):
+        with pytest.raises(FileNotFoundError):
+            IntegrationManifest.load("nonexistent", tmp_path)
+
+    def test_save_creates_directories(self, tmp_path):
+        m = IntegrationManifest("test", tmp_path)
+        m.record_file("f.txt", "content")
+        path = m.save()
+        assert path.exists()
+        data = json.loads(path.read_text(encoding="utf-8"))
+        assert data["integration"] == "test"
+
+    def test_save_preserves_installed_at(self, tmp_path):
+        m = IntegrationManifest("test", tmp_path)
+        m.record_file("f.txt", "content")
+        m.save()
+        first_ts = m._installed_at
+        m.save()
+        assert m._installed_at == first_ts
+
+
+class TestManifestLoadValidation:
+    def test_load_non_dict_raises(self, tmp_path):
+        path = tmp_path / ".specify" / "integrations" / "bad.manifest.json"
+        path.parent.mkdir(parents=True)
+        path.write_text('"just a string"', encoding="utf-8")
+        with pytest.raises(ValueError, match="JSON object"):
+            IntegrationManifest.load("bad", tmp_path)
+
+    def test_load_bad_files_type_raises(self, tmp_path):
+        path = tmp_path / ".specify" / "integrations" / "bad.manifest.json"
+        path.parent.mkdir(parents=True)
+        path.write_text(json.dumps({"files": ["not", "a", "dict"]}), encoding="utf-8")
+        with pytest.raises(ValueError, match="mapping"):
+            IntegrationManifest.load("bad", tmp_path)
+
+    def test_load_bad_files_values_raises(self, tmp_path):
+        path = tmp_path / ".specify" / "integrations" / "bad.manifest.json"
+        path.parent.mkdir(parents=True)
+        path.write_text(json.dumps({"files": {"a.txt": 123}}), encoding="utf-8")
+        with pytest.raises(ValueError, match="mapping"):
+            IntegrationManifest.load("bad", tmp_path)
+
+    def test_load_invalid_json_raises(self, tmp_path):
+        path = tmp_path / ".specify" / "integrations" / "bad.manifest.json"
+        path.parent.mkdir(parents=True)
+        path.write_text("{not valid json", encoding="utf-8")
+        with pytest.raises(ValueError, match="invalid JSON"):
+            IntegrationManifest.load("bad", tmp_path)

tests/integrations/test_registry.py

@@ -0,0 +1,45 @@
+"""Tests for INTEGRATION_REGISTRY."""
+
+import pytest
+
+from specify_cli.integrations import (
+    INTEGRATION_REGISTRY,
+    _register,
+    get_integration,
+)
+from specify_cli.integrations.base import MarkdownIntegration
+from .conftest import StubIntegration
+
+
+class TestRegistry:
+    def test_registry_is_dict(self):
+        assert isinstance(INTEGRATION_REGISTRY, dict)
+
+    def test_register_and_get(self):
+        stub = StubIntegration()
+        _register(stub)
+        try:
+            assert get_integration("stub") is stub
+        finally:
+            INTEGRATION_REGISTRY.pop("stub", None)
+
+    def test_get_missing_returns_none(self):
+        assert get_integration("nonexistent-xyz") is None
+
+    def test_register_empty_key_raises(self):
+        class EmptyKey(MarkdownIntegration):
+            key = ""
+        with pytest.raises(ValueError, match="empty key"):
+            _register(EmptyKey())
+
+    def test_register_duplicate_raises(self):
+        stub = StubIntegration()
+        _register(stub)
+        try:
+            with pytest.raises(KeyError, match="already registered"):
+                _register(StubIntegration())
+        finally:
+            INTEGRATION_REGISTRY.pop("stub", None)
+
+    def test_copilot_registered(self):
+        assert "copilot" in INTEGRATION_REGISTRY

tests/test_agent_config_consistency.py

@@ -29,11 +29,17 @@ class TestAgentConfigConsistency:
         assert "q" not in cfg
 
     def test_extension_registrar_includes_codex(self):
-        """Extension command registrar should include codex targeting .codex/prompts."""
+        """Extension command registrar should include codex targeting .agents/skills."""
         cfg = CommandRegistrar.AGENT_CONFIGS
 
         assert "codex" in cfg
-        assert cfg["codex"]["dir"] == ".codex/prompts"
+        assert cfg["codex"]["dir"] == ".agents/skills"
+        assert cfg["codex"]["extension"] == "/SKILL.md"
+
+    def test_runtime_codex_uses_native_skills(self):
+        """Codex runtime config should point at .agents/skills."""
+        assert AGENT_CONFIG["codex"]["folder"] == ".agents/"
+        assert AGENT_CONFIG["codex"]["commands_subdir"] == "skills"
 
     def test_release_agent_lists_include_kiro_cli_and_exclude_q(self):
         """Bash and PowerShell release scripts should agree on agent key set for Kiro."""
@@ -71,6 +77,16 @@ class TestAgentConfigConsistency:
         assert re.search(r"shai\)\s*\n.*?\.shai/commands", sh_text, re.S) is not None
         assert re.search(r"agy\)\s*\n.*?\.agent/commands", sh_text, re.S) is not None
 
+    def test_release_scripts_generate_codex_skills(self):
+        """Release scripts should generate Codex skills in .agents/skills."""
+        sh_text = (REPO_ROOT / ".github" / "workflows" / "scripts" / "create-release-packages.sh").read_text(encoding="utf-8")
+        ps_text = (REPO_ROOT / ".github" / "workflows" / "scripts" / "create-release-packages.ps1").read_text(encoding="utf-8")
+
+        assert ".agents/skills" in sh_text
+        assert ".agents/skills" in ps_text
+        assert re.search(r"codex\)\s*\n.*?create_skills.*?\.agents/skills.*?\"-\"", sh_text, re.S) is not None
+        assert re.search(r"'codex'\s*\{.*?\.agents/skills.*?New-Skills.*?-Separator '-'", ps_text, re.S) is not None
+
     def test_init_ai_help_includes_roo_and_kiro_alias(self):
         """CLI help text for --ai should stay in sync with agent config and alias guidance."""
         assert "roo" in AI_ASSISTANT_HELP
@@ -233,3 +249,221 @@ class TestAgentConfigConsistency:
     def test_ai_help_includes_kimi(self):
         """CLI help text for --ai should include kimi."""
         assert "kimi" in AI_ASSISTANT_HELP
+
+    # --- Trae IDE consistency checks ---
+
+    def test_trae_in_agent_config(self):
+        """AGENT_CONFIG should include trae with correct folder and commands_subdir."""
+        assert "trae" in AGENT_CONFIG
+        assert AGENT_CONFIG["trae"]["folder"] == ".trae/"
+        assert AGENT_CONFIG["trae"]["commands_subdir"] == "rules"
+        assert AGENT_CONFIG["trae"]["requires_cli"] is False
+        assert AGENT_CONFIG["trae"]["install_url"] is None
+
+    def test_trae_in_extension_registrar(self):
+        """Extension command registrar should include trae using .trae/rules and markdown, if present."""
+        cfg = CommandRegistrar.AGENT_CONFIGS
+
+        assert "trae" in cfg
+        trae_cfg = cfg["trae"]
+        assert trae_cfg["format"] == "markdown"
+        assert trae_cfg["args"] == "$ARGUMENTS"
+        assert trae_cfg["extension"] == ".md"
+
+    def test_trae_in_release_agent_lists(self):
+        """Bash and PowerShell release scripts should include trae in agent lists."""
+        sh_text = (REPO_ROOT / ".github" / "workflows" / "scripts" / "create-release-packages.sh").read_text(encoding="utf-8")
+        ps_text = (REPO_ROOT / ".github" / "workflows" / "scripts" / "create-release-packages.ps1").read_text(encoding="utf-8")
+
+        sh_match = re.search(r"ALL_AGENTS=\(([^)]*)\)", sh_text)
+        assert sh_match is not None
+        sh_agents = sh_match.group(1).split()
+
+        ps_match = re.search(r"\$AllAgents = @\(([^)]*)\)", ps_text)
+        assert ps_match is not None
+        ps_agents = re.findall(r"'([^']+)'", ps_match.group(1))
+
+        assert "trae" in sh_agents
+        assert "trae" in ps_agents
+
+    def test_trae_in_release_scripts_generate_commands(self):
+        """Release scripts should generate markdown commands for trae in .trae/rules."""
+        sh_text = (REPO_ROOT / ".github" / "workflows" / "scripts" / "create-release-packages.sh").read_text(encoding="utf-8")
+        ps_text = (REPO_ROOT / ".github" / "workflows" / "scripts" / "create-release-packages.ps1").read_text(encoding="utf-8")
+
+        assert ".trae/rules" in sh_text
+        assert ".trae/rules" in ps_text
+        assert re.search(r"'trae'\s*\{.*?\.trae/rules", ps_text, re.S) is not None
+
+    def test_trae_in_github_release_output(self):
+        """GitHub release script should include trae template packages."""
+        gh_release_text = (REPO_ROOT / ".github" / "workflows" / "scripts" / "create-github-release.sh").read_text(encoding="utf-8")
+
+        assert "spec-kit-template-trae-sh-" in gh_release_text
+        assert "spec-kit-template-trae-ps-" in gh_release_text
+
+    def test_trae_in_agent_context_scripts(self):
+        """Agent context scripts should support trae agent type."""
+        bash_text = (REPO_ROOT / "scripts" / "bash" / "update-agent-context.sh").read_text(encoding="utf-8")
+        pwsh_text = (REPO_ROOT / "scripts" / "powershell" / "update-agent-context.ps1").read_text(encoding="utf-8")
+
+        assert "trae" in bash_text
+        assert "TRAE_FILE" in bash_text
+        assert "trae" in pwsh_text
+        assert "TRAE_FILE" in pwsh_text
+
+    def test_trae_in_powershell_validate_set(self):
+        """PowerShell update-agent-context script should include 'trae' in ValidateSet."""
+        ps_text = (REPO_ROOT / "scripts" / "powershell" / "update-agent-context.ps1").read_text(encoding="utf-8")
+
+        validate_set_match = re.search(r"\[ValidateSet\(([^)]*)\)\]", ps_text)
+        assert validate_set_match is not None
+        validate_set_values = re.findall(r"'([^']+)'", validate_set_match.group(1))
+
+        assert "trae" in validate_set_values
+
+    def test_ai_help_includes_trae(self):
+        """CLI help text for --ai should include trae."""
+        assert "trae" in AI_ASSISTANT_HELP
+
+    # --- Pi Coding Agent consistency checks ---
+
+    def test_pi_in_agent_config(self):
+        """AGENT_CONFIG should include pi with correct folder and commands_subdir."""
+        assert "pi" in AGENT_CONFIG
+        assert AGENT_CONFIG["pi"]["folder"] == ".pi/"
+        assert AGENT_CONFIG["pi"]["commands_subdir"] == "prompts"
+        assert AGENT_CONFIG["pi"]["requires_cli"] is True
+        assert AGENT_CONFIG["pi"]["install_url"] is not None
+
+    def test_pi_in_extension_registrar(self):
+        """Extension command registrar should include pi using .pi/prompts."""
+        cfg = CommandRegistrar.AGENT_CONFIGS
+
+        assert "pi" in cfg
+        pi_cfg = cfg["pi"]
+        assert pi_cfg["dir"] == ".pi/prompts"
+        assert pi_cfg["format"] == "markdown"
+        assert pi_cfg["args"] == "$ARGUMENTS"
+        assert pi_cfg["extension"] == ".md"
+
+    def test_pi_in_release_agent_lists(self):
+        """Bash and PowerShell release scripts should include pi in agent lists."""
+        sh_text = (REPO_ROOT / ".github" / "workflows" / "scripts" / "create-release-packages.sh").read_text(encoding="utf-8")
+        ps_text = (REPO_ROOT / ".github" / "workflows" / "scripts" / "create-release-packages.ps1").read_text(encoding="utf-8")
+
+        sh_match = re.search(r"ALL_AGENTS=\(([^)]*)\)", sh_text)
+        assert sh_match is not None
+        sh_agents = sh_match.group(1).split()
+
+        ps_match = re.search(r"\$AllAgents = @\(([^)]*)\)", ps_text)
+        assert ps_match is not None
+        ps_agents = re.findall(r"'([^']+)'", ps_match.group(1))
+
+        assert "pi" in sh_agents
+        assert "pi" in ps_agents
+
+    def test_release_scripts_generate_pi_prompt_templates(self):
+        """Release scripts should generate Markdown prompt templates for pi in .pi/prompts."""
+        sh_text = (REPO_ROOT / ".github" / "workflows" / "scripts" / "create-release-packages.sh").read_text(encoding="utf-8")
+        ps_text = (REPO_ROOT / ".github" / "workflows" / "scripts" / "create-release-packages.ps1").read_text(encoding="utf-8")
+
+        assert ".pi/prompts" in sh_text
+        assert ".pi/prompts" in ps_text
+        assert re.search(r"pi\)\s*\n.*?\.pi/prompts", sh_text, re.S) is not None
+        assert re.search(r"'pi'\s*\{.*?\.pi/prompts", ps_text, re.S) is not None
+
+    def test_pi_in_powershell_validate_set(self):
+        """PowerShell update-agent-context script should include 'pi' in ValidateSet."""
+        ps_text = (REPO_ROOT / "scripts" / "powershell" / "update-agent-context.ps1").read_text(encoding="utf-8")
+
+        validate_set_match = re.search(r"\[ValidateSet\(([^)]*)\)\]", ps_text)
+        assert validate_set_match is not None
+        validate_set_values = re.findall(r"'([^']+)'", validate_set_match.group(1))
+
+        assert "pi" in validate_set_values
+
+    def test_pi_in_github_release_output(self):
+        """GitHub release script should include pi template packages."""
+        gh_release_text = (REPO_ROOT / ".github" / "workflows" / "scripts" / "create-github-release.sh").read_text(encoding="utf-8")
+
+        assert "spec-kit-template-pi-sh-" in gh_release_text
+        assert "spec-kit-template-pi-ps-" in gh_release_text
+
+    def test_agent_context_scripts_include_pi(self):
+        """Agent context scripts should support pi agent type."""
+        bash_text = (REPO_ROOT / "scripts" / "bash" / "update-agent-context.sh").read_text(encoding="utf-8")
+        pwsh_text = (REPO_ROOT / "scripts" / "powershell" / "update-agent-context.ps1").read_text(encoding="utf-8")
+
+        assert "pi" in bash_text
+        assert "Pi Coding Agent" in bash_text
+        assert "pi" in pwsh_text
+        assert "Pi Coding Agent" in pwsh_text
+
+    def test_ai_help_includes_pi(self):
+        """CLI help text for --ai should include pi."""
+        assert "pi" in AI_ASSISTANT_HELP
+
+    # --- iFlow CLI consistency checks ---
+
+    def test_iflow_in_agent_config(self):
+        """AGENT_CONFIG should include iflow with correct folder and commands_subdir."""
+        assert "iflow" in AGENT_CONFIG
+        assert AGENT_CONFIG["iflow"]["folder"] == ".iflow/"
+        assert AGENT_CONFIG["iflow"]["commands_subdir"] == "commands"
+        assert AGENT_CONFIG["iflow"]["requires_cli"] is True
+
+    def test_iflow_in_extension_registrar(self):
+        """Extension command registrar should include iflow targeting .iflow/commands."""
+        cfg = CommandRegistrar.AGENT_CONFIGS
+
+        assert "iflow" in cfg
+        assert cfg["iflow"]["dir"] == ".iflow/commands"
+        assert cfg["iflow"]["format"] == "markdown"
+        assert cfg["iflow"]["args"] == "$ARGUMENTS"
+
+    def test_iflow_in_release_agent_lists(self):
+        """Bash and PowerShell release scripts should include iflow in agent lists."""
+        sh_text = (REPO_ROOT / ".github" / "workflows" / "scripts" / "create-release-packages.sh").read_text(encoding="utf-8")
+        ps_text = (REPO_ROOT / ".github" / "workflows" / "scripts" / "create-release-packages.ps1").read_text(encoding="utf-8")
+
+        sh_match = re.search(r"ALL_AGENTS=\(([^)]*)\)", sh_text)
+        assert sh_match is not None
+        sh_agents = sh_match.group(1).split()
+
+        ps_match = re.search(r"\$AllAgents = @\(([^)]*)\)", ps_text)
+        assert ps_match is not None
+        ps_agents = re.findall(r"'([^']+)'", ps_match.group(1))
+
+        assert "iflow" in sh_agents
+        assert "iflow" in ps_agents
+
+    def test_iflow_in_release_scripts_build_variant(self):
+        """Release scripts should generate Markdown commands for iflow in .iflow/commands."""
+        sh_text = (REPO_ROOT / ".github" / "workflows" / "scripts" / "create-release-packages.sh").read_text(encoding="utf-8")
+        ps_text = (REPO_ROOT / ".github" / "workflows" / "scripts" / "create-release-packages.ps1").read_text(encoding="utf-8")
+
+        assert ".iflow/commands" in sh_text
+        assert ".iflow/commands" in ps_text
+        assert re.search(r"'iflow'\s*\{.*?\.iflow/commands", ps_text, re.S) is not None
+
+    def test_iflow_in_github_release_output(self):
+        """GitHub release script should include iflow template packages."""
+        gh_release_text = (REPO_ROOT / ".github" / "workflows" / "scripts" / "create-github-release.sh").read_text(encoding="utf-8")
+
+        assert "spec-kit-template-iflow-sh-" in gh_release_text
+        assert "spec-kit-template-iflow-ps-" in gh_release_text
+
+    def test_iflow_in_agent_context_scripts(self):
+        """Agent context scripts should support iflow agent type."""
+        bash_text = (REPO_ROOT / "scripts" / "bash" / "update-agent-context.sh").read_text(encoding="utf-8")
+        pwsh_text = (REPO_ROOT / "scripts" / "powershell" / "update-agent-context.ps1").read_text(encoding="utf-8")
+
+        assert "iflow" in bash_text
+        assert "IFLOW_FILE" in bash_text
+        assert "iflow" in pwsh_text
+        assert "IFLOW_FILE" in pwsh_text
+
+    def test_ai_help_includes_iflow(self):
+        """CLI help text for --ai should include iflow."""
+        assert "iflow" in AI_ASSISTANT_HELP

tests/test_ai_skills.py

@@ -11,10 +11,12 @@ Tests cover:
 """
 
 import re
+import zipfile
 import pytest
 import tempfile
 import shutil
 import yaml
+import typer
 from pathlib import Path
 from unittest.mock import patch
 
@@ -22,8 +24,8 @@ import specify_cli
 
 from specify_cli import (
     _get_skills_dir,
+    _migrate_legacy_kimi_dotted_skills,
     install_ai_skills,
-    AGENT_SKILLS_DIR_OVERRIDES,
     DEFAULT_SKILLS_DIR,
     SKILL_DESCRIPTIONS,
     AGENT_CONFIG,
@@ -62,7 +64,7 @@ def templates_dir(project_dir):
     tpl_root.mkdir(parents=True, exist_ok=True)
 
     # Template with valid YAML frontmatter
-    (tpl_root / "specify.md").write_text(
+    (tpl_root / "speckit.specify.md").write_text(
         "---\n"
         "description: Create or update the feature specification.\n"
         "handoffs:\n"
@@ -79,7 +81,7 @@ def templates_dir(project_dir):
     )
 
     # Template with minimal frontmatter
-    (tpl_root / "plan.md").write_text(
+    (tpl_root / "speckit.plan.md").write_text(
         "---\n"
         "description: Generate implementation plan.\n"
         "---\n"
@@ -91,7 +93,7 @@ def templates_dir(project_dir):
     )
 
     # Template with no frontmatter
-    (tpl_root / "tasks.md").write_text(
+    (tpl_root / "speckit.tasks.md").write_text(
         "# Tasks Command\n"
         "\n"
         "Body without frontmatter.\n",
@@ -99,7 +101,7 @@ def templates_dir(project_dir):
     )
 
     # Template with empty YAML frontmatter (yaml.safe_load returns None)
-    (tpl_root / "empty_fm.md").write_text(
+    (tpl_root / "speckit.empty_fm.md").write_text(
         "---\n"
         "---\n"
         "\n"
@@ -167,8 +169,8 @@ class TestGetSkillsDir:
         result = _get_skills_dir(project_dir, "copilot")
         assert result == project_dir / ".github" / "skills"
 
-    def test_codex_uses_override(self, project_dir):
-        """Codex should use the AGENT_SKILLS_DIR_OVERRIDES value."""
+    def test_codex_skills_dir_from_agent_config(self, project_dir):
+        """Codex should resolve skills directory from AGENT_CONFIG folder."""
         result = _get_skills_dir(project_dir, "codex")
         assert result == project_dir / ".agents" / "skills"
 
@@ -182,6 +184,11 @@ class TestGetSkillsDir:
         result = _get_skills_dir(project_dir, "kiro-cli")
         assert result == project_dir / ".kiro" / "skills"
 
+    def test_pi_skills_dir(self, project_dir):
+        """Pi should use .pi/skills/."""
+        result = _get_skills_dir(project_dir, "pi")
+        assert result == project_dir / ".pi" / "skills"
+
     def test_unknown_agent_uses_default(self, project_dir):
         """Unknown agents should fall back to DEFAULT_SKILLS_DIR."""
         result = _get_skills_dir(project_dir, "nonexistent-agent")
@@ -196,12 +203,71 @@ class TestGetSkillsDir:
             # Should always end with "skills"
             assert result.name == "skills"
 
-    def test_override_takes_precedence_over_config(self, project_dir):
-        """AGENT_SKILLS_DIR_OVERRIDES should take precedence over AGENT_CONFIG."""
-        for agent_key in AGENT_SKILLS_DIR_OVERRIDES:
-            result = _get_skills_dir(project_dir, agent_key)
-            expected = project_dir / AGENT_SKILLS_DIR_OVERRIDES[agent_key]
-            assert result == expected
+class TestKimiLegacySkillMigration:
+    """Test temporary migration from Kimi dotted skill names to hyphenated names."""
+
+    def test_migrates_legacy_dotted_skill_directory(self, project_dir):
+        skills_dir = project_dir / ".kimi" / "skills"
+        legacy_dir = skills_dir / "speckit.plan"
+        legacy_dir.mkdir(parents=True)
+        (legacy_dir / "SKILL.md").write_text("legacy")
+
+        migrated, removed = _migrate_legacy_kimi_dotted_skills(skills_dir)
+
+        assert migrated == 1
+        assert removed == 0
+        assert not legacy_dir.exists()
+        assert (skills_dir / "speckit-plan" / "SKILL.md").exists()
+
+    def test_removes_legacy_dir_when_hyphenated_target_exists_with_same_content(self, project_dir):
+        skills_dir = project_dir / ".kimi" / "skills"
+        legacy_dir = skills_dir / "speckit.plan"
+        legacy_dir.mkdir(parents=True)
+        (legacy_dir / "SKILL.md").write_text("legacy")
+        target_dir = skills_dir / "speckit-plan"
+        target_dir.mkdir(parents=True)
+        (target_dir / "SKILL.md").write_text("legacy")
+
+        migrated, removed = _migrate_legacy_kimi_dotted_skills(skills_dir)
+
+        assert migrated == 0
+        assert removed == 1
+        assert not legacy_dir.exists()
+        assert (target_dir / "SKILL.md").read_text() == "legacy"
+
+    def test_keeps_legacy_dir_when_hyphenated_target_differs(self, project_dir):
+        skills_dir = project_dir / ".kimi" / "skills"
+        legacy_dir = skills_dir / "speckit.plan"
+        legacy_dir.mkdir(parents=True)
+        (legacy_dir / "SKILL.md").write_text("legacy")
+        target_dir = skills_dir / "speckit-plan"
+        target_dir.mkdir(parents=True)
+        (target_dir / "SKILL.md").write_text("new")
+
+        migrated, removed = _migrate_legacy_kimi_dotted_skills(skills_dir)
+
+        assert migrated == 0
+        assert removed == 0
+        assert legacy_dir.exists()
+        assert (legacy_dir / "SKILL.md").read_text() == "legacy"
+        assert (target_dir / "SKILL.md").read_text() == "new"
+
+    def test_keeps_legacy_dir_when_matching_target_but_extra_files_exist(self, project_dir):
+        skills_dir = project_dir / ".kimi" / "skills"
+        legacy_dir = skills_dir / "speckit.plan"
+        legacy_dir.mkdir(parents=True)
+        (legacy_dir / "SKILL.md").write_text("legacy")
+        (legacy_dir / "notes.txt").write_text("custom")
+        target_dir = skills_dir / "speckit-plan"
+        target_dir.mkdir(parents=True)
+        (target_dir / "SKILL.md").write_text("legacy")
+
+        migrated, removed = _migrate_legacy_kimi_dotted_skills(skills_dir)
+
+        assert migrated == 0
+        assert removed == 0
+        assert legacy_dir.exists()
+        assert (legacy_dir / "notes.txt").read_text() == "custom"
 
 
 # ===== install_ai_skills Tests =====
@@ -337,7 +403,7 @@ class TestInstallAiSkills:
         cmds_dir = project_dir / ".claude" / "commands"
         cmds_dir.mkdir(parents=True)
 
-        (cmds_dir / "broken.md").write_text(
+        (cmds_dir / "speckit.broken.md").write_text(
             "---\n"
             "description: [unclosed bracket\n"
             "  invalid: yaml: content: here\n"
@@ -422,6 +488,27 @@ class TestInstallAiSkills:
         assert (cmds_dir / "speckit.specify.md").exists()
         assert (cmds_dir / "speckit.plan.md").exists()
 
+    def test_pi_prompt_dir_installs_skills(self, project_dir):
+        """Pi should install skills directly from .pi/prompts/."""
+        prompts_dir = project_dir / ".pi" / "prompts"
+        prompts_dir.mkdir(parents=True)
+        (prompts_dir / "speckit.specify.md").write_text(
+            "---\ndescription: Create or update the feature specification.\n---\n\n# Specify\n\nBody.\n"
+        )
+        (prompts_dir / "speckit.plan.md").write_text(
+            "---\ndescription: Generate implementation plan.\n---\n\n# Plan\n\nBody.\n"
+        )
+
+        result = install_ai_skills(project_dir, "pi")
+
+        assert result is True
+        skills_dir = project_dir / ".pi" / "skills"
+        assert skills_dir.exists()
+        skill_dirs = [d.name for d in skills_dir.iterdir() if d.is_dir()]
+        assert len(skill_dirs) >= 1
+        assert (prompts_dir / "speckit.specify.md").exists()
+        assert (prompts_dir / "speckit.plan.md").exists()
+
     @pytest.mark.parametrize("agent_key", [k for k in AGENT_CONFIG.keys() if k != "generic"])
     def test_skills_install_for_all_agents(self, temp_dir, agent_key):
         """install_ai_skills should produce skills for every configured agent."""
@@ -430,9 +517,12 @@ class TestInstallAiSkills:
 
         # Place .md templates in the agent's commands directory
         agent_folder = AGENT_CONFIG[agent_key]["folder"]
-        cmds_dir = proj / agent_folder.rstrip("/") / "commands"
+        commands_subdir = AGENT_CONFIG[agent_key].get("commands_subdir", "commands")
+        cmds_dir = proj / agent_folder.rstrip("/") / commands_subdir
         cmds_dir.mkdir(parents=True)
-        (cmds_dir / "specify.md").write_text(
+        # Copilot uses speckit.*.agent.md templates; other agents use speckit.*.md
+        fname = "speckit.specify.agent.md" if agent_key == "copilot" else "speckit.specify.md"
+        (cmds_dir / fname).write_text(
             "---\ndescription: Test command\n---\n\n# Test\n\nBody.\n"
         )
 
@@ -442,13 +532,104 @@ class TestInstallAiSkills:
         skills_dir = _get_skills_dir(proj, agent_key)
         assert skills_dir.exists()
         skill_dirs = [d.name for d in skills_dir.iterdir() if d.is_dir()]
-        # Kimi uses dot-separator (speckit.specify) to match /skill:speckit.* invocation;
-        # all other agents use hyphen-separator (speckit-specify).
-        expected_skill_name = "speckit.specify" if agent_key == "kimi" else "speckit-specify"
+        expected_skill_name = "speckit-specify"
         assert expected_skill_name in skill_dirs
         assert (skills_dir / expected_skill_name / "SKILL.md").exists()
 
+    def test_copilot_ignores_non_speckit_agents(self, project_dir):
+        """Non-speckit markdown in .github/agents/ must not produce skills."""
+        agents_dir = project_dir / ".github" / "agents"
+        agents_dir.mkdir(parents=True, exist_ok=True)
+        (agents_dir / "speckit.plan.agent.md").write_text(
+            "---\ndescription: Generate implementation plan.\n---\n\n# Plan\n\nBody.\n"
+        )
+        (agents_dir / "my-custom-agent.agent.md").write_text(
+            "---\ndescription: A user custom agent\n---\n\n# Custom\n\nBody.\n"
+        )
 
+        result = install_ai_skills(project_dir, "copilot")
+
+        assert result is True
+        skills_dir = _get_skills_dir(project_dir, "copilot")
+        assert skills_dir.exists()
+        skill_dirs = [d.name for d in skills_dir.iterdir() if d.is_dir()]
+        assert "speckit-plan" in skill_dirs
+        assert "speckit-my-custom-agent.agent" not in skill_dirs
+        assert "speckit-my-custom-agent" not in skill_dirs
+
+    @pytest.mark.parametrize("agent_key,custom_file", [
+        ("claude", "review.md"),
+        ("cursor-agent", "deploy.md"),
+        ("qwen", "my-workflow.md"),
+    ])
+    def test_non_speckit_commands_ignored_for_all_agents(self, temp_dir, agent_key, custom_file):
+        """User-authored command files must not produce skills for any agent."""
+        proj = temp_dir / f"proj-{agent_key}"
+        proj.mkdir()
+
+        agent_folder = AGENT_CONFIG[agent_key]["folder"]
+        commands_subdir = AGENT_CONFIG[agent_key].get("commands_subdir", "commands")
+        cmds_dir = proj / agent_folder.rstrip("/") / commands_subdir
+        cmds_dir.mkdir(parents=True)
+        (cmds_dir / "speckit.specify.md").write_text(
+            "---\ndescription: Create spec.\n---\n\n# Specify\n\nBody.\n"
+        )
+        (cmds_dir / custom_file).write_text(
+            "---\ndescription: User custom command\n---\n\n# Custom\n\nBody.\n"
+        )
+
+        result = install_ai_skills(proj, agent_key)
+
+        assert result is True
+        skills_dir = _get_skills_dir(proj, agent_key)
+        skill_dirs = [d.name for d in skills_dir.iterdir() if d.is_dir()]
+        assert "speckit-specify" in skill_dirs
+        custom_stem = Path(custom_file).stem
+        assert f"speckit-{custom_stem}" not in skill_dirs
+
+    def test_copilot_fallback_when_only_non_speckit_agents(self, project_dir):
+        """Fallback to templates/commands/ when .github/agents/ has no speckit.*.md files."""
+        agents_dir = project_dir / ".github" / "agents"
+        agents_dir.mkdir(parents=True, exist_ok=True)
+        # Only a user-authored agent, no speckit.* templates
+        (agents_dir / "my-custom-agent.agent.md").write_text(
+            "---\ndescription: A user custom agent\n---\n\n# Custom\n\nBody.\n"
+        )
+
+        result = install_ai_skills(project_dir, "copilot")
+
+        # Should succeed via fallback to templates/commands/
+        assert result is True
+        skills_dir = _get_skills_dir(project_dir, "copilot")
+        assert skills_dir.exists()
+        skill_dirs = [d.name for d in skills_dir.iterdir() if d.is_dir()]
+        # Should have skills from fallback templates, not from the custom agent
+        assert "speckit-plan" in skill_dirs
+        assert not any("my-custom" in d for d in skill_dirs)
+
+    @pytest.mark.parametrize("agent_key", ["claude", "cursor-agent", "qwen"])
+    def test_fallback_when_only_non_speckit_commands(self, temp_dir, agent_key):
+        """Fallback to templates/commands/ when agent dir has no speckit.*.md files."""
+        proj = temp_dir / f"proj-{agent_key}"
+        proj.mkdir()
+
+        agent_folder = AGENT_CONFIG[agent_key]["folder"]
+        commands_subdir = AGENT_CONFIG[agent_key].get("commands_subdir", "commands")
+        cmds_dir = proj / agent_folder.rstrip("/") / commands_subdir
+        cmds_dir.mkdir(parents=True)
+        # Only a user-authored command, no speckit.* templates
+        (cmds_dir / "my-custom-command.md").write_text(
+            "---\ndescription: User custom command\n---\n\n# Custom\n\nBody.\n"
+        )
+
+        result = install_ai_skills(proj, agent_key)
+
+        # Should succeed via fallback to templates/commands/
+        assert result is True
+        skills_dir = _get_skills_dir(proj, agent_key)
+        assert skills_dir.exists()
+        skill_dirs = [d.name for d in skills_dir.iterdir() if d.is_dir()]
+        assert not any("my-custom" in d for d in skill_dirs)
 
 class TestCommandCoexistence:
     """Verify install_ai_skills never touches command files.
@@ -460,14 +641,16 @@ class TestCommandCoexistence:
 
     def test_existing_commands_preserved_claude(self, project_dir, templates_dir, commands_dir_claude):
         """install_ai_skills must NOT remove pre-existing .claude/commands files."""
-        # Verify commands exist before
-        assert len(list(commands_dir_claude.glob("speckit.*"))) == 3
+        # Verify commands exist before (templates_dir adds 4 speckit.* files,
+        # commands_dir_claude overlaps with 3 of them)
+        before = list(commands_dir_claude.glob("speckit.*"))
+        assert len(before) >= 3
 
         install_ai_skills(project_dir, "claude")
 
         # Commands must still be there — install_ai_skills never touches them
         remaining = list(commands_dir_claude.glob("speckit.*"))
-        assert len(remaining) == 3
+        assert len(remaining) == len(before)
 
     def test_existing_commands_preserved_gemini(self, project_dir, templates_dir, commands_dir_gemini):
         """install_ai_skills must NOT remove pre-existing .gemini/commands files."""
@@ -570,6 +753,201 @@ class TestNewProjectCommandSkip:
         prompts_dir = target / ".kiro" / "prompts"
         assert not prompts_dir.exists()
 
+    def test_codex_native_skills_preserved_without_conversion(self, tmp_path):
+        """Codex should keep bundled .agents/skills and skip install_ai_skills conversion."""
+        from typer.testing import CliRunner
+
+        runner = CliRunner()
+        target = tmp_path / "new-codex-proj"
+
+        def fake_download(project_path, *args, **kwargs):
+            skill_dir = project_path / ".agents" / "skills" / "speckit-specify"
+            skill_dir.mkdir(parents=True, exist_ok=True)
+            (skill_dir / "SKILL.md").write_text("---\ndescription: Test skill\n---\n\nBody.\n")
+
+        with patch("specify_cli.download_and_extract_template", side_effect=fake_download), \
+             patch("specify_cli.ensure_executable_scripts"), \
+             patch("specify_cli.ensure_constitution_from_template"), \
+             patch("specify_cli.install_ai_skills") as mock_skills, \
+             patch("specify_cli.is_git_repo", return_value=False), \
+             patch("specify_cli.shutil.which", return_value="/usr/bin/codex"):
+            result = runner.invoke(
+                app,
+                ["init", str(target), "--ai", "codex", "--ai-skills", "--script", "sh", "--no-git"],
+            )
+
+        assert result.exit_code == 0
+        mock_skills.assert_not_called()
+        assert (target / ".agents" / "skills" / "speckit-specify" / "SKILL.md").exists()
+
+    def test_codex_native_skills_missing_falls_back_then_fails_cleanly(self, tmp_path):
+        """Codex should attempt fallback conversion when bundled skills are missing."""
+        from typer.testing import CliRunner
+
+        runner = CliRunner()
+        target = tmp_path / "missing-codex-skills"
+
+        with patch("specify_cli.download_and_extract_template", lambda *args, **kwargs: None), \
+             patch("specify_cli.ensure_executable_scripts"), \
+             patch("specify_cli.ensure_constitution_from_template"), \
+             patch("specify_cli.install_ai_skills", return_value=False) as mock_skills, \
+             patch("specify_cli.is_git_repo", return_value=False), \
+             patch("specify_cli.shutil.which", return_value="/usr/bin/codex"):
+            result = runner.invoke(
+                app,
+                ["init", str(target), "--ai", "codex", "--ai-skills", "--script", "sh", "--no-git"],
+            )
+
+        assert result.exit_code == 1
+        mock_skills.assert_called_once()
+        assert mock_skills.call_args.kwargs.get("overwrite_existing") is True
+        assert "Expected bundled agent skills" in result.output
+        assert "fallback conversion failed" in result.output
+
+    def test_codex_native_skills_ignores_non_speckit_skill_dirs(self, tmp_path):
+        """Non-spec-kit SKILL.md files should trigger fallback conversion, not hard-fail."""
+        from typer.testing import CliRunner
+
+        runner = CliRunner()
+        target = tmp_path / "foreign-codex-skills"
+
+        def fake_download(project_path, *args, **kwargs):
+            skill_dir = project_path / ".agents" / "skills" / "other-tool"
+            skill_dir.mkdir(parents=True, exist_ok=True)
+            (skill_dir / "SKILL.md").write_text("---\ndescription: Foreign skill\n---\n\nBody.\n")
+
+        with patch("specify_cli.download_and_extract_template", side_effect=fake_download), \
+             patch("specify_cli.ensure_executable_scripts"), \
+             patch("specify_cli.ensure_constitution_from_template"), \
+             patch("specify_cli.install_ai_skills", return_value=True) as mock_skills, \
+             patch("specify_cli.is_git_repo", return_value=False), \
+             patch("specify_cli.shutil.which", return_value="/usr/bin/codex"):
+            result = runner.invoke(
+                app,
+                ["init", str(target), "--ai", "codex", "--ai-skills", "--script", "sh", "--no-git"],
+            )
+
+        assert result.exit_code == 0
+        mock_skills.assert_called_once()
+        assert mock_skills.call_args.kwargs.get("overwrite_existing") is True
+
+    def test_kimi_legacy_migration_runs_without_ai_skills_flag(self, tmp_path):
+        """Kimi init should migrate dotted legacy skills even when --ai-skills is not set."""
+        from typer.testing import CliRunner
+
+        runner = CliRunner()
+        target = tmp_path / "kimi-legacy-no-ai-skills"
+
+        def fake_download(project_path, *args, **kwargs):
+            legacy_dir = project_path / ".kimi" / "skills" / "speckit.plan"
+            legacy_dir.mkdir(parents=True, exist_ok=True)
+            (legacy_dir / "SKILL.md").write_text("---\nname: speckit.plan\n---\n\nlegacy\n")
+
+        with patch("specify_cli.download_and_extract_template", side_effect=fake_download), \
+             patch("specify_cli.ensure_executable_scripts"), \
+             patch("specify_cli.ensure_constitution_from_template"), \
+             patch("specify_cli.is_git_repo", return_value=False), \
+             patch("specify_cli.shutil.which", return_value="/usr/bin/kimi"):
+            result = runner.invoke(
+                app,
+                ["init", str(target), "--ai", "kimi", "--script", "sh", "--no-git"],
+            )
+
+        assert result.exit_code == 0
+        assert not (target / ".kimi" / "skills" / "speckit.plan").exists()
+        assert (target / ".kimi" / "skills" / "speckit-plan" / "SKILL.md").exists()
+
+    def test_codex_ai_skills_here_mode_preserves_existing_codex_dir(self, tmp_path, monkeypatch):
+        """Codex --here skills init should not delete a pre-existing .codex directory."""
+        from typer.testing import CliRunner
+
+        runner = CliRunner()
+        target = tmp_path / "codex-preserve-here"
+        target.mkdir()
+        existing_prompts = target / ".codex" / "prompts"
+        existing_prompts.mkdir(parents=True)
+        (existing_prompts / "custom.md").write_text("custom")
+        monkeypatch.chdir(target)
+
+        with patch("specify_cli.download_and_extract_template", return_value=target), \
+             patch("specify_cli.ensure_executable_scripts"), \
+             patch("specify_cli.ensure_constitution_from_template"), \
+             patch("specify_cli.install_ai_skills", return_value=True), \
+             patch("specify_cli.is_git_repo", return_value=True), \
+             patch("specify_cli.shutil.which", return_value="/usr/bin/codex"):
+            result = runner.invoke(
+                app,
+                ["init", "--here", "--ai", "codex", "--ai-skills", "--script", "sh", "--no-git"],
+                input="y\n",
+            )
+
+        assert result.exit_code == 0
+        assert (target / ".codex").exists()
+        assert (existing_prompts / "custom.md").exists()
+
+    def test_codex_ai_skills_fresh_dir_does_not_create_codex_dir(self, tmp_path):
+        """Fresh-directory Codex skills init should not leave legacy .codex from archive."""
+        target = tmp_path / "fresh-codex-proj"
+        archive = tmp_path / "codex-template.zip"
+
+        with zipfile.ZipFile(archive, "w") as zf:
+            zf.writestr("template-root/.codex/prompts/speckit.specify.md", "legacy")
+            zf.writestr("template-root/.specify/templates/constitution-template.md", "constitution")
+
+        fake_meta = {
+            "filename": archive.name,
+            "size": archive.stat().st_size,
+            "release": "vtest",
+            "asset_url": "https://example.invalid/template.zip",
+        }
+
+        with patch("specify_cli.download_template_from_github", return_value=(archive, fake_meta)):
+            specify_cli.download_and_extract_template(
+                target,
+                "codex",
+                "sh",
+                is_current_dir=False,
+                skip_legacy_codex_prompts=True,
+                verbose=False,
+            )
+
+        assert target.exists()
+        assert (target / ".specify").exists()
+        assert not (target / ".codex").exists()
+
+    @pytest.mark.parametrize("is_current_dir", [False, True])
+    def test_download_and_extract_template_blocks_zip_path_traversal(self, tmp_path, monkeypatch, is_current_dir):
+        """Extraction should reject ZIP members escaping the target directory."""
+        target = (tmp_path / "here-proj") if is_current_dir else (tmp_path / "new-proj")
+        if is_current_dir:
+            target.mkdir()
+            monkeypatch.chdir(target)
+
+        archive = tmp_path / "malicious-template.zip"
+        with zipfile.ZipFile(archive, "w") as zf:
+            zf.writestr("../evil.txt", "pwned")
+            zf.writestr("template-root/.specify/templates/constitution-template.md", "constitution")
+
+        fake_meta = {
+            "filename": archive.name,
+            "size": archive.stat().st_size,
+            "release": "vtest",
+            "asset_url": "https://example.invalid/template.zip",
+        }
+
+        with patch("specify_cli.download_template_from_github", return_value=(archive, fake_meta)):
+            with pytest.raises(typer.Exit):
+                specify_cli.download_and_extract_template(
+                    target,
+                    "codex",
+                    "sh",
+                    is_current_dir=is_current_dir,
+                    skip_legacy_codex_prompts=True,
+                    verbose=False,
+                )
+
+        assert not (tmp_path / "evil.txt").exists()
+
     def test_commands_preserved_when_skills_fail(self, tmp_path):
         """If skills fail, commands should NOT be removed (safety net)."""
         from typer.testing import CliRunner
@@ -660,6 +1038,21 @@ class TestSkipIfExists:
         # All 4 templates should produce skills (specify, plan, tasks, empty_fm)
         assert len(skill_dirs) == 4
 
+    def test_existing_skill_overwritten_when_enabled(self, project_dir, templates_dir):
+        """When overwrite_existing=True, pre-existing SKILL.md should be replaced."""
+        skill_dir = project_dir / ".claude" / "skills" / "speckit-specify"
+        skill_dir.mkdir(parents=True)
+        custom_content = "# My Custom Specify Skill\nUser-modified content\n"
+        skill_file = skill_dir / "SKILL.md"
+        skill_file.write_text(custom_content)
+
+        result = install_ai_skills(project_dir, "claude", overwrite_existing=True)
+
+        assert result is True
+        updated_content = skill_file.read_text()
+        assert updated_content != custom_content
+        assert "name: speckit-specify" in updated_content
+
 
 # ===== SKILL_DESCRIPTIONS Coverage Tests =====
 
@@ -713,6 +1106,17 @@ class TestCliValidation:
         assert "Explicit command support was deprecated in Antigravity version 1.20.5." in result.output
         assert "--ai-skills" in result.output
 
+    def test_codex_without_ai_skills_fails(self):
+        """--ai codex without --ai-skills should fail with exit code 1."""
+        from typer.testing import CliRunner
+
+        runner = CliRunner()
+        result = runner.invoke(app, ["init", "test-proj", "--ai", "codex"])
+
+        assert result.exit_code == 1
+        assert "Custom prompt-based spec-kit initialization is deprecated for Codex CLI" in result.output
+        assert "--ai-skills" in result.output
+
     def test_interactive_agy_without_ai_skills_prompts_skills(self, monkeypatch):
         """Interactive selector returning agy without --ai-skills should automatically enable --ai-skills."""
         from typer.testing import CliRunner
@@ -755,6 +1159,72 @@ class TestCliValidation:
             assert result.exit_code == 0
             assert "Explicit command support was deprecated" not in result.output
 
+    def test_interactive_codex_without_ai_skills_enables_skills(self, monkeypatch):
+        """Interactive selector returning codex without --ai-skills should automatically enable --ai-skills."""
+        from typer.testing import CliRunner
+
+        def _fake_select_with_arrows(*args, **kwargs):
+            options = kwargs.get("options")
+            if options is None and len(args) >= 1:
+                options = args[0]
+
+            if isinstance(options, dict) and "codex" in options:
+                return "codex"
+            if isinstance(options, (list, tuple)) and "codex" in options:
+                return "codex"
+
+            if isinstance(options, dict) and options:
+                return next(iter(options.keys()))
+            if isinstance(options, (list, tuple)) and options:
+                return options[0]
+
+            return None
+
+        monkeypatch.setattr("specify_cli.select_with_arrows", _fake_select_with_arrows)
+
+        def _fake_download(*args, **kwargs):
+            project_path = Path(args[0])
+            skill_dir = project_path / ".agents" / "skills" / "speckit-specify"
+            skill_dir.mkdir(parents=True, exist_ok=True)
+            (skill_dir / "SKILL.md").write_text("---\ndescription: Test skill\n---\n\nBody.\n")
+
+        monkeypatch.setattr("specify_cli.download_and_extract_template", _fake_download)
+
+        runner = CliRunner()
+        with runner.isolated_filesystem():
+            result = runner.invoke(app, ["init", "test-proj", "--no-git", "--ignore-agent-tools"])
+
+            assert result.exit_code == 0
+            assert "Custom prompt-based spec-kit initialization is deprecated for Codex CLI" not in result.output
+            assert ".agents/skills" in result.output
+            assert "$speckit-constitution" in result.output
+            assert "/speckit.constitution" not in result.output
+            assert "Optional skills that you can use for your specs" in result.output
+
+    def test_kimi_next_steps_show_skill_invocation(self, monkeypatch):
+        """Kimi next-steps guidance should display /skill:speckit-* usage."""
+        from typer.testing import CliRunner
+
+        def _fake_download(*args, **kwargs):
+            project_path = Path(args[0])
+            skill_dir = project_path / ".kimi" / "skills" / "speckit-specify"
+            skill_dir.mkdir(parents=True, exist_ok=True)
+            (skill_dir / "SKILL.md").write_text("---\ndescription: Test skill\n---\n\nBody.\n")
+
+        monkeypatch.setattr("specify_cli.download_and_extract_template", _fake_download)
+
+        runner = CliRunner()
+        with runner.isolated_filesystem():
+            result = runner.invoke(
+                app,
+                ["init", "test-proj", "--ai", "kimi", "--no-git", "--ignore-agent-tools"],
+            )
+
+            assert result.exit_code == 0
+            assert "/skill:speckit-constitution" in result.output
+            assert "/speckit.constitution" not in result.output
+            assert "Optional skills that you can use for your specs" in result.output
+
     def test_ai_skills_flag_appears_in_help(self):
         """--ai-skills should appear in init --help output."""
         from typer.testing import CliRunner
@@ -774,10 +1244,12 @@ class TestCliValidation:
         target = tmp_path / "kiro-alias-proj"
 
         with patch("specify_cli.download_and_extract_template") as mock_download, \
+             patch("specify_cli.scaffold_from_core_pack", create=True) as mock_scaffold, \
              patch("specify_cli.ensure_executable_scripts"), \
              patch("specify_cli.ensure_constitution_from_template"), \
              patch("specify_cli.is_git_repo", return_value=False), \
              patch("specify_cli.shutil.which", return_value="/usr/bin/git"):
+            mock_scaffold.return_value = True
             result = runner.invoke(
                 app,
                 [
@@ -793,9 +1265,14 @@ class TestCliValidation:
             )
 
         assert result.exit_code == 0
-        assert mock_download.called
-        # download_and_extract_template(project_path, ai_assistant, script_type, ...)
+        # Without --offline, the download path should be taken.
+        assert mock_download.called, (
+            "Expected download_and_extract_template to be called (default non-offline path)"
+        )
         assert mock_download.call_args.args[1] == "kiro-cli"
+        assert not mock_scaffold.called, (
+            "scaffold_from_core_pack should not be called without --offline"
+        )
 
     def test_q_removed_from_agent_config(self):
         """Amazon Q legacy key should not remain in AGENT_CONFIG."""

tests/test_branch_numbering.py

@@ -0,0 +1,89 @@
+"""
+Unit tests for branch numbering options (sequential vs timestamp).
+
+Tests cover:
+- Persisting branch_numbering in init-options.json
+- Default value when branch_numbering is None
+- Validation of branch_numbering values
+"""
+
+import json
+from pathlib import Path
+
+from specify_cli import save_init_options
+
+
+class TestSaveBranchNumbering:
+    """Tests for save_init_options with branch_numbering."""
+
+    def test_save_branch_numbering_timestamp(self, tmp_path: Path):
+        opts = {"branch_numbering": "timestamp", "ai": "claude"}
+        save_init_options(tmp_path, opts)
+
+        saved = json.loads((tmp_path / ".specify/init-options.json").read_text())
+        assert saved["branch_numbering"] == "timestamp"
+
+    def test_save_branch_numbering_sequential(self, tmp_path: Path):
+        opts = {"branch_numbering": "sequential", "ai": "claude"}
+        save_init_options(tmp_path, opts)
+
+        saved = json.loads((tmp_path / ".specify/init-options.json").read_text())
+        assert saved["branch_numbering"] == "sequential"
+
+    def test_branch_numbering_defaults_to_sequential(self, tmp_path: Path, monkeypatch):
+        from typer.testing import CliRunner
+        from specify_cli import app
+
+        def _fake_download(project_path, *args, **kwargs):
+            Path(project_path).mkdir(parents=True, exist_ok=True)
+
+        monkeypatch.setattr("specify_cli.download_and_extract_template", _fake_download)
+
+        project_dir = tmp_path / "proj"
+        runner = CliRunner()
+        result = runner.invoke(app, ["init", str(project_dir), "--ai", "claude", "--ignore-agent-tools"])
+        assert result.exit_code == 0
+
+        saved = json.loads((project_dir / ".specify/init-options.json").read_text())
+        assert saved["branch_numbering"] == "sequential"
+
+
+class TestBranchNumberingValidation:
+    """Tests for branch_numbering CLI validation via CliRunner."""
+
+    def test_invalid_branch_numbering_rejected(self, tmp_path: Path):
+        from typer.testing import CliRunner
+        from specify_cli import app
+
+        runner = CliRunner()
+        result = runner.invoke(app, ["init", str(tmp_path / "proj"), "--ai", "claude", "--branch-numbering", "foobar"])
+        assert result.exit_code == 1
+        assert "Invalid --branch-numbering" in result.output
+
+    def test_valid_branch_numbering_sequential(self, tmp_path: Path, monkeypatch):
+        from typer.testing import CliRunner
+        from specify_cli import app
+
+        def _fake_download(project_path, *args, **kwargs):
+            Path(project_path).mkdir(parents=True, exist_ok=True)
+
+        monkeypatch.setattr("specify_cli.download_and_extract_template", _fake_download)
+
+        runner = CliRunner()
+        result = runner.invoke(app, ["init", str(tmp_path / "proj"), "--ai", "claude", "--branch-numbering", "sequential", "--ignore-agent-tools"])
+        assert result.exit_code == 0
+        assert "Invalid --branch-numbering" not in (result.output or "")
+
+    def test_valid_branch_numbering_timestamp(self, tmp_path: Path, monkeypatch):
+        from typer.testing import CliRunner
+        from specify_cli import app
+
+        def _fake_download(project_path, *args, **kwargs):
+            Path(project_path).mkdir(parents=True, exist_ok=True)
+
+        monkeypatch.setattr("specify_cli.download_and_extract_template", _fake_download)
+
+        runner = CliRunner()
+        result = runner.invoke(app, ["init", str(tmp_path / "proj"), "--ai", "claude", "--branch-numbering", "timestamp", "--ignore-agent-tools"])
+        assert result.exit_code == 0
+        assert "Invalid --branch-numbering" not in (result.output or "")

tests/test_check_tool.py

@@ -0,0 +1,96 @@
+"""Tests for check_tool() — Claude Code CLI detection across install methods.
+
+Covers issue https://github.com/github/spec-kit/issues/550:
+  `specify check` reports "Claude Code CLI (not found)" even when claude is
+  installed via npm-local (the default `claude` installer path).
+"""
+
+from unittest.mock import patch, MagicMock
+
+from specify_cli import check_tool
+
+
+class TestCheckToolClaude:
+    """Claude CLI detection must work for all install methods."""
+
+    def test_detected_via_migrate_installer_path(self, tmp_path):
+        """claude migrate-installer puts binary at ~/.claude/local/claude."""
+        fake_claude = tmp_path / "claude"
+        fake_claude.touch()
+
+        # Ensure npm-local path is missing so we only exercise migrate-installer path
+        fake_missing = tmp_path / "nonexistent" / "claude"
+
+        with patch("specify_cli.CLAUDE_LOCAL_PATH", fake_claude), \
+             patch("specify_cli.CLAUDE_NPM_LOCAL_PATH", fake_missing), \
+             patch("shutil.which", return_value=None):
+            assert check_tool("claude") is True
+
+    def test_detected_via_npm_local_path(self, tmp_path):
+        """npm-local install puts binary at ~/.claude/local/node_modules/.bin/claude."""
+        fake_npm_claude = tmp_path / "node_modules" / ".bin" / "claude"
+        fake_npm_claude.parent.mkdir(parents=True)
+        fake_npm_claude.touch()
+
+        # Neither the migrate-installer path nor PATH has claude
+        fake_migrate = tmp_path / "nonexistent" / "claude"
+
+        with patch("specify_cli.CLAUDE_LOCAL_PATH", fake_migrate), \
+             patch("specify_cli.CLAUDE_NPM_LOCAL_PATH", fake_npm_claude), \
+             patch("shutil.which", return_value=None):
+            assert check_tool("claude") is True
+
+    def test_detected_via_path(self, tmp_path):
+        """claude on PATH (global npm install) should still work."""
+        fake_missing = tmp_path / "nonexistent" / "claude"
+
+        with patch("specify_cli.CLAUDE_LOCAL_PATH", fake_missing), \
+             patch("specify_cli.CLAUDE_NPM_LOCAL_PATH", fake_missing), \
+             patch("shutil.which", return_value="/usr/local/bin/claude"):
+            assert check_tool("claude") is True
+
+    def test_not_found_when_nowhere(self, tmp_path):
+        """Should return False when claude is genuinely not installed."""
+        fake_missing = tmp_path / "nonexistent" / "claude"
+
+        with patch("specify_cli.CLAUDE_LOCAL_PATH", fake_missing), \
+             patch("specify_cli.CLAUDE_NPM_LOCAL_PATH", fake_missing), \
+             patch("shutil.which", return_value=None):
+            assert check_tool("claude") is False
+
+    def test_tracker_updated_on_npm_local_detection(self, tmp_path):
+        """StepTracker should be marked 'available' for npm-local installs."""
+        fake_npm_claude = tmp_path / "node_modules" / ".bin" / "claude"
+        fake_npm_claude.parent.mkdir(parents=True)
+        fake_npm_claude.touch()
+
+        fake_missing = tmp_path / "nonexistent" / "claude"
+        tracker = MagicMock()
+
+        with patch("specify_cli.CLAUDE_LOCAL_PATH", fake_missing), \
+             patch("specify_cli.CLAUDE_NPM_LOCAL_PATH", fake_npm_claude), \
+             patch("shutil.which", return_value=None):
+            result = check_tool("claude", tracker=tracker)
+
+        assert result is True
+        tracker.complete.assert_called_once_with("claude", "available")
+
+
+class TestCheckToolOther:
+    """Non-Claude tools should be unaffected by the fix."""
+
+    def test_git_detected_via_path(self):
+        with patch("shutil.which", return_value="/usr/bin/git"):
+            assert check_tool("git") is True
+
+    def test_missing_tool(self):
+        with patch("shutil.which", return_value=None):
+            assert check_tool("nonexistent-tool") is False
+
+    def test_kiro_fallback(self):
+        """kiro-cli detection should try both kiro-cli and kiro."""
+        def fake_which(name):
+            return "/usr/bin/kiro" if name == "kiro" else None
+
+        with patch("shutil.which", side_effect=fake_which):
+            assert check_tool("kiro-cli") is True

tests/test_core_pack_scaffold.py

@@ -0,0 +1,613 @@
+"""
+Validation tests for offline/air-gapped scaffolding (PR #1803).
+
+For every supported AI agent (except "generic") the scaffold output is verified
+against invariants and compared byte-for-byte with the canonical output produced
+by create-release-packages.sh.
+
+Since scaffold_from_core_pack() now invokes the release script at runtime, the
+parity test (section 9) runs the script independently and compares the results
+to ensure the integration is correct.
+
+Per-agent invariants verified
+──────────────────────────────
+  • Command files are written to the directory declared in AGENT_CONFIG
+  • File count matches the number of source templates
+  • Extension is correct: .toml (TOML agents), .agent.md (copilot), .md (rest)
+  • No unresolved placeholders remain ({SCRIPT}, {ARGS}, __AGENT__)
+  • Argument token is correct: {{args}} for TOML agents, $ARGUMENTS for others
+  • Path rewrites applied: scripts/ → .specify/scripts/ etc.
+  • TOML files have "description" and "prompt" fields
+  • Markdown files have parseable YAML frontmatter
+  • Copilot: companion speckit.*.prompt.md files are generated in prompts/
+  • .specify/scripts/ contains at least one script file
+  • .specify/templates/ contains at least one template file
+
+Parity invariant
+────────────────
+  Every file produced by scaffold_from_core_pack() must be byte-for-byte
+  identical to the same file in the ZIP produced by the release script.
+"""
+
+import os
+import re
+import shutil
+import subprocess
+import tomllib
+import zipfile
+from pathlib import Path
+
+import pytest
+import yaml
+
+from specify_cli import (
+    AGENT_CONFIG,
+    _TOML_AGENTS,
+    _locate_core_pack,
+    scaffold_from_core_pack,
+)
+
+_REPO_ROOT = Path(__file__).parent.parent
+_RELEASE_SCRIPT = _REPO_ROOT / ".github" / "workflows" / "scripts" / "create-release-packages.sh"
+
+
+def _find_bash() -> str | None:
+    """Return the path to a usable bash on this machine, or None."""
+    # Prefer PATH lookup so non-standard install locations (Nix, CI) are found.
+    on_path = shutil.which("bash")
+    if on_path:
+        return on_path
+    candidates = [
+        "/opt/homebrew/bin/bash",
+        "/usr/local/bin/bash",
+        "/bin/bash",
+        "/usr/bin/bash",
+    ]
+    for candidate in candidates:
+        try:
+            result = subprocess.run(
+                [candidate, "--version"],
+                capture_output=True, text=True, timeout=5,
+            )
+            if result.returncode == 0:
+                return candidate
+        except (FileNotFoundError, subprocess.TimeoutExpired):
+            continue
+    return None
+
+
+def _run_release_script(agent: str, script_type: str, bash: str, output_dir: Path) -> Path:
+    """Run create-release-packages.sh for *agent*/*script_type* and return the
+    path to the generated ZIP.  *output_dir* receives the build artifacts so
+    the repo working tree stays clean."""
+    env = os.environ.copy()
+    env["AGENTS"] = agent
+    env["SCRIPTS"] = script_type
+    env["GENRELEASES_DIR"] = str(output_dir)
+
+    result = subprocess.run(
+        [bash, str(_RELEASE_SCRIPT), "v0.0.0"],
+        capture_output=True, text=True,
+        cwd=str(_REPO_ROOT),
+        env=env,
+        timeout=300,
+    )
+
+    if result.returncode != 0:
+        pytest.fail(
+            f"Release script failed with exit code {result.returncode}\n"
+            f"stdout:\n{result.stdout}\nstderr:\n{result.stderr}"
+        )
+
+    zip_pattern = f"spec-kit-template-{agent}-{script_type}-v0.0.0.zip"
+    zip_path = output_dir / zip_pattern
+    if not zip_path.exists():
+        pytest.fail(
+            f"Release script did not produce expected ZIP: {zip_path}\n"
+            f"stdout:\n{result.stdout}\nstderr:\n{result.stderr}"
+        )
+    return zip_path
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+# Number of source command templates (one per .md file in templates/commands/)
+
+
+def _commands_dir() -> Path:
+    """Return the command templates directory (source-checkout or core_pack)."""
+    core = _locate_core_pack()
+    if core and (core / "commands").is_dir():
+        return core / "commands"
+    # Source-checkout fallback
+    repo_root = Path(__file__).parent.parent
+    return repo_root / "templates" / "commands"
+
+
+def _get_source_template_stems() -> list[str]:
+    """Return the stems of source command template files (e.g. ['specify', 'plan', ...])."""
+    return sorted(p.stem for p in _commands_dir().glob("*.md"))
+
+
+def _expected_cmd_dir(project_path: Path, agent: str) -> Path:
+    """Return the expected command-files directory for a given agent."""
+    cfg = AGENT_CONFIG[agent]
+    folder = (cfg.get("folder") or "").rstrip("/")
+    subdir = cfg.get("commands_subdir", "commands")
+    if folder:
+        return project_path / folder / subdir
+    return project_path / ".speckit" / subdir
+
+
+# Agents whose commands are laid out as <skills_dir>/<name>/SKILL.md.
+# Maps agent -> separator used in skill directory names.
+_SKILL_AGENTS: dict[str, str] = {"codex": "-", "kimi": "-"}
+
+
+def _expected_ext(agent: str) -> str:
+    if agent in _TOML_AGENTS:
+        return "toml"
+    if agent == "copilot":
+        return "agent.md"
+    if agent in _SKILL_AGENTS:
+        return "SKILL.md"
+    return "md"
+
+
+def _list_command_files(cmd_dir: Path, agent: str) -> list[Path]:
+    """List generated command files, handling skills-based directory layouts."""
+    if agent in _SKILL_AGENTS:
+        sep = _SKILL_AGENTS[agent]
+        return sorted(cmd_dir.glob(f"speckit{sep}*/SKILL.md"))
+    ext = _expected_ext(agent)
+    return sorted(cmd_dir.glob(f"speckit.*.{ext}"))
+
+
+def _collect_relative_files(root: Path) -> dict[str, bytes]:
+    """Walk *root* and return {relative_posix_path: file_bytes}."""
+    result: dict[str, bytes] = {}
+    for p in root.rglob("*"):
+        if p.is_file():
+            result[p.relative_to(root).as_posix()] = p.read_bytes()
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+@pytest.fixture(scope="session")
+def source_template_stems() -> list[str]:
+    return _get_source_template_stems()
+
+
+@pytest.fixture(scope="session")
+def scaffolded_sh(tmp_path_factory):
+    """Session-scoped cache: scaffold once per agent with script_type='sh'."""
+    cache = {}
+    def _get(agent: str) -> Path:
+        if agent not in cache:
+            project = tmp_path_factory.mktemp(f"scaffold_sh_{agent}")
+            ok = scaffold_from_core_pack(project, agent, "sh")
+            assert ok, f"scaffold_from_core_pack returned False for agent '{agent}'"
+            cache[agent] = project
+        return cache[agent]
+    return _get
+
+
+@pytest.fixture(scope="session")
+def scaffolded_ps(tmp_path_factory):
+    """Session-scoped cache: scaffold once per agent with script_type='ps'."""
+    cache = {}
+    def _get(agent: str) -> Path:
+        if agent not in cache:
+            project = tmp_path_factory.mktemp(f"scaffold_ps_{agent}")
+            ok = scaffold_from_core_pack(project, agent, "ps")
+            assert ok, f"scaffold_from_core_pack returned False for agent '{agent}'"
+            cache[agent] = project
+        return cache[agent]
+    return _get
+
+
+# ---------------------------------------------------------------------------
+# Parametrize over all agents except "generic"
+# ---------------------------------------------------------------------------
+
+_TESTABLE_AGENTS = [a for a in AGENT_CONFIG if a != "generic"]
+
+
+# ---------------------------------------------------------------------------
+# 1. Bundled scaffold — directory structure
+# ---------------------------------------------------------------------------
+
+@pytest.mark.parametrize("agent", _TESTABLE_AGENTS)
+def test_scaffold_creates_specify_scripts(agent, scaffolded_sh):
+    """scaffold_from_core_pack copies at least one script into .specify/scripts/."""
+    project = scaffolded_sh(agent)
+
+    scripts_dir = project / ".specify" / "scripts" / "bash"
+    assert scripts_dir.is_dir(), f".specify/scripts/bash/ missing for agent '{agent}'"
+    assert any(scripts_dir.iterdir()), f".specify/scripts/bash/ is empty for agent '{agent}'"
+
+
+@pytest.mark.parametrize("agent", _TESTABLE_AGENTS)
+def test_scaffold_creates_specify_templates(agent, scaffolded_sh):
+    """scaffold_from_core_pack copies at least one page template into .specify/templates/."""
+    project = scaffolded_sh(agent)
+
+    tpl_dir = project / ".specify" / "templates"
+    assert tpl_dir.is_dir(), f".specify/templates/ missing for agent '{agent}'"
+    assert any(tpl_dir.iterdir()), ".specify/templates/ is empty"
+
+
+@pytest.mark.parametrize("agent", _TESTABLE_AGENTS)
+def test_scaffold_command_dir_location(agent, scaffolded_sh):
+    """Command files land in the directory declared by AGENT_CONFIG."""
+    project = scaffolded_sh(agent)
+
+    cmd_dir = _expected_cmd_dir(project, agent)
+    assert cmd_dir.is_dir(), (
+        f"Command dir '{cmd_dir.relative_to(project)}' not created for agent '{agent}'"
+    )
+
+
+# ---------------------------------------------------------------------------
+# 2. Bundled scaffold — file count
+# ---------------------------------------------------------------------------
+
+@pytest.mark.parametrize("agent", _TESTABLE_AGENTS)
+def test_scaffold_command_file_count(agent, scaffolded_sh, source_template_stems):
+    """One command file is generated per source template for every agent."""
+    project = scaffolded_sh(agent)
+
+    cmd_dir = _expected_cmd_dir(project, agent)
+    generated = _list_command_files(cmd_dir, agent)
+
+    if cmd_dir.is_dir():
+        dir_listing = list(cmd_dir.iterdir())
+    else:
+        dir_listing = f"<command dir missing: {cmd_dir}>"
+
+    assert len(generated) == len(source_template_stems), (
+        f"Agent '{agent}': expected {len(source_template_stems)} command files "
+        f"({_expected_ext(agent)}), found {len(generated)}. Dir: {dir_listing}"
+    )
+
+
+@pytest.mark.parametrize("agent", _TESTABLE_AGENTS)
+def test_scaffold_command_file_names(agent, scaffolded_sh, source_template_stems):
+    """Each source template stem maps to a corresponding speckit.<stem>.<ext> file."""
+    project = scaffolded_sh(agent)
+
+    cmd_dir = _expected_cmd_dir(project, agent)
+    for stem in source_template_stems:
+        if agent in _SKILL_AGENTS:
+            sep = _SKILL_AGENTS[agent]
+            expected = cmd_dir / f"speckit{sep}{stem}" / "SKILL.md"
+        else:
+            ext = _expected_ext(agent)
+            expected = cmd_dir / f"speckit.{stem}.{ext}"
+        assert expected.is_file(), (
+            f"Agent '{agent}': expected file '{expected.name}' not found in '{cmd_dir}'"
+        )
+
+
+# ---------------------------------------------------------------------------
+# 3. Bundled scaffold — content invariants
+# ---------------------------------------------------------------------------
+
+@pytest.mark.parametrize("agent", _TESTABLE_AGENTS)
+def test_no_unresolved_script_placeholder(agent, scaffolded_sh):
+    """{SCRIPT} must not appear in any generated command file."""
+    project = scaffolded_sh(agent)
+
+    cmd_dir = _expected_cmd_dir(project, agent)
+    for f in cmd_dir.rglob("*"):
+        if f.is_file():
+            content = f.read_text(encoding="utf-8")
+            assert "{SCRIPT}" not in content, (
+                f"Unresolved {{SCRIPT}} in '{f.relative_to(project)}' for agent '{agent}'"
+            )
+
+
+@pytest.mark.parametrize("agent", _TESTABLE_AGENTS)
+def test_no_unresolved_agent_placeholder(agent, scaffolded_sh):
+    """__AGENT__ must not appear in any generated command file."""
+    project = scaffolded_sh(agent)
+
+    cmd_dir = _expected_cmd_dir(project, agent)
+    for f in cmd_dir.rglob("*"):
+        if f.is_file():
+            content = f.read_text(encoding="utf-8")
+            assert "__AGENT__" not in content, (
+                f"Unresolved __AGENT__ in '{f.relative_to(project)}' for agent '{agent}'"
+            )
+
+
+@pytest.mark.parametrize("agent", _TESTABLE_AGENTS)
+def test_no_unresolved_args_placeholder(agent, scaffolded_sh):
+    """{ARGS} must not appear in any generated command file (replaced with agent-specific token)."""
+    project = scaffolded_sh(agent)
+
+    cmd_dir = _expected_cmd_dir(project, agent)
+    for f in cmd_dir.rglob("*"):
+        if f.is_file():
+            content = f.read_text(encoding="utf-8")
+            assert "{ARGS}" not in content, (
+                f"Unresolved {{ARGS}} in '{f.relative_to(project)}' for agent '{agent}'"
+            )
+
+
+# Build a set of template stems that actually contain {ARGS} in their source.
+_TEMPLATES_WITH_ARGS: frozenset[str] = frozenset(
+    p.stem
+    for p in _commands_dir().glob("*.md")
+    if "{ARGS}" in p.read_text(encoding="utf-8")
+)
+
+
+@pytest.mark.parametrize("agent", _TESTABLE_AGENTS)
+def test_argument_token_format(agent, scaffolded_sh):
+    """For templates that carry an {ARGS} token:
+    - TOML agents must emit {{args}}
+    - Markdown agents must emit $ARGUMENTS
+    Templates without {ARGS} (e.g. implement, plan) are skipped.
+    """
+    project = scaffolded_sh(agent)
+
+    cmd_dir = _expected_cmd_dir(project, agent)
+
+    for f in _list_command_files(cmd_dir, agent):
+        # Recover the stem from the file path
+        if agent in _SKILL_AGENTS:
+            sep = _SKILL_AGENTS[agent]
+            stem = f.parent.name.removeprefix(f"speckit{sep}")
+        else:
+            ext = _expected_ext(agent)
+            stem = f.name.removeprefix("speckit.").removesuffix(f".{ext}")
+        if stem not in _TEMPLATES_WITH_ARGS:
+            continue  # this template has no argument token
+
+        content = f.read_text(encoding="utf-8")
+        if agent in _TOML_AGENTS:
+            assert "{{args}}" in content, (
+                f"TOML agent '{agent}': expected '{{{{args}}}}' in '{f.name}'"
+            )
+        else:
+            assert "$ARGUMENTS" in content, (
+                f"Markdown agent '{agent}': expected '$ARGUMENTS' in '{f.name}'"
+            )
+
+
+@pytest.mark.parametrize("agent", _TESTABLE_AGENTS)
+def test_path_rewrites_applied(agent, scaffolded_sh):
+    """Bare scripts/ and templates/ paths must be rewritten to .specify/ variants.
+
+    YAML frontmatter 'source:' metadata fields are excluded — they reference
+    the original template path for provenance, not a runtime path.
+    """
+    project = scaffolded_sh(agent)
+
+    cmd_dir = _expected_cmd_dir(project, agent)
+    for f in cmd_dir.rglob("*"):
+        if not f.is_file():
+            continue
+        content = f.read_text(encoding="utf-8")
+
+        # Strip YAML frontmatter before checking — source: metadata is not a runtime path
+        body = content
+        if content.startswith("---"):
+            parts = content.split("---", 2)
+            if len(parts) >= 3:
+                body = parts[2]
+
+        # Should not contain bare (non-.specify/) script paths
+        assert not re.search(r'(?<!\.specify/)scripts/', body), (
+            f"Bare scripts/ path found in '{f.relative_to(project)}' for agent '{agent}'"
+        )
+        assert not re.search(r'(?<!\.specify/)templates/', body), (
+            f"Bare templates/ path found in '{f.relative_to(project)}' for agent '{agent}'"
+        )
+
+
+# ---------------------------------------------------------------------------
+# 4. TOML format checks
+# ---------------------------------------------------------------------------
+
+@pytest.mark.parametrize("agent", sorted(_TOML_AGENTS))
+def test_toml_format_valid(agent, scaffolded_sh):
+    """TOML agents: every command file must have description and prompt fields."""
+    project = scaffolded_sh(agent)
+
+    cmd_dir = _expected_cmd_dir(project, agent)
+    for f in cmd_dir.glob("speckit.*.toml"):
+        content = f.read_text(encoding="utf-8")
+        assert 'description = "' in content, (
+            f"Missing 'description' in '{f.name}' for agent '{agent}'"
+        )
+        assert 'prompt = """' in content, (
+            f"Missing 'prompt' block in '{f.name}' for agent '{agent}'"
+        )
+
+
+# ---------------------------------------------------------------------------
+# 5. Markdown frontmatter checks
+# ---------------------------------------------------------------------------
+
+_MARKDOWN_AGENTS = [a for a in _TESTABLE_AGENTS if a not in _TOML_AGENTS]
+
+
+@pytest.mark.parametrize("agent", _MARKDOWN_AGENTS)
+def test_markdown_has_frontmatter(agent, scaffolded_sh):
+    """Markdown agents: every command file must start with valid YAML frontmatter."""
+    project = scaffolded_sh(agent)
+
+    cmd_dir = _expected_cmd_dir(project, agent)
+    for f in _list_command_files(cmd_dir, agent):
+        content = f.read_text(encoding="utf-8")
+        assert content.startswith("---"), (
+            f"No YAML frontmatter in '{f.name}' for agent '{agent}'"
+        )
+        parts = content.split("---", 2)
+        assert len(parts) >= 3, f"Incomplete frontmatter in '{f.name}'"
+        fm = yaml.safe_load(parts[1])
+        assert fm is not None, f"Empty frontmatter in '{f.name}'"
+        assert "description" in fm, (
+            f"'description' key missing from frontmatter in '{f.name}' for agent '{agent}'"
+        )
+
+
+# ---------------------------------------------------------------------------
+# 6. Copilot-specific: companion .prompt.md files
+# ---------------------------------------------------------------------------
+
+def test_copilot_companion_prompt_files(scaffolded_sh, source_template_stems):
+    """Copilot: a speckit.<stem>.prompt.md companion is created for every .agent.md file."""
+    project = scaffolded_sh("copilot")
+
+    prompts_dir = project / ".github" / "prompts"
+    assert prompts_dir.is_dir(), ".github/prompts/ not created for copilot"
+
+    for stem in source_template_stems:
+        prompt_file = prompts_dir / f"speckit.{stem}.prompt.md"
+        assert prompt_file.is_file(), (
+            f"Companion prompt file '{prompt_file.name}' missing for copilot"
+        )
+
+
+def test_copilot_prompt_file_content(scaffolded_sh, source_template_stems):
+    """Copilot companion .prompt.md files must reference their parent .agent.md."""
+    project = scaffolded_sh("copilot")
+
+    prompts_dir = project / ".github" / "prompts"
+    for stem in source_template_stems:
+        f = prompts_dir / f"speckit.{stem}.prompt.md"
+        content = f.read_text(encoding="utf-8")
+        assert f"agent: speckit.{stem}" in content, (
+            f"Companion '{f.name}' does not reference 'speckit.{stem}'"
+        )
+
+
+# ---------------------------------------------------------------------------
+# 7. PowerShell script variant
+# ---------------------------------------------------------------------------
+
+@pytest.mark.parametrize("agent", _TESTABLE_AGENTS)
+def test_scaffold_powershell_variant(agent, scaffolded_ps, source_template_stems):
+    """scaffold_from_core_pack with script_type='ps' creates correct files."""
+    project = scaffolded_ps(agent)
+
+    scripts_dir = project / ".specify" / "scripts" / "powershell"
+    assert scripts_dir.is_dir(), f".specify/scripts/powershell/ missing for '{agent}'"
+    assert any(scripts_dir.iterdir()), ".specify/scripts/powershell/ is empty"
+
+    cmd_dir = _expected_cmd_dir(project, agent)
+    generated = _list_command_files(cmd_dir, agent)
+    assert len(generated) == len(source_template_stems)
+
+
+# ---------------------------------------------------------------------------
+# 8. Parity: bundled vs. real create-release-packages.sh ZIP
+# ---------------------------------------------------------------------------
+
+@pytest.fixture(scope="session")
+def release_script_trees(tmp_path_factory):
+    """Session-scoped cache: run release script once per (agent, script_type)."""
+    cache: dict[tuple[str, str], dict[str, bytes]] = {}
+    bash = _find_bash()
+
+    def _get(agent: str, script_type: str) -> dict[str, bytes] | None:
+        if bash is None:
+            return None
+        key = (agent, script_type)
+        if key not in cache:
+            tmp = tmp_path_factory.mktemp(f"release_{agent}_{script_type}")
+            gen_dir = tmp / "genreleases"
+            gen_dir.mkdir()
+            zip_path = _run_release_script(agent, script_type, bash, gen_dir)
+            extracted = tmp / "extracted"
+            extracted.mkdir()
+            with zipfile.ZipFile(zip_path) as zf:
+                zf.extractall(extracted)
+            cache[key] = _collect_relative_files(extracted)
+        return cache[key]
+    return _get
+
+
+@pytest.mark.parametrize("script_type", ["sh", "ps"])
+@pytest.mark.parametrize("agent", _TESTABLE_AGENTS)
+def test_parity_bundled_vs_release_script(agent, script_type, scaffolded_sh, scaffolded_ps, release_script_trees):
+    """scaffold_from_core_pack() file tree is identical to the ZIP produced by
+    create-release-packages.sh for every agent and script type.
+
+    This is the true end-to-end parity check: the Python offline path must
+    produce exactly the same artifacts as the canonical shell release script.
+
+    Both sides are session-cached: each agent/script_type combination is
+    scaffolded and release-scripted only once across all tests.
+    """
+    script_tree = release_script_trees(agent, script_type)
+    if script_tree is None:
+        pytest.skip("bash required to run create-release-packages.sh")
+
+    # Reuse session-cached scaffold output
+    if script_type == "sh":
+        bundled_dir = scaffolded_sh(agent)
+    else:
+        bundled_dir = scaffolded_ps(agent)
+
+    bundled_tree = _collect_relative_files(bundled_dir)
+
+    only_bundled = set(bundled_tree) - set(script_tree)
+    only_script = set(script_tree) - set(bundled_tree)
+
+    assert not only_bundled, (
+        f"Agent '{agent}' ({script_type}): files only in bundled output (not in release ZIP):\n  "
+        + "\n  ".join(sorted(only_bundled))
+    )
+    assert not only_script, (
+        f"Agent '{agent}' ({script_type}): files only in release ZIP (not in bundled output):\n  "
+        + "\n  ".join(sorted(only_script))
+    )
+
+    for name in bundled_tree:
+        assert bundled_tree[name] == script_tree[name], (
+            f"Agent '{agent}' ({script_type}): file '{name}' content differs between "
+            f"bundled output and release script ZIP"
+        )
+
+
+# ---------------------------------------------------------------------------
+# Section 10 – pyproject.toml force-include covers all template files
+# ---------------------------------------------------------------------------
+
+def test_pyproject_force_include_covers_all_templates():
+    """Every file in templates/ (excluding commands/) must be listed in
+    pyproject.toml's [tool.hatch.build.targets.wheel.force-include] section.
+
+    This prevents new template files from being silently omitted from the
+    wheel, which would break ``specify init --offline``.
+    """
+    templates_dir = _REPO_ROOT / "templates"
+    # Collect all files directly in templates/ (not in subdirectories like commands/)
+    repo_template_files = sorted(
+        f.name for f in templates_dir.iterdir()
+        if f.is_file()
+    )
+    assert repo_template_files, "Expected at least one template file in templates/"
+
+    pyproject_path = _REPO_ROOT / "pyproject.toml"
+    with open(pyproject_path, "rb") as f:
+        pyproject = tomllib.load(f)
+    force_include = pyproject.get("tool", {}).get("hatch", {}).get("build", {}).get("targets", {}).get("wheel", {}).get("force-include", {})
+
+    missing = [
+        name for name in repo_template_files
+        if f"templates/{name}" not in force_include
+    ]
+    assert not missing, (
+        "Template files not listed in pyproject.toml force-include "
+        "(offline scaffolding will miss them):\n  "
+        + "\n  ".join(missing)
+    )

tests/test_extension_skills.py

@@ -0,0 +1,741 @@
+"""
+Unit tests for extension skill auto-registration.
+
+Tests cover:
+- SKILL.md generation when --ai-skills was used during init
+- No skills created when ai_skills not active
+- SKILL.md content correctness
+- Existing user-modified skills not overwritten
+- Skill cleanup on extension removal
+- Registry metadata includes registered_skills
+"""
+
+import json
+import pytest
+import tempfile
+import shutil
+import yaml
+from pathlib import Path
+
+from specify_cli.extensions import (
+    ExtensionManifest,
+    ExtensionManager,
+    ExtensionError,
+)
+
+
+# ===== Helpers =====
+
+def _create_init_options(project_root: Path, ai: str = "claude", ai_skills: bool = True):
+    """Write a .specify/init-options.json file."""
+    opts_dir = project_root / ".specify"
+    opts_dir.mkdir(parents=True, exist_ok=True)
+    opts_file = opts_dir / "init-options.json"
+    opts_file.write_text(json.dumps({
+        "ai": ai,
+        "ai_skills": ai_skills,
+        "script": "sh",
+    }))
+
+
+def _create_skills_dir(project_root: Path, ai: str = "claude") -> Path:
+    """Create and return the expected skills directory for the given agent."""
+    # Match the logic in _get_skills_dir() from specify_cli
+    from specify_cli import AGENT_CONFIG, DEFAULT_SKILLS_DIR
+
+    agent_config = AGENT_CONFIG.get(ai, {})
+    agent_folder = agent_config.get("folder", "")
+    if agent_folder:
+        skills_dir = project_root / agent_folder.rstrip("/") / "skills"
+    else:
+        skills_dir = project_root / DEFAULT_SKILLS_DIR
+
+    skills_dir.mkdir(parents=True, exist_ok=True)
+    return skills_dir
+
+
+def _create_extension_dir(temp_dir: Path, ext_id: str = "test-ext") -> Path:
+    """Create a complete extension directory with manifest and command files."""
+    ext_dir = temp_dir / ext_id
+    ext_dir.mkdir()
+
+    manifest_data = {
+        "schema_version": "1.0",
+        "extension": {
+            "id": ext_id,
+            "name": "Test Extension",
+            "version": "1.0.0",
+            "description": "A test extension for skill registration",
+        },
+        "requires": {
+            "speckit_version": ">=0.1.0",
+        },
+        "provides": {
+            "commands": [
+                {
+                    "name": f"speckit.{ext_id}.hello",
+                    "file": "commands/hello.md",
+                    "description": "Test hello command",
+                },
+                {
+                    "name": f"speckit.{ext_id}.world",
+                    "file": "commands/world.md",
+                    "description": "Test world command",
+                },
+            ]
+        },
+    }
+
+    with open(ext_dir / "extension.yml", "w") as f:
+        yaml.dump(manifest_data, f)
+
+    commands_dir = ext_dir / "commands"
+    commands_dir.mkdir()
+
+    (commands_dir / "hello.md").write_text(
+        "---\n"
+        "description: \"Test hello command\"\n"
+        "---\n"
+        "\n"
+        "# Hello Command\n"
+        "\n"
+        "Run this to say hello.\n"
+        "$ARGUMENTS\n"
+    )
+
+    (commands_dir / "world.md").write_text(
+        "---\n"
+        "description: \"Test world command\"\n"
+        "---\n"
+        "\n"
+        "# World Command\n"
+        "\n"
+        "Run this to greet the world.\n"
+    )
+
+    return ext_dir
+
+
+# ===== Fixtures =====
+
+@pytest.fixture
+def temp_dir():
+    """Create a temporary directory for tests."""
+    tmpdir = tempfile.mkdtemp()
+    yield Path(tmpdir)
+    shutil.rmtree(tmpdir)
+
+
+@pytest.fixture
+def project_dir(temp_dir):
+    """Create a mock spec-kit project directory."""
+    proj_dir = temp_dir / "project"
+    proj_dir.mkdir()
+
+    # Create .specify directory
+    specify_dir = proj_dir / ".specify"
+    specify_dir.mkdir()
+
+    return proj_dir
+
+
+@pytest.fixture
+def extension_dir(temp_dir):
+    """Create a complete extension directory."""
+    return _create_extension_dir(temp_dir)
+
+
+@pytest.fixture
+def skills_project(project_dir):
+    """Create a project with --ai-skills enabled and skills directory."""
+    _create_init_options(project_dir, ai="claude", ai_skills=True)
+    skills_dir = _create_skills_dir(project_dir, ai="claude")
+    return project_dir, skills_dir
+
+
+@pytest.fixture
+def no_skills_project(project_dir):
+    """Create a project without --ai-skills."""
+    _create_init_options(project_dir, ai="claude", ai_skills=False)
+    return project_dir
+
+
+# ===== ExtensionManager._get_skills_dir Tests =====
+
+class TestExtensionManagerGetSkillsDir:
+    """Test _get_skills_dir() on ExtensionManager."""
+
+    def test_returns_skills_dir_when_active(self, skills_project):
+        """Should return skills dir when ai_skills is true and dir exists."""
+        project_dir, skills_dir = skills_project
+        manager = ExtensionManager(project_dir)
+        result = manager._get_skills_dir()
+        assert result == skills_dir
+
+    def test_returns_none_when_no_ai_skills(self, no_skills_project):
+        """Should return None when ai_skills is false."""
+        manager = ExtensionManager(no_skills_project)
+        result = manager._get_skills_dir()
+        assert result is None
+
+    def test_returns_none_when_no_init_options(self, project_dir):
+        """Should return None when init-options.json is missing."""
+        manager = ExtensionManager(project_dir)
+        result = manager._get_skills_dir()
+        assert result is None
+
+    def test_returns_none_when_skills_dir_missing(self, project_dir):
+        """Should return None when skills dir doesn't exist on disk."""
+        _create_init_options(project_dir, ai="claude", ai_skills=True)
+        # Don't create the skills directory
+        manager = ExtensionManager(project_dir)
+        result = manager._get_skills_dir()
+        assert result is None
+
+    def test_returns_kimi_skills_dir_when_ai_skills_disabled(self, project_dir):
+        """Kimi should still use its native skills dir when ai_skills is false."""
+        _create_init_options(project_dir, ai="kimi", ai_skills=False)
+        skills_dir = _create_skills_dir(project_dir, ai="kimi")
+        manager = ExtensionManager(project_dir)
+        result = manager._get_skills_dir()
+        assert result == skills_dir
+
+    def test_returns_none_for_non_dict_init_options(self, project_dir):
+        """Corrupted-but-parseable init-options should not crash skill-dir lookup."""
+        opts_file = project_dir / ".specify" / "init-options.json"
+        opts_file.parent.mkdir(parents=True, exist_ok=True)
+        opts_file.write_text("[]")
+        _create_skills_dir(project_dir, ai="claude")
+        manager = ExtensionManager(project_dir)
+        result = manager._get_skills_dir()
+        assert result is None
+
+
+# ===== Extension Skill Registration Tests =====
+
+class TestExtensionSkillRegistration:
+    """Test _register_extension_skills() on ExtensionManager."""
+
+    def test_skills_created_when_ai_skills_active(self, skills_project, extension_dir):
+        """Skills should be created when ai_skills is enabled."""
+        project_dir, skills_dir = skills_project
+        manager = ExtensionManager(project_dir)
+        manifest = manager.install_from_directory(
+            extension_dir, "0.1.0", register_commands=False
+        )
+
+        # Check that skill directories were created
+        skill_dirs = sorted([d.name for d in skills_dir.iterdir() if d.is_dir()])
+        assert "speckit-test-ext-hello" in skill_dirs
+        assert "speckit-test-ext-world" in skill_dirs
+
+    def test_skill_md_content_correct(self, skills_project, extension_dir):
+        """SKILL.md should have correct agentskills.io structure."""
+        project_dir, skills_dir = skills_project
+        manager = ExtensionManager(project_dir)
+        manager.install_from_directory(
+            extension_dir, "0.1.0", register_commands=False
+        )
+
+        skill_file = skills_dir / "speckit-test-ext-hello" / "SKILL.md"
+        assert skill_file.exists()
+        content = skill_file.read_text()
+
+        # Check structure
+        assert content.startswith("---\n")
+        assert "name: speckit-test-ext-hello" in content
+        assert "description:" in content
+        assert "Test hello command" in content
+        assert "source: extension:test-ext" in content
+        assert "author: github-spec-kit" in content
+        assert "compatibility:" in content
+        assert "Run this to say hello." in content
+
+    def test_skill_md_has_parseable_yaml(self, skills_project, extension_dir):
+        """Generated SKILL.md should contain valid, parseable YAML frontmatter."""
+        project_dir, skills_dir = skills_project
+        manager = ExtensionManager(project_dir)
+        manager.install_from_directory(
+            extension_dir, "0.1.0", register_commands=False
+        )
+
+        skill_file = skills_dir / "speckit-test-ext-hello" / "SKILL.md"
+        content = skill_file.read_text()
+
+        assert content.startswith("---\n")
+        parts = content.split("---", 2)
+        assert len(parts) >= 3
+        parsed = yaml.safe_load(parts[1])
+        assert isinstance(parsed, dict)
+        assert parsed["name"] == "speckit-test-ext-hello"
+        assert "description" in parsed
+
+    def test_no_skills_when_ai_skills_disabled(self, no_skills_project, extension_dir):
+        """No skills should be created when ai_skills is false."""
+        manager = ExtensionManager(no_skills_project)
+        manifest = manager.install_from_directory(
+            extension_dir, "0.1.0", register_commands=False
+        )
+
+        # Verify registry
+        metadata = manager.registry.get(manifest.id)
+        assert metadata["registered_skills"] == []
+
+    def test_no_skills_when_init_options_missing(self, project_dir, extension_dir):
+        """No skills should be created when init-options.json is absent."""
+        manager = ExtensionManager(project_dir)
+        manifest = manager.install_from_directory(
+            extension_dir, "0.1.0", register_commands=False
+        )
+
+        metadata = manager.registry.get(manifest.id)
+        assert metadata["registered_skills"] == []
+
+    def test_existing_skill_not_overwritten(self, skills_project, extension_dir):
+        """Pre-existing SKILL.md should not be overwritten."""
+        project_dir, skills_dir = skills_project
+
+        # Pre-create a custom skill
+        custom_dir = skills_dir / "speckit-test-ext-hello"
+        custom_dir.mkdir(parents=True)
+        custom_content = "# My Custom Hello Skill\nUser-modified content\n"
+        (custom_dir / "SKILL.md").write_text(custom_content)
+
+        manager = ExtensionManager(project_dir)
+        manifest = manager.install_from_directory(
+            extension_dir, "0.1.0", register_commands=False
+        )
+
+        # Custom skill should be untouched
+        assert (custom_dir / "SKILL.md").read_text() == custom_content
+
+        # But the other skill should still be created
+        metadata = manager.registry.get(manifest.id)
+        assert "speckit-test-ext-world" in metadata["registered_skills"]
+        # The pre-existing one should NOT be in registered_skills (it was skipped)
+        assert "speckit-test-ext-hello" not in metadata["registered_skills"]
+
+    def test_registered_skills_in_registry(self, skills_project, extension_dir):
+        """Registry should contain registered_skills list."""
+        project_dir, skills_dir = skills_project
+        manager = ExtensionManager(project_dir)
+        manifest = manager.install_from_directory(
+            extension_dir, "0.1.0", register_commands=False
+        )
+
+        metadata = manager.registry.get(manifest.id)
+        assert "registered_skills" in metadata
+        assert len(metadata["registered_skills"]) == 2
+        assert "speckit-test-ext-hello" in metadata["registered_skills"]
+        assert "speckit-test-ext-world" in metadata["registered_skills"]
+
+    def test_kimi_uses_hyphenated_skill_names(self, project_dir, temp_dir):
+        """Kimi agent should use the same hyphenated skill names as hooks."""
+        _create_init_options(project_dir, ai="kimi", ai_skills=True)
+        _create_skills_dir(project_dir, ai="kimi")
+        ext_dir = _create_extension_dir(temp_dir, ext_id="test-ext")
+
+        manager = ExtensionManager(project_dir)
+        manifest = manager.install_from_directory(
+            ext_dir, "0.1.0", register_commands=False
+        )
+
+        metadata = manager.registry.get(manifest.id)
+        assert "speckit-test-ext-hello" in metadata["registered_skills"]
+        assert "speckit-test-ext-world" in metadata["registered_skills"]
+
+    def test_kimi_creates_skills_when_ai_skills_disabled(self, project_dir, temp_dir):
+        """Kimi should still auto-register extension skills in native-skills mode."""
+        _create_init_options(project_dir, ai="kimi", ai_skills=False)
+        skills_dir = _create_skills_dir(project_dir, ai="kimi")
+        ext_dir = _create_extension_dir(temp_dir, ext_id="test-ext")
+
+        manager = ExtensionManager(project_dir)
+        manifest = manager.install_from_directory(
+            ext_dir, "0.1.0", register_commands=False
+        )
+
+        metadata = manager.registry.get(manifest.id)
+        assert "speckit-test-ext-hello" in metadata["registered_skills"]
+        assert "speckit-test-ext-world" in metadata["registered_skills"]
+        assert (skills_dir / "speckit-test-ext-hello" / "SKILL.md").exists()
+
+    def test_skill_registration_resolves_script_placeholders(self, project_dir, temp_dir):
+        """Auto-registered extension skills should resolve script placeholders."""
+        _create_init_options(project_dir, ai="claude", ai_skills=True)
+        skills_dir = _create_skills_dir(project_dir, ai="claude")
+
+        ext_dir = temp_dir / "scripted-ext"
+        ext_dir.mkdir()
+        manifest_data = {
+            "schema_version": "1.0",
+            "extension": {
+                "id": "scripted-ext",
+                "name": "Scripted Extension",
+                "version": "1.0.0",
+                "description": "Test",
+            },
+            "requires": {"speckit_version": ">=0.1.0"},
+            "provides": {
+                "commands": [
+                    {
+                        "name": "speckit.scripted-ext.plan",
+                        "file": "commands/plan.md",
+                        "description": "Scripted plan command",
+                    }
+                ]
+            },
+        }
+        with open(ext_dir / "extension.yml", "w") as f:
+            yaml.dump(manifest_data, f)
+
+        (ext_dir / "commands").mkdir()
+        (ext_dir / "commands" / "plan.md").write_text(
+            "---\n"
+            "description: Scripted plan command\n"
+            "scripts:\n"
+            "  sh: ../../scripts/bash/setup-plan.sh --json \"{ARGS}\"\n"
+            "agent_scripts:\n"
+            "  sh: ../../scripts/bash/update-agent-context.sh __AGENT__\n"
+            "---\n\n"
+            "Run {SCRIPT}\n"
+            "Then {AGENT_SCRIPT}\n"
+            "Review templates/checklist.md and memory/constitution.md for __AGENT__.\n"
+        )
+
+        manager = ExtensionManager(project_dir)
+        manager.install_from_directory(ext_dir, "0.1.0", register_commands=False)
+
+        content = (skills_dir / "speckit-scripted-ext-plan" / "SKILL.md").read_text()
+        assert "{SCRIPT}" not in content
+        assert "{AGENT_SCRIPT}" not in content
+        assert "{ARGS}" not in content
+        assert "__AGENT__" not in content
+        assert '.specify/scripts/bash/setup-plan.sh --json "$ARGUMENTS"' in content
+        assert ".specify/scripts/bash/update-agent-context.sh claude" in content
+        assert ".specify/templates/checklist.md" in content
+        assert ".specify/memory/constitution.md" in content
+
+    def test_missing_command_file_skipped(self, skills_project, temp_dir):
+        """Commands with missing source files should be skipped gracefully."""
+        project_dir, skills_dir = skills_project
+
+        ext_dir = temp_dir / "missing-cmd-ext"
+        ext_dir.mkdir()
+        manifest_data = {
+            "schema_version": "1.0",
+            "extension": {
+                "id": "missing-cmd-ext",
+                "name": "Missing Cmd Extension",
+                "version": "1.0.0",
+                "description": "Test",
+            },
+            "requires": {"speckit_version": ">=0.1.0"},
+            "provides": {
+                "commands": [
+                    {
+                        "name": "speckit.missing-cmd-ext.exists",
+                        "file": "commands/exists.md",
+                        "description": "Exists",
+                    },
+                    {
+                        "name": "speckit.missing-cmd-ext.ghost",
+                        "file": "commands/ghost.md",
+                        "description": "Does not exist",
+                    },
+                ]
+            },
+        }
+        with open(ext_dir / "extension.yml", "w") as f:
+            yaml.dump(manifest_data, f)
+
+        (ext_dir / "commands").mkdir()
+        (ext_dir / "commands" / "exists.md").write_text(
+            "---\ndescription: Exists\n---\n\n# Exists\n\nBody.\n"
+        )
+        # Intentionally do NOT create ghost.md
+
+        manager = ExtensionManager(project_dir)
+        manifest = manager.install_from_directory(
+            ext_dir, "0.1.0", register_commands=False
+        )
+
+        metadata = manager.registry.get(manifest.id)
+        assert "speckit-missing-cmd-ext-exists" in metadata["registered_skills"]
+        assert "speckit-missing-cmd-ext-ghost" not in metadata["registered_skills"]
+
+
+# ===== Extension Skill Unregistration Tests =====
+
+class TestExtensionSkillUnregistration:
+    """Test _unregister_extension_skills() on ExtensionManager."""
+
+    def test_skills_removed_on_extension_remove(self, skills_project, extension_dir):
+        """Removing an extension should clean up its skill directories."""
+        project_dir, skills_dir = skills_project
+        manager = ExtensionManager(project_dir)
+        manifest = manager.install_from_directory(
+            extension_dir, "0.1.0", register_commands=False
+        )
+
+        # Verify skills exist
+        assert (skills_dir / "speckit-test-ext-hello" / "SKILL.md").exists()
+        assert (skills_dir / "speckit-test-ext-world" / "SKILL.md").exists()
+
+        # Remove extension
+        result = manager.remove(manifest.id, keep_config=False)
+        assert result is True
+
+        # Skills should be gone
+        assert not (skills_dir / "speckit-test-ext-hello").exists()
+        assert not (skills_dir / "speckit-test-ext-world").exists()
+
+    def test_other_skills_preserved_on_remove(self, skills_project, extension_dir):
+        """Non-extension skills should not be affected by extension removal."""
+        project_dir, skills_dir = skills_project
+
+        # Pre-create a custom skill
+        custom_dir = skills_dir / "my-custom-skill"
+        custom_dir.mkdir(parents=True)
+        (custom_dir / "SKILL.md").write_text("# My Custom Skill\n")
+
+        manager = ExtensionManager(project_dir)
+        manifest = manager.install_from_directory(
+            extension_dir, "0.1.0", register_commands=False
+        )
+
+        manager.remove(manifest.id, keep_config=False)
+
+        # Custom skill should still exist
+        assert (custom_dir / "SKILL.md").exists()
+        assert (custom_dir / "SKILL.md").read_text() == "# My Custom Skill\n"
+
+    def test_remove_handles_already_deleted_skills(self, skills_project, extension_dir):
+        """Gracefully handle case where skill dirs were already deleted."""
+        project_dir, skills_dir = skills_project
+        manager = ExtensionManager(project_dir)
+        manifest = manager.install_from_directory(
+            extension_dir, "0.1.0", register_commands=False
+        )
+
+        # Manually delete skill dirs before calling remove
+        shutil.rmtree(skills_dir / "speckit-test-ext-hello")
+        shutil.rmtree(skills_dir / "speckit-test-ext-world")
+
+        # Should not raise
+        result = manager.remove(manifest.id, keep_config=False)
+        assert result is True
+
+    def test_remove_no_skills_when_not_active(self, no_skills_project, extension_dir):
+        """Removal without active skills should not attempt skill cleanup."""
+        manager = ExtensionManager(no_skills_project)
+        manifest = manager.install_from_directory(
+            extension_dir, "0.1.0", register_commands=False
+        )
+
+        # Should not raise even though no skills exist
+        result = manager.remove(manifest.id, keep_config=False)
+        assert result is True
+
+
+# ===== Command File Without Frontmatter =====
+
+class TestExtensionSkillEdgeCases:
+    """Test edge cases in extension skill registration."""
+
+    def test_install_with_non_dict_init_options_does_not_crash(self, project_dir, extension_dir):
+        """Corrupted init-options payloads should disable skill registration, not crash install."""
+        opts_file = project_dir / ".specify" / "init-options.json"
+        opts_file.parent.mkdir(parents=True, exist_ok=True)
+        opts_file.write_text("[]")
+        _create_skills_dir(project_dir, ai="claude")
+
+        manager = ExtensionManager(project_dir)
+        manifest = manager.install_from_directory(
+            extension_dir, "0.1.0", register_commands=False
+        )
+
+        metadata = manager.registry.get(manifest.id)
+        assert metadata["registered_skills"] == []
+
+    def test_command_without_frontmatter(self, skills_project, temp_dir):
+        """Commands without YAML frontmatter should still produce valid skills."""
+        project_dir, skills_dir = skills_project
+
+        ext_dir = temp_dir / "nofm-ext"
+        ext_dir.mkdir()
+        manifest_data = {
+            "schema_version": "1.0",
+            "extension": {
+                "id": "nofm-ext",
+                "name": "No Frontmatter Extension",
+                "version": "1.0.0",
+                "description": "Test",
+            },
+            "requires": {"speckit_version": ">=0.1.0"},
+            "provides": {
+                "commands": [
+                    {
+                        "name": "speckit.nofm-ext.plain",
+                        "file": "commands/plain.md",
+                        "description": "Plain command",
+                    }
+                ]
+            },
+        }
+        with open(ext_dir / "extension.yml", "w") as f:
+            yaml.dump(manifest_data, f)
+
+        (ext_dir / "commands").mkdir()
+        (ext_dir / "commands" / "plain.md").write_text(
+            "# Plain Command\n\nBody without frontmatter.\n"
+        )
+
+        manager = ExtensionManager(project_dir)
+        manifest = manager.install_from_directory(
+            ext_dir, "0.1.0", register_commands=False
+        )
+
+        skill_file = skills_dir / "speckit-nofm-ext-plain" / "SKILL.md"
+        assert skill_file.exists()
+        content = skill_file.read_text()
+        assert "name: speckit-nofm-ext-plain" in content
+        # Fallback description when no frontmatter description
+        assert "Extension command: speckit.nofm-ext.plain" in content
+        assert "Body without frontmatter." in content
+
+    def test_gemini_agent_skills(self, project_dir, temp_dir):
+        """Gemini agent should use .gemini/skills/ for skill directory."""
+        _create_init_options(project_dir, ai="gemini", ai_skills=True)
+        _create_skills_dir(project_dir, ai="gemini")
+        ext_dir = _create_extension_dir(temp_dir, ext_id="test-ext")
+
+        manager = ExtensionManager(project_dir)
+        manifest = manager.install_from_directory(
+            ext_dir, "0.1.0", register_commands=False
+        )
+
+        skills_dir = project_dir / ".gemini" / "skills"
+        assert (skills_dir / "speckit-test-ext-hello" / "SKILL.md").exists()
+        assert (skills_dir / "speckit-test-ext-world" / "SKILL.md").exists()
+
+    def test_multiple_extensions_independent_skills(self, skills_project, temp_dir):
+        """Installing and removing different extensions should be independent."""
+        project_dir, skills_dir = skills_project
+
+        ext_dir_a = _create_extension_dir(temp_dir, ext_id="ext-a")
+        ext_dir_b = _create_extension_dir(temp_dir, ext_id="ext-b")
+
+        manager = ExtensionManager(project_dir)
+        manifest_a = manager.install_from_directory(
+            ext_dir_a, "0.1.0", register_commands=False
+        )
+        manifest_b = manager.install_from_directory(
+            ext_dir_b, "0.1.0", register_commands=False
+        )
+
+        # Both should have skills
+        assert (skills_dir / "speckit-ext-a-hello" / "SKILL.md").exists()
+        assert (skills_dir / "speckit-ext-b-hello" / "SKILL.md").exists()
+
+        # Remove ext-a
+        manager.remove("ext-a", keep_config=False)
+
+        # ext-a skills gone, ext-b skills preserved
+        assert not (skills_dir / "speckit-ext-a-hello").exists()
+        assert (skills_dir / "speckit-ext-b-hello" / "SKILL.md").exists()
+
+    def test_malformed_frontmatter_handled(self, skills_project, temp_dir):
+        """Commands with invalid YAML frontmatter should still produce valid skills."""
+        project_dir, skills_dir = skills_project
+
+        ext_dir = temp_dir / "badfm-ext"
+        ext_dir.mkdir()
+        manifest_data = {
+            "schema_version": "1.0",
+            "extension": {
+                "id": "badfm-ext",
+                "name": "Bad Frontmatter Extension",
+                "version": "1.0.0",
+                "description": "Test",
+            },
+            "requires": {"speckit_version": ">=0.1.0"},
+            "provides": {
+                "commands": [
+                    {
+                        "name": "speckit.badfm-ext.broken",
+                        "file": "commands/broken.md",
+                        "description": "Broken frontmatter",
+                    }
+                ]
+            },
+        }
+        with open(ext_dir / "extension.yml", "w") as f:
+            yaml.dump(manifest_data, f)
+
+        (ext_dir / "commands").mkdir()
+        # Malformed YAML: invalid key-value syntax
+        (ext_dir / "commands" / "broken.md").write_text(
+            "---\n"
+            "description: [invalid yaml\n"
+            "  unclosed: bracket\n"
+            "---\n"
+            "\n"
+            "# Broken Command\n"
+            "\n"
+            "This body should still be used.\n"
+        )
+
+        manager = ExtensionManager(project_dir)
+        # Should not raise
+        manifest = manager.install_from_directory(
+            ext_dir, "0.1.0", register_commands=False
+        )
+
+        skill_file = skills_dir / "speckit-badfm-ext-broken" / "SKILL.md"
+        assert skill_file.exists()
+        content = skill_file.read_text()
+        # Fallback description since frontmatter was invalid
+        assert "Extension command: speckit.badfm-ext.broken" in content
+        assert "This body should still be used." in content
+
+    def test_remove_cleans_up_when_init_options_deleted(self, skills_project, extension_dir):
+        """Skills should be cleaned up even if init-options.json is deleted after install."""
+        project_dir, skills_dir = skills_project
+        manager = ExtensionManager(project_dir)
+        manifest = manager.install_from_directory(
+            extension_dir, "0.1.0", register_commands=False
+        )
+
+        # Verify skills exist
+        assert (skills_dir / "speckit-test-ext-hello" / "SKILL.md").exists()
+
+        # Delete init-options.json to simulate user change
+        init_opts = project_dir / ".specify" / "init-options.json"
+        init_opts.unlink()
+
+        # Remove should still clean up via fallback scan
+        result = manager.remove(manifest.id, keep_config=False)
+        assert result is True
+        assert not (skills_dir / "speckit-test-ext-hello").exists()
+        assert not (skills_dir / "speckit-test-ext-world").exists()
+
+    def test_remove_cleans_up_when_ai_skills_toggled(self, skills_project, extension_dir):
+        """Skills should be cleaned up even if ai_skills is toggled to false after install."""
+        project_dir, skills_dir = skills_project
+        manager = ExtensionManager(project_dir)
+        manifest = manager.install_from_directory(
+            extension_dir, "0.1.0", register_commands=False
+        )
+
+        # Verify skills exist
+        assert (skills_dir / "speckit-test-ext-hello" / "SKILL.md").exists()
+
+        # Toggle ai_skills to false
+        _create_init_options(project_dir, ai="claude", ai_skills=False)
+
+        # Remove should still clean up via fallback scan
+        result = manager.remove(manifest.id, keep_config=False)
+        assert result is True
+        assert not (skills_dir / "speckit-test-ext-hello").exists()
+        assert not (skills_dir / "speckit-test-ext-world").exists()

tests/test_merge.py

@@ -0,0 +1,190 @@
+import stat
+
+from specify_cli import merge_json_files
+from specify_cli import handle_vscode_settings
+
+# --- Dimension 2: Polite Deep Merge Strategy ---
+
+def test_merge_json_files_type_mismatch_preservation(tmp_path):
+    """If user has a string but template wants a dict, PRESERVE user's string."""
+    existing_file = tmp_path / "settings.json"
+    # User might have overridden a setting with a simple string or different type
+    existing_file.write_text('{"chat.editor.fontFamily": "CustomFont"}')
+    
+    # Template might expect a dict for the same key (hypothetically)
+    new_settings = {
+        "chat.editor.fontFamily": {"font": "TemplateFont"}
+    }
+    
+    merged = merge_json_files(existing_file, new_settings)
+    # Result is None because user settings were preserved and nothing else changed
+    assert merged is None
+
+def test_merge_json_files_deep_nesting(tmp_path):
+    """Verify deep recursive merging of new keys."""
+    existing_file = tmp_path / "settings.json"
+    existing_file.write_text("""
+    {
+        "a": {
+            "b": {
+                "c": 1
+            }
+        }
+    }
+    """)
+    
+    new_settings = {
+        "a": {
+            "b": {
+                "d": 2  # New nested key
+            },
+            "e": 3      # New mid-level key
+        }
+    }
+    
+    merged = merge_json_files(existing_file, new_settings)
+    assert merged["a"]["b"]["c"] == 1
+    assert merged["a"]["b"]["d"] == 2
+    assert merged["a"]["e"] == 3
+
+def test_merge_json_files_empty_existing(tmp_path):
+    """Merging into an empty/new file."""
+    existing_file = tmp_path / "empty.json"
+    existing_file.write_text("{}")
+    
+    new_settings = {"a": 1}
+    merged = merge_json_files(existing_file, new_settings)
+    assert merged == {"a": 1}
+
+# --- Dimension 3: Real-world Simulation ---
+
+def test_merge_vscode_realistic_scenario(tmp_path):
+    """A realistic VSCode settings.json with many existing preferences, comments, and trailing commas."""
+    existing_file = tmp_path / "vscode_settings.json"
+    existing_file.write_text("""
+    {
+        "editor.fontSize": 12,
+        "editor.formatOnSave": true, /* block comment */
+        "files.exclude": {
+            "**/.git": true,
+            "**/node_modules": true,
+        },
+        "chat.promptFilesRecommendations": {
+            "existing.tool": true,
+        } // User comment
+    }
+    """)
+    
+    template_settings = {
+        "chat.promptFilesRecommendations": {
+            "speckit.specify": True,
+            "speckit.plan": True
+        },
+        "chat.tools.terminal.autoApprove": {
+            ".specify/scripts/bash/": True
+        }
+    }
+    
+    merged = merge_json_files(existing_file, template_settings)
+    
+    # Check preservation
+    assert merged["editor.fontSize"] == 12
+    assert merged["files.exclude"]["**/.git"] is True
+    assert merged["chat.promptFilesRecommendations"]["existing.tool"] is True
+    
+    # Check additions
+    assert merged["chat.promptFilesRecommendations"]["speckit.specify"] is True
+    assert merged["chat.tools.terminal.autoApprove"][".specify/scripts/bash/"] is True
+
+# --- Dimension 4: Error Handling & Robustness ---
+
+def test_merge_json_files_with_bom(tmp_path):
+    """Test files with UTF-8 BOM (sometimes created on Windows)."""
+    existing_file = tmp_path / "bom.json"
+    content = '{"a": 1}'
+    # Prepend UTF-8 BOM
+    existing_file.write_bytes(b'\xef\xbb\xbf' + content.encode('utf-8'))
+    
+    new_settings = {"b": 2}
+    merged = merge_json_files(existing_file, new_settings)
+    assert merged == {"a": 1, "b": 2}
+
+def test_merge_json_files_not_a_dictionary_template(tmp_path):
+    """If for some reason new_content is not a dict, PRESERVE existing settings by returning None."""
+    existing_file = tmp_path / "ok.json"
+    existing_file.write_text('{"a": 1}')
+    
+    # Secure fallback: return None to skip writing and avoid clobbering
+    assert merge_json_files(existing_file, ["not", "a", "dict"]) is None
+
+def test_merge_json_files_unparseable_existing(tmp_path):
+    """If the existing file is unparseable JSON, return None to avoid overwriting it."""
+    bad_file = tmp_path / "bad.json"
+    bad_file.write_text('{"a": 1, missing_value}') # Invalid JSON
+    
+    assert merge_json_files(bad_file, {"b": 2}) is None
+
+
+def test_merge_json_files_list_preservation(tmp_path):
+    """Verify that existing list values are preserved and NOT merged or overwritten."""
+    existing_file = tmp_path / "list.json"
+    existing_file.write_text('{"my.list": ["user_item"]}')
+    
+    template_settings = {
+        "my.list": ["template_item"]
+    }
+    
+    merged = merge_json_files(existing_file, template_settings)
+    # The polite merge policy says: keep existing values if they exist and aren't both dicts.
+    # Since nothing changed, it returns None.
+    assert merged is None
+
+def test_merge_json_files_no_changes(tmp_path):
+    """If the merge doesn't introduce any new keys or changes, return None to skip rewrite."""
+    existing_file = tmp_path / "no_change.json"
+    existing_file.write_text('{"a": 1, "b": {"c": 2}}')
+    
+    template_settings = {
+        "a": 1,          # Already exists
+        "b": {"c": 2}    # Already exists nested
+    }
+    
+    # Should return None because result == existing
+    assert merge_json_files(existing_file, template_settings) is None
+
+def test_merge_json_files_type_mismatch_no_op(tmp_path):
+    """If a key exists with different type and we preserve it, it might still result in no change."""
+    existing_file = tmp_path / "mismatch_no_op.json"
+    existing_file.write_text('{"a": "user_string"}')
+    
+    template_settings = {
+        "a": {"key": "template_dict"} # Mismatch, will be ignored
+    }
+    
+    # Should return None because we preserved the user's string and nothing else changed
+    assert merge_json_files(existing_file, template_settings) is None
+
+
+def test_handle_vscode_settings_preserves_mode_on_atomic_write(tmp_path):
+    """Atomic rewrite should preserve existing file mode bits."""
+    vscode_dir = tmp_path / ".vscode"
+    vscode_dir.mkdir()
+    dest_file = vscode_dir / "settings.json"
+    template_file = tmp_path / "template_settings.json"
+
+    dest_file.write_text('{"a": 1}\n', encoding="utf-8")
+    dest_file.chmod(0o640)
+    before_mode = stat.S_IMODE(dest_file.stat().st_mode)
+
+    template_file.write_text('{"b": 2}\n', encoding="utf-8")
+
+    handle_vscode_settings(
+        template_file,
+        dest_file,
+        "settings.json",
+        verbose=False,
+        tracker=None,
+    )
+
+    after_mode = stat.S_IMODE(dest_file.stat().st_mode)
+    assert after_mode == before_mode

tests/test_timestamp_branches.py

@@ -0,0 +1,414 @@
+"""
+Pytest tests for timestamp-based branch naming in create-new-feature.sh and common.sh.
+
+Converted from tests/test_timestamp_branches.sh so they are discovered by `uv run pytest`.
+"""
+
+import os
+import re
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+CREATE_FEATURE = PROJECT_ROOT / "scripts" / "bash" / "create-new-feature.sh"
+CREATE_FEATURE_PS = PROJECT_ROOT / "scripts" / "powershell" / "create-new-feature.ps1"
+COMMON_SH = PROJECT_ROOT / "scripts" / "bash" / "common.sh"
+
+
+@pytest.fixture
+def git_repo(tmp_path: Path) -> Path:
+    """Create a temp git repo with scripts and .specify dir."""
+    subprocess.run(["git", "init", "-q"], cwd=tmp_path, check=True)
+    subprocess.run(
+        ["git", "config", "user.email", "test@example.com"], cwd=tmp_path, check=True
+    )
+    subprocess.run(
+        ["git", "config", "user.name", "Test User"], cwd=tmp_path, check=True
+    )
+    subprocess.run(
+        ["git", "commit", "--allow-empty", "-m", "init", "-q"],
+        cwd=tmp_path,
+        check=True,
+    )
+    scripts_dir = tmp_path / "scripts" / "bash"
+    scripts_dir.mkdir(parents=True)
+    shutil.copy(CREATE_FEATURE, scripts_dir / "create-new-feature.sh")
+    shutil.copy(COMMON_SH, scripts_dir / "common.sh")
+    (tmp_path / ".specify" / "templates").mkdir(parents=True)
+    return tmp_path
+
+
+@pytest.fixture
+def no_git_dir(tmp_path: Path) -> Path:
+    """Create a temp directory without git, but with scripts."""
+    scripts_dir = tmp_path / "scripts" / "bash"
+    scripts_dir.mkdir(parents=True)
+    shutil.copy(CREATE_FEATURE, scripts_dir / "create-new-feature.sh")
+    shutil.copy(COMMON_SH, scripts_dir / "common.sh")
+    (tmp_path / ".specify" / "templates").mkdir(parents=True)
+    return tmp_path
+
+
+def run_script(cwd: Path, *args: str) -> subprocess.CompletedProcess:
+    """Run create-new-feature.sh with given args."""
+    cmd = ["bash", "scripts/bash/create-new-feature.sh", *args]
+    return subprocess.run(
+        cmd,
+        cwd=cwd,
+        capture_output=True,
+        text=True,
+    )
+
+
+def source_and_call(func_call: str, env: dict | None = None) -> subprocess.CompletedProcess:
+    """Source common.sh and call a function."""
+    cmd = f'source "{COMMON_SH}" && {func_call}'
+    return subprocess.run(
+        ["bash", "-c", cmd],
+        capture_output=True,
+        text=True,
+        env={**os.environ, **(env or {})},
+    )
+
+
+# ── Timestamp Branch Tests ───────────────────────────────────────────────────
+
+
+class TestTimestampBranch:
+    def test_timestamp_creates_branch(self, git_repo: Path):
+        """Test 1: --timestamp creates branch with YYYYMMDD-HHMMSS prefix."""
+        result = run_script(git_repo, "--timestamp", "--short-name", "user-auth", "Add user auth")
+        assert result.returncode == 0, result.stderr
+        branch = None
+        for line in result.stdout.splitlines():
+            if line.startswith("BRANCH_NAME:"):
+                branch = line.split(":", 1)[1].strip()
+        assert branch is not None
+        assert re.match(r"^\d{8}-\d{6}-user-auth$", branch), f"unexpected branch: {branch}"
+
+    def test_number_and_timestamp_warns(self, git_repo: Path):
+        """Test 3: --number + --timestamp warns and uses timestamp."""
+        result = run_script(git_repo, "--timestamp", "--number", "42", "--short-name", "feat", "Feature")
+        assert result.returncode == 0, result.stderr
+        assert "Warning" in result.stderr and "--number" in result.stderr
+
+    def test_json_output_keys(self, git_repo: Path):
+        """Test 4: JSON output contains expected keys."""
+        import json
+        result = run_script(git_repo, "--json", "--timestamp", "--short-name", "api", "API feature")
+        assert result.returncode == 0, result.stderr
+        data = json.loads(result.stdout)
+        for key in ("BRANCH_NAME", "SPEC_FILE", "FEATURE_NUM"):
+            assert key in data, f"missing {key} in JSON: {data}"
+        assert re.match(r"^\d{8}-\d{6}$", data["FEATURE_NUM"])
+
+    def test_long_name_truncation(self, git_repo: Path):
+        """Test 5: Long branch name is truncated to <= 244 chars."""
+        long_name = "a-" * 150 + "end"
+        result = run_script(git_repo, "--timestamp", "--short-name", long_name, "Long feature")
+        assert result.returncode == 0, result.stderr
+        branch = None
+        for line in result.stdout.splitlines():
+            if line.startswith("BRANCH_NAME:"):
+                branch = line.split(":", 1)[1].strip()
+        assert branch is not None
+        assert len(branch) <= 244
+        assert re.match(r"^\d{8}-\d{6}-", branch)
+
+
+# ── Sequential Branch Tests ──────────────────────────────────────────────────
+
+
+class TestSequentialBranch:
+    def test_sequential_default_with_existing_specs(self, git_repo: Path):
+        """Test 2: Sequential default with existing specs."""
+        (git_repo / "specs" / "001-first-feat").mkdir(parents=True)
+        (git_repo / "specs" / "002-second-feat").mkdir(parents=True)
+        result = run_script(git_repo, "--short-name", "new-feat", "New feature")
+        assert result.returncode == 0, result.stderr
+        branch = None
+        for line in result.stdout.splitlines():
+            if line.startswith("BRANCH_NAME:"):
+                branch = line.split(":", 1)[1].strip()
+        assert branch is not None
+        assert re.match(r"^\d{3}-new-feat$", branch), f"unexpected branch: {branch}"
+
+    def test_sequential_ignores_timestamp_dirs(self, git_repo: Path):
+        """Sequential numbering skips timestamp dirs when computing next number."""
+        (git_repo / "specs" / "002-first-feat").mkdir(parents=True)
+        (git_repo / "specs" / "20260319-143022-ts-feat").mkdir(parents=True)
+        result = run_script(git_repo, "--short-name", "next-feat", "Next feature")
+        assert result.returncode == 0, result.stderr
+        branch = None
+        for line in result.stdout.splitlines():
+            if line.startswith("BRANCH_NAME:"):
+                branch = line.split(":", 1)[1].strip()
+        assert branch == "003-next-feat", f"expected 003-next-feat, got: {branch}"
+
+    def test_sequential_supports_four_digit_prefixes(self, git_repo: Path):
+        """Sequential numbering should continue past 999 without truncation."""
+        (git_repo / "specs" / "999-last-3digit").mkdir(parents=True)
+        (git_repo / "specs" / "1000-first-4digit").mkdir(parents=True)
+        result = run_script(git_repo, "--short-name", "next-feat", "Next feature")
+        assert result.returncode == 0, result.stderr
+        branch = None
+        for line in result.stdout.splitlines():
+            if line.startswith("BRANCH_NAME:"):
+                branch = line.split(":", 1)[1].strip()
+        assert branch == "1001-next-feat", f"expected 1001-next-feat, got: {branch}"
+
+    def test_powershell_scanner_uses_long_tryparse_for_large_prefixes(self):
+        """PowerShell scanner should parse large prefixes without [int] casts."""
+        content = CREATE_FEATURE_PS.read_text(encoding="utf-8")
+        assert "[long]::TryParse($matches[1], [ref]$num)" in content
+        assert "$num = [int]$matches[1]" not in content
+
+
+# ── check_feature_branch Tests ───────────────────────────────────────────────
+
+
+class TestCheckFeatureBranch:
+    def test_accepts_timestamp_branch(self):
+        """Test 6: check_feature_branch accepts timestamp branch."""
+        result = source_and_call('check_feature_branch "20260319-143022-feat" "true"')
+        assert result.returncode == 0
+
+    def test_accepts_sequential_branch(self):
+        """Test 7: check_feature_branch accepts sequential branch."""
+        result = source_and_call('check_feature_branch "004-feat" "true"')
+        assert result.returncode == 0
+
+    def test_rejects_main(self):
+        """Test 8: check_feature_branch rejects main."""
+        result = source_and_call('check_feature_branch "main" "true"')
+        assert result.returncode != 0
+
+    def test_rejects_partial_timestamp(self):
+        """Test 9: check_feature_branch rejects 7-digit date."""
+        result = source_and_call('check_feature_branch "2026031-143022-feat" "true"')
+        assert result.returncode != 0
+
+
+# ── find_feature_dir_by_prefix Tests ─────────────────────────────────────────
+
+
+class TestFindFeatureDirByPrefix:
+    def test_timestamp_branch(self, tmp_path: Path):
+        """Test 10: find_feature_dir_by_prefix with timestamp branch."""
+        (tmp_path / "specs" / "20260319-143022-user-auth").mkdir(parents=True)
+        result = source_and_call(
+            f'find_feature_dir_by_prefix "{tmp_path}" "20260319-143022-user-auth"'
+        )
+        assert result.returncode == 0
+        assert result.stdout.strip() == f"{tmp_path}/specs/20260319-143022-user-auth"
+
+    def test_cross_branch_prefix(self, tmp_path: Path):
+        """Test 11: find_feature_dir_by_prefix cross-branch (different suffix, same timestamp)."""
+        (tmp_path / "specs" / "20260319-143022-original-feat").mkdir(parents=True)
+        result = source_and_call(
+            f'find_feature_dir_by_prefix "{tmp_path}" "20260319-143022-different-name"'
+        )
+        assert result.returncode == 0
+        assert result.stdout.strip() == f"{tmp_path}/specs/20260319-143022-original-feat"
+
+
+# ── get_current_branch Tests ─────────────────────────────────────────────────
+
+
+class TestGetCurrentBranch:
+    def test_env_var(self):
+        """Test 12: get_current_branch returns SPECIFY_FEATURE env var."""
+        result = source_and_call("get_current_branch", env={"SPECIFY_FEATURE": "my-custom-branch"})
+        assert result.stdout.strip() == "my-custom-branch"
+
+
+# ── No-git Tests ─────────────────────────────────────────────────────────────
+
+
+class TestNoGitTimestamp:
+    def test_no_git_timestamp(self, no_git_dir: Path):
+        """Test 13: No-git repo + timestamp creates spec dir with warning."""
+        result = run_script(no_git_dir, "--timestamp", "--short-name", "no-git-feat", "No git feature")
+        assert result.returncode == 0, result.stderr
+        spec_dirs = list((no_git_dir / "specs").iterdir()) if (no_git_dir / "specs").exists() else []
+        assert len(spec_dirs) > 0, "spec dir not created"
+        assert "git" in result.stderr.lower() or "warning" in result.stderr.lower()
+
+
+# ── E2E Flow Tests ───────────────────────────────────────────────────────────
+
+
+class TestE2EFlow:
+    def test_e2e_timestamp(self, git_repo: Path):
+        """Test 14: E2E timestamp flow — branch, dir, validation."""
+        run_script(git_repo, "--timestamp", "--short-name", "e2e-ts", "E2E timestamp test")
+        branch = subprocess.run(
+            ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+            cwd=git_repo,
+            capture_output=True,
+            text=True,
+        ).stdout.strip()
+        assert re.match(r"^\d{8}-\d{6}-e2e-ts$", branch), f"branch: {branch}"
+        assert (git_repo / "specs" / branch).is_dir()
+        val = source_and_call(f'check_feature_branch "{branch}" "true"')
+        assert val.returncode == 0
+
+    def test_e2e_sequential(self, git_repo: Path):
+        """Test 15: E2E sequential flow (regression guard)."""
+        run_script(git_repo, "--short-name", "seq-feat", "Sequential feature")
+        branch = subprocess.run(
+            ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+            cwd=git_repo,
+            capture_output=True,
+            text=True,
+        ).stdout.strip()
+        assert re.match(r"^\d{3}-seq-feat$", branch), f"branch: {branch}"
+        assert (git_repo / "specs" / branch).is_dir()
+        val = source_and_call(f'check_feature_branch "{branch}" "true"')
+        assert val.returncode == 0
+
+
+# ── Allow Existing Branch Tests ──────────────────────────────────────────────
+
+
+class TestAllowExistingBranch:
+    def test_allow_existing_switches_to_branch(self, git_repo: Path):
+        """T006: Pre-create branch, verify script switches to it."""
+        subprocess.run(
+            ["git", "checkout", "-b", "004-pre-exist"],
+            cwd=git_repo, check=True, capture_output=True,
+        )
+        subprocess.run(
+            ["git", "checkout", "-"],
+            cwd=git_repo, check=True, capture_output=True,
+        )
+        result = run_script(
+            git_repo, "--allow-existing-branch", "--short-name", "pre-exist",
+            "--number", "4", "Pre-existing feature",
+        )
+        assert result.returncode == 0, result.stderr
+        current = subprocess.run(
+            ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+            cwd=git_repo, capture_output=True, text=True,
+        ).stdout.strip()
+        assert current == "004-pre-exist", f"expected 004-pre-exist, got {current}"
+
+    def test_allow_existing_already_on_branch(self, git_repo: Path):
+        """T007: Verify success when already on the target branch."""
+        subprocess.run(
+            ["git", "checkout", "-b", "005-already-on"],
+            cwd=git_repo, check=True, capture_output=True,
+        )
+        result = run_script(
+            git_repo, "--allow-existing-branch", "--short-name", "already-on",
+            "--number", "5", "Already on branch",
+        )
+        assert result.returncode == 0, result.stderr
+
+    def test_allow_existing_creates_spec_dir(self, git_repo: Path):
+        """T008: Verify spec directory created on existing branch."""
+        subprocess.run(
+            ["git", "checkout", "-b", "006-spec-dir"],
+            cwd=git_repo, check=True, capture_output=True,
+        )
+        subprocess.run(
+            ["git", "checkout", "-"],
+            cwd=git_repo, check=True, capture_output=True,
+        )
+        result = run_script(
+            git_repo, "--allow-existing-branch", "--short-name", "spec-dir",
+            "--number", "6", "Spec dir feature",
+        )
+        assert result.returncode == 0, result.stderr
+        assert (git_repo / "specs" / "006-spec-dir").is_dir()
+        assert (git_repo / "specs" / "006-spec-dir" / "spec.md").exists()
+
+    def test_without_flag_still_errors(self, git_repo: Path):
+        """T009: Verify backwards compatibility (error without flag)."""
+        subprocess.run(
+            ["git", "checkout", "-b", "007-no-flag"],
+            cwd=git_repo, check=True, capture_output=True,
+        )
+        subprocess.run(
+            ["git", "checkout", "-"],
+            cwd=git_repo, check=True, capture_output=True,
+        )
+        result = run_script(
+            git_repo, "--short-name", "no-flag", "--number", "7", "No flag feature",
+        )
+        assert result.returncode != 0, "should fail without --allow-existing-branch"
+        assert "already exists" in result.stderr
+
+    def test_allow_existing_no_overwrite_spec(self, git_repo: Path):
+        """T010: Pre-create spec.md with content, verify it is preserved."""
+        subprocess.run(
+            ["git", "checkout", "-b", "008-no-overwrite"],
+            cwd=git_repo, check=True, capture_output=True,
+        )
+        spec_dir = git_repo / "specs" / "008-no-overwrite"
+        spec_dir.mkdir(parents=True)
+        spec_file = spec_dir / "spec.md"
+        spec_file.write_text("# My custom spec content\n")
+        subprocess.run(
+            ["git", "checkout", "-"],
+            cwd=git_repo, check=True, capture_output=True,
+        )
+        result = run_script(
+            git_repo, "--allow-existing-branch", "--short-name", "no-overwrite",
+            "--number", "8", "No overwrite feature",
+        )
+        assert result.returncode == 0, result.stderr
+        assert spec_file.read_text() == "# My custom spec content\n"
+
+    def test_allow_existing_creates_branch_if_not_exists(self, git_repo: Path):
+        """T011: Verify normal creation when branch doesn't exist."""
+        result = run_script(
+            git_repo, "--allow-existing-branch", "--short-name", "new-branch",
+            "New branch feature",
+        )
+        assert result.returncode == 0, result.stderr
+        current = subprocess.run(
+            ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+            cwd=git_repo, capture_output=True, text=True,
+        ).stdout.strip()
+        assert "new-branch" in current
+
+    def test_allow_existing_with_json(self, git_repo: Path):
+        """T012: Verify JSON output is correct."""
+        import json
+
+        subprocess.run(
+            ["git", "checkout", "-b", "009-json-test"],
+            cwd=git_repo, check=True, capture_output=True,
+        )
+        subprocess.run(
+            ["git", "checkout", "-"],
+            cwd=git_repo, check=True, capture_output=True,
+        )
+        result = run_script(
+            git_repo, "--allow-existing-branch", "--json", "--short-name", "json-test",
+            "--number", "9", "JSON test",
+        )
+        assert result.returncode == 0, result.stderr
+        data = json.loads(result.stdout)
+        assert data["BRANCH_NAME"] == "009-json-test"
+
+    def test_allow_existing_no_git(self, no_git_dir: Path):
+        """T013: Verify flag is silently ignored in non-git repos."""
+        result = run_script(
+            no_git_dir, "--allow-existing-branch", "--short-name", "no-git",
+            "No git feature",
+        )
+        assert result.returncode == 0, result.stderr
+
+
+class TestAllowExistingBranchPowerShell:
+    def test_powershell_supports_allow_existing_branch_flag(self):
+        """Static guard: PS script exposes and uses -AllowExistingBranch."""
+        contents = CREATE_FEATURE_PS.read_text(encoding="utf-8")
+        assert "-AllowExistingBranch" in contents
+        # Ensure the flag is referenced in script logic, not just declared
+        assert "AllowExistingBranch" in contents.replace("-AllowExistingBranch", "")