spae-spec

Files (5)

• SKILL.md
• SPEC.md · references/
• STATE.md · references/
• aspect-sweep.md · references/
• prose-protocol.md · references/

SKILL.md (first lines)

# 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 target `workstream` and scope by first available source:

- Explicit argument: target directory `.spae/[workstream]/`.
- Implicit active: resolve target directory via `.spae/current` symlink.
- Implicit new: auto-generate slug, target directory `.spae/[slug]/`.

## Workflow

Select sub-workflow by target `workstream` state:

- **New**: Target directory missing → `New spec workflow`.
- **Resume**: Target directory exists with `STATE.json` (`phase: spec`,
  `status: active`) → `Resume spec workflow`.
- **Revision**: Target directory exists with `STATE.json`
  (`status: revision_required`) and `VERIFY.md` present →
  `Revision spec workflow`.

### New spec workflow

Follow this workflow when target `workstream` directory missing.

1. **GATE**—Confirm target `workstream` directory absent. Halt if target
   directory exists.
2. **ORIENT**—Initialize `.spae/[workstream]/` directory; create
   `STATE.json` (`phase: spec`, `status: active`, `cursor: {}`,
   `tasks: {}`). Read `AGENTS.md` at project root in full when present;
   treat constraints, conventions, and gates as non-negotiable spec
   inputs. Source code unmodified.
3. **PLAN**—Identify codebase sections to read.
4. **ACT**—Execute:
   - Read codebase sections narrowly; widen only on uncertainty.
   - Consult `references/prose-protocol.md` before drafting.
   - Sweep the proposal for aspect coverage per
     `references/aspect-sweep.md`: scan all categories each phase,
     dedupe new candidates against the ledger, halt on the first
     zero-new-candidate phase or `PHASE_CAP` (4).
   - Derive goal, requirements, testing strategy, out-of-scope
     boundaries, and assumptions from the ledger; reflect all
     `AGENTS.md` constraints.
   - Assess derived requirements against `YAGNI`; discard `unrequested`
     scope, speculative features, or theoretical complexity;
     YAGNI-discarded ledger aspects land in `Out of scope` with a
     one-line rationale, never a silent drop.
   - Automatically place all version control operations (git staging,
     commits, branches, tags) and release operations (publishing,
     deployments) into `Out of scope`.
   - Forbid creating any `R-NNN` requirement covering git mutations,
     package publishing, or release workflows.
5. **VERIFY**—Loop over spec completeness criteria:
   - For each failure: return to `ACT`, fix, then re-enter `VERIFY`.
   - Exit only when spec complete, structure matches
     `references/SPEC.md`, every aspect-ledger entry resolves to a named
     `SPEC.md` disposition—no orphaned aspect—and no **Contradictions**
     finding survives.
   - Halt only for out-of-scope conditions.
6. **PERSIST**—Write `SPEC.md`. Point `.spae/current` symlink to
   `.spae/[workstream]`. 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 Result template.

### Resume spec workflow

Follow this workflow when target `workstream` directory exists with
`phase: spec`, `status: active`.

1. **GATE**—Target directory exists; `STATE.json` contains
   `phase: spec`. Self-heal metadata: inject missing `version`
   (`"1.0"`), `workstream` (from symlink or directory path), and
   `status` (`"active"`). Halt on unparseable JSON or phase mismatch.
2. **ORIENT**—Read `AGENTS.md` at project root in full when present;
   treat constraints as binding. Source code unmodified.
3. **PLAN**—Survey existing draft artifacts and prompt context. Identify
   codebase sections to inspect.
4. **ACT**—Execute:
   - Inspect codebase sections narrowly to complete missing details.
   - Consult `references/prose-protocol.md` before drafting.
   - Seed the aspect ledger from the current `SPEC.md` draft's existing
     `R-NNN`, `Out of scope`, `Assumptions`, and `Testing strategy`
     entries (mark covered), then sweep remaining proposal or task
     context per `references/aspect-sweep.md`: scan all categories each
     phase, dedupe against the ledger, halt on the first
     zero-new-candidate phase or `PHASE_CAP` (4).
   - Complete `SPEC.md` draft following `references/SPEC.md` structure.
   - Assess requirements against `YAGNI`; discard `unrequested` scope or
     speculative features; YAGNI-discarded ledger aspects land in
     `Out of scope` with a one-line rationale, never a silent drop.
   - Automatically place all version control operations (git staging,
     commits, branches, tags) and release operations (publishing,
     deployments) into `Out of scope`.
   - Forbid creating any `R-NNN` requirement covering git mutations,
     package publishing, or release workflows.
5. **VERIFY**—Loop over spec completeness criteria:
   - For each failure: return to `ACT`, fix, then re-enter `VERIFY`.
   - Exit only when spec complete, structure matches
     `references/SPEC.md`, every aspect-ledger entry resolves to a named
     `SPEC.md` disposition—no orphaned aspect—and no **Contradictions**
     finding survives.
   - Halt only for out-of-scope conditions.

From mystilleef/spae-framework, MIT.

More from mystilleef/spae-framework