cc-devflow 4.3.0 → 4.4.1

package/.claude/guides/agent-guides/agent-coordination-guide.md

@@ -1,459 +0,0 @@
-# Agent Coordination Rules
-
-## 概述
-
-cc-devflow 系统中的 7 个专业子代理需要严格的协调机制来避免冲突、确保数据一致性并优化工作效率。
-
-## 核心原则
-
-### 1. 编排器模式
-- **flow-orchestrator**: 工作流指导文档，主代理按其标准操作程序执行
-- **研究型代理**: 独立分析专业任务，输出文档和计划给主代理
-- **主代理执行**: 主代理基于所有计划文档直接执行代码实现
-
-### 2. 并行执行原则
-- **独立工作**: 每个子代理在自己的专业领域内独立工作
-- **最小依赖**: 减少子代理之间的直接依赖关系
-- **异步通信**: 通过文档和状态文件进行异步通信
-- **状态同步**: 所有代理向编排器报告进度和完成状态
-
-### 2. 工作流分配
-每个子代理都有明确的职责边界和工作文件模式：
-
-```yaml
-agent_workstreams:
-  flow-orchestrator:
-    files: ["devflow/requirements/*/LOG.md"]
-    responsibility: "总控协调和流程管理"
-
-  prd-writer:
-    files: ["devflow/requirements/*/PRD.md"]
-    responsibility: "产品需求文档生成"
-
-  planner:
-    files:
-      - "devflow/requirements/*/EPIC.md"
-      - "devflow/requirements/*/tasks/TASK_*.md"
-    responsibility: "需求规划和详细任务分解（包含实现指导）"
-
-  qa-tester:
-    files:
-      - "tests/**/*"
-      - "devflow/requirements/*/TEST_REPORT.md"
-    responsibility: "测试生成和质量验证"
-
-  security-reviewer:
-    files: ["SECURITY.md", "*.security"]
-    responsibility: "安全审查和漏洞修复"
-
-  release-manager:
-    files: ["CHANGELOG.md", ".github/**/*"]
-    responsibility: "发布管理和PR操作"
-```
-
-### 3. 文件访问协调
-
-#### 独占访问文件
-每个子代理对其专属文件具有独占写入权限：
-- 其他子代理不得直接修改
-- 需要修改时必须通过协调机制
-
-#### 共享访问文件
-对于需要多个子代理访问的文件，遵循以下规则：
-
-**读取优先**:
-```bash
-# 检查文件是否被其他进程使用
-check_file_lock() {
-    local file="$1"
-    if [ -f "${file}.lock" ]; then
-        echo "⚠️  文件被锁定: $file"
-        return 1
-    fi
-    return 0
-}
-```
-
-**写入锁定**:
-```bash
-# 获取文件写入锁
-acquire_file_lock() {
-    local file="$1"
-    local agent="$2"
-
-    echo "$agent:$(date -u +%Y-%m-%dT%H:%M:%SZ)" > "${file}.lock"
-    echo "🔒 获取文件锁: $file ($agent)"
-}
-
-# 释放文件写入锁
-release_file_lock() {
-    local file="$1"
-    rm -f "${file}.lock"
-    echo "🔓 释放文件锁: $file"
-}
-```
-
-### 4. 子代理间通信
-
-#### 状态文件通信
-使用状态文件进行子代理间的状态同步：
-
-```yaml
-# devflow/requirements/REQ-123/status.yml
-workflow_status:
-  current_stage: "development"
-  completed_stages: ["planning", "prd"]
-  active_agents: ["qa-tester", "security-reviewer"]
-
-agent_status:
-  prd-writer:
-    status: "completed"
-    output_files: ["PRD.md"]
-    completion_time: "2024-01-24T10:30:00Z"
-
-  planner:
-    status: "completed"
-    output_files: ["EPIC.md", "tasks/TASK_001.md", "tasks/TASK_002.md"]
-    completion_time: "2024-01-24T11:15:00Z"
-
-  main_agent:
-    status: "in_progress"
-    current_task: "TASK_001"
-    progress: "60%"
-
-  qa-tester:
-    status: "waiting"
-    depends_on: ["main_agent"]
-```
-
-#### 进度报告
-每个子代理完成工作后必须更新进度文件：
-
-```bash
-# 更新子代理状态
-update_agent_status() {
-    local req_id="$1"
-    local agent="$2"
-    local status="$3"
-    local output_files="$4"
-
-    local status_file="devflow/requirements/${req_id}/status.yml"
-    local timestamp=$(date -u +%Y-%m-%dT%H:%M:%SZ)
-
-    # 更新状态文件
-    yq eval ".agent_status.${agent}.status = \"${status}\"" -i "$status_file"
-    yq eval ".agent_status.${agent}.completion_time = \"${timestamp}\"" -i "$status_file"
-    yq eval ".agent_status.${agent}.output_files = [${output_files}]" -i "$status_file"
-
-    echo "📊 状态已更新: $agent -> $status"
-}
-```
-
-#### 依赖关系管理
-定义子代理之间的依赖关系：
-
-```yaml
-# .claude/rules/agent-dependencies.yml
-dependencies:
-  prd-writer:
-    depends_on: []
-    blocks: ["planner"]
-
-  planner:
-    depends_on: ["prd-writer"]
-    blocks: ["main_agent", "qa-tester"]
-
-  main_agent:
-    depends_on: ["planner"]
-    blocks: ["security-reviewer", "release-manager"]
-
-  qa-tester:
-    depends_on: ["main_agent"]
-    blocks: ["release-manager"]
-
-  security-reviewer:
-    depends_on: ["main_agent"]
-    blocks: ["release-manager"]
-
-  release-manager:
-    depends_on: ["qa-tester", "security-reviewer"]
-    blocks: []
-```
-
-### 5. 冲突处理
-
-#### 文件冲突检测
-```bash
-# 检测文件冲突
-detect_file_conflicts() {
-    local req_id="$1"
-    local conflicts=()
-
-    # 检查是否有多个代理试图修改同一文件
-    for file in devflow/requirements/${req_id}/*.md; do
-        local locks=$(find "${file%.*}*.lock" 2>/dev/null | wc -l)
-        if [ "$locks" -gt 1 ]; then
-            conflicts+=("$file")
-        fi
-    done
-
-    if [ ${#conflicts[@]} -gt 0 ]; then
-        echo "❌ 检测到文件冲突:"
-        printf '  - %s\n' "${conflicts[@]}"
-        return 1
-    fi
-
-    return 0
-}
-```
-
-#### 冲突解决策略
-1. **自动解决**: 简单冲突通过合并策略自动解决
-2. **人工介入**: 复杂冲突总是由人工解决
-3. **回滚机制**: 严重冲突时回滚到最后一个稳定状态
-
-```bash
-# 冲突解决
-resolve_conflicts() {
-    local req_id="$1"
-
-    echo "🔧 开始冲突解决流程..."
-
-    # 1. 停止所有相关子代理
-    stop_agents_for_requirement "$req_id"
-
-    # 2. 创建备份
-    backup_requirement_files "$req_id"
-
-    # 3. 标记需要人工干预
-    echo "❌ 需要人工解决冲突，请检查并手动合并文件"
-    echo "   备份位置: devflow/requirements/${req_id}/.backup/"
-
-    # 4. 生成冲突报告
-    generate_conflict_report "$req_id"
-}
-```
-
-### 6. 同步策略
-
-#### 检查点同步
-在关键节点进行同步检查：
-
-```bash
-# 检查点同步
-checkpoint_sync() {
-    local req_id="$1"
-    local checkpoint="$2"
-
-    echo "📍 检查点同步: $checkpoint"
-
-    # 等待所有活跃代理完成当前任务
-    wait_for_agents_completion "$req_id"
-
-    # 验证输出文件完整性
-    validate_output_files "$req_id" "$checkpoint"
-
-    # 更新全局状态
-    update_workflow_status "$req_id" "$checkpoint"
-
-    echo "✅ 检查点 $checkpoint 同步完成"
-}
-```
-
-#### 定期状态同步
-```bash
-# 定期状态同步 (每5分钟)
-periodic_sync() {
-    local req_id="$1"
-
-    while [ -f "devflow/requirements/${req_id}/.active" ]; do
-        # 收集所有子代理状态
-        collect_agent_states "$req_id"
-
-        # 检测潜在冲突
-        detect_potential_conflicts "$req_id"
-
-        # 更新整体进度
-        update_overall_progress "$req_id"
-
-        sleep 300  # 5分钟
-    done
-}
-```
-
-## 最佳实践
-
-### 1. 失败快速原则
-- 一旦检测到冲突或错误，立即停止并报告
-- 不要试图自动修复复杂问题
-- 保留所有状态信息用于调试
-
-### 2. 状态透明性
-- 所有子代理状态都应该可见和可查询
-- 提供实时进度反馈
-- 记录所有重要决策和状态变化
-
-### 3. 原子性操作
-- 每个子代理的操作都应该是原子性的
-- 要么完全成功，要么完全回滚
-- 避免中间状态的不一致
-
-### 4. 通信频率
-- 在重要状态变化时立即通信
-- 定期发送心跳信号
-- 在完成任务时发送确认信号
-
-## 示例工作流程
-
-```bash
-# 完整的协调流程示例
-coordinate_requirement_flow() {
-    local req_id="$1"
-
-    echo "🚀 启动需求流程协调: $req_id"
-
-    # 1. 初始化协调环境
-    setup_coordination_environment "$req_id"
-
-    # 2. 按依赖关系启动子代理
-    start_agent "prd-writer" "$req_id"
-    wait_for_agent_completion "prd-writer" "$req_id"
-
-    checkpoint_sync "$req_id" "prd-completed"
-
-    start_agent "planner" "$req_id"
-    wait_for_agent_completion "planner" "$req_id"
-
-    checkpoint_sync "$req_id" "planning-completed"
-
-    # 3. 并行启动开发相关子代理
-    start_agent "main_agent" "$req_id" &
-    start_agent "qa-tester" "$req_id" &
-
-    # 4. 监控和协调
-    monitor_parallel_execution "$req_id" "main_agent" "qa-tester"
-
-    # 5. 最终阶段
-    start_agent "security-reviewer" "$req_id"
-    start_agent "release-manager" "$req_id"
-
-    echo "✅ 需求流程协调完成: $req_id"
-}
-```
-
-## 监控和调试
-
-### 状态查询
-```bash
-# 查询子代理状态
-query_agent_status() {
-    local req_id="$1"
-    local agent="${2:-all}"
-
-    if [ "$agent" = "all" ]; then
-        yq eval '.agent_status' "devflow/requirements/${req_id}/status.yml"
-    else
-        yq eval ".agent_status.${agent}" "devflow/requirements/${req_id}/status.yml"
-    fi
-}
-```
-
-### 调试工具
-```bash
-# 生成协调报告
-generate_coordination_report() {
-    local req_id="$1"
-    local report_file="devflow/requirements/${req_id}/coordination-report.md"
-
-    cat > "$report_file" << EOF
-# 子代理协调报告
-
-## 基本信息
-- 需求ID: $req_id
-- 生成时间: $(date -u +%Y-%m-%dT%H:%M:%SZ)
-
-## 子代理状态
-$(yq eval '.agent_status' "devflow/requirements/${req_id}/status.yml")
-
-## 文件锁状态
-$(find "devflow/requirements/${req_id}" -name "*.lock" -exec ls -la {} \;)
-
-## 潜在问题
-$(detect_potential_issues "$req_id")
-EOF
-
-    echo "📋 协调报告已生成: $report_file"
-}
-```
-
-## 编排器模式状态协议
-
-### 编排器状态管理
-flow-orchestrator 维护整体编排状态：
-
-```json
-// devflow/requirements/${reqId}/orchestration_status.json
-{
-  "reqId": "${reqId}",
-  "currentPhase": "development",
-  "startTime": "2024-01-15T10:30:00Z",
-  "phaseStatus": {
-    "research": "completed",
-    "prd": "completed",
-    "planning": "completed",
-    "development": "in_progress",
-    "testing": "pending",
-    "security": "pending",
-    "release": "pending"
-  },
-  "activeAgents": [
-    {"agent": "main_agent", "taskId": "TASK_001", "status": "running", "startTime": "..."},
-    {"agent": "main_agent", "taskId": "TASK_002", "status": "running", "startTime": "..."}
-  ],
-  "completedTasks": ["TASK_003"],
-  "failedTasks": [],
-  "nextActions": ["wait_for_TASK_001", "wait_for_TASK_002"]
-}
-```
-
-### 任务级状态跟踪
-每个 main_agent 维护任务状态：
-
-```json
-// devflow/requirements/${reqId}/tasks/${taskId}_status.json
-{
-  "taskId": "${taskId}",
-  "reqId": "${reqId}",
-  "status": "completed",
-  "startTime": "2024-01-15T10:30:00Z",
-  "endTime": "2024-01-15T11:15:00Z",
-  "agent": "main_agent",
-  "phase": "completed",
-  "filesChanged": ["src/components/UserOrder.tsx", "src/api/orders.ts"],
-  "testsRun": true,
-  "qualityGatePassed": true,
-  "commitHash": "abc123..."
-}
-```
-
-### 完成标记文件
-成功完成的任务创建完成标记：
-
-```bash
-# devflow/requirements/${reqId}/tasks/${taskId}.completed
-2024-01-15T11:15:00Z
-Summary: Implemented user order creation with validation
-Files: src/components/UserOrder.tsx, src/api/orders.ts
-Tests: 5 new tests added, all passing
-Quality: TypeScript + ESLint + Security scan passed
-```
-
-### Agent 通信规范
-- **输入**: 通过 Task 工具的 prompt 参数传递
-- **输出**: 生成指定的文件和状态文件
-- **状态**: 更新自己的状态文件，创建完成标记
-- **错误**: 在状态文件中记录错误详情
-
----
-
-**重要提醒**: 子代理协调是确保 cc-devflow 系统稳定运行的关键。所有子代理都必须严格遵循这些协调规则，特别是新的编排器模式下的状态同步协议。