council/CLAUDE.md

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.