agentic-council

agentic-council

> Convene 20 agentic specialists on your hardest engineering problems. Distinct perspectives, unified design, actionable plans, every decision tracked.

Why a council

Hard engineering problems rarely have one right answer. The data model depends on the deployment story, the deployment story depends on the cost ceiling, the cost ceiling depends on what users will pay for. agentic-council brings in a roster of specialists to work the problem from every angle: an architect reasons about boundaries, a skeptic names what could break, a tuner argues about cost at scale, a guardian flags the privacy footprint. They post positions, challenge each other, and converge on a unified design. The Steward turns that design into a phased plan ready to hand to /ship.

Every decision is tracked

Every phase writes to .claude/council/sessions/<slug>/ as it happens: the interview, the assembled roster, each agent's position, every round of debate, the synthesis, and the final plan. Nothing is lost to a context window. Resume days later, list every council you've ever run, archive a session to a GitHub issue, or replay how a decision was reached when someone asks "why did we do it this way?".

And you watch it happen live: every session (except --brainstorm) opens session.html in your browser, a single page that fills in as the council works. Positions appear card by card as agents finish, tension pairs surface, and the design verdict, PRD scope, and verification status land as each phase completes. The page auto-refreshes from disk every 10 seconds via a zero-dependency python scribe; if python3 or a browser is missing, the session degrades to text-only with nothing lost, and chat always carries a compact summary of every decision.

Install

/plugin marketplace add https://github.com/dtsong/agentic-council
/plugin install agentic-council

That's it for the core flow. As of v1.2.0 the council deliberates via Claude Code's dynamic workflows runtime (Claude Code ≥ 2.1.154, available on all paid plans) — the experimental agent-teams flag is no longer required. Optionally enable it to unlock live panel steering in --meet and team-based execution in Path A:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1   # optional

See INSTALL.md for the full setup including troubleshooting. Without either runtime the engine degrades to sequential agent calls — slower and with no persistent agent memory across rounds (same on-disk artifacts, shallower deliberation).

Quick start

/council --brainstorm "Should we migrate from Node to Bun?"
/council --quick      "Add a tournament coach feature"
/council --meet       "Re-architect the billing stack"
/council --audit      "Audit our authentication stack"

Each mode scales differently:

| Mode | Agents | Rounds | Backend | Use when | |---|---|---|---|---| | --brainstorm | 3 | 1 | inline | Gut check, pre-decision ideation | | --quick | 3 | 1 | inline | You know roughly what you want | | (default) | 3 to 7 | 3 | workflow | Ambitious feature, full deliberation | | --deep | 3 to 7 | 3 + audit | workflow | Max rigor, ~1 hour | | --meet | 3 to 7 | cross-exam | teams | Discussion only, no plan | | --audit | 3 to 5 | passes | workflow | Adversarial codebase review |

Add --profile lean|balanced|max to any mode to control model spend — see the Cost guide.

Cost guide

The council spawns real agents, so sessions have real token costs. --profile routes each spawn site to a model tier:

| Profile | For | What it does | |---|---|---| | lean | API-billed / enterprise, token-conscious | Sonnet positions & converge; Opus one-shots only for the Round 2 challenges (where debate quality pays most) | | balanced (default) | Daily use | Opus deliberation, Sonnet audits | | max | Claude Max subscribers chasing ceiling quality | Opus everywhere, Fable challenge agents; rate-limit-bound, not dollar-bound |

A 5-agent standard session runs ~80–120K tokens on lean, ~120–180K on balanced, ~180–270K on max; brainstorm is ~10–15K everywhere. The engine prints an estimate at the roster-approval gate before anything spawns, and the conductor (interview, synthesis, PRD) always runs on your /model — set it to opus or fable before a big session for the single biggest quality lift.

Full playbooks for both billing models: Cost guide (source).

Example sessions

1. De-risk an ambitious feature before you build

/council "Add a tournament coach feature to our chess app"

The Strategist scopes the MVP, the Architect proposes the data model, the Tuner flags the LLM-call cost ceiling, the Skeptic names the failure modes, and the Advocate maps the user journey. After three rounds of debate, the Steward synthesizes a unified design and a phased build plan ready to hand to /ship. Every position, every round, and the final plan land in .claude/council/sessions/<slug>/ so you can resume the work next week or archive the whole deliberation to a GitHub issue.

2. Pressure-test a tradeoff with an auditable trail

/council --brainstorm "Should we migrate from Azure to AWS?"

Three agents (Operator, Tuner, Skeptic) post positions in parallel, the Steward synthesizes the tradeoffs, and you walk away with a one-page decision brief instead of a vibes-based commitment. Six months later when someone asks "why did we choose AWS?", the full deliberation is still on disk and in the git commit history. Replay every argument that led to the call.

3. Adversarial audit of an existing system

/council --audit "Audit our authentication stack"

Cipher, Warden, Guardian, and Skeptic deliberate on cryptographic choices, privilege boundaries, compliance gaps, and attack surface. Output: a prioritized remediation list with clear owners, persisted alongside every other council session for cross-project pattern-spotting.

How it works

1. Intake. "What's the big idea?" 2. Interview. Steward asks 3 to 7 questions to disambiguate scope, constraints, and success. 3. Assembly. Steward picks 3 to 7 council members based on the topic. Architect is always seated; Advocate, Skeptic, Guardian, and Tuner get bonus weight for relevant domains. You approve the roster — and see a token estimate — before anything spawns. 4. Deliberation. Three rounds run as a background workflow: Position, Challenge, Synthesis. Tension pairs surface organically (Skeptic vs Strategist, Operator vs Tuner). Round texts stay on disk and out of your session's context. 5. Output. Design doc, implementation plan, and an optional PRD ready to hand to /ship.

flowchart TD
    classDef userNode    fill:#1b4332,color:#d8f3dc,stroke:#2d6a4f,stroke-width:1px
    classDef artifactNode fill:#1c3461,color:#dbe4ff,stroke:#364fc7,stroke-width:1px
    classDef actionNode  fill:#3b1f2b,color:#fcc2d7,stroke:#9c36b5,stroke-width:1px
    classDef phaseNode   fill:#2b2b2b,color:#f1f3f5,stroke:#495057,stroke-width:1px

    START(["💡 Your idea"]):::actionNode

    subgraph P0["⓪  Intake"]
        p0u[/"👤 'What's the big idea?'"/]:::userNode
    end

    subgraph P1["①  Interview  ·  3–7 questions"]
        p1p["Steward scans your codebase, asks targeted questions"]:::phaseNode
        p1u[/"👤 Answer scope, constraints, success criteria"/]:::userNode
        p1a[("📄 interview.md")]:::artifactNode
        p1p --> p1u --> p1a
    end

    subgraph P2["②  Assembly  ·  5–9 agents"]
        p2p["20 agents scored by relevance · Architect always seated"]:::phaseNode
        p2u[/"👤 Approve, add, or remove agents"/]:::userNode
        p2a[("📄 assembly.md")]:::artifactNode
        p2p --> p2u --> p2a
    end

    subgraph P3["③  Deliberation  ·  3 rounds"]
        p3r1["Round 1 · Position — agents explore code, post independently"]:::phaseNode
        p3r2["Round 2 · Challenge — tension pairs rebut each other"]:::phaseNode
        p3r3["Round 3 · Synthesis — agents reconcile and finalize"]:::phaseNode
        p3a[("📄 round-1.md  ·  round-2.md  ·  round-3.md")]:::artifactNode
        p3r1 --> p3r2 --> p3r3 --> p3a
    end

    subgraph P4["④  Output"]
        p4p["Steward synthesizes design, plan, and optional PRD"]:::phaseNode
        p4u[/"👤 Scope review before handoff"/]:::userNode
        p4a[("📄 design.md  ·  plan.md")]:::artifactNode
        p4p --> p4u --> p4a
    end

    subgraph P5["⑤  Handoff"]
        p5s["🚀 /ship — implement, review, fix, PR"]:::actionNode
        p5d["🔍 /deepen — architecture review"]:::actionNode
        p5h["💾 /handover — save session knowledge"]:::actionNode
    end

    START --> P0 --> P1 --> P2 --> P3 --> P4 --> P5

Persistence and context handoff

Every session writes to .claude/council/sessions/<slug>/ in your workspace, capturing each phase as a discrete artifact:

.claude/council/sessions/<slug>/
├── interview.md         # Phase 1 questions and answers
├── assembly.md          # Phase 2 roster and rationale
├── deliberation/
│   ├── round-1.md       # Each agent's opening position
│   ├── round-2.md       # Cross-examination and rebuttals
│   └── round-3.md       # Synthesis
├── design.md            # Phase 4 design doc
└── plan.md              # Phase 4 build plan

This is the key to the council pattern. Subsequent agents read prior rounds from disk so context flows agent-to-agent without bloating the parent context window. A 9-agent, 3-round deliberation that would blow past any single context window stays lean because each agent only loads what it needs.

Session lifecycle commands:

| Command | Purpose | |---|---| | /council --resume | Resume the most recent active session | | /council --resume <slug> | Resume a specific session | | /council --list [--all] | List sessions in this workspace (or all) | | /council --status | Quick workspace summary | | /council --archive <slug> | Export a session to a GitHub issue | | /council --cleanup | Review and remove stale sessions |

A cross-workspace registry at ~/.claude/council/ tracks usage across projects, and /handover exports session knowledge for the next Claude conversation to pick up cold.

Plugin assets are read-only at ${CLAUDE_PLUGIN_ROOT}. Session and registry data always lives in your workspace and home directory.

Commands shipped

| Command | What it does | |---|---| | /council "<idea>" | Full workflow: interview, assembly, 3-round deliberation, design, plan | | /council --brainstorm "<idea>" | 30-second gut check from 3 agents | | /council --quick "<idea>" | Skip interview, single round | | /council --deep "<idea>" | Full council plus mandatory deep audit | | /council --meet "<question>" | Discussion only, no action plan | | /council --audit "<area>" | Direct codebase audit | | /brainstorm "<idea>" | Top-level alias for /council --brainstorm | | /ship | Post-council pipeline: implement, review, fix, PR | | /deepen | Architecture review, find shallow modules | | /handover | Save session knowledge to a handover doc |

Run /council --help for the complete reference.

The council

Engineering and systems

• Architect for system design, data models, APIs
• Craftsman for testing strategy, code quality, patterns
• Operator for DevOps, deployment, infrastructure
• Tuner for performance, scalability, optimization
• Alchemist for data engineering, ML workflows
• Sentinel for IoT, embedded, edge protocols
• Pathfinder for mobile, cross-platform, native

Product and design

• Strategist for business value, scope, MVP
• Advocate for UX, product thinking, accessibility
• Artisan for visual design, design systems, motion
• Herald for growth, monetization, onboarding
• Scout for research, precedent, external knowledge
• Chronicler for documentation, knowledge architecture

Risk and integrity

• Skeptic for risk, devil's advocate, edge cases
• Guardian for compliance, governance, privacy
• Cipher for cryptographic engineering, protocol security
• Warden for OS kernel security, isolation
• Prover for formal methods, mathematical verification
• Oracle for AI/LLM integration, RAG, prompt engineering

Maestro

• Steward facilitator and synthesizer (does not vote)

Skills bundled (60)

Each council agent is paired with 2 to 4 first-class skills (e.g., architect-schema-design, skeptic-threat-model, tuner-caching-strategy, guardian-compliance-review). They load on demand during deliberation, or you can invoke them directly as /agentic-council:<skill-name>.

Documentation

Browseable docs with search and navigation at dtsong.github.io/agentic-council, or read in-repo:

| Guide | What's in it | |---|---| | Usage | Session anatomy, all 8 modes, flags, action paths, lifecycle, artifacts | | Councils | All four councils: rosters, conductors, theme outputs, handoffs | | Cost guide | Profiles, token estimates, API-billed vs Max-plan playbooks | | Orchestration | Workflow / teams / sequential backends and degradation | | Architecture eval | The design record behind v1.2 |

Engineering guardrails

• scripts/validate.py runs 7 structural checks (manifest parsing, frontmatter completeness, roster cross-references, no hardcoded user paths, no held-back-dept leakage).
• GitHub Actions CI runs the validator and claude plugin validate on every push and PR.
• No telemetry, no network calls outside the agent runtime itself.

See CONTRIBUTING.md for the full local dev workflow.

License

Apache-2.0. See LICENSE.

Cross-platform note

agentic-council is Claude Code only: deliberation runs on Claude Code's dynamic-workflows runtime (with agent teams as an optional enhancement), both Claude Code primitives. SKILL.md and agent persona files use minimal, portable frontmatter to ease future Codex and Gemini support. See PLATFORMS.md.