# Design: The Spire Development Cycle

**Date**: 2026-09-22
**Source**: Gitea issue #5, journal `journals/2026-09-21-14-agent-rails.md`
**Status**: first pass — expect refinement

## The shape

The cycle is a loop, not a pipeline. Review is the decision point; it can send work back to any earlier stage, but almost always one step.

```
  brainstorm ──> research ──> design ──> plan ──> athanor ──> review ──> done
                    ^            ^         ^                    |
                    |            |         '── medium+ issues ──'   short loop (common)
                    |            '──────── design is wrong ─────'   long loop (rare)
                    '──────────────────── new problem space ────'   long loop (rare)
```

A **goal** anchors the loop. Goals are user-owned (`goals/`, read-only to agents; Igor may draft one on the user's behalf) and do not change during a cycle. A changed goal is a new cycle.

## Stages

| Stage | Who | Input | Output |
|---|---|---|---|
| 1. Brainstorm | Igor with user (or Pinky) | goal or hunch | `brainstorm/` — options, no commitment |
| 2. Research | researcher / adept | open questions | `research/` — findings |
| 3. Design | independent Opus agent (never the planner or Athanor) | goal + research | `designs/` — one approach, buildable |
| 4. Plan | independent Opus planning agent (never the designer or Athanor) | a design | `plans/` — steps, files, completion criteria; may be several |
| 5. Implement | **Athanor** | one plan | code on a branch; run report in `reports/` |
| 6. Review | fresh Opus reviewer (never the Athanor that cooked it) | diff + plan | `reports/` — findings with severity |

**Brainstorm** usually precedes the cycle proper; skip it when direction is clear.

**Research** is the most-skipped and most-decisive stage. If a design stalls on an unknown, research it — do not guess.

**Design** is convergent. Igor resolves open questions by picking the most likely answer and flagging it inline (`**Assumed:** ...`). A question becomes a blocker only when a wrong pick would waste the implementation — then it goes to research or the user.

**Plan** is the entry to the implementation loop: before it is thinking, after it is production. A plan must run in the Athanor without conversation.

**Implement**: the Athanor is the oven. A plan goes in, code comes out. It does not talk, ask, or surface partials mid-run.

**Review** measures output against the plan and design, not taste. Severity: `low` (nits), `medium` (wrong but contained), `high` (load-bearing, or plan not fulfilled).

## Review decision tree

1. **None or low only** — done. Lows stay in the report; fold into a later plan or drop. Never loop for lows.
2. **Any medium or high** — collect all findings into a new plan (step 4). The normal short loop; expect two or three turns.
3. **The approach is wrong, not the code** — back to design (step 3). Append a dated amendment; do not rewrite.
4. **An unresearched unknown surfaced** — back to research (step 2). Only for a genuinely new problem space, never for iteration.
5. **The goal is wrong** — stop. The user's call.

Igor routes and journals the decision. Default to the shortest loop that fits; long loops need a stated reason.

## Athanor queuing

Plans enter the Athanor **sequentially**; Igor holds the queue.

- Multiple plans from one design run in dependency order; each starts from the committed result of the previous, with review between.
- **A new plan arriving mid-run waits.** The door is closed; Igor sends nothing into a running Athanor. It is dispatched when the current run reports back.
- **If a new plan invalidates the one cooking**, Igor stops the run (`TaskStop`), shelves the partial output, and dispatches the replacement. **Assumed:** rare enough that manual stop suffices.
- Parallel Athanors only for disjoint code, each in its own worktree. Default is one.

## Cycle and workpad

Each stage writes to one folder; moving forward creates a new file, never mutates the previous one. The trail through the folders *is* the record of the cycle. A re-plan is a new dated file in `plans/` linking to the review report; a design amendment is a dated section on the existing design.

`journals/` is cross-cutting — every dispatch, routing decision, and loop-back gets a line. `specs/` sits outside the cycle: written when a cycle produces something that must not drift.

## Not part of the cycle

- **Conversation** — reasoning with the user, deciding direction. Igor's own job.
- **Ad-hoc questions** — a scout or adept answers; nothing enters the loop.
- **One-off tasks** — typo, commit, obvious small fix. Direct Sonnet/Haiku dispatch; no plan, no review.
- **Maintenance** — curation, adept handoffs, Zathras. Alongside the cycle, not inside it.

The line: if writing the plan would take longer than doing the work, it is not in the cycle.

## Settled rules

- **Plans and designs are always written by independent agents** — not Igor, not the Athanor. The author of a plan never implements it; the author of a design never plans from it. Separation keeps review honest.
- **The Athanor commits** — on its branch, per plan step. Nobody opens PRs.