From 8876659e98d444dbd457bd89ddb510dbb300487a Mon Sep 17 00:00:00 2001 From: Jeroen Schweitzer Date: Sun, 19 Apr 2026 20:18:00 +0200 Subject: [PATCH] reframe CLAUDE.md around PKB-as-substrate with Council as lens MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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-, /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) --- CLAUDE.md | 36 ++++++++++++++++++++++++++++++------ 1 file changed, 30 insertions(+), 6 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 3b3489c..28ade13 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,11 +4,17 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## What this repo is -A "Council of 10" deliberation system. Ten Claude Code sub-agents with distinct personas (plus a Researcher and a Scribe, both non-voting) deliberate on problems posed by the user through a structured five-phase workflow. **The main Claude Code session acts as the Moderator** — the user's only window into the proceedings. +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. -The repo root is an Obsidian vault. Sessions are the core artefact of the project, one directory per session at `sessions//`. +Available lenses: +- **`/council `** — full multi-agent deliberation with research, debate, revision, vote. Archived at `sessions//`. +- **`/ask- `** — single-agent consult, 11 variants (10 voting members + `/ask-researcher` for Naima). Lightweight; no research, no debate, no vote. +- **`/reflect [--member ] [--days ] [--on ]`** — 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//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`. -The full design is archived at `docs/structure/initial-plan.md`. +Full design archived at `docs/structure/initial-plan.md`. ## Running a council session @@ -48,11 +54,21 @@ 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` — `/council` orchestration +- `.claude/commands/` — `council.md`, `ask-.md` × 11, `reflect.md`, `triage-inbox.md`, `review-week.md`, `review-month.md` - `members//` — per-member memory (`persona.md`, `journal.md`, `on-the-user.md`, `revisit.md`) -- `sessions//` — one directory per session (`brief.md`, `research/`, `initial-answers.md`, `revised-answers.md`, `votes.md`, `outcome.md`, `summary.md`) -- `council-sessions.base`, `council-members.base` — Obsidian Bases at the root +- `sessions//` — 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//` — 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 @@ -61,8 +77,16 @@ Each voting member reads every file in its `members//` directory at the st - Updates to `on-the-user.md` and `revisit.md` only when something non-obvious comes up. - One full session directory at `sessions//`. +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//` directory (or `sessions//research/` for the Researcher, `sessions//` 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 |