zhuge-workflow 0.1.0

package/templates/claude/commands/ccg/_context.md

@@ -0,0 +1,152 @@
+# CCG Spec 上下文注入协议
+
+> 本文件定义 CCG Spec 工作流的上下文注入规范。
+> 所有 `/ccg:spec-*` 命令（除 `spec-init`）必须遵循此协议。
+
+---
+
+## 阶段一：基础规范（所有命令通用）
+
+### 1.1 发现规范目录结构
+
+使用 Glob 快速列出规范文件：
+
+```bash
+# 列出规范目录结构
+ls -la .trellis/spec/ 2>/dev/null
+```
+
+### 1.2 读取基础规范
+
+根据发现的目录结构和任务类型，读取相关规范：
+
+```
+mcp__ace-tool__search_context({
+  project_root_path: "$PWD",
+  query: "<任务描述> 需要遵循哪些编码规范和开发指南"
+})
+```
+
+### 1.3 规范约束
+
+读取的规范内容必须：
+1. **保持在工作记忆中** - 后续所有步骤都受这些规范约束
+2. **传递给外部模型** - 调用 Codex/Gemini 时，将相关规范内容包含在 prompt 中
+3. **优先于默认行为** - 规范与 AI 默认行为冲突时，以规范为准
+
+---
+
+## 阶段二：任务专属上下文（仅 spec-impl / spec-review）
+
+### 2.1 读取 ccg-context.jsonl
+
+```bash
+cat openspec/changes/<change-id>/ccg-context.jsonl 2>/dev/null
+```
+
+### 2.2 JSONL 格式
+
+每条规范关联到具体的 task 编号，支持多任务关联：
+
+```jsonl
+{"task": "1", "file": "<规范文件路径>", "reason": "<为什么与该任务相关>"}
+{"task": "1,2", "file": "<规范文件路径>", "reason": "<任务1和2都需要>"}
+{"task": "1,2,3", "file": "<规范文件路径>", "reason": "<多个任务共用>"}
+{"task": "*", "file": "<规范文件路径>", "reason": "<所有任务通用>"}
+```
+
+**字段说明**：
+- `task`: 任务编号，多个用逗号分隔（如 `"1,2,3"`），`"*"` 表示所有任务通用
+- `file`: 规范文件路径
+- `reason`: 为什么该规范与此任务相关
+
+### 2.3 按当前任务读取规范
+
+在 `spec-impl` 阶段，根据当前执行的任务编号筛选并读取规范：
+
+```bash
+# 读取任务 N 相关的规范（包括通用规范 "*" 和包含该任务的多任务条目）
+TASK_ID="1"
+cat openspec/changes/<change-id>/ccg-context.jsonl | while read line; do
+  task=$(echo "$line" | jq -r '.task')
+  # 匹配: "*" 或 精确匹配 或 在逗号分隔列表中
+  if [ "$task" = "*" ] || [ "$task" = "$TASK_ID" ] || echo ",$task," | grep -q ",$TASK_ID,"; then
+    file=$(echo "$line" | jq -r '.file')
+    echo "=== $file ==="
+    cat "$file" 2>/dev/null
+  fi
+done
+```
+
+---
+
+## 命令与阶段对应关系
+
+| 命令 | 阶段一（基础规范） | 阶段二（专属上下文） | 特殊职责 |
+|------|:------------------:|:--------------------:|----------|
+| `/ccg:spec-init` | ❌ | ❌ | 验证工具 |
+| `/ccg:spec-research` | ✅ | ❌ | 探索代码库 |
+| `/ccg:spec-plan` | ✅ | ❌ | **创建** ccg-context.jsonl |
+| `/ccg:spec-impl` | ✅ | ✅ | 按计划实现 |
+| `/ccg:spec-review` | ✅ | ✅ | 双模型审查 |
+
+---
+
+## ccg-context.jsonl 创建指南（spec-plan 职责）
+
+在 `spec-plan` 阶段，基于研究和规划结果，为每个 task 创建上下文配置。
+
+### 步骤
+
+1. **读取 tasks.md**：获取所有任务列表和编号
+2. **为每个任务分析所需规范**：使用mcp__ace-tool__search_context工具语义化查询找到相关规范
+3. **创建 ccg-context.jsonl**：每条规范关联到具体任务
+
+### 发现相关规范
+
+使用语义化查询找到与当前任务相关的规范：
+
+```
+mcp__ace-tool__search_context({
+  project_root_path: "$PWD",
+  query: "<任务描述> 需要遵循的具体规范文件"
+})
+```
+
+### 创建示例
+
+```bash
+cat > openspec/changes/<change-id>/ccg-context.jsonl << 'EOF'
+{"task": "*", "file": ".trellis/spec/guides/index.md", "reason": "所有任务通用的思维指南"}
+{"task": "1,2", "file": ".trellis/spec/backend/api.md", "reason": "任务1和2都涉及API开发"}
+{"task": "3", "file": ".trellis/spec/frontend/components.md", "reason": "任务3涉及组件开发"}
+EOF
+```
+
+### 选择原则
+
+1. **任务粒度** - 每条规范关联到具体任务，避免注入不相关内容
+2. **多任务共用** - 多个任务需要同一规范时用逗号分隔（如 `"1,2,3"`）
+3. **通用规范用 `"*"`** - 所有任务都需要的规范用 `"*"` 标记
+4. **明确理由** - 每个条目必须有清晰的 `reason`
+
+---
+
+## 传递规范给外部模型
+
+调用 Codex/Gemini 时，必须将相关规范包含在 prompt 中：
+
+```bash
+SPEC_CONTENT=$(cat <规范文件路径>)
+
+codeagent-wrapper --backend codex - "$PWD" <<EOF
+## 项目规范约束
+$SPEC_CONTENT
+
+## 任务
+<具体任务描述>
+
+## 输出格式
+Unified Diff Patch
+EOF
+```

package/templates/claude/commands/ccg/spec-impl.md

@@ -0,0 +1,161 @@
+---
+description: '按规范执行 + 多模型协作 + 归档'
+---
+<!-- CCG:SPEC:IMPL:START -->
+
+> ⚠️ **上下文注入（阶段一 + 阶段二）**
+> 执行本命令前，必须完成上下文注入。参考：`~/.claude/commands/ccg/_context.md`
+>
+> **阶段一**：发现并读取 `.trellis/spec/` 下相关目录的规范
+> **阶段二**：根据当前任务编号，从 `ccg-context.jsonl` 筛选并读取对应规范
+
+**Core Philosophy**
+- Implementation is pure mechanical execution—all decisions were made in Plan phase.
+- External model outputs are prototypes only; must be rewritten to production-grade code.
+- Keep changes tightly scoped; enforce side-effect review before any modification.
+- Minimize documentation—prefer self-explanatory code over comments.
+
+**Guardrails**
+- **NEVER** apply Codex/Gemini prototypes directly—all outputs are reference only.
+- **MANDATORY**: Request `unified diff patch` format from external models; they have zero write permission.
+- Keep implementation strictly within `tasks.md` scope—no scope creep.
+- Refer to `openspec/config.yaml` for conventions.
+
+**Steps**
+1. **Select Change**
+   - Run `/opsx:list` to inspect Active Changes.
+   - Confirm with user which change ID to implement.
+   - Run `/opsx:show <change_id>` to review tasks.
+
+2. **Apply OPSX Change**
+   - Use `/ccg:spec-impl` (which uses OpenSpec skills internally) to enter implementation mode.
+   - This skill will guide you through the tasks defined in `tasks.md`.
+
+3. **Identify Minimal Verifiable Phase**
+   - Review `tasks.md` and identify the **smallest verifiable phase**.
+   - Do NOT complete all tasks at once—control context window.
+   - Announce: "Implementing Phase X: [task group name]"
+
+4. **按任务编号注入规范（阶段二）**
+
+   在执行每个任务前，根据任务编号从 `ccg-context.jsonl` 筛选并读取规范。
+
+   **任务编号格式**：使用 `Phase.Section` 格式（如 `1.1`, `2.5`, `3.1`），与 tasks.md 保持一致。
+
+   ```bash
+   # 假设当前执行 Phase 2.5 预设选择器组件
+   TASK_ID="2.5"
+   CHANGE_ID="<change-id>"
+
+   cat openspec/changes/$CHANGE_ID/ccg-context.jsonl | while read line; do
+     task=$(echo "$line" | jq -r '.task')
+     # 匹配: "*" 或 精确匹配 或 在逗号分隔列表中
+     if [ "$task" = "*" ] || [ "$task" = "$TASK_ID" ] || echo ",$task," | grep -q ",$TASK_ID,"; then
+       file=$(echo "$line" | jq -r '.file')
+       reason=$(echo "$line" | jq -r '.reason')
+       echo "=== $file ($reason) ==="
+       cat "$file" 2>/dev/null
+     fi
+   done
+   ```
+
+   **匹配规则**：
+   - `"*"` - 所有任务通用，始终注入
+   - `"2.5"` - 精确匹配 Phase 2.5
+   - `"1.1,1.2,1.3"` - Phase 1.1、1.2、1.3 共用，匹配其中任一
+
+5. **Route Tasks to Appropriate Model**
+   - **Route A: Gemini** — Frontend/UI/styling (CSS, React, Vue, HTML, components)
+   - **Route B: Codex** — Backend/logic/algorithm (API, data processing, business logic)
+
+   For each task:
+   ```
+   codeagent-wrapper --backend <codex|gemini> - "$PWD" <<'EOF'
+   TASK: <task description from tasks.md>
+   CONTEXT: <relevant code context>
+   CONSTRAINTS: <constraints from spec>
+   OUTPUT: Unified Diff Patch format ONLY
+   EOF
+   ```
+
+5. **Rewrite Prototype to Production Code**
+   Upon receiving diff patch, **NEVER apply directly**. Rewrite by:
+   - Removing redundancy
+   - Ensuring clear naming and simple structure
+   - Aligning with project style
+   - Eliminating unnecessary comments
+   - Verifying no new dependencies introduced
+
+6. **Side-Effect Review** (Mandatory before apply)
+   Verify the change:
+   - [ ] Does not exceed `tasks.md` scope
+   - [ ] Does not affect unrelated modules
+   - [ ] Does not introduce new dependencies
+   - [ ] Does not break existing interfaces
+
+   If issues found, make targeted corrections.
+
+7. **Multi-Model Review (PARALLEL)**
+   - **CRITICAL**: You MUST launch BOTH Codex AND Gemini in a SINGLE message with TWO Bash tool calls.
+   - **DO NOT** call one model first and wait. Launch BOTH simultaneously with `run_in_background: true`.
+
+   **Step 7.1**: In ONE message, make TWO parallel Bash calls:
+
+   **FIRST Bash call (Codex)**:
+   ```
+   Bash({
+     command: "/Users/blackzhuge/.claude/bin/codeagent-wrapper --backend codex - \"$PWD\" <<'EOF'\nReview the implementation changes:\n- Correctness: logic errors, edge cases\n- Security: injection, auth issues\n- Spec compliance: constraints satisfied\nOUTPUT: JSON with findings\nEOF",
+     run_in_background: true,
+     timeout: 300000,
+     description: "Codex: correctness/security review"
+   })
+   ```
+
+   **SECOND Bash call (Gemini) - IN THE SAME MESSAGE**:
+   ```
+   Bash({
+     command: "/Users/blackzhuge/.claude/bin/codeagent-wrapper --backend gemini - \"$PWD\" <<'EOF'\nReview the implementation changes:\n- Maintainability: readability, complexity\n- Patterns: consistency with project style\n- Integration: cross-module impacts\nOUTPUT: JSON with findings\nEOF",
+     run_in_background: true,
+     timeout: 300000,
+     description: "Gemini: maintainability/patterns review"
+   })
+   ```
+
+   **Step 7.2**: After BOTH Bash calls return task IDs, wait for results with TWO TaskOutput calls:
+   ```
+   TaskOutput({ task_id: "<codex_task_id>", block: true, timeout: 600000 })
+   TaskOutput({ task_id: "<gemini_task_id>", block: true, timeout: 600000 })
+   ```
+
+   Address any critical findings before proceeding.
+
+8. **Update Task Status**
+   - Mark completed task in `tasks.md`: `- [x] Task description`
+   - Commit changes if appropriate.
+
+9. **Context Checkpoint**
+   - After completing a phase, report context usage.
+   - If below 80K: Ask user "Continue to next phase?"
+   - If approaching 80K: Suggest "Run `/clear` and resume with `/ccg:spec:impl`"
+
+10. **Sync Specs Before Archive (MANDATORY)**
+    - When ALL tasks in `tasks.md` are marked `[x]`:
+    - **MUST** run `/opsx:sync` first to merge delta specs to `openspec/specs/`
+    - Verify sync completed successfully before proceeding
+    - Only after sync succeeds, run `/opsx:archive` to archive the change
+
+    **WARNING**: Skipping sync will result in lost specifications!
+
+**Reference**
+- Check task status: `/opsx:show <id>`
+- Validate before archive: `/opsx:validate <id>`
+- View active changes: `/opsx:list`
+- Search existing patterns: `rg -n "function|class" <file>`
+
+**Exit Criteria**
+Implementation is complete when:
+- [ ] All tasks in `tasks.md` marked `[x]`
+- [ ] All multi-model reviews passed
+- [ ] Side-effect review confirmed no regressions
+- [ ] Change archived successfully
+<!-- CCG:SPEC:IMPL:END -->

package/templates/claude/commands/ccg/spec-plan-trellis.md

@@ -0,0 +1,239 @@
+---
+description: '多模型分析 → 消除歧义 → 零决策可执行计划 → 生成 Trellis Tasks'
+---
+<!-- CCG:SPEC:PLAN-NEW:START -->
+
+> ⚠️ **上下文注入（阶段一）**
+> 执行本命令前，必须先读取基础规范。参考：`~/.claude/commands/ccg/_context.md`
+>
+> **必读规范**：
+> 1. `.trellis/spec/guides/index.md` - 思维指南
+> 2. 根据开发类型读取 `backend/index.md` 或 `frontend/index.md`
+
+**Core Philosophy**
+- The goal is to eliminate ALL decision points—implementation should be pure mechanical execution.
+- Every ambiguity must be resolved into explicit constraints before proceeding.
+- Multi-model collaboration surfaces blind spots and conflicting assumptions.
+- Every requirement must have Property-Based Testing (PBT) properties—focus on invariants.
+
+**Guardrails**
+- Do not proceed to implementation until every ambiguity is resolved.
+- Multi-model collaboration is **mandatory**: use both Codex and Gemini.
+- If constraints cannot be fully specified, escalate to user or return to research phase.
+- Refer to `openspec/config.yaml` for project conventions.
+
+**Steps**
+1. **Select Change**
+   - Run `/opsx:list` to display Active Changes.
+   - Confirm with user which change ID to refine.
+   - Run `/opsx:status <change_id>` to review current state.
+
+2. **Multi-Model Implementation Analysis (PARALLEL)**
+   - **CRITICAL**: You MUST launch BOTH Codex AND Gemini in a SINGLE message with TWO Bash tool calls.
+   - **DO NOT** call one model first and wait. Launch BOTH simultaneously with `run_in_background: true`.
+
+   **Step 2.1**: In ONE message, make TWO parallel Bash calls:
+
+   **FIRST Bash call (Codex)**:
+   ```
+   Bash({
+     command: "/Users/blackzhuge/.claude/bin/codeagent-wrapper --backend codex - \"$PWD\" <<'EOF'\nAnalyze change <change_id> from backend perspective:\n- Implementation approach\n- Technical risks\n- Alternative architectures\n- Edge cases and failure modes\nOUTPUT: JSON with analysis\nEOF",
+     run_in_background: true,
+     timeout: 300000,
+     description: "Codex: backend analysis"
+   })
+   ```
+
+   **SECOND Bash call (Gemini) - IN THE SAME MESSAGE**:
+   ```
+   Bash({
+     command: "/Users/blackzhuge/.claude/bin/codeagent-wrapper --backend gemini - \"$PWD\" <<'EOF'\nAnalyze change <change_id> from frontend/integration perspective:\n- Maintainability assessment\n- Scalability considerations\n- Integration conflicts\nOUTPUT: JSON with analysis\nEOF",
+     run_in_background: true,
+     timeout: 300000,
+     description: "Gemini: frontend analysis"
+   })
+   ```
+
+   **Step 2.2**: After BOTH Bash calls return task IDs, wait for results with TWO TaskOutput calls:
+   ```
+   TaskOutput({ task_id: "<codex_task_id>", block: true, timeout: 600000 })
+   TaskOutput({ task_id: "<gemini_task_id>", block: true, timeout: 600000 })
+   ```
+
+   - Synthesize responses and present consolidated options to user.
+
+3. **Uncertainty Elimination Audit**
+   - **Codex**: "Review proposal for unspecified decision points. List each as: [AMBIGUITY] → [REQUIRED CONSTRAINT]"
+   - **Gemini**: "Identify implicit assumptions. Specify: [ASSUMPTION] → [EXPLICIT CONSTRAINT NEEDED]"
+
+   **Anti-Pattern Detection** (flag and reject):
+   - Information collection without decision boundaries
+   - Technical comparisons without selection criteria
+   - Deferred decisions marked "to be determined during implementation"
+
+   **Target Pattern** (required for approval):
+   - Explicit technology choices with parameters (e.g., "JWT with TTL=15min")
+   - Concrete algorithm selections with configs (e.g., "bcrypt cost=12")
+   - Precise behavioral rules (e.g., "Lock account 30min after 5 failed attempts")
+
+   Iterate with user until ALL ambiguities resolved.
+
+4. **PBT Property Extraction**
+   - **Codex**: "Extract PBT properties. For each requirement: [INVARIANT] → [FALSIFICATION STRATEGY]"
+   - **Gemini**: "Define system properties: [PROPERTY] | [DEFINITION] | [BOUNDARY CONDITIONS] | [COUNTEREXAMPLE GENERATION]"
+
+   **Property Categories**:
+   - **Commutativity/Associativity**: Order-independent operations
+   - **Idempotency**: Repeated operations yield same result
+   - **Round-trip**: Encode→Decode returns original
+   - **Invariant Preservation**: State constraints maintained
+   - **Monotonicity**: Ordering guarantees (e.g., timestamps increase)
+   - **Bounds**: Value ranges, size limits, rate constraints
+
+5. **Update OPSX Artifacts**
+   - The agent will use OpenSpec skills to generate/update:
+     * specs (Requirements + PBT)
+     * design (Technical decisions)
+     * tasks (Zero-decision implementation plan)
+   - Ensure all resolved constraints and PBT properties are included in the generated artifacts.
+
+   **tasks.md 格式约束（强制）**:
+
+   每个任务必须使用 checkbox 格式，便于跟踪进度：
+
+   ```markdown
+   ### 1.1 任务标题
+
+   - [ ] **文件**: `path/to/file.cs`
+
+   **实现要点**:
+   - 要点1
+   - 要点2
+
+   **验收**: 验收标准
+   ```
+
+   **格式规则**：
+   - 每个任务条目必须以 `- [ ]` 开头（待完成）
+   - 完成后标记为 `- [x]`
+   - 文件末尾必须包含进度统计表
+
+   **测试任务（强制）**：
+   - 每个功能实现任务必须有对应的测试任务
+   - 单元测试：覆盖核心逻辑、边界条件、异常处理
+   - 集成测试：覆盖 API 端点、数据库交互、跨模块协作
+   - 测试任务使用独立编号（如 1.2 实现 → 1.3 单元测试 → 1.4 集成测试）
+   - 具体测试框架参考 `openspec/config.yaml` 中的项目约定
+   - **禁止**：跳过测试任务或标记为"后续补充"
+
+   **进度统计表**：
+
+   ```markdown
+   ## 进度统计
+
+   | Phase | 总任务 | 已完成 | 进度 |
+   |-------|--------|--------|------|
+   | Phase 1 | N | 0 | 0% |
+   | **总计** | **N** | **0** | **0%** |
+   ```
+
+6. **生成 Trellis Tasks（替代 ccg-context.jsonl）**
+
+   基于 tasks.md 的 Phase 结构，为每个 Phase 创建独立的 Trellis Task。
+
+   **6.1 解析 tasks.md 获取所有 Phase**
+
+   ```bash
+   CHANGE_ID="<change-id>"
+   CHANGE_DIR="openspec/changes/$CHANGE_ID"
+
+   # 提取所有 Phase 编号和标题
+   grep -E "^## Phase [0-9]+:" "$CHANGE_DIR/tasks.md"
+   ```
+
+   **6.2 确定每个 Phase 的 dev_type**
+
+   根据 Phase 内容判断开发类型：
+   - 包含 `.cs`, `API`, `Service`, `Controller` → `backend`
+   - 包含 `.vue`, `.tsx`, `Component`, `UI` → `frontend`
+   - 混合内容 → `fullstack`
+   - 测试相关 → `test`
+
+   **6.3 为每个 Phase 创建 Trellis Task**
+
+   对每个 Phase 调用 task.sh：
+
+   ```bash
+   # Phase 1 示例
+   ./.trellis/scripts/task.sh create-from-phase \
+     --change "$CHANGE_DIR" \
+     --phase 1 \
+     --dev-type backend
+
+   # Phase 2 示例
+   ./.trellis/scripts/task.sh create-from-phase \
+     --change "$CHANGE_DIR" \
+     --phase 2 \
+     --dev-type backend
+
+   # Phase 3 示例（前端）
+   ./.trellis/scripts/task.sh create-from-phase \
+     --change "$CHANGE_DIR" \
+     --phase 3 \
+     --dev-type frontend
+   ```
+
+   **create-from-phase 输出结构**：
+
+   ```
+   .trellis/tasks/MM-DD-<change-name>-phase-N/
+   ├── task.json         # 包含 openspec_change, phase_number, ccg-impl action
+   ├── prd.md            # 描述执行哪个 change 的哪个 Phase
+   ├── implement.jsonl   # 包含 specs.md, design.md, tasks.md
+   ├── check.jsonl
+   └── debug.jsonl
+   ```
+
+   **6.4 列出创建的任务**
+
+   ```bash
+   ./.trellis/scripts/task.sh list
+   ```
+
+   **6.5 输出任务执行顺序**
+
+   向用户报告创建的任务列表和建议的执行顺序：
+
+   ```markdown
+   ## Trellis Tasks 已创建
+
+   | Task | Phase | Dev Type | 状态 |
+   |------|-------|----------|------|
+   | 02-10-xxx-phase-1 | Phase 1: 后端 DTO | backend | planning |
+   | 02-10-xxx-phase-2 | Phase 2: 树构建 | backend | planning |
+   | 02-10-xxx-phase-3 | Phase 3: API 端点 | backend | planning |
+   | ... | ... | ... | ... |
+   
+   ```
+
+7. **Context Checkpoint**
+   - Report current context usage.
+   - If approaching 80K tokens, suggest: "Run `/clear` and start executing tasks"
+
+**Exit Criteria**
+A change is ready for implementation only when:
+- [ ] All multi-model analyses completed and synthesized
+- [ ] Zero ambiguities remain (verified by step 3 audit)
+- [ ] All PBT properties documented with falsification strategies
+- [ ] Artifacts (specs, design, tasks) generated via OpenSpec skills
+- [ ] **tasks.md 包含单元测试和集成测试任务**（无"后续补充"标记）
+- [ ] **Trellis Tasks 已创建**（每个 Phase 一个 Task）
+- [ ] User has explicitly approved all constraint decisions
+
+**Reference**
+- Inspect change: `/opsx:status <id>`
+- Check conflicts: `/opsx:schemas`
+- Search patterns: `rg -n "INVARIANT:|PROPERTY:" openspec/`
+- List tasks: `./.trellis/scripts/task.sh list`
+- Use `AskUserQuestion` for ANY ambiguity—never assume
+<!-- CCG:SPEC:PLAN-NEW:END -->