diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..0eff3fa --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,85 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## 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. + +The repo root is an Obsidian vault. Sessions are the core artefact of the project, one directory per session at `sessions//`. + +The full design is archived at `docs/structure/initial-plan.md`. + +## Running a council session + +`/council ` — the only entry point. Orchestration lives in `.claude/commands/council.md`. Phases: + +- **0. Context interview** — Moderator ↔ user via `AskUserQuestion`. Moderator writes `sessions//brief.md`. +- **1. Pre-session research** — Researcher (Naima Quéré, Sonnet, only web-enabled sub-agent) writes `sessions//research/.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`. 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//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` — `/council` orchestration +- `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`) +- `council-sessions.base`, `council-members.base` — Obsidian Bases at the root +- `docs/structure/initial-plan.md` — archived design document + +## Memory protocol + +Each voting member reads every file in its `members//` 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//`. + +Researcher and Scribe have persona files only — no journals. + +## Tool permissions per sub-agent + +| Agent | Read | Write/Edit | WebSearch/WebFetch | +|---|---|---|---| +| Voting members (×10) | ✓ | only in own `members//` | ✗ | +| Researcher (Naima Quéré) | ✓ | only in `sessions//research/` | ✓ | +| Scribe (Ansel Voss) | ✓ | in `sessions//` 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-.md` and `members//persona.md` (mirror the changes). +- **Add a voting member:** create the agent def, seed `members//`, then update the roster and the "10 members" wording in `.claude/commands/council.md`. +- **Researcher and Scribe are singletons** — edit their files directly. diff --git a/README.md b/README.md new file mode 100644 index 0000000..76ebe0d --- /dev/null +++ b/README.md @@ -0,0 +1,55 @@ +# Council + +A Claude Code deliberation system with a persistent memory layer, browsable as an Obsidian vault. + +You pose a question; a council of ten distinct personas (plus a Researcher and a Scribe) deliberates through a structured five-phase workflow, produces a voting table, and hands you the winning answer. Every session leaves a full transcript and persistent memory behind. + +## Quick start + +Inside the repo in Claude Code: + +``` +/council +``` + +The Moderator (the main Claude Code session) will interview you briefly for context, then kick off the Council. You'll be asked follow-up questions along the way — to clarify the brief, resolve research gaps, or break vote ties. At the end you get a voting table and the full winning answer; everything is archived to `sessions//`. + +## The Council + +10 voting members, wild eclectic mix: + +- **Elif Tavşan** — retired stage magician & cold-reading coach +- **Dr. Wren Okafor** — deep-sea marine biologist → systems ecologist +- **Magnus Holt** — bankruptcy lawyer → insolvency-law lecturer +- **Sister Beatrix Vale** — Benedictine nun → hospice counselor +- **Nikolai "Niko" Prochazka** — Soviet cosmonaut trainer → wilderness survival instructor +- **Dr. Ingrid Vaasa** — theoretical physicist (QFT) → independent researcher +- **Kai "Breaker" Lindholm** — pro skateboarder → skatepark architect +- **Cassian Vire** — investigative journalist → speculative-fiction novelist +- **Marcelo "Marco" Tintori** — trained painter → 20 years as a corrections officer +- **Mari Koskela** — marine engineer on cargo ships → anthropologist of maritime labor + +Plus two non-voting roles: + +- **Naima Quéré** (Researcher) — the only sub-agent with web access. +- **Ansel Voss** (Scribe) — transcribes proceedings and writes session files. + +See `council-members.base` for the full roster as a table view in Obsidian. + +## Browsing sessions in Obsidian + +Open this repo as an Obsidian vault. The two Bases at the root provide table views: + +- **`council-sessions.base`** — every session, sortable by date / winner / whether a tie happened. +- **`council-members.base`** — the full roster with prior jobs and lenses. + +Individual session files live at `sessions//`: +- `brief.md` — the Moderator's brief from the Phase-0 interview +- `research/*.md` — the Researcher's per-topic notes +- `initial-answers.md`, `revised-answers.md`, `votes.md` — phase transcripts +- `outcome.md` — the canonical session file (winner, tally, full winning answer) + +## Deeper docs + +- `CLAUDE.md` — guidance for Claude Code when working inside this repo +- `docs/structure/initial-plan.md` — the full design document diff --git a/docs/structure/initial-plan.md b/docs/structure/initial-plan.md new file mode 100644 index 0000000..c864cb5 --- /dev/null +++ b/docs/structure/initial-plan.md @@ -0,0 +1,592 @@ +# Plan: Council of 10 + Researcher + Scribe + Moderator + +## Context + +`/var/mnt/data/projects/council/` is empty. The user wants a Claude Code project — used from the CLI **and** opened as a single Obsidian vault rooted at the repo — that runs a structured multi-agent deliberation on problems posed by the user. + +Roles: + +- **Moderator** (the main Claude Code session) interviews the user for context, orchestrates phases, narrates visibly, and brokers tie-breaks. Only the Moderator talks to the user. +- **Researcher** (Naima Quéré, Sonnet) is the **only** sub-agent with web access. She runs a pre-session research pass off the brief, and is re-invoked on demand when members flag gaps during debate. Writes per-topic research notes into the session directory as a shared evidence base. +- **10 Voting Members** deliberate in three phases (initial answer → debate/revise → vote). Members **cannot** browse the web; they rely on the shared research package. +- **Scribe** (Ansel Voss, Haiku) transcribes the proceedings as phases complete, writes the canonical session files. +- **The User** answers the Phase 0 interview, answers any Phase 3 clarification questions raised by members, and breaks vote ties when they occur. + +Sessions are the core artefact — one directory per session at the repo root. + +### Decisions locked in during planning + +| Decision | Choice | +|---|---| +| Command trigger | `/council ` | +| Voting cast | 10 voting members, "wild eclectic mix" | +| Non-voting cast | Researcher (Sonnet) + Scribe (Haiku) | +| Voting | **Transparent** — answers attributed by name; self-votes allowed; ties → **user breaks the tie** | +| Models | Sonnet 4.6 for initial answers / vote / memory updates / Researcher; Opus 4.7 for debate/revise; Haiku 4.5 for Scribe | +| Research access | Only Researcher and Moderator have `WebSearch`/`WebFetch`. Members request research via Phase-3 flags. | +| Pre-session research | Moderator writes the brief after interview; Researcher immediately runs a pre-session research pass off the brief; members open Phase 2 with a ready-made research package. | +| Clarification flag | `User clarification needed` can be raised by **any** agent in **any** phase (Researcher in Phase 1, members in Phases 2 / 3 / 4). Moderator batches, asks the user via `AskUserQuestion`, and appends answers to `brief.md`. Phase-specific handling in the orchestration section. | +| Research-gap flag | `Research gap` can be raised by Researcher (before Phase 1) or members (Phase 3). Moderator consolidates and re-invokes the Researcher. Round-2 research files carry `round: 2`. | +| Follow-up loop bound | At most **one** bounded extra revision round in Phase 3 (triggered by Phase-2 or Phase-3 flags). Further flags in later rounds are logged to `outcome.md` as open questions, not acted on. | +| Storage | Repo root is the Obsidian vault; sessions at `sessions//` | +| Session slug | `YYYY-MM-DD_`; `-2`, `-3`, … appended on same-day collisions | +| Obsidian version | Assume ≥1.9 (Bases) | +| User visibility | User sees only Moderator narration. No raw tool output, no inter-agent packets. | + +## The Cast + +### 10 Voting Members (wild eclectic mix) + +| # | Name | Prior job(s) | Personality | Lens | +|---|---|---|---|---| +| 1 | **Elif Tavşan** | Retired stage magician & cold-reading coach | Playful, watchful, fond of misdirection | Spots sleight-of-hand in arguments; suspicious of "obvious" framings | +| 2 | **Dr. Wren Okafor** | Deep-sea marine biologist → systems ecologist | Calm, patient, thinks in decades | Feedback loops, unintended consequences, long-time-horizon reasoning | +| 3 | **Magnus Holt** | Bankruptcy lawyer → insolvency law lecturer | Dry, adversarial, pessimism as craft | Failure modes — "what happens when this breaks?" | +| 4 | **Sister Beatrix Vale** | Benedictine nun → hospice counselor | Gentle, unflappable, never moralizes | Meaning, grief, what actually matters | +| 5 | **Nikolai "Niko" Prochazka** | Soviet cosmonaut trainer → wilderness survival instructor | Blunt, impatient with abstractions | Operational execution, checklists, ruthless prioritization | +| 6 | **Dr. Ingrid Vaasa** | Theoretical physicist (QFT) → independent researcher | Abstracts aggressively, reaches for the simplest model | First-principles reasoning, toy models, symmetries/invariants | +| 7 | **Kai "Breaker" Lindholm** | Pro skateboarder → skatepark architect | Kinetic, improvisational, body-first thinker | Embodied intuition, iteration, "does it feel right?" | +| 8 | **Cassian Vire** | Investigative journalist → speculative-fiction novelist (doorstopper systems-SF; Stephenson × Hamilton flavor) | Restless, tangent-prone, maximalist; infodumps if un-moderated | Systems-level extrapolation across long horizons; civilizational-scale consequence-chaining | +| 9 | **Marcelo "Marco" Tintori** | Trained painter (Bologna) → 20 years as a corrections officer → runs a prison art program | Dry, darkly funny, slightly melancholy; allergic to piety | Institutional reality vs. theory; dignity of the specific; absurdity as a signal of misalignment | +| 10 | **Mari Koskela** | Marine engineer on cargo ships (12 years) → PhD anthropology of maritime labor → independent ethnographer | Patient, observant, dry humor; asks "what do they actually do?" before "what does the spec say?" | How humans actually inhabit the systems they build; practice vs. procedure; ritual, labor, power | + +Slugs: `tavsan`, `okafor`, `holt`, `vale`, `prochazka`, `vaasa`, `lindholm`, `vire`, `tintori`, `koskela`. + +### Non-voting: Researcher + +**Naima Quéré** — ex-investigative journalist → national-archive research librarian → independent OSINT analyst. Slug: `researcher`. Model: Sonnet. + +- Only sub-agent with `WebSearch` / `WebFetch`. +- Methodical, skeptical-but-fair; cites sources with URL + access date; flags conflicting evidence and uncertainty explicitly. +- Writes one file per topic into `sessions//research/`. +- Runs twice at most per session: Phase 1 (pre-research off the brief), and optionally Phase 3b (follow-up on research gaps flagged by members). +- **May flag `User clarification needed` at any point during Phase 1** — before starting (if the brief is too vague to research usefully), or mid-research (if ambiguity surfaces once she starts digging). Either way, she returns early with 1-3 concrete questions; Moderator asks the user via `AskUserQuestion`, appends answers to `brief.md`, then re-invokes her. +- Does not opine on the council's question. + +### Non-voting: Scribe + +**Ansel Voss** — former court stenographer and municipal archivist. Slug: `scribe`. Model: Haiku 4.5. + +- Writes canonical session files (`initial-answers.md`, `revised-answers.md`, `votes.md`, `outcome.md`) as phases complete. +- Neutral — verbatim where it matters, summarizing where it helps. Never editorializes. Keeps Obsidian frontmatter and wikilinks tidy. + +### Moderator + +**The main Claude Code session** (not a sub-agent). Responsibilities: + +1. **Phase 0**: 2-4 context questions to the user via `AskUserQuestion`. Writes `sessions//brief.md`. +2. **Phase 1**: invokes Researcher with the brief to produce the pre-session research package. +3. Narrates between phases (≤ ~10 lines per update). +4. **Phase 3**: collects `Research gap` and `User clarification needed` flags from members; runs Researcher and/or `AskUserQuestion` as needed; triggers one bounded second revision round if either fired. +5. **Phase 5**: tallies votes; on tie, presents tied answers to the user via `AskUserQuestion` (full answer as option preview). +6. Invokes Scribe and the memory-update batch. +7. Never prints raw tool-call output — always distils. + +## Architecture + +### Directory layout + +``` +council/ # ← repo root = Obsidian vault +├── CLAUDE.md # Claude Code guidance +├── README.md # Vault-facing overview +├── .claude/ +│ ├── agents/ +│ │ ├── council-tavsan.md # 10 voting members (model: sonnet) +│ │ ├── council-okafor.md +│ │ ├── council-holt.md +│ │ ├── council-vale.md +│ │ ├── council-prochazka.md +│ │ ├── council-vaasa.md +│ │ ├── council-lindholm.md +│ │ ├── council-vire.md +│ │ ├── council-tintori.md +│ │ ├── council-koskela.md +│ │ ├── council-researcher.md # Naima Quéré (sonnet, web tools) +│ │ └── council-scribe.md # Ansel Voss (haiku) +│ └── commands/ +│ └── council.md # /council orchestration +├── council-members.base # Obsidian Base: roster +├── council-sessions.base # Obsidian Base: session index +├── docs/ # meta-docs about this project (not live data) +│ └── structure/ +│ └── initial-plan.md # archived copy of this plan (step 1 of implementation) +├── members/ +│ ├── tavsan/ +│ │ ├── persona.md # character sheet + frontmatter +│ │ ├── journal.md # append-only session-log entries +│ │ ├── on-the-user.md # accumulated observations about the user +│ │ └── revisit.md # open questions/topics to come back to +│ ├── okafor/ +│ ├── holt/ +│ ├── vale/ +│ ├── prochazka/ +│ ├── vaasa/ +│ ├── lindholm/ +│ ├── vire/ +│ ├── tintori/ +│ ├── koskela/ +│ ├── researcher/ +│ │ └── persona.md # persona only — no journal +│ └── scribe/ +│ └── persona.md # persona only — no journal +└── sessions/ # ← the core of the repo + └── 2026-04-19_self-host-email/ # one dir per /council run + ├── brief.md # moderator writes (Phase 0) + ├── research/ # researcher writes (Phase 1 + optional 3b) + │ ├── fastmail-reliability.md + │ └── self-hosting-risks.md + ├── initial-answers.md # scribe: Phase 2 verbatim, attributed + ├── revised-answers.md # scribe: Phase 3 critiques + revised (round 1 + optional round 2) + ├── votes.md # scribe: Phase 4 votes + tally + └── outcome.md # scribe: canonical session file (Obsidian Base target) +``` + +`.claude/` can be hidden in Obsidian's file-explorer settings; it doesn't break anything if visible. Wikilinks are folder-qualified (e.g. `[[members/vaasa/persona|Dr. Ingrid Vaasa]]`, `[[sessions/2026-04-19_self-host-email/outcome|Self-host email?]]`). + +### Per-member memory layout + +Each voting member owns `members//`. Every file in that directory is read at the start of every invocation. + +**`persona.md`** — seed character sheet with frontmatter: + +```markdown +--- +type: council-member +slug: tavsan +name: "Elif Tavşan" +prior_job: "Retired stage magician & cold-reading coach" +lens: "Pattern recognition, misdirection, skepticism of the obvious" +voting: true +model: sonnet +--- + +# Elif Tavşan + +**Personality:** … +**Voice:** … +**Things she notices first:** … +``` + +**`journal.md`** — append-only; one entry per `/council` run (newest on top), with wikilinks to the session outcome and to members referenced. + +```markdown +--- +type: council-journal +slug: tavsan +--- + +# Journal — Elif Tavşan + +## 2026-04-19 — [[sessions/2026-04-19_self-host-email/outcome|Should I self-host my email?]] +- **Stance:** Let the vendor carry the risk; switch only when it bites. +- **Revised answer gist:** … +- **My vote:** [[members/vaasa/persona|Vaasa]] — simplest model; the rest was theatre. +- **Outcome:** Vaasa won 4-3-2-1. +- **Lesson:** I lean toward misdirection-spotting; useful for grand plans, noise on small ones. +``` + +**`on-the-user.md`** — slow-growing picture of the user; update only when something non-obvious comes up. + +**`revisit.md`** — checklist of questions/topics to come back to. + +Researcher and Scribe have only `persona.md` — they write session files, not journals. + +### Session directory layout + +**`sessions//brief.md`** — Moderator writes after Phase 0 interview: + +```markdown +--- +type: council-brief +date: 2026-04-19 +slug: 2026-04-19_self-host-email +problem: "Should I self-host my email or use Fastmail?" +--- + +# Brief — Should I self-host my email? + +## Question +{verbatim user prompt} + +## Clarifications from the Phase-0 interview +- Time pressure: none — exploring. +- Constraints: single user, €20/mo soft budget, comfortable with Linux admin. +- Decision criteria: reliability > cost > sovereignty. + +## Research threads to investigate (for the Researcher) +- Fastmail reliability + recent incidents +- Self-hosted-mail deliverability today (SPF/DKIM/DMARC, IP reputation) +- Migration cost and lock-in +- … + +## What a good answer looks like +A recommendation with the conditions under which the recommendation flips. + +## Additions from Phase-1 clarifications + + +## Additions from Phase-2 clarifications + + +## Additions from Phase-3 clarifications + +``` + +**`sessions//research/.md`** — Researcher writes, one per topic: + +```markdown +--- +type: council-research +session: 2026-04-19_self-host-email +topic: "Fastmail reliability" +round: 1 +--- + +# Fastmail reliability + +## Summary +One or two paragraphs — what the evidence says, in Naima's analytic voice. + +## Evidence +- [status.fastmail.com — incidents 2024–2026](https://status.fastmail.com/history) (accessed 2026-04-19) +- … + +## Uncertainty / conflicting sources +- … +``` + +Round-2 research files (from Phase 3b follow-ups) set `round: 2`. + +**`initial-answers.md`, `revised-answers.md`, `votes.md`** — Scribe writes after each phase. `revised-answers.md` has sections for Round 1 and (if any) Round 2. `votes.md` includes each member's vote + rationale and the tally. + +**`outcome.md`** — canonical session file (picked up by the Obsidian Base): + +```markdown +--- +type: council-session +date: 2026-04-19 +slug: 2026-04-19_self-host-email +problem: "Should I self-host my email or use Fastmail?" +participants: [tavsan, okafor, holt, vale, prochazka, vaasa, lindholm, vire, tintori, koskela] +winner: vaasa +tied: false +tie_broken_by_user: false +votes: {vaasa: 4, okafor: 3, vale: 2, tintori: 1} +had_research_gap_round: false +had_phase1_clarification: false +had_phase2_clarification: false +had_phase3_clarification: false +open_questions_at_vote: [] +tags: [email, self-hosting, infra] +--- + +# Outcome — Should I self-host my email? + +See [[brief]], [[initial-answers]], [[revised-answers]], [[votes]]. + +## Winner — [[members/vaasa/persona|Dr. Ingrid Vaasa]] (4 votes) + +{verbatim winning revised answer} + +## Vote tally +{table from votes.md} +``` + +### Obsidian Bases + +**`council-sessions.base`**: + +```yaml +filters: + and: + - note.type == "council-session" +properties: + note.date: {displayName: Date} + note.problem: {displayName: Question} + note.winner: {displayName: Winner} + note.tied: {displayName: Tied} + note.tie_broken_by_user: {displayName: User tiebreak?} + note.had_research_gap_round: {displayName: Extra research?} + note.had_phase1_clarification: {displayName: Phase-1 clarif?} + note.had_phase2_clarification: {displayName: Phase-2 clarif?} + note.had_phase3_clarification: {displayName: Phase-3 clarif?} + note.tags: {displayName: Tags} +views: + - type: table + name: All sessions + order: [file.name, note.date, note.problem, note.winner, note.tied, note.tags] + sort: + - property: note.date + direction: DESC +``` + +**`council-members.base`**: + +```yaml +filters: + and: + - note.type == "council-member" +properties: + note.name: {displayName: Name} + note.prior_job: {displayName: Prior job} + note.lens: {displayName: Lens} + note.voting: {displayName: Votes?} +views: + - type: table + name: The Council + order: [note.name, note.prior_job, note.lens, note.voting] +``` + +## Orchestration — `/council ` + +Load-bearing file: `.claude/commands/council.md`. Every phase produces an internal data flow (sub-agent calls) **and** visible user output (Moderator narration). + +### Phase 0 — Context interview (Moderator ↔ User) + +1. Moderator reads `$ARGUMENTS`, proposes a session slug (`YYYY-MM-DD_`), creates `sessions//`. +2. Generates 2-4 targeted clarifying questions via `AskUserQuestion`: constraints, time pressure, who's affected, decision criteria, what a good answer looks like. +3. Writes `sessions//brief.md` — problem, user's answers, constraints, a first-pass list of research threads. + +**User sees:** the clarifying questions, then: "Brief written to `sessions/.../brief.md`. Sending to the Researcher for a pre-session pass." + +### Phase 1 — Pre-session research (1 × Sonnet Researcher; may trigger user-clarification sub-step) + +Moderator invokes `council-researcher` with the brief. The Researcher is told: "You may return a `## User clarification needed` section at **any point during your work** — before starting (if the brief is too vague to research) or mid-research (if ambiguity surfaces as you dig). 1-3 concrete questions only the user can answer. If you have no clarifications, proceed to research and produce topic files." + +**If Researcher flags clarifications:** +- Moderator consolidates → `AskUserQuestion` (up to 4 questions) → appends answers to `brief.md` under `## Additions from Phase-1 clarifications` → re-invokes Researcher once (she now has the updated brief). Max one clarification round at this phase. + +**If Researcher proceeds:** +- Identifies 5-10 concrete topics from the brief's "Research threads" section (expanding where she thinks useful). +- Runs web searches; synthesizes. +- Writes one `sessions//research/.md` per topic (frontmatter `round: 1`). +- Returns a short table of contents. + +**User sees:** either the clarification question block (if Researcher flagged), then a confirmation, then: list of topics researched, file count, "Research package ready in `sessions/.../research/`. Handing to the Council." + +### Phase 2 — Initial Answer (10 × Sonnet, parallel; members may flag clarifications) + +10 `Agent` calls in parallel. Each member reads: the brief, all files in `sessions//research/`, its own `members//` files. Returns: +- `## Initial answer` (self-contained) +- `## Confidence (1-5)` +- Optional `## User clarification needed` — 1-2 concrete questions only the user can answer that would change the answer. Still produce the initial answer as the member's best current shot. + +Members **must** cite research-file filenames when a claim leans on them. + +**If any member raises clarifications:** Moderator consolidates + dedupes → `AskUserQuestion` (up to 4 questions) → appends answers to `brief.md` under `## Additions from Phase-2 clarifications`. The updated brief flows into Phase 3; Phase 2 is **not** re-run (cost avoidance — Phase 3 is where revision happens anyway). + +After collection, Moderator invokes Scribe to write `sessions//initial-answers.md` (verbatim, attributed, including any clarification flags raised). + +**User sees:** +> **Moderator:** 10 initial answers in. One-line summaries: +> - **Tavşan:** <≤15 words> +> - **Okafor:** <≤15 words> +> - … +> +> [if any clarifications were raised:] Clarifications requested from you — see next question block. +> (Moderator then hits `AskUserQuestion`.) +> +> Written to `initial-answers.md`. Moving to debate + revise on Opus. + +### Phase 3 — Debate + Revise (10 × Opus, parallel, with optional bounded follow-up) + +Moderator assembles the debate packet: the 10 attributed initial answers. Dispatches 10 `Agent` calls with `model: "opus"`, each given: +- problem + brief + research files + debate packet + own memory +- phase directive: + > Critique the other 9 (one paragraph each). Produce a `Revised answer` (self-contained). `What changed and why` (≤3 bullets). + > + > If information is missing and would change your answer, include **one or both**: + > - `## Research gap` — one or two specific, searchable questions. Be concrete. + > - `## User clarification needed` — one or two questions only the user can answer. + > + > Either way, still produce your `Revised answer` as your best current shot. + +**Moderator handling after Phase 3a returns:** +- **If any member raised `Research gap`:** Moderator consolidates gaps → dedupes → invokes Researcher for a second run, writing new files to `research/` with `round: 2`. +- **If any member raised `User clarification needed`:** Moderator consolidates the questions → uses `AskUserQuestion` with up to 4 questions → appends the user's answers to `brief.md` under `## Additions from Phase-3 clarifications`. +- **If either fired**, Moderator runs one **bounded second revision round** (10 × Opus): members see their first-round revised answer + the new information and produce a final revised answer. Hard cap at one follow-up loop; further flags in round 2 are noted but not acted on. + +Scribe writes `revised-answers.md` (with Round 1 and, if present, Round 2 sections). + +Outcome flags `had_research_gap_round` / `had_user_clarification_round` in `outcome.md` frontmatter reflect whether these fired. + +**User sees:** +> **Moderator:** Revisions in. Notable shifts: +> - **Tavşan:** held ground / softened on X / pivoted to Y +> - … +> +> Research gaps flagged by [members]: running round-2 research on [topics]. +> (or: "No research gaps or clarifications requested.") +> +> Clarifications requested from you — see next question block. +> (Moderator then hits `AskUserQuestion` with the consolidated clarification questions.) +> +> Moving to vote on Sonnet. + +### Phase 4 — Vote (10 × Sonnet, parallel, transparent; late clarifications noted but not acted on) + +Moderator assembles the ballot: the 10 final revised answers, **attributed by name** (no anonymization — per user: "the agents will be reading each other's arguments and will already have an idea who is saying what; anonymity mostly hides things from me"). + +Dispatches 10 `Agent` calls, each given: +- problem + brief + ballot (attributed) + own memory +- "Reply with `## Vote: ` on its own line (e.g. `## Vote: vaasa`), then `## Rationale` (one sentence). Self-votes are allowed. You may add an optional `## User clarification needed` section if something still bothers you — it will be surfaced to the user in the outcome as an open question, but will not delay the vote." + +Voter-raised clarifications at this point are **informational** — Moderator surfaces them in `outcome.md` under `## Open questions raised at vote` and does not re-run earlier phases. (Enforces the one-bounded-loop rule.) + +Scribe writes `votes.md` with each member's vote + rationale, any clarification flags, and the tally. + +### Phase 5 — Tally, tie-break, present, archive + +1. **Moderator tallies.** +2. **No tie:** prints voting table + full winning answer; invokes Scribe to write `outcome.md`. +3. **Tie:** Moderator calls `AskUserQuestion` — one option per tied answer. `description` = 1-paragraph scribe-style summary + key differentiator. `preview` = verbatim full answer. User picks → winner. `outcome.md` records `tied: true`, `tie_broken_by_user: true`. +4. **Memory update batch**: 10 parallel Sonnet `Agent` calls, each told the final outcome + their own vote + the winner; each appends to `members//journal.md` (and updates `on-the-user.md`/`revisit.md` if warranted). Returns one-line confirmations. + +**Final user output:** + +``` +| Voter | Voted for (snippet) | +|---|---| +| Elif Tavşan | Dr. Ingrid Vaasa — "Strip to the minimal model…" | +| Dr. Wren Okafor | Dr. Wren Okafor (self) — "Treat this as a coupled…" | +| Magnus Holt | Dr. Ingrid Vaasa — "Least hidden state, least failure" | +| Sister Vale | Dr. Wren Okafor — "The decision underneath the decision" | +| Niko Prochazka | Dr. Ingrid Vaasa — "Cleanest checklist" | +| Dr. Vaasa | Dr. Ingrid Vaasa (self) — "Toy model is the argument" | +| Kai Lindholm | Marcelo Tintori — "Feels human" | +| Cassian Vire | Dr. Wren Okafor — "Scales across a century" | +| Marcelo Tintori | Sister Vale — "Cuts the theatre" | +| Mari Koskela | Dr. Ingrid Vaasa — "Matches observed practice" | + +**Result:** Dr. Ingrid Vaasa wins with 4 votes. + +--- + +## Winning answer — Dr. Ingrid Vaasa + + + +--- + +Session logged → `sessions/2026-04-19_self-host-email/` +``` + +### Moderator output discipline + +- Each between-phase update ≤ ~10 lines. +- Never dumps raw sub-agent output or tool-call content. +- If the user asks "what did X say?" mid-flow or after, Moderator can print that specific member's full answer on request. +- On sub-agent errors/timeouts, surfaces which members failed and whether to retry or proceed with fewer. + +## Tool permissions per agent + +Enforced via each sub-agent's `tools:` frontmatter; reiterated in each system prompt. + +| Agent | Read | Write/Edit | Grep/Glob | WebSearch / WebFetch | +|---|---|---|---|---| +| Voting members (×10) | ✓ | only in own `members//` | ✓ | ✗ | +| Researcher (Naima Quéré) | ✓ | only in `sessions//research/` | ✓ | ✓ | +| Scribe (Ansel Voss) | ✓ | in `sessions//` except `research/` | ✓ | ✗ | +| Moderator (main session) | ✓ | anywhere | ✓ | ✓ | + +Path-level write scoping is a convention reinforced in each system prompt; Claude Code sub-agents share the filesystem, so the social contract matters. + +## CLAUDE.md content (sketch) + +```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 "Council of 10" deliberation system, with a dedicated Researcher and a Scribe, orchestrated by the main Claude Code session as Moderator. Sessions are the core artefact — one directory per session at `sessions//`. The repo root is an Obsidian vault. + +## Running a council session + +`/council ` — the only entry point. Orchestration in `.claude/commands/council.md`. Phases: + +- **0. Context interview** — Moderator ↔ user via `AskUserQuestion`. Moderator writes `sessions//brief.md`. +- **1. Pre-session research** — Researcher (Naima Quéré, Sonnet, only web-enabled sub-agent) writes `sessions//research/.md` files off the brief. May flag `User clarification needed` before researching if the brief is too vague. +- **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. 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 writes `outcome.md`. Final Sonnet batch updates each member's `journal.md`. + +## Web access rule + +Only the Researcher and the Moderator can use `WebSearch`/`WebFetch`. Council members cannot. Members who need more info flag it in Phase 3 via `## Research gap`. + +## User clarification is available in every phase + +Any agent may flag `## User clarification needed` in any phase (Researcher in Phase 1, members in Phases 2–4). The Moderator batches the questions, asks the user via `AskUserQuestion`, and appends the answers to `brief.md`. Handling depends on the phase: Phase 1 → re-run Researcher once; Phase 2 → updated brief flows into Phase 3; Phase 3 → one bounded follow-up revision round; Phase 4 → surfaced in `outcome.md` only, no re-run. + +## Moderator responsibilities + +The main Claude Code session is the Moderator — the user's only window into the proceedings: +1. Narrates between phases (≤ ~10 lines per update). +2. Runs the Phase-0 interview and the Phase-3 user-clarification sub-interviews. +3. Consolidates research-gap flags and re-invokes the Researcher when warranted. +4. On vote ties, presents tied full answers via `AskUserQuestion`. +5. Never prints raw tool output. + +## Directory map + +- `.claude/agents/council-*.md` — 10 voting members + `council-researcher.md` + `council-scribe.md` +- `.claude/commands/council.md` — `/council` orchestration +- `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`) +- `council-sessions.base`, `council-members.base` — Obsidian Bases at repo root + +## Memory protocol + +Each voting member reads every file in its `members//` 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 non-obvious. +- One full session directory at `sessions//`. + +Researcher and Scribe have persona files only; no journals. + +## Obsidian conventions + +Every markdown file has YAML frontmatter with a `type` property (`council-member`, `council-journal`, `council-brief`, `council-research`, `council-session`). Wikilinks are folder-qualified. Two `.base` files provide table views. + +## Modifying the council + +- Swap a voting member: edit `.claude/agents/council-.md` and `members//persona.md` (mirror both). +- Add a voting member: create the agent def, seed `members//`, update the roster (and the "10 members" count wording) in `.claude/commands/council.md`. +- Researcher and Scribe are singletons — edit their files directly. +``` + +## Verification + +After implementation, verify end-to-end: + +1. Run `/council "Should I self-host my email or use Fastmail?"` — expect: + - Phase 0 `AskUserQuestion` (2-4 questions); `sessions/2026-04-19_self-host-email/brief.md` appears. + - `sessions/.../research/*.md` files appear from the Researcher's pre-session pass. + - 10 distinct initial answers cited against research files. + - `revised-answers.md` with Round-1 revisions; if any member flagged a `Research gap` / `User clarification needed`, verify Round 2 + updated brief. + - Transparent vote: ballot shows authors; votes + rationale logged. + - `outcome.md` with complete frontmatter, wikilinks, and verbatim winning answer. + - Each of the 10 `members//journal.md` gains one new entry referencing the session. +2. `council-sessions.base` in Obsidian shows the new session (sorted by date DESC). +3. `council-members.base` shows all 10 voting members + Researcher + Scribe, with `voting: false` for the latter two. +4. Run a second, unrelated question (`/council "How do I tell my sister I'm not coming to her wedding?"`) — personas stay in character; memories from run 1 don't inappropriately bleed in; fresh session directory. +5. Force a close vote (or wait until one happens). On tie: Moderator hits `AskUserQuestion` with tied full answers as option previews; `outcome.md` records `tie_broken_by_user: true`. +6. Run a question that the Researcher clearly can't fully answer upfront; expect at least one member to raise a `Research gap`, Researcher to produce a round-2 file, and Round-2 revised answers to appear. +7. Verify no voting member has `WebSearch`/`WebFetch` in its `tools:` frontmatter; only Researcher does. +8. Confirm Moderator narration stays concise; no raw sub-agent output leaks into user-facing text. + +## Critical files to create (in order) + +1. **`docs/structure/initial-plan.md`** — copy of this plan archived into the repo, so it lives alongside what it describes. Written first thing when implementation starts. +2. `CLAUDE.md`, `README.md` +3. `.claude/agents/council-tavsan.md` … `council-koskela.md` (10 voting members) +4. `.claude/agents/council-researcher.md` (Naima Quéré) +5. `.claude/agents/council-scribe.md` (Ansel Voss) +6. `members//persona.md` × 12 (10 voting + researcher + scribe) — with frontmatter +7. `members//{journal.md, on-the-user.md, revisit.md}` × 10 voting members — empty-with-header +8. `council-sessions.base`, `council-members.base` +9. `.claude/commands/council.md` — orchestration (save for last; depends on everything above)