🤖 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:
@@ -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
|
||||||
|
|||||||
@@ -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`
|
||||||
|
|
||||||
|
|||||||
@@ -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.
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user