A complete outcome spec that defines what to build and how to verify it — the agent determines the procedure.
Acceptance Criteria
Spec file contains:
Overview
What to build and why
Decisions
Key technical choices with rationale
Implementation Steps
Concrete, ordered steps
Edge Cases
Error handling, boundary conditions
Constraints
Sanitize topic for use as filename — strip path separators, special characters, and traversal patterns (
../
)
Read
memory:
and
specs:
from
.groove/index.md
; resolve spec directory as
if
specs:
key is present, otherwise
/specs/
Ensure the resolved specs directory exists (create if missing)
Research codebase first (use Explore agent)
Interview user for decisions, edge cases, testing approach, scope
Assess scope: if the work has natural seams (independent components, sequential phases, separable concerns), recommend splitting into a parent spec with child specs
Parent spec
Overview of the full feature, links to child specs, execution order if sequential
Child specs
Each self-contained with its own Overview, Decisions, Steps, Edge Cases
Naming
:
.md
for single specs,
/index.md
+
/01-.md
for split specs
User decides
Present the split recommendation with rationale, user confirms or overrides
Write spec in isolated context (use general-purpose agent)
Verify all required sections exist before completing
Reference actual codebase patterns, not generic advice
Quality Signals
Decisions reference real code patterns
Steps include actual file paths and function names
Edge cases reflect discovered constraints