📝 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.
2026-09-22 13:48:44 +02:00
parent bfa13312f0
commit 6655cab671
4 changed files with 173 additions and 0 deletions
@@ -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.