spae-build

Files (5)

• SKILL.md
• STATE.md · references/
• cleanup-guide.md · references/
• shell-command-guide.md · references/
• testing-guide.md · references/

SKILL.md (first lines)

# Build

## When to use

- `STATE.json` has `phase: build`.
- The work stream needs the next planned task completed.

## Goal

- Execute exactly one task from `PLAN.md`, mutating source/tests plus
  `STATE.json`, while preserving the framework execution cursor.
- Complete the active task with minimal production code that meets
  exhaustive tests, serves its `Intent` and the plan `## Goal`, and
  leaves seams for downstream tasks.
- Meet the task acceptance criteria through exhaustive tests and task
  verification steps.
- Hand off to `/check` for the `done` transition and cursor advance;
  never claim either.

## Input

Read:

- `.spae/current/STATE.json` for phase, cursor, and task registry
  (consult `references/STATE.md` for field reference, directives, and
  phase snapshots).
- `.spae/current/PLAN.md` for the plan `## Goal`, the active task, its
  `Intent`, acceptance criteria, and verification steps; they carry all
  the goal context build needs.
- Relevant project source, tests, docs, and configuration needed for the
  active task.

## Testing

See `references/testing-guide.md` for test structure, isolation,
mocking, assertion, and performance standards.

## Cleanup

See `references/cleanup-guide.md` for the self-introduced-artifact
checklist and diff-only audit scope.

## Workflow

1. **GATE**—Read `.spae/current/STATE.json`; confirm `phase: build` and
   an active task cursor. Self-heal metadata: inject missing `version`
   (`"1.0"`), `workstream` (from symlink or directory path), and
   `status` (`"active"`). Halt on state drift: if
   `tasks[`active_task_id`]` reads `"done"`, halt; report and make no
   changes. Halt on _unparseable_ JSON, unrecognized phase, or active
   task missing from `PLAN.md`. Read the plan `## Goal` and active task
   section — including its `Intent` — from `.spae/current/PLAN.md`. Read
   dependent and forward task titles plus acceptance criteria to map
   seams, not build them. Verify every task ID in the active task's
   `Dependencies` field carries status `"done"` in `tasks` registry in
   `STATE.json`; fail the task for any incomplete dependency.
2. **ORIENT**—State the goal in one sentence: execute the active task
   and hand off to `/check`. Name what won't change: `PLAN.md`,
   `SPEC.md`, and forward-task seams. Capture pre-task baseline snapshot
   per `references/cleanup-guide.md`. **Task status update**: set
   `tasks[`active_task_id`]` to `"in_progress"` in
   `.spae/current/STATE.json`.
3. **PLAN**—Declare the full implementation path that satisfies every
   acceptance criterion, advances the task `Intent` and plan `## Goal`,
   and leaves seams for forward tasks. Read
   `references/testing-guide.md`, `references/shell-command-guide.md`,
   and `references/cleanup-guide.md`. Map the test surface per
   criterion: expected behaviors, failure modes, and edge cases. Choose
   among valid implementations by goal fit, not local convenience.
4. **ACT**—Iterate over every acceptance criterion:
   - Write a failing test: expected behavior, failure modes, and edge
     cases.
   - Write minimal code to pass it.
   - Drive green; repeat `test→implement` until the criterion passes.

   Stop when all criteria have exhaustive passing test coverage. Never
   write production code before its test exists. Edit only source,
   tests, docs, or configuration files required by the task.

5. **VERIFY**—Loop over every acceptance criterion and verification
   command listed for the active task:
   - Audit every added or updated test file against CI Parity rules in
     `references/testing-guide.md`; fix any violation before proceeding.
   - Audit task edits against the pre-task baseline using the
     Self-cleanup checklist in `references/cleanup-guide.md`; remove
     every self-introduced artifact before proceeding.
   - For each unmet criterion or failing command: return to `ACT`,
     execute, then re-enter `VERIFY`.
   - Exit only when all criteria pass and all commands succeed.
   - Fail only for out-of-scope conditions: infeasible acceptance
     criterion, plan/spec defect, or broken external dependency.
6. **PERSIST**—Set `.spae/current/STATE.json` `phase: check`. `/check`
   owns the `done` transition and cursor advance. 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 all operations for agent, token, and context efficiency.
- Consult `references/shell-command-guide.md` for command safety,
  timeouts, redirects, and non-interactive environment directives.
- Consult `references/cleanup-guide.md` for self-introduced-artifact
  scope, baseline snapshotting, and checklist directives.
- Execute exactly one atomic task per invocation.
- Prefer existing project patterns over new design.
- Keep production code minimal, local, and test-driven; never reduce
  test scope.
- Look ahead, don't act ahead: read forward tasks to avoid foreclosing
  them; never build beyond the active task. Name any forward task you
  designed around in the result.
- Tests drive every task; write them first, exhaustively, before any
  production code. Implementation serves tests, never the reverse.
- Write every category of test the task demands: unit, integration,
  end-to-end, or otherwise. Cover expected behavior, failure modes, and
  edge cases exhaustively.
- When the task legitimately changes a contract, update the tests it
  invalidates to the new contract; never weaken, skip, or delete a test

From mystilleef/spae-framework, MIT.

More from mystilleef/spae-framework