Consensus

The consensus plugin uses provider-CLI-backed AI peers for five related workflows: converging artifacts through peer deliberation, one bounded read-only review, single-round panel responses with side-by-side attribution, advisory takes that the host dispositions (one-shot by default, with bounded follow-up rounds on request), and delegated tasks that the host verifies. It also packages observer and observer-collab, the plugin-local forms of the standalone session observation skills. The peers are invoked through the generated consensus CLI; the converging wrappers parse your document, run the peers through structured verdict rounds, and write a markdown deliberation artifact with the final output, resolution metadata, and a deliberation log.

The peer-workflow scope stays intentionally narrow: five converging skills, one panel skill, one review skill, one advisory skill, and one delegation skill. The plugin additionally ships two session-observation skills because observing and collaborating across providers belong with consensus behavior.

• create — creates a new artifact from a brief with independent_draft, parallel_synthesized, maximum agency, a deliberation log, and a consensus-resolution block.
• decide — chooses between documented options with independent_draft, parallel_synthesized, minimal agency, required decision headings, explicit ## Dissent / Unresolved Disagreement, and a consensus-resolution block.
• plan — turns a goal and inline constraints into a structured markdown plan with independent_draft, parallel_synthesized, moderate agency, required ## Steps, ## Dependencies, and ## Risks headings, and a consensus-resolution block.
• refine — refines a markdown draft by asking two peers to deliberate toward a converged artifact with an audit trail.
• evaluate — judges an artifact against a rubric, with unified findings, per-peer reasoning, and dissent preserved in the deliberation log.
• review — asks one independent reviewer to inspect a branch diff, selected files, or one document and writes validated OAT-compatible findings without applying them.
• panel — asks multiple provider-backed panelists the same question and writes side-by-side attributed responses while the host stays a neutral moderator.
• phone-a-friend — asks one other provider-backed peer for a structured advisory take, then leaves the host responsible for agreeing, applying, ignoring, or following up. It also ships standalone under the same name.
• delegate — hands one task to another provider: code changes run in a dedicated git worktree, questions and investigations run read-only, and the host verifies the diff before you decide what to keep. It also ships standalone as delegate.
• observer — plugin-local form of session-observer.
• observer-collab — plugin-local form of session-observer-collab; it requires the observer workflow and accepts either supported installation identity.

For the deepest reference — operator-QA walkthroughs, exact commands, and example inputs — see the consensus plugin README.

Peers, not personas

Consensus invokes provider CLIs as separate processes, rather than assigning several roles inside one conversation. The host remains responsible for acting on results. Disagreement is preserved in the artifact and deliberation log: an impasse is a valid result, decide includes a dissent section, and panel does not synthesize its independently attributed responses.

For example, after installing the plugin in Claude Code:

/consensus:refine draft.md --goal "tighten the failure-handling section"
/consensus:panel --question "Should retries live in the client or gateway?" --panel-size 3

The first seeks a refined artifact with an audit trail; the second gives you separate perspectives to judge. Codex uses $consensus:refine and $consensus:panel. Cursor's local plugin load uses the local skill names; see Installation for the host-specific setup.

The wrapper emits JSONL status events while the generated CLI returns one JSON envelope per run and spawns the other providers' CLIs as separate OS processes. IMPASSE is checked before convergence; a declined convergence consults the escalation triggers. Every terminal outcome writes the artifact.

Who decides: refine, panel, phone-a-friend

The three shapes are not interchangeable. refine deliberates to convergence or a reported impasse, panel returns attributed takes and refuses to synthesize, and phone-a-friend returns an advisory take that the host must disposition, with bounded follow-up rounds with the same peer when you ask for them.

Mermaid updated 2026-09-28

The outcome determines who acts next:

• Refine produces a converged artifact or reports an impasse. An impasse comes back to you; resume with --user-direction. Other escalation cases follow the agency policy.
• Panel requires at least two successful responses. Panelists respond independently, and the host's instructions prohibit adding a synthesis, vote, or recommendation.
• Phone-a-friend returns a take, recommendation, risks, follow-up questions, and confidence from one provider turn. The host must state whether it agrees, disagrees, applies, ignores, or follows up on that advice. When you ask for follow-up rounds, the host continues the same peer within a small call budget and reports agreement on a named revision, an evidence gap, an impasse, or an exhausted budget.

Iteration modes

The shipped consensus skills support three iteration modes, selected with --iteration:

• alternating (default for refine) — one peer revises and the other responds, turn by turn. Lowest cost: one peer call per round.
• parallel_revision (default for evaluate) — both peers revise the same input simultaneously each round, each critiquing its own and the peer's previous revision; the run converges on emergent agreement. Costs 2x peer calls per round.
• parallel_synthesized — parallel revision plus a per-round synthesis call that merges both revisions into the next round's shared input. Costs 2x peer calls plus one synthesis call per round.

Parallel modes disclose their per-round call multiplier in the run_started JSONL event (calls_per_round) and report actual peer_calls / synthesis_calls totals at completion.

Synthesizer, agency, and escalation

• Synthesizer — in parallel_synthesized mode, a synthesis call merges both peers' revisions each round. It defaults to the first configured peer's provider and can be overridden with --synthesizer <provider-id>. The synthesizer must be present in the provider inventory, and the flag is warned-and-ignored outside parallel_synthesized.
• Agency — --agency controls who resolves a stuck section. At minimal agency, unresolved peer disagreement is surfaced to the user rather than silently decided.
• Escalation — when a parallel-mode section gets stuck (persistent disagreement, oscillation, budget exhaustion, or near-done drift), the wrapper emits an escalation_required JSONL event routed by --agency to the user or the host. A user decision re-enters with --user-direction; a host decision re-enters with --host-direction and records as an attributed orchestrator round.

See Configuration for saved defaults and peer selection, Provider setup for readiness and diagnostics, and Provider run controls for output and write policies. The per-skill pages describe their full command sets.

What is handed to a provider process

This is the local process boundary, not a network boundary. The wrapper reads selected input and constructs a prompt payload, which every provider receives on stdin. A JSON-mode run also supplies the schema, and the consensus submit environment and instructions when the peer can run that command: not for Claude scoped-grant or workspace-write runs, and not for read-only Cursor. A --output text run supplies neither.

Transcript, observer, and run-state files are stored locally, but selected contents can enter the prompt. Provider subprocesses may also access files in their working directory under their own permission and sandbox settings; the wrapper's path guards do not confine those processes. Provider CLIs may transmit context to their services. Review those tools' configuration before sharing sensitive material. Returned structured payloads are schema-validated, but validation does not make their advice trustworthy or authorize following it.

Limitations

• The plugin ships create, decide, plan, refine, evaluate, panel, phone-a-friend, delegate, review, observer, and observer-collab. Phone, Review, and Delegate also have declared standalone forms; the two observer skills use their full session-* names standalone. The other six peer workflows are plugin-only.
• Remaining consensus-family skills are future work: consensus-research.
• Three iteration modes ship (alternating, parallel_revision, parallel_synthesized); parallel_revision and parallel_synthesized disclose their per-round call multiplier (2x peer calls, plus 1 synthesis call for synthesized) and escalate stuck states through the agency-gated ladder.
• The independent-draft cold-start strategy is exposed through create, decide, and plan. refine and evaluate remain shared-input only.
• Sections converge independently; whole-document harmonization and deliberation metrics / cost caps remain deferred.
• Verdict submission is best-effort by default: successful submit sidecars are preferred, then wrappers fall back to final-message parsing. Strict require-submission mode remains future work.
• Cursor is supported as a host runtime and as a first-floor peer when its local CLI is authenticated. Treat auth_required inventory/preflight results as a local setup issue, not a retryable consensus failure.
• Codex public marketplace submission is not assumed; Git/local install is the v0.1 path.
• skills.sh listing should not be claimed until indexing has been verified after publication.
• Prompt injection inside input artifacts is mitigated by prompt framing, filtering, and schema validation where applicable, but peer CLIs may still produce structurally valid bad advice. Review the audit trail before publishing outputs.
• This plugin adds no telemetry. Configured provider CLIs may have their own behavior; review those tools separately.

Contents

Create, Plan & Decide

• Create — create usage: brief inputs, independent_draft defaults, output contract, and input handling.
• Plan — plan usage: goal and inline constraints, moderate-agency defaults, required headings, and output contract.
• Decide — decide usage: options input, minimal-agency defaults, required headings, dissent surfacing, and output contract.

Improve & Assess

• Refine — refine usage: sequential default, iteration modes, resume, escalation, and host-mediated parallel sections.
• Evaluate — evaluate usage: artifact-vs-rubric command, defaults, output contract, and guided rubric creation.
• Review — review usage: three bounded selectors, one read-only reviewer invocation, OAT-compatible artifacts, and detection limits.

Consult Peers

• Phone-a-friend — phone-a-friend usage: advisory peer call, optional bounded follow-up, provider selection, and host disposition.
• Panel — panel usage: single-round multi-peer questions, panelist selection, JSONL status, output contract, and neutral moderation.
• Delegate — delegate usage: write or read-only mode, peer selection, worktree writes, host verification, and continuation.

Observe & Collaborate

• Observer — Read and watch a pinned peer session; also available standalone as session-observer.
• Collaborative Observer — Coordinate two sessions with explicit authority boundaries; also available standalone as session-observer-collab.

Reference

• Configuration — Saved workflow defaults, peer selection, synthesizer, and agency.
• Provider setup — Inventory, readiness, diagnostics, provider programs, and authentication.
• Provider run controls — Output modes, retries, timeouts, process cleanup, and write policies.