prizmkit 1.1.78 → 1.1.80

package/bundled/skills-windows/feature-workflow/SKILL.md

@@ -131,71 +131,11 @@ Record everything the user provides — these become inputs for Step 1.3.
 
 ### Step 1.3: Parallel Deep Reading
 
-**Goal**: Build comprehensive understanding of the project context before discussing detailed requirements. Spawn multiple agents in parallel to read all relevant materials simultaneously.
-
-**Parallel reading tasks** (launch concurrently):
-
-| Agent | What to read | Purpose |
-|-------|-------------|---------|
-| Agent A | User-provided code paths — read existing source files | Understand current architecture, patterns, conventions |
-| Agent B | User-provided documents — design docs, specs, PRDs | Understand intended requirements and constraints |
-| Agent C | `.prizmkit/prizm-docs/` — root.prizm, L1/L2 docs, TRAPS, RULES | Understand existing architecture knowledge and known pitfalls |
-| Agent D | Database/schema files + `.prizmkit/config.json` | Understand data model and tech stack preferences |
-
-**Also gather** (can be included in any agent's task):
-- Directory structure of the project
-- Existing test patterns and conventions
-- Dependency relationships between existing modules
-
-**After all agents complete**: Synthesize findings into a coherent understanding before proceeding to discussion.
+Read `${SKILL_DIR}/references/brainstorm-guide.md` §Step 1.3 for the parallel agent dispatch procedure — spawn 4 agents (A: code paths, B: documents, C: prizm-docs, D: database/config) to build comprehensive project context before discussion. Synthesize findings before proceeding.
 
 ### Step 1.4: Discuss Requirements
 
-**Now** — with deep knowledge of the actual codebase and documents — discuss the requirements with the user. This discussion is grounded in real context, not abstract questions.
-
-Present what you learned from the parallel reading:
-- Current project structure and patterns (with specific references)
-- Existing data model and schema conventions
-- Known TRAPS and pitfalls from `.prizmkit/prizm-docs/`
-- Integration points with existing modules
-
-Then ask targeted questions based on what you read. **Adapt question depth to the feature complexity** — a simple CRUD feature needs fewer questions than a real-time collaboration system.
-
-**Functional Requirements:**
-- What are the core user actions/workflows?
-- What inputs does the system accept? What outputs does it produce?
-- What are the key business rules and validation logic?
-- Are there different user roles with different permissions?
-
-**Data Model & Database** (if applicable):
-- What entities/data need to be stored?
-- What are the relationships between entities?
-- Are there existing database tables this feature must integrate with?
-- What fields are required vs optional? What data types?
-- Any unique constraints, indexes, or special query patterns needed?
-- **RULE**: If the project has existing database tables, ALL new table designs must reference and conform to the existing schema style (naming conventions, ID strategy, timestamp patterns, constraint patterns). Ask the user to confirm the data model before proceeding.
-
-**User Experience:**
-- What does the user see and interact with?
-- What is the expected flow/sequence of actions?
-- How should errors be displayed to the user?
-- Are there any specific UI/UX requirements?
-
-**Integration & Architecture:**
-- "Based on the existing code, this feature would integrate with [modules]. Does that match your expectations?"
-- Any external APIs or services involved?
-- What authentication/authorization model applies?
-- Any real-time requirements (WebSocket, SSE, polling)?
-
-**Edge Cases & Error Handling:**
-- What happens when things go wrong? (network failure, invalid input, concurrent access)
-- What are the boundary conditions? (empty states, max limits, permissions denied)
-- Any rate limiting, quotas, or resource constraints?
-
-**Non-Functional Requirements:**
-- Performance expectations? (response time, throughput)
-- Scalability considerations?
-- Security requirements? (encryption, audit logs, compliance)
+Read `${SKILL_DIR}/references/brainstorm-guide.md` §Step 1.4 for the full requirements discussion framework — functional requirements, data model, user experience, integration/architecture, edge cases, and non-functional requirements. Ask targeted questions based on what was learned from parallel reading. **Adapt question depth to the feature complexity.**
 
 ### Step 1.5: Confirm and Supplement
 
@@ -206,57 +146,11 @@ After the discussion:
 3. **Identify gaps** — if any areas are still unclear, list them explicitly and ask follow-up questions
 4. **Repeat** until the user confirms: "That covers everything" or "Let's proceed"
 
-**Signs that brainstorming is complete:**
-- All functional requirements have concrete acceptance criteria
-- Data model entities and relationships are defined
-- Edge cases and error handling are addressed
-- Integration points are identified
-- The user has confirmed the summary is accurate
-
-**Signs that more questions are needed:**
-- User's answers contain vague terms ("handle it appropriately", "make it user-friendly", "standard behavior")
-- Core business rules are undefined ("depends on the situation")
-- Data relationships are unclear ("somehow connected")
-- User says "I'm not sure" — help them think through it with concrete options
+Read `${SKILL_DIR}/references/brainstorm-guide.md` §Completion Signs for the full checklist of when brainstorming is complete vs when more questions are needed.
 
 ### Step 1.6: Requirements Summary
 
-Once brainstorming is complete, produce a structured requirements summary:
-
-```markdown
-## Requirements Summary
-
-### Project/Feature: [Name]
-
-### Core Functionality
-- [Bullet list of what the system does]
-
-### User Roles
-- [Role]: [What they can do]
-
-### Data Model Overview
-- [Entity]: [Key fields, relationships]
-
-### Key Business Rules
-- [Rule 1]
-- [Rule 2]
-
-### Integration Points
-- [External system/API/module]
-
-### Edge Cases & Error Handling
-- [Case]: [Expected behavior]
-
-### Non-Functional Requirements
-- [Requirement]
-
-### Reference Materials Reviewed
-- [List of code paths, documents, .prizmkit/prizm-docs/ files that were read]
-
-### Confirmed by user: ✓
-```
-
-Present this summary to the user and get explicit confirmation before proceeding.
+Once brainstorming is complete, produce a structured requirements summary. Read `${SKILL_DIR}/references/brainstorm-guide.md` §Requirements Summary Template for the structured output format. Present the summary to the user and get explicit confirmation before proceeding.
 
 **CHECKPOINT CP-FW-0**: Requirements fully clarified and confirmed by user.
 
@@ -503,17 +397,7 @@ While the pipeline runs, the user can continue the conversation:
 
 ## Comparison with Alternative Workflows
 
-| Dimension | feature-workflow | bug-fix-workflow | refactor-workflow |
-|-----------|-----------------|------------------|-------------------|
-| **Purpose** | New features (batch) | Single bug fix (interactive) | Code restructuring (batch) |
-| **Brainstorming** | Yes — collect materials, parallel read, discuss | No (bug report is input) | Yes — clarify type, collect materials, parallel read, discuss |
-| **Planning Skill** | `feature-planner` | None (triage built-in) | `refactor-planner` |
-| **Branch** | Pipeline manages per-feature | `fix/<BUG_ID>-*` | Pipeline manages per-refactor |
-| **Execution** | Foreground or background daemon | In-session, interactive | Foreground or background daemon |
-| **Input** | Rough idea or requirements | Bug report / stack trace | Rough refactoring idea or target |
-| **Output** | Multiple `feat()` commits | Single `fix()` commit | Multiple `refactor()` commits |
-| **Behavior Change** | Expected (new functionality) | Fix behavior | Forbidden (structure only) |
-| **Batch alternative** | (this is the batch flow) | `bug-planner` + `bugfix-pipeline-launcher` | (this is the batch flow) |
+Read `${SKILL_DIR}/references/brainstorm-guide.md` §Comparison for the full comparison table (feature-workflow vs bug-fix-workflow vs refactor-workflow across 9 dimensions).
 
 ---
 

package/bundled/skills-windows/feature-workflow/references/brainstorm-guide.md

@@ -0,0 +1,137 @@
+# Brainstorm Guide — Detailed Procedures
+
+Procedural details for Phase 1 brainstorming in feature-workflow.
+
+## Step 1.3: Parallel Deep Reading
+
+**Goal**: Build comprehensive understanding of the project context before discussing detailed requirements. Spawn multiple agents in parallel to read all relevant materials simultaneously.
+
+**Parallel reading tasks** (launch concurrently):
+
+| Agent | What to read | Purpose |
+|-------|-------------|---------|
+| Agent A | User-provided code paths — read existing source files | Understand current architecture, patterns, conventions |
+| Agent B | User-provided documents — design docs, specs, PRDs | Understand intended requirements and constraints |
+| Agent C | `.prizmkit/prizm-docs/` — root.prizm, L1/L2 docs, TRAPS, RULES | Understand existing architecture knowledge and known pitfalls |
+| Agent D | Database/schema files + `.prizmkit/config.json` | Understand data model and tech stack preferences |
+
+**Also gather** (can be included in any agent's task):
+- Directory structure of the project
+- Existing test patterns and conventions
+- Dependency relationships between existing modules
+
+**After all agents complete**: Synthesize findings into a coherent understanding before proceeding to discussion.
+
+## Step 1.4: Discuss Requirements
+
+**Now** — with deep knowledge of the actual codebase and documents — discuss the requirements with the user. This discussion is grounded in real context, not abstract questions.
+
+Present what you learned from the parallel reading:
+- Current project structure and patterns (with specific references)
+- Existing data model and schema conventions
+- Known TRAPS and pitfalls from `.prizmkit/prizm-docs/`
+- Integration points with existing modules
+
+Then ask targeted questions based on what you read. **Adapt question depth to the feature complexity** — a simple CRUD feature needs fewer questions than a real-time collaboration system.
+
+### Functional Requirements
+- What are the core user actions/workflows?
+- What inputs does the system accept? What outputs does it produce?
+- What are the key business rules and validation logic?
+- Are there different user roles with different permissions?
+
+### Data Model & Database (if applicable)
+- What entities/data need to be stored?
+- What are the relationships between entities?
+- Are there existing database tables this feature must integrate with?
+- What fields are required vs optional? What data types?
+- Any unique constraints, indexes, or special query patterns needed?
+- **RULE**: If the project has existing database tables, ALL new table designs must reference and conform to the existing schema style (naming conventions, ID strategy, timestamp patterns, constraint patterns). Ask the user to confirm the data model before proceeding.
+
+### User Experience
+- What does the user see and interact with?
+- What is the expected flow/sequence of actions?
+- How should errors be displayed to the user?
+- Are there any specific UI/UX requirements?
+
+### Integration & Architecture
+- "Based on the existing code, this feature would integrate with [modules]. Does that match your expectations?"
+- Any external APIs or services involved?
+- What authentication/authorization model applies?
+- Any real-time requirements (WebSocket, SSE, polling)?
+
+### Edge Cases & Error Handling
+- What happens when things go wrong? (network failure, invalid input, concurrent access)
+- What are the boundary conditions? (empty states, max limits, permissions denied)
+- Any rate limiting, quotas, or resource constraints?
+
+### Non-Functional Requirements
+- Performance expectations? (response time, throughput)
+- Scalability considerations?
+- Security requirements? (encryption, audit logs, compliance)
+
+## Comparison with Alternative Workflows
+
+| Dimension | feature-workflow | bug-fix-workflow | refactor-workflow |
+|-----------|-----------------|------------------|--------------------|
+| **Purpose** | New features (batch) | Single bug fix (interactive) | Code restructuring (batch) |
+| **Brainstorming** | Yes — collect materials, parallel read, discuss | No (bug report is input) | Yes — clarify type, collect materials, parallel read, discuss |
+| **Planning Skill** | `feature-planner` | None (triage built-in) | `refactor-planner` |
+| **Branch** | Pipeline manages per-feature | `fix/<BUG_ID>-*` | Pipeline manages per-refactor |
+| **Execution** | Foreground or background daemon | In-session, interactive | Foreground or background daemon |
+| **Input** | Rough idea or requirements | Bug report / stack trace | Rough refactoring idea or target |
+| **Output** | Multiple `feat()` commits | Single `fix()` commit | Multiple `refactor()` commits |
+| **Behavior Change** | Expected (new functionality) | Fix behavior | Forbidden (structure only) |
+| **Batch alternative** | (this is the batch flow) | `bug-planner` + `bugfix-pipeline-launcher` | (this is the batch flow) |
+
+## Completion Signs
+
+**Signs that brainstorming is complete:**
+- All functional requirements have concrete acceptance criteria
+- Data model entities and relationships are defined
+- Edge cases and error handling are addressed
+- Integration points are identified
+- The user has confirmed the summary is accurate
+
+**Signs that more questions are needed:**
+- User's answers contain vague terms ("handle it appropriately", "make it user-friendly", "standard behavior")
+- Core business rules are undefined ("depends on the situation")
+- Data relationships are unclear ("somehow connected")
+- User says "I'm not sure" — help them think through it with concrete options
+
+## Requirements Summary Template
+
+Once brainstorming is complete, produce a structured requirements summary using the following format. Present the summary to the user and get explicit confirmation before proceeding.
+
+```markdown
+## Requirements Summary
+
+### Project/Feature: [Name]
+
+### Core Functionality
+- [Bullet list of what the system does]
+
+### User Roles
+- [Role]: [What they can do]
+
+### Data Model Overview
+- [Entity]: [Key fields, relationships]
+
+### Key Business Rules
+- [Rule 1]
+- [Rule 2]
+
+### Integration Points
+- [External system/API/module]
+
+### Edge Cases & Error Handling
+- [Case]: [Expected behavior]
+
+### Non-Functional Requirements
+- [Requirement]
+
+### Reference Materials Reviewed
+- [List of code paths, documents, .prizmkit/prizm-docs/ files that were read]
+
+### Confirmed by user: ✓
+```

package/bundled/skills-windows/prizm-kit/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: "prizm-kit"
+description: "Full-lifecycle dev toolkit index. Routes to the right PrizmKit skill for spec-driven development, Prizm docs, code quality, deployment, and knowledge management. Use when the user asks 'which command?', 'help', 'how do I start a feature', 'get started', 'what tools', 'dev workflow', 'lifecycle', or '/prizmkit'. Use this as the entry point for the full PrizmKit development lifecycle."
+---
+
+# PrizmKit — Full-Lifecycle Development Toolkit
+
+### When to Use
+- User asks "which command?", "help", "how do I start a feature", "get started", "what tools"
+- User wants to understand the PrizmKit development lifecycle
+- User invokes "/prizmkit" or asks about dev workflow
+- User is new to the project and needs orientation
+
+### When NOT to Use
+- User already knows which specific skill to use — invoke it directly
+- Mid-implementation — use the specific skill needed (/prizmkit-implement, /prizmkit-code-review, etc.)
+- User wants to execute immediately without orientation — go directly to /prizmkit-plan or /prizmkit-implement
+
+## Task Execution Model
+
+PrizmKit uses **headless mode** — each task runs as an independent AI CLI session with NO context carryover between tasks. Every session starts by reading docs and ends by maintaining docs.
+
+**Per-task flow**:
+```
+read docs → plan → implement → code-review → retrospective → committer
+```
+
+Each task begins by reading context at two levels:
+
+**Application level** (read every session):
+- `.prizmkit/prizm-docs/root.prizm` — L0 project architecture index (modules, tech stack, conventions)
+- `.prizmkit/plans/project-brief.md` — user's product vision checklist (generated during project initialization)
+- `.prizmkit/config.json` — tech stack config, deploy strategy
+
+**Task level** (read for the specific task):
+- `spec.md` / `plan.md` — task specification and implementation plan
+- `.prizmkit/prizm-docs/<module>.prizm` (L1/L2) — architecture docs for affected modules (TRAPS, DECISIONS, INTERFACES)
+
+Each cycle produces spec, plan, and task artifacts that create a traceable record of what was built and why. `.prizmkit/prizm-docs/` stays in sync through retrospective, so the next session starts with up-to-date context.
+
+**Fast path** — for small, well-scoped changes, always ask user whether to use fast path:
+```
+/prizmkit-plan → /prizmkit-implement → /prizmkit-committer
+```
+
+### Development Scenarios
+
+PrizmKit supports any development scenario through the same skill chain. `/prizmkit-plan` produces `spec.md` + `plan.md` regardless of the task type:
+
+| Scenario | Artifacts | When to Use |
+|----------|-----------|-------------|
+| **Feature** | `spec.md` → `plan.md` → code | New functionality, UI, API, data model changes |
+| **Bug Fix** | `spec.md` → `plan.md` → code | Complex defects, regressions, crash fixes. Simple bugs can use fast path directly. |
+| **Refactor** | `spec.md` → `plan.md` → code | Restructure, extract, rename, performance. No behavior change. |
+
+All three follow the same per-task flow. Detailed documentation policies (when to update `.prizmkit/prizm-docs/`, when to skip steps) are defined within each skill — not here.
+
+### Best Practices for AI-Driven Development
+
+**Monorepo structure recommended**: Keep frontend, backend, and shared libraries in one repository. AI needs visibility into the full call chain — cross-repo references are invisible to it. If you have a multi-repo setup, add all related repos to the AI workspace so module boundaries and API contracts are discoverable.
+
+**Module organization**: Ensure every meaningful module has a `.prizmkit/prizm-docs/` L1 doc. AI reads TRAPS and DECISIONS before modifying files — undocumented modules get no guardrails.
+
+**Small, focused tasks**: Break large features into tasks that can each be completed in one AI session. The pipeline handles this automatically via `/prizmkit-plan` task decomposition.
+
+## Core Skill Reference
+
+| Skill | Purpose | Trigger Phrases |
+|-------|---------|-----------------|
+| `/prizmkit-plan` | Specify + plan: natural language → spec.md → plan.md + tasks | "specify", "plan", "new feature", "I want to add...", "architect", "break it down" |
+| `/prizmkit-implement` | Execute plan.md tasks, write code (TDD) | "implement", "build", "code it", "start coding" |
+| `/prizmkit-code-review` | Diagnose issues + produce Fix Instructions | "review", "check code", "is it ready to commit" |
+| `/prizmkit-retrospective` | Sync .prizmkit/prizm-docs/ with code changes | "retrospective", "retro", "sync docs", "wrap up" |
+| `/prizmkit-committer` | Safe git commit with Conventional Commits | "commit", "submit", "finish", "ship it" |
+| `/prizmkit-deploy` | Generate/update deployment documentation | "deploy docs", "deployment guide", "how to deploy" |
+| `/prizmkit-init` | Project bootstrap + .prizmkit/prizm-docs/ setup | "init", "initialize", "take over this project" |
+| `/prizmkit-prizm-docs` | Doc management (init/status/rebuild/validate) | "check docs", "rebuild docs", "validate docs" |
+
+**Reading guide**:
+- Need code structure/modules/interfaces/traps/decisions? → `.prizmkit/prizm-docs/`
+
+## Quick Start (First-Time Setup)
+
+1. `npx prizmkit install .` → installs skills, rules (`prizm-documentation.md`, `prizm-commit-workflow.md`), hooks, platform scaffolding
+2. `/prizmkit-init` → scans project code, generates `.prizmkit/prizm-docs/`, detects tech stack, populates `.prizmkit/config.json`
+3. `/prizmkit-plan` → specify your first feature → produces spec.md + plan.md
+4. `/prizmkit-implement` → TDD implementation following the plan
+5. `/prizmkit-code-review` → review before commit
+6. `/prizmkit-retrospective` → sync `.prizmkit/prizm-docs/` with changes
+7. `/prizmkit-committer` → safe Conventional Commit
+
+> **Note**: Rules and hooks are installed by `npx prizmkit install`, not by `/prizmkit-init`.

package/bundled/skills-windows/prizmkit-code-review/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: "prizmkit-code-review"
+description: "Iterative review-fix loop against spec and plan. Spawns a read-only Reviewer agent, filters findings, then a Dev agent applies fixes. Loops until PASS (max 3 rounds). Use after /prizmkit-implement as quality gate. Trigger on: 'review', 'check code', 'code review', 'is it ready to commit'. (project)"
+---
+
+# PrizmKit Code Review
+
+An iterative review-fix loop that reviews code changes against the spec and plan, then automatically fixes issues. Uses three separated roles:
+
+- **Reviewer Agent** (read-only): analyzes git diff against spec goals and plan decisions, produces structured findings
+- **Main Agent** (orchestrator): filters Reviewer findings for reasonableness, coordinates the loop
+- **Dev Agent** (read-write): applies fixes for accepted findings
+
+The loop repeats until the Reviewer finds no issues or the max round limit is reached.
+
+### When to Use
+- After `/prizmkit-implement` to verify code quality before commit
+- User says "review", "check code", "review my implementation"
+- As a quality gate before `/prizmkit-committer`
+
+### When NOT to Use
+- Trivial changes (typo, single-line config) → commit directly
+- No spec.md or plan.md exists → nothing to review against
+
+## Input
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `artifact_dir` | No | Directory containing spec.md + plan.md. If omitted, scan `.prizmkit/` subdirectories for the most recently modified directory with a `plan.md` whose tasks are all completed. |
+
+## Phase 0: Context Loading
+
+1. **Read spec.md** from the artifact directory — extract goals and acceptance criteria.
+2. **Read plan.md** from the artifact directory — extract architecture decisions and completed tasks.
+3. **Read dev rules** (if configured): If `.prizmkit/prizm-docs/root.prizm` exists, read it and check for a `RULES:` line. If present, read all referenced `.prizmkit/rules/<layer>-rules.md` files. If `root.prizm` or a referenced rules file does not exist, continue with "No custom dev rules configured — use general best practices."
+4. **Capture workspace diff**: run `git diff` (unstaged) + `git diff --cached` (staged) + `git status` to understand the full scope of changes. For new files in git status, note their paths for the Reviewer to read.
+   - If no changes are detected, skip Phase 1 and proceed to Phase 2 with verdict PASS, rounds 0, and an empty findings list. Always write `review-report.md`; downstream pipeline steps use it as the review gate.
+
+## Phase 1: Review-Fix Loop
+
+### Gate Mode Detection
+
+The loop exit conditions are enforced by a gatekeeper. Check Python availability first:
+
+```bash
+python3 --version 2>/dev/null && echo "SCRIPT_MODE" || echo "TEXT_MODE"
+```
+
+- **Script mode** (Python available): Use `${SKILL_DIR}/scripts/check_loop.py` to enforce exit conditions with round tracking, max-rounds enforcement, and divergence detection. The script prevents accidentally exceeding the 3-round limit.
+- **Text mode** (no Python): Follow §Text Fallback Constraints — identical behavior enforced manually.
+
+### Step 0: Initialize Loop State
+
+The script is stateless — no `--reset` or runtime files. Initialize these values before starting:
+
+**Script mode** — `findings_history = []`, `max_rounds = 3`, `round = 1`.
+**Text mode** — track manually: `round = 1`, `findings_history = []`.
+
+### Loop Flow
+
+```
+1. Spawn Reviewer Agent (read-only) → findings or PASS
+2. Parse result:
+   - PASS → Call Loop Exit Gate → Phase 2
+   - NEEDS_FIXES → count findings → Step 3 (do not call gate yet)
+3. Main Agent filters findings → Call Loop Exit Gate → if endLoop: Phase 2
+4. Spawn Dev Agent (read-write) → apply fixes
+5. Increment round and return to Step 1
+```
+
+### Loop Exit Gate
+
+Call the gate only in these cases:
+
+1. Reviewer returned `PASS`.
+2. Main Agent has finished filtering `NEEDS_FIXES` findings.
+
+Do not call the gate for `NEEDS_FIXES` before filtering, because `accepted_count` is not known yet. Only exit the loop when `endLoop` is `true` — the gate is the sole authority on exit decisions.
+
+**Script mode invocation:**
+```bash
+echo '{"reviewer_result":"NEEDS_FIXES","accepted_count":2,"findings_count":3,"round":1,"findings_history":[],"max_rounds":3,"filtering_done":true}' | python3 ${SKILL_DIR}/scripts/check_loop.py
+```
+
+| Input field | Type | Description |
+|-------------|------|-------------|
+| `reviewer_result` | `"PASS"` or `"NEEDS_FIXES"` | Reviewer's verdict |
+| `accepted_count` | int | Findings accepted by Main Agent. Use `0` for Reviewer PASS or when all findings were rejected after filtering. |
+| `findings_count` | int | Total findings returned by Reviewer this round |
+| `round` | int | Current round number (1-based, model-supplied — the script does not auto-increment) |
+| `findings_history` | `[int, ...]` | Findings count per round, used for divergence detection. Initialize as `[]`. Pass back the value from the previous gate call's output. |
+| `max_rounds` | int | Maximum review rounds before forced exit. Default `3`. |
+| `filtering_done` | bool | `true` only after Main Agent has filtered `NEEDS_FIXES` findings. For Reviewer PASS, this may be omitted. |
+
+Output: `{"endLoop": bool, "reason": str, "verdict": "PASS"|"NEEDS_FIXES"|null, "round": int, "maxRounds": int, "divergenceWarning": bool, "findings_history": [int, ...]}`
+
+The script enforces three exit conditions in order: (1) Reviewer PASS → exit with verdict PASS, (2) filtered `NEEDS_FIXES` with zero accepted findings → exit with verdict PASS, (3) max rounds reached after filtering → exit with verdict NEEDS_FIXES. It records `findings_count` once per round by round index, so repeated gate calls cannot duplicate history entries. If `divergenceWarning` is true, warn the user the loop may not be converging.
+
+**Text mode** — enforce §Text Fallback Constraints manually with identical logic.
+
+### Text Fallback Constraints
+
+When Python is unavailable, apply these rules exactly — they match the script's logic:
+
+1. **PASS exit**: Reviewer returns `PASS` → exit loop, verdict PASS.
+2. **Pre-filter NEEDS_FIXES**: Count findings and continue to filtering. Do not apply all-rejected or max-round exits before filtering.
+3. **All-rejected exit**: After filtering, if all findings were rejected → exit loop, verdict PASS.
+4. **Max rounds**: After filtering, if `round >= 3` and accepted findings remain → exit loop, verdict NEEDS_FIXES. Write `review-report.md` with unresolved findings.
+5. **Divergence**: If findings count strictly increases for 3 consecutive recorded rounds, warn user the loop may not converge.
+6. **Counter**: Increment `round` after each complete cycle (Steps 1-4). Track `findings_history` by round index to detect divergence — record `findings_count` once per round.
+
+### Step 1: Spawn Reviewer Agent
+
+Include the dev rules read in Phase 0 step 3 in the `## Dev Rules` section of the prompt. Spawn a platform-supported **read-only** reviewer agent; use `subagent_type: Explore` only on platforms that support it. If no read-only agent is available, perform the review in the Main Agent without editing files. Read `${SKILL_DIR}/references/reviewer-agent-prompt.md` for the full prompt template — fill `{goals}`, `{plan decisions}`, `{dev rules}`, `{round N}`, and `{round_context}` before spawning.
+
+Round context varies by round:
+- Round 1: "This is the first review. Examine all changes comprehensively."
+- Round 2+: "Previous round found issues that were fixed. Focus on: (1) whether previous fixes are correct, (2) whether fixes introduced new problems, (3) any remaining issues. Do not re-report issues that have already been fixed."
+
+### Step 2: Check Result + Gate
+
+Parse the Reviewer Agent's output:
+- If `Result: PASS` → call the **Loop Exit Gate** with `{"reviewer_result": "PASS", "accepted_count": 0, "findings_count": 0, "round": <current_round>, "findings_history": <current_history>, "max_rounds": 3}`. If `endLoop=true`, proceed to Phase 2.
+- If `Result: NEEDS_FIXES` → count findings, do not call the gate yet, then continue to Step 3.
+
+### Step 3: Main Agent Filters Findings + Gate
+
+Review each finding and decide whether it's reasonable. This prevents unnecessary or harmful changes.
+
+**For each finding, evaluate:**
+- Is this relevant to the current changes? (Reject findings about unmodified, unrelated code.)
+- Is this a real problem or a subjective style preference? (Reject pure style preferences unless they violate clear project conventions.)
+- Would fixing this improve the code without introducing risk? (Reject fixes that require large refactors outside scope.)
+
+**Output per finding:**
+- **Accepted**: The finding is reasonable — include it in the Dev Agent's task.
+- **Rejected** (with reason): Brief explanation (e.g., "Out of scope", "Style preference, not a defect").
+
+After filtering: call the **Loop Exit Gate** with `{"reviewer_result": "NEEDS_FIXES", "accepted_count": <N>, "findings_count": <total findings this round>, "round": <current_round>, "findings_history": <current_history>, "max_rounds": 3, "filtering_done": true}`. If `endLoop=true`, proceed to Phase 2.
+
+### Step 4: Spawn Dev Agent
+
+Spawn a platform-supported **read-write** developer agent. If no write-capable agent is available, the Main Agent applies accepted fixes directly. Read `${SKILL_DIR}/references/dev-agent-prompt.md` for the full prompt template — fill `{spec context}` and `{accepted findings}` before spawning.
+
+After the Dev Agent returns, record results and return to Step 1 for the next round.
+
+## Phase 2: Output
+
+Always write `review-report.md` to the artifact directory, including no-change PASS results. Read `${SKILL_DIR}/references/review-report-template.md` for the full output format.
+
+- `PASS`: Reviewer returned no findings (or all remaining findings were rejected as unreasonable)
+- `NEEDS_FIXES`: 3 rounds completed but unresolved findings remain
+
+Also output a completion summary to conversation.
+
+**HANDOFF:** `/prizmkit-retrospective` (if PASS) or inform the caller of remaining issues (if NEEDS_FIXES after max rounds)

package/bundled/skills-windows/prizmkit-code-review/references/dev-agent-prompt.md

@@ -0,0 +1,30 @@
+# Dev Agent Prompt Template
+
+Used in Phase 1 Step 4 of `/prizmkit-code-review`. The orchestrator fills `{spec context}` and `{accepted findings}` before spawning the Dev Agent.
+
+```
+You are a developer fixing code review findings. Apply each fix carefully without breaking existing functionality.
+
+## Spec Context
+{goals from spec.md for reference}
+
+## Findings to Fix
+{accepted findings list — each with Severity, Location, Problem, Suggestion, Verification}
+
+## Instructions
+1. Read each finding carefully.
+2. For each finding:
+   a. Read the relevant code and understand the context.
+   b. Implement the fix based on the suggestion.
+   c. If a suggestion is not feasible (would break other functionality, technically impossible), explain why.
+3. After all fixes, report what you did.
+
+## Output Format
+For each finding, report:
+- **Finding N**: [fixed | unable-to-fix]
+- **What was done**: Brief description
+- **Files modified**: List of changed files
+(If unable-to-fix, explain why)
+```
+
+After the Dev Agent returns, record results and return to Step 1 for the next round.

package/bundled/skills-windows/prizmkit-code-review/references/review-report-template.md

@@ -0,0 +1,31 @@
+# Review Report Output Template
+
+Used in Phase 2 of `/prizmkit-code-review`. Always write `review-report.md` to the artifact directory using this format.
+
+```markdown
+# Review Report
+
+## Verdict: <PASS|NEEDS_FIXES>
+## Rounds: <number of review rounds completed; use 0 for no-change PASS>
+## Total findings: <total> → Fixed: <fixed>, Rejected: <rejected>, Unresolved: <unresolved>
+
+## Round <N>
+Findings: <count> | Accepted: <count>, Rejected: <count>
+
+### Finding <N>: <short title>
+- Severity: <high|medium|low>
+- Dimension: <goal-alignment|defect|completeness|consistency|security|rules-compliance>
+- Location: <filepath:line or project-level>
+- Problem: <what was wrong and why it mattered>
+- Status: <fixed (round N)|rejected — reason|unresolved — reason>
+
+## Final Summary
+<One to three sentences summarizing the review outcome, including no-change PASS when applicable.>
+```
+
+For `PASS` with no findings, write `Total findings: 0 → Fixed: 0, Rejected: 0, Unresolved: 0` and `## Round 0: PASS — no workspace changes to review` or `## Round N: PASS — no issues found`.
+
+## Verdict Rules
+
+- `PASS`: Reviewer returned no findings, no workspace changes existed, or all remaining findings were rejected as unreasonable.
+- `NEEDS_FIXES`: Max rounds completed but accepted findings remain unresolved.