+
+[]()
+[]()
+[]()
+
+*Advanced multi-agent orchestration system for autonomous software development*
+
+
+
+---
+
+## ๐ Overview
+
+The **Claude Code Workflow System** is the core engine powering CCW's intelligent development automation. It orchestrates complex software development tasks through a sophisticated multi-agent architecture, JSON-first data model, and atomic session management.
+
+### ๐๏ธ **System Architecture Components**
+
+| Component | Purpose | Key Features |
+|-----------|---------|--------------|
+| ๐ค **Multi-Agent System** | Task orchestration | Specialized agents for planning, coding, review |
+| ๐ **JSON-First Data Model** | State management | Single source of truth, atomic operations |
+| โก **Session Management** | Context preservation | Zero-overhead switching, conflict resolution |
+| ๐ **Intelligent Analysis** | Context gathering | Dual CLI integration, smart search strategies |
+| ๐ฏ **Task Decomposition** | Work organization | Core standards, complexity management |
+
+---
+
+## ๐ค Multi-Agent Architecture
+
+### **Agent Specializations**
+
+#### ๐ฏ **Conceptual Planning Agent**
+```markdown
+**Role**: Strategic planning and architectural design
+**Capabilities**:
+- High-level system architecture design
+- Technology stack recommendations
+- Risk assessment and mitigation strategies
+- Integration pattern identification
+
+**Tools**: Gemini CLI, architectural templates, brainstorming frameworks
+**Output**: Strategic plans, architecture diagrams, technology recommendations
+```
+
+#### โก **Action Planning Agent**
+```markdown
+**Role**: Converts high-level concepts into executable implementation plans
+**Capabilities**:
+- Task breakdown and decomposition
+- Dependency mapping and sequencing
+- Resource allocation planning
+- Timeline estimation and milestones
+
+**Tools**: Task templates, decomposition algorithms, dependency analyzers
+**Output**: Executable task plans, implementation roadmaps, resource schedules
+```
+
+#### ๐จโ๐ป **Code Developer Agent**
+```markdown
+**Role**: Autonomous code implementation and refactoring
+**Capabilities**:
+- Full-stack development automation
+- Pattern-based code generation
+- Refactoring and optimization
+- Integration and testing
+
+**Tools**: Codex CLI, code templates, pattern libraries, testing frameworks
+**Output**: Production-ready code, tests, documentation, deployment configs
+```
+
+#### ๐ **Code Review Agent**
+```markdown
+**Role**: Quality assurance and compliance validation
+**Capabilities**:
+- Code quality assessment
+- Security vulnerability detection
+- Performance optimization recommendations
+- Standards compliance verification
+
+**Tools**: Static analysis tools, security scanners, performance profilers
+**Output**: Quality reports, fix recommendations, compliance certificates
+```
+
+#### ๐ **Memory Gemini Bridge**
+```markdown
+**Role**: Intelligent documentation management and updates
+**Capabilities**:
+- Context-aware documentation generation
+- Knowledge base synchronization
+- Change impact analysis
+- Living documentation maintenance
+
+**Tools**: Gemini CLI, documentation templates, change analyzers
+**Output**: Updated documentation, knowledge graphs, change summaries
+```
+
+---
+
+## ๐ JSON-First Data Model
+
+### **Core Architecture Principles**
+
+#### **๐ฏ Single Source of Truth**
+```json
+{
+ "principle": "All workflow state stored in structured JSON files",
+ "benefits": [
+ "Data consistency guaranteed",
+ "No synchronization conflicts",
+ "Atomic state transitions",
+ "Version control friendly"
+ ],
+ "implementation": ".task/impl-*.json files contain complete task state"
+}
+```
+
+#### **โก Generated Views**
+```json
+{
+ "principle": "Markdown documents generated on-demand from JSON",
+ "benefits": [
+ "Always up-to-date views",
+ "No manual synchronization needed",
+ "Multiple view formats possible",
+ "Performance optimized"
+ ],
+ "examples": ["IMPL_PLAN.md", "TODO_LIST.md", "progress reports"]
+}
+```
+
+### **Task JSON Schema (5-Field Architecture)**
+
+```json
+{
+ "id": "IMPL-1.2",
+ "title": "Implement JWT authentication system",
+ "status": "pending|active|completed|blocked|container",
+
+ "meta": {
+ "type": "feature|bugfix|refactor|test|docs",
+ "agent": "code-developer|planning-agent|code-review-test-agent",
+ "priority": "high|medium|low",
+ "complexity": 1-5,
+ "estimated_hours": 8
+ },
+
+ "context": {
+ "requirements": ["JWT token generation", "Refresh token support"],
+ "focus_paths": ["src/auth", "tests/auth", "config/auth.json"],
+ "acceptance": ["JWT validation works", "Token refresh functional"],
+ "parent": "IMPL-1",
+ "depends_on": ["IMPL-1.1"],
+ "inherited": {
+ "from": "IMPL-1",
+ "context": ["Authentication system architecture completed"]
+ },
+ "shared_context": {
+ "auth_strategy": "JWT with refresh tokens",
+ "security_level": "enterprise"
+ }
+ },
+
+ "flow_control": {
+ "pre_analysis": [
+ {
+ "step": "gather_dependencies",
+ "action": "Load context from completed dependencies",
+ "command": "bash(cat .workflow/WFS-[session-id]/.summaries/IMPL-1.1-summary.md)",
+ "output_to": "dependency_context",
+ "on_error": "skip_optional"
+ },
+ {
+ "step": "discover_patterns",
+ "action": "Find existing authentication patterns",
+ "command": "bash(rg -A 2 -B 2 'class.*Auth|interface.*Auth' --type ts [focus_paths])",
+ "output_to": "auth_patterns",
+ "on_error": "skip_optional"
+ }
+ ],
+ "implementation_approach": {
+ "task_description": "Implement JWT authentication with refresh tokens...",
+ "modification_points": [
+ "Add JWT generation in login handler (src/auth/login.ts:handleLogin:75-120)",
+ "Implement validation middleware (src/middleware/auth.ts:validateToken)"
+ ],
+ "logic_flow": [
+ "User login โ validate โ generate JWT โ store refresh token",
+ "Protected access โ validate JWT โ allow/deny"
+ ]
+ },
+ "target_files": [
+ "src/auth/login.ts:handleLogin:75-120",
+ "src/middleware/auth.ts:validateToken"
+ ]
+ }
+}
+```
+
+---
+
+## โก Advanced Session Management
+
+### **Atomic Session Architecture**
+
+#### **๐ท๏ธ Marker File System**
+```bash
+# Session state managed through atomic marker files
+.workflow/
+โโโ .active-WFS-oauth2-system # Active session marker
+โโโ .active-WFS-payment-fix # Another active session
+โโโ WFS-oauth2-system/ # Session directory
+ โโโ workflow-session.json # Session metadata
+ โโโ .task/ # Task definitions
+ โโโ .summaries/ # Completion summaries
+```
+
+#### **๐ Session Operations**
+```json
+{
+ "session_creation": {
+ "operation": "atomic file creation",
+ "time_complexity": "O(1)",
+ "performance": "<10ms average"
+ },
+ "session_switching": {
+ "operation": "marker file update",
+ "time_complexity": "O(1)",
+ "performance": "<5ms average"
+ },
+ "conflict_resolution": {
+ "strategy": "last-write-wins with backup",
+ "recovery": "automatic rollback available"
+ }
+}
+```
+
+### **Session Lifecycle Management**
+
+#### **๐ Session States**
+| State | Description | Operations | Next States |
+|-------|-------------|------------|-------------|
+| `๐ created` | Initial state | start, configure | active, paused |
+| `โถ๏ธ active` | Currently executing | pause, switch | paused, completed |
+| `โธ๏ธ paused` | Temporarily stopped | resume, archive | active, archived |
+| `โ
completed` | Successfully finished | archive, restart | archived |
+| `โ error` | Error state | recover, reset | active, archived |
+| `๐ archived` | Long-term storage | restore, delete | active |
+
+---
+
+## ๐ฏ Core Task Decomposition Standards
+
+### **Revolutionary Decomposition Principles**
+
+#### **1. ๐ฏ Functional Completeness Principle**
+```yaml
+definition: "Each task must deliver a complete, independently runnable functional unit"
+requirements:
+ - All related files (logic, UI, tests, config) included
+ - Task can be deployed and tested independently
+ - Provides business value when completed
+ - Has clear acceptance criteria
+
+examples:
+ โ
correct: "User authentication system (login, JWT, middleware, tests)"
+ โ wrong: "Create login component" (incomplete functional unit)
+```
+
+#### **2. ๐ Minimum Size Threshold**
+```yaml
+definition: "Single task must contain at least 3 related files or 200 lines of code"
+rationale: "Prevents over-fragmentation and context switching overhead"
+enforcement:
+ - Tasks below threshold must be merged with adjacent features
+ - Exception: Critical configuration or security files
+ - Measured after task completion for validation
+
+examples:
+ โ
correct: "Payment system (gateway, validation, UI, tests, config)" # 5 files, 400+ lines
+ โ wrong: "Update README.md" # 1 file, <50 lines - merge with related task
+```
+
+#### **3. ๐ Dependency Cohesion Principle**
+```yaml
+definition: "Tightly coupled components must be completed in the same task"
+identification:
+ - Shared data models or interfaces
+ - Same API endpoint (frontend + backend)
+ - Single user workflow components
+ - Components that fail together
+
+examples:
+ โ
correct: "Order processing (model, API, validation, UI, tests)" # Tightly coupled
+ โ wrong: "Order model" + "Order API" as separate tasks # Will break separately
+```
+
+#### **4. ๐ Hierarchy Control Rule**
+```yaml
+definition: "Clear structure guidelines based on task count"
+rules:
+ flat_structure: "โค5 tasks - single level hierarchy (IMPL-1, IMPL-2, ...)"
+ hierarchical_structure: "6-10 tasks - two level hierarchy (IMPL-1.1, IMPL-1.2, ...)"
+ re_scope_required: ">10 tasks - mandatory re-scoping into multiple iterations"
+
+enforcement:
+ - Hard limit prevents unmanageable complexity
+ - Forces proper planning and scoping
+ - Enables effective progress tracking
+```
+
+---
+
+## ๐ Intelligent Analysis System
+
+### **Dual CLI Integration Strategy**
+
+#### **๐ง Gemini CLI (Analysis & Investigation)**
+```yaml
+primary_use: "Deep codebase analysis, pattern recognition, context gathering"
+strengths:
+ - Large context window (2M+ tokens)
+ - Excellent pattern recognition
+ - Cross-module relationship analysis
+ - Architectural understanding
+
+optimal_tasks:
+ - "Analyze authentication patterns across entire codebase"
+ - "Understand module relationships and dependencies"
+ - "Find similar implementations for reference"
+ - "Identify architectural inconsistencies"
+
+command_examples:
+ - "~/.claude/scripts/gemini-wrapper -p 'Analyze patterns in auth module'"
+ - "gemini --all-files -p 'Review overall system architecture'"
+```
+
+#### **๐ค Codex CLI (Development & Implementation)**
+```yaml
+primary_use: "Autonomous development, code generation, implementation"
+strengths:
+ - Mathematical reasoning and optimization
+ - Security vulnerability assessment
+ - Performance analysis and tuning
+ - Autonomous feature development
+
+optimal_tasks:
+ - "Implement complete payment processing system"
+ - "Optimize database queries for performance"
+ - "Add comprehensive security validation"
+ - "Refactor code for better maintainability"
+
+command_examples:
+ - "codex --full-auto exec 'Implement JWT authentication system'"
+ - "codex --full-auto exec 'Optimize API performance bottlenecks'"
+```
+
+### **๐ Advanced Search Strategies**
+
+#### **Pattern Discovery Commands**
+```json
+{
+ "authentication_patterns": {
+ "command": "rg -A 3 -B 3 'authenticate|login|jwt|auth' --type ts --type js | head -50",
+ "purpose": "Discover authentication patterns with context",
+ "output": "Patterns with surrounding code for analysis"
+ },
+
+ "interface_extraction": {
+ "command": "rg '^\\s*interface\\s+\\w+' --type ts -A 5 | awk '/interface/{p=1} p&&/^}/{p=0;print}'",
+ "purpose": "Extract TypeScript interface definitions",
+ "output": "Complete interface definitions for analysis"
+ },
+
+ "dependency_analysis": {
+ "command": "rg '^import.*from.*auth' --type ts | awk -F'from' '{print $2}' | sort | uniq -c",
+ "purpose": "Analyze import dependencies for auth modules",
+ "output": "Sorted list of authentication dependencies"
+ }
+}
+```
+
+#### **Combined Analysis Pipelines**
+```bash
+# Multi-stage analysis pipeline
+step1="find . -name '*.ts' -o -name '*.js' | xargs rg -l 'auth|jwt' 2>/dev/null"
+step2="rg '^\\s*(function|const\\s+\\w+\\s*=)' --type ts [files_from_step1]"
+step3="awk '/^[[:space:]]*interface/{p=1} p&&/^[[:space:]]*}/{p=0;print}' [output]"
+
+# Context merging command
+echo "Files: [$step1]; Functions: [$step2]; Interfaces: [$step3]" > combined_analysis.txt
+```
+
+---
+
+## ๐ Performance & Optimization
+
+### **System Performance Metrics**
+
+| Operation | Target Performance | Current Performance | Optimization Strategy |
+|-----------|-------------------|-------------------|----------------------|
+| ๐ **Session Switch** | <10ms | <5ms average | Atomic file operations |
+| ๐ **JSON Query** | <1ms | <0.5ms average | Direct JSON access |
+| ๐ **Context Load** | <5s | <3s average | Intelligent caching |
+| ๐ **Doc Update** | <30s | <20s average | Targeted updates only |
+| โก **Task Execute** | 10min timeout | Variable | Parallel agent execution |
+
+### **Optimization Strategies**
+
+#### **๐ Performance Enhancements**
+```yaml
+json_operations:
+ strategy: "Direct JSON manipulation without parsing overhead"
+ benefit: "Sub-millisecond query response times"
+ implementation: "Native file system operations"
+
+session_management:
+ strategy: "Atomic marker file operations"
+ benefit: "Zero-overhead context switching"
+ implementation: "Single file create/delete operations"
+
+context_caching:
+ strategy: "Intelligent context preservation"
+ benefit: "Faster subsequent operations"
+ implementation: "Memory-based caching with invalidation"
+
+parallel_execution:
+ strategy: "Multi-agent parallel task processing"
+ benefit: "Reduced overall execution time"
+ implementation: "Async agent coordination with dependency management"
+```
+
+---
+
+## ๐ ๏ธ Development & Extension Guide
+
+### **Adding New Agents**
+
+#### **Agent Development Template**
+```markdown
+# Agent: [Agent Name]
+
+## Purpose
+[Clear description of agent's role and responsibilities]
+
+## Capabilities
+- [Specific capability 1]
+- [Specific capability 2]
+- [Specific capability 3]
+
+## Tools & Integration
+- **Primary CLI**: [Gemini|Codex|Both]
+- **Templates**: [List of template files used]
+- **Output Format**: [JSON schema or format description]
+
+## Task Assignment Logic
+```yaml
+triggers:
+ - keyword: "[keyword pattern]"
+ - task_type: "[feature|bugfix|refactor|test|docs]"
+ - complexity: "[1-5 scale]"
+assignment_priority: "[high|medium|low]"
+```
+
+## Implementation
+[Code structure and key files]
+```
+
+#### **Command Development Pattern**
+```yaml
+command_structure:
+ frontmatter:
+ name: "[command-name]"
+ description: "[clear description]"
+ usage: "[syntax pattern]"
+ examples: "[usage examples]"
+
+ content_sections:
+ - "## Purpose and Scope"
+ - "## Command Syntax"
+ - "## Execution Flow"
+ - "## Integration Points"
+ - "## Error Handling"
+
+file_naming: "[category]/[command-name].md"
+location: ".claude/commands/[category]/"
+```
+
+### **Template System Extension**
+
+#### **Template Categories**
+```yaml
+analysis_templates:
+ location: ".claude/workflows/cli-templates/prompts/analysis/"
+ purpose: "Pattern recognition, architectural understanding"
+ primary_tool: "Gemini"
+
+development_templates:
+ location: ".claude/workflows/cli-templates/prompts/development/"
+ purpose: "Code generation, implementation"
+ primary_tool: "Codex"
+
+planning_templates:
+ location: ".claude/workflows/cli-templates/prompts/planning/"
+ purpose: "Strategic planning, task breakdown"
+ tools: "Cross-tool compatible"
+
+role_templates:
+ location: ".claude/workflows/cli-templates/planning-roles/"
+ purpose: "Specialized perspective templates"
+ usage: "Brainstorming and strategic planning"
+```
+
+---
+
+## ๐ง Configuration & Customization
+
+### **System Configuration Files**
+
+#### **Core Configuration**
+```json
+// .claude/settings.local.json
+{
+ "session_management": {
+ "max_concurrent_sessions": 5,
+ "auto_cleanup_days": 30,
+ "backup_frequency": "daily"
+ },
+
+ "performance": {
+ "token_limit_gemini": 2000000,
+ "execution_timeout": 600000,
+ "cache_retention_hours": 24
+ },
+
+ "agent_preferences": {
+ "default_code_agent": "code-developer",
+ "default_analysis_agent": "conceptual-planning-agent",
+ "parallel_execution": true
+ },
+
+ "cli_integration": {
+ "gemini_wrapper_path": "~/.claude/scripts/gemini-wrapper",
+ "codex_command": "codex --full-auto exec",
+ "auto_approval_modes": true
+ }
+}
+```
+
+### **Custom Agent Configuration**
+
+#### **Agent Priority Matrix**
+```yaml
+task_assignment_rules:
+ feature_development:
+ primary: "code-developer"
+ secondary: "action-planning-agent"
+ review: "code-review-test-agent"
+
+ bug_analysis:
+ primary: "conceptual-planning-agent"
+ secondary: "code-developer"
+ review: "code-review-test-agent"
+
+ architecture_planning:
+ primary: "conceptual-planning-agent"
+ secondary: "action-planning-agent"
+ documentation: "memory-gemini-bridge"
+
+complexity_routing:
+ simple_tasks: "direct_execution" # Skip planning phase
+ medium_tasks: "standard_workflow" # Full planning + execution
+ complex_tasks: "multi_agent_orchestration" # All agents coordinated
+```
+
+---
+
+## ๐ Advanced Usage Patterns
+
+### **Enterprise Workflows**
+
+#### **๐ข Large-Scale Development**
+```bash
+# Multi-team coordination workflow
+/workflow:session:start "Microservices Migration Initiative"
+
+# Comprehensive analysis phase
+/workflow:brainstorm "microservices architecture strategy" \
+ --perspectives=system-architect,data-architect,security-expert,ui-designer
+
+# Parallel team planning
+/workflow:plan-deep "service decomposition" --complexity=high --depth=3
+/task:breakdown IMPL-1 --strategy=auto --depth=2
+
+# Coordinated implementation
+/codex:mode:auto "Implement user service microservice with full test coverage"
+/codex:mode:auto "Implement payment service microservice with integration tests"
+/codex:mode:auto "Implement notification service microservice with monitoring"
+
+# Cross-service integration
+/workflow:review --auto-fix
+/update-memory-full
+```
+
+#### **๐ Security-First Development**
+```bash
+# Security-focused workflow
+/workflow:session:start "Security Hardening Initiative"
+
+# Security analysis
+/workflow:brainstorm "application security assessment" \
+ --perspectives=security-expert,system-architect
+
+# Threat modeling and implementation
+/gemini:analyze "security vulnerabilities and threat vectors"
+/codex:mode:auto "Implement comprehensive security controls based on threat model"
+
+# Security validation
+/workflow:review --auto-fix
+/gemini:mode:bug-index "Verify all security controls are properly implemented"
+```
+
+---
+
+## ๐ฏ Best Practices & Guidelines
+
+### **Development Best Practices**
+
+#### **๐ Task Planning Guidelines**
+```yaml
+effective_planning:
+ - "Start with business value, not technical implementation"
+ - "Use brainstorming for complex or unfamiliar domains"
+ - "Always validate task decomposition against the 4 core standards"
+ - "Include integration and testing in every task"
+ - "Plan for rollback and error scenarios"
+
+task_sizing:
+ - "Aim for 1-3 day completion per task"
+ - "Include all related files in single task"
+ - "Consider deployment and configuration requirements"
+ - "Plan for documentation and knowledge transfer"
+
+quality_gates:
+ - "Every task must include tests"
+ - "Security review required for user-facing features"
+ - "Performance testing for critical paths"
+ - "Documentation updates for public APIs"
+```
+
+#### **๐ Analysis Best Practices**
+```yaml
+effective_analysis:
+ - "Use Gemini for understanding, Codex for implementation"
+ - "Start with project structure analysis"
+ - "Identify 3+ similar patterns before implementing new ones"
+ - "Document assumptions and decisions"
+ - "Validate analysis with targeted searches"
+
+context_gathering:
+ - "Load complete context before making changes"
+ - "Use focus_paths for targeted analysis"
+ - "Leverage free exploration phase for edge cases"
+ - "Combine multiple search strategies"
+ - "Cache and reuse analysis results"
+```
+
+### **๐จ Common Pitfalls & Solutions**
+
+| Pitfall | Impact | Solution |
+|---------|--------|----------|
+| **Over-fragmented tasks** | Context switching overhead | Apply 4 core decomposition standards |
+| **Missing dependencies** | Build failures, integration issues | Use dependency analysis commands |
+| **Insufficient context** | Poor implementation quality | Leverage free exploration phase |
+| **Inconsistent patterns** | Maintenance complexity | Always find 3+ similar implementations |
+| **Missing tests** | Quality and regression issues | Include testing in every task |
+
+---
+
+## ๐ฎ Future Enhancements & Roadmap
+
+### **Planned Improvements**
+
+#### **๐ง Enhanced AI Integration**
+```yaml
+advanced_reasoning:
+ - "Multi-step reasoning chains for complex problems"
+ - "Self-correcting analysis with validation loops"
+ - "Cross-agent knowledge sharing and learning"
+
+intelligent_automation:
+ - "Predictive task decomposition based on project history"
+ - "Automatic pattern detection and application"
+ - "Context-aware template selection and customization"
+```
+
+#### **โก Performance Optimization**
+```yaml
+performance_enhancements:
+ - "Distributed agent execution across multiple processes"
+ - "Intelligent caching with dependency invalidation"
+ - "Streaming analysis results for large codebases"
+
+scalability_improvements:
+ - "Support for multi-repository workflows"
+ - "Enterprise-grade session management"
+ - "Team collaboration and shared sessions"
+```
+
+#### **๐ง Developer Experience**
+```yaml
+dx_improvements:
+ - "Visual workflow designer and editor"
+ - "Interactive task breakdown with AI assistance"
+ - "Real-time collaboration and code review"
+ - "Integration with popular IDEs and development tools"
+```
+
+---
+
+
+
+## ๐ฏ **CCW Workflow System**
+
+*Advanced multi-agent orchestration for autonomous software development*
+
+**Built for developers, by developers, with AI-first principles**
+
+[](../README.md)
+[](https://github.com/catlog22/Claude-Code-Workflow/wiki)
+
+
\ No newline at end of file
diff --git a/README.md b/README.md
index d24c7421..6bb7ee98 100644
--- a/README.md
+++ b/README.md
@@ -1,54 +1,70 @@
-# Claude Code Workflow (CCW)
+# ๐ Claude Code Workflow (CCW)
-
+
+
+[](https://github.com/catlog22/Claude-Code-Workflow/releases)
+[](LICENSE)
+[]()
**Languages:** [English](README.md) | [ไธญๆ](README_CN.md)
-A comprehensive multi-agent automation framework for software development that orchestrates complex development tasks through intelligent workflow management and autonomous execution.
+---
-> **๐ฆ Latest Release v1.2**: Enhanced workflow diagrams, intelligent task saturation control, path-specific analysis system, and comprehensive documentation updates with detailed mermaid visualizations. See [CHANGELOG.md](CHANGELOG.md) for details.
+## ๐ Overview
-## Architecture Overview
+**Claude Code Workflow (CCW)** is a next-generation multi-agent automation framework for software development that orchestrates complex development tasks through intelligent workflow management and autonomous execution.
-Claude Code Workflow (CCW) is built on three core architectural principles enhanced with intelligent workflow orchestration:
+> **๐ฏ Latest Release v1.3**: Enhanced task decomposition standards, advanced search strategies with bash command combinations, free exploration phases for agents, and comprehensive workflow system improvements. See [CHANGELOG.md](CHANGELOG.md) for details.
-### **System Architecture Visualization**
+### ๐ Key Innovations
+
+- **๐ง Intelligent Task Decomposition**: New core standards prevent over-fragmentation with functional completeness principles
+- **๐ Advanced Search Strategies**: Powerful command combinations using ripgrep, grep, find, awk, sed for comprehensive analysis
+- **โก Free Exploration Phase**: Agents can gather supplementary context after structured analysis
+- **๐ฏ JSON-First Architecture**: Single source of truth with atomic session management
+- **๐ค Dual CLI Integration**: Gemini for analysis, Codex for autonomous development
+
+---
+
+## ๐๏ธ System Architecture
+
+### **๐ง Core Architectural Principles**
```mermaid
graph TB
- subgraph "CLI Interface Layer"
+ subgraph "๐ฅ๏ธ CLI Interface Layer"
CLI[CLI Commands]
GEM[Gemini CLI]
COD[Codex CLI]
- WRAPPER[Gemini Wrapper]
+ WRAPPER[Intelligent Gemini Wrapper]
end
- subgraph "Session Management"
- MARKER[".active-session marker"]
+ subgraph "๐ Session Management"
+ MARKER[".active-session markers"]
SESSION["workflow-session.json"]
WDIR[".workflow/ directories"]
end
- subgraph "Task System"
+ subgraph "๐ JSON-First Task System"
TASK_JSON[".task/impl-*.json"]
HIERARCHY["Task Hierarchy (max 2 levels)"]
STATUS["Task Status Management"]
+ DECOMP["Task Decomposition Engine"]
end
- subgraph "Agent Orchestration"
+ subgraph "๐ค Multi-Agent Orchestration"
PLAN_AGENT[Conceptual Planning Agent]
ACTION_AGENT[Action Planning Agent]
- CODE_AGENT[Code Developer]
+ CODE_AGENT[Code Developer Agent]
REVIEW_AGENT[Code Review Agent]
MEMORY_AGENT[Memory Gemini Bridge]
end
- CLI --> GEM
- CLI --> COD
CLI --> WRAPPER
WRAPPER --> GEM
+ CLI --> COD
GEM --> PLAN_AGENT
COD --> CODE_AGENT
@@ -57,459 +73,337 @@ graph TB
ACTION_AGENT --> TASK_JSON
CODE_AGENT --> TASK_JSON
- TASK_JSON --> HIERARCHY
+ TASK_JSON --> DECOMP
+ DECOMP --> HIERARCHY
HIERARCHY --> STATUS
SESSION --> MARKER
MARKER --> WDIR
```
-### **JSON-First Data Model**
-- **Single Source of Truth**: All workflow states and task definitions stored in structured `.task/impl-*.json` files
-- **Task-Specific Paths**: New `paths` field enables precise CLI analysis targeting concrete project paths
-- **Generated Views**: Markdown documents created on-demand from JSON data sources
-- **Data Consistency**: Eliminates synchronization issues through centralized data management
-- **Performance**: Direct JSON operations with sub-millisecond query response times
+### ๐๏ธ **Three-Pillar Foundation**
-### **Atomic Session Management**
-- **Marker File System**: Session state managed through atomic `.workflow/.active-[session]` files
-- **Instant Context Switching**: Zero-overhead session management and switching
-- **Conflict Resolution**: Automatic detection and resolution of session state conflicts
-- **Scalability**: Support for concurrent sessions without performance degradation
+| ๐๏ธ **JSON-First Data Model** | โก **Atomic Session Management** | ๐งฉ **Adaptive Complexity** |
+|---|---|---|
+| Single source of truth | Marker-based session state | Auto-adjusts to project size |
+| Sub-millisecond queries | Zero-overhead switching | Simple โ Medium โ Complex |
+| Generated Markdown views | Conflict-free concurrency | Task limit enforcement |
+| Data consistency guaranteed | Instant context switching | Intelligent decomposition |
-### **Adaptive Complexity Management**
-CCW automatically adjusts workflow structure based on project complexity:
+---
-| Complexity Level | Task Count | Structure | Features |
-|------------------|------------|-----------|----------|
-| **Simple** | <5 tasks | Single-level hierarchy | Minimal overhead, direct execution |
-| **Medium** | 5-15 tasks | Two-level task breakdown | Progress tracking, automated documentation |
-| **Complex** | >15 tasks | Three-level deep hierarchy | Full orchestration, multi-agent coordination |
+## โจ Major Enhancements v1.3
-## Major Enhancements Since v1.0
+### ๐ฏ **Core Task Decomposition Standards**
+Revolutionary task decomposition system with four core principles:
-### **๐ Intelligent Task Saturation Control**
-Advanced workflow planning prevents agent overload and optimizes task distribution across the system.
+1. **๐ฏ Functional Completeness Principle** - Complete, runnable functional units
+2. **๐ Minimum Size Threshold** - 3+ files or 200+ lines minimum
+3. **๐ Dependency Cohesion Principle** - Tightly coupled components together
+4. **๐ Hierarchy Control Rule** - Flat โค5, hierarchical 6-10, re-scope >10
-### **๐ง Gemini Wrapper Intelligence**
-Smart wrapper automatically manages token limits and approval modes based on task analysis:
-- Analysis keywords โ `--approval-mode default`
-- Development tasks โ `--approval-mode yolo`
-- Automatic `--all-files` flag management based on project size
+### ๐ **Advanced Search Strategies**
+Powerful command combinations for comprehensive codebase analysis:
-### **๐ฏ Path-Specific Analysis System**
-New task-specific path management enables precise CLI analysis targeting concrete project paths instead of wildcards.
+```bash
+# Pattern discovery with context
+rg -A 3 -B 3 'authenticate|login|jwt' --type ts --type js | head -50
-### **๐ Unified Template System**
-Cross-tool template compatibility with shared template library supporting both Gemini and Codex workflows.
+# Multi-tool analysis pipeline
+find . -name '*.ts' | xargs rg -l 'auth' | head -15
-### **โก Enhanced Performance**
-- Sub-millisecond JSON query response times
-- 10-minute execution timeout for complex operations
-- On-demand file creation reduces initialization overhead
-
-### **Command Execution Flow**
-
-```mermaid
-sequenceDiagram
- participant User
- participant CLI
- participant GeminiWrapper as Gemini Wrapper
- participant GeminiCLI as Gemini CLI
- participant CodexCLI as Codex CLI
- participant Agent
- participant TaskSystem as Task System
- participant FileSystem as File System
-
- User->>CLI: Command Request
- CLI->>CLI: Parse Command Type
-
- alt Analysis Task
- CLI->>GeminiWrapper: Analysis Request
- GeminiWrapper->>GeminiWrapper: Check Token Limit
- GeminiWrapper->>GeminiWrapper: Set Approval Mode
- GeminiWrapper->>GeminiCLI: Execute Analysis
- GeminiCLI->>FileSystem: Read Codebase
- GeminiCLI->>Agent: Route to Planning Agent
- else Development Task
- CLI->>CodexCLI: Development Request
- CodexCLI->>Agent: Route to Code Agent
- end
-
- Agent->>TaskSystem: Create/Update Tasks
- TaskSystem->>FileSystem: Save task JSON
- Agent->>Agent: Execute Task Logic
- Agent->>FileSystem: Apply Changes
- Agent->>TaskSystem: Update Task Status
- TaskSystem->>FileSystem: Regenerate Markdown Views
- Agent->>CLI: Return Results
- CLI->>User: Display Results
+# Interface extraction with awk
+rg '^\\s*interface\\s+\\w+' --type ts -A 5 | awk '/interface/{p=1} p&&/^}/{p=0;print}'
```
-## Complete Development Workflow Examples
+### ๐ **Free Exploration Phase**
+Agents can enter supplementary context gathering using bash commands (grep, find, rg, awk, sed) after completing structured pre-analysis steps.
+
+### ๐ง **Intelligent Gemini Wrapper**
+Smart automation with token management and approval modes:
+- **Analysis Detection**: Keywords trigger `--approval-mode default`
+- **Development Detection**: Action words trigger `--approval-mode yolo`
+- **Auto Token Management**: Handles `--all-files` based on project size
+- **Error Logging**: Comprehensive error tracking and recovery
+
+---
+
+## ๐ Complexity Management System
+
+CCW automatically adapts workflow structure based on project complexity:
+
+| **Complexity** | **Task Count** | **Structure** | **Features** |
+|---|---|---|---|
+| ๐ข **Simple** | <5 tasks | Single-level | Minimal overhead, direct execution |
+| ๐ก **Medium** | 5-10 tasks | Two-level hierarchy | Progress tracking, automated docs |
+| ๐ด **Complex** | >10 tasks | Force re-scoping | Multi-iteration planning required |
+
+---
+
+## ๐ ๏ธ Complete Command Reference
+
+### ๐ฎ **Core System Commands**
+
+| Command | Function | Example |
+|---------|----------|---------|
+| `๐ฏ /enhance-prompt` | Technical context enhancement | `/enhance-prompt "add auth system"` |
+| `๐ /context` | Unified context management | `/context --analyze --format=tree` |
+| `๐ /update-memory-full` | Complete documentation update | `/update-memory-full` |
+| `๐ /update-memory-related` | Smart context-aware updates | `/update-memory-related` |
+
+### ๐ **Gemini CLI Commands** (Analysis & Investigation)
+
+| Command | Purpose | Usage |
+|---------|---------|-------|
+| `๐ /gemini:analyze` | Deep codebase analysis | `/gemini:analyze "authentication patterns"` |
+| `๐ฌ /gemini:chat` | Direct Gemini interaction | `/gemini:chat "explain this architecture"` |
+| `โก /gemini:execute` | Intelligent execution | `/gemini:execute task-001` |
+| `๐ฏ /gemini:mode:auto` | Auto template selection | `/gemini:mode:auto "analyze security"` |
+| `๐ /gemini:mode:bug-index` | Bug analysis workflow | `/gemini:mode:bug-index "payment fails"` |
+
+### ๐ค **Codex CLI Commands** (Development & Implementation)
+
+| Command | Purpose | Usage |
+|---------|---------|-------|
+| `๐ /codex:analyze` | Development analysis | `/codex:analyze "optimization opportunities"` |
+| `๐ฌ /codex:chat` | Direct Codex interaction | `/codex:chat "implement JWT auth"` |
+| `โก /codex:execute` | Controlled development | `/codex:execute "refactor user service"` |
+| `๐ /codex:mode:auto` | **PRIMARY**: Full autonomous | `/codex:mode:auto "build payment system"` |
+| `๐ /codex:mode:bug-index` | Autonomous bug fixing | `/codex:mode:bug-index "fix race condition"` |
+
+### ๐ฏ **Workflow Management**
+
+#### ๐ Session Management
+| Command | Function | Usage |
+|---------|----------|-------|
+| `๐ /workflow:session:start` | Create new session | `/workflow:session:start "OAuth2 System"` |
+| `โธ๏ธ /workflow:session:pause` | Pause current session | `/workflow:session:pause` |
+| `โถ๏ธ /workflow:session:resume` | Resume session | `/workflow:session:resume "OAuth2 System"` |
+| `๐ /workflow:session:list` | List all sessions | `/workflow:session:list --active` |
+| `๐ /workflow:session:switch` | Switch sessions | `/workflow:session:switch "Payment Fix"` |
+
+#### ๐ฏ Workflow Operations
+| Command | Function | Usage |
+|---------|----------|-------|
+| `๐ญ /workflow:brainstorm` | Multi-agent planning | `/workflow:brainstorm "microservices architecture"` |
+| `๐ /workflow:plan` | Convert to executable plans | `/workflow:plan --from-brainstorming` |
+| `๐ /workflow:plan-deep` | Deep architectural planning | `/workflow:plan-deep "API redesign" --complexity=high` |
+| `โก /workflow:execute` | Implementation phase | `/workflow:execute --type=complex` |
+| `โ
/workflow:review` | Quality assurance | `/workflow:review --auto-fix` |
+
+#### ๐ท๏ธ Task Management
+| Command | Function | Usage |
+|---------|----------|-------|
+| `โ /task:create` | Create implementation task | `/task:create "User Authentication"` |
+| `๐ /task:breakdown` | Decompose into subtasks | `/task:breakdown IMPL-1 --depth=2` |
+| `โก /task:execute` | Execute specific task | `/task:execute IMPL-1.1 --mode=auto` |
+| `๐ /task:replan` | Adapt to changes | `/task:replan IMPL-1 --strategy=adjust` |
+
+---
+
+## ๐ฏ Complete Development Workflows
+
+### ๐ **Complex Feature Development**
-### ๐ **Complex Feature Development Flow**
```mermaid
graph TD
- START[New Feature Request] --> SESSION["/workflow:session:start 'OAuth2 System'"]
+ START[๐ฏ New Feature Request] --> SESSION["/workflow:session:start 'OAuth2 System'"]
SESSION --> BRAINSTORM["/workflow:brainstorm --perspectives=system-architect,security-expert"]
- BRAINSTORM --> SYNTHESIS["/workflow:brainstorm:synthesis"]
- SYNTHESIS --> PLAN["/workflow:plan --from-brainstorming"]
+ BRAINSTORM --> PLAN["/workflow:plan --from-brainstorming"]
PLAN --> EXECUTE["/workflow:execute --type=complex"]
- EXECUTE --> TASKS["/task:breakdown impl-1 --depth=2"]
- TASKS --> IMPL["/task:execute impl-1.1"]
- IMPL --> REVIEW["/workflow:review --auto-fix"]
+ EXECUTE --> REVIEW["/workflow:review --auto-fix"]
REVIEW --> DOCS["/update-memory-related"]
+ DOCS --> COMPLETE[โ
Complete]
```
-### ๐ฏ **Planning Method Selection Guide**
-| Project Type | Recommended Flow | Commands |
-|--------------|------------------|----------|
-| **Bug Fix** | Direct Planning | `/workflow:plan` โ `/task:execute` |
-| **Small Feature** | Gemini Analysis | `/gemini:mode:plan` โ `/workflow:execute` |
-| **Medium Feature** | Document + Gemini | Review docs โ `/gemini:analyze` โ `/workflow:plan` |
-| **Large System** | Full Brainstorming | `/workflow:brainstorm` โ synthesis โ `/workflow:plan-deep` |
+### ๐ฅ **Quick Development Examples**
-> ๐ **Comprehensive Workflow Diagrams**: For detailed system architecture, agent coordination, session management, and complete workflow variations, see [WORKFLOW_DIAGRAMS.md](WORKFLOW_DIAGRAMS.md).
+#### **๐ Full Stack Feature Implementation**
+```bash
+# 1. Initialize focused session
+/workflow:session:start "User Dashboard Feature"
-## Core Components
+# 2. Multi-perspective analysis
+/workflow:brainstorm "dashboard analytics system" \
+ --perspectives=system-architect,ui-designer,data-architect
-### Multi-Agent System
-- **Conceptual Planning Agent**: Strategic planning and architectural design
-- **Action Planning Agent**: Converts high-level concepts into executable implementation plans
-- **Code Developer**: Autonomous code implementation and refactoring
-- **Code Review Agent**: Quality assurance and compliance validation
-- **Memory Gemini Bridge**: Intelligent documentation management and updates
+# 3. Generate executable plan with task decomposition
+/workflow:plan --from-brainstorming
-### Dual CLI Integration
-- **Gemini CLI**: Deep codebase analysis, pattern recognition, and investigation workflows
-- **Codex CLI**: Autonomous development, code generation, and implementation automation
-- **Task-Specific Targeting**: Precise path management for focused analysis (replaces `--all-files`)
-- **Template System**: Unified template library for consistent workflow execution
-- **Cross-Platform Support**: Windows and Linux compatibility with unified path handling
+# 4. Autonomous implementation
+/codex:mode:auto "Implement user dashboard with analytics, charts, and real-time data"
-### Workflow Session Management
-- **Session Lifecycle**: Create, pause, resume, switch, and manage development sessions
-- **Context Preservation**: Maintains complete workflow state across session transitions
-- **Hierarchical Organization**: Structured workflow filesystem with automatic initialization
+# 5. Quality assurance and deployment
+/workflow:review --auto-fix
+/update-memory-related
+```
-### Intelligent Documentation System
-- **Living Documentation**: Four-tier hierarchical CLAUDE.md system that updates automatically
-- **Git Integration**: Context-aware updates based on repository changes
-- **Dual Update Modes**:
- - `related`: Updates only modules affected by recent changes
- - `full`: Complete project-wide documentation refresh
+#### **โก Rapid Bug Resolution**
+```bash
+# Quick bug fix workflow
+/workflow:session:start "Payment Processing Fix"
+/gemini:mode:bug-index "Payment validation fails on concurrent requests"
+/codex:mode:auto "Fix race condition in payment validation with proper locking"
+/workflow:review --auto-fix
+```
-## Installation
+#### **๐ Architecture Analysis & Refactoring**
+```bash
+# Deep architecture work
+/workflow:session:start "API Refactoring Initiative"
+/gemini:analyze "current API architecture patterns and technical debt"
+/workflow:plan-deep "microservices transition" --complexity=high --depth=3
+/codex:mode:auto "Refactor monolith to microservices following the analysis"
+```
-### Quick Installation
+---
+
+## ๐๏ธ Project Structure
+
+```
+๐ .claude/
+โโโ ๐ค agents/ # AI agent definitions
+โโโ ๐ฏ commands/ # CLI command implementations
+โ โโโ ๐ gemini/ # Gemini CLI commands
+โ โโโ ๐ค codex/ # Codex CLI commands
+โ โโโ ๐ฏ workflow/ # Workflow management
+โโโ ๐จ output-styles/ # Output formatting templates
+โโโ ๐ญ planning-templates/ # Role-specific planning
+โโโ ๐ฌ prompt-templates/ # AI interaction templates
+โโโ ๐ง scripts/ # Automation utilities
+โ โโโ ๐ gemini-wrapper # Intelligent Gemini wrapper
+โ โโโ ๐ read-task-paths.sh # Task path conversion
+โ โโโ ๐๏ธ get_modules_by_depth.sh # Project analysis
+โโโ ๐ ๏ธ workflows/ # Core workflow documentation
+โ โโโ ๐๏ธ workflow-architecture.md # System architecture
+โ โโโ ๐ intelligent-tools-strategy.md # Tool selection guide
+โ โโโ ๐ง tools-implementation-guide.md # Implementation details
+โโโ โ๏ธ settings.local.json # Local configuration
+
+๐ .workflow/ # Session workspace (auto-generated)
+โโโ ๐ท๏ธ .active-[session] # Active session markers
+โโโ ๐ WFS-[topic-slug]/ # Individual sessions
+ โโโ โ๏ธ workflow-session.json # Session metadata
+ โโโ ๐ .task/impl-*.json # Task definitions
+ โโโ ๐ IMPL_PLAN.md # Planning documents
+ โโโ โ
TODO_LIST.md # Progress tracking
+ โโโ ๐ .summaries/ # Completion summaries
+```
+
+---
+
+## โก Performance & Technical Specs
+
+### ๐ **Performance Metrics**
+| Metric | Performance | Details |
+|--------|-------------|---------|
+| ๐ **Session Switching** | <10ms | Atomic marker file operations |
+| ๐ **JSON Queries** | <1ms | Direct JSON access, no parsing overhead |
+| ๐ **Doc Updates** | <30s | Medium projects, intelligent targeting |
+| ๐ **Context Loading** | <5s | Complex codebases with caching |
+| โก **Task Execution** | 10min timeout | Complex operations with error handling |
+
+### ๐ ๏ธ **System Requirements**
+- **๐ฅ๏ธ OS**: Windows 10+, Ubuntu 18.04+, macOS 10.15+
+- **๐ฆ Dependencies**: Git, Node.js (Gemini), Python 3.8+ (Codex)
+- **๐พ Storage**: ~50MB core + variable project data
+- **๐ง Memory**: 512MB minimum, 2GB recommended
+
+### ๐ **Integration Requirements**
+- **๐ Gemini CLI**: Required for analysis workflows
+- **๐ค Codex CLI**: Required for autonomous development
+- **๐ Git Repository**: Required for change tracking
+- **๐ฏ Claude Code IDE**: Recommended for optimal experience
+
+---
+
+## โ๏ธ Installation & Configuration
+
+### ๐ **Quick Installation**
```powershell
Invoke-Expression (Invoke-WebRequest -Uri "https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.ps1" -UseBasicParsing).Content
```
-### Verify Installation
+### โ
**Verify Installation**
```bash
/workflow:session list
```
-### Required Configuration
-For Gemini CLI integration, configure your settings:
+### โ๏ธ **Essential Configuration**
+
+#### **Gemini CLI Setup**
```json
+// ~/.gemini/settings.json
{
"contextFileName": "CLAUDE.md"
}
```
-## Complete Command Reference
-
-### Core System Commands
-
-| Command | Syntax | Description |
-|---------|--------|-------------|
-| `/enhance-prompt` | `/enhance-prompt
` | Enhance user inputs with technical context and structure |
-| `/context` | `/context [task-id\|--filter] [--analyze] [--format=tree\|list\|json]` | Unified context management with automatic data consistency |
-| `/update-memory-full` | `/update-memory-full` | Complete project-wide CLAUDE.md documentation update |
-| `/update-memory-related` | `/update-memory-related` | Context-aware documentation updates for changed modules |
-
-### Gemini CLI Commands (Analysis & Investigation)
-
-| Command | Syntax | Description |
-|---------|--------|-------------|
-| `/gemini:analyze` | `/gemini:analyze
[--all-files] [--save-session]` | Deep codebase analysis and pattern investigation |
-| `/gemini:chat` | `/gemini:chat [--all-files] [--save-session]` | Direct Gemini CLI interaction without templates |
-| `/gemini:execute` | `/gemini:execute [--yolo] [--debug]` | Intelligent execution with automatic context inference |
-| `/gemini:mode:auto` | `/gemini:mode:auto ""` | Automatic template selection based on input analysis |
-| `/gemini:mode:bug-index` | `/gemini:mode:bug-index ` | Specialized bug analysis and diagnostic workflows |
-| `/gemini:mode:plan` | `/gemini:mode:plan ` | Architecture and planning template execution |
-
-### Codex CLI Commands (Development & Implementation)
-
-| Command | Syntax | Description |
-|---------|--------|-------------|
-| `/codex:analyze` | `/codex:analyze [patterns]` | Development-focused codebase analysis |
-| `/codex:chat` | `/codex:chat [patterns]` | Direct Codex CLI interaction |
-| `/codex:execute` | `/codex:execute [patterns]` | Controlled autonomous development |
-| `/codex:mode:auto` | `/codex:mode:auto ""` | **Primary Mode**: Full autonomous development |
-| `/codex:mode:bug-index` | `/codex:mode:bug-index ` | Autonomous bug fixing and resolution |
-| `/codex:mode:plan` | `/codex:mode:plan ` | Development planning and architecture |
-
-### Workflow Management Commands
-
-#### Session Management
-| Command | Syntax | Description |
-|---------|--------|-------------|
-| `/workflow:session:start` | `/workflow:session:start ""` | Create and activate new workflow session |
-| `/workflow:session:pause` | `/workflow:session:pause` | Pause current active session |
-| `/workflow:session:resume` | `/workflow:session:resume ""` | Resume paused workflow session |
-| `/workflow:session:list` | `/workflow:session:list [--active\|--all]` | List workflow sessions with status |
-| `/workflow:session:switch` | `/workflow:session:switch ""` | Switch to different workflow session |
-| `/workflow:session:status` | `/workflow:session:status` | Display current session information |
-
-#### Workflow Operations
-| Command | Syntax | Description |
-|---------|--------|-------------|
-| `/workflow:brainstorm` | `/workflow:brainstorm [--perspectives=role1,role2,...]` | Multi-agent conceptual planning |
-| `/workflow:plan` | `/workflow:plan [--from-brainstorming] [--skip-brainstorming]` | Convert concepts to executable plans |
-| `/workflow:plan-deep` | `/workflow:plan-deep [--complexity=high] [--depth=3]` | Deep architectural planning with comprehensive analysis |
-| `/workflow:execute` | `/workflow:execute [--type=simple\|medium\|complex] [--auto-create-tasks]` | Enter implementation phase |
-| `/workflow:review` | `/workflow:review [--auto-fix]` | Quality assurance and validation |
-
-#### Issue Management
-| Command | Syntax | Description |
-|---------|--------|-------------|
-| `/workflow:issue:create` | `/workflow:issue:create "" [--priority=level] [--type=type]` | Create new project issue |
-| `/workflow:issue:list` | `/workflow:issue:list [--status=status] [--assigned=agent]` | List project issues with filtering |
-| `/workflow:issue:update` | `/workflow:issue:update <issue-id> [--status=status] [--assign=agent]` | Update existing issue |
-| `/workflow:issue:close` | `/workflow:issue:close <issue-id> [--reason=reason]` | Close resolved issue |
-
-### Task Management Commands
-
-| Command | Syntax | Description |
-|---------|--------|-------------|
-| `/task:create` | `/task:create "<title>" [--type=type] [--priority=level] [--parent=parent-id]` | Create implementation tasks with hierarchy |
-| `/task:breakdown` | `/task:breakdown <task-id> [--strategy=auto\|interactive] [--depth=1-3]` | Decompose tasks into manageable subtasks |
-| `/task:execute` | `/task:execute <task-id> [--mode=auto\|guided] [--agent=type]` | Execute tasks with agent selection |
-| `/task:replan` | `/task:replan [task-id\|--all] [--reason] [--strategy=adjust\|rebuild]` | Adapt tasks to changing requirements |
-
-### Brainstorming Role Commands
-
-| Command | Description |
-|---------|-------------|
-| `/workflow:brainstorm:business-analyst` | Business requirements and market analysis |
-| `/workflow:brainstorm:data-architect` | Data modeling and architecture planning |
-| `/workflow:brainstorm:feature-planner` | Feature specification and user stories |
-| `/workflow:brainstorm:innovation-lead` | Technology innovation and emerging solutions |
-| `/workflow:brainstorm:product-manager` | Product strategy and roadmap planning |
-| `/workflow:brainstorm:security-expert` | Security analysis and threat modeling |
-| `/workflow:brainstorm:system-architect` | System design and technical architecture |
-| `/workflow:brainstorm:ui-designer` | User interface and experience design |
-| `/workflow:brainstorm:user-researcher` | User needs analysis and research insights |
-| `/workflow:brainstorm:synthesis` | Integrate and synthesize multiple perspectives |
-
-## Usage Workflows
-
-### Complex Feature Development
+#### **Optimized .geminiignore**
```bash
-# 1. Initialize workflow session
-/workflow:session:start "OAuth2 Authentication System"
-
-# 2. Multi-perspective analysis
-/workflow:brainstorm "OAuth2 implementation strategy" \
- --perspectives=system-architect,security-expert,data-architect
-
-# 3. Generate implementation plan
-/workflow:plan --from-brainstorming
-
-# 4. Create task hierarchy
-/task:create "Backend Authentication API"
-/task:breakdown IMPL-1 --strategy=auto --depth=2
-
-# 5. Execute development tasks
-/codex:mode:auto "Implement JWT token management system"
-/codex:mode:auto "Create OAuth2 provider integration"
-
-# 6. Review and validation
-/workflow:review --auto-fix
-
-# 7. Update documentation
-/update-memory-related
-```
-
-### Bug Analysis and Resolution
-```bash
-# 1. Create focused session
-/workflow:session:start "Payment Processing Bug Fix"
-
-# 2. Analyze issue
-/gemini:mode:bug-index "Payment validation fails on concurrent requests"
-
-# 3. Implement solution
-/codex:mode:auto "Fix race condition in payment validation logic"
-
-# 4. Verify resolution
-/workflow:review --auto-fix
-```
-
-### Project Documentation Management
-```bash
-# Daily development workflow
-/update-memory-related
-
-# After major changes
-git commit -m "Feature implementation complete"
-/update-memory-related
-
-# Project-wide refresh
-/update-memory-full
-
-# Module-specific updates
-cd src/api && /update-memory-related
-```
-
-## Directory Structure
-
-```
-.claude/
-โโโ agents/ # AI agent definitions and behaviors
-โโโ commands/ # CLI command implementations
-โโโ output-styles/ # Output formatting templates
-โโโ planning-templates/ # Role-specific planning approaches
-โโโ prompt-templates/ # AI interaction templates
-โโโ scripts/ # Automation and utility scripts
-โ โโโ read-task-paths.sh # Convert task JSON paths to @ format
-โ โโโ get_modules_by_depth.sh # Project structure analysis
-โโโ tech-stack-templates/ # Technology-specific configurations
-โโโ workflows/ # Core workflow documentation
-โ โโโ system-architecture.md # Architecture specifications
-โ โโโ data-model.md # JSON data model standards
-โ โโโ complexity-rules.md # Complexity management rules
-โ โโโ session-management-principles.md # Session system design
-โ โโโ file-structure-standards.md # Directory organization
-โ โโโ intelligent-tools-strategy.md # Tool selection strategy guide
-โ โโโ tools-implementation-guide.md # Tool implementation details
-โโโ settings.local.json # Local environment configuration
-
-.workflow/ # Session workspace (auto-generated)
-โโโ .active-[session-name] # Active session marker files
-โโโ WFS-[topic-slug]/ # Individual session directories
- โโโ workflow-session.json # Session metadata
- โโโ .task/impl-*.json # JSON task definitions
- โโโ IMPL_PLAN.md # Generated planning documents
- โโโ .summaries/ # Completion summaries
-```
-
-## Technical Specifications
-
-### Performance Metrics
-- **Session switching**: <10ms average
-- **JSON query response**: <1ms average
-- **Documentation updates**: <30s for medium projects
-- **Context loading**: <5s for complex codebases
-
-### System Requirements
-- **Operating System**: Windows 10+, Ubuntu 18.04+, macOS 10.15+
-- **Dependencies**: Git, Node.js (for Gemini CLI), Python 3.8+ (for Codex CLI)
-- **Storage**: ~50MB for core installation, variable for project data
-- **Memory**: 512MB minimum, 2GB recommended for complex workflows
-
-### Integration Requirements
-- **Gemini CLI**: Required for analysis workflows
-- **Codex CLI**: Required for autonomous development
-- **Git Repository**: Required for change tracking and documentation updates
-- **Claude Code IDE**: Recommended for optimal command integration
-
-## Configuration
-
-### Required Configuration
-For optimal CCW integration, configure Gemini CLI settings:
-
-```json
-// ~/.gemini/settings.json or .gemini/settings.json
-{
- "contextFileName": "CLAUDE.md"
-}
-```
-
-This setting ensures that CCW's intelligent documentation system integrates properly with Gemini CLI workflows.
-
-### .geminiignore Configuration
-
-To optimize Gemini CLI performance and reduce context noise, configure a `.geminiignore` file in your project root. This file excludes irrelevant files from analysis, providing cleaner context and faster processing.
-
-#### Creating .geminiignore
-Create `.geminiignore` in your project root:
-
-```bash
-# Exclude build outputs and dependencies
+# Performance optimization
/dist/
/build/
/node_modules/
/.next/
-# Exclude temporary files
+# Temporary files
*.tmp
*.log
/temp/
-# Exclude sensitive files
-/.env
-/config/secrets.*
-apikeys.txt
-
-# Exclude large data files
-*.csv
-*.json
-*.sql
-
-# Include important documentation (negation)
+# Include important docs
!README.md
-!CHANGELOG.md
!**/CLAUDE.md
```
-#### Configuration Benefits
-- **Improved Performance**: Faster analysis by excluding irrelevant files
-- **Better Context**: Cleaner analysis results without build artifacts
-- **Reduced Token Usage**: Lower costs by filtering out unnecessary content
-- **Enhanced Focus**: Better AI understanding through relevant context only
+---
-#### Best Practices
-- Always exclude `node_modules/`, `dist/`, `build/` directories
-- Filter out log files, temporary files, and build artifacts
-- Keep documentation files (use `!` to include specific patterns)
-- Update `.geminiignore` when project structure changes
-- Restart Gemini CLI session after modifying `.geminiignore`
+## ๐ค Contributing
-**Note**: Unlike `.gitignore`, `.geminiignore` only affects Gemini CLI operations and does not impact Git versioning.
+### ๐ ๏ธ **Development Setup**
+1. ๐ด Fork the repository
+2. ๐ฟ Create feature branch: `git checkout -b feature/enhancement-name`
+3. ๐ฆ Install dependencies
+4. โ
Test with sample projects
+5. ๐ค Submit detailed pull request
-## Contributing
-
-### Development Setup
-1. Fork the repository
-2. Create feature branch: `git checkout -b feature/enhancement-name`
-3. Install dependencies: `npm install` or equivalent for your environment
-4. Make changes following existing patterns
-5. Test with sample projects
-6. Submit pull request with detailed description
-
-### Code Standards
-- Follow existing command structure patterns
-- Maintain backward compatibility for public APIs
-- Add tests for new functionality
-- Update documentation for user-facing changes
-- Use semantic versioning for releases
-
-## Support and Resources
-
-- **Documentation**: [Project Wiki](https://github.com/catlog22/Claude-Code-Workflow/wiki)
-- **Issues**: [GitHub Issues](https://github.com/catlog22/Claude-Code-Workflow/issues)
-- **Discussions**: [Community Forum](https://github.com/catlog22/Claude-Code-Workflow/discussions)
-- **Changelog**: [Release History](CHANGELOG.md)
-
-## License
-
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+### ๐ **Code Standards**
+- โ
Follow existing command patterns
+- ๐ Maintain backward compatibility
+- ๐งช Add tests for new functionality
+- ๐ Update documentation
+- ๐ท๏ธ Use semantic versioning
---
-**Claude Code Workflow (CCW)** - Professional software development workflow automation through intelligent agent coordination and autonomous execution capabilities.
\ No newline at end of file
+## ๐ Support & Resources
+
+<div align="center">
+
+| Resource | Link | Description |
+|----------|------|-------------|
+| ๐ **Documentation** | [Project Wiki](https://github.com/catlog22/Claude-Code-Workflow/wiki) | Comprehensive guides |
+| ๐ **Issues** | [GitHub Issues](https://github.com/catlog22/Claude-Code-Workflow/issues) | Bug reports & features |
+| ๐ฌ **Discussions** | [Community Forum](https://github.com/catlog22/Claude-Code-Workflow/discussions) | Community support |
+| ๐ **Changelog** | [Release History](CHANGELOG.md) | Version history |
+
+</div>
+
+---
+
+## ๐ License
+
+This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.
+
+---
+
+<div align="center">
+
+**๐ Claude Code Workflow (CCW)**
+
+*Professional software development workflow automation through intelligent multi-agent coordination and autonomous execution capabilities.*
+
+[](https://github.com/catlog22/Claude-Code-Workflow)
+
+</div>
\ No newline at end of file