From 2a27c10cdeaf699b2080d7a4c519f2b3daec2ce7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gabor=20K=C3=B6rber?= Date: Tue, 22 Sep 2026 13:53:14 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=A4=96=20Wire=20development=20cycle=20int?= =?UTF-8?q?o=20Spire=20skills=20and=20agents?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Igor now has a Development Cycle section with six stages, review decision tree, Athanor queuing rules, and separation principle. Athanor, implementation, research, and research-tree skills all reference their cycle stage. Fixed remaining Athanor metaphor inversions in the plugin design spec. --- .../designs/2026-09-14-plugin-design-spec.md | 4 ++-- .../journals/2026-09-21-14-agent-rails.md | 3 +++ .../reports/2026-09-22-01-cycle-wiring.md | 18 ++++++++++++++++ plugins/spire/agents/athanor.md | 3 +++ plugins/spire/skills/igor/SKILL.md | 21 +++++++++++++++++++ plugins/spire/skills/implementation/SKILL.md | 2 ++ plugins/spire/skills/research-tree/SKILL.md | 2 ++ plugins/spire/skills/research/SKILL.md | 2 ++ 8 files changed, 53 insertions(+), 2 deletions(-) create mode 100644 docs/workpad/reports/2026-09-22-01-cycle-wiring.md diff --git a/docs/workpad/designs/2026-09-14-plugin-design-spec.md b/docs/workpad/designs/2026-09-14-plugin-design-spec.md index 9a382b7..daf49f0 100644 --- a/docs/workpad/designs/2026-09-14-plugin-design-spec.md +++ b/docs/workpad/designs/2026-09-14-plugin-design-spec.md @@ -17,7 +17,7 @@ This plugin replaces `g4b_ai` (v0.2.0), which is a flat collection of five skill | **Igor** | Session coordinator. Talks to the user, delegates work, keeps a journal, spawns adepts, routes to the athanor. | Built | `.claude/skills/assistant/` + `.claude/agents/assistant.md` (warpspace) | `skills/igor/` + `agents/igor.md` | | **Adept** | Domain-scoped knowledge agent. Orients on a domain, accumulates journals and CLAUDE.md, answers consultations, dies with the session but leaves knowledge behind. | Built | `.claude/agents/adept.md` (warpspace) | `agents/adept.md` | | **Tome** | Knowledge layer. Navigate (orient before work), curate (six methods for growing the wiki), check (validate health), handoff (post-work impact), init (bootstrap). Project-overlay pattern: generic `tome` + project-specific `-tome` mutation. | Built | `.claude/skills/tome/` (warpspace, standalone) | `skills/tome/` (absorbed into plugin) | -| **Athanor** | Dispatching orchestrator. Receives a brief, decomposes it, fans out subagents by tier, synthesizes results. The alchemist's slow furnace — "put it in the oven" is the colloquial shorthand. | Built | `.claude/agents/dispatching-orchestrator.md` (warpspace) | `agents/athanor.md` | +| **Athanor** | Dispatching orchestrator. Receives a brief, decomposes it, fans out subagents by tier, synthesizes results. The alchemist's slow furnace — plans go into the Athanor and implementations come out. | Built | `.claude/agents/dispatching-orchestrator.md` (warpspace) | `agents/athanor.md` | | **Workpad** | Document placement. Resolves where reports, plans, goals, journals go. Steers other skills to a single location. | Built | `skills/workpad/` (g4b_ai) | `skills/workpad/` | | **Research-tree** | Multi-topic research as a phased dependency tree. | Built | `skills/research-tree/` (g4b_ai) | `skills/research-tree/` | | **Research** | Research governance. Agent spawning rules, web fetch budgets, tier selection. | Built | `skills/research/` (g4b_ai) | `skills/research/` | @@ -142,6 +142,6 @@ The spire is raised wherever the alchemist lands. It's not a product — it's th | **Igor** | Session coordinator | Pratchett | The clan of brilliant assistants | | **Adept** | Domain knowledge agent | Alchemical | Skill through practice, not innate authority | | **Tome** | Knowledge layer | Medieval | Institutional memory | -| **Athanor** | Dispatching orchestrator | Alchemical | The slow furnace — "put it in the oven" | +| **Athanor** | Dispatching orchestrator | Alchemical | The slow furnace — plans go into the Athanor | | **Pinky** | Brainstorm catalyst | Warner Bros. | The fool whose instincts are right | | **Zathras** | Self-maintenance | Babylon 5 | The tireless machine-tender | diff --git a/docs/workpad/journals/2026-09-21-14-agent-rails.md b/docs/workpad/journals/2026-09-21-14-agent-rails.md index ca6be42..80a0a26 100644 --- a/docs/workpad/journals/2026-09-21-14-agent-rails.md +++ b/docs/workpad/journals/2026-09-21-14-agent-rails.md @@ -14,6 +14,8 @@ - 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. +- 00:05 — Gap analysis: cycle design exists but no skill/agent references it. Six files need wiring. +- 00:07 — Opus agent dispatched to wire cycle into skills. Returned: Igor got full Development Cycle section (stages, decision tree, queuing, separation rule). Athanor got 3 operating-rule bullets (queue, commit, no self-review). Implementation, research, research-tree got framing notes. Plugin design spec Athanor metaphor fixed (2 instances). ## Adepts @@ -24,6 +26,7 @@ No domain adepts active. Roster is empty (no domain folders yet). - `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) +- `docs/workpad/reports/2026-09-22-01-cycle-wiring.md` — Cycle wiring report ## Open threads diff --git a/docs/workpad/reports/2026-09-22-01-cycle-wiring.md b/docs/workpad/reports/2026-09-22-01-cycle-wiring.md new file mode 100644 index 0000000..46ea94d --- /dev/null +++ b/docs/workpad/reports/2026-09-22-01-cycle-wiring.md @@ -0,0 +1,18 @@ +# Report: Development Cycle Wiring + +**Date:** 2026-09-22 +**Source:** `designs/2026-09-22-development-cycle.md` + +## Changes + +1. **`plugins/spire/skills/igor/SKILL.md`** — Added `## Development Cycle` section between Delegation and Adepts. Covers: six stages with Igor as router, review decision tree (five outcomes), Athanor queuing rules (sequential, hold queue, TaskStop on invalidation), separation rule, exit heuristic, cycle-workpad relationship. ~250 words. + +2. **`plugins/spire/agents/athanor.md`** — Added three bullet points to Operating rules: Igor holds the queue (one plan at a time), commit per plan step on branch, output goes to a fresh reviewer (no self-review). + +3. **`plugins/spire/skills/implementation/SKILL.md`** — Added cycle framing note after intro: this skill governs Stage 5, Athanor receives a plan not a conversation, output goes to Stage 6 reviewer. + +4. **`plugins/spire/skills/research/SKILL.md`** — Added cycle framing note: research is Stage 2 or a loop-back from Stage 6; output feeds Stage 3. + +5. **`plugins/spire/skills/research-tree/SKILL.md`** — Added one-line framing note: structured form of Stage 2, output feeds Stage 3. + +6. **`docs/workpad/designs/2026-09-14-plugin-design-spec.md`** — Fixed two instances of old Athanor metaphor ("put it in the oven") to match corrected metaphor (plans go into the Athanor). diff --git a/plugins/spire/agents/athanor.md b/plugins/spire/agents/athanor.md index 2aad95e..3157b71 100644 --- a/plugins/spire/agents/athanor.md +++ b/plugins/spire/agents/athanor.md @@ -34,6 +34,9 @@ Project-specific knowledge is loaded by the `spire:project` skill at agent start - **Verify before claiming.** Implementation tasks are not done until the project's check/test commands have been run for the affected areas — delegate the run to a Haiku subagent if convenient — and the result is stated with evidence. - **Prefer working on main.** Markdown-only work (workpad files, docs, reports) happens directly on `main` — no worktree. Use a worktree branch only when the brief is a code implementation run that needs isolation (especially if another impl run is in flight) or the brief asks for one. - **Stay in your lane.** Work only within the brief's scope and the branch/worktree you were given or chose per the rule above. Never open pull requests; push code branches if instructed, never force-push. +- **Igor holds the queue.** You process one plan at a time. If another plan is waiting, Igor dispatches it after you report back. +- **Commit per plan step** on your branch. Each step's result is committed before the next begins. +- **Output goes to a fresh reviewer.** Your deliverable (diff + plan reference) is reviewed by an independent agent in Stage 6 — never by you. Do not self-review. ## Deliverable diff --git a/plugins/spire/skills/igor/SKILL.md b/plugins/spire/skills/igor/SKILL.md index 1ed21ee..d3b8909 100644 --- a/plugins/spire/skills/igor/SKILL.md +++ b/plugins/spire/skills/igor/SKILL.md @@ -88,6 +88,27 @@ The `athanor` is the forge — your heavy lifter. An Opus-tier agent that may us **Model must be explicit.** Always pass `model` on `Agent` calls (`"opus"`, `"sonnet"`, `"haiku"`) — omitting it inherits the coordinator's model, which may be Fable. Subagents are Opus or lower; never dispatch a Fable-tier subagent unless the user explicitly asks. +## Development Cycle + +Igor routes work through six stages. Not every task enters the cycle — one-off fixes, ad-hoc questions, and maintenance stay outside it. The line: if writing the plan would take longer than doing the work, it is not in the cycle. + +**Stages:** (1) Brainstorm — Igor with user or Pinky; skip when direction is clear. (2) Research — researcher/adept answers open questions. (3) Design — independent Opus agent produces one buildable approach. (4) Plan — independent Opus agent (never the designer) produces steps with completion criteria. (5) Implement — the Athanor receives the plan; code comes out. (6) Review — fresh Opus reviewer measures output against plan and design. + +**Separation rule:** Plans and designs are always written by independent agents. The author of a plan never implements it; the author of a design never plans from it. Separation keeps review honest. + +**Review decision tree:** Igor routes the outcome: +1. None or low findings only — done. Lows stay in the report; never loop for lows. +2. Any medium or high — collect findings into a new plan (stage 4). The normal short loop. +3. Approach is wrong, not the code — back to design (stage 3). Append a dated amendment. +4. Unresearched unknown surfaced — back to research (stage 2). Only for a genuinely new problem space. +5. Goal is wrong — stop. User's call. + +Default to the shortest loop that fits; long loops need a stated reason. + +**Athanor queuing:** Plans enter sequentially; Igor holds the queue. A new plan arriving mid-run waits — the door is closed. If a new plan invalidates the one cooking, Igor stops the run (`TaskStop`), shelves partial output, and dispatches the replacement. Parallel Athanors only for disjoint code in separate worktrees; default is one. + +**Cycle and workpad:** Each stage writes to its folder; moving forward creates a new file, never mutates the previous one. The folder trail is the record. + ## Adepts Adepts are domain-scoped knowledge agents that persist within a session. They accumulate knowledge in the workpad's `adepts//` folders — an index (`CLAUDE.md`), a rolling handoff (`handoff.md`), knowledge docs, and a `journal/` subfolder. diff --git a/plugins/spire/skills/implementation/SKILL.md b/plugins/spire/skills/implementation/SKILL.md index 47f6a89..ca51ec1 100644 --- a/plugins/spire/skills/implementation/SKILL.md +++ b/plugins/spire/skills/implementation/SKILL.md @@ -7,6 +7,8 @@ description: Orchestrate non-trivial implementation work across one or more agen This skill is about **how to drive implementation work**, not about how to write code. It covers: when to delegate to subagents vs. work inline, how to sequence agents, how to handle test/compile failures, and how to approach bugs without thrashing. +**Cycle context:** This skill governs what happens inside Stage 5 (Implement) of the development cycle. The Athanor receives a plan, not a conversation — no mid-run questions. Its output (diff + plan reference) goes to a fresh reviewer for Stage 6 (Review). + ## Default to sequence, not parallel Implementation work is almost always **sequential** by nature — later changes depend on earlier ones, even when they look independent on paper. Two agents editing the same file in parallel is a merge conflict; two agents touching adjacent abstractions in parallel is a subtle integration bug. diff --git a/plugins/spire/skills/research-tree/SKILL.md b/plugins/spire/skills/research-tree/SKILL.md index 3f18a5e..d86c63a 100644 --- a/plugins/spire/skills/research-tree/SKILL.md +++ b/plugins/spire/skills/research-tree/SKILL.md @@ -5,6 +5,8 @@ description: Orchestrate multi-topic research as a dependency tree of parallel p # Research Tree +**Cycle context:** Research-tree is the structured form of Stage 2; its output feeds Stage 3 (design). + Most non-trivial research questions decompose into many sub-topics, and those sub-topics are *not* independent — later questions get sharper once earlier ones are answered. Running every sub-topic in parallel as peer agents wastes work and produces shallow, redundant findings. Running them strictly in series wastes wall-clock time. The right shape is a **tree of phases**: within a phase, agents run in parallel; between phases, later agents inherit the earlier reports. This skill describes how to plan and run that tree. It does not describe how to write the contents of an individual research report — that's up to the agent doing the writing, plus whatever conventions the project has. diff --git a/plugins/spire/skills/research/SKILL.md b/plugins/spire/skills/research/SKILL.md index a79de3d..0b090fe 100644 --- a/plugins/spire/skills/research/SKILL.md +++ b/plugins/spire/skills/research/SKILL.md @@ -7,6 +7,8 @@ description: Governs how research is conducted — bounded agent spawning, no re This skill regulates **how** research agents behave. It does not replace research-tree (which governs the **structure** of multi-topic research) or workpad (which governs **where** output goes). It layers on top of both. +**Cycle context:** Research may be invoked as Stage 2 of the development cycle, or as a loop-back from review (Stage 6) when an unresearched unknown surfaces. Its output feeds into design (Stage 3). + ## The core problem this solves Without governance, a research agent can spawn sub-agents, which spawn more sub-agents, which each scrape entire websites. A simple "research X" request balloons into 10–20 agents crawling dozens of pages. That is not research — it is runaway resource consumption that produces shallow, redundant findings.