claude-code-workflow 7.2.15 → 7.2.16

package/.codex/skills/team-lifecycle-v4/roles/tester/role.md

@@ -0,0 +1,126 @@
+---
+role: tester
+prefix: TEST
+inner_loop: false
+message_types:
+  success: test_result
+  fix: fix_required
+  error: error
+---
+
+# Tester
+
+Test execution with iterative fix cycle.
+
+## Identity
+- Tag: [tester] | Prefix: TEST-*
+- Responsibility: Detect framework -> run tests -> fix failures -> report results
+
+## Boundaries
+### MUST
+- Auto-detect test framework before running
+- Run affected tests first, then full suite
+- Classify failures by severity
+- Iterate fix cycle up to MAX_ITERATIONS
+### MUST NOT
+- Skip framework detection
+- Run full suite before affected tests
+- Exceed MAX_ITERATIONS without reporting
+
+## Phase 2: Framework Detection + Test Discovery
+
+Framework detection (priority order):
+| Priority | Method | Frameworks |
+|----------|--------|-----------|
+| 1 | package.json devDependencies | vitest, jest, mocha, pytest |
+| 2 | package.json scripts.test | vitest, jest, mocha, pytest |
+| 3 | Config files | vitest.config.*, jest.config.*, pytest.ini |
+
+Affected test discovery from executor's modified files:
+
+1. **Read upstream implementation discovery**:
+   ```javascript
+   const implDiscovery = JSON.parse(Read(`{session}/discoveries/IMPL-001.json`))
+   const modifiedFiles = implDiscovery.files_modified || []
+   ```
+
+2. **Search for matching test files**:
+   - Search: <name>.test.ts, <name>.spec.ts, tests/<name>.test.ts, __tests__/<name>.test.ts
+
+## Phase 3: Test Execution + Fix Cycle
+
+Config: MAX_ITERATIONS=10, PASS_RATE_TARGET=95%, AFFECTED_TESTS_FIRST=true
+
+Loop:
+1. Run affected tests -> parse results
+2. Pass rate met -> run full suite
+3. Failures -> select strategy -> fix -> re-run
+
+Strategy selection:
+| Condition | Strategy |
+|-----------|----------|
+| Iteration <= 3 or pass >= 80% | Conservative: fix one critical failure |
+| Critical failures < 5 | Surgical: fix specific pattern everywhere |
+| Pass < 50% or iteration > 7 | Aggressive: fix all in batch |
+
+Test commands:
+| Framework | Affected | Full Suite |
+|-----------|---------|------------|
+| vitest | vitest run <files> | vitest run |
+| jest | jest <files> --no-coverage | jest --no-coverage |
+| pytest | pytest <files> -v | pytest -v |
+
+## Phase 4: Result Analysis + Report
+
+Failure classification:
+| Severity | Patterns |
+|----------|----------|
+| Critical | SyntaxError, cannot find module, undefined |
+| High | Assertion failures, toBe/toEqual |
+| Medium | Timeout, async errors |
+| Low | Warnings, deprecations |
+
+### Write Discovery
+
+```javascript
+Write(`{session}/discoveries/{id}.json`, JSON.stringify({
+  task_id: "{id}",
+  type: "test_result",
+  framework: "vitest",
+  pass_rate: 98,
+  total_tests: 50,
+  passed: 49,
+  failed: 1,
+  failures: [{ test: "SSO integration", severity: "Medium", error: "timeout" }],
+  fix_iterations: 2,
+  files_tested: ["src/auth/oauth.test.ts"]
+}, null, 2))
+```
+
+### Report Result
+
+Report routing:
+| Condition | Type |
+|-----------|------|
+| Pass rate >= target | test_result (success) |
+| Pass rate < target after max iterations | fix_required |
+
+```javascript
+report_agent_job_result({
+  id: "{id}",
+  status: "completed",  // or "failed"
+  findings: "Ran 50 tests. Pass rate: 98% (49/50). Fixed 2 failures in 2 iterations. Remaining: timeout in SSO integration test.",
+  quality_score: "",
+  supervision_verdict: "",
+  error: ""
+})
+```
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Framework not detected | Prompt coordinator |
+| No tests found | Report to coordinator |
+| Infinite fix loop | Abort after MAX_ITERATIONS |
+| Upstream discovery file missing | Report error, mark failed |

package/.codex/skills/team-lifecycle-v4/roles/writer/role.md

@@ -0,0 +1,125 @@
+---
+role: writer
+prefix: DRAFT
+inner_loop: true
+discuss_rounds: [DISCUSS-002]
+message_types:
+  success: draft_ready
+  revision: draft_revision
+  error: error
+---
+
+# Writer
+
+Template-driven document generation with progressive dependency loading.
+
+## Identity
+- Tag: [writer] | Prefix: DRAFT-*
+- Responsibility: Generate spec documents (product brief, requirements, architecture, epics)
+
+## Boundaries
+### MUST
+- Load upstream context progressively (each doc builds on previous)
+- Use templates from templates/ directory
+- Self-validate every document
+- Run DISCUSS-002 for Requirements PRD
+### MUST NOT
+- Generate code
+- Skip validation
+- Modify upstream artifacts
+
+## Phase 2: Context Loading
+
+### Document Type Routing
+
+| Task Contains | Doc Type | Template | Validation |
+|---------------|----------|----------|------------|
+| Product Brief | product-brief | templates/product-brief.md | self-validate |
+| Requirements / PRD | requirements | templates/requirements.md | DISCUSS-002 |
+| Architecture | architecture | templates/architecture.md | self-validate |
+| Epics | epics | templates/epics.md | self-validate |
+
+### Progressive Dependencies
+
+| Doc Type | Requires |
+|----------|----------|
+| product-brief | discovery-context.json |
+| requirements | + product-brief.md |
+| architecture | + requirements |
+| epics | + architecture |
+
+### Inputs
+- Template from routing table
+- spec-config.json from <session>/spec/
+- discovery-context.json from <session>/spec/
+- Prior decisions from context_accumulator (inner loop)
+- Discussion feedback from <session>/discussions/ (if exists)
+- Read `tasks.json` to get upstream task status
+- Read `discoveries/*.json` to load upstream discoveries and context
+
+## Phase 3: Document Generation
+
+CLI generation:
+```
+Bash({ command: `ccw cli -p "PURPOSE: Generate <doc-type> document following template
+TASK: * Load template * Apply spec config and discovery context * Integrate prior feedback * Generate all sections
+MODE: write
+CONTEXT: @<session>/spec/*.json @<template-path>
+EXPECTED: Document at <output-path> with YAML frontmatter, all sections, cross-references
+CONSTRAINTS: Follow document standards" --tool gemini --mode write --cd <session>`)
+```
+
+## Phase 4: Validation
+
+### Self-Validation (all doc types)
+| Check | Verify |
+|-------|--------|
+| has_frontmatter | YAML frontmatter present |
+| sections_complete | All template sections filled |
+| cross_references | Valid references to upstream docs |
+
+### Validation Routing
+| Doc Type | Method |
+|----------|--------|
+| product-brief | Self-validate -> report |
+| requirements | Self-validate + DISCUSS-002 |
+| architecture | Self-validate -> report |
+| epics | Self-validate -> report |
+
+### Reporting
+
+1. Write discovery to `discoveries/<task_id>.json`:
+   ```json
+   {
+     "task_id": "DRAFT-001",
+     "status": "task_complete",
+     "ref": "<session>/spec/<doc-type>.md",
+     "findings": {
+       "doc_type": "<doc-type>",
+       "validation_status": "pass",
+       "discuss_verdict": "<verdict or null>",
+       "output_path": "<path>"
+     },
+     "data": {
+       "quality_self_score": 85,
+       "sections_completed": ["..."],
+       "cross_references_valid": true
+     }
+   }
+   ```
+2. Report via `report_agent_job_result`:
+   ```
+   report_agent_job_result({
+     id: "DRAFT-001",
+     status: "completed",
+     findings: { doc_type, validation_status, discuss_verdict, output_path }
+   })
+   ```
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| CLI failure | Retry once with alternative tool |
+| Prior doc missing | Notify coordinator |
+| Discussion contradicts prior | Note conflict, flag for coordinator |

package/.codex/skills/team-lifecycle-v4/schemas/tasks-schema.md

@@ -1,178 +1,100 @@
-# Team Lifecycle v4 -- CSV Schema
+# Tasks Schema — team-lifecycle-v4
 
-## Master CSV: tasks.csv
+> Base schema: `~/.ccw/workflows/cli-templates/schemas/team-tasks-schema.json`
 
-### Column Definitions
+This file documents lifecycle-v4 specific extensions to the universal team tasks schema.
 
-#### Input Columns (Set by Decomposer)
+## Session ID Format
 
-| Column | Type | Required | Description | Example |
-|--------|------|----------|-------------|---------|
-| `id` | string | Yes | Unique task identifier | `"RESEARCH-001"` |
-| `title` | string | Yes | Short task title | `"Domain research"` |
-| `description` | string | Yes | Detailed task description (self-contained) | `"Explore domain, extract structured context..."` |
-| `role` | string | Yes | Worker role: analyst, writer, planner, executor, tester, reviewer, supervisor | `"analyst"` |
-| `pipeline_phase` | string | Yes | Lifecycle phase: research, product-brief, requirements, architecture, epics, checkpoint, readiness, planning, implementation, validation, review | `"research"` |
-| `deps` | string | No | Semicolon-separated dependency task IDs | `"RESEARCH-001"` |
-| `context_from` | string | No | Semicolon-separated task IDs for context | `"RESEARCH-001"` |
-| `exec_mode` | enum | Yes | Execution mechanism: `csv-wave` or `interactive` | `"csv-wave"` |
+`tlv4-<topic>-<YYYYMMDD>` (e.g., `tlv4-auth-system-20260324`)
 
-#### Computed Columns (Set by Wave Engine)
+## Valid Roles
 
-| Column | Type | Description | Example |
-|--------|------|-------------|---------|
-| `wave` | integer | Wave number (1-based, from topological sort) | `2` |
-| `prev_context` | string | Aggregated findings from context_from tasks (per-wave CSV only) | `"[Task RESEARCH-001] Explored domain..."` |
+Must match a directory in `.codex/skills/team-lifecycle-v4/roles/`:
 
-#### Output Columns (Set by Agent)
+| 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) |
 
-| Column | Type | Description | Example |
-|--------|------|-------------|---------|
-| `status` | enum | `pending` -> `completed` / `failed` / `skipped` | `"completed"` |
-| `findings` | string | Key discoveries (max 500 chars) | `"Identified 5 integration points..."` |
-| `quality_score` | string | Quality gate score (0-100) for reviewer tasks | `"85"` |
-| `supervision_verdict` | string | Checkpoint verdict: `pass` / `warn` / `block` | `"pass"` |
-| `error` | string | Error message if failed | `""` |
+## Valid Pipeline Phases
 
----
+From `specs/pipelines.md`:
 
-### exec_mode Values
+| Phase | Wave | Description |
+|-------|------|-------------|
+| 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 |
 
-| Value | Mechanism | Description |
-|-------|-----------|-------------|
-| `csv-wave` | `spawn_agents_on_csv` | One-shot batch execution within wave |
-| `interactive` | `spawn_agent`/`wait`/`send_input`/`close_agent` | Multi-round individual execution |
+## Valid Pipelines
 
-Interactive tasks appear in master CSV for dependency tracking but are NOT included in wave-{N}.csv files.
+| 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 |
 
----
-
-### Example Data
-
-```csv
-id,title,description,role,pipeline_phase,deps,context_from,exec_mode,wave,status,findings,quality_score,supervision_verdict,error
-"RESEARCH-001","Domain research","Explore domain and competitors. Extract structured context: problem statement, target users, domain, constraints, exploration dimensions. Use CLI analysis tools.","analyst","research","","","csv-wave","1","pending","","","",""
-"DRAFT-001","Product brief","Generate product brief from research context. Include vision statement, problem definition, target users, success goals. Use templates/product-brief.md template.","writer","product-brief","RESEARCH-001","RESEARCH-001","csv-wave","2","pending","","","",""
-"DRAFT-002","Requirements PRD","Generate requirements PRD with functional requirements (FR-NNN), acceptance criteria, MoSCoW prioritization, user stories.","writer","requirements","DRAFT-001","DRAFT-001","csv-wave","3","pending","","","",""
-"CHECKPOINT-001","Brief-PRD consistency","Verify: vision->requirements trace, terminology alignment, scope consistency, decision continuity, artifact existence.","supervisor","checkpoint","DRAFT-002","DRAFT-001;DRAFT-002","interactive","4","pending","","","",""
-"DRAFT-003","Architecture design","Generate architecture with component diagram, tech stack justification, ADRs, data model, integration points.","writer","architecture","CHECKPOINT-001","DRAFT-002;CHECKPOINT-001","csv-wave","5","pending","","","",""
-"DRAFT-004","Epics and stories","Generate 2-8 epics with 3-12 stories each. Include MVP subset, story format with ACs and estimates.","writer","epics","DRAFT-003","DRAFT-003","csv-wave","6","pending","","","",""
-"CHECKPOINT-002","Full spec consistency","Verify: 4-doc terminology, decision chain, architecture-epics alignment, quality trend, open questions.","supervisor","checkpoint","DRAFT-004","DRAFT-001;DRAFT-002;DRAFT-003;DRAFT-004","interactive","7","pending","","","",""
-"QUALITY-001","Readiness gate","Score spec quality across Completeness, Consistency, Traceability, Depth (25% each). Gate: >=80% pass, 60-79% review, <60% fail.","reviewer","readiness","CHECKPOINT-002","DRAFT-001;DRAFT-002;DRAFT-003;DRAFT-004","csv-wave","8","pending","","","",""
-"PLAN-001","Implementation planning","Explore codebase, generate plan.json + TASK-*.json (2-7 tasks), assess complexity (Low/Medium/High).","planner","planning","QUALITY-001","QUALITY-001","csv-wave","9","pending","","","",""
-"CHECKPOINT-003","Plan-input alignment","Verify: plan covers requirements, complexity sanity, dependency chain, execution method, upstream context.","supervisor","checkpoint","PLAN-001","PLAN-001","interactive","10","pending","","","",""
-"IMPL-001","Code implementation","Execute implementation plan tasks. Follow existing code patterns. Run convergence checks.","executor","implementation","CHECKPOINT-003","PLAN-001","csv-wave","11","pending","","","",""
-"TEST-001","Test execution","Detect test framework. Run affected tests first, then full suite. Fix failures (max 10 iterations, 95% target).","tester","validation","IMPL-001","IMPL-001","csv-wave","12","pending","","","",""
-"REVIEW-001","Code review","Multi-dimensional code review: quality, security, architecture, requirements coverage. Verdict: BLOCK/CONDITIONAL/APPROVE.","reviewer","review","IMPL-001","IMPL-001","csv-wave","12","pending","","","",""
-```
-
----
-
-### Column Lifecycle
-
-```
-Decomposer (Phase 1)     Wave Engine (Phase 2)    Agent (Execution)
----------------------    --------------------     -----------------
-id          ---------->  id          ---------->  id
-title       ---------->  title       ---------->  (reads)
-description ---------->  description ---------->  (reads)
-role        ---------->  role        ---------->  (reads)
-pipeline_phase -------->  pipeline_phase -------->  (reads)
-deps        ---------->  deps        ---------->  (reads)
-context_from---------->  context_from---------->  (reads)
-exec_mode   ---------->  exec_mode   ---------->  (reads)
-                          wave         ---------->  (reads)
-                          prev_context ---------->  (reads)
-                                                    status
-                                                    findings
-                                                    quality_score
-                                                    supervision_verdict
-                                                    error
-```
-
----
-
-## Output Schema (JSON)
-
-Agent output via `report_agent_job_result` (csv-wave tasks):
+## Example
 
 ```json
 {
-  "id": "RESEARCH-001",
-  "status": "completed",
-  "findings": "Explored domain: identified OAuth2+RBAC auth pattern, 5 integration points, TypeScript/React stack. Key constraint: must support SSO.",
-  "quality_score": "",
-  "supervision_verdict": "",
-  "error": ""
+  "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" },
+  "tasks": {
+    "RESEARCH-001": {
+      "title": "Domain research",
+      "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",
+      "quality_score": null,
+      "supervision_verdict": null,
+      "error": null
+    },
+    "DRAFT-001": {
+      "title": "Product brief",
+      "description": "Generate product brief from research context",
+      "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
+    }
+  }
 }
 ```
-
-Quality gate output:
-
-```json
-{
-  "id": "QUALITY-001",
-  "status": "completed",
-  "findings": "Quality gate: Completeness 90%, Consistency 85%, Traceability 80%, Depth 75%. Overall: 82.5% PASS.",
-  "quality_score": "82",
-  "supervision_verdict": "",
-  "error": ""
-}
-```
-
-Interactive tasks (CHECKPOINT-*) output via JSON written to `interactive/{id}-result.json`.
-
----
-
-## Discovery Types
-
-| Type | Dedup Key | Data Schema | Description |
-|------|-----------|-------------|-------------|
-| `research` | `data.dimension` | `{dimension, findings[], constraints[], integration_points[]}` | Research context |
-| `spec_artifact` | `data.doc_type` | `{doc_type, path, sections[], key_decisions[]}` | Specification document |
-| `exploration` | `data.angle` | `{angle, relevant_files[], patterns[], recommendations[]}` | Codebase exploration |
-| `plan_task` | `data.task_id` | `{task_id, title, files[], complexity, convergence_criteria[]}` | Plan task definition |
-| `implementation` | `data.task_id` | `{task_id, files_modified[], approach, changes_summary}` | Implementation result |
-| `test_result` | `data.framework` | `{framework, pass_rate, failures[], fix_iterations}` | Test result |
-| `review_finding` | `data.file` | `{file, line, severity, dimension, description, suggested_fix}` | Review finding |
-| `checkpoint` | `data.checkpoint_id` | `{checkpoint_id, verdict, score, risks[], blocks[]}` | Checkpoint result |
-| `quality_gate` | `data.gate_id` | `{gate_id, score, dimensions{}, verdict}` | Quality assessment |
-
-### Discovery NDJSON Format
-
-```jsonl
-{"ts":"2026-03-08T10:00:00+08:00","worker":"RESEARCH-001","type":"research","data":{"dimension":"domain","findings":["Auth system needs OAuth2 + RBAC"],"constraints":["Must support SSO"],"integration_points":["User service API"]}}
-{"ts":"2026-03-08T10:15:00+08:00","worker":"DRAFT-001","type":"spec_artifact","data":{"doc_type":"product-brief","path":"spec/product-brief.md","sections":["Vision","Problem","Users","Goals"],"key_decisions":["OAuth2 over custom auth"]}}
-{"ts":"2026-03-08T11:00:00+08:00","worker":"IMPL-001","type":"implementation","data":{"task_id":"IMPL-001","files_modified":["src/auth/oauth.ts","src/auth/rbac.ts"],"approach":"Strategy pattern for auth providers","changes_summary":"Created OAuth2 provider, RBAC middleware, session management"}}
-{"ts":"2026-03-08T11:30:00+08:00","worker":"TEST-001","type":"test_result","data":{"framework":"vitest","pass_rate":98,"failures":["timeout in SSO integration test"],"fix_iterations":2}}
-```
-
-> Both csv-wave and interactive agents read/write the same discoveries.ndjson file.
-
----
-
-## Cross-Mechanism Context Flow
-
-| Source | Target | Mechanism |
-|--------|--------|-----------|
-| CSV task findings | Interactive task | Injected via spawn message or send_input |
-| Interactive task result | CSV task prev_context | Read from interactive/{id}-result.json |
-| Any agent discovery | Any agent | Shared via discoveries.ndjson |
-
----
-
-## Validation Rules
-
-| Rule | Check | Error |
-|------|-------|-------|
-| Unique IDs | No duplicate `id` values | "Duplicate task ID: {id}" |
-| Valid deps | All dep IDs exist in tasks | "Unknown dependency: {dep_id}" |
-| No self-deps | Task cannot depend on itself | "Self-dependency: {id}" |
-| No circular deps | Topological sort completes | "Circular dependency detected involving: {ids}" |
-| context_from valid | All context IDs exist and in earlier waves | "Invalid context_from: {id}" |
-| exec_mode valid | Value is `csv-wave` or `interactive` | "Invalid exec_mode: {value}" |
-| Description non-empty | Every task has description | "Empty description for task: {id}" |
-| Status enum | status in {pending, completed, failed, skipped} | "Invalid status: {status}" |
-| Valid role | role in {analyst, writer, planner, executor, tester, reviewer, supervisor} | "Invalid role: {role}" |
-| Valid pipeline_phase | pipeline_phase in {research, product-brief, requirements, architecture, epics, checkpoint, readiness, planning, implementation, validation, review} | "Invalid pipeline_phase: {value}" |
-| Cross-mechanism deps | Interactive->CSV deps resolve correctly | "Cross-mechanism dependency unresolvable: {id}" |

package/.codex/skills/team-lifecycle-v4/specs/knowledge-transfer.md

@@ -0,0 +1,136 @@
+# Knowledge Transfer Protocols
+
+## 1. Transfer Channels
+
+| Channel | Method | Producer | Consumer |
+|---------|--------|----------|----------|
+| Artifacts | Files in `<session>/artifacts/` | Task executor | Next task in pipeline |
+| Discoveries | Files in `<session>/discoveries/{task_id}.json` | Task executor | Coordinator + downstream |
+| Wisdom | Append to `<session>/wisdom/*.md` | Any role | All roles |
+| Context Accumulator | In-memory aggregation | Inner loop only | Current task |
+| Exploration Cache | `<session>/explorations/` | Analyst / researcher | All roles |
+
+## 2. Context Loading Protocol (Before Task Execution)
+
+Every role MUST load context in this order before starting work.
+
+| Step | Action | Required |
+|------|--------|----------|
+| 1 | Read `<session>/tasks.json` -- locate upstream task entries, check status and findings | Yes |
+| 2 | Read `<session>/discoveries/{upstream_id}.json` for each upstream dependency -- get detailed findings and artifact paths | Yes |
+| 3 | Read artifact files from upstream discovery's `artifacts_produced` paths | Yes |
+| 4 | Read `<session>/wisdom/*.md` if exists | Yes |
+| 5 | Check `<session>/explorations/cache-index.json` before new exploration | If exploring |
+
+**Loading rules**:
+- Never skip step 1 -- tasks.json contains task status, wave progression, and summary findings
+- Never skip step 2 -- discoveries contain detailed key_findings, decisions, and artifact references
+- If artifact path in discovery does not exist, log warning and continue
+- Wisdom files are append-only -- read all entries, newest last
+
+## 3. Context Publishing Protocol (After Task Completion)
+
+| Step | Action | Required |
+|------|--------|----------|
+| 1 | Write deliverable to `<session>/artifacts/<task-id>-<name>.md` | Yes |
+| 2 | Write `<session>/discoveries/{task_id}.json` with payload (see schema below) | Yes |
+| 3 | Append wisdom entries for learnings, decisions, issues found | If applicable |
+
+## 4. Discovery File Schema
+
+Written to `<session>/discoveries/{task_id}.json` on task completion.
+
+```json
+{
+  "task_id": "<TASK-NNN>",
+  "worker": "<TASK-NNN>",
+  "timestamp": "2026-03-24T10:15:00+08:00",
+  "type": "<pipeline_phase>",
+  "status": "completed | failed",
+  "findings": "Summary string (max 500 chars)",
+  "quality_score": null,
+  "supervision_verdict": null,
+  "error": null,
+  "data": {
+    "key_findings": [
+      "Finding 1",
+      "Finding 2"
+    ],
+    "decisions": [
+      "Decision with rationale"
+    ],
+    "files_modified": [
+      "path/to/file.ts"
+    ],
+    "verification": "self-validated | peer-reviewed | tested"
+  },
+  "artifacts_produced": [
+    "<session>/artifacts/<task-id>-<name>.md"
+  ]
+}
+```
+
+**Field rules**:
+- `artifacts_produced`: Always artifact paths, never inline content
+- `data.key_findings`: Max 5 items, each under 100 chars
+- `data.decisions`: Include rationale, not just the choice
+- `data.files_modified`: Only for implementation tasks
+- `data.verification`: One of `self-validated`, `peer-reviewed`, `tested`
+
+**Supervisor-specific extensions** (CHECKPOINT tasks only):
+
+```json
+{
+  "supervision_verdict": "pass | warn | block",
+  "supervision_score": 0.85,
+  "data": {
+    "risks_logged": 0,
+    "blocks_detected": 0
+  }
+}
+```
+
+- `supervision_verdict`: Required for CHECKPOINT tasks. Determines pipeline progression.
+- `supervision_score`: Float 0.0-1.0. Aggregate of individual check scores.
+- `data.risks_logged`: Count of risks written to wisdom/issues.md.
+- `data.blocks_detected`: Count of blocking issues found. >0 implies verdict=block.
+
+## 5. Exploration Cache Protocol
+
+Prevents redundant research across tasks.
+
+| Step | Action |
+|------|--------|
+| 1 | Read `<session>/explorations/cache-index.json` |
+| 2 | If angle already explored, read cached result from `explore-<angle>.json` |
+| 3 | If not cached, perform exploration |
+| 4 | Write result to `<session>/explorations/explore-<angle>.json` |
+| 5 | Update `cache-index.json` with new entry |
+
+**cache-index.json format**:
+```json
+{
+  "entries": [
+    {
+      "angle": "competitor-analysis",
+      "file": "explore-competitor-analysis.json",
+      "created_by": "RESEARCH-001",
+      "timestamp": "2026-01-15T10:30:00Z"
+    }
+  ]
+}
+```
+
+**Rules**:
+- Cache key is the exploration `angle` (normalized to kebab-case)
+- Cache entries never expire within a session
+- Any role can read cached explorations; only the creator updates them
+
+## 6. Platform Mapping Reference
+
+| Claude Code 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` |
+| `TaskCreate` / `TaskUpdate` status fields | Read/Write `tasks.json` task entries |
+| In-memory state aggregation | Parse `tasks.json` + glob `discoveries/*.json` |