task-orchestrator

Task Orchestrator

Autonomous orchestration of multi-agent builds using tmux + Codex with self-healing monitoring.

Load the senior-engineering skill alongside this one for engineering principles.

Safety Boundaries

• Do not launch parallel workers for tasks with overlapping write scope until the dependency is resolved.
• Do not push branches, merge work, or self-heal by guessing when human review is required.
• Do not store secrets in manifests, logs, prompts, or tmux pane captures.
• Do not continue retrying a failing task indefinitely; stop and surface the blocker after bounded retries.

Core Concepts

1. Task Manifest

A JSON file defining all tasks, their dependencies, files touched, and status.

{
  "project": "project-name",
  "repo": "owner/repo",
  "workdir": "/path/to/worktrees",
  "created": "2026-01-17T00:00:00Z",
  "model": "gpt-5.2-codex",
  "modelTier": "high",
  "phases": [
    {
      "name": "Phase 1: Critical",
      "tasks": [
        {
          "id": "t1",
          "issue": 1,
          "title": "Fix X",
          "files": ["src/foo.js"],
          "dependsOn": [],
          "status": "pending",
          "worktree": null,
          "tmuxSession": null,
          "startedAt": null,
          "lastProgress": null,
          "completedAt": null,
          "prNumber": null
        }
      ]
    }
  ]
}

2. Dependency Rules

• Same file = sequential — Tasks touching the same file must run in order or merge
• Different files = parallel — Independent tasks can run simultaneously
• Explicit depends = wait — dependsOn array enforces ordering
• Phase gates — Next phase waits for current phase completion

3. Execution Model

• Each task gets its own git worktree (isolated branch)
• Each task runs in its own tmux session
• Use Codex with --yolo for autonomous execution
• Model: GPT-5.2-codex high (configurable)

---

Setup Commands

Initialize Orchestration

# 1. Create working directory
WORKDIR="${TMPDIR:-/tmp}/orchestrator-$(date +%s)"
mkdir -p "$WORKDIR"

# 2. Clone repo for worktrees
git clone https://github.com/OWNER/REPO.git "$WORKDIR/repo"
cd "$WORKDIR/repo"

# 3. Create tmux socket
SOCKET="$WORKDIR/orchestrator.sock"

# 4. Initialize manifest
cat > "$WORKDIR/manifest.json" << 'EOF'
{
  "project": "PROJECT_NAME",
  "repo": "OWNER/REPO",
  "workdir": "WORKDIR_PATH",
  "socket": "SOCKET_PATH",
  "created": "TIMESTAMP",
  "model": "gpt-5.2-codex",
  "modelTier": "high",
  "phases": []
}
EOF