feat: Add plan-deep command and Gemini analysis integration

- Create /workflow:plan:deep command for deep technical planning - Add GEMINI_ANALYSIS_REQUIRED support to conceptual-planning-agent - Translate brainstorm commands to English (business-analyst, partial innovation-lead) - Consolidate document format standards in file-structure-standards.md - Update action-planning-agent to reference centralized format standards Key changes: - plan-deep.md: New command with mandatory Gemini CLI analysis via agent - conceptual-planning-agent.md: Added Gemini Analysis Integration section - file-structure-standards.md: Enhanced with detailed IMPL_PLAN.md formats - Unified language to English for consistency
2026-02-11 02:33:51 +08:00 · 2025-09-09 10:52:51 +08:00
parent 6f85340ab8
commit b6dda499e4
6 changed files with 638 additions and 260 deletions
--- a/.claude/commands/workflow/brainstorm/business-analyst.md
+++ b/.claude/commands/workflow/brainstorm/business-analyst.md
@@ -10,51 +10,61 @@ examples:
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*)
 ---

-## 📊 **角色定义: Business Analyst**
+## 📊 **Role Overview: Business Analyst**

-### 核心职责
- **流程分析**: 分析现有业务流程的效率和改进机会
- **需求分析**: 识别和定义业务需求和功能要求
- **效益评估**: 评估解决方案的商业价值和投资回报
- **变更管理**: 规划和管理业务流程变更
+### Role Definition
+Business process expert responsible for analyzing workflows, identifying requirements, and optimizing business operations to maximize value and efficiency.

-### 关注领域
- **流程优化**: 工作流程、自动化机会、效率提升
- **数据分析**: 业务指标、KPI设计、性能测量
- **成本效益**: ROI分析、成本优化、价值创造
- **风险管理**: 业务风险、合规要求、变更风险
+### Core Responsibilities
+- **Process Analysis**: Analyze existing business processes for efficiency and improvement opportunities
+- **Requirements Analysis**: Identify and define business requirements and functional specifications
+- **Value Assessment**: Evaluate solution business value and return on investment
+- **Change Management**: Plan and manage business process changes

-## 🧠 **分析框架**
+### Focus Areas
+- **Process Optimization**: Workflows, automation opportunities, efficiency improvements
+- **Data Analysis**: Business metrics, KPI design, performance measurement
+- **Cost-Benefit**: ROI analysis, cost optimization, value creation
+- **Risk Management**: Business risks, compliance requirements, change risks
+
+### Success Metrics
+- Process efficiency improvements (time/cost reduction)
+- Requirements clarity and completeness
+- Stakeholder satisfaction levels
+- ROI achievement and value delivery
+
+## 🧠 **Analysis Framework**

@~/.claude/workflows/brainstorming-principles.md
@~/.claude/workflows/conceptual-planning-agent.md

-### 核心分析问题
-1. **业务流程分析**:
-   - 当前业务流程的瓶颈和低效环节？
-   - 哪些流程可以自动化或简化？
-   - 跨部门协作中的障碍点？
+### Key Analysis Questions

-2. **业务需求识别**:
-   - 利益相关者的核心需求？
-   - 业务目标和成功指标？
-   - 功能和非功能需求优先级？
+**1. Business Process Analysis**
+- What are the bottlenecks and inefficiencies in current business processes?
+- Which processes can be automated or simplified?
+- What are the obstacles in cross-departmental collaboration?

-3. **价值和效益分析**:
-   - 解决方案的预期商业价值？
-   - 实施成本vs收益对比？
-   - 风险评估和缓解策略？
+**2. Business Requirements Identification**
+- What are the core needs of stakeholders?
+- What are the business objectives and success metrics?
+- How should functional and non-functional requirements be prioritized?

-4. **实施和变更管理**:
-   - 变更对现有流程的影响？
-   - 培训和适应需求？
-   - 成功指标和监控机制？
+**3. Value and Benefit Analysis**
+- What is the expected business value of the solution?
+- How does implementation cost compare to expected benefits?
+- What are the risk assessments and mitigation strategies?

-## ⚙️ **执行协议**
+**4. Implementation and Change Management**
+- How will changes impact existing processes?
+- What training and adaptation requirements exist?
+- What success metrics and monitoring mechanisms are needed?

-### Phase 1: 会话检测与初始化
+## ⚙️ **Execution Protocol**
+
+### Phase 1: Session Detection & Initialization
 ```bash
-# 自动检测活动会话
+# Detect active workflow session
 CHECK: .workflow/.active-* marker files
 IF active_session EXISTS:
    session_id = get_active_session()
@@ -63,14 +73,14 @@ ELSE:
    request_user_for_session_creation()
 ```

-### Phase 2: 目录结构创建
+### Phase 2: Directory Structure Creation
 ```bash
-# 创建业务分析师分析目录
+# Create business analyst analysis directory
 mkdir -p .workflow/WFS-{topic-slug}/.brainstorming/business-analyst/
 ```

-### Phase 3: TodoWrite 初始化
-设置业务分析师视角分析的任务跟踪：
+### Phase 3: Task Tracking Initialization
+Initialize business analyst perspective analysis tracking:
 ```json
 [
  {"content": "Initialize business analyst brainstorming session", "status": "completed", "activeForm": "Initializing session"},
@@ -83,9 +93,17 @@ mkdir -p .workflow/WFS-{topic-slug}/.brainstorming/business-analyst/
 ]
 ```

-### Phase 4: 概念规划代理协调
+### Phase 4: Conceptual Planning Agent Coordination
 ```bash
 Task(conceptual-planning-agent): "
+ASSIGNED_ROLE: business-analyst
+GEMINI_ANALYSIS_REQUIRED: true
+ANALYSIS_DIMENSIONS: 
+  - process_optimization
+  - cost_analysis
+  - efficiency_metrics
+  - workflow_patterns
+
 Conduct business analyst perspective brainstorming for: {topic}

 ROLE CONTEXT: Business Analyst
@@ -148,26 +166,26 @@ OUTPUT REQUIREMENTS: Save comprehensive analysis to:
 Apply business analysis expertise to optimize processes and maximize business value."
 ```

-## 📊 **输出结构**
+## 📊 **Output Structure**

-### 保存位置
+### Output Location
 ```
 .workflow/WFS-{topic-slug}/.brainstorming/business-analyst/
-├── analysis.md                 # 主要业务分析和流程评估
-├── requirements.md             # 详细业务需求和规范
-├── business-case.md            # 成本效益分析和财务论证
-└── implementation-plan.md      # 变更管理和实施策略
+├── analysis.md                 # Main business analysis and process assessment
+├── requirements.md             # Detailed business requirements and specifications
+├── business-case.md            # Cost-benefit analysis and financial justification
+└── implementation-plan.md      # Change management and implementation strategy
 ```

-### 文档模板
+### Document Templates

-#### analysis.md 结构
+#### analysis.md Structure
 ```markdown
 # Business Analyst Analysis: {Topic}
 *Generated: {timestamp}*

 ## Executive Summary
-[核心业务分析发现和建议概述]
+[Overview of key business analysis findings and recommendations]

 ## Current State Assessment
 ### Business Process Mapping
@@ -212,10 +230,10 @@ Apply business analysis expertise to optimize processes and maximize business va
 ### Resource Requirements
 ```

-## 🔄 **会话集成**
+## 🔄 **Session Integration**

-### 状态同步
-分析完成后，更新 `workflow-session.json`:
+### Status Synchronization
+After analysis completion, update `workflow-session.json`:
 ```json
 {
  "phases": {
@@ -231,33 +249,33 @@ Apply business analysis expertise to optimize processes and maximize business va
 }
 ```

-### 与其他角色的协作
-业务分析师视角为其他角色提供：
- **业务需求和约束** → Product Manager
- **流程技术化需求** → System Architect
- **业务流程界面需求** → UI Designer
- **业务数据需求** → Data Architect
- **业务安全要求** → Security Expert
+### Collaboration with Other Roles
+Business analyst perspective provides to other roles:
+- **Business requirements and constraints** → Product Manager
+- **Process technology requirements** → System Architect
+- **Business process interface needs** → UI Designer
+- **Business data requirements** → Data Architect
+- **Business security requirements** → Security Expert

-## ✅ **质量标准**
+## ✅ **Quality Standards**

-### 必须包含的分析元素
- [ ] 详细的业务流程映射
- [ ] 明确的需求规范和优先级
- [ ] 量化的成本效益分析
- [ ] 全面的风险评估
- [ ] 可执行的实施计划
+### Required Analysis Elements
+- [ ] Detailed business process mapping
+- [ ] Clear requirements specifications and priorities
+- [ ] Quantified cost-benefit analysis
+- [ ] Comprehensive risk assessment
+- [ ] Actionable implementation plan

-### 业务分析原则检查
- [ ] 以价值为导向：关注商业价值创造
- [ ] 数据驱动：基于事实和数据进行分析
- [ ] 全局思维：考虑整个业务生态系统
- [ ] 风险意识：识别和管理各类风险
- [ ] 可持续性：长期可维护和改进
+### Business Analysis Principles Checklist
+- [ ] Value-oriented: Focus on business value creation
+- [ ] Data-driven: Analysis based on facts and data
+- [ ] Holistic thinking: Consider entire business ecosystem
+- [ ] Risk awareness: Identify and manage various risks
+- [ ] Sustainability: Long-term maintainability and improvement

-### 分析质量指标
- [ ] 需求的完整性和准确性
- [ ] 流程优化的量化收益
- [ ] 风险评估的全面性
- [ ] 实施计划的可行性
- [ ] 利益相关者的满意度
+### Analysis Quality Metrics
+- [ ] Requirements completeness and accuracy
+- [ ] Quantified benefits from process optimization
+- [ ] Comprehensiveness of risk assessment
+- [ ] Feasibility of implementation plan
+- [ ] Stakeholder satisfaction levels
--- a/.claude/commands/workflow/brainstorm/innovation-lead.md
+++ b/.claude/commands/workflow/brainstorm/innovation-lead.md
@@ -50,11 +50,11 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*)
   - 投资需求和预期回报？
   - 组织创新能力和适应性？

-## ⚙️ **执行协议**
+## ⚙️ **Execution Protocol**

-### Phase 1: 会话检测与初始化
+### Phase 1: Session Detection & Initialization
 ```bash
-# 自动检测活动会话
+# Detect active workflow session
 CHECK: .workflow/.active-* marker files
 IF active_session EXISTS:
    session_id = get_active_session()
@@ -63,14 +63,14 @@ ELSE:
    request_user_for_session_creation()
 ```

-### Phase 2: 目录结构创建
+### Phase 2: Directory Structure Creation
 ```bash
-# 创建创新领导分析目录
+# Create innovation lead analysis directory
 mkdir -p .workflow/WFS-{topic-slug}/.brainstorming/innovation-lead/
 ```

-### Phase 3: TodoWrite 初始化
-设置创新领导视角分析的任务跟踪：
+### Phase 3: Task Tracking Initialization
+Initialize innovation lead perspective analysis tracking:
 ```json
 [
  {"content": "Initialize innovation lead brainstorming session", "status": "completed", "activeForm": "Initializing session"},
@@ -83,9 +83,17 @@ mkdir -p .workflow/WFS-{topic-slug}/.brainstorming/innovation-lead/
 ]
 ```

-### Phase 4: 概念规划代理协调
+### Phase 4: Conceptual Planning Agent Coordination
 ```bash
 Task(conceptual-planning-agent): "
+ASSIGNED_ROLE: innovation-lead
+GEMINI_ANALYSIS_REQUIRED: true
+ANALYSIS_DIMENSIONS: 
+  - emerging_patterns
+  - technology_trends
+  - disruption_potential
+  - innovation_opportunities
+
 Conduct innovation lead perspective brainstorming for: {topic}

 ROLE CONTEXT: Innovation Lead
--- a/.claude/commands/workflow/plan-deep.md
+++ b/.claude/commands/workflow/plan-deep.md
@@ -0,0 +1,225 @@
+---
+name: workflow-plan-deep
+description: Deep technical planning with Gemini CLI analysis and action-planning-agent
+usage: /workflow:plan:deep <task_description>
+argument-hint: "task description" | requirements.md
+examples:
+  - /workflow:plan:deep "Refactor authentication system to use JWT"
+  - /workflow:plan:deep "Implement real-time notifications across modules"
+  - /workflow:plan:deep requirements.md
+---
+
+# Workflow Plan Deep Command (/workflow:plan:deep)
+
+## Overview
+Creates comprehensive implementation plans through deep codebase analysis using Gemini CLI and the action-planning-agent. This command enforces multi-dimensional context gathering before planning, ensuring technical decisions are grounded in actual codebase understanding.
+
+## Key Differentiators
+
+### vs /workflow:plan
+| Feature | /workflow:plan | /workflow:plan:deep |
+|---------|---------------|-------------------|
+| **Analysis Depth** | Basic requirements extraction | Deep codebase analysis |
+| **Gemini CLI** | Optional | **Mandatory (via agent)** |
+| **Context Scope** | Current input only | Multi-dimensional analysis |
+| **Agent Used** | None (direct processing) | action-planning-agent |
+| **Output Detail** | Standard IMPL_PLAN | Enhanced hierarchical plan |
+| **Best For** | Quick planning | Complex technical tasks |
+
+## When to Use This Command
+
+### Ideal Scenarios
+- **Cross-module refactoring** requiring understanding of multiple components
+- **Architecture changes** affecting system-wide patterns
+- **Complex feature implementation** spanning >3 modules
+- **Performance optimization** requiring deep code analysis
+- **Security enhancements** needing comprehensive vulnerability assessment
+- **Technical debt resolution** with broad impact
+
+### Not Recommended For
+- Simple, single-file changes
+- Documentation updates
+- Configuration adjustments
+- Tasks with clear, limited scope
+
+## Execution Flow
+
+### 1. Input Processing
+```
+Input Analysis:
+├── Parse task description or file
+├── Extract key technical terms
+├── Identify potential affected domains
+└── Prepare context for agent
+```
+
+### 2. Agent Invocation with Deep Analysis Flag
+The command invokes action-planning-agent with special parameters that **enforce** Gemini CLI analysis.
+
+### 3. Agent Processing (Delegated to action-planning-agent)
+
+**Agent Execution Flow**:
+```
+Agent receives DEEP_ANALYSIS_REQUIRED flag
+├── Executes 4-dimension Gemini CLI analysis in parallel:
+│   ├── Architecture Analysis (patterns, components)
+│   ├── Code Pattern Analysis (conventions, standards)
+│   ├── Impact Analysis (affected modules, dependencies)
+│   └── Testing Requirements (coverage, patterns)
+├── Consolidates Gemini results into gemini-analysis.md
+├── Creates workflow session directory
+├── Generates hierarchical IMPL_PLAN.md
+├── Creates TODO_LIST.md for tracking
+└── Saves all outputs to .workflow/WFS-[session-id]/
+```
+```markdown
+Task(action-planning-agent):
+  description: "Deep technical planning with mandatory codebase analysis"
+  prompt: |
+    Create implementation plan for: [task_description]
+    
+    EXECUTION MODE: DEEP_ANALYSIS_REQUIRED
+    
+    MANDATORY REQUIREMENTS:
+    - Execute comprehensive Gemini CLI analysis (4 dimensions)
+    - Skip PRD processing (no PRD provided)
+    - Skip session inheritance (standalone planning)
+    - Force GEMINI_CLI_REQUIRED flag = true
+    - Generate hierarchical task decomposition
+    - Create detailed IMPL_PLAN.md with subtasks
+    - Generate TODO_LIST.md for tracking
+    
+    GEMINI ANALYSIS DIMENSIONS (execute in parallel):
+    1. Architecture Analysis - design patterns, component relationships
+    2. Code Pattern Analysis - conventions, error handling, validation
+    3. Impact Analysis - affected modules, breaking changes
+    4. Testing Requirements - coverage needs, test patterns
+    
+    FOCUS: Technical implementation based on deep codebase understanding
+```
+
+### 4. Output Generation (by Agent)
+The action-planning-agent generates in `.workflow/WFS-[session-id]/`:
+- **IMPL_PLAN.md** - Hierarchical implementation plan with stages
+- **TODO_LIST.md** - Task tracking checklist (if complexity > simple)
+- **.task/*.json** - Task definitions for complex projects
+- **workflow-session.json** - Session tracking
+- **gemini-analysis.md** - Consolidated Gemini analysis results
+
+## Command Processing Logic
+
+```python
+def process_plan_deep_command(input):
+    # Step 1: Parse input
+    task_description = parse_input(input)
+    
+    # Step 2: Build agent prompt with deep analysis flag
+    agent_prompt = f"""
+    EXECUTION_MODE: DEEP_ANALYSIS_REQUIRED
+    TASK: {task_description}
+    
+    MANDATORY FLAGS:
+    - GEMINI_CLI_REQUIRED = true
+    - FORCE_PARALLEL_ANALYSIS = true
+    - SKIP_PRD = true
+    - SKIP_SESSION_INHERITANCE = true
+    
+    Execute comprehensive Gemini CLI analysis before planning.
+    """
+    
+    # Step 3: Invoke action-planning-agent
+    # Agent will handle session creation and Gemini execution
+    Task(
+        subagent_type="action-planning-agent",
+        description="Deep technical planning with mandatory analysis",
+        prompt=agent_prompt
+    )
+    
+    # Step 4: Agent handles all processing and outputs
+    return "Agent executing deep analysis and planning..."
+```
+
+## Error Handling
+
+### Common Issues and Solutions
+
+**Agent Execution Errors**
+- Verify action-planning-agent availability
+- Check for context size limits
+- Agent handles Gemini CLI failures internally
+
+**Gemini CLI Failures (handled by agent)**
+- Agent falls back to file-pattern based analysis
+- Agent retries with reduced scope automatically
+- Agent alerts if critical analysis fails
+
+**File Access Issues**
+- Verify permissions for workflow directory
+- Check file patterns for validity
+- Alert on missing CLAUDE.md files
+
+## Integration Points
+
+### Related Commands
+- `/workflow:plan` - Quick planning without deep analysis
+- `/workflow:execute` - Execute generated plans
+- `/workflow:review` - Review implementation progress
+- `/context` - View generated planning documents
+
+### Agent Dependencies
+- **action-planning-agent** - Core planning engine
+- **code-developer** - For execution phase
+- **code-review-agent** - For quality checks
+
+## Usage Examples
+
+### Example 1: Cross-Module Refactoring
+```bash
+/workflow:plan:deep "Refactor user authentication to use JWT tokens across all services"
+```
+Generates comprehensive plan analyzing:
+- Current auth implementation
+- All affected services
+- Migration strategy
+- Testing requirements
+
+### Example 2: Performance Optimization
+```bash
+/workflow:plan:deep "Optimize database query performance in reporting module"
+```
+Creates detailed plan including:
+- Current query patterns analysis
+- Bottleneck identification
+- Optimization strategies
+- Performance testing approach
+
+### Example 3: Architecture Enhancement
+```bash
+/workflow:plan:deep "Implement event-driven architecture for order processing"
+```
+Produces hierarchical plan with:
+- Current architecture assessment
+- Event flow design
+- Module integration points
+- Staged migration approach
+
+## Best Practices
+
+1. **Use for Complex Tasks**: Reserve for tasks requiring deep understanding
+2. **Provide Clear Descriptions**: Specific task descriptions yield better analysis
+3. **Review Gemini Output**: Check analysis results for accuracy
+4. **Iterate on Plans**: Refine based on initial analysis
+5. **Track Progress**: Use generated TODO_LIST.md for execution
+
+## Technical Notes
+
+- **Agent-Driven Analysis**: action-planning-agent executes all Gemini CLI commands
+- **Parallel Execution**: Agent runs 4 Gemini analyses concurrently for performance
+- **Context Management**: Agent handles context size limits automatically
+- **Structured Handoff**: Command passes DEEP_ANALYSIS_REQUIRED flag to agent
+- **Session Management**: Agent creates and manages workflow session
+- **Output Standards**: All documents follow established workflow formats
+
+---
+
+**System ensures**: Deep technical understanding before planning through mandatory Gemini CLI analysis and intelligent agent orchestration