diff --git a/.ccw/workflows/cli-templates/schemas/team-tasks-schema.json b/.ccw/workflows/cli-templates/schemas/team-tasks-schema.json new file mode 100644 index 00000000..4e02b55f --- /dev/null +++ b/.ccw/workflows/cli-templates/schemas/team-tasks-schema.json @@ -0,0 +1,255 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "team-tasks-schema", + "title": "Team Tasks State", + "description": "Universal tasks.json schema for all Codex team skills. Single source of truth for task state management, replacing Claude Code TaskCreate/TaskUpdate API.", + + "type": "object", + "required": ["session_id", "skill", "pipeline", "requirement", "created_at", "tasks"], + "properties": { + "session_id": { + "type": "string", + "description": "Unique session identifier. Format: --", + "pattern": "^[a-zA-Z0-9]+-[a-z0-9-]+-\\d{8}$", + "examples": ["tlv4-auth-system-20260324", "brs-product-strategy-20260324", "ao-api-perf-20260324"] + }, + "skill": { + "type": "string", + "description": "Source team skill name (e.g., team-lifecycle-v4, team-brainstorm, team-arch-opt)" + }, + "pipeline": { + "type": "string", + "description": "Selected pipeline name from the skill's specs/pipelines.md or specs/team-config.json" + }, + "requirement": { + "type": "string", + "description": "Original user requirement text, verbatim" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "ISO 8601 creation timestamp with timezone" + }, + "supervision": { + "type": "boolean", + "default": true, + "description": "Whether CHECKPOINT tasks are active" + }, + "completed_waves": { + "type": "array", + "items": { "type": "integer", "minimum": 1 }, + "default": [], + "description": "List of completed wave numbers" + }, + "active_agents": { + "type": "object", + "additionalProperties": { "type": "string" }, + "default": {}, + "description": "Runtime tracking: { task_id: agent_id } for currently running agents" + }, + "gc_rounds": { + "type": "integer", + "minimum": 0, + "default": 0, + "description": "Generator-Critic / Fix-Verify loop iteration count (skills with GC loops)" + }, + "tasks": { + "type": "object", + "additionalProperties": { "$ref": "#/$defs/TaskEntry" }, + "description": "Task registry: { TASK-ID: TaskEntry }" + } + }, + + "$defs": { + "TaskEntry": { + "type": "object", + "required": ["title", "description", "role", "deps", "wave", "status"], + "properties": { + "title": { + "type": "string", + "description": "Human-readable task name" + }, + "description": { + "type": "string", + "description": "What the task should accomplish" + }, + "role": { + "type": "string", + "description": "Role name matching roles//role.md in the skill directory" + }, + "pipeline_phase": { + "type": "string", + "description": "Phase from the skill's pipelines.md Task Metadata Registry (skill-specific)" + }, + "deps": { + "type": "array", + "items": { "type": "string" }, + "default": [], + "description": "Task IDs that must complete before this task starts. All must be 'completed'" + }, + "context_from": { + "type": "array", + "items": { "type": "string" }, + "default": [], + "description": "Task IDs whose discoveries to load as upstream context" + }, + "wave": { + "type": "integer", + "minimum": 1, + "description": "Execution wave number (1-based). Tasks in the same wave run in parallel" + }, + "status": { + "type": "string", + "enum": ["pending", "in_progress", "completed", "failed", "skipped"], + "default": "pending", + "description": "Current task state" + }, + "findings": { + "type": ["string", "null"], + "maxLength": 500, + "default": null, + "description": "Summary of task output (max 500 chars). Required when status=completed" + }, + "quality_score": { + "type": ["number", "null"], + "minimum": 0, + "maximum": 100, + "default": null, + "description": "0-100, set by reviewer/evaluator roles only" + }, + "supervision_verdict": { + "type": ["string", "null"], + "enum": ["pass", "warn", "block", null], + "default": null, + "description": "Set by CHECKPOINT/supervisor tasks only" + }, + "error": { + "type": ["string", "null"], + "default": null, + "description": "Error description. Required when status=failed or status=skipped" + } + } + }, + + "DiscoveryEntry": { + "type": "object", + "required": ["task_id", "timestamp", "status", "findings", "data"], + "description": "Schema for discoveries/{task_id}.json — each task writes one on completion", + "properties": { + "task_id": { + "type": "string", + "description": "Matches the task key in tasks.json" + }, + "worker": { + "type": "string", + "description": "Same as task_id (identifies the producing agent)" + }, + "timestamp": { + "type": "string", + "format": "date-time", + "description": "ISO 8601 completion timestamp" + }, + "type": { + "type": "string", + "description": "Same as pipeline_phase" + }, + "status": { + "type": "string", + "enum": ["completed", "failed"] + }, + "findings": { + "type": "string", + "maxLength": 500 + }, + "quality_score": { + "type": ["number", "null"] + }, + "supervision_verdict": { + "type": ["string", "null"], + "enum": ["pass", "warn", "block", null] + }, + "error": { + "type": ["string", "null"] + }, + "data": { + "type": "object", + "properties": { + "key_findings": { + "type": "array", + "items": { "type": "string", "maxLength": 100 }, + "maxItems": 5 + }, + "decisions": { + "type": "array", + "items": { "type": "string" }, + "description": "Include rationale, not just choice" + }, + "files_modified": { + "type": "array", + "items": { "type": "string" }, + "description": "Only for implementation tasks" + }, + "verification": { + "type": "string", + "enum": ["self-validated", "peer-reviewed", "tested"] + }, + "risks_logged": { + "type": "integer", + "description": "CHECKPOINT only: count of risks" + }, + "blocks_detected": { + "type": "integer", + "description": "CHECKPOINT only: count of blocking issues" + } + } + }, + "artifacts_produced": { + "type": "array", + "items": { "type": "string" }, + "description": "Paths to generated artifact files" + } + } + } + }, + + "$comment_validation_rules": { + "structural": [ + "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", + "Wave ordering: if task A depends on task B, then A.wave > B.wave", + "Role exists: role must match a directory in the skill's roles/" + ], + "runtime": [ + "Status transitions: pending->in_progress, in_progress->completed|failed, pending->skipped", + "Dependency check: task can only move to in_progress if all deps are completed", + "Skip propagation: if any dep is failed|skipped, task is automatically skipped", + "Discovery required: completed task MUST have discoveries/{task_id}.json", + "Findings required: completed task MUST have non-null findings", + "Error required: failed|skipped task MUST have non-null error", + "Supervision fields: CHECKPOINT tasks MUST set supervision_verdict on completion" + ] + }, + + "$comment_claude_code_mapping": { + "TaskCreate": { + "title": "tasks[id].title", + "description": "tasks[id].description", + "assignee": "tasks[id].role", + "status_open": "tasks[id].status = pending", + "metadata.deps": "tasks[id].deps", + "metadata.wave": "tasks[id].wave" + }, + "TaskUpdate": { + "status_in_progress": "Write tasks[id].status = in_progress", + "status_completed": "Write tasks[id].status = completed + Write discoveries/{id}.json", + "status_failed": "Write tasks[id].status = failed + tasks[id].error" + }, + "team_msg": { + "get_state": "Read tasks.json + Read discoveries/{upstream_id}.json", + "state_update": "Write discoveries/{task_id}.json", + "broadcast": "Write to wisdom/*.md" + } + } +} diff --git a/.codex/skills/team-lifecycle-v4/schemas/tasks-schema.md b/.codex/skills/team-lifecycle-v4/schemas/tasks-schema.md index eb18b7cf..912e987e 100644 --- a/.codex/skills/team-lifecycle-v4/schemas/tasks-schema.md +++ b/.codex/skills/team-lifecycle-v4/schemas/tasks-schema.md @@ -1,211 +1,89 @@ -# Tasks Schema (JSON) +# Tasks Schema — team-lifecycle-v4 -## 1. Overview +> Base schema: `~/.ccw/workflows/cli-templates/schemas/team-tasks-schema.json` -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. +This file documents lifecycle-v4 specific extensions to the universal team tasks schema. -## 2. tasks.json Top-Level Structure +## Session ID Format -```json -{ - "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" -} -``` +`tlv4--` (e.g., `tlv4-auth-system-20260324`) -### Required Fields +## Valid Roles -| Field | Type | Description | +Must match a directory in `.codex/skills/team-lifecycle-v4/roles/`: + +| Role | Task Prefix | Description | +|------|-------------|-------------| +| analyst | RESEARCH | Domain research and analysis | +| writer | DRAFT | Document generation (product brief, requirements, etc.) | +| planner | PLAN | Architecture and planning | +| executor | IMPL | Code implementation | +| tester | TEST | Testing and validation | +| reviewer | REVIEW / QUALITY | Code and spec review | +| supervisor | CHECKPOINT | Quality gate verification | +| coordinator | (orchestrator) | Pipeline orchestration (not a task role) | + +## Valid Pipeline Phases + +From `specs/pipelines.md`: + +| Phase | Wave | Description | |-------|------|-------------| -| `session_id` | string | Unique session identifier, format: `tlv4--` | -| `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 }` | +| research | 1 | Domain exploration | +| product-brief | 2 | Vision and problem definition | +| requirements | 3 | Functional/non-functional requirements | +| architecture | 4 | System design | +| epics | 5 | Epic and story breakdown | +| readiness | 6 | Pre-implementation readiness check | +| checkpoint | varies | Supervision gates | +| planning | 7 | Detailed implementation planning | +| arch-detail | 8 | Architecture refinement | +| orchestration | 9 | Task orchestration | +| implementation | 10+ | Code writing | +| validation | varies | Testing | +| review | varies | Code/spec review | -## 3. TaskEntry Schema +## Valid Pipelines -```json -{ - "title": "string — short task title", - "description": "string — detailed task description", - "role": "string — role name matching roles//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" -} -``` +| Pipeline | Description | +|----------|-------------| +| spec-only | Research → Brief → Requirements → Architecture → Epics → Readiness | +| impl-only | Planning → Implementation → Validation → Review | +| full-lifecycle | spec-only + impl-only combined | +| fe-only | Frontend-specific implementation | +| fullstack | Full-stack implementation | +| full-lifecycle-fe | Full lifecycle with frontend focus | -### 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")`. - -```json -{ - "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=)` | 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 +## Example ```json { "session_id": "tlv4-auth-system-20260324", + "skill": "team-lifecycle-v4", "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" - }, + "active_agents": { "DRAFT-001": "agent-abc123" }, "tasks": { "RESEARCH-001": { "title": "Domain research", - "description": "Explore auth domain: OAuth2 flows, RBAC patterns, competitor analysis, integration constraints", + "description": "Explore auth domain: OAuth2 flows, RBAC patterns, competitor analysis", "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", + "findings": "Identified OAuth2+RBAC pattern, 5 integration points, SSO requirement", "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", + "description": "Generate product brief from research context", "role": "writer", "pipeline_phase": "product-brief", "deps": ["RESEARCH-001"], @@ -216,20 +94,6 @@ Maps the conceptual "columns" from Claude Code's task board to tasks.json status "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 } } }