From 86c9347b56949f489bd35121ddb9c304d24b0a33 Mon Sep 17 00:00:00 2001 From: catlog22 Date: Sat, 13 Sep 2025 23:08:26 +0800 Subject: [PATCH] docs: Unify workflow architecture and optimize Gemini CLI guidelines MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Simplify workflow-architecture.md to focus on core architecture principles - Remove progressive file structures, adopt unified structure for all workflows - Reduce task hierarchy from 3 levels to 2 levels (impl-N.M max) - Eliminate non-architectural content (performance notes, detailed templates) - Emphasize dynamic task decomposition over file structure complexity - Update gemini-unified.md token limit handling guidance - Remove emphasis on --all-files as default behavior - Add explicit token limit fallback strategies with examples - Strengthen guidance for immediate retry with targeted patterns 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .claude/workflows/gemini-unified.md | 27 +- .claude/workflows/workflow-architecture.md | 308 +++------------------ 2 files changed, 58 insertions(+), 277 deletions(-) diff --git a/.claude/workflows/gemini-unified.md b/.claude/workflows/gemini-unified.md index e76b8b22..751bce56 100644 --- a/.claude/workflows/gemini-unified.md +++ b/.claude/workflows/gemini-unified.md @@ -7,7 +7,7 @@ type: technical-guideline ### 🚀 Command Overview: `gemini` - **Purpose**: A CLI tool for comprehensive codebase analysis, context gathering, and pattern detection across multiple files. -- **Directory Analysis Rule**: When user intends to analyze specific directory (cd XXX), always navigate first: `cd XXX && gemini --all-files -p "prompt"` +- **Directory Analysis Rule**: When user intends to analyze specific directory (cd XXX), always navigate first: `cd XXX && gemini -p "prompt"` - **Primary Triggers**: - When user intent is to "analyze", "get context", or "understand the codebase". - When a task requires understanding relationships between multiple files. @@ -24,20 +24,20 @@ type: technical-guideline gemini [flags] -p "@{patterns} {template} prompt" ``` - **Key Arguments**: - - `--all-files`: Includes all files in the current working directory. **Default behavior unless content limit exceeded**. + - `--all-files`: Includes all files in the current working directory - `-p`: The prompt string, which must contain file reference patterns and the analysis query. - `{template}`: Template injection using `$(cat ~/.claude/workflows/cli-templates/prompts/[category]/[template].txt)` for standardized analysis - `@{pattern}`: A special syntax for referencing files and directories. - **Template Usage**: ```bash - # Without template (manual prompt) - --all-files is default + # Without template (manual prompt) gemini --all-files -p "@{src/**/*} @{CLAUDE.md} Analyze code patterns and conventions" - # With template (recommended) - --all-files is default + # With template (recommended) gemini --all-files -p "@{src/**/*} @{CLAUDE.md} $(cat ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt)" - # Multi-template composition - --all-files is default + # Multi-template composition gemini --all-files -p "@{src/**/*} @{CLAUDE.md} $(cat <<'EOF' $(cat ~/.claude/workflows/cli-templates/prompts/analysis/architecture.txt) @@ -69,7 +69,7 @@ type: technical-guideline ### ⏱️ Execution Settings - **Default Timeout**: Bash command execution extended to **10 minutes** to handle large codebase analysis. -- **Content Limits**: When `--all-files` exceeds token limits, automatically fall back to selective `@` patterns. +- **Token Limit Handling**: When `--all-files` exceeds token limits, **remove `--all-files` and re-execute** with specific `@{patterns}` to target relevant files only. ### 📁 Templates @@ -150,6 +150,20 @@ These are recommended command templates for common scenarios. " ``` +- **Token Limit Fallback** + ```bash + # If --all-files exceeds token limits, immediately retry with targeted patterns: + + # Original command that failed: + gemini --all-files -p "Analyze authentication patterns" + + # Fallback with specific patterns: + gemini -p "@{src/auth/**/*} @{src/middleware/**/*} @{CLAUDE.md} Analyze authentication patterns" + + # Or focus on specific file types: + gemini -p "@{**/*.ts} @{**/*.js} @{CLAUDE.md} Analyze authentication patterns" + ``` + ### ⭐ Best Practices & Rules @@ -170,4 +184,5 @@ These are recommended command templates for common scenarios. - **Test patterns first**: Validate @ patterns match existing files - **Prefer directory navigation**: Reduces complexity and improves performance - **Preserve user patterns**: When user provides @, always keep them +- **Handle token limits**: If `--all-files` fails due to token limits, immediately retry without `--all-files` using targeted `@{patterns}` diff --git a/.claude/workflows/workflow-architecture.md b/.claude/workflows/workflow-architecture.md index 8fbaaf61..fc280865 100644 --- a/.claude/workflows/workflow-architecture.md +++ b/.claude/workflows/workflow-architecture.md @@ -2,14 +2,15 @@ ## Overview -This document defines the complete workflow system architecture using a **JSON-only data model**, **marker-based session management**, and **progressive file structures** that scale with task complexity. +This document defines the complete workflow system architecture using a **JSON-only data model**, **marker-based session management**, and **unified file structure** with dynamic task decomposition. ## Core Architecture Principles ### Key Design Decisions - **JSON files are the single source of truth** - All markdown documents are read-only generated views - **Marker files for session tracking** - Ultra-simple active session management -- **Progressive complexity structure** - File organization scales from simple to complex workflows +- **Unified file structure** - Same structure for all workflows regardless of complexity +- **Dynamic task decomposition** - Subtasks created as needed during execution - **Agent-agnostic task definitions** - Complete context preserved for autonomous execution ## Session Management @@ -205,14 +206,14 @@ The **implementation** field provides detailed code implementation guidance with - **auto-detected**: Auto-detected based on task type and context ### Hierarchical Task System -**Maximum Depth**: 3 levels (impl-N.M.P format) +**Maximum Depth**: 2 levels (impl-N.M format) ``` impl-1 # Main task -impl-1.1 # Subtask of impl-1 -impl-1.1.1 # Detailed subtask of impl-1.1 +impl-1.1 # Subtask of impl-1 (dynamically created) impl-1.2 # Another subtask of impl-1 impl-2 # Another main task +impl-2.1 # Subtask of impl-2 (dynamically created) ``` **Task Status Rules**: @@ -222,56 +223,24 @@ impl-2 # Another main task ## File Structure -### Progressive Structure System -File structure scales with task complexity to minimize overhead for simple tasks while providing comprehensive organization for complex workflows. +### Unified File Structure +All workflows use the same file structure regardless of complexity. Task complexity is expressed through dynamic task decomposition, not file structure variations. -#### Level 0: Minimal Structure (<5 tasks) ``` .workflow/WFS-[topic-slug]/ ├── workflow-session.json # Session metadata and state -├── [.brainstorming/] # Optional brainstorming phase -├── [.chat/] # Gemini CLI interaction sessions -├── IMPL_PLAN.md # Combined planning document +├── [.brainstorming/] # Optional brainstorming phase +├── .chat/ # CLI interaction sessions +│ ├── chat-*.md # Saved chat sessions +│ └── analysis-*.md # Analysis results +├── IMPL_PLAN.md # Planning document +├── TODO_LIST.md # Progress tracking ├── .summaries/ # Task completion summaries -│ └── IMPL-*.md # Individual task summaries +│ ├── IMPL-*.md # Main task summaries +│ └── IMPL-*.*.md # Subtask summaries └── .task/ - └── impl-*.json # Task definitions -``` - -#### Level 1: Enhanced Structure (5-15 tasks) -``` -.workflow/WFS-[topic-slug]/ -├── workflow-session.json # Session metadata and state -├── [.brainstorming/] # Optional brainstorming phase -├── [.chat/] # Gemini CLI interaction sessions -├── IMPL_PLAN.md # Combined planning document -├── TODO_LIST.md # Auto-triggered progress tracking -├── .summaries/ # Task completion summaries -│ ├── IMPL-*.md # Main task summaries -│ └── IMPL-*.*.md # Subtask summaries -└── .task/ - ├── impl-*.json # Main task definitions - └── impl-*.*.json # Subtask definitions (up to 3 levels) -``` - -#### Level 2: Complete Structure (>15 tasks) -``` -.workflow/WFS-[topic-slug]/ -├── workflow-session.json # Session metadata and state -├── [.brainstorming/] # Optional brainstorming phase -├── [.chat/] # Gemini CLI interaction sessions -│ ├── chat-*.md # Saved chat sessions -│ └── analysis-*.md # Comprehensive analysis results -├── IMPL_PLAN.md # Comprehensive planning document -├── TODO_LIST.md # Progress tracking and monitoring -├── .summaries/ # Task completion summaries -│ ├── IMPL-*.md # Main task summaries -│ ├── IMPL-*.*.md # Subtask summaries -│ └── IMPL-*.*.*.md # Detailed subtask summaries -└── .task/ - ├── impl-*.json # Task hierarchy (max 3 levels deep) - ├── impl-*.*.json # Subtasks - └── impl-*.*.*.json # Detailed subtasks + ├── impl-*.json # Main task definitions + └── impl-*.*.json # Subtask definitions (dynamic) ``` ### File Naming Conventions @@ -290,31 +259,31 @@ File structure scales with task complexity to minimize overhead for simple tasks ## Complexity Classification -### Unified Classification Rules -**Consistent thresholds across all workflow components:** +### Task Complexity Rules +**Complexity is determined by task count and decomposition needs:** -| Complexity | Task Count | Hierarchy Depth | Structure Level | Behavior | -|------------|------------|----------------|-----------------|----------| -| **Simple** | <5 tasks | 1 level (impl-N) | Level 0 - Minimal | Direct execution, basic docs | -| **Medium** | 5-15 tasks | 2 levels (impl-N.M) | Level 1 - Enhanced | Context coordination, TODO tracking | -| **Complex** | >15 tasks | 3 levels (impl-N.M.P) | Level 2 - Complete | Multi-agent orchestration, full docs | +| Complexity | Task Count | Hierarchy Depth | Decomposition Behavior | +|------------|------------|----------------|----------------------| +| **Simple** | <5 tasks | 1 level (impl-N) | Direct execution, minimal decomposition | +| **Medium** | 5-15 tasks | 2 levels (impl-N.M) | Moderate decomposition, context coordination | +| **Complex** | >15 tasks | 2 levels (impl-N.M) | Frequent decomposition, multi-agent orchestration | ### Simple Workflows **Characteristics**: Direct implementation tasks with clear, limited scope - **Examples**: Bug fixes, small feature additions, configuration changes -- **System Behavior**: Minimal structure, single-level tasks, basic planning only +- **Task Decomposition**: Usually single-level tasks, minimal breakdown needed - **Agent Coordination**: Direct execution without complex orchestration ### Medium Workflows -**Characteristics**: Feature implementation requiring task breakdown +**Characteristics**: Feature implementation requiring moderate task breakdown - **Examples**: New features, API endpoints with integration, database schema changes -- **System Behavior**: Enhanced structure, two-level hierarchy, auto-triggered TODO_LIST.md -- **Auto-trigger Conditions**: Tasks >5 OR modules >3 OR effort >4h OR complex dependencies +- **Task Decomposition**: Two-level hierarchy when decomposition is needed +- **Agent Coordination**: Context coordination between related tasks ### Complex Workflows **Characteristics**: System-wide changes requiring detailed decomposition - **Examples**: Major features, architecture refactoring, security implementations, multi-service deployments -- **System Behavior**: Complete structure, three-level hierarchy, comprehensive documentation +- **Task Decomposition**: Frequent use of two-level hierarchy with dynamic subtask creation - **Agent Coordination**: Multi-agent orchestration with deep context analysis ### Automatic Assessment & Upgrades @@ -324,61 +293,8 @@ File structure scales with task complexity to minimize overhead for simple tasks ## Document Templates -### IMPL_PLAN.md Templates - -#### Stage-Based Format (Simple Tasks) -```markdown -# Implementation Plan: [Task Name] - -## Overview -[Brief description of the overall goal and approach] - -## Requirements -[Functional and non-functional requirements] - -## Stage 1: [Name] -**Goal**: [Specific deliverable] -**Success Criteria**: -- [Testable outcome 1] -**Tests**: -- [Specific test case 1] -**Dependencies**: [Previous stages or external requirements] -**Status**: [Not Started] - -## Risk Mitigation -[Identified risks and mitigation strategies] -``` - -#### Hierarchical Format (Complex Tasks) -```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] -**Status**: [Not Started] - -#### Subtask: [IMPL-001.1] [Subtask Name] -**Description**: [Specific deliverable] -**Assigned Agent**: [code-developer/code-review-agent/general-purpose] -**Acceptance Criteria**: -- [Testable criteria 1] -**Status**: [Not Started] - -##### Action Item: [IMPL-001.1.1] [Specific Action] -**Type**: [Code/Test/Documentation/Review] -**Description**: [Concrete action] -**Files Affected**: [List of files] -**Status**: [Not Started] -``` +### IMPL_PLAN.md +Generated based on task complexity and requirements. Contains overview, requirements, and task structure. ### TODO_LIST.md Template ```markdown @@ -393,13 +309,13 @@ File structure scales with task complexity to minimize overhead for simple tasks ▸ **IMPL-003**: [Main Task Group] → [📋](./.task/impl-003.json) - [ ] **IMPL-003.1**: [Subtask] → [📋](./.task/impl-003.1.json) - - [ ] **IMPL-003.1.1**: [Sub-subtask] → [📋](./.task/impl-003.1.1.json) + - [ ] **IMPL-003.2**: [Subtask] → [📋](./.task/impl-003.2.json) ## Status Legend - `▸` = Container task (has subtasks) - `- [ ]` = Pending leaf task - `- [x]` = Completed leaf task -- Indentation shows hierarchy (2 spaces per level) +- Maximum 2 levels: Main tasks and subtasks only ## Notes [Optional notes] @@ -426,136 +342,6 @@ Agents receive complete task JSON plus workflow context: } ``` -## Analysis Method Integration - -### Supported Analysis Tools - -The workflow system supports multiple analysis methods for context gathering and code analysis: - -#### Analysis Method Selection -- **Gemini CLI**: Pattern-based codebase analysis and architectural understanding (default) -- **Codex CLI**: Autonomous development context gathering with intelligent file discovery - -#### Selection Criteria -- **Use Gemini when**: - - Need comprehensive pattern analysis and architectural understanding - - Analyzing existing code conventions and relationships - - Understanding complex module dependencies -- **Use Codex when**: - - Need autonomous file discovery and context gathering - - Working with complex refactoring scenarios - - Requiring intelligent code generation and autonomous development - -#### Analysis Method Mapping -```markdown -analysis_source → CLI Tool → Agent Marker -"gemini" → Gemini CLI → [GEMINI_CLI_REQUIRED] -"codex" → Codex CLI → [CODEX_CLI_REQUIRED] -"manual" → N/A → No marker -"auto-detected" → Context-based → [GEMINI_CLI_REQUIRED] (default) -``` - -## Gemini Analysis Integration - -### Implementation Field Population Strategy - -When task creation encounters insufficient implementation details, the system integrates with Gemini CLI for automated code analysis: - -#### Trigger Conditions -- **Missing File Paths**: No specific files identified in task scope -- **Vague Code Locations**: Generic descriptions without function/class names -- **Empty Risk Assessment**: No specific risks or dependencies identified -- **analysis_source**: Marked as "gemini" during task creation - -#### Gemini Analysis Command Template -```bash -gemini --all-files -p "@{scope-patterns} @{CLAUDE.md} -$(cat ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt) - -## Task-Specific Analysis: -Task: [task title and description] -Target Files: [scope patterns or 'auto-detect'] - -## Required Extraction: -1. **File Locations**: Identify specific files, functions, classes, line ranges -2. **Original Code**: Extract relevant code snippets that need modification -3. **Data Flow**: Map current logic flow and identify integration points -4. **Risk Assessment**: Analyze dependencies, performance impact, error scenarios -5. **Implementation Context**: Document required libraries, affected modules - -## Output Format: -- File references with :line format -- Code snippets in markdown blocks -- Flow diagrams using ───►, ◊───, ◄─── symbols -- Risk list with specific impact descriptions" -``` - -#### Analysis Result Processing -1. **Parse Gemini Output**: Extract file paths, code snippets, and analysis insights -2. **Structure Mapping**: Convert analysis results into implementation JSON structure -3. **Validation**: Ensure all required fields are populated with meaningful content -4. **Quality Check**: Verify logic_flow uses proper symbols and risks are specific - -#### Integration Points -- **Task Creation**: `/workflow:plan` and `/task:create` commands -- **Task Refinement**: `/task:replan` for updating incomplete implementation details -- **Manual Trigger**: Direct gemini analysis when implementation details are missing - -## Codex Analysis Integration - -### Autonomous Context Gathering Strategy - -When task creation specifies Codex analysis, the system integrates with Codex CLI for autonomous development context gathering: - -#### Trigger Conditions -- **analysis_source**: Marked as "codex" during task creation -- **Complex Refactoring**: Tasks involving system-wide changes or architectural modifications -- **Autonomous Development**: When intelligent file discovery and code generation is preferred - -#### Codex Analysis Command Template -```bash -codex --full-auto exec "$(cat ~/.claude/workflows/cli-templates/prompts/development/feature.txt) - -## Task-Specific Analysis: -Task: [task title and description] -Context: Autonomous analysis and implementation context gathering - -## Required Extraction: -1. **Intelligent File Discovery**: Auto-discover relevant files and code patterns -2. **Context Gathering**: Understand existing code architecture and dependencies -3. **Implementation Strategy**: Propose autonomous implementation approach -4. **Risk Assessment**: Identify potential issues and mitigation strategies - -## Autonomous Execution: -- Let Codex handle file discovery and pattern analysis -- Generate context-aware implementation guidance -- Provide autonomous development recommendations" -``` - -#### Analysis Result Processing -1. **Parse Codex Output**: Extract autonomous analysis and implementation recommendations -2. **Context Integration**: Incorporate Codex insights into task implementation field -3. **Autonomous Guidance**: Update task JSON with Codex-generated context and strategy -4. **Quality Validation**: Ensure autonomous recommendations meet project standards - -#### Integration Points -- **Task Creation**: `/workflow:plan --AM codex` command -- **Autonomous Development**: Tasks requiring intelligent code generation -- **Complex Refactoring**: System-wide changes with autonomous discovery needs - -### Implementation Field Validation - -**Required Quality Standards**: -- Each file must have specific `location.function` or `location.lines` -- `original_code` cannot be empty placeholder text -- `logic_flow` must use standard symbols: `───►` (flow), `◊───` (condition), `◄───` (return) -- `risks` array must contain at least one specific, actionable risk -- `dependencies` must list actual package names, not generic terms - -**Auto-Correction**: -- Missing line numbers → Trigger gemini re-analysis with specific file focus -- Generic risk descriptions → Request detailed impact analysis -- Empty original_code → Flag for manual code review or gemini extraction ## Data Operations @@ -579,9 +365,9 @@ generate_todo_list_from_json .task/ ### Task Integrity Rules 1. **ID Uniqueness**: All task IDs must be unique -2. **Hierarchical Format**: Must follow impl-N[.M[.P]] pattern +2. **Hierarchical Format**: Must follow impl-N[.M] pattern (maximum 2 levels) 3. **Parent References**: All parent IDs must exist as JSON files -4. **Depth Limits**: Maximum 3 levels deep +4. **Depth Limits**: Maximum 2 levels deep 5. **Status Consistency**: Status values from defined enumeration 6. **Required Fields**: All 9 core fields must be present 7. **Implementation Structure**: implementation.files array must contain valid file paths @@ -608,26 +394,6 @@ fi - **Corrupted Session File**: Recreate from template - **Broken Task Hierarchy**: Reconstruct parent-child relationships -## Performance Benefits - -### Marker File System -- **Session Detection**: Single `ls` command (< 1ms) -- **Session Switching**: Two file operations (delete + create) -- **Status Check**: File existence test (instant) -- **No Parsing Overhead**: Zero JSON/text processing - -### JSON-Only Architecture -- **Direct Access**: No document parsing overhead -- **Atomic Updates**: Single file operations -- **No Sync Conflicts**: Eliminates coordination complexity -- **Fast Queries**: Direct JSON traversal -- **Scalability**: Handles hundreds of tasks efficiently - -### On-Demand Generation -- **Memory Efficient**: Documents created only when needed -- **Always Fresh**: Generated views reflect current state -- **No Stale Data**: Eliminates sync lag issues - --- -**System ensures**: Unified workflow architecture with ultra-fast session management, JSON-only data model, and progressive file structures that scale from simple tasks to complex system-wide implementations. \ No newline at end of file +**System ensures**: Unified workflow architecture with ultra-fast session management, JSON-only data model, and unified file structure for all workflows regardless of complexity. \ No newline at end of file