maestro-flow 0.1.0

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

@@ -0,0 +1,100 @@
+# Tasks Schema — team-lifecycle-v4
+
+> Base schema: `~/.ccw/workflows/cli-templates/schemas/team-tasks-schema.json`
+
+This file documents lifecycle-v4 specific extensions to the universal team tasks schema.
+
+## Session ID Format
+
+`tlv4-<topic>-<YYYYMMDD>` (e.g., `tlv4-auth-system-20260324`)
+
+## Valid Roles
+
+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 |
+|-------|------|-------------|
+| 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 |
+
+## Valid Pipelines
+
+| 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
+
+```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" },
+  "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
+    }
+  }
+}
+```

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` |

package/.codex/skills/team-lifecycle-v4/specs/pipelines.md

@@ -0,0 +1,125 @@
+# Pipeline Definitions
+
+## 1. Pipeline Selection Criteria
+
+| Keywords | Pipeline |
+|----------|----------|
+| spec, design, document, requirements | `spec-only` |
+| implement, build, fix, code | `impl-only` |
+| full, lifecycle, end-to-end | `full-lifecycle` |
+| frontend, UI, react, vue | `fe-only` or `fullstack` |
+| Ambiguous / unclear | request_user_input |
+
+## 2. Spec-Only Pipeline
+
+**6 tasks + 2 optional checkpoints**
+
+```
+RESEARCH-001 -> DRAFT-001 -> DRAFT-002 -> [CHECKPOINT-001] -> DRAFT-003 -> DRAFT-004 -> [CHECKPOINT-002] -> QUALITY-001
+```
+
+| Task | Role | Description |
+|------|------|-------------|
+| RESEARCH-001 | analyst | Research domain, competitors, constraints |
+| DRAFT-001 | writer | Product brief, self-validate |
+| DRAFT-002 | writer | Requirements PRD |
+| CHECKPOINT-001 | supervisor | Brief<->PRD consistency, terminology alignment |
+| DRAFT-003 | writer | Architecture design, self-validate |
+| DRAFT-004 | writer | Epics & stories, self-validate |
+| CHECKPOINT-002 | supervisor | Full spec consistency (4 docs), quality trend |
+| QUALITY-001 | reviewer | Quality gate scoring |
+
+**Checkpoint**: After QUALITY-001 -- pause for user approval before any implementation.
+
+**Supervision opt-out**: Set `supervision: false` in tasks.json to skip CHECKPOINT tasks.
+
+## 3. Impl-Only Pipeline
+
+**4 tasks + 1 optional checkpoint**
+
+```
+PLAN-001 -> [CHECKPOINT-003] -> IMPL-001 -> TEST-001 + REVIEW-001
+```
+
+| Task | Role | Description |
+|------|------|-------------|
+| PLAN-001 | planner | Break down into implementation steps, assess complexity |
+| CHECKPOINT-003 | supervisor | Plan<->input alignment, complexity sanity check |
+| IMPL-001 | implementer | Execute implementation plan |
+| TEST-001 | tester | Validate against acceptance criteria |
+| REVIEW-001 | reviewer | Code review |
+
+TEST-001 and REVIEW-001 run in parallel after IMPL-001 completes.
+
+**Supervision opt-out**: Set `supervision: false` in tasks.json to skip CHECKPOINT tasks.
+
+## 4. Full-Lifecycle Pipeline
+
+**10 tasks + 3 optional checkpoints = spec-only (6+2) + impl (4+1)**
+
+```
+[Spec pipeline with CHECKPOINT-001/002] -> PLAN-001(blockedBy: QUALITY-001) -> [CHECKPOINT-003] -> IMPL-001 -> TEST-001 + REVIEW-001
+```
+
+PLAN-001 is blocked until QUALITY-001 passes and user approves the checkpoint.
+
+**Supervision opt-out**: Set `supervision: false` in tasks.json to skip all CHECKPOINT tasks.
+
+## 5. Frontend Pipelines
+
+| Pipeline | Description |
+|----------|-------------|
+| `fe-only` | Frontend implementation only: PLAN-001 -> IMPL-001 (fe-implementer) -> TEST-001 + REVIEW-001 |
+| `fullstack` | Backend + frontend: PLAN-001 -> IMPL-001 (backend) + IMPL-002 (frontend) -> TEST-001 + REVIEW-001 |
+| `full-lifecycle-fe` | Full spec pipeline -> fullstack impl pipeline |
+
+## 6. Conditional Routing
+
+PLAN-001 outputs a complexity assessment that determines the impl topology.
+
+| Complexity | Modules | Route |
+|------------|---------|-------|
+| Low | 1-2 | PLAN-001 -> IMPL-001 -> TEST + REVIEW |
+| Medium | 3-4 | PLAN-001 -> ORCH-001 -> IMPL-{1..N} (parallel) -> TEST + REVIEW |
+| High | 5+ | PLAN-001 -> ARCH-001 -> ORCH-001 -> IMPL-{1..N} -> TEST + REVIEW |
+
+- **ORCH-001** (orchestrator): Coordinates parallel IMPL tasks, manages dependencies
+- **ARCH-001** (architect): Detailed architecture decisions before orchestration
+
+## 7. Task Metadata Registry
+
+| Task ID | Role | Phase | Depends On | Priority |
+|---------|------|-------|------------|----------|
+| RESEARCH-001 | analyst | research | - | P0 |
+| DRAFT-001 | writer | product-brief | RESEARCH-001 | P0 |
+| DRAFT-002 | writer | requirements | DRAFT-001 | P0 |
+| DRAFT-003 | writer | architecture | DRAFT-002 | P0 |
+| DRAFT-004 | writer | epics | DRAFT-003 | P0 |
+| QUALITY-001 | reviewer | readiness | CHECKPOINT-002 (or DRAFT-004) | P0 |
+| CHECKPOINT-001 | supervisor | checkpoint | DRAFT-002 | P1 |
+| CHECKPOINT-002 | supervisor | checkpoint | DRAFT-004 | P1 |
+| CHECKPOINT-003 | supervisor | checkpoint | PLAN-001 | P1 |
+| PLAN-001 | planner | planning | QUALITY-001 (or user input) | P0 |
+| ARCH-001 | architect | arch-detail | PLAN-001 | P1 |
+| ORCH-001 | orchestrator | orchestration | PLAN-001 or ARCH-001 | P1 |
+| IMPL-001 | implementer | implementation | PLAN-001 or ORCH-001 | P0 |
+| IMPL-{N} | implementer | implementation | ORCH-001 | P0 |
+| TEST-001 | tester | validation | IMPL-* | P0 |
+| REVIEW-001 | reviewer | review | IMPL-* | P0 |
+
+## 8. Dynamic Specialist Injection
+
+When task content or user request matches trigger keywords, inject a specialist task.
+
+| Trigger Keywords | Specialist Role | Task Prefix | Priority | Insert After |
+|------------------|----------------|-------------|----------|--------------|
+| security, vulnerability, OWASP | security-expert | SECURITY-* | P0 | PLAN |
+| performance, optimization, latency | performance-optimizer | PERF-* | P1 | IMPL |
+| data, pipeline, ETL, migration | data-engineer | DATA-* | P0 | parallel with IMPL |
+| devops, CI/CD, deployment, infra | devops-engineer | DEVOPS-* | P1 | IMPL |
+| ML, model, training, inference | ml-engineer | ML-* | P0 | parallel with IMPL |
+
+**Injection rules**:
+- Specialist tasks inherit the session context and wisdom
+- They write discoveries/{task_id}.json on completion like any other task
+- P0 specialists block downstream tasks; P1 run in parallel