@martinffx/atelier 3.4.0 → 3.6.0

package/CHANGELOG.md

@@ -4,6 +4,31 @@
 
 - **breaking:** rename the `recon` agent to `sentinel`. Existing Atelier configuration is migrated automatically and legacy generated files are removed during the next command.
 
+## [3.6.0](https://github.com/martinffx/atelier/compare/v3.5.0...v3.6.0) (2026-10-25)
+
+
+### Features
+
+* **claude:** disable conflicting Claude Code built-ins ([40e074d](https://github.com/martinffx/atelier/commit/40e074df4e55a300ea4521fb05fad9232525715d))
+
+## [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)
 
 

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
@@ -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.
 
@@ -138,7 +141,7 @@ Run `atelier update --harness <claude|codex|opencode>` to choose models and thin
 
 Thinking is stored as `agents[].thinking`, `build_thinking`, and `plan_thinking` in `~/.atelier/config.json`. Values are model-specific: `default`, `off`, `on`, `low`, `medium`, `high`, `xhigh`, or `max`. The picker offers only verified capabilities. Custom models and catalog models whose controls have not been verified offer `default` only. Missing fields preserve legacy behavior; **Keep existing behavior** preserves that omission when editing. In particular, old Codex configurations retain medium agent/Build effort and high Plan effort. An explicit `default` omits Atelier's native effort override; other harness settings can still apply.
 
-- **Claude Code:** `opusplan` switches Opus/Sonnet by mode. Other session models share one thinking setting across modes. Atelier writes canonical `modelSettings.<model>.effortLevel` entries and subagent `effort`. Session `max` cannot be persisted, though supported subagents can use it. Use Claude Code **2.1.280 or later** for Opus 5.5 and the current aliases. Atelier also sets `disableClaudeAiConnectors: true`, `syncClaudeAiSkills: false` and `syncClaudeAiPlugins: false` in `~/.claude/settings.json`, so nothing from claude.ai is synced into Claude Code; `atelier remove` clears them unless you changed them. [Claude configuration](https://code.claude.com/docs/en/model-config)
+- **Claude Code:** `opusplan` switches Opus/Sonnet by mode. Other session models share one thinking setting across modes. Atelier writes canonical `modelSettings.<model>.effortLevel` entries and subagent `effort`. Session `max` cannot be persisted, though supported subagents can use it. Use Claude Code **2.1.280 or later** for Opus 5.5 and the current aliases. Atelier also sets `disableClaudeAiConnectors: true`, `syncClaudeAiSkills: false` and `syncClaudeAiPlugins: false` in `~/.claude/settings.json`, so nothing from claude.ai is synced into Claude Code; `atelier remove` clears them unless you changed them. It also disables the Claude Code built-ins that clash with Atelier skills (`disableBundledSkills`, `enableArtifact: false`, `disableWorkflows`, deny rules for `Artifact`, `ArtifactComments`, `ArtifactData`, `Workflow` and `DesignSync`, and `skillOverrides` turning off the `/security-review` and `/ultrareview` commands). Interactive `init` also offers a checklist of optional built-ins to disable, none selected by default: `cron` (`/loop` and the Cron tools), `chrome` (the claude-in-chrome MCP server) and `remote-trigger` (`RemoteTrigger`). `atelier remove` and unticking an option undo these the same way. [Claude configuration](https://code.claude.com/docs/en/model-config)
 - **Codex:** Plan and Build share the selected session model, with separate reasoning settings. Oracle and Architect use independent Astra configurations. `off` maps to native `none`, available on Sol/Luna but not Astra. [Codex configuration](https://developers.openai.com/codex/config-reference/)
 - **OpenCode:** all five assignments are independent. Use **1.18.30 or later** for GPT-6 integration. Atelier sends explicit provider options rather than relying on automatically discovered reasoning variants: `reasoningEffort` for OpenAI-compatible routes, `effort` for Anthropic, and `reasoningConfig` for Bedrock. GLM 5.3 supports low/high/max; it does not support medium. Bedrock defaults use US inference profiles with `us-east-1`. [OpenCode agents](https://opencode.ai/docs/agents/)
 - **MiMo:** `on`/`off` maps to `thinking.type: enabled`/`disabled`. There are no graded effort tiers. OpenCode agent files omit the old fixed temperature override so provider defaults apply. [MiMo API](https://mimo.mi.com/docs/en-US/api/chat/openai-api)
@@ -174,6 +177,7 @@ 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. |

package/dist/atelier.js

@@ -32570,7 +32570,10 @@ var OpenCodeConfigSchema = objectType({
   plan_thinking: ThinkingSchema.optional(),
   agents: arrayType(ThinkingAgentSchema).min(1)
 }).superRefine((config, ctx) => checkThinking("opencode", config, ctx));
-var ClaudeConfigSchema = SimpleConfigSchema.superRefine((config, ctx) => {
+var CLAUDE_OPTIONAL_BUILTINS = ["cron", "chrome", "remote-trigger"];
+var ClaudeConfigSchema = SimpleConfigSchema.extend({
+  disabled_builtins: arrayType(enumType(CLAUDE_OPTIONAL_BUILTINS)).optional()
+}).superRefine((config, ctx) => {
   checkThinking("claude", config, ctx);
   if (config.default_model !== "opusplan" && config.plan_thinking !== undefined && config.plan_thinking !== config.build_thinking) {
     ctx.addIssue({ code: "custom", path: ["plan_thinking"], message: "Separate Claude Plan/Build thinking requires opusplan" });
@@ -32602,6 +32605,16 @@ var CLAUDE_AI_OPT_OUTS = {
   syncClaudeAiSkills: false,
   syncClaudeAiPlugins: false
 };
+var CONFLICTING_BUILTINS = {
+  settings: { disableBundledSkills: true, enableArtifact: false, disableWorkflows: true },
+  deny: ["Artifact", "ArtifactComments", "ArtifactData", "Workflow", "DesignSync"],
+  skillOverrides: ["security-review", "ultrareview"]
+};
+var OPTIONAL_BUILTINS = {
+  cron: { env: { CLAUDE_CODE_DISABLE_CRON: "1" } },
+  chrome: { deniedMcpServers: ["claude-in-chrome"] },
+  "remote-trigger": { deny: ["RemoteTrigger"] }
+};
 var claudeAdapter = {
   name: "claude",
   configSchema: ClaudeConfigSchema,
@@ -32631,7 +32644,15 @@ function modelsForProvider(_provider) {
   return [...ANTHROPIC_MODELS];
 }
 async function promptSection(prompt, section) {
-  return promptForSimpleModels(prompt, section, modelsForProvider());
+  const claude = section;
+  const result = await promptForSimpleModels(prompt, claude, modelsForProvider());
+  const { disabled } = await prompt.prompt([{
+    type: "checkbox",
+    name: "disabled",
+    message: "Disable optional Claude Code built-ins",
+    choices: CLAUDE_OPTIONAL_BUILTINS.map((value) => ({ name: value, value, checked: claude.disabled_builtins?.includes(value) ?? false }))
+  }]);
+  return { ...result, disabled_builtins: disabled };
 }
 function installAgents(section, basePath) {
   const config = ClaudeConfigSchema.parse(section);
@@ -32671,6 +32692,13 @@ function mergeHarnessConfig(section, basePath) {
     model: config.default_model || DEFAULT_MODELS.default_model
   };
   applyModeThinking(settings, config);
+  applyBuiltins(settings, CONFLICTING_BUILTINS);
+  for (const name of CLAUDE_OPTIONAL_BUILTINS) {
+    if (config.disabled_builtins?.includes(name))
+      applyBuiltins(settings, OPTIONAL_BUILTINS[name]);
+    else
+      removeBuiltins(settings, OPTIONAL_BUILTINS[name]);
+  }
   try {
     mkdirSync2(claudeDir, { recursive: true });
     writeFileSync3(settingsPath, JSON.stringify(settings, null, 2) + `
@@ -32729,6 +32757,9 @@ function removeAtelierSettings(claudeDir, config) {
       delete content[key];
   }
   applyModeThinking(content, config, true);
+  removeBuiltins(content, CONFLICTING_BUILTINS);
+  for (const patch of Object.values(OPTIONAL_BUILTINS))
+    removeBuiltins(content, patch);
   writeOrDeleteSettings(settingsPath, content);
 }
 function applyModeThinking(settings, config, remove = false) {
@@ -32753,6 +32784,75 @@ function applyModeThinking(settings, config, remove = false) {
   else
     delete settings.modelSettings;
 }
+function applyBuiltins(settings, patch) {
+  Object.assign(settings, patch.settings);
+  if (patch.env)
+    settings.env = { ...settings.env, ...patch.env };
+  if (patch.deny) {
+    const permissions = { ...settings.permissions };
+    const deny = permissions.deny ?? [];
+    permissions.deny = [...deny, ...patch.deny.filter((rule) => !deny.includes(rule))];
+    settings.permissions = permissions;
+  }
+  if (patch.skillOverrides) {
+    const overrides = { ...settings.skillOverrides };
+    for (const name of patch.skillOverrides)
+      overrides[name] = "off";
+    settings.skillOverrides = overrides;
+  }
+  if (patch.deniedMcpServers) {
+    const denied = settings.deniedMcpServers ?? [];
+    const missing = patch.deniedMcpServers.filter((name) => !denied.some((entry) => entry.serverName === name));
+    settings.deniedMcpServers = [...denied, ...missing.map((serverName) => ({ serverName }))];
+  }
+}
+function removeBuiltins(settings, patch) {
+  for (const [key, value] of Object.entries(patch.settings ?? {})) {
+    if (settings[key] === value)
+      delete settings[key];
+  }
+  if (patch.env) {
+    const env = { ...settings.env };
+    for (const [key, value] of Object.entries(patch.env)) {
+      if (env[key] === value)
+        delete env[key];
+    }
+    if (Object.keys(env).length)
+      settings.env = env;
+    else
+      delete settings.env;
+  }
+  if (patch.deny && settings.permissions) {
+    const permissions = { ...settings.permissions };
+    const deny = (permissions.deny ?? []).filter((rule) => !patch.deny.includes(rule));
+    if (deny.length)
+      permissions.deny = deny;
+    else
+      delete permissions.deny;
+    if (Object.keys(permissions).length)
+      settings.permissions = permissions;
+    else
+      delete settings.permissions;
+  }
+  if (patch.skillOverrides && settings.skillOverrides) {
+    const overrides = { ...settings.skillOverrides };
+    for (const name of patch.skillOverrides) {
+      if (overrides[name] === "off")
+        delete overrides[name];
+    }
+    if (Object.keys(overrides).length)
+      settings.skillOverrides = overrides;
+    else
+      delete settings.skillOverrides;
+  }
+  if (patch.deniedMcpServers && settings.deniedMcpServers) {
+    const denied = settings.deniedMcpServers.filter((entry) => !patch.deniedMcpServers.includes(entry.serverName ?? ""));
+    if (denied.length)
+      settings.deniedMcpServers = denied;
+    else
+      delete settings.deniedMcpServers;
+  }
+}
 function parseSettingsJson(settingsPath) {
   try {
     return JSON.parse(readFileSync4(settingsPath, "utf-8"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@martinffx/atelier",
-  "version": "3.4.0",
+  "version": "3.6.0",
   "description": "Personal development toolkit - spec-driven development, code quality, deep thinking, and ecosystem patterns",
   "type": "module",
   "bin": {

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,7 +202,7 @@ 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, oracle-codebase-design): Adapt principles to

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)