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.

Usage Patterns

Single developer, sequential (most common)

One agent, one sprint. Same as today — the conductor just adds visibility:

You:  /conductor start
You:  /think → /nano → build → /review → /security → /qa → /ship
      [each phase auto-claims and auto-completes]

Single developer, parallel review

One build, then fan out review + qa + security in parallel:

Terminal 1:  /conductor start
Terminal 1:  /think → /nano → build
Terminal 1:  /review

Terminal 2:  /qa              # claims qa (build.done exists)

Terminal 3:  /security        # claims security (build.done exists)

Terminal 1:  /ship            # waits until review + qa + security all done

Team, distributed

Multiple developers, each running their own agent:

Dev A (claude):   /think → /nano
Dev B (codex):    build (claims after plan.done)
Dev A (claude):   /review (claims after build.done)
Dev C (opencode):     /security (claims after build.done, parallel with review)
Dev A (claude):   /ship (claims after review.done + security.done)

Phase Protocol

Every phase transition follows this protocol. The agent executes these steps at every boundary — they are mandatory, not optional.

Pre-phase (before starting a new phase)

1. Check for existing session: bin/session.sh resume
   • If resumable and user confirms, restore context via bin/restore-context.sh
   • If no session exists, create one: bin/session.sh init <type>
2. Validate upstream dependencies: bin/validate-dependencies.sh <phase>
   • If MISSING, stop and report which dependencies are not met
3. Update session: bin/session.sh phase-start <phase>

Post-phase (after completing a phase)

1. Save artifact with context_checkpoint via bin/save-artifact.sh
   • The context_checkpoint must include: summary, key_files, decisions_made, open_questions
   • No artifact is saved without context_checkpoint populated
2. Update session: bin/session.sh phase-complete <phase>
3. If context is running low, the agent reads the checkpoint summary instead of replaying full conversation

Session resume (on crash recovery)

1. bin/session.sh resume detects the last session state
2. bin/restore-context.sh reads all completed phase checkpoints
3. Skip completed phases, restart the in-progress phase from scratch

Telemetry finalize

Before returning control:

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

Pass abort or error instead of success if conductor did not complete normally.

Gotchas

• The conductor is optional. Single-agent sprints work without it. The conductor adds value only when multiple agents or sessions are involved.
• Build is manual. The conductor doesn't execute code — it tracks who is doing what. The human or agent does the actual work.
• Don't over-parallelize. review + qa + security in parallel is the sweet spot. Parallelizing think + plan is pointless — they're sequential by nature.
• Stale locks happen. If an agent crashes mid-phase, the lock stays. After 1 hour with a dead PID, any agent can reclaim.
• The sprint is project-scoped. One sprint per project at a time. Starting a new sprint archives the previous one.