cc-devflow 2.4.6 → 4.1.0

package/.claude/scripts/flow-context-add.sh

@@ -0,0 +1,134 @@
+#!/bin/bash
+# [INPUT]: 依赖 context/*.jsonl 文件
+# [OUTPUT]: 追加条目到指定的 jsonl 文件
+# [POS]: scripts 的 context 添加脚本，被 /flow-context add 调用
+# [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+
+set -e
+
+# ============================================================================
+# Usage
+# ============================================================================
+
+usage() {
+    cat << EOF
+Usage: flow-context-add.sh <agent> <path> <purpose> [--optional] [--type <file|directory|spec>]
+
+Add an entry to a context JSONL file.
+
+Arguments:
+    agent       Agent type (research, prd, tech, epic, dev, review)
+    path        File or directory path
+    purpose     Human-readable purpose
+
+Options:
+    --optional  Mark entry as optional
+    --type      Entry type (default: file)
+    --depth     Directory depth (only for directory type, default: 1)
+
+Examples:
+    flow-context-add.sh dev "src/utils/auth.ts" "Authentication utilities"
+    flow-context-add.sh dev "contracts/" "API contracts" --type directory --depth 2
+    flow-context-add.sh dev "ERROR_LOG.md" "Previous errors" --optional
+EOF
+    exit 1
+}
+
+# ============================================================================
+# Parse Arguments
+# ============================================================================
+
+AGENT=""
+PATH_ARG=""
+PURPOSE=""
+OPTIONAL="false"
+ENTRY_TYPE="file"
+DEPTH=1
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --optional)
+            OPTIONAL="true"
+            shift
+            ;;
+        --type)
+            ENTRY_TYPE="$2"
+            shift 2
+            ;;
+        --depth)
+            DEPTH="$2"
+            shift 2
+            ;;
+        --help|-h)
+            usage
+            ;;
+        *)
+            if [[ -z "$AGENT" ]]; then
+                AGENT="$1"
+            elif [[ -z "$PATH_ARG" ]]; then
+                PATH_ARG="$1"
+            elif [[ -z "$PURPOSE" ]]; then
+                PURPOSE="$1"
+            fi
+            shift
+            ;;
+    esac
+done
+
+if [[ -z "$AGENT" || -z "$PATH_ARG" || -z "$PURPOSE" ]]; then
+    echo "Error: agent, path, and purpose are required"
+    usage
+fi
+
+# ============================================================================
+# Detect REQ-ID
+# ============================================================================
+
+# Try environment variable first
+REQ_ID="${DEVFLOW_REQ_ID:-}"
+
+# Try git branch
+if [[ -z "$REQ_ID" ]]; then
+    BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
+    REQ_ID=$(echo "$BRANCH" | grep -oE 'REQ-[0-9]+' | head -1 || echo "")
+fi
+
+if [[ -z "$REQ_ID" ]]; then
+    echo "Error: Could not detect REQ-ID. Set DEVFLOW_REQ_ID or use a feature branch."
+    exit 1
+fi
+
+# ============================================================================
+# Main Logic
+# ============================================================================
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+CONTEXT_FILE="$PROJECT_ROOT/devflow/requirements/$REQ_ID/context/${AGENT}.jsonl"
+
+if [[ ! -f "$CONTEXT_FILE" ]]; then
+    echo "Error: Context file not found: $CONTEXT_FILE"
+    echo "Run '/flow-context init $REQ_ID' first."
+    exit 1
+fi
+
+# Build JSON entry
+if [[ "$ENTRY_TYPE" == "directory" ]]; then
+    if [[ "$OPTIONAL" == "true" ]]; then
+        ENTRY="{\"type\": \"$ENTRY_TYPE\", \"path\": \"$PATH_ARG\", \"purpose\": \"$PURPOSE\", \"depth\": $DEPTH, \"optional\": true}"
+    else
+        ENTRY="{\"type\": \"$ENTRY_TYPE\", \"path\": \"$PATH_ARG\", \"purpose\": \"$PURPOSE\", \"depth\": $DEPTH}"
+    fi
+else
+    if [[ "$OPTIONAL" == "true" ]]; then
+        ENTRY="{\"type\": \"$ENTRY_TYPE\", \"path\": \"$PATH_ARG\", \"purpose\": \"$PURPOSE\", \"optional\": true}"
+    else
+        ENTRY="{\"type\": \"$ENTRY_TYPE\", \"path\": \"$PATH_ARG\", \"purpose\": \"$PURPOSE\"}"
+    fi
+fi
+
+# Append to file
+echo "$ENTRY" >> "$CONTEXT_FILE"
+
+echo "✅ Added entry to $CONTEXT_FILE:"
+echo "   $ENTRY"

package/.claude/scripts/flow-context-init.sh

@@ -0,0 +1,133 @@
+#!/bin/bash
+# [INPUT]: 依赖 .claude/docs/templates/context/*.jsonl.template
+# [OUTPUT]: 创建 devflow/requirements/{REQ}/context/ 目录
+# [POS]: scripts 的 context 初始化脚本，被 /flow-context init 调用
+# [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+
+set -e
+
+# ============================================================================
+# Configuration
+# ============================================================================
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+TEMPLATES_DIR="$PROJECT_ROOT/.claude/docs/templates/context"
+
+# ============================================================================
+# Usage
+# ============================================================================
+
+usage() {
+    cat << EOF
+Usage: flow-context-init.sh <REQ-ID> [--type <backend|frontend|fullstack>]
+
+Initialize context directory for a requirement.
+
+Arguments:
+    REQ-ID      Requirement ID (e.g., REQ-007)
+
+Options:
+    --type      Project type (default: fullstack)
+                - backend: Exclude frontend specs
+                - frontend: Exclude backend specs
+                - fullstack: Include all specs
+
+Examples:
+    flow-context-init.sh REQ-007
+    flow-context-init.sh REQ-007 --type backend
+EOF
+    exit 1
+}
+
+# ============================================================================
+# Parse Arguments
+# ============================================================================
+
+REQ_ID=""
+PROJECT_TYPE="fullstack"
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --type)
+            PROJECT_TYPE="$2"
+            shift 2
+            ;;
+        --help|-h)
+            usage
+            ;;
+        *)
+            if [[ -z "$REQ_ID" ]]; then
+                REQ_ID="$1"
+            fi
+            shift
+            ;;
+    esac
+done
+
+if [[ -z "$REQ_ID" ]]; then
+    echo "Error: REQ-ID is required"
+    usage
+fi
+
+# Validate REQ-ID format
+if [[ ! "$REQ_ID" =~ ^REQ-[0-9]+$ ]]; then
+    echo "Error: Invalid REQ-ID format. Expected REQ-XXX (e.g., REQ-007)"
+    exit 1
+fi
+
+# ============================================================================
+# Main Logic
+# ============================================================================
+
+REQ_DIR="$PROJECT_ROOT/devflow/requirements/$REQ_ID"
+CONTEXT_DIR="$REQ_DIR/context"
+
+# Check if requirement directory exists
+if [[ ! -d "$REQ_DIR" ]]; then
+    echo "Error: Requirement directory not found: $REQ_DIR"
+    exit 1
+fi
+
+# Create context directory
+mkdir -p "$CONTEXT_DIR"
+
+echo "Initializing context for $REQ_ID (type: $PROJECT_TYPE)..."
+
+# Copy templates
+for template in "$TEMPLATES_DIR"/*.jsonl.template; do
+    if [[ -f "$template" ]]; then
+        filename=$(basename "$template" .template)
+        target="$CONTEXT_DIR/$filename"
+
+        # Skip if already exists
+        if [[ -f "$target" ]]; then
+            echo "  ⏭️  Skipping $filename (already exists)"
+            continue
+        fi
+
+        # Copy and filter based on project type
+        case $PROJECT_TYPE in
+            backend)
+                # Remove frontend spec entries
+                grep -v 'devflow/spec/frontend' "$template" > "$target" || cp "$template" "$target"
+                ;;
+            frontend)
+                # Remove backend spec entries
+                grep -v 'devflow/spec/backend' "$template" > "$target" || cp "$template" "$target"
+                ;;
+            *)
+                # Copy as-is
+                cp "$template" "$target"
+                ;;
+        esac
+
+        echo "  ✅ Created $filename"
+    fi
+done
+
+echo ""
+echo "Context initialized at: $CONTEXT_DIR"
+echo ""
+echo "Files created:"
+ls -la "$CONTEXT_DIR"

package/.claude/scripts/flow-context-validate.sh

@@ -0,0 +1,144 @@
+#!/bin/bash
+# [INPUT]: 依赖 context/*.jsonl 文件
+# [OUTPUT]: 验证结果输出到 stdout
+# [POS]: scripts 的 context 验证脚本，被 /flow-context validate 调用
+# [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+
+set -e
+
+# ============================================================================
+# Usage
+# ============================================================================
+
+usage() {
+    cat << EOF
+Usage: flow-context-validate.sh [REQ-ID]
+
+Validate all context paths exist for a requirement.
+
+Arguments:
+    REQ-ID      Requirement ID (optional, auto-detected from branch)
+
+Examples:
+    flow-context-validate.sh REQ-007
+    flow-context-validate.sh
+EOF
+    exit 1
+}
+
+# ============================================================================
+# Parse Arguments
+# ============================================================================
+
+REQ_ID="$1"
+
+# Auto-detect REQ-ID if not provided
+if [[ -z "$REQ_ID" ]]; then
+    REQ_ID="${DEVFLOW_REQ_ID:-}"
+
+    if [[ -z "$REQ_ID" ]]; then
+        BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
+        REQ_ID=$(echo "$BRANCH" | grep -oE 'REQ-[0-9]+' | head -1 || echo "")
+    fi
+fi
+
+if [[ -z "$REQ_ID" ]]; then
+    echo "Error: Could not detect REQ-ID. Provide it as argument or set DEVFLOW_REQ_ID."
+    usage
+fi
+
+# ============================================================================
+# Main Logic
+# ============================================================================
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+REQ_DIR="$PROJECT_ROOT/devflow/requirements/$REQ_ID"
+CONTEXT_DIR="$REQ_DIR/context"
+
+if [[ ! -d "$CONTEXT_DIR" ]]; then
+    echo "Error: Context directory not found: $CONTEXT_DIR"
+    echo "Run '/flow-context init $REQ_ID' first."
+    exit 1
+fi
+
+echo "Validating context for $REQ_ID..."
+echo ""
+
+TOTAL_VALID=0
+TOTAL_INVALID=0
+TOTAL_OPTIONAL_MISSING=0
+
+for jsonl_file in "$CONTEXT_DIR"/*.jsonl; do
+    if [[ ! -f "$jsonl_file" ]]; then
+        continue
+    fi
+
+    filename=$(basename "$jsonl_file")
+    valid=0
+    invalid=0
+    missing_paths=()
+
+    while IFS= read -r line || [[ -n "$line" ]]; do
+        # Skip empty lines and comments
+        [[ -z "$line" || "$line" =~ ^[[:space:]]*# || "$line" =~ ^[[:space:]]*// ]] && continue
+
+        # Parse JSON (basic extraction)
+        path=$(echo "$line" | grep -oP '"path"\s*:\s*"\K[^"]+' || echo "")
+        type=$(echo "$line" | grep -oP '"type"\s*:\s*"\K[^"]+' || echo "file")
+        optional=$(echo "$line" | grep -oP '"optional"\s*:\s*\K(true|false)' || echo "false")
+
+        if [[ -z "$path" ]]; then
+            continue
+        fi
+
+        # Resolve path
+        if [[ "$type" == "spec" ]]; then
+            full_path="$PROJECT_ROOT/$path"
+        else
+            full_path="$REQ_DIR/$path"
+        fi
+
+        # Check existence
+        if [[ -e "$full_path" ]]; then
+            ((valid++))
+        else
+            if [[ "$optional" == "true" ]]; then
+                ((TOTAL_OPTIONAL_MISSING++))
+            else
+                ((invalid++))
+                missing_paths+=("$path")
+            fi
+        fi
+    done < "$jsonl_file"
+
+    TOTAL_VALID=$((TOTAL_VALID + valid))
+    TOTAL_INVALID=$((TOTAL_INVALID + invalid))
+
+    total=$((valid + invalid))
+    if [[ $invalid -eq 0 ]]; then
+        echo "  ✓ $filename: $valid/$total paths valid"
+    else
+        echo "  ✗ $filename: $valid/$total paths valid"
+        for mp in "${missing_paths[@]}"; do
+            echo "    - Missing: $mp"
+        done
+    fi
+done
+
+echo ""
+GRAND_TOTAL=$((TOTAL_VALID + TOTAL_INVALID))
+if [[ $GRAND_TOTAL -gt 0 ]]; then
+    PERCENT=$((TOTAL_VALID * 100 / GRAND_TOTAL))
+    echo "Overall: $TOTAL_VALID/$GRAND_TOTAL paths valid ($PERCENT%)"
+    if [[ $TOTAL_OPTIONAL_MISSING -gt 0 ]]; then
+        echo "Optional missing: $TOTAL_OPTIONAL_MISSING (not counted in validation)"
+    fi
+else
+    echo "No context entries found."
+fi
+
+# Exit with error if any required paths are missing
+if [[ $TOTAL_INVALID -gt 0 ]]; then
+    exit 1
+fi

package/.claude/scripts/flow-delta-apply.sh

@@ -0,0 +1,297 @@
+#!/bin/bash
+# [INPUT]: 依赖 deltas/{delta-id}/delta.md, delta-parser.ts
+# [OUTPUT]: 应用 delta 到 PRD.md，移动到 archive/
+# [POS]: scripts 的 delta spec 应用脚本，被 /flow:delta apply 调用
+# [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+
+set -e
+
+# ============================================================================
+# Configuration
+# ============================================================================
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+PARSER_SCRIPT="$SCRIPT_DIR/delta-parser.ts"
+ARCHIVE_DIR="$PROJECT_ROOT/devflow/archive"
+
+# ============================================================================
+# Usage
+# ============================================================================
+
+usage() {
+    cat << EOF
+Usage: flow-delta-apply.sh <REQ-ID> <delta-slug> [--dry-run] [--force]
+
+Apply a delta spec to the main PRD.md specification.
+
+Arguments:
+    REQ-ID          Requirement ID (e.g., REQ-123)
+    delta-slug      Delta identifier (e.g., add-2fa or 2026-02-01-add-2fa)
+
+Options:
+    --dry-run       Show what would be done without making changes
+    --force         Apply even if status is not 'approved'
+    --all           Apply all approved deltas
+
+Examples:
+    flow-delta-apply.sh REQ-123 add-2fa
+    flow-delta-apply.sh REQ-123 add-2fa --dry-run
+    flow-delta-apply.sh REQ-123 --all
+EOF
+    exit 1
+}
+
+# ============================================================================
+# Parse Arguments
+# ============================================================================
+
+REQ_ID=""
+DELTA_SLUG=""
+DRY_RUN=false
+FORCE=false
+APPLY_ALL=false
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --dry-run)
+            DRY_RUN=true
+            shift
+            ;;
+        --force)
+            FORCE=true
+            shift
+            ;;
+        --all)
+            APPLY_ALL=true
+            shift
+            ;;
+        --help|-h)
+            usage
+            ;;
+        *)
+            if [[ -z "$REQ_ID" ]]; then
+                REQ_ID="$1"
+            elif [[ -z "$DELTA_SLUG" ]]; then
+                DELTA_SLUG="$1"
+            fi
+            shift
+            ;;
+    esac
+done
+
+if [[ -z "$REQ_ID" ]]; then
+    echo "Error: REQ-ID is required"
+    usage
+fi
+
+if [[ -z "$DELTA_SLUG" && "$APPLY_ALL" != "true" ]]; then
+    echo "Error: delta-slug is required (or use --all)"
+    usage
+fi
+
+# Validate REQ-ID format
+if [[ ! "$REQ_ID" =~ ^REQ-[0-9]+$ ]]; then
+    echo "Error: Invalid REQ-ID format. Expected: REQ-XXX"
+    exit 1
+fi
+
+# ============================================================================
+# Helper Functions
+# ============================================================================
+
+find_delta_dir() {
+    local req_dir="$1"
+    local slug="$2"
+    local deltas_dir="$req_dir/deltas"
+
+    # Try exact match first
+    if [[ -d "$deltas_dir/$slug" ]]; then
+        echo "$deltas_dir/$slug"
+        return 0
+    fi
+
+    # Try to find by suffix (slug without date prefix)
+    for dir in "$deltas_dir"/*-"$slug"; do
+        if [[ -d "$dir" ]]; then
+            echo "$dir"
+            return 0
+        fi
+    done
+
+    return 1
+}
+
+get_delta_status() {
+    local delta_file="$1"
+    grep -E '^status:' "$delta_file" | head -1 | sed 's/status:[[:space:]]*"\?\([^"]*\)"\?/\1/'
+}
+
+update_delta_status() {
+    local delta_file="$1"
+    local new_status="$2"
+
+    if $DRY_RUN; then
+        echo "  [DRY-RUN] Would update status to '$new_status'"
+        return 0
+    fi
+
+    # Use sed to update status in frontmatter
+    if [[ "$(uname)" == "Darwin" ]]; then
+        sed -i '' "s/^status:.*$/status: \"$new_status\"/" "$delta_file"
+    else
+        sed -i "s/^status:.*$/status: \"$new_status\"/" "$delta_file"
+    fi
+}
+
+apply_single_delta() {
+    local delta_dir="$1"
+    local delta_id=$(basename "$delta_dir")
+    local delta_file="$delta_dir/delta.md"
+    local prd_file="$REQ_DIR/PRD.md"
+
+    echo "Applying delta: $delta_id"
+
+    # Check delta file exists
+    if [[ ! -f "$delta_file" ]]; then
+        echo "  Error: Delta file not found: $delta_file"
+        return 1
+    fi
+
+    # Check PRD.md exists
+    if [[ ! -f "$prd_file" ]]; then
+        echo "  Error: PRD.md not found: $prd_file"
+        return 1
+    fi
+
+    # Check status
+    local status=$(get_delta_status "$delta_file")
+    if [[ "$status" != "approved" && "$FORCE" != "true" ]]; then
+        echo "  Error: Delta status is '$status', expected 'approved'"
+        echo "  Use --force to apply anyway"
+        return 1
+    fi
+
+    # Check if parser exists
+    if [[ ! -f "$PARSER_SCRIPT" ]]; then
+        echo "  Error: Delta parser not found: $PARSER_SCRIPT"
+        echo "  Falling back to simple copy..."
+
+        if $DRY_RUN; then
+            echo "  [DRY-RUN] Would apply delta to PRD.md"
+        else
+            # Simple fallback: just log that we would apply
+            echo "  Warning: Full delta parsing not available"
+            echo "  Please manually review and apply changes from: $delta_file"
+        fi
+        return 0
+    fi
+
+    # Apply delta using TypeScript parser
+    if $DRY_RUN; then
+        echo "  [DRY-RUN] Would apply delta to PRD.md"
+        echo "  Parsing delta..."
+        npx ts-node "$PARSER_SCRIPT" parse "$delta_file" 2>/dev/null || {
+            echo "  Warning: Could not parse delta (ts-node may not be available)"
+        }
+    else
+        echo "  Applying changes to PRD.md..."
+
+        # Create backup
+        cp "$prd_file" "$prd_file.bak"
+
+        # Apply delta
+        if npx ts-node "$PARSER_SCRIPT" apply "$prd_file" "$delta_file" > "$prd_file.new" 2>/dev/null; then
+            mv "$prd_file.new" "$prd_file"
+            rm "$prd_file.bak"
+            echo "  ✓ Changes applied to PRD.md"
+        else
+            echo "  Warning: TypeScript parser failed, using fallback"
+            rm -f "$prd_file.new"
+            mv "$prd_file.bak" "$prd_file"
+            echo "  Please manually review and apply changes from: $delta_file"
+        fi
+
+        # Update status
+        update_delta_status "$delta_file" "applied"
+        echo "  ✓ Status updated to 'applied'"
+
+        # Archive delta
+        local date_prefix=$(date +"%Y-%m")
+        local archive_target="$ARCHIVE_DIR/$date_prefix/$REQ_ID/deltas/$delta_id"
+
+        mkdir -p "$archive_target"
+        cp -r "$delta_dir"/* "$archive_target/"
+        rm -rf "$delta_dir"
+
+        echo "  ✓ Archived to: $archive_target"
+    fi
+
+    return 0
+}
+
+# ============================================================================
+# Main Logic
+# ============================================================================
+
+REQ_DIR="$PROJECT_ROOT/devflow/requirements/$REQ_ID"
+DELTAS_DIR="$REQ_DIR/deltas"
+
+if [[ ! -d "$REQ_DIR" ]]; then
+    echo "Error: Requirement directory not found: $REQ_DIR"
+    exit 1
+fi
+
+if [[ ! -d "$DELTAS_DIR" ]]; then
+    echo "No deltas found for $REQ_ID"
+    exit 0
+fi
+
+if $APPLY_ALL; then
+    echo "Applying all approved deltas for $REQ_ID..."
+    echo ""
+
+    APPLIED=0
+    SKIPPED=0
+
+    for delta_dir in "$DELTAS_DIR"/*/; do
+        if [[ ! -d "$delta_dir" ]]; then
+            continue
+        fi
+
+        delta_file="$delta_dir/delta.md"
+        if [[ ! -f "$delta_file" ]]; then
+            continue
+        fi
+
+        status=$(get_delta_status "$delta_file")
+        if [[ "$status" == "approved" ]]; then
+            if apply_single_delta "$delta_dir"; then
+                ((APPLIED++))
+            fi
+        else
+            ((SKIPPED++))
+        fi
+        echo ""
+    done
+
+    echo "Summary: $APPLIED applied, $SKIPPED skipped (not approved)"
+else
+    # Find the specific delta
+    DELTA_DIR=$(find_delta_dir "$REQ_DIR" "$DELTA_SLUG")
+
+    if [[ -z "$DELTA_DIR" || ! -d "$DELTA_DIR" ]]; then
+        echo "Error: Delta not found: $DELTA_SLUG"
+        echo "Available deltas:"
+        ls -1 "$DELTAS_DIR" 2>/dev/null || echo "  (none)"
+        exit 1
+    fi
+
+    apply_single_delta "$DELTA_DIR"
+fi
+
+echo ""
+if $DRY_RUN; then
+    echo "This was a dry run. No changes were made."
+    echo "Run without --dry-run to apply changes."
+fi