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

### 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.**

- **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

### 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

### Directory-Based Session Management
**Simple Location-Based Tracking**: Sessions in `.workflow/active/` directory

```bash
.workflow/
├── active/
│   ├── WFS-oauth-integration/         # Active session directory
│   ├── WFS-user-profile/             # Active session directory
│   └── WFS-bug-fix-123/              # Active session directory
└── archives/
    └── WFS-old-feature/              # Archived session (completed)
```


### Session Operations

#### Detect Active Session(s)
```bash
active_sessions=$(find .workflow/active/ -name "WFS-*" -type d 2>/dev/null)
count=$(echo "$active_sessions" | wc -l)

if [ -z "$active_sessions" ]; then
  echo "No active session"
elif [ "$count" -eq 1 ]; then
  session_name=$(basename "$active_sessions")
  echo "Active session: $session_name"
else
  echo "Multiple sessions found:"
  echo "$active_sessions" | while read session_dir; do
    session=$(basename "$session_dir")
    echo "  - $session"
  done
  echo "Please specify which session to work with"
fi
```

#### Archive Session
```bash
mv .workflow/active/WFS-feature .workflow/archives/WFS-feature
```

### Session State 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"]
  }
}
```

## Task System

### Hierarchical Task Structure
**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

### Enhanced Task JSON Schema
All task files use this unified 6-field schema with optional artifacts enhancement:

```json
{
  "id": "IMPL-1.2",
  "title": "Implement JWT authentication",
  "status": "pending|active|completed|blocked|container",
  "context_package_path": ".workflow/WFS-session/.process/context-package.json",

  "meta": {
    "type": "feature|bugfix|refactor|test-gen|test-fix|docs",
    "agent": "@code-developer|@action-planning-agent|@test-fix-agent|@universal-executor"
  },

  "context": {
    "requirements": ["JWT authentication", "OAuth2 support"],
    "focus_paths": ["src/auth", "tests/auth", "config/auth.json"],
    "acceptance": ["JWT validation works", "OAuth flow complete"],
    "parent": "IMPL-1",
    "depends_on": ["IMPL-1.1"],
    "inherited": {
      "from": "IMPL-1",
      "context": ["Authentication system design completed"]
    },
    "shared_context": {
      "auth_strategy": "JWT with refresh tokens"
    },
    "artifacts": [
      {
        "type": "role_analyses",
        "source": "brainstorm_clarification",
        "path": ".workflow/WFS-session/.brainstorming/*/analysis*.md",
        "priority": "highest",
        "contains": "role_specific_requirements_and_design"
      }
    ]
  },

  "flow_control": {
    "pre_analysis": [
      {
        "step": "check_patterns",
        "action": "Analyze existing patterns",
        "command": "bash(rg 'auth' [focus_paths] | head -10)",
        "output_to": "patterns"
      },
      {
        "step": "analyze_architecture",
        "action": "Review system architecture",
        "command": "gemini \"analyze patterns: [patterns]\"",
        "output_to": "design"
      },
      {
        "step": "check_deps",
        "action": "Check dependencies",
        "command": "bash(echo [depends_on] | xargs cat)",
        "output_to": "context"
      }
    ],
    "implementation_approach": [
      {
        "step": 1,
        "title": "Set up authentication infrastructure",
        "description": "Install JWT library and create auth config following [design] patterns from [parent]",
        "modification_points": [
          "Add JWT library dependencies to package.json",
          "Create auth configuration file using [parent] patterns"
        ],
        "logic_flow": [
          "Install jsonwebtoken library via npm",
          "Configure JWT secret and expiration from [inherited]",
          "Export auth config for use by [jwt_generator]"
        ],
        "depends_on": [],
        "output": "auth_config"
      },
      {
        "step": 2,
        "title": "Implement JWT generation",
        "description": "Create JWT token generation logic using [auth_config] and [inherited] validation patterns",
        "modification_points": [
          "Add JWT generation function in auth service",
          "Implement token signing with [auth_config]"
        ],
        "logic_flow": [
          "User login → validate credentials with [inherited]",
          "Generate JWT payload with user data",
          "Sign JWT using secret from [auth_config]",
          "Return signed token"
        ],
        "depends_on": [1],
        "output": "jwt_generator"
      },
      {
        "step": 3,
        "title": "Implement JWT validation middleware",
        "description": "Create middleware to validate JWT tokens using [auth_config] and [shared] rules",
        "modification_points": [
          "Create validation middleware using [jwt_generator]",
          "Add token verification using [shared] rules",
          "Implement user attachment to request object"
        ],
        "logic_flow": [
          "Protected route → extract JWT from Authorization header",
          "Validate token signature using [auth_config]",
          "Check token expiration and [shared] rules",
          "Decode payload and attach user to request",
          "Call next() or return 401 error"
        ],
        "command": "bash(npm test -- middleware.test.ts)",
        "depends_on": [1, 2],
        "output": "auth_middleware"
      }
    ],
    "target_files": [
      "src/auth/login.ts:handleLogin:75-120",
      "src/middleware/auth.ts:validateToken",
      "src/auth/PasswordReset.ts"
    ]
  }
}
```

### Focus Paths & Context Management

#### Context Package Path (Top-Level Field)
The **context_package_path** field provides the location of the smart context package:
- **Location**: Top-level field (not in `artifacts` array)
- **Path**: `.workflow/WFS-session/.process/context-package.json`
- **Purpose**: References the comprehensive context package containing project structure, dependencies, and brainstorming artifacts catalog
- **Usage**: Loaded in `pre_analysis` steps via `Read({{context_package_path}})`

#### Focus Paths Format
The **focus_paths** field specifies concrete project paths for task implementation:
- **Array of strings**: `["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`)

#### Artifacts Field ⚠️ NEW FIELD
Optional field referencing brainstorming outputs for task execution:

```json
"artifacts": [
  {
    "type": "role_analyses|topic_framework|individual_role_analysis",
    "source": "brainstorm_clarification|brainstorm_framework|brainstorm_roles",
    "path": ".workflow/WFS-session/.brainstorming/document.md",
    "priority": "highest|high|medium|low"
  }
]
```

**Types & Priority**: role_analyses (highest) → topic_framework (medium) → individual_role_analysis (low)

#### Flow Control Configuration
The **flow_control** field manages task execution through structured sequential steps. For complete format specifications and usage guidelines, see [Flow Control Format Guide](#flow-control-format-guide) below.

**Quick Reference**:
- **pre_analysis**: Context gathering steps (supports multiple command types)
- **implementation_approach**: Implementation steps array with dependency management
- **target_files**: Target files for modification (file:function:lines format)
- **Variable references**: Use `[variable_name]` to reference step outputs
- **Tool integration**: Supports Gemini, Codex, Bash commands, and MCP tools

## Flow Control Format Guide

The `[FLOW_CONTROL]` marker indicates that a task or prompt contains flow control steps for sequential execution. There are **two distinct formats** used in different scenarios:

### Format Comparison Matrix

| Aspect | Inline Format | JSON Format |
|--------|--------------|-------------|
| **Used In** | Brainstorm workflows | Implementation tasks |
| **Agent** | conceptual-planning-agent | code-developer, test-fix-agent, doc-generator |
| **Location** | Task() prompt (markdown) | .task/IMPL-*.json file |
| **Persistence** | Temporary (prompt-only) | Persistent (file storage) |
| **Complexity** | Simple (3-5 steps) | Complex (10+ steps) |
| **Dependencies** | None | Full `depends_on` support |
| **Purpose** | Load brainstorming context | Implement task with preparation |

### Inline Format (Brainstorm)

**Marker**: `[FLOW_CONTROL]` written directly in Task() prompt

**Structure**: Markdown list format

**Used By**: Brainstorm commands (`auto-parallel.md`, role commands)

**Agent**: `conceptual-planning-agent`

**Example**:
```markdown
[FLOW_CONTROL]

### Flow Control Steps
**AGENT RESPONSIBILITY**: Execute these pre_analysis steps sequentially with context accumulation:

1. **load_topic_framework**
   - Action: Load structured topic discussion framework
   - Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
   - Output: topic_framework

2. **load_role_template**
   - Action: Load role-specific planning template
   - Command: bash($(cat "~/.claude/workflows/cli-templates/planning-roles/{role}.md"))
   - Output: role_template

3. **load_session_metadata**
   - Action: Load session metadata and topic description
   - Command: bash(cat .workflow/WFS-{session}/workflow-session.json 2>/dev/null || echo '{}')
   - Output: session_metadata
```

**Characteristics**:
- 3-5 simple context loading steps
- Written directly in prompt (not persistent)
- No dependency management between steps
- Used for temporary context preparation
- Variables: `[variable_name]` for output references

### JSON Format (Implementation)

**Marker**: `[FLOW_CONTROL]` used in TodoWrite or documentation to indicate task has flow control

**Structure**: Complete JSON structure in task file

**Used By**: Implementation tasks (IMPL-*.json)

**Agents**: `code-developer`, `test-fix-agent`, `doc-generator`

**Example**:
```json
"flow_control": {
  "pre_analysis": [
    {
      "step": "load_role_analyses",
      "action": "Load role analysis documents from brainstorming",
      "commands": [
        "bash(ls .workflow/WFS-{session}/.brainstorming/*/analysis*.md 2>/dev/null || echo 'not found')",
        "Glob(.workflow/WFS-{session}/.brainstorming/*/analysis*.md)",
        "Read(each discovered role analysis file)"
      ],
      "output_to": "role_analyses",
      "on_error": "skip_optional"
    },
    {
      "step": "local_codebase_exploration",
      "action": "Explore codebase using local search",
      "commands": [
        "bash(rg '^(function|class|interface).*auth' --type ts -n --max-count 15)",
        "bash(find . -name '*auth*' -type f | grep -v node_modules | head -10)"
      ],
      "output_to": "codebase_structure"
    }
  ],
  "implementation_approach": [
    {
      "step": 1,
      "title": "Setup infrastructure",
      "description": "Install JWT library and create config following [role_analyses]",
      "modification_points": [
        "Add JWT library dependencies to package.json",
        "Create auth configuration file"
      ],
      "logic_flow": [
        "Install jsonwebtoken library via npm",
        "Configure JWT secret from [role_analyses]",
        "Export auth config for use by [jwt_generator]"
      ],
      "depends_on": [],
      "output": "auth_config"
    },
    {
      "step": 2,
      "title": "Implement JWT generation",
      "description": "Create JWT token generation logic using [auth_config]",
      "modification_points": [
        "Add JWT generation function in auth service",
        "Implement token signing with [auth_config]"
      ],
      "logic_flow": [
        "User login → validate credentials",
        "Generate JWT payload with user data",
        "Sign JWT using secret from [auth_config]",
        "Return signed token"
      ],
      "depends_on": [1],
      "output": "jwt_generator"
    }
  ],
  "target_files": [
    "src/auth/login.ts:handleLogin:75-120",
    "src/middleware/auth.ts:validateToken"
  ]
}
```

**Characteristics**:
- Persistent storage in .task/IMPL-*.json files
- Complete dependency management (`depends_on` arrays)
- Two-phase structure: `pre_analysis` + `implementation_approach`
- Error handling strategies (`on_error` field)
- Target file specifications
- Variables: `[variable_name]` for cross-step references

### JSON Format Field Specifications

#### pre_analysis Field
**Purpose**: Context gathering phase before implementation

**Structure**: Array of step objects with sequential execution

**Step Fields**:
- **step**: Step identifier (string, e.g., "load_role_analyses")
- **action**: Human-readable description of the step
- **command** or **commands**: Single command string or array of command strings
- **output_to**: Variable name for storing step output
- **on_error**: Error handling strategy (`skip_optional`, `fail`, `retry_once`, `manual_intervention`)

**Command Types Supported**:
- **Bash commands**: `bash(command)` - Any shell command
- **Tool calls**: `Read(file)`, `Glob(pattern)`, `Grep(pattern)`
- **MCP tools**: `mcp__exa__get_code_context_exa()`, `mcp__exa__web_search_exa()`
- **CLI commands**: `gemini`, `qwen`, `codex --full-auto exec`

**Example**:
```json
{
  "step": "load_context",
  "action": "Load project context and patterns",
  "commands": [
    "bash(ccw tool exec get_modules_by_depth '{}')",
    "Read(CLAUDE.md)"
  ],
  "output_to": "project_structure",
  "on_error": "skip_optional"
}
```

#### implementation_approach Field
**Purpose**: Define implementation steps with dependency management

**Structure**: Array of step objects (NOT object format)

**Step Fields (All Required)**:
- **step**: Unique step number (1, 2, 3, ...) - serves as step identifier
- **title**: Brief step title
- **description**: Comprehensive implementation description with context variable references
- **modification_points**: Array of specific code modification targets
- **logic_flow**: Array describing business logic execution sequence
- **depends_on**: Array of step numbers this step depends on (e.g., `[1]`, `[1, 2]`) - empty array `[]` for independent steps
- **output**: Output variable name that can be referenced by subsequent steps via `[output_name]`

**Optional Fields**:
- **command**: Command for step execution (supports any shell command or CLI tool)
  - When omitted: Agent interprets modification_points and logic_flow to execute
  - When specified: Command executes the step directly

**Execution Modes**:
- **Default (without command)**: Agent executes based on modification_points and logic_flow
- **With command**: Specified command handles execution

**Command Field Usage**:
- **Default approach**: Omit command field - let agent execute autonomously
- **CLI tools (codex/gemini/qwen)**: Add ONLY when user explicitly requests CLI tool usage
- **Simple commands**: Can include bash commands, test commands, validation scripts
- **Complex workflows**: Use command for multi-step operations or tool coordination

**Command Format Examples** (only when explicitly needed):
```json
// Simple Bash
"command": "bash(npm install package)"
"command": "bash(npm test)"

// Validation
"command": "bash(test -f config.ts && grep -q 'JWT_SECRET' config.ts)"

// Codex (user requested)
"command": "codex -C path --full-auto exec \"task\" --skip-git-repo-check -s danger-full-access"

// Codex Resume (user requested, maintains context)
"command": "codex --full-auto exec \"task\" resume --last --skip-git-repo-check -s danger-full-access"

// Gemini (user requested)
"command": "gemini \"analyze [context]\""

// Qwen (fallback for Gemini)
"command": "qwen \"analyze [context]\""
```

**Example Step**:
```json
{
  "step": 2,
  "title": "Implement JWT generation",
  "description": "Create JWT token generation logic using [auth_config]",
  "modification_points": [
    "Add JWT generation function in auth service",
    "Implement token signing with [auth_config]"
  ],
  "logic_flow": [
    "User login → validate credentials",
    "Generate JWT payload with user data",
    "Sign JWT using secret from [auth_config]",
    "Return signed token"
  ],
  "depends_on": [1],
  "output": "jwt_generator"
}
```

#### target_files Field
**Purpose**: Specify files to be modified or created

**Format**: Array of strings
- **Existing files**: `"file:function:lines"` (e.g., `"src/auth/login.ts:handleLogin:75-120"`)
- **New files**: `"path/to/NewFile.ts"` (file path only)

### Tool Reference

**Available Command Types**:

**Gemini CLI**:
```bash
gemini "prompt"
gemini --approval-mode yolo "prompt"  # For write mode
```

**Qwen CLI** (Gemini fallback):
```bash
qwen "prompt"
qwen --approval-mode yolo "prompt"  # For write mode
```

**Codex CLI**:
```bash
codex -C directory --full-auto exec "task" --skip-git-repo-check -s danger-full-access
codex --full-auto exec "task" resume --last --skip-git-repo-check -s danger-full-access
```

**Built-in Tools**:
- `Read(file_path)` - Read file contents
- `Glob(pattern)` - Find files by pattern
- `Grep(pattern)` - Search content with regex
- `bash(command)` - Execute bash command

**MCP Tools**:
- `mcp__exa__get_code_context_exa(query="...")` - Get code context from Exa
- `mcp__exa__web_search_exa(query="...")` - Web search via Exa

**Bash Commands**:
```bash
bash(rg 'pattern' src/)
bash(find . -name "*.ts")
bash(npm test)
bash(git log --oneline | head -5)
```

### Variable System & Context Flow

**Variable Reference Syntax**:
Both formats use `[variable_name]` syntax for referencing outputs from previous steps.

**Variable Types**:
- **Step outputs**: `[step_output_name]` - Reference any pre_analysis step output
- **Task properties**: `[task_property]` - Reference any task context field
- **Previous results**: `[analysis_result]` - Reference accumulated context
- **Implementation outputs**: Reference outputs from previous implementation steps

**Examples**:
```json
// Reference pre_analysis output
"description": "Install JWT library following [role_analyses]"

// Reference previous step output
"description": "Create middleware using [auth_config] and [jwt_generator]"

// Reference task context
"command": "bash(cd [focus_paths] && npm test)"
```

**Context Accumulation Process**:
1. **Structure Analysis**: `get_modules_by_depth.sh` → project hierarchy
2. **Pattern Analysis**: Tool-specific commands → existing patterns
3. **Dependency Mapping**: Previous task summaries → inheritance context
4. **Task Context Generation**: Combined analysis → task.context fields

**Context Inheritance Rules**:
- **Parent → Child**: Container tasks pass context via `context.inherited`
- **Dependency → Dependent**: Previous task summaries via `context.depends_on`
- **Session → Task**: Global session context included in all tasks
- **Module → Feature**: Module patterns inform feature implementation

### Agent Processing Rules

**conceptual-planning-agent** (Inline Format):
- Parses markdown list from prompt
- Executes 3-5 simple loading steps
- No dependency resolution needed
- Accumulates context in variables
- Used only in brainstorm workflows

**code-developer, test-fix-agent** (JSON Format):
- Loads complete task JSON from file
- Executes `pre_analysis` steps sequentially
- Processes `implementation_approach` with dependency resolution
- Handles complex variable substitution
- Updates task status in JSON file

### Usage Guidelines

**Use Inline Format When**:
- Running brainstorm workflows
- Need 3-5 simple context loading steps
- No persistence required
- No dependencies between steps
- Temporary context preparation

**Use JSON Format When**:
- Implementing features or tasks
- Need 10+ complex execution steps
- Require dependency management
- Need persistent task definitions
- Complex variable flow between steps
- Error handling strategies needed

### Variable Reference Syntax

Both formats use `[variable_name]` syntax for referencing outputs:

**Inline Format**:
```markdown
2. **analyze_context**
   - Action: Analyze using [topic_framework] and [role_template]
   - Output: analysis_results
```

**JSON Format**:
```json
{
  "step": 2,
  "description": "Implement following [role_analyses] and [codebase_structure]",
  "depends_on": [1],
  "output": "implementation"
}
```

### Task Validation 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. **Status Consistency**: Status values from defined enumeration
5. **Required Fields**: All 5 core fields must be present (id, title, status, meta, context, flow_control)
6. **Focus Paths Structure**: context.focus_paths must contain concrete paths (no wildcards)
7. **Flow Control Format**: pre_analysis must be array with required fields
8. **Dependency Integrity**: All task-level depends_on references must exist as JSON files
9. **Artifacts Structure**: context.artifacts (optional) must use valid type, priority, and path format
10. **Implementation Steps Array**: implementation_approach must be array of step objects
11. **Step Number Uniqueness**: All step numbers within a task must be unique and sequential (1, 2, 3, ...)
12. **Step Dependencies**: All step-level depends_on numbers must reference valid steps within same task
13. **Step Sequence**: Step numbers should match array order (first item step=1, second item step=2, etc.)
14. **Step Required Fields**: Each step must have step, title, description, modification_points, logic_flow, depends_on, output
15. **Step Optional Fields**: command field is optional - when omitted, agent executes based on modification_points and logic_flow

## Workflow 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/
├── [.scratchpad/]              # Non-session-specific outputs (created when needed)
│   ├── analyze-*-[timestamp].md        # One-off analysis results
│   ├── chat-*-[timestamp].md           # Standalone chat sessions
│   ├── plan-*-[timestamp].md           # Ad-hoc planning notes
│   ├── bug-index-*-[timestamp].md      # Quick bug analyses
│   ├── code-analysis-*-[timestamp].md  # Standalone code analysis
│   ├── execute-*-[timestamp].md        # Ad-hoc implementation logs
│   └── codex-execute-*-[timestamp].md  # Multi-stage execution logs
│
├── [design-run-*/]             # Standalone UI design outputs (created when needed)
│   └── (timestamped)/          # Timestamped design runs without session
│       ├── .intermediates/     # Intermediate analysis files
│       │   ├── style-analysis/ # Style analysis data
│       │   │   ├── computed-styles.json        # Extracted CSS values
│       │   │   └── design-space-analysis.json  # Design directions
│       │   └── layout-analysis/ # Layout analysis data
│       │       ├── dom-structure-{target}.json # DOM extraction
│       │       └── inspirations/               # Layout research
│       │           └── {target}-layout-ideas.txt
│       ├── style-extraction/   # Final design systems
│       │   ├── style-1/        # design-tokens.json, style-guide.md
│       │   └── style-N/
│       ├── layout-extraction/  # Layout templates
│       │   └── layout-templates.json
│       ├── prototypes/         # Generated HTML/CSS prototypes
│       │   ├── {target}-style-{s}-layout-{l}.html  # Final prototypes
│       │   ├── compare.html    # Interactive matrix view
│       │   └── index.html      # Navigation page
│       └── .run-metadata.json  # Run configuration
│
├── active/                          # Active workflow sessions
│   └── 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
│       ├── [.process/]                 # Planning analysis results (created by /workflow:plan)
│       │   └── ANALYSIS_RESULTS.md    # Analysis results and planning artifacts
│       ├── IMPL_PLAN.md                # Planning document (REQUIRED)
│       ├── TODO_LIST.md                # Progress tracking (REQUIRED)
│       ├── [.summaries/]               # Task completion summaries (created when tasks complete)
│       │   ├── IMPL-*-summary.md      # Main task summaries
│       │   └── IMPL-*.*-summary.md    # Subtask summaries
│       ├── [.review/]                  # Code review results (created by review commands)
│       │   ├── review-metadata.json    # Review configuration and scope
│       │   ├── review-state.json       # Review state machine
│       │   ├── review-progress.json    # Real-time progress tracking
│       │   ├── dimensions/             # Per-dimension analysis results
│       │   ├── iterations/             # Deep-dive iteration results
│       │   ├── reports/                # Human-readable reports and CLI outputs
│       │   ├── REVIEW-SUMMARY.md       # Final consolidated summary
│       │   └── dashboard.html          # Interactive review dashboard
│       ├── [design-*/]                 # UI design outputs (created by ui-design workflows)
│       │   ├── .intermediates/         # Intermediate analysis files
│       │   │   ├── style-analysis/     # Style analysis data
│       │   │   │   ├── computed-styles.json        # Extracted CSS values
│       │   │   │   └── design-space-analysis.json  # Design directions
│       │   │   └── layout-analysis/    # Layout analysis data
│       │   │       ├── dom-structure-{target}.json # DOM extraction
│       │   │       └── inspirations/               # Layout research
│       │   │           └── {target}-layout-ideas.txt
│       │   ├── style-extraction/       # Final design systems
│       │   │   ├── style-1/            # design-tokens.json, style-guide.md
│       │   │   └── style-N/
│       │   ├── layout-extraction/      # Layout templates
│       │   │   └── layout-templates.json
│       │   ├── prototypes/             # Generated HTML/CSS prototypes
│       │   │   ├── {target}-style-{s}-layout-{l}.html  # Final prototypes
│       │   │   ├── compare.html        # Interactive matrix view
│       │   │   └── index.html          # Navigation page
│       │   └── .run-metadata.json      # Run configuration
│       └── .task/                      # Task definitions (REQUIRED)
│           ├── IMPL-*.json             # Main task definitions
│           └── IMPL-*.*.json           # Subtask definitions (created dynamically)
└── archives/                       # Completed workflow sessions
    └── WFS-[completed-topic]/      # Archived session directories
```

#### 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
- **Dynamic Files**: Subtask JSON files created during task decomposition
- **Scratchpad Usage**: `.scratchpad/` created when CLI commands run without active session
- **Design Usage**: `design-{timestamp}/` created by UI design workflows in `.workflow/` directly for standalone design runs
- **Review Usage**: `.review/` created by review commands (`/workflow:review-module-cycle`, `/workflow:review-session-cycle`) for comprehensive code quality analysis
- **Intermediate Files**: `.intermediates/` contains analysis data (style/layout) separate from final deliverables
- **Layout Templates**: `layout-extraction/layout-templates.json` contains structural templates for UI assembly

#### Scratchpad Directory (.scratchpad/)
**Purpose**: Centralized location for non-session-specific CLI outputs

**When to Use**:
1. **No Active Session**: CLI analysis/chat commands run without an active workflow session
2. **Unrelated Analysis**: Quick analysis not related to current active session
3. **Exploratory Work**: Ad-hoc investigation before creating formal workflow
4. **One-Off Queries**: Standalone questions or debugging without workflow context

**Output Routing Logic**:
- **IF** active session exists in `.workflow/active/` AND command is session-relevant:
  - Save to `.workflow/active/WFS-[id]/.chat/[command]-[timestamp].md`
- **ELSE** (no session OR one-off analysis):
  - Save to `.workflow/.scratchpad/[command]-[description]-[timestamp].md`

**File Naming Pattern**: `[command-type]-[brief-description]-[timestamp].md`

**Examples**:

*Workflow Commands (lightweight):*
- `/workflow:lite-plan "feature idea"` (exploratory) → `.scratchpad/lite-plan-feature-idea-20250105-143110.md`
- `/workflow:lite-fix "bug description"` (bug fixing) → `.scratchpad/lite-fix-bug-20250105-143130.md`

> **Note**: Direct CLI commands (`/cli:analyze`, `/cli:execute`, etc.) have been replaced by semantic invocation and workflow commands.

**Maintenance**:
- Periodically review and clean up old scratchpad files
- Promote useful analyses to formal workflow sessions if needed
- No automatic cleanup - manual management recommended

### File Naming Conventions

#### Session Identifiers
**Format**: `WFS-[topic-slug]`

**WFS Prefix Meaning**:
- `WFS` = **W**ork**F**low **S**ession
- Identifies directories as workflow session containers
- Distinguishes workflow sessions from other project directories

**Naming Rules**:
- 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`)
- Maximum length: 50 characters including WFS- prefix

#### 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`

### Document Templates

#### TODO_LIST.md Template
```markdown
# 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-summary.md)

- [x] **IMPL-002**: [Simple Task] → [📋](./.task/IMPL-002.json) | [✅](./.summaries/IMPL-002-summary.md)

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

## Operations Guide

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

### Task Operations
```bash
# Create task
echo '{"id":"IMPL-1","title":"New task",...}' > .task/IMPL-1.json

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

# Generate TODO list from JSON state
generate_todo_list_from_json .task/
```

### Directory Creation (On-Demand)
```bash
mkdir -p .brainstorming     # When brainstorming is initiated
mkdir -p .chat              # When analysis commands are run
mkdir -p .summaries         # When first task completes
```

### Session Consistency Checks & Recovery
```bash
# Validate session directory structure
if [ -d ".workflow/active/" ]; then
  for session_dir in .workflow/active/WFS-*; do
    if [ ! -f "$session_dir/workflow-session.json" ]; then
      echo "⚠️ Missing workflow-session.json in $session_dir"
    fi
  done
fi
```

**Recovery Strategies**:
- **Missing Session File**: Recreate workflow-session.json from template
- **Corrupted Session File**: Restore from template with basic metadata
- **Broken Task Hierarchy**: Reconstruct parent-child relationships from task JSON files
- **Orphaned Sessions**: Move incomplete sessions to archives/

## 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 |

### Workflow Characteristics & Tool Guidance

#### Simple Workflows
- **Examples**: Bug fixes, small feature additions, configuration changes
- **Task Decomposition**: Usually single-level tasks, minimal breakdown needed
- **Agent Coordination**: Direct execution without complex orchestration
- **Tool Strategy**: `bash()` commands, `grep()` for pattern matching

#### Medium Workflows
- **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
- **Tool Strategy**: `gemini` for pattern analysis, `codex --full-auto` for implementation

#### Complex Workflows
- **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
- **Tool Strategy**: `gemini` for architecture analysis, `codex --full-auto` for complex problem solving, `bash()` commands for flexible analysis

### 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

## Agent Integration

### Agent Assignment
Based on task type and title keywords:
- **Planning tasks** → @action-planning-agent
- **Implementation** → @code-developer (code + tests)
- **Test execution/fixing** → @test-fix-agent
- **Review** → @universal-executor (optional, only when explicitly requested)

### Execution Context
Agents receive complete task JSON plus workflow context:
```json
{
  "task": { /* complete task JSON */ },
  "workflow": {
    "session": "WFS-user-auth",
    "phase": "IMPLEMENT"
  }
}
```