| 1 | --- |
| 2 | name: fleet-manager |
| 3 | description: Use when managing, triaging, restarting, escalating, or summarizing Codewhale fleet runs and workers. |
| 4 | metadata: |
| 5 | short-description: Triage Codewhale fleet runs |
| 6 | --- |
| 7 | |
| 8 | # Fleet Manager |
| 9 | |
| 10 | Use this skill when acting as a manager agent for Codewhale fleet runs. |
| 11 | Your job is to classify worker state, choose the narrowest safe typed action, |
| 12 | and leave a ledgered receipt or a safe escalation draft. |
| 13 | |
| 14 | ## Authority Boundary |
| 15 | |
| 16 | - Prefer typed fleet surfaces over shell spelunking: `codewhale fleet status`, |
| 17 | `inspect`, `logs`, `artifacts`, `interrupt`, `restart`, `resume`, `stop` |
| 18 | (stop requires `--all`), and the Runtime API endpoints. |
| 19 | - Do not read `.codewhale/fleet.jsonl`, host logs, or remote files directly |
| 20 | unless the typed command or API is missing required evidence. |
| 21 | - Do not send Slack, webhook, PagerDuty, email, or chat messages unless the |
| 22 | user or run config explicitly authorizes sending. Draft the message instead. |
| 23 | - Never include secrets, tokens, webhook URLs, routing keys, full prompts, or |
| 24 | oversized logs in a summary or escalation. |
| 25 | |
| 26 | ## Triage Loop |
| 27 | |
| 28 | 1. Identify the run and worker from the user request, run receipt, or fleet |
| 29 | status output. If no worker is named, start with `codewhale fleet status`. |
| 30 | 2. Inspect the worker with `codewhale fleet inspect <worker-id>` or the |
| 31 | matching Runtime API worker endpoint (`GET /v1/fleet/workers/{worker_id}`). |
| 32 | 3. Review bounded evidence with `codewhale fleet logs <worker-id>` and |
| 33 | `codewhale fleet artifacts <worker-id>`, or the Runtime API equivalents |
| 34 | (`GET /v1/fleet/runs/{run_id}/receipts/{task_id}/evidence` and |
| 35 | `GET /v1/fleet/runs/{run_id}/events/replay`). Summarize artifact refs, |
| 36 | not full payloads. |
| 37 | 4. Classify the state before acting: |
| 38 | - `transient failure`: transport error, timeout, stale heartbeat, host |
| 39 | unavailable, or retryable provider/network failure. |
| 40 | - `task failure`: worker completed the task but the result is wrong, |
| 41 | missing required artifacts, or reports a domain error. |
| 42 | - `verifier failure`: scorer/verifier failed or disagrees with the worker |
| 43 | result. |
| 44 | - `needs-human`: missing authority, unsafe secret boundary, destructive |
| 45 | action, repeated restart exhaustion, ambiguous product decision, or |
| 46 | conflict between artifacts and verifier. |
| 47 | 5. Choose one typed action: |
| 48 | - run has orphaned leases after a manager restart: |
| 49 | `codewhale fleet resume <run-id>` (idempotent reconcile). |
| 50 | - transient and retry budget remains: `codewhale fleet restart <worker-id>`. |
| 51 | - transient but unsafe to retry: draft escalation and mark needs-human. |
| 52 | - task failure: preserve artifacts, summarize the failure, and avoid restart |
| 53 | unless the task spec says retrying can produce new evidence. |
| 54 | - verifier failure: inspect scorer inputs and artifacts, then escalate if the |
| 55 | verifier cannot be corrected through a typed action. |
| 56 | - needs-human: do not restart automatically; draft a concise escalation. |
| 57 | 6. Record the result in the response: classification, action taken or drafted, |
| 58 | evidence commands, artifact refs, and next owner. |
| 59 | |
| 60 | ## Restart vs Escalate |
| 61 | |
| 62 | Restart only when all of these are true: |
| 63 | |
| 64 | - the failure is likely transient, |
| 65 | - the task is idempotent or the run policy allows retry, |
| 66 | - retry budget remains, |
| 67 | - no secret, permission, or destructive action boundary is involved, and |
| 68 | - the previous attempt produced enough receipt data to explain the restart. |
| 69 | |
| 70 | Escalate when any of these are true: |
| 71 | |
| 72 | - restart budget is exhausted, |
| 73 | - the worker requests secrets or new authority, |
| 74 | - artifacts indicate data loss, corruption, or destructive side effects, |
| 75 | - the verifier and task result conflict in a way you cannot resolve from typed |
| 76 | evidence, |
| 77 | - the same failure repeats after a restart, or |
| 78 | - a human product or release decision is required. |
| 79 | |
| 80 | ## Safe Escalation Draft |
| 81 | |
| 82 | Use this shape for Slack/PagerDuty drafts. Keep logs to three short lines or an |
| 83 | artifact ref. |
| 84 | |
| 85 | ```text |
| 86 | Codewhale fleet needs attention |
| 87 | Run: <run-id> |
| 88 | Worker: <worker-id> |
| 89 | Task: <task-id or unknown> |
| 90 | Classification: <transient failure | task failure | verifier failure | needs-human> |
| 91 | Reason: <one sentence, no secrets> |
| 92 | Latest typed evidence: codewhale fleet inspect <worker-id>; codewhale fleet artifacts <worker-id> |
| 93 | Safe log excerpt: <3 lines max or "see artifact <ref>"> |
| 94 | Requested decision: <restart approval | verifier review | task owner review | permission decision> |
| 95 | ``` |
| 96 | |
| 97 | ## Post-Run Receipt |
| 98 | |
| 99 | End every Fleet Manager response with a compact receipt: |
| 100 | |
| 101 | ```text |
| 102 | Fleet receipt |
| 103 | Run: <run-id> |
| 104 | Workers checked: <count/list> |
| 105 | Classification: <state> |
| 106 | Action: <restart/interrupt/stop/resume/escalation draft/no-op> |
| 107 | Ledger expectation: <typed action should be recorded | draft only, no send> |
| 108 | Artifacts reviewed: <refs> |
| 109 | Follow-up owner: <manager | task owner | human> |
| 110 | ``` |
| 111 |