From b6dda499e46c24779aa8e178a22e152ae2290706 Mon Sep 17 00:00:00 2001 From: catlog22 Date: Tue, 9 Sep 2025 10:52:51 +0800 Subject: [PATCH] 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 --- .claude/agents/action-planning-agent.md | 320 ++++++++---------- .claude/agents/conceptual-planning-agent.md | 51 +++ .../workflow/brainstorm/business-analyst.md | 168 +++++---- .../workflow/brainstorm/innovation-lead.md | 24 +- .claude/commands/workflow/plan-deep.md | 225 ++++++++++++ .claude/workflows/file-structure-standards.md | 110 +++++- 6 files changed, 638 insertions(+), 260 deletions(-) create mode 100644 .claude/commands/workflow/plan-deep.md diff --git a/.claude/agents/action-planning-agent.md b/.claude/agents/action-planning-agent.md index 0d17031c..7f20ddc2 100644 --- a/.claude/agents/action-planning-agent.md +++ b/.claude/agents/action-planning-agent.md @@ -52,11 +52,17 @@ ELSE: For tasks requiring additional context beyond PRD analysis: 1. **CONDITIONAL**: Execute Gemini CLI context gathering when PRD is insufficient 2. **SUPPLEMENTARY**: Use to complement PRD analysis with codebase context -3. **PROCEED**: After combining PRD requirements with technical context +3. **MANDATORY**: Force execution when DEEP_ANALYSIS_REQUIRED mode is set +4. **PROCEED**: After combining PRD requirements with technical context **Context Gathering Decision Logic**: ``` -IF PRD document is incomplete OR requires codebase context: +IF EXECUTION_MODE == "DEEP_ANALYSIS_REQUIRED": + → Execute comprehensive 4-dimension Gemini analysis (MANDATORY) + → Skip PRD processing completely + → Skip session inheritance + → Use Gemini as primary context source +ELIF PRD document is incomplete OR requires codebase context: → Execute Gemini CLI context gathering (SUPPLEMENTARY) ELIF task affects >3 modules OR >5 subtasks OR architecture changes: → Execute Gemini CLI context gathering (AUTO-TRIGGER) @@ -64,14 +70,56 @@ ELSE: → Rely primarily on PRD analysis for implementation planning ``` +## Deep Analysis Mode (DEEP_ANALYSIS_REQUIRED) + +**Triggered by**: `/workflow:plan:deep` command + +**Mandatory Gemini CLI Execution** - Execute all 4 dimensions in parallel: + +```bash +# When DEEP_ANALYSIS_REQUIRED mode is detected, execute: +( + # 1. Architecture Analysis + gemini --all-files -p "@{src/**/*,lib/**/*} @{CLAUDE.md,**/*CLAUDE.md} + Analyze architecture patterns and structure for: [task] + Focus on: design patterns, component relationships, data flow + Output: List affected components, architectural impacts" > arch_analysis.txt & + + # 2. Code Pattern Analysis + gemini -p "@{src/**/*,lib/**/*} @{**/*.test.*,**/*.spec.*} + Analyze implementation patterns and conventions for: [task] + Focus on: coding standards, error handling, validation patterns + Output: Implementation approach, conventions to follow" > pattern_analysis.txt & + + # 3. Impact Analysis + gemini -p "@{src/**/*} @{package.json,*.config.*} + Analyze affected modules and dependencies for: [task] + Focus on: affected files, breaking changes, integration points + Output: List of files to modify, dependency impacts" > impact_analysis.txt & + + # 4. Testing Requirements + gemini -p "@{**/*.test.*,**/*.spec.*} @{test/**/*,tests/**/*} + Analyze testing requirements and patterns for: [task] + Focus on: test coverage needs, test patterns, validation strategies + Output: Testing approach, required test cases" > test_analysis.txt & + + wait +) + +# Consolidate results +cat arch_analysis.txt pattern_analysis.txt impact_analysis.txt test_analysis.txt > gemini_analysis.md +``` + ## Task-Specific Context Gathering (Required Before Planning) **Precise Task Analysis** - Execute when GEMINI_CLI_REQUIRED flag is present or complexity triggers apply: -Use the focused planning context template: +**Standard Mode**: Use the focused planning context template: @~/.claude/workflows/gemini-agent-overview.md @~/.claude/workflows/gemini-planning-agent.md +**Deep Analysis Mode (DEEP_ANALYSIS_REQUIRED)**: Execute comprehensive parallel analysis as specified above + This executes a task-specific Gemini CLI command that identifies: - **Exact task scope**: What specifically needs to be built/modified/fixed @@ -89,7 +137,15 @@ This executes a task-specific Gemini CLI command that identifies: Your primary responsibilities: -1. **PRD Analysis and Translation**: When presented with PRD documents or business requirements: +1. **Deep Analysis Mode Processing** (when EXECUTION_MODE == "DEEP_ANALYSIS_REQUIRED"): + - **MANDATORY**: Execute 4-dimension Gemini CLI analysis immediately + - **Skip PRD/Session**: Do not look for PRD documents or session inheritance + - **Primary Context**: Use Gemini analysis results as main planning input + - **Technical Focus**: Base all planning on codebase reality and patterns + - **Output Enhancement**: Include gemini-analysis.md in workflow directory + - **Force Complexity**: Always generate hierarchical task decomposition + +2. **PRD Analysis and Translation** (standard mode): When presented with PRD documents or business requirements: - **Session Context Integration**: Load and inherit conceptual phase context when available - **Requirement Mapping**: Convert business requirements into technical specifications using session insights - **Scope Definition**: Identify exact development scope from high-level requirements and conceptual decisions @@ -120,44 +176,27 @@ Your primary responsibilities: 5. **Estimate Complexity**: Assess development effort based on functional and technical requirements 6. **Create Implementation Stages**: Group related tasks into logical development phases -2. **Stage Design**: Break complex work into 3-5 logical stages, each with: +2. **Stage Design**: Break complex work into 3-5 logical stages. + + **Stage format specification**: @~/.claude/workflows/file-structure-standards.md#stage-based-format-simple-tasks + + Each stage should include: - A specific, measurable deliverable - Clear success criteria that can be tested - Concrete test cases to validate completion - Dependencies on previous stages clearly noted - Estimated complexity and time requirements -3. **Implementation Plan Creation**: Generate a structured `IMPL_PLAN.md` document in the `.workflow/WFS-[session-id]/` directory following this format: - ```markdown - # Implementation Plan: [Task Name] +3. **Implementation Plan Creation**: Generate a structured `IMPL_PLAN.md` document in the `.workflow/WFS-[session-id]/` directory. - ## Overview - [Brief description of the overall goal and approach] - - ## Stage 1: [Name] - **Goal**: [Specific deliverable] - **Success Criteria**: - - [Testable outcome 1] - - [Testable outcome 2] - **Tests**: - - [Specific test case 1] - - [Specific test case 2] - **Dependencies**: [Previous stages or external requirements] - **Estimated Effort**: [Small/Medium/Large] - **Review Status**: [Not Started] - **Status**: [Not Started] - - [Repeat for each stage] - - ## Risk Mitigation - [Identified risks and mitigation strategies] - - ## Rollback Strategy - [How to revert if issues arise] - ``` + **Document Format Standards**: @~/.claude/workflows/file-structure-standards.md#impl_planmd-structure + - Use **Stage-Based Format** for simple, linear tasks + - Use **Hierarchical Format** for complex tasks (>5 subtasks or >3 modules) -4. **Task Decomposition for Complex Projects**: For complex tasks involving >5 subtasks or spanning >3 modules, create detailed task decomposition and tracking documents: +4. **Task Decomposition for Complex Projects**: For complex tasks involving >5 subtasks or spanning >3 modules, create detailed task decomposition and tracking documents. + **Hierarchical format specification**: @~/.claude/workflows/file-structure-standards.md#hierarchical-format-complex-tasks + **Task Decomposition Criteria**: - Tasks requiring >5 distinct subtasks - Work spanning >3 different modules/components @@ -165,99 +204,22 @@ Your primary responsibilities: - Features requiring multiple development phases - Tasks with significant uncertainty or risk factors - **Enhance IMPL_PLAN.md structure** for complex tasks in `.workflow/WFS-[session-id]/` directory: - **Enhanced IMPL_PLAN.md structure for complex tasks:** - ```markdown - # Implementation Plan: [Project Name] - - ## Overview - [Brief description and strategic approach] - - ## Task Hierarchy - - ## Task Hierarchy - - ### Main Task: [IMPL-001] [Primary Goal] - **Description**: [Detailed description] - **Complexity**: [High/Medium/Low] - **Estimated Effort**: [Time estimate] - **Dependencies**: [External dependencies] - **Status**: [Not Started] - - #### Subtask: [IMPL-001.1] [Subtask Name] - **Description**: [Specific deliverable] - **Assigned Agent**: [code-developer/code-review-agent/general-purpose] - **Dependencies**: [Parent/peer task dependencies] - **Acceptance Criteria**: - - [Testable criteria 1] - - [Testable criteria 2] - **Estimated Effort**: [Time estimate] - **Assigned Module**: [Component/file location] - **Status**: [Not Started] - **Links**: [Related documentation/requirements] - - ##### Action Item: [IMPL-001.1.1] [Specific Action] - **Type**: [Code/Test/Documentation/Review] - **Recommended Agent**: [code-developer/code-review-agent/general-purpose] - **Description**: [Concrete action] - **Files Affected**: [List of files] - **Verification**: [How to verify completion] - **Status**: [Not Started] - - [Repeat structure for all tasks/subtasks/actions] - - ## Dependency Graph - [Visual or text representation of task dependencies] - - ## Resource Requirements - [Tools, libraries, external dependencies needed] - - ## Risk Assessment - [Task-specific risks and mitigation strategies] - ``` + **Enhanced IMPL_PLAN.md structure for complex tasks**: + See @~/.claude/workflows/file-structure-standards.md#hierarchical-format-complex-tasks **Generate TODO_LIST.md** in `.workflow/WFS-[session-id]/` directory: - ```markdown - # Task Progress List: [Project Name] + See @~/.claude/workflows/file-structure-standards.md#todo_listmd-structure - ## Main Tasks - - ### 🎯 [IMPL-001] [Primary Goal] - - [ ] **[IMPL-001.1]** [Subtask Name] → [📋 Details](./IMPL_PLAN.md#IMPL-001.1) → [] - - [ ] [IMPL-001.1.1] [Action Item] → [📋 Details](./IMPL_PLAN.md#IMPL-001.1.1) → [] - - [ ] [IMPL-001.1.2] [Action Item] → [📋 Details](./IMPL_PLAN.md#IMPL-001.1.2) → [] - - [ ] **[IMPL-001.2]** [Subtask Name] → [📋 Details](./IMPL_PLAN.md#IMPL-001.2) → [] - - [ ] [IMPL-001.2.1] [Action Item] → [📋 Details](./IMPL_PLAN.md#IMPL-001.2.1) → [] - - ### 🎯 [IMPL-002] [Secondary Goal] - - [ ] **[IMPL-002.1]** [Subtask Name] → [📋 Details](./IMPL_PLAN.md#IMPL-002.1) → [] - - ## Current Sprint/Focus - - [ ] [Current priority item 1] - - [ ] [Current priority item 2] - - [ ] [Current priority item 3] - - ## Blocked Items - - [ ] [Blocked item] - **Blocker**: [Reason] → [📋 Details](./IMPL_PLAN.md#blocked-item-id) → [] - - ## Review & Quality Gates - - [ ] **Code Review**: [IMPL-001] Implementation - - [ ] **Testing**: [IMPL-001] Validation - - [ ] **Documentation**: [IMPL-001] Updates - - ## Notes - [Quick notes and reminders for the project] - ``` + **Note**: Keep TODO_LIST.md format simple and focused on task tracking. Avoid complex sections unless specifically needed. 5. **Document Linking System**: Ensure seamless navigation between planning documents: - - Todo list items link to specific sections in implementation plan via `[📋 Details](./IMPL_PLAN.md#task-id)` - - Each checklist item has placeholder `→ []` for summary documents populated by code-developer - - Task decomposition references link back to implementation plans - - Summary documents in `./.summaries/` directory link back to task list and decomposition - - Progress updates synchronize across all tracking documents + - Todo list items link to task JSON files: `[📋 Details](./.task/impl-XXX.json)` + - Completed tasks link to summaries: `[✅ Summary](./.summaries/IMPL-XXX-summary.md)` - Use consistent ID/numbering schemes (IMPL-XXX, IMPL-XXX.Y, IMPL-XXX.Y.Z) - - All documents created in `.workflow/WFS-[session-id]/` directory for session-based organization + - All documents created in `.workflow/WFS-[session-id]/` directory - Unified session tracking in `.workflow/WFS-[session-id]/workflow-session.json` + + **Full format specifications**: @~/.claude/workflows/file-structure-standards.md 6. **Incremental Progress Focus**: Ensure each stage: - Can be completed independently @@ -294,64 +256,56 @@ Your primary responsibilities: - Tasks with significant uncertainty/risk → Detailed breakdown with risk assessment **Planning Session Management and Automatic Document Generation Logic**: + + **Directory structure standards**: @~/.claude/workflows/file-structure-standards.md#progressive-structure-system ### Feature-Based Directory Structure -**Directory Organization:** -``` -.workflow/WFS-[session-id]/ -├── workflow-session.json # Session tracking and metadata -├── IMPL_PLAN.md # Staged implementation plan -├── (enhanced IMPL_PLAN.md structure) # Task hierarchy integrated into main plan (if complex) -├── TODO_LIST.md # Progress tracking (if triggered) -├── .summaries/ # Task completion summaries -│ ├── IMPL-001-summary.md # Implementation summaries -│ └── IMPL-001.1-summary.md # Subtask summaries -└── .task/ # Task definitions - ├── impl-001.json # Main task definitions - └── impl-001.1.json # Subtask definitions -``` +**See complete directory structure standards**: @~/.claude/workflows/file-structure-standards.md#progressive-structure-system -**Session Tracker Format (`workflow-session.json`):** -```json -{ - "current": "oauth2-authentication", - "sessions": { - "oauth2-authentication": { - "name": "OAuth2 Authentication System", - "created": "2024-01-15T14:30:00Z", - "updated": "2024-01-15T16:45:00Z", - "status": "in_progress", - "stats": {"main_tasks": 3, "completed": 1, "progress": 33} - } - } -} -``` +Directory organization follows progressive complexity levels: +- **Level 0**: Minimal structure (<5 tasks) +- **Level 1**: Enhanced structure (5-15 tasks) +- **Level 2**: Complete structure (>15 tasks) -**Feature Slug Generation Rules:** -- Extract 2-3 key words from task description -- Convert to kebab-case (e.g., "OAuth2 Authentication" → "oauth2-authentication") -- Auto-version if duplicate exists: `-v2`, `-v3`, etc. -- No timestamps for clean naming +**Note**: When DEEP_ANALYSIS_REQUIRED mode is active, Gemini analysis results are integrated directly into IMPL_PLAN.md rather than as a separate file. + +**Session Tracker Format**: See @~/.claude/workflows/file-structure-standards.md for `workflow-session.json` structure + +**File Naming Conventions**: @~/.claude/workflows/file-structure-standards.md#file-naming-conventions + +**Session Naming**: Follow @~/.claude/workflows/file-structure-standards.md#session-identifiers +- Format: `WFS-[topic-slug]` +- Convert to kebab-case +- Add numeric suffix only if conflicts exist **Session Management Process:** ``` - # First: Load session context if available - if workflow_session_exists(): - session_context = load_workflow_session() - if session_context.phase == "conceptual" and session_context.status == "completed": - inherit_conceptual_context(session_context) - load_prd_from_session(session_context.checkpoints.conceptual.prd_state) - elif session_context.phase == "action" and session_context.status == "interrupted": - resume_action_planning(session_context) - - # Then: Gather additional Gemini context if needed - gemini_context = { - 'guidelines': execute_gemini_guidelines_analysis(task_description), - 'architecture': execute_gemini_architecture_analysis(task_description), - 'patterns': execute_gemini_pattern_analysis(task_description), - 'features': execute_gemini_feature_analysis(task_description) if applicable - } + # Check for Deep Analysis Mode first + if prompt.contains("DEEP_ANALYSIS_REQUIRED"): + # Force comprehensive Gemini analysis + execute_parallel_gemini_analysis(task_description) + gemini_context = load_consolidated_gemini_results() + skip_prd = True + skip_session_inheritance = True + force_hierarchical_decomposition = True + else: + # Standard mode: Load session context if available + if workflow_session_exists(): + session_context = load_workflow_session() + if session_context.phase == "conceptual" and session_context.status == "completed": + inherit_conceptual_context(session_context) + load_prd_from_session(session_context.checkpoints.conceptual.prd_state) + elif session_context.phase == "action" and session_context.status == "interrupted": + resume_action_planning(session_context) + + # Then: Gather additional Gemini context if needed + gemini_context = { + 'guidelines': execute_gemini_guidelines_analysis(task_description), + 'architecture': execute_gemini_architecture_analysis(task_description), + 'patterns': execute_gemini_pattern_analysis(task_description), + 'features': execute_gemini_feature_analysis(task_description) if applicable + } # Step 1: Generate session ID from task description session_id = generate_session_id(task_description) # Format: WFS-[topic-slug] @@ -373,6 +327,7 @@ Your primary responsibilities: }) # Step 4: Generate planning documents in workflow directory + # All document formats follow: @~/.claude/workflows/file-structure-standards.md combined_context = merge_contexts(session_context, gemini_context) # Merge session and Gemini contexts if (subtasks > 5 OR modules > 3 OR high_complexity): @@ -380,7 +335,7 @@ Your primary responsibilities: generate_task_decomposition(combined_context, workflow_dir) # Architecture-aligned hierarchy with session decisions generate_todo_list(combined_context, workflow_dir) # Pattern-aware task list with session continuity create_document_links() # Cross-reference linking with relative paths - create_summaries_directory(f"{workflow_dir}/.summaries/") # Summary documents structure + create_summaries_directory(f"{workflow_dir}/.summaries/") # See @~/.claude/workflows/file-structure-standards.md#summary-management update_session_action_checkpoint() # Save action phase progress elif (components > 3 OR estimated_loc > 100): generate_implementation_plan(combined_context, workflow_dir) # Session + context-aware staged plan @@ -474,6 +429,31 @@ When creating plans: - Plan for documentation updates if APIs change **Planning Output Format** (include session and Gemini context): + +**For DEEP_ANALYSIS_REQUIRED Mode**: +``` +EXECUTION_MODE: DEEP_ANALYSIS_REQUIRED + +GEMINI_ANALYSIS_RESULTS: +- Architecture Analysis: [Design patterns, component relationships, data flow] +- Code Pattern Analysis: [Conventions, error handling, validation patterns] +- Impact Analysis: [Affected files list, breaking changes, integration points] +- Testing Requirements: [Coverage needs, test patterns, validation strategies] + +IMPLEMENTATION_PLAN: +- Stages: [Technical stages based on codebase analysis] +- Files to Modify: [Exact file list from impact analysis] +- Dependencies: [Technical dependencies from architecture analysis] +- Testing Strategy: [Comprehensive test plan from testing analysis] + +OUTPUT_DOCUMENTS: +- IMPL_PLAN.md: Enhanced hierarchical implementation plan +- TODO_LIST.md: Detailed task tracking checklist +- gemini-analysis.md: Consolidated analysis results +- .task/*.json: Task definitions for complex execution +``` + +**For Standard Mode**: ``` SESSION_CONTEXT_SUMMARY: - Conceptual Phase: [Inherited strategic decisions and requirement analysis] diff --git a/.claude/agents/conceptual-planning-agent.md b/.claude/agents/conceptual-planning-agent.md index dcdbc8e8..f32ab298 100644 --- a/.claude/agents/conceptual-planning-agent.md +++ b/.claude/agents/conceptual-planning-agent.md @@ -34,6 +34,51 @@ You are a conceptual planning specialist focused on single-role strategic thinki 4. **Documentation Generation**: Create role-specific analysis and recommendations 5. **Requirements Analysis**: Generate structured requirements from the assigned role's perspective +## Gemini Analysis Integration + +### Detection and Activation +When receiving task prompt, check for GEMINI_ANALYSIS_REQUIRED flag: +- **If GEMINI_ANALYSIS_REQUIRED: true** - Execute mandatory Gemini CLI analysis +- **ASSIGNED_ROLE** - Extract the specific role for focused analysis +- **ANALYSIS_DIMENSIONS** - Load role-specific analysis dimensions + +### Execution Logic +```python +def handle_gemini_analysis(prompt): + if "GEMINI_ANALYSIS_REQUIRED: true" in prompt: + role = extract_value("ASSIGNED_ROLE", prompt) + dimensions = extract_value("ANALYSIS_DIMENSIONS", prompt) + + for dimension in dimensions: + result = execute_gemini_cli( + dimension=dimension, + role_context=role, + topic=extract_topic(prompt) + ) + integrate_to_role_output(result, role) +``` + +### Role-Specific Gemini Dimensions + +| Role | Primary Dimensions | Focus Areas | +|------|-------------------|--------------| +| system-architect | architecture_patterns, scalability_analysis, integration_points | Technical design and system structure | +| ui-designer | user_flow_patterns, component_reuse, design_system_compliance | UI/UX patterns and consistency | +| business-analyst | process_optimization, cost_analysis, efficiency_metrics, workflow_patterns | Business process and ROI | +| data-architect | data_models, flow_patterns, storage_optimization | Data structure and flow | +| security-expert | vulnerability_assessment, threat_modeling, compliance_check | Security risks and compliance | +| user-researcher | usage_patterns, pain_points, behavior_analysis | User behavior and needs | +| product-manager | feature_alignment, market_fit, competitive_analysis | Product strategy and positioning | +| innovation-lead | emerging_patterns, technology_trends, disruption_potential | Innovation opportunities | +| feature-planner | implementation_complexity, dependency_mapping, risk_assessment | Development planning | + +### Output Integration +Gemini analysis results are integrated into the single role's output: +- Enhanced `analysis.md` with codebase insights +- Role-specific technical recommendations +- Pattern-based best practices from actual code +- Realistic feasibility assessments based on current implementation + ## Task Reception Protocol ### Task Reception @@ -42,6 +87,9 @@ When called, you receive: - **User Context**: Specific requirements, constraints, and expectations from user discussion - **Output Location**: Directory path for generated analysis files - **Role Hint** (optional): Suggested role or role selection guidance +- **GEMINI_ANALYSIS_REQUIRED** (optional): Flag to trigger Gemini CLI analysis +- **ASSIGNED_ROLE** (optional): Specific role assignment +- **ANALYSIS_DIMENSIONS** (optional): Role-specific analysis dimensions ### Dynamic Role Selection When no specific role is assigned: @@ -114,8 +162,11 @@ Generate documents according to loaded role template specifications: - **Success Criteria Identification**: Determine what success looks like from this role's perspective ### 2. Analysis Phase +- **Check Gemini Flag**: If GEMINI_ANALYSIS_REQUIRED, execute Gemini CLI analysis first - **Load Role Template**: `plan-executor.sh --load ` +- **Execute Gemini Analysis** (if flagged): Run role-specific Gemini dimensions analysis - **Deep Dive Analysis**: Apply role-specific analysis framework to the challenge +- **Integrate Gemini Results**: Merge codebase insights with role perspective - **Generate Insights**: Develop recommendations and solutions from role's expertise - **Document Findings**: Create structured analysis addressing user requirements diff --git a/.claude/commands/workflow/brainstorm/business-analyst.md b/.claude/commands/workflow/brainstorm/business-analyst.md index d55f71ee..8fe1a432 100644 --- 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 -### 分析质量指标 -- [ ] 需求的完整性和准确性 -- [ ] 流程优化的量化收益 -- [ ] 风险评估的全面性 -- [ ] 实施计划的可行性 -- [ ] 利益相关者的满意度 \ No newline at end of file +### Analysis Quality Metrics +- [ ] Requirements completeness and accuracy +- [ ] Quantified benefits from process optimization +- [ ] Comprehensiveness of risk assessment +- [ ] Feasibility of implementation plan +- [ ] Stakeholder satisfaction levels \ No newline at end of file diff --git a/.claude/commands/workflow/brainstorm/innovation-lead.md b/.claude/commands/workflow/brainstorm/innovation-lead.md index f9b4a309..8ebc7369 100644 --- 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 diff --git a/.claude/commands/workflow/plan-deep.md b/.claude/commands/workflow/plan-deep.md new file mode 100644 index 00000000..75a1a1be --- /dev/null +++ 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 +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 \ No newline at end of file diff --git a/.claude/workflows/file-structure-standards.md b/.claude/workflows/file-structure-standards.md index 267acd83..e0ea919d 100644 --- a/.claude/workflows/file-structure-standards.md +++ b/.claude/workflows/file-structure-standards.md @@ -125,11 +125,17 @@ impl-2 # Another main task ### Document Template Standards #### IMPL_PLAN.md Structure + +Two formats available based on task complexity: + +##### Stage-Based Format (Simple Tasks) +Use for tasks with clear, linear progression: + ```markdown -# Implementation Plan: [Session Topic] +# Implementation Plan: [Task Name] ## Overview -[High-level description] +[Brief description of the overall goal and approach] ## Requirements [Functional and non-functional requirements] @@ -137,17 +143,95 @@ impl-2 # Another main task ## [Brainstorming Integration] [If .brainstorming/ exists - reference analysis results] -## Implementation Strategy -[Technical approach and phases] +## Stage 1: [Name] +**Goal**: [Specific deliverable] +**Success Criteria**: +- [Testable outcome 1] +- [Testable outcome 2] +**Tests**: +- [Specific test case 1] +- [Specific test case 2] +**Dependencies**: [Previous stages or external requirements] +**Estimated Effort**: [Small/Medium/Large] +**Review Status**: [Not Started] +**Status**: [Not Started] -## Success Criteria -[Acceptance criteria and validation] +## Stage 2: [Name] +[Repeat stage structure] + +## Stage 3: [Name] +[Repeat stage structure] + +## Risk Mitigation +[Identified risks and mitigation strategies] + +## Rollback Strategy +[How to revert if issues arise] +``` + +##### Hierarchical Format (Complex Tasks) +Use for tasks requiring >5 subtasks or spanning >3 modules: + +```markdown +# Implementation Plan: [Project Name] + +## Overview +[Brief description and strategic approach] + +## Requirements +[Functional and non-functional requirements] + +## Task Hierarchy + +### Main Task: [IMPL-001] [Primary Goal] +**Description**: [Detailed description] +**Complexity**: [High/Medium/Low] +**Estimated Effort**: [Time estimate] +**Dependencies**: [External dependencies] +**Status**: [Not Started] + +#### Subtask: [IMPL-001.1] [Subtask Name] +**Description**: [Specific deliverable] +**Assigned Agent**: [code-developer/code-review-agent/general-purpose] +**Dependencies**: [Parent/peer task dependencies] +**Acceptance Criteria**: +- [Testable criteria 1] +- [Testable criteria 2] +**Estimated Effort**: [Time estimate] +**Assigned Module**: [Component/file location] +**Status**: [Not Started] +**Links**: [Related documentation/requirements] + +##### Action Item: [IMPL-001.1.1] [Specific Action] +**Type**: [Code/Test/Documentation/Review] +**Recommended Agent**: [code-developer/code-review-agent/general-purpose] +**Description**: [Concrete action] +**Files Affected**: [List of files] +**Verification**: [How to verify completion] +**Status**: [Not Started] + +[Repeat structure for all tasks/subtasks/actions] + +### Main Task: [IMPL-002] [Secondary Goal] +[Repeat task structure] + +## Dependency Graph +[Visual or text representation of task dependencies] + +## Resource Requirements +[Tools, libraries, external dependencies needed] ## Risk Assessment -[Potential issues and mitigation strategies] +[Task-specific risks and mitigation strategies] + +## Rollback Strategy +[System-wide rollback procedures] ``` #### TODO_LIST.md Structure + +**Keep simple and focused on task tracking:** + ```markdown # Task Progress List: [Session Topic] @@ -159,8 +243,20 @@ impl-2 # Another main task ### Subtasks (Auto-expanded when active) - [ ] **IMPL-001.1**: [Subtask Description] → [📋 Details](./.task/impl-001.1.json) + - [ ] **IMPL-001.1.1**: [Action Item] → [📋 Details](./.task/impl-001.1.1.json) +- [ ] **IMPL-001.2**: [Subtask Description] → [📋 Details](./.task/impl-001.2.json) + +## Notes +[Quick notes and reminders for the project] ``` +**Format Notes**: +- Main tasks use bold formatting: `**IMPL-XXX**` +- Subtasks indent under parent tasks +- Links to task JSON files for details +- Links to summaries when completed +- Keep format simple and scannable + ## Chat Session Management ### Chat Directory Structure