cc-devflow 2.4.6 → 4.1.0

package/.claude/hooks/types/team-types.d.ts

@@ -0,0 +1,238 @@
+/**
+ * [INPUT]: 无外部依赖
+ * [OUTPUT]: 对外提供 Claude Team 集成的 TypeScript 类型定义
+ * [POS]: hooks/types/ 的 Team 状态类型，被 teammate-idle-hook.ts 和 task-completed-hook.ts 消费
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+
+// =============================================================================
+// Teammate 状态类型
+// =============================================================================
+
+export type TeammateStatus = 'idle' | 'working' | 'blocked' | 'completed' | 'error';
+
+export interface TeammateState {
+  /** Teammate 唯一标识 (e.g., "dev-analyst", "spec-analyst") */
+  id: string;
+
+  /** Teammate 角色 (e.g., "developer", "analyst", "reviewer") */
+  role: string;
+
+  /** 当前状态 */
+  status: TeammateStatus;
+
+  /** 当前正在执行的任务 ID (e.g., "T001") */
+  currentTask: string | null;
+
+  /** 已完成的任务 ID 列表 */
+  completedTasks: string[];
+
+  /** 最后活跃时间 (ISO 8601) */
+  lastActiveAt: string;
+
+  /** 错误信息 (仅当 status === 'error') */
+  errorMessage?: string;
+}
+
+// =============================================================================
+// Team 状态类型
+// =============================================================================
+
+export type TeamMode = 'sequential' | 'parallel';
+
+export interface TeamState {
+  /** Team 执行模式 */
+  mode: TeamMode;
+
+  /** Team Lead 标识 */
+  lead: string;
+
+  /** 所有 Teammates 状态 */
+  teammates: TeammateState[];
+
+  /** 任务分配映射 (taskId -> teammateId) */
+  taskAssignments: Record<string, string>;
+
+  /** Team 创建时间 */
+  createdAt: string;
+
+  /** Team 最后更新时间 */
+  updatedAt: string;
+}
+
+// =============================================================================
+// Ralph Loop Team 模式类型
+// =============================================================================
+
+export interface TeammateRalphState {
+  /** 当前迭代次数 */
+  iteration: number;
+
+  /** 最后验证结果 */
+  lastVerifyResult: 'passed' | 'failed' | 'skipped';
+
+  /** 最后验证时间 */
+  lastVerifyAt?: string;
+
+  /** 最后失败记录 */
+  lastFailures?: FailureRecord[];
+}
+
+export interface FailureRecord {
+  command: string;
+  output: string;
+  timestamp: string;
+}
+
+export interface RalphLoopTeamState {
+  /** 是否启用 Ralph Loop */
+  enabled: boolean;
+
+  /** 每个 Teammate 的 Ralph 状态 */
+  teammates: Record<string, TeammateRalphState>;
+
+  /** 全局迭代次数 */
+  globalIteration: number;
+
+  /** 最大迭代次数 */
+  maxIterations: number;
+
+  /** 开始时间 */
+  startedAt: string;
+}
+
+// =============================================================================
+// 扩展的 orchestration_status.json 类型
+// =============================================================================
+
+export interface OrchestrationStatus {
+  /** 需求 ID */
+  reqId: string;
+
+  /** 需求标题 */
+  title?: string;
+
+  /** 当前状态 */
+  status: string;
+
+  /** 当前阶段 */
+  phase: string;
+
+  /** 已完成的步骤 */
+  completedSteps?: string[];
+
+  /** Git 分支名 */
+  branch?: string;
+
+  /** 创建时间 */
+  createdAt: string;
+
+  /** 更新时间 */
+  updatedAt: string;
+
+  // =========================================================================
+  // v4.7 新增: Team 状态
+  // =========================================================================
+
+  /** Team 状态 (仅在 Team 模式下存在) */
+  team?: TeamState;
+
+  /** Ralph Loop 状态 (支持多 Teammate) */
+  ralphLoop?: RalphLoopTeamState;
+
+  // =========================================================================
+  // 归档相关字段
+  // =========================================================================
+
+  /** 归档原因 */
+  archivedReason?: string;
+
+  /** 归档时间 */
+  archivedAt?: string;
+
+  /** 归档位置 */
+  archiveLocation?: string;
+
+  /** 归档前状态 */
+  statusBeforeArchive?: string;
+
+  /** Delta 数量 */
+  deltaCount?: number;
+}
+
+// =============================================================================
+// Hook 输入/输出类型
+// =============================================================================
+
+export interface TeammateIdleInput {
+  hook_event_name: 'TeammateIdle';
+  teammate_id: string;
+  teammate_role: string;
+  last_task_id?: string;
+  idle_reason: 'task_complete' | 'waiting_dependency' | 'no_tasks' | 'error';
+  cwd: string;
+  session_id: string;
+}
+
+export interface TeammateIdleOutput {
+  action: 'assign_task' | 'wait' | 'shutdown';
+  task_id?: string;
+  message?: string;
+}
+
+export interface TaskCompletedInput {
+  hook_event_name: 'TaskCompleted';
+  task_id: string;
+  task_subject: string;
+  completed_by: string;
+  completion_time: string;
+  cwd: string;
+  session_id: string;
+}
+
+export interface TaskCompletedOutput {
+  decision: 'accept' | 'reject';
+  reason: string;
+  next_actions?: string[];
+}
+
+// =============================================================================
+// quality-gates.yml Team 模式配置类型
+// =============================================================================
+
+export interface TeammateIdleConfig {
+  idle_checks?: VerifyCommand[];
+  assignment_strategy?: 'priority_first' | 'round_robin' | 'skill_match';
+  idle_timeout?: number;
+}
+
+export interface TaskCompletedConfig {
+  verify?: VerifyCommand[];
+  block_on_failure?: boolean;
+  max_retries?: number;
+}
+
+export interface RalphLoopTeamConfig {
+  enabled?: boolean;
+  scope?: 'teammate' | 'global';
+  teammate_verify?: Record<string, string[]>;
+  global_verify?: string[];
+  max_iterations_per_teammate?: number;
+  max_global_iterations?: number;
+}
+
+export interface VerifyCommand {
+  name?: string;
+  command: string;
+  required?: boolean;
+}
+
+export interface QualityGatesTeamConfig {
+  teammate_idle?: TeammateIdleConfig;
+  task_completed?: TaskCompletedConfig;
+  ralph_loop?: {
+    team_mode?: RalphLoopTeamConfig;
+    max_iterations?: number;
+    timeout_minutes?: number;
+  };
+}

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

@@ -61,9 +61,79 @@ devflow/requirements/${reqId}/
 
 ---
 
-## 🌿 Git 分支约定
+## 🌿 Git Worktree 约定 (v4.3)
+
+### Worktree vs Branch 模式
+
+| 模式 | 命令 | 适用场景 |
+|------|------|----------|
+| **Worktree (默认)** | `/flow-init "REQ-123\|Title"` | 多需求并行、需要隔离环境 |
+| **Branch** | `/flow-init "REQ-123\|Title" --branch-only` | 单需求开发、简单修改 |
+
+### Worktree 目录布局
+
+```
+~/projects/
+├── cc-devflow/                    # 主仓库 (main 分支)
+├── cc-devflow-REQ-001/            # REQ-001 worktree
+├── cc-devflow-REQ-002/            # REQ-002 worktree
+├── cc-devflow-analysis/           # 只读分析 worktree (可选)
+└── cc-devflow-hotfix/             # 紧急修复 worktree (可选)
+```
+
+### 命名规范
+
+```bash
+# Worktree 目录
+{repo-name}-{REQ_ID}
+# 示例: cc-devflow-REQ-123
+
+# 对应分支 (不变)
+feature/${reqId}-${slug(BRANCH_TITLE_EN)}
+# 示例: feature/REQ-123-user-order-support
+```
+
+### Worktree 操作流程
+
+1. **创建** (flow-init 自动执行)
+   ```bash
+   git worktree add -b feature/REQ-123-title ../cc-devflow-REQ-123
+   ```
+
+2. **切换**
+   ```bash
+   cd ../cc-devflow-REQ-123
+   # 或使用 shell 别名
+   zw REQ-123
+   ```
+
+3. **开发**
+   - 每个 worktree 独立的 Claude Code 会话
+   - 互不干扰，保持上下文
+
+4. **清理** (flow-release 自动执行)
+   ```bash
+   git worktree remove ../cc-devflow-REQ-123
+   git branch -d feature/REQ-123-title
+   ```
+
+### Shell 别名推荐
+
+```bash
+# 添加到 ~/.zshrc 或 ~/.bashrc
+alias za='cd $(git rev-parse --show-toplevel 2>/dev/null || echo .)'
+alias zl='git worktree list'
+alias zm='cd ~/projects/cc-devflow'
+
+zw() {
+  local req_id="${1:-}"
+  local repo_name=$(basename $(git rev-parse --show-toplevel 2>/dev/null))
+  cd ~/projects/${repo_name}-${req_id}
+}
+```
+
+### 分支命名 (保持不变)
 
-### 分支命名
 ```bash
 # 标准格式
 feature/${reqId}-${slug(BRANCH_TITLE_EN)}
@@ -75,13 +145,16 @@ feature/REQ-124-permission-management
 
 > BRANCH_TITLE_EN 为 TITLE 的英文意译 (语义为准，非拼音，使用模型意译)
 
-### 分支操作流程
-1. 检查当前在 main 分支且状态干净
-2. 创建特性分支
-3. 实施开发 (TDD方式)
-4. 质量闸检查
-5. 创建 PR
-6. 合并后清理分支
+### 分支操作流程 (Worktree 模式)
+
+1. 确保主仓库在 main 分支且状态干净
+2. 执行 `/flow-init` 创建 worktree + 分支
+3. 切换到 worktree 目录
+4. 启动新的 Claude Code 会话
+5. 实施开发 (TDD方式)
+6. 质量闸检查
+7. 创建 PR
+8. 合并后清理 worktree 和分支
 
 ---
 

package/.claude/scripts/archive-requirement.sh

@@ -1,8 +1,13 @@
 #!/usr/bin/env bash
 # =============================================================================
-# archive-requirement.sh - 需求归档脚本
+# archive-requirement.sh - 需求归档脚本 (v4.5 增强版)
 # 将已完成或废弃的需求移动到归档目录
+# 支持 Delta Specs 集成
 # =============================================================================
+# [INPUT]: 依赖 common.sh, orchestration_status.json
+# [OUTPUT]: 移动需求到 devflow/archive/{YYYY-MM}/
+# [POS]: scripts 的归档脚本，被 /flow:archive 调用
+# [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
 
 set -euo pipefail
 
@@ -276,12 +281,43 @@ archive_month=$(TZ='Asia/Shanghai' date '+%Y-%m')
 archive_dir=$(get_archive_dir "$REPO_ROOT" "$archive_month")
 target_dir="$archive_dir/$REQ_ID"
 
+# 检查 Delta Specs
+delta_count=$(get_delta_count "$source_dir")
+has_unapplied_deltas=false
+if [[ "$delta_count" -gt 0 ]]; then
+    # 检查是否有未应用的 deltas
+    for delta_dir in "$source_dir/deltas"/*/; do
+        [[ -d "$delta_dir" ]] || continue
+        delta_file="$delta_dir/delta.md"
+        if [[ -f "$delta_file" ]]; then
+            status=$(grep -E '^status:' "$delta_file" | head -1 | sed 's/status:[[:space:]]*"\?\([^"]*\)"\?/\1/')
+            if [[ "$status" != "applied" ]]; then
+                has_unapplied_deltas=true
+                break
+            fi
+        fi
+    done
+fi
+
 if [[ "$DRY_RUN" == "true" ]]; then
     echo "[DRY-RUN] 将移动: $source_dir → $target_dir"
     echo "[DRY-RUN] 归档原因: $REASON"
+    if [[ "$delta_count" -gt 0 ]]; then
+        echo "[DRY-RUN] Delta Specs: $delta_count 个"
+        if [[ "$has_unapplied_deltas" == "true" ]]; then
+            echo "[DRY-RUN] ⚠️  警告: 存在未应用的 Delta Specs"
+        fi
+    fi
     exit 0
 fi
 
+# 警告未应用的 deltas
+if [[ "$has_unapplied_deltas" == "true" ]]; then
+    echo "⚠️  警告: 存在未应用的 Delta Specs"
+    echo "   建议先运行: /flow:delta apply $REQ_ID --all"
+    echo ""
+fi
+
 # 创建归档目录
 mkdir -p "$archive_dir"
 
@@ -303,11 +339,13 @@ if [[ -f "$status_file" ]]; then
        --arg location "$target_dir" \
        --arg prev_status "$current_status" \
        --arg updated "$(get_beijing_time_iso)" \
+       --argjson delta_count "$delta_count" \
        '.status = "archived" |
         .archivedReason = $reason |
         .archivedAt = $archived_at |
         .archiveLocation = $location |
         .statusBeforeArchive = $prev_status |
+        .deltaCount = $delta_count |
         .updatedAt = $updated' \
        "$status_file" > "${status_file}.tmp" && mv "${status_file}.tmp" "$status_file"
 fi
@@ -322,6 +360,7 @@ if [[ -f "$log_file" ]]; then
 - 归档原因: $REASON
 - 归档位置: $target_dir
 - 归档前状态: $current_status
+- Delta Specs: $delta_count 个
 EOF
 fi
 
@@ -335,6 +374,7 @@ if [[ "$JSON_MODE" == "true" ]]; then
   "to": "$target_dir",
   "reason": "$REASON",
   "previousStatus": "$current_status",
+  "deltaCount": $delta_count,
   "archivedAt": "$(get_beijing_time_iso)",
   "status": "success"
 }
@@ -347,5 +387,8 @@ else
     echo "   新位置: $target_dir"
     echo "   归档原因: $REASON"
     echo "   归档前状态: $current_status"
+    if [[ "$delta_count" -gt 0 ]]; then
+        echo "   Delta Specs: $delta_count 个"
+    fi
     echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 fi