maestro-flow 0.3.9 → 0.3.11

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

@@ -4,107 +4,78 @@ description: Lightweight session execution skill. Resumes existing team-coordina
 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 Executor
-
+<purpose>
 Lightweight session execution skill: load session -> reconcile state -> spawn team-worker agents -> execute -> deliver. **No analysis, no role generation** -- only executes existing team-coordinate sessions.
 
-
-## Architecture
-
 ```
-+---------------------------------------------------+
-|  Skill(skill="team-executor")                      |
-|  args="--session=<path>" [REQUIRED]                |
-+-------------------+-------------------------------+
-                    | Session Validation
-         +---- --session valid? ----+
-         | NO                       | YES
-         v                          v
-    Error immediately          Orchestration Mode
-    (no session)               -> executor
-                                    |
-                    +-------+-------+-------+
-                    v       v       v       v
-                 [team-worker agents loaded from session role-specs]
+Skill(skill="team-executor")
+  args="--session=<path>" [REQUIRED]
+         |
+  Session Validation
+         |
+  +-- valid? --+-- NO --> Error immediately
+               +-- YES -> Orchestration Mode -> executor
+                              |
+              +-------+-------+-------+
+              v       v       v       v
+           [team-worker agents loaded from session role-specs]
 ```
+</purpose>
 
----
-
-## Session Validation (BEFORE routing)
-
-**CRITICAL**: Session validation MUST occur before any execution.
-
-### Parse Arguments
-
-Extract from `$ARGUMENTS`:
-- `--session=<path>`: Path to team-coordinate session folder (REQUIRED)
-
-### Validation Steps
-
-1. **Check `--session` provided**:
-   - If missing -> **ERROR**: "Session required. Usage: --session=<path-to-TC-folder>"
-
-2. **Validate session structure** (see specs/session-schema.md):
-   - Directory exists at path
-   - `team-session.json` exists and valid JSON
-   - `task-analysis.json` exists and valid JSON
-   - `role-specs/` directory has at least one `.md` file
-   - Each role in `team-session.json#roles` has corresponding `.md` file in `role-specs/`
-
-3. **Validation failure**:
-   - Report specific missing component
-   - Suggest re-running team-coordinate or checking path
-
----
-
-## Role Router
+<context>
+$ARGUMENTS — session path (required).
 
-This skill is **executor-only**. Workers do NOT invoke this skill -- they are spawned as `team-worker` agents directly.
+**Parse:** `--session=<path>` — Path to team-coordinate session folder (REQUIRED)
 
-### Dispatch Logic
+**Validation Steps:**
+1. Check `--session` provided
+2. Directory exists at path
+3. `team-session.json` exists and valid JSON
+4. `task-analysis.json` exists and valid JSON
+5. `role-specs/` directory has at least one `.md` file
+6. Each role in `team-session.json#roles` has corresponding `.md` in `role-specs/`
 
+**Dispatch:**
 | Scenario | Action |
 |----------|--------|
-| No `--session` | **ERROR** immediately |
-| `--session` invalid | **ERROR** with specific reason |
+| No `--session` | ERROR immediately |
+| `--session` invalid | ERROR with specific reason |
 | Valid session | Orchestration Mode -> executor |
 
-### Orchestration Mode
-
-**Invocation**: `Skill(skill="team-executor", args="--session=<session-folder>")`
-
-**Lifecycle**:
-```
-Validate session
-  -> executor Phase 0: Reconcile state (reset interrupted, detect orphans)
-  -> executor Phase 1: Spawn first batch team-worker agents (background) -> STOP
-  -> Worker executes -> callback -> executor advances next step
-  -> Loop until pipeline complete -> Phase 2 report + completion action
-```
-
 **User Commands** (wake paused executor):
-
 | Command | Action |
 |---------|--------|
 | `check` / `status` | Output execution status graph, no advancement |
 | `resume` / `continue` | Check worker states, advance next step |
 
----
-
-## Role Registry
-
+**Role Registry:**
 | Role | File | Type |
 |------|------|------|
 | executor | [roles/executor/role.md](roles/executor/role.md) | built-in orchestrator |
 | (dynamic) | `<session>/role-specs/<role-name>.md` | loaded from session |
 
----
+**Integration with team-coordinate:**
+| Scenario | Skill |
+|----------|-------|
+| New task, no session | team-coordinate |
+| Existing session, resume execution | **team-executor** |
+| Session needs new roles | team-coordinate (with resume) |
+| Pure execution, no analysis | **team-executor** |
+</context>
 
-## Executor Spawn Template
+<execution>
 
-### v2 Worker Spawn (all roles)
+### Orchestration Lifecycle
 
-When executor spawns workers, use `team-worker` agent with role-spec path:
+```
+Validate session
+  -> Phase 0: Reconcile state (reset interrupted, detect orphans)
+  -> Phase 1: Spawn first batch team-worker agents (background) -> STOP
+  -> Worker executes -> callback -> executor advances next step
+  -> Loop until pipeline complete -> Phase 2 report + completion action
+```
+
+### Worker Spawn Template
 
 ```
 spawn_agent({
@@ -132,45 +103,36 @@ pipeline_phase: <pipeline-phase>
 })
 ```
 
-After spawning, use `wait_agent({ timeout_ms: 1800000 })` to collect results (30 min). If `result.timed_out`, send STATUS_CHECK via followup_task (wait 3 min), then FINALIZE with interrupt (wait 3 min), then mark timed_out and close agents. Use `close_agent({ target: <name> })` each worker.
-
----
-
+After spawning: `wait_agent({ timeout_ms: 1800000 })` (30 min). If `result.timed_out`: STATUS_CHECK via followup_task (3 min) → FINALIZE with interrupt (3 min) → mark timed_out, close agents.
 
 ### Model Selection Guide
 
-team-executor loads roles dynamically from session role-specs. Use reasoning_effort based on the role type defined in the session:
+Roles loaded dynamically from session role-specs:
 - Implementation/fix roles: `reasoning_effort: "high"`
 - Verification/test roles: `reasoning_effort: "medium"`
-- Default when role type is unclear: `reasoning_effort: "high"`
-
-## v4 Agent Coordination
+- Default when unclear: `reasoning_effort: "high"`
 
 ### State Reconciliation
 
-On resume, executor reconciles session state with actual running agents:
+On resume, reconcile session state with actual running agents:
 ```
 const running = list_agents({})
-// Compare with session's task-analysis.json active tasks
+// Compare with task-analysis.json active tasks
 // Reset orphaned tasks (in_progress but agent gone) to pending
 ```
 
 ### Worker Communication
 
-- `send_message({ target: "<task-id>", message: "..." })` -- queue supplementary context
-- `followup_task({ target: "<task-id>", message: "..." })` -- assign new work to inner_loop worker
-- `close_agent({ target: "<task-id>" })` -- cleanup completed worker
-
-## Completion Action
+- `send_message({ target: "<task-id>", message: "..." })` — queue supplementary context
+- `followup_task({ target: "<task-id>", message: "..." })` — assign new work to inner_loop worker
+- `close_agent({ target: "<task-id>" })` — cleanup completed worker
 
-When pipeline completes (all tasks done), executor presents an interactive choice:
+### Completion Action
 
 ```
 request_user_input({
   questions: [{
     question: "Team pipeline complete. What would you like to do?",
-    header: "Completion",
-    multiSelect: false,
     options: [
       { label: "Archive & Clean (Recommended)", description: "Archive session, clean up team" },
       { label: "Keep Active", description: "Keep session for follow-up work" },
@@ -180,29 +142,14 @@ request_user_input({
 })
 ```
 
-### Action Handlers
-
 | Choice | Steps |
 |--------|-------|
 | Archive & Clean | Update session status="completed" -> output final summary with artifact paths |
-| Keep Active | Update session status="paused" -> output: "Resume with: Skill(skill='team-executor', args='--session=<path>')" |
-| Export Results | request_user_input(target path) -> copy artifacts to target -> Archive & Clean |
-
----
-
-## Integration with team-coordinate
-
-| Scenario | Skill |
-|----------|-------|
-| New task, no session | team-coordinate |
-| Existing session, resume execution | **team-executor** |
-| Session needs new roles | team-coordinate (with resume) |
-| Pure execution, no analysis | **team-executor** |
-
----
-
-## Error Handling
+| Keep Active | Update session status="paused" -> output resume command |
+| Export Results | request_user_input(target path) -> copy artifacts -> Archive & Clean |
+</execution>
 
+<error_codes>
 | Scenario | Resolution |
 |----------|------------|
 | No --session provided | ERROR immediately with usage message |
@@ -214,3 +161,14 @@ request_user_input({
 | capability_gap reported | Warn only, cannot generate new role-specs |
 | Fast-advance spawns wrong task | Executor reconciles on next callback |
 | Completion action fails | Default to Keep Active, log warning |
+</error_codes>
+
+<success_criteria>
+- [ ] Session validated (all required files present)
+- [ ] State reconciled on resume (orphaned tasks reset)
+- [ ] Team-worker agents spawned with correct role-specs
+- [ ] Workers complete or timeout handled gracefully
+- [ ] Pipeline advances step-by-step through all tasks
+- [ ] Completion action presented and executed
+- [ ] Session state updated throughout lifecycle
+</success_criteria>