cc-devflow 2.4.6 → 4.1.0

package/.claude/docs/guides/TEAM_MODE_GUIDE.md

@@ -0,0 +1,313 @@
+# Claude Team 模式使用指南
+
+> **版本**: v1.0.0
+> **日期**: 2026-02-07
+> **适用**: CC-DevFlow v4.7+
+
+---
+
+## 概述
+
+Claude Team 模式允许多个 Agent 并行协作开发，显著提升开发效率。
+
+### 核心优势
+
+| 指标 | 单 Agent | Team 模式 | 提升 |
+|------|----------|-----------|------|
+| 并行任务数 | 1 | 3-5 | +400% |
+| 需求完成时间 | 90 min | 50 min | -45% |
+| 上下文隔离 | 无 | 完全隔离 | 100% |
+
+---
+
+## 快速开始
+
+### 1. flow-dev Team 模式
+
+```bash
+# 启用 Team 模式 (默认 3 个 Agent)
+/flow:dev "REQ-123" --team
+
+# 指定 Agent 数量 (2-5)
+/flow:dev "REQ-123" --team --agents 5
+```
+
+### 2. flow-spec Team 模式
+
+```bash
+# Full Mode 自动使用 Team (tech + ui 并行)
+/flow:spec "REQ-123"
+
+# 简化模式使用 Subagent
+/flow:spec "REQ-123" --skip-tech --skip-ui
+```
+
+---
+
+## 工作原理
+
+### flow-dev Team 执行流程
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  1. 任务分析                                                 │
+│     → parse-task-dependencies.js 解析 TASKS.md              │
+│     → 识别 [P] 并行标记、[US*] 用户故事、Phase 依赖          │
+├─────────────────────────────────────────────────────────────┤
+│  2. 冲突检测                                                 │
+│     → detect-file-conflicts.sh 检测文件冲突                 │
+│     → 冲突任务分配给同一 Agent 串行执行                      │
+├─────────────────────────────────────────────────────────────┤
+│  3. 任务分配                                                 │
+│     → Round-robin 分配无冲突任务                            │
+│     → 更新 orchestration_status.json                        │
+├─────────────────────────────────────────────────────────────┤
+│  4. 并行执行                                                 │
+│     → 每个 Agent 独立执行分配的任务                          │
+│     → TeammateIdle Hook 自动分配下一任务                     │
+├─────────────────────────────────────────────────────────────┤
+│  5. 完成处理                                                 │
+│     → TaskCompleted Hook 验证质量                           │
+│     → 所有任务完成后 shutdown                                │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### flow-spec Team 执行流程
+
+```
+PRD (串行) → Tech + UI (Team 并行) → Epic (串行)
+
+Time ────────────────────────────────────────────►
+
+T0   ┌─────────────┐
+     │ prd-writer  │  (必须先完成)
+     └──────┬──────┘
+            │
+T1          ├────────────────────┐
+            │                    │
+     ┌──────▼──────┐      ┌──────▼──────┐
+     │tech-architect│      │ ui-designer │  (Team 并行)
+     └──────┬──────┘      └──────┬──────┘
+            │                    │
+            │  ← SendMessage 协商 →
+            │                    │
+T2          └─────────┬──────────┘
+                      │
+               ┌──────▼──────┐
+               │   planner   │  (等待两者完成)
+               └─────────────┘
+```
+
+---
+
+## TASKS.md 标记规范
+
+### 并行标记 [P]
+
+```markdown
+## Phase 3: Core Implementation
+
+- [ ] T005 [P] [US1] 实现用户注册 API (src/api/user.ts)
+- [ ] T006 [P] [US2] 实现订单创建 API (src/api/order.ts)
+- [ ] T007 [US1] 实现用户验证逻辑 (src/services/auth.ts)
+```
+
+- `[P]` 标记表示该任务可并行执行
+- 无 `[P]` 标记的任务必须串行执行
+- 同一文件的任务不应标记 `[P]`
+
+### 用户故事分组 [US*]
+
+```markdown
+- [ ] T005 [P] [US1] 用户注册 API
+- [ ] T006 [P] [US1] 用户登录 API
+- [ ] T007 [P] [US2] 订单创建 API
+```
+
+- `[US1]`, `[US2]` 等标记用户故事分组
+- 同一用户故事的任务优先分配给同一 Agent
+- 减少上下文切换，提高效率
+
+---
+
+## 文件冲突处理
+
+### 冲突检测
+
+```bash
+# 输入
+{
+  "tasks": [
+    {"id": "T001", "filePath": "src/user.ts"},
+    {"id": "T002", "filePath": "src/user.ts"},
+    {"id": "T003", "filePath": "src/order.ts"}
+  ]
+}
+
+# 输出
+{
+  "hasConflicts": true,
+  "conflicts": [
+    {"file": "src/user.ts", "tasks": ["T001", "T002"]}
+  ],
+  "safeGroups": [
+    {"tasks": ["T003"]}
+  ]
+}
+```
+
+### 冲突解决策略
+
+| 策略 | 描述 |
+|------|------|
+| **same_agent** | 冲突任务分配给同一 Agent 串行执行 |
+| **sequential** | 所有冲突任务按顺序执行 |
+| **worktree** | 使用 Git Worktree 隔离 (未来支持) |
+
+---
+
+## 状态管理
+
+### orchestration_status.json Team 字段
+
+```json
+{
+  "team": {
+    "mode": "parallel",
+    "lead": "dev-lead",
+    "teammates": [
+      {
+        "id": "dev-1",
+        "role": "developer",
+        "status": "working",
+        "currentTask": "T001",
+        "completedTasks": ["T000"],
+        "lastActiveAt": "2026-02-07T10:00:00Z"
+      }
+    ],
+    "taskAssignments": {
+      "T001": "dev-1",
+      "T002": "dev-2"
+    }
+  }
+}
+```
+
+### Teammate 状态
+
+| 状态 | 描述 |
+|------|------|
+| `idle` | 空闲，等待任务分配 |
+| `working` | 正在执行任务 |
+| `blocked` | 被依赖阻塞 |
+| `completed` | 所有任务完成 |
+
+---
+
+## Hook 配置
+
+### quality-gates.yml
+
+```yaml
+# TeammateIdle Hook 配置
+teammate_idle:
+  idle_checks:
+    - npm run lint --if-present
+    - npm run typecheck --if-present
+  assignment_strategy: priority_first
+  idle_timeout: 300  # 秒
+
+# TaskCompleted Hook 配置
+task_completed:
+  verify:
+    - npm run lint --if-present
+    - npm run typecheck --if-present
+    - npm test -- --passWithNoTests
+  block_on_failure: true
+  max_retries: 3
+
+# Ralph Loop Team 模式配置
+ralph_loop:
+  team_mode:
+    enabled: true
+    scope: teammate
+    teammate_verify:
+      dev-frontend:
+        - npm run lint -- --files-changed
+      dev-backend:
+        - npm test -- --changed
+    global_verify:
+      - npm run lint
+      - npm run typecheck
+      - npm test
+    max_iterations_per_teammate: 3
+    max_global_iterations: 10
+```
+
+---
+
+## 最佳实践
+
+### 1. 任务设计
+
+- **独立性**: 每个任务应尽量独立，减少文件冲突
+- **粒度**: 任务粒度适中，不要太大也不要太小
+- **标记**: 正确使用 `[P]` 和 `[US*]` 标记
+
+### 2. Agent 数量选择
+
+| 任务数 | 推荐 Agent 数 |
+|--------|---------------|
+| 1-5 | 2 |
+| 6-10 | 3 |
+| 11-20 | 4 |
+| 20+ | 5 |
+
+### 3. 监控和调试
+
+```bash
+# 查看 Team 状态
+cat devflow/requirements/REQ-123/orchestration_status.json | jq '.team'
+
+# 查看任务分配
+cat devflow/requirements/REQ-123/orchestration_status.json | jq '.team.taskAssignments'
+
+# 查看执行日志
+tail -f devflow/requirements/REQ-123/EXECUTION_LOG.md
+```
+
+---
+
+## 故障排除
+
+### 常见问题
+
+| 问题 | 原因 | 解决方案 |
+|------|------|----------|
+| Agent 空闲超时 | 任务执行时间过长 | 增加 `idle_timeout` 配置 |
+| 文件冲突频繁 | 任务设计不合理 | 重新设计任务，减少文件重叠 |
+| 验证失败循环 | 代码质量问题 | 检查 ERROR_LOG.md，修复问题 |
+| Team 状态不一致 | 异常退出 | 使用 `/flow:dev --resume` 恢复 |
+
+### 紧急停止
+
+```bash
+# 停止所有 Agent
+# 1. 清理 Team 状态
+jq '.team = null' orchestration_status.json > tmp.json && mv tmp.json orchestration_status.json
+
+# 2. 或使用命令
+/util:cancel-ralph
+```
+
+---
+
+## 参考资料
+
+- [CLAUDE_TEAM_INTEGRATION_PLAN.md](../../../devflow/CLAUDE_TEAM_INTEGRATION_PLAN.md) - 集成方案
+- [hooks/CLAUDE.md](../../hooks/CLAUDE.md) - Hook 文档
+- [flow-dev.md](../../commands/flow/dev.md) - flow-dev 命令文档
+
+---
+
+**[PROTOCOL]**: 变更时更新此头部，然后检查 CLAUDE.md

package/.claude/docs/templates/DELTA_SPEC_TEMPLATE.md

@@ -0,0 +1,91 @@
+---
+delta_id: "{DELTA_ID}"
+req_id: "{REQ_ID}"
+title: "{TITLE}"
+created_at: "{TIMESTAMP}"
+status: "draft"
+---
+
+# Delta: {TITLE}
+
+> **[PROTOCOL]**: 变更时更新此头部，然后检查 CLAUDE.md
+
+## Summary
+
+{简要描述变更内容}
+
+---
+
+## ADDED Requirements
+
+### Requirement: {Name}
+
+{Description}
+
+#### Scenario: {Scenario Name}
+
+- GIVEN {precondition}
+- WHEN {action}
+- THEN {expected result}
+
+---
+
+## MODIFIED Requirements
+
+### Requirement: {Name}
+
+{New description}
+
+(Previously: {old description})
+
+#### Scenario: {Scenario Name}
+
+- GIVEN {precondition}
+- WHEN {action}
+- THEN {expected result}
+
+---
+
+## REMOVED Requirements
+
+### Requirement: {Name}
+
+**Reason**: {why removed}
+
+**Migration**: {how to migrate}
+
+---
+
+## RENAMED Requirements
+
+- FROM: {Old Name}
+- TO: {New Name}
+
+---
+
+## Impact Analysis
+
+### Affected Files
+
+| File | Change Type | Description |
+|------|-------------|-------------|
+| `src/example.ts` | NEW | Example file |
+
+### Dependencies
+
+- Requires: None
+- Blocks: None
+
+---
+
+## Verification
+
+- [ ] Unit tests added for new functionality
+- [ ] Integration tests updated
+- [ ] Documentation updated
+- [ ] Backward compatibility verified
+
+---
+
+**Author**: {AUTHOR}
+**Reviewed By**: Pending

package/.claude/docs/templates/DESIGN_DECISIONS_TEMPLATE.md

@@ -0,0 +1,151 @@
+# Design Decisions Record
+
+> [INPUT]: 依赖 team-config.json 的 negotiate_topics 定义
+> [OUTPUT]: 对外提供设计决策记录格式
+> [POS]: templates/ 的 Team 协商决策记录模板，被 flow-spec Team 模式消费
+> [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+
+---
+req_id: "${REQ_ID}"
+created_at: "${TIMESTAMP}"
+updated_at: "${TIMESTAMP}"
+participants: ["tech-architect", "ui-designer", "planner"]
+---
+
+# Design Decisions for ${REQ_ID}
+
+本文档记录 spec-design-team 在设计阶段的共享决策。
+
+## Decision Log
+
+<!-- 每个决策按以下格式记录 -->
+
+### DD-001: API 响应格式
+
+**Topic ID**: `api_format`
+**Decision Owner**: tech-architect
+**Participants**: tech-architect, ui-designer
+**Status**: approved | pending | rejected
+
+**Context**:
+描述决策背景和需要解决的问题。
+
+**Decision**:
+最终决策内容。
+
+**Rationale**:
+选择该方案的原因。
+
+**Alternatives Considered**:
+1. 方案 A - 原因
+2. 方案 B - 原因
+
+**Impact**:
+- 前端: 影响描述
+- 后端: 影响描述
+
+**Timestamp**: ${TIMESTAMP}
+
+---
+
+### DD-002: 数据字段命名
+
+**Topic ID**: `field_naming`
+**Decision Owner**: tech-architect
+**Participants**: tech-architect, ui-designer, planner
+**Status**: approved | pending | rejected
+
+**Context**:
+统一数据字段命名规范，确保前后端一致。
+
+**Decision**:
+- 命名风格: camelCase / snake_case
+- 关键字段映射表
+
+**Rationale**:
+选择该方案的原因。
+
+**Timestamp**: ${TIMESTAMP}
+
+---
+
+### DD-003: 认证策略
+
+**Topic ID**: `auth_strategy`
+**Decision Owner**: tech-architect
+**Participants**: tech-architect, ui-designer
+**Status**: approved | pending | rejected
+
+**Context**:
+确定认证方案。
+
+**Decision**:
+- 认证方式: JWT / Session / OAuth
+- Token 存储: localStorage / httpOnly cookie
+- 刷新策略: 描述
+
+**Rationale**:
+选择该方案的原因。
+
+**Timestamp**: ${TIMESTAMP}
+
+---
+
+### DD-004: 状态管理方案
+
+**Topic ID**: `state_management`
+**Decision Owner**: ui-designer
+**Participants**: tech-architect, ui-designer
+**Status**: approved | pending | rejected
+
+**Context**:
+确定前端状态管理方案。
+
+**Decision**:
+- 方案: Redux / Context / Zustand / Jotai
+- 全局状态: 列表
+- 本地状态: 列表
+
+**Rationale**:
+选择该方案的原因。
+
+**Timestamp**: ${TIMESTAMP}
+
+---
+
+### DD-005: 组件粒度
+
+**Topic ID**: `component_granularity`
+**Decision Owner**: ui-designer
+**Participants**: ui-designer, planner
+**Status**: approved | pending | rejected
+
+**Context**:
+确定 UI 组件拆分粒度，影响任务分解。
+
+**Decision**:
+- 组件列表及复杂度评估
+- 每个组件预估时间
+
+**Rationale**:
+选择该方案的原因。
+
+**Timestamp**: ${TIMESTAMP}
+
+---
+
+## Summary
+
+| Topic | Decision | Owner | Status |
+|-------|----------|-------|--------|
+| api_format | | tech-architect | |
+| field_naming | | tech-architect | |
+| auth_strategy | | tech-architect | |
+| state_management | | ui-designer | |
+| component_granularity | | ui-designer | |
+
+## Changelog
+
+| Date | Topic | Change | By |
+|------|-------|--------|-----|
+| ${TIMESTAMP} | - | Initial creation | spec-lead |

package/.claude/docs/templates/JOURNAL_TEMPLATE.md

@@ -0,0 +1,75 @@
+---
+developer: "{DEVELOPER}"
+journal_number: 1
+created_at: "{TIMESTAMP}"
+---
+
+# Developer Journal: {DEVELOPER}
+
+> **[PROTOCOL]**: 变更时更新此头部，然后检查 CLAUDE.md
+
+---
+
+## [{DATE} {TIME}] Session Start
+
+**REQ**: {REQ_ID}
+**Phase**: {PHASE}
+**Task**: {TASK_ID}
+
+### Context Recovery
+
+Previous session ended at:
+- Last completed task: {LAST_TASK}
+- Current blockers: {BLOCKERS}
+- Open questions: {QUESTIONS}
+
+### Session Goals
+
+1. Goal 1
+2. Goal 2
+
+---
+
+## [{DATE} {TIME}] Progress Update
+
+### Completed
+
+- [x] Task description
+
+### In Progress
+
+- [ ] Current task
+
+### Blockers
+
+- None
+
+### Notes
+
+- Important observation
+- Decision made
+
+---
+
+## [{DATE} {TIME}] Session End
+
+### Summary
+
+Brief summary of what was accomplished.
+
+### Handoff Notes
+
+For next session:
+- Continue with: {NEXT_TASK}
+- Watch out for: {WARNINGS}
+- Questions to resolve: {QUESTIONS}
+
+---
+
+<!--
+Journal Guidelines:
+- Max 2000 lines per file
+- When approaching limit, create journal-{N+1}.md
+- Keep entries concise but informative
+- Focus on decisions and blockers, not routine progress
+-->

package/.claude/docs/templates/_shared/CLAUDE.md

@@ -0,0 +1,36 @@
+# _shared/ - Shared Template Components
+
+> L2 | 父级: `.claude/docs/templates/CLAUDE.md`
+
+## Purpose
+
+Reusable template components extracted from PRD/EPIC/TECH_DESIGN/UI_PROTOTYPE templates to reduce duplication and ensure consistency.
+
+## Members
+
+| File | Purpose | Lines | Used By |
+|------|---------|-------|---------|
+| `CONSTITUTION_CHECK.md` | Constitution compliance check section | ~150 | PRD, EPIC, TECH_DESIGN |
+| `VALIDATION_CHECKLIST.md` | Validation checklist patterns | ~100 | All templates |
+| `YAML_FRONTMATTER.md` | YAML frontmatter patterns | ~50 | All templates |
+
+## Usage Pattern
+
+Templates reference these components via include syntax:
+```markdown
+{{INCLUDE: _shared/CONSTITUTION_CHECK.md}}
+{{INCLUDE: _shared/VALIDATION_CHECKLIST.md#prd}}
+```
+
+Or copy relevant sections based on document type.
+
+## Design Principles
+
+1. **DRY**: Extract repeated content once, reference everywhere
+2. **Consistency**: Single source of truth for Constitution checks
+3. **Modularity**: Each component is self-contained
+4. **Versioned**: Components track Constitution version
+
+---
+
+[PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md