Conductor

/conductor — Multi-Agent Sprint Orchestrator

Coordinate multiple agent sessions working on the same project. Each agent claims a task, executes it, produces an artifact, and the next agent picks up where it left off.

No daemon. No service. No IPC. Just atomic file operations on .nanostack/conductor/.

Telemetry preamble

Defensive telemetry init. No-op if telemetry is disabled via NANOSTACK_NO_TELEMETRY=1, ~/.nanostack/.telemetry-disabled, or if the helpers are removed.

_P="$HOME/.claude/skills/nanostack/bin/lib/skill-preamble.sh"
[ -f "$_P" ] && . "$_P" conductor
unset _P

How it works

Agent A (claude)          Filesystem              Agent B (codex)
     │                        │                        │
     ├─ claim "plan" ────────►│                        │
     │                  [plan.lock = A]                 │
     │                        │◄──── claim "plan" ─────┤
     │                        │  REJECTED (locked)      │
     │                        │                        │
     ├─ complete "plan" ─────►│                        │
     │                  [plan.done + artifact]          │
     │                        │                        │
     │                        │◄──── claim "review" ───┤
     │                  [review.lock = B]               │
     │                        │  OK (plan.done exists)  │

Sprint Definition

A sprint is a sequence of phases with dependencies:

{
  "sprint_id": "abc123",
  "project": "/path/to/repo",
  "phases": [
    { "name": "think",    "depends_on": [] },
    { "name": "plan",     "depends_on": ["think"] },
    { "name": "build",    "depends_on": ["plan"] },
    { "name": "review",   "depends_on": ["build"] },
    { "name": "security", "depends_on": ["build"] },
    { "name": "qa",       "depends_on": ["build"] },
    { "name": "ship",     "depends_on": ["review", "security", "qa"] }
  ]
}

Note: review, security, and qa can run in parallel — they all depend on build, not on each other. ship waits for all three.

Commands

Start a sprint

conductor/bin/sprint.sh start [--phases "think,plan,build,review,security,qa,ship"]

Creates .nanostack/conductor/<sprint_id>/ with the phase graph. Default is the full workflow.

Claim a phase

conductor/bin/sprint.sh claim <phase> [--agent <name>]

Atomic claim using mkdir (POSIX atomic on same filesystem). Fails if:

• Phase is already claimed by another agent
• Dependencies are not complete
• Sprint doesn't exist

Complete a phase

conductor/bin/sprint.sh complete <phase> [--artifact <path>]

Marks phase done. Links the artifact if provided. Unlocks downstream phases.

Check status

conductor/bin/sprint.sh status

Outputs the current sprint state — which phases are pending, claimed, done, and by whom.

Abort

conductor/bin/sprint.sh abort [phase]

Release a claim without completing. Use when an agent encounters a blocker.

Next

conductor/bin/sprint.sh next

Print the first phase that is not done, has all dependencies met, and is not currently locked. Empty output means nothing is claimable right now (sprint complete, or all available phases are held by other agents). Use this so an agent that just joined the sprint does not have to parse status to know what to claim.

Unstuck

conductor/bin/sprint.sh unstuck <phase> [--force]

Force-release a lock when its owner PID is dead, without waiting the 1-hour grace period that claim uses for auto-recovery. Refuses if the PID is alive (you should let the owner finish or call abort yourself); pass --force to release a lock with a live PID. Use this when an agent crashed without releasing its lock and you need to keep moving.

Batch (auto-parallelize)

conductor/bin/sprint.sh batch

Reads concurrency metadata from each skill's SKILL.md frontmatter and outputs execution batches. Consecutive read phases with met dependencies are grouped into parallel batches. write phases run one at a time. exclusive phases run alone.

Concurrency classification:

Example output:

{"batch":1,"type":"read","phases":["think"]}
{"batch":2,"type":"read","phases":["plan"]}
{"batch":3,"type":"write","phases":["build"]}
{"batch":4,"type":"read","phases":["review","security","qa"]}
{"batch":5,"type":"exclusive","phases":["ship"]}

Batch 4 shows review, security, and qa running in parallel — they share concurrency: read and all depend only on build.

Filesystem Protocol

.nanostack/conductor/
└── <sprint_id>/
    ├── sprint.json              # Sprint definition + metadata
    ├── think/
    │   ├── lock                 # Contains: {"agent":"claude","claimed_at":"...","pid":1234}
    │   ├── done                 # Exists = phase complete. Contains: {"completed_at":"...","artifact":"..."}
    │   └── artifact.json → ...  # Symlink to the actual artifact in .nanostack/think/
    ├── plan/
    │   ├── lock
    │   └── ...
    ├── review/                  # Can start once build/done exists
    ├── qa/                      # Can start once build/done exists (parallel with review)
    ├── security/                # Can start once build/done exists (parallel with review)
    └── ship/                    # Can start once review/done AND qa/done AND security/done exist

Atomicity

• Claim: mkdir <phase>/lock.d (atomic on POSIX). If it succeeds, you own it. Write agent metadata, then mv lock.d lock.
• Complete: Write done file, remove lock.
• Abort: Remove lock directory.
• No polling: Agents check status only when they need to claim. No background loops.

Security

• Agent isolation: Each agent only writes to phases it has claimed. It reads (never writes) other phases' artifacts.
• Audit trail: Every claim and completion is timestamped with agent identity and PID.
• Stale lock detection: If a lock is older than 1 hour and the PID is dead, it's considered stale and can be reclaimed.
• No credential sharing: Agents use their own credentials. The conductor never touches secrets.
• Artifact integrity: Completed phases are read-only. An agent cannot modify another agent's artifact after completion.