Claude-Code-Workflow/.claude/skills/team-lifecycle-v3/specs/domain-model.md

Domain Model

This document defines the core entities, schemas, relationships, and state machines for Team Lifecycle v3.

1. Core Entities

1.1 Task

A Task represents a unit of work assigned to a specific role. Tasks have dependencies, priorities, and lifecycle states.

Definition: An atomic work item with a unique identifier, assigned role, execution phase, dependency constraints, and status tracking.

Fields:

• id (string): Unique task identifier following pattern {PREFIX}-{NNN} (e.g., IMPL-001, TEST-001)
• role (string): Role name responsible for execution (e.g., executor, tester, reviewer)
• phase (string): Execution phase (spec, impl, test, review)
• dependencies (array): List of task IDs that must complete before this task can start (blockedBy)
• status (enum): Current task state (pending, ready, in_progress, completed, failed)
• priority (enum): Execution priority (P0, P1, P2)
• metadata (object): Additional context (created_at, updated_at, attempt_count, error_message)

1.2 Artifact

An Artifact represents a deliverable produced by a worker, with validation status and dependency tracking.

Definition: A versioned output (document, code, test suite) with a manifest describing its type, creator, validation status, and dependencies.

Fields:

• artifact_id (string): Unique artifact identifier (e.g., product-brief-v1, impl-auth-service)
• artifact_type (string): Type classification (document, code, test, config, report)
• path (string): File system path relative to session directory
• creator_role (string): Role that produced this artifact
• version (string): Semantic version (e.g., 1.0, 1.1)
• validation_status (enum): Validation state (pending, passed, failed)
• validation_summary (string): Human-readable validation result
• dependencies (array): List of artifact IDs this artifact depends on
• metadata (object): Additional context (created_at, task_id, priority, file_size, checksum)

1.3 Role

A Role defines a specialized agent's capabilities, task prefix, and injection trigger.

Definition: A specification for an agent type, including its responsibilities, task naming convention, and conditions for activation.

Fields:

• name (string): Role identifier (e.g., executor, security-expert, orchestrator)
• type (enum): Role classification (coordinator, pipeline, specialist, utility)
• task_prefix (string): Task ID prefix pattern (e.g., IMPL-*, SECURITY-*, ORCH-*)
• injection_trigger (enum): Activation condition (always, complexity, keywords, manual)
• injection_criteria (object): Specific trigger conditions (keywords, complexity_threshold)
• capabilities (array): List of capabilities (e.g., code_generation, security_audit, performance_analysis)
• inner_loop (boolean): Whether role supports iterative refinement
• phase_execution (array): List of execution phases (1-5)

1.4 Session

A Session represents a complete workflow execution instance with persistent state.

Definition: A stateful execution context that tracks all tasks, artifacts, and coordination state for a single workflow run.

Fields:

• session_id (string): Unique session identifier (e.g., TLS-auth-impl-20260305)
• slug (string): Human-readable short name derived from task description
• created_at (string): ISO8601 timestamp of session creation
• updated_at (string): ISO8601 timestamp of last state change
• status (enum): Session lifecycle state (created, active, paused, completed, archived, failed)
• pipeline_type (enum): Selected pipeline (spec-only, impl-only, full-lifecycle, enhanced-parallel)
• artifact_registry (object): Map of artifact_id → Artifact manifest
• task_list (array): Ordered list of Task objects
• injected_roles (array): List of dynamically injected specialist roles
• checkpoint_history (array): Record of user checkpoint interactions
• session_directory (string): File system path to session workspace

---

2. Entity Schemas

2.1 Task Schema (JSON Schema)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "title": "Task",
  "required": ["id", "role", "phase", "status", "priority"],
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^[A-Z]+-[0-9]{3}$",
      "description": "Unique task identifier (e.g., IMPL-001)"
    },
    "role": {
      "type": "string",
      "description": "Role name responsible for execution"
    },
    "phase": {
      "type": "string",
      "enum": ["spec", "impl", "test", "review"],
      "description": "Execution phase"
    },
    "dependencies": {
      "type": "array",
      "items": {"type": "string", "pattern": "^[A-Z]+-[0-9]{3}$"},
      "default": [],
      "description": "List of task IDs that must complete first"
    },
    "status": {
      "type": "string",
      "enum": ["pending", "ready", "in_progress", "completed", "failed"],
      "description": "Current task state"
    },
    "priority": {
      "type": "string",
      "enum": ["P0", "P1", "P2"],
      "description": "Execution priority (P0 = highest)"
    },
    "metadata": {
      "type": "object",
      "properties": {
        "created_at": {"type": "string", "format": "date-time"},
        "updated_at": {"type": "string", "format": "date-time"},
        "attempt_count": {"type": "integer", "minimum": 0},
        "error_message": {"type": "string"}
      }
    }
  }
}

2.2 Artifact Schema (JSON Schema)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "title": "Artifact",
  "required": ["artifact_id", "artifact_type", "path", "creator_role", "validation_status"],
  "properties": {
    "artifact_id": {
      "type": "string",
      "description": "Unique artifact identifier"
    },
    "artifact_type": {
      "type": "string",
      "enum": ["document", "code", "test", "config", "report"],
      "description": "Type classification"
    },
    "path": {
      "type": "string",
      "description": "File system path relative to session directory"
    },
    "creator_role": {
      "type": "string",
      "description": "Role that produced this artifact"
    },
    "version": {
      "type": "string",
      "pattern": "^[0-9]+\\.[0-9]+$",
      "description": "Semantic version (e.g., 1.0)"
    },
    "validation_status": {
      "type": "string",
      "enum": ["pending", "passed", "failed"],
      "description": "Validation state"
    },
    "validation_summary": {
      "type": "string",
      "description": "Human-readable validation result"
    },
    "dependencies": {
      "type": "array",
      "items": {"type": "string"},
      "default": [],
      "description": "List of artifact IDs this depends on"
    },
    "metadata": {
      "type": "object",
      "properties": {
        "created_at": {"type": "string", "format": "date-time"},
        "task_id": {"type": "string", "pattern": "^[A-Z]+-[0-9]{3}$"},
        "priority": {"type": "string", "enum": ["P0", "P1", "P2"]},
        "file_size": {"type": "integer", "minimum": 0},
        "checksum": {"type": "string"}
      }
    }
  }
}

2.3 Role Schema (JSON Schema)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "title": "Role",
  "required": ["name", "type", "task_prefix", "injection_trigger"],
  "properties": {
    "name": {
      "type": "string",
      "description": "Role identifier"
    },
    "type": {
      "type": "string",
      "enum": ["coordinator", "pipeline", "specialist", "utility"],
      "description": "Role classification"
    },
    "task_prefix": {
      "type": "string",
      "pattern": "^[A-Z]+-\\*$",
      "description": "Task ID prefix pattern (e.g., IMPL-*)"
    },
    "injection_trigger": {
      "type": "string",
      "enum": ["always", "complexity", "keywords", "manual"],
      "description": "Activation condition"
    },
    "injection_criteria": {
      "type": "object",
      "properties": {
        "keywords": {"type": "array", "items": {"type": "string"}},
        "complexity_threshold": {"type": "string", "enum": ["low", "medium", "high"]}
      }
    },
    "capabilities": {
      "type": "array",
      "items": {"type": "string"},
      "description": "List of capabilities"
    },
    "inner_loop": {
      "type": "boolean",
      "description": "Supports iterative refinement"
    },
    "phase_execution": {
      "type": "array",
      "items": {"type": "integer", "minimum": 1, "maximum": 5},
      "description": "Execution phases (1-5)"
    }
  }
}

2.4 Session Schema (JSON Schema)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "title": "Session",
  "required": ["session_id", "slug", "status", "pipeline_type"],
  "properties": {
    "session_id": {
      "type": "string",
      "pattern": "^TLS-[a-z0-9-]+-[0-9]{8}$",
      "description": "Unique session identifier"
    },
    "slug": {
      "type": "string",
      "description": "Human-readable short name"
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "Session creation timestamp"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "Last state change timestamp"
    },
    "status": {
      "type": "string",
      "enum": ["created", "active", "paused", "completed", "archived", "failed"],
      "description": "Session lifecycle state"
    },
    "pipeline_type": {
      "type": "string",
      "enum": ["spec-only", "impl-only", "full-lifecycle", "enhanced-parallel"],
      "description": "Selected pipeline"
    },
    "artifact_registry": {
      "type": "object",
      "additionalProperties": {"$ref": "#/definitions/Artifact"},
      "description": "Map of artifact_id to Artifact manifest"
    },
    "task_list": {
      "type": "array",
      "items": {"$ref": "#/definitions/Task"},
      "description": "Ordered list of tasks"
    },
    "injected_roles": {
      "type": "array",
      "items": {"type": "string"},
      "description": "Dynamically injected specialist roles"
    },
    "checkpoint_history": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "checkpoint_id": {"type": "string"},
          "timestamp": {"type": "string", "format": "date-time"},
          "user_action": {"type": "string", "enum": ["resume", "improve", "revise", "recheck", "feedback"]},
          "context": {"type": "string"}
        }
      }
    },
    "session_directory": {
      "type": "string",
      "description": "File system path to session workspace"
    }
  }
}

---

3. Entity Relationships

┌─────────────────────────────────────────────────────────────────┐
│                          Session                                 │
│  - session_id                                                    │
│  - status: created|active|paused|completed|archived|failed       │
│  - pipeline_type: spec-only|impl-only|full-lifecycle|enhanced    │
├─────────────────────────────────────────────────────────────────┤
│  artifact_registry: Map<artifact_id, Artifact>                   │
│  task_list: Task[]                                               │
│  injected_roles: string[]                                        │
│  checkpoint_history: Checkpoint[]                                │
└──────────────┬──────────────────────────────┬───────────────────┘
               │                              │
               │ 1:N                          │ 1:N
               ▼                              ▼
       ┌───────────────┐              ┌──────────────┐
       │   Artifact    │              │     Task     │
       ├───────────────┤              ├──────────────┤
       │ artifact_id   │              │ id           │
       │ artifact_type │              │ role ────────┼──┐
       │ path          │              │ phase        │  │
       │ creator_role ─┼──┐           │ dependencies │  │ N:1
       │ validation_   │  │           │ status       │  │
       │   status      │  │           │ priority     │  │
       │ dependencies ─┼──┼───┐       └──────┬───────┘  │
       └───────────────┘  │   │              │          │
                          │   │              │ produces │
                          │   │              │ 1:1      │
                          │   │              ▼          │
                          │   │       ┌──────────────┐  │
                          │   └──────▶│   Artifact   │  │
                          │           └──────────────┘  │
                          │                             │
                          │ N:1                         │
                          ▼                             ▼
                   ┌──────────────┐            ┌──────────────┐
                   │     Role     │            │     Role     │
                   ├──────────────┤            ├──────────────┤
                   │ name         │            │ name         │
                   │ type         │            │ type         │
                   │ task_prefix  │            │ task_prefix  │
                   │ injection_   │            │ injection_   │
                   │   trigger    │            │   trigger    │
                   │ capabilities │            │ capabilities │
                   └──────────────┘            └──────────────┘

Relationship Descriptions:

1. Session → Task (1:N): A session contains multiple tasks in its task_list
2. Session → Artifact (1:N): A session tracks multiple artifacts in its artifact_registry
3. Task → Role (N:1): Each task is assigned to one role for execution
4. Task → Artifact (1:1): Each task produces one primary artifact upon completion
5. Task → Task (N:N): Tasks can depend on other tasks (dependencies field)
6. Artifact → Role (N:1): Each artifact is created by one role (creator_role)
7. Artifact → Artifact (N:N): Artifacts can depend on other artifacts (dependencies field)

---

4. State Machines

4.1 Task Status State Machine

                    ┌─────────────┐
                    │   pending   │ (initial state)
                    └──────┬──────┘
                           │
                           │ dependencies met
                           ▼
                    ┌─────────────┐
                    │    ready    │
                    └──────┬──────┘
                           │
                           │ worker spawned
                           ▼
                    ┌─────────────┐
                    │ in_progress │
                    └──────┬──────┘
                           │
                ┌──────────┴──────────┐
                │                     │
                │ success             │ failure
                ▼                     ▼
         ┌─────────────┐       ┌─────────────┐
         │  completed  │       │   failed    │
         └─────────────┘       └──────┬──────┘
                                      │
                                      │ retry (attempt_count++)
                                      ▼
                               ┌─────────────┐
                               │   pending   │
                               └─────────────┘

State Transitions:

• pending → ready: All dependencies completed
• ready → in_progress: Worker spawned by coordinator
• in_progress → completed: Worker reports success via SendMessage
• in_progress → failed: Worker reports failure or timeout
• failed → pending: Coordinator triggers retry (with exponential backoff)

Terminal States: completed

Retry Logic: Failed tasks return to pending with incremented attempt_count. Max retries configurable (default: 3).

4.2 Session Lifecycle State Machine

                    ┌─────────────┐
                    │   created   │ (initial state)
                    └──────┬──────┘
                           │
                           │ first task spawned
                           ▼
                    ┌─────────────┐
                    │    active   │◀──────────┐
                    └──────┬──────┘           │
                           │                  │
                ┌──────────┴──────────┐       │
                │                     │       │
                │ user pause          │ resume│
                ▼                     │       │
         ┌─────────────┐              │       │
         │   paused    │──────────────┘       │
         └─────────────┘                      │
                                              │
                    ┌─────────────┐           │
                    │    active   │───────────┘
                    └──────┬──────┘
                           │
                ┌──────────┴──────────┐
                │                     │
                │ all tasks done      │ unrecoverable error
                ▼                     ▼
         ┌─────────────┐       ┌─────────────┐
         │  completed  │       │   failed    │
         └──────┬──────┘       └──────┬──────┘
                │                     │
                │ archive             │ archive
                ▼                     ▼
         ┌─────────────┐       ┌─────────────┐
         │  archived   │       │  archived   │
         └─────────────┘       └─────────────┘

State Transitions:

• created → active: Coordinator spawns first batch of tasks
• active → paused: User issues pause command or checkpoint requires review
• paused → active: User issues resume command
• active → completed: All tasks in task_list reach completed status
• active → failed: Unrecoverable error (e.g., circular dependency, resource exhaustion)
• completed → archived: Session archived after retention period
• failed → archived: Failed session archived after investigation

Terminal States: archived

Checkpoint Behavior: Session transitions to paused at quality checkpoints (e.g., after QUALITY-001). User actions (resume, improve, revise) transition back to active.

4.3 Artifact Validation State Machine

                    ┌─────────────┐
                    │   pending   │ (initial state)
                    └──────┬──────┘
                           │
                           │ validation triggered
                           ▼
                    ┌─────────────┐
                    │  validating │
                    └──────┬──────┘
                           │
                ┌──────────┴──────────┐
                │                     │
                │ validation success  │ validation failure
                ▼                     ▼
         ┌─────────────┐       ┌─────────────┐
         │   passed    │       │   failed    │
         └─────────────┘       └──────┬──────┘
                                      │
                                      │ fix applied
                                      ▼
                               ┌─────────────┐
                               │   pending   │
                               └─────────────┘

State Transitions:

• pending → validating: Coordinator triggers validation (e.g., quality gate check)
• validating → passed: Artifact meets quality criteria
• validating → failed: Artifact fails quality criteria
• failed → pending: Worker applies fix and re-submits artifact

Terminal States: passed

Validation Gating: Downstream tasks blocked until upstream artifacts reach passed state.

---

5. Invariants and Constraints

5.1 Task Invariants

1. Unique Task IDs: No two tasks in a session can have the same id
2. Acyclic Dependencies: Task dependency graph must be a DAG (no cycles)
3. Valid Dependencies: All task IDs in dependencies array must exist in session's task_list
4. Priority Ordering: P0 tasks execute before P1, P1 before P2 (within same dependency level)
5. Single Active Worker: A task can only be in_progress for one worker at a time

5.2 Artifact Invariants

1. Unique Artifact IDs: No two artifacts in a session can have the same artifact_id
2. Valid Creator Role: creator_role must match a defined role in the system
3. Path Uniqueness: No two artifacts can have the same path within a session
4. Dependency Validity: All artifact IDs in dependencies array must exist in artifact_registry

5.3 Session Invariants

1. Unique Session IDs: No two sessions can have the same session_id
2. Monotonic Timestamps: updated_at >= created_at
3. Task Completeness: All tasks in task_list must reach terminal state before session can be completed
4. Artifact Registry Consistency: All artifacts referenced in task metadata must exist in artifact_registry

---

6. Usage Examples

6.1 Creating a Task

{
  "id": "IMPL-001",
  "role": "executor",
  "phase": "impl",
  "dependencies": ["PLAN-001"],
  "status": "pending",
  "priority": "P0",
  "metadata": {
    "created_at": "2026-03-05T10:00:00Z",
    "updated_at": "2026-03-05T10:00:00Z",
    "attempt_count": 0
  }
}

6.2 Creating an Artifact Manifest

{
  "artifact_id": "auth-service-impl-v1",
  "artifact_type": "code",
  "path": "artifacts/auth-service.ts",
  "creator_role": "executor",
  "version": "1.0",
  "validation_status": "passed",
  "validation_summary": "Code review passed: 95% test coverage, no security issues",
  "dependencies": ["auth-service-plan-v1"],
  "metadata": {
    "created_at": "2026-03-05T11:30:00Z",
    "task_id": "IMPL-001",
    "priority": "P0",
    "file_size": 15420,
    "checksum": "sha256:abc123..."
  }
}

6.3 Session State Example

{
  "session_id": "TLS-auth-impl-20260305",
  "slug": "auth-impl",
  "created_at": "2026-03-05T09:00:00Z",
  "updated_at": "2026-03-05T12:00:00Z",
  "status": "active",
  "pipeline_type": "impl-only",
  "artifact_registry": {
    "auth-service-plan-v1": { ... },
    "auth-service-impl-v1": { ... }
  },
  "task_list": [
    {"id": "PLAN-001", "status": "completed", ...},
    {"id": "IMPL-001", "status": "in_progress", ...},
    {"id": "TEST-001", "status": "pending", ...}
  ],
  "injected_roles": ["security-expert"],
  "checkpoint_history": [],
  "session_directory": ".workflow/.team/TLS-auth-impl-20260305/"
}

---

7. Cross-References

• Artifact Contract Specification: artifact-contract-spec.md
• Execution Flow: execution-flow.md
• Core Concepts: core-concepts.md
• Role Specifications: ../roles/README.md