jpmschweitzerandClaude Opus 4.7
8876659e98
The repo is now a personal knowledge base with the Council built in as a high-power advisory layer, not a Council-first project that happens to have an Obsidian vault. The "What this repo is" section leads with the six lenses (/council, /ask-<member>, /reflect, /triage-inbox, /review-week, /review-month) rather than just /council. Directory map expanded to include daily/, inbox/ (+ raw/), notes/, projects/, reading/, reflections/, reviews/, _templates/, scripts/, and the five new Obsidian Bases. Setup docs pointed at from the directory list. Memory protocol gains a note that lightweight commands (/ask-*, /reflect) may opportunistically append to on-the-user.md — same "only if genuinely non-obvious" discipline as the Phase-5 memory batch, applied at smaller scale. Added a dedicated PKB-access section describing the sub-agent read rules and when PKB context is pulled vs. stayed-out-of (/council stays bounded; the lens commands pull selectively). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
110 lines
8.5 KiB
Markdown
110 lines
8.5 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## What this repo is
|
||
|
||
A personal knowledge base (PKB) with a **Council of 10** high-power advisory system built in. The repo root is an Obsidian vault. Content substrate = daily journal + permanent notes + project logs + reading notes + voice-capture inbox. The Council is one of several lenses applied to that substrate.
|
||
|
||
Available lenses:
|
||
- **`/council <question>`** — full multi-agent deliberation with research, debate, revision, vote. Archived at `sessions/<slug>/`.
|
||
- **`/ask-<member> <question>`** — single-agent consult, 11 variants (10 voting members + `/ask-researcher` for Naima). Lightweight; no research, no debate, no vote.
|
||
- **`/reflect [--member <slug>] [--days <N>] [--on <path>]`** — single-agent pattern-surface over recent daily notes or a specific note. Reflective, not prescriptive. Default reflector: Vale.
|
||
- **`/triage-inbox`** — a member (default Koskela) reviews fleeting notes in `inbox/` and proposes destinations (`daily/`, `notes/`, `projects/<slug>/log.md`, `reading/`); you approve in batch.
|
||
- **`/review-week`** — three-member (Koskela / Vale / Prochazka) structured weekly review archived at `reviews/YYYY-WNN_week.md`.
|
||
- **`/review-month`** — five-member (Okafor / Vale / Holt / Vaasa / Vire) monthly zoom-out at `reviews/YYYY-MM_month.md`.
|
||
|
||
Full design archived at `docs/structure/initial-plan.md`.
|
||
|
||
## Running a council session
|
||
|
||
`/council <problem>` — the only entry point. Orchestration lives in `.claude/commands/council.md`. Phases:
|
||
|
||
- **0. Context interview** — Moderator ↔ user via `AskUserQuestion`. Moderator writes `sessions/<slug>/brief.md`.
|
||
- **1. Pre-session research** — Researcher (Naima Quéré, Sonnet, only web-enabled sub-agent) writes `sessions/<slug>/research/<topic>.md` files off the brief. May flag `User clarification needed` before or during researching.
|
||
- **2. Initial answers** — 10 members, parallel, Sonnet — with brief + research package in hand. Members may flag `User clarification needed`; answers append to `brief.md` and flow into Phase 3 (Phase 2 is not re-run).
|
||
- **3. Debate + Revise** — 10 members, parallel, Opus (via `model` override in the `Agent` call). Members may flag `Research gap` (→ Researcher round 2) or `User clarification needed` (→ Moderator asks user). If either fires, **one bounded** second revision round happens.
|
||
- **4. Vote** — 10 members, parallel, Sonnet. Ballot is **transparent** (attributed by name). Self-votes allowed. Any last clarification flags are surfaced in `outcome.md` as open questions without re-running earlier phases.
|
||
- **5. Tally + Tie-break + Archive** — Moderator tallies. On tie: `AskUserQuestion` with tied full answers as option previews. Scribe (Haiku) writes `outcome.md`. Moderator writes `summary.md` — the readable session artefact with vote distribution, phrases that crystallized, influence map, confidence trajectory, and stats. Final Sonnet batch updates each member's `journal.md`.
|
||
|
||
## Moderator responsibilities (this is you — the main session)
|
||
|
||
The main Claude Code session is the Moderator. The user **cannot** see sub-agent tool calls, Read output, or inter-agent packets. You are their only window.
|
||
|
||
1. Narrate between phases — ≤ ~10 lines per update. State what just happened and what's next.
|
||
2. Run the Phase-0 interview via `AskUserQuestion` before the Council sees anything.
|
||
3. Consolidate `Research gap` and `User clarification needed` flags when they appear; re-invoke Researcher or `AskUserQuestion` as appropriate.
|
||
4. On vote ties, present tied answers via `AskUserQuestion` with full answers as option previews.
|
||
5. Never dump raw sub-agent output into user-facing text — always distil.
|
||
|
||
## Web access rule
|
||
|
||
Only the **Researcher** and the **Moderator** can use `WebSearch` / `WebFetch`. Council members cannot — they rely on the shared research files in `sessions/<slug>/research/`. Members who need more info raise `## Research gap` in Phase 3.
|
||
|
||
## User clarification is available in every phase
|
||
|
||
Any sub-agent may include a `## User clarification needed` section in their output, at any phase:
|
||
- **Phase 1 (Researcher)** — before or mid-research → Moderator asks user, appends answers, re-invokes Researcher once.
|
||
- **Phase 2 (Members)** — after initial answers → Moderator asks user, appends answers; updated brief flows into Phase 3 (Phase 2 is not re-run).
|
||
- **Phase 3 (Members)** — during debate → one bounded follow-up revision round.
|
||
- **Phase 4 (Voters)** — informational only; surfaced in `outcome.md` as "Open questions raised at vote" without re-running.
|
||
|
||
Hard cap: at most **one** follow-up revision round per session.
|
||
|
||
## Directory map
|
||
|
||
- `.claude/agents/council-*.md` — 10 voting members + `council-researcher.md` + `council-scribe.md`
|
||
- `.claude/commands/` — `council.md`, `ask-<slug>.md` × 11, `reflect.md`, `triage-inbox.md`, `review-week.md`, `review-month.md`
|
||
- `members/<slug>/` — per-member memory (`persona.md`, `journal.md`, `on-the-user.md`, `revisit.md`)
|
||
- `sessions/<slug>/` — formal deliberation archive (`brief.md`, `research/`, `initial-answers.md`, `revised-answers.md`, `votes.md`, `outcome.md`, `summary.md`)
|
||
- `daily/` — daily journal notes (one file per day)
|
||
- `inbox/` — fleeting-note landing zone (AudioPen drops, quick captures); `inbox/raw/` holds un-normalised input
|
||
- `notes/` — permanent notes (Zettelkasten-atomic)
|
||
- `projects/<slug>/` — project briefs and logs
|
||
- `reading/` — reading notes + highlights
|
||
- `reflections/` — output of `/reflect` and `/ask-* --save`
|
||
- `reviews/` — weekly and monthly review outputs
|
||
- `_templates/` — Obsidian note templates (ignored by Obsidian's graph)
|
||
- `scripts/` — operational scripts (AudioPen ingest, webhook receiver, systemd units) — ignored by Obsidian's graph
|
||
- `*.base` — Obsidian Bases at root (`council-sessions`, `council-members`, `notes`, `projects`, `reading`, `reflections`, `inbox`)
|
||
- `docs/structure/initial-plan.md` — archived design document
|
||
- `docs/setup/audiopen.md`, `docs/setup/sync.md` — out-of-repo setup guides (Tailscale Funnel, Syncthing, Gitea SSH)
|
||
|
||
## Memory protocol
|
||
|
||
Each voting member reads every file in its `members/<slug>/` directory at the start of every invocation. Every `/council` run produces:
|
||
- One `journal.md` entry per voting member (mandatory, via the Phase-5 memory batch).
|
||
- Updates to `on-the-user.md` and `revisit.md` only when something non-obvious comes up.
|
||
- One full session directory at `sessions/<slug>/`.
|
||
|
||
Lighter-weight commands (`/ask-*`, `/reflect`) may opportunistically append to a member's `on-the-user.md` if something non-obvious surfaced — no obligation.
|
||
|
||
Researcher and Scribe have persona files only — no journals.
|
||
|
||
## PKB access for sub-agents
|
||
|
||
Every voting member (and the Researcher) has **read access to the user's full knowledge base** — `daily/`, `inbox/`, `notes/`, `projects/`, `reading/`, `reflections/`, `reviews/`, all of `sessions/`. Write access remains scoped to each agent's own `members/<slug>/` directory (or `sessions/<slug>/research/` for the Researcher, `sessions/<slug>/` for the Scribe).
|
||
|
||
When invoked via `/council`, members stick to the brief + research package + debate packet. The PKB is for `/ask-*`, `/reflect`, `/triage-inbox`, `/review-week`, `/review-month`.
|
||
|
||
## Tool permissions per sub-agent
|
||
|
||
| Agent | Read | Write/Edit | WebSearch/WebFetch |
|
||
|---|---|---|---|
|
||
| Voting members (×10) | ✓ | only in own `members/<slug>/` | ✗ |
|
||
| Researcher (Naima Quéré) | ✓ | only in `sessions/<slug>/research/` | ✓ |
|
||
| Scribe (Ansel Voss) | ✓ | in `sessions/<slug>/` except `research/` | ✗ |
|
||
| Moderator (main session) | ✓ | anywhere | ✓ |
|
||
|
||
Path-level write scoping is a convention enforced in each system prompt — sub-agents share the filesystem, so the social contract matters.
|
||
|
||
## Obsidian conventions
|
||
|
||
Every markdown file under the vault has YAML frontmatter with a `type` property (`council-member`, `council-journal`, `council-brief`, `council-research`, `council-session`). Inter-document references use folder-qualified wikilinks (e.g. `[[members/vaasa/persona|Dr. Ingrid Vaasa]]`). Two `.base` files at the root provide table views.
|
||
|
||
## Modifying the council
|
||
|
||
- **Swap a voting member:** edit both `.claude/agents/council-<slug>.md` and `members/<slug>/persona.md` (mirror the changes).
|
||
- **Add a voting member:** create the agent def, seed `members/<newslug>/`, then update the roster and the "10 members" wording in `.claude/commands/council.md`.
|
||
- **Researcher and Scribe are singletons** — edit their files directly.
|