@izkac/forgekit 0.1.0

package/vendor/skills/forge/references/runtime-integrity.md

@@ -0,0 +1,157 @@
+# Runtime integrity (hard rules)
+
+Forge verifies **outcomes of the system**, not only artifacts of work. These
+rules apply at every pace. Coordinators, implementers, and reviewers must not
+weaken them in briefs.
+
+## 1. No stubs / no false success
+
+A handler that only logs, bumps progress, or marks a job/request `succeeded`
+without doing the domain work is **forbidden**.
+
+- If a job kind (or API path) is enqueueable / callable in production, it MUST
+  run real domain logic, **or** fail closed with a clear error, **or** not be
+  exposed at all.
+- Never authorize “stub OK”, “minimal poll loop only”, or “wire later” for a
+  path this change claims.
+
+## 2. Runtime owner required
+
+A capability requirement is **not** met by a library module alone.
+
+- For every REQ / capability this change implements, name the **production
+  caller** (worker job kind, HTTP endpoint, CLI command, scheduled job, …).
+- Library-only = incomplete. Add a wiring task before marking the section done.
+
+## 3. Tests must fail on a no-op
+
+Evidence that only asserts ceremony is invalid.
+
+| Invalid | Valid |
+| ------- | ----- |
+| Job status became `succeeded` | Fixture upload/run left the expected domain side effects |
+| Handler was called | Mongo/files/artifacts match the capability (or structured failure) |
+| Queue claim/lease works | Pairing/stats/proposals/exports exist as specified |
+
+If a test suite would still pass with a no-op handler, it does not prove the
+task.
+
+## 4. Briefs may not narrow scope
+
+**Capability specs beat narrow task wording** when they conflict.
+
+- Coordinator briefs MUST NOT redefine done downward (e.g. authorize a stub
+  when the spec requires real ETL).
+- To shrink scope: stop and ask the user. Do not silently checkbox around gaps.
+- Prefer `DONE_WITH_CONCERNS` / incomplete tasks over green checkboxes.
+
+## 5. E2E means product loop, not job slice
+
+Before claiming the change complete:
+
+1. Run (or document exact commands for) the **closed product loop** through the
+   live entry points, **or**
+2. Leave an explicit **`BLOCKED`** list in `verify-evidence.md` — and do **not**
+   mark the change complete / advance to `done`.
+
+**A single job slice is not platform E2E.** When the design has a
+producer/consumer split (analyze vs execute, proposals vs ratify, write vs
+read), the required E2E is the full loop:
+
+```
+produce artifact → consumer reads it → decision/state change →
+next run's OUTPUT DIFFERS from the baseline
+```
+
+Example: ingest→Parquet plus a thin run→`.sav` does **not** verify a
+governance loop; analyze→proposals→ratify→run-applies-decisions does.
+Record it under a `## Product loop` heading in `verify-evidence.md` —
+the mechanical gate looks for it.
+
+## 6. Job-kind closure
+
+Every job kind / entry point on the product surface (enums, API, UI) is, before
+the change can be complete, exactly one of:
+
+- **Wired end-to-end** (enqueueable + handled + domain side effects), or
+- **Deleted** from the enums / API / UI surface.
+
+“Fail closed for unsupported kind” is only a **temporary BLOCKED state**, never
+“change complete.” Schema fiction (kinds nobody handles or enqueues) is a
+verify failure.
+
+## 7. Consumer–producer rule
+
+If a UI page, API response, or downstream job **reads** a collection, artifact,
+or field, verify must prove something in the **production path writes it**
+(fixture evidence), or the change is BLOCKED. Empty-forever queues that only
+tests can fill are a REJECT.
+
+## 8. Deferrals are tracked debt, never checkboxes
+
+“Wiring in a later task/section” is only acceptable when registered:
+
+```bash
+forge defer add --task <id> --reason "wiring lands in task <id>"
+forge defer resolve --task <id>     # when the wiring task actually lands
+```
+
+- Reviewers may only accept a deferral that names a **registered, still-open**
+  task (`forge defer list`).
+- `forge phase done|finish` **refuses** while any deferral is unresolved.
+- An unregistered "later" in a brief or review is a REJECT.
+
+## Spine matrix (mechanical — `forge spine`)
+
+**Spine is mandatory for every Forge change** — not gated on pace, and not
+inferred from slug keywords (that miss is how hollow platforms shipped).
+
+At plan time (every change):
+
+```bash
+forge spine init
+```
+
+Then either:
+
+1. **Fill rows** — one per capability/REQ cluster:
+
+   | capability | library | runtimeOwner | writes | reads | uiConsumer | evidence |
+
+   Every cell filled (`reads` / `uiConsumer` may be `"N/A"`); `evidence` points
+   at the tier-2/E2E proof of the **wired** path. Library-only rows fail
+   `forge spine check` — and `forge phase done` runs the same check.
+
+2. **Or** set `"notApplicable": "<reason>"` for sync-only / docs-only work
+   (e.g. `"sync HTTP only — no async producer/consumer"`). That is the honest
+   opt-out; missing `spine.json` is not.
+
+Product-loop evidence in `verify-evidence.md` is required when the spine has
+real rows. Prefer `notApplicable` for sync-only changes instead of inventing a
+fake loop.
+
+## Reviewer REJECT checklist (mandatory)
+
+REJECT the task (or final review → `NOT READY`) if any of:
+
+- Success path has no domain side effects required by the capability
+- Tests would pass with a no-op handler
+- API / UI can enqueue or trigger a kind the runtime cannot truly execute
+- UI / consumers depend on data nothing in the production path writes
+- Spec requirement has a library but no named runtime owner
+- Deferred wiring without a registered open deferral (`forge defer list`)
+- Spine row for this capability missing or library-only
+
+## Plan seam (every change)
+
+Before apply-ready:
+
+1. `forge spine init` — **always**. Fill rows for each capability, or set
+   `notApplicable` with a reason (sync-only / docs-only).
+2. If the change involves workers, job queues, handlers, or cross-runtime
+   calls, `tasks.md` MUST also include:
+   - Explicit **wiring** tasks per job kind / entry point → domain pipeline
+   - One **product-loop acceptance** task (last implement task, before verify)
+
+Missing spine = plan not ready. Keyword guesses about “jobs in scope” are not
+an excuse to skip the spine.

package/vendor/skills/forge/references/substantial-work.md

@@ -0,0 +1,37 @@
+# Substantial work triage
+
+Run this check **before** implementation on every agent turn unless the user
+sent **`/forge:skip`**.
+
+**Forge = OpenSpec.** If work is substantial enough for Forge, it is substantial enough for a
+tracked OpenSpec change. Smaller work skips Forge entirely (direct execution).
+
+## Enter Forge when ANY apply
+
+- New feature or behavior change
+- Bug fix that changes logic (not typo-only)
+- Multi-file or multi-workspace edit
+- Public API, Zod schema, OpenAPI, shared package export, or config schema change
+- Cross-package / cross-product impact (grep consumers)
+- User invokes `/forge` or any `/forge:*` command (except `/forge:skip`)
+- Work would likely produce an ADR or new `openspec/specs/` capability
+
+## Skip Forge (execute directly) when ALL apply
+
+- Pure question, explanation, or read-only review
+- Typo, comment, formatting-only, or rename with zero behavior change
+- User explicitly sent **`/forge:skip`** for this task
+
+## `/forge:skip` behaviour
+
+1. If an active Forge session exists, run:
+   ```bash
+   forge phase skipped
+   ```
+2. Do **not** start brainstorm or plan for this task.
+3. Proceed with the user's request under normal project rules.
+
+## Ambiguous cases
+
+Ask one clarifying question: **would this produce an OpenSpec change?** If yes → Forge (OpenSpec).
+If no → execute directly. Skip requires explicit user opt-out (`/forge:skip`).

package/vendor/skills/forge/references/tdd-core.md

@@ -0,0 +1,29 @@
+# TDD core (condensed — inject into implementer briefs)
+
+Full skill: [skills/test-driven-development/SKILL.md](../skills/test-driven-development/SKILL.md) — read it only when stuck (hard-to-test design, mock-heavy setup, unclear failures). Anti-patterns for mocks/test utilities: [testing-anti-patterns.md](../skills/test-driven-development/testing-anti-patterns.md).
+
+## Iron Law
+
+**No production code without a failing test first.** Wrote code before the test? Delete it and start over — don't keep it as "reference".
+
+## The loop
+
+1. **RED** — write one minimal test for one behavior. Clear name, real code (mocks only if unavoidable).
+2. **Verify RED (mandatory)** — run the scoped test; confirm it *fails* for the right reason (feature missing, not a typo/error). Passes immediately? You're testing existing behavior — fix the test.
+3. **GREEN** — simplest code that passes. No extra features, options, or "improvements" beyond the test (YAGNI).
+4. **Verify GREEN (mandatory)** — re-run the same scoped file/pattern; output pristine. Test fails? Fix code, not test.
+5. **REFACTOR** — dedupe, rename, extract; stay green; no new behavior.
+6. Repeat with the next failing test.
+
+## Test tiers (Forge)
+
+- **Tier 1 (each red/green cycle):** single test file or pattern — never the full workspace suite.
+- **Tier 2 (task done):** narrowest command proving this task — changed tests + directly related tests. Full workspace runs **once at verify (tier 3)**, not per task. Report command + exit code + pass/fail summary.
+
+## Red flags — stop and start over
+
+Code before test · test passes immediately · can't explain the failure · "I'll test after" · "already manually tested" · "too simple to test" · "keep as reference / adapt existing code" · "deleting X hours is wasteful" (sunk cost) · "run full workspace to be safe" (tier 3 belongs at verify) · "just this once".
+
+## Bugs
+
+Reproduce with a failing test first, then fix. Never fix a bug without a test.

package/vendor/skills/forge/references/test-evidence.md

@@ -0,0 +1,30 @@
+# Per-task test evidence (tier 2)
+
+Each implement task records **tier 2** proof that subagents ran tests. See [test-strategy.md](./test-strategy.md) for all three tiers.
+
+The **coordinator** records this file after the implementer reports — use `forge evidence --task <nn>-<slug> --command "<cmd>" --exit <code> --summary "<text>"` (machine timestamp; refuses non-zero exit without `--allow-fail`) rather than hand-writing it. Verify **audits** these files — it does **not** re-run the same tier 2 commands. Verify runs **tier 3** (full workspace) once separately; see [../phases/verify.md](../phases/verify.md).
+
+## Path
+
+`.forge/sessions/<session-id>/tasks/<nn>-<slug>/test-evidence.md`
+
+## Template
+
+```markdown
+# Test evidence — Task {nn}-{slug}
+
+- **Tier:** 2 (task-scoped — not full workspace unless noted)
+- **Command:** `npm test -- path/to/scoped.test.ts -- src/foo.test.ts`
+- **Exit code:** 0
+- **Summary:** 3/3 pass (or paste last ~20 lines of output)
+- **Run at:** 2026-06-05T15:04:22Z
+- **Recorded by:** implementer subagent (coordinator transcript)
+```
+
+## Rules
+
+- **Exit code must be `0`** before the task is marked complete.
+- **Default:** narrowest command — changed test file(s) + directly related tests. **Not** the full workspace suite.
+- **Full workspace at tier 2** only when the task changes shared contracts, cross-module integration, or the brief explicitly requires it. Note `Tier: 2 (full workspace — contract/integration)` in the file.
+- If the implementer re-ran tests after a fix, overwrite with the latest successful tier 2 run.
+- Verify **audits** tier 2 files and runs **tier 3** (full workspace) once — see [test-strategy.md](./test-strategy.md).

package/vendor/skills/forge/references/test-strategy.md

@@ -0,0 +1,68 @@
+# Tiered test strategy (Forge)
+
+Forge uses **three tiers**. Do **not** run the full workspace or monorepo test suite on every subagent task — that is slow and redundant when verify runs tier 3 once.
+
+## Tier 1 — TDD loop (within a task)
+
+During red/green/refactor, run **scoped** commands only:
+
+```bash
+npm test -- path/to/scoped.test.ts -- path/to/changed.test.ts
+```
+
+- Single test file or pattern for the behavior under change
+- Mandatory for TDD integrity (watch fail → pass)
+- Fast; repeat as often as needed
+
+## Tier 2 — Task completion evidence
+
+Before marking a task complete, run the **narrowest** command that proves **this task's** changes work:
+
+- Changed test file(s) + directly related tests in the same module/directory
+- Subpath or pattern filter when the runner supports it
+- **Not** the full workspace suite by default
+
+Record in `.forge/sessions/<id>/tasks/<nn>-<slug>/test-evidence.md`. See [test-evidence.md](./test-evidence.md).
+
+### Tier 2 may be wider (still not full monorepo)
+
+- Shared contract or public API change → include contract tests in affected packages
+- Cross-module integration within one workspace → run the relevant integration test directory
+- Task brief explicitly requires full workspace coverage
+
+### Do not use full workspace at tier 2 when
+
+- Changes are localized (typical 1–3 file task)
+- Multiple tasks target the same workspace (full suite runs once at **verify**)
+- Motivation is only "to be safe" — that is **verify's** job
+
+## Tier 3 — Verify phase (coordinator, after all tasks)
+
+After all implement tasks complete:
+
+1. **Audit** every `tasks/<nn>-<slug>/test-evidence.md` (exit `0`, pass summary, reviewers approved).
+2. Run **one fresh full workspace test** for each affected workspace (plus downstream consumer workspaces when contracts changed).
+3. Save output to `.forge/sessions/<id>/verify-evidence.md`.
+
+Tier 3 is the integration/regression gate. Cite this file when claiming the implementation passes.
+
+Re-run tier 3 when: tier 3 failed, coordinator edited code after verify evidence, quality/final review flagged test gaps, or the user asks for a fresh run.
+
+**Do not** re-run tier 2 narrow commands at verify — audit them instead.
+
+## Quick reference
+
+| Tier | Who | When | Scope |
+| ---- | --- | ---- | ----- |
+| 1 | Implementer | Each TDD red/green/refactor | Single file or pattern |
+| 2 | Implementer | Task done | Narrowest proof for this task |
+| 3 | Coordinator | Verify phase (once) | Full affected workspace(s) |
+
+## Anti-patterns
+
+| Don't | Do instead |
+| ----- | ---------- |
+| Full workspace test on every task | Tier 1 scoped + tier 2 narrow evidence |
+| Skip tier 3 because tasks passed | Always run tier 3 once at verify |
+| Re-run tier 2 commands at verify | Audit task evidence; run tier 3 full suite |
+| Full monorepo test at tier 2 | Tier 2 narrow; tier 3 per workspace (or listed consumers) |

package/vendor/skills/forge/skills/NOTICE.md

@@ -0,0 +1,17 @@
+# Vendored skills (Superpowers)
+
+Forge bundles adapted copies of skills from the [Superpowers](https://github.com/obra/superpowers)
+plugin (MIT). Upstream is not required at runtime.
+
+| Skill | Purpose in Forge |
+| ----- | ---------------- |
+| brainstorming | Brainstorm phase |
+| test-driven-development | Implement phase (per task) |
+| subagent-driven-development | Implement phase orchestration |
+| verification-before-completion | Verify phase |
+| requesting-code-review | Review phase |
+| systematic-debugging | Blockers during implement/debug |
+
+These copies are a **maintained fork**: originally vendored from Superpowers (MIT), then
+restructured  (single task reviewer, tiered testing, trimmed prose). Do not re-vendor
+from upstream — edit here and run `forgekit install --skills forge --force`.

package/vendor/skills/forge/skills/brainstorming/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: brainstorming
+description: Forge — brainstorm before plan. Internal skill; read via forge orchestrator.
+---
+
+# Brainstorming Ideas Into Designs
+
+Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
+
+Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design and get user approval.
+
+<HARD-GATE>
+Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.
+</HARD-GATE>
+
+## Anti-Pattern: "This Is Too Simple To Need A Design"
+
+Every project goes through this process. A todo list, a single-function utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval.
+
+## Checklist
+
+You MUST create a task for each of these items and complete them in order:
+
+1. **Explore project context** — check files, docs, recent commits
+2. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria (genuinely visual questions use `design/<surface>/` mockups — see Visual questions below)
+3. **Propose 2-3 approaches** — with trade-offs and your recommendation
+4. **Present design** — in sections scaled to their complexity, get user approval after each section
+5. **Write design doc** — save to `.forge/sessions/<session-id>/brainstorm/notes.md` and `decisions.md`
+6. **Spec self-review** — quick inline check for placeholders, contradictions, ambiguity, scope (see below)
+7. **User reviews written spec** — ask user to review the spec file before proceeding
+8. **OpenSpec propose** — invoke `openspec-propose` or `/opsx:propose <prefix>-<slug>` per forge plan-routing (no plan-mode prompt)
+
+## Process Flow
+
+Explore context → clarify (one question at a time) → propose 2-3 approaches → present design sections (revise until approved) → write design doc → spec self-review (fix inline) → user reviews spec (revise until approved) → **OpenSpec propose**.
+
+**The terminal state is OpenSpec propose.** Do NOT invoke frontend-design, mcp-builder, or any other implementation skill. Run `/opsx:propose` (or `openspec-propose`) — do not implement until OpenSpec artefacts are approved.
+
+## The Process
+
+**Understanding the idea:**
+
+- Check out the current project state first (files, docs, recent commits)
+- Before asking detailed questions, assess scope: if the request describes multiple independent subsystems (e.g., "build a platform with chat, file storage, billing, and analytics"), flag this immediately. Don't spend questions refining details of a project that needs to be decomposed first.
+- If the project is too large for a single spec, help the user decompose into sub-projects: what are the independent pieces, how do they relate, what order should they be built? Then brainstorm the first sub-project through the normal design flow. Each sub-project gets its own spec → plan → implementation cycle.
+- For appropriately-scoped projects, ask questions one at a time to refine the idea
+- Prefer multiple choice questions when possible, but open-ended is fine too
+- Only one question per message - if a topic needs more exploration, break it into multiple questions
+- Focus on understanding: purpose, constraints, success criteria
+
+**Exploring approaches:**
+
+- Propose 2-3 different approaches with trade-offs
+- Present options conversationally with your recommendation and reasoning
+- Lead with your recommended option and explain why
+
+**Presenting the design:**
+
+- Once you believe you understand what you're building, present the design
+- Scale each section to its complexity: a few sentences if straightforward, up to 200-300 words if nuanced
+- Ask after each section whether it looks right so far
+- Cover: architecture, components, data flow, error handling, testing
+- Be ready to go back and clarify if something doesn't make sense
+
+**Design for isolation and clarity:**
+
+- Break the system into smaller units that each have one clear purpose, communicate through well-defined interfaces, and can be understood and tested independently
+- For each unit, you should be able to answer: what does it do, how do you use it, and what does it depend on?
+- Can someone understand what a unit does without reading its internals? Can you change the internals without breaking consumers? If not, the boundaries need work.
+- Smaller, well-bounded units are also easier for you to work with - you reason better about code you can hold in context at once, and your edits are more reliable when files are focused. When a file grows large, that's often a signal that it's doing too much.
+
+**Working in existing codebases:**
+
+- Explore the current structure before proposing changes. Follow existing patterns.
+- Where existing code has problems that affect the work (e.g., a file that's grown too large, unclear boundaries, tangled responsibilities), include targeted improvements as part of the design - the way a good developer improves code they're working in.
+- Don't propose unrelated refactoring. Stay focused on what serves the current goal.
+
+## After the Design
+
+**Documentation:**
+
+- Write the validated design (spec) to `.forge/sessions/<session-id>/brainstorm/notes.md`
+  - (User preferences for spec location override this default)
+- Use elements-of-style:writing-clearly-and-concisely skill if available
+- Do not commit unless the user explicitly asks
+
+**Spec Self-Review:**
+After writing the spec document, look at it with fresh eyes:
+
+1. **Placeholder scan:** Any "TBD", "TODO", incomplete sections, or vague requirements? Fix them.
+2. **Internal consistency:** Do any sections contradict each other? Does the architecture match the feature descriptions?
+3. **Scope check:** Is this focused enough for a single implementation plan, or does it need decomposition?
+4. **Ambiguity check:** Could any requirement be interpreted two different ways? If so, pick one and make it explicit.
+
+Fix any issues inline. No need to re-review — just fix and move on.
+
+**User Review Gate:**
+After the spec review loop passes, ask the user to review the written spec before proceeding:
+
+> "Spec written to `<path>`. Please review before we proceed to the implementation plan."
+
+Wait for the user's response. If they request changes, make them and re-run the spec review loop. Only proceed once the user approves.
+
+**Implementation:**
+
+- Proceed to forge **plan phase** (OpenSpec via `/opsx:propose`)
+- Do NOT invoke implement phase or write production code yet
+
+## Key Principles
+
+- **One question at a time** - Don't overwhelm with multiple questions
+- **Multiple choice preferred** - Easier to answer than open-ended when possible
+- **YAGNI ruthlessly** - Remove unnecessary features from all designs
+- **Explore alternatives** - Always propose 2-3 approaches before settling
+- **Incremental validation** - Present design, get approval before moving on
+- **Be flexible** - Go back and clarify when something doesn't make sense
+
+## Visual questions
+
+When a question is genuinely visual (mockups, wireframes, layout comparisons — not merely *about* a UI topic), use the Janus convention instead of describing designs in prose: write static HTML mockups to `design/<surface-name>/` with a picker `index.html` plus one file per variant (AGENTS.md § Design exploration artefacts), then ask the user to open them and pick. Text questions (requirements, tradeoffs, A/B/C choices) stay in the terminal.

package/vendor/skills/forge/skills/requesting-code-review/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: requesting-code-review
+description: Forge — dispatch code review subagents. Internal skill; read via forge orchestrator.
+---
+
+# Requesting Code Review
+
+Dispatch forge/skills/code-reviewer subagent to catch issues before they cascade. The reviewer gets precisely crafted context for evaluation — never your session's history. This keeps the reviewer focused on the work product, not your thought process, and preserves your own context for continued work.
+
+**Core principle:** Review early, review often.
+
+## When to Request Review
+
+**Mandatory:**
+- After each task in subagent-driven development
+- After completing major feature
+- Before hand-off to user
+
+**Optional but valuable:**
+- When stuck (fresh perspective)
+- Before refactoring (baseline check)
+- After fixing complex bug
+
+## How to Request
+
+**1. Get git SHAs:**
+```bash
+BASE_SHA=$(git rev-parse HEAD~1)  # or origin/main
+HEAD_SHA=$(git rev-parse HEAD)
+```
+
+**2. Dispatch code-reviewer subagent:**
+
+Use Task tool with forge/skills/code-reviewer type, fill template at `code-reviewer.md`
+
+**Placeholders:**
+- `{WHAT_WAS_IMPLEMENTED}` - What you just built
+- `{PLAN_OR_REQUIREMENTS}` - What it should do
+- `{BASE_SHA}` - Starting commit
+- `{HEAD_SHA}` - Ending commit
+- `{DESCRIPTION}` - Brief summary
+
+**3. Act on feedback:**
+- Fix Critical issues immediately
+- Fix Important issues before proceeding
+- Note Minor issues for later
+- Push back if reviewer is wrong (with reasoning)
+
+## Integration with Forge
+
+- Per-task review is handled by the **task reviewer** in the implement phase
+- This skill drives the **final** whole-session review (and ad-hoc reviews when stuck or before merge)
+
+## Red Flags
+
+**Never:**
+- Skip review because "it's simple"
+- Ignore Critical issues
+- Proceed with unfixed Important issues
+- Argue with valid technical feedback
+
+**If reviewer wrong:**
+- Push back with technical reasoning
+- Show code/tests that prove it works
+- Request clarification
+
+Template: ./skills/requesting-code-review/code-reviewer.md

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

@@ -0,0 +1,146 @@
+# Code Review Agent
+
+You are reviewing code changes for production readiness.
+
+**Your task:**
+1. Review {WHAT_WAS_IMPLEMENTED}
+2. Compare against {PLAN_OR_REQUIREMENTS}
+3. Check code quality, architecture, testing
+4. Categorize issues by severity
+5. Assess production readiness
+
+## What Was Implemented
+
+{DESCRIPTION}
+
+## Requirements/Plan
+
+{PLAN_REFERENCE}
+
+## Git Range to Review
+
+**Base:** {BASE_SHA}
+**Head:** {HEAD_SHA}
+
+```bash
+git diff --stat {BASE_SHA}..{HEAD_SHA}
+git diff {BASE_SHA}..{HEAD_SHA}
+```
+
+## Review Checklist
+
+**Code Quality:**
+- Clean separation of concerns?
+- Proper error handling?
+- Type safety (if applicable)?
+- DRY principle followed?
+- Edge cases handled?
+
+**Architecture:**
+- Sound design decisions?
+- Scalability considerations?
+- Performance implications?
+- Security concerns?
+
+**Testing:**
+- Tests actually test logic (not mocks)?
+- Edge cases covered?
+- Integration tests where needed?
+- All tests passing?
+
+**Requirements:**
+- All plan requirements met?
+- Implementation matches spec?
+- No scope creep?
+- Breaking changes documented?
+
+**Production Readiness:**
+- Migration strategy (if schema changes)?
+- Backward compatibility considered?
+- Documentation complete?
+- No obvious bugs?
+
+## 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 improvements]
+
+**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 hand off?** [Yes/No/With fixes]
+
+**Reasoning:** [Technical assessment in 1-2 sentences]
+
+## Critical Rules
+
+**DO:**
+- Categorize by actual severity (not everything is Critical)
+- Be specific (file:line, not vague)
+- Explain WHY issues matter
+- Acknowledge strengths
+- Give clear verdict
+
+**DON'T:**
+- Say "looks good" without checking
+- Mark nitpicks as Critical
+- Give feedback on code you didn't review
+- Be vague ("improve error handling")
+- Avoid giving a clear verdict
+
+## 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 hand off: 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.
+```