cc-devflow 4.1.4 → 4.1.6

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/hooks/teammate-idle-hook.ts

@@ -117,7 +117,7 @@ function findRepoRoot(startPath: string): string | null {
 }
 
 /**
- * 从 worktree 目录名或分支名提取 REQ-ID
+ * 从环境变量、.current-req 文件或目录扫描提取 REQ-ID
  */
 function extractReqId(repoRoot: string): string | null {
   // 尝试从目录名提取 (e.g., cc-devflow-REQ-123)

package/.claude/rules/devflow-conventions.md

@@ -61,100 +61,9 @@ devflow/requirements/${reqId}/
 
 ---
 
-## 🌿 Git Worktree 约定 (v4.3)
+## 🌿 Git 约定
 
-### Worktree vs Branch 模式
-
-| 模式 | 命令 | 适用场景 |
-|------|------|----------|
-| **Worktree (默认)** | `/flow-init "REQ-123\|Title"` | 多需求并行、需要隔离环境 |
-| **Branch** | `/flow-init "REQ-123\|Title" --branch-only` | 单需求开发、简单修改 |
-
-### Worktree 目录布局
-
-```
-~/projects/
-├── cc-devflow/                    # 主仓库 (main 分支)
-├── cc-devflow-REQ-001/            # REQ-001 worktree
-├── cc-devflow-REQ-002/            # REQ-002 worktree
-├── cc-devflow-analysis/           # 只读分析 worktree (可选)
-└── cc-devflow-hotfix/             # 紧急修复 worktree (可选)
-```
-
-### 命名规范
-
-```bash
-# Worktree 目录
-{repo-name}-{REQ_ID}
-# 示例: cc-devflow-REQ-123
-
-# 对应分支 (不变)
-feature/${reqId}-${slug(BRANCH_TITLE_EN)}
-# 示例: feature/REQ-123-user-order-support
-```
-
-### Worktree 操作流程
-
-1. **创建** (flow-init 自动执行)
-   ```bash
-   git worktree add -b feature/REQ-123-title ../cc-devflow-REQ-123
-   ```
-
-2. **切换**
-   ```bash
-   cd ../cc-devflow-REQ-123
-   # 或使用 shell 别名
-   zw REQ-123
-   ```
-
-3. **开发**
-   - 每个 worktree 独立的 Claude Code 会话
-   - 互不干扰，保持上下文
-
-4. **清理** (flow-release 自动执行)
-   ```bash
-   git worktree remove ../cc-devflow-REQ-123
-   git branch -d feature/REQ-123-title
-   ```
-
-### Shell 别名推荐
-
-```bash
-# 添加到 ~/.zshrc 或 ~/.bashrc
-alias za='cd $(git rev-parse --show-toplevel 2>/dev/null || echo .)'
-alias zl='git worktree list'
-alias zm='cd ~/projects/cc-devflow'
-
-zw() {
-  local req_id="${1:-}"
-  local repo_name=$(basename $(git rev-parse --show-toplevel 2>/dev/null))
-  cd ~/projects/${repo_name}-${req_id}
-}
-```
-
-### 分支命名 (保持不变)
-
-```bash
-# 标准格式
-feature/${reqId}-${slug(BRANCH_TITLE_EN)}
-
-# 示例
-feature/REQ-123-user-order-support
-feature/REQ-124-permission-management
-```
-
-> BRANCH_TITLE_EN 为 TITLE 的英文意译 (语义为准，非拼音，使用模型意译)
-
-### 分支操作流程 (Worktree 模式)
-
-1. 确保主仓库在 main 分支且状态干净
-2. 执行 `/flow-init` 创建 worktree + 分支
-3. 切换到 worktree 目录
-4. 启动新的 Claude Code 会话
-5. 实施开发 (TDD方式)
-6. 质量闸检查
-7. 创建 PR
-8. 合并后清理 worktree 和分支
+> Git 分支、worktree、PR、合并由用户自行管理，DevFlow 不参与 Git 拓扑管理。
 
 ---
 

package/.claude/scripts/CLAUDE.md

@@ -17,7 +17,7 @@ check-dependencies.sh: 依赖关系检查脚本。
 check-prerequisites.sh: 流程前置条件统一校验脚本。
 check-task-status.sh: TASKS 完成状态统计脚本。
 checklist-errors.sh: Checklist 错误码与诊断脚本。
-common.sh: 脚本公共函数库（REQ 识别、worktree 路径、日志工具等）。
+common.sh: 脚本公共函数库（REQ 识别、日志工具等）。
 consolidate-research.sh: research 结果汇总脚本。
 create-requirement.sh: 创建需求目录与初始状态；同步 workspace 的 `.current-req`。
 delta-parser.ts: Delta 解析器。
@@ -36,8 +36,6 @@ flow-quality-full.sh: 全量质量检查脚本。
 flow-quality-quick.sh: 快速质量检查脚本。
 flow-workspace-init.sh: 开发者 workspace 初始化脚本。
 flow-workspace-record.sh: workspace journal 追加记录脚本。
-flow-workspace-start.sh: workspace 会话恢复脚本；支持 REQ 覆盖与 worktree 切换提示。
-flow-workspace-switch.sh: workspace REQ 切换脚本；支持 `--print-cd` 与 `--cd`。
 generate-clarification-questions.sh: Clarify 问题生成脚本。
 generate-clarification-report.sh: Clarify 报告生成脚本。
 generate-quickstart.sh: quickstart 文档生成脚本。
@@ -75,5 +73,4 @@ workflow-status.ts: 工作流状态类型化读取器。
 ## 设计约束
 
 - 需求识别统一复用 `common.sh`，避免多处正则分叉。
-- worktree 与 workspace 职责分离：代码隔离由 worktree 提供，连续上下文由 workspace 提供。
 - 新增脚本优先保持幂等与可重入，便于中断恢复。

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")