README.md
# council
> Adversarially improves anything (a design, a piece of writing, code, a plan) with a council of Orca agents on the models you name, revising until every member scores it at least 9 out of 10.
## What it does
`council` runs a critique-and-revise loop. Your agent is the author; a council of [Orca](https://www.onorca.dev/docs) workers, one per model you name, are the critics. Each round, every member scores the current version against a fixed rubric and writes a verdict with ranked, concrete changes. The author triages every critique (accept, reject with a reason, or escalate to you), revises, and convenes the next round. It ends when every member scores the same version at or above the bar.
The loop is built to resist the usual ways review councils go soft:
- **A fixed rubric.** The criteria and score anchors are written before round 1, from your answers to any priority questions, and never move, so the goalposts stay put.
- **Blind verdicts.** Members score independently each round and see each other's points only through the author's change log, so nobody anchors on the first score.
- **A hidden bar.** Members know the rubric and the anchors (9 means it would ship to a demanding expert audience with nothing worth changing) but not the pass mark or the round cap, so they score the work rather than toward an exit.
- **Earned scores.** A member who raises or lowers a score names the change that moved it.
- **Pinned versions.** Each round reviews a pinned copy (screenshots, text, or diff), and the pass requires every member to clear the bar on the same version.
- **One author.** Members only critique; the author makes every change, so the artifact stays coherent and each change traces to a critique.
When the council stalls (the round cap, or no progress for two rounds), it stops and hands you the dispute instead of grinding on.
## When to use it
- *"Council this landing page with opus and gpt-5.5 until it's a 9."*
- *"Get a council to tear apart this blog post and keep revising until they all agree it's great."*
- *"Run the onboarding flow past a council of three models and improve it."*
- *"Have a council review this API design doc."*
If you name no models, it asks which ones to seat before starting. If a fair score depends on something you left open (which quality wins when two conflict, a property the work must have, where it ships), it asks you one to three questions first and builds the rubric from your answers.
**Not the right skill if** you want a single review with no revision (ask for a review), or a batch of GitHub issues implemented (→ [`orca-implement`](../orca-implement/)).
## Example walkthrough
**Prompt**
> Council the pricing page with opus and gpt-5.5. It's for developers comparing us to two competitors.
**What the skill does**
1. **Seats the council**: an `opus` member on `claude` and a `gpt-5-5` member on `codex`.
2. **Asks one question**: should the page win on price or on features? The answer sets which criterion weighs most.
3. **Writes the rubric**: clarity of the plan differences, honesty of the comparison, visual hierarchy, mobile layout, call to action, each with what a 10 looks like.
4. **Round 1**: screenshots the page at phone and desktop widths, light and dark, into `.council/pricing-page/round-1/`. Both members score it (6 and 7) and list changes.
5. **Triage and revise**: accepts eleven changes, rejects one ("drop the free tier" conflicts with the goal), rebuilds, re-screenshots.
6. **Rounds 2–3**: scores climb to 8 and 8, then 9 and 9 with no blocking items.
7. **Reports**: final scores, the changes that moved them most, the contested rejection, and where the record lives.
A verdict excerpt:
```markdown
**Score**: 8 overall. Hierarchy 9, comparison 7 (the competitor table omits seat limits, which is where we win), mobile 8.
**Changes**
1. Comparison table, row 3: add per-seat limits for all three plans; it's the strongest argument and it's missing.
2. Hero, phone width: the annual/monthly toggle wraps under the price; move it above the cards.
**Weakest point**: the "Enterprise" card still reads as an afterthought.
```
## Installation
```bash
npx skills add thatjuan/agent-skills --skill council
```
Requires the Orca app with orchestration enabled (Settings → Experimental) and the `orchestration` skill that ships with Orca.
## Bundled resources
| File | Purpose |
| ---------- | ------------------------------------------------------------- |
| `SKILL.md` | The council loop: seating, rubric, evidence, rounds, finish. |
## Tips
- Seat models from different providers; two models from one family tend to share blind spots.
- Two or three members is the sweet spot. More members make every round slower without adding many new points.
- Say who the audience is. The rubric, and how hard the members judge, comes from it.
- Set a different bar ("until it's a 10") or round cap in the prompt if the default 9 and six rounds don't fit.
- For designs, say which screens and states are in scope, or the council judges only what the author screenshots.
## Related skills
- [`orca-implement`](../orca-implement/): Orca workers implementing a batch of GitHub issues.
- [`clean-writing`](../../creative/clean-writing/): the prose standard to revise writing against.
SKILL.md
---
name: council
description: Adversarially improve anything (a design, writing, code, a plan, a prompt) with a council of Orca agents on models the user names, who score and critique each revision until every member rates it at least 9/10. Use when the user asks for a council, an adversarial critique-and-revise loop, or to iterate on something until reviewers agree it is a 9 out of 10.
---
# Council
You are the **author**. A **council** of Orca workers, one per model the user names, are your critics. Each round, every member scores the current version against a fixed **rubric** and writes a **verdict**; you triage the verdicts, revise, and convene the next round. The work is done when every member scores the same version at or above the **bar** (default 9/10, or the one the user sets).
Members only critique. You alone change the artifact, so it keeps one coherent hand and every change is traceable to a critique.
## Load Orca
Invoke the `orchestration` skill, resolve the Orca executable it describes, and load its version-matched guide; it is the single source of truth for command syntax, waking, `send`, and release. Running this skill is the user's request for supervision, so you are the coordinator. `ORCA status --json` must succeed first; if orchestration commands are rejected as disabled, tell the user to enable it under Orca Settings → Experimental and stop.
## Seat the council
1. **Models.** Seat one member per model named in the prompt; a model named twice seats two members. When the prompt names no models, ask which models sit on the council, in the same message as any priority questions (step 4), and wait for the answer before anything else.
2. **Agents.** Map each model to the Orca agent that serves it (Claude models → `claude`, OpenAI models → `codex`; the rest from the `--agent` list in `ORCA orchestration worker-start --help`) and pass its provider model id with `--model`. Pass `--effort` only when the user names one.
3. **Artifact.** Identify what is being improved and how a member will see it (**Evidence**). When the prompt asks for something that does not exist yet, make the first version yourself; that is round 1.
4. **Priorities.** Decide whether a fair score depends on something the prompt leaves open: which quality wins when two conflict, a property the work must have, or the conditions it is judged under (the audience, where it ships, what it competes with). If it does, ask the user 1–3 questions before the first round, each saying what its answer changes in the rubric, and wait for the answers. Ask nothing the prompt already settles, and drop any question whose answer would not change a criterion or what a 10 looks like for it.
5. **Rubric.** Write 4–7 criteria drawn from the user's goal, the audience, the answers to the priority questions, and the artifact's kind, and for each one what a 10 looks like. Add these anchors for the overall score: 10 is the best example of its kind you have seen; 9 would ship to a demanding expert audience with nothing worth changing; 7 is competent and forgettable; 5 has a problem a user would notice. The rubric is fixed for the whole council, so every round is scored against the same goalposts.
6. **Record.** Create `.council/<slug>/` at the workspace root and add `.council/` to `.git/info/exclude`. Write the rubric to `rubric.md` there, headed by the priority questions and the user's answers. Name each member after its model (`opus`, `gpt-5-5`, with `-2` for a repeat).
7. Show the user the members (model and agent), the rubric, the bar, and the round cap (default 6), then start.
## Evidence
Each round lives in `.council/<slug>/round-<n>/`, holding a pinned copy of the version under review so members judge exactly what you judged, even while you keep editing.
| Artifact | What goes in the round directory |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Design, UI, a page | Screenshots of every screen and state in scope, at phone and desktop widths, light and dark when both exist, plus the URL |
| Writing | A copy of the text, and where it will be published |
| Code | The diff against the starting point, and the commands that build and test it |
| Anything else | Whatever a demanding reviewer would ask to see before scoring it |
Members score the current version on its own merits. The previous round's directory is there to catch regressions, never to grade improvement.
## Member spec
Start every member in the same turn with `worker-start --worktree current --agent <agent> --model <id> --task-title "council: <member>" --spec-file .council/<slug>/spec-<member>.md`, then end your turn. Each spec carries:
- The user's goal, the audience, any constraints, and the answers to the priority questions, in the user's words.
- The rubric file and the round directory to judge.
- The verdict to write to `round-<n>/<member>.md`:
- **Score**: the overall score and one per criterion, each a whole number with a one-line reason.
- **Blocking**: anything that by itself keeps the work below a 9.
- **Changes**: ranked by impact, each naming the place in the artifact, the problem, and a concrete fix.
- **Keep**: what works and must survive revision.
- **Weakest point**: at a 9 or above, the one thing still most worth changing.
- The stance: you are a relentless, adversarial critic, judging as the most demanding member of the audience would. Every claim points at a specific place in the artifact. A score moves only when the artifact changes: a raised or lowered score names the change that moved it.
- Read the artifact and your own earlier verdicts; leave other members' verdicts unread until the change log quotes them. Edit nothing but your verdict file.
- Finish each round with `worker_done`, its summary holding your overall score and the path of your verdict.
Members learn the rubric and the anchors, never the bar or the round cap. A critic who knows the pass mark scores toward it.
## Run the rounds
Orca wakes you as members report. Once every member has reported:
1. **Tally.** Record each member's overall score for the round in `.council/<slug>/scores.md`.
2. **Pass check.** The council passes when every member scored this round's version at or above the bar and no Blocking item is open. On a pass, go to **Finish**.
3. **Triage** every Blocking item and Change into one disposition, written to `round-<n>/changelog.md` with the member it came from:
- **Accept**: you will make the change.
- **Reject**: it conflicts with the user's goal, the rubric, or another member's stronger point. State the reason on substance; the member may contest it.
- **Escalate**: a taste call that belongs to the user, or two members deadlocked on opposite demands with equal support in the rubric. Ask the user and wait.
Weigh critiques on their merit against the rubric. Two members agreeing does not make a point right, and a lone dissent can be the best note in the round.
4. **Revise.** Make every accepted change, protecting each member's Keep list. Verify the result the way the artifact demands (rebuild and screenshot a design, run the tests on code, reread prose end to end).
5. **Convene** round n+1: pin the new version in `round-<n+1>/`, then `send` each member the new round directory and the change log, asking for a fresh verdict. End your turn.
**Stop early** and report to the user when the round cap is reached, or when the lowest score has not risen for two rounds in a row. Report each member's last score, the open Blocking items, and the dispute keeping the council apart, then ask how to proceed: another round, a ruling from the user, or stop here.
## Finish
The improved artifact is in place where it started. Release every member as the orchestration guide describes, and confirm `worker-list --run <run_id> --terminal-state reclaimable --json` returns none.
Report to the user:
- The final score from each member, and how many rounds it took.
- The changes that moved the scores most, one line each.
- Critiques you rejected that a member still contested, with your reason.
- Where the record lives (`.council/<slug>/`), and that you will delete it unless they want to keep it.