--- name: team-executor description: Lightweight session execution skill. Resumes existing team-coordinate sessions for pure execution. No analysis, no role generation -- only loads and executes. Session path required. Triggers on "team executor". allowed-tools: TeamCreate(*), TeamDelete(*), SendMessage(*), TaskCreate(*), TaskUpdate(*), TaskList(*), TaskGet(*), Task(*), AskUserQuestion(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*) --- # Team Executor Lightweight session execution skill: load session -> reconcile state -> spawn workers -> execute -> deliver. **No analysis, no role generation** -- only executes existing team-coordinate sessions. ## Architecture ``` +---------------------------------------------------+ | Skill(skill="team-executor") | | args="--session=" [REQUIRED] | | args="--role=" (for worker dispatch) | +-------------------+-------------------------------+ | Session Validation +---- --session valid? ----+ | NO | YES v v Error immediately Role Router (no session) | +-------+-------+ | --role present? | | YES | | NO v | v Route to | Orchestration Mode session | -> executor role.md | ``` --- ## Session Validation (BEFORE routing) **CRITICAL**: Session validation MUST occur before any role routing. ### Parse Arguments Extract from `$ARGUMENTS`: - `--session=`: Path to team-coordinate session folder (REQUIRED) - `--role=`: Role to dispatch (optional, defaults to orchestration mode) ### Validation Steps 1. **Check `--session` provided**: - If missing -> **ERROR**: "Session required. Usage: --session=" - Do NOT proceed 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 - `roles/` directory has at least one `.md` file - Each role in `team-session.json#roles` has corresponding `.md` file in `roles/` 3. **Validation failure**: - Report specific missing component - Suggest re-running team-coordinate or checking path - Do NOT proceed ### Validation Checklist ``` Session Validation Checklist: [ ] --session argument provided [ ] Directory exists at path [ ] team-session.json exists and parses [ ] task-analysis.json exists and parses [ ] roles/ directory has >= 1 .md files [ ] All session.roles[] have corresponding roles/.md ``` --- ## Role Router ### Dispatch Logic | Scenario | Action | |----------|--------| | No `--session` | **ERROR** immediately | | `--session` invalid | **ERROR** with specific reason | | No `--role` | Orchestration Mode -> executor | | `--role=executor` | Read built-in `roles/executor/role.md` | | `--role=` | Read `/roles/.md` | ### Orchestration Mode When invoked without `--role`, executor auto-starts. **Invocation**: `Skill(skill="team-executor", args="--session=")` **Lifecycle**: ``` Validate session -> executor Phase 0: Reconcile state (reset interrupted, detect orphans) -> executor Phase 1: Spawn first batch workers (background) -> STOP -> Worker executes -> SendMessage callback -> executor advances next step -> Loop until pipeline complete -> Phase 2 report ``` **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 | File | Type | |------|------|------| | executor | [roles/executor/role.md](roles/executor/role.md) | built-in orchestrator | | (dynamic) | `/roles/.md` | loaded from session | > **COMPACT PROTECTION**: Role files are execution documents. After context compression, role instructions become summaries only -- **MUST immediately `Read` the role.md to reload before continuing**. Never execute any Phase based on summaries. --- ## Shared Infrastructure The following templates apply to all worker roles. Each loaded role.md follows the same structure. ### Worker Phase 1: Task Discovery (all workers shared) Each worker on startup executes the same task discovery flow: 1. Call `TaskList()` to get all tasks 2. Filter: subject matches this role's prefix + owner is this role + status is pending + blockedBy is empty 3. No tasks -> idle wait 4. Has tasks -> `TaskGet` for details -> `TaskUpdate` mark in_progress **Resume Artifact Check** (prevent duplicate output after resume): - Check if this task's output artifacts already exist - Artifacts complete -> skip to Phase 5 report completion - Artifacts incomplete or missing -> normal Phase 2-4 execution ### Worker Phase 5: Report + Fast-Advance (all workers shared) Task completion with optional fast-advance to skip executor round-trip: 1. **Message Bus**: Call `mcp__ccw-tools__team_msg` to log message - Params: operation="log", team=****, from=, to="executor", type=, summary="[] ", ref= - **`team` must be session ID** (e.g., `TC-my-project-2026-02-27`), NOT team name. Extract from task description `Session:` field -> take folder name. - **CLI fallback**: `ccw team log --team --from --to executor --type --summary "[] ..." --json` 2. **TaskUpdate**: Mark task completed 3. **Fast-Advance Check**: - Call `TaskList()`, find pending tasks whose blockedBy are ALL completed - If exactly 1 ready task AND its owner matches a simple successor pattern -> **spawn it directly** (skip executor) - Otherwise -> **SendMessage** to executor for orchestration 4. **Loop**: Back to Phase 1 to check for next task **Fast-Advance Rules**: | Condition | Action | |-----------|--------| | Same-prefix successor (Inner Loop role) | Do not spawn, main agent inner loop (Phase 5-L) | | 1 ready task, simple linear successor, different prefix | Spawn directly via Task(run_in_background: true) | | Multiple ready tasks (parallel window) | SendMessage to executor (needs orchestration) | | No ready tasks + others running | SendMessage to executor (status update) | | No ready tasks + nothing running | SendMessage to executor (pipeline may be complete) | **Fast-advance failure recovery**: If a fast-advanced task fails, the executor detects it as an orphaned in_progress task on next `resume`/`check` and resets it to pending for re-spawn. Self-healing. See [monitor.md](roles/executor/commands/monitor.md). ### Worker Inner Loop (roles with multiple same-prefix serial tasks) When a role has **2+ serial same-prefix tasks**, it loops internally instead of spawning new agents: **Inner Loop flow**: ``` Phase 1: Discover task (first time) | +- Found task -> Phase 2-3: Load context + Execute work | | | v | Phase 4: Validation (+ optional Inline Discuss) | | | v | Phase 5-L: Loop Completion | | | +- TaskUpdate completed | +- team_msg log | +- Accumulate summary to context_accumulator | | | +- More same-prefix tasks? | | +- YES -> back to Phase 1 (inner loop) | | +- NO -> Phase 5-F: Final Report | | | +- Interrupt conditions? | +- consensus_blocked HIGH -> SendMessage -> STOP | +- Errors >= 3 -> SendMessage -> STOP | +- Phase 5-F: Final Report +- SendMessage (all task summaries) +- STOP ``` **Phase 5-L vs Phase 5-F**: | Step | Phase 5-L (looping) | Phase 5-F (final) | |------|---------------------|-------------------| | TaskUpdate completed | YES | YES | | team_msg log | YES | YES | | Accumulate summary | YES | - | | SendMessage to executor | NO | YES (all tasks summary) | | Fast-Advance to next prefix | - | YES (check cross-prefix successors) | ### Wisdom Accumulation (all roles) Cross-task knowledge accumulation. Loaded from session at startup. **Directory**: ``` /wisdom/ +-- learnings.md # Patterns and insights +-- decisions.md # Design and strategy decisions +-- issues.md # Known risks and issues ``` **Worker load** (Phase 2): Extract `Session: ` from task description, read wisdom files. **Worker contribute** (Phase 4/5): Write discoveries to corresponding wisdom files. ### Role Isolation Rules | Allowed | Prohibited | |---------|-----------| | Process own prefix tasks | Process other role's prefix tasks | | SendMessage to executor | Directly communicate with other workers | | Use tools appropriate to responsibility | Create tasks for other roles | | Fast-advance simple successors | Spawn parallel worker batches | | Report capability_gap to executor | Attempt work outside scope | Executor additionally prohibited: directly write/modify deliverable artifacts, call implementation subagents directly, directly execute analysis/test/review, generate new roles. --- ## Cadence Control **Beat model**: Event-driven, each beat = executor wake -> process -> spawn -> STOP. ``` Beat Cycle (single beat) ====================================================================== Event Executor Workers ---------------------------------------------------------------------- callback/resume --> +- handleCallback -+ | mark completed | | check pipeline | +- handleSpawnNext -+ | find ready tasks | | spawn workers ---+--> [Worker A] Phase 1-5 | (parallel OK) --+--> [Worker B] Phase 1-5 +- STOP (idle) -----+ | | callback <-----------------------------------------+ (next beat) SendMessage + TaskUpdate(completed) ====================================================================== Fast-Advance (skips executor for simple linear successors) ====================================================================== [Worker A] Phase 5 complete +- 1 ready task? simple successor? --> spawn Worker B directly +- complex case? --> SendMessage to executor ====================================================================== ``` --- ## Executor Spawn Template ### Standard Worker (single-task role) ``` Task({ subagent_type: "general-purpose", description: "Spawn worker", team_name: , name: "", run_in_background: true, prompt: `You are team "" . ## Primary Instruction All your work MUST be executed by calling Skill to get role definition: Skill(skill="team-executor", args="--role= --session=") Current requirement: Session: ## Role Guidelines - Only process -* tasks, do not execute other role work - All output prefixed with [] tag - Only communicate with executor - Do not use TaskCreate to create tasks for other roles - Before each SendMessage, call mcp__ccw-tools__team_msg to log (team= from Session field, NOT team name) - After task completion, check for fast-advance opportunity (see SKILL.md Phase 5) ## Workflow 1. Call Skill -> get role definition and execution logic 2. Follow role.md 5-Phase flow 3. team_msg(team=) + SendMessage results to executor 4. TaskUpdate completed -> check next task or fast-advance` }) ``` ### Inner Loop Worker (multi-task role) ``` Task({ subagent_type: "general-purpose", description: "Spawn worker (inner loop)", team_name: , name: "", run_in_background: true, prompt: `You are team "" . ## Primary Instruction All your work MUST be executed by calling Skill to get role definition: Skill(skill="team-executor", args="--role= --session=") Current requirement: Session: ## Inner Loop Mode You will handle ALL -* tasks in this session, not just the first one. After completing each task, loop back to find the next -* task. Only SendMessage to executor when: - All -* tasks are done - A consensus_blocked HIGH occurs - Errors accumulate (>= 3) ## Role Guidelines - Only process -* tasks, do not execute other role work - All output prefixed with [] tag - Only communicate with executor - Do not use TaskCreate to create tasks for other roles - Before each SendMessage, call mcp__ccw-tools__team_msg to log (team= from Session field, NOT team name) - Use subagent calls for heavy work, retain summaries in context` }) ``` --- ## 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 | Scenario | Resolution | |----------|------------| | No --session provided | ERROR immediately with usage message | | Session directory not found | ERROR with path, suggest checking path | | team-session.json missing | ERROR, session incomplete, suggest re-run team-coordinate | | task-analysis.json missing | ERROR, session incomplete, suggest re-run team-coordinate | | No roles in session | ERROR, session incomplete, suggest re-run team-coordinate | | Role file not found | ERROR with expected path | | capability_gap reported | Warn only, cannot generate new roles (see monitor.md handleAdapt) | | Fast-advance spawns wrong task | Executor reconciles on next callback |