specky-sdd 3.10.2 → 3.11.1

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

@@ -6,11 +6,14 @@ argument-hint: <feature to add>
 Add the Specky SDD pipeline to this existing codebase.
 
 **Feature:** [FEATURE NAME]
+**Feature number:** [NNN — explicit, three digits]
+**Workload:** [api | web-application | service | cli | library | infrastructure]
+**Execution mode:** [full | rapid | emergency]
 **What to modernize:** [Component, module, or area to target]
-**Tech stack:** [detected or stated]
+**Capabilities and parameters:** [explicit]
 
 Please:
-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
+1. Run `sdd_scan_codebase` with explicit depth and exclusion patterns
+2. Call @specky-sdd-init with lifecycle `brownfield`, selected workload/mode, explicit number, and exact capability configuration
+3. Pass the codebase summary into brownfield discovery and capture compatibility/rollback evidence
+4. Do not create a branch unless the persisted release policy enables it in the current phase

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

@@ -6,13 +6,15 @@ argument-hint: <project idea>
 Start a greenfield project with the Specky SDD pipeline.
 
 **Project:** [PROJECT NAME]
+**Feature number:** [NNN — explicit, three digits]
+**Workload:** [api | web-application | service | cli | library | infrastructure]
+**Execution mode:** [full | rapid | emergency]
 **Description:** [What the system will do in 1-2 sentences]
-**Stack:** [e.g., Node.js + PostgreSQL + React | Python + FastAPI | undecided]
-**Timeline:** [e.g., MVP in 8 weeks | no deadline]
-**Compliance:** [e.g., GDPR | HIPAA | SOC 2 | none]
+**Capabilities:** [explicit list, or none]
+**Capability parameters:** [complete configuration for every enabled capability]
 
 Please:
 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
+3. Initialize exactly the selected feature and show its contract fingerprint and signed state path
+4. Do not create a branch unless release capability is enabled and the feature reaches an allowed branch phase

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

@@ -5,4 +5,4 @@ argument-hint: <feature-number>
 ---
 Run the SDD implementation phase for feature [FEATURE NUMBER].
 
-@specky-implementer — generate implementation plan, quality checklists, test stubs with REQ-* traceability, and infrastructure scaffolding.
+@specky-implementer — follow the persisted capability contract to generate an implementation plan, executable requirement-bound tests/properties, and only the explicitly configured IaC/development artifacts.

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

@@ -5,4 +5,4 @@ argument-hint: <feature description or number>
 ---
 Run the full SDD pipeline for feature [FEATURE NUMBER or NAME].
 
-@specky-orchestrator — coordinate all 10 phases (Init → Discover → Specify → Clarify → Design → Tasks → Analyze → Implement → Verify → Release), validate artifacts between phases, enforce LGTM gates at Phases 2/4/5, and route to the correct agent per phase.
+@specky-orchestrator — resolve the selected feature's signed phase graph, validate contract-specific evidence, enforce configured LGTM/gate policy, and route the current phase to its lean agent.

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

@@ -3,19 +3,42 @@ 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-*`
+# Design — Complete Evidence Contract
+
+## Preconditions
+
+Read the signed feature contract, Constitution, and Specification. The selected workload controls `workload_design` and `required_diagrams`.
+
+## Common Required Fields
+
+`sdd_write_design` requires all of the following; no section is inferred:
+
+- `architecture_overview`, `system_context`, `container_architecture`
+- `component_design`, `code_level_design`
+- `data_models`, `infrastructure`, `security_architecture`
+- `error_handling`, `cross_cutting`
+- at least one `mermaid_diagrams` entry and one ADR
+- `workload_design` whose `type` exactly matches persisted workload
+- `api_contracts`: required and non-empty for API; explicit empty array for non-API workloads with no network API
+- explicit `spec_dir`, `feature_number`, and `force`
+
+## Workload Payloads
+
+| Workload | Required fields |
+|---|---|
+| API | versioning strategy, error model, authentication, rate limits |
+| Web application | user journeys, UI states, accessibility, responsive behavior, API integration |
+| Service | protocols, dependencies, failure modes, operability, observability |
+| CLI | command grammar, arguments, exit codes, standard streams, shell compatibility |
+| Library | public API, compatibility, versioning, error surface, consumer examples |
+| Infrastructure | topology, provider, state management, identity, network security |
+
+Every design must contain real REQ-ID references. Missing Specification IDs or incomplete architecture evidence blocks writing.
+
+## Diagrams
+
+Use `required_diagrams` from signed state. For each required type, provide Mermaid code and source `evidence_refs`. `sdd_generate_all_diagrams` requires the exact set: no missing, extra, or duplicate types. Sources are contract-defined; the tool does not infer nodes from headings.
+
+## Review
+
+Present DESIGN.md, ADR decisions, API contracts when applicable, and every grounded diagram. Do not present placeholders, skeletons, or generic C4 content.

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

@@ -1,171 +1,59 @@
 ---
 name: specky-implementer
-description: "This skill should be used when the user asks to 'generate implementation plan', 'create test stubs', 'set up infrastructure', 'generate quality checklists', 'transition from spec to code', or needs guidance on Phase 7 implementation scaffolding. Also trigger on 'sdd implement', 'implementation handoff', 'IaC generation', or 'test framework selection'."
+description: "Use for contracted implementation planning, executable TDD bindings, IaC, Docker, devcontainer, local environment, or Codespaces tools after an APPROVE analysis gate."
 ---
 
-# Implementation Orchestrator (Phase 7)
+# Implement — Persisted Capability Execution
 
-## Overview
-
-Phase 7 transforms specification and design artifacts into a structured implementation plan with code scaffolding, infrastructure definitions, and quality assurance frameworks.
-
-## Prerequisites Check
-
-Before starting implementation, verify:
-- You are on the correct `spec/NNN-*` branch (not develop, stage, or main)
-- SPECIFICATION.md is complete with EARS notation requirements
-- DESIGN.md includes architecture, API contracts, and data schema
-- TASKS.md has work breakdown structure with dependencies
-- All stakeholders have approved DESIGN.md
-- Technical team has reviewed and confirmed feasibility
-- Infrastructure resources are allocated and accessible
+## Preconditions
 
-Run `/specky:check-phase-5` to validate prerequisites.
+Read signed feature state, DESIGN.md, TASKS.md, and ANALYSIS.md. Implementation-sensitive tools require gate `APPROVE`. Every call includes explicit `spec_dir` and `feature_number`.
 
-## Implementation Plan Generation
+## Implementation Plan
 
-Generate a phased implementation plan with four distinct stages:
+Call `sdd_implement` with:
 
-### Foundation Stage
-Set up project skeleton, CI/CD pipelines, database migrations, and authentication framework. Duration typically 15-20% of total effort. Outputs:
-- Empty project structure matching DESIGN.md architecture
-- Docker/container definitions for local and production
-- Database migration system initialized
-- GitHub Actions/CI configuration from DESIGN.md
+- `task_ids`: explicit IDs; `[]` intentionally selects every task
+- `checkpoint`: explicit boolean
 
-### Core Stage
-Implement core business logic per TASKS.md sequencing. Focus on entities, APIs, and critical paths. Duration 40-50% of effort. Outputs:
-- Data models and ORM definitions
-- REST/GraphQL APIs matching DESIGN.md contracts
-- Business logic implementation
-- Unit test stubs for all modules
+The tool orders existing tasks. It does not implement application code.
 
-### Integration Stage
-Connect subsystems, external APIs, and third-party services. Duration 20-25% of effort. Outputs:
-- Third-party integrations (payment, auth, analytics)
-- Message queue/event system setup
-- Cross-module integration tests
-- API gateway configuration
-
-### Polish Stage
-Performance optimization, error handling, logging, and observability. Duration 10-15% of effort. Outputs:
-- Caching strategy implementation
-- Comprehensive error handling
-- Structured logging framework
-- Monitoring and alerting setup
+## Executable TDD
 
-## Quality Checklist Generation
+Use only when `tdd` capability is enabled. Frameworks, output directory, threshold, trace marker, imports, example-test bindings, and property bindings are persisted in `capability_config.tdd`.
 
-Generate domain-specific quality checklists from SPECIFICATION.md:
-
-**Security Domain:**
-- OWASP Top 10 items applicable to architecture
-- Data encryption requirements (in-transit, at-rest)
-- Authentication and authorization mechanisms
-- Input validation and sanitization rules
-- Audit logging and compliance tracking
-
-**Testing Domain:**
-- Unit test coverage targets (default 80% minimum)
-- Integration test scenarios per SPECIFICATION.md
-- End-to-end test paths for critical user flows
-- Performance benchmarks from DESIGN.md NFRs
-- Security test cases (SQL injection, XSS, CSRF)
-
-**Conditional NFRs:**
-If SPECIFICATION.md includes scalability requirements:
-- Load testing strategy with target RPS
-- Database query optimization checklist
-- Caching strategy validation
-- Horizontal scaling test scenarios
-
-If high availability required:
-- Failover test procedures
-- Data consistency verification
-- Recovery time objectives (RTO) validation
-- Backup and restore procedures
-
-## Test Framework Auto-Detection
-
-Analyze technology stack from DESIGN.md and recommend test frameworks:
-
-**Python projects** → pytest + pytest-cov
-**Node.js projects** → Jest + Vitest for unit, Playwright for E2E
-**Go projects** → testing package + testify
-**Java projects** → JUnit 5 + Mockito + TestContainers
-**C#/.NET projects** → xUnit + Moq + SpecFlow
-**Rust projects** → built-in testing + proptest
-
-Generate starter test configuration files and example test templates.
-
-## Infrastructure Decision Tree
-
-From DESIGN.md deployment topology, auto-generate infrastructure choices:
-
-1. **Container Runtime** — Docker recommended; Podman alternative
-2. **Orchestration** — Kubernetes if multi-replica; Docker Compose if single-node dev
-3. **Database** — SQL (PostgreSQL) vs NoSQL per DESIGN.md data schema
-4. **Caching Layer** — Redis for session/cache, memcached alternative
-5. **Message Queue** — RabbitMQ/Kafka per event volume in SPECIFICATION.md
-6. **Monitoring** — Prometheus + Grafana stack
-7. **Log Aggregation** — ELK (Elasticsearch) or Loki
-
-Generate Terraform/CloudFormation/Helm templates matching selections.
-
-## Spec-Sync During Implementation
-
-Continuous synchronization between SPECIFICATION.md and implementation:
-
-- When code deviates from SPECIFICATION.md, flag as spec drift
-- When implementation discovers missing requirement, update SPECIFICATION.md
-- If design changes needed mid-implementation, update DESIGN.md and notify stakeholders
-- Daily specky-spec-sync report comparing implemented features to SPECIFICATION.md
-
-## Implementation Handoff Template
-
-When Phase 7 completes, provide handoff document including:
-
-```
-## Implementation Status
-- Artifacts generated: [list]
-- Scaffolding complete: [yes/no]
-- Quality checklist items: [count]
-- Framework selections validated: [yes/no]
-- Infrastructure templates generated: [yes/no]
-
-## Next Phase Entry Criteria
-All Phase 7 outputs ready for Phase 8 (Verify):
-- Code compiles without errors
-- All test stubs created
-- CI/CD pipeline functional
-- Infrastructure definitions validated
-
-## Known Gaps
-- [List of incomplete items, if any]
-- Estimated effort to complete: [hours]
-
-## Recommendations
-- [Technical notes for implementation team]
-```
-
-Reference: **arXiv:2502.08235** — Use standard inference (no extended thinking) for Phase 7 scaffolding to optimize quality-cost tradeoff. Extended thinking adds 43% cost with 30% quality reduction in code generation.
-
-## MCP Tools
-
-| Tool | Purpose |
-|------|---------|
-| `sdd_implement` | Generate ordered implementation plan (Foundation → Core → Integration → Polish) |
-| `sdd_checklist` | Generate domain-specific quality checklists (security, testing, NFRs) |
-| `sdd_generate_tests` | Generate test stubs with REQ-ID traceability (vitest, jest, pytest, junit, xunit, playwright) |
-| `sdd_generate_pbt` | Generate property-based tests from EARS invariants |
-| `sdd_generate_iac` | Generate Terraform/Bicep infrastructure from DESIGN.md |
-| `sdd_validate_iac` | Validate generated IaC against best practices |
-| `sdd_generate_dockerfile` | Generate Dockerfile + docker-compose from tech stack |
-| `sdd_generate_devcontainer` | Generate devcontainer.json for Codespaces/Dev Containers |
-| `sdd_setup_local_env` | Generate local development environment setup |
-| `sdd_setup_codespaces` | Generate GitHub Codespaces configuration |
-| `sdd_create_branch` | Generate branch name following spec/NNN-feature convention |
-
-## Companion Agent
-
-**@specky-implementer** — Phase 7 agent that calls these tools in sequence. Load this skill as first step.
+- `sdd_generate_tests` takes only feature identity. It rejects missing/unknown requirement bindings, TODO bodies, and trivial assertions.
+- `sdd_generate_pbt` takes only feature identity. Property code must include its REQ-ID and cannot use generated model stubs.
+- Do not auto-detect or override frameworks per call.
+
+## IaC
+
+Use only when `iac` capability is enabled. `capability_config.iac` fixes:
+
+- provider (`terraform`)
+- cloud
+- concrete `{module, service}` resource list
+- state backend
+- region policy
+
+`sdd_generate_iac` requires DESIGN.md evidence and accepts no provider/cloud/module override. Run `sdd_validate_iac` before any external plan/apply. Specky returns validation routing; it does not apply infrastructure.
+
+## Development Environment
+
+Use only when `dev-environment` is enabled. The persisted contract fixes language, framework, runtime, package manager, port, sidecar services, Codespaces machine, extensions, base image, features, compose, and multi-stage choices.
+
+The local environment, Dockerfile, devcontainer, and Codespaces tools accept feature identity only. Unsupported stacks fail; no generic Ubuntu or TypeScript fallback is emitted.
+
+## Checklists and Evidence
+
+Run checklist domains explicitly and preserve implementation/code paths for Verify. Never claim files, containers, cloud resources, or Codespaces exist unless the writing/routed tool confirms them.
+
+## Handoff
+
+Report:
+
+- selected contract and capability fingerprints
+- task IDs included
+- generated executable test/property files
+- generated and validated IaC/environment files
+- remaining external actions and their exact routing payloads

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

@@ -1,161 +1,55 @@
 ---
 name: specky-onboarding
-description: "This skill should be used when the user asks 'help me with specky', 'what is specky', 'how to use specky', 'specky onboarding', 'get started', or needs guidance on project setup, work modes, or available agents/tools/prompts. Also trigger on '@specky', 'specky help', or 'show me specky commands'."
+description: "Use when starting or resuming Specky work, selecting lifecycle/workload/mode/capabilities, diagnosing config/state, or choosing an agent/tool."
 ---
 
-# Specky SDD Onboarding Guide
-
-## Overview
-
-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
-
-### Step 1: Detect Context
-Check for:
-- `.specs/` directory → existing pipeline, offer resume
-- `.sdd-state.json` → current phase state
-- `*.vtt`, `*.srt` files → meeting transcripts available
-- `src/`, `package.json`, `*.py` → existing codebase
-- Empty workspace → fresh start
-
-### Step 2: Project Type
-- **Greenfield** → New project from scratch → /specky-greenfield
-- **Brownfield** → Add features to existing code → /specky-brownfield
-- **Modernization** → Migrate/upgrade existing system → /specky-migration
-- **API Design** → Design an API specification → /specky-api
-
-### Step 3: Input Source
-- **Documents** → sdd_import_document, sdd_batch_import
-- **Transcripts** → sdd_import_transcript, sdd_auto_pipeline (end-to-end)
-- **Figma** → sdd_figma_to_spec
-- **Nothing** → sdd_discover (7 guided questions)
-
-### Step 4: Work Mode
-- **Full Pipeline** → @specky-orchestrator coordinates all 10 phases
-- **Agent-by-agent** → User picks agents manually
-- **Direct MCP tools** → User calls sdd_* tools directly
-
-### Step 5: Branch Setup
-- **Auto** → `git checkout develop && git checkout -b spec/NNN-feature`
-- **Manual** → Show git commands
-- **Skip** → No branching (solo/prototype work)
+# Specky Onboarding — Explicit Contract Wizard
 
-## All 13 Agents
-
-| Agent | Phase | Purpose |
-|-------|-------|---------|
-| @specky-onboarding | Pre | Interactive wizard and help |
-| @specky-orchestrator | All | Full pipeline coordinator |
-| @specky-sdd-init | 0 | Initialize pipeline + create spec branch |
-| @specky-research-analyst | 1 | Codebase scan + discovery |
-| @specky-spec-engineer | 2 | Write SPECIFICATION.md with EARS |
-| @specky-sdd-clarify | 3 | Resolve ambiguities + EARS validation |
-| @specky-design-architect | 4 | Write DESIGN.md + diagrams |
-| @specky-task-planner | 5 | Write TASKS.md + CHECKLIST.md |
-| @specky-quality-reviewer | 6 | Completeness audit + compliance |
-| @specky-implementer | 7 | Implementation plan + test stubs + IaC |
-| @specky-test-verifier | 8 | Coverage + drift + phantom detection |
-| @specky-requirements-engineer | Pre | FRD + NFRD from raw input |
-| @specky-release-engineer | 9 | Gates + PR + docs + work items |
-
-## All 22 Prompts
-
-**Quick Start:**
-- /specky-onboarding — Interactive wizard
-- /specky-orchestrate — Full pipeline
-- /specky-greenfield — New project
-- /specky-brownfield — Existing codebase
-- /specky-migration — System migration
-- /specky-api — API design
-
-**Pipeline Phases:**
-- /specky-research — Phase 1 (Discover)
-- /specky-specify — Phase 2 (Specify)
-- /specky-clarify — Phase 3 (Clarify)
-- /specky-design — Phase 4
-- /specky-tasks — Phase 5
-- /specky-implement — Phase 7 (Implement)
-- /specky-verify — Phase 8 (Verify)
-- /specky-release — Phase 9
-- /specky-deploy — Deployment artifacts
-
-**Special:**
-- /specky-from-figma — Import Figma designs
-- /specky-from-meeting — Import meeting transcripts
-- /specky-check-drift — Detect spec-code drift
-- /specky-resolve-conflict — Resolve spec conflicts
-
-**Debug:**
-- /specky-debug-hook — Debug hook execution
-- /specky-pipeline-status — Check pipeline status
-- /specky-reset-phase — Reset a pipeline phase
-
-## 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" |
-| research-analyst | "research codebase", "scan tech stack", "import documents" |
-| specky-sdd-markdown-standard | "artifact format", "spec formatting" |
-
-## 58 MCP Tools by Category
-
-**Pipeline Core (8):** sdd_init, sdd_discover, sdd_write_spec, sdd_clarify, sdd_write_design, sdd_write_tasks, sdd_run_analysis, sdd_advance_phase
-
-**Input/Conversion (6):** sdd_import_transcript, sdd_auto_pipeline, sdd_batch_transcripts, sdd_import_document, sdd_batch_import, sdd_figma_to_spec
-
-**Quality/Validation (5):** sdd_checklist, sdd_verify_tasks, sdd_compliance_check, sdd_cross_analyze, sdd_validate_ears
-
-**Visualization (4):** sdd_generate_diagram, sdd_generate_all_diagrams, sdd_generate_user_stories, sdd_figma_diagram
-
-**Infrastructure (3):** sdd_generate_iac, sdd_validate_iac, sdd_generate_dockerfile
-
-**Environment (3):** sdd_setup_local_env, sdd_setup_codespaces, sdd_generate_devcontainer
-
-**Integration/Export (5):** sdd_create_branch, sdd_export_work_items, sdd_create_pr, sdd_implement, sdd_research
-
-**Documentation (5):** sdd_generate_docs, sdd_generate_api_docs, sdd_generate_runbook, sdd_generate_onboarding, sdd_generate_all_docs
-
-**Testing (3):** sdd_generate_tests, sdd_verify_tests, sdd_generate_pbt
-
-**Turnkey (1):** sdd_turnkey_spec
-
-**Checkpointing (3):** sdd_checkpoint, sdd_restore, sdd_list_checkpoints
-
-**Utility (8):** sdd_get_status, sdd_get_template, sdd_write_bugfix, sdd_scan_codebase, sdd_amend, sdd_check_ecosystem, sdd_check_sync, sdd_metrics
-
-**Governance (4):** sdd_model_routing, sdd_context_status, sdd_check_access, sdd_verify_audit
-
-## 16 Hook Scripts
-
-**Blocking (exit 2 = halt):**
-- specky-artifact-validator.sh — Prerequisite .md files exist
-- specky-phase-gate.sh — Output artifact created with quality
-- specky-security-scan.sh — OWASP + secrets scan
-- specky-release-gate.sh — 90% pass rate + artifact checks
-
-**Advisory (exit 0 = warn):**
-- specky-branch-validator.sh — Branch matches phase expectations
-- specky-pipeline-guard.sh — Pipeline ordering / phase-skip guard
-- specky-lgtm-gate.sh — Human review reminder at Phases 2/4/5
-- specky-session-banner.sh — Session start pipeline-status banner
-- specky-spec-sync.sh — Detect spec-code drift
-- specky-auto-checkpoint.sh — Suggest checkpoint after writes
-- specky-spec-quality.sh — Specification quality metrics
-- specky-ears-validator.sh — EARS pattern compliance
-- specky-task-tracer.sh — Task dependency graph
-- specky-drift-monitor.sh — CONSTITUTION drift detection
-- specky-cognitive-debt-alert.sh — Cognitive surrender detection
-- specky-metrics-dashboard.sh — Quality metrics collection
+## 1. Validate Workspace
+
+1. Validate `.specky/config.yml`; an existing invalid/partial file blocks execution.
+2. Enumerate `.specs/NNN-name/` directories.
+3. Report signed v5 state per feature. Root `.specs/.sdd-state.json`, unsigned state, or older versions require `specky migrate-contracts --dry-run` before tools run.
+4. Never select the latest or first feature automatically.
+
+## 2. Select the Use Case
+
+Collect independently:
+
+- lifecycle: greenfield, brownfield, migration
+- workload: API, web application, service, CLI, library, infrastructure
+- execution mode: full, rapid, emergency
+- explicit three-digit feature number
+
+The selected mode produces a persisted phase graph. Do not describe rapid/emergency as “skipping” a mandatory full graph; their contracted graphs are different by design.
+
+## 3. Select Capabilities
+
+Capabilities are opt-in and require matching parameter objects. Review the exact table in the `specky-sdd-init` skill. Ask for every provider, framework, resource, branch, threshold, format, platform, and environment value. `capabilities: []` requires `capability_config: {}`.
+
+## 4. Gather Lifecycle Evidence
+
+- Greenfield: outcome, boundaries, stakeholders, fixed/open constraints.
+- Brownfield: run `sdd_scan_codebase` with explicit depth/exclusions; preserve baseline, compatibility, insertion, and rollback evidence.
+- Migration: preserve named source inventory, target inventory, parity/divergence, wave, cutover, rollback, and decommission evidence.
+
+## 5. Choose Input Source
+
+- Documents: enable `document-import`; explicitly allow formats.
+- Transcripts: enable `transcript-import`; import may parse source, but auto/batch orchestration also requires explicit Constitution, source-backed requirements, complete architecture, tasks, and gates. Source quotes are validated before writes.
+- Figma: enable `figma` and select extraction scope/diagram types.
+- Direct discovery: questions are lifecycle/workload-specific.
+
+## 6. Choose Execution Surface
+
+- Orchestrator: follows signed phase graph and delegates to lean agents.
+- Agent: first reads its rich companion skill.
+- Direct MCP: caller supplies every required field; no Zod defaults exist.
+
+## 7. Branching
+
+Do not create a branch in Init. When `release` capability is enabled and phase policy permits, use persisted branch prefix/base/draft/checkpoint parameters.
+
+## Completion
+
+Before routing, repeat the full selection and obtain confirmation. Then initialize or resume the exact feature and report the contract ID, fingerprint, canonical state path, and next contracted phase.