cc-devflow 4.1.5 → 4.2.0

package/.claude/guides/workflow-guides/flow-orchestrator.md

@@ -1,282 +1,48 @@
 ---
 name: flow-orchestrator-guide
-description: Standard Operating Procedure for main agent when executing /flow-new command. Not an executable agent, but workflow guidance.
+description: Standard Operating Procedure for main agent when executing canonical /flow:* delivery chain.
 type: workflow-guide
 ---
 
-# 需求开发流程标准作业程序
+# 需求开发流程标准作业程序（主链版）
 
-当用户执行 `/flow-new "REQ-ID|TITLE|PLAN_URLS"` 时，主 Agent (Claude 本身) 应按以下标准流程操作：
-
-## 核心原则 (遵循 Claude Code 最佳实践)
-
-### 主 Agent 职责
-- **完整上下文管理**: 主 Agent 拥有项目全貌，负责所有代码实施
-- **Sub-agent 协调**: 调用研究型 sub-agents 收集专业信息和制定计划
-- **最终实施**: 基于所有研究报告和计划，主 Agent 直接执行代码修改
-
-### Sub-agent 定位
-- **研究员角色**: 仅提供研究报告、分析文档、实施计划
-- **无代码执行**: 不直接修改项目文件，只输出 Markdown 文档
-- **专业分工**: 各自在专业领域提供深度分析和建议
-
-### 工作流原则
-1. **顺序执行**: 避免并行代码修改，确保一致性
-2. **上下文保持**: 主 Agent 保持完整项目上下文
-3. **计划先行**: 充分规划后再执行实施
-4. **质量保证**: 每个阶段都有相应的质量检查
-5. **避免过度设计**: 在需求研究与规划分解阶段，坚持最小可行实现与核心价值，避免提前引入复杂架构、抽象或不必要的扩展点
-
-## Rules Integration
-You MUST follow these rules during orchestration:
-
-0. **Constitution** (${DEVFLOW_CLAUDE_DIR:-.claude}/rules/project-constitution.md):
-   - **Project Constitution**: Follow all constitutional principles without exception
-   - **Quality Gates**: Enforce all quality gate requirements
-   - **Architecture Constraints**: Adhere to architectural consistency rules
-   - **Security Principles**: Apply security-first approach to all operations
-
-1. **Standard Patterns**:
-   - Apply Fail Fast principle: validate inputs immediately
-   - Use Clear Errors with structured error messages
-   - Maintain Minimal Output approach in user communication
-   - Follow Trust System principle for sub-agent delegation
-
-2. **DevFlow Patterns**:
-   - Enforce REQ-ID format validation: REQ-\d+
-   - Use standard branch naming: feature/${reqId}-${slug(BRANCH_TITLE_EN)} (模型意译生成，禁止拼音/音译)
-   - Apply commit message format: feat(${reqId}): ${taskTitle}
-   - Maintain complete document chain: PRD → EPIC → TASKS
-
-3. **Agent Coordination**:
-   - Use file locks for concurrent access prevention
-   - Update status in LOG.md after each sub-agent call
-   - Implement proper error propagation between agents
-   - Follow the defined sub-agent call sequence
-
-4. **Branch Operations** (${DEVFLOW_CLAUDE_DIR:-.claude}/guides/technical-guides/git-github-guide.md):
-   - Verify clean working directory before branch creation
-   - Use conventional commit messages with Co-authored-by
-   - Enforce quality gates before any push operations
-   - Clean up branches after successful merge
-
-5. **GitHub Operations** (${DEVFLOW_CLAUDE_DIR:-.claude}/guides/technical-guides/git-github-guide.md):
-   - Check authentication status before PR operations
-   - Verify repository is not a template before modifications
-   - Use structured PR descriptions with links to documentation
-   - Handle permission errors gracefully
-
-6. **Test Execution**:
-   - Delegate all testing to qa-tester sub-agent
-   - Capture verbose test output for audit trail
-   - Enforce minimum coverage thresholds
-   - Never mock external services in tests
-
-7. **DateTime Handling**:
-   - Use real system time in ISO 8601 UTC format
-   - Include timestamps in all YAML frontmatter
-   - Handle timezone-aware operations correctly
-   - Support cross-platform datetime operations
-
-8. **MCP Integration**:
-   - Use WebFetch tool for all external content retrieval
-   - Apply URL validation rules for security
-   - Implement retry logic with exponential backoff
-   - Cache content appropriately to reduce API calls
-
-Steps:
-0) Constitutional Validation
-   - Read and internalize ${DEVFLOW_CLAUDE_DIR:-.claude}/rules/project-constitution.md requirements
-   - Validate all inputs against constitutional principles
-   - Ensure current environment meets constitutional standards
-   - Apply constitutional constraints to the entire workflow
-
-1) Context intake
-   - If planSources include URLs, first use MCP server "docs-web" (or WebFetch) to fetch HTML/MD/PDF and write them under devflow/requirements/${reqId}/research/${reqId}_*.md.
-   - Read local .claude/docs/plan/*.md and CLAUDE.md to learn codebase constraints.
-
-2) Git branch
-   - git switch -c feature/${reqId}-${slug(BRANCH_TITLE_EN)}
-
-## 标准作业流程
-
-### 阶段1: 需求研究和分析
-1. **外部资料研究**
-   ```bash
-   Task: prd-writer "Analyze ${planSources} and generate comprehensive PRD for ${reqId}: ${title}"
-   ```
-
-   - prd-writer 输出: `devflow/requirements/${reqId}/PRD.md`
-   - 主 Agent 读取并理解需求
-
-2. **规划和分解**
-   ```bash
-   Task: planner "Based on PRD, create Epic and detailed task breakdown for ${reqId}"
-   ```
-
-   - planner 输出: `EPIC.md` 和 `tasks/TASK_*.md`
-   - 主 Agent 审查规划合理性
-
-### 阶段2: 实施准备
-3. **一致性初步验证**（计划阶段）
-   ```bash
-   Task: consistency-checker "Verify document consistency and requirement traceability for ${reqId}"
-   ```
-
-   - consistency-checker 输出: `CONSISTENCY_ANALYSIS.md`
-   - 包含: 文档一致性检查、需求可追溯性验证、潜在冲突识别
-   - **触发条件**: PRD 和 EPIC 生成完成后自动执行
-
-4. **测试计划**（代码实现前）
-   ```bash
-   Task: qa-tester "Create comprehensive test plan for ${reqId} based on EPIC and tasks"
-   ```
-
-   - qa-tester 输出: `TEST_PLAN.md`
-   - 包含: 测试策略、用例设计、覆盖率要求
-   - **触发词**: 包含 "test plan" 的提示词
-
-5. **安全评估计划**（代码实现前）
-   ```bash
-   Task: security-reviewer "Create comprehensive security plan for ${reqId} based on requirements"
-   ```
-
-   - security-reviewer 输出: `SECURITY_PLAN.md`
-   - 包含: 安全检查点、风险评估、缓解措施
-   - **触发词**: 包含 "security plan" 的提示词
-
-### 阶段3: 主 Agent 代码实施
-5. **代码实施**
-   - 主 Agent 基于详细的 TASK 文档直接编写代码
-   - 遵循现有项目模式和约定
-   - 实施所有 TASK 的功能要求
-
-### 阶段4: 质量验证（代码实现后）
-6. **测试执行和报告**
-   ```bash
-   Task: qa-tester "Analyze implemented code and generate comprehensive test report for ${reqId}"
-   ```
-
-   - 主 Agent 基于 TEST_PLAN.md 编写和执行测试
-   - qa-tester 分析测试结果，输出: `TEST_REPORT.md`
-   - 包含: 覆盖率分析、测试结果、质量评估
-   - **触发词**: 包含 "test report" 的提示词
-
-7. **安全检查和报告**
-   ```bash
-   Task: security-reviewer "Analyze implemented code and generate comprehensive security report for ${reqId}"
-   ```
-
-   - security-reviewer 分析实际代码，输出: `SECURITY_REPORT.md`
-   - 包含: 漏洞扫描、安全风险、修复建议
-   - **触发词**: 包含 "security report" 的提示词
-
-8. **最终一致性验证**（实施完成后）
-   ```bash
-   Task: consistency-checker "Perform comprehensive consistency verification for completed ${reqId}"
-   ```
-
-   - consistency-checker 输出: `FINAL_CONSISTENCY_REPORT.md`
-   - 包含: 实现与规格一致性、测试覆盖完整性、文档同步状态
-   - **触发条件**: 代码实现和质量报告完成后执行
-
-9. **发布准备**
-   ```bash
-   Task: release-manager "Create release plan for ${reqId} based on quality reports"
-   ```
-
-   - release-manager 输出: `RELEASE_PLAN.md`
-   - 包含: 发布流程、回滚计划、部署策略
-
-### 阶段5: 发布执行
-10. **质量闸检查**
-   - **宪法合规检查**: 验证所有代码和流程符合项目宪法
-   - **质量闸验证**: 确保通过所有质量闸要求
-   - **架构一致性**: 验证架构约束得到遵循
-   - **安全原则**: 确保安全原则得到执行
-   - 修复 TEST_REPORT.md 和 SECURITY_REPORT.md 中发现的问题
-
-11. **发布和合并**
-    - 主 Agent 基于 RELEASE_PLAN.md 创建 PR
-    - 执行最终质量闸检查
-    - 处理代码合并流程
-
-### 阶段6: 总结和归档
-12. **文档更新**
-    - 更新项目文档和说明
-    - 记录实施过程和决策
-    - 记录需求完成状态
-
-13. **执行日志**
-    - 在 LOG.md 中记录完整执行过程
-    - 包含时间线、决策点、问题解决
+当用户执行需求交付时，主 Agent 按显式主链推进：
 
 ```text
-devflow/requirements/${reqId}/
-├── PRD.md                 # 产品需求文档
-├── EPIC.md               # Epic 规划
-├── tasks/                # 任务分解
-│   ├── TASK_001.md
-│   ├── TASK_002.md
-│   └── ...
-├── research/             # 外部研究材料
-│   ├── ${reqId}_plan_1.md
-│   └── ${reqId}_plan_2.md
-├── TEST_REPORT.md        # 测试报告
-└── LOG.md               # 执行日志
+/flow:init -> /flow:spec -> /flow:dev -> /flow:verify -> /flow:release
 ```
 
-## Agent Coordination Protocol
+## 主 Agent 职责
+- 维护全局上下文与最终实现。
+- 仅把研究/规划/审查任务分发给对应子代理。
+- 在每个阶段结束后写入状态与审计日志。
 
-### Status Management
-Create and maintain status files for coordination:
-```json
-// devflow/requirements/${reqId}/orchestration_status.json
-{
-  "reqId": "${reqId}",
-  "currentPhase": "development",
-  "startTime": "2024-01-15T10:30:00Z",
-  "phaseStatus": {
-    "research": "completed",
-    "prd": "completed",
-    "planning": "completed",
-    "development": "in_progress",
-    "testing": "pending",
-    "security": "pending",
-    "release": "pending"
-  },
-  "activeAgents": [
-    {"agent": "qa-tester", "phase": "test_analysis", "status": "running", "startTime": "..."},
-    {"agent": "security-reviewer", "phase": "security_analysis", "status": "running", "startTime": "..."}
-  ],
-  "completedTasks": ["TASK_003"],
-  "failedTasks": [],
-  "nextActions": ["wait_for_TASK_001", "wait_for_TASK_002"]
-}
-```
+## 阶段作业
+
+### 1) 初始化 `/flow:init`
+- 创建需求目录与运行时上下文。
+- 写入初始 `orchestration_status.json`。
 
-### Sequential Execution Pattern
-When coordinating research agents:
-1. **Pre-Launch**: Create orchestration_status.json
-2. **Sequential Launch**: Start agents one by one based on dependencies
-3. **Monitor**: Check agent completion via file system
-4. **Quality Check**: Validate each agent's output before proceeding
-5. **Main Agent Execution**: Execute code implementation based on all plans
+### 2) 规格与任务 `/flow:spec`
+- 统一完成 PRD、技术方案、UI 约束（按模式可裁剪）。
+- 产出可执行 `TASKS.md`，进入 `spec_complete`。
 
-### Error Handling
-- If any research agent fails, pause and report
-- Allow manual intervention or retry
-- Update status file with failure details
-- Provide recovery options
+### 3) 开发执行 `/flow:dev`
+- 按 task manifest 执行并更新进度。
+- 失败任务通过 `--resume` 增量恢复。
 
-### Communication Files
-- `orchestration_status.json` - Current execution state
-- `LOG.md` - Detailed audit trail
-- `dev_status.json` - Development phase specifics
-- Individual task completion markers in tasks/ directory
+### 4) 质量闸 `/flow:verify`
+- 快速模式用于日常检查。
+- `--strict` 作为发布前唯一准入门禁。
 
-Be conservative with privileges. Ask when performing push/merge. Persist everything in Markdown.
+### 5) 发布收口 `/flow:release`
+- 仅在 verify 通过后创建发布产物。
+- 收尾清理 runtime/worktree 噪音。
 
-## Key Implementation Notes
+## 失败恢复原则
+- 不回退整条链，优先从失败阶段重试。
+- 优先命令：`/flow:status`、`/flow:dev --resume`、`/flow:verify --strict`。
 
-**REMEMBER**: This is a workflow guide for the main agent. The main agent should call research-type sub-agents using Task tool for analysis and planning, then execute all actual code implementation, testing, and git operations directly based on the plans received from sub-agents.
+## 约束
+- 必须遵循项目宪法与质量门禁。
+- 禁止把旧链路命令（如 `/flow-new`）作为主流程推荐。

package/.claude/hooks/CLAUDE.md

@@ -86,7 +86,7 @@ Hook 检测到 Task 工具调用
 | prd-writer | flow-spec | prd-writer.jsonl |
 | tech-architect | flow-spec | tech-architect.jsonl |
 | planner | flow-spec | planner.jsonl |
-| qa-tester | flow-quality | qa-tester.jsonl |
+| qa-tester | flow-verify | qa-tester.jsonl |
 
 ## ralph-loop.ts (v4.7 Team 模式)
 

package/.claude/hooks/checklist-gate.js

@@ -228,7 +228,7 @@ function logGateSkip(reqDir, completion, threshold, reason) {
 **Completion**: ${completion.percentage}%
 **Threshold**: ${threshold}%
 **Reason**: ${reason}
-**Command**: /flow-epic --skip-gate --reason "${reason}"
+**Command**: /flow:spec --skip-gate --reason "${reason}"
 `;
 
     try {
@@ -252,7 +252,7 @@ function outputText(result) {
         console.log('❌ Checklist Gate: NO_CHECKLISTS');
         console.log('   No checklist files found.');
         console.log('');
-        console.log('   Run /flow-checklist --type <type> first.');
+        console.log('   Run /flow:verify --strict first.');
         return;
     }
 
@@ -273,7 +273,7 @@ function outputText(result) {
         console.log('');
         console.log('   To continue:');
         console.log('   1. Review and complete checklist items');
-        console.log('   2. Run /flow-checklist --status to check progress');
+        console.log('   2. Run /flow:verify --strict to re-check progress');
         console.log('   3. Or use --skip-gate --reason "your reason" to bypass');
     }
 
@@ -382,7 +382,7 @@ function main() {
         },
         message: passed
             ? `Checklist completion ${completion.percentage}% >= ${threshold}% threshold`
-            : `Checklist completion ${completion.percentage}% < ${threshold}% threshold. Run /flow-checklist --status to review.`
+            : `Checklist completion ${completion.percentage}% < ${threshold}% threshold. Run /flow:verify --strict to review.`
     };
 
     if (options.json) {

package/.claude/hooks/inject-agent-context.ts

@@ -50,8 +50,8 @@ const AGENT_SKILL_MAP: Record<string, string> = {
   'ui-designer': 'flow-spec',
   'planner': 'flow-spec',
   'dev-implementer': 'flow-dev',
-  'qa-tester': 'flow-quality',
-  'security-reviewer': 'flow-quality',
+  'qa-tester': 'flow-verify',
+  'security-reviewer': 'flow-verify',
   'release-manager': 'flow-release',
 };
 

package/.claude/scripts/calculate-checklist-completion.sh

@@ -152,7 +152,7 @@ if [[ ! -d "$CHECKLISTS_DIR" ]]; then
         echo "ERROR: NO_CHECKLISTS" >&2
         echo "Checklists directory not found: $CHECKLISTS_DIR" >&2
         echo "" >&2
-        echo "Run /flow-checklist --type <type> first." >&2
+        echo "Run /flow:verify --strict first." >&2
     fi
     exit 1
 fi
@@ -171,7 +171,7 @@ if [[ ${#CHECKLIST_FILES[@]} -eq 0 ]]; then
         echo "ERROR: NO_CHECKLISTS" >&2
         echo "No checklist files found in $CHECKLISTS_DIR" >&2
         echo "" >&2
-        echo "Run /flow-checklist --type <type> first." >&2
+        echo "Run /flow:verify --strict first." >&2
     fi
     exit 1
 fi

package/.claude/scripts/check-prerequisites.sh

@@ -126,7 +126,7 @@ 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
+    echo "Run /flow:init first to create the requirement structure." >&2
     exit 1
 fi
 
@@ -229,4 +229,4 @@ else
         check_file "$ANALYSIS_FILE" "ANALYSIS.md"
         check_file "$PLAN_FILE" "PLAN.md"
     fi
-fi
+fi

package/.claude/scripts/checklist-errors.sh

@@ -2,7 +2,7 @@
 # ============================================================================
 # checklist-errors.sh
 # ============================================================================
-# Error codes and messages for /flow-checklist command and related hooks
+# Error codes and messages for checklist gate and related hooks
 #
 # Usage: source this file in scripts that need checklist error handling
 #
@@ -51,7 +51,7 @@ print_checklist_error() {
             echo "ERROR: $code" >&2
             echo "PRD.md not found in requirement directory." >&2
             echo "" >&2
-            echo "Run /flow-prd first." >&2
+            echo "Run /flow:spec first." >&2
             ;;
         "$ERR_INVALID_TYPE")
             echo "ERROR: $code" >&2
@@ -63,7 +63,7 @@ print_checklist_error() {
             echo "ERROR: $code" >&2
             echo "No checklists found in checklists/ directory." >&2
             echo "" >&2
-            echo "Run /flow-checklist --type <type> first." >&2
+            echo "Run /flow:verify --strict first." >&2
             ;;
         "$ERR_ITEM_NOT_FOUND")
             echo "WARNING: $code" >&2
@@ -73,7 +73,7 @@ print_checklist_error() {
             echo "ERROR: $code" >&2
             echo "Checklist completion $extra" >&2
             echo "" >&2
-            echo "Run /flow-checklist --status to review incomplete items." >&2
+            echo "Run /flow:verify --strict to review incomplete items." >&2
             echo "Or use --skip-gate --reason \"your reason\" to bypass." >&2
             ;;
         "$ERR_SKIP_REASON_REQUIRED")

package/.claude/scripts/flow-quality-full.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 # [INPUT]: 依赖 run-quality-gates.sh, spec-reviewer, code-quality-reviewer, security-reviewer
 # [OUTPUT]: 完整质量验证结果和报告
-# [POS]: scripts 的完整质量验证脚本，被 /flow-quality --full 调用
+# [POS]: scripts 的完整质量验证脚本，被 /flow:verify --strict 调用
 # [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
 
 set -e
@@ -72,7 +72,7 @@ echo "   Output: $REQ_DIR/SPEC_REVIEW.md"
 cat > "$REQ_DIR/SPEC_REVIEW.md" << EOF
 # Spec Compliance Review
 
-> Generated by /flow-quality --full
+> Generated by /flow:verify --strict
 
 ## Summary
 
@@ -103,7 +103,7 @@ echo "   Output: $REQ_DIR/CODE_QUALITY_REVIEW.md"
 cat > "$REQ_DIR/CODE_QUALITY_REVIEW.md" << EOF
 # Code Quality Review
 
-> Generated by /flow-quality --full
+> Generated by /flow:verify --strict
 
 ## Summary
 
@@ -139,7 +139,7 @@ fi
 cat > "$REQ_DIR/SECURITY_REPORT.md" << EOF
 # Security Report
 
-> Generated by /flow-quality --full
+> Generated by /flow:verify --strict
 
 ## Summary
 
@@ -167,7 +167,7 @@ echo "--------------------"
 cat > "$REQ_DIR/TEST_REPORT.md" << EOF
 # Test Report
 
-> Generated by /flow-quality --full
+> Generated by /flow:verify --strict
 
 ## Summary
 

package/.claude/scripts/flow-quality-quick.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 # [INPUT]: 依赖 run-quality-gates.sh
 # [OUTPUT]: 快速质量验证结果
-# [POS]: scripts 的快速质量验证脚本，被 /flow-quality 调用
+# [POS]: scripts 的快速质量验证脚本，被 /flow:verify 调用
 # [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
 
 set -e
@@ -54,7 +54,7 @@ if [[ -n "$REQ_DIR" && -d "$REQ_DIR" ]]; then
     cat > "$REQ_DIR/TEST_REPORT.md" << EOF
 # Test Report
 
-> Generated by /flow-quality (quick mode)
+> Generated by /flow:verify (quick mode)
 
 ## Summary
 
@@ -76,7 +76,7 @@ EOF
     cat > "$REQ_DIR/SECURITY_REPORT.md" << EOF
 # Security Report
 
-> Generated by /flow-quality (quick mode)
+> Generated by /flow:verify (quick mode)
 
 ## Summary
 
@@ -87,7 +87,7 @@ EOF
 ## Checks Performed
 
 - [x] Baseline quality gate security checks
-- [ ] Deep security audit (use /flow-quality --full when needed)
+- [ ] Deep security audit (use /flow:verify --strict when needed)
 
 ## Quality Gate
 

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

@@ -88,7 +88,7 @@ Workspace created for $DEVELOPER.
 
 ### Next Steps
 
-1. Start a requirement with \`/flow-init "REQ-XXX|Title"\`
+1. Start a requirement with \`/flow:init "REQ-XXX|Title"\`
 2. Use \`/flow-workspace record "message"\` to track progress
 3. Use \`/flow-workspace start\` to recover context in new sessions
 
@@ -113,5 +113,5 @@ echo "Files created:"
 ls -la "$DEV_WORKSPACE"
 echo ""
 echo "Next steps:"
-echo "  1. Start a requirement: /flow-init \"REQ-XXX|Title\""
+echo "  1. Start a requirement: /flow:init \"REQ-XXX|Title\""
 echo "  2. Record progress: /flow-workspace record \"message\""

package/.claude/scripts/generate-clarification-report.sh

@@ -288,21 +288,21 @@ EOF
         cat << EOF
 ✅ **Clarification complete**. All ${questions_answered} questions answered.
 
-Recommended next command: \`/flow-prd ${req_id}\`
+Recommended next command: \`/flow:spec ${req_id}\`
 EOF
     elif [[ "$questions_count" -eq 0 ]]; then
         cat << EOF
 ✅ **No critical ambiguities detected**. research.md is sufficiently specified.
 
-Recommended next command: \`/flow-prd ${req_id}\`
+Recommended next command: \`/flow:spec ${req_id}\`
 EOF
     else
         cat << EOF
 ⚠️ **Clarification incomplete**. ${questions_answered}/${questions_count} questions answered.
 
 Options:
-1. Continue with \`/flow-clarify ${req_id}\` to complete remaining questions
-2. Proceed with \`/flow-prd ${req_id}\` (acceptable risk if remaining items are low-impact)
+1. Continue with \`/flow:spec ${req_id} --overwrite\` to complete remaining questions
+2. Proceed with \`/flow:spec ${req_id}\` (acceptable risk if remaining items are low-impact)
 EOF
     fi