| name | sdd-feature |
| description | Execute a complete, repository-grounded spec-driven workflow for a feature, substantial refactor, architectural change, or multi-file behavior change. Create and maintain spec.md, design.md, tasks.md, and verification.md; implement bounded task slices; and require evidence before completion. Do not use for trivial isolated fixes. |
| metadata | {"version":"3.0","tags":["sdd","planning","implementation","traceability","verification"]} |
| license | MIT |
SDD Feature Workflow
Use repository artifacts as the durable contract between planning, implementation, and review. Keep product intent, technical decisions, work units, and evidence distinct.
Operating rules
- Inspect the active checkout, instructions, history, relevant code, tests, and existing specs before proposing changes.
- Preserve unrelated work. Do not reset, clean, or overwrite user changes.
- Do not implement while discovering, specifying, designing, or analyzing.
- Never silently change a requirement to justify implementation behavior.
- Work one independently testable task or small dependency-ordered group at a time.
- Treat a successful build or agent summary as insufficient evidence for behavioral claims.
- Ask for human approval before implementation when requirements, security boundaries, migrations, or external side effects remain materially ambiguous.
- Treat the specification as spec-anchored: it evolves with behavior, but is not generated code and must not be mutated to excuse an implementation defect.
Artifact contract
Use specs/<feature>/ unless the repository defines another convention:
spec.md: problem, actors, scope/non-goals, stable REQ-### IDs, concrete scenarios, failure behavior, constraints, assumptions, AC-### acceptance criteria, and open questions.design.md: current state, reused abstractions, architecture/data flow, contracts, data changes, affected files, security, failure handling, testing, rollout/rollback, alternatives.tasks.md: dependency-ordered T-### tasks with requirement links, ownership/file boundaries, dependencies, deliverables, exact validation, evidence location, and status.verification.md: requirement-by-requirement implementation and validation evidence, evidence type, discrepancies, uncertainty, and final status.
Lifecycle
Discover
Read repository instructions and inspect the relevant modules, interfaces, tests, configuration, history, and existing artifacts. Record facts separately from assumptions. Identify unknowns that could change scope, safety, compatibility, or user-visible behavior.
Specify
Write stable, testable requirements. Prefer concrete scenarios and explicit failure behavior. Include security, privacy, accessibility, performance, compatibility, and observability constraints when relevant. State non-goals. Use WHEN ... THE SYSTEM SHALL ... or Given/When/Then for important behavior, including negative scenarios. Every acceptance criterion must be observable. Do not prescribe implementation unless it is an explicit constraint.
Design
Ground every major decision in the current code. Name files, symbols, interfaces, data ownership, migration strategy, authorization boundaries, error paths, and rollback. Explain rejected alternatives. Flag conflicts with spec.md instead of hiding them.
Analyze
Before coding, perform a read-only cross-artifact analysis: every requirement has design coverage; every acceptance criterion has validation; every task maps to requirements; no task is orphaned; dependencies are ordered; and risky paths have validation. Record PASS/FAIL and stop on critical gaps or contradictions.
Implement
For each selected task:
- Re-read its requirement and design references.
- Inspect the exact files and existing tests.
- State conflicts before editing.
- Make the smallest complete change within the task boundary.
- Run the narrowest relevant validation, then inspect the diff and status.
- Record discoveries and evidence in the artifact.
- Mark the task complete only when validation passes and evidence is recorded.
Stop at the requested milestone. Do not expand scope because adjacent cleanup seems attractive.
Verify and reconcile
Create verification.md. For every requirement and acceptance criterion, point to implementation symbols/files and actual test or command evidence. Label what was observed versus inferred from a build. Run relevant regression, integration, smoke, migration, and security checks. Classify discrepancies as implementation defect, missing requirement, outdated design, approved deviation, or incomplete task. The feature is complete only when specification, implementation, and tests agree.
Handoff format
At every stop, report:
- Current artifact and task/milestone
- Files changed and files intentionally untouched
- Commands run and observed results
- Requirements covered and uncovered
- Decisions, discoveries, and deviations
- Remaining risks and exact next action
Safety and observability
Do not expose secrets or place them in artifacts. Validate paths, identities, authorization, destructive operations, migrations, and external calls before execution. Log or record skill name/version, activation intent, artifacts read/changed, tools/commands used, outcome, and uncertainty when the host supports it.
