claude-code-pilot 3.0.0 → 3.1.0

package/src/pilot/workflows/review.md

@@ -0,0 +1,244 @@
+<purpose>
+Cross-AI peer review — invoke external AI CLIs to independently review phase plans.
+Each CLI gets the same prompt (PROJECT.md context, phase plans, requirements) and
+produces structured feedback. Results are combined into REVIEWS.md for the planner
+to incorporate via --reviews flag.
+
+This implements adversarial review: different AI models catch different blind spots.
+A plan that survives review from 2-3 independent AI systems is more robust.
+</purpose>
+
+<process>
+
+<step name="detect_clis">
+Check which AI CLIs are available on the system:
+
+```bash
+# Check each CLI
+command -v gemini >/dev/null 2>&1 && echo "gemini:available" || echo "gemini:missing"
+command -v claude >/dev/null 2>&1 && echo "claude:available" || echo "claude:missing"
+command -v codex >/dev/null 2>&1 && echo "codex:available" || echo "codex:missing"
+command -v coderabbit >/dev/null 2>&1 && echo "coderabbit:available" || echo "coderabbit:missing"
+```
+
+Parse flags from `$ARGUMENTS`:
+- `--gemini` → include Gemini
+- `--claude` → include Claude
+- `--codex` → include Codex
+- `--coderabbit` → include CodeRabbit
+- `--all` → include all available
+- No flags → include all available
+
+If no CLIs are available:
+```
+No external AI CLIs found. Install at least one:
+- gemini: https://github.com/google-gemini/gemini-cli
+- codex: https://github.com/openai/codex
+- claude: https://github.com/anthropics/claude-code
+
+Then run /ccp:review again.
+```
+Exit.
+
+If only one CLI is the current runtime (e.g. running inside Claude), skip it for the review
+to ensure independence. At least one DIFFERENT CLI must be available.
+</step>
+
+<step name="gather_context">
+Collect phase artifacts for the review prompt:
+
+```bash
+INIT=$(node "$HOME/.claude/pilot/bin/ccp-tools.cjs" init phase-op "${PHASE_ARG}")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Read from init: `phase_dir`, `phase_number`, `padded_phase`.
+
+Then read:
+1. `.planning/PROJECT.md` (first 80 lines — project context)
+2. Phase section from `.planning/ROADMAP.md`
+3. All `*-PLAN.md` files in the phase directory
+4. `*-CONTEXT.md` if present (user decisions)
+5. `*-RESEARCH.md` if present (domain research)
+6. `.planning/REQUIREMENTS.md` (requirements this phase addresses)
+</step>
+
+<step name="build_prompt">
+Build a structured review prompt:
+
+```markdown
+# Cross-AI Plan Review Request
+
+You are reviewing implementation plans for a software project phase.
+Provide structured feedback on plan quality, completeness, and risks.
+
+## Project Context
+{first 80 lines of PROJECT.md}
+
+## Phase {N}: {phase name}
+### Roadmap Section
+{roadmap phase section}
+
+### Requirements Addressed
+{requirements for this phase}
+
+### User Decisions (CONTEXT.md)
+{context if present}
+
+### Research Findings
+{research if present}
+
+### Plans to Review
+{all PLAN.md contents}
+
+## Review Instructions
+
+Analyze each plan and provide:
+
+1. **Summary** — One-paragraph assessment
+2. **Strengths** — What's well-designed (bullet points)
+3. **Concerns** — Potential issues, gaps, risks (bullet points with severity: HIGH/MEDIUM/LOW)
+4. **Suggestions** — Specific improvements (bullet points)
+5. **Risk Assessment** — Overall risk level (LOW/MEDIUM/HIGH) with justification
+
+Focus on:
+- Missing edge cases or error handling
+- Dependency ordering issues
+- Scope creep or over-engineering
+- Security considerations
+- Performance implications
+- Whether the plans actually achieve the phase goals
+
+Output your review in markdown format.
+```
+
+Write to a temp file: `/tmp/ccp-review-prompt-{phase}.md`
+</step>
+
+<step name="invoke_reviewers">
+For each selected CLI, invoke in sequence (not parallel — avoid rate limits):
+
+**Gemini:**
+```bash
+gemini -p "$(cat /tmp/ccp-review-prompt-{phase}.md)" 2>/dev/null > /tmp/ccp-review-gemini-{phase}.md
+```
+
+**Claude (separate session):**
+```bash
+claude -p "$(cat /tmp/ccp-review-prompt-{phase}.md)" --no-input 2>/dev/null > /tmp/ccp-review-claude-{phase}.md
+```
+
+**Codex:**
+```bash
+codex exec --skip-git-repo-check "$(cat /tmp/ccp-review-prompt-{phase}.md)" 2>/dev/null > /tmp/ccp-review-codex-{phase}.md
+```
+
+**CodeRabbit:**
+
+Note: CodeRabbit reviews the current git diff/working tree — it does not accept a prompt. It may take up to 5 minutes. Use `timeout: 360000` on the Bash tool call.
+
+```bash
+coderabbit review --prompt-only 2>/dev/null > /tmp/ccp-review-coderabbit-{phase}.md
+```
+
+If a CLI fails, log the error and continue with remaining CLIs.
+
+Display progress:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ CCP > CROSS-AI REVIEW — Phase {N}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+◆ Reviewing with {CLI}... done ✓
+◆ Reviewing with {CLI}... done ✓
+```
+</step>
+
+<step name="write_reviews">
+Combine all review responses into `{phase_dir}/{padded_phase}-REVIEWS.md`:
+
+```markdown
+---
+phase: {N}
+reviewers: [gemini, claude, codex, coderabbit]
+reviewed_at: {ISO timestamp}
+plans_reviewed: [{list of PLAN.md files}]
+---
+
+# Cross-AI Plan Review — Phase {N}
+
+## Gemini Review
+
+{gemini review content}
+
+---
+
+## Claude Review
+
+{claude review content}
+
+---
+
+## Codex Review
+
+{codex review content}
+
+---
+
+## CodeRabbit Review
+
+{coderabbit review content}
+
+---
+
+## Consensus Summary
+
+{synthesize common concerns across all reviewers}
+
+### Agreed Strengths
+{strengths mentioned by 2+ reviewers}
+
+### Agreed Concerns
+{concerns raised by 2+ reviewers — highest priority}
+
+### Divergent Views
+{where reviewers disagreed — worth investigating}
+```
+
+Commit:
+```bash
+node "$HOME/.claude/pilot/bin/ccp-tools.cjs" commit "docs: cross-AI review for phase {N}" --files {phase_dir}/{padded_phase}-REVIEWS.md
+```
+</step>
+
+<step name="present_results">
+Display summary:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ CCP > REVIEW COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Phase {N} reviewed by {count} AI systems.
+
+Consensus concerns:
+{top 3 shared concerns}
+
+Full review: {padded_phase}-REVIEWS.md
+
+To incorporate feedback into planning:
+  /ccp:plan-phase {N} --reviews
+```
+
+Clean up temp files.
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] At least one external CLI invoked successfully
+- [ ] REVIEWS.md written with structured feedback
+- [ ] Consensus summary synthesized from multiple reviewers
+- [ ] Temp files cleaned up
+- [ ] User knows how to use feedback (/ccp:plan-phase --reviews)
+</success_criteria>

package/src/pilot/workflows/secure-phase.md

@@ -0,0 +1,164 @@
+<purpose>
+Verify threat mitigations for a completed phase. Confirm PLAN.md threat register dispositions are resolved. Update SECURITY.md.
+</purpose>
+
+<required_reading>
+@~/.claude/pilot/references/ui-brand.md
+</required_reading>
+
+<available_agent_types>
+Valid CCP subagent types (use exact names — do not fall back to 'general-purpose'):
+- ccp-security-auditor — Verifies threat mitigation coverage
+</available_agent_types>
+
+<process>
+
+## 0. Initialize
+
+```bash
+INIT=$(node "$HOME/.claude/pilot/bin/ccp-tools.cjs" init phase-op "${PHASE_ARG}")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+AGENT_SKILLS_AUDITOR=$(node "$HOME/.claude/pilot/bin/ccp-tools.cjs" agent-skills ccp-security-auditor 2>/dev/null)
+```
+
+Parse: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`.
+
+```bash
+AUDITOR_MODEL=$(node "$HOME/.claude/pilot/bin/ccp-tools.cjs" resolve-model ccp-security-auditor --raw)
+SECURITY_CFG=$(node "$HOME/.claude/pilot/bin/ccp-tools.cjs" config-get workflow.security_enforcement --raw 2>/dev/null || echo "true")
+```
+
+If `SECURITY_CFG` is `false`: exit with "Security enforcement disabled. Enable via /ccp:settings."
+
+Display banner: `CCP > SECURE PHASE {N}: {name}`
+
+## 1. Detect Input State
+
+```bash
+SECURITY_FILE=$(ls "${PHASE_DIR}"/*-SECURITY.md 2>/dev/null | head -1)
+PLAN_FILES=$(ls "${PHASE_DIR}"/*-PLAN.md 2>/dev/null)
+SUMMARY_FILES=$(ls "${PHASE_DIR}"/*-SUMMARY.md 2>/dev/null)
+```
+
+- **State A** (`SECURITY_FILE` non-empty): Audit existing
+- **State B** (`SECURITY_FILE` empty, `PLAN_FILES` and `SUMMARY_FILES` non-empty): Run from artifacts
+- **State C** (`SUMMARY_FILES` empty): Exit — "Phase {N} not executed. Run /ccp:execute-phase {N} first."
+
+## 2. Discovery
+
+### 2a. Read Phase Artifacts
+
+Read PLAN.md — extract `<threat_model>` block: trust boundaries, STRIDE register (`threat_id`, `category`, `component`, `disposition`, `mitigation_plan`).
+
+### 2b. Read Summary Threat Flags
+
+Read SUMMARY.md — extract `## Threat Flags` entries.
+
+### 2c. Build Threat Register
+
+Per threat: `{ threat_id, category, component, disposition, mitigation_pattern, files_to_check }`
+
+## 3. Threat Classification
+
+Classify each threat:
+
+| Status | Criteria |
+|--------|----------|
+| CLOSED | mitigation found OR accepted risk documented in SECURITY.md OR transfer documented |
+| OPEN | none of the above |
+
+Build: `{ threat_id, category, component, disposition, status, evidence }`
+
+If `threats_open: 0` → skip to Step 6 directly.
+
+## 4. Present Threat Plan
+
+Call AskUserQuestion with threat table and options:
+1. "Verify all open threats" → Step 5
+2. "Accept all open — document in accepted risks log" → add to SECURITY.md accepted risks, set all CLOSED, Step 6
+3. "Cancel" → exit
+
+## 5. Spawn ccp-security-auditor
+
+```
+Task(
+  prompt="Read ./.claude/agents/ccp-security-auditor.md for instructions.\n\n" +
+    "<files_to_read>{PLAN, SUMMARY, impl files, SECURITY.md}</files_to_read>" +
+    "<threat_register>{threat register}</threat_register>" +
+    "<config>asvs_level: {SECURITY_ASVS}, block_on: {SECURITY_BLOCK_ON}</config>" +
+    "<constraints>Never modify implementation files. Verify mitigations exist — do not scan for new threats. Escalate implementation gaps.</constraints>" +
+    "${AGENT_SKILLS_AUDITOR}",
+  subagent_type="ccp-security-auditor",
+  model="{AUDITOR_MODEL}",
+  description="Verify threat mitigations for Phase {N}"
+)
+```
+
+Handle return:
+- `## SECURED` → record closures → Step 6
+- `## OPEN_THREATS` → record closed + open, present user with accept/block choice → Step 6
+- `## ESCALATE` → present to user → Step 6
+
+## 6. Write/Update SECURITY.md
+
+**State B (create):**
+1. Read template from `./.claude/pilot/templates/SECURITY.md`
+2. Fill: frontmatter, threat register, accepted risks, audit trail
+3. Write to `${PHASE_DIR}/${PADDED_PHASE}-SECURITY.md`
+
+**State A (update):**
+1. Update threat register statuses, append to audit trail:
+
+```markdown
+## Security Audit {date}
+| Metric | Count |
+|--------|-------|
+| Threats found | {N} |
+| Closed | {M} |
+| Open | {K} |
+```
+
+**ENFORCING GATE:** If `threats_open > 0` after all options exhausted (user did not accept, not all verified closed):
+
+```
+CCP > PHASE {N} SECURITY BLOCKED
+{K} threats open — phase advancement blocked until threats_open: 0
+▶ Fix mitigations then re-run: /ccp:secure-phase {N}
+▶ Or document accepted risks in SECURITY.md and re-run.
+```
+
+Do NOT emit next-phase routing. Stop here.
+
+## 7. Commit
+
+```bash
+node "$HOME/.claude/pilot/bin/ccp-tools.cjs" commit "docs(phase-${PHASE}): add/update security threat verification"
+```
+
+## 8. Results + Routing
+
+**Secured (threats_open: 0):**
+```
+CCP > PHASE {N} THREAT-SECURE
+threats_open: 0 — all threats have dispositions.
+▶ /ccp:validate-phase {N}    validate test coverage
+▶ /ccp:verify-work {N}       run UAT
+```
+
+Display `/clear` reminder.
+
+</process>
+
+<success_criteria>
+- [ ] Security enforcement checked — exit if false
+- [ ] Input state detected (A/B/C) — state C exits cleanly
+- [ ] PLAN.md threat model parsed, register built
+- [ ] SUMMARY.md threat flags incorporated
+- [ ] threats_open: 0 → skip directly to Step 6
+- [ ] User gate with threat table presented
+- [ ] Auditor spawned with complete context
+- [ ] All three return formats (SECURED/OPEN_THREATS/ESCALATE) handled
+- [ ] SECURITY.md created or updated
+- [ ] threats_open > 0 BLOCKS advancement (no next-phase routing emitted)
+- [ ] Results with routing presented on success
+</success_criteria>

package/src/rules/common/code-review.md

@@ -0,0 +1,124 @@
+# Code Review Standards
+
+## Purpose
+
+Code review ensures quality, security, and maintainability before code is merged. This rule defines when and how to conduct code reviews.
+
+## When to Review
+
+**MANDATORY review triggers:**
+
+- After writing or modifying code
+- Before any commit to shared branches
+- When security-sensitive code is changed (auth, payments, user data)
+- When architectural changes are made
+- Before merging pull requests
+
+**Pre-Review Requirements:**
+
+Before requesting review, ensure:
+
+- All automated checks (CI/CD) are passing
+- Merge conflicts are resolved
+- Branch is up to date with target branch
+
+## Review Checklist
+
+Before marking code complete:
+
+- [ ] Code is readable and well-named
+- [ ] Functions are focused (<50 lines)
+- [ ] Files are cohesive (<800 lines)
+- [ ] No deep nesting (>4 levels)
+- [ ] Errors are handled explicitly
+- [ ] No hardcoded secrets or credentials
+- [ ] No console.log or debug statements
+- [ ] Tests exist for new functionality
+- [ ] Test coverage meets 80% minimum
+
+## Security Review Triggers
+
+**STOP and use security-reviewer agent when:**
+
+- Authentication or authorization code
+- User input handling
+- Database queries
+- File system operations
+- External API calls
+- Cryptographic operations
+- Payment or financial code
+
+## Review Severity Levels
+
+| Level | Meaning | Action |
+|-------|---------|--------|
+| CRITICAL | Security vulnerability or data loss risk | **BLOCK** - Must fix before merge |
+| HIGH | Bug or significant quality issue | **WARN** - Should fix before merge |
+| MEDIUM | Maintainability concern | **INFO** - Consider fixing |
+| LOW | Style or minor suggestion | **NOTE** - Optional |
+
+## Agent Usage
+
+Use these agents for code review:
+
+| Agent | Purpose |
+|-------|---------|
+| **code-reviewer** | General code quality, patterns, best practices |
+| **security-reviewer** | Security vulnerabilities, OWASP Top 10 |
+| **typescript-reviewer** | TypeScript/JavaScript specific issues |
+| **python-reviewer** | Python specific issues |
+| **go-reviewer** | Go specific issues |
+| **rust-reviewer** | Rust specific issues |
+
+## Review Workflow
+
+```
+1. Run git diff to understand changes
+2. Check security checklist first
+3. Review code quality checklist
+4. Run relevant tests
+5. Verify coverage >= 80%
+6. Use appropriate agent for detailed review
+```
+
+## Common Issues to Catch
+
+### Security
+
+- Hardcoded credentials (API keys, passwords, tokens)
+- SQL injection (string concatenation in queries)
+- XSS vulnerabilities (unescaped user input)
+- Path traversal (unsanitized file paths)
+- CSRF protection missing
+- Authentication bypasses
+
+### Code Quality
+
+- Large functions (>50 lines) - split into smaller
+- Large files (>800 lines) - extract modules
+- Deep nesting (>4 levels) - use early returns
+- Missing error handling - handle explicitly
+- Mutation patterns - prefer immutable operations
+- Missing tests - add test coverage
+
+### Performance
+
+- N+1 queries - use JOINs or batching
+- Missing pagination - add LIMIT to queries
+- Unbounded queries - add constraints
+- Missing caching - cache expensive operations
+
+## Approval Criteria
+
+- **Approve**: No CRITICAL or HIGH issues
+- **Warning**: Only HIGH issues (merge with caution)
+- **Block**: CRITICAL issues found
+
+## Integration with Other Rules
+
+This rule works with:
+
+- [testing.md](testing.md) - Test coverage requirements
+- [security.md](security.md) - Security checklist
+- [git-workflow.md](git-workflow.md) - Commit standards
+- [agents.md](agents.md) - Agent delegation

package/src/rules/zh/README.md

@@ -0,0 +1,108 @@
+# 规则
+
+## 结构
+
+规则按**通用**层和**语言特定**目录组织：
+
+```
+rules/
+├── common/          # 语言无关的原则（始终安装）
+│   ├── coding-style.md
+│   ├── git-workflow.md
+│   ├── testing.md
+│   ├── performance.md
+│   ├── patterns.md
+│   ├── hooks.md
+│   ├── agents.md
+│   ├── security.md
+│   ├── code-review.md
+│   └── development-workflow.md
+├── zh/              # 中文翻译版本
+│   ├── coding-style.md
+│   ├── git-workflow.md
+│   ├── testing.md
+│   ├── performance.md
+│   ├── patterns.md
+│   ├── hooks.md
+│   ├── agents.md
+│   ├── security.md
+│   ├── code-review.md
+│   └── development-workflow.md
+├── typescript/      # TypeScript/JavaScript 特定
+├── python/          # Python 特定
+├── golang/          # Go 特定
+├── swift/           # Swift 特定
+└── php/             # PHP 特定
+```
+
+- **common/** 包含通用原则 — 无语言特定的代码示例。
+- **zh/** 包含 common 目录的中文翻译版本。
+- **语言目录** 扩展通用规则，包含框架特定的模式、工具和代码示例。每个文件引用其对应的通用版本。
+
+## 安装
+
+### 选项 1：安装脚本（推荐）
+
+```bash
+# 安装通用 + 一个或多个语言特定的规则集
+./install.sh typescript
+./install.sh python
+./install.sh golang
+./install.sh swift
+./install.sh php
+
+# 同时安装多种语言
+./install.sh typescript python
+```
+
+### 选项 2：手动安装
+
+> **重要提示：** 复制整个目录 — 不要使用 `/*` 展开。
+> 通用和语言特定目录包含同名文件。
+> 将它们展开到一个目录会导致语言特定文件覆盖通用规则，
+> 并破坏语言特定文件使用的 `../common/` 相对引用。
+
+```bash
+# 创建目标目录
+mkdir -p ~/.claude/rules
+
+# 安装通用规则（所有项目必需）
+cp -r rules/common ~/.claude/rules/common
+
+# 安装中文翻译版本（可选）
+cp -r rules/zh ~/.claude/rules/zh
+
+# 根据项目技术栈安装语言特定规则
+cp -r rules/typescript ~/.claude/rules/typescript
+cp -r rules/python ~/.claude/rules/python
+cp -r rules/golang ~/.claude/rules/golang
+cp -r rules/swift ~/.claude/rules/swift
+cp -r rules/php ~/.claude/rules/php
+```
+
+## 规则 vs 技能
+
+- **规则** 定义广泛适用的标准、约定和检查清单（如"80% 测试覆盖率"、"禁止硬编码密钥"）。
+- **技能**（`skills/` 目录）为特定任务提供深入、可操作的参考材料（如 `python-patterns`、`golang-testing`）。
+
+语言特定的规则文件在适当的地方引用相关技能。规则告诉你*做什么*；技能告诉你*怎么做*。
+
+## 规则优先级
+
+当语言特定规则与通用规则冲突时，**语言特定规则优先**（特定覆盖通用）。这遵循标准的分层配置模式（类似于 CSS 特异性或 `.gitignore` 优先级）。
+
+- `rules/common/` 定义适用于所有项目的通用默认值。
+- `rules/golang/`、`rules/python/`、`rules/swift/`、`rules/php/`、`rules/typescript/` 等在语言习惯不同时覆盖这些默认值。
+- `rules/zh/` 是通用规则的中文翻译，与英文版本内容一致。
+
+### 示例
+
+`common/coding-style.md` 推荐不可变性作为默认原则。语言特定的 `golang/coding-style.md` 可以覆盖这一点：
+
+> 惯用的 Go 使用指针接收器进行结构体变更 — 参见 [common/coding-style.md](../common/coding-style.md) 了解通用原则，但这里首选符合 Go 习惯的变更方式。
+
+### 带覆盖说明的通用规则
+
+`rules/common/` 中可能被语言特定文件覆盖的规则会被标记：
+
+> **语言说明**：此规则可能会被语言特定规则覆盖；对于某些语言，该模式可能并不符合惯用写法。

package/src/rules/zh/agents.md

@@ -0,0 +1,50 @@
+# 代理编排
+
+## 可用代理
+
+位于 `~/.claude/agents/`：
+
+| 代理 | 用途 | 何时使用 |
+|-------|---------|------------|
+| planner | 实现规划 | 复杂功能、重构 |
+| architect | 系统设计 | 架构决策 |
+| tdd-guide | 测试驱动开发 | 新功能、bug 修复 |
+| code-reviewer | 代码审查 | 编写代码后 |
+| security-reviewer | 安全分析 | 提交前 |
+| build-error-resolver | 修复构建错误 | 构建失败时 |
+| e2e-runner | E2E 测试 | 关键用户流程 |
+| refactor-cleaner | 死代码清理 | 代码维护 |
+| doc-updater | 文档 | 更新文档 |
+| rust-reviewer | Rust 代码审查 | Rust 项目 |
+
+## 立即使用代理
+
+无需用户提示：
+1. 复杂功能请求 - 使用 **planner** 代理
+2. 刚编写/修改的代码 - 使用 **code-reviewer** 代理
+3. Bug 修复或新功能 - 使用 **tdd-guide** 代理
+4. 架构决策 - 使用 **architect** 代理
+
+## 并行任务执行
+
+对独立操作始终使用并行 Task 执行：
+
+```markdown
+# 好：并行执行
+同时启动 3 个代理：
+1. 代理 1：认证模块安全分析
+2. 代理 2：缓存系统性能审查
+3. 代理 3：工具类型检查
+
+# 坏：不必要的顺序
+先代理 1，然后代理 2，然后代理 3
+```
+
+## 多视角分析
+
+对于复杂问题，使用分角色子代理：
+- 事实审查者
+- 高级工程师
+- 安全专家
+- 一致性审查者
+- 冗余检查者