spae-plan

Files (4)

• SKILL.md
• PLAN.md · references/
• STATE.md · references/
• prose-protocol.md · references/

SKILL.md (first lines)

# Plan (`SPAE`)

## When to use

- `SPEC.md` exists and needs an execution plan.
- `STATE.json` reports `phase: plan`.
- A revision cycle re-enters planning after `/spec` reprocesses
  findings.

## Goal

- Convert normalized requirements into a concise, acyclic, atomic task
  graph while preserving strict phase and write boundaries.
- Produce `.spae/current/PLAN.md`, initialize task tracking in
  `.spae/current/STATE.json`, and advance the `workstream` to
  `phase: inspect`.

## Input

Use only relevant context from:

- `.spae/current/SPEC.md`.
- `.spae/current/STATE.json` (consult `references/STATE.md` for field
  reference, directives, and phase snapshots).
- Repository source patterns, read only for codebase fit.

**Never read `.spae/current/VERIFY.md`**—not an input to this phase.
Reading qualifies as content-blocking.

## Workflow

1. **GATE**—Read `.spae/current/STATE.json`; self-heal metadata: inject
   missing `version` (`"1.0"`), `workstream` (from symlink or directory
   path), and `status` (`"active"`). Confirm `.spae/current/SPEC.md`
   exists and `STATE.json` reports `phase: plan`. Halt immediately on
   _unparseable_ JSON, missing `SPEC.md`, or `phase ≠ plan`; report
   failure and make no changes.
2. **ORIENT**—Extract goal, requirements, testing strategy, out-of-scope
   items, and assumptions from `SPEC.md`. Capture every `R-NNN` item
   into an in-memory coverage checklist. Gather only the source patterns
   needed for codebase fit; never edit repository files.
3. **PLAN**—Decompose work to cover the spec without over-splitting.
4. **ACT**—Delete `.spae/current/PLAN.md` (ignore if absent) and clear
   the `tasks` registry in `.spae/current/STATE.json` to empty —
   unconditionally. Read the template from `references/PLAN.md`; consult
   `references/prose-protocol.md` before drafting task prose. Decompose
   work into atomic tasks numbered from `T-001`. Set each task's
   `Satisfies` to the `R-NNN` IDs it implements and its `Intent` to a
   one-line distillation of the goal those requirements serve—or, for an
   enabling task, the structural purpose it serves toward the plan
   `## Goal`. Sort tasks by dependency, risk, and vertical value; each
   task must leave the system working.
5. **VERIFY**—Loop over every plan validity criterion:
   - For any `R-NNN` gap: return to `ACT`, add the missing task, then
     re-enter `VERIFY`. Treat `Satisfies: none` as intentional; flag
     empty or missing `Satisfies` as a scope-creep observation.
   - For any graph violation—cycle or forward-order failure: return to
     `ACT`, correct it, then re-enter `VERIFY`.
   - Exit only when all `R-NNN` items map to tasks and the graph has no
     violations.
   - Fail only for out-of-scope conditions.
6. **PERSIST**—Write `.spae/current/PLAN.md`. Initialize all task IDs as
   `todo` in `.spae/current/STATE.json`. Clear `cursor` to `{}`. Set
   `phase: inspect`. Write once, atomically. Re-read `STATE.json` after
   writing; on a field mismatch, rewrite and re-read before `REPORT`.
7. **REPORT**—Emit the result following the result directives and using
   the result template.

## Directives

- Optimize for agent, token, and context efficiency.
- Refine and optimize `PLAN.md` for agent consumption: agents read it
  for varied purposes, with no memory of this run; keep it
  self-contained, explicit, token-dense, and minimal.
- Prefer existing codebase patterns over speculative design.
- Slice vertically; avoid infrastructure-only tasks unless required.
- Assume each task executes, reviews, and refines under a stateless
  agent with no memory beyond `PLAN.md` text and resulting source; write
  `Context` to supply every fact that agent needs—never a detail
  available only from planning the task.
- Write acceptance criteria as observable outcomes; name testable
  behaviors for a `Satisfies`-bearing task (include failure modes and
  edge cases only when specified in `SPEC.md` or required by task
  logic); state structural assurances for a `Satisfies: none` enabling
  task.
- Write verification as concrete test commands and deterministic checks;
  every task's Verification section must include test execution.
- Reject verification steps that presume human execution, an attended or
  interactive terminal, or human presence; flag as a spec defect instead
  of encoding them in `PLAN.md`.
- Never add `SPAE` artifacts beyond core files and ephemeral
  `VERIFY.md`.
- Never generate tasks for git operations (staging, commits, tags,
  branches) or release deployment. The plan scope concludes when local
  tests pass against verified source code.
- Never stage or commit `.spae/` artifacts or execute git mutations.
- Consult `references/prose-protocol.md` before drafting `PLAN.md`.

## Constraints

- **Write scope**: `.spae/current/PLAN.md` and
  `.spae/current/STATE.json`.
- **Forbidden writes**: source code, tests, configuration files, docs,
  `SPEC.md`, `VERIFY.md`, and any non-`SPAE` project file.
- **Scope boundary**: Never create tasks for git mutations, package
  publishing, or release workflows.
- **Read-only source**: inspect repository code only for fit.
- **Phase boundary**: hand off to `/inspect`; don't execute tasks.
- **Autonomy**: Never ask users for input or clarification
  mid-execution; halts and failures stop autonomously.
- **Full autonomy**: Never write a task whose Verification section
  depends on human execution, an attended or interactive terminal, or
  human presence.
- Never introduce fields to `STATE.json` outside the schema reference.

## Verification

- `.spae/current/PLAN.md` contains atomic, acyclic, dependency-ordered
  tasks—no cycles; every `Dependencies` ID numerically precedes its

From mystilleef/spae-framework, MIT.

More from mystilleef/spae-framework