cc-devflow 2.4.6 → 4.1.0

package/.claude/skills/workflow/flow-init/references/flow-researcher.md

@@ -0,0 +1,132 @@
+---
+name: flow-researcher
+description: Executes mandatory /flow-init deep research using MCP services (Context7/WebSearch/WebFetch) with file-based memory. Produces research artifacts under devflow/requirements/$REQ_ID/research/ and returns only a short summary + file paths (no long pastes).
+tools: Read, Write, Grep, Glob, WebFetch, WebSearch, mcp__context7__resolve-library-id, mcp__context7__get-library-docs
+model: inherit
+---
+
+You are a requirement research runner invoked by `/flow-init`.
+
+Your job is to do **research work** without exhausting the main session context:
+- Put large content into files under `devflow/requirements/$REQ_ID/research/`
+- Return only a **short** summary + **paths**, never paste long docs into chat
+
+## MCP Research Requirement
+
+This agent MUST use **MCP services** to fetch external materials for deep research:
+- **Context7 MCP**: official documentation for detected frameworks/libraries (`mcp__context7__resolve-library-id` + `mcp__context7__get-library-docs`)
+- **WebSearch + WebFetch**: tutorials, guides, examples, case studies, and plan URLs
+
+All fetched content MUST be written to `research/mcp/YYYYMMDD/**` (not pasted into chat).
+
+## Hard Rules
+
+1. **NO USER INTERACTION**
+   - Never ask the user questions.
+   - If information is missing, record it under `## Unresolved Questions` in `research/research-summary.md`.
+
+2. **FILE-BASED MEMORY (MANDATORY)**
+   - Any fetched/long content must be written to files in `research/`.
+   - Chat output must stay small (decision bullets + file paths).
+
+3. **NO PLACEHOLDERS**
+   - Do not leave `TODO`, `FIXME`, `{{PLACEHOLDER}}`.
+   - Ensure `validate-research.sh --strict` passes.
+
+4. **TRACEABILITY**
+   - Every decision must include a concrete `Source` (file path + section/line if possible).
+
+## Input Contract (provided via prompt)
+
+You will receive a JSON payload in the prompt:
+
+```json
+{
+  "reqId": "REQ-123",
+  "reqDir": "devflow/requirements/REQ-123",
+  "title": "User Authentication",
+  "planUrls": ["https://..."],
+  "contextFiles": {
+    "brainstorm": "devflow/requirements/REQ-123/BRAINSTORM.md",
+    "roadmap": "devflow/ROADMAP.md",
+    "architecture": "devflow/ARCHITECTURE.md"
+  }
+}
+```
+
+## Required Outputs (MUST create/update)
+
+Under `${reqDir}/research/`:
+- `internal/codebase-overview.md`
+- `mcp/YYYYMMDD/official/*.md` (if applicable)
+- `mcp/YYYYMMDD/guides/*.md` (if applicable)
+- `mcp/YYYYMMDD/tutorials/*.md` (if applicable)
+- `mcp/YYYYMMDD/examples/*.md` (if applicable)
+- `research-summary.md` (human-readable decisions)
+- `tasks.json` (decision/rationale/alternatives filled)
+- `research.md` (consolidated, Decision/Rationale/Alternatives format)
+
+## Execution Procedure (follow in order)
+
+### Step 1: Validate Paths & Prepare Directories
+- Ensure `${reqDir}` exists.
+- Ensure `${reqDir}/research/` exists, create missing subfolders:
+  - `research/internal/`
+  - `research/mcp/YYYYMMDD/{official,guides,tutorials,examples}/`
+- Read `${reqDir}/BRAINSTORM.md` and `${reqDir}/README.md` if present.
+
+### Step 2: Internal Codebase Research (S0)
+Goal: produce a **useful** `research/internal/codebase-overview.md` with:
+- Repo tech stack snapshot (from `package.json`, lockfiles, etc.)
+- Relevant modules/entry points you will likely touch
+- Existing patterns for auth/data validation/error handling/tests
+- Constraints you must not violate (existing conventions, CI, tooling)
+
+### Step 3: External Research (Task 1-5)
+Do not paste docs into chat; store them as files.
+
+1) **Official docs (Context7 MCP)** for the detected key libraries/frameworks
+2) **Tutorials/guides (WebSearch + WebFetch)** for practical patterns
+3) **Examples/case studies (WebSearch + WebFetch)** similar to this requirement
+4) Write short per-source notes at top of each saved file:
+   - What it answers
+   - What it recommends
+   - Any caveats
+
+If planUrls exist:
+- Fetch each URL and store content under `research/mcp/YYYYMMDD/guides/plan-*.md` (or `tutorials/` if more appropriate).
+
+### Step 4: Write `research/research-summary.md`
+Use `.claude/docs/templates/RESEARCH_TEMPLATE.md` as the format baseline.
+- Create **at least 3** Decision blocks `### R001`, `### R002`, `### R003`.
+- Each decision must cite sources under `research/` (internal or external).
+- Add unresolved questions only when genuinely blocked.
+
+### Step 5: Generate & Fill `tasks.json`
+- Run:
+  - `bash .claude/scripts/generate-research-tasks.sh "${reqDir}"`
+- Ensure `tasks.json` contains at least **1** task.
+  - If the generator produced 0 tasks, append baseline tasks matching your decision blocks (`R001..R003`).
+- Fill each task's `decision`, `rationale`, `alternatives` based on `research-summary.md`.
+  - Prefer using `bash .claude/scripts/populate-research-tasks.sh "${reqDir}"` if it matches the ID format.
+
+### Step 6: Consolidate & Validate
+- Run:
+  - `bash .claude/scripts/consolidate-research.sh "${reqDir}"`
+  - `bash .claude/scripts/validate-research.sh "${reqDir}" --strict`
+- If validation fails:
+  - Fix the files (do not weaken validation).
+  - Re-run validation until it passes.
+
+## Return Format (chat output)
+
+Return ONLY:
+- 3–6 bullet decisions (R001..), one line each
+- Paths created/updated
+- Any unresolved questions (≤5)
+
+Never paste long fetched content.
+
+---
+
+**[PROTOCOL]**: 变更时更新此头部，然后检查 CLAUDE.md

package/.claude/skills/workflow/flow-init/scripts/check-prerequisites.sh

@@ -0,0 +1,232 @@
+#!/usr/bin/env bash
+
+# Consolidated prerequisite checking script for cc-devflow
+#
+# This script provides unified prerequisite checking for development workflow.
+# Based on spec-kit design principles with cc-devflow enhancements.
+#
+# Usage: ./check-prerequisites.sh [OPTIONS]
+#
+# OPTIONS:
+#   --json              Output in JSON format
+#   --require-epic      Require EPIC.md to exist (for task generation phase)
+#   --require-tasks     Require tasks/ to exist (for implementation phase)
+#   --include-tasks     Include tasks/ in AVAILABLE_DOCS list
+#   --paths-only        Only output path variables (no validation)
+#   --help, -h          Show help message
+#
+# OUTPUTS:
+#   JSON mode: {"REQ_ID":"...", "REQ_DIR":"...", "AVAILABLE_DOCS":["..."]}
+#   Text mode: REQ_ID:... \n REQ_DIR:... \n AVAILABLE_DOCS: \n ✓/✗ file.md
+#   Paths only: REPO_ROOT: ... \n REQ_ID: ... \n REQ_DIR: ... etc.
+
+set -e
+
+# Parse command line arguments
+JSON_MODE=false
+REQUIRE_EPIC=false
+REQUIRE_TASKS=false
+INCLUDE_TASKS=false
+PATHS_ONLY=false
+
+for arg in "$@"; do
+    case "$arg" in
+        --json)
+            JSON_MODE=true
+            ;;
+        --require-epic)
+            REQUIRE_EPIC=true
+            ;;
+        --require-tasks)
+            REQUIRE_TASKS=true
+            ;;
+        --include-tasks)
+            INCLUDE_TASKS=true
+            ;;
+        --paths-only)
+            PATHS_ONLY=true
+            ;;
+        --help|-h)
+            cat << 'EOF'
+Usage: check-prerequisites.sh [OPTIONS]
+
+Consolidated prerequisite checking for cc-devflow workflow.
+
+OPTIONS:
+  --json              Output in JSON format
+  --require-epic      Require EPIC.md to exist (for task generation phase)
+  --require-tasks     Require tasks/ to exist (for implementation phase)
+  --include-tasks     Include tasks/ in AVAILABLE_DOCS list
+  --paths-only        Only output path variables (no prerequisite validation)
+  --help, -h          Show this help message
+
+EXAMPLES:
+  # Check planning prerequisites (PRD.md required)
+  ./check-prerequisites.sh --json
+
+  # Check task generation prerequisites (PRD.md + EPIC.md required)
+  ./check-prerequisites.sh --json --require-epic
+
+  # Check implementation prerequisites (PRD.md + EPIC.md + tasks/ required)
+  ./check-prerequisites.sh --json --require-epic --require-tasks --include-tasks
+
+  # Get requirement paths only (no validation)
+  ./check-prerequisites.sh --paths-only
+
+EOF
+            exit 0
+            ;;
+        *)
+            echo "ERROR: Unknown option '$arg'. Use --help for usage information." >&2
+            exit 1
+            ;;
+    esac
+done
+
+# Source common functions
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+# Get requirement paths
+eval $(get_requirement_paths)
+
+# Validate requirement ID exists
+if [[ -z "$REQ_ID" ]]; then
+    echo "ERROR: No requirement ID found" >&2
+    echo "Please ensure you are on a feature branch (feature/REQ-XXX-title)" >&2
+    echo "Or set DEVFLOW_REQ_ID environment variable" >&2
+    exit 1
+fi
+
+# Validate requirement ID format
+validate_req_id "$REQ_ID" || exit 1
+
+# If paths-only mode, output paths and exit (support JSON + paths-only combined)
+if $PATHS_ONLY; then
+    if $JSON_MODE; then
+        # Minimal JSON paths payload (no validation performed)
+        printf '{"%s":"%s","%s":"%s","%s":"%s","%s":"%s","%s":"%s","%s":"%s"}\n' \
+            "REPO_ROOT" "$REPO_ROOT" \
+            "REQ_ID" "$REQ_ID" \
+            "REQ_TYPE" "$REQ_TYPE" \
+            "REQ_DIR" "$REQ_DIR" \
+            "PRD_FILE" "$PRD_FILE" \
+            "EPIC_FILE" "$EPIC_FILE"
+    else
+        echo "REPO_ROOT: $REPO_ROOT"
+        echo "REQ_ID: $REQ_ID"
+        echo "REQ_TYPE: $REQ_TYPE"
+        echo "REQ_DIR: $REQ_DIR"
+        echo "PRD_FILE: $PRD_FILE"
+        echo "EPIC_FILE: $EPIC_FILE"
+    fi
+    exit 0
+fi
+
+# Validate required directories and files
+if [[ ! -d "$REQ_DIR" ]]; then
+    echo "ERROR: Requirement directory not found: $REQ_DIR" >&2
+    echo "Run /flow-new first to create the requirement structure." >&2
+    exit 1
+fi
+
+if [[ ! -f "$PRD_FILE" ]]; then
+    echo "ERROR: PRD.md not found in $REQ_DIR" >&2
+    echo "Run prd-writer agent first to create the PRD." >&2
+    exit 1
+fi
+
+# Check for EPIC.md if required
+if $REQUIRE_EPIC && [[ ! -f "$EPIC_FILE" ]]; then
+    echo "ERROR: EPIC.md not found in $REQ_DIR" >&2
+    echo "Run planner agent first to create the Epic." >&2
+    exit 1
+fi
+
+# Check for tasks/ or TASKS.md if required
+# Support both tasks/ directory (old format) and TASKS.md file (new format)
+if $REQUIRE_TASKS; then
+    TASKS_FILE="$REQ_DIR/TASKS.md"
+    if [[ ! -d "$TASKS_DIR" || -z "$(ls -A "$TASKS_DIR" 2>/dev/null)" ]] && [[ ! -f "$TASKS_FILE" ]]; then
+        echo "ERROR: Neither tasks/ directory nor TASKS.md file found in $REQ_DIR" >&2
+        echo "Run planner agent first to create the task breakdown." >&2
+        exit 1
+    fi
+fi
+
+# Build list of available documents
+docs=()
+
+# Check optional docs
+[[ -d "$RESEARCH_DIR" && -n "$(ls -A "$RESEARCH_DIR" 2>/dev/null)" ]] && docs+=("research/")
+[[ -f "$TEST_PLAN_FILE" ]] && docs+=("TEST_PLAN.md")
+[[ -f "$SECURITY_PLAN_FILE" ]] && docs+=("SECURITY_PLAN.md")
+[[ -f "$TEST_REPORT_FILE" ]] && docs+=("TEST_REPORT.md")
+[[ -f "$SECURITY_REPORT_FILE" ]] && docs+=("SECURITY_REPORT.md")
+[[ -f "$RELEASE_PLAN_FILE" ]] && docs+=("RELEASE_PLAN.md")
+[[ -f "$LOG_FILE" ]] && docs+=("EXECUTION_LOG.md")
+
+# Include tasks/ or TASKS.md if requested and it exists
+# Support both tasks/ directory (old format) and TASKS.md file (new format)
+if $INCLUDE_TASKS; then
+    TASKS_FILE="$REQ_DIR/TASKS.md"
+    if [[ -d "$TASKS_DIR" && -n "$(ls -A "$TASKS_DIR" 2>/dev/null)" ]]; then
+        docs+=("tasks/")
+    elif [[ -f "$TASKS_FILE" ]]; then
+        docs+=("TASKS.md")
+    fi
+fi
+
+# For BUG type, check BUG-specific files
+if [[ "$REQ_TYPE" == "bug" ]]; then
+    [[ -f "$ANALYSIS_FILE" ]] && docs+=("ANALYSIS.md")
+    [[ -f "$PLAN_FILE" ]] && docs+=("PLAN.md")
+fi
+
+# Output results
+if $JSON_MODE; then
+    # Build JSON array of documents
+    if [[ ${#docs[@]} -eq 0 ]]; then
+        json_docs="[]"
+    else
+        json_docs=$(printf '"%s",' "${docs[@]}")
+        json_docs="[${json_docs%,}]"
+    fi
+
+    printf '{"%s":"%s","%s":"%s","%s":"%s","%s":%s}\n' \
+        "REQ_ID" "$REQ_ID" \
+        "REQ_TYPE" "$REQ_TYPE" \
+        "REQ_DIR" "$REQ_DIR" \
+        "AVAILABLE_DOCS" "$json_docs"
+else
+    # Text output
+    echo "REQ_ID: $REQ_ID"
+    echo "REQ_TYPE: $REQ_TYPE"
+    echo "REQ_DIR: $REQ_DIR"
+    echo "AVAILABLE_DOCS:"
+
+    # Show status of each potential document
+    check_dir "$RESEARCH_DIR" "research/"
+    check_file "$TEST_PLAN_FILE" "TEST_PLAN.md"
+    check_file "$SECURITY_PLAN_FILE" "SECURITY_PLAN.md"
+    check_file "$TEST_REPORT_FILE" "TEST_REPORT.md"
+    check_file "$SECURITY_REPORT_FILE" "SECURITY_REPORT.md"
+    check_file "$RELEASE_PLAN_FILE" "RELEASE_PLAN.md"
+    check_file "$LOG_FILE" "EXECUTION_LOG.md"
+
+    if $INCLUDE_TASKS; then
+        TASKS_FILE="$REQ_DIR/TASKS.md"
+        # Check for tasks/ directory first, fallback to TASKS.md
+        if [[ -d "$TASKS_DIR" && -n "$(ls -A "$TASKS_DIR" 2>/dev/null)" ]]; then
+            check_dir "$TASKS_DIR" "tasks/"
+        else
+            check_file "$TASKS_FILE" "TASKS.md"
+        fi
+    fi
+
+    # BUG-specific files
+    if [[ "$REQ_TYPE" == "bug" ]]; then
+        check_file "$ANALYSIS_FILE" "ANALYSIS.md"
+        check_file "$PLAN_FILE" "PLAN.md"
+    fi
+fi

package/.claude/skills/workflow/flow-init/scripts/consolidate-research.sh

@@ -0,0 +1,182 @@
+#!/usr/bin/env bash
+# shellcheck disable=SC2312
+
+set -euo pipefail
+
+usage() {
+  cat <<'USAGE'
+Usage: scripts/bash/consolidate-research.sh <requirement-dir>
+
+Aggregates research findings into research/research.md using the standard
+Decision/Rationale/Alternatives format. Existing files are overwritten.
+USAGE
+}
+
+if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+  usage
+  exit 0
+fi
+
+if [[ $# -lt 1 ]]; then
+  echo "Error: requirement directory is required." >&2
+  usage
+  exit 1
+fi
+
+REQ_DIR="$1"
+if [[ ! -d "$REQ_DIR" ]]; then
+  echo "Error: requirement directory '$REQ_DIR' does not exist." >&2
+  exit 1
+fi
+
+python3 - "$REQ_DIR" <<'PY'
+from __future__ import annotations
+
+import json
+import os
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+req_dir = Path(sys.argv[1]).resolve()
+research_dir = req_dir / "research"
+research_dir.mkdir(exist_ok=True, parents=True)
+summary_path = research_dir / "research.md"
+tasks_path = research_dir / "tasks.json"
+
+def detect_feature_title() -> str:
+    readme = req_dir / "README.md"
+    if readme.exists():
+        for line in readme.read_text(encoding="utf-8").splitlines():
+            line = line.strip("# ").strip()
+            if line:
+                return line
+    return req_dir.name
+
+def validate_task_completeness(tasks: list) -> tuple[int, int, list]:
+    """Validate tasks have decision/rationale/alternatives fields.
+
+    Returns:
+        (total_tasks, completed_tasks, incomplete_task_ids)
+    """
+    total = len(tasks)
+    completed = 0
+    incomplete = []
+
+    for task in tasks:
+        task_id = task.get("id", "???")
+        decision = task.get("decision", "")
+        rationale = task.get("rationale", "")
+        alternatives = task.get("alternatives", "")
+
+        # 字段完整的条件：非空 + 不是 TODO 占位符
+        has_decision = bool(decision and decision.strip() and decision != "TODO - fill decision outcome")
+        has_rationale = bool(rationale and rationale.strip() and rationale != "TODO - explain why this decision was chosen")
+        has_alternatives = bool(alternatives and alternatives.strip() and alternatives != "TODO - list evaluated alternatives")
+
+        if has_decision and has_rationale and has_alternatives:
+            completed += 1
+        else:
+            incomplete.append(task_id)
+
+    return total, completed, incomplete
+
+feature_title = detect_feature_title()
+generated_at = datetime.now(timezone.utc).isoformat()
+
+tasks_data = {}
+if tasks_path.exists():
+    try:
+        tasks_data = json.loads(tasks_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        print(f"ERROR: {tasks_path} is not valid JSON", file=sys.stderr)
+        sys.exit(1)
+
+tasks = tasks_data.get("tasks", [])
+
+# Validate task completion
+if tasks:
+    total, completed, incomplete = validate_task_completeness(tasks)
+    completion_rate = completed / total if total > 0 else 0
+
+    print(f"Research Tasks: {completed}/{total} completed ({completion_rate:.0%})", file=sys.stderr)
+
+    if completion_rate < 0.5:
+        print(f"WARNING: Research incomplete. Only {completed}/{total} tasks have decisions.", file=sys.stderr)
+        print(f"Incomplete tasks: {', '.join(incomplete)}", file=sys.stderr)
+        print(f"Generated research.md will contain TODO placeholders.", file=sys.stderr)
+        print(f"Fix: Add decision/rationale/alternatives fields to tasks.json", file=sys.stderr)
+
+sources = []
+for path in research_dir.rglob("*.md"):
+    if path.name in {"research.md"}:
+        continue
+    sources.append(str(path.relative_to(req_dir)))
+
+lines = []
+lines.append(f"# Research Summary — {feature_title}")
+lines.append("")
+lines.append(f"Generated: {generated_at}")
+lines.append("")
+lines.append("## Decisions")
+lines.append("")
+
+if not tasks:
+    lines.append("_No research tasks detected. Populate research/tasks.json to track clarifications._")
+else:
+    for task in tasks:
+        task_id = task.get("id", "R???")
+        prompt = task.get("prompt", "(unknown prompt)")
+        lines.append(f"### {task_id} — {prompt}")
+
+        # 处理空字符串，替换为 TODO 占位符
+        decision = task.get("decision", "")
+        rationale = task.get("rationale", "")
+        alternatives = task.get("alternatives", "")
+
+        decision = decision.strip() if decision.strip() else "TODO - fill decision outcome"
+        rationale = rationale.strip() if rationale.strip() else "TODO - explain why this decision was chosen"
+        alternatives = alternatives.strip() if alternatives.strip() else "TODO - list evaluated alternatives"
+
+        lines.append(f"- Decision: {decision}")
+        lines.append(f"- Rationale: {rationale}")
+        lines.append(f"- Alternatives considered: {alternatives}")
+        source = task.get("source")
+        if source:
+            lines.append(f"- Source: {source}")
+        lines.append("")
+
+lines.append("## Source Library")
+lines.append("")
+if sources:
+    for src in sorted(sources):
+        lines.append(f"- {src}")
+else:
+    lines.append("_No research source files detected yet._")
+
+summary_path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+# Post-write validation: detect TODO placeholders
+content = summary_path.read_text(encoding="utf-8")
+todo_count = content.count("TODO")
+placeholder_count = content.count("{{") + content.count("}}")
+
+if todo_count > 0 or placeholder_count > 0:
+    print(f"⚠️  WARNING: Generated research.md contains quality issues:", file=sys.stderr)
+    if todo_count > 0:
+        print(f"   - {todo_count} TODO marker(s) found", file=sys.stderr)
+    if placeholder_count > 0:
+        print(f"   - Placeholder markers {{{{ }}}} found", file=sys.stderr)
+    print(f"", file=sys.stderr)
+    print(f"This will cause validate-research.sh to FAIL.", file=sys.stderr)
+    print(f"", file=sys.stderr)
+    print(f"Fix Options:", file=sys.stderr)
+    print(f"  1. Update tasks.json with actual decision/rationale/alternatives", file=sys.stderr)
+    print(f"  2. Manually edit {summary_path.relative_to(req_dir)}", file=sys.stderr)
+    print(f"  3. Use .claude/docs/templates/RESEARCH_TEMPLATE.md as reference", file=sys.stderr)
+    print(f"", file=sys.stderr)
+    print(f"Wrote research summary → {summary_path} (WITH WARNINGS)", file=sys.stderr)
+else:
+    print(f"✅ Wrote research summary → {summary_path}", file=sys.stderr)
+    print(f"   Quality check: No TODO/PLACEHOLDER markers detected", file=sys.stderr)
+PY