📝 Add development cycle design and session artifacts for issue #5
First-pass design doc codifying the Spire development cycle: six stages (brainstorm → research → design → plan → athanor → review), review decision tree, Athanor queuing rules, workpad mapping. Session journal and fix reports included.
This commit is contained in:
@@ -0,0 +1,81 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,35 @@
|
||||
# Agent Rails — Igor Session Journal
|
||||
|
||||
**Date**: 2026-09-21
|
||||
**Topic**: Gitea issue #5 — Agent Rails (agent write capabilities, cycle codification, Athanor clarification)
|
||||
**Worktree/branch**: main
|
||||
|
||||
## Log
|
||||
|
||||
- 14:00 — Session opened. Issue #5 fetched from Gitea. Three threads identified: (1) agents need write access, not just read-only Explore/Plan, (2) codify the development cycle (brainstorm → research → design → plan → athanor → review → loop), (3) clarify Athanor naming — it IS the oven, not something put into the oven.
|
||||
- 00:00 — Three agents dispatched in parallel:
|
||||
- Opus: fix agent write capabilities (audit + edit all delegation guidance)
|
||||
- Opus: fix Athanor naming/metaphor consistency
|
||||
- Fable: design the development cycle spec
|
||||
- 00:02 — Athanor naming agent returned. 3 files edited (athanor.md, igor/SKILL.md, zathras/SKILL.md). Metaphor guardrail added to Igor voice section. Report filed.
|
||||
- 00:03 — Fable cycle design agent returned. Design written to `designs/2026-09-22-development-cycle.md`. 6 stages, review decision tree, Athanor queuing rules, workpad mapping. Flagged: Pinky agent referenced in design spec but no agent def exists.
|
||||
- 00:04 — Write-capabilities agent returned. 4 files edited (model-tiers.md, igor/SKILL.md, zathras/SKILL.md, adept.md). Root cause: model-tiers.md promoted Explore/Plan as "safe leaves" without noting read-only limitation. Now replaced with write-capability guard section steering to scout/search/researcher.
|
||||
|
||||
## Adepts
|
||||
|
||||
No domain adepts active. Roster is empty (no domain folders yet).
|
||||
|
||||
## Artifacts
|
||||
|
||||
- `docs/workpad/reports/2026-09-22-00-athanor-naming-fix.md` — Athanor metaphor fix report
|
||||
- `docs/workpad/reports/2026-09-22-00-agent-write-capabilities-fix.md` — Write-capability fix report
|
||||
- `docs/workpad/designs/2026-09-22-development-cycle.md` — Development cycle design (first pass)
|
||||
|
||||
## Open threads
|
||||
|
||||
- Pinky agent: referenced in plugin design spec as brainstorm agent, no `agents/pinky.md` exists. Stale or TODO?
|
||||
- Cycle design is a first-pass design doc — user may want to promote parts to spec after review.
|
||||
- Review severity definitions are loose — may want tighter criteria.
|
||||
- Assistant skill fixed to route to Igor instead of Zathras (Zathras skill not loading in remote env).
|
||||
|
||||
## Graduation candidates
|
||||
@@ -0,0 +1,36 @@
|
||||
# Agent Write-Capabilities Fix
|
||||
|
||||
**Date:** 2026-09-22
|
||||
**Scope:** Spire skill and agent definitions
|
||||
|
||||
## Problem
|
||||
|
||||
The `Explore` and `Plan` agent types in Claude Code are READ-ONLY -- they cannot use Edit, Write, or NotebookEdit. Spire's delegation guidance promoted these types as preferred "safe leaves" (because they cannot sub-delegate), without warning that they also cannot produce file artifacts. This caused Igor and other coordinators to dispatch `Explore` agents for research and investigation tasks that needed to write reports, designs, or plans to the workpad.
|
||||
|
||||
## Changes
|
||||
|
||||
### `plugins/spire/skills/igor/references/model-tiers.md`
|
||||
- Added `subagent_type` column to the delegation table with explicit values for each tier (`"researcher"`, `"scout"`, `"search"`, `"adept"`, `"athanor"`, or "omit" for general-purpose).
|
||||
- Added `scout` and `search` rows for read-only lookup tiers.
|
||||
- Replaced the old "Sub-delegation guard" section (which presented `Explore`/`Plan` as desirable defaults) with a new "Write-capability guard" section that explicitly warns about their read-only limitation and recommends Spire's pinned agents instead.
|
||||
- Kept the sub-delegation guard as a separate section focused only on which types can spawn children.
|
||||
|
||||
### `plugins/spire/skills/igor/SKILL.md`
|
||||
- Replaced "Dispatch an Explore agent" with "Dispatch a `search` agent" (line 19).
|
||||
- Replaced "one-shot Explore agent" with "one-shot `search` or `scout` agent" (line 105).
|
||||
- Added `subagent_type` / `model` column to the delegation table with explicit values for every row.
|
||||
|
||||
### `plugins/spire/skills/zathras/SKILL.md`
|
||||
- Replaced "Explore agent or adept" with "`search` agent or adept" in the delegation table.
|
||||
- Added `subagent_type` / `model` column to the delegation table.
|
||||
|
||||
### `plugins/spire/agents/adept.md`
|
||||
- Replaced "Dispatch Explore subagents" with "Dispatch `search` subagents" in both genesis (line 50) and consultation (line 77) sections.
|
||||
|
||||
## Principle
|
||||
|
||||
- `Explore` and `Plan`: only for pure lookups or pure planning where the answer returns in agent reply text, not as a file.
|
||||
- `scout` and `search`: preferred read-only alternatives (Spire-pinned, tool-restricted).
|
||||
- `researcher`: the correct choice for research that produces a written report.
|
||||
- Omit `subagent_type` (general-purpose default) for any task needing write access that does not match a pinned agent.
|
||||
- `model` parameter remains required on all Agent calls.
|
||||
@@ -0,0 +1,21 @@
|
||||
# Athanor Metaphor Consistency Fix
|
||||
|
||||
**Date:** 2026-09-22
|
||||
|
||||
## Problem
|
||||
|
||||
The Athanor's name comes from alchemy -- an athanor is a self-feeding furnace. The Athanor IS the oven/forge. But some phrasings were ambiguous enough that Igor could generate lines like "Athanor is in the oven," inverting the metaphor.
|
||||
|
||||
## Changes
|
||||
|
||||
### `plugins/spire/agents/athanor.md`
|
||||
- **Description:** Replaced ambiguous "put it in the oven" (where "it" could be misread as the Athanor) with "plans go into it and implementations come out." Added "Fire up the Athanor" / "into the Athanor with it" as the canonical shorthand.
|
||||
- **Body:** Added explicit "You ARE the oven" framing. Replaced "Put it in the oven" tagline with the clearer canonical phrases.
|
||||
|
||||
### `plugins/spire/skills/igor/SKILL.md`
|
||||
- **Voice section:** Added a new bullet: "The Athanor IS the furnace" -- explicit guardrail explaining the metaphor and forbidding inversions like "the Athanor is in the oven."
|
||||
- **Voice examples:** Replaced two lines. "Ah, the Athanor. Mighty forge of code" became "Into the Athanor with this one. It'll cook." "Back into the forge it goes" became "Fire up the forge. This plan needs heat." Both reinforce the correct direction: work goes into the Athanor.
|
||||
- **Delegation paragraph:** Reworded to use forge metaphor: "Load it with a brief, close the door, let it cook."
|
||||
|
||||
### `plugins/spire/skills/zathras/SKILL.md`
|
||||
- Reworded athanor reference from "the athanor transforms plans" to "plans go into the athanor and forged artifacts come out" -- reinforces directionality.
|
||||
Reference in New Issue
Block a user