cc-devflow 2.5.0 → 4.1.1

package/.claude/commands/flow/spec.md

@@ -0,0 +1,186 @@
+---
+name: flow-spec
+description: 'Unified specification phase: PRD → Tech+UI (parallel) → Epic/Tasks. Usage: /flow-spec "REQ-123" [--skip-tech] [--skip-ui]'
+scripts:
+  prereq: .claude/scripts/check-prerequisites.sh
+  validate_research: .claude/scripts/validate-research.sh
+  validate_constitution: .claude/scripts/validate-constitution.sh
+---
+
+# Flow-Spec - 统一规格阶段命令
+
+> **v4.1 新增**: 合并 flow-prd/flow-tech/flow-ui/flow-epic 为单一命令
+
+## User Input
+
+```text
+$ARGUMENTS = "REQ_ID [--skip-tech] [--skip-ui]"
+```
+
+若未提供 REQ_ID 则根据当前分支或 `DEVFLOW_REQ_ID` 自动解析。
+
+## 命令格式
+
+```bash
+# Full Mode (默认) - PRD + Tech + UI + Epic
+/flow-spec "REQ-123"
+
+# Quick Mode (小需求) - PRD + Epic only
+/flow-spec "REQ-123" --skip-tech --skip-ui
+
+# Backend Only - PRD + Tech + Epic
+/flow-spec "REQ-123" --skip-ui
+
+# Frontend Only - PRD + UI + Epic
+/flow-spec "REQ-123" --skip-tech
+```
+
+## Mode Matrix
+
+| Mode | Flags | Agents | Output |
+|------|-------|--------|--------|
+| Full | (default) | PRD + Tech + UI + Epic | PRD.md, TECH_DESIGN.md, UI_PROTOTYPE.html, EPIC.md, TASKS.md |
+| Quick | `--skip-tech --skip-ui` | PRD + Epic | PRD.md, EPIC.md, TASKS.md |
+| Backend | `--skip-ui` | PRD + Tech + Epic | PRD.md, TECH_DESIGN.md, EPIC.md, TASKS.md |
+| Frontend | `--skip-tech` | PRD + UI + Epic | PRD.md, UI_PROTOTYPE.html, EPIC.md, TASKS.md |
+
+## 执行流程
+
+**加载 Skill 指令**:
+```
+→ 读取 .claude/skills/workflow/flow-spec/SKILL.md
+→ 按 SKILL.md 中定义的 Execution Flow 执行
+```
+
+### 阶段 1: Entry Gate
+
+```yaml
+Prerequisites:
+  1. REQ_ID 解析:
+     - 从参数获取
+     - 或从当前分支推断 (feature/REQ-XXX-*)
+     - 或从 orchestration_status.json 获取
+
+  2. BRAINSTORM.md 存在:
+     - 路径: devflow/requirements/${REQ_ID}/BRAINSTORM.md
+     - 必须包含: 需求描述、目标用户、核心功能
+
+  3. Research 完成:
+     - 路径: devflow/requirements/${REQ_ID}/research/research.md
+     - 无 TODO/PLACEHOLDER
+
+  4. Status Check:
+     - orchestration_status.status ∈ {"initialized", "spec_failed"}
+
+  5. Constitution Gate:
+     - 读取 BRAINSTORM.md 验证需求边界
+```
+
+### 阶段 2: PRD Generation (Sequential)
+
+```yaml
+Agent: prd-writer (research-type)
+Input:
+  - BRAINSTORM.md
+  - research/research.md
+  - research/internal/codebase-overview.md
+
+Output:
+  - PRD.md
+
+Rules:
+  - ANTI-EXPANSION: 未提及 → [NEEDS CLARIFICATION]
+  - NO TECH DETAILS: 只关注 WHAT/WHY
+  - STORY INDEPENDENCE: 每个故事有独立测试
+```
+
+### 阶段 3: Tech + UI (Parallel)
+
+```yaml
+Parallel Execution:
+  tech-architect (if !--skip-tech):
+    Input: PRD.md, research/codebase-overview.md
+    Output: TECH_DESIGN.md, data-model.md, contracts/
+
+  ui-designer (if !--skip-ui AND UI detected):
+    Input: PRD.md, STYLE.md (optional)
+    Output: UI_PROTOTYPE.html, ui_design_strategy.md
+
+Method:
+  - 使用 Task tool 并行调用两个 agent
+  - 等待两者完成后进入 Stage 4
+```
+
+### 阶段 4: Epic Generation (Sequential)
+
+```yaml
+Agent: planner (research-type)
+Input:
+  - PRD.md
+  - TECH_DESIGN.md (if exists)
+  - UI_PROTOTYPE.html (if exists)
+
+Output:
+  - EPIC.md
+  - TASKS.md
+
+Rules:
+  - TDD Order: Phase 2 (Tests) → Phase 3 (Implementation)
+  - Bite-Sized Tasks: 每个 step 2-5 分钟
+  - Phase -1 Gates: Simplicity, Anti-Abstraction, Integration-First
+```
+
+### 阶段 5: Exit Gate
+
+```yaml
+File Checks:
+  - [ ] PRD.md exists, no {{PLACEHOLDER}}
+  - [ ] TECH_DESIGN.md exists (if !--skip-tech)
+  - [ ] UI_PROTOTYPE.html exists (if !--skip-ui AND UI detected)
+  - [ ] EPIC.md exists, no {{PLACEHOLDER}}
+  - [ ] TASKS.md exists, TDD order correct
+
+Status Update:
+  - orchestration_status.status = "spec_complete"
+  - orchestration_status.phase = "spec"
+```
+
+## 输出
+
+```
+devflow/requirements/${REQ_ID}/
+├── PRD.md                          # Always
+├── TECH_DESIGN.md                  # If !--skip-tech
+├── data-model.md                   # If !--skip-tech
+├── contracts/openapi.yaml          # If !--skip-tech
+├── UI_PROTOTYPE.html               # If !--skip-ui AND UI detected
+├── EPIC.md                         # Always
+├── TASKS.md                        # Always
+└── orchestration_status.json       # Updated
+```
+
+## 错误处理
+
+- **Entry Gate 失败**: 返回具体缺失项，指导用户运行 `/flow-init`
+- **PRD 生成失败**: status = "spec_failed"，可重试
+- **Tech/UI 失败**: 继续执行，标记为 skipped
+- **Epic 失败**: status = "spec_failed"，可用 `--from=epic` 重试
+
+## 下一步
+
+```bash
+/flow-dev "${REQ_ID}"
+```
+
+## Agent References
+
+| Agent | Purpose | Location |
+|-------|---------|----------|
+| prd-writer | PRD 生成 | `.claude/agents/prd-writer.md` |
+| tech-architect | 技术设计 | `.claude/agents/tech-architect.md` |
+| ui-designer | UI 原型 | `.claude/agents/ui-designer.md` |
+| planner | Epic/Tasks | `.claude/agents/planner.md` |
+
+## 详细指令
+
+完整执行逻辑见: `.claude/skills/workflow/flow-spec/SKILL.md`

package/.claude/commands/flow/workspace.md

@@ -0,0 +1,146 @@
+---
+name: flow-workspace
+description: Manage developer workspace and session persistence (RM-018)
+version: 3.0.0
+---
+
+# /flow-workspace
+
+> **[PROTOCOL]**: 变更时更新此头部，然后检查 CLAUDE.md
+
+## Purpose
+
+Manage developer workspaces for session persistence.
+Enables context recovery across sessions and tracks development progress.
+
+## Usage
+
+```bash
+# Initialize workspace for a developer
+/flow-workspace init [developer]
+
+# Start session (recover context)
+/flow-workspace start
+
+# Record progress to journal
+/flow-workspace record "message"
+
+# Switch to different requirement
+/flow-workspace switch REQ-XXX
+```
+
+## Subcommands
+
+### init
+
+Initialize a workspace for a developer.
+
+```bash
+/flow-workspace init dimon
+```
+
+Creates:
+```
+devflow/workspace/dimon/
+├── .current-req    # Current requirement ID
+├── journal-1.md    # Session journal
+└── ...
+```
+
+### start
+
+Start a new session, recovering context from previous session.
+
+```bash
+/flow-workspace start
+```
+
+Process:
+1. Read `.current-req` to get current requirement
+2. Read latest journal entries
+3. Display context summary
+4. Ready to continue work
+
+### record
+
+Record progress to the journal.
+
+```bash
+/flow-workspace record "Completed T015, starting T016"
+```
+
+Appends to current journal file. Creates new journal file when approaching 2000 lines.
+
+### switch
+
+Switch to a different requirement.
+
+```bash
+/flow-workspace switch REQ-008
+```
+
+Updates `.current-req` and creates a new journal entry.
+
+## Workspace Structure
+
+```
+devflow/workspace/
+├── index.md            # Active developers list
+└── {developer}/
+    ├── .current-req    # Current REQ-ID (e.g., "REQ-007")
+    ├── journal-1.md    # Session journal (max 2000 lines)
+    ├── journal-2.md    # Overflow journal
+    └── ...
+```
+
+## Journal Format
+
+```markdown
+## [2026-02-06 10:30] Session Start
+
+**REQ**: REQ-007
+**Phase**: flow-dev
+**Task**: T015
+
+### Progress
+- Completed: T014 (auth middleware)
+- Current: T015 (rate limiting)
+- Blocked: None
+
+### Notes
+- Discovered edge case in token refresh
+- Need to revisit error handling in T016
+```
+
+## Integration
+
+### With flow-init
+
+When `/flow-init` creates a new requirement:
+```bash
+# Auto-update workspace
+echo "REQ-XXX" > devflow/workspace/{developer}/.current-req
+```
+
+### With flow-dev
+
+During development, progress is automatically recorded:
+```bash
+/flow-workspace record "Completed T015"
+```
+
+### With Attention Refresh
+
+Journal is read at Protocol 3 (Ralph iteration start) to maintain context.
+
+## Scripts
+
+- `.claude/scripts/flow-workspace-init.sh` - Initialize workspace
+- `.claude/scripts/flow-workspace-start.sh` - Start session
+- `.claude/scripts/flow-workspace-record.sh` - Record progress
+
+## Related
+
+- **Template**: `.claude/docs/templates/JOURNAL_TEMPLATE.md`
+- **Index**: `devflow/workspace/index.md`
+- **Attention Refresh**: `.claude/skills/flow-attention-refresh/SKILL.md`

package/.claude/commands/{cancel-ralph.md → util/cancel-ralph.md}

@@ -1,4 +1,5 @@
 ---
+name: "cancel-ralph"
 description: "Cancel active Ralph Wiggum loop"
 allowed-tools: ["Bash(test -f .claude/ralph-loop.local.md:*)", "Bash(rm .claude/ralph-loop.local.md)", "Read(.claude/ralph-loop.local.md)"]
 hide-from-slash-command-tool: "true"

package/.claude/config/quality-gates.yml

@@ -0,0 +1,305 @@
+# ============================================================================
+# Quality Gates Configuration for CC-DevFlow v3.0
+# ============================================================================
+# Version: 3.0.0
+# Purpose: Define programmatic quality verification rules for each flow phase.
+#          Replaces completion marker checking with code-verifies-code approach.
+# Reference: RM-016 Quality Gate Enhancement
+# ============================================================================
+
+# ============================================================================
+# Global Settings
+# ============================================================================
+global:
+  # Maximum iterations before forced stop (Ralph loop safety)
+  max_iterations: 10
+
+  # Timeout per phase in minutes
+  timeout_minutes: 30
+
+  # Enable verbose logging
+  verbose: false
+
+# ============================================================================
+# Ralph Loop Configuration (SubagentStop Hook)
+# ============================================================================
+# Top-level verify commands for ralph-loop.ts hook
+# These run when any subagent attempts to stop
+verify:
+  - npm run lint --if-present
+  - npm run typecheck --if-present
+  - npm test -- --passWithNoTests
+
+ralph_loop:
+  # Maximum iterations before forced stop
+  max_iterations: 5
+
+  # Timeout in minutes before forced stop
+  timeout_minutes: 30
+
+# ============================================================================
+# Claude Team Hooks Configuration (v4.7)
+# ============================================================================
+
+# ----------------------------------------------------------------------------
+# TaskCompleted Hook: Verify task completion quality
+# ----------------------------------------------------------------------------
+task_completed:
+  # Verification commands (uses top-level verify if not specified)
+  verify:
+    - npm run lint --if-present
+    - npm run typecheck --if-present
+    - npm test -- --passWithNoTests
+
+  # Block task completion if verification fails
+  block_on_failure: true
+
+  # Maximum retry attempts before allowing completion
+  max_retries: 3
+
+# ----------------------------------------------------------------------------
+# TeammateIdle Hook: Task assignment strategy
+# ----------------------------------------------------------------------------
+teammate_idle:
+  # Checks to run before assigning new task
+  idle_checks:
+    - npm run lint --if-present
+    - npm run typecheck --if-present
+
+  # Task assignment strategy: priority_first | round_robin | skill_match
+  assignment_strategy: priority_first
+
+  # Idle timeout in seconds before triggering shutdown
+  idle_timeout: 300
+
+# ============================================================================
+# Phase-Specific Quality Gates
+# ============================================================================
+
+# ----------------------------------------------------------------------------
+# flow-dev: Development Phase
+# ----------------------------------------------------------------------------
+flow-dev:
+  # Programmatic verification commands (must all pass to exit)
+  verify:
+    - name: "Lint Check"
+      command: "npm run lint --if-present || true"
+      required: true
+
+    - name: "Type Check"
+      command: "npm run typecheck --if-present || true"
+      required: true
+
+    - name: "Unit Tests"
+      command: "npm test -- --passWithNoTests"
+      required: true
+
+  # Fallback to completion markers if verify commands not available
+  completion_markers:
+    - "ALL_TASKS_COMPLETE"
+    - "TDD_CHECKPOINT_PASS"
+
+  # Phase-specific settings
+  max_iterations: 15
+  timeout_minutes: 45
+
+# ----------------------------------------------------------------------------
+# flow-review: Code Review Phase
+# ----------------------------------------------------------------------------
+flow-review:
+  verify:
+    - name: "Lint Check"
+      command: "npm run lint --if-present || true"
+      required: true
+
+    - name: "Type Check"
+      command: "npm run typecheck --if-present || true"
+      required: true
+
+  completion_markers:
+    - "SPEC_REVIEW_PASS"
+    - "CODE_QUALITY_PASS"
+
+  max_iterations: 5
+  timeout_minutes: 20
+
+# ----------------------------------------------------------------------------
+# flow-quality: Combined Quality Phase (v3.0 NEW)
+# ----------------------------------------------------------------------------
+flow-quality:
+  # Quick mode (default)
+  quick:
+    verify:
+      - name: "Lint Check"
+        command: "npm run lint --if-present || true"
+        required: true
+
+      - name: "Type Check"
+        command: "npm run typecheck --if-present || true"
+        required: true
+
+      - name: "Unit Tests"
+        command: "npm test -- --passWithNoTests"
+        required: true
+
+  # Full mode (--full flag)
+  full:
+    verify:
+      - name: "Lint Check"
+        command: "npm run lint --if-present || true"
+        required: true
+
+      - name: "Type Check"
+        command: "npm run typecheck --if-present || true"
+        required: true
+
+      - name: "Unit Tests"
+        command: "npm test -- --passWithNoTests"
+        required: true
+
+      - name: "Integration Tests"
+        command: "npm run test:integration --if-present || true"
+        required: false
+
+      - name: "Security Scan"
+        command: "npm audit --audit-level=high || true"
+        required: false
+
+    completion_markers:
+      - "SPEC_REVIEW_PASS"
+      - "CODE_QUALITY_PASS"
+      - "QA_PASS"
+      - "SECURITY_PASS"
+
+  max_iterations: 10
+  timeout_minutes: 30
+
+# ----------------------------------------------------------------------------
+# flow-qa: QA Phase (deprecated in v3.0, use flow-quality)
+# ----------------------------------------------------------------------------
+flow-qa:
+  verify:
+    - name: "Unit Tests"
+      command: "npm test -- --passWithNoTests"
+      required: true
+
+    - name: "Security Audit"
+      command: "npm audit --audit-level=high || true"
+      required: false
+
+  completion_markers:
+    - "QA_PASS"
+    - "SECURITY_PASS"
+
+  max_iterations: 5
+  timeout_minutes: 20
+
+# ----------------------------------------------------------------------------
+# flow-release: Release Phase
+# ----------------------------------------------------------------------------
+flow-release:
+  verify:
+    - name: "All Tests Pass"
+      command: "npm test -- --passWithNoTests"
+      required: true
+
+    - name: "Build Success"
+      command: "npm run build --if-present || true"
+      required: true
+
+  completion_markers:
+    - "PR_CREATED"
+    - "RELEASE_READY"
+
+  max_iterations: 3
+  timeout_minutes: 15
+
+# ============================================================================
+# Error Recording Configuration
+# ============================================================================
+error_recording:
+  # Path to ERROR_LOG.md (relative to requirement directory)
+  log_file: "ERROR_LOG.md"
+
+  # Error entry format
+  format: |
+    ## [{timestamp}] E{error_number}: {title}
+
+    **Phase**: {phase}
+    **Error Type**: {error_type}
+    **Error Message**:
+    ```
+    {error_message}
+    ```
+    **Root Cause**: {root_cause}
+    **Resolution**: {resolution}
+    **Prevention**: {prevention}
+
+  # Error types
+  types:
+    - "Test Failure"
+    - "Build Error"
+    - "Lint Error"
+    - "Type Error"
+    - "Runtime Error"
+    - "Security Issue"
+
+# ============================================================================
+# Integration with Ralph Loop
+# ============================================================================
+ralph_loop:
+  # State file location
+  state_file: "ralph-loop.local.json"
+
+  # Fields to track
+  state_fields:
+    - phase
+    - iteration
+    - errors
+    - lastVerifyResult
+    - lastVerifyTimestamp
+
+  # Exit conditions
+  exit_conditions:
+    - "all_verify_pass"
+    - "max_iterations_reached"
+    - "timeout_reached"
+    - "manual_stop"
+
+  # ----------------------------------------------------------------------------
+  # Team Mode Configuration (v4.7)
+  # ----------------------------------------------------------------------------
+  team_mode:
+    # Enable Team mode Ralph Loop
+    enabled: true
+
+    # Verification scope: teammate (per-teammate) or global (all at once)
+    scope: teammate
+
+    # Teammate-specific verification commands
+    # Each teammate can have custom verify commands based on their role
+    teammate_verify:
+      dev-frontend:
+        - npm run lint -- --files-changed
+        - npm run typecheck --if-present
+        - npm test -- --changed
+      dev-backend:
+        - npm run lint -- --files-changed
+        - npm run typecheck --if-present
+        - npm test -- --changed
+      dev-database:
+        - npm run lint -- --files-changed
+        - npm run typecheck --if-present
+
+    # Global verification (runs when last teammate stops)
+    global_verify:
+      - npm run lint
+      - npm run typecheck --if-present
+      - npm test -- --passWithNoTests
+
+    # Maximum iterations per teammate before forced stop
+    max_iterations_per_teammate: 3
+
+    # Maximum global iterations before forced stop
+    max_global_iterations: 10
+