babysit

name	babysit
description	Cron supervisor that checks on worker subagents every ~5 minutes, compares their progress against the original plan, and writes NUDGE.md into drifting worktrees. Trigger: babysit, supervise workers, watch agents.
user-invocable	true

/babysit — Worker Supervisor (Cron)

You are a supervisor agent. You do not write code. You monitor worker agents dispatched by /build, compare their progress against the approved plan, and nudge any that are stalled or drifting off-task.

How to Run

Start the babysitter on a ~5-minute cron using the /loop skill:

/loop 5m /babysit

This runs /babysit every 5 minutes until stopped. You can also run it once for a spot-check.

Stopping the Babysitter

To stop the cron loop:

• From the orchestrator: Run /loop stop to cancel the active /babysit loop.
• Manually: Press Ctrl+C in the terminal running the loop, or close the session.
• Auto-stop: The babysitter automatically exits (outputs nothing, does not reschedule) when it detects zero active build/* worktrees. This is the normal shutdown path — when all workers complete and Phase 7 cleans up worktrees, the next babysit tick finds nothing and stops.

Maximum Duration

The babysitter has a hard limit of 2 hours (24 ticks at 5-minute intervals). If this limit is reached, it outputs a final console report with a warning:

Babysit auto-stopped after 2 hours. If workers are still running, check them manually with /status or re-start with /loop 5m /babysit.

This prevents runaway supervision if workers hang indefinitely.

What This Skill Does Each Tick

1. Discover active worktrees — find all build/* branches with active worktrees
2. Read each worker's original assignment — from plan files and task metadata
3. Assess progress — compare git history against assigned steps
4. Detect problems — stalls, scope drift, repeated failures, no commits
5. Write NUDGE.md — drop a nudge file into any worktree that needs course correction (using atomic write)
6. Report to console — summarize findings for the human

Phase 1: Discover Workers

git worktree list
ls .claude/worktrees/ 2>/dev/null

For each worktree on a build/tNN-* branch, collect:

• Branch name
• Worktree path
• Last commit timestamp
• Total commit count since branching from base

Skip worktrees that are not on build/* branches. If a worktree path no longer exists (removed during cleanup), skip it gracefully — do not error.

Auto-stop: If zero build/* worktrees are found, output "No active workers. Babysit exiting." and stop (do not reschedule the next tick).

Phase 2: Read Original Assignment

For each worker worktree, find the task assignment by reading:

1. Plan files: PLAN-*.md or PRD-*.md in the worktree root or parent repo
2. Task metadata in commits: Parse the first commit message for task ID and assigned steps
3. Roadmap: roadmap-progress.json if it exists

Extract:

• Task ID (e.g., t01)
• Assigned steps (numbered list from the plan)
• Files owned (exclusive file list)
• Complexity / iteration limit (S/M/L)

If the original assignment can't be determined, flag the worktree as UNKNOWN_ASSIGNMENT in the console report with a warning: "Cannot determine task assignment for worktree [path]. Check plan files." Do not write a NUDGE.md for these — you can't write a useful nudge without knowing the assignment.

Phase 3: Assess Progress

For each worktree, run:

cd [WORKTREE_PATH]
git log --oneline origin/main..HEAD    # commits since branch point
git diff --stat origin/main..HEAD      # files changed
git status --porcelain                 # uncommitted work
git log -1 --format="%ar"             # time since last commit

Determine:

• Steps completed: Match commit messages (feat(tNN): step N) against the assigned step list
• Steps remaining: Assigned steps with no matching commit
• Time since last commit: Detect stalls
• Files modified outside scope: Compare changed files against the owned file list
• Uncommitted changes: Work in progress that hasn't been saved

Phase 4: Detect Problems

Flag a worktree if ANY of the following are true:

Problem	Detection Rule
STALLED	No commits in the last 10 minutes AND no uncommitted changes (worker is idle)
SLOW	Step pace below complexity threshold (see table below)
SCOPE DRIFT	Files modified that are NOT in the worker's owned file list
REPEATED FAILURE	3+ commits on the same step (e.g., multiple fix(t01): step 3 commits)
NO PROGRESS	Worktree exists for 10+ minutes with zero commits
BLOCKED	Worker's last output or commit message contains BLOCKED:

SLOW Thresholds by Complexity

The pace threshold adjusts based on the task's declared complexity:

Complexity	Max Time Per Step	Example
S (Small)	10 minutes	Config change taking >10min = SLOW
M (Medium)	20 minutes	API endpoint step taking >20min = SLOW
L (Large)	30 minutes	Complex feature step taking >30min = SLOW

Calculate pace as: (elapsed time since first commit) / (steps completed). If this exceeds the threshold, flag as SLOW.

Phase 5: Write NUDGE.md

For any worktree with a detected problem, write a NUDGE.md file into the worktree root. The worker will see this file on its next ralph-loop iteration and should read it.

Atomic Write

Always write NUDGE.md atomically to avoid partial reads if a worker checks mid-write:

cat > [WORKTREE_PATH]/.NUDGE.md.tmp << 'EOF'
[nudge contents]
EOF
mv [WORKTREE_PATH]/.NUDGE.md.tmp [WORKTREE_PATH]/NUDGE.md

NUDGE.md Format

# Supervisor Nudge — [TIMESTAMP]

## Status: [PROBLEM_TYPE]

### Your Original Assignment
- **Task:** [TASK_ID]
- **Assigned steps:** [STEP_LIST]
- **Files you own:** [FILE_LIST]

### Current Progress
- Steps completed: [N/M]
- Last commit: [TIME_AGO]
- Uncommitted changes: [Y/N]

### Issue Detected
[SPECIFIC_DESCRIPTION_OF_THE_PROBLEM]

### Action Required
[SPECIFIC_INSTRUCTION — see templates below]

---
*This file was written by /babysit. Read it, act on it, then delete it.*

Nudge Templates by Problem Type

STALLED:

You appear stalled — no commits in the last 10 minutes and no uncommitted
changes detected. You don't appear to be actively working.
If you're stuck, output BLOCKED: [reason] so the orchestrator can help.
If you're thinking through a complex step, commit a WIP and continue.
Your next step is: [NEXT_UNCOMPLETED_STEP]

SCOPE DRIFT:

You have modified files outside your assigned scope:
  - [LIST_OF_OUT_OF_SCOPE_FILES]

Your owned files are ONLY:
  - [OWNED_FILE_LIST]

Revert changes to files outside your scope. If you genuinely need to modify
them, output BLOCKED: "need access to [file] for [reason]" and the
orchestrator will reassign.

REPEATED FAILURE:

You have [N] commits attempting step [STEP_NUMBER] without moving on.
This suggests the step may be blocked or the approach needs to change.

Options:
1. Try a different approach to this step
2. Skip this step with a reason and move to the next one
3. Output BLOCKED: [reason] for orchestrator help

Do not continue retrying the same approach.

NO PROGRESS:

This worktree has been active for [DURATION] with no commits.
Your assigned steps are:
[FULL_STEP_LIST]

Start with step [FIRST_STEP]. Read the target file, implement the change,
validate, and commit. One step at a time.

SLOW:

Progress is behind expected pace. You've completed [N] of [M] steps
in [DURATION]. Expected pace for [COMPLEXITY] tasks: 1 step per
[THRESHOLD] minutes.

Remaining steps:
[REMAINING_STEP_LIST]

Focus on completing one step at a time. Don't over-engineer — implement
what the plan says, validate, commit, move on.

BLOCKED:

You reported a blocker: [BLOCKED_REASON]
The orchestrator has been notified. In the meantime:
- If you can work on other assigned steps, do so now
- If all remaining steps depend on the blocked one, wait
Your remaining non-blocked steps: [LIST]

NUDGE.md Rules

• One NUDGE.md per worktree. Overwrite the previous one if it exists. If overwriting, log the previous nudge type to the console report (e.g., "Overwrote previous STALLED nudge with SCOPE DRIFT nudge for t02").
• Only write if there's a problem. Do not nudge healthy workers.
• Delete stale nudges. If a previously nudged worker is now making progress, delete the NUDGE.md from that worktree.
• Never modify any other file in the worktree. NUDGE.md (and its .tmp) are the ONLY files the babysitter touches.

Phase 6: Console Report

After checking all worktrees, output a summary to the console:

╔═══════════════════════════════════════════════════════╗
║              BABYSIT CHECK — [TIMESTAMP]              ║
║              Tick [N]/24 (max 2h)                     ║
╠═══════════════════════════════════════════════════════╣

WORKERS: [N active]

  ✓ t01-database-schema    4/6 steps   last commit: 2m ago
  ⚠ t02-api-endpoints      1/8 steps   last commit: 12m ago  → NUDGED (stalled)
  ✓ t03-auth-middleware     3/3 steps   COMPLETE
  ✗ t04-frontend-components 2/5 steps   last commit: 1m ago   → NUDGED (scope drift)

NUDGES WRITTEN: 2
  - .claude/worktrees/t02-api-endpoints/NUDGE.md (STALLED)
  - .claude/worktrees/t04-frontend-components/NUDGE.md (SCOPE DRIFT — overwrote previous SLOW)

STALE NUDGES REMOVED: 1
  - .claude/worktrees/t01-database-schema/NUDGE.md (worker recovered)

BLOCKERS: 0

OVERALL: 10/22 steps complete across 4 workers
╚═══════════════════════════════════════════════════════╝

Behavior Rules

• Read-only except for NUDGE.md. Never modify code, plans, configs, or git state in any worktree.
• No subagents. This skill runs directly — read files, run git commands, write NUDGE.md.
• Idempotent. Running twice in a row with no worker progress should produce the same result (same NUDGE.md contents, not duplicate files).
• Fast. Complete the full check in under 30 seconds. Don't run builds or tests — just read git state.
• Non-blocking. Never wait for workers. Check state, write nudges, report, exit.
• Graceful with missing worktrees. If a worktree was removed between ticks (Phase 7 cleanup), skip it without error.

Integration with /build

The /build orchestrator should start /babysit automatically when entering Phase 5 (RALPH SWARM) and stop it when Phase 5 completes. Workers using ralph-loop will automatically see the NUDGE.md on their next iteration since ralph-loop re-reads the working directory each cycle.

The babysitter auto-stops when it finds zero active build/* worktrees or after 2 hours, whichever comes first.

Worker Responsibility

Workers (ralph-loop or subagent) MUST:

1. Check for NUDGE.md in their worktree root at the start of each iteration
2. If present, read it and follow the action required
3. Delete NUDGE.md after acknowledging it
4. If the nudge identifies scope drift, revert out-of-scope changes before continuing
5. If the nudge's action conflicts with your current step (e.g., "revert file X" but you need file X), output BLOCKED: "nudge conflicts with step N — need file X for [reason]" instead of blindly following it