spae-spec

Spec (SPAE)

When to use

• Initialize a new SPAE workstream.
• Resume interrupted spec work (phase: spec, status: active).
• Rewrite requirements from scratch after a failed /verify (status: revision_required).

Goal

• Distill user requests, verification findings, and codebase context into concise, testable requirements while preserving SPAE phase boundaries.
• Generate .spae/[workstream]/SPEC.md and advance STATE.json to phase: plan.

Input

Determine scope by the first available source:

• proposal or task from user
• Existing STATE.json (consult references/STATE.md for field reference, directives, and phase snapshots) and VERIFY.md in .spae/current when present.

Workflow

Select sub-workflow by .spae/current symlink state:

• New (symlink absent): New spec workflow
• Revision (symlink present): Revision spec workflow

New spec workflow

If absent symlink follow this workflow.

1. GATE—.spae/current absent. Halt if symlink exists (revision path).
2. ORIENT—Produce SPEC.md and STATE.json for [workstream]. Codebase unmodified.
3. PLAN—Derive [workstream] slug from args or auto-generate. Identify codebase sections to read.
4. ACT—Execute:
   • Initialize .spae/[workstream]/; point .spae/current symlink; create STATE.json (phase: spec, status: active).
   • If AGENTS.md exists at the project root, read it in full before any codebase sections; treat its constraints, conventions, and gates as non-negotiable spec inputs.
   • Read codebase sections narrowly; widen only on uncertainty.
   • Consult references/prose-protocol.md before drafting.
   • Derive goal, requirements, testing strategy, out-of-scope boundaries, and assumptions; reflect all AGENTS.md constraints.
   • Assess derived requirements against YAGNI; discard unrequested scope, speculative features, or theoretical complexity.
5. VERIFY—Loop over spec completeness criteria:
   • For each failure: return to ACT, fix, then re-enter VERIFY.
   • Exit only when spec complete and structure matches references/SPEC.md.
   • Fail only for out-of-scope conditions.
6. PERSIST—Write SPEC.md. Update STATE.json (phase: plan, status: active, cursor: {}, tasks: {}). Re-read STATE.json after writing; on a field mismatch, rewrite and re-read before REPORT.
7. REPORT—Emit result using the Result template.