Claude-Code-Workflow/.codex/skills/team-lifecycle-v4/schemas/tasks-schema.md

Tasks Schema (JSON)

1. Overview

Codex uses tasks.json as the single source of truth for task state management, replacing Claude Code's TaskCreate/TaskUpdate API calls and CSV-based state tracking. Each session has one tasks.json file and multiple discoveries/{task_id}.json files.

2. tasks.json Top-Level Structure

{
  "session_id": "string — unique session identifier (e.g., tlv4-auth-system-20260324)",
  "pipeline": "string — one of: spec-only | impl-only | full-lifecycle | fe-only | fullstack | full-lifecycle-fe",
  "requirement": "string — original user requirement text",
  "created_at": "string — ISO 8601 timestamp with timezone",
  "supervision": "boolean — whether CHECKPOINT tasks are active (default: true)",
  "completed_waves": "number[] — list of completed wave numbers",
  "active_agents": "object — map of task_id -> agent_id for currently running agents",
  "tasks": "object — map of task_id -> TaskEntry"
}

Required Fields

Field	Type	Description
session_id	string	Unique session identifier, format: tlv4-<topic>-<YYYYMMDD>
pipeline	string	Selected pipeline name from pipelines.md
requirement	string	Original user requirement, verbatim
created_at	string	ISO 8601 creation timestamp
supervision	boolean	Enable/disable CHECKPOINT tasks
completed_waves	number[]	Waves that have finished execution
active_agents	object	Runtime tracking: { "TASK-ID": "agent-id" }
tasks	object	Task registry: { "TASK-ID": TaskEntry }

3. TaskEntry Schema

{
  "title": "string — short task title",
  "description": "string — detailed task description",
  "role": "string — role name matching roles/<role>/role.md",
  "pipeline_phase": "string — phase from pipelines.md Task Metadata Registry",
  "deps": "string[] — task IDs that must complete before this task starts",
  "context_from": "string[] — task IDs whose discoveries to load as upstream context",
  "wave": "number — execution wave (1-based, determines parallel grouping)",
  "status": "string — one of: pending | in_progress | completed | failed | skipped",
  "findings": "string | null — summary of task output (max 500 chars)",
  "quality_score": "number | null — 0-100, set by reviewer roles only",
  "supervision_verdict": "string | null — pass | warn | block, set by CHECKPOINT tasks only",
  "error": "string | null — error description if status is failed or skipped"
}

Field Definitions

Field	Type	Required	Default	Description
title	string	Yes	-	Human-readable task name
description	string	Yes	-	What the task should accomplish
role	string	Yes	-	One of: analyst, writer, planner, implementer, tester, reviewer, supervisor, orchestrator, architect, security-expert, performance-optimizer, data-engineer, devops-engineer, ml-engineer
pipeline_phase	string	Yes	-	One of: research, product-brief, requirements, architecture, epics, readiness, checkpoint, planning, arch-detail, orchestration, implementation, validation, review
deps	string[]	Yes	[]	Task IDs that block execution. All must be completed before this task starts
context_from	string[]	Yes	[]	Task IDs whose discoveries/{id}.json files are loaded as upstream context
wave	number	Yes	-	Execution wave number. Tasks in the same wave run in parallel
status	string	Yes	"pending"	Current task state
findings	string|null	No	null	Populated on completion. Summary of key output
quality_score	number|null	No	null	Only set by QUALITY-* and REVIEW-* tasks
supervision_verdict	string|null	No	null	Only set by CHECKPOINT-* tasks
error	string|null	No	null	Set when status is failed or skipped

Status Lifecycle

pending -> in_progress -> completed
                       -> failed
pending -> skipped (when upstream dependency failed/skipped)

4. discoveries/{task_id}.json Schema

Each task writes a discovery file on completion. This replaces Claude Code's team_msg(type="state_update").

{
  "task_id": "string — matches the task key in tasks.json",
  "worker": "string — same as task_id (identifies the producing agent)",
  "timestamp": "string — ISO 8601 completion timestamp",
  "type": "string — same as pipeline_phase",
  "status": "string — completed | failed",
  "findings": "string — summary (max 500 chars)",
  "quality_score": "number | null",
  "supervision_verdict": "string | null — pass | warn | block",
  "error": "string | null",
  "data": {
    "key_findings": "string[] — max 5 items, each under 100 chars",
    "decisions": "string[] — include rationale, not just choice",
    "files_modified": "string[] — only for implementation tasks",
    "verification": "string — self-validated | peer-reviewed | tested",
    "risks_logged": "number — CHECKPOINT only: count of risks",
    "blocks_detected": "number — CHECKPOINT only: count of blocking issues"
  },
  "artifacts_produced": "string[] — paths to generated artifact files"
}

5. Validation Rules

Structural Validation

Rule	Description
Unique IDs	Every key in tasks must be unique
Valid deps	Every entry in deps must reference an existing task ID
Valid context_from	Every entry in context_from must reference an existing task ID
No cycles	Dependency graph must be a DAG (no circular dependencies)
Wave ordering	If task A depends on task B, then A.wave > B.wave
Role exists	role must match a directory in .codex/skills/team-lifecycle-v4/roles/
Pipeline phase valid	pipeline_phase must be one of the defined phases

Runtime Validation

Rule	Description
Status transitions	Only valid transitions: pending->in_progress, in_progress->completed/failed, pending->skipped
Dependency check	A task can only move to in_progress if all deps are completed
Skip propagation	If any dep is failed or skipped, task is automatically skipped
Discovery required	A completed task MUST have a corresponding discoveries/{task_id}.json file
Findings required	A completed task MUST have non-null findings
Error required	A failed or skipped task MUST have non-null error
Supervision fields	CHECKPOINT tasks MUST set supervision_verdict on completion
Quality fields	QUALITY-/REVIEW- tasks SHOULD set quality_score on completion

6. Semantic Mapping: Claude Code <-> Codex

TaskCreate Mapping

Claude Code TaskCreate Field	Codex tasks.json Equivalent
title	tasks[id].title
description	tasks[id].description
assignee (role)	tasks[id].role
status: "open"	tasks[id].status: "pending"
metadata.pipeline_phase	tasks[id].pipeline_phase
metadata.deps	tasks[id].deps
metadata.context_from	tasks[id].context_from
metadata.wave	tasks[id].wave

TaskUpdate Mapping

Claude Code TaskUpdate Operation	Codex Equivalent
status: "in_progress"	Write tasks[id].status = "in_progress" in tasks.json
status: "completed" + findings	Write tasks[id].status = "completed" + Write discoveries/{id}.json
status: "failed" + error	Write tasks[id].status = "failed" + tasks[id].error
Attach result metadata	Write discoveries/{id}.json with full data payload

team_msg Mapping

Claude Code team_msg Operation	Codex Equivalent
team_msg(operation="get_state", role=<upstream>)	Read tasks.json + Read discoveries/{upstream_id}.json
team_msg(type="state_update", payload={...})	Write discoveries/{task_id}.json
team_msg(type="broadcast", ...)	Write to wisdom/*.md (session-wide visibility)

7. Column Lifecycle Correspondence

Maps the conceptual "columns" from Claude Code's task board to tasks.json status values.

Claude Code Column	tasks.json Status	Transition Trigger
Backlog	pending	Task created in tasks.json
In Progress	in_progress	spawn_agent called for task
Blocked	pending (deps not met)	Implicit: deps not all completed
Done	completed	Agent writes discovery + coordinator updates status
Failed	failed	Agent reports error or timeout
Skipped	skipped	Upstream dependency failed/skipped

8. Example: Full tasks.json

{
  "session_id": "tlv4-auth-system-20260324",
  "pipeline": "full-lifecycle",
  "requirement": "Design and implement user authentication system with OAuth2 and RBAC",
  "created_at": "2026-03-24T10:00:00+08:00",
  "supervision": true,
  "completed_waves": [1],
  "active_agents": {
    "DRAFT-001": "agent-abc123"
  },
  "tasks": {
    "RESEARCH-001": {
      "title": "Domain research",
      "description": "Explore auth domain: OAuth2 flows, RBAC patterns, competitor analysis, integration constraints",
      "role": "analyst",
      "pipeline_phase": "research",
      "deps": [],
      "context_from": [],
      "wave": 1,
      "status": "completed",
      "findings": "Identified OAuth2+RBAC pattern, 5 integration points, SSO requirement from enterprise customers",
      "quality_score": null,
      "supervision_verdict": null,
      "error": null
    },
    "DRAFT-001": {
      "title": "Product brief",
      "description": "Generate product brief from research context, define vision, problem, users, success metrics",
      "role": "writer",
      "pipeline_phase": "product-brief",
      "deps": ["RESEARCH-001"],
      "context_from": ["RESEARCH-001"],
      "wave": 2,
      "status": "in_progress",
      "findings": null,
      "quality_score": null,
      "supervision_verdict": null,
      "error": null
    },
    "DRAFT-002": {
      "title": "Requirements PRD",
      "description": "Write requirements document with functional/non-functional reqs, user stories, acceptance criteria",
      "role": "writer",
      "pipeline_phase": "requirements",
      "deps": ["DRAFT-001"],
      "context_from": ["DRAFT-001"],
      "wave": 3,
      "status": "pending",
      "findings": null,
      "quality_score": null,
      "supervision_verdict": null,
      "error": null
    }
  }
}