# Handoff: Spire guidance pass + gremlins MVP wiring

**From**: Igor, session [2026-10-15-21-grotto-work](../journals/2026-10-15-21-grotto-work.md), 2026-10-17 00:04
**For**: a dedicated coordinator. This is Spire self-maintenance, so `spire:zathras` (`/spire:zathras guidance-pass`) is the natural fit; an Igor works too.
**Status**: not started. Every decision marked *(user)* needs the user's answer before it's built.

## Why

The headless-forks build ([post-mortem](../reports/2026-10-16-23-headless-forks-postmortem.md)) delivered 4,155 lines where about 600–800 were needed, in ~9 active hours. Half of the root causes are in the guidance text itself ([text audit](../reports/2026-10-16-23-spire-guidance-text-audit.md)):
- Single sentences steer toward completeness and audit-style output ("answer every … flag … one by one", "hunt", eight-field handoff notes with no length cap, an attacker asked for more scope).
- Nothing steers toward the structure and size the requirement needs.
- About 23% filler, 9% general knowledge, and rules repeated up to 11 times.
- Stale text, such as the Agent-tool fork in athanor.md:32.
- Planner, attacker and reviewer carry about 83% preloaded text from other skills.

The gremlins MVP (branch `gremlins-mvp`, 972 lines, built by gremlins in 21 min) worked first time. The guidance should make that path the normal one.

## Inputs (read these, nothing else up front)

1. reports/2026-10-16-23-spire-guidance-text-audit.md: per-file sizes, a/b/c/d/e classes, duplication table, steering list, lean target sizes. **The main work list.**
2. reports/2026-10-16-23-headless-forks-postmortem.md: root causes and the 14 lesson options.
3. brainstorm/2026-10-16-22-grotto-plan-structure.md: the user's thinking. Especially **"Steering sentences cut both ways"**: don't fix over-building with "small / happy path / delete", which can fire the other way. Use the safer framing listed there.
4. On branch `gremlins-mvp`: `plugins/spire/skills/gremlins/SKILL.md` and docs/workpad/reports/2026-10-17-gremlins-mvp-review.md.

## Scope: four parts, in this order

### A. Wire gremlins into the Athanor (small, mechanical)
- athanor.md and implementation SKILL.md: replace the Agent-tool "fork of yourself" path (athanor.md:32, implementation SKILL.md:45-50) with the gremlins path:
  - train one base on plan, design and trunk;
  - `spawn` per complex block via Bash `run_in_background`;
  - stop a gremlin with `TaskStop`;
  - fresh Agent-tool agents stay for mechanical blocks.
- Add the gremlins skill to the Athanor's preloaded skills.
- igor/SKILL.md:66 "Fork sparingly": reword or drop it; it refers to the dead Agent-tool fork.
- Done when no Spire text tells an agent to Agent-tool-fork itself, and the Athanor's procedure names the gremlins call sequence in ≤ ~15 lines (details stay in gremlins/SKILL.md).

### B. Stale and contradicting text (audit class e)
- zathras SKILL:74 "Always pass `model`" contradicts the pin rule.
- The injected `.claude/spire/project.md`: its agent list lacks planner, attacker and reviewer; it has no `## Build` section; it still lists g4b_ai as legacy.
- Everything else in the audit's class-e table.

### C. Steering sentences (audit §4): the part that changes behaviour
Rewrite, don't just delete, using the brainstorm's safer framing:
- **reviewer.md:22** "answer every deviation and flag … one by one". Move to: findings first; flags answered only where they change a verdict; a size and unrequested-surface section where the decision stays with the user.
- **run-log.md:54** and the eight-field handoff note: give it a length expectation; findings, not narration.
- **attacker.md:25** "missing function … error handling, security", which conflicts with :33 "scope cut back to the goal". Tie it to the goal's boxes.
- **Planner:** plans fix **code structure** (modules, data model, main interfaces) and include an **ecosystem inventory** (what harness, CLI output, stdlib and existing tools already provide) before anything is designed to be built. These are grotto lessons. Put them here now; grotto can lift them later.
- **Igor and Athanor:** briefs carry a time budget; re-plan when a preflight removes a design premise; mechanical blocks get a cheaper model; a fresh Athanor per phase; check the self-written contract digest before building.
- Each changed sentence gets its counterweight in the same sentence (see the brainstorm).

### D. Size and duplication (audit classes c and d, §3, §5)
- Stop preloading workpad and implementation into planner, attacker and reviewer. Their briefs name the output paths. Audit target: ~500–800 words each.
- One home per repeated rule ("stamp the model id" ×11, leaf-brief ×11, delegation ×9, test cadence ×7). Other files point to it in one line.
- Igor persona and mindset: trim to the audit's moderate target (~4k words for the boot bundle). *(user)* how much of the voice to keep.
- Remove general knowledge the model already has (audit class c quotes).

## Decisions needed from the user *(user)*

1. **The 15 unjustified unrequested items** in the MVP (review §2). Keep, cut, or keep with a reason. The build report justified the other 15 of 30. Candidates the coordinator can propose a default for: unused stream fields and the leftover `SPIRE_GREMLIN_CHILD` marker (cut), `briefs/<job>.md` (keep, useful for debugging), torn-line ledger repair (keep).
2. **Merge order:** merge `gremlins-mvp` first and do A on main, or do A on the MVP branch. The `headless-forks` branch stays an unmerged prototype record either way.
3. **Version:** 0.3.0 for MVP plus guidance pass together, or MVP alone first.
4. How far to trim Igor's persona (D).
5. **The three live checks still open on the MVP:** TaskStop on an MVP spawn, `rebase`, a WSL or Linux run. Before the merge or after.

### Answered 2026-10-17 (user)

- **Decision 1:** keep the useful items, throw out the ones that aren't useful. The coordinator applies that per item, using review §2's list, and records the keep/cut call for each with a one-line reason in its report. Commit before cutting.
- **Part A is confirmed:** bring gremlins into the Athanor.
- **Decision 2:** apply the decision-1 cuts and the pre-merge check, merge `gremlins-mvp`, then do A on main.
- **Decision 3:** 0.3.0 for MVP plus guidance pass together, one bump at the end.
- **Decision 4:** moderate (audit option I-2): Voice cut to ~150 words; drop the example flourishes, "yeth, marthter", the furnace grammar rule, mindset.md's editor note, repeated delegation lines, history and Pinky. Workpad stays preloaded.
- **Decision 5:** `TaskStop` on an MVP spawn before the merge; `rebase` and a WSL/Linux run after.
- Steering proof run: not taken (no answer; default skip).

## How to run it (lessons applied)

- **Timebox:** A + B ≈ 30 min; C ≈ 45 min; D ≈ 45 min. One agent per part. Text is small, so a cold start is cheap. Sonnet for B and the mechanical parts of D; Opus for C.
- **Order matters:** C before D, so the trimmed text keeps the new steering.
- **Commit before deleting text,** so the history keeps every line.
- **One review at the end,** asking: did each bundle reach its target size, did any rule lose its only home, and does any new sentence over-steer the other way? No per-part review loops.
- **Proof that the steering changed (optional, cheap):** re-run the experiment's planning step, or a small plan, before and after C, and compare plan size and structure. *(user)* whether to spend the run.
- Accretion rule for Igor still holds: dated refinement sections in existing docs; compression is the curator's job. This pass **is** a deliberate compression, run as Spire maintenance, which is why Zathras fits.

## Out of scope

- Grotto itself (design → plan → handoff procedure, standalone storage). Use this pass's planner changes as input.
- The Rust session-harness app (reports/2026-10-16-01-session-harness-app-forms.md).
- Fixing the `headless-forks` prototype.