forge-nightshift
Overnight session-limit-resilient builder — work-package queue, auto-resume, morning briefing: run this overnight, keep going while I'm away, resume tomorrow, opt-in only.
SKILL.md.claude/skills/forge-nightshift/SKILL.md
GitHubForge playbook — Nightshift (overnight self-resuming builder)
Do not duplicate existing tools — defer to: forge-manifest.cjs (ARM/RECONCILE per-WP manifest),
forge-swarm-resume.cjs (re-dispatch plan for unfinished WPs), forge-checkpoint.cjs (idempotency for any
side-effecting WP), forge-actiongate.cjs (hard-gates — deploy/push/spend/DNS/etc.), usage-guard.cjs
(the real, already-built session/usage-limit watchdog + auto-resume signal), and forge-briefing.cjs
(piece J5 — the real, tested morning-briefing generator this skill's output depends on). This file is
doctrine/orchestration only: it explains how those pieces compose into an overnight run, it does not
reimplement any of them.
What Nightshift actually is (and is not)
Nightshift is not a new autonomous scheduler and not a background daemon that decides on its own to start work. It is a documented pattern for composing four already-real, already-tested pieces so a large swarm can survive a session/usage-limit interruption and resume honestly the next time a session runs:
- Plan the work queue up front and ARM it (
forge-manifest.cjs::arm()) so every work package's exact scope (narrowed_prompt,deps) is persisted BEFORE dispatch — never re-derived from memory later. - Dispatch normally (Agent-tool subagents, per this project's real-agents-only governance). Each
WP's real completion/failure is logged as an ordinary event (
wp_completed/check_passedorwp_failed/check_failed) — Nightshift adds no new event-logging mechanism of its own. - Survive the interruption. If the session ends (session-limit pause, usage-limit pause, or the owner
simply closes the laptop), nothing is lost: the manifest +
events.jsonlalready on disk are the complete record. The NEXT session that runs callsforge-swarm-resume.cjs::resume({run_id})to get back exactly the unfinished WPs (with their original scoping) — never a fabricated "pick up where I think I left off". - Report honestly. Before (or instead of) resuming, run
forge-briefing.cjs --run <id>to generate the MORNING BRIEFING — a markdown of what ran, what's blocked, and what only the owner can decide (retry/reassign/drop a failure, resume/reprioritize/drop an unfinished WP), derived purely from the run's own logged manifest + events. This is a real, hermetically-tested tool (forge-bin/forge-briefing.cjs+forge-briefing.test.cjs), not a scaffold.
Hard rules
- Hard-gates still interrupt overnight. Nothing about running unattended changes
forge-actiongate.cjs's classifier or the owner-approval requirement it enforces. A deploy/push/spend/ DNS-change/credential-rotate/workflow-activate/outbound-send WP that gets dispatched overnight still stops and waits forowner_confirmed:true— it does not queue itself for "approve all in the morning". An overnight run that hits a hard gate logs the block and moves on to other, non-gated WPs; it never silently proceeds past one. - Scheduling is opt-in only — this skill never self-schedules. Nothing in this project starts a new Claude Code session on its own. Two real, owner-enabled opt-in paths exist (see "Opt-in flow" below); neither is active until the owner turns it on.
- Every resumed WP still owns its own idempotency. A re-dispatched WP that has a real side effect
(email, deploy, external write) MUST check
forge-checkpoint.cjs::shouldRun/claimfor its own idempotency key before repeating that side effect —forge-swarm-resume.cjs::resume()only tells you WHICH WPs are unfinished, it does not itself guard against double-running one (see that file's own header). - Never fabricate progress. A WP with no qualifying completion/failure event stays "armed" — exactly
forge-manifest.cjs's "never fabricate a completed WP" invariant — and is reported as unfinished in the morning briefing, never quietly assumed done because "it was probably fine." - The briefing is evidence, not narrative.
forge-briefing.cjsonly ever renders what the run's own manifest.json/events.jsonl already say. If a WP's outcome was never logged, the briefing says so; it does not infer success from a file that merely looks correct.
Opt-in flow (dormant until the owner acts)
Nothing below is active by default. Both paths are the owner's explicit choice, and both still end in the SAME place: a Claude Code session running the plan → dispatch → resume → briefing loop above.
usage-guard.cjswatch/auto-resume (already real, already built). The owner runsnode .claude/forge-bin/usage-guard.cjs startto watch the real Anthropic usage endpoint. When a session-limit pause happens, the guard's own documented RESET-RHYTHM auto-resume signals the paused session to continue once the limit window resets (see that file's header — this is existing, tested behavior, not new for Nightshift). Nightshift's contribution is simply: on that continue signal, the resumed session's FIRST action isforge-swarm-resume.cjs::resume({run_id}), not "start over."- OS-level scheduler (cron / Windows Task Scheduler), fully owner-configured. For a literal overnight
wake-up (not just a usage-limit reset), the owner configures their OWN OS scheduler to start a Claude
Code session at a chosen time, with a prompt that names the
run_idto resume (e.g. "resume Forge run <id> via forge-swarm-resume, then produce the morning briefing"). Forge does not ship or install this scheduler config — it is standard OS tooling the owner sets up outside this project, exactly like any other cron job the owner already runs. Either path ends at the same resume+briefing loop; neither is required for Nightshift's tools to work manually (an owner can always runforge-swarm-resume.cjs/forge-briefing.cjsby hand, on demand, with no scheduler at all — that manual path is the actually-proven one).
Skills / commands / MCP
forge-manifest.cjs (arm/reconcile/status), forge-swarm-resume.cjs (resume plan), forge-checkpoint.cjs
(per-WP idempotency), forge-actiongate.cjs (hard-gate classifier, reused not duplicated), usage-guard.cjs
(real session/usage-limit watchdog + auto-resume), forge-briefing.cjs (real morning-briefing generator —
node .claude/forge-bin/forge-briefing.cjs --run <id> [--json]), forge-worktrees skill when overnight
work is parallelized across multiple Bosses.
Fan-out & flow
No dedicated team of its own — Nightshift is a cross-cutting composition pattern the Lead (Head Chef) applies
around whatever domain team a task already needs (forge-website, forge-fullstack, etc.).
Serial, once per session boundary: plan + ARM manifest → dispatch WPs normally → (session ends) →
next session: forge-swarm-resume.cjs::resume() → re-dispatch only the unfinished WPs → forge-briefing.cjs
before/after each resume, so the owner always has an up-to-date, real morning briefing rather than only a
next-morning one.
Ship-readiness (unique)
A real manifest was armed before dispatch (manifest.json exists for the run); every WP's real
completion/failure is a logged event, never inferred; forge-swarm-resume.cjs output was actually used to
scope the resumed dispatch (not a manually-reconstructed guess); every hard-gate hit during the run is
still logged as a block awaiting owner_confirmed:true, never silently bypassed; the morning briefing
(forge-briefing.cjs --run <id>) was actually generated and its ran/blocked/decisions_needed reflect
real logged content; any side-effecting resumed WP re-checked its own forge-checkpoint.cjs idempotency key
before repeating a real action. State plainly whether an opt-in scheduling path is active or the resume was
run manually — never imply an automatic overnight wake-up happened when the owner simply re-ran the command.