nitm-ai-dev-toolkit 5.2.0 → 5.3.0

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

@@ -5,113 +5,95 @@ Implement a feature by completing tasks sequentially with proper tracking.
 ## Usage
 
 ```
-
 /implement-feature {{ISSUE_KEY}}-123
 /implement-feature apps/{{APP_NAME}}/docs/features/{{FEATURE_NAME}}/tasks.md
-
-````
+```
 
 ## 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
 
 1. **Load Feature Context**:
-   - Read specification from `apps/{{APP_NAME}}/docs/features/{{ISSUE_ID}}-{{FEATURE_NAME}}/spec.md`
-   - Read implementation plan from `apps/{{APP_NAME}}/docs/features/{{ISSUE_ID}}-{{FEATURE_NAME}}/plan.md`
-   - Read task list from `apps/{{APP_NAME}}/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 `apps/{{APP_NAME}}/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**
 
    b. **Research & Understand**:
-
    - 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**:
+   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 in its app or package.
+   - 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.
 
-   - 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. **Commit Changes**:
+   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**:
-
-   After all tasks complete:
+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.
 
-   a. **Final Validation**:
+6. **Create Pull Request** (only after the feature review is accepted):
 
-   - 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/monorepo/.claude/prompt-snippets/implement-fixes.md

@@ -5,18 +5,18 @@ Implement bug fixes and corrections with proper validation and documentation.
 ## Usage
 
 ```
-
 /implement-fixes {{ISSUE_KEY}}-456
 /implement-fixes "Fix authentication timeout issue"
-
-````
+```
 
 ## 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,60 +25,51 @@ Implement bug fixes and corrections with proper validation and documentation.
 
 ## Process
 
-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**:
+   Then take the baseline snapshot as in implement.md step 1, before any build.
 
-   - 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
+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.
 
-6. **Commit and Push**:
+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:
 
@@ -104,7 +95,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

package/src/monorepo/.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/monorepo/.claude/prompt-snippets/plan.md

@@ -5,15 +5,19 @@ You are helping to create an implementation plan for a feature or requirement.
 > **🛑 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.
 
 ## Your Task
 
 1. **Load context**:
 
+   - Use the supplied requirement as sufficient input. Ask targeted questions only when the request is unclear; do not require creating a specification first.
    - Read `AGENTS.md` for project architecture and patterns
    - Review `docs/constitution.md` for project principles (if exists)
-   - Read the feature spec from `apps/{{APP_NAME}}/docs/features/{{ISSUE_ID}}-{{FEATURE_NAME}}/spec.md`
+   - If an existing specification is available at `apps/{{APP_NAME}}/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.
    - Check relevant existing code for patterns to follow
 
 2. **Analyze the requirement**:
@@ -39,6 +43,14 @@ You are helping to create an implementation plan for a feature or requirement.
    - Include estimated complexity and effort
    - List any open questions or decisions needed
 
+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, with the plan path, artifact check evidence, and any remaining questions for human approval.
+
 ## Plan Template
 
 ```markdown
@@ -48,6 +60,12 @@ You are helping to create an implementation plan for a feature or requirement.
 
 [Brief description of the feature]
 
+## 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.]
+
 ## Technical Approach
 
 [How this will be implemented]

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

@@ -18,8 +18,15 @@ You are helping to create a feature specification based on the user's descriptio
    - Use the template structure below
    - Be specific and actionable
 
-4. **Output**:
-   - Confirm specification created
+4. **Review and Accept the Specification**:
+   - Dispatch an independent, read-only reviewer with the original request (verbatim, with any later user amendments), the feature description, 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.
+
+5. **Output** (only after artifact acceptance):
+   - Confirm specification created and accepted
    - Summarize key requirements
    - Suggest next step: `/plan` to create implementation plan
 

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

@@ -1,12 +1,12 @@
 You are helping to break down a feature into actionable tasks.
 
-`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.
 
 ## Your Task
 
 1. **Load context**:
-   - Read the specification in `apps/{{APP_NAME}}/docs/features/{{ISSUE_ID}}-{{FEATURE_NAME}}/spec.md`
-   - Read the plan in `apps/{{APP_NAME}}/docs/features/{{ISSUE_ID}}-{{FEATURE_NAME}}/plan.md` (if exists)
+   - Read the plan in `apps/{{APP_NAME}}/docs/features/{{ISSUE_ID}}-{{FEATURE_NAME}}/plan.md` when present
+   - 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.
    - Review `AGENTS.md` for project patterns
 
 2. **Break down into tasks** (aim for 3-7 total; never exceed 10):
@@ -65,6 +65,6 @@ You are helping to break down a feature into actionable tasks.
 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/monorepo/.claude/rules-snippets/documentation.md

@@ -85,7 +85,7 @@ Each app maintains its own feature documentation:
 
 **Location:** `apps/{{APP_NAME}}/docs/features/<feature>/`
 
-**Required Files:**
+**Required Files** (subject to the [requirement-only planning exception](#requirement-only-planning-exception) and the separate [supplied-task exception](#supplied-task-exception)):
 
 ```
 apps/{{APP_1}}/docs/features/<feature>/
@@ -156,6 +156,14 @@ Tracks monorepo-wide changes.
 
 **⚠️ 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 and in the decision tree above. Every other applicable item still applies.
+
 ### Pre-Commit Checklist
 
 Before running `git commit`, verify ALL items that apply to your change: