feat: revise sdd plan skill to reduce number of review rounds

AGENTS.md

@@ -0,0 +1,43 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this repo is
+
+Personal dotfiles managed with [chezmoi](https://chezmoi.io). This directory (`~/.local/share/chezmoi`) is chezmoi's *source* directory — files here use chezmoi's naming conventions and are rendered/installed into `$HOME` on the target machine, they are not consumed directly from this path.
+
+**Use the `chezmoi` skill (`.claude/skills/chezmoi-skill/SKILL.md`) for any work in this repo.** It covers chezmoi's source-file naming conventions (`dot_`, `private_`, `executable_`, `.tmpl`), machine-specific templating patterns, the required `chezmoi apply --refresh-externals --force` flags, `.chezmoiremove`/`.chezmoiexternal.toml`, and troubleshooting — invoke it rather than re-deriving this from scratch.
+
+## Commands
+
+Preview and apply changes (run from anywhere; chezmoi finds the source dir automatically):
+
+```bash
+chezmoi diff                                  # preview pending changes before applying
+chezmoi apply --refresh-externals --force     # apply — always use both flags (force avoids interactive prompts Claude can't answer)
+chezmoi cat <file>                            # preview a rendered template's output
+chezmoi execute-template '{{ .chezmoi.os }}'  # test a template snippet in isolation
+chezmoi re-add <file>                         # pull an edited target file back into the source dir
+chezmoi status                                # what's pending
+```
+
+Syncing to git (per README.md):
+
+```bash
+chezmoi cd            # cd into the source dir (this repo)
+git add --all && git commit && git push
+chezmoi update        # pull + apply on another machine
+```
+
+There is no build, lint, or test suite — this is a config repo. "Testing" a change means `chezmoi diff`/`chezmoi cat` to check rendering, then `chezmoi apply --refresh-externals --force` and exercising the shell/tool it affects.
+
+## Architecture
+
+- **`run_onchange_before_NN_*.sh`** — idempotent setup scripts chezmoi re-runs whenever their content hash changes, in numeric order (`0` installs apt packages, `1` sets zsh as default shell and installs antidote, `20`+ install individual tools: fzf, diff-so-fancy, vim-plug, tmux plugin manager, lazygit, fonts, nbdime). New machine-setup steps should follow this pattern: a numbered `run_onchange_before_*.sh` with `set -euo pipefail` and an existence check so re-runs are no-ops.
+- **`.chezmoi.toml.tmpl`** — chezmoi's own config template. Interactively prompts once for `github_email`/`machineClass` on a real terminal; when non-interactive (`stdinIsATTY` false), `CODESPACES` is set, or `.chezmoi.username` is `vscode` — auto-detected as `ephemeral`, overridable via `CHEZMOI_EPHEMERAL` — it skips prompting and instead reads `CHEZMOI_GITHUB_EMAIL` (may be left empty) and `CHEZMOI_MACHINE_CLASS` (defaults to `public`). `ephemeral` is written to `[data]` alongside `machineClass`/`github_email` and gates lifecycle-only setup (fonts — see `run_onchange_before_25_fonts.sh.tmpl`). `chezmoi apply` never auto-commits/pushes to this repo on any machine; sync manually per the Commands section below.
+- **Shell startup chain**: `dot_zshrc` sources `bin/term-background` (must run before the p10k instant-prompt block, since it reads the tty for OSC 11 background detection) → p10k instant prompt → `~/.environment`(`dot_environment`) + optional `~/.environment.local` → `~/.aliases` (`dot_aliases`) + optional `~/.aliases.local` → antidote plugin load (plugin list in `dot_zsh_plugins.txt`) → `~/.p10k.zsh`. The `.local` files are gitignored, host-specific overrides — never add machine-specific values directly to the tracked files.
+- **`dot_gitconfig.tmpl`** — templated on `.github_email`, whose `[user] email` line is omitted entirely when `.github_email` is empty (e.g. an ephemeral machine with no `CHEZMOI_GITHUB_EMAIL` set); wires up diff-so-fancy as the pager and nbdime for Jupyter notebook diffing. `~/.gitconfig.local` (untracked) is included for machine-specific overrides.
+- **`private_dot_config/`** → installs to `~/.config/` with restrictive permissions (nvim, matplotlib styles, fontconfig).
+- **`bin/`** → installs to `~/bin/`; `executable_term-background` detects terminal light/dark background via OSC 11 for theme-matching in nvim etc.
+- **`.chezmoiignore`** lists source-repo-only paths (`README.md`, `.codex`, `.agents`, `CLAUDE.md`, `CLAUDE.local.md`, `key.txt.age`) that chezmoi should never install to `$HOME`, plus a `machineClass`-gated conditional excluding `.ssh/config.d/home`, `.ssh/config.d/web`, and `.claude/settings.json` on any machine that isn't `machineClass = "private"` — `~/.claude/settings.json` has no user-level `.local.json` merge mechanism, so machines with differing Claude Code config (e.g. `enabledPlugins`) manage that file by hand instead of via chezmoi.
+- **Age encryption**: `key.txt.age` (repo root) is an age private key encrypted with a passphrase.`run_onchange_before_02_decrypt-age-key.sh.tmpl` decrypts it into `~/.config/chezmoi/key.txt`.

CLAUDE.md

@@ -1,43 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## What this repo is
-
-Personal dotfiles managed with [chezmoi](https://chezmoi.io). This directory (`~/.local/share/chezmoi`) is chezmoi's *source* directory — files here use chezmoi's naming conventions and are rendered/installed into `$HOME` on the target machine, they are not consumed directly from this path.
-
-**Use the `chezmoi` skill (`.claude/skills/chezmoi-skill/SKILL.md`) for any work in this repo.** It covers chezmoi's source-file naming conventions (`dot_`, `private_`, `executable_`, `.tmpl`), machine-specific templating patterns, the required `chezmoi apply --refresh-externals --force` flags, `.chezmoiremove`/`.chezmoiexternal.toml`, and troubleshooting — invoke it rather than re-deriving this from scratch.
-
-## Commands
-
-Preview and apply changes (run from anywhere; chezmoi finds the source dir automatically):
-
-```bash
-chezmoi diff                                  # preview pending changes before applying
-chezmoi apply --refresh-externals --force     # apply — always use both flags (force avoids interactive prompts Claude can't answer)
-chezmoi cat <file>                            # preview a rendered template's output
-chezmoi execute-template '{{ .chezmoi.os }}'  # test a template snippet in isolation
-chezmoi re-add <file>                         # pull an edited target file back into the source dir
-chezmoi status                                # what's pending
-```
-
-Syncing to git (per README.md):
-
-```bash
-chezmoi cd            # cd into the source dir (this repo)
-git add --all && git commit && git push
-chezmoi update        # pull + apply on another machine
-```
-
-There is no build, lint, or test suite — this is a config repo. "Testing" a change means `chezmoi diff`/`chezmoi cat` to check rendering, then `chezmoi apply --refresh-externals --force` and exercising the shell/tool it affects.
-
-## Architecture
-
-- **`run_onchange_before_NN_*.sh`** — idempotent setup scripts chezmoi re-runs whenever their content hash changes, in numeric order (`0` installs apt packages, `1` sets zsh as default shell and installs antidote, `20`+ install individual tools: fzf, diff-so-fancy, vim-plug, tmux plugin manager, lazygit, fonts, nbdime). New machine-setup steps should follow this pattern: a numbered `run_onchange_before_*.sh` with `set -euo pipefail` and an existence check so re-runs are no-ops.
-- **`.chezmoi.toml.tmpl`** — chezmoi's own config template. Interactively prompts once for `github_email`/`machineClass` on a real terminal; when non-interactive (`stdinIsATTY` false), `CODESPACES` is set, or `.chezmoi.username` is `vscode` — auto-detected as `ephemeral`, overridable via `CHEZMOI_EPHEMERAL` — it skips prompting and instead reads `CHEZMOI_GITHUB_EMAIL` (may be left empty) and `CHEZMOI_MACHINE_CLASS` (defaults to `public`). `ephemeral` is written to `[data]` alongside `machineClass`/`github_email` and gates lifecycle-only setup (fonts — see `run_onchange_before_25_fonts.sh.tmpl`). `chezmoi apply` never auto-commits/pushes to this repo on any machine; sync manually per the Commands section below.
-- **Shell startup chain**: `dot_zshrc` sources `bin/term-background` (must run before the p10k instant-prompt block, since it reads the tty for OSC 11 background detection) → p10k instant prompt → `~/.environment`(`dot_environment`) + optional `~/.environment.local` → `~/.aliases` (`dot_aliases`) + optional `~/.aliases.local` → antidote plugin load (plugin list in `dot_zsh_plugins.txt`) → `~/.p10k.zsh`. The `.local` files are gitignored, host-specific overrides — never add machine-specific values directly to the tracked files.
-- **`dot_gitconfig.tmpl`** — templated on `.github_email`, whose `[user] email` line is omitted entirely when `.github_email` is empty (e.g. an ephemeral machine with no `CHEZMOI_GITHUB_EMAIL` set); wires up diff-so-fancy as the pager and nbdime for Jupyter notebook diffing. `~/.gitconfig.local` (untracked) is included for machine-specific overrides.
-- **`private_dot_config/`** → installs to `~/.config/` with restrictive permissions (nvim, matplotlib styles, fontconfig).
-- **`bin/`** → installs to `~/bin/`; `executable_term-background` detects terminal light/dark background via OSC 11 for theme-matching in nvim etc.
-- **`.chezmoiignore`** lists source-repo-only paths (`README.md`, `.codex`, `.agents`, `CLAUDE.md`, `CLAUDE.local.md`, `key.txt.age`) that chezmoi should never install to `$HOME`, plus a `machineClass`-gated conditional excluding `.ssh/config.d/home`, `.ssh/config.d/web`, and `.claude/settings.json` on any machine that isn't `machineClass = "private"` — `~/.claude/settings.json` has no user-level `.local.json` merge mechanism, so machines with differing Claude Code config (e.g. `enabledPlugins`) manage that file by hand instead of via chezmoi.
-- **Age encryption**: `key.txt.age` (repo root) is an age private key encrypted with a passphrase.`run_onchange_before_02_decrypt-age-key.sh.tmpl` decrypts it into `~/.config/chezmoi/key.txt`.

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

dot_claude/skills/sdd-code-review/SKILL.md

@@ -6,7 +6,7 @@ description: >-
   "did the implementation match the spec", or "review the changes".
   Also invoked internally by sdd-implement at run completion.
 context: fork
-model: opus
+model: sonnet
 effort: high
 allowed-tools:
   - Agent
@@ -56,13 +56,13 @@ Assemble for each reviewer:
 
 ## Step 2: Fan out reviewer subagents in parallel
 
-Dispatch all applicable reviewers **at once**. Do not wait for one before dispatching
+Dispatch all applicable reviewers **at once**, via the Agent tool with `model: sonnet`.
-the next. Wait for all to complete before aggregating.
+Do no wait for one before dispatching the next. Wait for all to complete before aggregating.
 
 ### Agent 1 — Developer Review
 
 ```
-Task (general-purpose):
+Task (general-purpose, model: sonnet):
   You are a senior software engineer reviewing code for quality, correctness, and spec compliance.
   Do NOT modify any code. Do NOT invoke subagents.
 
@@ -109,7 +109,7 @@ Task (general-purpose):
 ### Agent 2 — Quality Engineer Review
 
 ```
-Task (general-purpose):
+Task (general-purpose, model: sonnet):
   You are a QA engineer reviewing code for test coverage and correctness.
   Do NOT modify any code. Do NOT invoke subagents.
 
@@ -150,7 +150,7 @@ Task (general-purpose):
 ### Agent 3 — Security Engineer Review
 
 ```
-Task (general-purpose):
+Task (general-purpose, model: sonnet):
   You are a security engineer reviewing code for vulnerabilities and data safety.
   Do NOT modify any code. Do NOT invoke subagents.
 
@@ -190,7 +190,7 @@ Task (general-purpose):
 ### Agent 4 — DevOps Review
 
 ```
-Task (general-purpose):
+Task (general-purpose, model: sonnet):
   You are a DevOps/platform engineer reviewing code for operational readiness.
   Do NOT modify any code. Do NOT invoke subagents.
 
@@ -231,7 +231,7 @@ assets, accessibility attributes). Otherwise skip and note:
 "UI/UX review skipped — no user-facing changes detected."
 
 ```
-Task (general-purpose):
+Task (general-purpose, model: sonnet):
   You are a UI/UX designer reviewing code for user experience quality.
   Do NOT modify any code. Do NOT invoke subagents.
 
@@ -271,7 +271,7 @@ through the normal aggregation. Always dispatch it (every spec has a Documentati
 Scope of Change to check against).
 
 ```
-Task (general-purpose):
+Task (general-purpose, model: sonnet):
   You are a documentation reviewer checking that the architecture and user docs were updated
   to match the implemented change. Do NOT modify any code or docs. Do NOT invoke subagents.
 

dot_claude/skills/sdd-implement/SKILL.md

@@ -5,7 +5,7 @@ description: >-
   updating architecture and user docs as part of the work.
   Use when asked to "implement the spec", "start implementing <feature>", "implement spec-<slug>.md",
   or when the user points to a spec file to implement. Accepts a --worktree flag.
-model: opus
+model: Sonnet
 effort: high
 allowed-tools:
   - Agent

dot_claude/skills/sdd-plan/SKILL.md

@@ -218,39 +218,25 @@ The **Documentation** subsection under Scope of Change is mandatory and non-empt
 state why explicitly there. Every Functional Requirement must carry a concrete **Verify**
 block; an FR you cannot describe how to verify is not yet specified well enough.
 
-## Step 5: Agentic review loop (owned here)
+## Step 5: Agentic review (single automatic pass)
 
-Do NOT self-review. You own this loop; `sdd-spec-review` is a pure critic that only returns
+Do NOT self-review. `sdd-spec-review` is a pure critic that only returns findings. This step
-findings.
+runs **once, automatically** — do NOT auto-apply fixes and do NOT auto-loop. Step 6 hands
+control to the user for everything after this pass.
 
 1. Invoke the **Skill tool** with `skill: "sdd-spec-review"`, passing the spec path:
    ```
    Spec file: <path to spec-<slug>.md>
    ```
 2. Collect the returned findings (grouped Critical / Important / Minor) and verdict.
-3. **Surface the findings before you act — never fix silently.** Report to the user, for this
+3. For every Critical and Important finding, draft a **proposed fix** — the concrete change you
-   pass:
+   would make to the spec to resolve it — but do NOT apply anything yet.
-   - the pass number and the overall verdict;
-   - each Critical and Important finding, one line each;
-   - for each, the change you will make to the spec to address it.
 
-   Format it as a short list, e.g.:
+## Step 6: Human-in-the-loop review & approval
-   ```
-   Review pass 1 — NEEDS_REVISION (2 Critical, 1 Important)
-   - [Critical] <finding> → will <fix>
-   - [Critical] <finding> → will <fix>
-   - [Important] <finding> → will <fix>
-   ```
-4. If the verdict is `NEEDS_REVISION` (any Critical or Important findings): apply the fixes you
-   just described to the spec for **every** Critical and Important finding, then go back to
-   step 1 with a **fresh** `sdd-spec-review` invocation.
-5. Repeat until the reviewer returns `APPROVED` (no Critical/Important findings), capped at
-   **3 passes**. If issues remain after the cap, stop looping and carry them into Step 6.
-   **Retain each unresolved finding's full text — title, description, Impact, and Suggested
-   fix — verbatim from the reviewer.** You will present these richly in Step 6, so do not
-   reduce them to one-liners here.
 
-## Step 6: Human approval gate (owned here)
+This is a collaborative loop the user drives, not a gate you run alone. The user is expected to
+read the spec and the critique themselves; your job is to present findings with proposed
+solutions, then discuss, revise, and let the user decide when to re-review or approve.
 
 ### 6a. Present to user
 
@@ -258,42 +244,47 @@ Present in this order:
 
 1. **Spec summary** — 3–5 sentences: what is being built, why, the chosen approach, and the
    most important constraints/decisions.
-2. **Spec path** — the file location.
+2. **Key design decisions** — the most consequential choices made so far, giving the user the
-3. **Resolved review findings** — a compact table of the Critical/Important findings the loop
+   context they need before evaluating the findings below.
-   already fixed. Keep this terse; these are done and need nothing from the user. Omit Minor
+3. **Spec path** — the file location, so the user can read it directly.
-   nits entirely.
+4. **Review findings with proposed solutions** — every Critical and Important finding from
+   Step 5, each with your proposed fix, so the user can accept, push back on, or ignore each
+   independently. Write each in clear, plain language the user can act on without re-reading the
+   spec or the raw reviewer output — not a terse restatement of the reviewer's finding:
 
-   | Issue | How addressed |
+   > **<finding title>** [Critical|Important]
-   |-------|---------------|
-   | <one line> | <one line — what changed in the spec> |
-
-4. **Open findings needing your input** — include this section **only if** findings remain
-   after the 3-pass cap. Do NOT put open findings in the table above, and never write
-   "cap reached" as their explanation — that tells the user nothing. Present each one with
-   enough substance to act on without re-reading the spec:
-
-   > **<finding title>**
    > - What it is: <1–3 sentences describing the problem, with enough context to locate it in the spec>
    > - Why it matters: <the impact — what breaks or stays ambiguous for implementation>
-   > - Suggested fix: <the concrete change you recommend>
+   > - Proposed fix: <the concrete change you'd make>
 
-   (Repeat per open finding, drawn from the full finding text you retained in Step 5.) After
+   List Minor findings compactly, one line each (or omit if none are worth the user's time) —
-   the list, state plainly that these are what the agentic review would still refine and that
+   they don't need the same treatment.
-   the spec is otherwise sound — a spec need not be perfect to be implementable.
+5. **Overall verdict** from this review pass — APPROVED or NEEDS_REVISION.
 
-5. **Overall verdict** — APPROVED, or NEEDS_REVISION with the count of open findings.
+Then stop and hand control to the user — tell them you're ready to discuss, revise, or move to
-6. **Key design decisions** — the most consequential choices made.
+implementation whenever they are. Do not apply any fix yet.
 
-### 6b. Wait for response
+### 6b. Discuss and revise
 
-- **User approves** → the spec is final. Stop here. Do not derive tasks. Do not implement.
+The user drives this part. Expect any mix of:
-  Suggest the user invoke `sdd-implement` (optionally `--worktree`) to proceed.
+- Accepting a proposed fix as-is.
-- **User gives feedback** → you are the sole mutator of the spec: apply their changes to the
+- Pushing back on a proposed fix or the finding itself — discuss it, and if they're right, drop
-  spec file, then return to **Step 6a** immediately.
+  or change the fix rather than applying it reflexively.
-- **When open findings are present**, make the choices explicit and let the user pick: (a) tell
+- Adding their own review comments beyond what the agentic reviewer found.
-  you which open findings to address — you apply the suggested fixes (or their variant) and
+- Asking you to apply some proposed fixes and leave others open.
-  re-present; (b) run another agentic review round (return to Step 5); or (c) approve as-is,
+
-  accepting the open findings. Do not re-run the agentic review automatically unless asked.
+You are the sole mutator of the spec: apply whatever is agreed upon via Edit, and confirm what
+changed. Keep iterating on this discussion for as long as the user wants — there is no fixed
+number of rounds and no cap.
+
+### 6c. Next round or approval — the user's call
+
+Once the user is satisfied with the current round of changes, ask explicitly what they want to
+do next (don't assume):
+- **Run another `sdd-spec-review` pass** — a fresh invocation, back to Step 5. Only do this when
+  the user asks for it; never re-run the agentic review automatically.
+- **Approve as final** — stop here. Do not derive tasks. Do not implement. Suggest the user
+  invoke `sdd-implement` (optionally `--worktree`) to proceed.
 
 ## Principles
 
@@ -305,11 +296,11 @@ Present in this order:
 - Functional and non-functional requirements both belong in the spec.
 - The spec is ephemeral and lives in the repo root as `spec-<slug>.md`; never delete it.
 - You own the review loop and the human gate, and you are the only skill that edits the spec.
-- Always run the agentic review loop (Step 5) before the human gate — never self-review.
+- Run exactly one automatic agentic review pass (Step 5) before handing control to the user —
-- On each review pass, surface the Critical/Important findings and the fix you will make for
+  never self-review, never auto-apply fixes, never auto-loop past that first pass.
-  each before applying them — the loop is visible, never silent.
+- Present every Critical/Important finding with a proposed fix, but leave the decision to apply
-- Present unresolved findings (cap reached) actionably: description, why it matters, and a
+  it to the user — never fix silently.
-  concrete suggested fix — never as a bare line whose only explanation is "cap reached".
+- The user controls the pace: what to accept, push back on, or add themselves, and whether
-- After human feedback, apply changes and re-present immediately (Step 6a).
+  another review round runs or the spec is approved as-is. Only re-review when asked.
 - Do not implement anything, even if it seems obvious. Human approval is the gate before
   implementation.

dot_claude/skills/sdd-spec-review/SKILL.md

@@ -8,7 +8,6 @@ context: fork
 model: opus
 effort: high
 allowed-tools:
-  - Agent
   - AskUserQuestion
   - Glob
   - Grep
@@ -18,30 +17,24 @@ allowed-tools:
 
 # Spec Review
 
-You are a spec-review orchestrator and a **pure critic**. You fan out specialist reviewer
+You are a **pure critic**. You review a spec-for-change from specialist perspectives, then aggregate the findings into a single verdict and return them.
-subagents in parallel, aggregate their findings into a single verdict, and return them.
 
 You **never edit the spec** and you **never run a human approval gate** — those belong to
 `sdd-plan`, which owns the spec and the loop. Your only output is findings + a verdict.
 
-**Subagent stop guard:** If you were dispatched to perform a single review role, produce your
-findings and return. Do NOT invoke further subagents. Do NOT edit the spec.
-
 ## Step 1: Read the spec
 
 1. Locate the spec file. If a path was passed in, use it. If invoked standalone with no path,
    look for `spec-*.md` in the repo root; if there are several, ask the user which one.
 2. Read the spec completely (no limit/offset).
 
-## Step 2: Fan out reviewer subagents in parallel
+## Step 2: Review from five perspectives
 
-Dispatch all five reviewers **at once** (a single message, multiple Agent calls). Do not wait
+Work through the spec and review it from the five perspectives below. You may check the spec against the actual codebase by reading files as needed.
-for one before dispatching the next. Wait for all to return before aggregating. Pass the full
-spec content to each.
 
-Each reviewer uses the output contract below. **Every finding must be self-contained and
+Each perspective produces findings using the output contract below. **Every finding must be
-actionable** — enough detail that someone could fix it without re-reading the reviewer's mind.
+self-contained and actionable** — enough detail that someone could fix it without re-reading
-Use this exact per-finding structure:
+your reasoning. Use this exact per-finding structure:
 
 ```
 - **<short title>** — <what is wrong, missing, or ambiguous, with enough context to locate it
@@ -69,115 +62,62 @@ examples, or details the implementer can reasonably decide within the guardrails
 Critical/Important; put them in Minor or omit them. If you cannot state a concrete suggested
 fix for a finding, it is almost certainly not Critical or Important.
 
-**When you dispatch each reviewer, append this entire contract verbatim to its prompt** — a
+Apply the severity calibration below to every perspective — it governs what counts as
-subagent only sees what you send it, so the per-finding structure and severity calibration must
+Critical/Important/Minor across all five passes, not just one.
-be included in every reviewer prompt.
 
-### Reviewer 1 — Completeness & Clarity
+### Perspective 1 — Completeness & Clarity
 
-```
+Do not praise the spec — find problems. Evaluate:
-Task (general-purpose):
+- Are all sections present and non-empty (Summary, Problem Statement, Current State, Goals,
-  You are reviewing a spec-for-change for completeness and clarity. Do NOT edit it. Do NOT
+  Non-Goals, Functional Requirements, Non-Functional Requirements, Design & Architectural
-  invoke subagents. Do not praise it — find problems.
+  Decisions, Scope of Change, Edge Cases, Risks & Constraints)?
+- Does every Functional Requirement carry a concrete **Verify** block?
+- Is each requirement unambiguous and individually verifiable?
+- Is anything important missing or left implicit?
+- Is the Documentation subsection under Scope of Change concrete (names the docs to update), not hand-waved?
 
-  Spec content:
+### Perspective 2 — Internal Consistency
-  <full spec>
 
-  Evaluate:
+Evaluate:
-  - Are all sections present and non-empty (Summary, Problem Statement, Current State, Goals,
+- Do Goals, Requirements (FR/NFR), and Design & Architectural Decisions agree with each other?
-    Non-Goals, Functional Requirements, Non-Functional Requirements, Design & Architectural
+- Do any Non-Goals contradict a stated Goal or Requirement?
-    Decisions, Scope of Change, Edge Cases, Risks & Constraints)?
+- Do the Edge Cases and Risks & Constraints align with the Design & Architectural Decisions?
-  - Does every Functional Requirement carry a concrete **Verify** block?
+- Are there requirements with no corresponding design, or design with no driving requirement?
-  - Is each requirement unambiguous and individually verifiable?
-  - Is anything important missing or left implicit?
-  - Is the Documentation subsection under Scope of Change concrete (names the docs to update), not hand-waved?
 
-  Output the Critical / Important / Minor / Verdict contract.
+### Perspective 3 — Architectural Soundness
-```
 
-### Reviewer 2 — Internal Consistency
+Read existing code with Read/Glob/Grep as needed to check the design against reality. Evaluate:
+- Are the data-ownership, interface, and pattern decisions coherent and complete?
+- Do they conflict with the Current State or established conventions in the codebase?
+- Are the chosen interfaces/contracts at the right boundary? Any leaky or missing abstractions?
+- Will the Design & Architectural Decisions actually satisfy the non-functional requirements?
 
-```
+### Perspective 4 — Irreversibility & Risk
-Task (general-purpose):
-  You are reviewing a spec-for-change for internal consistency. Do NOT edit it. Do NOT invoke subagents.
 
-  Spec content:
+Evaluate:
-  <full spec>
+- Are hard-to-reverse decisions (schema changes, persisted data formats, public API/contract
+  changes, migrations) explicitly called out with their consequences?
+- What could break existing behaviour? Are the Constraints sufficient to prevent it?
+- Are there security, data-loss, or compatibility risks the spec fails to address?
+- Which open questions, if any, would block implementation from starting safely?
 
-  Evaluate:
+### Perspective 5 — Testability
-  - Do Goals, Requirements (FR/NFR), and Design & Architectural Decisions agree with each other?
-  - Do any Non-Goals contradict a stated Goal or Requirement?
-  - Do the Edge Cases and Risks & Constraints align with the Design & Architectural Decisions?
-  - Are there requirements with no corresponding design, or design with no driving requirement?
 
-  Output the Critical / Important / Minor / Verdict contract.
+Evaluate as a QA engineer would:
-```
+- Does every Functional Requirement have a **Verify** block, and is that block concrete and
-
+  actionable (a real test, command + expected output, or observable behaviour) rather than vague?
-### Reviewer 3 — Architectural Soundness
+- Are the Goals measurable?
-
+- Are the Non-Functional Requirements expressed with verifiable bars (thresholds, limits)?
-```
+- Are the Edge Cases concrete enough to write tests from?
-Task (general-purpose):
+- Could an implementer turn the Verify blocks straight into acceptance tests, or would they have to guess?
-  You are a software architect reviewing a spec-for-change. Do NOT edit it. Do NOT invoke subagents.
-  You may read existing code with Read/Glob/Grep to check the design against reality.
-
-  Spec content:
-  <full spec>
-
-  Evaluate:
-  - Are the data-ownership, interface, and pattern decisions coherent and complete?
-  - Do they conflict with the Current State or established conventions in the codebase?
-  - Are the chosen interfaces/contracts at the right boundary? Any leaky or missing abstractions?
-  - Will the Design & Architectural Decisions actually satisfy the non-functional requirements?
-
-  Output the Critical / Important / Minor / Verdict contract.
-```
-
-### Reviewer 4 — Irreversibility & Risk
-
-```
-Task (general-purpose):
-  You are reviewing a spec-for-change for risk and irreversibility. Do NOT edit it. Do NOT invoke subagents.
-
-  Spec content:
-  <full spec>
-
-  Evaluate:
-  - Are hard-to-reverse decisions (schema changes, persisted data formats, public API/contract
-    changes, migrations) explicitly called out with their consequences?
-  - What could break existing behaviour? Are the Constraints sufficient to prevent it?
-  - Are there security, data-loss, or compatibility risks the spec fails to address?
-  - Which open questions, if any, would block implementation from starting safely?
-
-  Output the Critical / Important / Minor / Verdict contract.
-```
-
-### Reviewer 5 — Testability
-
-```
-Task (general-purpose):
-  You are a QA engineer reviewing a spec-for-change for testability. Do NOT edit it. Do NOT invoke subagents.
-
-  Spec content:
-  <full spec>
-
-  Evaluate:
-  - Does every Functional Requirement have a **Verify** block, and is that block concrete and
-    actionable (a real test, command + expected output, or observable behaviour) rather than vague?
-  - Are the Goals measurable?
-  - Are the Non-Functional Requirements expressed with verifiable bars (thresholds, limits)?
-  - Are the Edge Cases concrete enough to write tests from?
-  - Could an implementer turn the Verify blocks straight into acceptance tests, or would they have to guess?
-
-  Output the Critical / Important / Minor / Verdict contract.
-```
 
 ## Step 3: Aggregate
 
-Once all reviewers return:
+Once all five passes are done:
 
-1. **Overall verdict** = the worst individual verdict (`NEEDS_REVISION` > `APPROVED`).
+1. **Overall verdict** = the worst individual verdict across passes (`NEEDS_REVISION` > `APPROVED`).
-2. **Deduplicate** overlapping findings across reviewers — when two reviewers raise the same
+2. **Deduplicate** overlapping findings across passes — when two passes raise the same issue,
-   issue, merge them but keep the fullest description, impact, and suggested fix.
+   merge them but keep the fullest description, impact, and suggested fix.
 3. **Group by severity**: Critical → Important → Minor.
 4. **Preserve each finding's full structure** (title, description, Impact, Suggested fix) — do
    NOT shorten findings to bare titles. The caller needs the detail to act on or present them.
@@ -199,7 +139,6 @@ finding forces `NEEDS_REVISION`.
 ## Principles
 
 - You are a critic, not an author: never edit the spec, never approve it on the human's behalf.
-- All reviewer subagents run in parallel — never sequentially.
+- Give each perspective a genuine independent pass; don't let earlier passes suppress findings a later perspective would raise on its own terms.
-- Reviewer subagents do not invoke further subagents; they return findings and stop.
+- Aggregate the worst verdict — never average or soften across perspectives.
-- Aggregate the worst verdict — never average or soften across reviewers.
 - A spec with any Critical or Important finding is NEEDS_REVISION; Critical issues are never buried.

dot_claude/skills/vibe/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: vibe
+description: >
+  Delegate coding tasks to Mistral Vibe CLI for cost-efficient execution.
+  Use this skill whenever a task is straightforward, well-defined, and does not
+  require Claude's full reasoning capabilities — simple refactors, boilerplate generation,
+  test scaffolding, documentation updates, file renaming, linting fixes, dependency bumps,
+  small bug fixes, formatting, or mechanical code changes. Also use when the user explicitly
+  asks to use Vibe, Devstral, or Mistral for a task. Do NOT use for complex architectural
+  decisions, multi-step debugging requiring deep reasoning, or security-sensitive code review.
+---
+
+# Mistral Vibe CLI Delegation Skill
+
+Delegate simple, well-defined coding tasks to Mistral's Vibe CLI agent
+to save Claude tokens for harder problems. Vibe runs non-interactively via `--prompt` and returns
+results that Claude summarizes for the user.
+
+## Prerequisites
+
+- Do not use this skill if you are mistral vibe.
+- `vibe` CLI installed and on `PATH`
+- Confirm installation: `vibe --version`; resolve any errors before using this skill
+
+If `vibe` is not installed or not configured, inform the user and provide the installation
+instructions above. Do NOT attempt to run vibe commands if the prerequisites are not met.
+
+## How It Works
+
+1. Claude evaluates the user's request
+2. If the task is simple/mechanical, Claude delegates to Vibe via a shell command
+3. Vibe runs non-interactively with `--prompt`, auto-approving tool executions
+4. Vibe needs a trusted folder to run. Always add the `--trust` flag to prompts
+4. Claude reads the output and summarizes results back to the user
+5. If Vibe's output is insufficient or incorrect, Claude can either retry with a refined
+   prompt or fall back to handling the task itself
+
+## Task Routing Guidelines
+
+### Delegate to Vibe (cheap, fast)
+- Boilerplate generation (new files, structs, interfaces, CRUD endpoints)
+- Simple refactors (rename, extract function, move code between files)
+- Test scaffolding and simple test writing
+- Documentation and comment generation
+- Formatting, linting fixes, import sorting
+- Dependency version bumps
+- Mechanical find-and-replace across files
+- Adding error handling to straightforward functions
+- Generating type definitions or interfaces from existing code
+- Simple bug fixes where the issue is clearly identified
+
+### Keep in Claude (complex, nuanced)
+- Architectural decisions or design pattern selection
+- Security-sensitive code review or vulnerability analysis
+- Complex multi-step debugging requiring deep reasoning
+- Performance optimization requiring profiling analysis
+- Tasks requiring understanding of the full project context across many files
+- Anything the user explicitly wants Claude to handle
+
+### When in doubt
+Ask the user: "This looks like it could be delegated to Vibe to save tokens.
+Want me to handle it myself or delegate?"
+
+## CLI Usage
+
+### Basic non-interactive execution
+
+```bash
+vibe --prompt "<task description>" --max-turns <N> --trust 2>/dev/null
+```
+
+### Flags reference
+
+| Flag | Description | Default in --prompt mode |
+|------|-------------|--------------------------|
+| `--prompt "<task>"` | Run non-interactively with this prompt | Required |
+| `--max-turns N` | Limit assistant turns | No limit |
+| `--enabled-tools TOOL` | Restrict to specific tools (can repeat) | All tools enabled |
+
+### Important notes
+
+- `--prompt` mode automatically enables auto-approve (no user confirmation needed)
+- `--trust` trusts the current working directory and is always required.
+- Stderr contains thinking tokens / debug output — suppress with `2>/dev/null` to avoid
+  bloating Claude Code's context window
+- If the user explicitly asks to see Vibe's thinking/reasoning, omit the `2>/dev/null`
+- Vibe requires a trusted folder — always append --trust
+
+## Execution Patterns
+
+### Pattern 1: Simple task delegation (most common)
+
+For a contained, single-purpose task:
+
+```bash
+cd /path/to/project && vibe --prompt "Add JSDoc comments to all exported functions in src/utils.ts" --max-turns 10 2>/dev/null
+```
+
+### Pattern 2: Read-only analysis
+
+For tasks that only need to read code (no writes):
+
+```bash
+cd /path/to/project && vibe --prompt "List all API endpoints in this project with their HTTP methods and paths" --enabled-tools read_file --enabled-tools grep --max-turns 8 2>/dev/null
+```
+
+### Pattern 3: Scoped file edits
+
+For edits limited to specific files:
+
+```bash
+cd /path/to/project && vibe --prompt "Refactor the error handling in src/api/client.rs to use thiserror instead of manual impl. Only modify files in src/api/." --max-turns 15 2>/dev/null
+```
+
+### Pattern 4: Test generation
+
+```bash
+cd /path/to/project && vibe --prompt "Generate unit tests for the functions in src/auth/token.go. Use the standard testing package. Place tests in src/auth/token_test.go" --max-turns 12 2>/dev/null
+```
+
+## Prompt Engineering for Vibe
+
+When constructing the `--prompt` string for Vibe, follow these guidelines:
+
+1. **Be specific and self-contained** — Vibe does not have the conversation context that Claude has.
+   Include all relevant details: file paths, function names, expected behavior, constraints.
+
+2. **Specify scope explicitly** — Tell Vibe which files/directories to work in and which to avoid.
+
+3. **State the expected output** — "Create a new file at X", "Modify function Y in file Z",
+   "Print a summary to stdout".
+
+4. **Include language/framework context** — "This is a Rust project using Actix-web",
+   "This is a SvelteKit app with TypeScript".
+
+5. **Set boundaries** — "Do not modify any files outside src/api/",
+   "Do not add new dependencies".
+
+## Handling Vibe Output
+
+After Vibe completes:
+
+1. **Read the stdout output** — This contains Vibe's actions and results
+2. **Verify the changes** — Check modified files if needed (use `git diff` or read the files)
+3. **Summarize for the user** — Tell them what Vibe did, what files changed, and whether
+   the task completed successfully
+4. **Handle failures gracefully** — If Vibe failed or produced incorrect results:
+   - For minor issues: retry with a more specific prompt
+   - For fundamental failures: fall back to handling the task directly with Claude
+   - Always inform the user what happened
+
+## Example Workflow
+
+**User says:** "Add error handling to the API calls in src/services/"
+
+**Claude's process:**
+1. Recognizes this as a mechanical task suitable for Vibe
+2. Constructs a specific prompt with project context
+3. Runs:
+```bash
+cd /path/to/project && vibe --prompt "Add proper error handling (try/catch or Result types as appropriate) to all API call functions in the src/services/ directory. Preserve existing function signatures. Use the project's existing error handling patterns." --max-turns 15 --max-price 0.50 2>/dev/null
+```
+4. Reads output, verifies changes with `git diff --stat`
+5. Reports to user: "Vibe updated 4 files in src/services/ — added error handling to 12 API calls. Here's a summary of changes: ..."

dot_gitconfig.tmpl

@@ -6,7 +6,7 @@
     email = {{ .github_email | quote }}
 {{- end }}
 [core]
-    pager = sh -c 'command -v diff-so-fancy >/dev/null && exec diff-so-fancy || less --tabs=4 -RX'
+	pager = sh -c 'command -v diff-so-fancy >/dev/null && diff-so-fancy | less --tabs=4 -RX || less --tabs=4 -RX'
 	autocrlf = input
 	attributesFile = {{ .chezmoi.homeDir }}/.gitattributes
 [alias]
@@ -15,7 +15,7 @@
 	br = branch
     worktree-ai = "!~/bin/git-worktree-ai"
 [interactive]
-    diffFilter = sh -c 'command -v diff-so-fancy >/dev/null && exec diff-so-fancy --patch || exec cat'
+	diffFilter = sh -c 'command -v diff-so-fancy >/dev/null && diff-so-fancy --patch || cat'
 [color]
 	ui = true
 [color "diff-highlight"]

dot_vibe/symlink_skills

@@ -0,0 +1 @@
+../.claude/skills