nitm-ai-dev-toolkit 5.2.0 → 5.2.1

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

@@ -11,41 +11,41 @@ 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
    - 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 +53,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**: the accepted verify results from step 5 (every required check ran and passed).
 
-   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}}

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

@@ -1,51 +1,109 @@
-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.
 
-## 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. 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. Stop and ask the user for the command (see the Blocked exit in step 5).
+- Ask only when the task 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, offering the options, and wait.
+- 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.
 
-1. **Load context**:
+**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.
 
-   - Read the specification or task list provided
-   - Review `AGENTS.md` for coding patterns
-   - Check relevant documentation in `docs/`
+### 3. Verify (orchestrator)
 
-2. **Analyze implementation requirements**:
+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.
 
-   - 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.
 
-   - 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):** the builder reports `BLOCKED`, or a required check cannot be discovered or run, or no independent reviewer is available. Stop, report `BLOCKED` with the blocker and what would unblock it. Never mark blocked work accepted.
+- **Needs user decision (exit):** the task is unclear in a way only the user can settle. Stop, report `NOT ACCEPTED: needs decision` with the question. 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.
+
+### 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 BLOCKED.** The orchestrator may run its own verify and report the evidence, but it cannot accept the work on its own review. Report `BLOCKED`, and stop.
+- A self-review is never presented as an independent review.
+
+## 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.
+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 +111,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. Review the actual artifacts for completeness, dependencies/order, actionability, and coverage of the request; return `VERDICT: PASS` or `VERDICT: CHANGES` with blocking findings and section references.
+   - Repair blocking findings within the agreed scope, repeat affected artifact checks, and re-review the changed artifacts independently. Repeat until PASS or blocked; unresolved decisions go to the user.
+   - 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/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/subagent-workflow.md

@@ -114,6 +114,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, stop, report the blocker, and ask the user which model to use.
+- **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).