catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-02-12 02:37:45 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: Unify workflow architecture and optimize Gemini CLI guidelines

Browse Source 
- 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 <noreply@anthropic.com>
This commit is contained in:
catlog22
2025-09-13 23:08:26 +08:00
parent b717f229a4
commit 86c9347b56
2 changed files with 58 additions and 277 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
.claude/workflows/gemini-unified.md
View File

@@ -7,7 +7,7 @@ type: technical-guideline
### 🚀 Command Overview: `gemini` ### 🚀 Command Overview: `gemini`
- **Purpose**: A CLI tool for comprehensive codebase analysis, context gathering, and pattern detection across multiple files. - **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**: - **Primary Triggers**:
- When user intent is to "analyze", "get context", or "understand the codebase". - When user intent is to "analyze", "get context", or "understand the codebase".
- When a task requires understanding relationships between multiple files. - When a task requires understanding relationships between multiple files.
@@ -24,20 +24,20 @@ type: technical-guideline
gemini [flags] -p "@{patterns} {template} prompt" gemini [flags] -p "@{patterns} {template} prompt"
``` ```
- **Key Arguments**: - **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. - `-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 - `{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. - `@{pattern}`: A special syntax for referencing files and directories.
- **Template Usage**: - **Template Usage**:
```bash ```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" 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)" 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' gemini --all-files -p "@{src/**/*} @{CLAUDE.md} $(cat <<'EOF'
$(cat ~/.claude/workflows/cli-templates/prompts/analysis/architecture.txt) $(cat ~/.claude/workflows/cli-templates/prompts/analysis/architecture.txt)
@@ -69,7 +69,7 @@ type: technical-guideline
### ⏱️ Execution Settings ### ⏱️ Execution Settings
- **Default Timeout**: Bash command execution extended to **10 minutes** to handle large codebase analysis. - **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 ### 📁 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 ### ⭐ Best Practices & Rules
@@ -170,4 +184,5 @@ These are recommended command templates for common scenarios.
- **Test patterns first**: Validate @ patterns match existing files - **Test patterns first**: Validate @ patterns match existing files
- **Prefer directory navigation**: Reduces complexity and improves performance - **Prefer directory navigation**: Reduces complexity and improves performance
- **Preserve user patterns**: When user provides @, always keep them - **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}`

306
.claude/workflows/workflow-architecture.md
View File

@@ -2,14 +2,15 @@
## Overview ## 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 ## Core Architecture Principles
### Key Design Decisions ### Key Design Decisions
- **JSON files are the single source of truth** - All markdown documents are read-only generated views - **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 - **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 - **Agent-agnostic task definitions** - Complete context preserved for autonomous execution
## Session Management ## 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 - **auto-detected**: Auto-detected based on task type and context
### Hierarchical Task System ### 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 # Main task
impl-1.1 # Subtask of impl-1 impl-1.1 # Subtask of impl-1 (dynamically created)
impl-1.1.1 # Detailed subtask of impl-1.1
impl-1.2 # Another subtask of impl-1 impl-1.2 # Another subtask of impl-1
impl-2 # Another main task impl-2 # Another main task
impl-2.1 # Subtask of impl-2 (dynamically created)
``` ```
**Task Status Rules**: **Task Status Rules**:
@@ -222,56 +223,24 @@ impl-2 # Another main task
## File Structure ## File Structure
### Progressive Structure System ### Unified File Structure
File structure scales with task complexity to minimize overhead for simple tasks while providing comprehensive organization for complex workflows. 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/WFS-[topic-slug]/
├── workflow-session.json # Session metadata and state ├── workflow-session.json # Session metadata and state
├── [.brainstorming/] # Optional brainstorming phase ├── [.brainstorming/] # Optional brainstorming phase
├── [.chat/] # Gemini CLI interaction sessions ├── .chat/ # CLI interaction sessions
├── IMPL_PLAN.md # Combined planning document │ ├── chat-*.md # Saved chat sessions
│ └── analysis-*.md # Analysis results
├── IMPL_PLAN.md # Planning document
├── TODO_LIST.md # Progress tracking
├── .summaries/ # Task completion summaries ├── .summaries/ # Task completion summaries
│ └── IMPL-*.md # Individual task summaries │ ├── IMPL-*.md # Main task summaries
│ └── IMPL-*.*.md # Subtask summaries
└── .task/ └── .task/
└── impl-*.json # Task definitions ├── impl-*.json # Main task definitions
``` └── impl-*.*.json # Subtask definitions (dynamic)
#### 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
``` ```
### File Naming Conventions ### File Naming Conventions
@@ -290,31 +259,31 @@ File structure scales with task complexity to minimize overhead for simple tasks
## Complexity Classification ## Complexity Classification
### Unified Classification Rules ### Task Complexity Rules
**Consistent thresholds across all workflow components:** **Complexity is determined by task count and decomposition needs:**
| Complexity | Task Count | Hierarchy Depth | Structure Level | Behavior | | Complexity | Task Count | Hierarchy Depth | Decomposition Behavior |
|------------|------------|----------------|-----------------|----------| |------------|------------|----------------|----------------------|
| **Simple** | <5 tasks | 1 level (impl-N) | Level 0 - Minimal | Direct execution, basic docs | | **Simple** | <5 tasks | 1 level (impl-N) | Direct execution, minimal decomposition |
| **Medium** | 5-15 tasks | 2 levels (impl-N.M) | Level 1 - Enhanced | Context coordination, TODO tracking | | **Medium** | 5-15 tasks | 2 levels (impl-N.M) | Moderate decomposition, context coordination |
| **Complex** | >15 tasks | 3 levels (impl-N.M.P) | Level 2 - Complete | Multi-agent orchestration, full docs | | **Complex** | >15 tasks | 2 levels (impl-N.M) | Frequent decomposition, multi-agent orchestration |
### Simple Workflows ### Simple Workflows
**Characteristics**: Direct implementation tasks with clear, limited scope **Characteristics**: Direct implementation tasks with clear, limited scope
- **Examples**: Bug fixes, small feature additions, configuration changes - **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 - **Agent Coordination**: Direct execution without complex orchestration
### Medium Workflows ### 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 - **Examples**: New features, API endpoints with integration, database schema changes
- **System Behavior**: Enhanced structure, two-level hierarchy, auto-triggered TODO_LIST.md - **Task Decomposition**: Two-level hierarchy when decomposition is needed
- **Auto-trigger Conditions**: Tasks >5 OR modules >3 OR effort >4h OR complex dependencies - **Agent Coordination**: Context coordination between related tasks
### Complex Workflows ### Complex Workflows
**Characteristics**: System-wide changes requiring detailed decomposition **Characteristics**: System-wide changes requiring detailed decomposition
- **Examples**: Major features, architecture refactoring, security implementations, multi-service deployments - **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 - **Agent Coordination**: Multi-agent orchestration with deep context analysis
### Automatic Assessment & Upgrades ### Automatic Assessment & Upgrades
@@ -324,61 +293,8 @@ File structure scales with task complexity to minimize overhead for simple tasks
## Document Templates ## Document Templates
### IMPL_PLAN.md Templates ### IMPL_PLAN.md
Generated based on task complexity and requirements. Contains overview, requirements, and task structure.
#### 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]
```
### TODO_LIST.md Template ### TODO_LIST.md Template
```markdown ```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**: [Main Task Group] → [📋](./.task/impl-003.json)
- [ ] **IMPL-003.1**: [Subtask] → [📋](./.task/impl-003.1.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 ## Status Legend
- `▸` = Container task (has subtasks) - `▸` = Container task (has subtasks)
- `- [ ]` = Pending leaf task - `- [ ]` = Pending leaf task
- `- [x]` = Completed leaf task - `- [x]` = Completed leaf task
- Indentation shows hierarchy (2 spaces per level) - Maximum 2 levels: Main tasks and subtasks only
## Notes ## Notes
[Optional 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 ## Data Operations
@@ -579,9 +365,9 @@ generate_todo_list_from_json .task/
### Task Integrity Rules ### Task Integrity Rules
1. **ID Uniqueness**: All task IDs must be unique 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 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 5. **Status Consistency**: Status values from defined enumeration
6. **Required Fields**: All 9 core fields must be present 6. **Required Fields**: All 9 core fields must be present
7. **Implementation Structure**: implementation.files array must contain valid file paths 7. **Implementation Structure**: implementation.files array must contain valid file paths
@@ -608,26 +394,6 @@ fi
- **Corrupted Session File**: Recreate from template - **Corrupted Session File**: Recreate from template
- **Broken Task Hierarchy**: Reconstruct parent-child relationships - **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. **System ensures**: Unified workflow architecture with ultra-fast session management, JSON-only data model, and unified file structure for all workflows regardless of complexity.