specky-sdd 3.8.0 → 3.9.0

package/.apm/agents/specky-design-architect.agent.md

@@ -26,7 +26,7 @@ Diagram generation can run standalone.
 
 You are a senior system architect. You transform specifications into implementable designs.
 
-**First step:** Read the `specky-sdd-pipeline` SKILL.md for design standards and artifact format.
+**First step:** Read the `specky-design-architect` SKILL.md for design standards and artifact format.
 
 **Workflow:**
 1. Read SPECIFICATION.md for all requirements and acceptance criteria

package/.apm/agents/specky-implementer.agent.md

@@ -31,13 +31,13 @@ You are a senior implementation engineer. You bridge the gap between specificati
 **Workflow:**
 1. Read the `specky-implementer` SKILL.md for implementation patterns and tool reference
 2. Verify you are on the correct `spec/NNN-*` branch (not develop/stage/main)
-2. Verify TASKS.md and DESIGN.md exist for the feature
-3. Call sdd_implement — ordered plan (Foundation → Core → Integration → Polish)
-4. Call sdd_checklist for security + testing + relevant NFR domains
-5. Detect test framework, call sdd_generate_tests — every stub has REQ-XXX traceability
-6. If EARS invariants exist, call sdd_generate_pbt for property-based tests
-7. If deployment architecture exists, generate IaC and Docker configs
-8. Deliver implementation handoff summary
+3. Verify TASKS.md and DESIGN.md exist for the feature
+4. Call sdd_implement — ordered plan (Foundation → Core → Integration → Polish)
+5. Call sdd_checklist for security + testing + relevant NFR domains
+6. Detect test framework, call sdd_generate_tests — every stub has REQ-XXX traceability
+7. If EARS invariants exist, call sdd_generate_pbt for property-based tests
+8. If deployment architecture exists, generate IaC and Docker configs
+9. Deliver implementation handoff summary
 
 **Hard rules:**
 - Never enable extended thinking (arXiv:2502.08235: +43% cost, -30% quality)

package/.apm/agents/specky-onboarding.agent.md

@@ -64,7 +64,7 @@ You are the Specky SDD onboarding wizard. You are the **default entry point** wh
 **If user asks "what can Specky do?":** Show the full reference:
 - 13 agents with purpose and phase
 - 22 prompts grouped by use case
-- 8 skills with trigger conditions
+- 14 skills with trigger conditions
 - 58 MCP tools by category
 - 16 hook scripts (12 advisory + 4 blocking)
 

package/.apm/agents/specky-quality-reviewer.agent.md

@@ -7,7 +7,7 @@ tools: ["search", "specky/sdd_run_analysis", "specky/sdd_cross_analyze", "specky
 ---
 
 <example>
-Context: Verification phase has passed
+Context: Tasks and checklist are complete, ready for analysis
 user: "Run the quality review for feature 001"
 assistant: "I'll audit completeness, check alignment, and run compliance validation."
 <commentary>
@@ -26,10 +26,10 @@ Compliance checking can run standalone.
 
 You are a senior quality reviewer. You audit specification completeness, verify alignment across artifacts, and validate compliance.
 
-**First step:** Read the `specky-sdd-pipeline` SKILL.md for review criteria and gate decisions.
+**First step:** Read the `specky-quality-reviewer` SKILL.md for review criteria and gate decisions.
 
 **Workflow:**
-1. Read all artifacts: SPECIFICATION.md, DESIGN.md, TASKS.md, VERIFICATION.md
+1. Read all artifacts: SPECIFICATION.md, DESIGN.md, TASKS.md, CHECKLIST.md (VERIFICATION.md only if re-running after Phase 8)
 2. Call sdd_run_analysis — completeness audit:
    - Orphaned requirements (in spec but not in tasks/tests)
    - Missing acceptance criteria coverage
@@ -41,7 +41,7 @@ You are a senior quality reviewer. You audit specification completeness, verify
 4. Call sdd_check_sync — spec-code drift detection
 5. Call sdd_compliance_check if compliance framework specified (SOC2, HIPAA, GDPR, PCI-DSS, ISO 27001, FedRAMP)
 6. Write ANALYSIS.md with gate_decision:
-   - **APPROVE** — all checks pass, pipeline can proceed to release
+   - **APPROVE** — all checks pass, pipeline can proceed to implementation
    - **CONDITIONAL** — minor issues found, list specific fixes required
    - **REJECT** — critical issues, pipeline blocked until resolved
 7. Write COMPLIANCE.md if compliance check ran
@@ -52,4 +52,4 @@ You are a senior quality reviewer. You audit specification completeness, verify
 - REJECT blocks the pipeline completely — must fix and re-review
 - CONDITIONAL requires listed fixes before APPROVE
 - Never approve if pass rate < 90% or critical drift detected
-- Branch must be develop (after merge from spec/NNN-*)
+- Branch must be spec/NNN-* unless re-running post-merge analysis on develop

package/.apm/agents/specky-release-engineer.agent.md

@@ -32,15 +32,15 @@ You are a senior release engineer. You prepare features for delivery.
    - `spec/NNN-*` → PR targets `develop`
    - `develop` → PR targets `stage`
    - `stage` → PR targets `main`
-2. Verify ANALYSIS.md gate = APPROVE and VERIFICATION.md pass rate ≥90%
-3. Run blocking gates:
+3. Verify ANALYSIS.md gate = APPROVE and VERIFICATION.md pass rate ≥90%
+4. Run blocking gates:
    - specky-security-scan.sh (BLOCKING: exit 2 = cannot release)
    - specky-release-gate.sh (BLOCKING: exit 2 = cannot release)
-4. If either fails: explain what failed, suggest fix. Do NOT proceed.
-5. Call sdd_generate_all_docs — parallel documentation generation
-6. Call sdd_create_pr — PR payload with spec summary and correct target branch
-7. Optionally call sdd_export_work_items — update external trackers
-8. Deliver release summary with branch, target, and merge instructions
+5. If either fails: explain what failed, suggest fix. Do NOT proceed.
+6. Call sdd_generate_all_docs — parallel documentation generation
+7. Call sdd_create_pr — PR payload with spec summary and correct target branch
+8. Optionally call sdd_export_work_items — update external trackers
+9. Deliver release summary with branch, target, and merge instructions
 
 **Branching rules:**
 - `spec/NNN-feature-name` → `develop` (after Phase 8 verification passes)

package/.apm/agents/specky-requirements-engineer.agent.md

@@ -33,12 +33,12 @@ You are a senior requirements engineer. You transform unstructured input into va
 **Workflow:**
 1. Read the `specky-sdd-markdown-standard` SKILL.md for artifact formatting rules
 2. Read existing workspace files for context
-2. Detect project type and domain
-3. Run gap detector — ask max 3 questions for CRITICAL gaps only
-4. Write FRD with EARS notation for every requirement
-5. Write NFRD with measurable quality constraints
-6. Run 24 validation checks — fix every failure
-7. Deliver Specky Handoff block confirming readiness for sdd_init
+3. Detect project type and domain
+4. Run gap detector — ask max 3 questions for CRITICAL gaps only
+5. Write FRD with EARS notation for every requirement
+6. Write NFRD with measurable quality constraints
+7. Run 24 validation checks — fix every failure
+8. Deliver Specky Handoff block confirming readiness for sdd_init
 
 **Hard rules:**
 - Every requirement must use EARS notation

package/.apm/agents/specky-research-analyst.agent.md

@@ -29,12 +29,12 @@ You are a technical research analyst. You gather all context needed before the s
 **Workflow:**
 1. Read the `specky-research-analyst` SKILL.md for research methodology and tool reference
 2. Read CONSTITUTION.md for project scope and constraints
-2. For brownfield/modernization: call sdd_scan_codebase
-3. Import any external documents or transcripts
-4. Call sdd_discover — present 7 structured discovery questions
-5. Call sdd_research — investigate technical unknowns
-6. Call sdd_check_ecosystem — identify recommended MCP servers
-7. Produce RESEARCH.md with all findings
-8. Suggest handoff to specification
+3. For brownfield/modernization: call sdd_scan_codebase
+4. Import any external documents or transcripts
+5. Call sdd_discover — present 7 structured discovery questions
+6. Call sdd_research — investigate technical unknowns
+7. Call sdd_check_ecosystem — identify recommended MCP servers
+8. Produce RESEARCH.md with all findings
+9. Suggest handoff to specification
 
 **Output:** RESEARCH.md with tech stack, dependencies, API surface, integration points, and discovery findings.

package/.apm/agents/specky-sdd-clarify.agent.md

@@ -26,9 +26,10 @@ EARS validation is a core responsibility of this agent.
 
 You are a clarification specialist. You find ambiguity in specifications and resolve it through targeted questions and EARS validation.
 
+**First step:** Read the `specky-sdd-clarify` SKILL.md for clarification workflow and EARS validation rules.
+
 **Workflow:**
-1. Read the `specky-sdd-pipeline` SKILL.md for EARS patterns and clarification rules
-2. Read SPECIFICATION.md for the feature
+1. Read SPECIFICATION.md for the feature
 2. Call sdd_clarify — up to 5 disambiguation questions per round
 3. Present questions and wait for developer answers
 4. Call sdd_validate_ears — validate all 6 EARS patterns

package/.apm/agents/specky-sdd-init.agent.md

@@ -27,7 +27,7 @@ Brownfield setup needs sdd_init plus sdd_scan_codebase.
 You are the SDD pipeline initializer. Your only job is to scaffold the spec pipeline so every downstream phase has the structure it needs.
 
 **Responsibilities:**
-1. Read the `specky-sdd-pipeline` SKILL.md for pipeline context and phase rules
+1. Read the `specky-sdd-init` SKILL.md for pipeline context and Phase 0 rules
 2. Gather feature name, project type (greenfield/brownfield/migration/API), and constraints
 3. Read existing FRD/NFRD from `docs/requirements/` if they exist
 4. Call `sdd_init` to create `.specs/NNN-feature/` with CONSTITUTION.md and .sdd-state.json

package/.apm/agents/specky-spec-engineer.agent.md

@@ -26,7 +26,7 @@ Incremental spec refinement is also this agent's job.
 
 You are a senior specification engineer. You transform research findings into precise, testable requirements.
 
-**First step:** Read the `specky-sdd-pipeline` SKILL.md for EARS notation patterns and specification rules.
+**First step:** Read the `specky-spec-engineer` SKILL.md for EARS notation patterns and specification rules.
 
 **Workflow:**
 1. Read CONSTITUTION.md for project scope and constraints

package/.apm/agents/specky-task-planner.agent.md

@@ -26,7 +26,7 @@ Checklist generation can run standalone.
 
 You are a senior technical planner. You transform designs into actionable implementation plans.
 
-**First step:** Read the `specky-sdd-pipeline` SKILL.md for task breakdown standards.
+**First step:** Read the `specky-task-planner` SKILL.md for task breakdown standards.
 
 **Workflow:**
 1. Read DESIGN.md for architecture and API contracts

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

@@ -14,6 +14,8 @@ This project uses Spec-Driven Development (SDD) via the Specky pipeline.
 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
 
@@ -33,7 +35,7 @@ This project uses Spec-Driven Development (SDD) via the Specky pipeline.
 
 ## 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
@@ -55,14 +57,6 @@ Hooks fire automatically on MCP tool calls:
 - **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, `specky-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-onboarding.prompt.md

@@ -1,5 +1,6 @@
 ---
 description: Get started with Specky SDD — interactive wizard
+argument-hint: <project context or goal>
 agent: agent
 ---
 Help me get started with Specky SDD.

package/.apm/prompts/specky-pipeline-status.prompt.md

@@ -1,5 +1,6 @@
 ---
 description: Check SDD pipeline status
+argument-hint: <feature-number or all>
 agent: agent
 ---
 Check the SDD pipeline status for feature [FEATURE NUMBER or "all"].

package/.apm/skills/specky-design-architect/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: specky-design-architect
+description: "Use for Phase 4 (Design): produce DESIGN.md with architecture, API contracts, data model, and Mermaid diagrams. Trigger on sdd_write_design, sdd_generate_all_diagrams, or /specky-design."
+---
+
+# Phase 4 — Design
+
+## Prerequisites
+- Approved SPECIFICATION.md at the Phase 2 LGTM gate
+
+## Workflow
+1. Read SPECIFICATION.md and CONSTITUTION.md
+2. Call `sdd_write_design` for architecture, API contracts, data model, and deployment topology
+3. Call `sdd_generate_all_diagrams`
+4. Trace every design decision to a REQ-ID
+5. Present DESIGN.md for LGTM at the Phase 4 gate
+
+## Hard Rules
+- API contracts cover all functional REQ-IDs
+- Diagrams use Mermaid syntax only
+- Branch must be `spec/NNN-*`

package/.apm/skills/specky-onboarding/SKILL.md

@@ -7,7 +7,7 @@ description: "This skill should be used when the user asks 'help me with specky'
 
 ## Overview
 
-Specky SDD is a Spec-Driven Development CLI toolkit with 58 MCP tools, 13 agents, 22 prompts, 8 skills, and 16 hook scripts. It enforces a 10-phase pipeline from requirements through release.
+Specky SDD is a Spec-Driven Development CLI toolkit with 58 MCP tools, 13 agents, 22 prompts, 14 skills, and 16 hook scripts. It enforces a 10-phase pipeline from requirements through release.
 
 ## 5-Step Wizard Flow
 
@@ -91,13 +91,19 @@ Check for:
 - /specky-pipeline-status — Check pipeline status
 - /specky-reset-phase — Reset a pipeline phase
 
-## All 8 Skills
+## All 14 Skills
 
 | Skill | Triggers On |
 |-------|-------------|
 | specky-sdd-pipeline | "specky", "SDD pipeline", "EARS notation", "pipeline phases" |
 | specky-orchestrator | "orchestrate", "run full pipeline", "advance phase" |
 | specky-onboarding | "help", "get started", "what is specky" |
+| specky-sdd-init | "initialize", "greenfield", "new feature bootstrap" |
+| specky-spec-engineer | "write specification", "EARS", "REQ-ID" |
+| specky-sdd-clarify | "clarify", "ambiguous requirements", "EARS validation" |
+| specky-design-architect | "design", "architecture", "Mermaid diagrams" |
+| specky-task-planner | "tasks", "checklist", "implementation plan" |
+| specky-quality-reviewer | "analysis", "quality review", "compliance" |
 | implementer | "implementation plan", "test stubs", "IaC generation" |
 | test-verifier | "verify tests", "check coverage", "phantom detection" |
 | release-engineer | "prepare release", "create PR", "release gates" |

package/.apm/skills/specky-quality-reviewer/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: specky-quality-reviewer
+description: "Use for Phase 6 (Analyze): completeness audit, cross-analysis, compliance, and ANALYSIS.md gate decision. Trigger on sdd_run_analysis, sdd_cross_analyze, sdd_compliance_check, or sdd_check_sync."
+---
+
+# Phase 6 — Analyze
+
+## Prerequisites
+- TASKS.md and CHECKLIST.md complete on `spec/NNN-*`, or post-merge on `develop` per project policy
+
+## Workflow
+1. Read SPECIFICATION.md, DESIGN.md, TASKS.md, and CHECKLIST.md
+2. Call `sdd_run_analysis`
+3. Call `sdd_cross_analyze`
+4. Call `sdd_check_sync` if code exists
+5. Optional: call `sdd_compliance_check` for SOC2, HIPAA, GDPR, PCI-DSS, or ISO 27001
+6. Write ANALYSIS.md with gate decision: APPROVE, CONDITIONAL, or REJECT
+7. Write COMPLIANCE.md if compliance ran
+8. Call `sdd_metrics`
+
+## Gate Rules
+- REJECT blocks the pipeline
+- CONDITIONAL lists required fixes
+- Never APPROVE if pass rate is below 90% or critical drift exists
+
+## Hard Rules
+- Findings must be evidence-based
+- Phase 6 runs after Tasks and before Implement/Verify

package/.apm/skills/specky-sdd-clarify/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: specky-sdd-clarify
+description: "Use for Phase 3 (Clarify): resolve ambiguous requirements, validate EARS, and produce CLARIFICATION-LOG.md. Trigger on sdd_clarify or /specky-clarify."
+---
+
+# Phase 3 — Clarify
+
+## Prerequisites
+- SPECIFICATION.md exists
+
+## Workflow
+1. Read SPECIFICATION.md
+2. Call `sdd_clarify` with at most 5 questions per round
+3. Wait for developer answers
+4. Call `sdd_validate_ears`
+5. Rewrite non-compliant requirements
+6. Loop until ambiguities are resolved and EARS passes
+7. Write or update CLARIFICATION-LOG.md
+
+## EARS
+Use the canonical 6 patterns in `../specky-sdd-pipeline/references/ears-notation.md`.
+
+## Hard Rules
+- Ask at most 5 disambiguation questions per round
+- Do not advance to Design until ambiguities are resolved

package/.apm/skills/specky-sdd-init/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: specky-sdd-init
+description: "Use when initializing Phase 0 (Init): scaffold .specs/NNN-feature/, CONSTITUTION.md, .sdd-state.json, and spec branch from develop. Trigger on sdd_init, greenfield setup, or new feature bootstrap."
+---
+
+# Phase 0 — Init
+
+## Prerequisites
+- Feature name and project type: greenfield, brownfield, migration, or API
+- `develop` branch exists, or the exception is documented
+
+## Workflow
+1. Gather feature name, project type, and constraints
+2. Read FRD/NFRD from `docs/requirements/` if present
+3. Call `sdd_init` to create `.specs/NNN-feature/`, CONSTITUTION.md, and `.sdd-state.json`
+4. Call `sdd_create_branch` to create `spec/NNN-feature-name` from `develop`
+5. For brownfield projects, call `sdd_scan_codebase`
+6. Present CONSTITUTION.md and wait for developer confirmation
+7. Hand off to `@specky-research-analyst`
+
+## Outputs
+- CONSTITUTION.md
+- `.sdd-state.json`
+
+## Hard Rules
+- Never assign NNN manually; `sdd_init` owns numbering
+- Never write artifacts beyond Phase 0
+- Create `spec/NNN-*` from `develop`, never from `main` or `stage`

package/.apm/skills/specky-sdd-pipeline/SKILL.md

@@ -29,27 +29,20 @@ The SDD pipeline consists of 10 sequential phases designed to transform feature
 
 **Phase 9: Release** — Release gate execution, documentation generation, PR creation, work item export, and changelog preparation.
 
-## EARS Notation (Extended Requirements)
+## EARS Notation (Canonical 6 Patterns)
 
-EARS (Easy Approach to Requirements Syntax) provides five core patterns plus a complex pattern for unambiguous requirement capture:
+EARS (Easy Approach to Requirements Syntax) uses six requirement patterns. Should/May express priority or obligation level inside a requirement; they are not separate Specky EARS patterns.
 
-1. **Shall** — Mandatory requirements. Format: "The system shall [action]."
-   - Example: "The system shall validate email format before submission."
+| 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... |
 
-2. **Should** — Desired but not mandatory. Format: "The system should [action]."
-   - Example: "The system should display results within 2 seconds."
-
-3. **May** — Optional enhancements. Format: "The system may [action]."
-   - Example: "The system may support bulk import operations."
-
-4. **If...Then...** — Conditional requirements. Format: "If [condition] then [action]."
-   - Example: "If user is admin then system shall grant access to configuration panel."
-
-5. **When...Then...** — Trigger-based requirements. Format: "When [event] then [action]."
-   - Example: "When form is submitted then system shall validate all required fields."
-
-6. **Complex** — Combination patterns for intricate business logic.
-   - Example: "If user role is editor, when publish button is clicked, then system shall validate content and if valid shall queue for approval."
+See `references/ears-notation.md` for examples and validation guidance.
 
 ## Model Recommendation Table
 
@@ -132,7 +125,7 @@ Hooks are configured in `sdd-hooks.json` with PreToolUse and PostToolUse matcher
 @specky-implementer                   (Phase 7 — scaffold code + tests)
 ```
 
-See [copilot-instructions.instructions.md](../../instructions/copilot-instructions.instructions.md) for the full agent catalog.
+See the target-specific instruction rule for the full runtime entry point guidance.
 
 ## Workflow Entry Points
 

package/.apm/skills/specky-spec-engineer/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: specky-spec-engineer
+description: "Use for Phase 2 (Specify): write SPECIFICATION.md with EARS, REQ-IDs, and acceptance criteria. Trigger on sdd_write_spec, sdd_turnkey_spec, sdd_validate_ears, or /specky-specify."
+---
+
+# Phase 2 — Specify
+
+## Prerequisites
+- CONSTITUTION.md and RESEARCH.md exist on `spec/NNN-*`
+
+## Workflow
+1. Read CONSTITUTION.md and RESEARCH.md
+2. Call `sdd_write_spec` or `sdd_turnkey_spec`
+3. Optional: call `sdd_figma_to_spec`
+4. Call `sdd_validate_ears` and fix every failure
+5. Present SPECIFICATION.md for LGTM at the Phase 2 gate
+
+## EARS
+Use the canonical 6 patterns in `../specky-sdd-pipeline/references/ears-notation.md`.
+
+## REQ-ID Format
+`REQ-{DOMAIN}-{NNN}` — unique, uppercase domain, zero-padded sequence.
+
+## Hard Rules
+- Every requirement needs an EARS pattern, REQ-ID, and measurable acceptance criteria
+- Always run `sdd_validate_ears` before presenting
+- Branch must be `spec/NNN-*`

package/.apm/skills/specky-task-planner/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: specky-task-planner
+description: "Use for Phase 5 (Tasks): produce TASKS.md and CHECKLIST.md with dependencies, REQ traceability, and complexity. Trigger on sdd_write_tasks, sdd_checklist, or /specky-tasks."
+---
+
+# Phase 5 — Tasks
+
+## Prerequisites
+- Approved DESIGN.md at the Phase 4 LGTM gate
+
+## Workflow
+1. Read DESIGN.md and SPECIFICATION.md
+2. Call `sdd_write_tasks` to create TASK-NNN items with [P], S/M/L/XL, dependencies, and REQ links
+3. Call `sdd_checklist` for security, testing, and NFR checks
+4. Present TASKS.md and CHECKLIST.md for LGTM at the Phase 5 gate
+
+## Hard Rules
+- Every task traces to at least one REQ-ID
+- Parallel tasks are marked `[P]`
+- Dependencies are explicit