From 76967a735047fc9b3239d430d352ffbc0bf80cdc Mon Sep 17 00:00:00 2001 From: catlog22 Date: Sun, 1 Feb 2026 22:51:04 +0800 Subject: [PATCH] feat: enhance workflow commands with dynamic analysis, multi-agent parallel exploration, and best practices - analyze-with-file: Add dynamic direction generation from dimensions, support up to 4 parallel agent perspectives, enable cli-explore-agent parallelization - brainstorm-with-file: Add dynamic direction generation from dimensions, add Agent-First guideline for complex tasks - collaborative-plan-with-file: Add Understanding phase guidelines to prioritize latest documentation and resolve ambiguities with user clarification Key improvements: - Dimension-Direction Mapping replaces hard-coded options, enabling task-aware direction recommendations - Multi-perspective parallel exploration (Analysis Perspectives, up to 4) with synthesis - cli-explore-agent supports parallel execution per perspective for richer codebase context - Agent-First principle: delegate complex tasks (code analysis, implementation) to agents/CLI instead of main process analysis - Understanding phase emphasizes latest documentation discovery and clarification of ambiguities before planning --- .../commands/workflow/analyze-with-file.md | 210 +++++++++++++----- .../commands/workflow/brainstorm-with-file.md | 13 +- .../workflow/collaborative-plan-with-file.md | 31 ++- 3 files changed, 184 insertions(+), 70 deletions(-) diff --git a/.claude/commands/workflow/analyze-with-file.md b/.claude/commands/workflow/analyze-with-file.md index 2ac3292a..c690177b 100644 --- a/.claude/commands/workflow/analyze-with-file.md +++ b/.claude/commands/workflow/analyze-with-file.md @@ -39,8 +39,10 @@ When `--yes` or `-y`: Auto-confirm exploration decisions, use recommended analys | Artifact | Description | |----------|-------------| -| `exploration-codebase.json` | Codebase context from cli-explore-agent | -| `explorations.json` | Aggregated CLI findings (Gemini/Codex) | +| `exploration-codebase.json` | Single codebase context from cli-explore-agent | +| `explorations/*.json` | Multi-perspective codebase explorations (parallel, up to 4) | +| `explorations.json` | Single perspective aggregated findings | +| `perspectives.json` | Multi-perspective findings (up to 4 perspectives) with synthesis | | Updated `discussion.md` | Round 1 with exploration results | ### Phase 3: Interactive Discussion @@ -75,8 +77,10 @@ Interactive collaborative analysis workflow with **documented discussion process │ └─ Initialize discussion.md │ │ │ │ Phase 2: CLI Exploration │ -│ ├─ cli-explore-agent: Codebase context (FIRST) │ -│ ├─ Gemini/Codex: Deep analysis (AFTER exploration) │ +│ ├─ Codebase Exploration (cli-explore-agent, supports parallel ≤4) │ +│ ├─ Multi-Perspective Analysis (AFTER exploration) │ +│ │ ├─ Single: Comprehensive analysis │ +│ │ └─ Multi (≤4): Parallel perspectives with synthesis │ │ ├─ Aggregate findings │ │ └─ Update discussion.md with Round 1 │ │ │ @@ -102,8 +106,12 @@ Interactive collaborative analysis workflow with **documented discussion process ``` .workflow/.analysis/ANL-{slug}-{date}/ ├── discussion.md # ⭐ Evolution of understanding & discussions -├── exploration-codebase.json # Phase 2: Codebase context -├── explorations.json # Phase 2: Aggregated CLI findings +├── exploration-codebase.json # Phase 2: Single codebase context +├── explorations/ # Phase 2: Multi-perspective codebase explorations (if selected) +│ ├── technical.json +│ └── architectural.json +├── explorations.json # Phase 2: Single perspective findings +├── perspectives.json # Phase 2: Multi-perspective findings (if selected) └── conclusions.json # Phase 4: Final synthesis ``` @@ -147,7 +155,8 @@ Interactive collaborative analysis workflow with **documented discussion process - Default to "general" if no match 2. **Initial Scoping** (if new session + not auto mode) - - **Focus**: Multi-select from code implementation, architecture design, best practices, problem diagnosis + - **Focus**: Multi-select from directions generated by detected dimensions (see Dimension-Direction Mapping) + - **Perspectives**: Multi-select up to 4 analysis perspectives (see Analysis Perspectives), default: single comprehensive view - **Depth**: Single-select from Quick Overview (10-15min) / Standard Analysis (30-60min) / Deep Dive (1-2hr) 3. **Initialize discussion.md** @@ -170,23 +179,18 @@ Interactive collaborative analysis workflow with **documented discussion process - discussion.md initialized - Dimensions identified -**Workflow Steps**: +**Workflow Steps** (⚠️ Codebase exploration FIRST): -1. **Primary Codebase Exploration via cli-explore-agent** (⚠️ FIRST) +1. **Codebase Exploration via cli-explore-agent** (supports parallel up to 4) - Agent type: `cli-explore-agent` - - Execution mode: synchronous (run_in_background: false) - - **Tasks**: - - Run: `ccw tool exec get_modules_by_depth '{}'` - - Execute searches based on topic keywords - - Read: `.workflow/project-tech.json` if exists - - **Output**: `{sessionFolder}/exploration-codebase.json` - - relevant_files: [{path, relevance, rationale}] - - patterns: [] - - key_findings: [] - - questions_for_user: [] - - **Purpose**: Enrich CLI prompts with codebase context + - Execution mode: parallel if multi-perspective selected, otherwise single (run_in_background: false for sequential, true for parallel) + - **Single exploration**: General codebase analysis + - **Multi-perspective**: Parallel explorations per perspective focus (max 4, each with specific angle) + - **Common tasks**: Run `ccw tool exec get_modules_by_depth '{}'`, execute searches based on topic keywords, read `.workflow/project-tech.json` + - **Output**: `{sessionFolder}/exploration-codebase.json` (single) or `{sessionFolder}/explorations/{perspective}.json` (multi) + - **Purpose**: Enrich CLI prompts with codebase context for each perspective -**Agent Call Example**: +**Single Exploration Example**: ```javascript Task({ subagent_type: "cli-explore-agent", @@ -209,25 +213,50 @@ ${dimensions.map(d => `- ${d}: Identify relevant code patterns and structures`). ## Output Write findings to: ${sessionFolder}/exploration-codebase.json -Schema: -{ - "relevant_files": [{"path": "...", "relevance": "high|medium|low", "rationale": "..."}], - "patterns": [], - "key_findings": [], - "questions_for_user": [], - "_metadata": { "exploration_type": "codebase", "timestamp": "..." } -} +Schema: {relevant_files, patterns, key_findings, questions_for_user, _metadata} ` }) ``` -2. **CLI Deep Analysis** (⚠️ AFTER exploration) - - Launch Gemini CLI with analysis mode - - **Shared context**: Include exploration-codebase.json findings in prompt - - **Execution**: Bash with run_in_background: true, wait for results - - **Output**: Analysis findings with insights and discussion points +**Multi-Perspective Parallel Example** (up to 4 agents): +```javascript +// Launch parallel explorations for each selected perspective +selectedPerspectives.forEach(perspective => { + Task({ + subagent_type: "cli-explore-agent", + run_in_background: false, // Sequential execution, wait for each + description: `Explore ${perspective.name}: ${topicSlug}`, + prompt: ` +## Analysis Context +Topic: ${topic_or_question} +Perspective: ${perspective.name} - ${perspective.focus} +Session: ${sessionFolder} -**CLI Call Example**: +## MANDATORY FIRST STEPS +1. Run: ccw tool exec get_modules_by_depth '{}' +2. Execute searches focused on ${perspective.focus} +3. Read: .workflow/project-tech.json (if exists) + +## Exploration Focus (${perspective.name} angle) +${perspective.exploration_tasks.map(t => `- ${t}`).join('\n')} + +## Output +Write findings to: ${sessionFolder}/explorations/${perspective.name}.json + +Schema: {relevant_files, patterns, key_findings, perspective_insights, _metadata} +` + }) +}) +``` + +2. **Multi-Perspective CLI Analysis** (⚠️ AFTER exploration) + - If user selected multiple perspectives (≤4): Launch CLI calls in parallel + - If single/default perspective: Launch single comprehensive CLI analysis + - **Shared context**: Include exploration-codebase.json findings in all prompts + - **Execution**: Bash with run_in_background: true, wait for all results + - **Output**: perspectives.json with analysis from each perspective + +**Single Perspective Example**: ```javascript Bash({ command: `ccw cli -p " @@ -246,33 +275,59 @@ TASK: • Generate discussion points for user clarification MODE: analysis - CONTEXT: @**/* | Topic: ${topic_or_question} - -EXPECTED: -- Structured analysis with clear sections -- Specific insights tied to evidence -- Questions to deepen understanding -- Recommendations with rationale - +EXPECTED: Structured analysis with clear sections, specific insights tied to evidence, questions to deepen understanding, recommendations with rationale CONSTRAINTS: Focus on ${dimensions.join(', ')} " --tool gemini --mode analysis`, run_in_background: true }) +``` -// ⚠️ STOP POINT: Wait for hook callback to receive results before continuing +**Multi-Perspective Example** (parallel, up to 4): +```javascript +// Build shared context once +const explorationContext = ` +PRIOR EXPLORATION CONTEXT: +- Key files: ${explorationResults.relevant_files.slice(0,5).map(f => f.path).join(', ')} +- Patterns found: ${explorationResults.patterns.slice(0,3).join(', ')} +- Key findings: ${explorationResults.key_findings.slice(0,3).join(', ')}` + +// Launch parallel CLI calls based on selected perspectives (max 4) +selectedPerspectives.forEach(perspective => { + Bash({ + command: `ccw cli -p " +PURPOSE: ${perspective.purpose} for '${topic_or_question}' +Success: ${perspective.success_criteria} + +${explorationContext} + +TASK: +${perspective.tasks.map(t => `• ${t}`).join('\n')} + +MODE: analysis +CONTEXT: @**/* | Topic: ${topic_or_question} +EXPECTED: ${perspective.expected_output} +CONSTRAINTS: ${perspective.constraints} +" --tool ${perspective.tool} --mode analysis`, + run_in_background: true + }) +}) + +// ⚠️ STOP POINT: Wait for hook callback to receive all results before continuing ``` 3. **Aggregate Findings** - - Consolidate codebase and CLI findings - - Extract key findings, discussion points, open questions - - Write to explorations.json + - Consolidate all codebase explorations (exploration-codebase.json or explorations/*.json) and CLI perspective findings + - If multi-perspective: Extract synthesis from both explorations and analyses (convergent themes, conflicting views, unique contributions) + - Extract aggregated findings, discussion points, open questions across all sources + - Write to explorations.json (single) or perspectives.json (multi) 4. **Update discussion.md** - Append Round 1 section with exploration results - - Include sources analyzed, key findings, discussion points, open questions + - Single perspective: Include sources analyzed, key findings, discussion points, open questions + - Multi-perspective: Include per-perspective findings + synthesis section -**explorations.json Schema**: +**explorations.json Schema** (single perspective): - `session_id`: Session identifier - `timestamp`: Exploration completion time - `topic`: Original topic/question @@ -282,11 +337,22 @@ CONSTRAINTS: Focus on ${dimensions.join(', ')} - `discussion_points[]`: Questions for user - `open_questions[]`: Unresolved questions +**perspectives.json Schema** (multi-perspective): +- `session_id`: Session identifier +- `timestamp`: Exploration completion time +- `topic`: Original topic/question +- `dimensions[]`: Analysis dimensions +- `perspectives[]`: [{name, tool, findings, insights, questions}] +- `synthesis`: {convergent_themes, conflicting_views, unique_contributions} +- `aggregated_findings[]`: Main insights across perspectives +- `discussion_points[]`: Questions for user +- `open_questions[]`: Unresolved questions + **Success Criteria**: -- exploration-codebase.json created with codebase context -- explorations.json created with aggregated findings +- exploration-codebase.json (single) or explorations/*.json (multi) created with codebase context +- explorations.json (single) or perspectives.json (multi) created with findings - discussion.md updated with Round 1 results -- All CLI calls completed successfully +- All agents and CLI calls completed successfully ### Phase 3: Interactive Discussion @@ -297,6 +363,8 @@ CONSTRAINTS: Focus on ${dimensions.join(', ')} - explorations.json contains initial findings - discussion.md has Round 1 results +**Guideline**: For complex tasks (code analysis, implementation, refactoring), delegate to agents via Task tool (cli-explore-agent, code-developer, universal-executor) or CLI calls (ccw cli). Avoid direct analysis/execution in main process. + **Workflow Steps**: 1. **Present Findings** @@ -412,6 +480,35 @@ CONSTRAINTS: Focus on ${dimensions.join(', ')} ## Configuration +### Analysis Perspectives + +Optional multi-perspective parallel exploration (single perspective is default, max 4): + +| Perspective | Tool | Focus | Best For | +|------------|------|-------|----------| +| **Technical** | Gemini | Implementation, code patterns, technical feasibility | Understanding how and technical details | +| **Architectural** | Claude | System design, scalability, component interactions | Understanding structure and organization | +| **Business** | Codex | Value, ROI, stakeholder impact, strategy | Understanding business implications | +| **Domain Expert** | Gemini | Domain-specific patterns, best practices, standards | Industry-specific knowledge and practices | + +**Selection**: User can multi-select up to 4 perspectives in Phase 1, or default to single comprehensive view + +### Dimension-Direction Mapping + +When user selects focus areas, generate directions dynamically from detected dimensions (don't use static options): + +| Dimension | Possible Directions | +|-----------|-------------------| +| architecture | System Design, Component Interactions, Technology Choices, Integration Points, Design Patterns, Scalability Strategy | +| implementation | Code Structure, Implementation Details, Code Patterns, Error Handling, Testing Approach, Algorithm Analysis | +| performance | Performance Bottlenecks, Optimization Opportunities, Resource Utilization, Caching Strategy, Concurrency Issues | +| security | Security Vulnerabilities, Authentication/Authorization, Access Control, Data Protection, Input Validation | +| concept | Conceptual Foundation, Core Mechanisms, Fundamental Patterns, Theory & Principles, Trade-offs & Reasoning | +| comparison | Solution Comparison, Pros & Cons Analysis, Technology Evaluation, Approach Differences | +| decision | Decision Criteria, Trade-off Analysis, Risk Assessment, Impact Analysis, Implementation Implications | + +**Implementation**: Present 2-3 top dimension-related directions, allow user to multi-select and add custom directions. + ### Analysis Dimensions Dimensions matched against topic keywords to identify focus areas: @@ -476,10 +573,11 @@ In round 1 we discussed X, then in round 2 user said Y... ## Best Practices 1. **Clear Topic Definition**: Detailed topics → better dimension identification -2. **Review discussion.md**: Check understanding evolution before conclusions -3. **Embrace Corrections**: Track wrong→right transformations as learnings -4. **Document Evolution**: discussion.md captures full thinking process -5. **Use Continue Mode**: Resume sessions to build on previous analysis +2. **Agent-First for Complex Tasks**: For code analysis, implementation, or refactoring tasks during discussion, delegate to agents via Task tool (cli-explore-agent, code-developer, universal-executor) or CLI calls (ccw cli). Avoid direct analysis/execution in main process +3. **Review discussion.md**: Check understanding evolution before conclusions +4. **Embrace Corrections**: Track wrong→right transformations as learnings +5. **Document Evolution**: discussion.md captures full thinking process +6. **Use Continue Mode**: Resume sessions to build on previous analysis ## Templates diff --git a/.claude/commands/workflow/brainstorm-with-file.md b/.claude/commands/workflow/brainstorm-with-file.md index 0845d4e3..42cbb193 100644 --- a/.claude/commands/workflow/brainstorm-with-file.md +++ b/.claude/commands/workflow/brainstorm-with-file.md @@ -166,7 +166,7 @@ Interactive brainstorming workflow with **multi-CLI collaboration** and **docume - **Manual mode**: AskUserQuestion with recommended roles + "Use simple perspectives" option 3. **Initial Scoping Questions** (if new session + not auto mode) - - **Direction**: Multi-select from technical, UX, innovation, feasibility + - **Direction**: Multi-select from directions generated by detected dimensions (see Brainstorm Dimensions) - **Depth**: Single-select from quick/balanced/deep (15-20min / 30-60min / 1-2hr) - **Constraints**: Multi-select from existing architecture, time, resources, or no constraints @@ -410,6 +410,8 @@ CONSTRAINTS: Consider existing system architecture - perspectives.json contains initial ideas - brainstorm.md has Round 2 findings +**Guideline**: For complex tasks (code analysis, implementation, POC creation), delegate to agents via Task tool (cli-explore-agent, code-developer, universal-executor) or CLI calls (ccw cli). Avoid direct analysis/execution in main process. + **Workflow Steps**: 1. **Present Current State** @@ -723,10 +725,11 @@ Dimensions matched against topic keywords to identify focus areas: ## Best Practices 1. **Clear Topic Definition**: Detailed topics → better role selection and exploration -2. **Review brainstorm.md**: Check thought evolution before final decisions -3. **Embrace Conflicts**: Perspective conflicts often reveal important tradeoffs -4. **Document Evolution**: brainstorm.md captures full thinking process for team review -5. **Use Continue Mode**: Resume sessions to build on previous exploration +2. **Agent-First for Complex Tasks**: For code analysis, POC implementation, or technical validation during refinement, delegate to agents via Task tool (cli-explore-agent, code-developer, universal-executor) or CLI calls (ccw cli). Avoid direct analysis/execution in main process +3. **Review brainstorm.md**: Check thought evolution before final decisions +4. **Embrace Conflicts**: Perspective conflicts often reveal important tradeoffs +5. **Document Evolution**: brainstorm.md captures full thinking process for team review +6. **Use Continue Mode**: Resume sessions to build on previous exploration ## Templates diff --git a/.claude/commands/workflow/collaborative-plan-with-file.md b/.claude/commands/workflow/collaborative-plan-with-file.md index 9ebf6c22..03a2989b 100644 --- a/.claude/commands/workflow/collaborative-plan-with-file.md +++ b/.claude/commands/workflow/collaborative-plan-with-file.md @@ -141,6 +141,8 @@ Unified collaborative planning workflow using **Plan Note** architecture: - Session initialized with valid sessionId and sessionFolder - Task description available from $ARGUMENTS +**Guideline**: In Understanding phase, prioritize identifying latest documentation (README, design docs, architecture guides). When ambiguities exist, ask user for clarification instead of assuming interpretations. + **Workflow Steps**: 1. **Initialize Progress Tracking** @@ -152,8 +154,10 @@ Unified collaborative planning workflow using **Plan Note** architecture: - Execution mode: synchronous (run_in_background: false) 3. **Agent Tasks**: - - **Understand Requirements**: Extract core objective, key points, constraints from task description - - **Form Checklist**: Identify critical questions needing clarification + - **Identify Latest Documentation**: Search for and prioritize latest README, design docs, architecture guides + - **Understand Requirements**: Extract core objective, key points, constraints from task description and latest docs + - **Identify Ambiguities**: List any unclear points or multiple possible interpretations + - **Form Clarification Checklist**: Prepare questions for user if ambiguities found (use AskUserQuestion) - **Split Sub-Domains**: Identify 2-{maxAgents} parallelizable focus areas - **Create Plan Note**: Generate plan-note.md with pre-allocated sections @@ -172,6 +176,8 @@ Unified collaborative planning workflow using **Plan Note** architecture: - `total_agents`: Number of agents to spawn **Success Criteria**: +- Latest documentation identified and referenced (if available) +- Ambiguities resolved via user clarification (if any found) - 2-{maxAgents} clear sub-domains identified - Each sub-domain can be planned independently - Plan Note template includes all pre-allocated sections @@ -191,14 +197,19 @@ Task( prompt=` ## Mission: Create Plan Note Template +### Key Guidelines +1. **Prioritize Latest Documentation**: Search for and reference latest README, design docs, architecture guides when available +2. **Handle Ambiguities**: When requirement ambiguities exist, ask user for clarification (use AskUserQuestion) instead of assuming interpretations + ### Input Requirements ${taskDescription} ### Tasks -1. **Understand Requirements**: Extract core objective, key points, constraints -2. **Form Checklist**: Identify critical questions needing clarification -3. **Split Sub-Domains**: Identify 2-${maxAgents} parallelizable focus areas -4. **Create Plan Note**: Generate plan-note.md with pre-allocated sections +1. **Understand Requirements**: Extract core objective, key points, constraints (reference latest docs when available) +2. **Identify Ambiguities**: List any unclear points or multiple possible interpretations +3. **Form Clarification Checklist**: Prepare questions for user if ambiguities found +4. **Split Sub-Domains**: Identify 2-${maxAgents} parallelizable focus areas +5. **Create Plan Note**: Generate plan-note.md with pre-allocated sections ### Output Files @@ -595,9 +606,11 @@ Schema: ~/.claude/workflows/cli-templates/schemas/plan-json-schema.json ## Best Practices 1. **Clear Requirements**: Detailed requirements → better sub-domain splitting -2. **Review Plan Note**: Check plan-note.md before execution -3. **Resolve Conflicts**: Address high/critical conflicts before execution -4. **Inspect Details**: Use agents/{focus-area}/plan.json for deep dive +2. **Reference Latest Documentation**: Understanding agent should prioritize identifying and referencing latest docs (README, design docs, architecture guides) +3. **Ask When Uncertain**: When ambiguities or multiple interpretations exist, ask user for clarification instead of assuming +4. **Review Plan Note**: Check plan-note.md before execution +5. **Resolve Conflicts**: Address high/critical conflicts before execution +6. **Inspect Details**: Use agents/{focus-area}/plan.json for deep dive ---