diff --git a/docs/workpad/journals/2026-10-15-21-grotto-work.md b/docs/workpad/journals/2026-10-15-21-grotto-work.md index 414f4df..f526012 100644 --- a/docs/workpad/journals/2026-10-15-21-grotto-work.md +++ b/docs/workpad/journals/2026-10-15-21-grotto-work.md @@ -251,6 +251,12 @@ - Line gap mostly form: 248 of the 362 extra lines are blanks, docstrings, comments and imports; logic is 724 vs 610. - No real bug; `init` validates twice. - Open items for the user: the three live checks (TaskStop, rebase, WSL/Linux), and the decision on the 15 unjustified items. +- 00:04 — User asked what the two open items mean, and for a guidance pass on the Spire skills from today's findings, possibly as a handoff. Igor wrote plans/2026-10-17-00-spire-guidance-pass-handoff.md: + - A: wire gremlins into the Athanor; + - B: stale text; + - C: steering sentences rewritten with the safer framing, plus the planner gets code structure and an ecosystem inventory; + - D: size and duplication. + - Plus 5 user decisions, timeboxes per part, one end review. Aimed at Zathras (Spire self-maintenance), or an Igor. ## Adepts diff --git a/docs/workpad/plans/2026-10-17-00-spire-guidance-pass-handoff.md b/docs/workpad/plans/2026-10-17-00-spire-guidance-pass-handoff.md new file mode 100644 index 0000000..88a85dd --- /dev/null +++ b/docs/workpad/plans/2026-10-17-00-spire-guidance-pass-handoff.md @@ -0,0 +1,78 @@ +# 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/.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. + +## 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.