the-frame-ai 0.14.0 → 0.16.0

package/README.md

@@ -15,7 +15,8 @@ If you're building a product alone with Claude Code and want to work like a team
 | Losing context between sessions | Project memory and automatic state dump on session start |
 | Chaos in tasks and priorities | 6-phase workflow: Research → Plan → Build → Review → Ship → Reflect |
 | Fear of breaking something important | Safety hooks block destructive commands before they run |
-| Repetitive routine tasks | 28 ready-made commands for the full development cycle |
+| Repetitive routine tasks | 29 ready-made commands for the full development cycle |
+| Slow, one-by-one fixes after review | `/frame:fix` — closes review findings in parallel, one fixer per file |
 | Complex features with dependencies | Parallel subagents for independent tasks (wave-based planning) |
 | No structure for solo work | Roadmap, STATE.md, MAP.md — always know where you are and what's next |
 | Shipping code with security holes | `/frame:audit` — unified security, performance, and dependency audit before deploy |
@@ -39,7 +40,8 @@ Run `/frame:research <topic>` — Claude explores the codebase and external sour
 `/frame:build` reads the `Parallel:` labels from plan.md and automatically decides whether to run tasks sequentially or in parallel worktrees. No flags needed. Stuck — `/frame:unstuck`. Found a bug — `/frame:debug`.
 
 **Review** — check before deploying
-`/frame:review` runs automated checks and a 6-panel review (spec compliance, security, performance, business logic, tests, conventions) on the diff.
+`/frame:review` runs automated checks and a 6-panel review (spec compliance, security, performance, business logic, tests, conventions) on the diff. FAIL findings are verified adversarially in parallel.
+If review requests changes, `/frame:fix` closes the findings in parallel — one fixer subagent per file, light findings skip the TDD ceremony, one quality-gate run at the end.
 
 **Ship** — deploy and record
 `/frame:ship` commits, optional push/PR, and updates project memory.
@@ -186,7 +188,8 @@ claude -p "/frame:audit quick" --allowedTools "Bash,Read,Write,Grep"
 FRAME provides:
 
 - **6-phase workflow**: Research → Plan → Build → Review → Ship → Reflect
-- **28 commands**: from quick tasks to full feature development cycle
+- **29 commands**: from quick tasks to full feature development cycle
+- **Parallel review fixes**: `/frame:fix` closes findings file-by-file in one pass — no worktrees, no per-fix ceremony
 - **10 AI agents**: Researcher, Planner, Builder, Reviewer, Auditor, Devil's Advocate, Security, Performance Auditor, Tests Reviewer, Conventions Reviewer
 - **Safety Hooks**: block destructive operations, enforce quality gates
 - **Git Safety**: checkpoints, rollback, worktrees, pause/resume
@@ -255,6 +258,7 @@ These commands cover 90% of solo dev work:
 | Command | When to use |
 |---------|-------------|
 | `/frame:build` | Implement plan with TDD — auto-detects sequential vs parallel from plan |
+| `/frame:fix [REV-N ...]` | Close review findings in parallel — one fixer per file, single gates run |
 | `/frame:fast <task>` | Quick task under 30 minutes |
 | `/frame:debug <issue>` | Systematic bug investigation with git archaeology |
 | `/frame:debug --deep` | Deep forensic investigation (parallel investigators, 5-why, timeline) |
@@ -334,6 +338,7 @@ These commands cover 90% of solo dev work:
 | `/frame:debug` | Systematically debug an issue — or run deep forensic investigation with 5-why analysis | `[--deep] <SEC-N|issue description>` |
 | `/frame:doctor` | Check FRAME installation health — verify paths, config, and hook registration | — |
 | `/frame:fast` | Execute a quick task end-to-end without full research/plan cycle | `<task description>` |
+| `/frame:fix` | Close review findings in parallel — groups findings by file, spawns one fixer per non-conflicting group, single gates run at the end | `[feature] [REV-N ...]` |
 | `/frame:health` | Daily health check: tests, lint, types, security scan freshness — or sprint velocity check | `[sprint]` |
 | `/frame:init` | Initialize project: scan codebase, fill MAP.md, STATE.md, and memory files | — |
 | `/frame:migrate` | Plan and execute a database or schema migration with rollback safety | `<migration description>` |
@@ -415,7 +420,7 @@ npx the-frame-ai version               # Show CLI version
 
 ```
 .claude/
-  commands/          # 28 FRAME commands
+  commands/          # 29 FRAME commands
   agents/            # 10 AI agents
   hooks/             # 5 safety hooks
 .frame/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "the-frame-ai",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "FRAME — Framework for AI-Assisted Solo Development",
   "type": "module",
   "bin": {

package/src/languages.js

@@ -74,11 +74,6 @@ const STACK_PRESETS = {
   rust: { typecheck: 'cargo check', test: 'cargo test', lint: 'cargo clippy', build: 'cargo build' },
 };
 
-const MODEL_DESCRIPTIONS = {
-  opus: 'opus   — best quality, slower (recommended for architecture/security)',
-  sonnet: 'sonnet — faster, good for most tasks',
-};
-
 export async function promptConfig(defaultConfig, yes = false) {
   if (!process.stdin.isTTY || yes) return defaultConfig;
 
@@ -118,16 +113,6 @@ export async function promptConfig(defaultConfig, yes = false) {
     }
   }
 
-  console.log('\n? Preferred model for agents:\n');
-  Object.values(MODEL_DESCRIPTIONS).forEach((d, i) => console.log(`  ${i + 1}) ${d}`));
-  const modelAnswer = (await ask(rl, '\n  Enter number [1-2] (or press Enter for opus): ')).trim().toLowerCase();
-  if (modelAnswer === '2' || modelAnswer === 'sonnet') {
-    config.model = 'sonnet';
-    console.log('\x1b[32m✓\x1b[0m Model preference: sonnet');
-  } else {
-    config.model = 'opus';
-  }
-
   rl.close();
   return config;
 }

package/templates/agents/builder.md

@@ -17,7 +17,19 @@ description: "Implementation agent. Writes code using TDD, runs quality gates, c
 
 > **Model**: sonnet (override via `model` in `.frame/config.json`)
 
-## Instructions
+## Execution Modes
+
+The orchestrating command tells you which mode you are in:
+
+| Mode | When | What changes |
+|------|------|--------------|
+| **solo** (default) | Agent invoked directly, no task in the prompt | Full workflow below: find plan.md, loop over all tasks, own checkpoints and commits |
+| **single-task** | `/frame:build` passes exactly one task from a parallel wave | Do **only** that task. Skip Step 1 (don't scan plan.md) and Step 7 (don't loop). Do **not** create checkpoint tags, do **not** edit plan.md/STATE.md — the orchestrator does all of that from your report |
+| **single-fix** | `/frame:fix` passes one group of review findings | Like single-task, but the work is defined by findings (Claim/Evidence/Fix), not a plan task. Ceremony (light vs full-TDD) is specified in the brief. Do **not** commit, do **not** run full gates — only the targeted test for your file(s) |
+
+**In single-task and single-fix modes**: everything you need (task/findings, relevant conventions, anti-patterns) is **in the prompt**. Do NOT read memory/context files yourself — that context is already packed in. Return your report as final text; the orchestrator merges it.
+
+## Instructions (solo mode)
 
 ### Core Workflow
 
@@ -37,13 +49,17 @@ Before doing anything, check:
 
 > **NEVER write .planning/STATE.md** — STATE.md is owned by the orchestrating command, not subagents.
 
-Then create git checkpoint:
+> **single-task / single-fix mode**: skip this checkpoint entirely. The orchestrator already created one feature-scoped checkpoint before spawning the wave — a second tag from inside a subagent both duplicates it and collides with sibling subagents (git tags are repo-global). Jump straight to your task/findings.
+
+Then (solo mode only) create git checkpoint:
 ```bash
-git tag "frame/checkpoint/build-$(date +%Y%m%dT%H%M%S)" -m "Auto checkpoint before build phase"
+git tag "frame/checkpoint/build-{feature}-$(date +%Y%m%dT%H%M%S)" -m "Auto checkpoint before build phase"
 ```
 
 #### Step 1: Find plan.md
 
+> **single-task / single-fix mode**: skip this step. Your work is defined by the task/findings in the prompt, not by scanning plan.md. Go to Step 3.
+
 ```bash
 find docs/specs -name "plan.md" | head -5
 ```
@@ -52,6 +68,8 @@ Read plan.md and find all uncompleted tasks.
 
 #### Step 2: Read Context
 
+> **single-task / single-fix mode**: skip this step. Conventions, anti-patterns, and Memory Impact relevant to your work are already in the prompt. Reading these files again wastes tokens and startup time. Go to Step 3.
+
 Read in this order:
 - `.planning/memory/context.md` — **read first**: current focus and blockers
 - `docs/specs/{feature}/research.md` — **Memory Impact** section (why this approach was chosen)
@@ -71,8 +89,10 @@ Read in this order:
 | Risk | Action |
 |------|--------|
 | `low` | Standard TDD cycle |
-| `medium` | Create checkpoint: `git tag frame/checkpoint/task-{N}` |
-| `high` | Checkpoint + show user warning + **wait for confirmation** before proceeding |
+| `medium` | Create checkpoint: `git tag frame/checkpoint/task-{N}` (solo mode only) |
+| `high` | Checkpoint + show user warning + **wait for confirmation** before proceeding (solo mode only) |
+
+> **single-task / single-fix mode**: you cannot wait for user confirmation — a subagent has no channel to the user. `Risk: high` tasks arrive **already confirmed by the orchestrator** (it asked the user before spawning you). Do not create checkpoint tags. Just do the work.
 
 ##### RED — Write Test
 1. Create test file (in project test directory — see CLAUDE.md)
@@ -117,6 +137,8 @@ If after **3 attempts** the test does not reach GREEN:
 
 #### Step 5: Git Commit
 
+> **single-task mode**: skip commit — the orchestrator commits after the wave's quality gates pass, so wave commits stay atomic and ordered. **single-fix mode**: skip commit and skip full gates — run only the targeted test for your file(s); the orchestrator commits once after all fixers return. In both cases, end at your report (see Task Execution Flow).
+
 ```bash
 git add {specific_files}
 git commit -m "{type}({scope}): {description}"
@@ -126,13 +148,17 @@ git commit -m "{type}({scope}): {description}"
 
 #### Step 6: Update Status
 
-Mark task in plan.md:
+> **single-task / single-fix mode**: do NOT edit plan.md. The orchestrator marks `[DONE]` / `[FIXED]` from your report — concurrent subagents editing the same plan.md would clobber each other.
+
+Mark task in plan.md (solo mode only):
 ```markdown
 ### Task N: {Name} [DONE]
 ```
 
 #### Step 7: Next Task
 
+> **single-task / single-fix mode**: there is no next task. Return your report as final text and stop.
+
 If more tasks exist, go to Step 3.
 If all tasks complete, go to Step 8.
 
@@ -183,10 +209,12 @@ Run final quality gates:
 - **NEVER modify files outside task scope**
 - **NEVER skip quality gates**
 - **NEVER modify memory files** — that is Retrospective's responsibility
-- **NEVER start without plan.md** — fail-fast if missing
+- **NEVER start without plan.md** — fail-fast if missing (solo mode only; single-task/single-fix get their work from the prompt)
+- **NEVER edit plan.md/STATE.md or create checkpoint tags in single-task/single-fix mode** — the orchestrator owns all shared state; concurrent subagents would clobber it
 
 ## Task Execution Flow
 
+### Solo mode
 ```
 Step 0: Fail-fast validation → git checkpoint
 Step 1: Find plan.md
@@ -212,6 +240,36 @@ Tests: PASS | FAIL
 Commit: {hash}
 Acceptance met: {AC ids covered, or "N/A"}
 ```
+
+### single-task mode (one wave task from /frame:build)
+```
+Skip Step 0 checkpoint, Step 1, Step 2 (context is in the prompt).
+Do the one task: RED → GREEN → REFACTOR (or per ceremony in brief).
+Run targeted test for your file(s). Do NOT commit, do NOT run full gates, do NOT touch plan.md/STATE.md.
+Return:
+```
+Task: {task name}
+Status: DONE | FAILED | BLOCKED
+Changed files: {comma-separated list}
+Tests: PASS | FAIL
+Acceptance met: {AC ids covered, or "N/A"}
+Notes: {anything the orchestrator should know}
+```
+
+### single-fix mode (one findings group from /frame:fix)
+```
+Skip Step 0/1/2. Apply the fix(es) from the findings brief (Claim/Evidence/Fix).
+Ceremony per brief: light = direct fix + targeted test; full-TDD = RED → GREEN → REFACTOR.
+Run only the targeted test for your file(s). Do NOT commit, do NOT run full gates, do NOT touch plan.md/STATE.md/review.md.
+Return:
+```
+Group: {file(s)}
+Findings closed: {REV-ids}
+Status: DONE | FAILED | BLOCKED
+Changed files: {comma-separated list}
+Targeted test: PASS | FAIL | none
+Notes: {anything the orchestrator should know}
+```
 ```
 
 ## Success Criteria

package/templates/agents/planner.md

@@ -116,6 +116,16 @@ If a task is too large (Files Changed > 3 or Complexity: high) — split it.
 | `medium` | 3-5 files or touches public APIs |
 | `high` | 5+ files, touches core logic or routing |
 
+**Estimate definition:**
+
+| Estimate | Criteria |
+|----------|----------|
+| `30min` | Complexity: low, 1-2 files, no new abstractions |
+| `1h` | Complexity: medium, 2-3 files, or new type/interface/schema |
+| `2h` | Complexity: medium, 3 files, external integration or DB change |
+
+If a task would need more than 2h — it is not atomic enough. Split it.
+
 For each requirement, identify:
 - What files need to be created/modified
 - What tests need to be written

package/templates/agents/researcher.md

@@ -1,6 +1,6 @@
 ---
 name: researcher
-model: sonnet
+model: opus
 tools:
   - Read
   - Write
@@ -16,7 +16,7 @@ description: "Research agent. Analyzes codebase or web for alternatives and cont
 
 **Job**: Receive a scoped brief from the orchestrating command (codebase scope or web scope), conduct focused research, return findings as final text.
 
-> **Model**: sonnet (override via `model` in `.frame/config.json`).
+> **Model**: opus.
 > **NEVER write .planning/STATE.md** — STATE.md is owned by the orchestrating command, not subagents.
 
 ## Instructions

package/templates/agents/reviewer.md

@@ -164,7 +164,7 @@ Create `docs/specs/{feature}/review.md`:
 
 Return as final text:
 - **PASS**: "Review approved. {N} warnings (non-blocking). Ready for /frame:ship."
-- **FAIL**: "Review failed. {N} critical issues. Fix via /frame:build. See: docs/specs/{feature}/review.md → Action Items"
+- **FAIL**: "Review failed. {N} critical issues. Fix via /frame:fix (parallel), or /frame:build for large changes. See: docs/specs/{feature}/review.md → Action Items"
 
 ## Review Checklist
 

package/templates/commands/frame:build.md

@@ -16,11 +16,13 @@ Reads plan.md, executes tasks with TDD and quality gates. Parallelism is determi
 
 ### Step 0: Checkpoint + Update STATE.md (IN_PROGRESS)
 
-Create checkpoint before starting:
+Create checkpoint before starting (feature-scoped tag — avoids collisions across parallel worktrees):
 ```bash
-git tag "frame/checkpoint/build-$(date +%Y%m%dT%H%M%S)" -m "Auto checkpoint before build phase"
+git tag "frame/checkpoint/build-{feature}-$(date +%Y%m%dT%H%M%S)" -m "Auto checkpoint before build phase"
 ```
 
+This is the **only** build checkpoint. Subagents spawned in Step 4 do **not** create their own tags.
+
 Update `.planning/STATE.md`:
 ```markdown
 ## Current Position
@@ -42,7 +44,7 @@ Read `docs/specs/{feature}/plan.md`. If not found — STOP: "plan.md not found.
 ### Step 2: Determine execution mode
 
 Check `.planning/STATE.md`:
-- `Status: REVIEW_FAILED` → **Fix mode**: read `docs/specs/{feature}/review.md` → Action Items, create fix tasks in plan.md under `## Fix Tasks (review {date})`, then execute using the same algorithm below. Each fix task references its review finding ID.
+- `Status: REVIEW_FAILED` → **prefer `/frame:fix`** for closing review findings — it groups findings by file and fixes them in parallel without the full plan/TDD ceremony. Suggest it: "Review failed with {N} findings. Run `/frame:fix` to close them in parallel." Only continue here in **build fix-mode** when the fixes are large/architectural (findings pile into the same shared files, or require re-planning): read `docs/specs/{feature}/review.md` → Action Items, create fix tasks in plan.md under `## Fix Tasks (review {date})` **with `Files:`, `Wave:`, and a `Parallel:` label on each wave** (otherwise Step 4 can't parallelize them), then execute using the algorithm below. Each fix task references its review finding ID.
 - Normal plan → proceed with Step 3.
 
 ### Step 3: Read Context
@@ -60,6 +62,8 @@ Read before implementing:
 
 ### Step 4: Execute waves from plan.md
 
+**Before any wave — confirm high-risk tasks once.** Scan the whole plan for `Risk: high` tasks. If any exist, list them and **ask the user once**: "These tasks are high-risk: {list}. Proceed with all, or hold some?" Subagents cannot ask mid-run, so all confirmation happens here, up front. Tasks you spawn later are treated as already confirmed.
+
 For each wave defined in plan.md:
 
 #### Wave has 1 task OR `Parallel: no`
@@ -68,22 +72,32 @@ Execute inline (sequential TDD cycle — see Step 4.1 below).
 
 #### Wave has ≥2 tasks AND `Parallel: yes`
 
-Launch one `builder` subagent per task, one message, `isolation: "worktree"`, max 5 concurrent.
+The planner already guarantees **no two tasks in a wave touch the same file** (frame:plan.md Step A4). So parallel builders can safely share the working tree — **no worktree isolation needed** in the normal case.
+
+Launch one `builder` subagent per task, one message, max 5 concurrent. Pass each subagent **`Mode: single-task`**.
 
-Each subagent receives:
-- Task description + Files + Acceptance criteria
-- Relevant conventions (from conventions.md)
-- Anti-patterns to avoid
-- Instructions: return final text with list of changed files + test status + commit hash
+Each subagent receives a self-contained brief (it does NOT read memory/context itself):
+- **Mode: single-task** — do only this task; don't scan plan.md, don't loop, don't checkpoint, don't edit plan.md/STATE.md, don't commit
+- Task description + Files + Acceptance criteria + Risk (already confirmed if high)
+- Relevant conventions (extract the 3-5 applicable rules from conventions.md — don't make the agent read the file)
+- Anti-patterns to avoid (the applicable ones from learnings.md)
+- Instructions: implement + run the targeted test for your file(s); return final text with changed files + test status (no commit hash — orchestrator commits)
 
-After all subagents complete → **wave quality gates**:
+**Isolation exception**: only if a wave's tasks *could* still touch a shared file (e.g. a barrel/index, a config, a lock file the planner couldn't fully separate) — spawn those with `isolation: "worktree"` and, after each returns, bring its work into the current branch with `git cherry-pick {hash}` before running wave gates. Default path (file-disjoint tasks) needs none of this.
+
+After all subagents complete → **wave commit + quality gates** (orchestrator, in the shared tree):
 ```bash
+# commit each task's changes (specific files from the subagent reports)
+git add {files_from_reports}
+git commit -m "{type}({scope}): {wave description}"
+
 {quality.commands.typecheck}
 {quality.commands.test}
 {quality.commands.lint}
 ```
+Then mark each completed task `[DONE]` in plan.md (orchestrator owns plan.md — subagents never touch it).
 
-If wave gates FAIL → retry only the failed tasks (max 2 retries). If still failing:
+If wave gates FAIL → retry only the failed tasks (re-spawn single-task, max 2 retries). If still failing:
 ```bash
 git tag "frame/wave-failure-$(date +%Y%m%dT%H%M%S)"
 ```
@@ -223,6 +237,10 @@ Next step: `/frame:review`
 - **Never modify files outside the task scope** — stay within task boundaries
 - **Parallelism from plan, not flags** — plan.md `Parallel: yes/no` is the source of truth
 - **Max 5 subagents per wave** — concurrency cap
+- **Shared tree by default** — file-disjoint wave tasks need no worktree; use `isolation: "worktree"` + `cherry-pick` only for the shared-file exception
+- **Orchestrator owns commits, plan.md, STATE.md, checkpoints** — single-task subagents own none of these
+- **Confirm high-risk once, up front** — never rely on a subagent to wait for the user
+- **Review fixes → prefer `/frame:fix`** — build fix-mode is only for large/architectural changes
 
 ## Result
 

package/templates/commands/frame:fix.md

@@ -0,0 +1,190 @@
+---
+description: "Close review findings in parallel — groups findings by file, spawns one fixer per non-conflicting group, single gates run at the end"
+argument-hint: "[feature] [REV-N ...]"
+allowed-tools: [Read, Write, Edit, Bash]
+---
+# /frame:fix -- Parallel Review Fixes
+
+Reads `review.md`, takes confirmed FAIL findings, groups them by file, and spawns one fixer subagent per non-conflicting group **in parallel, in the shared tree** (no worktrees — findings in different files never collide). Light findings skip the full TDD ceremony. One quality-gate run at the end, then a scoped re-review.
+
+This is the fast path for "review found N small issues in N different files". For large architectural rework, use `/frame:build` fix-mode instead.
+
+### Routing
+
+- (no args) — fix all confirmed FAIL findings from the current feature's `review.md`
+- `{feature}` — fix findings for a specific feature
+- `REV-1 REV-4 ...` — fix only the listed finding IDs
+
+## Instructions
+
+### Step 0: Find review.md + checkpoint
+
+Determine feature from `.planning/STATE.md` (or the `{feature}` arg). Read `docs/specs/{feature}/review.md`.
+
+If not found → **STOP**: "review.md not found. Run /frame:review first."
+
+Create a single checkpoint (orchestrator-owned, feature-scoped to avoid collisions):
+```bash
+git tag "frame/checkpoint/fix-{feature}-$(date +%Y%m%dT%H%M%S)" -m "Auto checkpoint before fix phase"
+```
+
+### Step 1: Select findings
+
+From `review.md → Findings`, select findings that are **confirmed FAIL**:
+- `Verified: yes` (refuted findings are skipped — they are not real)
+- Severity CRITICAL / HIGH / MEDIUM (LOW findings are optional; include only if explicitly listed by ID)
+
+If `REV-N` IDs were passed as args → restrict to those.
+
+If nothing selected → **STOP**: "No confirmed FAIL findings to fix. Review recommendation: {approve/...}."
+
+**Heartbeat**: "Selected {N} findings to fix across {M} files."
+
+### Step 2: Group by file (conflict-free batches)
+
+Group selected findings so that **no two groups touch the same file**:
+- Findings whose `File` is the same path → one group (one fixer handles them together, so two fixers never edit the same file).
+- Findings in distinct files → separate groups → run in parallel.
+
+Determine each group's ceremony level from the findings' `Effort` field:
+- All findings in the group are `Effort: XS` or `S` → **light** (direct fix + targeted test, no RED-first cycle)
+- Any finding is `Effort: M` or `L` → **full TDD** (RED → GREEN → REFACTOR)
+
+If a finding has no `Effort` field, infer: single-line/local change → light; new logic or multi-function change → full TDD.
+
+### Step 3: Confirm risky fixes up front (before spawning)
+
+Scan selected findings for any that touch core logic, auth, money, migrations, or routing (Severity CRITICAL on such files). If any exist → list them and **ask the user once**: "These fixes touch sensitive areas: {list}. Proceed with all, or hold some for manual review?"
+
+Subagents cannot ask questions mid-run — all confirmation happens here, at the orchestrator level, before any fixer is spawned.
+
+### Step 4: Spawn fixers in parallel
+
+Launch one `builder` subagent **per group, in a single message** (parallel), max 5 concurrent. **No `isolation: "worktree"`** — groups are file-disjoint by construction, so they share the working tree safely.
+
+Each fixer receives a self-contained brief (it does **not** read memory/context files itself — everything it needs is in the prompt):
+- **Mode**: `single-fix` (fix only what is described; do not scan plan.md, do not loop over other tasks, do not create checkpoints, do not edit plan.md/STATE.md)
+- **Findings** (full): for each — `ID`, `File:line`, `Claim`, `Evidence` (code quote), `Fix` (approach), `Effort`
+- **Ceremony**: light or full-TDD (from Step 2)
+- **Relevant conventions**: the specific naming/type/style rules from `conventions.md` that apply to these files (orchestrator extracts and pastes them — 3-5 lines, not the whole file)
+- **Anti-patterns**: any from `learnings.md` that apply to this change
+- **Instructions**: apply the fix; add/adjust a targeted test only if logic changed; run `{quality.commands.test} {file}` for the touched file; do **not** run full gates (orchestrator does that once); do **not** commit (orchestrator commits); return the final report
+
+Each fixer returns:
+```
+Group: {file(s)}
+Findings closed: {REV-ids}
+Status: DONE | FAILED | BLOCKED
+Changed files: {list}
+Targeted test: PASS | FAIL | none
+Notes: {anything the orchestrator should know}
+```
+
+**Heartbeat**: "Spawned {M} fixers, waiting for completion..."
+
+### Step 5: One quality-gate run
+
+After **all** fixers return, run full gates once in the shared tree:
+```bash
+{quality.commands.typecheck}
+{quality.commands.test}
+{quality.commands.lint}
+```
+
+**D-step**: all must pass.
+
+If gates FAIL → identify which group's change caused it (from the error location), re-spawn only that fixer with the error output (max 2 retries). If still failing:
+```bash
+git tag "frame/fix-failure-$(date +%Y%m%dT%H%M%S)"
+```
+Report to the user, do **not** roll back the passing fixes. Stop.
+
+### Step 6: Commit
+
+Commit the fixes (orchestrator-owned). Prefer one commit that references all closed findings:
+```bash
+git add {specific_files}
+git commit -m "fix(review): close {REV-ids}"
+```
+If the groups are logically distinct, one commit per group is also fine. **Never `git add -A`** — add only the files the fixers changed.
+
+Mark each closed finding in `review.md`:
+```markdown
+### [REV-1] {Title}  [FIXED]
+```
+
+### Step 7: Scoped re-review
+
+Re-verify only the categories whose findings were fixed (same idea as `/frame:review audit` — don't re-run the whole panel).
+
+For each closed finding, launch the matching panel agent on the **new** diff to confirm the issue is gone:
+
+| Finding category | Re-review agent |
+|------------------|-----------------|
+| Spec / architecture | reviewer |
+| Security | security |
+| Performance | performance-auditor |
+| Business logic | devils-advocate |
+| Tests | tests-reviewer |
+| Conventions | conventions-reviewer |
+
+Launch the needed agents in one message (parallel). Each confirms: is `REV-N` actually resolved in the diff? Return `RESOLVED | STILL_OPEN` per finding.
+
+Any `STILL_OPEN` → note it, keep the `[FIXED]` mark off that finding, report to user.
+
+### Step 8: Update STATE.md + report
+
+**If all findings RESOLVED**:
+```markdown
+## Current Position
+- Phase: REVIEW
+- Feature: {feature}
+- Status: Review complete, ready to ship
+- Review: docs/specs/{feature}/review.md
+```
+```
+✅ Fixed {N} findings across {M} files ({parallel} in parallel). Gates green, re-review clean.
+   → /frame:ship
+```
+
+**If any STILL_OPEN**:
+```markdown
+## Current Position
+- Phase: BUILD
+- Feature: {feature}
+- Status: REVIEW_FAILED
+- Review: docs/specs/{feature}/review.md
+- Remaining: {list of STILL_OPEN ids}
+```
+```
+⚠️ Closed {X}/{N} findings. Remaining: {ids} — need manual attention or /frame:build.
+```
+
+---
+
+## When to use
+
+- `/frame:review` came back with **request changes** and the findings are localized edits in distinct files.
+- You want the fixes done in one parallel pass instead of a sequential build cycle.
+
+**Not for**: fixes that require re-architecting, cross-cutting changes touching many shared files, or anything where findings pile into the same 1-2 files (no parallelism to gain — use `/frame:build` fix-mode).
+
+## Rules
+
+- **Confirmed FAIL only** — never act on refuted findings
+- **File-disjoint groups** — one file is owned by exactly one fixer; no worktrees needed
+- **Light findings skip TDD** — Effort XS/S get a direct fix; M/L keep full TDD
+- **Subagents don't self-read context** — the orchestrator packs conventions/anti-patterns into the brief
+- **Subagents don't commit or run full gates** — orchestrator does both, once
+- **Confirmation before spawn** — sensitive fixes are cleared with the user up front, never mid-run
+- **Specific files only** — never `git add -A`
+- **Scoped re-review** — only re-run the categories that were fixed
+
+## Result
+
+- Confirmed FAIL findings closed in parallel
+- One quality-gate run, all green
+- Fixes committed with finding references
+- Findings marked `[FIXED]` in review.md
+- Scoped re-review confirms resolution
+- `.planning/STATE.md` updated (ready to ship, or remaining list)

package/templates/commands/frame:plan.md

@@ -83,6 +83,16 @@ If task too large (>3 files or Complexity: high) — split it.
 | `medium` | 3–5 files or touches public APIs |
 | `high` | 5+ files, touches core logic or routing |
 
+**Estimate definition**:
+
+| Estimate | Criteria |
+|----------|----------|
+| `30min` | Complexity: low, 1–2 files, no new abstractions |
+| `1h` | Complexity: medium, 2–3 files, or new type/interface/schema |
+| `2h` | Complexity: medium, 3 files, external integration or DB change |
+
+If a task would need more than 2h — it is not atomic. Split it.
+
 Each task gets:
 - `Acceptance: AC2, AC5` — which ACs it covers
 - `Findings: ` — empty for feature tasks (used in Mode B)

package/templates/commands/frame:review.md

@@ -111,11 +111,17 @@ Launch all panel agents in one message (parallel). Each receives:
 
 ### Step 4: Verification pass
 
-For each **FAIL** finding from the panel:
-1. Open the referenced file at the given line
-2. Attempt to refute the finding: is there validation higher in the stack? Is the condition reachable? Is this a test file?
-3. **Not refuted** → `Verified: yes` — confirmed FAIL
-4. **Refuted** → downgrade to WARN with note `unverified — see appendix`
+Verify **FAIL** findings adversarially, in parallel — launch `devils-advocate` subagents in refute mode, **batches of ≤5** (same pattern as `/frame:audit` Step 3). Each subagent receives one finding + the referenced file content, and tries to refute it:
+- Is there validation higher in the stack?
+- Is the condition reachable?
+- Is this a test/example file?
+- Output: `{ refuted: boolean, reason: string }` — default `refuted: false` unless there is concrete evidence.
+
+Then:
+- **Not refuted** → `Verified: yes` — confirmed FAIL
+- **Refuted** → downgrade to WARN with note `unverified — see appendix`
+
+If there are ≤2 FAIL findings, verifying inline (without subagents) is fine — the parallel path is for larger batches.
 
 Confirmed FAIL findings block ship.
 
@@ -173,7 +179,7 @@ Base: {BASE commit or tag}
 approve | request changes
 
 ## Action Items
-{For each FAIL finding — numbered, actionable. Build fix-mode reads this section.}
+{For each FAIL finding — numbered, actionable. `/frame:fix` (and build fix-mode) read this section. Each item should carry its finding's File and Effort so the fixer can group and scope the work.}
 1. [REV-1] Fix {issue} in {file}:{line}
 2. ...
 
@@ -211,7 +217,7 @@ approve | request changes
 ```
 ❌ Review failed. {N} critical issues.
    Fixes: docs/specs/{feature}/review.md → Action Items
-   Run /frame:build to fix.
+   Run /frame:fix to close them in parallel (or /frame:build for large/architectural changes).
 ```
 
 ---