Architecture decision: two designs, a critic and an ADR
Settle a design question with Architecture Debate: two Architect proposals, a Reviewer critique and a final synthesis, saved as a proposed ADR for a person.
Use this template when a team keeps reopening the same design question. Architecture Debate produces two competing proposals, a critique of both and a written decision, before anyone builds the thing.
Which agents run
The steps run one after another, and each sees what came before. Architect B reads the first proposal, so frame the task as a real choice ("a queue, or keep cron") rather than one idea to elaborate. The critic reads both proposals, and the final synthesis weighs all three.
What you get
When the session completes, the final synthesis is recorded as an architecture decision record with status proposed, linked to the session. Nothing is accepted on the AI's word: a person accepts or rejects it under Plan → ADRs.
Like every session on a project with a repository, the workflow ends with a code pass that writes a change. That is why the starting task asks for the decision in docs/adr/: the change is a Markdown file, and it follows the normal path. The AI review reads the diff and records findings, your test command runs against it, and someone other than the person who started the session approves it before the pull request opens.
Cap what a debate can spend
With the Auto model tier, the Architect counts as a steering step and gets the best tier you have allowance for, and this workflow runs it three times. Under Configure → Billing, set a workspace budget, then choose Edit limits and give Architecture Debate its own cap:
| Field | Example value |
|---|---|
| Period | Monthly |
| Hard limit (USD) | 200 |
| Per-workflow caps (USD) | Architecture Debate: 15 |
The cap covers all Architecture Debate sessions in the period. Once their spend reaches it, the next one is refused and a running one stops with Blocked by budget. See cost controls.
Tips
- Put the constraints in the task: data volume, who runs it in production, what must not change.
- Ask one question per session. Two questions get two half-answers.
- If the outcome is close, send a follow-up with the critic's open points instead of starting over.
- Once the decision is accepted, scope the work with the feature spec template.
Frequently asked questions
Do the two architects work at the same time?
No. Architect B runs after Architect A and reads its proposal. Debate describes how the steps divide the work, not timing.
Is the ADR accepted automatically?
No. It is saved as proposed. A person moves it to accepted or rejected under Plan, ADRs.
Will the session change my application code?
It writes whatever the task asks for. This task asks for a Markdown file in docs/adr/, so the change is the decision record itself.