Claude-Code-Workflow/.claude/workflows/workflow-architecture.md

Workflow Architecture

Overview

This document defines the complete workflow system architecture using a JSON-only data model, marker-based session management, and unified file structure with dynamic task decomposition.

Core Architecture Principles

Key Design Decisions

• JSON files are the single source of truth - All markdown documents are read-only generated views
• Marker files for session tracking - Ultra-simple active session management
• Unified file structure definition - Same structure template for all workflows, created on-demand
• Dynamic task decomposition - Subtasks created as needed during execution
• On-demand file creation - Directories and files created only when required
• Agent-agnostic task definitions - Complete context preserved for autonomous execution

Session Management

Active Session Marker System

Ultra-Simple Active Tracking: .workflow/.active-[session-name]

.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

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

rm .workflow/.active-* 2>/dev/null && touch .workflow/.active-WFS-new-feature

Individual Session Tracking

Each session directory contains workflow-session.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"]
  }
}

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 10-field schema:

{
  "id": "impl-1",
  "title": "Build authentication module",
  "status": "pending|active|completed|blocked|container",
  "type": "feature|bugfix|refactor|test|docs", 
  "agent": "code-developer|planning-agent|code-review-test-agent",
  "paths": "src/auth;tests/auth;config/auth.json;src/middleware/auth.ts",
  
  "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
  },
  
  "implementation": {
    "files": [
      {
        "path": "src/auth/login.ts",
        "location": {
          "function": "handleLogin",
          "lines": "75-120",
          "description": "Core logic of login handler function"
        },
        "original_code": "// Related code not provided, requires gemini analysis",
        "modifications": {
          "current_state": "Currently using simple password validation",
          "proposed_changes": [
            "Add JWT token generation logic",
            "Integrate OAuth2 authentication flow", 
            "Enhance error handling mechanisms"
          ],
          "logic_flow": [
            "validateInput() ───► checkCredentials()",
            "◊─── if valid ───► generateJWT() ───► return token",
            "◊─── if OAuth ───► redirectToProvider() ───► handleCallback()",
            "◊─── if error ───► logError() ───► return errorResponse"
          ],
          "reason": "Meet JWT and OAuth2 authentication requirements, enhance security",
          "expected_outcome": "Flexible login system supporting multiple authentication methods"
        }
      }
    ],
    "context_notes": {
      "dependencies": ["jsonwebtoken", "passport-oauth2"],
      "affected_modules": ["user-profile", "session-manager"],
      "risks": [
        "Need to update authentication middleware for all API endpoints",
        "May affect existing user sessions",
        "Require database migration to add token storage table"
      ],
      "performance_considerations": "JWT validation will add approximately 5ms latency",
      "error_handling": "Ensure sensitive information is not leaked in error responses"
    },
    "analysis_source": "manual|gemini|codex|auto-detected"
  }
}

Paths Field Details

The paths field specifies concrete project paths (folders and files) relevant to the task implementation:

Path Format

• Semicolon-separated list: "folder1;folder2;specific_file.ts"
• Concrete paths: Use actual directory/file names without wildcards
• Mixed types: Can include both directories and specific files
• Relative paths: From project root (e.g., src/auth, not ./src/auth)

Path Selection Strategy

• Directories: Include relevant module directories (e.g., src/auth, tests/auth)
• Specific files: Include files explicitly mentioned in requirements (e.g., config/auth.json)
• Avoid wildcards: Use concrete paths discovered via get_modules_by_depth.sh
• Focus scope: Only include paths directly related to task implementation

Examples

// Authentication system task
"paths": "src/auth;tests/auth;config/auth.json;src/middleware/auth.ts"

// UI component task
"paths": "src/components/Button;src/styles;tests/components"

// Database migration task  
"paths": "migrations;src/models;config/database.json"

Implementation Field Details

The implementation field provides detailed code implementation guidance with 4 core components:

files Array - Detailed File Information

• path: File path or filename
• location: Specific code location (function name, class name, line range)
• original_code: Original code snippet to be modified (mark as "requires gemini analysis" if not obtained)
• modifications: Modification details
  • current_state: Brief description of current code state
  • proposed_changes: Step-by-step list of modification points
  • logic_flow: Data flow and call relationship diagram
  • reason: Modification rationale and objectives
  • expected_outcome: Expected results

context_notes - Implementation Context Information

• dependencies: Required dependency packages or modules
• affected_modules: Other modules that will be affected
• risks: Potential risk points and cascading effects
• performance_considerations: Performance impact assessment
• error_handling: Error handling requirements

analysis_source - Information Source Identifier

• manual: Detailed information manually provided by user
• gemini: Automatically obtained through Gemini CLI analysis
• codex: Automatically obtained through Codex CLI analysis
• auto-detected: Auto-detected based on task type and context

Hierarchical Task System

Maximum Depth: 2 levels (impl-N.M format)

impl-1              # Main task
impl-1.1            # Subtask of impl-1 (dynamically created)
impl-1.2            # Another subtask of impl-1
impl-2              # Another main task
impl-2.1            # Subtask of impl-2 (dynamically created)

Task Status Rules:

• 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

Unified File Structure

All workflows use the same file structure definition regardless of complexity. Directories and files are created on-demand as needed, not all at once during initialization.

Complete Structure Reference

.workflow/WFS-[topic-slug]/
├── workflow-session.json        # Session metadata and state (REQUIRED)
├── [.brainstorming/]           # Optional brainstorming phase (created when needed)
├── [.chat/]                    # CLI interaction sessions (created when analysis is run)
│   ├── chat-*.md              # Saved chat sessions
│   └── analysis-*.md          # Analysis results
├── IMPL_PLAN.md                # Planning document (REQUIRED)
├── TODO_LIST.md                # Progress tracking (REQUIRED)
├── [.summaries/]               # Task completion summaries (created when tasks complete)
│   ├── IMPL-*.md              # Main task summaries
│   └── IMPL-*.*.md            # Subtask summaries
└── .task/                      # Task definitions (REQUIRED)
    ├── impl-*.json             # Main task definitions
    └── impl-*.*.json           # Subtask definitions (created dynamically)

Creation Strategy

• Initial Setup: Create only workflow-session.json, IMPL_PLAN.md, TODO_LIST.md, and .task/ directory
• On-Demand Creation: Other directories created when first needed:
  • .brainstorming/ → When brainstorming phase is initiated
  • .chat/ → When CLI analysis commands are executed
  • .summaries/ → When first task is completed
• Dynamic Files: Subtask JSON files created during task decomposition

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-analysis-*.md
• Task summaries: IMPL-[task-id]-summary.md

Complexity Classification

Task Complexity Rules

Complexity is determined by task count and decomposition needs:

Complexity	Task Count	Hierarchy Depth	Decomposition Behavior
Simple	<5 tasks	1 level (impl-N)	Direct execution, minimal decomposition
Medium	5-15 tasks	2 levels (impl-N.M)	Moderate decomposition, context coordination
Complex	>15 tasks	2 levels (impl-N.M)	Frequent decomposition, multi-agent orchestration

Simple Workflows

Characteristics: Direct implementation tasks with clear, limited scope

• Examples: Bug fixes, small feature additions, configuration changes
• Task Decomposition: Usually single-level tasks, minimal breakdown needed
• Agent Coordination: Direct execution without complex orchestration

Medium Workflows

Characteristics: Feature implementation requiring moderate task breakdown

• Examples: New features, API endpoints with integration, database schema changes
• Task Decomposition: Two-level hierarchy when decomposition is needed
• Agent Coordination: Context coordination between related tasks

Complex Workflows

Characteristics: System-wide changes requiring detailed decomposition

• Examples: Major features, architecture refactoring, security implementations, multi-service deployments
• Task Decomposition: Frequent use of two-level hierarchy with dynamic subtask creation
• 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

Generated based on task complexity and requirements. Contains overview, requirements, and task structure.

TODO_LIST.md Template

# Tasks: [Session Topic]

## Task Progress
▸ **IMPL-001**: [Main Task Group] → [📋](./.task/impl-001.json)
  - [ ] **IMPL-001.1**: [Subtask] → [📋](./.task/impl-001.1.json)
  - [x] **IMPL-001.2**: [Subtask] → [📋](./.task/impl-001.2.json) | [✅](./.summaries/IMPL-001.2.md)
  
- [x] **IMPL-002**: [Simple Task] → [📋](./.task/impl-002.json) | [✅](./.summaries/IMPL-002.md)

▸ **IMPL-003**: [Main Task Group] → [📋](./.task/impl-003.json)
  - [ ] **IMPL-003.1**: [Subtask] → [📋](./.task/impl-003.1.json)
  - [ ] **IMPL-003.2**: [Subtask] → [📋](./.task/impl-003.2.json)

## Status Legend
- `▸` = Container task (has subtasks)
- `- [ ]` = Pending leaf task  
- `- [x]` = Completed leaf task
- Maximum 2 levels: Main tasks and subtasks only

## Notes
[Optional notes]

Agent Integration

Agent Assignment

Based on task type and title keywords:

• Planning tasks → planning-agent
• Implementation → code-developer
• Testing → code-review-test-agent
• Review → review-agent

Execution Context

Agents receive complete task JSON plus workflow context:

{
  "task": { /* complete task JSON */ },
  "workflow": {
    "session": "WFS-user-auth",
    "phase": "IMPLEMENT"
  }
}

Data Operations

Session Initialization

# Create minimal required structure
mkdir -p .workflow/WFS-topic-slug/.task
echo '{"session_id":"WFS-topic-slug",...}' > .workflow/WFS-topic-slug/workflow-session.json
echo '# Implementation Plan' > .workflow/WFS-topic-slug/IMPL_PLAN.md
echo '# Tasks' > .workflow/WFS-topic-slug/TODO_LIST.md

Task Creation

echo '{"id":"impl-1","title":"New task",...}' > .task/impl-1.json

Directory Creation (On-Demand)

# Create directories only when needed
mkdir -p .brainstorming     # When brainstorming is initiated
mkdir -p .chat              # When analysis commands are run
mkdir -p .summaries         # When first task completes

Task Updates

jq '.status = "active"' .task/impl-1.json > temp && mv temp .task/impl-1.json

Document Generation

# 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] pattern (maximum 2 levels)
3. Parent References: All parent IDs must exist as JSON files
4. Depth Limits: Maximum 2 levels deep
5. Status Consistency: Status values from defined enumeration
6. Required Fields: All 9 core fields must be present
7. Implementation Structure: implementation.files array must contain valid file paths
8. Analysis Source: analysis_source must be one of: manual|gemini|codex|auto-detected

Session Consistency Checks

# 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

---

System ensures: Unified workflow architecture with ultra-fast session management, JSON-only data model, and unified file structure for all workflows regardless of complexity.