nitm-ai-dev-toolkit 5.2.0 → 5.2.1

package/src/monorepo/.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/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. 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, 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/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:

package/src/monorepo/.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/monorepo/.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 toolkit templates and applying updates.
 

package/src/monorepo/.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 and review gates.
 

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

@@ -10,6 +10,6 @@ argument-hint: "optional patch options"
 | Agent | When to use |
 |-------|-------------|
 | `fixer` | Standard patch — incremental changes to existing config |
-| `planner` | Complex patch — cross-cutting changes needing analysis first |
+| `reviewer` | Independent read-only review before approval and after apply |
 
 **CRITICAL: READ:** [.claude/prompt-snippets/bootstrap-patch.md](../../.claude/prompt-snippets/bootstrap-patch.md).

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

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

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

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

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

@@ -10,6 +10,6 @@ argument-hint: "feature specification or task list"
 | Agent | When to use |
 |-------|-------------|
 | `fixer` | Bounded feature work — spec is clear, files are known |
-| `feature-builder` | Complex feature — needs research, planning, and coordination |
+| `feature-builder` | Complex feature build — builder only; the orchestrator still runs the review |
 
 **CRITICAL: READ:** [.claude/prompt-snippets/implement-feature.md](../../.claude/prompt-snippets/implement-feature.md).

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

@@ -1,5 +1,6 @@
 ---
 description: Create an implementation plan for a feature
+tools: ["read", "search", "edit", "agent"]
 argument-hint: "feature specification or requirement"
 ---
 

package/src/monorepo/.opencode/commands/bootstrap-patch.md

@@ -9,7 +9,7 @@ description: "Patch AI instructions by fetching updates from the toolkit repo an
 | 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 |
 
 ## Arguments
 

package/src/monorepo/.opencode/commands/implement-feature.md

@@ -9,7 +9,7 @@ description: "Implement a feature by completing tasks sequentially"
 | 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 |
 
 ## Arguments
 

package/src/monorepo/AGENTS.md

@@ -382,6 +382,10 @@ Documentation updates are **mandatory before committing** any feature or fix. Se
 - Reference `docs/constitution.md` for project principles and governance
 - Include all doc changes in the same commit/PR as the code
 
+**Supplied-task exception (`implement`, `implement-feature`, `implement-fixes` only):** the task supplied to these commands replaces the spec and plan prerequisites. Do not create or require `spec.md` or `plan.md` for the feature or fix unless the user asks for them. Every other applicable item in the [documentation checklist](.claude/rules-snippets/documentation.md) still applies, including the fix log, `CHANGELOG.md`, `docs/api/`, and `README.md`.
+
+**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.
+
 ## Related Documentation
 
 - [README.md](README.md) - Project overview

package/src/repo/.claude/agents-snippets/implementer.md

@@ -19,7 +19,11 @@ You are an implementation specialist. Your job is to write production-quality co
 - Write tests alongside implementation
 - Use existing patterns and utilities — don't reinvent
 - Keep changes focused on the assigned task
-- If something is unclear, **ask** before proceeding
+- If the task is unclear in a way that changes what you build, **ask** before proceeding. Otherwise build the task as written.
+- **You build; you do not accept.** Your self-review and report are evidence for the orchestrator, not approval. An independent reviewer and the orchestrator decide.
+- Leave your changes uncommitted and do not tick tasks. Commit or tick only when your calling flow asks, and only after acceptance.
+- Report each acceptance criterion as `pass` with the command and its result, or `not verified` with the reason.
+- In repair mode, answer every blocking review item: fix it, or say in your report why it should stand.
 
 ## Output
 

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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