RonanCodes/skills/night-shift

/ro:night-shift

The "swarm the factory" trigger. Run inside any repo with a gh remote and at least one ready-for-agent slice (or a draft PRD inbox if you want grill-first scope).

This is the shortest path between "I'm going to bed" and "the swarm is working", BUT the opening grill (US-0) makes "AFK" mean something explicit. Three AFK modes look identical from the couch and very different in the morning. Pick on purpose.

Part of the local factory

/ro:night-shift is the AFK entrypoint to the local factory — the family of agent-loop skills that run autonomously on Ronan's machine. Siblings: /ro:ralph, /ro:planner-worker (alias /ro:swarm), /ro:matt-pocock-coding-workflow, /ro:day-shift. They share artefact shape (worker-scratch + harvested patterns + per-session aggregate), gitignore rules, and PR conventions. See /ro:ralph § "Run artefacts (the canonical shape)" for the canonical reference.

The companion is the remote factory — the Factory app (tracked separately) that runs equivalent loops as a cloud service. Story formats and PR conventions are compatible.

What it does at a glance

1. Pre-flight + opening grill (US-0). Probes the backlog and prints a plain-English summary — how many slices are ready to drain, how many drafts/parents need grilling/slicing first, and how many issues are blocked on a human (with the one-line reason each is stuck). Then asks: grill now, or drain what's ready? Plus follow-up questions on looping, follow-ups, and caps. Skipped by --yes or --no-grill plus the relevant flag overrides.
2. Rank the queue (US-1). 4-signal weighted score: age, priority label, size/scope, unblocks-others count. Top of the ranked queue runs first.
3. Build the dep + file-area graph (US-2). Hybrid static (read slice bodies for declared paths) plus a probe-scout fallback if the first wave hits cross-worker merge conflicts.
4. Dispatch a wave (US-3). Up to --workers N parallel agents in git worktrees, no two on overlapping file-areas, no two violating ## Blocked by deps. Calls /ro:planner-worker --skip-grill --queue <ranked-file>.
5. Wait for the wave. All workers either merge clean or escalate. Merger is Opus 4.7.
6. Re-rank and re-dispatch (US-4). If the queue still has unblocked work, run another wave. Loop until terminator.
7. Queue refill (US-5). When the ready queue empties, refill per scope: auto-slice the next parent PRD via a planner sub-agent, grill a prd:draft, or stop.
8. Workers may open follow-up issues (US-6). Out-of-scope TODOs surfaced mid-implementation become new ready-for-agent issues labelled nightshift-followup so they get triaged the next morning, not dropped.
9. Nightsheet (US-7). End-of-session aggregate: a GH issue labelled nightsheet summarising what shipped, what's open, what's blocked, plus a /ro:completion-report HTML on disk.
10. Retro + morning briefing (Phase 7, see below). /ro:night-shift-retro runs after the swarm exits, captures matrix-row failures and failure modes per slice, files SYSTEM action items against ronan-skills / factory, files PROJECT action items against the current repo as ready-for-human, writes a markdown + JSON artefact under .nightshift/retros/<date>-<run-id>.{md,json}, and renders a morning briefing HTML under .nightshift/briefings/<date>.html. Pushover and Telegram fire AFTER the retro and deep-link to the briefing HTML (the "wake-up-to-coffee" artefact).

US-0: Opening grill — what does AFK mean tonight?

Unless --yes, --no-grill, or all four scope flags are passed explicitly, the skill opens with four AskUserQuestion gates. Each has a project-aware recommendation derived from the current queue state.

Self-grill mode (--self-grill) — AFK with no one to answer

When the user is genuinely AFK ("I'm going AFK, continue with everything"), there's no one to answer the US-0 gates or any mid-run clarifying question. Don't stall and don't silently guess: self-grill. For every decision you would otherwise put to the user, pick the recommended/safest option yourself, record it as an assumption with rationale, proceed, and surface the whole list in the morning briefing so the user can confirm or correct over coffee.

Triggered by --self-grill, or implied whenever the run is AFK and no interactive answers are available (e.g. invoked with "I'm AFK" / "continue with all tasks" and no flags). It does NOT skip the thinking — it makes the thinking auditable.

Behaviour:

1. US-0 gates → auto-answer each via its existing recommendation logic (Question 1 scope, 2 loop, 3 follow-ups, 4 caps). Log each: {decision, chosen, rationale, reversible}.
2. Mid-run decisions (ambiguous slice scope, a draft that needs grilling, a fork in an implementation) → instead of escalating to blocked-on-human, self-grill it: write the clarifying questions you'd have asked, answer them with the safest reversible default, log the Q+A+assumption, and proceed. Only escalate to blocked-on-human when the decision is genuinely irreversible or needs a credential/access you don't have (deploys, paid actions, destructive ops, external auth).
3. Assumptions log → append every entry to <repo>/.nightshift/assumptions.md (gitignored) as a table row. This file is the source for the briefing's "Assumptions" section.

Assumptions-log row shape:

| # | Decision | I chose | Rationale | Reversible? |

Bias: prefer the reversible option, the smaller scope, and the path that leaves a clean PR the user can revert. When two options are equally safe, pick the one that unblocks the most other work. An assumption that turns out wrong should cost one revert, never a data-loss or a surprise spend.

CLI: --self-grill (force on), --no-self-grill (force the old behaviour: escalate instead of assuming). Default: on when AFK, off when interactive.

Probe up front (before asking anything):

# Canonical query (per ~/Dev/ronan-skills/canon/labels.md): kind:slice + ready-for-agent.
# This is the ONLY set night-shift workers dispatch against. needs-grilling is day-shift's job.
gh issue list --label kind:slice --label ready-for-agent --state open --search "-label:prd:draft -label:needs-grilling" --json number,body,labels --limit 200 > /tmp/nightshift-ready.json
# needs-grilling is the canonical equivalent of the legacy prd:draft label; both are
# excluded from the ready queue. The drafts probe picks up either label for the
# grill-first / full-drain scope decisions.
gh issue list --search "is:open is:issue label:needs-grilling,prd:draft" --json number,title,updatedAt,labels --limit 50 > /tmp/nightshift-drafts.json
# Parents are kind:prd; useful for the auto-slice scope.
gh issue list --label kind:prd --state open --json number,title,labels --limit 50 > /tmp/nightshift-parents.json
jq 'length' /tmp/nightshift-ready.json     # N_slices
jq 'length' /tmp/nightshift-parents.json   # N_parents
jq 'length' /tmp/nightshift-drafts.json    # N_drafts
# Blocked: needs a human action / external unblock. Workers CANNOT touch these — surface,
# never silently swallow.
gh issue list --label blocked-on-human --state open --json number,title,body,labels --limit 50 > /tmp/nightshift-blocked.json
jq 'length' /tmp/nightshift-blocked.json   # N_blocked

Pre-flight summary — ALWAYS print this in chat BEFORE Question 1. It's the most useful thing the user reads at kickoff: the actual shape of their backlog right now. Make it scannable.

🌙 Night-shift pre-flight for <repo>:

  ✅ Ready to drain now:            <N_slices> slices
       #282 Connections loading skeleton
       #283 Topbar avatar skeleton
       #268 E2E install verification
  ✏️  Need grilling/slicing first:  <N_drafts> drafts + <N_parents> parent PRDs
       #174 [PRD] Admin dashboard + RBAC
       #209 [PRD] Onboarding context capture
       …
  🚫 Blocked on you (workers can't touch): <N_blocked>
       #199 Flip Clerk Dashboard to Waitlist mode  ← gates the whole waitlist chain
       #208 GitHub Actions billing
       …

For each blocked item, pull the one-line "what's needed" from the issue body (## Blocked by section or first paragraph) so the user sees WHY it's stuck, not just that it is.

Question 1 — Grill now, or drain what's ready?

Phrase it with the live counts, exactly the decision the user faces:

"You've got <N_slices> slices ready to go. <N_drafts + N_parents> need a grilling/slicing session before the swarm can touch them, and <N_blocked> are blocked on you. Want to run a grilling session now to open up the blocked/unsliced work, or kick off the swarm on the ready ones and leave the rest for a /ro:day-shift?"

| Option | What it does | When recommended | |---|---|---| | ready-only | Drain only the <N_slices> existing ready-for-agent slices. Stop when empty. No grilling, no slicing. | Default when N_slices >= 1. The "I'm going to bed, just ship what's ready" path. | | grill-first | Run a grilling session now: grill each draft into a Pocock 7-section parent, slice each parent, THEN drain. | When the user wants the blocked/unsliced work opened up tonight and is willing to answer questions before sleeping. Adds 5-15 min per draft. | | auto-slice | Slice open parent PRDs (## Problem Statement body) into child slices automatically — no per-question grilling — then drain. | When N_parents >= 1, N_drafts == 0, and the parents are well-specified enough to slice without grilling. | | full-drain | Everything: grill drafts → slice parents → drain. Closes the most issues. | "I want to see all issues closed tomorrow" or N_drafts + N_parents >= 2. |

Recommendation logic for the AskUserQuestion default:

• N_slices >= 3 and N_drafts + N_parents == 0 → recommend ready-only (clean drain).
• N_slices == 0 and N_drafts + N_parents >= 1 → recommend grill-first (nothing to drain without grilling first; say so plainly).
• otherwise → recommend ready-only and note the unsliced count so the user can opt up to grill-first/full-drain.

If N_blocked > 0, ALWAYS name the blocked items in the question body — the user may want to resolve one on the spot (e.g. the 30-second Clerk dashboard toggle) before going AFK, which unblocks a whole chain.

CLI: --scope ready-only|grill-first|auto-slice|full-drain.

Question 2 — Loop until empty, or single wave?

"Drain in one wave, drain the whole queue, or loop indefinitely?"

| Option | What it does | When recommended | |---|---|---| | single-wave | Dispatch exactly one wave of workers (up to --workers N). Exit when wave returns. | Sanity-check runs, lunch-break swarms. | | drain | Multiple waves until ready queue is empty. Default. | The night-shift default. | | indefinite | Drain + refill (per scope) + drain + refill until --max-waves or --max-runtime cap. | "Wake up to an empty backlog" + full-drain scope. |

CLI: --max-waves N (default 20 for indefinite, 6 for drain). --max-runtime (default 8h).

Question 3 — Workers permitted to open follow-up issues?

"If workers hit an out-of-scope TODO mid-implementation, should they open a follow-up GH issue?"

| Option | What it does | When recommended | |---|---|---| | yes | Workers may gh issue create --label ready-for-agent --label nightshift-followup for adjacent work they find. Listed in the morning nightsheet. | Default. Backlog grows by maybe 0-5 issues per wave; you triage in the morning. | | no | Workers stay strictly on-task; out-of-scope TODOs are dropped on the floor. | When you want a quiet morning queue. |

CLI: --no-followups to suppress.

Question 4 — Caps?

"Workers cap and max runtime?"

| Field | Default | Notes | |---|---|---| | --workers | min(5, cores - 2) | Default 5 on a fresh usage window. Scale DOWN to 2-3 when sharing the window with a long interactive session (2026-06-11: 5 workers + a heavy main session exhausted the cap mid-run). Scale UP via --workers N or .swarm.json. Hard ceiling 10 without --unsafe-many. | | --max-runtime | 8h | Wall-clock cap, the swarm exits cleanly at the cap regardless of queue state. | | --max-waves | 6 for drain, 20 for indefinite | Belt-and-braces stop. |

Each answer is echoed back as the equivalent CLI flag. The full set of flags forms a one-line repeatable invocation for next time.

--yes / --no-grill shortcut

Skips US-0 entirely. Uses defaults: --scope ready-only, --workers 5, --max-waves 6, --max-runtime 8h, follow-ups ON. This is the original zero-config behaviour; explicit now so users opt in. Differs from --self-grill: --yes takes the defaults silently, --self-grill takes the recommended answer per gate AND logs each as an auditable assumption for the morning briefing. AFK runs should prefer --self-grill so the morning briefing explains every call that was made.

Filter / scope: prd:draft is NEVER auto-picked

prd:draft issues are NEVER picked up as work by this skill UNLESS --scope grill-first or --scope full-drain is selected. In those scopes drafts are picked up by the grill phase, not the worker dispatch — they get rewritten into Pocock parents BEFORE any worker sees them.

Defence in depth on the ready-queue query:

1. gh issue list --label ready-for-agent --search "-label:prd:draft" ... (server-side exclude).
2. Post-filter the JSON: drop any labels[].name == "prd:draft".
3. Only consider issues whose body opens with ## Parent\n\n#<N> as slices (parents have ## Problem Statement).

US-1: Rank the queue

4-signal weighted score. Higher = run first. Weights are tuneable via .swarm.json ranking.weights but ship as:

ranking:
  weights:
    age: 1.0              # days since open, normalised 0..1 across queue
    priority: 2.0         # P0=1.0, P1=0.66, P2=0.33, unset=0
    size: 1.5             # smaller first: S=1.0, M=0.5, L=0.0 (parsed from `estimate:` body field)
    unblocks: 2.5         # count of OTHER open issues whose `## Blocked by` references this issue, normalised

score = sum(weight[i] * normalised_signal[i]). Ties broken by issue number (lower first).

How signals are read:

• age — gh createdAt minus now.
• priority — labels starting with priority: or matching P[0-9]. Repos without priority labels get 0 for all.
• size — slice body's estimate: frontmatter or ## Size section. If missing, infer from line-count of touched-paths declared in the body (1-2 paths = S, 3-6 = M, >6 = L). If body doesn't declare paths, default M.
• unblocks — build the reverse Blocked by graph from all open slices; this signal is the count of issues this one unblocks if closed.

The ranked queue is written to .swarm/ranked-queue.md as a Markdown table with scores, used by all subsequent waves and printed to the user pre-dispatch.

US-2: Build the dep + file-area graph (hybrid conflict detection)

Two graphs, both consulted before any wave:

Dep graph (static, always)

Parse ## Blocked by sections in each slice body. Edges from blocker → blocked. Workers may only dispatch when all blockers are merged.

File-area graph (hybrid: static first wave, probe-scout if conflicts appear)

Static pass (wave 1):

Read each slice body for any of these:

• A ## Files touched or ## Touches section listing paths.
• Inline mentions matching src/..., app/..., apps/..., packages/..., drizzle/..., etc.
• An estimate: frontmatter block with a paths: list.

Build an undirected affinity graph: two slices share an edge if their declared path sets intersect by file or by directory at depth >=2 (e.g. src/routes/settings.tsx and src/routes/settings.test.ts share src/routes/). Two slices sharing an edge are never dispatched in the same wave.

Scout pass (only if wave 1 had cross-worker merge conflicts):

After a wave reports any merger-stage conflict between two workers' branches (i.e. rebase-onto-staging conflict), promote conflict detection: spawn a scout Agent per remaining slice with this prompt:

You are a SCOUT sub-agent for /ro:night-shift.

Slice: <issue body inlined>

Task: read the slice and predict the SET of file paths the implementation will touch.
Output a JSON object on stdout, nothing else:
  {"paths": ["src/routes/...", "src/lib/..."], "confidence": "high|medium|low"}

Rules:
- Do not edit anything.
- Do not run pnpm install or any side-effects.
- Read the codebase enough to be accurate. ~2-3 min budget.
- If you cannot tell, output paths: [] with confidence: low — the planner will assume worst case.

Scout outputs are merged into the file-area graph for waves 2+.

Claims pass (waves 2+, free):

Before dispatching wave N+1, merge the actual touched paths from .swarm/claims.jsonl (the live claims registry workers append to during a wave — see planner-worker US-3c2) for all completed waves into the file-area graph. Actual claims beat predictions: a slice body may declare src/lib/, but if the worker's claims show it also touched src/routes/admin/, the graph carries the real footprint forward. This is how scope drift observed in wave N stops wave N+1 from repeating the collision — at zero scout cost, because the data was written as a side-effect of the work.

CLI: --no-scout disables scout pass entirely (purely static). The claims pass still runs — it's free and reads data that already exists.

US-3: Wave dispatch

kind:research issues are first-class queue citizens. The ranked-queue probe (US-1) includes kind:research alongside kind:slice. Research issues only ever touch docs/research/, so they never conflict on file-areas with code workers and are always safe to fan out (treat as parallel-eligible). When a peeled issue carries kind:research, planner-worker routes it to the research-worker prompt and asserts the research close-the-loop matrix (doc + index + wiki ingest + bidirectional links) instead of tests — see [[canon:research-tasks]] + planner-worker US-3d. A wave can freely mix code slices and research issues.

Step 0 (before wave 1, once per run): the orchestrator seeds the cooperative protocol files in .swarm/ — an empty .swarm/claims.jsonl and a .swarm/shared-learnings.md pre-populated with any known repo quirks (from .ralph/patterns.md, the repo CLAUDE.md, or previous nightsheets: build-order gotchas, flaky tests, migration-journal rules). Every worker prompt in every wave carries the claims + shared-learnings protocol (planner-worker US-3c2); seeding at run start means wave-1 workers arrive to a file with content, not an empty stub.

For each wave:

1. From ranked queue, peel issues in score order that satisfy: deps met AND no file-area overlap with already-peeled-this-wave AND status != stuck. Stop when wave hits --workers N.
2. Dispatch via /ro:planner-worker --skip-grill --queue .swarm/wave-<N>.md (passes the peeled slice IDs through).
3. The planner-worker run handles its own US-1 .. US-14 inside the wave: worktree per worker, DoD, merger Opus 4.7, escalation on conflict.
4. Wait for the wave to fully resolve (all merged or escalated). Re-read open issues from GH (workers may have opened follow-ups, see US-6).
5. If queue still has unblocked work, goto wave N+1. Else, drop into US-5 refill.

Wave summary appended to .swarm/nightshift-status.md after each wave.

US-4: Refill when ready queue empties

Branch on --scope:

• ready-only — exit clean. Print "ready queue drained, N waves, M PRs merged, K escalated."
• auto-slice — pick the top-ranked open parent PRD (body opens with ## Problem Statement, has the ready-for-agent label). Dispatch /ro:slice-into-issues --prd <parent-number> (publishes child slices as GH issues, body ## Parent\n\n#<parent-number>). When new slices appear, goto US-1.
• grill-first — pick the top-ranked open prd:draft. Dispatch /grill <draft-number> (rewrites the body into Pocock 7-section and the user/skill swaps prd:draft for ready-for-agent). Then goto US-4 again — the newly-grilled parent now needs slicing.
• full-drain — grill all drafts first, then slice all parents, then drain. Iterate: drain → slice next parent → drain → slice next → ... → grill next draft → slice → drain → ... → exit when no drafts, no parents, no slices.

All refill phases are bounded by --max-waves and --max-runtime. When a cap is hit, the loop exits cleanly via US-7 nightsheet, no half-merged worktrees left behind.

US-5: Workers may open follow-up issues

Unless --no-followups, every worker's dispatch prompt gets appended:

You may open ONE follow-up GH issue per slice you complete IF you encounter
a clearly-out-of-scope TODO that is:
  - in the same area of the codebase
  - small enough to be a future vertical slice (S or M)
  - not already an open issue (check with `gh issue list --search "<topic>"`)

If you open one, do it with EXACTLY:
  gh issue create \
    --label ready-for-agent --label nightshift-followup \
    --title "<one-line>" \
    --body "<followup-body with ## Parent #<source-slice> if relevant, plus ## Blocked by None>"

Then continue with your assigned slice. Follow-ups DO NOT count as a DoD item.

Follow-ups are visible to the next wave's ranker (they're now part of the ready queue) but the rank is age-based so they sort below older work.

US-6: Nightsheet at end of session

On final exit (clean drain, max-waves hit, max-runtime hit, or fatal error), the skill ALWAYS writes a nightsheet via TWO outputs:

Output A — GH issue with nightsheet label

gh issue create \
  --label nightsheet \
  --title "Night shift $(date -u +%Y-%m-%dT%H:%M) — <N> merged, <M> escalated, <K> follow-ups" \
  --body "$(cat .swarm/nightsheet-<ts>.md)"

Body template:

# Night shift run <ISO8601 start> → <ISO8601 end>

**Scope:** <scope> | **Waves:** <N> | **Duration:** <duration>

## Merged PRs (<N>)
- #<pr> — <title> (slice #<issue>)
...

## Escalated (<M>)
- #<pr> — <title> — <one-line cause> — worktree: .swarm/worktrees/<id>
...

## Follow-up issues opened (<K>)
- #<issue> — <title> — opened by worker on slice #<source>
...

## Drafts grilled (<G>)
- #<issue> — <title> — parent now #<parent-issue>
...

## Parents sliced (<P>)
- #<parent> — sliced into <X> children: #<a>, #<b>, ...
...

## Blockers carrying over to tomorrow
- #<issue> — blocked by #<other>
...

## Ranked queue at exit
| score | issue | title | reason |
|--- |--- |--- |--- |
| 0.81 | #234 | settings page polish | top: high unblocks-others, P1 |
...

## Completion report
- Local HTML: `<repo>/.completion-reports/<ts>-<slug>.html`
- Open with: `open <path>`

Output B — completion-report HTML

/ro:completion-report --prs "<merged-pr-list>" --title "night-shift-<ts>" --no-open
# capture the printed path

Pushover + Telegram with deep link

Per global ~/CLAUDE.md rule 4 (Pushover) and the Telegram sibling rule, fire BOTH:

# Deep-link target priority: briefing HTML (US-7 output) > retro markdown > completion-report HTML.
url="file://<completion-report-path>"
[ -f .nightshift/last-retro-url.txt ]    && url=$(cat .nightshift/last-retro-url.txt)
[ -f .nightshift/last-briefing-url.txt ] && url=$(cat .nightshift/last-briefing-url.txt)  # wins if present

# Self-grill runs: include the assumptions count so the morning ping says how
# many calls were made on the user's behalf.
assume_line=""
if [ -f .nightshift/assumptions.md ]; then
  n_assume=$(grep -cE '^\| [A-Z]?[0-9]' .nightshift/assumptions.md 2>/dev/null || echo 0)
  assume_line=" — ${n_assume} assumptions to confirm"
fi

bash ~/Dev/ronan-skills/skills/pushover/scripts/notify.sh \
  "night shift done: <N> merged, <M> stuck, <K> follow-ups${assume_line}" \
  --title "Night shift" \
  --url "$url"

# Telegram (RoClaw bot) — notify.sh does NOT accept --url, so embed it inline.
bash ~/Dev/ronan-skills/skills/telegram/scripts/notify.sh \
  "night shift done: <N> merged, <M> stuck, <K> follow-ups${assume_line}

briefing: $url
nightsheet: <nightsheet-issue-url>" \
  --title "Night shift"

On a --self-grill run the briefing's Assumptions section is the payload that matters: the Pushover tap opens the briefing HTML (assumptions up top), and the Telegram message leads with the count so the user knows how many decisions are waiting for a yes/no before they even open the link.

Tapping the Pushover notification opens the morning briefing in the browser (the most useful deep-link target). Telegram displays the URLs inline so they're tappable from the chat. The nightsheet GH issue is the durable triage queue for the morning.

Skip BOTH notifications only when --no-ping or --plan-only.

US-7 (Phase 7): Run retro

After the swarm exits (clean drain, max-waves, max-runtime, or fatal error) AND after the nightsheet GH issue + completion-report HTML are written, BUT BEFORE the Pushover + Telegram pings fire:

/ro:night-shift-retro --run-id "$run_id" --dispatcher night-shift

The retro:

1. Reads .swarm/nightsheet-*.md, .swarm/run-*.md, .swarm/status.md, .swarm/logs/*.log, and gh pr list --search "merged:>=$started_at" to reconstruct the run.
2. Classifies each slice's outcome (merged / blocked / deferred / auto-split) and failure mode (thrashing / proxy-gaming / misalignment / non-convergence / context-drift / runaway-resource / other).
3. Drafts action items, classified SYSTEM (ronan-skills / factory) vs PROJECT (current repo, ready-for-human label) vs UNCLEAR (markdown only).
4. Writes .nightshift/retros/<YYYY-MM-DD>-<run-id>.md + .json.
5. Renders the morning briefing HTML to .nightshift/briefings/<YYYY-MM-DD>[-<suffix>].html (when retros.morning_briefing: true, default). This is the "wake-up-to-coffee" artefact: hero card, merged PRs, new slices, "what to do this morning", deploy status, biggest surprise, run summary, links. See /ro:night-shift-retro US-4b for the section shape.
6. Files cross-repo issues per the routing rules in [[night-shift-retro-and-day-shift]] § "Cross-repo routing" when .ronan-skills.json retros.open_followup_issues: true.
7. Drops the briefing path into .nightshift/last-briefing-url.txt (preferred deep-link target) and the retro path into .nightshift/last-retro-url.txt (fallback) so the subsequent Pushover + Telegram tail call picks whichever exists.

The Pushover + Telegram pings (US-6 above) THEN fire with the briefing HTML as the deep-link — tapping the phone notification lands on the morning briefing, which links onward to the retro markdown, completion-report HTML, and the nightsheet issue.

Skip the retro under any of:

• --no-retro (explicit skip)
• --plan-only (nothing ran)

--no-ping does NOT skip the retro; it only skips the notification. The retro artefact is always written when work happened.

See /ro:night-shift-retro for the full skill definition.

Defaults inherited from ronan-skills ≥ 1.56.x

• --source github:<label> — read from current repo's GH backlog (passed through to /ro:planner-worker)
• Opus 4.7 merger (planner-worker default)
• --afk semantics: auto-approve config inside each wave, judge-agent termination per wave, skip grilling per wave
• --workers 5 cap unless overridden
• Pushover + Telegram at end per global CLAUDE.md rule 4

Override any by passing the flag explicitly.

Quick start

# Interactive: opens the four-question grill, then runs
/ro:night-shift

# Ready-queue drain, no questions
/ro:night-shift --scope ready-only --yes

# Full overnight: grill drafts + slice parents + drain
/ro:night-shift --scope full-drain --max-runtime 8h --max-waves 20

# Truly AFK: self-grill every decision, log assumptions, explain them in the briefing
/ro:night-shift --self-grill --scope full-drain

# Auto-slice open parent PRDs and drain, but don't touch drafts
/ro:night-shift --scope auto-slice

# Serial Ralph instead of parallel swarm (use when slices are dep-chained)
/ro:night-shift --build ralph

# Smaller crew (Max plan weekly cap considerate)
/ro:night-shift --workers 2

# Custom queue label (Pocock synonym example)
/ro:night-shift --label Sandcastle

# Dry-run: print what would dispatch, no actual work
/ro:night-shift --plan-only

# Silent: skip the notification
/ro:night-shift --no-ping

# No retro artefact (still pings)
/ro:night-shift --no-retro

When NOT to use

• No GH remote. /ro:night-shift requires a gh remote. Run gh repo create or use the local-file flow via /ro:planner-worker --prd <name> directly.
• No backlog AND no drafts AND no parents. Run /ro:write-a-prd and /ro:slice-into-issues first, or use /agentic-e2e-flow for the full pipeline.
• First time in a repo with unknown config. The opening grill handles this, but if you also want to grill on worker count, judge-agent, etc., run /ro:swarm directly the first time, then come back here.
• Single-story exploration. Use /ro:ralph --mode single.
• Untrusted code or hostile input. No container isolation; the cloud factory at github.com/RonanCodes/factory is the sandboxed path (see skill-lab:factory-overnight-coding-swarm).

Errors

| Condition | Message | |---|---| | No gh remote | "Not in a gh-remote repo. /ro:night-shift requires a GitHub remote. Run gh repo create to add one." | | Empty ready queue + no drafts + no parents | "No <label> slices, no prd:draft drafts, no open parent PRDs. Run /ro:write-a-prd + /ro:slice-into-issues to populate the backlog (or use /agentic-e2e-flow for the full pipeline)." | | Empty ready queue + drafts exist but scope=ready-only | "No ready slices, but you have N prd:draft issues. Re-run with --scope grill-first or --scope full-drain, or run /ro:list-draft-prds to see them." | | Empty ready queue + parents exist but scope=ready-only | "No ready slices, but you have N open parent PRDs that haven't been sliced. Re-run with --scope auto-slice or --scope full-drain, or run /ro:slice-into-issues --prd <N> manually." | | All slices blocked by escalations | "All <label> slices are blocked, by: #N, #M, #K. Resolve those first or unblock manually." | | Max-waves hit | "Hit --max-waves <N> cap. Nightsheet written to issue #<N>. Resume with /ro:night-shift --scope <same>." | | Max-runtime hit | "Hit --max-runtime <duration> cap. Nightsheet written to issue #<N>. Resume with /ro:night-shift --scope <same>." | | Build flag --build ralph with parallel-eligible slices | "Heads-up: most slices look parallel-eligible. --build swarm would finish faster. Continue with serial Ralph? (y/N)" — auto-continue if --yes. |

How this composes with related skills

• /ro:planner-worker (alias /ro:swarm) — night-shift wraps it. Planner-worker is one wave; night-shift is the multi-wave drain + refill loop with the explicit-scope grill on top. Use planner-worker directly when you want a single wave or a different PRD source.
• /ro:ralph — alternative serial build inside a wave via --build ralph. Use when slices are dep-chained (mostly linear Blocked by graph).
• /ro:write-a-prd — upstream PRD writer. Night-shift's --scope grill-first / --scope full-drain triggers a grill on existing prd:draft issues but does not invent new PRDs.
• /ro:slice-into-issues — invoked by --scope auto-slice and --scope full-drain to break parent PRDs into child slices mid-loop.
• /grill (grill-with-docs) — invoked by --scope grill-first and --scope full-drain to promote drafts into Pocock parents.
• /agentic-e2e-flow — the full end-to-end pipeline if you also want the swarm-research and grill-with-docs phases upstream. Night-shift is the "I already have a backlog, just drain it" subset.
• /ro:completion-report — invoked at end of session to build the HTML deep link.
• /ro:night-shift-retro — Phase 7 sibling; captures SYSTEM/PROJECT action items + the markdown+JSON retro artefact deep-linked from Pushover/Telegram.
• /ro:day-shift — morning sibling; grills the backlog into shape for tonight's run. Pair these two for the full async chain (see [[night-shift-retro-and-day-shift]]).
• /ro:pushover + /ro:telegram — fired at end per global CLAUDE.md rule 4.

Provenance

• 2026-05-14 — created in response to "I want a forward slash command that auto runs the night-shift swarm with sub-agent planners and sub-agent workers against the existing GH backlog for the current repo." Built on top of /ro:planner-worker and the auto-pushover + Opus-reviewer defaults locked in ronan-skills 1.46.1.
• 2026-05-19 — major rewrite. Added explicit-scope opening grill (US-0), 4-signal ranker (US-1), hybrid file-area conflict detection (US-2), indefinite drain + refill loop (US-3, US-4), worker follow-up issues (US-5), nightsheet (US-6). The trigger that motivated this: "I want to see all issues closed tomorrow", which made the zero-config single-wave behaviour insufficient. Also: making "AFK" mean three different things (ready-only / grill-first / full-drain) and forcing the user to pick once at the start of the run.
• 2026-05-28 — added --self-grill mode: on a truly-AFK run, auto-answer the US-0 gates and any mid-run decision via the recommendation logic, log each as an auditable assumption in .nightshift/assumptions.md, and surface them as the top section of the morning briefing (deep-linked from Pushover + RoClaw Telegram). Only genuinely irreversible / credential-needing decisions still escalate to blocked-on-human. Trigger: "I'm going AFK, continue with everything, self-grill if it makes sense and give me the assumptions in the morning."
• 2026-06-11 — added the live claims registry + shared learnings protocol after the nutmeg double-shift. Idea from Ronan mid-run: slices #167/#168 had disjoint predicted territories but both created admin/sources.tsx — scope drift that pre-dispatch prediction cannot catch. Night-shift now seeds .swarm/claims.jsonl + .swarm/shared-learnings.md at run start (US-3 step 0) and merges actual claimed paths from completed waves into the file-area graph (US-2 claims pass). The worker-side protocol lives in planner-worker US-3c2. Cooperative sibling of the factory's enforced DO file-lock graph.

See also: skill-lab:factory-overnight-coding-swarm for the cloud-deployed sibling running on Pi + Cloudflare Sandbox.