From f76e5edbdf933fd6aeac513af98ada1b378f0983 Mon Sep 17 00:00:00 2001 From: catlog22 Date: Tue, 9 Sep 2025 22:15:17 +0800 Subject: [PATCH] refactor: consolidate workflow documentation into unified architecture MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Create unified workflow-architecture.md combining: - data-model.md (JSON-only architecture, task schemas) - file-structure-standards.md (progressive structures, templates) - session-management-principles.md (marker files, session ops) - complexity-rules.md (classification thresholds, behaviors) - Update 11 files with references to new consolidated document - Remove redundant documentation while preserving all functionality - Streamline maintenance with single source of truth ๐Ÿค– Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .claude/agents/action-planning-agent.md | 26 +- .claude/commands/context.md | 2 +- .claude/commands/gemini/execute.md | 2 +- .claude/commands/task/breakdown.md | 2 +- .claude/commands/task/create.md | 2 +- .claude/commands/task/execute.md | 2 +- .claude/commands/task/replan.md | 2 +- .claude/commands/workflow/execute.md | 2 +- .claude/commands/workflow/plan.md | 2 +- .claude/commands/workflow/review.md | 2 +- .claude/workflows/complexity-rules.md | 199 ------- .claude/workflows/data-model.md | 264 --------- .claude/workflows/file-structure-standards.md | 388 ------------- .claude/workflows/gemini-unified.md | 547 ++++++++---------- .../session-management-principles.md | 278 --------- .claude/workflows/system-architecture.md | 129 ----- .claude/workflows/workflow-architecture.md | 401 +++++++++++++ 17 files changed, 657 insertions(+), 1593 deletions(-) delete mode 100644 .claude/workflows/complexity-rules.md delete mode 100644 .claude/workflows/data-model.md delete mode 100644 .claude/workflows/file-structure-standards.md delete mode 100644 .claude/workflows/session-management-principles.md delete mode 100644 .claude/workflows/system-architecture.md create mode 100644 .claude/workflows/workflow-architecture.md diff --git a/.claude/agents/action-planning-agent.md b/.claude/agents/action-planning-agent.md index 5c9723f2..accca71f 100644 --- a/.claude/agents/action-planning-agent.md +++ b/.claude/agents/action-planning-agent.md @@ -177,7 +177,7 @@ Your primary responsibilities: 2. **Stage Design**: Break complex work into 3-5 logical stages. - **Stage format specification**: @~/.claude/workflows/file-structure-standards.md#stage-based-format-simple-tasks + **Stage format specification**: @~/.claude/workflows/workflow-architecture.md#stage-based-format-simple-tasks Each stage should include: - A specific, measurable deliverable @@ -188,13 +188,13 @@ Your primary responsibilities: 3. **Implementation Plan Creation**: Generate a structured `IMPL_PLAN.md` document in the `.workflow/WFS-[session-id]/` directory. - **Document Format Standards**: @~/.claude/workflows/file-structure-standards.md#impl_planmd-structure + **Document Format Standards**: @~/.claude/workflows/workflow-architecture.md#impl_planmd-templates - Use **Stage-Based Format** for simple, linear tasks - Use **Hierarchical Format** for complex tasks (>5 subtasks or >3 modules) 4. **Task Decomposition for Complex Projects**: For complex tasks involving >5 subtasks or spanning >3 modules, create detailed task decomposition and tracking documents. - **Hierarchical format specification**: @~/.claude/workflows/file-structure-standards.md#hierarchical-format-complex-tasks + **Hierarchical format specification**: @~/.claude/workflows/workflow-architecture.md#hierarchical-format-complex-tasks **Task Decomposition Criteria**: - Tasks requiring >5 distinct subtasks @@ -204,10 +204,10 @@ Your primary responsibilities: - Tasks with significant uncertainty or risk factors **Enhanced IMPL_PLAN.md structure for complex tasks**: - See @~/.claude/workflows/file-structure-standards.md#hierarchical-format-complex-tasks + See @~/.claude/workflows/workflow-architecture.md#hierarchical-format-complex-tasks **Generate TODO_LIST.md** in `.workflow/WFS-[session-id]/` directory: - See @~/.claude/workflows/file-structure-standards.md#todo_listmd-structure + See @~/.claude/workflows/workflow-architecture.md#todo_listmd-template **Note**: Keep TODO_LIST.md format simple and focused on task tracking. Avoid complex sections unless specifically needed. @@ -218,7 +218,7 @@ Your primary responsibilities: - All documents created in `.workflow/WFS-[session-id]/` directory - Unified session tracking in `.workflow/WFS-[session-id]/workflow-session.json` - **Full format specifications**: @~/.claude/workflows/file-structure-standards.md + **Full format specifications**: @~/.claude/workflows/workflow-architecture.md 6. **Incremental Progress Focus**: Ensure each stage: - Can be completed independently @@ -256,11 +256,11 @@ Your primary responsibilities: **Planning Session Management and Automatic Document Generation Logic**: - **Directory structure standards**: @~/.claude/workflows/file-structure-standards.md#progressive-structure-system + **Directory structure standards**: @~/.claude/workflows/workflow-architecture.md#progressive-structure-system ### Feature-Based Directory Structure -**See complete directory structure standards**: @~/.claude/workflows/file-structure-standards.md#progressive-structure-system +**See complete directory structure standards**: @~/.claude/workflows/workflow-architecture.md#progressive-structure-system Directory organization follows progressive complexity levels: - **Level 0**: Minimal structure (<5 tasks) @@ -269,11 +269,11 @@ Directory organization follows progressive complexity levels: **Note**: When DEEP_ANALYSIS_REQUIRED mode is active, Gemini analysis results are integrated directly into IMPL_PLAN.md rather than as a separate file. -**Session Tracker Format**: See @~/.claude/workflows/file-structure-standards.md for `workflow-session.json` structure +**Session Tracker Format**: See @~/.claude/workflows/workflow-architecture.md for `workflow-session.json` structure -**File Naming Conventions**: @~/.claude/workflows/file-structure-standards.md#file-naming-conventions +**File Naming Conventions**: @~/.claude/workflows/workflow-architecture.md#file-naming-conventions -**Session Naming**: Follow @~/.claude/workflows/file-structure-standards.md#session-identifiers +**Session Naming**: Follow @~/.claude/workflows/workflow-architecture.md#session-identifiers - Format: `WFS-[topic-slug]` - Convert to kebab-case - Add numeric suffix only if conflicts exist @@ -326,7 +326,7 @@ Directory organization follows progressive complexity levels: }) # Step 4: Generate planning documents in workflow directory - # All document formats follow: @~/.claude/workflows/file-structure-standards.md + # All document formats follow: @~/.claude/workflows/workflow-architecture.md combined_context = merge_contexts(session_context, gemini_context) # Merge session and Gemini contexts if (subtasks > 5 OR modules > 3 OR high_complexity): @@ -334,7 +334,7 @@ Directory organization follows progressive complexity levels: generate_task_decomposition(combined_context, workflow_dir) # Architecture-aligned hierarchy with session decisions generate_todo_list(combined_context, workflow_dir) # Pattern-aware task list with session continuity create_document_links() # Cross-reference linking with relative paths - create_summaries_directory(f"{workflow_dir}/.summaries/") # See @~/.claude/workflows/file-structure-standards.md#summary-management + create_summaries_directory(f"{workflow_dir}/.summaries/") # See @~/.claude/workflows/workflow-architecture.md#file-structure update_session_action_checkpoint() # Save action phase progress elif (components > 3 OR estimated_loc > 100): generate_implementation_plan(combined_context, workflow_dir) # Session + context-aware staged plan diff --git a/.claude/commands/context.md b/.claude/commands/context.md index 020008dc..072e034e 100644 --- a/.claude/commands/context.md +++ b/.claude/commands/context.md @@ -16,7 +16,7 @@ examples: Generates on-demand views from JSON task data. No synchronization needed - all views are calculated from the current state of JSON files. ## Core Principles -**Data Source:** @~/.claude/workflows/data-model.md +**Data Source:** @~/.claude/workflows/workflow-architecture.md ## Key Features diff --git a/.claude/commands/gemini/execute.md b/.claude/commands/gemini/execute.md index 55ed027a..83c7666a 100644 --- a/.claude/commands/gemini/execute.md +++ b/.claude/commands/gemini/execute.md @@ -198,7 +198,7 @@ This template is automatically filled and generated after execution. - **IF active session exists**: Save to existing `.workflow/WFS-[topic-slug]/.chat/` directory - **IF no active session**: Create new session directory following WFS naming convention -**Session Management**: @~/.claude/workflows/session-management-principles.md +**Session Management**: @~/.claude/workflows/workflow-architecture.md - **File Format**: `execute-YYYYMMDD-HHMMSS.md` with timestamp for unique identification. - **Structure**: Integrates with session management system using WFS-[topic-slug] format for consistency. - **Coordination**: Session files coordinate with workflow-session.json and maintain document-state separation. diff --git a/.claude/commands/task/breakdown.md b/.claude/commands/task/breakdown.md index 9cd01b75..c006c31b 100644 --- a/.claude/commands/task/breakdown.md +++ b/.claude/commands/task/breakdown.md @@ -15,7 +15,7 @@ examples: Intelligently breaks down complex tasks into manageable subtasks with automatic context distribution and agent assignment. ## Core Principles -**Task Schema:** @~/.claude/workflows/data-model.md +**Task Schema:** @~/.claude/workflows/workflow-architecture.md ## Features diff --git a/.claude/commands/task/create.md b/.claude/commands/task/create.md index 1801c6fe..ca7147ba 100644 --- a/.claude/commands/task/create.md +++ b/.claude/commands/task/create.md @@ -15,7 +15,7 @@ examples: Creates new implementation tasks during IMPLEMENT phase with automatic context awareness and ID generation. ## Core Principles -**Task Management:** @~/.claude/workflows/data-model.md +**Task Management:** @~/.claude/workflows/workflow-architecture.md ## Features diff --git a/.claude/commands/task/execute.md b/.claude/commands/task/execute.md index 9dece35e..6669d936 100644 --- a/.claude/commands/task/execute.md +++ b/.claude/commands/task/execute.md @@ -12,7 +12,7 @@ examples: ### ๐Ÿš€ **Command Overview: `/task:execute`** - **Purpose**: Executes tasks using intelligent agent selection, context preparation, and progress tracking. -- **Core Principles**: @~/.claude/workflows/data-model.md +- **Core Principles**: @~/.claude/workflows/workflow-architecture.md ### โš™๏ธ **Execution Modes** diff --git a/.claude/commands/task/replan.md b/.claude/commands/task/replan.md index fa67561d..f4840604 100644 --- a/.claude/commands/task/replan.md +++ b/.claude/commands/task/replan.md @@ -15,7 +15,7 @@ examples: Replans individual tasks based on detailed user input with comprehensive change tracking, version management, and document synchronization. Focuses exclusively on single-task modifications with rich input options. ## Core Principles -**Task Management:** @~/.claude/workflows/data-model.md +**Task Management:** @~/.claude/workflows/workflow-architecture.md ## Single-Task Focus This command operates on **individual tasks only**. For workflow-wide changes, use `/workflow:action-plan` instead. diff --git a/.claude/commands/workflow/execute.md b/.claude/commands/workflow/execute.md index 30d96db2..12d3c5e9 100644 --- a/.claude/commands/workflow/execute.md +++ b/.claude/commands/workflow/execute.md @@ -14,7 +14,7 @@ Coordinates multiple agents for executing existing workflow tasks through automa ## Core Principles -**Session Management:** @~/.claude/workflows/session-management-principles.md +**Session Management:** @~/.claude/workflows/workflow-architecture.md **Agent Orchestration:** @~/.claude/workflows/agent-orchestration-patterns.md ## Execution Philosophy diff --git a/.claude/commands/workflow/plan.md b/.claude/commands/workflow/plan.md index b27fe120..6678bd34 100644 --- a/.claude/commands/workflow/plan.md +++ b/.claude/commands/workflow/plan.md @@ -16,7 +16,7 @@ examples: Creates actionable implementation plans with intelligent input source detection. Supports text, files, issues, and templates through automatic recognition. ## Core Principles -**File Structure:** @~/.claude/workflows/file-structure-standards.md +**File Structure:** @~/.claude/workflows/workflow-architecture.md ## Usage ```bash diff --git a/.claude/commands/workflow/review.md b/.claude/commands/workflow/review.md index 549cda6e..45be8ecb 100644 --- a/.claude/commands/workflow/review.md +++ b/.claude/commands/workflow/review.md @@ -13,7 +13,7 @@ examples: Final phase for quality validation, testing, and completion. ## Core Principles -**Session Management:** @~/.claude/workflows/session-management-principles.md +**Session Management:** @~/.claude/workflows/workflow-architecture.md ## Review Process diff --git a/.claude/workflows/complexity-rules.md b/.claude/workflows/complexity-rules.md deleted file mode 100644 index 52b6f92a..00000000 --- a/.claude/workflows/complexity-rules.md +++ /dev/null @@ -1,199 +0,0 @@ -# Workflow Complexity Rules - -## Overview - -This document defines unified complexity classification rules across all workflow components, ensuring consistent thresholds and scaling behavior throughout the system. - -## Complexity Classification - -### Unified Thresholds -**Based on task count for consistent classification across all system components** - -| Complexity | Task Count | Max Hierarchy Depth | File Structure Level | -|------------|------------|-------------------|-------------------| -| **Simple** | <5 tasks | 1 level (impl-N) | Level 0 - Minimal | -| **Medium** | 5-15 tasks | 2 levels (impl-N.M) | Level 1 - Enhanced | -| **Complex** | >15 tasks | 3 levels (impl-N.M.P) | Level 2 - Complete | - -## Simple Workflows - -### Characteristics -- **Direct implementation tasks** with clear, limited scope -- **Single-file or small-module changes** -- **Clear requirements** without complex dependencies -- **Atomic functionality** that can be implemented in one session - -### System Behavior -- **File Structure**: Minimal directory structure (Level 0) -- **Task Hierarchy**: Single level only (impl-1, impl-2, etc.) -- **Documentation**: Basic IMPL_PLAN.md, no TODO_LIST.md -- **Agent Coordination**: Direct execution without complex orchestration - -### Examples -- Bug fixes in existing functionality -- Small feature additions to existing modules -- Documentation updates -- Configuration changes -- Simple utility functions - -## Medium Workflows - -### Characteristics -- **Feature implementation** requiring task breakdown -- **Multiple file modifications** across related modules -- **Some integration requirements** with existing systems -- **Clear feature boundaries** with moderate complexity - -### System Behavior -- **File Structure**: Enhanced directory structure (Level 1) -- **Task Hierarchy**: Two levels (impl-N.M format) -- **Documentation**: IMPL_PLAN.md + auto-triggered TODO_LIST.md -- **Agent Coordination**: Context-driven coordination with shared state - -### Auto-trigger Conditions -TODO_LIST.md and enhanced structure triggered when: -- Task count > 5 OR -- Modules affected > 3 OR -- Estimated effort > 4h OR -- Complex inter-module dependencies exist - -### Examples -- New feature implementation within existing architecture -- API endpoint creation with frontend integration -- Database schema changes with application updates -- Authentication/authorization enhancements -- Performance optimization across multiple components - -## Complex Workflows - -### Characteristics -- **System-wide changes** requiring detailed decomposition -- **Architectural modifications** affecting multiple systems -- **Cross-team coordination** or external dependencies -- **High-risk changes** requiring extensive testing and review - -### System Behavior -- **File Structure**: Complete directory structure (Level 2) -- **Task Hierarchy**: Three levels maximum (impl-N.M.P format) -- **Documentation**: Comprehensive planning + progress tracking + summaries -- **Agent Coordination**: Multi-agent orchestration with deep context analysis - -### Examples -- New major feature development -- System architecture refactoring -- Third-party service integrations -- Security implementations (OAuth, encryption) -- Database migrations with application changes -- Multi-service deployments - -## Complexity Assessment Rules - -### Automatic Classification -**System evaluates tasks during creation and applies appropriate complexity level** - -```pseudo -function classify_complexity(tasks, scope, dependencies): - task_count = count(tasks) - - if task_count < 5 and scope.is_simple() and not dependencies.complex(): - return SIMPLE - elif task_count <= 15 and scope.is_moderate(): - return MEDIUM - else: - return COMPLEX -``` - -### Upgrade Triggers -**Complexity can be upgraded during workflow execution** - -- **Simple โ†’ Medium**: When subtasks are created or scope expands -- **Medium โ†’ Complex**: When task count exceeds 15 or deep hierarchy needed -- **No Downgrades**: Complexity level never decreases to prevent data loss - -### Override Rules -**Manual complexity override allowed for edge cases** - -- User can specify higher complexity at workflow creation -- System warnings issued for mismatched complexity/scope -- Cannot specify lower complexity than system assessment - -## Component Integration - -### File Structure Mapping -**Complexity directly determines file structure level** - -| Complexity | Directory Structure | Required Files | -|------------|-------------------|---------------| -| Simple | Minimal (.task/, .summaries/) | workflow-session.json, IMPL_PLAN.md | -| Medium | Enhanced (+ TODO_LIST.md) | + Auto-generated progress tracking | -| Complex | Complete (+ comprehensive docs) | + Full documentation suite | - -### Agent Orchestration Mapping -**Complexity determines agent coordination patterns** - -| Complexity | Gemini Analysis | Agent Coordination | Review Process | -|------------|----------------|-------------------|---------------| -| Simple | Focused file-level | Direct context-aware execution | Quick validation | -| Medium | Comprehensive multi-file | Context-driven coordination | Thorough single-pass | -| Complex | Deep system-wide | Multi-agent orchestration | Multiple review iterations | - -### Task Hierarchy Mapping -**Complexity enforces hierarchy depth limits** - -- **Simple**: Single level (impl-N) -- **Medium**: Two levels (impl-N.M) -- **Complex**: Three levels maximum (impl-N.M.P) - -## Decision Tree - -### Workflow Creation -``` -Start: Analyze user requirements -โ”‚ -โ”œโ”€ Task count < 5 AND single module AND clear scope? -โ”‚ โ””โ”€ YES โ†’ SIMPLE workflow -โ”‚ -โ”œโ”€ Task count โ‰ค 15 AND moderate scope AND some integration? -โ”‚ โ””โ”€ YES โ†’ MEDIUM workflow -โ”‚ -โ””โ”€ Task count > 15 OR system-wide OR high-risk? - โ””โ”€ YES โ†’ COMPLEX workflow -``` - -### Complexity Upgrade Assessment -``` -During Execution: Monitor task growth -โ”‚ -โ”œโ”€ Simple workflow + subtasks created? -โ”‚ โ””โ”€ Upgrade to MEDIUM -โ”‚ -โ”œโ”€ Medium workflow + task count > 15? -โ”‚ โ””โ”€ Upgrade to COMPLEX -โ”‚ -โ””โ”€ Any workflow + architectural changes? - โ””โ”€ Consider upgrade to COMPLEX -``` - -## Quality Assurance - -### Validation Rules -- Complexity level must match actual task count -- File structure must align with complexity level -- Agent coordination patterns must match complexity -- Documentation completeness must match complexity requirements - -### Performance Monitoring -- Track completion times by complexity level -- Monitor accuracy of initial complexity assessments -- Adjust thresholds based on historical data -- Measure overhead costs of each complexity level - -### Consistency Checks -- All system components use same complexity thresholds -- Cross-references between complexity-dependent files are valid -- Upgrade paths preserve existing work and structure -- No orphaned files after complexity changes - ---- - -**System ensures**: Unified complexity classification across all workflow components with consistent scaling behavior and automatic optimization for task scope and system performance \ No newline at end of file diff --git a/.claude/workflows/data-model.md b/.claude/workflows/data-model.md deleted file mode 100644 index dd8ee12f..00000000 --- a/.claude/workflows/data-model.md +++ /dev/null @@ -1,264 +0,0 @@ -# Workflow Data Model - -## Overview - -This document defines the complete data model for the workflow system using a **JSON-only architecture**. JSON task files are the single source of truth, with all documents generated on-demand as read-only views. - -## Core Data Architecture - -### Key Principle: JSON-Only Data Model -**JSON files (.task/impl-*.json) are the only authoritative source of task state. All markdown documents are read-only generated views that never persist state.** - -- **Task State**: Stored exclusively in JSON files -- **Documents**: Generated on-demand from JSON data -- **No Synchronization**: Eliminates bidirectional sync complexity -- **Performance**: Direct JSON access without parsing overhead - -## Task JSON Schema - -### Core Task Structure -All task files use this simplified 8-field schema: - -```json -{ - "id": "impl-1", - "title": "Build authentication module", - "status": "pending", - "type": "feature", - "agent": "code-developer", - - "context": { - "requirements": ["JWT authentication", "OAuth2 support"], - "scope": ["src/auth/*", "tests/auth/*"], - "acceptance": ["Module handles JWT tokens", "OAuth2 flow implemented"], - "inherited_from": "WFS-user-auth" - }, - - "relations": { - "parent": null, - "subtasks": ["impl-1.1", "impl-1.2"], - "dependencies": ["impl-0"] - }, - - "execution": { - "attempts": 0, - "last_attempt": null - }, - - "meta": { - "created": "2025-09-05T10:30:00Z", - "updated": "2025-09-05T10:30:00Z" - } -} -``` - -### Status Values -- **pending**: Task created but not started -- **active**: Task currently being worked on -- **completed**: Task successfully finished -- **blocked**: Task cannot proceed due to dependencies -- **container**: Parent task with subtasks (not directly executable) - -### Task Types -- **feature**: New functionality implementation -- **bugfix**: Fixing existing issues -- **refactor**: Code improvement without functionality change -- **test**: Test implementation or testing tasks -- **docs**: Documentation creation or updates - -## Hierarchical Task System - -### Task Hierarchy Rules -**Maximum Depth**: 3 levels (impl-N.M.P format) - -``` -impl-1 # Main task -impl-1.1 # Subtask of impl-1 -impl-1.1.1 # Detailed subtask of impl-1.1 -impl-1.2 # Another subtask of impl-1 -impl-2 # Another main task -``` - -### Parent-Child Relationships -```json -// Parent task -{ - "id": "impl-1", - "title": "Build authentication module", - "status": "pending", - "relations": { - "parent": null, - "subtasks": ["impl-1.1", "impl-1.2"], - "dependencies": [] - } -} - -// Child task -{ - "id": "impl-1.1", - "title": "Design auth schema", - "status": "pending", - "relations": { - "parent": "impl-1", - "subtasks": [], - "dependencies": [] - } -} -``` - -### Task Status Rules - -#### Container Task Rules -- Parent tasks become "container" status when broken down -- Cannot be directly executed (must execute subtasks) -- Status derived from subtask completion - -#### Leaf Task Rules -- Only leaf tasks can be executed directly -- Status reflects actual execution state -- Progress tracked at leaf level only - -## Context Management - -### Context Structure -Context provides complete information for agent execution: - -- **requirements**: Specific functional requirements -- **scope**: File patterns and modules affected -- **acceptance**: Success criteria and completion definition -- **inherited_from**: Source workflow or parent task - -### Context Inheritance -- **Workflow โ†’ Task**: Global requirements and constraints -- **Parent โ†’ Subtask**: Refined scope and specific requirements -- **Context Preservation**: All fields maintained for agent execution - -## Complexity Classification - -### Simple Workflows -**Criteria**: Direct implementation tasks with clear scope -- **Structure**: Single-level tasks (impl-N format) -- **Task Files**: impl-*.json only -- **Max Depth**: 1 level -- **Task Count**: <5 tasks - -### Medium Workflows -**Criteria**: Feature implementation requiring task breakdown -- **Structure**: Two-level hierarchy (impl-N.M format) -- **Task Files**: Parent and child JSON files -- **Max Depth**: 2 levels -- **Task Count**: 5-15 tasks - -### Complex Workflows -**Criteria**: System-wide changes requiring detailed decomposition -- **Structure**: Three-level hierarchy (impl-N.M.P format) -- **Task Files**: Multi-level JSON hierarchy -- **Max Depth**: 3 levels (maximum allowed) -- **Task Count**: >15 tasks - -## Agent Integration - -### Agent Assignment -Based on task type and title keywords: -- **Planning tasks** โ†’ planning-agent -- **Implementation** โ†’ code-developer -- **Testing** โ†’ test-agent -- **Documentation** โ†’ docs-agent -- **Review** โ†’ review-agent - -### Execution Context -Agents receive complete task JSON plus workflow context: -```json -{ - "task": { /* complete task JSON */ }, - "workflow": { - "session": "WFS-user-auth", - "phase": "IMPLEMENT" - } -} -``` - -## File Organization - -### JSON Task Files -**Location**: `.task/impl-[id].json` -**Naming**: Follows hierarchical ID format -**Content**: Complete task definition - -### Document Generation -**On-Demand**: Documents generated from JSON when requested -**Read-Only**: Documents never store state -**Templates**: Standard templates for consistent output - -#### Generated Documents -- `TODO_LIST.md`: Task progress view generated from JSON -- `IMPL_PLAN.md`: Planning document with task references -- Task summaries: Generated from completed task JSON - -## Data Operations - -### Task Creation -```bash -# Create new task JSON file -echo '{"id":"impl-1","title":"New task",...}' > .task/impl-1.json -``` - -### Task Updates -```bash -# Update task status directly in JSON -jq '.status = "active"' .task/impl-1.json > temp && mv temp .task/impl-1.json -``` - -### Document Generation -```bash -# Generate TODO_LIST.md from current JSON state -generate_todo_list_from_json .task/ -``` - -## Validation Rules - -### Task Integrity -1. **ID Uniqueness**: All task IDs must be unique -2. **Hierarchical Format**: Must follow impl-N[.M[.P]] pattern -3. **Parent References**: All parent IDs must exist as JSON files -4. **Depth Limits**: Maximum 3 levels deep -5. **Status Consistency**: Status values from defined enumeration -6. **Required Fields**: All 8 core fields must be present - -### Relationship Validation -- Parent-child relationships must be bidirectional -- Dependencies must reference existing tasks -- Container tasks cannot be completed until all subtasks complete -- No circular dependencies allowed - -## Error Handling - -### Common Scenarios -1. **Missing JSON File**: Indicates broken reference - must repair -2. **Invalid Status**: Update to valid status value -3. **Broken Hierarchy**: Reconstruct parent-child relationships -4. **Orphaned Task**: Reassign to proper parent or workflow - -### Recovery Strategy -- **JSON Authoritative**: Task JSON files are source of truth -- **Validation Warnings**: For non-critical inconsistencies -- **Manual Resolution**: For complex relationship conflicts -- **Document Regeneration**: Recreate documents from JSON when corrupted - -## Performance Benefits - -### 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**: Consistent task management using simplified JSON-only data model with complete context preservation for agent execution and on-demand document generation for human readability \ No newline at end of file diff --git a/.claude/workflows/file-structure-standards.md b/.claude/workflows/file-structure-standards.md deleted file mode 100644 index e0ea919d..00000000 --- a/.claude/workflows/file-structure-standards.md +++ /dev/null @@ -1,388 +0,0 @@ -# Workflow File Structure Standards - -## Overview - -This document defines directory layouts, file naming conventions, and progressive complexity structures for workflow sessions. - -## Progressive Structure System -**Complexity โ†’ Structure Level** - -File structure scales with task complexity to minimize overhead for simple tasks while providing comprehensive organization for complex workflows. - -### Level 0: Minimal Structure (<5 tasks) -**Target**: Simple workflows with clear, limited scope - -``` -.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 with timestamps -โ”œโ”€โ”€ IMPL_PLAN.md # Combined planning document -โ”œโ”€โ”€ .summaries/ # Task completion summaries -โ”‚ โ””โ”€โ”€ IMPL-*.md # Individual task summaries -โ””โ”€โ”€ .task/ - โ””โ”€โ”€ impl-*.json # Task definitions -``` - -### Level 1: Enhanced Structure (5-15 tasks) -**Target**: Medium complexity workflows with multiple phases - -``` -.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 with timestamps -โ”œโ”€โ”€ 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) -**Target**: Complex workflows with extensive documentation needs - -``` -.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 with timestamps -โ”‚ โ””โ”€โ”€ 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 - -### Session Identifiers -**Format**: `WFS-[topic-slug]` -- Convert topic to lowercase with hyphens (e.g., "User Auth System" โ†’ `WFS-user-auth-system`) -- Add `-NNN` suffix only if conflicts exist (e.g., `WFS-payment-integration-002`) - -### Task File Naming -**Hierarchical ID Format**: -``` -impl-1 # Main task -impl-1.1 # Subtask of impl-1 -impl-1.1.1 # Detailed subtask of impl-1.1 -impl-1.2 # Another subtask of impl-1 -impl-2 # Another main task -``` - -**Maximum Depth**: 3 levels (impl-N.M.P) - -### Document Naming -- `workflow-session.json` - Session state (required) -- `IMPL_PLAN.md` - Planning document (required) -- `TODO_LIST.md` - Progress tracking (auto-generated when needed) -- Chat sessions: `chat-YYYYMMDD-HHMMSS.md` -- Analysis results: `analysis-[topic].md` -- Task summaries: `IMPL-[task-id]-summary.md` - -## Directory Structure Rules - -### Required Directories -- `.task/` - Always present, contains JSON task definitions -- `.summaries/` - Always present, contains task completion documentation - -### Optional Directories -- `.brainstorming/` - Present when brainstorming phase was used -- `.chat/` - Present when Gemini CLI sessions were saved - -### Directory Permissions and Access -- All workflow directories are project-local -- Active session marked by `.workflow/.active-[session-name]` marker file (global) -- Individual sessions in `.workflow/WFS-[topic-slug]/` (session-specific) - -## Document Generation Triggers - -### Automatic Document Creation -**Based on complexity assessment**: - -| **Complexity** | **IMPL_PLAN.md** | **TODO_LIST.md** | **Task Files** | -|----------------|------------------|------------------|----------------| -| Simple (<5 tasks) | Always | No | impl-*.json | -| Medium (5-15 tasks) | Always | Auto-trigger* | impl-*.*.json | -| Complex (>15 tasks) | Always | Always | impl-*.*.*.json | - -**Auto-trigger conditions (*):** -- Tasks > 5 OR modules > 3 OR estimated effort > 4h OR complex dependencies - -### Document Template Standards - -#### IMPL_PLAN.md Structure - -Two formats available based on task complexity: - -##### Stage-Based Format (Simple Tasks) -Use for tasks with clear, linear progression: - -```markdown -# Implementation Plan: [Task Name] - -## Overview -[Brief description of the overall goal and approach] - -## Requirements -[Functional and non-functional requirements] - -## [Brainstorming Integration] -[If .brainstorming/ exists - reference analysis results] - -## Stage 1: [Name] -**Goal**: [Specific deliverable] -**Success Criteria**: -- [Testable outcome 1] -- [Testable outcome 2] -**Tests**: -- [Specific test case 1] -- [Specific test case 2] -**Dependencies**: [Previous stages or external requirements] -**Estimated Effort**: [Small/Medium/Large] -**Review Status**: [Not Started] -**Status**: [Not Started] - -## Stage 2: [Name] -[Repeat stage structure] - -## Stage 3: [Name] -[Repeat stage structure] - -## Risk Mitigation -[Identified risks and mitigation strategies] - -## Rollback Strategy -[How to revert if issues arise] -``` - -##### Hierarchical Format (Complex Tasks) -Use for tasks requiring >5 subtasks or spanning >3 modules: - -```markdown -# Implementation Plan: [Project Name] - -## Overview -[Brief description and strategic approach] - -## Requirements -[Functional and non-functional requirements] - -## Task Hierarchy - -### Main Task: [IMPL-001] [Primary Goal] -**Description**: [Detailed description] -**Complexity**: [High/Medium/Low] -**Estimated Effort**: [Time estimate] -**Dependencies**: [External dependencies] -**Status**: [Not Started] - -#### Subtask: [IMPL-001.1] [Subtask Name] -**Description**: [Specific deliverable] -**Assigned Agent**: [code-developer/code-review-agent/general-purpose] -**Dependencies**: [Parent/peer task dependencies] -**Acceptance Criteria**: -- [Testable criteria 1] -- [Testable criteria 2] -**Estimated Effort**: [Time estimate] -**Assigned Module**: [Component/file location] -**Status**: [Not Started] -**Links**: [Related documentation/requirements] - -##### Action Item: [IMPL-001.1.1] [Specific Action] -**Type**: [Code/Test/Documentation/Review] -**Recommended Agent**: [code-developer/code-review-agent/general-purpose] -**Description**: [Concrete action] -**Files Affected**: [List of files] -**Verification**: [How to verify completion] -**Status**: [Not Started] - -[Repeat structure for all tasks/subtasks/actions] - -### Main Task: [IMPL-002] [Secondary Goal] -[Repeat task structure] - -## Dependency Graph -[Visual or text representation of task dependencies] - -## Resource Requirements -[Tools, libraries, external dependencies needed] - -## Risk Assessment -[Task-specific risks and mitigation strategies] - -## Rollback Strategy -[System-wide rollback procedures] -``` - -#### TODO_LIST.md Structure - -**Keep simple and focused on task tracking:** - -```markdown -# Task Progress List: [Session Topic] - -## Implementation Tasks - -### Main Tasks -- [ ] **IMPL-001**: [Task Description] โ†’ [๐Ÿ“‹ Details](./.task/impl-001.json) -- [x] **IMPL-002**: [Completed Task] โ†’ [๐Ÿ“‹ Details](./.task/impl-002.json) | [โœ… Summary](./.summaries/IMPL-002-summary.md) - -### Subtasks (Auto-expanded when active) -- [ ] **IMPL-001.1**: [Subtask Description] โ†’ [๐Ÿ“‹ Details](./.task/impl-001.1.json) - - [ ] **IMPL-001.1.1**: [Action Item] โ†’ [๐Ÿ“‹ Details](./.task/impl-001.1.1.json) -- [ ] **IMPL-001.2**: [Subtask Description] โ†’ [๐Ÿ“‹ Details](./.task/impl-001.2.json) - -## Notes -[Quick notes and reminders for the project] -``` - -**Format Notes**: -- Main tasks use bold formatting: `**IMPL-XXX**` -- Subtasks indent under parent tasks -- Links to task JSON files for details -- Links to summaries when completed -- Keep format simple and scannable - -## Chat Session Management - -### Chat Directory Structure -``` -.chat/ -โ”œโ”€โ”€ chat-YYYYMMDD-HHMMSS.md # Individual chat sessions with timestamps -โ”œโ”€โ”€ analysis-[topic].md # Comprehensive analysis results -โ””โ”€โ”€ context-[phase].md # Phase-specific context gathering -``` - -### Chat Session Template -```markdown -# Chat Session: [Timestamp] - [Topic] - -## Query -[Original user inquiry] - -## Template Used -[Auto-selected template name and rationale] - -## Context -[Files and patterns included in analysis] - -## Gemini Response -[Complete response from Gemini CLI] - -## Key Insights -- [Important findings] -- [Architectural insights] -- [Implementation recommendations] - -## Links -- [๐Ÿ”™ Back to Workflow](../workflow-session.json) -- [๐Ÿ“‹ Implementation Plan](../IMPL_PLAN.md) -``` - -## Summary Management - -### Summary Directory Structure -``` -.summaries/ -โ”œโ”€โ”€ IMPL-001-summary.md # Main task summaries -โ”œโ”€โ”€ IMPL-001.1-summary.md # Subtask summaries -โ””โ”€โ”€ IMPL-001.1.1-summary.md # Detailed subtask summaries -``` - -### Summary Template -```markdown -# Task Summary: [Task-ID] [Task Name] - -## What Was Done -- [Files modified/created] -- [Functionality implemented] -- [Key changes made] - -## Issues Resolved -- [Problems solved] -- [Bugs fixed] - -## Links -- [๐Ÿ”™ Back to Task List](../TODO_LIST.md#[Task-ID]) -- [๐Ÿ“‹ Implementation Plan](../IMPL_PLAN.md#[Task-ID]) -``` - -## Brainstorming Integration - -When `.brainstorming/` directory exists, documents MUST reference brainstorming results: - -### In IMPL_PLAN.md -```markdown -## Brainstorming Integration -Based on multi-role analysis from `.brainstorming/`: -- **Architecture Insights**: [Reference system-architect/analysis.md] -- **User Experience Considerations**: [Reference ui-designer/analysis.md] -- **Technical Requirements**: [Reference relevant role analyses] -- **Implementation Priorities**: [Reference synthesis-analysis.md] -``` - -### In JSON Task Context -```json -{ - "context": { - "brainstorming_refs": [ - ".workflow/WFS-[topic-slug]/.brainstorming/system-architect/technical-specifications.md", - ".workflow/WFS-[topic-slug]/.brainstorming/ui-designer/user-experience-plan.md" - ], - "requirements": ["derived from brainstorming analysis"] - } -} -``` - -## Quality Control - -### File System Validation -- Verify directory structure matches complexity level -- Validate file naming conventions -- Check for required vs optional directories -- Ensure proper file permissions - -### Cross-Reference Validation -- All document links point to existing files -- Task IDs consistent across JSON files and TODO_LIST.md -- Brainstorming references are valid when .brainstorming/ exists -- Summary links properly reference parent tasks - -### Performance Considerations -- Lazy directory creation (create only when needed) -- Efficient file structure scanning -- Minimal overhead for simple workflows -- Scalable organization for complex projects - -## Error Recovery - -### Missing File Scenarios -- **workflow-session.json missing**: Recreate from available documents -- **Required directories missing**: Auto-create with proper structure -- **Template files corrupted**: Regenerate from templates -- **Naming convention violations**: Auto-correct or flag for manual resolution - -### Structure Consistency -- Validate structure level matches task complexity -- Auto-upgrade structure when complexity increases -- Maintain backward compatibility during transitions -- Preserve existing content during structure changes - ---- - -**System ensures**: Consistent, scalable file organization with minimal overhead for simple tasks โ†’ comprehensive structure for complex projects - diff --git a/.claude/workflows/gemini-unified.md b/.claude/workflows/gemini-unified.md index 8dbd266f..e7019d50 100644 --- a/.claude/workflows/gemini-unified.md +++ b/.claude/workflows/gemini-unified.md @@ -1,239 +1,201 @@ +```markdown --- name: gemini-unified description: Consolidated Gemini CLI guidelines - core rules, syntax, patterns, templates, and best practices type: technical-guideline --- -# Unified Gemini CLI Guidelines +### ๐Ÿš€ Command Overview: `gemini` -## ๐Ÿš€ Core Rules +- **Purpose**: A CLI tool for comprehensive codebase analysis, context gathering, and pattern detection across multiple files. +- **Primary Triggers**: + - When user intent is to "analyze", "get context", or "understand the codebase". + - When a task requires understanding relationships between multiple files. + - When the problem scope exceeds a single file. +- **Core Use Cases**: + - Project-wide context acquisition. + - Architectural analysis and pattern detection. + - Identification of coding standards and conventions. -### When to Trigger -- **Semantic Intent**: User asks to "analyze with Gemini", "get context", or "understand codebase" -- **Context Need**: Task requires understanding multiple files or relationships -- **Complex Analysis**: Problem exceeds single-file scope +### โš™๏ธ Command Syntax & Arguments -### Primary Use Cases -- Project context acquisition and codebase understanding -- Pattern detection and architectural analysis -- Standards extraction and convention identification +- **Basic Structure**: + ```bash + gemini [flags] -p "@{patterns} {template} prompt" + ``` +- **Key Arguments**: + - `--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/gemini-templates/prompts/[category]/[template].txt)` for standardized analysis + - `@{pattern}`: A special syntax for referencing files and directories. -### Standard Template Structure +- **Template Usage**: + ```bash + # Without template (manual prompt) + gemini -p "@{src/**/*} @{CLAUDE.md} Analyze code patterns and conventions" + + # With template (recommended) + gemini -p "@{src/**/*} @{CLAUDE.md} $(cat ~/.claude/workflows/gemini-templates/prompts/analysis/pattern.txt)" + + # Multi-template composition + gemini -p "@{src/**/*} @{CLAUDE.md} $(cat <<'EOF' + $(cat ~/.claude/workflows/gemini-templates/prompts/analysis/architecture.txt) + + Additional Security Focus: + $(cat ~/.claude/workflows/gemini-templates/prompts/analysis/security.txt) + EOF + )" + ``` -#### Basic Structure (Manual Prompts) -```bash -gemini --all-files -p "@{target_patterns} @{CLAUDE.md,**/*CLAUDE.md} +### ๐Ÿ”„ Execution Modes -Context: [Analysis type] targeting @{target_patterns} -Guidelines: Include CLAUDE.md standards +- **1. Directory-Scoped**: Navigate to a directory first, then run `gemini`. + ```bash + cd src/components && gemini --all-files -p "@{CLAUDE.md} Analyze component patterns" + ``` +- **2. Pattern-Based**: Target files directly from any location using patterns. + ```bash + gemini -p "@{src/components/**/*} @{CLAUDE.md} Analyze component patterns" + ``` +- **3. Template-Injected**: Use `$(cat)` to inject a predefined prompt template. + ```bash + gemini -p "@{src/**/*} $(cat ~/.claude/workflows/gemini-templates/prompts/analysis/pattern.txt)" + ``` +- **4. Parallel Execution**: Run multiple analyses concurrently for efficiency. + ```bash + ( + gemini -p "@{**/*auth*} @{CLAUDE.md} Auth patterns" & + gemini -p "@{**/api/**/*} @{CLAUDE.md} API patterns" & + wait + ) + ``` -## Analysis: -1. [Point 1] -2. [Point 2] -3. [Point 3] +### ๐Ÿ“‚ File Pattern Rules -## Output: -- File:line references -- Code examples -- Actionable guidance -- Standards compliance" +- **Syntax**: + - `@{pattern}`: Single file or directory pattern. + - `@{pattern1,pattern2}`: Multiple patterns, comma-separated. +- **Wildcards**: + ```bash + * # Any character (excluding path separators) + ** # Any directory levels (recursive) + ? # Any single character + [abc] # Any character within the brackets + {a,b,c} # Any of the options within the braces + ``` +- **Cross-Platform Rules**: + - Always use forward slashes (`/`) for paths. + - Enclose paths with spaces in quotes: `@{"My Project/src/**/*"}`. + - Escape special characters like brackets: `@{src/**/*\[bracket\]*}`. + +### ๐Ÿง  Smart Pattern Discovery - Logic Flow + +This feature automates the process of finding relevant files for analysis. + +`Step 1: Analyze File Extensions` -> `Step 2: Generate Patterns` -> `Step 3: Execute Gemini` + +```pseudo +FUNCTION analyze_and_run_gemini(analysis_type): + // Step 1: Analyze the project's file types. + // Corresponds to the `discover_extensions` shell function. + discovered_extensions = analyze_project_extensions() + log("Discovered extensions:", discovered_extensions) + + // Also identify the likely primary programming language. + // Corresponds to the `detect_primary_language` shell function. + primary_language = detect_main_language(discovered_extensions) + log("Primary language:", primary_language) + + // Step 2: Generate file patterns based on the analysis type (e.g., "code", "config"). + // Corresponds to the `generate_patterns_by_extension` shell function. + patterns = generate_patterns(analysis_type, discovered_extensions) + log("Generated patterns:", patterns) + + // Step 3: Construct and execute the gemini command. + // Always include project standards from CLAUDE.md. + // Uses a pre-defined analysis template for consistency. + command = "gemini -p \"" + patterns + " @{CLAUDE.md} $(cat ~/.claude/workflows/gemini-templates/prompts/analysis/pattern.txt)\"" + execute_shell(command) + +END FUNCTION ``` -#### Template-Enhanced Structure (Recommended) -```bash -# Using predefined templates for consistent analysis -gemini --all-files -p "@{target_patterns} @{CLAUDE.md,**/*CLAUDE.md} -$(cat ~/.claude/workflows/gemini-templates/prompts/[category]/[template].txt)" -``` +### ๐Ÿ“œ Smart Discovery - Shell Implementation -#### Template Reference Examples -```bash -# Pattern analysis with template -gemini -p "@{src/**/*} @{CLAUDE.md} $(cat ~/.claude/workflows/gemini-templates/prompts/analysis/pattern.txt)" +These functions provide the concrete implementation for the smart discovery logic. -# Architecture analysis with template -gemini -p "@{src/**/*} @{CLAUDE.md} $(cat ~/.claude/workflows/gemini-templates/prompts/analysis/architecture.txt)" +- **Step 1: Analyze File Extensions & Language** + ```bash + # Discover actual file types in project + discover_extensions() { + echo "=== File Extension Analysis ===" + find . -type f -name "*.*" 2>/dev/null | \ + sed 's/.*\.//' | \ + sort | uniq -c | sort -rn | \ + head -10 + } -# Multi-template composition -gemini -p "@{src/**/*} @{CLAUDE.md} $(cat <<'EOF' -$(cat ~/.claude/workflows/gemini-templates/prompts/analysis/pattern.txt) + # Identify primary language + detect_primary_language() { + local extensions=$(find . -type f -name "*.*" 2>/dev/null | sed 's/.*\.//' | sort | uniq -c | sort -rn) + if echo "$extensions" | grep -q "js\|jsx\|ts\|tsx"; then + echo "JavaScript/TypeScript" + elif echo "$extensions" | grep -q "py\|pyw"; then + echo "Python" + # ... other language checks ... + else + echo "Unknown/Mixed" + fi + } + ``` +- **Step 2: Generate Patterns** + ```bash + # Generate patterns from discovered extensions + generate_patterns_by_extension() { + local analysis_type="$1" + local top_exts=$(find . -type f -name "*.*" 2>/dev/null | sed 's/.*\.//' | sort | uniq -c | sort -rn | head -5 | awk '{print $2}') + local pattern="" + case "$analysis_type" in + "code") + for ext in $top_exts; do + case $ext in + js|ts|jsx|tsx|py|java|go|rs|cpp|c|h) + pattern="${pattern}**/*.${ext}," + ;; + esac + done + echo "@{${pattern%,}}" + ;; + "config") echo "@{*.json,*.yml,*.yaml,*.toml,*.ini,*.env}" ;; + "docs") echo "@{**/*.md,**/*.txt,**/README*}" ;; + "all") + for ext in $top_exts; do pattern="${pattern}**/*.${ext},"; done + echo "@{${pattern%,}}" + ;; + esac + } + ``` -Additional Security Focus: -$(cat ~/.claude/workflows/gemini-templates/prompts/analysis/security.txt) -EOF -)" -``` +### โšก Smart Discovery - Quick Commands -**Template Benefits:** -- **Consistency**: Standardized analysis structure across all uses -- **Completeness**: Pre-defined analysis points ensure comprehensive coverage -- **Quality**: Proven analysis frameworks with specific output requirements -- **Efficiency**: No need to manually construct analysis prompts +| Need | Command | Description | +|------|---------|-------------| +| Analyze Extensions | `discover_extensions` | View project file type distribution. | +| Code Files | `generate_patterns_by_extension "code"` | Generate patterns for source code files only. | +| Config Files | `generate_patterns_by_extension "config"` | Generate patterns for configuration files. | +| Docs | `generate_patterns_by_extension "docs"` | Generate patterns for documentation. | +| All Top Types | `generate_patterns_by_extension "all"` | Generate patterns for all discovered file types. | -**Mandatory**: Always include `@{CLAUDE.md,**/*CLAUDE.md}` for project standards. +### TPL (Templates) -## โš™๏ธ Command Syntax - -### Basic Structure -```bash -gemini [flags] -p "@{patterns} prompt" -``` - -### Key Arguments -- `--all-files`: Includes all files in current directory (path-dependent) -- `-p`: Prompt string with file patterns and query -- `@{pattern}`: File reference pattern - -### Execution Modes - -#### 1. Directory-Scoped -Navigate first, then execute: -```bash -cd src/components && gemini --all-files -p "@{CLAUDE.md} Analyze patterns" -``` - -#### 2. Pattern-Based -Target files directly: -```bash -gemini -p "@{src/components/**/*} @{CLAUDE.md} Component analysis" -``` - -#### 3. Template-Injected -Use `$(cat)` for templates: -```bash -gemini -p "@{src/**/*} $(cat ~/.claude/workflows/gemini-templates/prompts/analysis/pattern.txt)" -``` - -#### 4. Parallel Execution -Multiple analyses concurrently: -```bash -( - gemini -p "@{**/*auth*} @{CLAUDE.md} Auth patterns" & - gemini -p "@{**/api/**/*} @{CLAUDE.md} API patterns" & - wait -) -``` - -## ๐Ÿ“‚ File Patterns - -### Pattern Syntax -```bash -@{pattern} # Single pattern -@{pattern1,pattern2} # Multiple patterns -``` - -### Wildcards -```bash -* # Any character (not path separators) -** # Any directory levels -? # Single character -[abc] # Character in brackets -{a,b,c} # Any option in braces -``` - -### Frontend Patterns -```bash -# React -@{src/components/**/*.{jsx,tsx}} -@{src/hooks/**/*.{js,ts}} -@{src/context/**/*.{jsx,tsx}} - -# Vue -@{src/components/**/*.vue} -@{src/composables/**/*.{js,ts}} - -# Angular -@{src/app/**/*.component.{ts,html}} -@{src/app/**/*.service.ts} -``` - -### Backend Patterns -```bash -# Node.js -@{routes/**/*.js,controllers/**/*.js} -@{middleware/**/*.js} -@{models/**/*.js} - -# Python -@{**/views.py,**/models.py,**/urls.py} -@{**/serializers.py} - -# Java -@{**/*Controller.java} -@{**/*Service.java,**/*Repository.java} -``` - -### Config & Testing -```bash -# Configuration -@{*.config.{js,ts},**/*.config.*} -@{package.json,yarn.lock} -@{Dockerfile,docker-compose.yml} - -# Tests -@{**/*.test.{js,ts,jsx,tsx}} -@{**/*.spec.{js,ts}} -@{**/__tests__/**/*} - -# Documentation -@{**/*.md,**/README*} -@{**/*.d.ts,**/types/**/*.ts} -``` - -### Domain Patterns -```bash -# Auth & Security -@{**/*auth*,**/*login*,**/*session*} -@{**/*permission*,**/*role*} -@{**/*crypto*,**/*hash*} - -# API & Data -@{**/api/**/*,**/routes/**/*} -@{**/controllers/**/*,**/handlers/**/*} -@{**/models/**/*,**/entities/**/*} - -# UI & Styling -@{src/components/**/*,src/ui/**/*} -@{src/styles/**/*,**/*.{css,scss,sass}} -@{src/layouts/**/*} -``` - -### Cross-Platform Rules -- Always use forward slashes: `@{src/components/**/*}` -- Quote paths with spaces: `@{"My Project/src/**/*"}` -- Escape special chars: `@{src/**/*\[bracket\]*}` - -## ๐Ÿ“‹ Template System - -### Template Categories and Functions - -#### Analysis Templates (`prompts/analysis/`) -- **`pattern.txt`** - ๅˆ†ๆžไปฃ็ ๆจกๅผใ€ๅทฅๅ…ทๅบ“ใ€็ผ–็ ๆ ‡ๅ‡†ๅ’Œๅๆจกๅผ -- **`architecture.txt`** - ๆ˜ ๅฐ„ๆจกๅ—ไพ่ต–ใ€้›†ๆˆ็‚นใ€ๅฏๆ‰ฉๅฑ•ๆ€ง่ฏ„ไผฐ -- **`security.txt`** - ๆ‰ซๆๅฎ‰ๅ…จๆผๆดžใ€่ฎค่ฏ้—ฎ้ข˜ใ€ๅŠ ๅฏ†ๆ–นๆณ• -- **`performance.txt`** - ่ฏ†ๅˆซ็“ถ้ขˆใ€็ฎ—ๆณ•ๅคๆ‚ๅบฆใ€็ผ“ๅญ˜็ญ–็•ฅ -- **`quality.txt`** - ่ฏ„ไผฐๅฏ็ปดๆŠคๆ€งใ€ๆŠ€ๆœฏๅ€บๅŠกใ€ไปฃ็ ็ป„็ป‡ - -#### Planning Templates (`prompts/planning/`) -- **`task-breakdown.txt`** - ไปปๅŠกๅˆ†่งฃใ€ไพ่ต–ๅ…ณ็ณปใ€ๅทฅไฝœ้‡ไผฐ็ฎ— -- **`migration.txt`** - ็ณป็ปŸ่ฟ็งป่ง„ๅˆ’ใ€ๅ…ผๅฎนๆ€งใ€้ฃŽ้™ฉ่ฏ„ไผฐ - -#### Implementation Templates (`prompts/implementation/`) -- **`component.txt`** - ็ป„ไปถๆŽฅๅฃ่ฎพ่ฎกใ€็Šถๆ€็ฎก็†ใ€ๆต‹่ฏ•ๆ–นๆณ• - -#### Review Templates (`prompts/review/`) -- **`code-review.txt`** - ๅ…จ้ขไปฃ็ ๅฎกๆŸฅใ€่ดจ้‡ๆฃ€ๆŸฅใ€ๆ ‡ๅ‡†ๅˆ่ง„ - -#### DMS Templates (`prompts/dms/`) -- **`hierarchy-analysis.txt`** - ้กน็›ฎๅคๆ‚ๅบฆๅˆ†ๆžใ€ๆ–‡ๆกฃ็ป“ๆž„ไผ˜ๅŒ– - -### Directory Structure +#### ๐Ÿ—‚๏ธ Template Directory Structure +This structure must be located at `~/.claude/workflows/gemini-templates/`. ``` ~/.claude/workflows/gemini-templates/ โ”œโ”€โ”€ prompts/ โ”‚ โ”œโ”€โ”€ analysis/ # Code analysis templates โ”‚ โ”‚ โ”œโ”€โ”€ pattern.txt # โœจ Implementation patterns & conventions -โ”‚ โ”‚ โ”œโ”€โ”€ architecture.txt # ๐Ÿ—๏ธ System architecture & dependencies +โ”‚ โ”‚ โ”œโ”€โ”€ architecture.txt # ๐Ÿ—๏ธ System architecture & dependencies โ”‚ โ”‚ โ”œโ”€โ”€ security.txt # ๐Ÿ”’ Security vulnerabilities & protection โ”‚ โ”‚ โ”œโ”€โ”€ performance.txt # โšก Performance bottlenecks & optimization โ”‚ โ”‚ โ””โ”€โ”€ quality.txt # ๐Ÿ“Š Code quality & maintainability @@ -247,127 +209,86 @@ Multiple analyses concurrently: โ”‚ โ””โ”€โ”€ dms/ # DMS-specific โ”‚ โ””โ”€โ”€ hierarchy-analysis.txt # ๐Ÿ“š Documentation structure optimization โ””โ”€โ”€ commands/ # Command examples - โ”œโ”€โ”€ context-analysis.md # Complete context gathering examples - โ”œโ”€โ”€ parallel-execution.md # Parallel analysis patterns - โ””โ”€โ”€ folder-analysis.md # Directory-specific analysis ``` -### Template Selection Guide -| ไปปๅŠก็ฑปๅž‹ | ไธป่ฆๆจกๆฟ | ็”จ้€” | -|---------|---------|------| -| ็†่งฃ็Žฐๆœ‰ไปฃ็  | `pattern.txt` | ๅญฆไน ไปฃ็ ๅบ“ใ€ๅ…ฅ่ŒๅŸน่ฎญ | -| ่ง„ๅˆ’ๆ–ฐๅŠŸ่ƒฝ | `task-breakdown.txt` | ๅŠŸ่ƒฝๅผ€ๅ‘่ง„ๅˆ’ | -| ๅฎ‰ๅ…จๅฎกๆŸฅ | `security.txt` | ๅฎ‰ๅ…จๅฎก่ฎกใ€ๆผๆดž่ฏ„ไผฐ | -| ๆ€ง่ƒฝไผ˜ๅŒ– | `performance.txt` | ๆ€ง่ƒฝ้—ฎ้ข˜ๆŽ’ๆŸฅ | -| ไปฃ็ ่ดจ้‡ๆ”น่ฟ› | `quality.txt` | ้‡ๆž„ใ€ๆŠ€ๆœฏๅ€บๅŠกๅ‡ๅฐ‘ | -| ็ณป็ปŸ็ŽฐไปฃๅŒ– | `migration.txt` | ๆŠ€ๆœฏๅ‡็บงใ€ๆžถๆž„ๅ˜ๆ›ด | -| ็ป„ไปถๅผ€ๅ‘ | `component.txt` | ๆž„ๅปบๅฏๅค็”จ็ป„ไปถ | -| ๅ‘ๅธƒๅ‰ๅฎกๆŸฅ | `code-review.txt` | ๅ‘ๅธƒๅฐฑ็ปชๆฃ€ๆŸฅ | +#### ๐Ÿงญ Template Selection Guide +| Task Type | Primary Template | Purpose | +|---|---|---| +| Understand Existing Code | `pattern.txt` | Codebase learning, onboarding. | +| Plan New Features | `task-breakdown.txt`| Feature development planning. | +| Security Review | `security.txt` | Security audits, vulnerability assessment. | +| Performance Tuning | `performance.txt` | Bottleneck investigation. | +| Code Quality Improvement | `quality.txt` | Refactoring, technical debt reduction. | +| System Modernization | `migration.txt` | Tech upgrades, architectural changes. | +| Component Development | `component.txt` | Building reusable components. | +| Pre-Release Review | `code-review.txt` | Release readiness checks. | -### Template Usage Examples -#### Basic Template Usage -```bash -# Single template - pattern analysis -gemini -p "@{src/**/*} $(cat ~/.claude/workflows/gemini-templates/prompts/analysis/pattern.txt)" +### ๐Ÿ“ฆ Standard Command Structures -# Multi-template composition -gemini -p "@{src/**/*} $(cat <<'EOF' -$(cat ~/.claude/workflows/gemini-templates/prompts/analysis/architecture.txt) +These are recommended command templates for common scenarios. -Additional Quality Focus: -$(cat ~/.claude/workflows/gemini-templates/prompts/analysis/quality.txt) -EOF -)" -``` +- **Basic Structure (Manual Prompt)** + ```bash + gemini --all-files -p "@{target_patterns} @{CLAUDE.md,**/*CLAUDE.md} -#### Common Use Cases -```bash -# New feature development workflow -gemini -p "@{src/**/*similar*} $(cat ~/.claude/workflows/gemini-templates/prompts/analysis/pattern.txt)" -gemini -p "@{src/**/*} $(cat ~/.claude/workflows/gemini-templates/prompts/planning/task-breakdown.txt)" + Context: [Analysis type] targeting @{target_patterns} + Guidelines: Include CLAUDE.md standards -# Security audit -gemini -p "@{**/*auth*,**/*login*} $(cat ~/.claude/workflows/gemini-templates/prompts/analysis/security.txt)" + ## Analysis: + 1. [Point 1] + 2. [Point 2] -# Performance optimization -gemini -p "@{src/**/*} $(cat ~/.claude/workflows/gemini-templates/prompts/analysis/performance.txt)" -``` + ## Output: + - File:line references + - Code examples" + ``` -#### Template Best Practices -- **Single Template**: ไธ“ๆณจๅˆ†ๆžใ€็‰นๅฎš้—ฎ้ข˜ใ€ๆ—ถ้—ด้™ๅˆถ -- **Multiple Templates**: ็ปผๅˆๅฎกๆŸฅใ€ๅคๆ‚้กน็›ฎใ€ๅ…จ้ข่ง„ๅˆ’ -- **Performance**: ๅˆๅนถ็›ธๅ…ณๆจกๆฟๅˆฐๅ•ไธชๅ‘ฝไปค๏ผŒไฝฟ็”จ็‰นๅฎšๆ–‡ไปถๆจกๅผๅ‡ๅฐ‘่Œƒๅ›ด +- **Template-Enhanced (Recommended)** + ```bash + # Using a predefined template for consistent, high-quality analysis + gemini --all-files -p "@{target_patterns} @{CLAUDE.md,**/*CLAUDE.md} $(cat ~/.claude/workflows/gemini-templates/prompts/[category]/[template].txt) -## ๐Ÿง  Intelligent Features + ## Analysis: + 1. [Point 1] + 2. [Point 2] -### Technology Detection -```python -# Simplified logic -indicators = { - 'React': ['package.json contains react', '**/*.jsx'], - 'Vue': ['package.json contains vue', '**/*.vue'], - 'Python': ['requirements.txt', '**/*.py'], - 'Java': ['pom.xml', '**/*.java'] -} -``` + ## Output: + - File:line references + - Code examples" + " + ``` -### Domain Extraction -```python -# Domain mapping -domains = { - 'auth': ['authentication', 'login', 'session'], - 'api': ['api', 'endpoint', 'route'], - 'frontend': ['component', 'ui', 'react'], - 'backend': ['server', 'database', 'model'] -} -``` +- **Multi-Template Composition** + ```bash + gemini -p "@{src/**/*} @{CLAUDE.md} + $(cat ~/.claude/workflows/gemini-templates/prompts/analysis/pattern.txt) -### Fallback Strategy -1. **Primary Pattern**: Try user-specified pattern -2. **Simplified Pattern**: Remove extensions/specificity -3. **Directory Pattern**: Use common directories like `@{src/**/*}` + Additional Security Focus: + $(cat ~/.claude/workflows/gemini-templates/prompts/analysis/security.txt) -### Performance Tips -- Avoid patterns matching >1000 files -- Use directory-scoped execution for large projects -- Prefer specific patterns over broad ones -- Process large datasets in parallel chunks + ## Analysis: + 1. [Point 1] + 2. [Point 2] -## โญ Best Practices + ## Output: + - File:line references + - Code examples" + " + ``` -### Core Principles -- **Always include** `@{CLAUDE.md,**/*CLAUDE.md}` for project context -- **Be specific** with patterns to reduce scope and improve performance -- **Group logically** related patterns in single commands -- **Use forward slashes** for cross-platform compatibility +### โญ Best Practices & Rules -### Common Patterns -```bash -# Get project context -gemini --all-files -p "@{src/**/*} @{CLAUDE.md} Extract patterns and standards" +- **Mandatory Context**: Always include `@{CLAUDE.md,**/*CLAUDE.md}` to ground the analysis in project-specific standards. +- **Specificity**: Use precise file patterns to reduce scope, improve performance, and increase accuracy. +- **Performance**: Avoid overly broad patterns (`@{**/*}`) on large projects. Prefer directory-scoped execution or parallel chunks. +- **Agent Integration**: All agent workflows **must** begin with a context analysis step using `gemini`. + ```bash + # Mandatory first step for any agent task + gemini --all-files -p "@{relevant_patterns} @{CLAUDE.md} Context for: [task_description]" + ``` +- **Error Handling**: + - Validate patterns match existing files before executing a long analysis. + - Quote paths that contain spaces or special characters. + - Test complex patterns on a small subset of files first. -# Domain analysis -gemini -p "@{**/*auth*} @{CLAUDE.md} Authentication implementation analysis" - -# Technology-specific -gemini -p "@{src/components/**/*} $(cat ~/.claude/workflows/gemini-templates/prompts/tech/react-component.txt)" -``` - -### Error Handling -- Validate patterns match files before execution -- Use fallback patterns for robustness -- Quote paths with spaces or special characters -- Test patterns on small subsets first - -### Agent Integration -All agent workflows should begin with context analysis: -```bash -# Mandatory first step -gemini --all-files -p "@{relevant_patterns} @{CLAUDE.md} Context for: [task_description]" -``` - -### Integration References -- This unified guide replaces all individual Gemini guideline files -- Templates are stored in `~/.claude/workflows/gemini-templates/` -- Always reference this file for Gemini CLI usage patterns \ No newline at end of file diff --git a/.claude/workflows/session-management-principles.md b/.claude/workflows/session-management-principles.md deleted file mode 100644 index 4ae2c6e5..00000000 --- a/.claude/workflows/session-management-principles.md +++ /dev/null @@ -1,278 +0,0 @@ -# Workflow Session Management Principles - -## Overview - -This document provides simplified session state management using marker files for active session tracking. - -## Multi-Session Architecture - -### Active Session Marker System -**Ultra-Simple Active Tracking**: `.workflow/.active-[session-name]` - -The system supports multiple concurrent sessions with a single active session marked by file presence: -```bash -.workflow/ -โ”œโ”€โ”€ WFS-oauth-integration/ # Session directory (paused) -โ”œโ”€โ”€ WFS-user-profile/ # Session directory (paused) -โ”œโ”€โ”€ WFS-bug-fix-123/ # Session directory (completed) -โ””โ”€โ”€ .active-WFS-user-profile # Marker file (indicates active session) -``` - -**Marker File Benefits**: -- **Zero Parsing**: File existence check is atomic and instant -- **Atomic Operations**: File creation/deletion is naturally atomic -- **Visual Discovery**: `ls .workflow/.active-*` shows active session immediately -- **No Corruption Risk**: No JSON parsing, no file format issues -- **Simple Switching**: Delete old marker + create new marker = session switch - -### Command Pre-execution Protocol -**Universal Session Awareness**: All commands automatically detect active session through marker file - -```pseudo -FUNCTION execute_command(command, args): - active_marker = find_file(".workflow/.active-*") - - IF active_marker EXISTS: - session_name = extract_name_from_marker(active_marker) - session_dir = ".workflow/" + session_name - context = load_session_context(session_dir + "/workflow-session.json") - workspace = session_dir - ELSE: - context = create_temporary_workspace() - workspace = temporary_directory - - execute_with_context(command, args, context, workspace) -END FUNCTION -``` - -**Protocol Benefits**: -- **Instant Discovery**: No file parsing, just check file existence -- **Context Inheritance**: Use active session directory for all operations -- **Fallback Mode**: Commands work without any active session -- **Output Location**: Active session determines file creation location -- **Task Context**: Active session provides current workflow context - -### Session State Management - -#### Active Session Detection -```bash -# Check for active session -active_session=$(ls .workflow/.active-* 2>/dev/null | head -1) -if [ -n "$active_session" ]; then - session_name=$(basename "$active_session" | sed 's/^\.active-//') - echo "Active session: $session_name" -else - echo "No active session" -fi -``` - -#### Session Activation -```bash -# Switch to different session -rm .workflow/.active-* 2>/dev/null # Remove any existing active marker -touch .workflow/.active-WFS-new-feature # Mark new session as active -``` - -#### Session Discovery -```bash -# List all available sessions -ls -d .workflow/WFS-*/ 2>/dev/null | sed 's|.workflow/||;s|/$||' - -# Show active session status -if ls .workflow/.active-* >/dev/null 2>&1; then - active=$(ls .workflow/.active-* | sed 's|.workflow/.active-||') - echo "โœ… Active: $active" -else - echo "โธ๏ธ No active session" -fi -``` - -## Individual Session Tracking - -All workflow state for each session managed through `workflow-session.json` in each session directory: - -### Session State Structure -```json -{ - "session_id": "WFS-[topic-slug]", - "project": "feature description", - "type": "simple|medium|complex", - "current_phase": "PLAN|IMPLEMENT|REVIEW", - "status": "active|paused|completed", - - "progress": { - "completed_phases": ["PLAN"], - "current_tasks": ["impl-1", "impl-2"], - "last_checkpoint": "2025-09-07T10:00:00Z" - }, - - "meta": { - "created": "2025-09-05T10:00:00Z", - "updated": "2025-09-07T10:00:00Z" - } -} -``` - -**Note**: The `status` field in individual session files is informational only. The actual active status is determined by the presence of `.active-[session-name]` marker file. - -## Session Lifecycle Operations - -### Create New Session -```bash -# 1. Create session directory -mkdir .workflow/WFS-new-feature - -# 2. Initialize workflow-session.json -echo '{"session_id":"WFS-new-feature","status":"active",...}' > .workflow/WFS-new-feature/workflow-session.json - -# 3. Set as active (deactivate others automatically) -rm .workflow/.active-* 2>/dev/null -touch .workflow/.active-WFS-new-feature -``` - -### Switch Session -```bash -# Atomic session switching -rm .workflow/.active-* 2>/dev/null && touch .workflow/.active-WFS-different-feature -``` - -### Pause Session (Deactivate) -```bash -# Remove active marker (session becomes paused) -rm .workflow/.active-WFS-current-feature -``` - -### Resume Session -```bash -# Reactivate paused session -rm .workflow/.active-* 2>/dev/null # Clear any active session -touch .workflow/.active-WFS-paused-session # Activate target session -``` - -### Complete Session -```bash -# 1. Update session status -echo '{"session_id":"WFS-feature","status":"completed",...}' > .workflow/WFS-feature/workflow-session.json - -# 2. Remove active marker -rm .workflow/.active-WFS-feature - -# 3. Optional: Archive session directory -mv .workflow/WFS-feature .workflow/completed/WFS-feature -``` - -## Simplified Phase Management - -### Phase-Level Tracking Only -- **Planning Phase**: Track completion status only -- **Implementation Phase**: Track active tasks, not detailed progress -- **Review Phase**: Track completion status only - -### Minimal Checkpoint Strategy -- **Phase Transitions**: Save state when moving between phases -- **User Request**: Manual checkpoint on explicit user action -- **Session End**: Final state save before closing - -### Checkpoint Data (Minimal) -```json -{ - "save_triggers": ["phase_complete", "user_request", "session_end"], - "save_data": ["phase_status", "active_tasks", "session_meta"], - "resume_logic": "resume_from_last_phase_checkpoint" -} -``` - -## Simplified Context Preservation - -### Essential Context Only -- Planning documents available to implementation phase -- Implementation results available to review phase -- Minimal handoff data between phases - -### Simple State Transitions -```json -{ - "phase_completed": "PLAN", - "next_phase": "IMPLEMENT", - "completed_at": "2025-09-07T10:00:00Z", - "artifacts": { - "plan_document": "IMPL_PLAN.md" - } -} -``` - -## Error Recovery and Validation - -### Session Consistency Checks -```bash -# Validate active session integrity -active_marker=$(ls .workflow/.active-* 2>/dev/null | head -1) -if [ -n "$active_marker" ]; then - session_name=$(basename "$active_marker" | sed 's/^\.active-//') - session_dir=".workflow/$session_name" - - if [ ! -d "$session_dir" ]; then - echo "โš ๏ธ Orphaned active marker: $active_marker" - echo " Session directory missing: $session_dir" - echo " Removing orphaned marker..." - rm "$active_marker" - fi -fi -``` - -### Multi-Active Session Detection -```bash -# Detect multiple active markers (error condition) -active_count=$(ls .workflow/.active-* 2>/dev/null | wc -l) -if [ "$active_count" -gt 1 ]; then - echo "โŒ Multiple active sessions detected:" - ls .workflow/.active-* | sed 's|.workflow/.active-| - |' - echo " Keeping most recent, removing others..." - - # Keep newest, remove others - newest=$(ls -t .workflow/.active-* 2>/dev/null | head -1) - ls .workflow/.active-* 2>/dev/null | grep -v "$newest" | xargs rm -f - echo " โœ… Resolved: $(basename "$newest" | sed 's/^\.active-//')" -fi -``` - -### Recovery Strategies -- **Missing Session Directory**: Remove orphaned active marker -- **Multiple Active Markers**: Keep newest, remove others -- **Corrupted Session File**: Recreate from template with session name -- **No Active Session**: Commands work in temporary mode - -## Performance Benefits - -### Ultra-Fast Operations -- **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 - -### Scalability -- **Hundreds of Sessions**: No performance degradation -- **Concurrent Access**: File system handles locking automatically -- **Atomic Operations**: No race conditions or corruption risk - -## Implementation Guidelines - -### Key Principles -- **File Existence = Truth**: Marker file presence is the single source of truth -- **Atomic State Changes**: All session operations are atomic file operations -- **Visual Management**: Users can see and manage active sessions directly -- **Zero Configuration**: No registry files to maintain or repair -- **Self-Healing**: Automatic detection and resolution of inconsistent states - - - -### Success Metrics -- Fast session resume (< 100ms) -- Zero parsing overhead -- Visual session management -- Self-healing consistency -- No registry maintenance needed - ---- - -**System ensures**: Ultra-simple session management using marker files for instant, atomic, and visually manageable session state tracking. \ No newline at end of file diff --git a/.claude/workflows/system-architecture.md b/.claude/workflows/system-architecture.md deleted file mode 100644 index 5e8620e7..00000000 --- a/.claude/workflows/system-architecture.md +++ /dev/null @@ -1,129 +0,0 @@ -# Workflow System Architecture - -## Core Philosophy - -### Document-State Separation -**"Documents store plans, JSON manages state"** - -- **Markdown Files** โ†’ Planning, requirements, task structure, implementation strategies -- **JSON Files** โ†’ Execution state, progress tracking, session metadata, dynamic changes -- **JSON-Only Data Model** โ†’ Single source of truth for all task state and workflow coordination - -### Progressive Complexity -**"Minimal overhead โ†’ comprehensive structure"** - -- **Simple** โ†’ Lightweight JSON + optional docs -- **Medium** โ†’ Structured planning + conditional documents -- **Complex** โ†’ Complete document suite + full coordination - -### Session-First Architecture -**"All commands check active session for context"** - -All workflow operations inherit from active session context through `.active-[session-name]` marker file system for seamless workflow integration. - -## System Components - -### Session Management -**Marker File System**: Ultra-simple active tracking using `.workflow/.active-[session-name]` - -- **Multi-Session Architecture**: Supports concurrent sessions with single active session pattern -- **Command Pre-execution Protocol**: All commands automatically detect active session through marker file -- **State Management**: Individual session state with phase-aware progress tracking - -**Technical Details**: @./session-management-principles.md - -### Data Model System -**JSON-Only Architecture**: Single source of truth with on-demand document generation - -- **Task Definitions**: JSON files contain all task data with hierarchical structure -- **No Synchronization**: Documents generated on-demand from JSON, no bidirectional sync -- **State Coordination**: Real-time coordination through JSON task files only - -**Technical Details**: @./data-model.md - -### File Structure System -**Progressive Structure**: Scales from minimal structure for simple tasks to comprehensive organization for complex workflows - -- **Complexity Levels**: Three levels (0-2) with automatic structure generation based on task count and scope -- **Standard Templates**: Consistent directory layouts and file naming across all complexity levels - -**Technical Details**: @./file-structure-standards.md - -### Agent Orchestration -**Context-Driven Coordination**: Gemini context analysis mandatory before agent execution - -- **Gemini Context Analysis**: MANDATORY context gathering before any agent execution -- **Dynamic Agent Selection**: Choose agents based on discovered context and patterns -- **Cross-Agent Context Sharing**: Maintain shared context state across all agents - -**Technical Details**: @./agent-orchestration-patterns.md - -## Architectural Principles - -### Fundamental Design Patterns - -#### Session-First Architecture -- All workflow operations inherit from active session context -- Multi-session support with single active session pattern -- Context switching preserves complete state - -#### Hierarchical Task Management -- JSON-based task definitions with up to 3 levels of decomposition -- Progress tracking with dependency management -- JSON-only data model eliminates synchronization issues - -#### Complexity-Driven Structure -- File structure scales automatically with task complexity -- Document generation triggered by complexity thresholds -- Progressive enhancement without breaking simple workflows - -#### Real-time Coordination -- TodoWrite tool provides immediate task visibility -- JSON task files maintain cross-session continuity -- Agent coordination through unified JSON interface - -## Quality Assurance Principles - -### Data Integrity -- Single source of truth: JSON task files -- Automatic validation and consistency checks -- Error recovery with graceful degradation - -### Performance Guidelines -- Lazy loading of complex structures -- Minimal overhead for simple workflows -- Real-time updates without blocking operations - -### Extensibility Rules -- Plugin architecture for specialized agents -- Template-based document generation -- Configurable complexity thresholds - -## Implementation Flow - -**Workflow Phases**: Session initialization โ†’ [Optional brainstorming] โ†’ Planning โ†’ Implementation โ†’ Review -**Progressive Complexity**: Structure and documentation automatically scale with task complexity -**Cross-Integration**: Real-time coordination across all system components through JSON-only data model - -## Command Integration - -### Embedded Workflow Logic -**Workflow Commands**: Session management, planning, and implementation with embedded document generation -**Task Commands**: Task creation, breakdown, execution, and status with automatic JSON coordination -**Manual Tools**: Maintenance operations for edge cases and manual intervention - -## Architecture Integration - -This document provides the technical architecture framework. For complete system documentation, see: - -**๐Ÿ“‹ Complete Documentation**: -- **Session Management**: @./session-management-principles.md -- **Data Model**: @./data-model.md -- **Complexity Rules**: @./complexity-rules.md -- **File Structure**: @./file-structure-standards.md -- **Agent Orchestration**: @./agent-orchestration-patterns.md -- **Brainstorming Integration**: @./brainstorming-principles.md - ---- - -**Architecture ensures**: Consistent scalable workflow management with JSON-only data model, marker file sessions, and progressive complexity scaling from simple tasks โ†’ comprehensive project coordination \ No newline at end of file diff --git a/.claude/workflows/workflow-architecture.md b/.claude/workflows/workflow-architecture.md new file mode 100644 index 00000000..9134c8a0 --- /dev/null +++ b/.claude/workflows/workflow-architecture.md @@ -0,0 +1,401 @@ +# Workflow Architecture + +## 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. + +## 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 +- **Agent-agnostic task definitions** - Complete context preserved for autonomous execution + +## Session Management + +### Active Session Marker System +**Ultra-Simple Active Tracking**: `.workflow/.active-[session-name]` + +```bash +.workflow/ +โ”œโ”€โ”€ WFS-oauth-integration/ # Session directory (paused) +โ”œโ”€โ”€ WFS-user-profile/ # Session directory (paused) +โ”œโ”€โ”€ WFS-bug-fix-123/ # Session directory (completed) +โ””โ”€โ”€ .active-WFS-user-profile # Marker file (indicates active session) +``` + +**Marker File Benefits**: +- **Zero Parsing**: File existence check is atomic and instant +- **Atomic Operations**: File creation/deletion is naturally atomic +- **Visual Discovery**: `ls .workflow/.active-*` shows active session immediately +- **Simple Switching**: Delete old marker + create new marker = session switch + +### Session Operations + +#### Detect Active Session +```bash +active_session=$(ls .workflow/.active-* 2>/dev/null | head -1) +if [ -n "$active_session" ]; then + session_name=$(basename "$active_session" | sed 's/^\.active-//') + echo "Active session: $session_name" +fi +``` + +#### Switch Session +```bash +rm .workflow/.active-* 2>/dev/null && touch .workflow/.active-WFS-new-feature +``` + +### Individual Session Tracking +Each session directory contains `workflow-session.json`: + +```json +{ + "session_id": "WFS-[topic-slug]", + "project": "feature description", + "type": "simple|medium|complex", + "current_phase": "PLAN|IMPLEMENT|REVIEW", + "status": "active|paused|completed", + "progress": { + "completed_phases": ["PLAN"], + "current_tasks": ["impl-1", "impl-2"], + "last_checkpoint": "2025-09-07T10:00:00Z" + }, + "meta": { + "created": "2025-09-05T10:00:00Z", + "updated": "2025-09-07T10:00:00Z" + } +} +``` + +## Data Model + +### JSON-Only Architecture +**JSON files (.task/impl-*.json) are the only authoritative source of task state. All markdown documents are read-only generated views.** + +- **Task State**: Stored exclusively in JSON files +- **Documents**: Generated on-demand from JSON data +- **No Synchronization**: Eliminates bidirectional sync complexity +- **Performance**: Direct JSON access without parsing overhead + +### Task JSON Schema +All task files use this 8-field schema: + +```json +{ + "id": "impl-1", + "title": "Build authentication module", + "status": "pending|active|completed|blocked|container", + "type": "feature|bugfix|refactor|test|docs", + "agent": "code-developer|planning-agent|test-agent|docs-agent", + + "context": { + "requirements": ["JWT authentication", "OAuth2 support"], + "scope": ["src/auth/*", "tests/auth/*"], + "acceptance": ["Module handles JWT tokens", "OAuth2 flow implemented"], + "inherited_from": "WFS-user-auth" + }, + + "relations": { + "parent": null, + "subtasks": ["impl-1.1", "impl-1.2"], + "dependencies": ["impl-0"] + }, + + "execution": { + "attempts": 0, + "last_attempt": null + }, + + "meta": { + "created": "2025-09-05T10:30:00Z", + "updated": "2025-09-05T10:30:00Z" + } +} +``` + +### Hierarchical Task System +**Maximum Depth**: 3 levels (impl-N.M.P format) + +``` +impl-1 # Main task +impl-1.1 # Subtask of impl-1 +impl-1.1.1 # Detailed subtask of impl-1.1 +impl-1.2 # Another subtask of impl-1 +impl-2 # Another main task +``` + +**Task Status Rules**: +- **Container tasks**: Parent tasks with subtasks (cannot be directly executed) +- **Leaf tasks**: Only these can be executed directly +- **Status inheritance**: Parent status derived from subtask completion + +## File Structure + +### Progressive Structure System +File structure scales with task complexity to minimize overhead for simple tasks while providing comprehensive organization for complex workflows. + +#### 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 +โ”œโ”€โ”€ .summaries/ # Task completion summaries +โ”‚ โ””โ”€โ”€ IMPL-*.md # Individual task 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 with timestamps +โ”‚ โ””โ”€โ”€ 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 + +#### Session Identifiers +**Format**: `WFS-[topic-slug]` +- Convert topic to lowercase with hyphens (e.g., "User Auth System" โ†’ `WFS-user-auth-system`) +- Add `-NNN` suffix only if conflicts exist (e.g., `WFS-payment-integration-002`) + +#### Document Naming +- `workflow-session.json` - Session state (required) +- `IMPL_PLAN.md` - Planning document (required) +- `TODO_LIST.md` - Progress tracking (auto-generated when needed) +- Chat sessions: `chat-YYYYMMDD-HHMMSS.md` +- Task summaries: `IMPL-[task-id]-summary.md` + +## Complexity Classification + +### Unified Classification Rules +**Consistent thresholds across all workflow components:** + +| 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 | + +### 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 +- **Agent Coordination**: Direct execution without complex orchestration + +### Medium Workflows +**Characteristics**: Feature implementation requiring 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 + +### 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 +- **Agent Coordination**: Multi-agent orchestration with deep context analysis + +### Automatic Assessment & Upgrades +- **During Creation**: System evaluates requirements and assigns complexity +- **During Execution**: Can upgrade (Simpleโ†’Mediumโ†’Complex) but never downgrade +- **Override Allowed**: Users can specify higher complexity manually + +## 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] +``` + +### TODO_LIST.md Template +```markdown +# Task Progress List: [Session Topic] + +## Implementation Tasks + +### Main Tasks +- [ ] **IMPL-001**: [Task Description] โ†’ [๐Ÿ“‹ Details](./.task/impl-001.json) +- [x] **IMPL-002**: [Completed Task] โ†’ [๐Ÿ“‹ Details](./.task/impl-002.json) | [โœ… Summary](./.summaries/IMPL-002-summary.md) + +### Subtasks (Auto-expanded when active) +- [ ] **IMPL-001.1**: [Subtask Description] โ†’ [๐Ÿ“‹ Details](./.task/impl-001.1.json) +``` + +## Agent Integration + +### Agent Assignment +Based on task type and title keywords: +- **Planning tasks** โ†’ planning-agent +- **Implementation** โ†’ code-developer +- **Testing** โ†’ test-agent +- **Documentation** โ†’ docs-agent +- **Review** โ†’ review-agent + +### Execution Context +Agents receive complete task JSON plus workflow context: +```json +{ + "task": { /* complete task JSON */ }, + "workflow": { + "session": "WFS-user-auth", + "phase": "IMPLEMENT" + } +} +``` + +## Data Operations + +### Task Creation +```bash +echo '{"id":"impl-1","title":"New task",...}' > .task/impl-1.json +``` + +### Task Updates +```bash +jq '.status = "active"' .task/impl-1.json > temp && mv temp .task/impl-1.json +``` + +### Document Generation +```bash +# Generate TODO_LIST.md from current JSON state +generate_todo_list_from_json .task/ +``` + +## Validation and Error Handling + +### Task Integrity Rules +1. **ID Uniqueness**: All task IDs must be unique +2. **Hierarchical Format**: Must follow impl-N[.M[.P]] pattern +3. **Parent References**: All parent IDs must exist as JSON files +4. **Depth Limits**: Maximum 3 levels deep +5. **Status Consistency**: Status values from defined enumeration +6. **Required Fields**: All 8 core fields must be present + +### Session Consistency Checks +```bash +# Validate active session integrity +active_marker=$(ls .workflow/.active-* 2>/dev/null | head -1) +if [ -n "$active_marker" ]; then + session_name=$(basename "$active_marker" | sed 's/^\.active-//') + session_dir=".workflow/$session_name" + + if [ ! -d "$session_dir" ]; then + echo "โš ๏ธ Orphaned active marker, removing..." + rm "$active_marker" + fi +fi +``` + +### Recovery Strategies +- **Missing Session Directory**: Remove orphaned active marker +- **Multiple Active Markers**: Keep newest, remove others +- **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