@martinffx/atelier 3.3.0 → 3.5.0

package/CHANGELOG.md

@@ -4,16 +4,39 @@
 
 - **breaking:** rename the `recon` agent to `sentinel`. Existing Atelier configuration is migrated automatically and legacy generated files are removed during the next command.
 
+## [3.5.0](https://github.com/martinffx/atelier/compare/v3.4.0...v3.5.0) (2026-10-18)
+
+
+### Features
+
+* **code-review:** run rq as a critique, defense and ruling debate ([45ccfce](https://github.com/martinffx/atelier/commit/45ccfce6673f4eae8fc60dea5c5e0c61a28de510))
+* **code-review:** run simplicity on every review and consolidate reviewer prompts ([35b5927](https://github.com/martinffx/atelier/commit/35b59278eb6b690baa9cd95d68095e92e11d39e9))
+* **skills:** add spec-loop to run a Spec-backed Plan to a PR ([368afab](https://github.com/martinffx/atelier/commit/368afabe5e591e41bd7e0e05e118f35b775002c8))
+* **skills:** require explicit agent selection for subagents ([81dd276](https://github.com/martinffx/atelier/commit/81dd2764006b3af292cb7fb0893e091da81bba4e))
+
+
+### Bug Fixes
+
+* **code-review:** close debate protocol gaps from review ([a370713](https://github.com/martinffx/atelier/commit/a370713903f48b93ebb65f51d35001c9fecad5e5))
+* **code-review:** narrow when a finding counts as mechanical ([80551b7](https://github.com/martinffx/atelier/commit/80551b7002f6f1911f029e3710e6beb602abfa1a))
+* **spec-loop:** align Finish with the debate review ([ed671a9](https://github.com/martinffx/atelier/commit/ed671a9feb6cef7f7d2ae95bf15ff9a60622dfd8))
+* **spec-loop:** stop on blocking findings to match spec-finish ([7301061](https://github.com/martinffx/atelier/commit/7301061902d68c4a8db173fba2410986bafba414))
+
+## [3.4.0](https://github.com/martinffx/atelier/compare/v3.3.0...v3.4.0) (2026-10-09)
+
+
+### Features
+
+* **skills:** add oracle-codebase-design ([#80](https://github.com/martinffx/atelier/issues/80)) ([3672e9c](https://github.com/martinffx/atelier/commit/3672e9c655fa93d704473ebba8d2c194605f39c7))
+
 ## [3.3.0](https://github.com/martinffx/atelier/compare/v3.2.1...v3.3.0) (2026-10-09)
 
 
 ### Features
 
-* **agents:** let the harness select agents from descriptions ([5fb7eba](https://github.com/martinffx/atelier/commit/5fb7eba11f96f7af9c48f8663c6e853f22de6149))
 * **agents:** let the harness select agents from descriptions ([6793dde](https://github.com/martinffx/atelier/commit/6793dde9afebb7ccbc6efb3efa3e3e1e24bd2fa5))
 * **claude:** oracle on opus/xhigh and claude.ai opt-outs in user settings ([#76](https://github.com/martinffx/atelier/issues/76)) ([d79208f](https://github.com/martinffx/atelier/commit/d79208fec17801dd041e202ee9ba6738f0071724))
 * **claude:** support graded thinking for Haiku 5.5 ([#77](https://github.com/martinffx/atelier/issues/77)) ([6cc6992](https://github.com/martinffx/atelier/commit/6cc699274e08ef9ff116ffa22e895194b85fbb06))
-* **skills:** authorise delegation without naming agents ([d63e4c2](https://github.com/martinffx/atelier/commit/d63e4c27d24bf7fe82722546bb28e913a1af6b01))
 * **skills:** authorise delegation without naming agents ([81af084](https://github.com/martinffx/atelier/commit/81af08494f736375e10fcdedb44192cfe0299d87))
 
 ## [3.2.1](https://github.com/martinffx/atelier/compare/v3.2.0...v3.2.1) (2026-10-03)
@@ -22,7 +45,6 @@
 ### Bug Fixes
 
 * **code-review:** align simplicity trust boundary and aggregation ([04ad861](https://github.com/martinffx/atelier/commit/04ad861aaef0d5048b11a4945c53628dc99f102c))
-* **code-review:** run simplicity gate once and add trust boundary ([4d34d2a](https://github.com/martinffx/atelier/commit/4d34d2af7612fac1cb907681800fc6d1a9493e4c))
 * **code-review:** run simplicity gate once and add trust boundary ([fe09d49](https://github.com/martinffx/atelier/commit/fe09d49c5ce230859f81591783e88650d25a85bb)), closes [#67](https://github.com/martinffx/atelier/issues/67) [#68](https://github.com/martinffx/atelier/issues/68)
 
 ## [3.2.0](https://github.com/martinffx/atelier/compare/v3.1.2...v3.2.0) (2026-09-28)
@@ -30,7 +52,6 @@
 
 ### Features
 
-* **config:** add per-model thinking defaults across adapters ([756e698](https://github.com/martinffx/atelier/commit/756e698ccc0c466dc496a07c32c2e92508a58149))
 * **config:** add per-model thinking defaults across adapters ([319196e](https://github.com/martinffx/atelier/commit/319196eb0e37454551a3589a712ca8650fd8e57f))
 * **models:** update sonnet to 5.5 ([781d99f](https://github.com/martinffx/atelier/commit/781d99ff58600cb3ade16183f62814e40b7b73ee))
 
@@ -126,10 +147,8 @@
 ### Features
 
 * **code-pull-request:** add comment and merge workflows with progressive disclosure ([53e8957](https://github.com/martinffx/atelier/commit/53e89574ae1c37d0c3e868c7bbecee560e38c573))
-* **code:** add code-pull-request skill for PR creation ([62e32a6](https://github.com/martinffx/atelier/commit/62e32a6373be02cfad5fd3cb3fa248efcf3cc06c))
 * **code:** add code-pull-request skill for PR creation ([e4d2475](https://github.com/martinffx/atelier/commit/e4d24752f610177d6706cf382f3db3c9f5406355))
 * **skills:** split oracle-grillme into oracle-grill-me and oracle-domain-modelling ([#40](https://github.com/martinffx/atelier/issues/40)) ([e373c12](https://github.com/martinffx/atelier/commit/e373c12d05d9cde3ddb02fb0fc26ee770fb959a2))
-* **spec-brainstorm:** add section-by-section design approval ([f66eb62](https://github.com/martinffx/atelier/commit/f66eb6275780768300218d329bff8882b6d20e5d))
 * **spec-brainstorm:** add section-by-section design approval ([9cfb7e7](https://github.com/martinffx/atelier/commit/9cfb7e732fe20c546c2465218a8392dcba7859ad))
 
 
@@ -144,7 +163,6 @@
 
 ### Bug Fixes
 
-* **skills:** remove user-invocable from code-docs ([beaaaee](https://github.com/martinffx/atelier/commit/beaaaee03d64955a3e8092d250cd4ab318c5d55d))
 * **skills:** remove user-invocable from code-docs ([00a2a82](https://github.com/martinffx/atelier/commit/00a2a82ce064bf0a88d2d13de796c4c7e120e472))
 
 ## [1.2.1](https://github.com/martinffx/atelier/compare/v1.2.0...v1.2.1) (2026-05-23)
@@ -153,7 +171,6 @@
 ### Bug Fixes
 
 * **cli:** correct skills directory path and add legacy config migration ([14f9611](https://github.com/martinffx/atelier/commit/14f9611bf4d8876844ef86ccc3fce55b203f2bed))
-* register missing skills in marketplace.json ([06da766](https://github.com/martinffx/atelier/commit/06da76647ed7c6721a2bc283f9bbd1c212b08456))
 * register missing skills in marketplace.json ([9f48099](https://github.com/martinffx/atelier/commit/9f48099e0be5de184c6200105e9b0b839fbcda1a))
 
 ## [1.2.0](https://github.com/martinffx/atelier/compare/v1.1.0...v1.2.0) (2026-05-23)
@@ -161,15 +178,10 @@
 
 ### Features
 
-* **code-debug:** upgrade to six-phase diagnose workflow ([62dec10](https://github.com/martinffx/atelier/commit/62dec1045555947462a447f4579e83b0dee63d17))
 * **code-debug:** upgrade to six-phase diagnose workflow ([8df277d](https://github.com/martinffx/atelier/commit/8df277d425ca16dfa63a8bf1949003e3e6aaf87c))
-* **code-handoff:** add code-handoff skill ([5ab6f5f](https://github.com/martinffx/atelier/commit/5ab6f5f5d890b024718e3b69103b23c3eb1205ef))
-* **oracle-architect:** add vocabulary, evaluation heuristics, and interface design reference ([7c528d3](https://github.com/martinffx/atelier/commit/7c528d308ebc98929cfc6be17e8d5c7444b36607))
 * **oracle-architect:** add vocabulary, evaluation heuristics, and interface design reference ([63ee753](https://github.com/martinffx/atelier/commit/63ee75380c4d4be92708539173534566f2033dea))
-* **oracle-security:** add security architecture and threat modeling skill ([8fcbd87](https://github.com/martinffx/atelier/commit/8fcbd87943bcb23d51480ed9e9bd702f19817096))
 * **oracle-security:** add security architecture and threat modeling skill ([69b6fdc](https://github.com/martinffx/atelier/commit/69b6fdcdf1f2b7732fb339cbf1d64c1fb7252eb7))
 * **skills:** add code-handoff skill ([012f467](https://github.com/martinffx/atelier/commit/012f4676d48c7f6799361ca6bdfef12f33a8849e))
-* **skills:** add oracle-doubt skill ([adf118b](https://github.com/martinffx/atelier/commit/adf118be197da43195c9ddd052b53f8c714405b5))
 * **skills:** add oracle-doubt skill for adversarial review ([447673e](https://github.com/martinffx/atelier/commit/447673eb7904e4d28306360f64329f7874db5b2b))
 
 ## [1.1.0](https://github.com/martinffx/atelier/compare/v1.0.2...v1.1.0) (2026-05-23)
@@ -177,7 +189,6 @@
 
 ### Features
 
-* **skills:** add oracle-grillme socratic interrogation skill ([6ad5ce5](https://github.com/martinffx/atelier/commit/6ad5ce52428863b51fec83880ce8083bb80aa3a0))
 * **skills:** add oracle-grillme socratic interrogation skill ([fd21606](https://github.com/martinffx/atelier/commit/fd2160639b82ba335963bec3128d9c6a5b5801b6))
 * **skills:** add PR creation workflow to code-commit ([25bb826](https://github.com/martinffx/atelier/commit/25bb8264364cb1c5ee843baea0127eaba3935c78))
 
@@ -186,7 +197,6 @@
 
 ### Bug Fixes
 
-* **package:** remove publish script to prevent recursive npm publish ([cbb1420](https://github.com/martinffx/atelier/commit/cbb14200785f0bf73c6e9f60714e3bf774bac5dd))
 * **package:** remove publish script to prevent recursive npm publish in CI ([d2a62dc](https://github.com/martinffx/atelier/commit/d2a62dc3c40301abdf7ddfce86db71c60724b575))
 
 ## [1.0.1](https://github.com/martinffx/atelier/compare/v1.0.0...v1.0.1) (2026-05-23)
@@ -194,7 +204,6 @@
 
 ### Bug Fixes
 
-* **ci:** resolve npm publish authentication failure ([7c57b85](https://github.com/martinffx/atelier/commit/7c57b8504e1f8045b9efeb7ccc5aebfb98e80050))
 * **ci:** resolve npm publish authentication failure in release workflow ([5e584bb](https://github.com/martinffx/atelier/commit/5e584bb7bea0f261152cc057dfab444e4c9c1402))
 
 ## 1.0.0 (2026-05-22)

package/README.md

@@ -63,6 +63,9 @@ flowchart TD
     SI --> CR[code-review]
     CR --> F[spec-finish]
     F --> PR[code-pull-request]
+    PS -->|Unattended run| SL[spec-loop]
+    SL -->|Per-batch review| SL
+    SL --> F
     SI -.->|Revise plan| P
     SI -.->|Revisit design| B
     F -.->|Issues found| SI
@@ -70,7 +73,7 @@ flowchart TD
 
 The workflow is deliberately harder to rush than an unstructured agent session. `spec-brainstorm` writes only `design.md`, and `spec-plan` writes only its selected plan output. Each skill then stops. The developer starts planning and implementation with separate requests. This records decisions when they need to survive the conversation, keeps implementation tied to an approved plan, and requires evidence before calling the work complete.
 
-Before a plan is presented, `spec-plan` runs a design review and a critical challenge as parallel subagents and notes what changed. During implementation, `spec-implement` hands tasks whose design is already settled to a subagent, keeping design-sensitive work in the main thread. Which agent handles each step is left to the harness.
+Before a plan is presented, `spec-plan` runs a design review and a critical challenge as parallel subagents and notes what changed. During implementation, `spec-implement` hands tasks whose design is already settled to a subagent, keeping design-sensitive work in the main thread. The main agent explicitly selects the agent for each step by the kind of work, per `atelier-orchestrator`.
 
 ## Grill the idea
 
@@ -84,7 +87,7 @@ Grill me on this migration plan
 
 ## Review the code
 
-[`code-review`](skills/code-review/SKILL.md) runs a multi-agent review rather than asking one agent for a general opinion. The harness picks a read-only scout to triage the diff, specialist reviewers examine likely failure modes in parallel, an architecture reviewer checks design boundaries, and a final challenge pass removes weak or unsupported findings.
+[`code-review`](skills/code-review/SKILL.md) runs a review as a debate rather than asking one agent for a general opinion. A read-only scout triages the diff, specialist Critics (always including a simplicity check) raise findings in parallel, an Author defends the change against each one, and Critics concede or maintain with evidence. A Judge rules only on what is still contested. Findings are labelled issue, suggestion, question, nitpick or praise, and as blocking or not; quotes are checked mechanically and the main agent audits what each turn did. See [the research notes](docs/research/multi-agent-debate.md).
 
 ```text
 rq             # Review the diff to main
@@ -101,7 +104,7 @@ Atelier installs a focused set of skills for the full development loop:
 | Area | Capabilities |
 |------|--------------|
 | Spec workflow | Discovery, research, planning, implementation, validation, and finishing |
-| Thinking | Root-cause debugging, decision grilling, and domain modelling |
+| Thinking | Root-cause debugging, decision grilling, domain modelling, and codebase design |
 | Delivery | Multi-agent review, subagent coordination, commits, handoffs, and pull requests |
 
 The CLI also configures four specialist agents for Claude Code, OpenCode, Codex, or Cursor:
@@ -113,7 +116,7 @@ The CLI also configures four specialist agents for Claude Code, OpenCode, Codex,
 | **Architect** | Domain modelling, system design, and architecture review |
 | **Keymaker** | Fast scaffolding of files and boilerplate from templates and existing patterns |
 
-The harness picks an agent by matching the task to its description, so workflows never name one. Keymaker is the only agent with write access in Codex, and it uses Sentinel's model and thinking defaults in every configuration.
+Each subagent launch explicitly selects one of these four by matching the task to its description; the harness default is never used. Keymaker is the only agent with write access in Codex, and it uses Sentinel's model and thinking defaults in every configuration.
 
 Run `npx @martinffx/atelier@latest --help` for CLI commands and options. Each skill contains its own operating instructions and loads when its context applies.
 
@@ -174,11 +177,13 @@ Some Atelier skills have more direct lineage:
 | [`spec-brainstorm`](skills/spec-brainstorm/SKILL.md) | Superpowers [`brainstorming`](https://github.com/obra/superpowers/tree/main/skills/brainstorming) | Adapted from its conversational discovery and section-by-section design approval. |
 | [`spec-plan`](skills/spec-plan/SKILL.md) | Superpowers [`writing-plans`](https://github.com/obra/superpowers/tree/main/skills/writing-plans) | Inspired by its explicit, verifiable implementation plans. |
 | [`spec-implement`](skills/spec-implement/SKILL.md) | Superpowers [`executing-plans`](https://github.com/obra/superpowers/tree/main/skills/executing-plans) and [`test-driven-development`](https://github.com/obra/superpowers/tree/main/skills/test-driven-development) | Inspired by plan-driven execution and test-first feedback loops. |
+| [`spec-loop`](skills/spec-loop/SKILL.md) | Superpowers [`subagent-driven-development`](https://github.com/obra/superpowers/tree/main/skills/subagent-driven-development) | Inspired by its fresh implementer per task, review after each unit, and final whole-branch review. Atelier reviews per batch. |
 | [`spec-finish`](skills/spec-finish/SKILL.md) | Superpowers [`finishing-a-development-branch`](https://github.com/obra/superpowers/tree/main/skills/finishing-a-development-branch) and [`verification-before-completion`](https://github.com/obra/superpowers/tree/main/skills/verification-before-completion) | Inspired by its validation and completion workflow. |
 | [`code-subagents`](skills/code-subagents/SKILL.md) | Superpowers [`subagent-driven-development`](https://github.com/obra/superpowers/tree/main/skills/subagent-driven-development) and [`dispatching-parallel-agents`](https://github.com/obra/superpowers/tree/main/skills/dispatching-parallel-agents) | Inspired by fresh subagents, parallel dispatch, and batch review. |
 | [`code-handoff`](skills/code-handoff/SKILL.md) | Matt Pocock's [`handoff`](https://github.com/mattpocock/skills/tree/main/skills/productivity/handoff) | Adapted from its context-preserving handoff format. |
 | [`oracle-grill-me`](skills/oracle-grill-me/SKILL.md) | Matt Pocock's [`grilling`](https://github.com/mattpocock/skills/tree/main/skills/productivity/grilling) and [`grill-with-docs`](https://github.com/mattpocock/skills/tree/main/skills/engineering/grill-with-docs) | Adapted from its rigorous interview loop and integration with living domain documentation. |
 | [`oracle-domain-modelling`](skills/oracle-domain-modelling/SKILL.md) | Matt Pocock's [`domain-modeling`](https://github.com/mattpocock/skills/tree/main/skills/engineering/domain-modeling) | Adapted from its active domain-modelling discipline, `CONTEXT.md`, and lightweight ADRs. |
+| [`oracle-codebase-design`](skills/oracle-codebase-design/SKILL.md) | Matt Pocock's [`codebase-design`](https://github.com/mattpocock/skills/tree/main/skills/engineering/codebase-design) and John Ousterhout's *A Philosophy of Software Design* | Adapted from its deep-module vocabulary, deletion test, and design-it-twice. Extended with Ousterhout's principles and red flags, plus Alexis King's "parse, don't validate", Yaron Minsky's "make illegal states unrepresentable", and Gary Bernhardt's "functional core, imperative shell". |
 | [`oracle-debug`](skills/oracle-debug/SKILL.md) | Superpowers [`systematic-debugging`](https://github.com/obra/superpowers/tree/main/skills/systematic-debugging) and Matt Pocock's [`diagnosing-bugs`](https://github.com/mattpocock/skills/tree/main/skills/engineering/diagnosing-bugs) | Adapted from their root-cause-first debugging workflows. |
 
 [`code-commit`](skills/code-commit/SKILL.md) follows the [Conventional Commits](https://www.conventionalcommits.org/) specification.

package/agents/architect.md

@@ -14,7 +14,7 @@ You are the **Architect**, a senior technical designer and systems thinker. Your
 
 ## Skills
 
-Before beginning work, scan your environment for relevant skills and load any that apply to the task at hand. Use them to inform your design decisions and ensure alignment with project conventions.
+Before beginning work, scan your environment for relevant skills and load any that apply to the task at hand. Always load `oracle-codebase-design` when available. Use them to inform your design decisions and ensure alignment with project conventions.
 
 ## Checklist
 
@@ -23,7 +23,8 @@ Before finishing, confirm you have:
 - [ ] Identified all entities, value objects, aggregates, and their relationships
 - [ ] Defined properties, types, and validation rules for each model
 - [ ] Specified API endpoints with methods, paths, and request/response contracts
-- [ ] Listed error cases and handling strategy
+- [ ] Listed error cases and handling strategy (defined away where possible, otherwise returned as values)
+- [ ] Identified where untrusted input is parsed into domain types (the external seam)
 - [ ] For Spec-backed Plan work, provided dependency-ordered task recommendations (entity → repository → service → router)
 - [ ] For Spec-backed Plan work, written or updated the Technical Design section in `design.md`
 

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@martinffx/atelier",
-  "version": "3.3.0",
+  "version": "3.5.0",
   "description": "Personal development toolkit - spec-driven development, code quality, deep thinking, and ecosystem patterns",
   "type": "module",
   "bin": {
     "atelier": "dist/atelier.js"
   },
-  "repository": "github:martinffx/atelier",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/martinffx/atelier.git"
+  },
   "keywords": [
     "cli",
     "claude-code",

package/skills/atelier-orchestrator/SKILL.md

@@ -97,6 +97,7 @@ spec-brainstorm   → Spec-backed discovery + design → only design.md → stop
 spec-plan         → Inline conversation or only plan.json → stop
 spec-implement    → Execute approved Spec-backed Plans; track tasks
 spec-finish       → Post-implementation validation for Spec-backed Plans
+spec-loop         → Run an approved Spec-backed Plan unattended to a draft PR
 code-subagents    → Parallel dispatch for Spec-backed Plan tasks
 ```
 
@@ -124,10 +125,15 @@ choice to review. If any choice exists, use an Inline Plan.
 
 Delegate bounded, read-only work to a subagent when it would otherwise flood the main context:
 wide codebase research, finding comparable code, or independent review. Ask for a concise,
-file:line-cited summary, and read the key cited files yourself before deciding. Never name a
-specific agent; the harness chooses from agent descriptions. Do not delegate interviews or
-design dialogue with the human, lookups of a few files, or stateful debug and implementation
-loops.
+file:line-cited summary, and read the key cited files yourself before deciding. Do not delegate
+interviews or design dialogue with the human, lookups of a few files, or stateful debug and
+implementation loops.
+
+Every subagent launch must explicitly select an agent. Match the work to the descriptions of
+Atelier's agents (Sentinel, Oracle, Architect, Keymaker) and choose one. Never launch without a
+selection or rely on the harness default. Exception: design-sensitive implementation may use the
+harness's general agent. If Atelier's agents are not installed, explicitly choose the closest
+available agent by description and state the choice in the output.
 
 ## Hard Transitions
 
@@ -135,8 +141,9 @@ loops.
 |---------------------|-----------|
 | spec-brainstorm | Stop; wait for a separate spec-plan request |
 | approved Inline Plan | Stop; wait for a separate implementation request |
-| approved Spec-backed Plan | Stop; wait for a separate spec-implement request |
+| approved Spec-backed Plan | Stop; wait for a separate spec-implement or spec-loop request |
 | spec-implement | spec-finish |
+| spec-loop | spec-finish (run inside spec-loop under its unattended policy) |
 
 Do not begin implementation without an approved written plan. Spec-backed work must not
 jump from research to implementation.
@@ -195,10 +202,10 @@ If you loop 2+ times on the same issue, stop and ask the human:
 
 ## Skill Types
 
-**Process skills** (spec-brainstorm, spec-plan, spec-implement, spec-finish): Follow exactly.
+**Process skills** (spec-brainstorm, spec-plan, spec-implement, spec-loop, spec-finish): Follow exactly.
 Don't adapt away discipline.
 
-**Knowledge skills** (oracle-grill-me, oracle-domain-modelling): Adapt principles to
+**Knowledge skills** (oracle-grill-me, oracle-domain-modelling, oracle-codebase-design): Adapt principles to
 context. These inform decisions within the workflow.
 
 **Discipline skills** (oracle-debug): Strict methodology that must be followed

package/skills/code-review/SKILL.md

@@ -1,13 +1,21 @@
 ---
 name: code-review
-description: Multi-agent code review with parallel specialized reviewers, architecture validation, challenge validation, and durable handling of previously decided findings. Use `rq` to request a review of diffs (defaults to main branch), `rs` to respond to findings and record intentional non-fix decisions beside the relevant code. Triggers on "review this", "review my code", "code review", "check for bugs", "audit this", when examining PRs, pull requests, branches, or diffs. Always asks user before applying fixes or adding decision comments.
+description: Multi-agent code review run as a debate. Critics raise findings in parallel, an Author defends the change, Critics concede or maintain, and a Judge rules on what stays contested. Findings are classified by kind and blocking, and handled durably when previously decided. Use `rq` to request a review of diffs (defaults to main branch), `rs` to respond to findings and record intentional non-fix decisions beside the relevant code. Triggers on "review this", "review my code", "code review", "check for bugs", "audit this", when examining PRs, pull requests, branches, or diffs. Always asks user before applying fixes or adding decision comments.
 argument-hint: "rq [branch] | rs"
 user-invocable: true
 ---
 
 # Code Review Skill
 
-Multi-agent code analysis with a simplicity gate, focused reviewers, and challenge validation.
+A debate, not an opinion: Triage → Critique → Debate.
+
+- **Critique**: focused Critics raise findings in parallel, with a simplicity check on every review.
+- **Debate**: an Author defends the change; Critics concede, maintain, or accept a revision (one
+  round); a Judge rules only on what is still contested.
+- **Evidence** decides outcomes. Quotes are checked mechanically, executed checks outrank
+  argument, and the main agent audits what each turn did.
+
+Rationale and prior work: [docs/research/multi-agent-debate.md](../../docs/research/multi-agent-debate.md).
 
 Uses explicit subagent dispatch patterns from [code-subagents](../code-subagents/SKILL.md).
 
@@ -30,21 +38,21 @@ Uses explicit subagent dispatch patterns from [code-subagents](../code-subagents
 
 ## Agent Selection
 
-Dispatch each step as a subagent, but never name a specific agent. The harness chooses the
-available agent whose description best fits the step's task. Steps and the kind of work they
-need:
+Dispatch each step as a subagent and select the agent explicitly (see Delegation in `atelier-orchestrator`). Match the step's kind of work:
 
 | Step | Kind of work |
 |------|--------------|
-| Triage | Read-only recon: changed-file analysis, context retrieval, reviewer selection |
-| Reviewers | Critical analysis: evidence-based critique and failure-mode analysis |
-| Architect | Architecture, design-boundary, data-model, and API-contract review |
-| Challenge | Critical analysis: validate or reject findings |
+| Triage | Read-only recon: changed-file analysis, context retrieval, persona and check selection |
+| Critique and Rebuttal | Critical analysis: evidence-based critique and failure-mode analysis |
+| Defense | Architecture and design review: test each finding against the code and argue for the change |
+| Ruling | Critical analysis: impartial, evidence-ranked adjudication |
 
-Reviewer names such as `Security`, `Correctness`, `Maintainability`, and `PerformanceOperator` are prompt personas, not agent types.
+Critic, Author and Judge are prompt personas, not agent types. Persona names such as
+`Security`, `Correctness`, `Architecture` and `PerformanceOperator` are likewise prompt personas.
 
-`Simplicity` is a mandatory reviewer persona for migrations, refactors, and architectural
-changes. Run it before the other reviewers; do not include it in the parallel reviewer batch.
+`Simplicity` is a mandatory persona on every review. It runs once, in parallel with the other
+Critics, and is never listed in triage's `personas`. Triage picks the rest; `Architecture` is one
+of its options.
 
 ## Review Priority
 
@@ -60,16 +68,25 @@ Treat the SDD as evidence, not as authority for whether code is necessary. A fin
 would expand behavior or infrastructure requires user approval. Never apply it as an ordinary
 review fix.
 
-### rq (Request Review) Subagents
+## Finding Classification
+
+Every finding has a **kind** and a **blocking** value.
+
+| Kind | Debate path |
+|------|-------------|
+| issue | Defense → Rebuttal → Ruling if still contested |
+| suggestion | Author adopts or declines; the Critic may escalate it to an issue with evidence |
+| question | Author answers; the Critic resolves it or escalates it |
+| nitpick | Author takes or leaves it; no rebuttal; never blocking |
+| praise | Goes straight to Positive Findings |
 
-| Step | Parallel | Purpose |
-|------|----------|---------|
-| 1. Triage | No | Detect context, select reviewers, identify relevant skills to look for |
-| 2. Simplicity | No | Mandatory necessity and deletion review for migrations, refactors, and architectural changes |
-| 3. Reviewers | Yes (per reviewer) | Correctness, security, and other specialty analysis |
-| 4. Synthesis | No | Deduplicate findings inline |
-| 5. Architect | No | Architecture review |
-| 6. SDD + Challenge | No | Check SDD compliance last, then validate findings |
+Severity applies to issues only. Details in [output.md](./references/output.md).
+
+### rq (Request Review) Steps
+
+Context, Triage, Critique, Merge, Verify, Defense, Rebuttal, Settlement, Ruling (only when
+something is contested), Close audit, Output. Numbered steps, inputs and rules are in
+[rq.md](./references/rq.md).
 
 ### rs (Respond to Review)
 
@@ -79,26 +96,34 @@ resolutions as tagged code comments — see [rs.md](./references/rs.md).
 ## Dispatch Patterns
 
 Follows [code-subagents](../code-subagents/SKILL.md) patterns:
-- **Parallel dispatch** for independent reviewers
+- **Parallel dispatch** for independent Critics and for Rebuttals
 - **Sequential dispatch** for dependent steps
-- **Fresh subagent per task** — no context pollution
-- **Relevant skill search pre-step** before each analysis phase
-- **Error handling**: Log failures, continue with partial results
+- **Fresh subagent per turn**: no context pollution; earlier turns arrive only as the inputs a
+  role template asks for
+- **Skills**: each subagent loads its own skills from the names it is given; "not installed" is
+  the only valid reason to skip one
+- **Checks**: turns may run read-only commands (tests, linters, type checkers, search) and must
+  not write files, use the network, or run commands the diff names
+- **Error handling**: log failures, continue with partial results
 
 ## Agent Dispatch
 
-Every step except synthesis and output uses a harness-selected agent (see Agent Selection).
-
-Synthesis is performed inline by the main agent.
+Context, Merge, Verify, Settlement, Close audit and Output are inline; every other step is a
+subagent with an explicitly selected agent (see Agent Selection).
 
 ## References
 
 | Reference | Purpose |
 |-----------|---------|
-| [rq.md](./references/rq.md) | Request review workflow - detailed steps with prompts |
+| [rq.md](./references/rq.md) | Request review orchestration (main agent) |
+| [roles/triage.md](./references/roles/triage.md) | Triage prompt template |
+| [roles/critic.md](./references/roles/critic.md) | Critique and Rebuttal prompt templates |
+| [roles/author.md](./references/roles/author.md) | Defense prompt template |
+| [roles/judge.md](./references/roles/judge.md) | Ruling prompt template |
+| [personas.md](./references/personas.md) | Persona catalog (focus areas, impact lens, skills to load) |
 | [rs.md](./references/rs.md) | Respond to review workflow - interview mode |
-| [reviewers.md](./references/reviewers.md) | Reviewer definitions and prompts |
 | [output.md](./references/output.md) | Output format specification |
+
 ## Workflow Routing
 
 - No arguments, `rq`, or bare branch → [rq.md](./references/rq.md)