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

.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)

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

mv .workflow/active/WFS-feature .workflow/archives/WFS-feature

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

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:

{
  "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:

"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 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:

[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:

"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:

{
  "step": "load_context",
  "action": "Load project context and patterns",
  "commands": [
    "bash(~/.claude/scripts/get_modules_by_depth.sh)",
    "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):

// 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:

{
  "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:

gemini "prompt"
gemini --approval-mode yolo "prompt"  # For write mode

Qwen CLI (Gemini fallback):

qwen "prompt"
qwen --approval-mode yolo "prompt"  # For write mode

Codex CLI:

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(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:

// 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:

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

JSON Format:

{
  "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
│       ├── [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
• 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:

Analysis Commands (read-only):

• /cli:analyze "security" (no session) → .scratchpad/analyze-security-20250105-143022.md
• /cli:chat "build process" (unrelated to active session) → .scratchpad/chat-build-process-20250105-143045.md
• /cli:mode:plan "feature idea" (exploratory) → .scratchpad/plan-feature-idea-20250105-143110.md
• /cli:mode:code-analysis "trace auth flow" (no session) → .scratchpad/code-analysis-auth-flow-20250105-143130.md

Implementation Commands (⚠️ modifies code):

• /cli:execute "implement JWT auth" (no session) → .scratchpad/execute-jwt-auth-20250105-143200.md
• /cli:codex-execute "refactor API layer" (no session) → .scratchpad/codex-execute-api-refactor-20250105-143230.md

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 = WorkFlow Session
• 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

# 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

# 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

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

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

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

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