sprint-overseer

name	sprint-overseer
description	Periodically inspect a sprint manager and worker sessions against a sprint spec, classify progress, nudge only for real stalls, and always append a checkpoint log beside the sprint file.
metadata	{"owner":"interlateral","version":"1.0","weight":"light"}
compatibility	Any explicitly selected agent running alongside a sprint lead. Default to Claude Code + Codex; Gemini and Antigravity are opt-in only when the human explicitly selects them.

Sprint Overseer

Purpose

You are a sprint overseer. Your job is to periodically check on another agent running a sprint, determine whether the sprint is on track, and log that judgment.

You do not execute the sprint yourself. You observe, classify, and intervene only when needed.

Default roster: use Claude Code and Codex overseers. Do not assign Gemini CLI, Antigravity CLI, or Antigravity Desktop as overseers unless the human prompt explicitly names that peer.

Inputs

All inputs come from the prompt.

Required:

• sprint_file: absolute path to the sprint specification file

Optional:

• manager_session: tmux session name for the sprint lead. Default: ia-claude
• poll_interval: human-readable cadence for the mechanical wake-ups. Default: every 5 minutes
• done_marker: text that signals team completion in the team evidence file. Default: STATUS: DONE
• sprint_team_pattern: tmux session glob for sprint workers. Default: sprint*
• closeout_file: explicit absolute path to the team-completion artifact. Use this when the sprint does not use the default {sprint_dir}/evidence/sprint_closeout.md.
• stop_file: explicit absolute path to the overseer-completion artifact. Use this when the timer should continue after team completion until the overseers write their own final closeout.
• stop_marker: text that signals overseer completion in stop_file. Default: same as done_marker

Derived Paths

Derive these from sprint_file every time:

• sprint directory: parent of sprint_file
• overseer log: {sprint_dir}/sprint-overseer-log.md
• evidence directory: {sprint_dir}/evidence/
• team evidence file: {closeout_file} if provided, otherwise {sprint_dir}/evidence/sprint_closeout.md
• overseer stop file: {stop_file} if provided, otherwise the same path as the team evidence file

Do not hardcode repo-specific paths.

First Activation

1. Read the sprint file fully enough to understand phases, gates, and completion criteria.
2. Create the overseer log if it does not exist with this header:

# Sprint Overseer Log

Sprint file: {sprint_file}
Manager session: {manager_session}
Started: {timestamp}
Team done marker: {done_marker}
Overseer stop marker: {stop_marker}

3. Append the first checkpoint entry.

Periodic Check-In

On every wake-up, perform these steps:

1. Re-read the sprint file to identify the expected current phase and gates.
2. Inspect the manager terminal (manager_session).
3. Inspect worker tmux sessions matching sprint_team_pattern.
4. Inspect evidence progress in {sprint_dir}/evidence/.
5. Classify the sprint state:
   • on-track: active work or clear progress
   • off-track: active work, but on the wrong thing or looping
   • idle/stalled: no material gate-evidence progress for 20+ minutes across manager, workers, and evidence
   • team-complete-overseer-open: the sprint team appears done, but the overseers still owe final health/evidence review, peer coordination, or final closeout
6. Act:
   • on-track: log only
   • off-track: log and send a specific nudge to the manager
   • idle/stalled: log and send a wake-up nudge to the manager
   • team-complete-overseer-open: stop nudging the team, coordinate Joint ACK with the peer overseer, and write the overseer closeout if the final review is green

When the team appears substantively complete but has not marked done_marker, the overseers may use the Override Authority below to break deadlock.

Stall, False-Green, And Spiral Controls

Default stall threshold: 20 minutes without new material gate-evidence progress. Terminal activity alone is not progress. New material progress means a new or updated expected evidence artifact, a gate packet, a review/breaker/verifier result, a verified command result, or a concrete controller decision tied to the sprint spec.

Calibration override rule: any shorter, longer, or gate-specific threshold must be explicit in the sprint spec or launch packet, reviewed, and pinned before launch/use. Gatekeepers and overseers must not invent thresholds at decision time. If no reviewed pinned override exists, use the 20-minute default.

False-green rule: do not classify on-track from chatty terminal output, repeated status text, unchanged timestamps, stale evidence, missing done/stop markers, or an ACK-only heartbeat. If the manager is active but evidence does not advance before the stall threshold, classify idle/stalled or off-track and nudge with the missing artifact or decision.

Retry-loop rule: repeated attempts against the same failure are progress only when the retry packet or log states the prior failure, what changed, and remaining budget. Otherwise classify as off-track before it becomes a stall.

Review-spiral threshold: default 3 reviewer/breaker rounds without a class-1 finding. After the third round, require materiality triage: class 1 and 2 findings block, class 3 may be deferred with rationale, and class 4 must not block. Escalate to the controller for stop/patch/defer/accept disposition when the team cannot close the loop.

Local Classification Logic Check

When overseer stall, false-green, retry-loop, or review-spiral classification thresholds are changed or calibrated, scripts/watcher-control-sim.js all can exercise local classification examples. It does not validate a live overseer topology, timer, manager session, evidence directory, heartbeat loop, injection path, or stop condition, and it is not required for ordinary short tasks.

Nudge Rules

• Quiet output is not automatically idleness.
• Check worker sessions before deciding the manager is stalled.
• Nudge only for confirmed stalls or clear drift.
• Nudge the lead only. Workers do not receive overseer nudges.
• Be specific: say what you observed and what the sprint expects next.

Use the repo comms helpers when available:

node interlateral_dna/cc.js send "message"
node interlateral_dna/codex.js send "message"
node interlateral_dna/gemini.js send "message"   # only if Gemini was explicitly selected
node interlateral_dna/agy.js send "message"      # only if Antigravity CLI was explicitly selected

Lead Self-Nudge

If the overseer is also the sprint lead, write the checkpoint first, then send the nudge to your own active session or treat the next turn as the nudge response.

The self-nudge must still be concrete:

• what is stalled or drifting
• what the sprint expects next
• what artifact or command sequence should be updated

Do not use self-nudge authority to expand scope or skip evidence.

Cadence Discipline

Default polling cadence is 5 minutes. Acceptable human-configured range is 3 to 5 minutes unless the sprint explicitly says otherwise.

Do not poll more often than every 3 minutes for normal oversight. Faster polling increases duplicate nudges and false stall classification.

Every wake-up writes a checkpoint entry with:

• Classification
• Action taken

Even when no action is taken, record Action taken: none.

Stop Condition

Stop when either:

• the configured overseer stop file exists and contains stop_marker
• the human explicitly redirects or pauses the overseer

When the team evidence file reaches done_marker but the overseer stop file does not yet contain stop_marker, continue running. At that point your job changes from team progress monitoring to final overseer closeout and Joint ACK coordination.

When the team evidence file has not reached done_marker, but the overseers invoke Override Authority, treat that as functionally equivalent to team completion for the purpose of final Joint ACK and overseer closeout. This may happen either through coordinated use by both overseers or through the lone-overseer fallback described below.

When no heartbeat file is present (empty-file tick between heartbeats), write a short-form tick entry to the log anyway so the log proves the overseer is alive between heartbeats. A gap in the log means the overseer was dead — not that nothing happened.

When the stop condition is met, append a final checkpoint entry.

Overseer Override Authority

If the team has not marked done_marker in the team evidence file but the overseers judge the sprint objectives met — based on the declared health checks, acceptance criteria, regression surfaces, and live endpoint verification — the overseers are authorized to:

1. Write the team's done_marker into the team evidence file themselves, with a note: OVERRIDE-BY-OVERSEERS: <reason>.
2. Immediately switch to Joint Overseer ACK and closeout.

This authority exists to prevent a single stuck or pedantic team agent from silently blocking the entire overseer completion path. The overseers have final say on whether a sprint is done, not the team.

When to use: Prefer coordinated use by both overseers after they independently verify that the sprint's acceptance criteria are met via live checks. If only one overseer is active, that overseer may invoke the authority only after two consecutive check-ins with no team progress and a complete live verification. Never use to skip genuinely incomplete work.

Checkpoint Format

Append every check-in to {sprint_dir}/sprint-overseer-log.md:

## {timestamp} — Checkpoint {N}

**Sprint phase:** {phase}
**Manager ({manager_session}):** {active / waiting / idle}
**Worker sessions:** {sessions and status}
**Evidence progress:** {latest artifacts and markers}
**Classification:** {on-track / off-track / idle-stalled / team-complete-overseer-open}
**Action taken:** {none / nudge sent / escalation noted}

Every wake-up writes a log entry — including empty-file ticks where no heartbeat is pending. Use a one-paragraph short form for those so the log proves the overseer is alive between heartbeats. Example: "Cron tick — no heartbeat pending. Team status: on-track, LEAD actively coding. No action."

Keep entries concise and scannable.

When To Use The Timer

The mechanical overseer timer is optional sprint scaffolding, not a universal requirement. Use it when the sprint is long-running, unattended, multi-agent, or high-risk enough that silent stalls matter. Skip it for ordinary short tasks where a simple closeout is enough.

When a sprint chooses the timer, start it by the human operator or overseer boot script BEFORE the team boot sequence begins. The timer should show at least one "Timer alive" entry in its log before the first team prompt is injected.

Startup order:

1. Start the overseer timer(s)
2. Verify timer log shows "PREFLIGHT PASSED" and "Timer alive"
3. THEN boot the team sessions
4. THEN inject the lead prompt

For overnight, high-risk, or complex autonomous sprints, do not replace the timer with vague manual supervision unless the sprint spec or human explicitly accepts that risk. Agent sessions can go idle and nothing will wake them.

Before any overnight sprint or new overseer topology, run scripts/heartbeat_validation_harness.sh first to prove visible injection and HEARTBEAT_ID acknowledgment on the real target CLI session.

The timer runs the heartbeat acknowledgment protocol: Each heartbeat carries a unique HEARTBEAT_ID. The overseer must echo that ID in their checkpoint log entry. A cycle counts as successful only when the ID appears in the overseer log. If 3 consecutive heartbeats receive no acknowledgment, the timer logs a WARNING to comms.md for escalation.

Timer Exit Contract

When the mechanical timer is used, the sprint spec or launch record must capture:

• the --closeout-file path;
• the exact --done-marker string;
• the --stop-file path;
• the exact --stop-marker string;
• who is responsible for writing each marker;
• how the team verifies the timer has stopped.

Sprint closeout is not complete until the exact done_marker appears in the team evidence file, the exact stop_marker appears in the overseer stop file, and a process or final-log check confirms the timer is no longer running for that sprint. If those literal strings are not written, the timer will keep polling even when the sprint is substantively done.

Recommended Mechanical Wake-Up

The timer supports two delivery paths depending on the overseer's CLI:

Codex CLI overseers — tmux injection (default)

scripts/sprint_overseer.sh /abs/path/to/sprint.md \
  --manager ia-claude \
  --overseer ia-codex \
  --closeout-file /abs/path/to/project/docs/evidence/sprint3_proof.md \
  --done-marker "STATUS: DONE" \
  --stop-file /abs/path/to/project/docs/evidence/sprint3_overseer_closeout.md \
  --stop-marker "STATUS: OVERSEER-DONE" \
  --interval 300

This uses the existing Escape-then-Enter tmux injection, which is proven reliable for Codex (9/9 ACKs in validation).

Claude Code CLI overseers — native /loop + file polling

Claude Code v2.1.101+ does not reliably process tmux-injected prompts as fresh turns when idle. The validated workaround uses /loop inside the TUI with a shared file:

Timer side (adds --native-file):

scripts/sprint_overseer.sh /abs/path/to/sprint.md \
  --manager ia-codex \
  --overseer ia-claude \
  --native-file /path/to/workdir/sprint_heartbeat_command.txt \
  --closeout-file /abs/path/to/project/docs/evidence/sprint3_proof.md \
  --done-marker "STATUS: DONE" \
  --stop-file /abs/path/to/project/docs/evidence/sprint3_overseer_closeout.md \
  --stop-marker "STATUS: OVERSEER-DONE" \
  --interval 300

Claude side (type into TUI):

/loop 60s Read /path/to/workdir/sprint_heartbeat_command.txt — if the file
exists and has content, treat it as a heartbeat prompt: follow the instructions
in the file, write HEARTBEAT_ID + ACK to the overseer log, then DELETE the file.
If the file is missing or empty, output: heartbeat check — no pending command

Interval guidance: /loop interval should be ≤ half the timer interval. For --interval 300, use /loop 60s to /loop 120s. For validation (--interval 30), use /loop 15s (rounded to 1m by cron minimum).

File detection: Read-and-delete. The loop reads the file, acts on it, deletes it. Next cycle sees no file = no action. No mtime tracking or state between iterations.

Note: Claude's TUI injection path (agent_send_long) is preserved in sprint_overseer.sh for future Channels integration but is not used for heartbeats when --native-file is set. /loop is session-scoped — if the Claude session crashes, /loop must be re-registered as part of overseer startup.

Common to both paths

The timer runs a launch preflight check (verifies session exists, pane is CLI, stop marker absent) before entering the main loop. It logs "Timer alive" each cycle independent of injection success, making stale timers detectable. The timer only wakes the overseer — you still do the actual review and logging.

Example Prompt

Use the sprint-overseer skill.
Sprint file: /Users/dazza/repos/project/docs/sprint.md
Manager session: ia-claude
Sprint team pattern: s3-*
Poll interval: every 5 minutes
Closeout file: /Users/dazza/repos/project/docs/evidence/sprint3_proof.md
Done marker: STATUS: DONE
Stop file: /Users/dazza/repos/project/docs/evidence/sprint3_overseer_closeout.md
Stop marker: STATUS: OVERSEER-DONE

Safety

• Do not execute sprint work yourself.
• Do not edit the sprint spec.
• Do not edit team evidence files except:
  1. when the sprint explicitly designates an overseer closeout artifact as yours to write, or
  2. when both overseers invoke Override Authority and write the team's done_marker with an OVERRIDE-BY-OVERSEERS: note.
• Only write the overseer log, the designated overseer closeout artifact, and the narrow override note described above.
• If you cannot determine status confidently, say so in the log.

Final Status Format

SKILL: sprint-overseer
STATUS: SPRINT COMPLETE
CHECKPOINTS: {N}
NUDGES SENT: {count}
SPRINT FILE: {path}
LOG FILE: {path}