nitm-ai-dev-toolkit 5.2.0 → 5.3.0

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

@@ -1,51 +1,117 @@
-You are helping to implement features based on a task list or specification.
+# Implement
+
+You are the orchestrator for this implementation. You derive the acceptance criteria from the supplied task, delegate the build, get an independent review, verify the evidence yourself, and decide whether the work is accepted. Only the orchestrator accepts work, and only when the loop below says so. Accepting does not commit: the calling flow decides that.
 
 ## Orchestrator Checkpoint
 
-> **🛑 Before starting**: If the task list contains 2+ tasks across different domains or files,
-> use the **orchestrator-first** flow. Dispatch a fresh subagent per task using the
-> `subagent-driven-development` skill. For 3+ independent `[P]` tasks, use the
-> `dispatching-parallel-agents` skill to run them concurrently.
-> See `.claude/rules-snippets/subagent-workflow.md` for full patterns.
+> **🛑 Before starting**: Every task or fix runs the delivery loop below. Dispatch the builder directly
+> with this loop. Do not route through a planning skill, and do not write a spec or plan first.
+> For 3+ independent `[P]` tasks that touch disjoint files, the loops may run concurrently with the
+> `dispatching-parallel-agents` skill. Each task still runs its own loop.
+> Nontrivial ad-hoc code changes outside these commands follow the same loop. Context-heavy nontrivial work may be built directly, but acceptance still needs an independent reviewer; without one it is BLOCKED. Trivial changes (typos, one-line edits) stay outside this loop.
 
-## Your Task
+## Roles
+
+| Role         | Agent                                                                                             | Rules                                                                                                                                                                                 |
+| ------------ | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Orchestrator | this session                                                                                      | Derives the acceptance criteria, dispatches, verifies, decides. Only the orchestrator accepts work or ticks tasks as accepted.                                                       |
+| Builder      | `fixer` (bounded) or `implementer` where the harness has it; `feature-builder` for complex builds | Reproduces, builds, repairs and reports evidence. Never approves its own work. Its internal self-review, and any reviewer it dispatches, do not count as the independent review.       |
+| Reviewer     | `reviewer`, or any read-only agent given the reviewer brief                                       | Reads the original task, the diff, the untracked files and the checks. Never edits.                                                                                                    |
+| Oracle       | `oracle`                                                                                          | Advises on approach or root cause before a build. Does not build or review.                                                                                                            |
+
+## Delivery Loop
+
+The loop repeats until it reaches an exit. It is not a single pass, and it has no fixed round limit.
+
+```
+build → verify → review → decide ─┬─ accept   (review PASS, every requirement verified, every required check passing)
+  ▲                               ├─ blocked  (stop and report; never accepted)
+  └──── repair (any gap) ─────────┤─ needs user decision (stop and report; never accepted)
+                                  └─ (anything else loops back to build)
+```
+
+### 1. Task, checks and baseline (orchestrator)
+
+- The original supplied task (request, task list entry, or fix description) is the requirement. Keep its text and give it to the builder and the reviewer unchanged. Explicit user amendments and answers given during the loop are part of the requirement too: record each one as a dated entry beside the original text (do not rewrite it), and give the builder and the reviewer the original text plus every amendment. Do not require a new spec or plan first, and do not write one.
+- Turn every requirement in the supplied task into an acceptance criterion, `AC-1`, `AC-2`, ... There is no fixed count: one criterion per requirement, however many there are. Do not add requirements the task does not state.
+- Each AC names its check. Discover the real checks; do not assume them. Read the project's manifests (for example `package.json` scripts, `Makefile`, `pyproject.toml`, `Cargo.toml`, `go.mod`), its CI configuration (for example `.github/workflows`), its README, and `AGENTS.md`. Use the commands the project actually runs.
+- A documentation criterion may be checked by direct inspection: open the file and confirm the content, and quote what you found as evidence.
+- A required check that cannot be discovered, or cannot be run, is a gap. It is not a pass, and it is not a bypass. It blocks acceptance of the affected task and of any aggregate run that needs it. Ask the user for the command as one targeted question and keep that question in the progress report. Independent tasks whose checks do not depend on the gap continue (see the Blocked exit in step 5).
+- Ask only when a requirement is unclear in a way that changes what gets built: two readings lead to different code, or a needed fact is missing. Ask one targeted question with its options. A task-scoped question blocks only that task and its dependents: independent tasks with clear requirements continue, and the question stays in the progress report (see [subagent-workflow.md](../rules-snippets/subagent-workflow.md), Autonomous Execution and Blockers). If the whole request is unclear, stop and ask before any build.
+- Take a baseline snapshot once, before any build. It is a plain copy of the state the task starts from, kept in a temporary directory outside the repository:
+  - `git rev-parse HEAD`: the base commit.
+  - `git status --porcelain > <tmp>/baseline/status.txt`: which files were already changed, staged or untracked.
+  - `git diff --binary HEAD > <tmp>/baseline/tracked.patch`: a record of the preexisting tracked changes, staged and unstaged. It is for reference only. The review never subtracts it.
+  - A copy of the content of every preexisting dirty tracked file and every preexisting untracked file, under `<tmp>/baseline/files/<path>`.
+- Preexisting untracked files the task would change are out of scope until the user agrees to that scope. If the task must touch one, stop before the overlap, ask, and continue only with the agreed scope. Hashes alone do not show which lines changed, so the saved copy is the comparison point.
+
+### 2. Build or repair (builder)
+
+**Round 1 (build):** dispatch one builder, directly, with the original task text, the AC list, the discovered checks, the base commit, and the baseline snapshot. The builder must:
+
+- For a bug, first write a failing test that reproduces it, and watch it fail for the right reason. Then make the minimal change that passes it. For a feature, follow TDD: failing test, minimal code, then refactor. Keep the diff as small as the task allows.
+- Leave all its changes uncommitted and unstaged, including new files, so the review sees them. Do not commit.
+- Report each AC as `pass` with the command and result, or `not verified` with the reason. List every changed and new file.
+- Report `BLOCKED` with the decision the human must make if the task cannot be built as written.
+
+**Later rounds (repair):** dispatch the same builder again with only the open items: every blocking review item, every AC that is not `pass`, and every check that failed or did not run. It must fix each item, or say in its report why it should stand. It must not expand scope.
 
-1. **Load context**:
+### 3. Verify (orchestrator)
 
-   - Read the specification or task list provided
-   - Review `AGENTS.md` for coding patterns
-   - Check relevant documentation in `docs/`
+Every round, run every check that covers an AC, using the commands from step 1. Treat the builder's report as a lead, not as evidence. For each AC, record `pass` with the command and result from this round, or `not verified` or `fail` with the reason. Docs criteria are recorded with the quoted content.
 
-2. **Analyze implementation requirements**:
+Checks are scoped: each repair and each task runs the checks for its own ACs. After all writers are reconciled, run the project's full required regression checks once: the repo-defined full suite, lint, typecheck, and build, where they exist. Use only commands the project defines; do not invent them. A failed required check is a repair. A required check that does not exist or cannot run is BLOCKED (see step 5).
 
-   - Identify files to create or modify
-   - Understand dependencies between tasks
-   - Note testing requirements
-   - **Parallelization check**: Identify `[P]` tasks and group independent work by domain
-   - Tasks touching different files with no shared state → dispatch in parallel
+### 4. Review (reviewer, read-only)
 
-3. **Execute implementation**:
+Every round, after verify, dispatch the reviewer on the current working tree. Give it the original supplied task text, the AC list, this round's check results, the base commit, and the baseline snapshot. Its review scope covers the whole task, and it compares content, not patches:
 
-   - For sequential tasks: implement in dependency order
-   - For parallel `[P]` tasks: dispatch domain specialist subagents concurrently
-   - **Follow TDD**: Write failing tests before implementation (red-green-refactor). See `test-driven-development/SKILL.md`.
-   - Follow project coding standards
-   - Add appropriate comments and documentation
+- Tracked file that was clean at baseline: `git diff --binary HEAD -- <file>`, which covers staged and unstaged changes.
+- Tracked file that was dirty at baseline: compare the current file with its saved copy under `<tmp>/baseline/files/<path>`.
+- New untracked file: read each one in full.
+- Preexisting untracked file: compare it with its saved copy, and only if the user agreed to the scope (step 1).
 
-4. **Review gate**:
-   - Dispatch **Reviewer** agent after implementation, before marking work complete
-   - Use `verification-before-completion` skill for final quality check
+The reviewer's rules:
 
-5. **Validate implementation**:
+- Read-only. Do not edit files, format code, stage, or commit.
+- The first line of the reply is exactly `VERDICT: PASS` or `VERDICT: CHANGES`.
+- `VERDICT: CHANGES` needs at least one blocking item, each with `file:line`, the problem, and the specific fix. Blocking means a correctness issue, a failing check, a requirement with no test or evidence, or a clear convention break. Taste goes in non-blocking notes.
+- Check each requirement of the original task, not only the diff. A requirement with no coverage is a blocking item.
+- Scope drift, both ways: trace the diff against the original supplied task. A change that no requirement needs is a blocking item unless the reviewer confirms it is a necessary implementation detail for a stated goal and says why. Goals are the original supplied task plus the user amendments recorded in step 1: do not require or assume a spec or plan (supplied-task exception). Simplicity and SRP notes stay non-blocking unless they add scope the task does not ask for.
 
-   - Run linting: `{{PACKAGE_MANAGER}} run lint`
-   - Run tests: `{{PACKAGE_MANAGER}} run test`
-   - Build project: `{{PACKAGE_MANAGER}} run build`
+### 5. Decide (orchestrator)
+
+Pick one outcome per round:
+
+- **Repair (back to step 2):** the review is `VERDICT: CHANGES`, **or** any AC is `not verified` or `fail`, **or** a required check failed or did not run. Send the open items to the builder, then run steps 3, 4 and 5 again on the current tree.
+- **Accept (exit):** all of these hold on this round's verify and review: the review is `VERDICT: PASS`; every requirement has an AC marked `pass` with evidence from this round; every required check ran and passed; an independent reviewer produced the verdict; and the builder did not report `BLOCKED`. Then report `ACCEPTED` with the AC evidence. A review PASS alone never accepts.
+- **Blocked (exit for the affected work):** the builder reports `BLOCKED`, a required check cannot be discovered or run, or no independent reviewer is available. Report `BLOCKED` with the blocker and what would unblock it. Never mark blocked work accepted. Work that depends on it stops; independent authorized work with its own checks and reviewer continues. Without an independent reviewer nothing is accepted, but discovery and builds that do not need acceptance may continue and be reported as awaiting review. Stop the run only when no authorized work remains or a mandatory approval, security, or permission gate applies.
+- **Needs user decision (exit for the affected work):** the task is unclear in a way only the user can settle. Stop work on that task and its dependents, report `NOT ACCEPTED: needs decision` with the question, and continue independent authorized work. This is not acceptance.
+
+No other exit exists. An unmet requirement, a failing check, or a `not verified` result always loops back to repair. There is no round limit to escape the loop.
+
+**Evidence freshness.** Acceptance uses evidence from the tree it accepts. Any edit after a verify or review, whether by the builder, a repair, or the orchestrator, invalidates the evidence it affects: rerun the checks covering those ACs and re-review the changed diff. Reuse evidence that the edit cannot affect. If unsure whether an edit affects a check, treat it as affected. Do not rerun everything for an unrelated edit.
+
+### Commit (only when the calling flow asks)
+
+The loop never commits by itself. Accepting reports the result; it does not create a commit. The calling command decides whether accepted work is committed, and only when its own flow says so and the user has not asked otherwise. When it does commit:
+
+- Stage only the paths this task changed, taken from the builder's list and checked against the baseline. Never `git add -A`, and never stage a preexisting or foreign change.
+- Skip the commit when nothing is staged. Do not create empty commits, and do not create a separate commit for each repair round.
+
+### Limits
+
+- **No independent reviewer means nothing is accepted.** The orchestrator may run its own verify and report the evidence, but it cannot accept the work on its own review. Report `BLOCKED` for acceptance. Do not treat all work as blocked when independent discovery or build can proceed (see the Blocked exit in step 5).
+- Mandatory approval, security, and permission gates are never bypassed. They apply to the affected work, or to the whole run when the gate is global.
+- A self-review is never presented as an independent review.
+- These gates are prompt instructions, not host enforcement. Resuming after a pause depends on the host; this prompt does not guarantee automatic resume.
+
+## Your Task
 
-6. **Track progress**:
-   - Mark completed tasks
-   - Report any blockers or issues
-   - Summarize changes made
+1. **Analyze**: identify the files to create or modify, the dependencies between tasks, and the `[P]` tasks.
+   Dispatch `[P]` tasks in parallel only when they touch different files with no shared state. Otherwise keep them sequential. A task whose write set is unknown or undeclared runs serially until the builder's changed-file list establishes its scope.
+2. **Run the delivery loop** for each task, in dependency order, until it exits as accepted, blocked, or needs a user decision.
+3. **Track progress**: tick a task only after the orchestrator accepts it. Report blockers and summarize the accepted changes.
 
 ## Guidelines
 
@@ -53,4 +119,4 @@ You are helping to implement features based on a task list or specification.
 - Keep changes focused and atomic
 - Write tests for new functionality
 - Update documentation as needed
-- Use conventional commit messages
+- Use conventional commit messages when a commit is requested

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

@@ -1,6 +1,6 @@
 # Plan Feature Implementation
 
-Plan how to implement the specified feature. This is the second step in the development lifecycle.
+Plan how to implement the supplied feature or requirement; a prior specification is not required.
 
 ## Usage
 
@@ -14,6 +14,7 @@ Plan how to implement the specified feature. This is the second step in the deve
 > **🛑 Before starting**: For complex features spanning multiple domains (backend + frontend + API + docs),
 > dispatch **Researcher** subagents in parallel to analyze each domain simultaneously.
 > Use the `writing-plans` skill for structured plan creation.
+> For this command, the artifact-only scope, source preservation, template and review gates below override that skill's execution handoff, worktree and commit procedures. Stop after reporting the accepted artifacts.
 > See `.claude/rules-snippets/subagent-workflow.md` for full patterns.
 
 ## Process
@@ -21,7 +22,10 @@ Plan how to implement the specified feature. This is the second step in the deve
 > **📋 Standards**: Reference [Patterns](../rules-snippets/patterns.md) for architecture patterns.
 
 1. **Load Feature Context**:
-   - Read specification from `docs/features/{{ISSUE_ID}}-{{FEATURE_NAME}}/spec.md`
+   - Use the supplied requirement as sufficient input. Ask targeted questions only when the request is unclear; do not require creating a specification first.
+   - If an existing specification is available at `docs/features/{{ISSUE_ID}}-{{FEATURE_NAME}}/spec.md`, read it as optional context.
+   - Without an existing specification, persist the original supplied requirements and acceptance criteria verbatim in `plan.md` under **Requirements Source** and **Acceptance Criteria**, including the source path or issue key when available. Preserve constraints; label any derived criteria or assumptions separately and ask the user about unclear or missing criteria rather than inventing approval. This plan is the durable requirements source for `/tasks` and `/assign-tasks`.
+   - With an existing specification, link to its requirements and acceptance criteria instead of duplicating them. Surface conflicts with the supplied request to the user before proceeding.
    - Review `AGENTS.md` for architecture patterns
    - Check `docs/constitution.md` for project principles
 
@@ -50,7 +54,13 @@ Plan how to implement the specified feature. This is the second step in the deve
    - `docs/features/{{ISSUE_ID}}-{{FEATURE_NAME}}/data-model.md` - Data model details
    - `docs/features/{{ISSUE_ID}}-{{FEATURE_NAME}}/api-contract.md` - API specifications
 
-5. **Report Completion**:
+5. **Review and Accept Planning Artifacts**:
+   - The orchestrator dispatches an independent, read-only reviewer with the original request, requirements/context, plan and any additional artifact paths. Use the goal-fit brief (read and follow [fit-review](../rules-snippets/fit-review.md)): Oracle when available read-only, otherwise a separate reviewer; the author's self-review does not count. Review the actual artifacts for completeness, dependencies/order, actionability, and coverage of the request, and trace goals and plan items both ways. Return `VERDICT: PASS` or `VERDICT: CHANGES` with blocking findings and section references. A finding that needs a user decision is blocking, marked `requires user decision; do not auto-repair`; stop and ask the user.
+   - Repair blocking findings within the agreed scope, repeat affected artifact checks, and re-review the changed artifacts independently. Repeat until PASS or blocked, or until the user decides. Stop as BLOCKED with the reason when a repair changes nothing or the same finding returns unchanged. A goal change from the review is a user decision, not a repair. Open decisions block PASS until the user resolves them.
+   - Only the orchestrator accepts, after an independent PASS and evidence for every requirement and applicable artifact check. If an independent reviewer is unavailable, report BLOCKED; self-review cannot substitute for independent acceptance.
+   - This is a lightweight artifact review, not a code build loop: do not implement the plan, run runtime build/TDD/git procedures, or add commit, push, or apply steps. Keep any required human approval separate from artifact acceptance.
+
+6. **Report Completion** (only after artifact acceptance):
    - Plan file path
    - Additional artifacts created
    - Ready for `/tasks` command
@@ -63,6 +73,12 @@ Plan how to implement the specified feature. This is the second step in the deve
 ## Overview
 [Feature description and goals]
 
+## Requirements Source
+[Without a specification: original supplied requirements verbatim and source path/issue key. Otherwise: link to the specification's requirements.]
+
+## Acceptance Criteria
+[Without a specification: original supplied acceptance criteria verbatim; label derived criteria/assumptions separately. Otherwise: link to the specification's criteria.]
+
 ## Architecture
 [Component structure and relationships]
 

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

@@ -65,12 +65,19 @@ Start a new feature by creating a specification. This is the first step in the d
    - [ ] [Questions needing clarification]
    ```
 
-5. **Create Git Branch** (optional):
+5. **Review and Accept the Specification**:
+   - Dispatch an independent, read-only reviewer with the original request (verbatim, with any later user amendments), the feature description, any intake answers, and `spec.md`. Use the goal-fit brief (read and follow [fit-review](../rules-snippets/fit-review.md)): Oracle when available read-only, otherwise a separate reviewer; the author's self-review does not count.
+   - The reviewer traces requirements and acceptance criteria both ways against the original request, checks that each criterion is testable, and returns `VERDICT: PASS` or `VERDICT: CHANGES` with blocking findings and section references. A finding that needs a user decision is blocking, marked `requires user decision; do not auto-repair`; stop and ask the user.
+   - Repair blocking findings within the agreed scope, repeat the affected checks, and re-review the changed spec independently. Repeat until PASS or blocked, or until the user decides. Stop as BLOCKED with the reason when a repair changes nothing or the same finding returns unchanged. A goal change from the review is a user decision, not a repair. Open decisions block PASS until the user resolves them.
+   - Only the orchestrator accepts, after an independent PASS. If an independent reviewer is unavailable, report BLOCKED; self-review cannot substitute for independent acceptance.
+   - Acceptance is separate from human approval: the human still confirms the spec.
+
+6. **Create Git Branch** (optional):
    ```bash
    git checkout -b feature/{{FEATURE_NAME}}
    ```
 
-6. **Report Completion**:
+7. **Report Completion** only after artifact acceptance:
    - Feature directory path
    - Spec file path
    - Branch name (if created)

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

@@ -1,8 +1,8 @@
 # Generate Task Checklist
 
-Break the implementation plan into a slim task checklist. This is the third step in the development lifecycle.
+Break the implementation plan into a slim task checklist; no prior specification is required.
 
-`tasks.md` is a checklist only. Acceptance criteria live in `spec.md`; approach, files, and effort live in `plan.md`. Do not repeat them here.
+`tasks.md` is a checklist only. Acceptance criteria live in `spec.md` when present, otherwise in `plan.md` under **Requirements Source** and **Acceptance Criteria**; approach, files, and effort live in `plan.md`. Do not repeat them here.
 
 ## Usage
 
@@ -13,7 +13,7 @@ Break the implementation plan into a slim task checklist. This is the third step
 
 ## When Not to Create tasks.md
 
-Small work (1-2 steps) needs no `tasks.md`. Implement it directly.
+Small work (1-2 steps) needs no `tasks.md`. Report that a separate implementation command can handle it; do not implement it in this command.
 
 ## Consolidation Rules (CRITICAL)
 
@@ -37,7 +37,7 @@ Before finalizing, ask: Can adjacent tasks merge? Would one developer naturally
 
 ## Process
 
-1. **Load context**: `docs/features/{{ISSUE_ID}}-{{FEATURE_NAME}}/spec.md`, `plan.md`, and `AGENTS.md` (project patterns).
+1. **Load context**: Read `docs/features/{{ISSUE_ID}}-{{FEATURE_NAME}}/plan.md` and `AGENTS.md` (project patterns). Read sibling `spec.md` when present; otherwise use `plan.md` under **Requirements Source** and **Acceptance Criteria** as the requirements source. Cover every requirement and acceptance criterion in the deliverables without copying them into the checklist. If that source is missing or unclear, ask the user; do not require creating a specification.
 
 2. **Write `docs/features/{{ISSUE_ID}}-{{FEATURE_NAME}}/tasks.md`** in the format below.
 
@@ -78,6 +78,6 @@ Ordering: setup before implementation; tests before or alongside code (TDD); cor
 When this list is used by `/implement-feature` or `/implement`:
 
 - **`[P]` tasks**: dispatch one subagent per task concurrently, using `dispatching-parallel-agents`
-- **Other tasks**: execute in dependency order, one subagent per task, using `subagent-driven-development`
+- **Other tasks**: execute in dependency order, one subagent per task
 - **Domain routing**: match each task to a specialist (Backend Architect, Frontend Developer, API Specialist, etc.)
-- **Review gate**: every task passes a Reviewer before it is ticked `[x]`
+- **Review gate**: follow the shared delivery loop in `implement.md`; only the orchestrator accepts and ticks `[x]` after independent review and required evidence. This command only generates the checklist; do not dispatch implementation or bypass required human approval.

package/src/repo/.claude/rules-snippets/documentation.md

@@ -32,7 +32,7 @@ Create feature documentation for:
 
 **Location:** `docs/features/{{ISSUE_ID}}-{{FEATURE_NAME}}/`
 
-**Required Files:**
+**Required Files** (subject to the [requirement-only planning exception](#requirement-only-planning-exception) and the separate [supplied-task exception](#supplied-task-exception)):
 
 ```
 {{ISSUE_ID}}-{{FEATURE_NAME}}/
@@ -43,6 +43,8 @@ Create feature documentation for:
 
 ### Creating Feature Documentation
 
+The [requirement-only planning exception](#requirement-only-planning-exception) takes precedence over the spec-first sequence below for `/plan`, `/tasks` and `/assign-tasks` without a specification.
+
 1. **Use the spec workflow**: Run `/specify` command to generate `spec.md` in `docs/features/{{ISSUE_ID}}-{{FEATURE_NAME}}/`
 2. **Create implementation plan**: Run `/plan` command to generate `plan.md` in the same feature folder
 3. **Keep it updated**: Update during implementation if scope changes
@@ -500,6 +502,14 @@ What is the change we're proposing and/or doing?
 
 **⚠️ MANDATORY: Documentation MUST be written or updated BEFORE committing code. This is a hard requirement — no commit should land without the corresponding docs entry.**
 
+### Requirement-Only Planning Exception
+
+For `/plan` without an existing specification, preserve the original supplied requirements and acceptance criteria in `plan.md` under **Requirements Source** and **Acceptance Criteria**; do not require or create `spec.md`. `/tasks` and `/assign-tasks` consume that plan source when no specification exists; keep acceptance criteria out of the slim task checklist. This exception overrides the spec prerequisite and mandatory spec-first sequence above and in the documentation checklist only for these planning artifacts. It does not authorize implementation, replace artifact review, waive required human approvals, or change any other documentation duties. The separate implementation-command supplied-task exception remains unchanged.
+
+### Supplied-Task Exception
+
+For changes made by the `implement`, `implement-feature` and `implement-fixes` commands only, the task supplied to the command replaces the spec and plan prerequisites. Do not create or require `spec.md` or `plan.md` (feature folders or complex fix folders) unless the user asks for them. This exception covers only the spec and plan items below. Every other applicable item still applies.
+
 ### Pre-Commit Checklist
 
 Before running `git commit`, verify ALL items that apply to your change:

package/src/repo/.claude/rules-snippets/fit-review.md

@@ -0,0 +1,62 @@
+# Goal-Fit Review Brief
+
+Read and follow this brief when a gate or command asks for a goal-fit review of a spec, a plan, or a build's scope. It adds to the reviewer rules of the calling flow.
+
+## Reviewer
+
+- Read-only. Do not edit files, stage, or commit. Do not write any file the caller did not ask for.
+- Independent of the author. Use Oracle when it is available read-only; otherwise a separate reviewer in fresh context. The author's self-review, the author's summary, and a single session playing every role do not count.
+- If no independent reviewer can run, the caller reports `BLOCKED`. Do not review in its place.
+- Review the current artifacts from scratch on every run, including resumed runs. Do not rely on an earlier reply, an earlier summary, or the author's account of what changed.
+
+## Goal sources
+
+Use only these as goal authority:
+
+1. The original user request, verbatim, and every explicit user amendment (intake answers, operator change requests, rework decisions). The caller passes them to you as text in the dispatch.
+2. Accepted constraints from earlier artifacts, when the caller passes them: for a plan review, the accepted spec's requirements, acceptance criteria, and `[DECIDED]` items; for a build review, the accepted spec and plan. Trace against these. They are not goal authority on their own.
+
+Not goal sources: a slug, a ticket key, a ticket title, the existing spec alone, the planner's or author's summary, and any reviewer finding from an earlier round.
+
+If the original request is not in the dispatch, do not infer goals from the spec or the plan. Reply `VERDICT: CHANGES` with a blocking finding: `Missing authoritative baseline: requires user decision; do not auto-repair.`
+
+Quote the original request in your report. When a lower source (a spec, a plan, or a summary) conflicts with the original request, report the conflict with both quotes. Do not silently trust the lower source.
+
+## Trace both ways
+
+- **Forward:** every goal is covered by a requirement, acceptance criterion, or step. Name the section that covers it, or report the gap.
+- **Backward:** every requirement, step, or file change traces to a goal. A change that no goal needs is scope drift.
+- Implementation details that a goal needs are allowed without their own acceptance criterion (for example, a migration that a storage goal requires). Do not demand that every mundane detail be an acceptance criterion. Name the goal that justifies such a detail.
+
+## Lenses (separate from correctness)
+
+- **Ponytail:** is this the simplest work that meets the goals? Flag speculative abstraction, dead flexibility, reinvented standard-library behavior, and steps no goal asks for. Block only when the finding adds scope or complexity the goals do not justify; otherwise note it.
+- **SOLID and SRP, proportional:** flag a responsibility split only when it harms a goal, for example one unit doing unrelated work the request keeps apart. Do not require abstractions or interfaces, and do not forbid a justified interface. Judge by the goals, not by the pattern.
+
+## Decisions and repairs
+
+- A change to a goal (dropping, narrowing, or adding one) is a user decision. So is any other question only the user can settle. A decision stays blocking until the user resolves it with an explicit amendment. Report it as a blocking finding under `VERDICT: CHANGES`, marked `requires user decision; do not auto-repair`, and also list it under **Decisions for the user**. Do not repair it, and do not assume an answer.
+- Other blocking findings are scoped repairs: name the section and the specific change. The caller passes your findings to the author as dispatch context and reviews the changed artifacts again. You do not write repair notes or repair files.
+- `VERDICT: PASS` means no blocking findings. Absence of blocking findings is not a pass. A finding that needs a user decision is blocking, so it is never a pass.
+
+## Output
+
+The first line is exactly `VERDICT: PASS` or `VERDICT: CHANGES`. `CHANGES` needs at least one blocking finding. Then use these sections:
+
+```markdown
+## Goal sources
+- Original request (quoted, short), amendments, accepted constraints. Conflicts: <quotes, or none>
+
+## Trace
+- Forward: <goal → covering section, or gap>
+- Backward: <untraced item → scope drift, or none>
+
+## Blocking findings
+- [section] Problem. Repair: <specific change>
+
+## Decisions for the user
+- <goal change or open decision, or none>
+
+## Notes (non-blocking)
+- [section] Ponytail or SRP observation. Optional.
+```

package/src/repo/.claude/rules-snippets/subagent-workflow.md

@@ -71,42 +71,73 @@ When dispatching implementation tasks, match the specialist to the domain:
 
 ## Orchestration Patterns
 
-### Sequential (default)
+### Delegation Default
 
-Tasks with dependencies are implemented one at a time in dependency order. Each must pass review before the next begins.
+- **Delegate by default.** Hand substantial, safely separable discovery, implementation, test, and review work to subagents. Use a single agent only for trivial work, as listed under "When to Use a Single Agent Directly".
+- **The coordinator keeps outcome responsibility.** It defines each task's scope, reconciles every result, makes sure verification runs, and reports the final outcome. A subagent reporting success is not the outcome.
+- **Work directly only** for trivial changes (one small edit, a quick answer) or when the context is too heavy to hand off cheaply, such as work that depends on large context the coordinator already holds. Say why when you skip delegation.
+- **No delegation capability.** If the host offers no subagent dispatch, say so explicitly in the report. Do permitted direct work where it is safe. Never self-review in place of an independent gate: record the gate as pending and end as BLOCKED or WAITING.
 
-### Parallel
+### Dependency Graph and Parallel Batches (REQUIRED before dispatching)
 
-Independent tasks can be dispatched to multiple specialist subagents simultaneously. Use when tasks don't share files or state.
+Before dispatching any task list, the orchestrator builds the dependency graph. No `[P]` marker is required. If a task list has `[P]` markers, treat them as hints and verify them.
 
-### Parallelization Analysis (REQUIRED before dispatching)
+1. **Read and write sets.** For each task, list the files, directories, or packages it reads and writes.
+2. **Exclusive writable scopes.** Each writer gets a scope no other concurrent task writes. Two tasks that share any writable path are dependent. A task whose write set is unknown or undeclared runs serially until its scope is established from the changed-file list.
+3. **Data dependencies.** A task that reads what another task writes waits for that task.
+4. **Ready batch.** Tasks whose dependencies are satisfied and whose writable scopes are disjoint form one batch. Dispatch the whole batch together. Dependent and shared-write tasks run in later batches, one at a time.
+5. **Route by domain.** Backend tasks → Backend Architect; frontend → Frontend Developer; API contracts → API Specialist; docs → Documenter; cross-cutting → Implementer.
+6. **Track handles.** Record each dispatched task's handle, agent, writable scope, and status until its result is reconciled.
+7. **Reconcile before dependents.** Inspect each result (changed files, summary, verification) before dispatching any task that depends on it. If a result changed a path the graph did not expect, stop the affected tasks and re-plan the batch.
+8. **Continue the chain.** When a batch's results are reconciled, compute the next ready batch and dispatch it. Do not wait for the user unless a mandatory gate applies or no authorized, unblocked work remains (see Autonomous Execution and Blockers).
 
-Before executing any task list, the orchestrator MUST run this analysis:
-
-1. **Scan for `[P]` markers** in the task list — these are pre-identified parallel candidates
-   - If no `[P]` markers exist, do **not** assume sequential-only work. Treat all tasks as candidates and infer parallel-safe groups via the independence test.
-2. **Build a dependency graph**: For each task, list which files it reads and writes
-3. **Apply the independence test**:
-   - Tasks that write to **different files** with **no shared state** → parallel-safe
-   - Tasks that share any writable file → sequential (dependency edge)
-   - Tasks where one reads what another writes → sequential (data dependency)
-4. **Group by domain** for specialist routing:
-   - Backend tasks → Backend Architect
-   - Frontend tasks → Frontend Developer
-   - API contract tasks → API Specialist
-   - Documentation tasks → Documenter
-   - Cross-cutting → Implementer
-5. **Dispatch decision**:
-   - **3+ independent tasks** → Use `dispatching-parallel-agents` skill, one agent per task
-   - **2 independent tasks** → Parallel dispatch (simpler coordination)
-   - **All tasks dependent** → Sequential with `subagent-driven-development` skill
-   - **Mixed** → Dispatch independent group in parallel, then continue sequential chain
+**Dispatch shape:** 3+ independent tasks → `dispatching-parallel-agents`, one agent per task. 2 independent tasks → parallel dispatch. All tasks dependent → sequential with `subagent-driven-development`. Mixed → run each ready batch in parallel, then continue the sequential chain.
 
 ```
-Example: 5 tasks → T1 (setup) → T2 [P] (backend API) + T3 [P] (frontend UI) + T4 [P] (docs) → T5 (integration tests)
-         Dispatch: T1 sequential → T2+T3+T4 parallel → T5 sequential
+Example: 5 tasks → T1 (setup) → T2 (backend API) + T3 (frontend UI) + T4 (docs) → T5 (integration tests)
+         Batches: [T1] → [T2, T3, T4] → [T5]
+         T2, T3, and T4 run together only because their writable scopes are disjoint.
 ```
 
+## Turn Completion and Waiting
+
+During active multi-step execution, never end a turn silently, and never treat dispatch or partial progress as completion. End each such turn in exactly one of these states. Informational answers need no status line:
+
+- **DONE:** the requested work is complete and verified under Quality Gates. State the outcome and the validation that ran.
+- **WAITING:** name each pending task (handle and agent) and its resume trigger, such as a subagent notification or a user reply at a named gate. List what completed and what remains.
+- **BLOCKED / NEEDS-DECISION:** state the blocker or decision, what completed, what remains, and the exact next user action.
+
+Resume mechanics depend on the host:
+
+- When the host notifies on subagent completion, reconcile the notified result and continue with the next eligible batch. Check each handle once per notification.
+- When the host cannot resume in the background, do not claim that it will. Either run the batch in the foreground and collect the results within the turn, or end as WAITING and say that the user must send a message to resume, naming the exact step.
+- Do not busy-poll. Never loop on status checks.
+
+## Autonomous Execution and Blockers
+
+During multi-step execution, work autonomously within the approved goal, scope, and permissions. Autonomy grants no extra authority.
+
+- **A blocker pauses only the affected task and its dependents.** Independent ready work within authority continues in the next batch.
+- **Record each unresolved blocker immediately** in the existing progress record or the conversation: the affected task, what is needed and why, safe options or a targeted input, and the next action. Keep it visible in progress updates and the final report. Never drop it silently.
+- **Defer non-global blockers** as follow-up questions while work can safely advance.
+- **Stop for user input** only when no authorized, unblocked work remains, or when a mandatory approval, security, or permission gate prevents the remaining work. Agents still running are WAITING, not blocked.
+- **Ask clearly.** Present the consolidated outstanding questions through the harness's native question or clarification tool when one is available. Do not assume a tool name or support. Without one, give numbered options or a fill-in block in chat.
+- **Answers can arrive early.** Do not require a blocking tool prompt while independent work continues. Report deferred questions in progress updates.
+- **Never** silently choose a consequential scope or requirement change, bypass a required human approval, or mark a partially blocked task DONE.
+
+## Long-Session Checkpoint
+
+For sessions that span several batches or a context reset:
+
+- Use existing progress records only: a progress section the plan or task list already has, Factory job notes, or task records, when they exist. Keep the approved goal, current step, active task handles, blocker, and next action in those notes or in the conversation.
+- Never add fields to structured files such as Factory `job.json`, never rewrite accepted requirements or spec/plan text, and never replace an authoritative source with a summary.
+- If no such records exist, a short checkpoint in the conversation is enough. Do not create new files for trivial work.
+- On resume, reread the accepted source (spec, plan, or task text) instead of relying on the checkpoint summary, and check the working tree before dispatching anything.
+
+## Factory Approvals
+
+Spec and plan confirmations remain mandatory human steps; final approval, escalation, and merge behavior follow the job's `APPROVAL_MODE` and `MERGE_MODE`. Delegation, batching, autonomy, and subagent sign-offs never satisfy spec or plan human confirmation, or human final approval when `APPROVAL_MODE=human`. Mode-defined approver behavior is preserved. Stop at the gate and report it as WAITING or BLOCKED.
+
 ## Quality Gates
 
 - Every implementation must pass **Reviewer** before proceeding
@@ -114,6 +145,19 @@ Example: 5 tasks → T1 (setup) → T2 [P] (backend API) + T3 [P] (frontend UI)
 - Coordinators should not skip review even for "simple" changes
 - If a reviewer requests changes, the original specialist fixes them and re-review occurs
 
+## Model Capacity Fallback
+
+When a subagent stops on a model capacity, quota, session limit, or reset-wait failure (most often Claude), switch its **model** and keep its **agent**. This is automatic for those failures; do not ask first.
+
+- **Same agent, same role.** Re-dispatch the same agent with the same task, permissions, and context (and session, where the harness supports it). Do not substitute an equivalent agent.
+- **Model order, one attempt each.** Try the next model in the configured fallback order for that agent. When the order is exhausted, try the harness's known available default, unless it was already tried. Then stop; do not cycle back.
+- **Never** retry the same unavailable model, and never wait blindly for a quota reset.
+- **Only supported switching.** Change the model through per-call selection the runtime supports, using only fallback models and defaults that are already configured or exposed. Do not invent model IDs, and do not edit persistent or global config, accounts, or billing.
+- **Blocker when nothing is left.** If no configured fallback or default is available, or per-call selection is unsupported, the affected task is reported BLOCKED with the question of which model to use. Its dependents stop; independent authorized work continues (see Autonomous Execution and Blockers).
+- **Inspect before resuming.** Check what the failed attempt left in the working tree, then resume from that partial work. Never run two writers on the same files at once.
+- **Keep review independent.** The reviewer stays a separate agent from the builder, even when the builder moves to a fallback model.
+- **Disclose.** The final report names the original model, each fallback attempted, and the model that finished the work.
+
 ## Skills Integration
 
 These skills complement subagent workflows:

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

@@ -10,7 +10,7 @@ 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 |
 
 Patch AI instructions by comparing against the latest templates and applying updates.
 

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

@@ -10,7 +10,7 @@ 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 |
 
 Implement a feature by completing tasks sequentially with proper tracking.
 

package/src/repo/.github/prompts/bootstrap-patch.prompt.md

@@ -1,6 +1,6 @@
 ---
 description: Patch AI instructions by fetching updates from the toolkit repo and applying new/updated/missing guidance
-tools: ["read", "search", "edit", "terminal"]
+tools: ["read", "search", "edit", "terminal", "agent"]
 argument-hint: "[--dry-run] [--category <category>]"
 ---
 
@@ -11,6 +11,6 @@ argument-hint: "[--dry-run] [--category <category>]"
 | 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 |
 
 **CRITICAL: READ:** [.claude/prompt-snippets/bootstrap-patch.md](../../.claude/prompt-snippets/bootstrap-patch.md).

package/src/repo/.github/prompts/constitution.prompt.md

@@ -1,6 +1,6 @@
 ---
 description: Create or update the project constitution
-tools: ["read", "search", "edit"]
+tools: ["read", "search", "edit", "agent"]
 argument-hint: "no arguments required"
 ---
 

package/src/repo/.github/prompts/create-skill.prompt.md

@@ -1,6 +1,6 @@
 ---
 description: Create a new agent skill following VS Code and agentskills.io specifications
-tools: ["read", "search", "edit"]
+tools: ["read", "search", "edit", "agent"]
 tags: [skill-creation, agent-skills, documentation, automation]
 version: 1.0.0
 argument-hint: "skill purpose or description"

package/src/repo/.github/prompts/implement-feature.prompt.md

@@ -1,6 +1,6 @@
 ---
 description: Implement a feature by completing tasks sequentially
-tools: ["read", "search", "edit", "terminal"]
+tools: ["read", "search", "edit", "terminal", "agent"]
 argument-hint: "issue key or task file path"
 ---
 
@@ -11,6 +11,6 @@ argument-hint: "issue key or task file path"
 | 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 |
 
 **CRITICAL: READ:** [.claude/prompt-snippets/implement-feature.md](../../.claude/prompt-snippets/implement-feature.md).

package/src/repo/.github/prompts/implement-fixes.prompt.md

@@ -1,6 +1,6 @@
 ---
 description: Implement bug fixes with proper tracking and validation
-tools: ["read", "search", "edit", "terminal"]
+tools: ["read", "search", "edit", "terminal", "agent"]
 argument-hint: "issue key or fix description"
 ---
 

package/src/repo/.github/prompts/implement.prompt.md

@@ -1,6 +1,6 @@
 ---
 description: Implement features based on a task list or specification
-tools: ["read", "search", "edit", "runInTerminal", "terminalLastCommand"]
+tools: ["read", "search", "edit", "runInTerminal", "terminalLastCommand", "agent"]
 argument-hint: "task list or specification"
 ---
 

package/src/repo/.github/prompts/plan.prompt.md

@@ -1,6 +1,6 @@
 ---
 description: Create an implementation plan for a feature
-tools: ["read", "search"]
+tools: ["read", "search", "edit", "agent"]
 argument-hint: "issue key or spec file path"
 ---