cc-devflow 2.4.6 → 4.1.0

package/.claude/skills/workflow/flow-spec/scripts/entry-gate.sh

@@ -0,0 +1,194 @@
+#!/bin/bash
+# ============================================================================
+# flow-spec Entry Gate
+# ============================================================================
+# [INPUT]: REQ_ID (参数或自动检测)
+# [OUTPUT]: 验证结果 (exit code 0=pass, 1=fail)
+# [POS]: flow-spec 的入口检查，验证前置条件
+# [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+# ============================================================================
+
+set -euo pipefail
+
+# ============================================================================
+# 参数解析
+# ============================================================================
+
+REQ_ID=""
+SKIP_TECH=false
+SKIP_UI=false
+RETRY=false
+FROM_STAGE=""
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --skip-tech)
+            SKIP_TECH=true
+            shift
+            ;;
+        --skip-ui)
+            SKIP_UI=true
+            shift
+            ;;
+        --retry)
+            RETRY=true
+            shift
+            ;;
+        --from=*)
+            FROM_STAGE="${1#*=}"
+            shift
+            ;;
+        *)
+            if [[ -z "$REQ_ID" ]]; then
+                REQ_ID="$1"
+            fi
+            shift
+            ;;
+    esac
+done
+
+# ============================================================================
+# REQ_ID 解析
+# ============================================================================
+
+if [[ -z "$REQ_ID" ]]; then
+    # 尝试从分支名推断
+    BRANCH=$(git branch --show-current 2>/dev/null || echo "")
+    if [[ "$BRANCH" =~ feature/(REQ-[0-9]+) ]]; then
+        REQ_ID="${BASH_REMATCH[1]}"
+    fi
+fi
+
+if [[ -z "$REQ_ID" ]]; then
+    # 尝试从 orchestration_status.json 获取
+    STATUS_FILE="devflow/requirements/*/orchestration_status.json"
+    for f in $STATUS_FILE; do
+        if [[ -f "$f" ]]; then
+            REQ_ID=$(jq -r '.req_id // empty' "$f" 2>/dev/null || echo "")
+            if [[ -n "$REQ_ID" ]]; then
+                break
+            fi
+        fi
+    done
+fi
+
+if [[ -z "$REQ_ID" ]]; then
+    echo "ERROR: REQ_ID not provided and cannot be auto-detected"
+    echo "Usage: entry-gate.sh REQ-XXX [--skip-tech] [--skip-ui]"
+    exit 1
+fi
+
+# ============================================================================
+# 路径定义
+# ============================================================================
+
+REQ_DIR="devflow/requirements/${REQ_ID}"
+BRAINSTORM_FILE="${REQ_DIR}/BRAINSTORM.md"
+RESEARCH_FILE="${REQ_DIR}/research/research.md"
+STATUS_FILE="${REQ_DIR}/orchestration_status.json"
+
+# ============================================================================
+# 检查 1: REQ_ID 格式
+# ============================================================================
+
+if [[ ! "$REQ_ID" =~ ^REQ-[0-9]+$ ]]; then
+    echo "ERROR: Invalid REQ_ID format: $REQ_ID"
+    echo "Expected: REQ-XXX (e.g., REQ-001, REQ-123)"
+    exit 1
+fi
+
+echo "✓ REQ_ID format valid: $REQ_ID"
+
+# ============================================================================
+# 检查 2: 目录存在
+# ============================================================================
+
+if [[ ! -d "$REQ_DIR" ]]; then
+    echo "ERROR: Requirement directory not found: $REQ_DIR"
+    echo "Run /flow-init first"
+    exit 1
+fi
+
+echo "✓ Requirement directory exists: $REQ_DIR"
+
+# ============================================================================
+# 检查 3: BRAINSTORM.md 存在
+# ============================================================================
+
+if [[ ! -f "$BRAINSTORM_FILE" ]]; then
+    echo "ERROR: BRAINSTORM.md not found: $BRAINSTORM_FILE"
+    echo "Run /flow-init first"
+    exit 1
+fi
+
+echo "✓ BRAINSTORM.md exists"
+
+# ============================================================================
+# 检查 4: Research 完成
+# ============================================================================
+
+if [[ ! -f "$RESEARCH_FILE" ]]; then
+    echo "ERROR: research.md not found: $RESEARCH_FILE"
+    echo "Run /flow-init with research first"
+    exit 1
+fi
+
+# 检查 research.md 无 TODO/PLACEHOLDER
+if grep -qE '\{\{[A-Z_]+\}\}|TODO|TBD|PLACEHOLDER' "$RESEARCH_FILE"; then
+    echo "WARNING: research.md contains TODO/PLACEHOLDER markers"
+    echo "Consider completing research before proceeding"
+fi
+
+echo "✓ Research file exists"
+
+# ============================================================================
+# 检查 5: Status Check
+# ============================================================================
+
+if [[ -f "$STATUS_FILE" ]]; then
+    CURRENT_STATUS=$(jq -r '.status // "unknown"' "$STATUS_FILE")
+
+    VALID_STATUSES=("initialized" "spec_failed" "prd_complete" "tech_design_complete" "ui_complete")
+
+    if [[ "$RETRY" == "true" ]]; then
+        echo "✓ Retry mode: bypassing status check"
+    elif [[ ! " ${VALID_STATUSES[*]} " =~ " ${CURRENT_STATUS} " ]]; then
+        echo "ERROR: Invalid status for /flow-spec: $CURRENT_STATUS"
+        echo "Valid statuses: ${VALID_STATUSES[*]}"
+        exit 1
+    else
+        echo "✓ Status valid: $CURRENT_STATUS"
+    fi
+else
+    echo "WARNING: orchestration_status.json not found, creating..."
+fi
+
+# ============================================================================
+# 输出结果
+# ============================================================================
+
+echo ""
+echo "============================================"
+echo "Entry Gate PASSED"
+echo "============================================"
+echo "REQ_ID: $REQ_ID"
+echo "REQ_DIR: $REQ_DIR"
+echo "SKIP_TECH: $SKIP_TECH"
+echo "SKIP_UI: $SKIP_UI"
+echo "FROM_STAGE: ${FROM_STAGE:-prd}"
+echo "============================================"
+
+# 输出 JSON 供后续脚本使用
+cat << EOF
+{
+  "req_id": "$REQ_ID",
+  "req_dir": "$REQ_DIR",
+  "skip_tech": $SKIP_TECH,
+  "skip_ui": $SKIP_UI,
+  "from_stage": "${FROM_STAGE:-prd}",
+  "brainstorm_file": "$BRAINSTORM_FILE",
+  "research_file": "$RESEARCH_FILE"
+}
+EOF
+
+exit 0

package/.claude/skills/workflow/flow-spec/scripts/exit-gate.sh

@@ -0,0 +1,244 @@
+#!/bin/bash
+# ============================================================================
+# flow-spec Exit Gate
+# ============================================================================
+# [INPUT]: REQ_ID, 生成的文件列表
+# [OUTPUT]: 验证结果 (exit code 0=pass, 1=fail)
+# [POS]: flow-spec 的出口检查，验证所有输出文件
+# [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+# ============================================================================
+
+set -euo pipefail
+
+# ============================================================================
+# 参数解析
+# ============================================================================
+
+REQ_ID=""
+SKIP_TECH=false
+SKIP_UI=false
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --skip-tech)
+            SKIP_TECH=true
+            shift
+            ;;
+        --skip-ui)
+            SKIP_UI=true
+            shift
+            ;;
+        *)
+            if [[ -z "$REQ_ID" ]]; then
+                REQ_ID="$1"
+            fi
+            shift
+            ;;
+    esac
+done
+
+if [[ -z "$REQ_ID" ]]; then
+    echo "ERROR: REQ_ID required"
+    exit 1
+fi
+
+# ============================================================================
+# 路径定义
+# ============================================================================
+
+REQ_DIR="devflow/requirements/${REQ_ID}"
+PRD_FILE="${REQ_DIR}/PRD.md"
+TECH_FILE="${REQ_DIR}/TECH_DESIGN.md"
+UI_FILE="${REQ_DIR}/UI_PROTOTYPE.html"
+EPIC_FILE="${REQ_DIR}/EPIC.md"
+TASKS_FILE="${REQ_DIR}/TASKS.md"
+STATUS_FILE="${REQ_DIR}/orchestration_status.json"
+
+ERRORS=()
+WARNINGS=()
+
+# ============================================================================
+# 检查 1: PRD.md
+# ============================================================================
+
+echo "Checking PRD.md..."
+
+if [[ ! -f "$PRD_FILE" ]]; then
+    ERRORS+=("PRD.md not found")
+else
+    # 检查 placeholder
+    if grep -qE '\{\{[A-Z_]+\}\}' "$PRD_FILE"; then
+        ERRORS+=("PRD.md contains {{PLACEHOLDER}} markers")
+    fi
+    echo "✓ PRD.md exists and valid"
+fi
+
+# ============================================================================
+# 检查 2: TECH_DESIGN.md (如果未跳过)
+# ============================================================================
+
+if [[ "$SKIP_TECH" == "false" ]]; then
+    echo "Checking TECH_DESIGN.md..."
+
+    if [[ ! -f "$TECH_FILE" ]]; then
+        ERRORS+=("TECH_DESIGN.md not found (use --skip-tech to skip)")
+    else
+        if grep -qE '\{\{[A-Z_]+\}\}' "$TECH_FILE"; then
+            ERRORS+=("TECH_DESIGN.md contains {{PLACEHOLDER}} markers")
+        fi
+
+        # 检查必需章节
+        if ! grep -q "## 1. System Architecture" "$TECH_FILE"; then
+            WARNINGS+=("TECH_DESIGN.md missing System Architecture section")
+        fi
+        if ! grep -q "## 4. API Design" "$TECH_FILE"; then
+            WARNINGS+=("TECH_DESIGN.md missing API Design section")
+        fi
+
+        echo "✓ TECH_DESIGN.md exists"
+    fi
+else
+    echo "⊘ TECH_DESIGN.md skipped"
+fi
+
+# ============================================================================
+# 检查 3: UI_PROTOTYPE.html (如果未跳过)
+# ============================================================================
+
+if [[ "$SKIP_UI" == "false" ]]; then
+    echo "Checking UI_PROTOTYPE.html..."
+
+    # 检查 PRD 是否有 UI 关键词
+    HAS_UI_KEYWORDS=false
+    if [[ -f "$PRD_FILE" ]]; then
+        if grep -qiE '用户界面|前端|页面|交互|UI|界面设计' "$PRD_FILE"; then
+            HAS_UI_KEYWORDS=true
+        fi
+    fi
+
+    if [[ "$HAS_UI_KEYWORDS" == "true" ]]; then
+        if [[ ! -f "$UI_FILE" ]]; then
+            WARNINGS+=("UI_PROTOTYPE.html not found but PRD contains UI keywords")
+        else
+            echo "✓ UI_PROTOTYPE.html exists"
+        fi
+    else
+        echo "⊘ UI_PROTOTYPE.html not required (no UI keywords in PRD)"
+    fi
+else
+    echo "⊘ UI_PROTOTYPE.html skipped"
+fi
+
+# ============================================================================
+# 检查 4: EPIC.md
+# ============================================================================
+
+echo "Checking EPIC.md..."
+
+if [[ ! -f "$EPIC_FILE" ]]; then
+    ERRORS+=("EPIC.md not found")
+else
+    if grep -qE '\{\{[A-Z_]+\}\}' "$EPIC_FILE"; then
+        ERRORS+=("EPIC.md contains {{PLACEHOLDER}} markers")
+    fi
+    echo "✓ EPIC.md exists and valid"
+fi
+
+# ============================================================================
+# 检查 5: TASKS.md
+# ============================================================================
+
+echo "Checking TASKS.md..."
+
+if [[ ! -f "$TASKS_FILE" ]]; then
+    ERRORS+=("TASKS.md not found")
+else
+    if grep -qE '\{\{[A-Z_]+\}\}' "$TASKS_FILE"; then
+        ERRORS+=("TASKS.md contains {{PLACEHOLDER}} markers")
+    fi
+
+    # 检查 TDD 顺序: Phase 2 (Tests) 应该在 Phase 3 (Implementation) 之前
+    PHASE2_LINE=$(grep -n "Phase 2" "$TASKS_FILE" | head -1 | cut -d: -f1 || echo "0")
+    PHASE3_LINE=$(grep -n "Phase 3" "$TASKS_FILE" | head -1 | cut -d: -f1 || echo "0")
+
+    if [[ "$PHASE2_LINE" -gt 0 && "$PHASE3_LINE" -gt 0 ]]; then
+        if [[ "$PHASE2_LINE" -gt "$PHASE3_LINE" ]]; then
+            ERRORS+=("TASKS.md TDD order incorrect: Phase 2 (Tests) should come before Phase 3 (Implementation)")
+        else
+            echo "✓ TASKS.md TDD order correct"
+        fi
+    fi
+
+    echo "✓ TASKS.md exists"
+fi
+
+# ============================================================================
+# 更新状态
+# ============================================================================
+
+if [[ ${#ERRORS[@]} -eq 0 ]]; then
+    echo "Updating orchestration_status.json..."
+
+    # 构建输出文件列表
+    OUTPUTS='["PRD.md", "EPIC.md", "TASKS.md"'
+    if [[ "$SKIP_TECH" == "false" && -f "$TECH_FILE" ]]; then
+        OUTPUTS+=', "TECH_DESIGN.md"'
+    fi
+    if [[ "$SKIP_UI" == "false" && -f "$UI_FILE" ]]; then
+        OUTPUTS+=', "UI_PROTOTYPE.html"'
+    fi
+    OUTPUTS+=']'
+
+    # 更新状态文件
+    if [[ -f "$STATUS_FILE" ]]; then
+        jq --arg status "spec_complete" \
+           --arg phase "spec" \
+           --argjson outputs "$OUTPUTS" \
+           '.status = $status | .phase = $phase | .outputs = $outputs | .updated_at = now | .spec_completed_at = now' \
+           "$STATUS_FILE" > "${STATUS_FILE}.tmp" && mv "${STATUS_FILE}.tmp" "$STATUS_FILE"
+    fi
+
+    echo "✓ Status updated to spec_complete"
+fi
+
+# ============================================================================
+# 输出结果
+# ============================================================================
+
+echo ""
+echo "============================================"
+
+if [[ ${#ERRORS[@]} -gt 0 ]]; then
+    echo "Exit Gate FAILED"
+    echo "============================================"
+    echo ""
+    echo "ERRORS:"
+    for err in "${ERRORS[@]}"; do
+        echo "  ✗ $err"
+    done
+fi
+
+if [[ ${#WARNINGS[@]} -gt 0 ]]; then
+    echo ""
+    echo "WARNINGS:"
+    for warn in "${WARNINGS[@]}"; do
+        echo "  ⚠ $warn"
+    done
+fi
+
+if [[ ${#ERRORS[@]} -eq 0 ]]; then
+    echo "Exit Gate PASSED"
+    echo "============================================"
+    echo ""
+    echo "Generated files:"
+    echo "  - PRD.md"
+    [[ "$SKIP_TECH" == "false" && -f "$TECH_FILE" ]] && echo "  - TECH_DESIGN.md"
+    [[ "$SKIP_UI" == "false" && -f "$UI_FILE" ]] && echo "  - UI_PROTOTYPE.html"
+    echo "  - EPIC.md"
+    echo "  - TASKS.md"
+    echo ""
+    echo "Next step: /flow-dev \"$REQ_ID\""
+    exit 0
+else
+    exit 1
+fi

package/.claude/skills/workflow/flow-spec/scripts/parallel-orchestrator.sh

@@ -0,0 +1,205 @@
+#!/bin/bash
+# ============================================================================
+# flow-spec Parallel Orchestrator
+# ============================================================================
+# [INPUT]: REQ_ID, 模式标志
+# [OUTPUT]: 并行执行状态
+# [POS]: 协调 tech-architect 和 ui-designer 的并行执行
+# [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+# ============================================================================
+
+# 注意: 此脚本主要用于文档目的
+# 实际的并行执行由 Claude 的 Task tool 处理
+# 此脚本提供执行逻辑的参考实现
+
+set -euo pipefail
+
+# ============================================================================
+# 参数解析
+# ============================================================================
+
+REQ_ID=""
+SKIP_TECH=false
+SKIP_UI=false
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --skip-tech)
+            SKIP_TECH=true
+            shift
+            ;;
+        --skip-ui)
+            SKIP_UI=true
+            shift
+            ;;
+        *)
+            if [[ -z "$REQ_ID" ]]; then
+                REQ_ID="$1"
+            fi
+            shift
+            ;;
+    esac
+done
+
+if [[ -z "$REQ_ID" ]]; then
+    echo "ERROR: REQ_ID required"
+    exit 1
+fi
+
+# ============================================================================
+# 路径定义
+# ============================================================================
+
+REQ_DIR="devflow/requirements/${REQ_ID}"
+PRD_FILE="${REQ_DIR}/PRD.md"
+EXECUTION_LOG="${REQ_DIR}/EXECUTION_LOG.md"
+
+# ============================================================================
+# 并行执行逻辑 (伪代码)
+# ============================================================================
+
+cat << 'EOF'
+============================================
+Parallel Orchestration Logic
+============================================
+
+This script documents the parallel execution strategy.
+Actual execution is handled by Claude's Task tool.
+
+Execution Flow:
+---------------
+
+1. PRD Generation (Sequential - Must complete first)
+   Agent: prd-writer
+   Output: PRD.md
+
+2. Parallel Execution (After PRD completes)
+
+   ┌─────────────────────────────────────────────────────┐
+   │                                                     │
+   │  ┌─────────────────┐    ┌─────────────────┐        │
+   │  │ tech-architect  │    │  ui-designer    │        │
+   │  │                 │    │                 │        │
+   │  │ Condition:      │    │ Condition:      │        │
+   │  │ !--skip-tech    │    │ !--skip-ui AND  │        │
+   │  │                 │    │ UI keywords in  │        │
+   │  │                 │    │ PRD             │        │
+   │  │                 │    │                 │        │
+   │  │ Output:         │    │ Output:         │        │
+   │  │ - TECH_DESIGN   │    │ - UI_PROTOTYPE  │        │
+   │  │ - data-model    │    │ - ui_design_    │        │
+   │  │ - contracts/    │    │   strategy.md   │        │
+   │  └────────┬────────┘    └────────┬────────┘        │
+   │           │                      │                 │
+   │           └──────────┬───────────┘                 │
+   │                      │                             │
+   │                      ▼                             │
+   │              Wait for both                         │
+   │                                                    │
+   └─────────────────────────────────────────────────────┘
+
+3. Epic Generation (After parallel stage completes)
+   Agent: planner
+   Input: PRD.md + TECH_DESIGN.md (optional) + UI_PROTOTYPE.html (optional)
+   Output: EPIC.md + TASKS.md
+
+Claude Task Tool Usage:
+-----------------------
+
+// Stage 2: Parallel execution
+const tasks = [];
+
+if (!skipTech) {
+  tasks.push(Task({
+    subagent_type: "tech-architect",
+    prompt: `Generate TECH_DESIGN.md for ${REQ_ID}`,
+    description: "Tech design generation"
+  }));
+}
+
+if (!skipUI && hasUIKeywords) {
+  tasks.push(Task({
+    subagent_type: "ui-designer",
+    prompt: `Generate UI_PROTOTYPE.html for ${REQ_ID}`,
+    description: "UI prototype generation"
+  }));
+}
+
+// Execute in parallel
+await Promise.all(tasks);
+
+Error Handling:
+---------------
+
+- If tech-architect fails: Continue with UI, mark tech as skipped
+- If ui-designer fails: Continue without UI, mark ui as skipped
+- If both fail: Log error, status = spec_failed
+
+Timing Expectations:
+--------------------
+
+| Stage | Duration | Notes |
+|-------|----------|-------|
+| PRD   | 2-3 min  | Sequential |
+| Tech  | 2-3 min  | Parallel |
+| UI    | 2-3 min  | Parallel |
+| Epic  | 2-3 min  | Sequential |
+| Total | 5-8 min  | With parallelization |
+
+Without parallelization: 8-12 min
+Improvement: ~35% time reduction
+
+============================================
+EOF
+
+# ============================================================================
+# 检测 UI 关键词
+# ============================================================================
+
+echo ""
+echo "Checking PRD for UI keywords..."
+
+if [[ -f "$PRD_FILE" ]]; then
+    if grep -qiE '用户界面|前端|页面|交互|UI|界面设计|Web页面' "$PRD_FILE"; then
+        echo "✓ UI keywords detected in PRD"
+        echo "  ui-designer will be invoked (unless --skip-ui)"
+    else
+        echo "⊘ No UI keywords in PRD"
+        echo "  ui-designer will be skipped"
+    fi
+else
+    echo "✗ PRD.md not found"
+fi
+
+# ============================================================================
+# 输出执行计划
+# ============================================================================
+
+echo ""
+echo "============================================"
+echo "Execution Plan for $REQ_ID"
+echo "============================================"
+echo ""
+echo "Stage 1: PRD Generation"
+echo "  Agent: prd-writer"
+echo "  Status: Pending"
+echo ""
+echo "Stage 2: Parallel Execution"
+if [[ "$SKIP_TECH" == "false" ]]; then
+    echo "  [A] tech-architect: Enabled"
+else
+    echo "  [A] tech-architect: Skipped (--skip-tech)"
+fi
+if [[ "$SKIP_UI" == "false" ]]; then
+    echo "  [B] ui-designer: Enabled (if UI keywords)"
+else
+    echo "  [B] ui-designer: Skipped (--skip-ui)"
+fi
+echo ""
+echo "Stage 3: Epic Generation"
+echo "  Agent: planner"
+echo "  Status: Pending"
+echo ""
+echo "============================================"
+
+exit 0