From c62d92ed2fef5e4f64518fb3ec350afde502d06c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gabor=20K=C3=B6rber?= <gab@g4b.org>
Date: Fri, 18 Sep 2026 15:03:32 +0200
Subject: [PATCH] =?UTF-8?q?=F0=9F=A4=96=20Update=20init=20templates=20and?=
 =?UTF-8?q?=20supporting=20files=20for=20adept=20discovery?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Rewrite init Phase 4: adepts/CLAUDE.md uses tiered conventions,
_template/CLAUDE.md becomes an index template with frontmatter, add
_template/handoff.md template. Update workpad skill with adepts/ folder,
project.md with roster reference, curator with adept scope note.
---
 plugins/spire/skills/curator/SKILL.md         |   2 +
 .../spire/skills/igor/references/project.md   |   2 +-
 plugins/spire/skills/init/SKILL.md            | 110 +++++++++++++-----
 plugins/spire/skills/workpad/SKILL.md         |   1 +
 4 files changed, 82 insertions(+), 33 deletions(-)

diff --git a/plugins/spire/skills/curator/SKILL.md b/plugins/spire/skills/curator/SKILL.md
index 208ad76..7c8a8c1 100644
--- a/plugins/spire/skills/curator/SKILL.md
+++ b/plugins/spire/skills/curator/SKILL.md
@@ -39,3 +39,5 @@ Accretion is how the lab remembers; curation is how it stays readable. Igor appe
 ## Scope
 
 This skill operates on individual files — workpad documents, adept CLAUDEs, skill files. It does not touch the wiki or knowledge layer; that is Tome's domain.
+
+**Adept knowledge docs** (`key-files.md`, `conventions.md`, `architecture.md`, `gotchas.md`, etc.) accrete refinement sections and are curator targets. `handoff.md` and `journal/` entries are **not** curator targets — `handoff.md` is overwritten by the living adept, and journals are append-only session records.
diff --git a/plugins/spire/skills/igor/references/project.md b/plugins/spire/skills/igor/references/project.md
index 563314b..996b2df 100644
--- a/plugins/spire/skills/igor/references/project.md
+++ b/plugins/spire/skills/igor/references/project.md
@@ -11,7 +11,7 @@ preload) changes.
 
 - **Tome skill**: <!-- e.g. `my-project-tome:navigate` — or remove this line if the project has no tome skill. Igor will orient via direct file reads instead. -->
 - **Workpad**: <!-- Workpad location, e.g. `docs/workpad/` with its subfolder structure (goals/, plans/, reports/, research/, designs/, journals/, bugs/, specs/, archive/, adepts/). Reference the workpad's AGENTS.md or README for formatting rules. -->
-- **Adepts**: <!-- Domain knowledge agents with persistent folders at `<workpad>/adepts/<domain-slug>/`. See Igor skill's Adepts section for spawning/consulting conventions. -->
+- **Adepts**: Listed by `spire:adepts` at boot. Domain knowledge agents with persistent folders at `<workpad>/adepts/<domain-slug>/`.
 - **Pinned agents** (prefer these over generic tiers):
   <!-- List project-specific agents from `.claude/agents/` that should be preferred for certain task types. Example:
   - `my-researcher` — research/bug investigation, writes reports, never modifies code
diff --git a/plugins/spire/skills/init/SKILL.md b/plugins/spire/skills/init/SKILL.md
index d9f2efd..f548c3e 100644
--- a/plugins/spire/skills/init/SKILL.md
+++ b/plugins/spire/skills/init/SKILL.md
@@ -163,24 +163,32 @@ named with a short kebab-case slug.
 ```
 adepts/
   CLAUDE.md              ← you are here
-  _template/CLAUDE.md    ← starter template for new domains
+  _template/             ← starter template; copied on founding
+    CLAUDE.md
+    handoff.md
   <domain-slug>/
-    CLAUDE.md            ← domain orientation, key files, conventions
-    YYYY-MM-DD-HH-journal-*.md  ← session journals from adept work
+    CLAUDE.md            ← INDEX — frontmatter + tiered reading list. Short. Auto-loaded.
+    handoff.md           ← rolling state for the successor. Overwritten, not appended.
+    key-files.md         ← solid knowledge docs — as many as the domain needs
+    conventions.md
+    architecture.md
+    gotchas.md
+    ...                  ← any other doc, provided it is listed in CLAUDE.md
+    journal/
+      YYYY-MM-DD-HH-genesis.md
+      YYYY-MM-DD-HH-<topic>.md
 ```
 
 ## Conventions
 
-- **One domain per folder.** If two domains overlap, pick the stricter scope.
-  Broad names are gravity wells — prefer specificity.
-- **CLAUDE.md is the handoff document.** When an adept spawns into an existing
-  domain, it reads this file first. Write it for your successor, not yourself.
-- **Journals are append-only.** Each session gets a new journal entry. Include
-  what you found, what you changed, what's still unclear, and what steps you
-  took to orient (files read, searches run, what was useful vs. noise).
-- **Don't hoard.** If a finding belongs in the project's main docs or workpad
-  reports, put it there and link from here. The adept folder is for domain
-  context that helps the next adept orient, not a shadow wiki.
+- **One domain per folder.** Overlap → pick the stricter scope. Broad names are gravity wells.
+- **CLAUDE.md is an index, not a document.** Frontmatter + tiered reading list + open questions. Under ~60 lines. It is auto-loaded whenever anything in the folder is read — keep it cheap.
+- **Every file in the domain root is listed in CLAUDE.md.** Unlisted files do not exist.
+- **handoff.md is overwritten, never appended.** Write it early, refresh it after anything significant. `verified-at` is the commit the solid docs were last checked against.
+- **journal/ is append-only.** One file per topic or session, `YYYY-MM-DD-HH-<topic>.md`. Recency and session counts are derived from these names — keep the prefix exact.
+- **Solid knowledge goes in docs; experiences go in the journal.** Branch observations stay in the journal (and handoff.md's "In flight") until the code is on main.
+- **Don't hoard.** Findings that belong in the project's docs or a workpad report go there; link from here.
+- **Metadata is derived.** Never hand-maintain counts, dates, or an index file. Declare `domain`, `summary`, `covers`, `related`, `status` once in frontmatter; the roster does the rest.
 ```
 
 ### 4.3 — Write `adepts/_template/CLAUDE.md`
@@ -191,39 +199,76 @@ If `${WORKPAD}/adepts/_template/CLAUDE.md` already exists and contains
 ```markdown
 ---
 status: generated
+domain: <Domain Name>
+summary: <One-line summary of what this domain covers.>
+covers:
+  - <path/to/main/source/>
+  - <path/to/tests/>
+related: []
+status: active
 ---
 # <Domain Name>
 
-<!-- Replace this heading with the domain name. Fill in the sections below
-     during your genesis orientation. -->
+<!-- Replace this heading and fill the frontmatter during genesis orientation.
+     This file is the index — keep it under ~60 lines. It is auto-loaded by
+     the harness whenever any file in this folder is read. -->
 
-## Domain
+<!-- One paragraph: scope, boundaries, what is and is not this domain. -->
 
-<!-- What this domain covers. One paragraph: scope, boundaries, why it exists
-     as a separate domain. -->
+## Must-read
 
-## Key files
+Every genesis, before answering anything. Keep this list to three or four entries.
 
-<!-- Files and directories central to this domain. Use a table or bullet list.
-     Include paths relative to the repo root. -->
+- `handoff.md` — where the previous adept left things. Always first.
+- `key-files.md` — the files that matter, what each does, where the seams are.
+<!-- - `conventions.md` — rules here that differ from the project-wide ones. -->
 
-| Path | What it is |
-|------|-----------|
-| <!-- e.g. src/auth/ --> | <!-- e.g. Authentication module --> |
+## Good-to-read-if
 
-## Conventions
+<!-- State the condition for each entry. -->
 
-<!-- Domain-specific conventions: naming patterns, error handling style,
-     testing expectations, dependency rules. Only note things that differ
-     from or add to the project-wide conventions. -->
+<!-- - `architecture.md` — if asked how the pieces fit, or where a new thing should go. -->
+<!-- - `gotchas.md` — if asked why something behaves oddly. -->
+- `journal/` — if `handoff.md` points at a specific entry, or a question touches a dead end noted there. Do not read the whole journal.
 
 ## Open questions
 
-<!-- Things the founding adept couldn't resolve. Future adepts should
-     attempt these before adding new ones. Remove entries as they're
-     answered. -->
+Carried forward by predecessors. Try to resolve one before adding one.
 
-- <!-- e.g. "Why does FooService bypass the standard auth middleware?" -->
+<!-- - "Why does FooService bypass the standard auth middleware?" (since YYYY-MM-DD) -->
+```
+
+### 4.4 — Write `adepts/_template/handoff.md`
+
+If `${WORKPAD}/adepts/_template/handoff.md` already exists and contains
+`status: authored`, skip it. Otherwise write:
+
+```markdown
+---
+status: generated
+updated: <YYYY-MM-DD-HH>
+session: <path to current session journal entry>
+branch: <current branch or worktree>
+verified-at: <commit SHA when solid docs were last checked against code>
+---
+# Handoff — <Domain Name>
+
+## State
+<!-- Where things stand. What is documented and verified, what is not. -->
+
+## In flight (experiences, not solid)
+<!-- Branch observations, unmerged work. These stay here until the code is on main. -->
+
+## Open threads
+<!-- Unfinished investigations, pending questions, next steps. -->
+
+## Successor: read first
+1. This file.
+2. `key-files.md` — most likely to have drifted.
+<!-- 3. `journal/<entry>.md` if a specific branch is still open. -->
+
+## Drift check
+    git log --oneline <verified-at>..HEAD -- '<path1>' '<path2>'
 ```
 
 ---
@@ -277,6 +322,7 @@ If `$INSTALL_TYPE` is **shared**:
    - `.claude/spire/project.md`
    - `${WORKPAD}/adepts/CLAUDE.md`
    - `${WORKPAD}/adepts/_template/CLAUDE.md`
+   - `${WORKPAD}/adepts/_template/handoff.md`
    - `.claude/skills/assistant/SKILL.md` (if created in Phase 6)
 2. Commit with message: `🤖 Initialize Spire project config`
 
diff --git a/plugins/spire/skills/workpad/SKILL.md b/plugins/spire/skills/workpad/SKILL.md
index 42ebd53..9e5a89d 100644
--- a/plugins/spire/skills/workpad/SKILL.md
+++ b/plugins/spire/skills/workpad/SKILL.md
@@ -41,6 +41,7 @@ It may also contain any of these, created on demand:
 - `research/` — external research, library evaluations, prior art
 - `specs/` — frozen, unchanging specifications
 - `tickets/` — per-ticket scratch space, one subfolder per ticket id (see "Ticket context")
+- `adepts/` — adept domain folders — see `spire:adepts`
 
 If one of these optional folders is needed and doesn't exist yet, create it. Don't create folders speculatively. Treat unknown folders as owned by the user and ignore them.