specky-sdd 3.7.3 → 3.9.0

package/.apm/hooks/sdd-hooks.json

@@ -5,7 +5,7 @@
       "hooks": [
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/session-banner.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-session-banner.sh",
           "timeout": 5
         }
       ]
@@ -17,7 +17,7 @@
       "hooks": [
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/pipeline-guard.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-pipeline-guard.sh",
           "timeout": 5
         }
       ]
@@ -29,7 +29,7 @@
       "hooks": [
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/branch-validator.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-branch-validator.sh",
           "timeout": 5
         }
       ]
@@ -39,12 +39,12 @@
       "hooks": [
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/artifact-validator.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-artifact-validator.sh",
           "timeout": 10
         },
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/branch-validator.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-branch-validator.sh",
           "timeout": 5
         }
       ]
@@ -54,12 +54,12 @@
       "hooks": [
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/artifact-validator.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-artifact-validator.sh",
           "timeout": 10
         },
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/branch-validator.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-branch-validator.sh",
           "timeout": 5
         }
       ]
@@ -69,12 +69,12 @@
       "hooks": [
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/artifact-validator.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-artifact-validator.sh",
           "timeout": 10
         },
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/branch-validator.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-branch-validator.sh",
           "timeout": 5
         }
       ]
@@ -84,12 +84,12 @@
       "hooks": [
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/artifact-validator.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-artifact-validator.sh",
           "timeout": 10
         },
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/branch-validator.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-branch-validator.sh",
           "timeout": 5
         }
       ]
@@ -99,12 +99,12 @@
       "hooks": [
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/artifact-validator.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-artifact-validator.sh",
           "timeout": 10
         },
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/branch-validator.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-branch-validator.sh",
           "timeout": 5
         }
       ]
@@ -114,12 +114,12 @@
       "hooks": [
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/artifact-validator.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-artifact-validator.sh",
           "timeout": 10
         },
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/branch-validator.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-branch-validator.sh",
           "timeout": 5
         }
       ]
@@ -129,12 +129,12 @@
       "hooks": [
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/artifact-validator.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-artifact-validator.sh",
           "timeout": 10
         },
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/branch-validator.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-branch-validator.sh",
           "timeout": 5
         }
       ]
@@ -144,22 +144,22 @@
       "hooks": [
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/artifact-validator.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-artifact-validator.sh",
           "timeout": 10
         },
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/branch-validator.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-branch-validator.sh",
           "timeout": 5
         },
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/security-scan.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-security-scan.sh",
           "timeout": 30
         },
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/release-gate.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-release-gate.sh",
           "timeout": 15
         }
       ]
@@ -169,7 +169,7 @@
       "hooks": [
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/branch-validator.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-branch-validator.sh",
           "timeout": 5
         }
       ]
@@ -181,12 +181,12 @@
       "hooks": [
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/phase-gate.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-phase-gate.sh",
           "timeout": 10
         },
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/auto-checkpoint.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-auto-checkpoint.sh",
           "timeout": 5
         }
       ]
@@ -196,32 +196,32 @@
       "hooks": [
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/phase-gate.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-phase-gate.sh",
           "timeout": 10
         },
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/spec-quality.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-spec-quality.sh",
           "timeout": 10
         },
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/ears-validator.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-ears-validator.sh",
           "timeout": 10
         },
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/lgtm-gate.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-lgtm-gate.sh",
           "timeout": 5
         },
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/spec-sync.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-spec-sync.sh",
           "timeout": 10
         },
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/auto-checkpoint.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-auto-checkpoint.sh",
           "timeout": 5
         }
       ]
@@ -231,22 +231,22 @@
       "hooks": [
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/phase-gate.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-phase-gate.sh",
           "timeout": 10
         },
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/spec-sync.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-spec-sync.sh",
           "timeout": 10
         },
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/lgtm-gate.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-lgtm-gate.sh",
           "timeout": 5
         },
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/auto-checkpoint.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-auto-checkpoint.sh",
           "timeout": 5
         }
       ]
@@ -256,27 +256,27 @@
       "hooks": [
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/phase-gate.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-phase-gate.sh",
           "timeout": 10
         },
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/task-tracer.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-task-tracer.sh",
           "timeout": 10
         },
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/lgtm-gate.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-lgtm-gate.sh",
           "timeout": 5
         },
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/spec-sync.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-spec-sync.sh",
           "timeout": 10
         },
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/auto-checkpoint.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-auto-checkpoint.sh",
           "timeout": 5
         }
       ]
@@ -286,7 +286,7 @@
       "hooks": [
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/auto-checkpoint.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-auto-checkpoint.sh",
           "timeout": 5
         }
       ]
@@ -296,12 +296,12 @@
       "hooks": [
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/spec-sync.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-spec-sync.sh",
           "timeout": 10
         },
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/auto-checkpoint.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-auto-checkpoint.sh",
           "timeout": 5
         }
       ]
@@ -311,12 +311,12 @@
       "hooks": [
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/phase-gate.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-phase-gate.sh",
           "timeout": 10
         },
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/drift-monitor.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-drift-monitor.sh",
           "timeout": 10
         }
       ]
@@ -326,22 +326,22 @@
       "hooks": [
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/phase-gate.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-phase-gate.sh",
           "timeout": 10
         },
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/cognitive-debt-alert.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-cognitive-debt-alert.sh",
           "timeout": 10
         },
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/metrics-dashboard.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-metrics-dashboard.sh",
           "timeout": 5
         },
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/drift-monitor.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-drift-monitor.sh",
           "timeout": 10
         }
       ]
@@ -351,12 +351,12 @@
       "hooks": [
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/spec-sync.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-spec-sync.sh",
           "timeout": 10
         },
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/auto-checkpoint.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-auto-checkpoint.sh",
           "timeout": 5
         }
       ]
@@ -368,7 +368,7 @@
       "hooks": [
         {
           "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/security-scan.sh",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/specky-security-scan.sh",
           "timeout": 30
         }
       ]

package/.apm/hooks/specky-run.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# specky-run.sh - Cursor hook adapter -> Specky hook scripts.
+set -euo pipefail
+
+SCRIPT="${1:?usage: specky-run.sh <script-name> [--blocking]}"
+BLOCKING="${2:-}"
+HOOK=".cursor/hooks/scripts/${SCRIPT}"
+INPUT=$(cat || true)
+
+if command -v jq >/dev/null 2>&1 && [ -n "$INPUT" ]; then
+  RAW=$(echo "$INPUT" | jq -r '
+    .tool_name // .toolName // .tool // .mcpTool // .mcp_tool // .name // empty
+  ' 2>/dev/null || true)
+  case "$RAW" in
+    mcp__specky__*) export SDD_TOOL_NAME="${RAW#mcp__specky__}" ;;
+    MCP:*|*mcp__specky__*) export SDD_TOOL_NAME="$(echo "$RAW" | sed -n 's/.*sdd_/sdd_/p')" ;;
+    Write|Edit|MultiEdit) export SDD_TOOL_NAME="$RAW" ;;
+  esac
+
+  PROMPT=$(echo "$INPUT" | jq -r '.prompt // .user_prompt // .text // empty' 2>/dev/null || true)
+  [ -n "$PROMPT" ] && export CLAUDE_USER_PROMPT="$PROMPT"
+fi
+
+set +e
+bash "$HOOK"
+CODE=$?
+set -e
+
+if [ "$BLOCKING" = "--blocking" ] && [ "$CODE" -eq 2 ]; then
+  echo '{"permission":"deny","user_message":"Specky quality gate blocked this action."}'
+fi
+exit "$CODE"

package/.apm/instructions/claude-instructions.instructions.md

@@ -0,0 +1,74 @@
+---
+applyTo: '**'
+---
+
+# Specky SDD
+
+This project uses Spec-Driven Development (SDD) via the Specky pipeline.
+
+## Key Rules
+
+1. **EARS notation is mandatory.** Every requirement must follow one of the 6 EARS patterns.
+2. **REQ-ID traceability is non-negotiable.** Every test, task, and design decision traces to a REQ-ID.
+3. **Model routing matters.** Use a fast model class for lightweight scaffolding (Phase 0, 9), a balanced model class for iterative delivery (Phase 1, 5-7), and a reasoning-focused model class for complex analysis and design (Phase 2-4, 8). The user chooses any available model.
+4. **Never skip hooks.** Blocking hooks (specky-security-scan, specky-release-gate) must pass before release.
+5. **Artifacts live in `.specs/NNN-feature/`.** CONSTITUTION.md, RESEARCH.md, SPECIFICATION.md, DESIGN.md, TASKS.md, VERIFICATION.md, ANALYSIS.md.
+6. **One branch per spec.** Create `spec/NNN-feature-name` from `develop` for all pipeline work (Phases 0-7). All `.specs/` artifacts are created on this branch. Merge to `develop` after verification, then `stage` for QA and release gates, then `main` for production. Never commit spec work directly to develop, stage, or main.
+7. **Load companion SKILL.md first.** Every agent reads its companion skill file (`.claude/skills/{skill-name}/SKILL.md`) as the first workflow step. Phase agents have dedicated skills (specky-sdd-init, specky-spec-engineer, specky-sdd-clarify, specky-design-architect, specky-task-planner, specky-quality-reviewer); shared pipeline context lives in specky-sdd-pipeline.
+8. **Orchestrator is the single entry point.** When `.specs/` exists with an active pipeline (`.sdd-state.json` present), ALL work — code, branches, commits, PRs — MUST flow through `@specky-orchestrator`. Direct calls to phase agents, manual branch creation outside `spec/NNN-*`, or free-form edits bypass the quality gates and are pipeline violations. If unsure where to start, invoke `@specky-onboarding`. Starting in v3.5, `specky-pipeline-guard` hook enforces this automatically.
+
+## Available Agents
+
+- @specky-onboarding — Interactive wizard and default entry point
+- @specky-orchestrator — Full pipeline coordinator (all 10 phases)
+- @specky-sdd-init — Initialize pipeline (Phase 0)
+- @specky-requirements-engineer — Produce FRD + NFRD
+- @specky-research-analyst — Technical research (Phase 1)
+- @specky-spec-engineer — Write SPECIFICATION.md with EARS (Phase 2)
+- @specky-sdd-clarify — Resolve ambiguities (Phase 3)
+- @specky-design-architect — Write DESIGN.md + diagrams (Phase 4)
+- @specky-task-planner — Write TASKS.md + CHECKLIST.md (Phase 5)
+- @specky-quality-reviewer — Completeness audit + compliance (Phase 6)
+- @specky-implementer — Implementation scaffolding (Phase 7)
+- @specky-test-verifier — Coverage verification (Phase 8)
+- @specky-release-engineer — Release preparation (Phase 9)
+
+## Available Commands
+
+Use slash commands in Claude Code (`/prompt-name`):
+
+**Quick Start:** /specky-onboarding, /specky-orchestrate, /specky-greenfield, /specky-brownfield, /specky-migration, /specky-api
+**Pipeline:** /specky-research, /specky-clarify, /specky-specify, /specky-design, /specky-tasks, /specky-implement, /specky-verify, /specky-release, /specky-deploy
+**Special:** /specky-from-figma, /specky-from-meeting, /specky-check-drift, /specky-resolve-conflict
+**Debug:** /specky-debug-hook, /specky-pipeline-status, /specky-reset-phase
+
+## Quality Gates
+
+Claude Code enforces gates natively via `.claude/settings.json` hook registration and the scripts in `.claude/hooks/scripts/`:
+
+- **Pre-tool:** specky-artifact-validator (BLOCKING) + specky-branch-validator (advisory) before every phase tool
+- **Post-tool:** specky-phase-gate (BLOCKING) + specky-lgtm-gate (advisory) + quality hooks after artifact writes
+- **LGTM gates:** Phases 2 (Specify), 4 (Design), 5 (Tasks) pause for human review
+- **Blocking gates:** specky-security-scan + specky-release-gate before PR creation
+
+## Work Modes
+
+- **Full Pipeline:** Use @specky-orchestrator or /specky-orchestrate for automated end-to-end
+- **Agent-by-agent:** Call individual agents (@specky-spec-engineer, @specky-implementer, etc.)
+- **Direct MCP tools:** Call sdd_* tools directly for maximum control
+- **Use /specky-onboarding to choose your mode**
+
+## MCP Server
+
+The specky-sdd MCP server (58 tools) is configured in .mcp.json and runs via npx.
+
+## EARS Patterns
+
+| Pattern | Format |
+|---------|--------|
+| Ubiquitous | The system shall... |
+| Event-driven | When [event], the system shall... |
+| State-driven | While [state], the system shall... |
+| Optional | Where [condition], the system shall... |
+| Unwanted | If [condition], then the system shall... |
+| Complex | While [state], when [event], the system shall... |

package/.apm/instructions/copilot-instructions.instructions.md

@@ -11,29 +11,31 @@ This project uses Spec-Driven Development (SDD) via the Specky pipeline.
 1. **EARS notation is mandatory.** Every requirement must follow one of the 6 EARS patterns.
 2. **REQ-ID traceability is non-negotiable.** Every test, task, and design decision traces to a REQ-ID.
 3. **Model routing matters.** Use a fast model class for lightweight scaffolding (Phase 0, 9), a balanced model class for iterative delivery (Phase 1, 5-7), and a reasoning-focused model class for complex analysis and design (Phase 2-4, 8). The user chooses any available model.
-4. **Never skip hooks.** Blocking hooks (security-scan, release-gate) must pass before release.
+4. **Never skip hooks.** Blocking hooks (specky-security-scan, specky-release-gate) must pass before release.
 5. **Artifacts live in `.specs/NNN-feature/`.** CONSTITUTION.md, RESEARCH.md, SPECIFICATION.md, DESIGN.md, TASKS.md, VERIFICATION.md, ANALYSIS.md.
 6. **One branch per spec.** Create `spec/NNN-feature-name` from `develop` for all pipeline work (Phases 0-7). All `.specs/` artifacts are created on this branch. Merge to `develop` after verification, then `stage` for QA and release gates, then `main` for production. Never commit spec work directly to develop, stage, or main.
+7. **Load companion SKILL.md first.** Every agent reads its companion skill file (`.github/skills/{skill-name}/SKILL.md`) as the first workflow step. Phase agents have dedicated skills (specky-sdd-init, specky-spec-engineer, specky-sdd-clarify, specky-design-architect, specky-task-planner, specky-quality-reviewer); shared pipeline context lives in specky-sdd-pipeline.
+8. **Orchestrator is the single entry point.** When `.specs/` exists with an active pipeline (`.sdd-state.json` present), ALL work — code, branches, commits, PRs — MUST flow through `@specky-orchestrator`. Direct calls to phase agents, manual branch creation outside `spec/NNN-*`, or free-form edits bypass the quality gates and are pipeline violations. If unsure where to start, invoke `@specky-onboarding`. Starting in v3.5, `specky-pipeline-guard` hook enforces this automatically.
 
 ## Available Agents
 
 - @specky-onboarding — Interactive wizard and default entry point
 - @specky-orchestrator — Full pipeline coordinator (all 10 phases)
-- @sdd-init — Initialize pipeline (Phase 0)
-- @requirements-engineer — Produce FRD + NFRD
-- @research-analyst — Technical research (Phase 1)
-- @spec-engineer — Write SPECIFICATION.md with EARS (Phase 2)
-- @sdd-clarify — Resolve ambiguities (Phase 3)
-- @design-architect — Write DESIGN.md + diagrams (Phase 4)
-- @task-planner — Write TASKS.md + CHECKLIST.md (Phase 5)
-- @quality-reviewer — Completeness audit + compliance (Phase 6)
-- @implementer — Implementation scaffolding (Phase 7)
-- @test-verifier — Coverage verification (Phase 8)
-- @release-engineer — Release preparation (Phase 9)
+- @specky-sdd-init — Initialize pipeline (Phase 0)
+- @specky-requirements-engineer — Produce FRD + NFRD
+- @specky-research-analyst — Technical research (Phase 1)
+- @specky-spec-engineer — Write SPECIFICATION.md with EARS (Phase 2)
+- @specky-sdd-clarify — Resolve ambiguities (Phase 3)
+- @specky-design-architect — Write DESIGN.md + diagrams (Phase 4)
+- @specky-task-planner — Write TASKS.md + CHECKLIST.md (Phase 5)
+- @specky-quality-reviewer — Completeness audit + compliance (Phase 6)
+- @specky-implementer — Implementation scaffolding (Phase 7)
+- @specky-test-verifier — Coverage verification (Phase 8)
+- @specky-release-engineer — Release preparation (Phase 9)
 
 ## Available Prompts
 
-Use in Copilot Chat with `@workspace /prompt-name`:
+Use slash commands in Copilot Chat (`/prompt-name`):
 
 **Quick Start:** /specky-onboarding, /specky-orchestrate, /specky-greenfield, /specky-brownfield, /specky-migration, /specky-api
 **Pipeline:** /specky-research, /specky-clarify, /specky-specify, /specky-design, /specky-tasks, /specky-implement, /specky-verify, /specky-release, /specky-deploy
@@ -43,26 +45,18 @@ Use in Copilot Chat with `@workspace /prompt-name`:
 ## Hook Enforcement
 
 Hooks fire automatically on MCP tool calls:
-- **Pre-tool:** artifact-validator (BLOCKING) + branch-validator (advisory) before every phase tool
-- **Post-tool:** phase-gate (BLOCKING) + lgtm-gate (advisory) + quality hooks after artifact writes
+- **Pre-tool:** specky-artifact-validator (BLOCKING) + specky-branch-validator (advisory) before every phase tool
+- **Post-tool:** specky-phase-gate (BLOCKING) + specky-lgtm-gate (advisory) + quality hooks after artifact writes
 - **LGTM gates:** Phases 2 (Specify), 4 (Design), 5 (Tasks) pause for human review
-- **Blocking gates:** security-scan + release-gate before PR creation
+- **Blocking gates:** specky-security-scan + specky-release-gate before PR creation
 
 ## Work Modes
 
 - **Full Pipeline:** Use @specky-orchestrator or /specky-orchestrate for automated end-to-end
-- **Agent-by-agent:** Call individual agents (@spec-engineer, @implementer, etc.)
+- **Agent-by-agent:** Call individual agents (@specky-spec-engineer, @specky-implementer, etc.)
 - **Direct MCP tools:** Call sdd_* tools directly for maximum control
 - **Use /specky-onboarding to choose your mode**
 
-## Rule #7
-
-7. **Load companion SKILL.md first.** Every agent must read its companion skill file as the first workflow step.
-
-## Rule #8
-
-8. **Orchestrator is the single entry point.** When `.specs/` exists with an active pipeline (`.sdd-state.json` present), ALL work — code, branches, commits, PRs — MUST flow through `@specky-orchestrator`. Direct calls to phase agents, manual branch creation outside `spec/NNN-*`, or free-form edits bypass the quality gates and are pipeline violations. If unsure where to start, invoke `@specky-onboarding`. The orchestrator validates branch, artifacts, phase prerequisites, and routes to the correct phase agent. Starting in v3.5, `pipeline-guard` hook enforces this automatically.
-
 ## MCP Server
 
 The specky-sdd MCP server (58 tools) is configured in .vscode/mcp.json and runs via npx.

package/.apm/instructions/cursor-instructions.instructions.md

@@ -0,0 +1,20 @@
+---
+applyTo: '**'
+---
+
+# Specky SDD - Cursor Instructions
+
+1. EARS notation is mandatory: use the 6 canonical patterns from `.agents/skills/specky-sdd-pipeline/references/ears-notation.md`.
+2. REQ-ID traceability is required on every requirement, task, design decision, and test.
+3. Pipeline artifacts live in `.specs/NNN-feature/`; Phases 0-7 run on `spec/NNN-*` branches from `develop`.
+4. Active pipeline (`.sdd-state.json`) routes through `@specky-orchestrator`; otherwise start with `@specky-onboarding`.
+5. Load the companion SKILL.md before phase work: `.agents/skills/{agent-name}/SKILL.md`.
+6. Cursor MCP is configured in `.cursor/mcp.json` with the `specky` server.
+
+## Quality Gates
+
+Cursor installs native hooks at `.cursor/hooks.json` and `.cursor/hooks/scripts/` when `dist/cursor-hooks.json` is available. Blocking gates deny unsafe artifact, phase, security, and release actions; advisory gates warn for branch, pipeline, LGTM, drift, and checkpoint workflows.
+
+If hooks are unavailable, enforce the same gates through MCP tools, agent workflows, and this rule. Do not claim non-Cursor hook or MCP locations are Cursor runtime paths.
+
+For the full phase workflow, invoke `/specky-onboarding` or read `.agents/skills/specky-sdd-pipeline/SKILL.md`.

package/.apm/prompts/specky-api.prompt.md

@@ -12,6 +12,6 @@ Design an API using the Specky SDD pipeline.
 **Versioning:** [e.g., URL path /v1/, header, none]
 
 Please:
-1. Call @requirements-engineer to produce FRD + NFRD for the API
-2. Call @sdd-init with project_type=api
+1. Call @specky-requirements-engineer to produce FRD + NFRD for the API
+2. Call @specky-sdd-init with project_type=api
 3. Proceed through discover → specify → design phases

package/.apm/prompts/specky-brownfield.prompt.md

@@ -10,7 +10,7 @@ Add the Specky SDD pipeline to this existing codebase.
 **Tech stack:** [detected or stated]
 
 Please:
-1. Call @sdd-init with project_type=brownfield
-2. Run @research-analyst to scan the codebase and detect the tech stack
+1. Call @specky-sdd-init with project_type=brownfield
+2. Run @specky-research-analyst to scan the codebase and detect the tech stack
 3. Show me what was detected and suggest next steps
 4. Create branch `spec/NNN-[feature]` from `develop` for all pipeline work

package/.apm/prompts/specky-clarify.prompt.md

@@ -5,4 +5,4 @@ argument-hint: <feature-number>
 ---
 Run the SDD clarification phase for feature [FEATURE NUMBER].
 
-@sdd-clarify — find ambiguities in SPECIFICATION.md, ask disambiguation questions, and validate all EARS patterns.
+@specky-sdd-clarify — find ambiguities in SPECIFICATION.md, ask disambiguation questions, and validate all EARS patterns.

package/.apm/prompts/specky-debug-hook.prompt.md

@@ -5,7 +5,7 @@ argument-hint: <hook name or error message>
 ---
 Debug a failing SDD hook.
 
-**Hook name:** [e.g., security-scan, release-gate, spec-sync]
+**Hook name:** [e.g., specky-security-scan, specky-release-gate, specky-spec-sync]
 **Error message:** [PASTE ERROR]
 
 Check the hook script in .specky/hooks/, verify prerequisites, and suggest a fix.

package/.apm/prompts/specky-deploy.prompt.md

@@ -5,4 +5,4 @@ argument-hint: <feature-number>
 ---
 Generate deployment artifacts for feature [FEATURE NUMBER].
 
-@implementer — generate IaC (Terraform/Bicep), Dockerfile, devcontainer, runbook, and onboarding guide from DESIGN.md and TASKS.md.
+@specky-implementer — generate IaC (Terraform/Bicep), Dockerfile, devcontainer, runbook, and onboarding guide from DESIGN.md and TASKS.md.

package/.apm/prompts/specky-design.prompt.md

@@ -5,4 +5,4 @@ argument-hint: <feature-number>
 ---
 Run the SDD design phase for feature [FEATURE NUMBER].
 
-@design-architect — produce DESIGN.md with component architecture (Mermaid C4 diagrams), API interface definitions, data models, and integration points. Call sdd_write_design then sdd_generate_all_diagrams.
+@specky-design-architect — produce DESIGN.md with component architecture (Mermaid C4 diagrams), API interface definitions, data models, and integration points. Call sdd_write_design then sdd_generate_all_diagrams.

package/.apm/prompts/specky-from-meeting.prompt.md

@@ -7,4 +7,4 @@ Import a meeting transcript into the SDD pipeline.
 
 **Transcript file:** #file:[PATH TO TRANSCRIPT]
 
-Extract requirements, decisions, and action items. Produce FRD + NFRD using @requirements-engineer.
+Extract requirements, decisions, and action items. Produce FRD + NFRD using @specky-requirements-engineer.

package/.apm/prompts/specky-greenfield.prompt.md

@@ -12,7 +12,7 @@ Start a greenfield project with the Specky SDD pipeline.
 **Compliance:** [e.g., GDPR | HIPAA | SOC 2 | none]
 
 Please:
-1. Call @requirements-engineer to extract FRD and NFRD
-2. Then @sdd-init to initialize the pipeline and create CONSTITUTION.md
+1. Call @specky-requirements-engineer to extract FRD and NFRD
+2. Then @specky-sdd-init to initialize the pipeline and create CONSTITUTION.md
 3. Show me the feature number (NNN) and the path `.specs/NNN-[feature]/`
 4. Create branch `spec/NNN-[feature]` from `develop` for all pipeline work