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
This commit is contained in:
catlog22
2026-02-01 22:51:04 +08:00
parent 7dcc0a1c05
commit 76967a7350
3 changed files with 184 additions and 70 deletions

View File

@@ -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

View File

@@ -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

View File

@@ -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
---