ccgx-workflow 1.0.0

package/templates/commands/workflow.md

@@ -0,0 +1,190 @@
+---
+description: '多模型协作开发工作流（研究→构思→计划→执行→优化→评审），智能路由前端→{{FRONTEND_PRIMARY}}、后端→{{BACKEND_PRIMARY}}'
+context_budget: orchestrator-15
+subagent_freshness: required
+---
+
+# Workflow - 多模型协作开发
+
+使用质量把关、MCP 服务和多模型协作执行结构化开发工作流。
+
+## 使用方法
+
+```bash
+/workflow <任务描述>
+```
+
+## 上下文
+
+- 要开发的任务：$ARGUMENTS
+- 带质量把关的结构化 6 阶段工作流
+- 多模型协作：{{BACKEND_PRIMARY}}（后端）+ {{FRONTEND_PRIMARY}}（前端）+ Claude（编排）
+- MCP 服务集成（ace-tool）以增强功能
+
+## 你的角色
+
+你是**编排者**，协调多模型协作系统（研究 → 构思 → 计划 → 执行 → 优化 → 评审），用中文协助用户，面向专业程序员，交互应简洁专业，避免不必要解释。
+
+**协作模型**：
+- **{{BACKEND_PRIMARY}}** – 后端逻辑、算法、调试（**后端权威，可信赖**）
+- **{{FRONTEND_PRIMARY}}** – 前端 UI/UX、视觉设计（**前端高手，后端意见仅供参考**）
+- **Claude (自己)** – 编排、计划、执行、交付
+
+---
+
+## 多模型调用规范
+
+**工作目录**：
+- `{{WORKDIR}}`：**必须通过 Bash 执行 `pwd`（Unix）或 `cd`（Windows CMD）获取当前工作目录的绝对路径**，禁止从 `$HOME` 或环境变量推断
+- 如果用户通过 `/add-dir` 添加了多个工作区，先用 Glob/Grep 确定任务相关的工作区
+- 如果无法确定，用 `AskUserQuestion` 询问用户选择目标工作区
+
+**调用语法**（并行用 `run_in_background: true`，串行用 `false`）：
+
+```
+# 新会话调用
+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: "简短描述"
+})
+
+# 复用会话调用
+Bash({
+  command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--progress --backend <{{BACKEND_PRIMARY}}|{{FRONTEND_PRIMARY}}> {{GEMINI_MODEL_FLAG}}resume <SESSION_ID> - \"{{WORKDIR}}\" <<'EOF'
+ROLE_FILE: <角色提示词路径>
+<TASK>
+需求：<增强后的需求（如未增强则用 $ARGUMENTS）>
+上下文：<前序阶段收集的项目上下文、分析结果等>
+</TASK>
+OUTPUT: 期望输出格式
+EOF",
+  run_in_background: true,
+  timeout: 3600000,
+  description: "简短描述"
+})
+```
+
+**角色提示词**：
+
+| 阶段 | 后端 | 前端 |
+|------|-------|--------|
+| 分析 | `~/.claude/.ccg/prompts/{{BACKEND_PRIMARY}}/analyzer.md` | `~/.claude/.ccg/prompts/{{FRONTEND_PRIMARY}}/analyzer.md` |
+| 规划 | `~/.claude/.ccg/prompts/{{BACKEND_PRIMARY}}/architect.md` | `~/.claude/.ccg/prompts/{{FRONTEND_PRIMARY}}/architect.md` |
+| 审查 | `~/.claude/.ccg/prompts/{{BACKEND_PRIMARY}}/reviewer.md` | `~/.claude/.ccg/prompts/{{FRONTEND_PRIMARY}}/reviewer.md` |
+
+**会话复用**：每次调用返回 `SESSION_ID: xxx`，后续阶段用 `resume xxx` 复用上下文（注意：是 `resume`，不是 `--resume`）。
+
+**并行调用 + 事件驱动等待（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. 响应以模式标签 `[模式：X]` 开始，初始为 `[模式：研究]`。
+2. 核心工作流严格按 `研究 → 构思 → 计划 → 执行 → 优化 → 评审` 顺序流转。
+3. 每个阶段完成后必须请求用户确认。
+4. 评分低于 7 分或用户未批准时强制停止。
+5. 在需要询问用户时，尽量使用 `AskUserQuestion` 工具进行交互，举例场景：请求用户确认/选择/批准
+
+---
+
+## 执行工作流
+
+**任务描述**：$ARGUMENTS
+
+### 🔍 阶段 1：研究与分析
+
+`[模式：研究]` - 理解需求并收集上下文：
+
+1. **Prompt 增强**（按 `/ccg:enhance` 的逻辑执行）：分析 $ARGUMENTS 的意图、缺失信息、隐含假设，补全为结构化需求（明确目标、技术约束、范围边界、验收标准），**用增强结果替代原始 $ARGUMENTS，后续调用后端/前端模型 时传入增强后的需求**
+2. **上下文检索**：调用 `{{MCP_SEARCH_TOOL}}`
+3. **需求完整性评分**（0-10 分）：
+   - 目标明确性（0-3）、预期结果（0-3）、边界范围（0-2）、约束条件（0-2）
+   - ≥7 分：继续 | <7 分：⛔ 停止，提出补充问题
+
+### 💡 阶段 2：方案构思
+
+`[模式：构思]` - 多模型并行分析：
+
+**并行调用**（`run_in_background: true`）：
+- {{BACKEND_PRIMARY}}：使用分析提示词，输出技术可行性、方案、风险
+- {{FRONTEND_PRIMARY}}：使用分析提示词，输出 UI 可行性、方案、体验
+
+用 `TaskOutput` 等待结果。**📌 保存 SESSION_ID**（`CODEX_SESSION` 和 `GEMINI_SESSION`）。
+
+**务必遵循上方 `多模型调用规范` 的 `重要` 指示**
+
+综合两方分析，输出方案对比（至少 2 个方案），等待用户选择。
+
+### 📋 阶段 3：详细规划
+
+`[模式：计划]` - 多模型协作规划：
+
+**并行调用**（复用会话）：
+- {{BACKEND_PRIMARY}}：使用规划提示词 + `resume $CODEX_SESSION`，输出后端架构
+- {{FRONTEND_PRIMARY}}：使用规划提示词 + `resume $GEMINI_SESSION`，输出前端架构
+
+用 `TaskOutput` 等待结果。
+
+**务必遵循上方 `多模型调用规范` 的 `重要` 指示**
+
+**Claude 综合规划**：采纳 {{BACKEND_PRIMARY}} 后端规划 + {{FRONTEND_PRIMARY}} 前端规划，用户批准后存入 `.claude/plan/任务名.md`
+
+### ⚡ 阶段 4：实施
+
+`[模式：执行]` - 代码开发：
+
+- 严格按批准的计划实施
+- 遵循项目现有代码规范
+- 在关键里程碑请求反馈
+
+### 🚀 阶段 5：代码优化
+
+`[模式：优化]` - 多模型并行审查：
+
+**并行调用**：
+- {{BACKEND_PRIMARY}}：使用审查提示词，关注安全、性能、错误处理
+- {{FRONTEND_PRIMARY}}：使用审查提示词，关注可访问性、设计一致性
+
+用 `TaskOutput` 等待结果。整合审查意见，用户确认后执行优化。
+
+**务必遵循上方 `多模型调用规范` 的 `重要` 指示**
+
+### ✅ 阶段 6：质量审查
+
+`[模式：评审]` - 最终评估：
+
+- 对照计划检查完成情况
+- 运行测试验证功能
+- 报告问题与建议
+- 请求最终用户确认
+
+---
+
+## 关键规则
+
+1. 阶段顺序不可跳过（除非用户明确指令）
+2. 外部模型对文件系统**零写入权限**，所有修改由 Claude 执行
+3. 评分 <7 或用户未批准时**强制停止**

package/templates/commands/worktree.md

@@ -0,0 +1,128 @@
+---
+description: '管理 Git Worktree：在 ../.ccg/项目名/ 目录创建，支持 IDE 集成和内容迁移'
+---
+
+# Worktree - Git Worktree 管理
+
+在结构化目录管理 Git worktree，支持智能默认和 IDE 集成。
+
+## 使用方法
+
+```bash
+/worktree <add|list|remove|prune|migrate> [options]
+```
+
+## 子命令
+
+| 命令 | 说明 |
+|------|------|
+| `add <path>` | 创建新 worktree |
+| `list` | 列出所有 worktree |
+| `remove <path>` | 删除指定 worktree |
+| `prune` | 清理无效引用 |
+| `migrate <target>` | 迁移内容到目标 worktree |
+
+## 选项
+
+| 选项 | 说明 |
+|------|------|
+| `-b <branch>` | 创建新分支 |
+| `-o, --open` | 创建后用 IDE 打开 |
+| `--from <source>` | 迁移源路径 |
+| `--stash` | 迁移 stash 内容 |
+| `--track` | 跟踪远程分支 |
+| `--detach` | 分离 HEAD |
+| `--lock` | 锁定 worktree |
+
+---
+
+## 目录结构
+
+```
+parent-directory/
+├── your-project/           # 主项目
+│   ├── .git/
+│   └── src/
+└── .ccg/                   # worktree 管理目录
+    └── your-project/
+        ├── feature-ui/     # 功能分支
+        ├── hotfix/         # 修复分支
+        └── debug/          # 调试 worktree
+```
+
+---
+
+## 执行工作流
+
+### Add - 创建 Worktree
+
+`[模式：创建]`
+
+1. 验证 Git 仓库
+2. 计算路径：`../.ccg/项目名/<path>`
+3. 创建 worktree
+4. 自动复制环境文件（`.env` 等）
+5. 可选：用 IDE 打开
+
+### Migrate - 迁移内容
+
+`[模式：迁移]`
+
+1. 验证源有未提交内容
+2. 确保目标干净
+3. 显示即将迁移的改动
+4. 安全迁移
+5. 确认结果
+
+---
+
+## 示例
+
+```bash
+# 基本创建
+/worktree add feature-ui
+
+# 创建并用 IDE 打开
+/worktree add feature-ui -o
+
+# 创建指定分支
+/worktree add hotfix -b fix/login -o
+
+# 迁移未提交内容
+/worktree migrate feature-ui --from main
+
+# 迁移 stash 内容
+/worktree migrate feature-ui --stash
+
+# 管理操作
+/worktree list
+/worktree remove feature-ui
+/worktree prune
+```
+
+## 输出示例
+
+```
+✅ Worktree created at ../.ccg/项目名/feature-ui
+✅ 已复制 .env
+✅ 已复制 .env.local
+📋 已从 .gitignore 复制 2 个环境文件
+🖥️ 是否在 IDE 中打开？[y/n]: y
+🚀 正在用 VS Code 打开...
+```
+
+---
+
+## 智能特性
+
+1. **智能默认** – 未指定分支时使用路径名
+2. **IDE 集成** – 自动检测 VS Code / Cursor / WebStorm
+3. **环境文件** – 自动复制 `.gitignore` 中的 `.env` 文件
+4. **路径安全** – 始终使用绝对路径防止嵌套问题
+5. **分支保护** – 验证分支未被其他地方使用
+
+## 注意事项
+
+- Worktree 共享 `.git` 目录，节省磁盘空间
+- 迁移仅限未提交改动，已提交内容用 `git cherry-pick`
+- 支持 Windows、macOS、Linux

package/templates/hooks/ccg-context-monitor.js

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+// ccg-hook: context-monitor
+// Context Monitor - PostToolUse hook for CCG Workflow.
+// Reads context metrics from the statusline bridge file and injects warnings
+// into the agent's conversation when context usage is high. This makes the
+// AGENT itself aware of context limits (the statusline only shows the user).
+//
+// How it works:
+// 1. ccg-statusline.js writes metrics to {os.tmpdir()}/claude-ctx-{session_id}.json
+// 2. This hook reads those metrics after each tool use
+// 3. When remaining context drops below thresholds, it injects a warning
+//    as additionalContext, which the agent sees on its next turn
+//
+// Thresholds:
+//   WARNING  (remaining <= 35%): Agent should wrap up current task
+//   CRITICAL (remaining <= 25%): Agent should stop immediately and inform user
+//
+// Debounce: 5 tool uses between warnings to avoid spam.
+// Severity escalation (WARNING -> CRITICAL) bypasses debounce so the user
+// always sees the elevated alert.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const WARNING_THRESHOLD = 35;  // remaining_percentage <= 35%
+const CRITICAL_THRESHOLD = 25; // remaining_percentage <= 25%
+const STALE_SECONDS = 60;      // ignore metrics older than 60s
+const DEBOUNCE_CALLS = 5;      // min tool uses between warnings
+
+let input = '';
+// Timeout guard: if stdin doesn't close within 10s (e.g. pipe issues on
+// Windows/Git Bash, or slow Claude Code piping during large outputs),
+// exit silently instead of hanging until Claude Code kills the process
+// and reports "hook error".
+const stdinTimeout = setTimeout(() => process.exit(0), 10000);
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  clearTimeout(stdinTimeout);
+  try {
+    const data = JSON.parse(input);
+    const sessionId = data.session_id;
+
+    if (!sessionId) {
+      process.exit(0);
+    }
+
+    // Reject session IDs that contain path traversal sequences or path separators.
+    // session_id is used to construct file paths in tmp — an unsanitized value
+    // could escape the temp directory and read or write arbitrary files.
+    if (/[/\\]|\.\./.test(sessionId)) {
+      process.exit(0);
+    }
+
+    // Per-project opt-out via .ccg/config.json:
+    //   { "hooks": { "context_warnings": false } }
+    // Quick sentinel check: skip config read entirely for non-CCG projects.
+    const cwd = data.cwd || process.cwd();
+    const ccgDir = path.join(cwd, '.ccg');
+    if (fs.existsSync(ccgDir)) {
+      try {
+        const configPath = path.join(ccgDir, 'config.json');
+        if (fs.existsSync(configPath)) {
+          const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+          if (config.hooks?.context_warnings === false) {
+            process.exit(0);
+          }
+        }
+      } catch (e) {
+        // Ignore config read/parse errors (config is optional)
+      }
+    }
+
+    const tmpDir = os.tmpdir();
+    const metricsPath = path.join(tmpDir, `claude-ctx-${sessionId}.json`);
+
+    // If no metrics file, this is a subagent or fresh session -- exit silently
+    if (!fs.existsSync(metricsPath)) {
+      process.exit(0);
+    }
+
+    const metrics = JSON.parse(fs.readFileSync(metricsPath, 'utf8'));
+    const now = Math.floor(Date.now() / 1000);
+
+    // Ignore stale metrics
+    if (metrics.timestamp && (now - metrics.timestamp) > STALE_SECONDS) {
+      process.exit(0);
+    }
+
+    const remaining = metrics.remaining_percentage;
+    const usedPct = metrics.used_pct;
+
+    // No warning needed
+    if (remaining > WARNING_THRESHOLD) {
+      process.exit(0);
+    }
+
+    // Debounce: check if we warned recently
+    const warnPath = path.join(tmpDir, `claude-ctx-${sessionId}-warned.json`);
+    let warnData = { callsSinceWarn: 0, lastLevel: null };
+    let firstWarn = true;
+
+    if (fs.existsSync(warnPath)) {
+      try {
+        warnData = JSON.parse(fs.readFileSync(warnPath, 'utf8'));
+        firstWarn = false;
+      } catch (e) {
+        // Corrupted file, reset
+      }
+    }
+
+    warnData.callsSinceWarn = (warnData.callsSinceWarn || 0) + 1;
+
+    const isCritical = remaining <= CRITICAL_THRESHOLD;
+    const currentLevel = isCritical ? 'critical' : 'warning';
+
+    // Emit immediately on first warning, then debounce subsequent ones.
+    // Severity escalation (WARNING -> CRITICAL) bypasses debounce so the
+    // elevated alert is never missed.
+    const severityEscalated = currentLevel === 'critical' && warnData.lastLevel === 'warning';
+    if (!firstWarn && warnData.callsSinceWarn < DEBOUNCE_CALLS && !severityEscalated) {
+      // Update counter and exit without warning
+      fs.writeFileSync(warnPath, JSON.stringify(warnData));
+      process.exit(0);
+    }
+
+    // Reset debounce counter
+    warnData.callsSinceWarn = 0;
+    warnData.lastLevel = currentLevel;
+    fs.writeFileSync(warnPath, JSON.stringify(warnData));
+
+    // Build advisory warning message (advisory only — never imperative; the
+    // user, not the hook, decides how to proceed).
+    let message;
+    if (isCritical) {
+      message = `[CCG] CONTEXT CRITICAL: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
+        'Context is nearly exhausted. Inform the user that context is low and ask how they ' +
+        'want to proceed. Avoid starting new complex work, large refactors, or autonomous ' +
+        'state-saving unless the user asks for it.';
+    } else {
+      message = `[CCG] CONTEXT WARNING: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
+        'Context is getting limited. Avoid unnecessary exploration or starting new complex ' +
+        'work. Consider wrapping up the current task at the next natural stopping point.';
+    }
+
+    const output = {
+      hookSpecificOutput: {
+        hookEventName: process.env.GEMINI_API_KEY ? 'AfterTool' : 'PostToolUse',
+        additionalContext: message,
+      },
+    };
+
+    process.stdout.write(JSON.stringify(output));
+  } catch (e) {
+    // Silent fail -- never block tool execution
+    process.exit(0);
+  }
+});