🤖 Update init templates and supporting files for adept discovery

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.
This commit is contained in:
2026-09-18 15:03:32 +02:00
parent 2dc52e639d
commit c62d92ed2f
4 changed files with 82 additions and 33 deletions
+2
View File
@@ -39,3 +39,5 @@ Accretion is how the lab remembers; curation is how it stays readable. Igor appe
## Scope ## 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. 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.
@@ -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. --> - **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. --> - **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): - **Pinned agents** (prefer these over generic tiers):
<!-- List project-specific agents from `.claude/agents/` that should be preferred for certain task types. Example: <!-- 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 - `my-researcher` — research/bug investigation, writes reports, never modifies code
+78 -32
View File
@@ -163,24 +163,32 @@ named with a short kebab-case slug.
``` ```
adepts/ adepts/
CLAUDE.md ← you are here 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>/ <domain-slug>/
CLAUDE.md ← domain orientation, key files, conventions CLAUDE.md ← INDEX — frontmatter + tiered reading list. Short. Auto-loaded.
YYYY-MM-DD-HH-journal-*.md ← session journals from adept work 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 ## Conventions
- **One domain per folder.** If two domains overlap, pick the stricter scope. - **One domain per folder.** Overlap → pick the stricter scope. Broad names are gravity wells.
Broad names are gravity wells — prefer specificity. - **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.
- **CLAUDE.md is the handoff document.** When an adept spawns into an existing - **Every file in the domain root is listed in CLAUDE.md.** Unlisted files do not exist.
domain, it reads this file first. Write it for your successor, not yourself. - **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.
- **Journals are append-only.** Each session gets a new journal entry. Include - **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.
what you found, what you changed, what's still unclear, and what steps you - **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.
took to orient (files read, searches run, what was useful vs. noise). - **Don't hoard.** Findings that belong in the project's docs or a workpad report go there; link from here.
- **Don't hoard.** If a finding belongs in the project's main docs or workpad - **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.
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.
``` ```
### 4.3 — Write `adepts/_template/CLAUDE.md` ### 4.3 — Write `adepts/_template/CLAUDE.md`
@@ -191,39 +199,76 @@ If `${WORKPAD}/adepts/_template/CLAUDE.md` already exists and contains
```markdown ```markdown
--- ---
status: generated 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> # <Domain Name>
<!-- Replace this heading with the domain name. Fill in the sections below <!-- Replace this heading and fill the frontmatter during genesis orientation.
during your 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 ## Must-read
as a separate domain. -->
## 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. - `handoff.md` — where the previous adept left things. Always first.
Include paths relative to the repo root. --> - `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 | ## Good-to-read-if
|------|-----------|
| <!-- e.g. src/auth/ --> | <!-- e.g. Authentication module --> |
## Conventions <!-- State the condition for each entry. -->
<!-- Domain-specific conventions: naming patterns, error handling style, <!-- - `architecture.md` — if asked how the pieces fit, or where a new thing should go. -->
testing expectations, dependency rules. Only note things that differ <!-- - `gotchas.md` — if asked why something behaves oddly. -->
from or add to the project-wide conventions. --> - `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 ## Open questions
<!-- Things the founding adept couldn't resolve. Future adepts should Carried forward by predecessors. Try to resolve one before adding one.
attempt these before adding new ones. Remove entries as they're
answered. -->
- <!-- 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` - `.claude/spire/project.md`
- `${WORKPAD}/adepts/CLAUDE.md` - `${WORKPAD}/adepts/CLAUDE.md`
- `${WORKPAD}/adepts/_template/CLAUDE.md` - `${WORKPAD}/adepts/_template/CLAUDE.md`
- `${WORKPAD}/adepts/_template/handoff.md`
- `.claude/skills/assistant/SKILL.md` (if created in Phase 6) - `.claude/skills/assistant/SKILL.md` (if created in Phase 6)
2. Commit with message: `🤖 Initialize Spire project config` 2. Commit with message: `🤖 Initialize Spire project config`
+1
View File
@@ -41,6 +41,7 @@ It may also contain any of these, created on demand:
- `research/` — external research, library evaluations, prior art - `research/` — external research, library evaluations, prior art
- `specs/` — frozen, unchanging specifications - `specs/` — frozen, unchanging specifications
- `tickets/` — per-ticket scratch space, one subfolder per ticket id (see "Ticket context") - `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. 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.