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

Team PlanEx — Tasks Schema

Task Metadata Registry

Team PlanEx uses a message bus + state file architecture instead of CSV. Tasks are tracked in .msg/meta.json with state updates via team_msg.

Task State Fields

Field	Type	Description	Example
task_id	string	Unique task identifier	"PLAN-001"
issue_id	string	Source issue identifier	"ISS-20260308-001"
title	string	Task title from solution	"Implement OAuth2 provider"
role	enum	Worker role: planner, executor	"executor"
status	enum	Task status: pending, in_progress, completed, failed	"completed"
assigned_to	string	Worker agent name	"executor"
depends_on	array	Dependency task IDs	["PLAN-001"]
files	array	Files to modify	["src/auth/oauth.ts"]
convergence_criteria	array	Success criteria	["Tests pass", "No lint errors"]
started_at	string	ISO timestamp	"2026-03-08T10:00:00+08:00"
completed_at	string	ISO timestamp	"2026-03-08T10:15:00+08:00"
error	string	Error message if failed	""

---

Message Bus Schema

Message Types

Type	From	To	Data Schema	Description
plan_ready	planner	coordinator	{issue_id, solution_path, task_count}	Planning complete
impl_start	executor	coordinator	{task_id, issue_id}	Implementation started
impl_complete	executor	coordinator	{task_id, issue_id, files_modified[], commit_hash}	Implementation complete
impl_progress	executor	coordinator	{task_id, progress_pct, current_step}	Progress update
error	any	coordinator	{task_id, error_type, message}	Error occurred
state_update	any	coordinator	{role, state: {}}	Role state update (auto-synced to meta.json)

Message Format (NDJSON)

{"id":"MSG-001","ts":"2026-03-08T10:00:00+08:00","from":"planner","to":"coordinator","type":"plan_ready","summary":"Planning complete for ISS-001","data":{"issue_id":"ISS-20260308-001","solution_path":"artifacts/solutions/ISS-20260308-001.json","task_count":3}}
{"id":"MSG-002","ts":"2026-03-08T10:05:00+08:00","from":"executor","to":"coordinator","type":"impl_start","summary":"Starting EXEC-001","data":{"task_id":"EXEC-001","issue_id":"ISS-20260308-001"}}
{"id":"MSG-003","ts":"2026-03-08T10:15:00+08:00","from":"executor","to":"coordinator","type":"impl_complete","summary":"Completed EXEC-001","data":{"task_id":"EXEC-001","issue_id":"ISS-20260308-001","files_modified":["src/auth/oauth.ts"],"commit_hash":"abc123"}}

---

State File Schema (meta.json)

Structure

{
  "session_id": "PEX-auth-system-20260308",
  "pipeline_mode": "plan-execute",
  "execution_method": "codex",
  "status": "running",
  "started_at": "2026-03-08T10:00:00+08:00",
  "issues": {
    "ISS-20260308-001": {
      "status": "completed",
      "solution_path": "artifacts/solutions/ISS-20260308-001.json",
      "tasks": ["EXEC-001", "EXEC-002"],
      "completed_at": "2026-03-08T10:30:00+08:00"
    }
  },
  "tasks": {
    "EXEC-001": {
      "task_id": "EXEC-001",
      "issue_id": "ISS-20260308-001",
      "title": "Implement OAuth2 provider",
      "role": "executor",
      "status": "completed",
      "assigned_to": "executor",
      "depends_on": [],
      "files": ["src/auth/oauth.ts"],
      "convergence_criteria": ["Tests pass", "No lint errors"],
      "started_at": "2026-03-08T10:05:00+08:00",
      "completed_at": "2026-03-08T10:15:00+08:00",
      "error": ""
    }
  },
  "roles": {
    "coordinator": {
      "status": "active",
      "current_phase": "execution",
      "last_update": "2026-03-08T10:15:00+08:00"
    },
    "planner": {
      "status": "idle",
      "issues_planned": 5,
      "last_update": "2026-03-08T10:10:00+08:00"
    },
    "executor": {
      "status": "active",
      "current_task": "EXEC-002",
      "tasks_completed": 1,
      "last_update": "2026-03-08T10:15:00+08:00"
    }
  }
}

---

Solution File Schema

Planner generates solution files in artifacts/solutions/<issue-id>.json:

{
  "issue_id": "ISS-20260308-001",
  "title": "Implement OAuth2 authentication",
  "approach": "Strategy pattern with provider abstraction",
  "complexity": "Medium",
  "tasks": [
    {
      "task_id": "EXEC-001",
      "title": "Create OAuth2 provider interface",
      "description": "Define provider interface with authorize/token/refresh methods",
      "files": ["src/auth/providers/oauth-provider.ts"],
      "depends_on": [],
      "convergence_criteria": [
        "Interface compiles without errors",
        "Type definitions exported"
      ]
    },
    {
      "task_id": "EXEC-002",
      "title": "Implement Google OAuth2 provider",
      "description": "Concrete implementation for Google OAuth2",
      "files": ["src/auth/providers/google-oauth.ts"],
      "depends_on": ["EXEC-001"],
      "convergence_criteria": [
        "Tests pass",
        "Handles token refresh",
        "Error handling complete"
      ]
    }
  ],
  "exploration_findings": {
    "existing_patterns": ["Strategy pattern in payment module"],
    "tech_stack": ["TypeScript", "Express", "Passport.js"],
    "integration_points": ["User service", "Session store"]
  }
}

---

Execution Method Selection

Coordinator selects execution method based on issue complexity:

Complexity	Method	Criteria
Low	gemini	1-2 files, simple logic, no architecture changes
Medium	codex	3-5 files, moderate complexity, existing patterns
High	codex	6+ files, complex logic, architecture changes

Stored in meta.json → execution_method field.

---

Validation Rules

Rule	Check	Error
Unique task IDs	No duplicate task_id in meta.json	"Duplicate task ID: {task_id}"
Valid deps	All depends_on task IDs exist	"Unknown dependency: {dep_id}"
No self-deps	Task cannot depend on itself	"Self-dependency: {task_id}"
No circular deps	Dependency graph is acyclic	"Circular dependency detected"
Valid status	status ∈ {pending, in_progress, completed, failed}	"Invalid status: {status}"
Valid role	role ∈ {planner, executor}	"Invalid role: {role}"
Issue exists	issue_id exists in issues registry	"Unknown issue: {issue_id}"
Solution file exists	solution_path points to valid file	"Solution file not found: {path}"

---

Cross-Role Context Flow

Source	Target	Mechanism
Planner solution	Executor	Read solution JSON from artifacts/solutions/
Executor progress	Coordinator	Message bus (impl_progress, impl_complete)
Coordinator state	All workers	Read meta.json state field
Any role state update	meta.json	Auto-sync via team_msg type="state_update"

---

Discovery Types

Team PlanEx does not use discoveries.ndjson. All context is stored in:

• Solution files (planner output)
• Message bus (real-time communication)
• meta.json (persistent state)
• wisdom/ directory (cross-task knowledge)