reliquary/docs/workpad/designs/2026-09-22-development-cycle.md

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.