fleet-run

Your objective is to execute a CocoFleet manifest.

Before proceeding, verify that .cocoplus/ exists. If not: output "CocoPlus not initialized in this directory. Run $pod init to begin." Then stop.

Parse argument: $fleet run [manifest-path] If no manifest-path: output "Usage: $fleet run [manifest-path]" Then stop.

Read the manifest file at [manifest-path]. If not found: output "Manifest not found: [manifest-path]" Then stop.

Validate Manifest

Check: instance count ≤ 10. If exceeded: output "WARNING: Fleet has [N] instances, exceeding the 10-instance maximum. Edit manifest to reduce instance count." Then stop.

If mode = "goal_decomposition" or "mode": "goal_decomposition":

1. Require a planner role entry that writes .cocoplus/fleet/[fleet-id]/task-plan.json.
2. Require each planned task to declare:
   • id
   • role: planner, producer, or critic
   • model_tier: smol, regular, smart, or ultra
   • file_scope: array of files or directories owned by the task
   • depends_on: array, empty when no predecessor exists
   • critic_required: boolean for producer outputs that need signoff
3. Require critic tasks to declare tool_set: "read_only". A critic that can write the artifact it grades is invalid.
4. Validate concurrent producer tasks have disjoint file_scope entries. If scopes overlap, do not fail the run; rewrite the launch plan so overlapping tasks run sequentially.
5. A goal-decomposition fleet is complete only after every producer with critic_required = true has a dependent critic task with PASS signoff recorded in task-plan.json or state.json.

Check if coco is available (cross-platform: run coco --version and verify exit code 0). If not found: output "ERROR: 'coco' CLI not in PATH. Install Coco and ensure it is accessible before running a fleet." Then stop.

Create Fleet State File

Generate fleet-id: fleet-YYYYMMDD-HHMMSS

Create .cocoplus/fleet/[fleet-id]/.

Write .cocoplus/fleet/[fleet-id]/state.json:

{
  "fleet_id": "[fleet-id]",
  "manifest_path": "[manifest-path]",
  "started_at": "[ISO 8601 timestamp]",
  "status": "running",
  "mode": "[standard|goal_decomposition]",
  "instances": {},
  "roles": {
    "planner": [],
    "producer": [],
    "critic": []
  }
}

Initialize each instance in the state with status "pending".

Create .cocoplus/fleet/[fleet-id]/comms.log and append one JSON line for every dispatch, heartbeat, completion, blocker, and critic signoff event:

{"ts":"[ISO]","fleet_id":"[fleet-id]","event":"dispatch","role":"producer","instance_id":"[id]","summary":"[short task]"}

Resolve and Execute Instances

Algorithm:

1. Find all instances with no depends_on or with all dependencies satisfied in state.json

2. For each ready instance: a. Create directory: .cocoplus/fleet/[fleet-id]/[instance-id]/ b. Verify task_file exists. If not: mark instance as failed, log error. c. Spawn Coco process using the Bash tool (cross-platform):

   • On Windows (PowerShell): Start-Process coco -ArgumentList "--task-file .cocoplus/fleet/[instance-id]/task.md" -RedirectStandardOutput ".cocoplus/fleet/[instance-id]/output.log" -PassThru | Select-Object -ExpandProperty Id | Out-File ".cocoplus/fleet/[instance-id]/pid.txt"
   • On Mac/Linux (bash): coco --task-file .cocoplus/fleet/[instance-id]/task.md > .cocoplus/fleet/[instance-id]/output.log 2>&1 & echo $! > .cocoplus/fleet/[instance-id]/pid.txt
   • Detect platform with node -e "console.log(process.platform)" — use win32 for Windows check. d. Record PID in state.json, set status = "running", started_at = [timestamp]

3. Record each launched instance in state.json, update last_heartbeat_at and current_task_summary, append a dispatch event to comms.log, and leave blocked instances in pending.

4. Return control to the developer immediately after the initial ready set is launched.

5. Do NOT poll in this command. Ongoing monitoring belongs to $fleet status and follow-up fleet orchestration logic.

Write Aggregated Results

When later orchestration determines the fleet is complete, write .cocoplus/fleet/[fleet-id]/aggregated-results.md:

# Fleet Results: [manifest-path]

**Fleet ID:** [fleet-id]
**Completed:** [ISO 8601 timestamp]
**Duration:** [seconds]

## Instance Summary
| Instance | Status | Duration | Checkpoints |
|----------|--------|----------|-------------|
[one row per instance]

## Overall Status
[COMPLETE / PARTIAL (N failed) / FAILED]

Output: "Fleet started from [manifest-path]. Fleet ID: [fleet-id]. Initial ready instances were launched and the session returned immediately. Use $fleet status [fleet-id] to monitor. Use $fleet stop [fleet-id] to terminate all processes."

Anti-Rationalization

Temptation	Why Not
Block waiting for all instances	Fleet must return control to developer immediately
Share context between instances	Instances are process-isolated by design — no shared context
Exceed 10 instances without warning	10 is the safety limit — always enforce
Let a critic edit the artifact it grades	Producers never grade themselves; critic tasks must be read-only
Launch overlapping producers concurrently	Shared file scope breaks concurrency correctness; sequence overlapping scopes

Exit Criteria

• .cocoplus/fleet/[fleet-id]/state.json exists with status: "running" and an entry for each instance
• .cocoplus/fleet/[fleet-id]/comms.log records dispatch and heartbeat events
• All ready instances (no unmet dependencies) have been spawned with PIDs recorded in state.json
• output.log and pid.txt files exist in each launched instance's directory
• Goal-decomposition mode has task-plan role fields, read-only critics, disjoint concurrent file scopes, and critic PASS signoffs for required producer outputs
• Control is returned to the developer immediately after launching the initial ready set — the command does not block