Claude-Code-Workflow/.claude/workflows/data-model.md

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:

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

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

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

# Create new task JSON file
echo '{"id":"impl-1","title":"New task",...}' > .task/impl-1.json

Task Updates

# Update task status directly in JSON
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 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