claude-code-workflow 7.2.12 → 7.2.14

package/.claude/agents/workflow-research-agent.md

@@ -0,0 +1,112 @@
+---
+name: workflow-research-agent
+description: External research agent — web search for API details, design patterns, best practices, and technology validation. Returns structured markdown, does NOT write files.
+tools: Read, WebSearch, WebFetch, Bash
+---
+
+# External Research Agent
+
+## Role
+You perform targeted external research using web search to gather API details, design patterns, architecture approaches, best practices, and technology evaluations. You synthesize findings into structured, actionable markdown for downstream analysis workflows.
+
+Spawned by: analyze-with-file (Phase 2), brainstorm-with-file, or any workflow needing external context.
+
+**CRITICAL**: Return structured markdown only. Do NOT write any files unless explicitly instructed in the prompt.
+
+## Process
+
+1. **Parse research objective** — Understand the topic, focus area, and what the caller needs
+2. **Plan queries** — Design 3-5 focused search queries targeting the objective
+3. **Execute searches** — Use `WebSearch` for general research, `WebFetch` for specific documentation pages
+4. **Cross-reference** — If codebase files are provided in prompt, `Read` them to ground research in actual code context
+5. **Synthesize findings** — Extract key insights, patterns, and recommendations from search results
+6. **Return structured output** — Markdown-formatted research findings
+
+## Research Modes
+
+### Detail Verification (default for analyze)
+Focus: verify assumptions, check best practices, validate technology choices, confirm patterns.
+Queries target: benchmarks, production postmortems, known issues, compatibility matrices, official docs.
+
+### API Research (for implementation planning)
+Focus: concrete API details, library versions, integration patterns, configuration options.
+Queries target: official documentation, API references, migration guides, changelog entries.
+
+### Design Research (for brainstorm/architecture)
+Focus: design alternatives, architecture patterns, competitive analysis, UX patterns.
+Queries target: design systems, pattern libraries, case studies, comparison articles.
+
+## Execution
+
+### Query Strategy
+```
+1. Parse topic → extract key technologies, patterns, concepts
+2. Generate 3-5 queries:
+   - Q1: "{technology} best practices {year}"
+   - Q2: "{pattern} vs {alternative} comparison"
+   - Q3: "{technology} known issues production"
+   - Q4: "{specific API/library} documentation {version}"
+   - Q5: "{domain} architecture patterns"
+3. Execute queries via WebSearch
+4. For promising results, WebFetch full content for detail extraction
+5. Synthesize across all sources
+```
+
+### Codebase Grounding
+When the prompt includes `codebase_context` (file paths, patterns, tech stack):
+- Read referenced files to understand actual usage
+- Compare external best practices against current implementation
+- Flag gaps between current code and recommended patterns
+
+## Output Format
+
+Return structured markdown (do NOT write files):
+
+```markdown
+## Research: {topic}
+
+### Key Findings
+- **{Finding 1}**: {detail} (confidence: HIGH|MEDIUM|LOW, source: {url_or_reference})
+- **{Finding 2}**: {detail} (confidence: HIGH|MEDIUM|LOW, source: {url_or_reference})
+
+### Technology / API Details
+- **{Library/API}**: version {X}, {key capabilities}
+  - Integration: {how to integrate}
+  - Caveats: {known issues or limitations}
+
+### Best Practices
+- {Practice 1}: {rationale} (source: {reference})
+- {Practice 2}: {rationale} (source: {reference})
+
+### Recommended Approach
+{Prescriptive recommendation with rationale — "use X" not "consider X or Y" when evidence is strong}
+
+### Alternatives Considered
+| Option | Pros | Cons | Verdict |
+|--------|------|------|---------|
+| {A} | ... | ... | Recommended / Viable / Avoid |
+
+### Pitfalls & Known Issues
+- {Issue 1}: {mitigation} (source: {reference})
+
+### Codebase Gaps (if codebase_context provided)
+- {Gap}: current code does {X}, best practice recommends {Y}
+
+### Sources
+- {source title}: {url} — {key takeaway}
+```
+
+## Error Handling
+- If WebSearch returns no results for a query: note "no results" and proceed with remaining queries
+- If WebFetch fails for a URL: skip and note the intended lookup
+- If all searches fail: return "research unavailable — proceed with codebase-only analysis" and list the queries that were attempted
+- If codebase files referenced in prompt don't exist: proceed with external research only
+
+## Constraints
+- Be prescriptive ("use X") not exploratory ("consider X or Y") when evidence is strong
+- Assign confidence levels (HIGH/MEDIUM/LOW) to all findings
+- Cite sources for claims — include URLs
+- Keep output under 200 lines
+- Do NOT write any files — return structured markdown only
+- Do NOT fabricate URLs or sources — only cite actual search results
+- Bash calls MUST use `run_in_background: false` (subagent cannot receive hook callbacks)

package/.claude/commands/workflow/analyze-with-file.md

@@ -10,11 +10,11 @@ allowed-tools: TodoWrite(*), Agent(*), AskUserQuestion(*), Read(*), Grep(*), Glo
 When `--yes` or `-y`: Auto-confirm exploration decisions, use recommended analysis angles.
 
 <purpose>
-Interactive collaborative analysis workflow combining codebase exploration (cli-explore-agent) with CLI-assisted analysis (Gemini/Codex). Produces a documented discussion timeline with evolving understanding, decision trails, and actionable conclusions.
+Interactive collaborative analysis workflow combining codebase exploration (cli-explore-agent), external research (workflow-research-agent), and CLI-assisted analysis (Gemini/Codex). Produces a documented discussion timeline with evolving understanding, decision trails, and actionable conclusions.
 
 Invoked when user needs deep, multi-perspective analysis of a topic or codebase question — e.g., architecture review, implementation analysis, concept exploration, or decision evaluation.
 
-Produces: `discussion.md` (evolving analysis document with TOC, rounds, narrative synthesis), `explorations.json`/`perspectives.json` (structured findings), `conclusions.json` (final synthesis with recommendations). All artifacts stored in `.workflow/.analysis/{session-id}/`.
+Produces: `discussion.md` (evolving analysis document with TOC, rounds, narrative synthesis), `explorations.json`/`perspectives.json` (structured findings), `research.json` (external research findings), `conclusions.json` (final synthesis with recommendations). All artifacts stored in `.workflow/.analysis/{session-id}/`.
 </purpose>
 
 <conventions>
@@ -72,6 +72,12 @@ All `AskUserQuestion` calls MUST comply:
 
 **Principles**: Immediacy (record as-it-happens), Completeness (context+options+chosen+reason+rejected), Traceability (later phases trace back), Depth (capture reasoning, not just outcomes)
 
+**Technical Solution Triggers** — record using Technical Solution Record Format when ANY of:
+- An implementation approach is described with specific files/patterns/code changes
+- Two or more alternatives are compared with trade-offs
+- User confirms, modifies, or rejects a proposed approach
+- A concrete code change strategy emerges (what to modify, how, why)
+
 ### Output Artifacts
 
 | Phase | Artifact | Description |
@@ -80,8 +86,9 @@ All `AskUserQuestion` calls MUST comply:
 | 1 | Session variables | Dimensions, focus areas, analysis depth |
 | 2 | `exploration-codebase.json` | Shared Layer 1 discovery (files, modules, patterns) — always created |
 | 2 | `explorations/*.json` | Per-perspective Layer 2-3 deep-dives (multi-perspective only, max 4) |
-| 2 | `explorations.json` | Single perspective aggregated findings (Layer 1 + CLI analysis) |
-| 2 | `perspectives.json` | Multi-perspective findings (Layer 1 shared + per-perspective deep-dives) with synthesis |
+| 2 | `research.json` | External research findings (best practices, API details, known issues) — from workflow-research-agent |
+| 2 | `explorations.json` | Single perspective aggregated findings (Layer 1 + CLI analysis + research) |
+| 2 | `perspectives.json` | Multi-perspective findings (Layer 1 shared + per-perspective deep-dives + research) with synthesis |
 | 2 | Updated `discussion.md` | Round 1 + Initial Intent Coverage Check + Current Understanding replaced |
 | 3 | Updated `discussion.md` | Round 2-N: feedback, insights, narrative synthesis; TOC + Current Understanding updated each round |
 | 4 | `conclusions.json` | Final synthesis with recommendations (incl. steps[] + review_status) |
@@ -177,6 +184,52 @@ Schema: {relevant_files: [{path, annotation, dimensions[]}], patterns[], module_
 })
 ```
 
+**Phase A2 — External Research** (parallel with Phase A, runs when topic involves technologies/patterns/APIs):
+
+Determine if external research would add value — skip for purely internal codebase questions (e.g., "how does module X work"), run for topics involving technology choices, best practices, architecture patterns, API usage, or comparison with industry standards.
+
+```javascript
+// External research — runs in PARALLEL with Phase A codebase exploration
+// Skip if topic is purely internal codebase navigation
+const needsResearch = dimensions.some(d =>
+  ['architecture', 'comparison', 'decision', 'performance', 'security'].includes(d)
+) || topic_or_question.match(/best practice|pattern|vs|compare|approach|standard|library|framework/i)
+
+if (needsResearch) {
+  Agent({
+    subagent_type: "workflow-research-agent",
+    run_in_background: false,
+    description: `Research: ${topicSlug}`,
+    prompt: `
+## Research Objective
+Topic: ${topic_or_question}
+Mode: detail-verification
+Dimensions: ${dimensions.join(', ')}
+
+## Focus
+${dimensions.includes('architecture') ? '- Architecture patterns and best practices for this domain' : ''}
+${dimensions.includes('performance') ? '- Performance benchmarks and optimization patterns' : ''}
+${dimensions.includes('security') ? '- Security best practices and known vulnerabilities' : ''}
+${dimensions.includes('comparison') ? '- Technology comparison and trade-off analysis' : ''}
+${dimensions.includes('decision') ? '- Decision frameworks and industry recommendations' : ''}
+- Verify assumptions about technologies/patterns involved
+- Known issues and pitfalls in this area
+- Recommended approaches with evidence
+
+## Codebase Context (from Phase A if available)
+Tech stack: ${techStack || 'detect from project files'}
+Key patterns observed: ${sharedDiscovery?.patterns?.join(', ') || 'pending Phase A results'}
+
+## Output
+Return structured markdown per your output format.
+Do NOT write files.
+`
+  })
+  // Parse research agent output → save to ${sessionFolder}/research.json
+  // Schema: {topic, mode, findings[], best_practices[], alternatives[], pitfalls[], sources[], _metadata}
+}
+```
+
 **Phase B — Perspective Deep-Dive** (parallel, only for multi-perspective, max 4):
 Each perspective agent receives shared Layer 1 results, performs only Layer 2-3 on its relevant subset.
 Skip if single-perspective (single mode proceeds directly to Step 2 CLI analysis with Layer 1 results).
@@ -262,9 +315,12 @@ CONSTRAINTS: Focus on ${dimensions.join(', ')} | Do NOT re-discover files — us
 ```
 
 **Step 3: Aggregate Findings**
-- Consolidate explorations + CLI results
+- Consolidate explorations + CLI results + research findings (if research.json exists)
+- Merge research best_practices[] and pitfalls[] into discussion points
+- Cross-reference: flag gaps where codebase patterns diverge from research best practices
 - Multi: Extract synthesis (convergent themes, conflicting views, unique contributions)
 - Write to `explorations.json` (single) or `perspectives.json` (multi)
+- If research.json exists, add `external_research` section to explorations/perspectives with: key findings, best practices, codebase gaps
 
 **Step 4: Update discussion.md** — Append Round 1 with sources, key findings, discussion points, open questions
 
@@ -275,24 +331,7 @@ CONSTRAINTS: Focus on ${dimensions.join(', ')} | Do NOT re-discover files — us
 - Present to user at beginning of Phase 3: "初始探索完成后，以下意图的覆盖情况：[list]。接下来的讨论将重点关注未覆盖的部分。"
 - Purpose: Early course correction — catch drift before spending multiple interactive rounds
 
-**exploration-codebase.json Schema** (shared Layer 1):
-- `session_id`, `timestamp`, `topic`, `dimensions[]`
-- `relevant_files[]`: {path, annotation, dimensions[]}
-- `patterns[]`, `module_map`: {}
-- `questions_for_user[]`, `_metadata`
-
-**explorations.json Schema** (single — Layer 1 + CLI analysis merged):
-- `session_id`, `timestamp`, `topic`, `dimensions[]`
-- `sources[]`: {type, file/summary}
-- `key_findings[]`, `code_anchors[]`: {file, lines, snippet, significance}
-- `call_chains[]`: {entry, chain, files}
-- `discussion_points[]`, `open_questions[]`
-- `technical_solutions[]`: {round, solution, problem, rationale, alternatives, status: proposed|validated|rejected, evidence_refs[], next_action}
-
-**perspectives.json Schema** (multi — Layer 1 shared + per-perspective Layer 2-3):
-- `shared_discovery`: {relevant_files[], patterns[], module_map}
-- `perspectives[]`: [{name, tool, findings, insights, questions, code_anchors[], call_chains[]}]
-- `synthesis`: {convergent_themes, conflicting_views, unique_contributions}
+> All JSON schemas consolidated in `<schemas>` section below.
 
 | Condition | Action |
 |-----------|--------|
@@ -334,28 +373,36 @@ const priorContext = `
 
 3. **Gather Feedback** (AskUserQuestion, single-select, header: "分析反馈"):
    - **继续深入**: Direction correct — deepen automatically or user specifies direction (combines agree+deepen and agree+suggest)
+   - **外部研究**: Need external research on specific technology/pattern/best practice (spawns workflow-research-agent)
    - **调整方向**: Different focus or specific questions to address
-   - **补充信息**: User has additional context, constraints, or corrections to provide
    - **分析完成**: Sufficient -> exit to Phase 4
 
 4. **Process Response** (always record user choice + impact to discussion.md):
 
+   **Record-Before-Continue Rule**: Each path below MUST write findings and discussion synthesis to `discussion.md` BEFORE proceeding to Step 5. Specifically, after agent/CLI returns results:
+   - Append the exploration results, reasoning, and any technical approaches discussed to the current round section
+   - Apply **Technical Solution Triggers** (see Decision Recording Protocol) — if triggered, record using Technical Solution Record Format
+   - Only THEN proceed to Step 5 for Current Understanding replacement and TOC update
+
    **继续深入** -> Sub-question to choose direction (AskUserQuestion, single-select, header: "深入方向"):
    - Dynamically generate **max 3** context-driven options from: unresolved questions, low-confidence findings, unexplored dimensions, user-highlighted areas
    - Add **1** heuristic option that breaks current frame (e.g., "compare with best practices", "review from security perspective", "explore simpler alternatives")
    - Total: **max 4 options**. Each specifies: label, description, tool (cli-explore-agent for code-level / Gemini CLI for pattern-level), scope
    - **"Other" is auto-provided** by AskUserQuestion — covers user-specified custom direction (no need for separate "suggest next step" option)
-   - Execute selected direction -> merge new code_anchors/call_chains -> record confirmed assumptions + deepen angle
+   - Execute selected direction -> merge new code_anchors/call_chains into explorations.json -> **write exploration results, analysis reasoning, and any proposed approaches to discussion.md** -> record confirmed assumptions + deepen angle
 
-   **调整方向** -> AskUserQuestion (header: "新方向", user selects or provides custom via "Other") -> new CLI exploration -> Record Decision (old vs new direction, reason, impact)
+   **外部研究** -> Spawn workflow-research-agent for targeted research:
+   - AskUserQuestion (header: "研究主题", freetext via "Other"): What specific technology/pattern/approach needs external research?
+   - Spawn research agent with topic + current codebase context (from explorations.json)
+   - Merge research findings into explorations.json `external_research` section
+   - Update research.json with new findings (append, don't overwrite)
+   - Record research findings as Key Findings in discussion.md
 
-   **补充信息** -> Capture user input, integrate into context, answer questions via CLI/analysis if needed -> Record corrections/additions + updated understanding
+   **调整方向** -> AskUserQuestion (header: "新方向", user selects or provides custom via "Other") -> new CLI exploration -> Record Decision (old vs new direction, reason, impact)
 
    **分析完成** -> Exit loop -> Record why concluding
 
-5. **Update discussion.md**:
-   - **Append** Round N: user input, direction adjustment, Q&A, corrections, new insights
-   - **Append Technical Solutions** — for every solution proposed, validated, or rejected this round, record immediately using Technical Solution Record Format in `#### Technical Solutions`
+5. **Update discussion.md** (after Record-Before-Continue writes are done):
    - **Replace** `## Current Understanding` block with latest consolidated understanding (follow Consolidation Rules)
    - **Update** `## Table of Contents` with links to new Round N sections
 
@@ -554,7 +601,45 @@ ${implScope.map((item, i) => `${i+1}. **${item.objective}** [${item.priority}]
 
    **TodoWrite**: Update `next-step` -> `"completed"` after user selection is handled
 
-**conclusions.json Schema**:
+> conclusions.json schema: see `<schemas>` section below.
+</step>
+
+</process>
+
+<schemas>
+
+**exploration-codebase.json** (shared Layer 1):
+- `session_id`, `timestamp`, `topic`, `dimensions[]`
+- `relevant_files[]`: {path, annotation, dimensions[]}
+- `patterns[]`, `module_map`: {}
+- `questions_for_user[]`, `_metadata`
+
+**research.json** (external research findings):
+- `topic`, `mode` (detail-verification|api-research|design-research), `timestamp`
+- `findings[]`: {finding, detail, confidence, source_url}
+- `best_practices[]`: {practice, rationale, source}
+- `alternatives[]`: {option, pros, cons, verdict}
+- `pitfalls[]`: {issue, mitigation, source}
+- `codebase_gaps[]`: {gap, current_approach, recommended_approach}
+- `sources[]`: {title, url, key_takeaway}
+- `_metadata`: {queries_executed, results_found}
+
+**explorations.json** (single — Layer 1 + CLI analysis + research merged):
+- `session_id`, `timestamp`, `topic`, `dimensions[]`
+- `sources[]`: {type, file/summary}
+- `key_findings[]`, `code_anchors[]`: {file, lines, snippet, significance}
+- `call_chains[]`: {entry, chain, files}
+- `discussion_points[]`, `open_questions[]`
+- `technical_solutions[]`: {round, solution, problem, rationale, alternatives, status: proposed|validated|rejected, evidence_refs[], next_action}
+- `external_research`: {findings[], best_practices[], codebase_gaps[], sources[]} — merged from research.json if available
+
+**perspectives.json** (multi — Layer 1 shared + per-perspective Layer 2-3 + research):
+- `shared_discovery`: {relevant_files[], patterns[], module_map}
+- `perspectives[]`: [{name, tool, findings, insights, questions, code_anchors[], call_chains[]}]
+- `external_research`: {findings[], best_practices[], codebase_gaps[], sources[]} — merged from research.json if available
+- `synthesis`: {convergent_themes, conflicting_views, unique_contributions}
+
+**conclusions.json**:
 - `session_id`, `topic`, `completed`, `total_rounds`, `summary`
 - `key_conclusions[]`: {point, evidence, confidence, code_anchor_refs[]}
 - `code_anchors[]`: {file, lines, snippet, significance}
@@ -564,9 +649,8 @@ ${implScope.map((item, i) => `${i+1}. **${item.objective}** [${item.priority}]
 - `decision_trail[]`: {round, decision, context, options_considered, chosen, rejected_reasons, reason, impact}
 - `narrative_trail[]`: {round, starting_point, key_progress, hypothesis_impact, updated_understanding, remaining_questions}
 - `intent_coverage[]`: {intent, status, where_addressed, notes}
-</step>
 
-</process>
+</schemas>
 
 <error_codes>
 
@@ -579,6 +663,8 @@ ${implScope.map((item, i) => `${i+1}. **${item.objective}** [${item.priority}]
 | E005 | error | No relevant findings from exploration — broaden search, ask user for clarification | cli_exploration |
 | E006 | warning | Session folder conflict — append timestamp suffix | session_init |
 | E007 | error | Gemini unavailable — fallback to Codex or manual analysis | cli_exploration |
+| E008 | warning | Research agent WebSearch failed — continue with codebase-only analysis, note limitation | cli_exploration |
+| E009 | warning | Research findings conflict with codebase patterns — flag as codebase_gaps for user review | cli_exploration |
 
 </error_codes>
 
@@ -588,6 +674,8 @@ ${implScope.map((item, i) => `${i+1}. **${item.objective}** [${item.priority}]
 - [ ] Dimensions identified and user preferences captured (Phase 1)
 - [ ] discussion.md initialized with TOC, Current Understanding, metadata
 - [ ] Codebase exploration completed with code_anchors and call_chains (Phase 2)
+- [ ] External research executed if topic warrants it (architecture/comparison/decision/performance/security dimensions)
+- [ ] Research findings merged into explorations/perspectives with codebase_gaps flagged
 - [ ] CLI analysis executed and findings aggregated
 - [ ] Initial Intent Coverage Check appended to discussion.md
 - [ ] Interactive discussion rounds documented with narrative synthesis (Phase 3)
@@ -650,9 +738,6 @@ Present 2-3 top directions per dimension, allow multi-select + custom.
 | Preserve key learnings | Keep insights valuable for future reference |
 
 </configuration>
-
-> **Lite-plan handoff**: Phase 4「执行任务」builds structured `handoff-spec` JSON (implementation_scope with acceptance_criteria, code_anchors, key_findings) embedded in `## Prior Analysis` block. lite-plan parses `json:handoff-spec` to directly map scope items → tasks, skipping exploration and using acceptance_criteria as convergence.criteria.
-
 ---
 
 **Now execute analyze-with-file for**: $ARGUMENTS

package/.claude/skills/workflow-lite-plan/SKILL.md

@@ -340,9 +340,6 @@ Generate implementation plan and write plan.json.
 - ${sessionFolder}/plan.json (plan overview — NO embedded tasks[])
 - ${sessionFolder}/.task/TASK-*.json (independent task files, one per task)
 
-## Schema Reference
-Execute: cat ~/.ccw/workflows/cli-templates/schemas/plan-overview-base-schema.json
-
 ## Project Context (MANDATORY)
 Execute: ccw spec load --category planning
 **CRITICAL**: All generated tasks MUST comply with constraints in specs/*.md
@@ -392,7 +389,6 @@ ${complexity}
 ## Requirements
 - _metadata.exploration_angles: ${JSON.stringify(manifest.explorations.map(e => e.angle))}
 - Two-layer output: plan.json (task_ids[], NO tasks[]) + .task/TASK-*.json
-- Follow plan-overview-base-schema.json for plan.json, task-schema.json for .task/*.json
 - Field names: files[].change (not modification_points), convergence.criteria (not acceptance)
 
 ## Task Grouping Rules
@@ -405,9 +401,9 @@ ${complexity}
 7. **Prefer parallel**: Most tasks should be independent
 
 ## Execution
-1. Read schema → 2. ccw spec load → 3. Read ALL exploration files → 4. Synthesize + generate
-5. Write: planning-context.md, .task/TASK-*.json, plan.json (task_ids[], NO tasks[])
-6. Return brief completion summary
+1. ccw spec load → 2. Read ALL exploration files → 3. Synthesize + generate
+4. Write: planning-context.md, .task/TASK-*.json, plan.json (task_ids[], NO tasks[])
+5. Return brief completion summary
 `
 )
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-workflow",
-  "version": "7.2.12",
+  "version": "7.2.14",
   "description": "JSON-driven multi-agent development framework with intelligent CLI orchestration (Gemini/Qwen/Codex), context-first architecture, and automated workflow execution",
   "type": "module",
   "main": "ccw/dist/index.js",