prizmkit 1.1.10 → 1.1.12

package/bundled/dev-pipeline/templates/bugfix-bootstrap-prompt.md

@@ -2,40 +2,18 @@
 
 ## Session Context
 
-- **Pipeline Run ID**: {{RUN_ID}}
-- **Session ID**: {{SESSION_ID}}
 - **Bug ID**: {{BUG_ID}}
 - **Bug Title**: {{BUG_TITLE}}
 - **Severity**: {{SEVERITY}}
 - **Verification Type**: {{VERIFICATION_TYPE}}
-- **Retry Count**: {{RETRY_COUNT}} / {{MAX_RETRIES}}
-- **Previous Session Status**: {{PREV_SESSION_STATUS}}
-- **Resume From Phase**: {{RESUME_PHASE}}
 
 ## Your Mission
 
-You are the **bug fix session orchestrator**. Fix Bug {{BUG_ID}}: "{{BUG_TITLE}}".
+You are the **bug fix session agent**. Fix Bug {{BUG_ID}}: "{{BUG_TITLE}}".
 
-**CRITICAL SESSION LIFECYCLE RULE**: You MUST NOT exit until ALL work is complete and session-status.json is written. When you spawn subagents, you MUST **wait for each to finish** (run_in_background=false) before proceeding. Do NOT spawn an agent in the background and exit — that kills the session.
+**CRITICAL**: You MUST NOT exit until ALL work is complete and committed.
 
-**NON-INTERACTIVE MODE**: You are running in headless non-interactive mode. There is NO human on the other end. NEVER ask for user confirmation, NEVER wait for user input, NEVER use interactive prompts (e.g. "Would you like me to…"). If a skill has an interactive step (e.g. offer remediation, ask for approval), skip it and proceed autonomously. Make decisions based on the data available and move forward.
-
-**MANDATORY TEAM REQUIREMENT**: You MUST use the `prizm-dev-team` agents (Dev + Reviewer). This is NON-NEGOTIABLE. All implementation and review work MUST be performed by the appropriate team agents (Dev, Reviewer). You are the orchestrator — handle coordination, planning, and commit phases directly.
-
-**BUG FIX DOCUMENTATION POLICY**:
-- **DEFAULT**: Run `/prizmkit-retrospective` with structural sync only (Job 1). Skip knowledge injection (Job 2).
-- **UPDATE DOCS** (run full retrospective — Job 1 + Job 2) when the bug fix causes:
-  • Interface signature changes
-  • Dependency additions/removals
-  • Observable behavior changes to existing features
-  • Newly discovered TRAPs (gotchas/pitfalls)
-- **Simple bugs** (single file, clear root cause, ≤10 lines): Direct triage → fix → commit. No spec/plan needed. Artifacts: `fix-plan.md` + `fix-report.md` only.
-- **Complex bugs** (cross-module, cascading, data model/API changes): Use `/prizmkit-plan` with `artifact_dir=.prizmkit/bugfix/{{BUG_ID}}/` → generates `spec.md` + `plan.md`. Then use `/prizmkit-implement` to execute the plan. Artifacts: `spec.md` + `plan.md` + `fix-report.md`.
-- Commit with `fix(<scope>):` prefix, NOT `feat:`
-
-### Team Definition Reference
-
-- **Team config**: `{{TEAM_CONFIG_PATH}}`
+**NON-INTERACTIVE MODE**: There is NO human on the other end. NEVER ask for user confirmation, NEVER wait for user input. Make decisions autonomously and move forward.
 
 ### Bug Description
 
@@ -58,203 +36,184 @@ You are the **bug fix session orchestrator**. Fix Bug {{BUG_ID}}: "{{BUG_TITLE}}
 
 {{GLOBAL_CONTEXT}}
 
-## Bug Fix Artifacts Directory
+### Project Conventions
 
-**ALWAYS** use per-bug subdirectory `.prizmkit/bugfix/{{BUG_ID}}/`:
+> Read {{PLATFORM_CONVENTIONS}} for project-level coding standards, architecture decisions, and development rules.
 
-```
-Simple bugs:
-.prizmkit/bugfix/{{BUG_ID}}/
-├── fix-plan.md       ← Phase 1 output (generated after triage)
-└── fix-report.md     ← Phase 5 output (generated after commit)
+## ⚠️ Context Budget Rules (CRITICAL)
+
+0. **NON-INTERACTIVE MODE** — NEVER ask for confirmation. Proceed autonomously.
+1. **context-snapshot.md is your single source of truth** — After it is built, read context-snapshot.md instead of re-reading individual source files.
+2. **Never re-read your own writes** — Trust your write was correct.
+3. **Stay focused** — Do NOT explore code unrelated to this bug.
+4. **Minimize tool output** — Capture to temp file, scan head/tail, filter with grep/sed/awk. Never load full output.
+5. **No intermediate commits** — All changes committed once at the end via `/prizmkit-committer`.
 
-Complex bugs (cross-module, data model/API changes):
+## Bug Fix Artifacts Directory
+
+```
 .prizmkit/bugfix/{{BUG_ID}}/
-├── spec.md           ← /prizmkit-plan output (goals, root cause, scope)
-├── plan.md           ← /prizmkit-plan output (fix approach, tasks)
-└── fix-report.md     ← Phase 5 output (generated after commit)
+├── spec.md              ← /prizmkit-plan output (root cause, scope, behavior preservation)
+├── plan.md              ← /prizmkit-plan output (fix tasks, first task = reproduction test)
+├── context-snapshot.md  ← Project context for this bug
+└── fix-report.md        ← Final bug resolution report
 ```
 
-**IMPORTANT**: Simple bugs produce 2 artifact files (fix-plan.md + fix-report.md). Complex bugs produce 3 artifact files (spec.md + plan.md + fix-report.md).
-
 ## Workflow Checkpoint System
 
-A checkpoint file tracks your progress through this workflow:
-
 **Path**: `{{CHECKPOINT_PATH}}`
 
 **Rules**:
-1. **Before each step**: Read `workflow-checkpoint.json`, verify the previous step has `status: "completed"` or `status: "skipped"`. If not, complete it first.
-2. **Starting a step**: Update the current step to `status: "in_progress"`.
-3. **After each step completes**: Update the step to `status: "completed"`. Verify JSON is valid after writing.
-4. **On failure**: Set the step to `status: "failed"` and halt.
-5. **On resume**: Steps already `"completed"` are skipped. Start from the first `"pending"` or `"in_progress"` step.
+1. **Before each step**: Read `workflow-checkpoint.json`, verify the previous step is `"completed"`. If not, complete it first.
+2. **Starting a step**: Update to `status: "in_progress"`.
+3. **After step completes**: Update to `status: "completed"`.
+4. **On failure**: Set to `status: "failed"` and continue if possible.
+5. **On resume**: Skip `"completed"` steps. Start from first `"pending"` or `"in_progress"` step.
+
+---
 
-## Execution Instructions
+## Execution
 
-**YOU are the orchestrator. Execute each phase by spawning the appropriate team agent with run_in_background=false.**
+### Phase 0: Initialize
 
-### Step 1: Initialize
+```bash
+mkdir -p .prizmkit/bugfix/{{BUG_ID}}
+```
 
-#### Agent Setup
+### Phase 1: Diagnose & Plan
 
-Reference `{{TEAM_CONFIG_PATH}}` for agent definitions:
-- Dev: `{{DEV_SUBAGENT_PATH}}`
-- Reviewer: `{{REVIEWER_SUBAGENT_PATH}}`
+**Goal**: Identify root cause, build project context, produce spec.md + plan.md.
 
-3. Create bug fix artifacts directory:
-   ```bash
-   mkdir -p .prizmkit/bugfix/{{BUG_ID}}
-   ```
+**Step 1 — Diagnose the bug**:
 
-### Step 2: Pipeline Phases
+1. Read `.prizm-docs/root.prizm` and relevant L1/L2 docs for affected modules
+2. Trace the bug:
+   - Classify error type (Runtime / Network / Auth / Data / Logic / Config / External)
+   - Check `.prizm-docs/` TRAPS sections for matching known issues
+   - Trace call chain from error source to root cause
+   - Identify all affected files and modules
+3. Read the affected source files and related test files
 
-#### Phase 1: Triage — Classification
+**Step 2 — Build context snapshot** (skip if already exists):
 
-**Goal**: Classify the bug, identify scope and severity, check known issues, produce fix-plan.md.
+Write `.prizmkit/bugfix/{{BUG_ID}}/context-snapshot.md`:
+- **Section 1 — Bug Brief**: bug description + acceptance criteria + root cause analysis
+- **Section 2 — Affected Files**: full verbatim content of each affected source file
+- **Section 3 — Existing Tests**: full content of related test files
+- **Section 4 — Prizm Context**: relevant TRAPS, RULES from .prizm-docs/
 
-- Spawn Dev agent (Agent tool, subagent_type="prizm-dev-team-dev", run_in_background=false)
-  Prompt: "Read {{DEV_SUBAGENT_PATH}}. For bug {{BUG_ID}} ('{{BUG_TITLE}}'):
-  1. Triage the bug: classify error type (Runtime/Network/Auth/Data/Logic/Config/External), check `.prizm-docs/` TRAPS for known patterns, trace call chain to identify root cause
-  2. Check `.prizm-docs/` TRAPS sections for matching known issues
-  3. Classify: category, subcategory, root cause (confirmed or suspected), affected files
-  4. Assess impact: which modules are affected, what is the blast radius
-  5. Design test strategy based on verification_type='{{VERIFICATION_TYPE}}'
-  6. Propose fix approach: specific code changes, estimated scope
-  7. Write the complete fix plan to `.prizmkit/bugfix/{{BUG_ID}}/fix-plan.md`
+**Step 3 — Plan the fix**:
 
-  The fix-plan.md MUST contain these sections:
-  - Bug Summary (ID, title, severity, source type, affected feature)
-  - Root Cause Analysis (error classification, root cause, call chain, TRAP match)
-  - Impact Assessment (directly affected files, potentially affected modules)
-  - Test Strategy (reproduction test design, regression test plan, manual steps if hybrid/manual)
-  - Fix Approach (proposed fix, fix scope, constraints)
-  "
-- **Wait for Dev to return**
-- **CP-BF-1**: `.prizmkit/bugfix/{{BUG_ID}}/fix-plan.md` exists
-- **Checkpoint update**: set step `bug-diagnosis` to `"completed"` in `{{CHECKPOINT_PATH}}`
+Run `/prizmkit-plan` with `artifact_dir=.prizmkit/bugfix/{{BUG_ID}}/`:
+- The spec.md should capture: root cause, impact scope, behavior that must be preserved
+- The plan.md Tasks section **MUST start with a reproduction test task** — a test that FAILS with current code (RED state), proving the bug exists
+- Subsequent tasks implement the minimal fix to make the test pass (GREEN state)
+- Resolve any `[NEEDS CLARIFICATION]` markers autonomously — do NOT pause
 
 **DECISION GATE — Fast Path Check**:
-- If severity is LOW or MEDIUM, AND root cause is obvious (high confidence), AND fix is < 10 lines:
-  → Set `FAST_PATH=true`, skip Phase 2, go to Phase 3
-- Otherwise → proceed to Phase 2
+- If plan.md has ≤ 2 tasks AND root cause is obvious → mark `FAST_PATH=true`, skip Phase 3 (Review) later
+
+**CP-1**: spec.md and plan.md exist with Tasks section.
+
+**Checkpoint update**: Set step `bug-diagnosis-and-plan` to `"completed"`.
 
 {{IF_VERIFICATION_MANUAL_OR_HYBRID}}
-**NOTE**: When verification_type is 'manual' or 'hybrid', the fix-plan.md MUST also include:
+**NOTE**: verification_type is '{{VERIFICATION_TYPE}}'. The plan.md MUST also include:
 - Manual Verification Plan section with UAT checklist
 - User Review Required section specifying reviewer and blocking behavior
 {{END_IF_VERIFICATION_MANUAL_OR_HYBRID}}
 
 ---
 
-#### Phase 2: Reproduce — Reproduction Confirmation
-
-**Goal**: Create an automated reproduction that proves the bug exists.
-
-- Spawn Dev agent (Agent tool, subagent_type="prizm-dev-team-dev", run_in_background=false)
-  Prompt: "Read {{DEV_SUBAGENT_PATH}}. For bug {{BUG_ID}}:
-  1. Read the fix plan from `.prizmkit/bugfix/{{BUG_ID}}/fix-plan.md`
-  2. Generate a minimal reproduction test (API: curl sequence; UI: step-by-step; Logic: unit test; Data: seed+query) that FAILS with current code
-  4. Execute the reproduction test to confirm it fails
-  5. If reproduction fails, refine and retry (max 2 rounds)
-  6. Report: reproduction test path, red/green status, investigation pointers
-  "
-- **Wait for Dev to return**
-- If Dev reports reproduction failed after 2 rounds:
-  - Output: "Unable to reproduce bug {{BUG_ID}}. Need more information."
-  - Write session-status.json with status="partial", errors=["reproduction_failed"]
-  - Set bug status to `needs_info` and STOP
-- **CP-BF-2**: Reproduction test exists and FAILS
-- **Checkpoint update**: set step `bug-reproduce` to `"completed"` in `{{CHECKPOINT_PATH}}`
+### Phase 2: Implement & Fix
 
----
+**Goal**: Execute the fix plan. Reproduction test goes from RED → GREEN.
+
+Run `/prizmkit-implement` with `artifact_dir=.prizmkit/bugfix/{{BUG_ID}}/`:
+- Executes plan.md tasks in order (TDD: first task creates failing test, subsequent tasks fix the code)
+- Marks each task `[x]` on completion
+- Runs test suite after each task
+- Uses convergence-based test failure recovery (keep fixing while progress is being made)
+
+After implement completes, verify:
+1. All tasks in plan.md are `[x]`
+2. Reproduction test passes (GREEN)
+3. Full test suite passes (no regression)
+4. Each acceptance criterion is met
 
-#### Phase 3: Fix — Implementation
-
-**Goal**: Implement the fix. The reproduction test goes from red to green.
-
-- Spawn Dev agent (Agent tool, subagent_type="prizm-dev-team-dev", run_in_background=false)
-  Prompt: "Read {{DEV_SUBAGENT_PATH}}. For bug {{BUG_ID}}:
-  1. Read the fix plan from `.prizmkit/bugfix/{{BUG_ID}}/fix-plan.md`
-  2. Read `.prizm-docs/` for affected modules (TRAPS, RULES, PATTERNS)
-  3. Implement the minimal fix following TDD:
-     - The reproduction test is the 'red test'
-     - Make it pass with the smallest possible code change
-     - Do NOT refactor — fix the bug only
-  4. Run the reproduction test → MUST PASS
-  5. Run the module's test suite → MUST PASS (no regression)
-  6. If the fix involves multiple files or steps: run `/compact` after completing the core fix and before running the full test suite, to free context budget. If `/compact` is unavailable, continue without it.
-  7. If fix fails after 3 rounds, report detailed analysis
-  "
-- **Wait for Dev to return**
-- If fix fails after 3 rounds: escalate to user, write status="failed"
-- **CP-BF-3**: Reproduction test passes, module tests pass
-- **Checkpoint update**: set step `bug-fix` to `"completed"` in `{{CHECKPOINT_PATH}}`
+**CP-2**: All tasks complete, reproduction test passes, no regression.
+
+**Checkpoint update**: Set step `prizmkit-implement` to `"completed"`.
 
 ---
 
-#### Phase 4: Verify — Code Review & Regression Verification
+### Phase 3: Review
+
+If `FAST_PATH=true` (≤ 2 tasks, obvious root cause), skip this phase entirely.
 
-**Goal**: Ensure fix correctness and no regressions.
+Run `/prizmkit-code-review` with `artifact_dir=.prizmkit/bugfix/{{BUG_ID}}/`:
+- Reviews changes against spec.md
+- If NEEDS_FIXES: fix the issues and re-run review (max 3 review rounds)
+- If PASS or PASS_WITH_WARNINGS: proceed
 
-- Spawn Reviewer agent (Agent tool, subagent_type="prizm-dev-team-reviewer", run_in_background=false)
-  Prompt: "Read {{REVIEWER_SUBAGENT_PATH}}. For bug {{BUG_ID}}:
-  1. Read `.prizmkit/bugfix/{{BUG_ID}}/fix-plan.md` for goals, root cause, and fix approach (always exists for both simple and complex bugs)
-  2. Read `.prizmkit/bugfix/{{BUG_ID}}/plan.md` (if it exists, complex bugs only) for architecture decisions and completed tasks
-  3. Run `/prizmkit-code-review` with artifact_dir=.prizmkit/bugfix/{{BUG_ID}}/ scoped to CHANGED FILES ONLY (both phases: diagnostic + fix strategy)
-  4. Run full test suite and verify ALL tests pass
-  5. review-report.md will be written to .prizmkit/bugfix/{{BUG_ID}}/ by prizmkit-code-review
-  6. Report: number of findings found, or 'no findings' if clean
-  "
-- **Wait for Reviewer to return**
-- **Verdict decision** (L4 responsibility): If findings exist → return to Phase 3 for refinement (max 2 review rounds). If no findings → proceed.
-- **CP-BF-4**: Code review passes, all tests green
-- **Checkpoint update**: set step `prizmkit-code-review` to `"completed"` in `{{CHECKPOINT_PATH}}`
+**CP-3**: Code review passes, all tests green.
+
+**Checkpoint update**: Set step `prizmkit-code-review` to `"completed"`.
 
 {{IF_VERIFICATION_MANUAL_OR_HYBRID}}
 **MANUAL VERIFICATION GATE**:
-- After automated review passes, Pipeline PAUSES here
-- Output: "Bug {{BUG_ID}} fix is ready for manual verification. Please perform UAT checklist from fix-plan.md."
-- Write session-status.json with status="partial", current_phase=4, resume_from_phase=5
-- Set bug status to `verifying` and wait for user confirmation
+- After automated review passes, write session-status.json with status="partial", resume_from_phase=4
+- Set bug status to `verifying` and STOP — manual UAT required before commit
 {{END_IF_VERIFICATION_MANUAL_OR_HYBRID}}
 
 ---
 
-#### Phase 5: Commit & Learn — Commit & Knowledge Capture
-
-**Goal**: Commit the fix, update TRAPS, generate fix-report.md.
+### Phase 4: Commit & Learn
 
-**This phase is executed by YOU (the orchestrator), NOT a subagent.**
+**Bug Fix Documentation Policy**:
+- **DEFAULT**: Run `/prizmkit-retrospective` with structural sync only (Job 1). Skip knowledge injection.
+- **Full retrospective** (Job 1 + Job 2): Only when the fix causes interface signature changes, dependency additions/removals, observable behavior changes, or reveals new TRAPs.
 
-1. If a new pitfall was discovered (not previously in TRAPS):
+**a.** If a new pitfall was discovered (not previously in TRAPS):
    - Update the affected module's TRAPS section in `.prizm-docs/`
    - Format: `- TRAP: <description> | FIX: <solution> | DATE: YYYY-MM-DD`
 
-2. Run `/prizmkit-retrospective` following the BUG FIX DOCUMENTATION POLICY above:
-   - **DEFAULT**: Structural sync only (Job 1)
-   - **Full retrospective** (Job 1 + Job 2): Only if the fix changes interfaces, dependencies, observable behavior, or reveals new TRAPs
+**b.** Run `/prizmkit-retrospective` following the policy above.
+   Stage doc changes: `git add .prizm-docs/`
 
-3. Run `/prizmkit-committer` with:
-   - Commit message: `fix({{FIX_SCOPE}}): {{BUG_TITLE}}`
+**c.** Stage all changed files explicitly (NEVER use `git add -A` or `git add .`):
+```bash
+git add <specific-files-modified>
+git add .prizm-docs/
+```
+
+**d.** Run `/prizmkit-committer`:
+   - Commit message prefix: `fix({{FIX_SCOPE}}): {{BUG_TITLE}}`
    - Include both fix code and reproduction test
-   - Do NOT push (user will push manually)
+   - Do NOT push
+
+**e.** Final verification:
+```bash
+git status --short
+```
+Working tree MUST be clean. If any files remain, amend the commit.
 
-4. Write the complete fix report to `.prizmkit/bugfix/{{BUG_ID}}/fix-report.md`
+**f.** Write fix report to `.prizmkit/bugfix/{{BUG_ID}}/fix-report.md`:
 
-  The fix-report.md MUST contain these sections:
-  - Bug Resolution Summary (ID, title, status, phases completed, duration)
-  - What Was Fixed (changes made, diff summary, commit message)
-  - Verification Results (reproduction test before/after, regression tests, review findings)
-  - Knowledge Captured (TRAPS updated, prevention recommendation)
-  - Acceptance Criteria Verification (checklist with pass/fail for each criterion)
+The fix-report.md MUST contain:
+- **Bug Resolution Summary**: ID, title, status, phases completed
+- **What Was Fixed**: changes made, diff summary, commit hash
+- **Verification Results**: reproduction test before/after, regression tests, review findings
+- **Knowledge Captured**: TRAPS updated (if any), prevention recommendation
+- **Acceptance Criteria Verification**: checklist with pass/fail for each criterion
 
-- **CP-BF-5**: Commit recorded, fix-report.md written, TRAPS updated (if applicable)
-- **Checkpoint update**: set steps `prizmkit-committer` and `bug-report` to `"completed"` in `{{CHECKPOINT_PATH}}`
+**Checkpoint update**: Set steps `prizmkit-committer` and `bug-report` to `"completed"`.
+
+---
 
 ### Step 3: Report Session Status
 
-**CRITICAL**: Before this session ends, you MUST write the session status file.
+**CRITICAL**: Before exiting, write the session status file.
 
 Write to: `{{SESSION_STATUS_PATH}}`
 
@@ -263,15 +222,16 @@ Write to: `{{SESSION_STATUS_PATH}}`
   "session_id": "{{SESSION_ID}}",
   "bug_id": "{{BUG_ID}}",
   "status": "<success|partial|failed>",
-  "completed_phases": [1, 2, 3, 4, 5],
-  "current_phase": 5,
-  "checkpoint_reached": "CP-BF-5",
+  "completed_phases": [1, 2, 3, 4],
+  "current_phase": 4,
+  "checkpoint_reached": "CP-4",
   "fast_path": false,
   "errors": [],
   "can_resume": false,
   "resume_from_phase": null,
   "artifacts": {
-    "fix_plan_path": ".prizmkit/bugfix/{{BUG_ID}}/fix-plan.md",
+    "spec_path": ".prizmkit/bugfix/{{BUG_ID}}/spec.md",
+    "plan_path": ".prizmkit/bugfix/{{BUG_ID}}/plan.md",
     "fix_report_path": ".prizmkit/bugfix/{{BUG_ID}}/fix-report.md"
   },
   "git_commit": "<commit hash>",
@@ -280,30 +240,23 @@ Write to: `{{SESSION_STATUS_PATH}}`
 }
 ```
 
-**Status values**: `success` (all phases done) | `partial` (can resume) | `failed` (unrecoverable)
-
 ## Critical Paths
 
 | Resource | Path |
 |----------|------|
-| Team Definition (source of truth) | `{{TEAM_CONFIG_PATH}}` |
 | Bug Fix Artifacts Dir | `.prizmkit/bugfix/{{BUG_ID}}/` |
-| Fix Plan | `.prizmkit/bugfix/{{BUG_ID}}/fix-plan.md` |
+| Spec | `.prizmkit/bugfix/{{BUG_ID}}/spec.md` |
+| Plan | `.prizmkit/bugfix/{{BUG_ID}}/plan.md` |
 | Fix Report | `.prizmkit/bugfix/{{BUG_ID}}/fix-report.md` |
-| Dev Agent Def | {{DEV_SUBAGENT_PATH}} |
-| Reviewer Agent Def | {{REVIEWER_SUBAGENT_PATH}} |
 | Session Status Output | {{SESSION_STATUS_PATH}} |
 | Project Root | {{PROJECT_ROOT}} |
 
 ## Reminders
 
-- **MANDATORY**: Use `prizm-dev-team` agents — single-agent execution is FORBIDDEN
-- **Only 2 artifact files per bug**: fix-plan.md + fix-report.md — NEVER more
-- **Simple bugs**: No spec/plan needed — artifacts are `fix-plan.md` + `fix-report.md` only
-- **Complex bugs** (cross-module, data model/API changes): Use `/prizmkit-plan` with `artifact_dir=.prizmkit/bugfix/{{BUG_ID}}/` → `spec.md` + `plan.md` + `fix-report.md`
-- **DEFAULT**: Run `/prizmkit-retrospective` structural sync only (Job 1). Run full retrospective (Job 1 + Job 2) when fix changes interfaces, dependencies, observable behavior, or reveals new TRAPs
-- **Commit with** `fix(<scope>):` prefix, NOT `feat:`
-- **Update TRAPS** in `.prizm-docs/` only if a genuinely new pitfall was discovered
-- Dev agents use TDD approach: reproduction test goes from RED → GREEN
+- Use L1 Skills: `/prizmkit-plan`, `/prizmkit-implement`, `/prizmkit-code-review`, `/prizmkit-committer`, `/prizmkit-retrospective`
+- All skills use `artifact_dir=.prizmkit/bugfix/{{BUG_ID}}/`
+- plan.md first task MUST be reproduction test (RED → GREEN TDD)
+- Commit with `fix(<scope>):` prefix, NOT `feat:`
+- DEFAULT: `/prizmkit-retrospective` structural sync only (Job 1). Full retrospective when fix changes interfaces/dependencies/behavior
 - ALWAYS write session-status.json before exiting
-- Do NOT use `run_in_background=true` when spawning agents
+- Do NOT run `git add`/`git commit` during Phases 1-3 — all committed once in Phase 4

package/bundled/dev-pipeline/templates/feature-list-schema.json

@@ -72,9 +72,10 @@
             "enum": [
               "low",
               "medium",
-              "high"
+              "high",
+              "critical"
             ],
-            "description": "Estimated implementation complexity. Determines pipeline execution tier: low=lite, medium=standard, high=full."
+            "description": "Estimated implementation complexity. Determines pipeline execution tier: low/medium → lite (single agent), high → standard (orchestrator + dev + reviewer), critical → full (full team + critic)."
           },
           "dependencies": {
             "type": "array",
@@ -166,32 +167,16 @@
           },
           "browser_interaction": {
             "type": "object",
-            "description": "Browser verification config for features with UI. Requires playwright-cli. Pipeline uses this to verify UI behavior after implementation.",
+            "description": "Browser verification config for features with UI. Requires playwright-cli. AI auto-detects dev server command, URL, and port from project config at runtime.",
             "properties": {
-              "url": {
-                "type": "string",
-                "description": "URL to open for verification (e.g. http://localhost:3000/login)"
-              },
-              "setup_command": {
-                "type": "string",
-                "description": "Command to start the dev server before verification (e.g. npm run dev)"
-              },
               "verify_steps": {
                 "type": "array",
-                "description": "Verification goals describing WHAT to verify (not HOW). Pipeline AI decides concrete playwright-cli actions at runtime based on actual code and snapshot.",
+                "description": "Verification goals describing WHAT to verify (not HOW). AI decides concrete playwright-cli actions at runtime based on actual code and snapshot. If omitted, AI explores the app and verifies the feature works.",
                 "items": {
                   "type": "string"
                 }
-              },
-              "screenshot": {
-                "type": "boolean",
-                "description": "Capture screenshot after verification steps. Default: true.",
-                "default": true
               }
-            },
-            "required": [
-              "url"
-            ]
+            }
           }
         }
       }

package/bundled/dev-pipeline/templates/refactor-bootstrap-prompt.md

@@ -2,16 +2,11 @@
 
 ## Session Context
 
-- **Pipeline Run ID**: {{RUN_ID}}
-- **Session ID**: {{SESSION_ID}}
 - **Refactor ID**: {{REFACTOR_ID}}
 - **Refactor Title**: {{REFACTOR_TITLE}}
 - **Refactor Type**: {{REFACTOR_TYPE}}
 - **Priority**: {{PRIORITY}}
 - **Complexity**: {{COMPLEXITY}}
-- **Retry Count**: {{RETRY_COUNT}} / {{MAX_RETRIES}}
-- **Previous Session Status**: {{PREV_SESSION_STATUS}}
-- **Resume From Phase**: {{RESUME_PHASE}}
 
 ## Your Mission
 
@@ -64,6 +59,10 @@ You are the **refactor session orchestrator**. Execute Refactor {{REFACTOR_ID}}:
 
 {{GLOBAL_CONTEXT}}
 
+### Project Conventions
+
+> Read {{PLATFORM_CONVENTIONS}} for project-level coding standards, architecture decisions, and development rules.
+
 ## Refactor Artifacts Directory
 
 **ALWAYS** use per-refactor subdirectory `.prizmkit/refactor/{{REFACTOR_ID}}/`:
@@ -136,11 +135,12 @@ Resolve any `[NEEDS CLARIFICATION]` markers using the refactor description — d
   1. Read `.prizmkit/refactor/{{REFACTOR_ID}}/spec.md` and `.prizmkit/refactor/{{REFACTOR_ID}}/plan.md`
   2. Read `.prizm-docs/` for affected modules (TRAPS, RULES, PATTERNS)
   3. Before making any changes, run the existing test suite to establish a green baseline
-  4. Execute each task from plan.md in order:
-     - Apply the change
-     - Run the test suite after EVERY task — all tests MUST pass
+  4. Run `/prizmkit-implement` with `artifact_dir=.prizmkit/refactor/{{REFACTOR_ID}}/` — this handles the full implementation cycle:
+     - Reads plan.md Tasks section
+     - Implements task-by-task, marking each `[x]` immediately
+     - Runs tests after EVERY task — all tests MUST pass (behavior preservation)
      - If tests fail: revert the task, analyze why, try alternative approach
-     - Mark task as [x] in plan.md after tests pass
+     - Writes '## Implementation Log' to context-snapshot.md (or equivalent)
   5. Do NOT change behavior — only improve structure
   6. If the refactor involves multiple files: run `/compact` after completing half the tasks to free context budget. If `/compact` is unavailable, continue without it.
   7. After all tasks complete, run the full test suite one final time

package/bundled/dev-pipeline/templates/sections/context-budget-rules.md

@@ -8,6 +8,6 @@ You are running in **headless non-interactive mode** with a FINITE context windo
 2. **Never re-read your own writes** — After you create/modify a file, do NOT read it back to verify. Trust your write was correct.
 3. **Stay focused** — Do NOT explore code unrelated to this feature. No curiosity-driven reads.
 4. **One task at a time** — Complete and test one task before starting the next.
-5. **Minimize tool output** — When running commands, use `| head -20` or `| tail -20` to limit output. Never dump entire test suites or logs.
+5. **Minimize tool output** — Never load full command output into context. First capture to a temp file (`cmd 2>&1 | tee /tmp/out.txt | tail -20`), then scan the head/tail to identify relevant fields, and use targeted filtering (`grep`, `sed`, `awk`) to extract only the information needed for the current task. Only read the filtered result — never the raw full output.
 6. **No intermediate commits** — Do NOT run `git add`/`git commit` during implementation phases. All changes are committed once at the end via `/prizmkit-committer`.
 7. **Capture test output once** — When running test suites, always use `$TEST_CMD 2>&1 | tee /tmp/test-out.txt | tail -20`. Then grep `/tmp/test-out.txt` for details. Never re-run the suite just to apply a different filter.

package/bundled/dev-pipeline/templates/sections/feature-context.md

@@ -22,4 +22,8 @@
 ### App Global Context
 
 {{GLOBAL_CONTEXT}}
+
+### Project Conventions
+
+> Read {{PLATFORM_CONVENTIONS}} for project-level coding standards, architecture decisions, and development rules. Follow these conventions throughout implementation.
 </feature-context>

package/bundled/dev-pipeline/templates/sections/phase-browser-verification.md

@@ -2,32 +2,49 @@
 
 You MUST execute this phase. Do NOT skip it. Do NOT mark it as completed without actually running playwright-cli.
 
-**Startup**:
-1. Check if port is already in use: `lsof -ti:3001 | xargs kill -9 2>/dev/null || true`
-2. Start dev server: `{{BROWSER_SETUP_COMMAND}}`
-3. Wait for server to be ready: poll `{{BROWSER_URL}}` with `curl -s -o /dev/null -w "%{http_code}"` until it returns 200 or 302 (max 30 seconds, 2s interval)
-4. If the page requires authentication, use playwright-cli to register a test user and log in first
-
-**Verification**:
-5. Use `playwright-cli snapshot` on `{{BROWSER_URL}}` to discover actual element refs, then verify these goals:
-   {{BROWSER_VERIFY_STEPS}}
-   Decide the concrete playwright-cli actions (click, fill, assert, etc.) yourself based on the snapshot output and your knowledge of the implemented code. The goals above describe WHAT to verify — you determine HOW.
-6. Take a final screenshot for evidence
-
-**Cleanup (REQUIRED — you started it, you stop it)**:
-7. Stop the dev server process you started in step 2 (kill the process)
-8. Verify port is released: `lsof -ti:3001 | xargs kill -9 2>/dev/null || true`
-
-**Reporting**:
-9. Append results to `context-snapshot.md`:
+**Step 1 — Start Dev Server**:
+
+You know this project's tech stack. Detect and start the dev server yourself:
+
+1. Identify the dev server start command from project config (`package.json` scripts, `Makefile`, `docker-compose.yml`, etc.)
+2. Choose an available port — check what the project defaults to, or pick one that is free:
+   ```bash
+   lsof -ti:<port> 2>/dev/null && echo "PORT_IN_USE" || echo "PORT_FREE"
    ```
-   ## Browser Verification
-   URL: {{BROWSER_URL}}
-   Steps executed: [list]
-   Screenshot: [path]
-   Result: PASS / FAIL (reason)
-   Server cleanup: confirmed
+3. Start the dev server in background, capture PID:
+   ```bash
+   <start-command> &
+   DEV_SERVER_PID=$!
    ```
+4. Wait for server to be ready: poll the target URL with `curl -s -o /dev/null -w "%{http_code}"` until it returns 200 or 302 (max 30 seconds, 2s interval)
+5. If the page requires authentication, use playwright-cli to register a test user and log in first
+
+**Step 2 — Verification**:
+
+Use `playwright-cli snapshot` on the running app to discover actual element refs, then verify these goals:
+{{BROWSER_VERIFY_STEPS}}
+
+Decide the concrete playwright-cli actions (click, fill, assert, etc.) yourself based on the snapshot output and your knowledge of the implemented code. The goals above describe WHAT to verify — you determine HOW.
+
+Take a final screenshot for evidence.
+
+**Step 3 — Cleanup (REQUIRED — you started it, you stop it)**:
+
+1. Kill the dev server process: `kill $DEV_SERVER_PID 2>/dev/null || true`
+2. Verify port is released: `lsof -ti:<port> | xargs kill -9 2>/dev/null || true`
+
+**Step 4 — Reporting**:
+
+Append results to `context-snapshot.md`:
+```
+## Browser Verification
+URL: <actual URL used>
+Dev Server Command: <actual command used>
+Steps executed: [list]
+Screenshot: [path]
+Result: PASS / FAIL (reason)
+Server cleanup: confirmed
+```
 
 If verification fails, log the failure details but continue to commit. Failures do NOT block the commit, but you MUST attempt verification and MUST clean up the dev server.