cc-devflow 2.4.6 → 4.1.0

package/.claude/skills/workflow/flow-dev/assets/IMPLEMENTATION_PLAN_TEMPLATE.md

@@ -0,0 +1,71 @@
+# Implementation Plan Template
+
+> [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+
+---
+req_id: "${REQ_ID}"
+task_id: "${TASK_ID}"
+created_at: "${TIMESTAMP}"
+status: "pending"
+---
+
+## Task Overview
+
+**Task**: ${TASK_DESCRIPTION}
+
+**DoD (Definition of Done)**:
+${DOD_ITEMS}
+
+## Implementation Strategy
+
+### Approach
+
+${APPROACH_DESCRIPTION}
+
+### Files to Modify
+
+| File | Action | Description |
+|------|--------|-------------|
+| ${FILE_PATH} | ${ACTION} | ${DESCRIPTION} |
+
+### Dependencies
+
+- ${DEPENDENCY_1}
+- ${DEPENDENCY_2}
+
+## TDD Sequence
+
+### Phase 2: Write Tests First
+
+```${LANGUAGE}
+// Test file: ${TEST_FILE_PATH}
+${TEST_CODE}
+```
+
+**Expected Result**: Test should FAIL initially
+
+### Phase 3: Implementation
+
+```${LANGUAGE}
+// Implementation file: ${IMPL_FILE_PATH}
+${IMPL_CODE}
+```
+
+**Expected Result**: Test should PASS after implementation
+
+## Verification Steps
+
+1. Run tests: `${TEST_COMMAND}`
+2. Verify output: ${EXPECTED_OUTPUT}
+3. Check coverage: `${COVERAGE_COMMAND}`
+
+## Constitution Compliance
+
+- [ ] Article I: Complete implementation, no placeholders
+- [ ] Article II: Reused existing code where possible
+- [ ] Article III: No hardcoded secrets
+- [ ] Article VI: TDD sequence followed
+
+## Notes
+
+${ADDITIONAL_NOTES}

package/.claude/skills/workflow/flow-dev/context.jsonl

@@ -0,0 +1,8 @@
+{"file": "devflow/requirements/{REQ}/TASKS.md", "reason": "Task list"}
+{"file": "devflow/requirements/{REQ}/EPIC.md", "reason": "Epic overview"}
+{"file": "devflow/requirements/{REQ}/BRAINSTORM.md", "reason": "Original intent"}
+{"file": "devflow/requirements/{REQ}/ERROR_LOG.md", "reason": "Previous errors", "optional": true}
+{"file": "devflow/requirements/{REQ}/TECH_DESIGN.md", "reason": "Technical design", "optional": true}
+{"file": "devflow/spec/frontend/index.md", "reason": "Frontend conventions", "optional": true}
+{"file": "devflow/spec/backend/index.md", "reason": "Backend conventions", "optional": true}
+{"file": ".claude/rules/project-constitution.md", "reason": "Quality rules"}

package/.claude/skills/workflow/flow-dev/dev-implementer.jsonl

@@ -0,0 +1,8 @@
+{"file": "devflow/requirements/{REQ}/TASKS.md", "reason": "Task list with DoD"}
+{"file": "devflow/requirements/{REQ}/EPIC.md", "reason": "Epic overview and architecture"}
+{"file": "devflow/requirements/{REQ}/BRAINSTORM.md", "reason": "Original intent and context"}
+{"file": "devflow/requirements/{REQ}/ERROR_LOG.md", "reason": "Previous errors to avoid", "optional": true}
+{"file": "devflow/requirements/{REQ}/TECH_DESIGN.md", "reason": "Technical design decisions", "optional": true}
+{"file": "devflow/spec/frontend/index.md", "reason": "Frontend conventions", "optional": true}
+{"file": "devflow/spec/backend/index.md", "reason": "Backend conventions", "optional": true}
+{"file": ".claude/rules/project-constitution.md", "reason": "Quality rules and TDD mandate"}

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

@@ -0,0 +1,116 @@
+#!/usr/bin/env bash
+# ============================================================================
+# flow-dev Entry Gate
+# ============================================================================
+# [INPUT]: REQ_ID, devflow/requirements/${REQ_ID}/
+# [OUTPUT]: JSON validation result
+# [POS]: flow-dev 的入口检查脚本，验证开发阶段前置条件
+# [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+# ============================================================================
+
+set -euo pipefail
+
+# ============================================================================
+# Configuration
+# ============================================================================
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "${SCRIPT_DIR}/../../../../.." && pwd)"
+
+# ============================================================================
+# Functions
+# ============================================================================
+log_error() {
+    echo "[ERROR] $1" >&2
+}
+
+log_info() {
+    echo "[INFO] $1" >&2
+}
+
+output_json() {
+    local status="$1"
+    local message="$2"
+    local details="${3:-}"
+
+    if [[ -n "$details" ]]; then
+        echo "{\"status\":\"${status}\",\"message\":\"${message}\",\"details\":${details}}"
+    else
+        echo "{\"status\":\"${status}\",\"message\":\"${message}\"}"
+    fi
+}
+
+# ============================================================================
+# Main
+# ============================================================================
+main() {
+    local req_id="${1:-}"
+
+    # 1. REQ_ID 验证
+    if [[ -z "$req_id" ]]; then
+        output_json "error" "REQ_ID is required"
+        exit 1
+    fi
+
+    local req_dir="${PROJECT_ROOT}/devflow/requirements/${req_id}"
+
+    # 2. 目录存在性检查
+    if [[ ! -d "$req_dir" ]]; then
+        output_json "error" "Requirement directory not found: ${req_dir}"
+        exit 1
+    fi
+
+    # 3. 必需文件检查
+    local missing_files=()
+
+    [[ ! -f "${req_dir}/TASKS.md" ]] && missing_files+=("TASKS.md")
+    [[ ! -f "${req_dir}/EPIC.md" ]] && missing_files+=("EPIC.md")
+    [[ ! -f "${req_dir}/PRD.md" ]] && missing_files+=("PRD.md")
+    [[ ! -f "${req_dir}/orchestration_status.json" ]] && missing_files+=("orchestration_status.json")
+
+    if [[ ${#missing_files[@]} -gt 0 ]]; then
+        local files_json=$(printf '"%s",' "${missing_files[@]}" | sed 's/,$//')
+        output_json "error" "Missing required files" "[${files_json}]"
+        exit 1
+    fi
+
+    # 4. 状态检查
+    local status_file="${req_dir}/orchestration_status.json"
+    local current_status
+
+    if command -v jq &> /dev/null; then
+        current_status=$(jq -r '.status // "unknown"' "$status_file" 2>/dev/null || echo "unknown")
+    else
+        current_status=$(grep -o '"status"[[:space:]]*:[[:space:]]*"[^"]*"' "$status_file" | head -1 | sed 's/.*"\([^"]*\)"$/\1/')
+    fi
+
+    local valid_statuses=("spec_complete" "epic_complete" "development_in_progress" "development_failed")
+    local status_valid=false
+
+    for valid in "${valid_statuses[@]}"; do
+        if [[ "$current_status" == "$valid" ]]; then
+            status_valid=true
+            break
+        fi
+    done
+
+    if [[ "$status_valid" != "true" ]]; then
+        output_json "error" "Invalid status for flow-dev: ${current_status}. Expected: spec_complete, epic_complete, development_in_progress, or development_failed"
+        exit 1
+    fi
+
+    # 5. TASKS.md 格式检查
+    if ! grep -q "^- \[ \]" "${req_dir}/TASKS.md" 2>/dev/null; then
+        # 检查是否所有任务都已完成
+        if grep -q "^- \[x\]" "${req_dir}/TASKS.md" 2>/dev/null; then
+            log_info "All tasks appear to be completed"
+        else
+            output_json "error" "TASKS.md has no valid task format (- [ ] or - [x])"
+            exit 1
+        fi
+    fi
+
+    # 6. 成功
+    output_json "success" "Entry gate passed" "{\"req_id\":\"${req_id}\",\"status\":\"${current_status}\"}"
+}
+
+main "$@"

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

@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+# ============================================================================
+# flow-dev Exit Gate
+# ============================================================================
+# [INPUT]: REQ_ID, devflow/requirements/${REQ_ID}/
+# [OUTPUT]: JSON validation result
+# [POS]: flow-dev 的出口检查脚本，验证开发阶段完成条件
+# [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+# ============================================================================
+
+set -euo pipefail
+
+# ============================================================================
+# Configuration
+# ============================================================================
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "${SCRIPT_DIR}/../../../../.." && pwd)"
+
+# ============================================================================
+# Functions
+# ============================================================================
+log_error() {
+    echo "[ERROR] $1" >&2
+}
+
+log_info() {
+    echo "[INFO] $1" >&2
+}
+
+output_json() {
+    local status="$1"
+    local message="$2"
+    local details="${3:-}"
+
+    if [[ -n "$details" ]]; then
+        echo "{\"status\":\"${status}\",\"message\":\"${message}\",\"details\":${details}}"
+    else
+        echo "{\"status\":\"${status}\",\"message\":\"${message}\"}"
+    fi
+}
+
+# ============================================================================
+# Main
+# ============================================================================
+main() {
+    local req_id="${1:-}"
+
+    # 1. REQ_ID 验证
+    if [[ -z "$req_id" ]]; then
+        output_json "error" "REQ_ID is required"
+        exit 1
+    fi
+
+    local req_dir="${PROJECT_ROOT}/devflow/requirements/${req_id}"
+    local tasks_file="${req_dir}/TASKS.md"
+
+    # 2. 任务完成度检查
+    local total_tasks=0
+    local completed_tasks=0
+
+    if [[ -f "$tasks_file" ]]; then
+        total_tasks=$(grep -c "^- \[" "$tasks_file" 2>/dev/null || echo "0")
+        completed_tasks=$(grep -c "^- \[x\]" "$tasks_file" 2>/dev/null || echo "0")
+    fi
+
+    if [[ "$total_tasks" -eq 0 ]]; then
+        output_json "error" "No tasks found in TASKS.md"
+        exit 1
+    fi
+
+    local incomplete_tasks=$((total_tasks - completed_tasks))
+
+    if [[ "$incomplete_tasks" -gt 0 ]]; then
+        output_json "warning" "Not all tasks completed" "{\"total\":${total_tasks},\"completed\":${completed_tasks},\"incomplete\":${incomplete_tasks}}"
+        exit 1
+    fi
+
+    # 3. 测试验证 (检查是否有测试相关文件)
+    local has_tests=false
+
+    # 检查常见测试目录/文件
+    if [[ -d "${PROJECT_ROOT}/tests" ]] || \
+       [[ -d "${PROJECT_ROOT}/test" ]] || \
+       [[ -d "${PROJECT_ROOT}/__tests__" ]] || \
+       [[ -d "${PROJECT_ROOT}/spec" ]]; then
+        has_tests=true
+    fi
+
+    # 4. 实现文件检查 (检查 tasks/ 目录)
+    local impl_dir="${req_dir}/tasks"
+    local has_implementation=false
+
+    if [[ -d "$impl_dir" ]] && [[ -n "$(ls -A "$impl_dir" 2>/dev/null)" ]]; then
+        has_implementation=true
+    fi
+
+    # 5. 成功
+    output_json "success" "Exit gate passed" "{\"req_id\":\"${req_id}\",\"total_tasks\":${total_tasks},\"completed_tasks\":${completed_tasks},\"has_tests\":${has_tests},\"has_implementation\":${has_implementation}}"
+}
+
+main "$@"

package/.claude/skills/workflow/flow-dev/scripts/task-orchestrator.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+# ============================================================================
+# flow-dev Task Orchestrator
+# ============================================================================
+# [INPUT]: REQ_ID, TASKS.md
+# [OUTPUT]: JSON with next task info
+# [POS]: flow-dev 的任务调度脚本，解析 TASKS.md 并返回下一个待执行任务
+# [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+# ============================================================================
+
+set -euo pipefail
+
+# ============================================================================
+# Configuration
+# ============================================================================
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "${SCRIPT_DIR}/../../../../.." && pwd)"
+
+# ============================================================================
+# Functions
+# ============================================================================
+output_json() {
+    local status="$1"
+    local message="$2"
+    local details="${3:-}"
+
+    if [[ -n "$details" ]]; then
+        echo "{\"status\":\"${status}\",\"message\":\"${message}\",\"details\":${details}}"
+    else
+        echo "{\"status\":\"${status}\",\"message\":\"${message}\"}"
+    fi
+}
+
+# ============================================================================
+# Main
+# ============================================================================
+main() {
+    local req_id="${1:-}"
+    local action="${2:-next}"  # next, status, mark-complete
+    local task_id="${3:-}"
+
+    if [[ -z "$req_id" ]]; then
+        output_json "error" "REQ_ID is required"
+        exit 1
+    fi
+
+    local req_dir="${PROJECT_ROOT}/devflow/requirements/${req_id}"
+    local tasks_file="${req_dir}/TASKS.md"
+
+    if [[ ! -f "$tasks_file" ]]; then
+        output_json "error" "TASKS.md not found"
+        exit 1
+    fi
+
+    case "$action" in
+        next)
+            # 找到第一个未完成的任务
+            local next_task
+            next_task=$(grep -n "^- \[ \]" "$tasks_file" | head -1 || echo "")
+
+            if [[ -z "$next_task" ]]; then
+                output_json "complete" "All tasks completed"
+            else
+                local line_num=$(echo "$next_task" | cut -d: -f1)
+                local task_content=$(echo "$next_task" | cut -d: -f2-)
+
+                # 提取任务 ID (T###)
+                local extracted_id=$(echo "$task_content" | grep -o 'T[0-9]\{3\}' | head -1 || echo "")
+
+                output_json "success" "Next task found" "{\"line\":${line_num},\"task_id\":\"${extracted_id}\",\"content\":\"${task_content}\"}"
+            fi
+            ;;
+
+        status)
+            local total=$(grep -c "^- \[" "$tasks_file" 2>/dev/null || echo "0")
+            local completed=$(grep -c "^- \[x\]" "$tasks_file" 2>/dev/null || echo "0")
+            local pending=$((total - completed))
+
+            output_json "success" "Task status" "{\"total\":${total},\"completed\":${completed},\"pending\":${pending}}"
+            ;;
+
+        mark-complete)
+            if [[ -z "$task_id" ]]; then
+                output_json "error" "task_id required for mark-complete"
+                exit 1
+            fi
+
+            # 标记任务完成 (将 [ ] 改为 [x])
+            if grep -q "^- \[ \].*${task_id}" "$tasks_file"; then
+                sed -i.bak "s/^- \[ \]\(.*${task_id}.*\)/- [x]\1/" "$tasks_file"
+                rm -f "${tasks_file}.bak"
+                output_json "success" "Task marked complete" "{\"task_id\":\"${task_id}\"}"
+            else
+                output_json "error" "Task not found or already completed: ${task_id}"
+                exit 1
+            fi
+            ;;
+
+        *)
+            output_json "error" "Unknown action: ${action}. Use: next, status, mark-complete"
+            exit 1
+            ;;
+    esac
+}
+
+main "$@"

package/.claude/skills/workflow/flow-fix/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: flow-fix
+description: 'One-shot BUG fix flow with systematic debugging. Usage: /flow-fix "BUG-123|登录时报 500"'
+---
+
+# Flow-Fix Skill
+
+> [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+
+## Purpose
+
+系统化 BUG 修复流程，遵循 4 阶段调试法。
+
+## The Iron Law
+
+```
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+```
+
+## Input Format
+
+```
+/flow-fix "BUG_ID|TITLE"
+```
+
+示例: `/flow-fix "BUG-123|登录时报500"`
+
+## Rationalization Prevention
+
+| Excuse | Reality |
+|--------|---------|
+| "我知道问题在哪" | 证明它。先调查。 |
+| "快速修复一下" | 快速修复 = 快速回归。系统化调试。 |
+| "没时间写测试" | 没测试 = 不知道是否真的修好了。 |
+| "这个改动很小" | 小改动也能引入大 bug。测试它。 |
+
+## Execution Flow
+
+### Stage 0: Entry Gate
+
+1. 解析 BUG_ID、TITLE
+2. 创建 `devflow/bugs/${BUG_ID}/` 目录
+3. 创建分支: `bugfix/${BUG_ID}-${slug}`
+
+### Stage 1: Root Cause Investigation
+
+**Iron Law**: 禁止写任何修复代码
+
+1. 完整阅读错误信息
+2. 稳定复现
+3. 检查最近变更
+4. 逆向追踪数据流
+
+输出: ANALYSIS.md
+
+### Stage 2: Pattern Analysis & Planning
+
+1. 找到正常工作的例子
+2. 与参考实现对比
+3. 调用 planner 生成 PLAN.md
+
+输出: PLAN.md, tasks/, TEST_PLAN.md
+
+### Stage 3: Fix Execution (TDD)
+
+1. 先写失败测试用例
+2. 按 tasks/ 顺序执行
+3. 每任务完成后 Git 提交
+4. 3+ 次失败 → STOP，质疑架构
+
+### Stage 4: Verification
+
+1. TEST_REPORT.md (必须全部通过)
+2. SECURITY_REPORT.md
+3. RELEASE_PLAN.md
+4. Status: `fix_complete`
+
+## Output
+
+```
+devflow/bugs/${BUG_ID}/
+├── ANALYSIS.md
+├── PLAN.md
+├── tasks/
+├── TEST_PLAN.md
+├── TEST_REPORT.md
+├── SECURITY_REPORT.md
+├── RELEASE_PLAN.md
+└── orchestration_status.json
+```
+
+## Red Flags - STOP
+
+如果你发现自己:
+- 没有复现就开始修复
+- 在"试试这个，试试那个"
+- 3+ 次修复尝试失败
+- 没写测试就说"修好了"
+
+**STOP. 回到阶段 1. 调查根因。**
+
+## Next Step
+
+1. 提交 PR: `fix(${BUG_ID}): <summary>`
+2. 通知相关需求负责人回归验证

package/.claude/skills/workflow/flow-fix/context.jsonl

@@ -0,0 +1,6 @@
+{"file": "devflow/bugs/{BUG}/ANALYSIS.md", "reason": "Root cause analysis", "optional": true}
+{"file": "devflow/bugs/{BUG}/PLAN.md", "reason": "Fix plan", "optional": true}
+{"file": "devflow/bugs/{BUG}/ERROR_LOG.md", "reason": "Previous errors", "optional": true}
+{"file": ".claude/skills/flow-debugging/SKILL.md", "reason": "Debugging methodology"}
+{"file": ".claude/skills/flow-tdd/SKILL.md", "reason": "TDD principles"}
+{"file": ".claude/rules/project-constitution.md", "reason": "Quality rules"}