cc-devflow 2.4.6 → 4.1.0

package/.claude/commands/{flow-dev.md → flow/dev.md}

@@ -1,6 +1,6 @@
 ---
 name: flow-dev
-description: 'Execute development tasks following TDD order. Usage: /flow-dev "REQ-123" [--manual] [--max-iterations N]'
+description: 'Execute development tasks following TDD order. Usage: /flow-dev "REQ-123" [--manual] [--max-iterations N] [--team] [--agents N]'
 scripts:
   prereq: .claude/scripts/check-prerequisites.sh
   check_tasks: .claude/scripts/check-task-status.sh
@@ -8,6 +8,9 @@ scripts:
   validate_constitution: .claude/scripts/validate-constitution.sh
   verify_gate: .claude/scripts/verify-gate.sh
   setup_loop: .claude/scripts/setup-ralph-loop.sh
+  team_init: .claude/scripts/team-dev-init.sh
+  parse_tasks: .claude/scripts/parse-task-dependencies.js
+  detect_conflicts: .claude/scripts/detect-file-conflicts.sh
 skills:
   tdd: .claude/skills/flow-tdd/SKILL.md
   verification: .claude/skills/verification-before-completion/SKILL.md
@@ -55,25 +58,28 @@ NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
 
 ## User Input
 ```text
-$ARGUMENTS = "REQ_ID? [--task T###] [--manual] [--max-iterations N]"
+$ARGUMENTS = "REQ_ID? [--task T###] [--manual] [--max-iterations N] [--team] [--agents N]"
 ```
 
 - **REQ_ID**: 未提供时从当前分支或 `DEVFLOW_REQ_ID` 推断
 - **--task T###**: 指定起始任务（从该任务开始执行）
 - **--manual**: Manual模式，遇错停止等待人工修复（向后兼容）
 - **--max-iterations N**: Autonomous模式最大迭代次数（默认10）
+- **--team**: Team模式，启用多 Agent 并行执行 [NEW: v4.7]
+- **--agents N**: Team模式下的 Agent 数量（默认3，范围2-5）[NEW: v4.7]
 
 **默认行为**: Autonomous模式（自动重试直到完成）
 
 ### 运行模式对比
 
-| | Manual模式 | Autonomous模式（默认） |
-|--|------------|----------------------|
-| 触发方式 | `--manual` | 默认（或指定 `--max-iterations`） |
-| 遇到错误 | 停止，等待人工修复 | 自动重试，记录 ERROR_LOG.md |
-| 注意力刷新 | Protocol 2（每任务） | Protocol 2 + Protocol 3（每迭代） + Protocol 4（遇错） |
-| 适用场景 | 复杂需求需人工判断 | 清晰需求可无人值守 |
-| 退出条件 | 任务失败可停止 | 迭代直到完成或达到上限 |
+| | Manual模式 | Autonomous模式（默认） | Team模式 [NEW] |
+|--|------------|----------------------|----------------|
+| 触发方式 | `--manual` | 默认 | `--team` |
+| 遇到错误 | 停止，等待人工修复 | 自动重试 | 分布式重试 |
+| 并行执行 | 否 | 否 | 是（多 Agent） |
+| 注意力刷新 | Protocol 2 | Protocol 2+3+4 | 每 Agent 独立 |
+| 适用场景 | 复杂需求 | 清晰需求 | 大量并行任务 |
+| 退出条件 | 任务失败可停止 | 迭代直到完成 | 所有 Agent 完成 |
 
 **示例**:
 ```bash
@@ -82,6 +88,8 @@ $ARGUMENTS = "REQ_ID? [--task T###] [--manual] [--max-iterations N]"
 /flow-dev "REQ-123" --manual             # Manual模式，遇错停止
 /flow-dev "REQ-123" --task T005          # 从 T005 开始（Autonomous模式）
 /flow-dev "REQ-123" --task T005 --manual # 从 T005 开始（Manual模式）
+/flow-dev "REQ-123" --team               # Team模式，3 个 Agent 并行
+/flow-dev "REQ-123" --team --agents 5    # Team模式，5 个 Agent 并行
 ```
 
 ## 执行流程
@@ -89,9 +97,10 @@ $ARGUMENTS = "REQ_ID? [--task T###] [--manual] [--max-iterations N]"
 ### 阶段 1: Entry Gate
 ```
 1. 解析参数
-   → Parse: REQ_ID, --task, --manual, --max-iterations
+   → Parse: REQ_ID, --task, --manual, --max-iterations, --team, --agents
    → If REQ_ID not provided: run {SCRIPT:prereq} --json --paths-only
    → Determine mode:
+      • --team flag present → Team mode
       • --manual flag present → Manual mode
       • Otherwise → Autonomous mode (default max_iterations = 10)
 
@@ -115,6 +124,12 @@ $ARGUMENTS = "REQ_ID? [--task T###] [--manual] [--max-iterations N]"
    → 任务格式 `- [ ] T### [P?] [US?] Description (path)`
 
 4. 模式初始化
+   → If Team mode:
+      • Run: {SCRIPT:team_init} init "${REPO_ROOT}" "${REQ_ID}" ${NUM_AGENTS}
+      • Analyze tasks: {SCRIPT:team_init} analyze "${REPO_ROOT}" "${REQ_ID}"
+      • Check conflicts: {SCRIPT:team_init} conflicts "${REPO_ROOT}" "${REQ_ID}"
+      • Assign tasks: {SCRIPT:team_init} assign "${REPO_ROOT}" "${REQ_ID}" ${NUM_AGENTS}
+      • Log to EXECUTION_LOG.md: "Starting Team mode with N agents"
    → If Autonomous mode:
       • Run: {SCRIPT:setup_loop} "${REQ_ID}" --max-iterations ${MAX_ITERATIONS}
       • Creates .claude/ralph-loop.local.md (state file for Stop Hook)
@@ -158,6 +173,84 @@ $ARGUMENTS = "REQ_ID? [--task T###] [--manual] [--max-iterations N]"
 
 ### 阶段 3: 执行循环
 
+**Team 模式循环** (--team) [NEW: v4.7]:
+```
+┌──────────────────────────────────────────────────────────────────┐
+│ Team Mode Execution Flow                                          │
+├──────────────────────────────────────────────────────────────────┤
+│                                                                   │
+│  1. 任务分析与分配                                                 │
+│     → Run: {SCRIPT:team_init} analyze "${REPO_ROOT}" "${REQ_ID}"  │
+│     → Run: {SCRIPT:team_init} conflicts "${REPO_ROOT}" "${REQ_ID}"│
+│     → Run: {SCRIPT:team_init} assign "${REPO_ROOT}" "${REQ_ID}" N │
+│                                                                   │
+│  2. 并行执行                                                       │
+│     → 每个 Agent 独立执行分配的任务                                │
+│     → 文件冲突的任务分配给同一 Agent 串行执行                       │
+│     → 无冲突的任务可并行执行                                       │
+│                                                                   │
+│  3. 任务完成处理                                                   │
+│     → TeammateIdle Hook 验证任务完成                               │
+│     → 验证通过 → 标记完成，分配下一任务                            │
+│     → 验证失败 → 继续修复                                          │
+│                                                                   │
+│  4. 阶段转换                                                       │
+│     → 当前阶段所有任务完成 → 进入下一阶段                          │
+│     → 重新分析任务并行性和冲突                                     │
+│                                                                   │
+│  5. 完成条件                                                       │
+│     → 所有任务完成 → 所有 Agent shutdown                           │
+│     → 更新 orchestration_status.json                               │
+│                                                                   │
+└──────────────────────────────────────────────────────────────────┘
+
+Task Assignment Strategy:
+┌─────────────────────────────────────────────────────────────────┐
+│ 1. 解析 TASKS.md 获取当前阶段任务                                 │
+│    → node {SCRIPT:parse_tasks} next TASKS.md                     │
+│                                                                  │
+│ 2. 检测文件冲突                                                   │
+│    → {SCRIPT:detect_conflicts} < tasks.json                      │
+│                                                                  │
+│ 3. 分配策略                                                       │
+│    → 有冲突: 冲突任务分配给同一 Agent                             │
+│    → 无冲突: Round-robin 分配给各 Agent                           │
+│                                                                  │
+│ 4. 输出分配计划                                                   │
+│    {                                                             │
+│      "assignments": [                                            │
+│        {"agent": "dev-1", "tasks": ["T001", "T002"]},            │
+│        {"agent": "dev-2", "tasks": ["T003"]},                    │
+│        {"agent": "dev-3", "tasks": ["T004"]}                     │
+│      ],                                                          │
+│      "hasConflicts": false                                       │
+│    }                                                             │
+└─────────────────────────────────────────────────────────────────┘
+
+Conflict Resolution:
+┌─────────────────────────────────────────────────────────────────┐
+│ 文件冲突检测示例:                                                 │
+│                                                                  │
+│ Input:                                                           │
+│   T001 [P] 修改 src/user.ts                                      │
+│   T002 [P] 修改 src/user.ts                                      │
+│   T003 [P] 修改 src/order.ts                                     │
+│                                                                  │
+│ Output:                                                          │
+│   {                                                              │
+│     "hasConflicts": true,                                        │
+│     "conflicts": [                                               │
+│       {"file": "src/user.ts", "tasks": ["T001", "T002"]}         │
+│     ],                                                           │
+│     "safeGroups": [{"tasks": ["T003"]}]                          │
+│   }                                                              │
+│                                                                  │
+│ Assignment:                                                      │
+│   dev-1: T001, T002 (串行，因为冲突)                              │
+│   dev-2: T003 (独立)                                             │
+└─────────────────────────────────────────────────────────────────┘
+```
+
 **Manual 模式循环** (--manual):
 ```
 For each remaining task (顺序严格遵循 TASKS.md):
@@ -281,10 +374,11 @@ Note: Stop Hook (.claude/hooks/ralph-stop-hook.sh) 会在 Autonomous 模式下:
 ## 运行提示
 - **默认 Autonomous 模式**: 遇错自动重试，无需人工干预
 - **使用 `--manual` 退出**: 适合需要人工判断的复杂场景
+- **使用 `--team` 并行**: 适合大量可并行任务的需求 [NEW: v4.7]
 - **使用 `/cancel-ralph` 停止**: 紧急停止 Autonomous 循环
 - 始终使用 quickstart 中提供的命令（测试、lint、db migrate 等）
 - Phase 2 的所有测试必须在实现前失败；若某测试直接通过，回滚并修正
-- 遵循 TASKS.md 标注的 `[P]` 仅表示逻辑上可并行，实际执行依旧串行
+- 遵循 TASKS.md 标注的 `[P]` 表示可并行，Team 模式下会真正并行执行
 - 如需恢复，可使用 `/flow-dev --task TXYZ` 指向首个未完成任务
 
 ## 错误处理
@@ -301,6 +395,13 @@ Note: Stop Hook (.claude/hooks/ralph-stop-hook.sh) 会在 Autonomous 模式下:
 - 达到 max_iterations → 输出状态报告（已完成/剩余任务），保持 development_in_progress
 - 紧急停止 → 使用 `/cancel-ralph` 删除状态文件，立即终止循环
 
+**Team 模式** [NEW: v4.7]:
+- 缺少资产 → 同 Manual 模式（Entry Gate 阻止）
+- 文件冲突 → 自动检测并分配给同一 Agent 串行执行
+- Agent 任务失败 → TeammateIdle Hook 触发重试
+- 所有 Agent 空闲但任务未完成 → 重新分配任务
+- 紧急停止 → 清理 Team 状态，所有 Agent shutdown
+
 ## 取消 Autonomous 循环
 
 ```bash

package/.claude/commands/flow/init.md

@@ -0,0 +1,45 @@
+---
+name: flow-init
+description: 'Initialize requirement structure. Usage: /flow-init "REQ-123|Title|URLs"'
+skill: workflow/flow-init
+---
+
+# Flow-Init Command (Trigger Entry)
+
+> 此文件为触发入口，详细实现见 `.claude/skills/workflow/flow-init/SKILL.md`
+
+## Usage
+
+```bash
+/flow-init "REQ-123|User Authentication"
+/flow-init "REQ-124|数据导出|https://docs.example.com/export-spec.md"
+/flow-init --interactive
+```
+
+## Quick Reference
+
+| Stage | Purpose | Output |
+|-------|---------|--------|
+| 1 | Entry Gate | 参数验证 |
+| 1.2 | Git Branch | feature/REQ-xxx-title |
+| 1.5 | Context Loading | ROADMAP/ARCHITECTURE |
+| 2 | Directory Init | 目录结构 |
+| 2.3 | Brainstorming | BRAINSTORM.md |
+| 2.5 | Research | research/* |
+| 3 | README | README.md |
+| 4 | Exit Gate | 5-Level 验证 |
+
+## Skill Location
+
+**Full Implementation**: `.claude/skills/workflow/flow-init/SKILL.md`
+
+**Resources**:
+- Scripts: `.claude/skills/workflow/flow-init/scripts/`
+- References: `.claude/skills/workflow/flow-init/references/`
+- Assets: `.claude/skills/workflow/flow-init/assets/`
+
+## Next Step
+
+```
+/flow-prd "${REQ_ID}"
+```

package/.claude/commands/flow/quality.md

@@ -0,0 +1,159 @@
+---
+name: flow-quality
+description: Combined quality verification (replaces flow-review + flow-qa)
+version: 3.0.0
+---
+
+# /flow-quality
+
+> **[PROTOCOL]**: 变更时更新此头部，然后检查 CLAUDE.md
+
+## Purpose
+
+Combined quality verification command that replaces the separate `/flow-review` and `/flow-qa` commands.
+Provides both quick programmatic verification and full comprehensive review.
+
+## Usage
+
+```bash
+# Quick mode (default) - programmatic verification only
+/flow-quality [REQ-ID]
+
+# Full mode - comprehensive review including spec compliance
+/flow-quality [REQ-ID] --full
+```
+
+## Modes
+
+### Quick Mode (Default)
+
+Fast programmatic verification using quality-gates.yml:
+
+1. **Lint Check** - `npm run lint`
+2. **Type Check** - `npm run typecheck`
+3. **Unit Tests** - `npm test`
+
+**Use Case**: Rapid iteration during development, CI/CD pipelines.
+
+**Duration**: ~1-2 minutes
+
+### Full Mode (`--full`)
+
+Comprehensive review including:
+
+1. **Programmatic Checks** (same as quick mode)
+2. **Spec Compliance Review** - Verify implementation matches PRD/TECH_DESIGN
+3. **Code Quality Review** - Structure, patterns, Constitution compliance
+4. **Security Scan** - `npm audit`, secret detection
+5. **Integration Tests** - `npm run test:integration` (if available)
+
+**Use Case**: Before PR creation, milestone completion.
+
+**Duration**: ~5-10 minutes
+
+## Entry Gate
+
+```yaml
+prerequisites:
+  - development_complete: true
+  - TASKS.md: All tasks marked [x]
+  - Tests: All passing
+```
+
+## Exit Gate
+
+### Quick Mode
+```yaml
+exit_criteria:
+  - lint: pass
+  - typecheck: pass
+  - tests: pass
+```
+
+### Full Mode
+```yaml
+exit_criteria:
+  - lint: pass
+  - typecheck: pass
+  - tests: pass
+  - spec_review: PASS
+  - code_quality: PASS
+  - security: no high-severity issues
+```
+
+## Output
+
+### Quick Mode
+```
+✅ Quality Gate PASSED (Quick Mode)
+
+  ✓ Lint Check
+  ✓ Type Check
+  ✓ Unit Tests (42 passed)
+
+Duration: 1m 23s
+```
+
+### Full Mode
+```
+✅ Quality Gate PASSED (Full Mode)
+
+Programmatic Checks:
+  ✓ Lint Check
+  ✓ Type Check
+  ✓ Unit Tests (42 passed)
+  ✓ Integration Tests (8 passed)
+
+Reviews:
+  ✓ Spec Compliance: PASS
+  ✓ Code Quality: PASS
+  ✓ Security: No issues
+
+Reports Generated:
+  - SPEC_REVIEW.md
+  - CODE_QUALITY_REVIEW.md
+  - SECURITY_REPORT.md
+
+Duration: 7m 45s
+```
+
+## Integration
+
+### With flow-dev
+
+After `/flow-dev` completes, the orchestrator recommends:
+```
+status: "development_complete"
+  → Recommend: /flow-quality (quick verification)
+  → Alternative: /flow-quality --full (comprehensive review)
+```
+
+### With flow-release
+
+`/flow-release` requires quality gate to pass:
+```yaml
+flow-release:
+  prerequisites:
+    - quality_complete: true
+```
+
+## Deprecation Notice
+
+The following commands are deprecated in v3.0:
+
+- `/flow-review` → Use `/flow-quality --full`
+- `/flow-qa` → Use `/flow-quality --full`
+
+These commands still work for backward compatibility but will show a deprecation warning.
+
+## Scripts
+
+- `.claude/scripts/flow-quality-quick.sh` - Quick verification
+- `.claude/scripts/flow-quality-full.sh` - Full verification
+- `.claude/scripts/run-quality-gates.sh` - Core gate execution
+
+## Related
+
+- **Config**: `.claude/config/quality-gates.yml`
+- **Error Log**: `ERROR_LOG.md` (errors recorded here)
+- **Orchestrator**: Updates `orchestration_status.json` on completion

package/.claude/commands/flow/spec.md

@@ -0,0 +1,186 @@
+---
+name: flow-spec
+description: 'Unified specification phase: PRD → Tech+UI (parallel) → Epic/Tasks. Usage: /flow-spec "REQ-123" [--skip-tech] [--skip-ui]'
+scripts:
+  prereq: .claude/scripts/check-prerequisites.sh
+  validate_research: .claude/scripts/validate-research.sh
+  validate_constitution: .claude/scripts/validate-constitution.sh
+---
+
+# Flow-Spec - 统一规格阶段命令
+
+> **v4.1 新增**: 合并 flow-prd/flow-tech/flow-ui/flow-epic 为单一命令
+
+## User Input
+
+```text
+$ARGUMENTS = "REQ_ID [--skip-tech] [--skip-ui]"
+```
+
+若未提供 REQ_ID 则根据当前分支或 `DEVFLOW_REQ_ID` 自动解析。
+
+## 命令格式
+
+```bash
+# Full Mode (默认) - PRD + Tech + UI + Epic
+/flow-spec "REQ-123"
+
+# Quick Mode (小需求) - PRD + Epic only
+/flow-spec "REQ-123" --skip-tech --skip-ui
+
+# Backend Only - PRD + Tech + Epic
+/flow-spec "REQ-123" --skip-ui
+
+# Frontend Only - PRD + UI + Epic
+/flow-spec "REQ-123" --skip-tech
+```
+
+## Mode Matrix
+
+| Mode | Flags | Agents | Output |
+|------|-------|--------|--------|
+| Full | (default) | PRD + Tech + UI + Epic | PRD.md, TECH_DESIGN.md, UI_PROTOTYPE.html, EPIC.md, TASKS.md |
+| Quick | `--skip-tech --skip-ui` | PRD + Epic | PRD.md, EPIC.md, TASKS.md |
+| Backend | `--skip-ui` | PRD + Tech + Epic | PRD.md, TECH_DESIGN.md, EPIC.md, TASKS.md |
+| Frontend | `--skip-tech` | PRD + UI + Epic | PRD.md, UI_PROTOTYPE.html, EPIC.md, TASKS.md |
+
+## 执行流程
+
+**加载 Skill 指令**:
+```
+→ 读取 .claude/skills/workflow/flow-spec/SKILL.md
+→ 按 SKILL.md 中定义的 Execution Flow 执行
+```
+
+### 阶段 1: Entry Gate
+
+```yaml
+Prerequisites:
+  1. REQ_ID 解析:
+     - 从参数获取
+     - 或从当前分支推断 (feature/REQ-XXX-*)
+     - 或从 orchestration_status.json 获取
+
+  2. BRAINSTORM.md 存在:
+     - 路径: devflow/requirements/${REQ_ID}/BRAINSTORM.md
+     - 必须包含: 需求描述、目标用户、核心功能
+
+  3. Research 完成:
+     - 路径: devflow/requirements/${REQ_ID}/research/research.md
+     - 无 TODO/PLACEHOLDER
+
+  4. Status Check:
+     - orchestration_status.status ∈ {"initialized", "spec_failed"}
+
+  5. Constitution Gate:
+     - 读取 BRAINSTORM.md 验证需求边界
+```
+
+### 阶段 2: PRD Generation (Sequential)
+
+```yaml
+Agent: prd-writer (research-type)
+Input:
+  - BRAINSTORM.md
+  - research/research.md
+  - research/internal/codebase-overview.md
+
+Output:
+  - PRD.md
+
+Rules:
+  - ANTI-EXPANSION: 未提及 → [NEEDS CLARIFICATION]
+  - NO TECH DETAILS: 只关注 WHAT/WHY
+  - STORY INDEPENDENCE: 每个故事有独立测试
+```
+
+### 阶段 3: Tech + UI (Parallel)
+
+```yaml
+Parallel Execution:
+  tech-architect (if !--skip-tech):
+    Input: PRD.md, research/codebase-overview.md
+    Output: TECH_DESIGN.md, data-model.md, contracts/
+
+  ui-designer (if !--skip-ui AND UI detected):
+    Input: PRD.md, STYLE.md (optional)
+    Output: UI_PROTOTYPE.html, ui_design_strategy.md
+
+Method:
+  - 使用 Task tool 并行调用两个 agent
+  - 等待两者完成后进入 Stage 4
+```
+
+### 阶段 4: Epic Generation (Sequential)
+
+```yaml
+Agent: planner (research-type)
+Input:
+  - PRD.md
+  - TECH_DESIGN.md (if exists)
+  - UI_PROTOTYPE.html (if exists)
+
+Output:
+  - EPIC.md
+  - TASKS.md
+
+Rules:
+  - TDD Order: Phase 2 (Tests) → Phase 3 (Implementation)
+  - Bite-Sized Tasks: 每个 step 2-5 分钟
+  - Phase -1 Gates: Simplicity, Anti-Abstraction, Integration-First
+```
+
+### 阶段 5: Exit Gate
+
+```yaml
+File Checks:
+  - [ ] PRD.md exists, no {{PLACEHOLDER}}
+  - [ ] TECH_DESIGN.md exists (if !--skip-tech)
+  - [ ] UI_PROTOTYPE.html exists (if !--skip-ui AND UI detected)
+  - [ ] EPIC.md exists, no {{PLACEHOLDER}}
+  - [ ] TASKS.md exists, TDD order correct
+
+Status Update:
+  - orchestration_status.status = "spec_complete"
+  - orchestration_status.phase = "spec"
+```
+
+## 输出
+
+```
+devflow/requirements/${REQ_ID}/
+├── PRD.md                          # Always
+├── TECH_DESIGN.md                  # If !--skip-tech
+├── data-model.md                   # If !--skip-tech
+├── contracts/openapi.yaml          # If !--skip-tech
+├── UI_PROTOTYPE.html               # If !--skip-ui AND UI detected
+├── EPIC.md                         # Always
+├── TASKS.md                        # Always
+└── orchestration_status.json       # Updated
+```
+
+## 错误处理
+
+- **Entry Gate 失败**: 返回具体缺失项，指导用户运行 `/flow-init`
+- **PRD 生成失败**: status = "spec_failed"，可重试
+- **Tech/UI 失败**: 继续执行，标记为 skipped
+- **Epic 失败**: status = "spec_failed"，可用 `--from=epic` 重试
+
+## 下一步
+
+```bash
+/flow-dev "${REQ_ID}"
+```
+
+## Agent References
+
+| Agent | Purpose | Location |
+|-------|---------|----------|
+| prd-writer | PRD 生成 | `.claude/agents/prd-writer.md` |
+| tech-architect | 技术设计 | `.claude/agents/tech-architect.md` |
+| ui-designer | UI 原型 | `.claude/agents/ui-designer.md` |
+| planner | Epic/Tasks | `.claude/agents/planner.md` |
+
+## 详细指令
+
+完整执行逻辑见: `.claude/skills/workflow/flow-spec/SKILL.md`