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