maestro-flow 0.2.1 → 0.3.0

package/.claude/skills/team-testing/roles/strategist/role.md

@@ -0,0 +1,83 @@
+---
+role: strategist
+prefix: STRATEGY
+inner_loop: false
+message_types:
+  success: strategy_ready
+  error: error
+---
+
+# Test Strategist
+
+Analyze git diff, determine test layers, define coverage targets, and formulate test strategy with prioritized execution order.
+
+## Phase 2: Context & Environment Detection
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Task description | From task subject/description | Yes |
+| Session path | Extracted from task description | Yes |
+| .msg/meta.json | <session>/wisdom/.msg/meta.json | No |
+
+1. Extract session path and scope from task description
+2. Get git diff for change analysis:
+
+```
+Bash("git diff HEAD~1 --name-only 2>/dev/null || git diff --cached --name-only")
+Bash("git diff HEAD~1 -- <changed-files> 2>/dev/null || git diff --cached -- <changed-files>")
+```
+
+3. Detect test framework from project files:
+
+| Signal File | Framework | Test Pattern |
+|-------------|-----------|-------------|
+| jest.config.js/ts | Jest | `**/*.test.{ts,tsx,js}` |
+| vitest.config.ts/js | Vitest | `**/*.test.{ts,tsx}` |
+| pytest.ini / pyproject.toml | Pytest | `**/test_*.py` |
+| No detection | Default | Jest patterns |
+
+4. Scan existing test patterns:
+
+```
+Glob("**/*.test.*")
+Glob("**/*.spec.*")
+```
+
+5. Read .msg/meta.json if exists for session context
+
+## Phase 3: Strategy Formulation
+
+**Change analysis dimensions**:
+
+| Change Type | Analysis | Priority |
+|-------------|----------|----------|
+| New files | Need new tests | High |
+| Modified functions | Need updated tests | Medium |
+| Deleted files | Need test cleanup | Low |
+| Config changes | May need integration tests | Variable |
+
+**Strategy output structure**:
+
+1. **Change Analysis Table**: File, Change Type, Impact, Priority
+2. **Test Layer Recommendations**:
+   - L1 Unit: Scope, Coverage Target, Priority Files, Patterns
+   - L2 Integration: Scope, Coverage Target, Integration Points
+   - L3 E2E: Scope, Coverage Target, User Scenarios
+3. **Risk Assessment**: Risk, Probability, Impact, Mitigation
+4. **Test Execution Order**: Prioritized sequence
+
+Write strategy to `<session>/strategy/test-strategy.md`
+
+**Self-validation**:
+
+| Check | Criteria | Fallback |
+|-------|----------|----------|
+| Has L1 scope | L1 scope not empty | Default to all changed files |
+| Has coverage targets | L1 target > 0 | Use defaults (80/60/40) |
+| Has priority files | List not empty | Use all changed files |
+
+## Phase 4: Wisdom & State Update
+
+1. Write discoveries to `<session>/wisdom/conventions.md` (detected framework, patterns)
+2. Update `<session>/wisdom/.msg/meta.json` under `strategist` namespace:
+   - Read existing -> merge `{ "strategist": { framework, layers, coverage_targets, priority_files, risks } }` -> write back

package/.claude/skills/team-testing/specs/pipelines.md

@@ -0,0 +1,101 @@
+# Testing Pipelines
+
+Pipeline definitions and task registry for team-testing.
+
+## Pipeline Selection
+
+| Condition | Pipeline |
+|-----------|----------|
+| fileCount <= 3 AND moduleCount <= 1 | targeted |
+| fileCount <= 10 AND moduleCount <= 3 | standard |
+| Otherwise | comprehensive |
+
+## Pipeline Definitions
+
+### Targeted Pipeline (3 tasks, serial)
+
+```
+STRATEGY-001 -> TESTGEN-001 -> TESTRUN-001
+```
+
+| Task ID | Role | Dependencies | Layer | Description |
+|---------|------|-------------|-------|-------------|
+| STRATEGY-001 | strategist | (none) | — | Analyze changes, define test strategy |
+| TESTGEN-001 | generator | STRATEGY-001 | L1 | Generate L1 unit tests |
+| TESTRUN-001 | executor | TESTGEN-001 | L1 | Execute L1 tests, collect coverage |
+
+### Standard Pipeline (6 tasks, progressive layers)
+
+```
+STRATEGY-001 -> TESTGEN-001 -> TESTRUN-001 -> TESTGEN-002 -> TESTRUN-002 -> TESTANA-001
+```
+
+| Task ID | Role | Dependencies | Layer | Description |
+|---------|------|-------------|-------|-------------|
+| STRATEGY-001 | strategist | (none) | — | Analyze changes, define test strategy |
+| TESTGEN-001 | generator | STRATEGY-001 | L1 | Generate L1 unit tests |
+| TESTRUN-001 | executor | TESTGEN-001 | L1 | Execute L1 tests, collect coverage |
+| TESTGEN-002 | generator | TESTRUN-001 | L2 | Generate L2 integration tests |
+| TESTRUN-002 | executor | TESTGEN-002 | L2 | Execute L2 tests, collect coverage |
+| TESTANA-001 | analyst | TESTRUN-002 | — | Defect pattern analysis, quality report |
+
+### Comprehensive Pipeline (8 tasks, parallel windows)
+
+```
+STRATEGY-001 -> [TESTGEN-001 || TESTGEN-002] -> [TESTRUN-001 || TESTRUN-002] -> TESTGEN-003 -> TESTRUN-003 -> TESTANA-001
+```
+
+| Task ID | Role | Dependencies | Layer | Description |
+|---------|------|-------------|-------|-------------|
+| STRATEGY-001 | strategist | (none) | — | Analyze changes, define test strategy |
+| TESTGEN-001 | generator-1 | STRATEGY-001 | L1 | Generate L1 unit tests (parallel) |
+| TESTGEN-002 | generator-2 | STRATEGY-001 | L2 | Generate L2 integration tests (parallel) |
+| TESTRUN-001 | executor-1 | TESTGEN-001 | L1 | Execute L1 tests (parallel) |
+| TESTRUN-002 | executor-2 | TESTGEN-002 | L2 | Execute L2 tests (parallel) |
+| TESTGEN-003 | generator | TESTRUN-001, TESTRUN-002 | L3 | Generate L3 E2E tests |
+| TESTRUN-003 | executor | TESTGEN-003 | L3 | Execute L3 tests, collect coverage |
+| TESTANA-001 | analyst | TESTRUN-003 | — | Defect pattern analysis, quality report |
+
+## GC Loop (Generator-Critic)
+
+Generator and executor iterate per test layer:
+
+```
+TESTGEN -> TESTRUN -> (if pass_rate < 0.95 OR coverage < target) -> TESTGEN-fix -> TESTRUN-fix
+                      (if pass_rate >= 0.95 AND coverage >= target) -> next layer or TESTANA
+```
+
+- Max iterations: 3 per layer
+- After 3 iterations: accept current state with warning
+
+## Coverage Targets
+
+| Layer | Name | Default Target |
+|-------|------|----------------|
+| L1 | Unit Tests | 80% |
+| L2 | Integration Tests | 60% |
+| L3 | E2E Tests | 40% |
+
+## Session Directory
+
+```
+.workflow/.team/TST-<slug>-<YYYY-MM-DD>/
+├── .msg/messages.jsonl          # Message bus log
+├── .msg/meta.json               # Session metadata
+├── wisdom/                     # Cross-task knowledge
+│   ├── learnings.md
+│   ├── decisions.md
+│   ├── conventions.md
+│   └── issues.md
+├── strategy/                   # Strategist output
+│   └── test-strategy.md
+├── tests/                      # Generator output
+│   ├── L1-unit/
+│   ├── L2-integration/
+│   └── L3-e2e/
+├── results/                    # Executor output
+│   ├── run-001.json
+│   └── coverage-001.json
+└── analysis/                   # Analyst output
+    └── quality-report.md
+```

package/.claude/skills/team-testing/specs/team-config.json

@@ -0,0 +1,93 @@
+{
+  "team_name": "team-testing",
+  "team_display_name": "Team Testing",
+  "description": "Testing team with Generator-Critic loop, shared defect memory, and progressive test layers",
+  "version": "1.0.0",
+
+  "roles": {
+    "coordinator": {
+      "task_prefix": null,
+      "responsibility": "Change scope analysis, layer selection, quality gating",
+      "message_types": ["pipeline_selected", "gc_loop_trigger", "quality_gate", "task_unblocked", "error", "shutdown"]
+    },
+    "strategist": {
+      "task_prefix": "STRATEGY",
+      "responsibility": "Analyze git diff, determine test layers, define coverage targets",
+      "message_types": ["strategy_ready", "error"]
+    },
+    "generator": {
+      "task_prefix": "TESTGEN",
+      "responsibility": "Generate test cases by layer (unit/integration/E2E)",
+      "message_types": ["tests_generated", "tests_revised", "error"]
+    },
+    "executor": {
+      "task_prefix": "TESTRUN",
+      "responsibility": "Execute tests, collect coverage, auto-fix failures",
+      "message_types": ["tests_passed", "tests_failed", "coverage_report", "error"]
+    },
+    "analyst": {
+      "task_prefix": "TESTANA",
+      "responsibility": "Defect pattern analysis, coverage gap analysis, quality report",
+      "message_types": ["analysis_ready", "error"]
+    }
+  },
+
+  "pipelines": {
+    "targeted": {
+      "description": "Small scope: strategy → generate L1 → run",
+      "task_chain": ["STRATEGY-001", "TESTGEN-001", "TESTRUN-001"],
+      "gc_loops": 0
+    },
+    "standard": {
+      "description": "Progressive: L1 → L2 with analysis",
+      "task_chain": ["STRATEGY-001", "TESTGEN-001", "TESTRUN-001", "TESTGEN-002", "TESTRUN-002", "TESTANA-001"],
+      "gc_loops": 1
+    },
+    "comprehensive": {
+      "description": "Full coverage: parallel L1+L2, then L3 with analysis",
+      "task_chain": ["STRATEGY-001", "TESTGEN-001", "TESTGEN-002", "TESTRUN-001", "TESTRUN-002", "TESTGEN-003", "TESTRUN-003", "TESTANA-001"],
+      "gc_loops": 2,
+      "parallel_groups": [["TESTGEN-001", "TESTGEN-002"], ["TESTRUN-001", "TESTRUN-002"]]
+    }
+  },
+
+  "innovation_patterns": {
+    "generator_critic": {
+      "generator": "generator",
+      "critic": "executor",
+      "max_rounds": 3,
+      "convergence_trigger": "coverage >= target && pass_rate >= 0.95"
+    },
+    "shared_memory": {
+      "file": "shared-memory.json",
+      "fields": {
+        "strategist": "test_strategy",
+        "generator": "generated_tests",
+        "executor": "execution_results",
+        "analyst": "analysis_report"
+      },
+      "persistent_fields": ["defect_patterns", "effective_test_patterns", "coverage_history"]
+    },
+    "dynamic_pipeline": {
+      "selector": "coordinator",
+      "criteria": "changed_file_count + module_count + change_type"
+    }
+  },
+
+  "test_layers": {
+    "L1": { "name": "Unit Tests", "coverage_target": 80, "description": "Function-level isolation tests" },
+    "L2": { "name": "Integration Tests", "coverage_target": 60, "description": "Module interaction tests" },
+    "L3": { "name": "E2E Tests", "coverage_target": 40, "description": "User scenario end-to-end tests" }
+  },
+
+  "collaboration_patterns": ["CP-1", "CP-3", "CP-5"],
+
+  "session_dirs": {
+    "base": ".workflow/.team/TST-{slug}-{YYYY-MM-DD}/",
+    "strategy": "strategy/",
+    "tests": "tests/",
+    "results": "results/",
+    "analysis": "analysis/",
+    "messages": ".workflow/.team-msg/{team-name}/"
+  }
+}

package/.codex/skills/maestro-coordinate/SKILL.md

@@ -2,7 +2,7 @@
 name: maestro-coordinate
 description: Team-agent pipeline coordinator — classifies intent, maps to skill chain, spawns one agent per step whose prompt contains the skill invocation ($skill-name "intent"). Step results propagate as context to each successor. Session state at .workflow/.maestro-coordinate/{session-id}/state.json.
 argument-hint: "\"intent text\" [-y] [-c|--continue] [--dry-run] [--chain <name>]"
-allowed-tools: spawn_agent, wait, send_input, close_agent, Read, Write, Bash, Glob, Grep
+allowed-tools: spawn_agent, wait_agent, send_message, close_agent, Read, Write, Bash, Glob, Grep
 ---
 
 ## Auto Mode
@@ -165,10 +165,10 @@ for (const step of state.steps.filter(s => s.status === 'pending')) {
   const agent = spawn_agent({ message: stepPrompt })
 
   // Wait — with timeout urge
-  let result = wait({ ids: [agent], timeout_ms: 600000 })
+  let result = wait_agent({ timeout_ms: 600000 })
   if (result.timed_out) {
-    send_input({ id: agent, message: "Please wrap up and output your findings JSON now." })
-    result = wait({ ids: [agent], timeout_ms: 120000 })
+    send_message({ target: agent, message: "Please wrap up and output your findings JSON now." })
+    result = wait_agent({ timeout_ms: 600000 })
   }
 
   // Parse structured output from agent
@@ -178,7 +178,7 @@ for (const step of state.steps.filter(s => s.status === 'pending')) {
     hints_for_next: ""
   }
 
-  close_agent({ id: agent })
+  close_agent({ target: agent })
 
   // Persist step result
   step.status = result.timed_out ? "failed" : "completed"
@@ -307,5 +307,5 @@ Resume: $maestro-coordinate --continue
 5. **Skip on Failure**: Step failure immediately marks all remaining steps `skipped` and aborts the loop
 6. **Close before spawn**: Always `close_agent` the current step agent before spawning the next
 7. **Dry-run is read-only**: Stop after displaying the chain plan — never spawn agents
-8. **Timeout handling**: One urge via `send_input`; if still timed out → mark `failed`
+8. **Timeout handling**: One urge via `send_message`; if still timed out → mark `failed`
 9. **No CLI fallback**: All execution is agent-native — no `exec_command("maestro cli ...")`

package/.codex/skills/maestro-overlay/SKILL.md

@@ -68,9 +68,7 @@ functions.update_plan({
 ```javascript
 functions.request_user_input({
   id: "overlay-clarify",
-  items: [
-    { type: "text", text: "Which command(s) should this overlay target? (e.g. maestro-execute, maestro-plan)" }
-  ]
+  message: "Which command(s) should this overlay target? (e.g. maestro-execute, maestro-plan)"
 })
 ```
 

package/.codex/skills/manage-issue-analyze/SKILL.md

@@ -69,7 +69,7 @@ If `status` is not `open` or `registered`, emit W001 but continue.
 ```javascript
 spawn_agent({
   task_name: "ctx-explore",
-  fork_context: false,
+  fork_turns: "none",
   message: `## TASK ASSIGNMENT
 
 ### MANDATORY FIRST STEPS
@@ -87,7 +87,7 @@ Identify: affected locations (file:line), caller/callee chains, data flow, exist
 EXPECTED: JSON with: affected_files [{file, line, snippet, relevance}], related_modules, error_handling_gaps, test_coverage_gaps.
 `
 })
-const ctxResult = wait_agent({ targets: ["ctx-explore"], timeout_ms: 300000 })
+const ctxResult = wait_agent({ timeout_ms: 600000 })
 close_agent({ target: "ctx-explore" })
 ```
 

package/.codex/skills/quality-retrospective/SKILL.md

@@ -63,7 +63,7 @@ $maestro-retrospective "3 --compare 2 --auto-yes"
                      │
   Stage 4: Context-Agent Fork (Pattern 2.10)
   ┌────────────────────────────────────────────────────────────────┐
-  │  spawn ctx (fork_context: false)                               │
+  │  spawn ctx (fork_turns: "none")                                │
   │  wait ctx                                                      │
   │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐         │
   │  │lens-tech │ │lens-proc │ │lens-qual │ │lens-dec  │         │
@@ -75,7 +75,7 @@ $maestro-retrospective "3 --compare 2 --auto-yes"
                      │ lens results
   Stage 5: Synthesizer
   ┌──────────────────────────────────────────┐
-  │  spawn synthesizer (fork_context: false) │
+  │  spawn synthesizer (fork_turns: "none") │
   │  → wait → close                          │
   └──────────────────┬───────────────────────┘
                      │ distilled_insights
@@ -84,29 +84,29 @@ $maestro-retrospective "3 --compare 2 --auto-yes"
 
 ## Agent Registry
 
-| Agent | task_name | fork_context | Responsibility |
-|-------|-----------|-------------|----------------|
-| Context Agent | `ctx` | false | Load all phase artifacts: index.json, plan.json, verification.json, review.json, uat.md, issues.jsonl, task summaries |
-| Technical Lens | `lens-tech` | true | Technical debt, architecture decisions, code quality gaps, performance issues |
-| Process Lens | `lens-proc` | true | Workflow efficiency, collaboration patterns, planning accuracy, bottlenecks |
-| Quality Lens | `lens-qual` | true | Test coverage gaps, verification failures, UAT issues, quality gate outcomes |
-| Decision Lens | `lens-dec` | true | Key decisions made, tradeoffs accepted, ADR candidates, reversibility |
-| Synthesizer | `synthesizer` | false | Merge lens results, deduplicate insights, classify routing targets |
+| Agent | task_name | fork_turns | Responsibility |
+|-------|-----------|------------|----------------|
+| Context Agent | `ctx` | "none" | Load all phase artifacts: index.json, plan.json, verification.json, review.json, uat.md, issues.jsonl, task summaries |
+| Technical Lens | `lens-tech` | "all" | Technical debt, architecture decisions, code quality gaps, performance issues |
+| Process Lens | `lens-proc` | "all" | Workflow efficiency, collaboration patterns, planning accuracy, bottlenecks |
+| Quality Lens | `lens-qual` | "all" | Test coverage gaps, verification failures, UAT issues, quality gate outcomes |
+| Decision Lens | `lens-dec` | "all" | Key decisions made, tradeoffs accepted, ADR candidates, reversibility |
+| Synthesizer | `synthesizer` | "none" | Merge lens results, deduplicate insights, classify routing targets |
 
-## Fork Context Strategy
+## Fork Turns Strategy
 
-| Agent | task_name | fork_context | fork_from | Rationale |
-|-------|-----------|-------------|-----------|-----------|
-| Context Agent | `ctx` | false | — | Independent artifact loader; clean start |
-| Technical Lens | `lens-tech` | true | `ctx` | Inherits loaded artifacts — no redundant file reads |
-| Process Lens | `lens-proc` | true | `ctx` | Inherits loaded artifacts — no redundant file reads |
-| Quality Lens | `lens-qual` | true | `ctx` | Inherits loaded artifacts — no redundant file reads |
-| Decision Lens | `lens-dec` | true | `ctx` | Inherits loaded artifacts — no redundant file reads |
-| Synthesizer | `synthesizer` | false | — | Clean context; receives lens results via message |
+| Agent | task_name | fork_turns | fork_from | Rationale |
+|-------|-----------|------------|-----------|-----------|
+| Context Agent | `ctx` | "none" | — | Independent artifact loader; clean start |
+| Technical Lens | `lens-tech` | "all" | `ctx` | Inherits loaded artifacts — no redundant file reads |
+| Process Lens | `lens-proc` | "all" | `ctx` | Inherits loaded artifacts — no redundant file reads |
+| Quality Lens | `lens-qual` | "all" | `ctx` | Inherits loaded artifacts — no redundant file reads |
+| Decision Lens | `lens-dec` | "all" | `ctx` | Inherits loaded artifacts — no redundant file reads |
+| Synthesizer | `synthesizer` | "none" | — | Clean context; receives lens results via message |
 
-**Context-Agent Lifecycle**: Spawn `ctx` first → `wait_agent` → spawn all lens agents (`fork_context: true`) → `wait_agent` batch for lenses → `close_agent` lenses → `close_agent ctx` LAST.
+**Context-Agent Lifecycle**: Spawn `ctx` first → `wait_agent` → spawn all lens agents (`fork_turns: "all"`) → `wait_agent` batch for lenses → `close_agent` lenses → `close_agent ctx` LAST.
 
-> **fork_context semantics**: `fork_context: true` means the spawned agent inherits the *orchestrator's* current conversation context — not the ctx agent's own context. When `wait_agent(["ctx"])` returns, the ctx agent's completed artifact summaries are visible in the orchestrator's context. Lens agents forked after that point therefore inherit those summaries. Lens agents do **not** fork directly from `ctx`; the `fork_from: ctx` column above is conceptual shorthand for this sequencing.
+> **fork_turns semantics**: `fork_turns: "all"` means the spawned agent inherits the *orchestrator's* current conversation context — not the ctx agent's own context. When `wait_agent` for ctx returns, the ctx agent's completed artifact summaries are visible in the orchestrator's context. Lens agents forked after that point therefore inherit those summaries. Lens agents do **not** fork directly from `ctx`; the `fork_from: ctx` column above is conceptual shorthand for this sequencing.
 
 ---
 
@@ -172,7 +172,7 @@ If existing `retrospective.{md,json}` present, move to `{phase_dir}/.history/` w
 ```javascript
 spawn_agent({
   task_name: "ctx",
-  fork_context: false,
+  fork_turns: "none",
   message: `## TASK ASSIGNMENT
 
 ### MANDATORY FIRST STEPS
@@ -199,14 +199,14 @@ EXPECTED: Comprehensive artifact summary covering:
 - Key metrics: lines changed, test coverage, time taken
 `
 })
-wait_agent({ targets: ["ctx"], timeout_ms: 300000 })
+wait_agent({ timeout_ms: 600000 })
 ```
 
 **Step 4b: Fork 4 lens agents** (only active lenses based on `--lens` flag; default: all 4)
 ```javascript
 spawn_agent({
   task_name: "lens-tech",
-  fork_context: true,
+  fork_turns: "all",
   message: `## TECHNICAL LENS ANALYSIS
 
 Analyze the loaded phase artifacts from a TECHNICAL perspective.
@@ -232,7 +232,7 @@ EXPECTED: JSON array of insights, each: {
 
 spawn_agent({
   task_name: "lens-proc",
-  fork_context: true,
+  fork_turns: "all",
   message: `## PROCESS LENS ANALYSIS
 
 Analyze the loaded phase artifacts from a PROCESS perspective.
@@ -250,7 +250,7 @@ EXPECTED: Same JSON array schema as technical lens.
 
 spawn_agent({
   task_name: "lens-qual",
-  fork_context: true,
+  fork_turns: "all",
   message: `## QUALITY LENS ANALYSIS
 
 Analyze the loaded phase artifacts from a QUALITY perspective.
@@ -268,7 +268,7 @@ EXPECTED: Same JSON array schema as technical lens.
 
 spawn_agent({
   task_name: "lens-dec",
-  fork_context: true,
+  fork_turns: "all",
   message: `## DECISION LENS ANALYSIS
 
 Analyze the loaded phase artifacts from a DECISION perspective.
@@ -285,7 +285,6 @@ EXPECTED: Same JSON array schema as technical lens.
 })
 
 const lensResults = wait_agent({
-  targets: ["lens-tech", "lens-proc", "lens-qual", "lens-dec"],
   timeout_ms: 600000
 })
 
@@ -302,7 +301,7 @@ If `lensResults.timed_out` for any agent: emit W001, continue with partial cover
 ```javascript
 spawn_agent({
   task_name: "synthesizer",
-  fork_context: false,
+  fork_turns: "none",
   message: `## SYNTHESIS TASK
 
 Merge and distill insights from 4 lens analyses.
@@ -324,7 +323,7 @@ EXPECTED: JSON with:
 `
 })
 
-const synthResult = wait_agent({ targets: ["synthesizer"], timeout_ms: 300000 })
+const synthResult = wait_agent({ timeout_ms: 600000 })
 close_agent({ target: "synthesizer" })
 ```
 
@@ -498,7 +497,7 @@ Next:
 2. **Context-agent spawns first**: `ctx` must complete before any lens agent is spawned
 3. **Parallel lens dispatch**: All active lens agents spawned in a single batch, then `wait_agent` for all together — never sequentially
 4. **Context-agent closes last**: Close all lens agents before closing `ctx`
-5. **Synthesizer is isolated**: `fork_context: false` — receives lens results only via message, not full conversation history
+5. **Synthesizer is isolated**: `fork_turns: "none"` — receives lens results only via message, not full conversation history
 6. **Stable INS-ids**: `INS-{8hex}` from `hash(phase_num + lens + title)` — re-runs do not create duplicates
 7. **Archive before overwrite**: Move existing retrospective.{md,json} to `.history/` with timestamp before writing new ones
 8. **Spec learnings.md backward-compat**: Append to it only if it already exists — never create it

package/.codex/skills/team-coordinate/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: team-coordinate
 description: Universal team coordination skill with dynamic role generation. Uses team-worker agent architecture with role-spec files. Only coordinator is built-in -- all worker roles are generated at runtime as role-specs and spawned via team-worker agent. Beat/cadence model for orchestration. Triggers on "Team Coordinate ".
-allowed-tools: spawn_agent(*), wait_agent(*), send_message(*), assign_task(*), close_agent(*), list_agents(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*)
+allowed-tools: spawn_agent(*), wait_agent(*), send_message(*), followup_task(*), close_agent(*), list_agents(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), mcp__maestro-tools__team_msg(*)
 ---
 
 # Team Coordinate
@@ -40,7 +40,7 @@ Before calling ANY tool, apply this check:
 
 | Tool Call | Verdict | Reason |
 |-----------|---------|--------|
-| `spawn_agent`, `wait_agent`, `close_agent`, `send_message`, `assign_task` | ALLOWED | Orchestration |
+| `spawn_agent`, `wait_agent`, `close_agent`, `send_message`, `followup_task` | ALLOWED | Orchestration |
 | `list_agents` | ALLOWED | Agent health check |
 | `request_user_input` | ALLOWED | User interaction |
 | `mcp__maestro-tools__team_msg` | ALLOWED | Message bus |
@@ -138,9 +138,8 @@ When coordinator spawns workers, use `team-worker` agent with role-spec path:
 spawn_agent({
   agent_type: "team_worker",
   task_name: "<task-id>",
-  fork_context: false,
-  items: [
-    { type: "text", text: `## Role Assignment
+  fork_turns: "none",
+  message: `## Role Assignment
 role: <role>
 role_spec: <session-folder>/role-specs/<role>.md
 session: <session-folder>
@@ -148,21 +147,20 @@ session_id: <session-id>
 requirement: <task-description>
 inner_loop: <true|false>
 
-Read role_spec file to load Phase 2-4 domain instructions.` },
+Read role_spec file to load Phase 2-4 domain instructions.
 
-    { type: "text", text: `## Task Context
+## Task Context
 task_id: <task-id>
 title: <task-title>
 description: <task-description>
-pipeline_phase: <pipeline-phase>` },
+pipeline_phase: <pipeline-phase>
 
-    { type: "text", text: `## Upstream Context
-<prev_context>` }
-  ]
+## Upstream Context
+<prev_context>`
 })
 ```
 
-After spawning, use `wait_agent({ targets: [...], timeout_ms: 900000 })` to collect results, then `close_agent({ target: <name> })` each worker.
+After spawning, use `wait_agent({ timeout_ms: 900000 })` to collect results, then `close_agent({ target: <name> })` each worker.
 
 **Inner Loop roles** (role has 2+ serial same-prefix tasks): Set `inner_loop: true`. The team-worker agent handles the loop internally.
 
@@ -190,10 +188,10 @@ Override model/reasoning_effort in spawn_agent when cost optimization is needed:
 spawn_agent({
   agent_type: "team_worker",
   task_name: "<task-id>",
-  fork_context: false,
+  fork_turns: "none",
   model: "<model-override>",
   reasoning_effort: "<effort-level>",
-  items: [...]
+  message: "..."
 })
 ```
 
@@ -204,14 +202,14 @@ spawn_agent({
 | Intent | API | Example |
 |--------|-----|---------|
 | Queue supplementary info (don't interrupt) | `send_message` | Send upstream task findings to a running downstream worker |
-| Not used in this skill | `assign_task` | No resident agents -- all workers are one-shot |
+| Not used in this skill | `followup_task` | No resident agents -- all workers are one-shot |
 | Check running agents | `list_agents` | Verify agent health during resume |
 
 **Note**: Since roles are dynamically generated, the coordinator must resolve task prefixes and role names from `team-session.json#roles` at runtime. There are no hardcoded role-specific examples.
 
-### fork_context Strategy
+### fork_turns Strategy
 
-`fork_context: false` is the default. Consider `fork_context: true` only when:
+`fork_turns: "none"` is the default. Consider `fork_turns: "all"` only when:
 - Runtime analysis reveals the task requires deep familiarity with the full conversation context
 - The dynamically-generated role-spec indicates the worker needs project-wide understanding
 - The coordinator has already accumulated significant context about the codebase
@@ -232,7 +230,7 @@ const running = list_agents({})
 ### Named Agent Targeting
 
 Workers are spawned with `task_name: "<task-id>"` enabling direct addressing:
-- `send_message({ target: "<TASK-ID>", items: [...] })` -- queue upstream context without interrupting
+- `send_message({ target: "<TASK-ID>", message: "..." })` -- queue upstream context without interrupting
 - `close_agent({ target: "<TASK-ID>" })` -- cleanup by name
 
 ## Completion Action