cc-devflow 4.2.0 → 4.4.1

package/.claude/skills/workflow/flow-init/assets/INIT_FLOW_TEMPLATE.md

@@ -1,198 +0,0 @@
-# Flow-Init Execution Flow Template
-
-> Detailed stages for `/flow-init` requirement initialization
-
-<!-- ============================================================
-     调用上下文声明 (Invocation Context Declaration)
-     ============================================================
-
-本模板由 `/flow-init` 命令通过 {TEMPLATE:flow} 引用加载。
-
-模板中的 {SCRIPT:xxx} 占位符引用 flow-init.md 头文件中的 scripts 定义：
-```yaml
-# 来源: .claude/commands/flow-init.md 头文件
-scripts:
-  create: .claude/scripts/create-requirement.sh
-  prereq: .claude/scripts/check-prerequisites.sh
-  research_tasks: .claude/scripts/generate-research-tasks.sh
-  populate_tasks: .claude/scripts/populate-research-tasks.sh
-  consolidate: .claude/scripts/consolidate-research.sh
-  validate_research: .claude/scripts/validate-research.sh
-```
-
-占位符解析:
-- {SCRIPT:prereq}           → bash .claude/scripts/check-prerequisites.sh
-- {SCRIPT:create}           → bash .claude/scripts/create-requirement.sh
-- {SCRIPT:research_tasks}   → bash .claude/scripts/generate-research-tasks.sh
-- {SCRIPT:populate_tasks}   → bash .claude/scripts/populate-research-tasks.sh
-- {SCRIPT:consolidate}      → bash .claude/scripts/consolidate-research.sh
-- {SCRIPT:validate_research} → bash .claude/scripts/validate-research.sh
-============================================================ -->
-
----
-
-## Stage 1: Entry Gate (参数验证)
-
-```bash
-# 1. 解析参数
-REQ_ID|TITLE|PLAN_URLS → 验证 REQ_ID 格式: ^(REQ|BUG)-[0-9]+$
-→ 若 TITLE 含中文/非ASCII，使用模型意译生成 BRANCH_TITLE_EN（英文语义翻译，禁止拼音/音译）
-→ BRANCH_TITLE_EN 仅用于分支名，文档标题仍使用原始 TITLE
-→ 若意译不确定或未生成 ASCII 结果，向用户确认英文分支标题
-
-# 2. 前置条件检查
-bash {SCRIPT:prereq} --json --paths-only
-→ Git 状态干净 + devflow/ 目录存在
-
-# 3. 目录唯一性检查
-→ 确认 devflow/requirements/${REQ_ID}/ 不存在
-```
-
----
-
-## Stage 1.2: Git Branch Creation
-
-```bash
-# 创建功能分支
-Requirements: feature/${REQ_ID}-${slug(BRANCH_TITLE_EN)}
-Bug Fixes:    bugfix/${BUG_ID}-${slug(BRANCH_TITLE_EN)}
-
-# BRANCH_TITLE_EN = TITLE 的英文意译 (语义为准，非拼音，使用模型意译)
-# slug() = lowercase, replace spaces/special chars with hyphens
-```
-
----
-
-## Stage 1.5: Context Loading (路线图与架构)
-
-**目标**: 理解需求在项目中的位置
-
-```bash
-# 检查 ROADMAP.md 和 ARCHITECTURE.md
-→ 如果存在: 加载上下文，展示需求位置
-→ 如果不存在: 提示可选运行 /core-roadmap (不阻塞执行)
-```
-
----
-
-## Stage 2: Directory Initialization
-
-```bash
-# 创建需求目录
-bash {SCRIPT:create} "${REQ_ID}" --title "${TITLE}" --branch-title "${BRANCH_TITLE_EN}" --json
-
-→ 若未生成 BRANCH_TITLE_EN，则省略 --branch-title
-
-# 生成文件
-devflow/requirements/${REQ_ID}/
-├── README.md
-├── EXECUTION_LOG.md
-├── orchestration_status.json
-└── research/ (空目录)
-```
-
----
-
-## Stage 2.5: Research (Subagent Mandatory)
-
-**目标**: 研究默认必跑，但研究过程必须“隔离上下文”。
-
-**规则**: 大内容写入 `research/`，主会话只保留路径引用与决策摘要。
-
-### Mandatory: Call `flow-researcher` Subagent
-
-```
-Task tool call:
-  subagent_type: "flow-researcher"
-  prompt: (JSON) reqId/reqDir/title/planUrls/contextFiles
-```
-
-**产物** (由 subagent 写入):
-- `research/internal/codebase-overview.md`
-- `research/mcp/$(date +%Y%m%d)/**`
-- `research/research-summary.md`
-- `research/tasks.json`
-- `research/research.md`
-
----
-
-## Stage 2.6: Research Consolidation
-
-> 该阶段由 `flow-researcher` subagent 执行（含 tasks 生成/回填/整合/校验）。
-
----
-
-
-
-## Stage 3: README Generation
-
-```bash
-# 生成工作流指南
-→ devflow/requirements/${REQ_ID}/README.md
-→ 包含: 需求概述、工作流步骤、检查清单
-```
-
----
-
-## Stage 4: Exit Gate (5-Level Quality Check)
-
-### Level 1: File Existence Check
-```bash
-→ 验证所有必需文件已创建
-```
-
-### Level 2: Research.md Structure Validation
-```bash
-bash {SCRIPT:validate_research} "${REQ_DIR}" --strict
-→ 检查 research.md 结构
-```
-
-### Level 3: Research.md Content Quality
-```bash
-→ 无 TODO/FIXME/{{PLACEHOLDER}} 标记
-→ 每个 Decision block 完整
-```
-
-### Level 4: Research Tasks Validation
-```bash
-→ 验证 tasks.json 格式和内容
-```
-
-### Level 5: Git & Status & Constitution
-```bash
-→ Git 分支创建成功
-→ orchestration_status.json 正确
-→ Constitution 符合性检查
-```
-
----
-
-## Output Structure
-
-```
-devflow/requirements/${REQ_ID}/
-├── README.md
-├── research/
-│   ├── internal/
-│   │   └── codebase-overview.md
-│   ├── mcp/
-│   │   └── $(date +%Y%m%d)/
-│   │       ├── official/
-│   │       ├── guides/
-│   │       ├── tutorials/
-│   │       └── examples/
-│   ├── research.md
-│   ├── research-summary.md
-│   └── tasks.json
-├── EXECUTION_LOG.md
-└── orchestration_status.json
-```
-
-**Git**:
-- Branch: `feature/${REQ_ID}-${slug(BRANCH_TITLE_EN)}`
-- Status: orchestration_status.json.status = "initialized"
-- Phase: orchestration_status.json.phase = "planning"
-
----
-
-**Last Updated**: 2025-12-19

package/.claude/skills/workflow/flow-init/assets/RESEARCH_TEMPLATE.md

@@ -1,276 +0,0 @@
-# Research Summary — {FEATURE_NAME}
-
-> **Purpose**: Document all technical decisions made during requirement initialization
-> **Owner**: prd-writer / planner agents
-> **Status**: Living document (updated until PRD finalized)
-> **Template Version**: v1.0.0
-> **Constitution Compliance**: Article X.1 (Forced Clarification), Article X.2 (No Speculation)
-
-Generated: {GENERATED_AT}
-
----
-
-## Decisions
-
-### R001 — {TOPIC_DESCRIPTION}
-- **Decision**: {技术选型或架构决策}
-- **Rationale**:
-  - {理由 1: 必须明确说明为什么选择这个方案}
-  - {理由 2: 至少提供 2 条理由，证明决策经过深思熟虑}
-  - {理由 3 (可选): 更多支持性论据}
-- **Alternatives Considered**:
-  - {替代方案 1}: {简要评估 - 为什么不选择}
-  - {替代方案 2}: {简要评估 - 优缺点对比}
-- **Source**: {来源: PRD.md:42 或 Tech-Choice:Frontend Framework}
-
-### R002 — {TOPIC_DESCRIPTION}
-- **Decision**: {实际选择的技术/方案}
-- **Rationale**:
-  - {业务需求匹配度}
-  - {技术优势或团队熟悉度}
-- **Alternatives Considered**:
-  - {对比方案}: {不选择的原因}
-- **Source**: {来源}
-
----
-
-## Unresolved Questions
-
-> ⚠️ 使用 `[NEEDS CLARIFICATION]` 标记所有待澄清问题
-> 📌 每个问题必须包含: Context (上下文) + Impact (影响) + Blocked Tasks (阻塞任务)
-
-- **[NEEDS CLARIFICATION]**: {具体问题描述}
-  - **Context**: {为什么需要澄清这个问题}
-  - **Impact**: {不澄清会影响哪些决策或实现}
-  - **Blocked Tasks**: {哪些任务被阻塞 - 如 data-model.md, API contracts}
-
----
-
-## Source Library
-
-> **说明**: 列出所有研究材料的相对路径（相对于 REQ_DIR）
-
-### Internal Codebase Research
-- `research/internal/codebase-overview.md` - 现有代码库结构和可复用模块
-- `research/internal/testing-strategy.md` - 现有测试框架和模式
-
-### External Research Materials (MCP)
-- `research/mcp/20250126/official/nextjs-docs.md` - Next.js 14 官方文档（App Router）
-- `research/mcp/20250126/guides/prisma-best-practices.md` - Prisma ORM 最佳实践
-- `research/mcp/20250126/security/auth0-vs-clerk.md` - 认证方案对比
-
-### Manual Research Notes
-- `research/manual/database-benchmarks.md` - 性能基准测试结果
-- `research/manual/team-feedback.md` - 团队技术偏好调研
-
----
-
-## Research Completion Checklist
-
-> ✅ 使用此清单验证 research.md 是否完整且符合规范
-
-### Structure Validation
-- [ ] 包含 "## Decisions" 章节
-- [ ] 至少有 1 个 Decision block (### R001, R002, ...)
-- [ ] 包含 "## Source Library" 章节
-
-### Content Quality
-- [ ] 每个 Decision block 包含 Decision/Rationale/Alternatives 三部分
-- [ ] Rationale 至少 2 条理由（不能是单行敷衍）
-- [ ] Alternatives 至少 1 个具体方案（不能是 "无" 或 "未评估"）
-- [ ] 无 TODO 标记
-- [ ] 无 {{PLACEHOLDER}} 占位符
-- [ ] 无 FIXME/XXX 标记
-
-### Constitution Compliance
-- [ ] Article X.1: 所有 NEEDS CLARIFICATION 已明确标记
-- [ ] Article X.2: 无推测性语言（"可能"/"未来"/"预留"）
-- [ ] Article I.1: 无部分实现标记（"暂时"/"临时"/"简化版"）
-
-### Source Traceability
-- [ ] 每个 Decision 有明确的 Source 字段
-- [ ] Source Library 列出所有研究材料路径
-- [ ] 研究材料文件实际存在于 research/ 目录
-
----
-
-## Usage Instructions
-
-### For AI Agents (prd-writer, planner)
-
-1. **Initialize from Template**:
-   ```bash
-   cp .claude/docs/templates/RESEARCH_TEMPLATE.md \
-      devflow/requirements/${REQ_ID}/research/research.md
-   ```
-
-2. **Fill Template Variables**:
-   - Replace `{FEATURE_NAME}` with actual feature title
-   - Replace `{GENERATED_AT}` with ISO 8601 UTC timestamp
-   - Replace all `{PLACEHOLDERS}` with actual content
-
-3. **Populate Decisions**:
-   - Read `research/tasks.json` for research task list
-   - For each task, create a Decision block
-   - Ensure Decision/Rationale/Alternatives are complete
-
-4. **Validate Before Saving**:
-   ```bash
-   bash .claude/scripts/validate-research.sh ${REQ_DIR} --strict
-   ```
-
-### For Human Developers
-
-1. **Manual Research Workflow**:
-   ```bash
-   # 1. Run flow-init (generates tasks.json)
-   /flow-init "REQ-123|Feature Name"
-
-   # 2. Research each task
-   # - Check existing codebase
-   # - Search official docs (use MCP)
-   # - Benchmark alternatives
-
-   # 3. Update tasks.json with findings
-   # - Add decision, rationale, alternatives fields
-   # - Update status to "completed"
-
-   # 4. Consolidate findings
-   bash .claude/scripts/consolidate-research.sh devflow/requirements/REQ-123
-
-   # 5. Validate
-   bash .claude/scripts/validate-research.sh devflow/requirements/REQ-123 --strict
-   ```
-
-2. **Direct Editing**:
-   - Copy this template to `research/research.md`
-   - Fill in decisions based on your research
-   - Run validation script before proceeding to /flow:spec
-
----
-
-## Example: Complete Decision Block
-
-```markdown
-### R003 — Research authentication strategy for User Management System
-- **Decision**: Auth0 with Next.js Middleware integration
-- **Rationale**:
-  - Native support for Next.js App Router middleware authentication
-  - Pre-built UI components reduce frontend development time
-  - SaaS model eliminates need for auth infrastructure maintenance
-  - Compliance certifications (SOC 2, GDPR) included in Pro plan
-- **Alternatives Considered**:
-  - Clerk: Similar features but higher pricing at scale (>10k users)
-  - NextAuth.js: Open-source but requires self-hosting and security audits
-  - AWS Cognito: Lower cost but complex integration with Next.js middleware
-  - Custom JWT: Maximum flexibility but significant security risk and dev time
-- **Source**: PRD.md:89 (User Story US-002: User Authentication)
-```
-
----
-
-## Anti-Patterns (避免这些错误)
-
-### ❌ Bad Example 1: 敷衍的 Rationale
-```markdown
-### R001 — Database choice
-- Decision: PostgreSQL
-- Rationale: 好用
-- Alternatives: MySQL
-```
-**问题**: Rationale 太简单，没有说明为什么好用。Alternatives 没有对比分析。
-
-### ❌ Bad Example 2: 包含 TODO
-```markdown
-### R001 — Database choice
-- Decision: TODO - fill decision outcome
-- Rationale: TODO - explain why
-- Alternatives: TODO - list alternatives
-```
-**问题**: 未完成的研究，validate-research.sh 会拒绝。
-
-### ❌ Bad Example 3: 推测性语言
-```markdown
-### R001 — Database choice
-- Decision: PostgreSQL
-- Rationale:
-  - 未来可能需要复杂查询
-  - 预留扩展性支持分片
-```
-**问题**: "未来可能"/"预留" 违反 Article X.2 (No Speculation)。
-
-### ✅ Good Example: 完整且符合规范
-```markdown
-### R001 — Research database choice for E-commerce Platform
-- **Decision**: PostgreSQL 15 with Prisma ORM
-- **Rationale**:
-  - PRD requires ACID transactions for order processing (US-005)
-  - Prisma provides type-safe database access aligned with TypeScript stack
-  - Team has 3 years PostgreSQL production experience (reduces onboarding time)
-  - Native JSON support needed for product catalog flexible attributes (US-012)
-- **Alternatives Considered**:
-  - MongoDB: No ACID transactions, unsuitable for financial operations
-  - MySQL: Weaker JSON support, no partial indexes (needed for US-012)
-  - Supabase: Vendor lock-in concerns, enterprise pricing unclear
-- **Source**: PRD.md:42 (User Story US-005: Order Processing)
-```
-
----
-
-## Troubleshooting
-
-### Q: consolidate-research.sh 生成的 research.md 全是 TODO，怎么办？
-
-**A**: 这说明 `research/tasks.json` 缺少 `decision/rationale/alternatives` 字段。
-
-**解决方案 1** (推荐): 手动填充 tasks.json
-```json
-{
-  "tasks": [
-    {
-      "id": "R001",
-      "prompt": "Research database choice",
-      "status": "completed",
-      "decision": "PostgreSQL 15 with Prisma ORM",
-      "rationale": "ACID compliance, type-safe access, team experience",
-      "alternatives": "MongoDB (no ACID), MySQL (weaker JSON support)",
-      "source": "PRD.md:42"
-    }
-  ]
-}
-```
-
-**解决方案 2**: 直接编辑 research.md，参考此模板格式。
-
-**解决方案 3**: 跳过 consolidate-research.sh，完全手动创建 research.md。
-
-### Q: validate-research.sh 报错 "No Decision blocks found"，但我有内容？
-
-**A**: Decision block 必须符合格式 `### R001 —` (三个 #，空格，R + 数字，空格，破折号)。
-
-**正确格式**:
-```markdown
-### R001 — Topic description
-```
-
-**错误格式**:
-```markdown
-## R001 Topic   # ❌ 两个 # 不对
-### R1 - Topic  # ❌ 破折号是 - 不是 —
-### Decision 1  # ❌ 没有 R00X 编号
-```
-
-### Q: 我的 research.md 很长，可以拆分吗？
-
-**A**: 不建议拆分。research.md 是单一真相源 (Single Source of Truth)。
-- 如果决策太多（>20 个），考虑需求是否过大，应拆分为多个 REQ-ID。
-- 详细研究材料放在 `research/internal/` 或 `research/mcp/`，research.md 只记录决策摘要。
-
----
-
-**Maintained By**: CC-DevFlow Team
-**Last Updated**: 2025-01-26
-**Related Docs**:
-- [flow-init.md](../../commands/flow-init.md) - 需求初始化流程
-- [validate-research.sh](../../scripts/validate-research.sh) - 验证脚本
-- [flow-init-optimization-plan.md](../../../flow-init-optimization-plan.md) - 优化方案

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

@@ -1,5 +0,0 @@
-{"file": "devflow/ROADMAP.md", "reason": "Project roadmap context", "optional": true}
-{"file": "devflow/ARCHITECTURE.md", "reason": "Architecture context", "optional": true}
-{"file": "devflow/requirements/{REQ}/harness-state.json", "reason": "Existing harness state", "optional": true}
-{"file": "devflow/requirements/{REQ}/context-package.md", "reason": "Existing context package", "optional": true}
-{"file": ".claude/rules/project-constitution.md", "reason": "Quality rules and constraints"}

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

@@ -1,132 +0,0 @@
----
-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