thachvd-kit 1.0.35 → 1.0.37

package/bin/upgrade.js

@@ -116,23 +116,25 @@ function replaceLegacyLine(text, legacyLine, replacementLine) {
 
 const AGENTS_WORKFLOW_SECTION = `## Workflow
 
-Matt Pocock's promoted skills (installed under \`.agents/skills/\` by \`thachvd-kit setup\`) are the workflow layer. Use the matching skill when a specialized workflow is useful:
+Matt Pocock's promoted skills plus thachvd-kit's native workflow skills (installed under \`.agents/skills/\` and \`.claude/skills/\` by \`thachvd-kit setup\`) are the workflow layer. Use the matching skill when a specialized workflow is useful:
 
 - Clear, localized change: inspect -> edit -> focused verification. Do not force a heavyweight skill.
 - Ambiguous feature or design: \`/grill-with-docs\`, then optionally \`/to-spec\` for a durable contract.
-- Normal feature: \`/grill-with-docs\` -> \`/to-spec\` -> \`/implement\`.
-- Large feature needing decomposition: add \`/to-tickets\` before \`/implement\`.
+- Normal feature: \`/grill-with-docs\` -> \`/to-spec\` -> choose workspace -> \`/implement\`.
+- Large feature needing decomposition: add \`/to-tickets\`, choose workspace, then choose \`/implement\` or \`/subagent-driven-development\`.
 - Huge, multi-session uncertainty: \`/wayfinder\`.
 - Bug or failing behavior: \`/diagnosing-bugs\`.
 - Test-driven implementation: \`/tdd\` (skip the ceremony for trivial config/text changes).
 - Architecture survey: \`/improve-codebase-architecture\`; use \`/codebase-design\` as the design vocabulary.
 - Pre-completion review: \`/code-review\` once when code risk warrants it.
+- Workspace choice: stay on the current branch when explicitly requested; use \`/using-git-worktrees\` only when isolation is wanted.
+- Branch handoff: \`/finishing-a-development-branch\` after verification and review.
 
 If unsure which skill fits, use \`/ask-matt\`.
 
 Questions and research do not edit product code. A fast path is allowed only when the change is localized, mechanically obvious, low-risk, and has focused verification; file count alone is not a gate. State the scope and verification before editing. If the task becomes ambiguous or its behavior, contract, or risk surface grows, use the matching planning skill above instead.
 
-See \`.agent/docs/workflow.md\` for the full route matrix. This kit does not implement a second workflow engine; it only installs and checks the promoted skill set (\`thachvd-kit skills install|check|update\`).`;
+See \`.agent/docs/workflow.md\` for the full route matrix. This kit does not implement a second Matt workflow engine; it installs Matt's promoted skills plus thachvd-kit native skills (\`thachvd-kit skills install|check|update\`).`;
 
 function migrateAgentsStyleMarkdown(content) {
     let text = normalize(content);
@@ -146,7 +148,7 @@ function migrateAgentsStyleMarkdown(content) {
     text = replaceLegacyLine(
         text,
         'Use Superpowers as the workflow backend. Use direct local evidence when it is sufficient and structural tooling such as codebase-memory MCP only when ownership, call paths, architecture, or impact need discovery.',
-        "Use Matt Pocock's promoted skills (`.agents/skills/`) as the workflow backend; run `/ask-matt` if unsure which one fits. Use direct local evidence when it is sufficient and structural tooling such as codebase-memory MCP only when ownership, call paths, architecture, or impact need discovery."
+        "Use Matt Pocock's promoted and thachvd-kit native skills (`.agents/skills/` and `.claude/skills/`) as the workflow layer; run `/ask-matt` if unsure which one fits. Use direct local evidence when it is sufficient and structural tooling such as codebase-memory MCP only when ownership, call paths, architecture, or impact need discovery."
     );
     return text;
 }
@@ -158,8 +160,8 @@ const WORKFLOW_ROUTE_MATRIX_SECTION = `## Route Matrix
 | Question or research only | direct answer or research | no product-code edits |
 | Clear, localized change | fast path (no skill) | inspect -> edit -> focused verify |
 | Ambiguous feature or design | /grill-with-docs, then optionally /to-spec | durable contract before implementation when useful |
-| Normal feature | /grill-with-docs -> /to-spec -> /implement | spec agreed before implementation |
-| Large feature needing decomposition | /grill-with-docs -> /to-spec -> /to-tickets -> /implement | tickets agreed before implementation |
+| Normal feature | /grill-with-docs -> /to-spec -> choose workspace -> /implement | spec agreed before implementation |
+| Large feature needing decomposition | /grill-with-docs -> /to-spec -> /to-tickets -> choose workspace -> executor | tickets agreed before implementation |
 | Huge, multi-session uncertainty | /wayfinder | shared decision map before implementation |
 | Bug or failing behavior | /diagnosing-bugs | reproduce -> root cause -> regression protection -> fix -> verify |
 | Test-driven implementation | /tdd | red -> green -> refactor per slice |
@@ -170,14 +172,14 @@ Not sure which row applies? Run /ask-matt instead of guessing.`;
 
 const WORKFLOW_STANDARD_FLOW_SECTION = `## Standard Feature Flow
 
-/grill-with-docs -> /to-spec -> (/to-tickets for large work) -> /implement (with /tdd where it helps) -> /code-review.`;
+/grill-with-docs -> /to-spec -> (/to-tickets for large work) -> choose workspace -> choose executor (/implement or /subagent-driven-development) -> /code-review -> /finishing-a-development-branch.`;
 
 function migrateWorkflowMarkdown(content) {
     let text = normalize(content);
     text = replaceLegacyLine(
         text,
         'This project uses Superpowers as the workflow backend. thachvd-kit only provides project context and integration setup.',
-        "This project uses Matt Pocock's promoted skills (installed under .agents/skills/ by `thachvd-kit setup`) as the workflow layer. thachvd-kit only provides project context, the skill manifest, and integration setup; it is not a second workflow engine."
+        "This project uses Matt Pocock's promoted skills plus thachvd-kit's native workflow skills (installed under .agents/skills/ and .claude/skills/ by `thachvd-kit setup`) as the workflow layer. Native skills add opt-in workspace isolation, subagent-driven execution, and branch finishing; they do not replace Matt's planning, implementation, testing, or review skills."
     );
     text = replaceLegacyLine(
         text,
@@ -192,16 +194,18 @@ function migrateWorkflowMarkdown(content) {
     return text;
 }
 
-const TOOLING_MATT_SKILLS_SECTION = `## Matt Pocock Skills
+const TOOLING_MATT_SKILLS_SECTION = `## Matt Pocock Skills + Native Workflow Skills
 
-Matt Pocock's promoted engineering and productivity skills are the workflow layer for this project, installed project-locally under \`.agents/skills/\` (never globally):
+Matt Pocock's promoted engineering and productivity skills are installed project-locally under \`.agents/skills/\` (never globally); thachvd-kit native workflow skills are installed under \`.agents/skills/\` and \`.claude/skills/\`:
 
 - Install the promoted set: \`thachvd-kit skills install\` (\`--dry-run\` to preview the command without running it)
 - Check what is installed: \`thachvd-kit skills check\` (read-only)
 - Update the promoted set: \`thachvd-kit skills update\` (re-adds each skill individually for safety, so it is slower than install — one network clone per skill)
 - The full manifest lives in \`bin/matt-skills.js\` (\`PROMOTED_SKILLS\`); it mirrors upstream's \`skills/engineering/\` + \`skills/productivity/\` catalog and never includes \`in-progress\`, \`misc\`, or \`deprecated\` skills.
 - After the first install, run \`/setup-matt-pocock-skills\` once inside the AI client to configure the issue tracker, triage labels, and generated docs location. thachvd-kit does not simulate that skill.
-- Unsure which skill fits a task? Run \`/ask-matt\`.`;
+- Unsure which skill fits a task? Run \`/ask-matt\`.
+- Native skills: \`/using-git-worktrees\` (opt-in isolation), \`/subagent-driven-development\` (alternative executor for multi-task plans), and \`/finishing-a-development-branch\`.
+- Native skills are refreshed from bundled copies; runtime updates never fetch upstream repositories.`;
 
 function migrateToolingMarkdown(content) {
     const text = normalize(content);
@@ -212,7 +216,7 @@ const GETTING_STARTED_SETUP_SECTION = `## Setup
 
 1. Run \`thachvd-kit init\` in the repository.
 2. Open or print \`.agent/docs/index-project-prompt.md\` with \`thachvd-kit prompt\`.
-3. Run \`thachvd-kit setup\` (installs the promoted skill set by default; add \`--no-install-skills\` to skip) and RTK.
+3. Run \`thachvd-kit setup\` (installs promoted and native skill sets by default; add \`--no-install-skills\` to skip) and RTK.
 4. Inside the AI client, run \`/setup-matt-pocock-skills\` once to configure the issue tracker, triage labels, and doc layout.
 5. Run \`thachvd-kit doctor\` and restart the AI client.`;
 
@@ -221,8 +225,9 @@ const GETTING_STARTED_STANDARD_FLOW_SECTION = `## Standard Flow
 1. \`/grill-with-docs\` for unclear requirements or design.
 2. \`/to-spec\` when a durable implementation contract is useful.
 3. \`/to-tickets\` for large work that benefits from decomposition.
-4. \`/implement\`, with \`/tdd\` where red-green-refactor helps.
-5. \`/code-review\` once before completion.
+4. Choose the current branch/workspace or \`/using-git-worktrees\` when isolation is wanted.
+5. Choose \`/implement\` (with \`/tdd\` where useful) or \`/subagent-driven-development\` for multiple relatively independent tasks.
+6. \`/code-review\`, then \`/finishing-a-development-branch\` once verification is complete.
 
 Not sure which skill fits? Run \`/ask-matt\`.`;
 
@@ -235,7 +240,7 @@ function migrateGettingStartedMarkdown(content) {
     text = replaceLegacyLine(
         text,
         'thachvd-kit creates project context. Superpowers owns the development workflow.',
-        "thachvd-kit creates project context. Matt Pocock's promoted skills own the development workflow."
+        "thachvd-kit creates project context. Matt Pocock's promoted and thachvd-kit native skills own the development workflow."
     );
     text = replaceLegacySection(text, '## Setup', /Install Superpowers and RTK/, GETTING_STARTED_SETUP_SECTION);
     text = replaceLegacySection(text, '## Standard Flow', /Use Superpowers native skills/, GETTING_STARTED_STANDARD_FLOW_SECTION);
@@ -249,7 +254,7 @@ function migrateIndexProjectPrompt(content) {
     return replaceLegacyLine(
         normalize(content),
         'Use Superpowers for the workflow and use codebase-memory MCP for structural code discovery when available.',
-        'Use the project\'s Matt Pocock skills for workflow (see AGENTS.md; run /ask-matt if unsure which fits) and use codebase-memory MCP for structural code discovery when available.'
+        'Use the project\'s Matt Pocock skills plus thachvd-kit native skills for workflow (see AGENTS.md; run /ask-matt if unsure which fits) and use codebase-memory MCP for structural code discovery when available.'
     );
 }
 

package/package.json

@@ -1,12 +1,14 @@
 {
     "name": "thachvd-kit",
-    "version": "1.0.35",
+    "version": "1.0.37",
     "description": "Cross-agent project rules bootstrap kit for Codex, Antigravity, and Claude Code",
     "bin": {
         "thachvd-kit": "./bin/entry.js"
     },
     "files": [
         "bin",
+        "skills",
+        "THIRD_PARTY_NOTICES.md",
         "README.md",
         "LICENSE"
     ],
@@ -15,8 +17,8 @@
         "node": ">=16.7"
     },
     "scripts": {
-        "test": "node test/cli.test.js && node test/policy.test.js && node test/matt-skills.test.js && node test/upgrade.test.js && node test/global.test.js",
-        "release:verify": "npm test && node --check bin/cli.js && node --check bin/entry.js && node --check bin/policy.js && node --check bin/matt-skills.js && node --check bin/upgrade.js && node --check bin/global.js && npm pack --dry-run",
+        "test": "node test/cli.test.js && node test/policy.test.js && node test/matt-skills.test.js && node test/native-skills.test.js && node test/upgrade.test.js && node test/global.test.js",
+        "release:verify": "npm test && node --check bin/cli.js && node --check bin/entry.js && node --check bin/policy.js && node --check bin/matt-skills.js && node --check bin/native-skills.js && node --check bin/upgrade.js && node --check bin/global.js && node --check skills/subagent-driven-development/scripts/sdd-workspace-lib.js && node --check skills/subagent-driven-development/scripts/sdd-workspace.js && node --check skills/subagent-driven-development/scripts/task-brief.js && node --check skills/subagent-driven-development/scripts/review-package.js && npm pack --dry-run",
         "preversion": "npm run release:verify",
         "release:patch": "npm version patch",
         "release:dry-run": "npm pack --dry-run",

package/skills/finishing-a-development-branch/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: finishing-a-development-branch
+description: Use when implementation is complete, all tests pass, and you need to decide how to integrate the work
+---
+
+# Finishing a Development Branch
+
+## Overview
+
+**Core principle:** Verify tests → Detect environment → Present options → Execute choice → Clean up.
+
+**Announce at start:** "I'm using the finishing-a-development-branch skill to complete this work."
+
+## Step 1: Verify Tests
+
+Run the project's full test suite using the documented project command (for example, one of `npm test`, `cargo test`, `pytest`, or `go test ./...`).
+
+**If tests fail**, report the failures and stop — the menu comes after a green suite:
+
+```
+Tests failing (<N> failures). Must fix before completing:
+
+[Show failures]
+```
+
+**If tests pass:** continue to Step 2.
+
+## Step 2: Determine Workspace Provenance
+
+Determine whether implementation happened in-place or in a task-created isolated workspace. Use the implementation handoff, plan, or conversation as the source of truth:
+
+- **In-place:** the user chose the current branch/workspace, or the existing workspace was reused without creating a branch/worktree for this task. This includes an explicitly requested direct change on `main` or another named branch.
+- **Task-created isolated workspace:** this workflow or an explicitly requested `/using-git-worktrees` flow created the branch/worktree for this task.
+- **Unknown:** do not infer task ownership from a named branch, a non-default branch, or Git topology alone. Treat it as in-place unless the human confirms that this task created the branch/worktree.
+
+For an in-place workspace, after tests pass report the verified current branch/workspace and hand off. Do not determine a base branch, offer a self-merge, remove the current branch, or remove the current worktree. Pushing or opening a PR remains a separate explicit user decision.
+
+```text
+Implementation complete in the current workspace on `<branch>`. Tests pass.
+No merge or branch/worktree cleanup is needed. The current branch is ready for handoff.
+```
+
+Only continue to the environment and integration menu below for a task-created isolated workspace.
+
+## Step 3: Detect Environment
+
+```text
+git rev-parse --git-dir
+git rev-parse --git-common-dir
+git rev-parse --show-toplevel
+git rev-parse --show-superproject-working-tree
+git branch --show-current
+git worktree list --porcelain
+```
+
+Compare the first two results rather than relying on Bash path normalization. Capture the repository root and worktree path before changing directories. This determines which menu to show and how cleanup works:
+
+| State | Menu | Cleanup |
+|-------|------|---------|
+| `--git-dir` equals `--git-common-dir` (normal repo) | Standard 3 options | No worktree to clean up |
+| Values differ, named branch, not a submodule | Standard 3 options | Provenance-based (see Step 7) |
+| Values differ, detached HEAD | Reduced 2 options (no merge) | Externally managed — leave in place |
+
+## Step 4: Determine Base Branch
+
+The base branch is whatever this work forked from — usually named in the
+plan, the conversation, or the branch's upstream. If it is not already
+known, ask: "This branch split from <your best guess> - is that correct?"
+Confirm before merging: merging into the wrong base is expensive to undo.
+
+## Step 5: Present Options
+
+**Normal repo and named-branch worktree — present exactly these 3 options:**
+
+```
+Implementation complete. What would you like to do?
+
+1. Merge back to <base-branch> locally
+2. Push and create a Pull Request
+3. Keep the branch as-is (I'll handle it later)
+
+Which option?
+```
+
+**Detached HEAD — present exactly these 2 options:**
+
+```
+Implementation complete. You're on a detached HEAD (externally managed workspace).
+
+1. Push as new branch and create a Pull Request
+2. Keep as-is (I'll handle it later)
+
+Which option?
+```
+
+Present the menu exactly as written — concise, with every option coming
+from the list above. Discarding the work happens only in response to your
+human partner explicitly asking for it (see "If your human partner asks to
+discard the work" below). Wait for their answer; the integration decision
+is theirs.
+
+## Step 6: Execute Choice
+
+### Option 1: Merge Locally
+
+```text
+# From the main repository root, after confirming the base branch:
+git rev-parse --show-toplevel
+git switch <base-branch>
+git pull
+git merge <feature-branch>
+
+# Verify tests on merged result
+<test command>
+```
+
+If tests fail on the merged result: stop, leave the worktree and branch in
+place, and investigate — nothing has been pushed, so the merge is local
+and recoverable.
+
+Once the merged result is green: clean up the worktree (Step 7), then
+delete the branch:
+
+```bash
+git branch -d <feature-branch>
+```
+
+### Option 2: Push and Create PR
+
+```bash
+git push -u origin <feature-branch>
+# From a detached HEAD, name the new branch on the remote:
+# git push origin HEAD:refs/heads/<new-branch>
+```
+
+Then create the pull/merge request against <base-branch> with the forge's
+tooling — its CLI if one is available, or the creation URL most forges
+print when you push — following the repo's PR template and conventions if
+present, and report the URL to your human partner.
+
+Keep the worktree — your human partner iterates on PR feedback there.
+
+### Option 3: Keep As-Is
+
+Report: "Keeping branch <name>. Worktree preserved at <path>."
+
+### If your human partner asks to discard the work
+
+This path exists only as a response to an explicit request to throw the
+work away. Confirm first:
+
+```
+This will permanently delete:
+- Branch <name>
+- All commits: <commit-list>
+- Worktree at <path>
+
+Type 'discard' to confirm.
+```
+
+Wait for that exact confirmation. When it arrives:
+
+```text
+# From the main repository root, after explicit discard confirmation:
+git rev-parse --show-toplevel
+```
+
+Then clean up the worktree (Step 7) and force-delete the branch:
+
+```bash
+git branch -D <feature-branch>
+```
+
+## Step 7: Cleanup Workspace
+
+**Runs for Option 1 and confirmed discards.** Options 2 and 3 always
+preserve the worktree. Both callers have already changed directory to the
+main repo root — worktree removal must run from outside the worktree —
+and use the Git directory/common-directory comparison and worktree path captured
+in Step 2, from before that directory change.
+
+**If `--git-dir` equals `--git-common-dir`:** Normal repo, no worktree to clean up. Done.
+
+**If the captured worktree path is under `.worktrees/` or `worktrees/`:** This
+workflow owns the manually managed project-local worktree and may clean it up:
+
+```bash
+git worktree remove "<captured-worktree-path>"
+git worktree prune  # Self-healing: clean up any stale registrations
+```
+
+**If removal is refused** (`contains modified or untracked files`): the
+worktree holds files that exist nowhere else — uncommitted plans, notes,
+or scratch work. Never `--force` on your own initiative. Show your human
+partner what is at stake and ask:
+
+```bash
+git -C "<captured-worktree-path>" status --porcelain -uall
+```
+
+```
+Worktree removal refused — these files were never committed:
+
+<file list>
+
+1. Commit them to <branch> before cleanup
+2. Move them into <main repo root>
+3. Delete them (unrecoverable)
+
+Which?
+```
+
+Carry out the choice, then remove the worktree.
+
+**Otherwise:** The host environment owns this workspace — leave it in
+place. If your platform provides a workspace-exit tool, use it.
+
+## Quick Reference
+
+| Option | Merge | Push | Keep Worktree | Cleanup Branch |
+|--------|-------|------|---------------|----------------|
+| 1. Merge locally | yes | - | - | yes |
+| 2. Create PR | - | yes | yes | - |
+| 3. Keep as-is | - | - | yes | - |
+| Discard (explicit request only) | - | - | - | yes (force) |
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "Tests passed earlier this session" | Run the suite on the tree you are about to integrate. A green run only proves the tree it ran on. |
+| "They obviously want it merged" | Integration is your human partner's decision. Present the menu and wait. |
+| "They seem done with this feature — I'll offer to discard it" | The menu is complete as written. Discard happens only when your human partner asks for it in so many words. |
+| "'Yeah, get rid of it' counts as confirmation" | Only the typed word `discard` authorizes deletion. |
+| "The PR is up, so the worktree is clutter now" | PR feedback gets fixed in that worktree. It stays until the work lands. |
+| "This other worktree looks stale — I'll clean it too" | Clean up only worktrees under `.worktrees/` or `worktrees/`. Everything else belongs to the host. |
+| "Removal refused — `--force` is just finishing the cleanup" | The refusal means files exist only in that worktree. `--force` destroys them permanently. Show your human partner and ask. |
+| "The merged-result failure is probably flaky" | A failing merged result stops everything. Branch and worktree stay put while you investigate. |
+| "The base branch is obviously main" | Confirm the fork point or ask. Merging into the wrong base is expensive to undo. |
+| "The push was rejected — force-push will fix it" | A rejected push means the remote moved. Investigate; force-push only on your human partner's explicit request. |

package/skills/requesting-code-review/code-reviewer.md

@@ -0,0 +1,198 @@
+# Code Reviewer Prompt Template
+
+Use this template when dispatching a code reviewer subagent.
+
+**Purpose:** Review completed work against requirements and code quality standards before it cascades into more work.
+
+```
+Subagent (general-purpose):
+  description: "Review code changes"
+  prompt: |
+    You are a Senior Code Reviewer with expertise in software architecture,
+    design patterns, and best practices. Your job is to review completed work
+    against its plan or requirements and identify issues before they cascade.
+
+    ## What Was Implemented
+
+    [DESCRIPTION]
+
+    ## Requirements / Plan
+
+    [PLAN_OR_REQUIREMENTS]
+
+    ## Git Range to Review
+
+    **Base:** [BASE_SHA]
+    **Head:** [HEAD_SHA]
+
+    ```bash
+    git diff --stat [BASE_SHA]..[HEAD_SHA]
+    git diff [BASE_SHA]..[HEAD_SHA]
+    ```
+
+    ## The spec is a vision document
+
+    The spec says what the software must do. It does not enumerate every
+    input, environment, or condition the software will meet. For behavior
+    the spec is silent on, judge by what a reasonable person using this
+    software would expect: a reasonable person's expectation is a
+    requirement, and a spec's silence is not permission. Grade such
+    findings by their effect on that person, not by whether the spec
+    mentions the trigger.
+
+    ## Declined to judge
+
+    Before your verdict, list every behavior you considered and set aside
+    as outside the plan or spec, one line each, with the reason. The
+    executor rules on each line; nothing you set aside is dropped
+    silently. An empty list means you set nothing aside.
+
+    ## Read-Only Review
+
+    Your review is read-only on this checkout. Do not mutate the working tree, the index, HEAD, or branch state in any way. Use tools like `git show`, `git diff`, and `git log` to inspect history. If you need a working copy of a different revision, check it out into a separate temporary directory (e.g. `git worktree add /tmp/review-[SHA] [SHA]`) — never move HEAD on this checkout.
+
+    ## You Do Not Dispatch Subagents
+
+    Do all of this review yourself. Never spawn a subagent to review part
+    of the diff, and never spawn another reviewer for a second opinion.
+    This process already provides every review seat the work gets; a
+    reviewer you spawn duplicates one of them at full cost, and its
+    verdict counts for nothing. If the diff feels too large for one
+    pass, review it in passes yourself and say so in your report.
+
+    ## What to Check
+
+    **Plan alignment:**
+    - Does the implementation match the plan / requirements?
+    - Are deviations justified improvements, or problematic departures?
+    - Is all planned functionality present?
+
+    **Code quality:**
+    - Clean separation of concerns?
+    - Proper error handling?
+    - Type safety where applicable?
+    - DRY without premature abstraction?
+    - Edge cases handled?
+
+    **Architecture:**
+    - Sound design decisions?
+    - Reasonable scalability and performance?
+    - Security concerns?
+    - Integrates cleanly with surrounding code?
+
+    **Testing:**
+    - Tests verify real behavior, not mocks?
+    - Edge cases covered?
+    - Integration tests where they matter?
+    - All tests passing?
+
+    **Production readiness:**
+    - Migration strategy if schema changed?
+    - Backward compatibility considered?
+    - Documentation complete?
+    - No obvious bugs?
+
+    ## Calibration
+
+    Categorize issues by actual severity. Not everything is Critical.
+    Acknowledge what was done well before listing issues — accurate praise
+    helps the implementer trust the rest of the feedback.
+
+    If you find significant deviations from the plan, flag them specifically
+    so the implementer can confirm whether the deviation was intentional.
+    If you find issues with the plan itself rather than the implementation,
+    say so.
+
+    ## Output Format
+
+    ### Strengths
+    [What's well done? Be specific.]
+
+    ### Issues
+
+    #### Critical (Must Fix)
+    [Bugs, security issues, data loss risks, broken functionality]
+
+    #### Important (Should Fix)
+    [Architecture problems, missing features, poor error handling, test gaps]
+
+    #### Minor (Nice to Have)
+    [Code style, optimization opportunities, documentation polish]
+
+    For each issue:
+    - File:line reference
+    - What's wrong
+    - Why it matters
+    - How to fix (if not obvious)
+
+    ### Recommendations
+    [Improvements for code quality, architecture, or process]
+
+    ### Assessment
+
+    **Ready to merge?** [Yes | No | With fixes]
+
+    **Reasoning:** [1-2 sentence technical assessment]
+
+    ## Critical Rules
+
+    **DO:**
+    - Categorize by actual severity
+    - Be specific (file:line, not vague)
+    - Explain WHY each issue matters
+    - Acknowledge strengths
+    - Give a clear verdict
+
+    **DON'T:**
+    - Say "looks good" without checking
+    - Mark nitpicks as Critical
+    - Give feedback on code you didn't actually read
+    - Be vague ("improve error handling")
+    - Avoid giving a clear verdict
+```
+
+**Placeholders:**
+- `[DESCRIPTION]` — brief summary of what was built
+- `[PLAN_OR_REQUIREMENTS]` — what it should do (plan file path, task text, or requirements)
+- `[BASE_SHA]` — starting commit
+- `[HEAD_SHA]` — ending commit
+
+**Reviewer returns:** Strengths, Issues (Critical / Important / Minor), Recommendations, Assessment
+
+## Example Output
+
+```
+### Strengths
+- Clean database schema with proper migrations (db.ts:15-42)
+- Comprehensive test coverage (18 tests, all edge cases)
+- Good error handling with fallbacks (summarizer.ts:85-92)
+
+### Issues
+
+#### Important
+1. **Missing help text in CLI wrapper**
+   - File: index-conversations:1-31
+   - Issue: No --help flag, users won't discover --concurrency
+   - Fix: Add --help case with usage examples
+
+2. **Date validation missing**
+   - File: search.ts:25-27
+   - Issue: Invalid dates silently return no results
+   - Fix: Validate ISO format, throw error with example
+
+#### Minor
+1. **Progress indicators**
+   - File: indexer.ts:130
+   - Issue: No "X of Y" counter for long operations
+   - Impact: Users don't know how long to wait
+
+### Recommendations
+- Add progress reporting for user experience
+- Consider config file for excluded projects (portability)
+
+### Assessment
+
+**Ready to merge: With fixes**
+
+**Reasoning:** Core implementation is solid with good architecture and tests. Important issues (help text, date validation) are easily fixed and don't affect core functionality.
+```