prizmkit 1.0.0 → 1.0.2

package/bundled/agents/prizm-dev-team-reviewer.md

@@ -0,0 +1,119 @@
+---
+name: prizm-dev-team-reviewer
+description: PrizmKit-integrated quality reviewer. Uses prizmkit.analyze for cross-document consistency, prizmkit.code-review for spec compliance and code quality, and writes integration tests. Use when performing analysis, testing, or code review.
+tools: Read, Write, Edit, Bash, Glob, Grep, TaskCreate, TaskGet, TaskUpdate, TaskList, SendMessage
+model: inherit
+skills: prizmkit-code-review, prizmkit-analyze, prizmkit-prizm-docs
+---
+
+你是 **Reviewer Agent**，PrizmKit-integrated Multi-Agent 软件开发协作团队的质量审查员。
+
+### 核心身份
+
+你是团队的"质检员 + 校对员"——不生产产品但确保质量，负责两个阶段的工作：
+1. **交叉校验（Phase 4）**: 在实现前用 `prizmkit.analyze` 检查 spec/plan/tasks 的一致性
+2. **评审（Phase 6）**: 在实现后用 `prizmkit.code-review` 检查代码质量，编写和执行集成测试
+
+### 项目上下文
+
+项目文档在 `.prizm-docs/`。审查前先读 `root.prizm` 了解项目规则（RULES）、模式（PATTERNS）和已知陷阱（TRAPS），需要时读取模块级文档。
+
+### 制品路径
+
+| 路径 | 用途 |
+|------|------|
+| `.prizm-docs/` | 项目知识层 — 规则、模式、已知陷阱 |
+| `.prizmkit/specs/###-feature-name/` | 功能制品 — spec.md / plan.md / tasks.md |
+
+### 必须做 (MUST)
+
+1. Phase 4 时运行 `prizmkit.analyze` 做交叉一致性校验
+2. Phase 6 时运行 `prizmkit.code-review` 做规格合规和代码质量审查
+3. Phase 6 时编写和执行集成测试，验证模块间交互
+4. 验证实际实现是否符合 plan.md 中的接口设计
+5. 验证跨模块数据流的完整性和正确性
+6. 测试边界条件和异常路径
+7. 检查代码是否符合 `.prizm-docs/` RULES 和 PATTERNS
+8. 审查是**只读操作**（Phase 4 和 Phase 6 的审查部分不修改代码文件）
+9. 集成测试用例必须覆盖 spec.md 定义的所有用户故事
+
+### 绝不做 (NEVER)
+
+- 不编写实现代码（Dev 的职责）
+- 不分解任务（PM 的职责）
+- 不进行任务调度（Coordinator 的职责）
+
+### 行为规则
+
+```
+REV-01: Phase 4 使用 prizmkit.analyze 做交叉校验
+REV-02: Phase 6 使用 prizmkit.code-review 做代码审查
+REV-03: 每个发现必须引用具体的文件路径和行号
+REV-04: CRITICAL 级别发现必须包含具体的修复建议
+REV-05: 最多 30 个发现（保持可操作性）
+REV-06: Spec compliance 失败始终为 HIGH 或 CRITICAL
+REV-07: 安全发现始终为 HIGH 或 CRITICAL
+REV-08: 集成测试必须覆盖 spec.md 所有用户故事
+REV-09: 审查代码是否符合 .prizm-docs/ PATTERNS 和 RULES
+```
+
+### Phase 4 工作流程：交叉校验
+
+**前置条件**: PM 已完成 spec.md / plan.md / tasks.md
+
+1. 运行 `prizmkit.analyze`（只读）
+   - 输入: spec.md, plan.md, tasks.md
+   - 6 个检测通道: 重复检测、歧义检测、不完整检测、Prizm 规则对齐、覆盖缺口、不一致性
+   - 输出: 一致性分析报告（仅对话输出）
+2. 如发现 CRITICAL 问题，报告给 Coordinator 退回 PM 修复
+3. 发送 COMPLETION_SIGNAL（含分析结果）
+
+### Phase 6 工作流程：评审
+
+**前置条件**: Dev 已完成实现，所有任务标记 `[x]`
+
+1. 读取 `.prizm-docs/root.prizm`，重点关注 RULES 和 PATTERNS
+2. 运行 `prizmkit.code-review`（只读）
+   - 6 个审查维度: 规格符合度、计划遵循度、代码质量、安全性、一致性、测试覆盖
+   - 判定: PASS | PASS WITH WARNINGS | NEEDS FIXES
+3. 编写和执行集成测试:
+   - 接口合规性（请求格式、响应格式）
+   - 跨模块数据流完整性
+   - 用户故事验收标准（来自 spec.md）
+   - 边界条件和异常路径
+4. 生成统一评审报告
+5. 发送 COMPLETION_SIGNAL（含判定结果）
+
+### 判定标准
+
+| 判定 | 条件 | 后续动作 |
+|------|------|---------|
+| **PASS** | 无 CRITICAL 或 HIGH 发现 | 进入下一阶段 |
+| **PASS_WITH_WARNINGS** | 无 CRITICAL，有 HIGH 发现 | 记录待改进项，可进入下一阶段 |
+| **NEEDS_FIXES** | 存在 CRITICAL 发现 | 退回 Dev 修复后重新评审 |
+
+### 严重级别
+
+| 级别 | 定义 | 示例 |
+|------|------|------|
+| CRITICAL | 安全风险或严重架构问题 | SQL 注入、硬编码密钥 |
+| HIGH | 影响可维护性的显著问题 | 规格不符、大量重复代码 |
+| MEDIUM | 代码质量改进点 | 命名不统一、缺少注释 |
+| LOW | 风格建议 | 格式微调、可选优化 |
+
+### 异常处理
+
+| 场景 | 策略 |
+|------|------|
+| analyze 发现 CRITICAL | 报告 Coordinator → 退回 PM 修复 |
+| code-review 发现 CRITICAL | 报告 Coordinator → 退回 Dev 修复 |
+| 集成测试失败 | 分类严重级别 → ISSUE_REPORT → Coordinator 派发给 Dev |
+| 审查发现超过 30 个 | 只保留最严重的 30 个 |
+| Prizm RULES 违规 | 自动标记为 CRITICAL |
+
+### 通信规则
+
+允许 Agent 之间直接通信，但关键消息和结论必须通知 Coordinator。
+- 发送 COMPLETION_SIGNAL（含判定结果）标志完成
+- 发送 ISSUE_REPORT 报告 CRITICAL 发现
+- 接收 TASK_ASSIGNMENT 获取分配的工作

package/bundled/dev-pipeline/README.md

@@ -0,0 +1,482 @@
+# dev-pipeline
+
+Autonomous development pipeline that drives the `prizm-dev-team` multi-agent team through iterative CodeBuddy CLI sessions, implementing a complete app feature-by-feature from a `feature-list.json` specification.
+
+## Prerequisites
+
+- Python 3.6+
+- [jq](https://jqlang.github.io/jq/) (`brew install jq`)
+- AI CLI in PATH: CodeBuddy (`cbc`) or Claude Code (`claude`)
+- `feature-list.json` generated by the `app-planner` skill
+
+## Quick Start
+
+```bash
+# 1. Generate feature list (via app-planner skill in an AI CLI session)
+#    Output: feature-list.json in project root
+
+# 2. Initialize pipeline state
+python3 dev-pipeline/scripts/init-pipeline.py \
+  --feature-list feature-list.json \
+  --state-dir dev-pipeline/state
+
+# 3. Run the pipeline (foreground, Ctrl+C to pause, re-run to resume)
+./dev-pipeline/run.sh run feature-list.json
+
+# 4. Check progress at any time (from another terminal)
+./dev-pipeline/run.sh status feature-list.json
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `./run.sh run [feature-list.json]` | Start or resume the pipeline. Processes features sequentially by dependency order. |
+| `./run.sh status [feature-list.json]` | Display current pipeline status: completed, pending, blocked, failed features. |
+| `./run.sh reset` | Clear all runtime state in `state/`. Pipeline starts fresh on next `run`. |
+| `./run.sh help` | Show usage help. |
+| `./retry-feature.sh <feature-id> [feature-list.json]` | Retry a single failed feature. Runs one session then exits. |
+| `./reset-feature.sh <feature-id> [--clean] [--run]` | Reset a feature to pending. `--clean` deletes artifacts, `--run` auto-retries. |
+
+If `feature-list.json` path is omitted, defaults to `.dev-pipeline/feature-list.json` (run.sh) or `feature-list.json` (retry-feature.sh).
+
+### Retrying a Failed Feature
+
+When a feature fails after max retries, use `retry-feature.sh` to run a single retry session:
+
+```bash
+# Retry F-007
+./dev-pipeline/retry-feature.sh F-007
+
+# With custom feature list
+./dev-pipeline/retry-feature.sh F-007 feature-list.json
+
+# With timeout (default: no limit)
+SESSION_TIMEOUT=7200 ./dev-pipeline/retry-feature.sh F-007
+```
+
+The script will:
+1. Reset the feature status to allow retry
+2. Generate a fresh bootstrap prompt
+3. Run exactly one AI CLI session with heartbeat monitoring
+4. Update feature status based on the result
+5. Exit (does not continue to other features)
+
+### Resetting a Failed Feature
+
+When a feature is stuck (e.g. retry count exceeded, bad artifacts), use `reset-feature.sh` to wipe its state:
+
+```bash
+# Reset status only (retry_count → 0, status → pending)
+./dev-pipeline/reset-feature.sh F-007
+
+# Reset + delete all session history and .prizmkit artifacts
+./dev-pipeline/reset-feature.sh F-007 --clean
+
+# Reset + clean + immediately retry
+./dev-pipeline/reset-feature.sh F-007 --clean --run
+
+# With custom feature list
+./dev-pipeline/reset-feature.sh F-007 --clean my-features.json
+```
+
+What gets cleaned with `--clean`:
+- `state/features/F-XXX/sessions/` — all session logs and prompts
+- `.prizmkit/specs/{feature-slug}/` — spec.md, plan.md, tasks.md, contracts/
+
+What is always reset (with or without `--clean`):
+- `status.json` — status → pending, retry_count → 0
+- `feature-list.json` — feature status → pending
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MAX_RETRIES` | `3` | Maximum retry attempts per feature before marking as failed. |
+| `SESSION_TIMEOUT` | `0` (no limit) | Timeout in seconds per AI CLI session. 0 = no timeout. |
+| `AI_CLI` | auto-detect | AI CLI command name. Auto-detects `cbc` or `claude`. Set to override. |
+| `HEARTBEAT_INTERVAL` | `30` | Seconds between heartbeat log output while a session is running. |
+| `HEARTBEAT_STALE_THRESHOLD` | `600` | Seconds before a session is considered stale/stuck. |
+
+Example with custom config:
+
+```bash
+MAX_RETRIES=5 ./dev-pipeline/run.sh run feature-list.json
+
+# With 2-hour timeout per session
+SESSION_TIMEOUT=7200 ./dev-pipeline/run.sh run feature-list.json
+```
+
+## How It Works
+
+### Execution Flow
+
+```
+run.sh main loop
+  │
+  ├─ detect-stuck.py          # Check for stale/stuck sessions
+  ├─ update-feature-status.py # get_next: find next runnable feature (pending + deps met)
+  │
+  ├─ generate-bootstrap-prompt.py  # Build prompt with feature details + context
+  │
+  ├─ AI CLI session            # cbc --print -y < prompt (CodeBuddy)
+  │   │                        # claude --print -p "$(cat prompt)" --yes (Claude Code)
+  │   └─ prizm-dev-team       # Multi-agent team implements the feature
+  │       ├─ Coordinator      # Orchestrates the 10-phase pipeline
+  │       ├─ PM               # Phase 1-4: specify → plan → tasks → analyze
+  │       ├─ Dev x N           # Phase 6: implement with TDD
+  │       ├─ QA               # Phase 7: integration tests + code review
+  │       ├─ Review           # Phase 7: code consistency audit
+  │       └─ Coordinator      # Phase 9: summarize → commit → retrospective
+  │
+  ├─ check-session-status.py  # Parse session outcome
+  ├─ update-feature-status.py # Update feature state (completed/failed/retry)
+  │
+  └─ loop → next feature
+```
+
+### 10-Phase Pipeline (per feature session)
+
+Each AI CLI session drives the prizm-dev-team through these phases. **All phases are mandatory** — the bootstrap prompt enforces sequential execution.
+
+> **Note**: The Coordinator Agent definition describes a simplified **8-phase** view (Phase 0-7) where Phases 1-3 and Phase 5 are consolidated. The bootstrap prompt adapts these phases based on complexity mode (lite/standard/full). The 10-phase breakdown below is the most granular view for pipeline monitoring.
+
+| Phase | Name | Agent | PrizmKit Skills | Artifacts |
+|-------|------|-------|----------------|-----------|
+| 0 | Init | Coordinator | `prizmkit-init` | `.prizm-docs/root.prizm`, `.prizmkit/config.json` |
+| 1 | Specify | PM | `prizmkit-specify`, `prizmkit-clarify` | `.prizmkit/specs/spec.md`, `.dev-team/specs/requirements.md` |
+| 2 | Plan | PM | `prizmkit-plan` | `.prizmkit/plans/plan.md`, `.dev-team/contracts/` |
+| 3 | Tasks | PM | `prizmkit-tasks` | `.prizmkit/tasks/tasks.md`, `.dev-team/tasks/` |
+| 4 | Analyze | PM | `prizmkit-analyze` | Analysis report (no CRITICAL issues) |
+| 5 | Schedule | Coordinator | — | TaskList entries assigned |
+| 6 | Implement | Dev x N | `prizmkit-implement` | Code + tests, tasks.md marked `[x]` |
+| 7 | Review | QA + Review | `prizmkit-code-review` | Integration tests, review report |
+| 8 | Fix Loop | Dev | — | Max 3 rounds of fixes |
+| 9 | Summarize & Commit | Coordinator | `prizmkit-summarize`, `prizmkit-committer`, `prizmkit-retrospective` | REGISTRY.md, git commit, .prizm-docs/ updated |
+
+### Feature Dependency Resolution
+
+Features are executed in dependency order. The pipeline uses a DAG (Directed Acyclic Graph) to determine which features are runnable:
+
+- A feature is **runnable** if status is `pending` and all dependencies are `completed`.
+- A feature is **blocked** if any dependency is not yet `completed`.
+- Features with no remaining runnable features and incomplete blocked features enter a 60s retry wait.
+
+### Session Lifecycle
+
+1. **Bootstrap prompt** is generated from the feature spec, tech stack context, and acceptance criteria.
+2. The AI CLI is spawned as a background process:
+   - **CodeBuddy**: `cbc --print -y < prompt` (prompt via stdin)
+   - **Claude Code**: `claude --print -p "$(cat prompt)" --yes` (prompt via `-p` argument)
+3. A **timeout watchdog** runs in parallel if `SESSION_TIMEOUT > 0`; kills the session if it exceeds the limit.
+4. A **heartbeat monitor** prints progress every `HEARTBEAT_INTERVAL` seconds (default 30s).
+5. On completion, the script checks for `session-status.json` to determine success/failure.
+6. Feature status is updated. On failure, retry count increments. After `MAX_RETRIES`, the feature is marked failed.
+
+### Heartbeat Output
+
+While an AI CLI session is running, the pipeline outputs periodic heartbeat lines:
+
+```
+  ▶ [HEARTBEAT] 1m30s elapsed | log: 245KB (+12480B) | Creating team prizm-dev-team-F-001...
+  ▶ [HEARTBEAT] 2m0s elapsed | log: 389KB (+147456B) | Generating spec.md for feature...
+  ⏸ [HEARTBEAT] 2m30s elapsed | log: 389KB (+0B) | (waiting for AI response)
+```
+
+- `▶` (green): log is growing — session is actively producing output
+- `⏸` (yellow): log unchanged since last check — session may be waiting or stuck
+- Shows elapsed time, log file size, growth since last heartbeat, and last log line
+
+### Monitoring Session Logs
+
+Each AI CLI session 的完整输出（tool 调用、文件读写、代码生成、AI 思考过程）都记录在 session log 中。开一个新终端实时查看：
+
+```bash
+# 实时跟踪当前正在执行的 session 日志
+tail -f dev-pipeline/state/features/F-*/sessions/*/logs/session.log
+
+# 如果知道具体 feature ID，可以更精确
+tail -f dev-pipeline/state/features/F-003/sessions/*/logs/session.log
+```
+
+通过日志可以判断：
+- session 当前在执行哪个 phase
+- 是否在读正确的文件
+- 是否出现幻觉或方向错误
+- 具体卡在什么步骤
+
+session 结束后查看完整日志：
+
+```bash
+cat dev-pipeline/state/features/F-003/sessions/F-003-*/logs/session.log | less
+```
+
+### Pause & Resume
+
+- **Ctrl+C** during execution triggers graceful shutdown — current state is saved.
+- **Re-running** `./run.sh run feature-list.json` resumes from where it left off. Completed features are skipped.
+
+### Manual Intervention
+
+If a feature fails after max retries, the pipeline blocks. To resolve:
+
+```bash
+# Check what failed
+./dev-pipeline/run.sh status feature-list.json
+
+# Review session logs
+cat dev-pipeline/state/features/F-XXX/sessions/*/logs/session.log
+
+# Option A: Fix manually and mark as complete
+python3 dev-pipeline/scripts/update-feature-status.py \
+  --feature-list feature-list.json \
+  --state-dir dev-pipeline/state \
+  --feature-id F-XXX --action complete
+
+# Option B: Reset the feature for retry
+python3 dev-pipeline/scripts/update-feature-status.py \
+  --feature-list feature-list.json \
+  --state-dir dev-pipeline/state \
+  --feature-id F-XXX --action reset
+
+# Resume pipeline
+./dev-pipeline/run.sh run feature-list.json
+```
+
+## Directory Structure
+
+```
+dev-pipeline/
+├── run.sh                        # Main entry point — full pipeline loop
+├── retry-feature.sh              # Retry a single failed feature
+├── reset-feature.sh              # Reset/clean a feature for fresh re-execution
+├── README.md                     # This file
+├── .gitignore                    # Ignores state/ and __pycache__/
+├── scripts/
+│   ├── init-pipeline.py          # Initialize state/ from feature-list.json
+│   ├── init-dev-team.py          # Initialize .dev-team/ and .prizmkit/ directories
+│   ├── generate-bootstrap-prompt.py  # Build per-feature prompt for AI CLI session
+│   ├── check-session-status.py   # Parse session-status.json for outcome
+│   ├── update-feature-status.py  # Update feature state + get_next + status display
+│   └── detect-stuck.py           # Detect stuck/stale sessions by heartbeat
+├── templates/
+│   ├── bootstrap-prompt.md       # Prompt template for AI CLI sessions
+│   ├── feature-list-schema.json  # JSON schema for feature-list.json
+│   └── session-status-schema.json  # JSON schema for session output
+├── assets/
+│   ├── feature-list-example.json # Example feature list (TaskFlow app)
+│   └── prizm-dev-team-integration.md  # How pipeline integrates with prizm-dev-team
+└── state/                        # Runtime state (gitignored, auto-generated)
+    ├── pipeline.json             # Pipeline run metadata
+    ├── current-session.json      # Currently executing session
+    └── features/
+        └── F-XXX/
+            ├── status.json       # Feature status, retry count, session history
+            └── sessions/
+                └── F-XXX-YYYYMMDDHHMMSS/
+                    ├── bootstrap-prompt.md  # Generated prompt for this session
+                    └── logs/
+│                    └── session.log      # Full AI CLI session output
+```
+
+### PrizmKit Artifact Structure (per-feature)
+
+Each feature generates artifacts in a dedicated subdirectory under `.prizmkit/specs/`:
+
+```
+.prizmkit/
+├── config.json                          # PrizmKit configuration
+└── specs/
+    ├── REGISTRY.md                      # Feature registry (Phase 9 appends here)
+    ├── 001-project-infrastructure-setup/
+    │   ├── spec.md                      # Phase 1: Feature specification
+    │   ├── checklists/
+    │   │   └── requirements.md          # Phase 1: Spec quality checklist
+    │   ├── plan.md                      # Phase 2: Implementation plan
+    │   ├── data-model.md               # Phase 2: Data model (if applicable)
+    │   ├── contracts/                   # Phase 2: API contracts (if applicable)
+    │   └── tasks.md                     # Phase 3: Task breakdown
+    ├── 002-core-encryption-vault/
+    │   └── ...
+    └── ...
+```
+
+## macOS Compatibility Notes
+
+The original `run.sh` used GNU `timeout` which is not available on macOS by default. The current implementation uses a background process + watchdog pattern instead, which works on both macOS and Linux without additional dependencies.
+
+Key adaptations:
+- The AI CLI is run as a background process with `&`
+- A separate watchdog subshell handles timeout via `sleep + kill`
+- A heartbeat monitor subshell prints periodic progress to the terminal
+- SIGTERM (exit code 143) is mapped to exit code 124 (GNU timeout convention)
+- All cleanup commands use `|| true` to prevent `set -e` from causing silent exits
+
+## Troubleshooting
+
+### Pipeline stops after completing one feature
+
+Check if `set -e` is causing a silent exit. All python script invocations in the main loop should have `|| true` guards. Review `run.sh` for any unguarded commands that might return non-zero.
+
+### Session log is empty
+
+The AI CLI session didn't produce any output. Verify:
+- Your CLI is in PATH and functional:
+  - CodeBuddy: `echo "test" | cbc --print -y`
+  - Claude Code: `claude --print -p "test" --yes`
+- The bootstrap prompt file was generated: check `state/features/F-XXX/sessions/*/bootstrap-prompt.md`
+
+### "PIPELINE_BLOCKED" message loops
+
+All remaining features have unmet dependencies. Check `status` to find which features failed:
+
+```bash
+./dev-pipeline/run.sh status feature-list.json
+```
+
+Then manually complete or reset the blocking feature.
+
+### Feature marked as "crashed"
+
+The AI CLI session exited without producing a `session-status.json`. This typically means the session crashed or the agent didn't write a completion status. The pipeline will retry up to `MAX_RETRIES` times.
+
+### .prizmkit/specs/ is empty after feature completion
+
+The session skipped the PrizmKit artifact generation phases (spec.md, plan.md, tasks.md). This can happen if:
+
+1. **Agent definitions not found**: Check that agent definition files exist
+   - CodeBuddy: `.codebuddy/agents/prizm-dev-team-*.md`
+   - Claude Code: `.claude/agents/prizm-dev-team-*.md`
+2. **Team config missing**: Check that team configuration exists
+   - CodeBuddy: `~/.codebuddy/teams/prizm-dev-team/config.json`
+   - Claude Code: `.claude/team-info.json`
+3. **Session took shortcuts**: The AI CLI session implemented the feature directly without following the 10-phase pipeline
+
+To fix, ensure the agent definitions and team configs are properly installed per the Prizm-Kit-Construct-Guide.md.
+
+## Agent and Team Configuration
+
+The pipeline expects:
+
+**CodeBuddy (CBC):**
+
+| Resource | Location | Description |
+|----------|----------|-------------|
+| Agent Definitions | `.codebuddy/agents/prizm-dev-team-*.md` | 4 agent types: coordinator, pm, dev, reviewer |
+| Team Config | `~/.codebuddy/teams/prizm-dev-team/config.json` | Team runtime configuration |
+| Team Inboxes | `~/.codebuddy/teams/prizm-dev-team/inboxes/` | Agent message inboxes |
+
+**Claude Code (CC):**
+
+| Resource | Location | Description |
+|----------|----------|-------------|
+| Agent Definitions | `.claude/agents/prizm-dev-team-*.md` | 4 agent types: coordinator, pm, dev, reviewer |
+| Team Config | `.claude/team-info.json` | Team runtime configuration (project-level) |
+
+The `generate-bootstrap-prompt.py` script resolves these paths automatically. If paths are incorrect, check the `build_replacements()` function in that script.
+
+---
+
+## Bug Fix Pipeline (Outer Automation)
+
+The bug fix pipeline provides the same autonomous outer-loop automation as the feature pipeline, but tailored for bug fixes from a `bug-fix-list.json`.
+
+### Quick Start
+
+```bash
+# 1. Generate bug fix list (via bug-planner skill in an AI CLI session)
+#    Output: bug-fix-list.json in project root
+
+# 2. Run the bugfix pipeline (foreground)
+./dev-pipeline/run-bugfix.sh run bug-fix-list.json
+
+# 3. Or run as a background daemon
+./dev-pipeline/launch-bugfix-daemon.sh start bug-fix-list.json
+
+# 4. Check progress
+./dev-pipeline/run-bugfix.sh status bug-fix-list.json
+```
+
+### Bug Fix Commands
+
+| Command | Description |
+|---------|-------------|
+| `./run-bugfix.sh run [bug-fix-list.json]` | Run all bugs by severity/priority order |
+| `./run-bugfix.sh run <bug-id> [options]` | Run a single bug fix |
+| `./run-bugfix.sh status [bug-fix-list.json]` | Display bug fix pipeline status |
+| `./run-bugfix.sh reset` | Clear all bugfix runtime state |
+| `./retry-bug.sh <bug-id> [bug-fix-list.json]` | Retry a single failed bug fix |
+| `./launch-bugfix-daemon.sh start [bug-fix-list.json]` | Start bugfix pipeline in background |
+| `./launch-bugfix-daemon.sh stop` | Gracefully stop the bugfix daemon |
+| `./launch-bugfix-daemon.sh status` | Check daemon status with progress JSON |
+| `./launch-bugfix-daemon.sh logs --follow` | Live tail daemon logs |
+
+### Bug Fix Execution Flow
+
+```
+run-bugfix.sh main loop
+  │
+  ├─ update-bug-status.py        # get_next: find next bug (by severity → priority)
+  │
+  ├─ generate-bugfix-prompt.py   # Build prompt from bugfix-bootstrap-prompt.md template
+  │
+  ├─ AI CLI session               # cbc --print -y < prompt (CBC)
+  │   │                            # claude --print -p "$(cat prompt)" --yes (CC)
+  │   └─ prizmkit-bug-fix-workflow  # 5-phase pipeline
+  │       ├─ Phase 1: Triage      (Dev agent: classify, assess impact, write fix-plan.md)
+  │       ├─ Phase 2: Reproduce   (Dev agent: create failing reproduction test)
+  │       ├─ Phase 3: Fix         (Dev agent: TDD — make reproduction test pass)
+  │       ├─ Phase 4: Verify      (Reviewer agent: code review + regression tests)
+  │       └─ Phase 5: Commit      (Dev agent: commit, update TRAPS, write fix-report.md)
+  │
+  ├─ check-session-status.py     # Parse session outcome
+  ├─ update-bug-status.py        # Update bug state (completed/failed/retry)
+  │
+  └─ loop → next bug
+```
+
+### Bug Priority Resolution
+
+Bugs are processed in this order:
+1. **Severity** first: `critical` > `high` > `medium` > `low`
+2. **Priority field** second: lower number = higher priority
+3. **In-progress** bugs (interrupted sessions) are resumed before pending bugs
+
+### Bug Fix Artifacts
+
+Each bug fix produces exactly 2 artifacts:
+
+```
+.prizmkit/bugfix/B-001/
+├── fix-plan.md       ← Phase 1 output
+└── fix-report.md     ← Phase 5 output
+```
+
+### Bug Fix State Directory
+
+```
+dev-pipeline/bugfix-state/        # Runtime state (gitignored)
+├── pipeline.json                 # Pipeline run metadata
+├── current-session.json          # Currently executing session
+└── bugs/
+    └── B-XXX/
+        ├── status.json           # Bug status, retry count, session history
+        └── sessions/
+            └── B-XXX-YYYYMMDDHHMMSS/
+                ├── bootstrap-prompt.md  # Generated prompt for this session
+                └── logs/
+                    └── session.log      # Full session output
+```
+
+### Differences from Feature Pipeline
+
+| Aspect | Feature Pipeline | Bug Fix Pipeline |
+|--------|-----------------|-----------------|
+| Input file | `feature-list.json` | `bug-fix-list.json` |
+| ID format | `F-NNN` | `B-NNN` |
+| State dir | `state/` | `bugfix-state/` |
+| Ordering | Dependencies DAG → priority | Severity → priority (no dependencies) |
+| Phases | 10-phase (specify → plan → tasks → implement → review) | 5-phase (triage → reproduce → fix → verify → commit) |
+| Agents | Coordinator + PM + Dev + Reviewer | Dev + Reviewer only |
+| Artifacts | spec.md, plan.md, tasks.md, REGISTRY.md | fix-plan.md, fix-report.md only |
+| Commit prefix | `feat(<scope>):` | `fix(<scope>):` |