|
|
|
@@ -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`
|
|
|
|
|
|
|
|
|
|
