agent-council

Agent Council

Four reviewers examine your work from distinct perspectives; a separate adjudicator turns their findings into a decision with reasons and required changes.

A runtime-portable review gate for text you write, AI generates, or you create together. Skeptic, Evidence, Voice, and Strategy review independently, then read the full first-round findings for one second review. A separate Adjudicator synthesizes both rounds and remaining disagreements. Code enforces the final SHIP, REVISE, HOLD, or INCOMPLETE result; the model recommendation cannot bypass that policy.

No required SDK or API key in the core package. Runtime adapters use a configured CLI (claude, ollama), LM Studio's HTTP server, or an offline mock. Provider authentication and model availability are still your responsibility. Producing agents need no Council dependency.

Personal research, separate from my day-job at Microsoft. MIT-licensed.

Install · How it works · Quickstart · Customize · AGENTS.md · CHANGELOG

---

Install

Claude Code (plugin)

claude plugin marketplace add Avyayalaya/agent-council
claude plugin install agent-council@avyayalaya

Then in any Claude Code session: /council-review path/to/artifact.md or /council-sweep.

Python (pip from source)

git clone https://github.com/Avyayalaya/agent-council.git
cd agent-council
pip install -e .
cp council.yaml.example council.yaml  # then edit
python -m agent_council review path/to/artifact.md --tier=1 --config=council.yaml

Requires Python ≥3.11 and a configured runtime. mock_cli needs no model or external service.

MCP server (Claude Desktop, Cursor, Cline, custom agents)

pip install "mcp>=1.0"

Add to your client's MCP config:

{
  "mcpServers": {
    "agent-council": {
      "command": "python",
      "args": ["<absolute-path>/agent-council/mcp/agent_council_mcp_server.py"],
      "env": {
        "COUNCIL_CONFIG": "<absolute-path>/agent-council/council.yaml"
      }
    }
  }
}

Tool exposed: council_review(artifact_path, tier=1). Full setup: mcp/README.md. Use the Python CLI for sweep and audit.

GitHub Copilot CLI, Cursor, Cline, OpenCode (via APM Skills)

v0.1.1 ships each deliberator as a standalone Skill under skills/ so any APM-compatible harness gets the methodology inline — no Python CLI required for single-perspective review.

apm marketplace add Avyayalaya/agent-council
apm install agent-council --target copilot

Then in the harness, load one Skill at a time:

• skeptic-review — adversarial steelman pass
• voice-identity-review — line-level voice audit + CXO test
• evidence-calibration-review — per-claim T1-T6 evidence-tier audit
• strategy-stakes-review — goal-fit and opportunity-cost check
• adjudicator-synthesis — verdict synthesis from 2+ deliberator outputs

Use cases per surface:

Use case	Surface
Run full automated Council on an artifact with parallel deliberators + 2-round cross-read + JSONL audit	python -m agent_council review path/to/artifact.md --tier=1 --config=council.yaml or MCP council_review tool
Apply one deliberator role to a doc I am editing right now (Copilot, Claude, Cursor)	Load the matching Skill
Compose 2 or 3 deliberators ad-hoc for a multi-angle ad-hoc review	Load multiple Skills sequentially, then optionally load adjudicator-synthesis
Use slash commands in Claude Code	/council-review path/to/artifact.md (Claude Code only)

Skills vs CLI — what you get on each path

The Skills are the interactive role-specific surface. The CLI / MCP is the automated full-Council surface with four reviewers and separate synthesis. Standalone Skills do not enforce the runtime's configured policy:

Capability	Compose Skills sequentially	Full Council via CLI / MCP
One perspective at a time	yes	yes (the deliberators)
Parallel deliberator execution	no	yes
Round 2 cross-read (each reviewer sees all four R1 findings, including its own)	no	yes
Adjudicator prior-verdict compounding loop on artifact_type	no	yes
JSONL audit log and archived transcripts	no	yes
Single synthesized decision	optional synthesis Skill	yes, with enforced policy
Structured, persisted verdict record per run	no	yes
Calls per review	harness-dependent	9 on the default happy path; at most one schema reprompt per call
Sweet spot	Ad-hoc 1 or 2 perspectives on a doc you are editing	Pre-ship gating in pipelines; structured, persisted audit trail

Sequentially composing review Skills can provide multiple perspectives and optional synthesis. It does not ensure independent first reads, run the two-round protocol, or enforce the Python verdict policy. Use the CLI / MCP path for those guarantees and persisted records.

Any other LLM (ChatGPT, Gemini, manual)

Read the four reviewer prompts and the separate synthesis prompt at prompts/. For manual review, keep first reads separate and supply the actual policy to the adjudicator. The automated rules live in VerdictPolicy and merge_verdicts.

---

How it works

1. Independent first reviews: four parallel calls receive the artifact and their role-specific context, without seeing each other's answers.
2. One cross-read round: each receives the full available R1 payloads, not just scores. Different perspectives can expose new questions: does "better" have a measurement, or does the evidence support a causal interpretation? Reviewers record concessions, escalations and reasons; agreement is not the objective.
3. Separate synthesis and enforcement: the Adjudicator reads both rounds and up to five prior verdicts of the same artifact type. It recommends a decision, explains disagreements and proposes changes. Code applies the configured policy and merges its result with that recommendation.

The default is two review rounds plus one synthesis, not a continuous debate or automatic revision loop. rounds: 1 disables R2. A later review is a new invocation chosen by the operator.

Default policy	Result
Fewer than three schema-valid R1 reviews, or unusable synthesis	INCOMPLETE
Any participating valid-R2 irreducible flag, or at least three hard/soft blocks	Policy HOLD
No hard/soft blocks and every present score is at least 3	Policy SHIP
Remaining cases, including a score of 2 or one/two blocks	Policy REVISE

would_block is a hard block; a score at or below 1 counts as a soft block when that reviewer has no hard block. Valid R2 takes precedence; failed or disabled R2 falls back to valid R1. Failed R1 never counts toward quorum, even if R2 succeeds. The stricter of model recommendation and policy wins, except policy HOLD may become REVISE when the model recommends it and there is no participating irreducible dissent.

Schema failure triggers one reprompt; there are no additional runtime-error retries. Synthesis timeouts/runtime failures return audited INCOMPLETE. Review failures and R1 fallback are visible in the returned record and dissent summary. Missing actionable briefs are explicitly reported with available reviewer findings rather than invented fixes. See architecture for the output and failure contract.

My review workflow

The author's workflow for authored, AI-generated and co-created content. The diagram's "required reviews complete" standard and revise/review loop describe the personal workflow, not an exact executable state machine. This implementation retains a three-valid-R1 quorum and valid-R1 fallback when R2 fails; it does not require all four reviews in both rounds. Publishing remains the operator's decision.

Read the accompanying LinkedIn post.

The five roles

Role	Concern	Reads
Skeptic	Adversarial review — catches premature coherence, narrative fallacy, survivorship bias, unstated assumptions	(artifact only)
Voice & Identity	Voice DNA, banned-pattern enforcement, channel register, CXO test	Operator's voice corpus + persona DNA
Evidence & Calibration	Assess supplied support, evidence tiers (T1–T6), confidence and base rates; identify gaps	Artifact + optional supplied source/context text
Strategy & Stakes	Goal alignment, stake calibration, opportunity cost vs. operator's active projects	Operator's goals doc + project state
Adjudicator	Separate synthesis, recommendation and revision brief; runtime enforces final verdict	Both review rounds + prior verdict summaries

Why a council, not a single judge?

A review needs to answer distinct questions:

• Is the argument adversarially sound?
• Does it match the operator's voice?
• Are the sources credible?
• Does it advance the operator's actual goals?
• Should it ship?

A single judge can address multiple criteria too. Council makes the division of responsibility explicit and preserves who raised an issue, what changed after cross-reading, and what remains disputed. More reviewers or cross-reading do not establish better output: comparative quality is a hypothesis, not a demonstrated result in this repository.

This matters for tier-1 artifacts where the cost of shipping a flaw is high (public publish, irreversible commitment, identity-shaping document) and the cost of one more revision pass is low.

---

Quickstart

After pip install -e . and copying council.yaml.example → council.yaml:

# Single artifact
python -m agent_council review path/to/artifact.md --tier=1 --config=council.yaml --json

# Daily sweep over watch paths
python -m agent_council sweep --since=24h --config=council.yaml

# Audit recent verdicts
python -m agent_council audit --since=7d --log=council_log.jsonl

Review output is human-readable unless --json is supplied. Each completed protocol run, including structured failures, appends an audit row to the configured log. For an offline smoke review, use --config=tests/council.example.yaml with tests/sample_artifact.md; the shipped mock fixture returns REVISE (exit 1).

See what a verdict looks like

examples/demo/ ships a fictional LinkedIn post + the structured verdict the Council produced for it + the extracted revision brief. Read these first to calibrate expectations before running your first real review.

Tier classification

The Council is designed for tier-1 artifacts — the ones where review cost is justified:

• Tier 1 (gates through Council): external-facing OR irreversible OR identity-shaping OR memory writes. Examples: published writing, public READMEs, investor messages, resume revisions, additions to a learnings file, memory writes.
• Tier 2 (skips Council): internal drafts, dashboards, infrastructure, dispatch updates.
• Tier 3 (1-in-5 sample): daily briefings, internal analyses, planning artifacts.