ccgx-workflow 1.0.0

package/templates/commands/init.md

@@ -0,0 +1,123 @@
+---
+description: '初始化项目 AI 上下文：生成根级与模块级 CLAUDE.md 索引'
+---
+
+# Init - 初始化项目 AI 上下文
+
+以「根级简明 + 模块级详尽」策略生成项目 AI 上下文文档。
+
+## 使用方法
+
+```bash
+/init <项目摘要或名称>
+```
+
+## 上下文
+
+- 项目摘要：$ARGUMENTS
+- 生成/更新根级与模块级 `CLAUDE.md`
+- 自动生成 Mermaid 结构图和导航面包屑
+
+## 你的角色
+
+你是**协调者**，负责调用子智能体完成项目扫描与文档生成。
+
+---
+
+## 执行工作流
+
+**⚠️ 必须按以下步骤执行，使用 Task 工具调用子智能体**
+
+### 🕐 步骤 1：获取当前时间戳
+
+**必须首先调用 `get-current-datetime` 子智能体**：
+
+```
+Task({
+  subagent_type: "get-current-datetime",
+  prompt: "获取当前日期时间，用于文档时间戳",
+  description: "获取当前时间"
+})
+```
+
+等待返回时间戳后，保存为 `$TIMESTAMP` 供后续使用。
+
+### 🗺️ 步骤 1.5：codebase-mapper 4 路并行扫描（v4.0）
+
+**强制**：在调用 init-architect 之前，**必须在同一条 assistant message 中并行 spawn 4 个 `codebase-mapper`**（多 tool calls 一次发出）。每个实例只处理一个 focus，把扫描结果写到 `.context/codebase/` 下对应文件，主线只接收一行确认。
+
+| Focus | 写入文件 |
+|-------|---------|
+| `tech` | `.context/codebase/STACK.md` + `.context/codebase/INTEGRATIONS.md` |
+| `arch` | `.context/codebase/ARCHITECTURE.md` + `.context/codebase/STRUCTURE.md` |
+| `quality` | `.context/codebase/CONVENTIONS.md` + `.context/codebase/TESTING.md` |
+| `concerns` | `.context/codebase/CONCERNS.md` |
+
+**调用示例**（同一 message，4 个 Task tool calls 并发）：
+
+```
+Task({ subagent_type: "codebase-mapper", prompt: "focus=tech\nworkdir={{WORKDIR}}", description: "扫码栈/集成" })
+Task({ subagent_type: "codebase-mapper", prompt: "focus=arch\nworkdir={{WORKDIR}}", description: "扫架构/结构" })
+Task({ subagent_type: "codebase-mapper", prompt: "focus=quality\nworkdir={{WORKDIR}}", description: "扫规范/测试" })
+Task({ subagent_type: "codebase-mapper", prompt: "focus=concerns\nworkdir={{WORKDIR}}", description: "扫技术债" })
+```
+
+等 4 个实例全部返回 `WROTE: ... | FOCUS: ... | EVIDENCE_COUNT: ...` 单行确认后再进入步骤 2。**不要把扫描内容拉进主线 context**——init-architect 步骤会按需 Read `.context/codebase/*.md`，避免重复探索。
+
+### 🏗️ 步骤 2：调用初始化架构师
+
+**使用 `init-architect` 子智能体执行完整扫描**：
+
+```
+Task({
+  subagent_type: "init-architect",
+  prompt: "扫描项目并生成 CLAUDE.md 文档。\n\n项目摘要：$ARGUMENTS\n当前时间戳：$TIMESTAMP\n工作目录：{{WORKDIR}}\n\n请执行：\n1. 阶段 A：全仓清点（文件统计、模块识别）\n2. 阶段 B：模块优先扫描（入口、接口、依赖、测试）\n3. 阶段 C：深度补捞（按需）\n4. 阶段 D：生成文档（根级 + 模块级 CLAUDE.md）\n\n输出覆盖率报告与推荐下一步。",
+  description: "初始化项目文档"
+})
+```
+
+### 📊 步骤 3：汇总结果
+
+子智能体完成后，向用户展示：
+
+```markdown
+## 初始化结果摘要
+
+### 根级文档
+- 状态：[创建/更新]
+- 主要栏目：<列表>
+
+### 模块识别
+- 识别模块数：X
+- 模块列表：
+  1. <模块路径>
+  2. ...
+
+### 覆盖率
+- 已扫描文件：X / Y
+- 覆盖模块：X%
+- 跳过原因：<如有>
+
+### 生成内容
+- ✅ Mermaid 结构图
+- ✅ N 个模块导航面包屑
+
+### 推荐下一步
+- [ ] 补扫：<路径>
+```
+
+---
+
+## 安全边界
+
+1. **只读/写文档** – 不改源代码
+2. **忽略生成物** – 跳过 `node_modules`、`dist`、二进制文件
+3. **增量更新** – 重复运行时做断点续扫
+
+## 关键规则
+
+1. **必须使用 Task 工具**调用子智能体，不要自己执行扫描逻辑
+2. 先调用 `get-current-datetime` 获取时间戳
+3. 然后 4 路并行 spawn `codebase-mapper`（focus=tech/arch/quality/concerns），写入 `.context/codebase/*.md`
+4. 再调用 `init-architect` 执行完整扫描（可 Read mapper 产出避免重复探索）
+5. 结果在主对话打印摘要，全文由子智能体写入仓库

package/templates/commands/optimize.md

@@ -0,0 +1,217 @@
+---
+description: '多模型性能优化：{{BACKEND_PRIMARY}} 后端优化 + {{FRONTEND_PRIMARY}} 前端优化'
+argument-hint: "<优化目标> [--role=architect|critic|implementer|tester|writer]"
+---
+
+# Optimize - 多模型性能优化
+
+双模型并行分析性能瓶颈，按性价比排序优化建议。
+
+## 使用方法
+
+```bash
+/optimize <优化目标> [--role=<name>]
+```
+
+## Role-based routing（v4.1 specialist matrix）
+
+可选 `--role=<name>` 叠加 role 维度路由：
+
+| Role × Layer  | architect      | critic              | implementer | tester        | writer          |
+| ------------- | -------------- | ------------------- | ----------- | ------------- | --------------- |
+| **backend**   | codex/architect.md | codex/reviewer.md (adversarial) | codex/architect.md | codex/tester.md | claude  |
+| **frontend**  | gemini/architect.md | gemini/reviewer.md (adversarial) | gemini/architect.md | gemini/tester.md | gemini/analyzer.md |
+| **fullstack** | codex+gemini/architect.md | both reviewer.md (adversarial) | runner 决 | runner 决 | claude |
+
+**未传 --role 时按 v4.0 双模型并行（{{BACKEND_PRIMARY}}/{{FRONTEND_PRIMARY}} optimizer.md），完全兼容**。`--role=critic` 触发"性价比反对意见"——挑战通用优化套路（如盲目缓存 / over-engineering）。详见 `src/utils/specialist-router.ts`。
+
+## 上下文
+
+- 优化目标：$ARGUMENTS
+- {{BACKEND_PRIMARY}} 专注后端性能（数据库、算法、缓存）
+- {{FRONTEND_PRIMARY}} 专注前端性能（渲染、加载、交互）
+
+## 你的角色
+
+你是**性能工程师**，编排多模型优化流程：
+- **{{BACKEND_PRIMARY}}** – 后端性能优化（**后端权威**）
+- **{{FRONTEND_PRIMARY}}** – 前端性能优化（**前端权威**）
+- **Claude (自己)** – 综合优化、实施变更
+
+---
+
+## 调用通道路由（v4.1 Phase 20，CCG codeagent 退役）
+
+CCG v4.1 把双模型并行通道从 `Bash(codeagent-wrapper)` **默认切换**为 plugin spawn：
+
+1. **优先 plugin spawn**（默认）：装了 `codex@openai-codex` + `gemini@google-gemini` plugin → 用 `Agent(subagent_type="codex:codex-rescue")` + `Agent(subagent_type="gemini:gemini-rescue")` 并行，主线接 ≤200 token 摘要。
+2. **降级 codeagent-wrapper**（v4.0 BC fallback）：plugin 未装 → fallback 到 Bash 调用，行为与 v4.0 完全一致。
+
+**判定**：preflight `Bash` 跑 `ls ~/.claude/plugins/` 看有无 `codex@*` / `gemini@*` 子目录。helper 见 `src/utils/plugin-detection.ts`。
+
+⚠️ Optimize 命令在主线 context 内，**允许** `Agent(...)`——与 subagent "禁止嵌套 spawn" 约束不冲突。
+
+---
+
+## 多模型调用规范
+
+**工作目录**：
+- `{{WORKDIR}}`：**必须通过 Bash 执行 `pwd`（Unix）或 `cd`（Windows CMD）获取当前工作目录的绝对路径**，禁止从 `$HOME` 或环境变量推断
+- 如果用户通过 `/add-dir` 添加了多个工作区，先用 Glob/Grep 确定任务相关的工作区
+- 如果无法确定，用 `AskUserQuestion` 询问用户选择目标工作区
+
+**调用语法**（v4.1 Phase 20 双通道）：
+
+**通道 A — plugin spawn（默认）**：
+
+```
+Agent({
+  subagent_type: "<codex:codex-rescue|gemini:gemini-rescue>",
+  description: "Optimize: <backend|frontend>",
+  prompt: `ROLE_FILE: <角色提示词路径>
+
+<TASK>
+需求：<增强后的需求（如未增强则用 $ARGUMENTS）>
+上下文：<目标代码、现有性能指标等>
+</TASK>
+
+OUTPUT: 性能瓶颈列表、优化方案、预期收益
+Return ≤200 token structured summary (plugin-native protocol).
+`
+})
+```
+
+并行**两个 Agent 在同一 message 内同时 spawn**。
+
+**通道 B — codeagent-wrapper fallback**（plugin 未装时降级，并行用 `run_in_background: true`）：
+
+```
+Bash({
+  command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--progress --backend <{{BACKEND_PRIMARY}}|{{FRONTEND_PRIMARY}}> {{GEMINI_MODEL_FLAG}}- \"{{WORKDIR}}\" <<'EOF'
+ROLE_FILE: <角色提示词路径>
+<TASK>
+需求：<增强后的需求（如未增强则用 $ARGUMENTS）>
+上下文：<目标代码、现有性能指标等>
+</TASK>
+OUTPUT: 性能瓶颈列表、优化方案、预期收益
+EOF",
+  run_in_background: true,
+  timeout: 3600000,
+  description: "简短描述"
+})
+```
+
+> ⚠️ 通道 B `codeagent-wrapper` 在 v4.1 已标 **deprecated**，将在 v5.0 移除。
+
+**角色提示词**：
+
+| 模型 | 提示词 |
+|------|--------|
+| 后端 | `~/.claude/.ccg/prompts/{{BACKEND_PRIMARY}}/optimizer.md` |
+| 前端 | `~/.claude/.ccg/prompts/{{FRONTEND_PRIMARY}}/optimizer.md` |
+
+**并行调用 + 事件驱动等待（v4.5.2 起）**：
+
+1. 同 message 内 spawn 多个 `Bash(run_in_background: true)` 并行任务
+2. spawn 完后主线说明已启动 task-id，**直接 turn end**，**不调 TaskOutput**
+3. Claude Code 引擎在每个 task 完成时自动发 `<task-notification>` system-reminder 触发主线新 turn
+4. 主线在新 turn 处理：从 `<output-file>` 路径 read stdout，按通道 schema parse 结果
+5. **必须等所有相关 task 都收到通知**才进入下一阶段（按 task-id 计数已收齐）
+
+⛔ **禁止**：
+- 调 `TaskOutput({block: true, timeout: 600000})` —— v4.5.1 之前的旧 freeze poll 模式，已废弃
+- 收到部分通知就跳过等其他模型
+- 主动 Kill task
+
+⚠️ **失败处理**：notification status=failed / exit ≠ 0 / stdout < 100B / JSON parse 失败 → v1.7.87 标准 2-retry / 5s / 3-attempts；3 次全失败才降级单模型继续。
+
+---
+
+## 沟通守则
+
+1. 在需要询问用户时，尽量使用 `AskUserQuestion` 工具进行交互，举例场景：请求用户确认/选择/批准
+
+---
+
+## 执行工作流
+
+**优化目标**：$ARGUMENTS
+
+### 🔍 阶段 0：Prompt 增强（可选）
+
+`[模式：准备]` - **Prompt 增强**（按 `/ccg:enhance` 的逻辑执行）：分析 $ARGUMENTS 的意图、缺失信息、隐含假设，补全为结构化需求（明确目标、技术约束、范围边界、验收标准），**用增强结果替代原始 $ARGUMENTS，后续调用后端/前端模型 时传入增强后的需求**
+
+### 🔍 阶段 1：性能基线
+
+`[模式：研究]`
+
+1. 调用 `{{MCP_SEARCH_TOOL}}` 检索目标代码（如可用）
+2. 识别性能关键路径
+3. 收集现有指标（如有）
+
+### 🔬 阶段 2：并行性能分析
+
+`[模式：分析]`
+
+**⚠️ 必须发起两个并行 Bash 调用**（参照上方调用规范）：
+
+1. **{{BACKEND_PRIMARY}} 后端分析**：`Bash({ command: "...--backend {{BACKEND_PRIMARY}}...", run_in_background: true })`
+   - ROLE_FILE: `~/.claude/.ccg/prompts/{{BACKEND_PRIMARY}}/optimizer.md`
+   - 需求：分析后端性能问题（$ARGUMENTS）
+   - OUTPUT：性能瓶颈列表、优化方案、预期收益
+
+2. **{{FRONTEND_PRIMARY}} 前端分析**：`Bash({ command: "...--backend {{FRONTEND_PRIMARY}}...", run_in_background: true })`
+   - ROLE_FILE: `~/.claude/.ccg/prompts/{{FRONTEND_PRIMARY}}/optimizer.md`
+   - 需求：分析前端性能问题（Core Web Vitals）
+   - OUTPUT：性能瓶颈列表、优化方案、预期收益
+
+事件驱动等待 (v4.5.2)：spawn 完两个 Bash bg 后主线 turn end，等 task-notification 自动唤醒。**必须等所有模型返回后才能进入下一阶段**。
+
+**务必遵循上方 `多模型调用规范` 的 `重要` 指示**
+
+### 🔀 阶段 3：优化整合
+
+`[模式：计划]`
+
+1. 收集双模型分析结果
+2. **优先级排序**：按 `影响程度 × 实施难度⁻¹` 计算性价比
+3. 请求用户确认优化方案
+
+### ⚡ 阶段 4：实施优化
+
+`[模式：执行]`
+
+用户确认后按优先级实施，确保不破坏现有功能。
+
+### ✅ 阶段 5：验证
+
+`[模式：评审]`
+
+运行测试验证功能，对比优化前后指标。
+
+---
+
+## 性能指标参考
+
+| 类型 | 指标 | 良好 | 需优化 |
+|------|------|------|--------|
+| 后端 | API 响应 | <100ms | >500ms |
+| 后端 | 数据库查询 | <50ms | >200ms |
+| 前端 | LCP | <2.5s | >4s |
+| 前端 | FID | <100ms | >300ms |
+| 前端 | CLS | <0.1 | >0.25 |
+
+## 常见优化模式
+
+**后端**：N+1→批量加载、缺索引→复合索引、重复计算→缓存、同步→异步
+
+**前端**：大 Bundle→代码分割、频繁重渲染→memo、大列表→虚拟滚动、未优化图片→WebP
+
+---
+
+## 关键规则
+
+1. **先测量后优化** – 没有数据不盲目优化
+2. **性价比优先** – 高影响 + 低难度优先
+3. **不破坏功能** – 优化不能引入 bug
+4. **信任规则** – 后端以 {{BACKEND_PRIMARY}} 为准，前端以 {{FRONTEND_PRIMARY}} 为准