cc-devflow 2.4.3 → 2.4.6

package/.claude/CLAUDE.md

@@ -10,6 +10,7 @@ This directory contains Claude Code CLI extensions for the CC-DevFlow developmen
 ├── agents/                    # Agent instruction files (research-type, invoked by commands)
 │   ├── checklist-agent.md     # Checklist generation logic [NEW: REQ-002]
 │   ├── clarify-analyst.md     # Requirements clarification
+│   ├── flow-researcher.md     # /flow-init mandatory research runner (subagent; file-based memory)
 │   ├── prd-writer.md          # PRD generation
 │   ├── tech-architect.md      # Technical design
 │   ├── planner.md             # EPIC/TASKS planning
@@ -19,7 +20,7 @@ This directory contains Claude Code CLI extensions for the CC-DevFlow developmen
 │
 ├── commands/                  # Slash command definitions
 │   ├── flow-checklist.md      # /flow-checklist command [NEW: REQ-002]
-│   ├── flow-init.md           # /flow-init (modified: Git Branch Creation moved to Stage 1.2)
+│   ├── flow-init.md           # /flow-init (modified: research delegated to flow-researcher subagent)
 │   ├── flow-clarify.md        # /flow-clarify
 │   ├── flow-prd.md            # /flow-prd
 │   ├── flow-tech.md           # /flow-tech
@@ -132,7 +133,7 @@ Combine Ralph-Wiggum's autonomous iteration loop with Manus-style Planning-with-
 
 **Modified Files**:
 - `commands/flow-dev.md` - Merged Ralph Loop (Autonomous by default)
-- `commands/flow-init.md` - Added Manus method in Stage 2.5 Research
+- `commands/flow-init.md` - Research made mandatory via `flow-researcher` subagent (context-isolated)
 - `skills/cc-devflow-orchestrator/SKILL.md` - Updated routing for autonomous flow
 
 ### Attention Refresh Protocols

package/.claude/agents/bug-analyzer.md

@@ -25,7 +25,6 @@ You MUST follow these rules during BUG analysis:
 2. **Agent Coordination**:
    - Update status in orchestration_status.json when analysis begins and completes
    - Implement proper error handling for unclear BUG symptoms
-   - Create analysis completion markers (.completed files)
    - Avoid file locks (read-only agent - only generate documents)
 
 3. **DateTime Handling**:

package/.claude/agents/compatibility-checker.md

@@ -25,7 +25,6 @@ You MUST follow these rules during compatibility analysis:
 
 2. **Agent Coordination**:
    - Update orchestration_status.json when analysis begins/completes
-   - Create completion markers (.completed files) after successful analysis
    - Coordinate with impact-analyzer for change assessment
    - Research-only agent: no file modifications, only document generation
 

package/.claude/agents/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/agents/impact-analyzer.md

@@ -24,7 +24,6 @@ You MUST follow these rules during impact analysis:
 
 2. **Agent Coordination**:
    - Update orchestration_status.json when analysis begins/completes
-   - Create completion markers (.completed files) after analysis
    - Research-only agent: no code modifications, only analysis documents
    - Coordinate with compatibility-checker for version management
 

package/.claude/commands/flow-fix.md

@@ -157,7 +157,7 @@ Step 4: 逆向追踪数据流
 3. 每个任务完成后:
    → 运行 quickstart 中相关测试命令
    → Git 提交 (一任务一提交)
-   → 更新 tasks/TASK_*.completed
+   → 更新 TASKS.md (checkbox 标记)
 
 4. 3+ 次修复失败 → STOP
    → 停下来，质疑架构

package/.claude/commands/flow-init.md

@@ -219,85 +219,53 @@ Red Flags - STOP:
 
 ---
 
-### Stage 2.5: Research (MCP Mandatory Flow)
+### Stage 2.5: Research (Subagent Mandatory)
 
-**目标**: 收集"真实材料"，所有步骤 **MANDATORY**
+**目标**: 研究默认必跑，但将“研究型内容”隔离到 subagent，避免主会话上下文耗尽。
 
-**Manus 研究方法** (Planning-with-files 融合):
+**Iron Law**: 大内容落盘，主会话只返回「决策摘要 + 文件路径」。
 
-```yaml
-原则 1: 大内容存文件
-  → 抓取的文档存 research/mcp/$(date +%Y%m%d)/
-  → 上下文只保留路径引用
-  → 避免塞满上下文窗口
-
-原则 2: 决策前读取
-  → 每次做研究决策前，先读 research/research.md Decisions 章节
-  → 确保不重复已有决策
-  → 注意力刷新，目标回到窗口
-
-原则 3: 失败尝试记录
-  → 研究中放弃的方案写入 research/attempts/
-  → 说明放弃原因和学习（见 ATTEMPT_TEMPLATE 格式）
-  → 失败是学习数据，不要隐藏
-
-原则 4: 增量追加
-  → 使用 append 而非 rewrite
-  → 保持研究历史完整
-  → 避免覆盖已有信息
-```
-
-```
-S0: Internal Codebase Research (必需)
-→ 分析现有代码库，生成 research/internal/codebase-overview.md
+#### ✅ Mandatory: Call `flow-researcher` Subagent
 
-Task 1-5: External Learning Materials (MCP)
-1. Official Documentation (Context7)
-2. Domain Tutorials (Web Search)
-3. Core Materials (WebFetch)
-4. Case Studies/Examples (Web Search + WebFetch)
-5. Summary & Recommendations
+> subagent 负责内部/外部研究、落盘、任务回填、研究整合与质量验证；主 agent 只做编排与最终 Gate。
 
-→ 详见 {TEMPLATE:flow} Stage 2.5
+```
+Task tool call:
+  description: "Run mandatory research for /flow-init (file-based memory)"
+  subagent_type: "flow-researcher"
+  model: "inherit"
+  prompt: (JSON)
+    {
+      "reqId": "${REQ_ID}",
+      "reqDir": "devflow/requirements/${REQ_ID}",
+      "title": "${TITLE}",
+      "planUrls": ["..."],
+      "contextFiles": {
+        "brainstorm": "devflow/requirements/${REQ_ID}/BRAINSTORM.md",
+        "roadmap": "devflow/ROADMAP.md",
+        "architecture": "devflow/ARCHITECTURE.md"
+      }
+    }
 ```
 
-**输出**:
-- `research/internal/codebase-overview.md`
-- `research/mcp/$(date +%Y%m%d)/official/*`
-- `research/mcp/$(date +%Y%m%d)/guides/*`
-- `research/mcp/$(date +%Y%m%d)/tutorials/*`
-- `research/mcp/$(date +%Y%m%d)/examples/*`
-- `research/research-summary.md`
+**期望输出** (由 subagent 写入):
+- `devflow/requirements/${REQ_ID}/research/internal/codebase-overview.md`
+- `devflow/requirements/${REQ_ID}/research/mcp/$(date +%Y%m%d)/**`
+- `devflow/requirements/${REQ_ID}/research/research-summary.md`
+- `devflow/requirements/${REQ_ID}/research/tasks.json` (decision/rationale/alternatives 完整)
+- `devflow/requirements/${REQ_ID}/research/research.md` (可通过 validate-research)
 
 ---
 
 ### Stage 2.6: Research Consolidation
 
-```
-研究决策整合:
-1. Generate research tasks
-   → Run: {SCRIPT:research_tasks} "${REQ_DIR}"
-   → Output: research/tasks.json
-
-2. Populate task decisions
-   → Run: {SCRIPT:populate_tasks} "${REQ_DIR}"
-   → Fill decision/rationale/alternatives from research
-
-3. Consolidate research
-   → Run: {SCRIPT:consolidate} "${REQ_DIR}"
-   → Output: research/research.md
-   → Format: Decision/Rationale/Alternatives/Source
+> 该阶段由 `flow-researcher` subagent 执行（包含 tasks 生成/回填/整合/校验）。
 
-4. Update status
-   → orchestration_status.json.phase0_complete = true
-
-→ 详见 {TEMPLATE:flow} Stage 2.6
-```
+主 agent 在 Exit Gate 中只做最终验证与状态更新：
+- Run: `{SCRIPT:validate_research} "${REQ_DIR}" --strict`
+- `orchestration_status.json.phase0_complete = true`
 
 ---
-
-
-
 ### Stage 3: README Generation
 
 ```
@@ -317,7 +285,7 @@ Level 1: File Existence Check
 → 验证所有必需文件已创建
 
 Level 2: Research.md Structure Validation
-→ Run: {SCRIPT:validate_research} "${REQ_DIR}"
+→ Run: {SCRIPT:validate_research} "${REQ_DIR}" --strict
 → 检查 research.md 结构
 
 Level 3: Research.md Content Quality

package/.claude/commands/flow-new.md

@@ -239,7 +239,7 @@ $ARGUMENTS = "REQ_ID|TITLE|PLAN_URLS?"
 **输出**:
 - 实现代码
 - 测试代码
-- tasks/*.completed 标记
+- TASKS.md 更新 (checkbox 标记)
 - Git commits (每个任务一个)
 
 ---
@@ -349,8 +349,7 @@ devflow/requirements/${REQ_ID}/
 ├── contracts/openapi.yaml
 ├── quickstart.md
 ├── EPIC.md
-├── TASKS.md (bite-sized)
-├── tasks/*.completed
+├── TASKS.md (bite-sized, checkbox 标记)
 ├── SPEC_REVIEW.md ⭐ v2.1.0 新增
 ├── CODE_QUALITY_REVIEW.md ⭐ v2.1.0 新增
 ├── TEST_PLAN.md + TEST_REPORT.md