nitm-ai-dev-toolkit 5.2.0 → 5.3.0

package/src/repo/.claude/commands/bootstrap-patch.md

@@ -1,6 +1,6 @@
 ---
 description: Patch AI instructions by fetching updates from the toolkit repo and applying new/updated/missing guidance
-allowed-tools: "Read, Write, Edit, Bash(*)"
+allowed-tools: "Read, Write, Edit, Bash(*), Task"
 argument-hint: "optional patch options"
 ---
 
@@ -10,6 +10,6 @@ argument-hint: "optional patch options"
 | Agent | When to use |
 |-------|-------------|
 | `fixer` | Standard patch — incremental changes to existing config |
-| `planner` | Complex patch — cross-cutting changes needing analysis first |
+| `reviewer` | Independent read-only review before approval and after apply |
 
 Follow the prompt defined in [.claude/prompt-snippets/bootstrap-patch.md](../prompt-snippets/bootstrap-patch.md).

package/src/repo/.claude/commands/constitution.md

@@ -1,6 +1,6 @@
 ---
 description: Create or update the project constitution defining core principles and guidelines
-allowed-tools: "Read, Write, Edit, Bash(*)"
+allowed-tools: "Read, Write, Edit, Bash(*), Task"
 argument-hint: "no arguments required"
 ---
 

package/src/repo/.claude/commands/create-skill.md

@@ -1,6 +1,6 @@
 ---
 description: Create a new agent skill following VS Code and agentskills.io specifications
-allowed-tools: "Read, Write, Edit, Bash(*)"
+allowed-tools: "Read, Write, Edit, Bash(*), Task"
 argument-hint: "skill name and requirements"
 ---
 

package/src/repo/.claude/commands/implement-feature.md

@@ -1,6 +1,6 @@
 ---
 description: Implement a feature by completing tasks sequentially
-allowed-tools: "Read, Write, Edit, Bash(*)"
+allowed-tools: "Read, Write, Edit, Bash(*), Task"
 argument-hint: "feature specification or task list"
 ---
 
@@ -10,6 +10,6 @@ argument-hint: "feature specification or task list"
 | Agent | When to use |
 |-------|-------------|
 | `fixer` | Bounded feature work — spec is clear, files are known |
-| `feature-builder` | Complex feature — needs research, planning, and coordination |
+| `feature-builder` | Complex feature build — builder only; the orchestrator still runs the review |
 
 Follow the prompt defined in [.claude/prompt-snippets/implement-feature.md](../prompt-snippets/implement-feature.md).

package/src/repo/.claude/commands/implement-fixes.md

@@ -1,6 +1,6 @@
 ---
 description: Implement bug fixes with proper tracking and validation
-allowed-tools: "Read, Write, Edit, Bash(*)"
+allowed-tools: "Read, Write, Edit, Bash(*), Task"
 argument-hint: "bug description or fix requirements"
 ---
 

package/src/repo/.claude/commands/implement.md

@@ -1,6 +1,6 @@
 ---
 description: Execute implementation tasks from a task list or specification
-allowed-tools: "Read, Write, Edit, Bash(*)"
+allowed-tools: "Read, Write, Edit, Bash(*), Task"
 argument-hint: "task list or specification"
 ---
 

package/src/repo/.claude/commands/plan.md

@@ -1,6 +1,6 @@
 ---
 description: Create an implementation plan from a feature specification or requirement
-allowed-tools: "Read, Write, Edit, Bash(*)"
+allowed-tools: "Read, Write, Edit, Bash(*), Task"
 argument-hint: "feature specification or requirement"
 ---
 

package/src/repo/.claude/prompt-snippets/assign-tasks.md

@@ -49,6 +49,7 @@ When interacting with {{ISSUE_TRACKER}}, use MCP tools first (see the `issue-tra
 
 1. **Parse Document**:
    - Load the specified document (.md, .txt, .json)
+   - For `tasks.md`, load sibling `spec.md` when present; otherwise load sibling `plan.md` under **Requirements Source** and **Acceptance Criteria** as the requirements source. For a requirement document supplied directly, use its requirements and acceptance criteria. If the source or criteria are missing or unclear, ask the user before creating tickets; do not require creating a specification.
    - Detect document structure (headers, lists, task categories)
    - For `tasks.md`, detect the format first:
      - **Slim** (has `- [ ] T<n>` or `- [x] T<n>` lines): each such line is one task. The text after the ID is the summary. Sub-bullets, if any, are subtasks. A line already has a ticket only when it ends with ` — {{PROJECT_KEY}}-<digits>`; skip it then. Any other ` — ` suffix (e.g. ` — depends on T3`) is a note, not a key: keep the line
@@ -72,7 +73,7 @@ When interacting with {{ISSUE_TRACKER}}, use MCP tools first (see the `issue-tra
    - **Task**: Implementation work, 2-8 story points (avoid < 2 SP)
    - **Subtask**: Only for complex tasks, 1-3 story points (use sparingly)
 
-4. **Estimate Effort** (`tasks.md` has no effort field: take hours from `plan.md` for the matching work, or estimate from the scope in `spec.md`):
+4. **Estimate Effort** (`tasks.md` has no effort field: take hours from `plan.md` for the matching work, or estimate from the selected requirements source):
    - 0.5-1 hours → **Merge with related task** (too small alone)
    - 2-3 hours → 2 story points
    - 4-6 hours → 3-5 story points
@@ -84,7 +85,7 @@ When interacting with {{ISSUE_TRACKER}}, use MCP tools first (see the `issue-tra
    - Link child issues to parents
    - Set assignees, labels, and story points
    - Create dependency links where noted
-   - Ticket description: the task summary plus the acceptance criteria from `spec.md` for that deliverable
+   - Ticket description: the task summary plus the acceptance criteria from the selected requirements source for that deliverable (`spec.md` when present, otherwise `plan.md` for a task checklist, or the directly supplied requirement document). Preserve the original criteria and constraints; include a source path/issue key and section reference. Do not copy acceptance criteria into `tasks.md`.
    - **Slim `tasks.md`**: append ` — <KEY>` at the end of the task's line, after any notes (`- [ ] T1 Schema + migration — PROJ-124`)
    - **Legacy `tasks.md`**: never write back. Record heading → ticket key in the report instead
 

package/src/repo/.claude/prompt-snippets/bootstrap-patch.md

@@ -185,26 +185,28 @@ The CLI runs the same patch flow without an AI session: `npx nitm-ai-dev-toolkit
 
     ### Summary
 
-    - **Auto-apply**: X add + Y update entries, as printed by `patch`
+    - **Apply after review and user approval**: X add + Y update entries, as printed by `patch`
     - **Review needed**: Z needs-review files and W wrapper proposals
     - **Not written**: N not-relevant or retired entries
     - **No action**: W files already current
     ```
 
-5.  **Confirm and Apply**:
+    **Independent review loop (before approval/apply, including dry-run):**
+    - The orchestrator derives acceptance checks from the user's request and the safeguards above; no new spec, plan, persistent state, or configuration is required. The patch author prepares/repairs the proposal and reports evidence, but cannot approve its own work.
+    - The orchestrator dispatches an independent read-only `reviewer` (or available read-only agent), not the patch author or its self-review. Give it the original request, target/source version evidence, current project files, proposed diffs/report (including merges and removals), and check results. Review scope, relevance/retirement decisions, preserved customizations, trust/version gates, and backup/approval requirements.
+    - The reviewer returns `VERDICT: PASS` or `VERDICT: CHANGES`; each blocking finding names the file, problem, and required repair. Send findings or failed checks back to the patch author, repair the proposal, verify it, and re-review the revised proposal. Repeat until PASS or BLOCKED; never proceed merely because a round limit was reached.
+    - Only the orchestrator accepts the proposal, after independently inspecting the evidence for every acceptance check and the current review PASS. A reviewer PASS alone is not acceptance and never replaces user approval. If an independent reviewer or required evidence/check is unavailable, report **BLOCKED** with what would unblock it; do not apply or claim completion.
+
+5.  **Confirm and Apply** (only the accepted proposal):
     - If `--dry-run` flag: Output the report without making changes
-    - Otherwise: Present the report and ask the user to confirm with (Y/n)
+    - Otherwise: Present the reviewed report and ask the user to confirm with (Y/n). Before writes, back up affected existing files/config and confirm the source, project state, and patch still match the reviewed proposal; if they changed, regenerate and repeat review and user approval. Apply only approved changes.
     - On confirmation:
       a. **Add and update**: run `npx nitm-ai-dev-toolkit patch`. It writes only the add and update entries it printed; do not copy template files by hand
       b. **Retirements**: after approval, record each path in `.nitm/retired.json` with a reason and date. Do not delete files to retire them
-      c. **Needs review**: propose a merge per file (structural additions, preserved project values) and apply it only after the operator approves that file. Wrappers that inline policy: propose moving the content into the snippet and reducing the wrapper to a thin link (see Thin Wrapper Policy in `bootstrap.md`)
+      c. **Needs review**: include each proposed merge (structural additions, preserved project values) in Step 4's report and independent review, and apply it only after the operator approves that file. Wrappers that inline policy: propose moving the content into the snippet and reducing the wrapper to a thin link (see Thin Wrapper Policy in `bootstrap.md`)
       d. **OpenCode plugins**: Apply only the approved obsolete Ponytail cleanup above after backing up the known obsolete toolkit copies and local config; preserve all unrelated local/global plugins. Never add Ponytail to project config.
       e. **Toolkit version**: Keep the `.toolkit-version` value the CLI writes for the verified target version (the installed package version, 4.0.0 or later; never hard-coded) only after the approved migration and OpenCode preflight pass (or OpenCode is confirmed out of scope).
-      f. **Git commit**: Stage and commit all changes with message:
-      ```bash
-      git add -A
-      git commit -m "chore: patch AI instructions from toolkit [$(date +%Y-%m-%d)]"
-      ```
+      f. **Git commit**: Do not auto-commit. Only if the user explicitly requests a commit, and only after Step 7 acceptance, stage just this patch's approved paths; never stage unrelated changes.
 
 6.  **Cleanup**:
 
@@ -216,6 +218,9 @@ The CLI runs the same patch flow without an AI session: `npx nitm-ai-dev-toolkit
     - Verify no `{{PLACEHOLDER}}` syntax was accidentally re-introduced
     - Confirm all files are valid (no broken frontmatter, no syntax errors)
     - List any new placeholders that need manual `bootstrap` to fill
+    - Inspect the actual applied diff/files against the approved proposal and backups: verify preserved project values/config, relevance/retirements, approved merges/removals, and the target version marker. Run the applicable syntax/frontmatter checks and report commands/results, not assumed runtime validation.
+    - Dispatch the independent read-only reviewer on the actual applied outcome, approval scope, and validation evidence using the same verdict contract above. On findings or failed checks, repair only within the approved scope, rerun validation, and re-review; any new/unapproved change must return through proposal review and user approval before writes.
+    - Only the orchestrator reports **ACCEPTED** when the current outcome has review PASS and verified evidence for every acceptance check. Missing reviewer/evidence means **BLOCKED**, never completion. For `--dry-run`, accept only the reviewed preview and explicitly report that nothing was applied or post-apply verified. Acceptance never authorizes extra writes, deletions, or a commit.
 
 ## Smart Merge Strategy
 
@@ -240,4 +245,4 @@ When a file has been bootstrapped (placeholders replaced with real values), the
 - **Non-destructive by default**: Always show changes before applying
 - **Preserve customizations**: Never lose project-specific configuration
 - **Incremental**: Only apply what's changed, don't re-bootstrap everything
-- **Auditable**: Commit message includes date for tracking patch history
+- **Auditable**: Report approved paths, review verdicts, and verification evidence; commit only on explicit request

package/src/repo/.claude/prompt-snippets/constitution.md

@@ -2,7 +2,7 @@ You are helping to create or update the project constitution at `docs/constituti
 
 ## Your Task
 
-1. **Load existing constitution** (if it exists) at `docs/constitution.md`.
+1. **Load existing constitution** (if it exists) at `docs/constitution.md`. Retain its original content for comparison during review.
 
 2. **Collect project information**:
    - Project name and description
@@ -25,6 +25,12 @@ You are helping to create or update the project constitution at `docs/constituti
 
 5. **Save** the constitution to `docs/constitution.md`.
 
+6. **Review and accept the artifact** before reporting completion:
+   - The orchestrator dispatches an independent, read-only reviewer with the original request, gathered requirements, original constitution (or confirmation this is new), saved constitution, and validation results. Review the actual artifact for contradictions, unintended policy changes, and requirements coverage; return `VERDICT: PASS` or `VERDICT: CHANGES` with blocking findings and section references.
+   - Repair blocking findings within the agreed scope, repeat affected validation checks, and re-review the changed artifact independently. Repeat until PASS or blocked; unresolved policy decisions go to the user, not an invented amendment.
+   - Only the orchestrator accepts, after an independent PASS and evidence that every requirement and applicable validation check is satisfied. If an independent reviewer is unavailable, report BLOCKED; self-review cannot substitute for independent acceptance.
+   - Keep human/team approval and the constitution's amendment governance separate from artifact acceptance. This review adds no commit, push, or apply step.
+
 ## Constitution Template
 
 ```markdown

package/src/repo/.claude/prompt-snippets/create-skill.md

@@ -299,6 +299,16 @@ After validation, create the skill:
    - `assets/`
 4. **Add resource files**: Based on skill requirements
 
+## Artifact Review and Acceptance
+
+Before Post-Creation or a success summary, the orchestrator must:
+
+1. Dispatch an independent, read-only reviewer with the original request, gathered requirements, created skill and resource paths, and validation results. Review the actual files for naming/frontmatter, structure, reference resolution, and coverage of the requested capability; return `VERDICT: PASS` or `VERDICT: CHANGES` with blocking findings and file references.
+2. Repair blocking findings within the agreed scope, repeat affected validation checks, and re-review the changed artifacts independently. Repeat until PASS or blocked; ask the user rather than inventing requirements or expanding scope.
+3. Accept only after the independent reviewer returns PASS and the orchestrator verifies every requirement and applicable validation check against evidence. If an independent reviewer is unavailable, report BLOCKED; self-review cannot substitute for independent acceptance.
+
+Keep any required human approval separate from artifact acceptance. This review adds no commit, push, or apply step.
+
 ## Post-Creation
 
 After creating the skill:

package/src/repo/.claude/prompt-snippets/implement-feature.md

@@ -11,41 +11,42 @@ Implement a feature by completing tasks sequentially with proper tracking.
 
 ## Orchestrator Checkpoint
 
-> **🛑 Before starting**: This command involves planning, implementation, testing, and review.
-> Use the **orchestrator-first** flow. Delegate to the **Feature Builder** coordinator or use
-> the `subagent-driven-development` skill to dispatch a fresh subagent per task.
-> See `.claude/rules-snippets/subagent-workflow.md` for full patterns.
+> **🛑 Before starting**: Every task and the whole feature run the delivery loop in
+> [implement.md](implement.md). Dispatch the builder directly with that loop. Do not route through a
+> planning skill, and do not write a spec or plan first. **Feature Builder** may be the builder for a
+> task, but its own review never replaces the independent review, and only the orchestrator accepts.
 
 ## Process
 
 > **📋 Standards**: Follow [Coding Standards](../rules-snippets/coding-standards.md), [Testing](../rules-snippets/testing.md), and [Documentation](../rules-snippets/documentation.md).
 
 1. **Load Feature Context**:
-   - Read specification from `docs/features/{{ISSUE_ID}}-{{FEATURE_NAME}}/spec.md`
-   - Read implementation plan from `docs/features/{{ISSUE_ID}}-{{FEATURE_NAME}}/plan.md`
-   - Read task list from `docs/features/{{ISSUE_ID}}-{{FEATURE_NAME}}/tasks.md`
-   - Review `AGENTS.md` for project patterns
+   - The supplied feature text or task list is the requirement. Do not require a spec or plan first.
+   - If `docs/features/{{ISSUE_ID}}-{{FEATURE_NAME}}/` exists, read whichever of `spec.md`, `plan.md` and `tasks.md` it contains as context. Skip any that are absent.
+   - Review `AGENTS.md` for project patterns.
+   - Turn every requirement of the feature into an acceptance criterion and discover the real checks, as in [implement.md](implement.md) step 1.
+   - Preserve the original full-feature text, acceptance criteria, and real checks separately for aggregate feature review; task-local inputs must not overwrite them.
 
 2. **Parallelization Analysis**:
    - Scan task list for `[P]` markers and independent tasks
    - Group tasks by domain (backend, frontend, docs, tests)
-   - Tasks that touch **different files with no shared state** → dispatch in parallel
+   - Tasks that touch **different files with no shared state** → run their loops in parallel
    - Tasks with dependencies or shared files → keep sequential
+   - Tasks with an unknown or undeclared write set → keep sequential until the scope is established
    - Use `dispatching-parallel-agents` skill when 3+ independent tasks exist
 
-3. **Create Feature Branch**:
+3. **Create Feature Branch** (before any build):
 
    ```bash
    git checkout -b feature/{{FEATURE_NAME}}
    git pull origin {{DEFAULT_BRANCH}}
    ```
 
-4. **Task Implementation** (sequential or parallel per analysis):
+   Then take the baseline snapshot as in implement.md step 1, before any build.
 
-   For tasks with dependencies, execute in order.
-   For `[P]` tasks with no shared state, **dispatch parallel subagents** — one per task domain:
+4. **Task Implementation** (sequential or parallel per analysis):
 
-   For each task:
+   For each task, in dependency order:
 
    a. **Mark Task In Progress**
 
@@ -53,70 +54,49 @@ Implement a feature by completing tasks sequentially with proper tracking.
    - Search codebase for similar patterns
    - Review referenced files
    - Understand dependencies
+   - Before entering the task's delivery loop, bind the current task's original text unchanged, task-local acceptance criteria, and applicable real checks as in implement.md step 1. Use these inputs for the builder, verification, independent reviewer, and acceptance in steps 2–5. Do not use another task's criteria or require later tasks to pass. Keep the saved baseline unchanged.
 
-   c. **Implement (TDD required)**:
-   - Follow the acceptance criteria in `spec.md` for this task's deliverable
-   - Use patterns from `AGENTS.md`
-   - **Write a failing test first** — one behavior per test, clear name, real code
-   - **Verify it fails** — watch it fail for the right reason (feature missing, not error)
-   - **Write minimal code to pass** — simplest implementation, no over-engineering
-   - **Verify it passes** — all tests green, no regressions
-   - **Refactor** — clean up only after green (remove duplication, improve names)
-   - Ensure type safety
-   - See `test-driven-development/SKILL.md` for the full cycle
-
-   d. **Validate**:
-   - Run type checking: `{{PACKAGE_MANAGER}} run check-types`
-   - Run linter: `{{PACKAGE_MANAGER}} run lint`
-   - Run tests: `{{PACKAGE_MANAGER}} run test`
-   - Build: `{{PACKAGE_MANAGER}} run build`
-
-   e. **Update Documentation**:
-   - Ensure `docs/features/{{ISSUE_ID}}-{{FEATURE_NAME}}/spec.md` reflects final implementation
-   - Update `plan.md` if implementation deviated from original plan
-   - Update `docs/api/` if any API surfaces changed
-   - Update `README.md` if setup steps, commands, or env vars changed
-   - Add entry to `CHANGELOG.md` under `[Unreleased]`
-   - See `.claude/rules-snippets/documentation.md` for full pre-commit checklist
-
-   f. **Commit Changes**:
+   c. **Delivery loop for the task** (implement.md steps 2–5):
+   - Builder: write the failing test first, watch it fail for the right reason, make the minimal change to pass, then refactor (TDD). Update the docs the task requires: `docs/api/` if API surfaces changed, `README.md` if setup steps, commands, or env vars changed, and `CHANGELOG.md` under `[Unreleased]`. Update a feature `spec.md` or `plan.md` only if one exists.
+   - Orchestrator: verify the checks yourself, dispatch the independent read-only reviewer, then decide.
+   - Repair goes back to the builder. Repeat until the task is accepted or blocked. Do not commit or tick the task before acceptance.
+   - See `.claude/rules-snippets/documentation.md` for the full pre-commit checklist.
+
+   d. **Commit the Task** (after acceptance, only when there are accepted changes): stage only this task's paths, never `git add -A` or a foreign change, then commit. Skip the commit when nothing is staged.
 
    ```bash
    git commit -m "feat({{SCOPE}}): {{DESCRIPTION}}"
    ```
 
-   f. **Mark Task Complete**:
+   e. **Mark Task Complete** (after the commit):
    - Slim `tasks.md`: tick `- [x]` on the task's line
    - Legacy `tasks.md`: tick `- [x]` only on checkboxes under the current task's heading (until the next heading). Never tick checkboxes under other headings. If that heading has no checkboxes, report "no checkboxes under <heading>; nothing ticked" and continue
 
-5. **Post-Implementation Review**:
-   - Dispatch **Reviewer** agent on all changes before proceeding
-   - If reviewer requests changes, route back to the original domain specialist
-   - Use `verification-before-completion` skill for final quality gate
-
-6. **Create Pull Request**:
+5. **Feature Review** (aggregate loop, every round):
+   - Restore the saved full-feature text, acceptance criteria, and real checks as the inputs for aggregate verification, independent review, and acceptance.
+   - Run implement.md steps 3, 4 and 5 for the **whole feature**, against every requirement from step 1, not only the last task.
+   - Review scope: the current working tree against the merge-base, `git diff $(git merge-base {{DEFAULT_BRANCH}} HEAD)`. This covers committed task work, uncommitted repairs, and new files (read the untracked ones directly). Do not review only `{{DEFAULT_BRANCH}}...HEAD`: it misses uncommitted repairs and new files. Compare preexisting files against the saved baseline copies from step 1, as in implement.md step 4.
+   - Repairs go to the builder that owns each file, uncommitted. Then run steps 3–5 again on the current tree.
+   - Exits are the same as implement.md step 5: accepted, blocked, or needs a user decision. There is no round limit. Only acceptance ends the feature review successfully.
 
-   After all tasks complete:
+6. **Create Pull Request** (only after the feature review is accepted):
 
-   a. **Final Validation**:
-   - All tests passing
-   - No type errors
-   - No linter errors
-   - Build successful
+   a. **Final Validation**: after all tasks are reconciled, run the project's full required regression checks once on the final integrated tree (implement.md step 3): the repo-defined full suite, lint, typecheck, and build, where they exist. Every required check must pass on this tree. Any edit after this run requires revalidation.
 
-   b. **Push and Create PR**:
+   b. **Commit and push**: if accepted feature-review changes are still uncommitted, commit them once, staging only the feature's paths, and skip the commit when nothing is staged. Do not create repair-only commits.
 
    ```bash
+   git commit -m "feat({{SCOPE}}): {{DESCRIPTION}}"   # only when there are uncommitted accepted changes
    git push -u origin feature/{{FEATURE_NAME}}
    ```
 
    - Create PR targeting `{{DEFAULT_BRANCH}}`
-   - Include feature summary and testing notes
+   - Include feature summary, the AC evidence, and testing notes
 
 7. **Report Status**:
-   - Completed tasks count
-   - PR URL
-   - Ready for code review
+   - Tasks accepted (count) and any task blocked or awaiting a user decision
+   - Feature review verdict and `ACCEPTED` or `BLOCKED` / `NOT ACCEPTED` with the open items
+   - PR URL, only when accepted
 
 ## Guidelines
 

package/src/repo/.claude/prompt-snippets/implement-fixes.md

@@ -11,10 +11,12 @@ Implement bug fixes and corrections with proper validation and documentation.
 
 ## Orchestrator Checkpoint
 
-> **🛑 For multiple independent fixes**: If fixing 2+ unrelated bugs, use `dispatching-parallel-agents`
-> to dispatch one subagent per bug (different root causes, different files = parallel-safe).
-> For a single focused fix, proceed directly — single-agent is appropriate.
-> See `.claude/rules-snippets/subagent-workflow.md` for patterns.
+> **🛑 Every fix runs the delivery loop** in [implement.md](implement.md). Initialize steps 1 and 2 below
+> before any reproduction or build. Then one builder reproduces and fixes the bug, and the orchestrator
+> repeats verify, review and decide until the fix is accepted or a stop condition is reached. Do not
+> fix the bug inline, and do not write a spec or plan first.
+> For several unrelated bugs, run one loop per bug, each with its own builder. Use
+> `dispatching-parallel-agents` only when their root causes and files do not overlap.
 
 ## Workflow Modes
 
@@ -25,55 +27,51 @@ Implement bug fixes and corrections with proper validation and documentation.
 
 > **📋 Standards**: Follow [Coding Standards](../rules-snippets/coding-standards.md) and [Documentation](../rules-snippets/documentation.md).
 
-1. **Load Fix Context**:
+1. **Load Fix Context** (orchestrator, before any build):
    - Retrieve issue details if applicable
-   - Understand the reported bug
-   - Identify affected code areas
+   - The reported bug and any stated expected behavior are the requirement. Do not require a spec or plan first.
+   - Identify the affected code areas
+   - Turn the requirements into acceptance criteria, one per requirement: for example "the reported behavior no longer occurs" and "existing behavior the bug touches still works". Discover the real checks as in [implement.md](implement.md) step 1.
+
+2. **Create Fix Branch and Capture Baseline** (orchestrator, before any build):
 
-2. **Create Fix Branch**:
    ```bash
    git checkout {{DEFAULT_BRANCH}}
    git pull origin {{DEFAULT_BRANCH}}
    git checkout -b fix/{{FIX_DESCRIPTION}}
    ```
 
-3. **Reproduce & Test (TDD required)**:
-   - Identify root cause
-   - **Write a failing test that reproduces the bug** — this proves you understand the issue
-   - **Verify it fails** — watch it fail for the right reason
-   - See `test-driven-development/SKILL.md` for the bug fix workflow
-
-4. **Implement Fix**:
-   - Write minimal code to make the failing test pass
-   - Fix only the reported issue
-   - Maintain backward compatibility
-   - **Verify all tests pass** — run the full suite, no regressions
-
-5. **Validate Fix**:
-   - Run type checking: `{{PACKAGE_MANAGER}} run check-types`
-   - Run tests: `{{PACKAGE_MANAGER}} run test`
-   - Build: `{{PACKAGE_MANAGER}} run build`
-   - Verify fix resolves the issue
-   - Check for regressions
-
-6. **Commit and Push**:
+   Then take the baseline snapshot as in implement.md step 1, before any build.
+
+3. **Reproduce and Build** (builder, implement.md step 2):
+   - Dispatch one builder with the bug report, the AC list, the discovered checks, the base commit and the baseline.
+   - The builder identifies the root cause and writes a **failing test that reproduces the bug**. It watches the test fail for the right reason, then makes the minimal change that passes it. The reproduction belongs to the builder, not to the orchestrator.
+   - Fix only the reported issue. Maintain backward compatibility. Leave all changes uncommitted, including new files.
+
+4. **Verify, Review and Decide** (repeat implement.md steps 3, 4 and 5 until an exit):
+   - Verify: rerun the reproducing test and confirm it passes now, run every check that covers an AC, and run the full test suite for regressions.
+   - Review: the independent read-only reviewer checks the fix, the reproducing test, and the untracked files.
+   - Decide: repair goes back to the same builder. Repeat until `ACCEPTED`, `BLOCKED`, or `NOT ACCEPTED: needs decision`. There is no round limit. A review PASS alone never accepts.
+
+5. **Commit and Push** (only after `ACCEPTED`, and only when there are accepted changes): stage only the fix's paths, never `git add -A` or a foreign change. Skip the commit when nothing is staged.
    ```bash
    git commit -m "fix({{SCOPE}}): {{FIX_DESCRIPTION}}"
    git push -u origin fix/{{FIX_DESCRIPTION}}
    ```
 
-7. **Create Pull Request**:
+6. **Create Pull Request** (only after `ACCEPTED`):
    - Target: `{{DEFAULT_BRANCH}}`
    - Include:
      - Root cause explanation
      - Fix approach description
-     - Testing performed
+     - Testing performed, with the reproducing test and its failing-then-passing output
      - Potential impacts
 
-8. **Report Status**:
+7. **Report Status**:
    - Bug fixed and root cause
-   - Validation completed
-   - PR ready for review
+   - Review verdict and `ACCEPTED`, or `BLOCKED` / `NOT ACCEPTED` with the open items
+   - Validation evidence per AC
+   - PR ready for review (only when accepted)
 
    **Include a Fixes Applied table** summarizing every change:
 
@@ -99,7 +97,7 @@ Implement bug fixes and corrections with proper validation and documentation.
 - **Minimal Scope**: Fix only the reported issue
 - **No Refactoring**: Avoid unrelated code changes
 - **Backward Compatible**: Don't break existing functionality
-- **Test First**: Write a failing test reproducing the bug before writing the fix — no exceptions
+- **Test First**: The builder writes a failing test reproducing the bug before writing the fix — no exceptions
 - **Document**: Record the fix in changelog if significant
 
 ## Documentation
@@ -110,6 +108,7 @@ For significant fixes, document in `docs/fixes/` or `CHANGELOG.md`:
 ## [{{VERSION}}] - {{DATE}}
 
 ### Fixed
+
 - {{FIX_DESCRIPTION}} ({{ISSUE_KEY}})
   - Root cause: {{ROOT_CAUSE}}
   - Solution: {{SOLUTION}}