Design debate
You are the orchestrator. You frame the problem, stop once for the user to approve the framing, then run designers and a judge as subagents, and write one proposal. You never let a subagent write to the repository, and you never commit.
References, all bundled:
- @./references/lenses.md — lens briefs and the optional menu
- @./references/models.md — model family per slot, fallbacks, judge rule, effort per harness
- @./references/prompts.md — every subagent prompt and its required headings
- @./references/proposal-template.md — the proposal skeleton
Requires a subagent tool
The debate depends on designers working independently, in separate contexts. Check for a tool
that spawns a subagent with its own prompt (task in Copilot, Task in Claude Code, or the
equivalent in other clients). If there is none, stop and say this skill cannot run in this client.
Never simulate designers inside your own context: they would not be independent.
Invocation and defaults
design-debate <problem> [designers=3] [rounds=2] [lenses=a,b,c] [models=A:x,B:y]
[effort=high] [judge-model=x] [judge-effort=x] [slug=x]
design-debate resume <slug>
design-debate status <slug>
Accept the same settings in plain words ("use 4 designers, low effort", "debate until they agree").
| Setting | Default | Allowed | When out of range |
|---|---|---|---|
designers (N) | 3 | 2–5 | clamp to the nearest bound |
rounds (R) | 2 | a whole number from 1 up, with no upper bound, or auto (see Auto rounds) | below 1: use 1 |
lenses | pragmatist, domain-architecture, operations-runtime | names from lenses.md, or free text; a lens may repeat | use free text as the brief; fewer lenses than N: fill from the defaults, then the menu |
models | family preference per slot (models.md) | per-slot id or family | apply the models.md fallback |
effort | high | low, medium, high, xhigh; global or per slot | harness can't set it: "not applied" |
judge-model | strongest model from a family no designer used | model id | models.md fallback |
judge-effort | same as effort | as effort | as effort |
slug | kebab-case from the problem, at most 6 words | kebab-case | slugify it |
List every clamp, fallback and "not applied" at the checkpoint. Never drop a setting silently.
Planned calls are N + N×R + 1 (designs, debate rounds, judge), plus up to N repair calls (only
for final designs with gaps, see Completeness) and 1 shared retry: 10 planned at the defaults (13
with every repair). There is no upper bound: the checkpoint shows the count, and approving the
checkpoint approves it. With rounds=auto the count is not known in advance: show the calls up to
the end of round 1 (2N + 1, judge included) and N per further round.
Defaults files
Settings not given at invoke time come from, highest first:
- the invocation;
design-debate.jsonat the repo root, for the project;${XDG_CONFIG_HOME:-~/.config}/design-debate/config.json, for the user;- the defaults in the table above.
Each file is a JSON object whose keys are the setting names above. Both files are optional, and a
key in a higher file replaces the same key in a lower one, whole (a models object or lenses
list is not merged). slug is per run, so it is never read from a file.
{
"designers": 3,
"rounds": "auto",
"lenses": ["pragmatist", "domain-architecture", "operations-runtime"],
"models": { "A": "opus", "B": "sonnet" },
"effort": "high",
"judge-model": "opus",
"judge-effort": "xhigh"
}
A value from a file is checked like one given at invoke time, with the same out-of-range rules.
A file that is not a JSON object is ignored as a whole. An unknown key, or slug, is ignored. List
both at the checkpoint, so a typo never passes silently. Read the files only at preflight and on
resume: a file changed mid-run changes nothing until resume, which then goes back to the
checkpoint (the approval line differs).
Auto rounds
With rounds=auto, run debate rounds until one changes no design:
- After each round, compare every designer's
## Key decisionswith its own previous design (the draft, for round 1), bullet by bullet, ignoring order and surrounding whitespace. - Converged: every designer's bullets are the same as in its previous design. Append
converged: round-<k>torun.md, and go to Completeness with round k as the final round. - Cycling: not converged, but every designer's bullets match one of its own earlier designs.
Another round would only repeat the debate. Append
cycled: round-<k>and treat it as converged. - Otherwise run another round.
Every auto round carries the Final-design note (prompts.md), since any round may be the last. A run
whose designers never settle keeps going; the user can stop it, and resume continues from the
next round. Report how many rounds ran and why they ended.
Run state
Keep state outside the working tree, in
$(git rev-parse --absolute-git-dir)/design-debate/<slug>/. It survives new sessions, never
shows in git status, and is per worktree.
run.md settings table, approval line, dispatch log, retry line, status
framing.md
drafts/<slot>.md slots are A..E
round-<k>/<slot>.md one folder per round, from round-1
completeness.md written by the orchestrator, no subagent
repair/<slot>.md only for slots that needed a repair
judge.md
run.md lines, appended as they happen:
approval: <hash>|N=<n>|R=<r or auto>|<slot:lens:model:effort,...>|judge=<model:effort>, where<hash>isgit hash-object framing.mddispatch: <stage>/<slot> <ISO time>, written before every subagent spawnlabels: <stage>/<reader> P=<slot>,Q=<slot>,..., written before each round or judge spawn (see Peer labels)retry-used: <stage>/<slot>converged: round-<k>orcycled: round-<k>, only withrounds=auto(see Auto rounds)proposal: <repo-relative path>, written as soon as the proposal file existsstatus: <framing|approved|design|round-<k>|completeness|judge|written|validated|written-unvalidated|stopped:<reason>>
Peer labels
Designers and the judge never see slot letters for other designs. Show designs under the peer
labels P, Q, R, S, T, shuffled per reader, so a label can never be mistaken for a slot.
- Before each round or judge spawn, append that reader's mapping to
run.md, for examplelabels: round-1/A P=C,Q=Borlabels: judge P=B,Q=A,R=C. - Map every critique back to its slot with that line before storing or forwarding it. Each round after the first gets each designer the critiques aimed at its own slot in the round before, relabelled into that designer's new mapping. The judge's critiques and dispositions are relabelled into the judge's mapping.
- Map the judge's winner and grafts back to slots with the judge's
labels:line before filling the proposal. On resume, always use the recorded lines; never reshuffle a completed stage.
A stage file is valid only if it has every heading prompts.md requires for that stage.
Stages
- Preflight.
- Resolve the repo root.
- Record the baseline signature (see Mutation check in Safety) in
run.md. - Detect the harness and read the subagent tool's live model list.
- Resolve the settings from the invocation and the defaults files (see Defaults files).
- If a state folder exists for the slug, do not start a new run over it. Say so in plain text,
with its status and the
resume <slug>command, and end your turn. Never offer it through an ask-user or question tool. - Note whether
docs/working/proposals/exists.
- Frame. You write
framing.mdyourself, with no subagent, following the Framer checklist in prompts.md. Writerun.mdwith the resolved settings andstatus: framing. - Checkpoint. See below. This is the only human stop.
- Design. Spawn N designers in parallel with the Designer prompt, each with its slot's lens,
model and effort. Log each dispatch first. Save each valid reply to
drafts/<slot>.md. Run the mutation check. - Debate. Run the rounds in order, one at a time. Save each to
round-<k>/and run the mutation check after each.- Round 1: every designer gets its own draft and every peer under shuffled peer labels.
- Rounds 2 to R, or with
rounds=autountil they converge (see Auto rounds): the Rebuttal prompt, with each designer's round k−1 design, the round k−1 critiques aimed at it, and its peers' round k−1 designs. - The last round carries the Final-design note (prompts.md); with
rounds=auto, every round does.
- Completeness. See Completeness below. Write
completeness.md, run any repairs, and run the mutation check if a repair was spawned. - Judge. Spawn the judge with the Judge prompt: final designs under shuffled peer labels, plus all
critiques and dispositions, plus the gaps still open in
completeness.md, relabelled into the judge's mapping. Save tojudge.md. Run the mutation check. - Write.
- Fill proposal-template.md into
docs/working/proposals/YYYY-MM-DD-<slug>.md, creating the folder if needed. Compute the scorecard totals yourself from the judge's per-criterion scores, for every design, ineligible ones included and marked. Never overwrite: if the path exists, use-2,-3, and so on. Appendproposal: <path>andstatus: writtentorun.mdstraight away. Ifrun.mdalready has aproposal:line, do not write a new file: re-validate and repair that file in place. - Validate:
- Run
python3 .github/scripts/docs/check_integrity.pyif it exists. - Check that every relative link and every
path:linecitation in the proposal resolves. The integrity checker skipsdocs/working/. - Check that there are at least 2 mermaid blocks.
- Run
- Set
status: validated, orstatus: written-unvalidatedwith the failures listed. - Run the final mutation check, which allows the one proposal file.
- Fill proposal-template.md into
- Report. See Report.
Completeness
The judge reads only each designer's final design: round-<k>/<slot>.md for the last round run. A design that answered an
item in an earlier draft but dropped it from the final text has not answered it. Check before the
judge, so a gap gets fixed instead of deciding the result.
- For each slot, read the final design's
## Framing answersand check it has an entry for every requirement (R1,R2, …) and open question (Q1,Q2, …) inframing.md, and that each entry says something, not "see above" or "unchanged". - Write
completeness.md: one table, a row per framing item, a column per slot, each cellokormissing. A slot's open gaps are itsmissingcells. - For each slot with gaps, log
dispatch: repair/<slot>and spawn one Repair prompt (prompts.md), with that slot's model and effort, in parallel. No peer designs, so nolabels:line. - A repair is accepted only if the reply has every required heading and keeps every earlier
## Key decisionsbullet word for word. Save an accepted reply torepair/<slot>.md; it becomes that slot's final design. Otherwise keep the last round's design and noterepair rejected: <reason>under the table. - Re-check accepted repairs and update the table. Never send a second repair.
Repairs are best effort and outside the shared retry. A failed, invalid or rejected repair never
uses the retry and never stops the run: the judge scores the gap instead (prompts.md, Judge). On
resume, a repair/<slot> dispatch with no file is re-run once like any uncertain call.
Checkpoint (hard stop)
Present the checkpoint, then end your turn.
- Approval is an explicit new message from the user:
approve, or one or moreeditreplies followed byapprove. - Never ask for approval through an ask-user, question or confirmation tool. In autopilot or unattended modes those are answered automatically, which would skip the only human gate.
- Silence, a timeout, an automated reply or "continue on your own" instructions are not approval. In autopilot, stop at the checkpoint anyway and say why.
The checkpoint message contains:
framing.mdand the state folder as clickable links (see Linking outputs), with a 3–5 line summary of the framing.- The slug and the proposal path. Say if
docs/working/proposals/will be created. - A table of slots, with lens, requested model, resolved model, effort and fallback note for each, plus the judge.
- N, R, the planned calls (
N + N×R + 1, or forrounds=autothe calls through round 1 andNper further round), the up-to-N repair calls and the 1 retry. - Every clamp, fallback and "not applied" setting, which defaults files were read, which settings came from them, and every ignored file or key.
- The reply forms:
approve,edit <setting>=<value>(for exampleedit rounds=1),edit framing(the user edits the file, then repliesapprove), andcancel.
On approve, append the approval line to run.md and set status: approved. On any edit, re-show
the checkpoint. On cancel, append status: stopped:cancelled and end.
Linking outputs
Every file you hand to the user is a link they can click, never a bare path to go and find:
framing.md at the checkpoint, the proposal in the report, and the state folder.
- If the client has a tool that publishes or attaches files to the chat, use it.
- Otherwise write a markdown link with the absolute path:
[proposal](file:///abs/path.md).
Resume and status
design-debate status <slug> reads run.md and lists each stage as done, missing or uncertain.
design-debate resume <slug>:
- Recompute the approval line from the current
framing.mdand settings, defaults files included. If it differs from the recorded one, or there is none, go back to the checkpoint and say why. - If the user re-approves a changed approval line, the earlier designs answered a different
framing or panel. Move
drafts/, everyround-<k>/,completeness.md,repair/andjudge.mdintosuperseded-<n>/in the state folder, keep the retry line, and restart from Design. - If
run.mdhas aproposal:line, go straight to Write step 2: validate and repair that file. - Otherwise skip every valid stage file.
- List each
dispatch:with no valid file as "uncertain, may already be billed", then run it again. These re-runs do not use the retry. - Keep the retry: a
retry-used:line from an earlier session still counts. - Take a fresh baseline signature, and continue from the first incomplete stage.
Safety
-
Every subagent prompt carries the read-only safety block from prompts.md. Use read-only agent types where the harness offers them and they accept a model override; otherwise use a general agent and rely on the block plus the mutation check.
-
Mutation check: the signature is these three values, recorded at preflight and compared after every subagent stage:
git status --porcelain --untracked-files=allgit diff HEAD | git hash-object --stdingit ls-files -o --exclude-standard -z | xargs -0 git hash-object | git hash-object --stdin(contents of untracked files, which the first two miss)
The final check after Write allows exactly the one
proposal:file.- On any difference: set
status: stopped:mutation, list the changed paths, and stop. - Never revert, reset, checkout or stash anything; the change may be the user's own work.
resumetakes a new baseline.
-
The only repository write is the proposal. Never commit, push, open a PR, edit documentation conventions or create tickets.
Failure policy
| Failure | Response |
|---|---|
| Model unavailable | Use the fallback shown at the checkpoint; record the actual model |
| Reply missing a required heading | Use the shared retry for that call, then stop |
| Retry already used, including in an earlier session | Stop, keep state, report incomplete with the resume command. Never continue with fewer designers |
| Session dies mid-stage | resume lists uncertain calls and re-runs them |
| Framing or settings changed after approval | Back to the checkpoint; on re-approval, earlier designs move to superseded-<n>/ and Design restarts |
| Mutation check fails | Stop, list paths, never revert |
| Final design misses a framing item | One repair call for that slot (see Completeness); if it fails, the judge scores the gap. Never uses the retry |
| Judge returns UNRESOLVED | Write the proposal with the gates table and the reasons; status validated if checks pass |
| Proposal fails validation | written-unvalidated, list the failures, keep state for repair |
Report
End with:
- The proposal and the state folder as clickable links, and the proposal's status (
validatedorwritten-unvalidated). - The winner and grafts, in 2–3 lines.
- Planned vs. actual calls (repairs counted separately, with which slots were repaired), the
rounds run (with
rounds=auto: and whether they converged or cycled), requested vs. actual model per slot, and every setting not applied. - Uncertain re-runs, if any, and the resume command if the run is incomplete.
- If the repo documents where working docs go (for example in
AGENTS.md) and does not mentiondocs/working/proposals/, suggest adding it in a separate change. Do not edit it. - Next step: turn section 8 into tickets, with the user's ticket-writing skill if one is installed. Default to one story. Cite the proposal by repo path; use a blob URL only if a pushed branch already contains the file.
Harness notes
- Copilot (CLI and app): spawn with
task, passingmodelandreasoning_effortper call. Prefergeneral-purposeagents: read-only types may not honour a model override. Launch the designers of one stage together, in parallel. The live model list is in thetasktool'smodelparameter. - Claude Code: spawn with
Task, several in one message for parallelism, withmodel: opus|sonnet|haiku. Only Claude models are available, so the judge always shares a family with a designer: declare it. Effort is not applied. - Other clients (Codex, OpenCode, VS Code): untested. Run only if a subagent tool exists (see Requires a subagent tool). Use the models.md "Other harnesses" column, and say in the report that the client is untested so the user can share the result.
Status
Experimental. It is worth keeping once a few real design problems, run in at least two clients, produce proposals that reviewers rate, blind, as more defensible than a single-agent proposal from the same framing.
Before then, check whether lenses earn their place. By default each slot mixes a model and a lens,
so a run cannot tell which one shaped a design. On one real framing, run two extra debates with
rounds=1, each with its own slug. At each checkpoint, reply edit framing and replace that run's
framing.md with the original run's, so all three answer the same framing:
- Same lens, different models:
slug=<slug>-models lenses=pragmatist,pragmatist,pragmatist, with the default model mix. - Same model, different lenses:
slug=<slug>-lenses models=A:<id>,B:<id>,C:<id>(one model id), with the default lenses.
Compare the ## Key decisions of the drafts within each run. If the lens run spreads decisions much
less than the model run, simplify the lenses (for example to one shared brief).