cc-devflow 1.0.1

package/.claude/hooks/skill-activation-prompt.sh

@@ -0,0 +1,36 @@
+#!/bin/bash
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# 技能自动激活 Hook - Bash 包装器
+# ═══════════════════════════════════════════════════════════════════════════════
+#
+# 【核心功能】
+# Bash 脚本包装器，调用 TypeScript 实现的技能激活逻辑
+#
+# 【工作原理】
+# 1. 切换到 hooks 目录
+# 2. 通过管道传递 stdin 到 TypeScript 脚本
+# 3. 使用 npx tsx 运行 TypeScript（无需编译）
+#
+# 【为什么需要这个包装器？】
+# - Claude Code hooks 必须是可执行的 shell 脚本
+# - 此脚本负责设置环境并调用实际的 TypeScript 实现
+#
+# 【设计原则】
+# KISS - Keep It Simple, Stupid
+# 包装器只做一件事：调用 TypeScript 实现
+#
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# 错误时立即退出
+set -e
+
+# 切换到 hooks 目录（确保能找到 TypeScript 文件）
+cd "$CLAUDE_PROJECT_DIR/.claude/hooks"
+
+# 通过管道传递 stdin 到 TypeScript 脚本
+# - cat: 读取 stdin
+# - |: 管道传递
+# - npx tsx: 直接运行 TypeScript（无需 tsc 编译）
+# - skill-activation-prompt.ts: TypeScript 实现
+cat | npx tsx skill-activation-prompt.ts

package/.claude/hooks/skill-activation-prompt.ts

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// 技能自动激活 Hook - TypeScript 实现
+// ═══════════════════════════════════════════════════════════════════════════════
+//
+// 【核心功能】
+// 在用户每次提交 prompt 时自动分析并建议相关技能
+//
+// 【工作原理】
+// 1. 读取用户输入的 prompt
+// 2. 加载 skill-rules.json 配置文件
+// 3. 根据关键词和意图模式匹配技能
+// 4. 按优先级分组并输出建议
+//
+// 【设计哲学】
+// "工具应该适应人的思维，而不是让人适应工具"
+// 技能在你需要时激活，而不是在你记得时激活
+//
+// ═══════════════════════════════════════════════════════════════════════════════
+
+import { readFileSync } from 'fs';
+import { join } from 'path';
+
+// ───────────────────────────────────────────────────────────────────────────────
+// 类型定义
+// ───────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Hook 输入接口
+ * Claude Code 传递给 UserPromptSubmit hook 的数据结构
+ */
+interface HookInput {
+    session_id: string;        // 会话 ID
+    transcript_path: string;   // 对话记录路径
+    cwd: string;               // 当前工作目录
+    permission_mode: string;   // 权限模式
+    prompt: string;            // 用户输入的提示词
+}
+
+/**
+ * 提示触发器配置
+ * 定义如何通过用户输入触发技能
+ */
+interface PromptTriggers {
+    keywords?: string[];        // 关键词列表（精确匹配）
+    intentPatterns?: string[];  // 意图模式列表（正则表达式）
+}
+
+/**
+ * 技能规则配置
+ * 定义单个技能的激活条件和优先级
+ */
+interface SkillRule {
+    type: 'guardrail' | 'domain';                    // 技能类型：护栏 | 领域
+    enforcement: 'block' | 'suggest' | 'warn';       // 强制级别：阻塞 | 建议 | 警告
+    priority: 'critical' | 'high' | 'medium' | 'low'; // 优先级
+    promptTriggers?: PromptTriggers;                  // 提示触发器
+}
+
+/**
+ * 技能规则集合
+ * skill-rules.json 的根数据结构
+ */
+interface SkillRules {
+    version: string;                    // 规则版本
+    skills: Record<string, SkillRule>;  // 技能名称 -> 规则配置
+}
+
+/**
+ * 匹配到的技能
+ * 内部使用，记录匹配结果
+ */
+interface MatchedSkill {
+    name: string;                          // 技能名称
+    matchType: 'keyword' | 'intent';       // 匹配类型：关键词 | 意图
+    config: SkillRule;                     // 技能配置
+}
+
+// ───────────────────────────────────────────────────────────────────────────────
+// 主函数
+// ───────────────────────────────────────────────────────────────────────────────
+
+async function main() {
+    try {
+        // ┌─────────────────────────────────────────────────────────────────────┐
+        // │ 步骤 1: 读取输入                                                      │
+        // └─────────────────────────────────────────────────────────────────────┘
+        // 从 stdin 读取 Claude Code 传递的 JSON 数据
+        const input = readFileSync(0, 'utf-8');
+        const data: HookInput = JSON.parse(input);
+        const prompt = data.prompt.toLowerCase(); // 转小写便于匹配
+
+        // ┌─────────────────────────────────────────────────────────────────────┐
+        // │ 步骤 2: 加载技能规则配置                                              │
+        // └─────────────────────────────────────────────────────────────────────┘
+        const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+        const rulesPath = join(projectDir, '.claude', 'skills', 'skill-rules.json');
+        const rules: SkillRules = JSON.parse(readFileSync(rulesPath, 'utf-8'));
+
+        // 存储匹配到的技能
+        const matchedSkills: MatchedSkill[] = [];
+
+        // ┌─────────────────────────────────────────────────────────────────────┐
+        // │ 步骤 3: 遍历所有技能，检查是否匹配                                     │
+        // └─────────────────────────────────────────────────────────────────────┘
+        for (const [skillName, config] of Object.entries(rules.skills)) {
+            const triggers = config.promptTriggers;
+
+            // 如果没有配置触发器，跳过此技能
+            if (!triggers) {
+                continue;
+            }
+
+            // ┌───────────────────────────────────────────────────────────────┐
+            // │ 3.1 关键词匹配                                                 │
+            // └───────────────────────────────────────────────────────────────┘
+            // 检查 prompt 中是否包含配置的关键词
+            if (triggers.keywords) {
+                const keywordMatch = triggers.keywords.some(kw =>
+                    prompt.includes(kw.toLowerCase())
+                );
+                if (keywordMatch) {
+                    matchedSkills.push({ name: skillName, matchType: 'keyword', config });
+                    continue; // 匹配到就继续下一个技能
+                }
+            }
+
+            // ┌───────────────────────────────────────────────────────────────┐
+            // │ 3.2 意图模式匹配                                               │
+            // └───────────────────────────────────────────────────────────────┘
+            // 使用正则表达式匹配更复杂的意图模式
+            if (triggers.intentPatterns) {
+                const intentMatch = triggers.intentPatterns.some(pattern => {
+                    const regex = new RegExp(pattern, 'i'); // 'i' = 忽略大小写
+                    return regex.test(prompt);
+                });
+                if (intentMatch) {
+                    matchedSkills.push({ name: skillName, matchType: 'intent', config });
+                }
+            }
+        }
+
+        // ┌─────────────────────────────────────────────────────────────────────┐
+        // │ 步骤 4: 生成输出（如果有匹配）                                         │
+        // └─────────────────────────────────────────────────────────────────────┘
+        if (matchedSkills.length > 0) {
+            let output = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n';
+            output += '🎯 SKILL ACTIVATION CHECK\n';
+            output += '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n';
+
+            // ┌───────────────────────────────────────────────────────────────┐
+            // │ 4.1 按优先级分组                                               │
+            // └───────────────────────────────────────────────────────────────┘
+            const critical = matchedSkills.filter(s => s.config.priority === 'critical');
+            const high = matchedSkills.filter(s => s.config.priority === 'high');
+            const medium = matchedSkills.filter(s => s.config.priority === 'medium');
+            const low = matchedSkills.filter(s => s.config.priority === 'low');
+
+            // ┌───────────────────────────────────────────────────────────────┐
+            // │ 4.2 输出各优先级的技能                                         │
+            // └───────────────────────────────────────────────────────────────┘
+
+            // 关键技能（必需）
+            if (critical.length > 0) {
+                output += '⚠️ CRITICAL SKILLS (REQUIRED):\n';
+                critical.forEach(s => output += `  → ${s.name}\n`);
+                output += '\n';
+            }
+
+            // 推荐技能
+            if (high.length > 0) {
+                output += '📚 RECOMMENDED SKILLS:\n';
+                high.forEach(s => output += `  → ${s.name}\n`);
+                output += '\n';
+            }
+
+            // 建议技能
+            if (medium.length > 0) {
+                output += '💡 SUGGESTED SKILLS:\n';
+                medium.forEach(s => output += `  → ${s.name}\n`);
+                output += '\n';
+            }
+
+            // 可选技能
+            if (low.length > 0) {
+                output += '📌 OPTIONAL SKILLS:\n';
+                low.forEach(s => output += `  → ${s.name}\n`);
+                output += '\n';
+            }
+
+            // 操作提示
+            output += 'ACTION: Use Skill tool BEFORE responding\n';
+            output += '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n';
+
+            // 输出到 stdout（Claude Code 会捕获并显示给用户）
+            console.log(output);
+        }
+
+        process.exit(0); // 成功退出
+    } catch (err) {
+        // 错误处理：输出错误信息到 stderr
+        console.error('Error in skill-activation-prompt hook:', err);
+        process.exit(1); // 错误退出
+    }
+}
+
+// ───────────────────────────────────────────────────────────────────────────────
+// 程序入口
+// ───────────────────────────────────────────────────────────────────────────────
+main().catch(err => {
+    console.error('Uncaught error:', err);
+    process.exit(1);
+});

package/.claude/hooks/state/skills-used-test-guard.json

@@ -0,0 +1,3 @@
+[
+  "devflow-tdd-enforcer"
+]

package/.claude/rules/devflow-conventions.md

@@ -0,0 +1,305 @@
+# CC-DevFlow 工作流约定
+
+> **类型**: 工作流约定 (Workflow Conventions)
+> **适用**: CC-DevFlow 需求开发流程
+> **层级**: Rules Layer (具体约定和格式)
+> **前置**: 遵循 Constitution 和 Core Patterns
+
+---
+
+## 🎯 核心约定
+
+### REQ-ID 格式规范
+- **格式**: `REQ-\d+` (例如: REQ-123, REQ-001)
+- **唯一性**: 在当前仓库范围内必须唯一
+- **禁止**: 重复使用已存在的 REQ-ID
+
+### 命令参数格式
+```bash
+# 标准格式
+/flow-new "REQ-123|支持用户下单|https://plan.example.com/Q1"
+
+# 多文档格式
+/flow-new "REQ-124|权限管理|https://spec.doc,https://api.doc"
+
+# 无外部文档
+/flow-new "REQ-125|数据导出"
+```
+
+---
+
+## 📁 文件组织约定
+
+### 目录结构
+```text
+devflow/requirements/${reqId}/
+├── PRD.md                      # 产品需求文档
+├── UI_PROTOTYPE.html           # UI原型 ⚡️ 条件生成 (仅UI需求)
+├── EPIC.md                     # Epic 规划
+├── TASKS.md                    # 任务分解 (单文件管理所有任务)
+├── tasks/                      # 任务执行标记
+│   ├── TASK_001.completed      # 任务完成标记
+│   ├── TASK_002.completed
+│   └── IMPLEMENTATION_PLAN.md  # dev-implementer 输出
+├── research/                   # 研究资料
+│   ├── ${reqId}_plan_1.md
+│   ├── ${reqId}_plan_2.md
+│   └── ui_design_strategy.md   # UI设计策略 (可选)
+├── TEST_PLAN.md                # 测试计划
+├── TEST_REPORT.md              # 测试报告
+├── SECURITY_PLAN.md            # 安全计划
+├── SECURITY_REPORT.md          # 安全报告
+├── RELEASE_PLAN.md             # 发布计划
+└── EXECUTION_LOG.md            # 执行日志
+```
+
+### 文档命名约定
+- **PRD 文件**: `PRD.md`
+- **Epic 文件**: `EPIC.md`
+- **Tasks 文件**: `TASKS.md` (所有任务集中在一个文件)
+- **任务完成标记**: `tasks/TASK_{ID}.completed` (空文件)
+- **研究文件**: `${reqId}_plan_{序号}.md`
+- **测试报告**: `TEST_REPORT.md`
+- **执行日志**: `EXECUTION_LOG.md`
+
+---
+
+## 🌿 Git 分支约定
+
+### 分支命名
+```bash
+# 标准格式
+feature/${reqId}-${slug(title)}
+
+# 示例
+feature/REQ-123-user-order-support
+feature/REQ-124-permission-management
+```
+
+### 分支操作流程
+1. 检查当前在 main 分支且状态干净
+2. 创建特性分支
+3. 实施开发 (TDD方式)
+4. 质量闸检查
+5. 创建 PR
+6. 合并后清理分支
+
+---
+
+## 💬 提交信息约定
+
+### 提交格式
+```text
+{type}({reqId}): {taskTitle}
+
+{详细描述}
+
+- 实现功能点1
+- 实现功能点2
+
+Co-authored-by: Claude <claude@anthropic.com>
+```
+
+### 提交类型
+- `feat(REQ-xxx)`: 新功能
+- `fix(REQ-xxx)`: 错误修复
+- `docs(REQ-xxx)`: 文档更新
+- `test(REQ-xxx)`: 测试添加/修改
+- `refactor(REQ-xxx)`: 重构
+- `chore(REQ-xxx)`: 构建、配置等杂务
+
+---
+
+## 🤖 子代理调用约定
+
+### 调用顺序 (7个阶段)
+```text
+1. flow-init      → 初始化需求结构
+   ↓
+2. flow-prd       → prd-writer (研究型) → PRD.md
+   ↓
+2.5 flow-ui       → ui-designer (研究型) → UI_PROTOTYPE.html ⚡️ 条件触发
+   ↓              仅在检测到UI需求时自动执行
+3. flow-epic      → planner (研究型) → EPIC.md + TASKS.md
+   ↓              如存在UI_PROTOTYPE.html, 自动集成UI上下文
+4. flow-dev       → dev-implementer (研究型, 每个任务) → IMPLEMENTATION_PLAN.md
+                  → main-agent (执行型) → 代码实现
+   ↓              前端任务会引用UI_PROTOTYPE.html
+5. flow-qa        → qa-tester (研究型) → TEST_PLAN.md
+                  → security-reviewer (研究型) → SECURITY_PLAN.md
+                  → main-agent (执行型) → 运行测试、安全扫描
+   ↓
+6. flow-release   → release-manager (研究型) → RELEASE_PLAN.md
+                  → main-agent (执行型) → 创建PR、合并
+```
+
+### 状态同步约定
+- 每个阶段完成后更新 `orchestration_status.json`
+- 每个任务完成后创建 `tasks/TASK_{ID}.completed`
+- 所有重要操作记录到 `EXECUTION_LOG.md`
+
+---
+
+## ⚠️ 错误处理约定
+
+### 错误分类
+1. **参数错误**: 命令格式、REQ-ID 格式等
+2. **环境错误**: Git状态、权限、依赖等
+3. **网络错误**: URL访问失败
+4. **质量闸错误**: 代码质量不达标
+5. **系统错误**: 子代理异常、文件操作失败
+
+### 错误恢复命令
+```bash
+# 从特定阶段继续
+/flow-restart "REQ-123" --from=prd
+/flow-restart "REQ-123" --from=dev
+/flow-restart "REQ-123" --from=qa
+```
+
+### 错误日志格式
+```yaml
+---
+error_type: parameter_error
+timestamp: 2024-01-15T10:30:00Z
+req_id: REQ-123
+step: parameter_parsing
+---
+
+# 错误详情
+参数格式不正确：缺少标题部分
+
+## 解决方案
+请使用正确格式：/flow-new "REQ-123|需求标题|计划URL"
+```
+
+---
+
+## 📊 文档元数据约定
+
+### YAML Frontmatter 格式
+```yaml
+---
+req_id: "REQ-123"
+title: "支持用户下单"
+created_at: "2024-01-15T10:00:00Z"
+updated_at: "2024-01-15T15:30:00Z"
+version: "1.0.0"
+status: "completed"
+author: "prd-writer"
+---
+```
+
+---
+
+## 🎯 性能指标约定
+
+### 时间要求
+- **整个流程**: 90% 情况下在 15 分钟内完成
+- **单个任务**: 实施时间不超过 5 分钟
+- **质量闸检查**: 不超过 2 分钟
+
+### 资源约束
+- **内存占用**: < 500MB (峰值)
+- **并发需求**: 支持 3 个并发需求
+- **文档数量**: 支持 1000 个需求文档
+
+---
+
+## ⚙️ 配置约定
+
+### .claude/settings.json 配置项
+```json
+{
+  "devflow": {
+    "baseBranch": "main",
+    "autoApprove": false,
+    "qualityGate": {
+      "minCoverage": 80,
+      "strictMode": true
+    },
+    "templates": {
+      "customPrdTemplate": ".claude/templates/custom-prd.md"
+    }
+  }
+}
+```
+
+### 环境变量
+```bash
+# 调试模式
+export FLOW_DEBUG=1
+
+# 超时设置 (秒)
+export FLOW_TIMEOUT=300
+
+# 最小测试覆盖率
+export MIN_COVERAGE=80
+```
+
+---
+
+## 🔧 工具集成约定
+
+### 钩子脚本
+- `pre-push-guard.sh`: 推送前质量检查
+- `markdown_formatter.py`: 文档格式化
+- `auto-progress-update.py`: 进度自动更新
+
+### 测试脚本
+- `.claude/tests/run-all-tests.sh`: 运行所有测试
+- `.claude/tests/scripts/test_*.sh`: 单个测试套件
+
+---
+
+## 🛠️ 故障排除约定
+
+### 环境检查
+```bash
+# 检查 Git 状态
+git status
+
+# 检查 GitHub CLI
+gh auth status
+
+# 检查 npm 脚本
+npm run --silent
+
+# 检查权限
+ls -la .claude/
+```
+
+### 日志查看
+```bash
+# 查看执行日志
+tail -f devflow/requirements/REQ-123/EXECUTION_LOG.md
+
+# 查看错误日志
+tail -f .claude/logs/flow-*.log
+```
+
+---
+
+## 📋 最佳实践清单
+
+### 开始新需求前
+- [ ] 确认 REQ-ID 唯一性
+- [ ] 准备完整的需求输入 (标题 + 可选URL)
+- [ ] 确保 Git 工作目录干净
+- [ ] 在 main 分支上启动
+
+### 开发过程中
+- [ ] 遵循 TDD 顺序 (Tests First → Implementation)
+- [ ] 每个任务完成后立即提交
+- [ ] 定期同步主分支
+- [ ] 及时更新文档
+
+### 发布前检查
+- [ ] 所有测试通过
+- [ ] 测试覆盖率 ≥ 80%
+- [ ] 安全扫描无高危问题
+- [ ] 文档完整且格式正确
+
+---
+
+**重要提示**: 所有约定都是强制性的。这些约定确保 CC-DevFlow 工作流的一致性和可预测性。