night-shift

Run the computer while the human sleeps, but keep the loop bounded, auditable, and reversible.

night-shift is an unattended analysis skill. It fans out read-only workers across recently active repositories, captures findings, synthesizes architectural leverage, and produces a morning HTML report. It is not a license to edit production code or burn unlimited model quota.

Core Contract

Every run must have:

• a time box;
• a worker cap;
• a repo cap;
• a provider fallback policy;
• a failure ledger;
• a self-contained HTML report;
• no writes to production code unless the user explicitly starts a follow-up AOSwarm execution phase.

AOSwarm SDLC

Use AOSwarm as the SDLC shape:

1. Scout swarm: read-only workers inspect independent repos or domains.
2. Synthesis lead: one agent clusters findings, identifies themes, and writes the morning report.
3. Human gate: the user reviews the report and chooses follow-up work.
4. Execution swarm: approved code-changing work is dispatched through ao spawn or ao batch-spawn, one PR/MR per task.
5. Verification: merged only after normal repo verification and review gates.

The nightly phase is phases 1 and 2 only. Phases 3 to 5 require explicit human approval.

The bundled nightly runner uses direct read-only CLI scouts (claude, codex, gemini) for phases 1 and 2 so it can collect local Markdown artifacts deterministically. Use ao spawn / ao batch-spawn for phase 4 code-changing execution after the human gate.

Worker Types

Run workers as independent scouts. Assign each worker one repo and one lens unless the repo is small.

Preflight

Before launching workers:

1. Print repo root, output directory, time window, repo cap, worker cap, and provider order.
2. Confirm tools when available: claude, codex, gemini, ao, tmux.
3. Ensure at least two default Claude CLI remote-control sessions are running:

ps -axo command | grep -F "claude --remote-control" | grep -v grep

If fewer than two are found and tmux is installed, start missing sessions with the default claude binary:

tmux new-session -d -s agentic-nightly-remote-1 "claude --remote-control agentic-nightly-remote-1"
tmux new-session -d -s agentic-nightly-remote-2 "claude --remote-control agentic-nightly-remote-2"

Record the before/after count in the report.

Repo Selection

Rank repositories by:

1. dirty worktree state;
2. commits in the selected time window;
3. recently modified .planning, .gsd, .omc, reports, or skill files;
4. current branch not being the default branch;
5. explicit user-provided repo list.

Skip dependency directories, generated artifacts, archived repos, and repos without readable project context.

Provider Fallback Protocol

Default provider order:

1. Claude CLI: best first pass for repo-aware analysis.
2. Codex CLI: fallback for hard engineering reasoning and current OpenAI-side availability.
3. Gemini CLI: fallback for long-context synthesis and external research.

Use CLIs only. Never call model REST APIs directly.

Rate-limit and failure handling:

• Detect provider failures from exit code plus error text containing rate limit, quota, overloaded, 429, insufficient_quota, authentication, invalid api key, or usage limit.
• After one failure, retry once with exponential backoff.
• After three consecutive failures for a provider, mark it unavailable for the rest of the run.
• When falling back, reduce concurrency by half for the next provider when the runner supports dynamic throttling; otherwise cap the next run and record the requested lower concurrency.
• If all providers fail, stop launching model workers and produce an evidence-only HTML report.
• Always preserve partial findings. A partial report is better than a hidden failed run.

Do not spin. Do not keep re-authenticating unattended. Do not print secrets.

Worker Prompt Contract

Each worker prompt must include:

• repo path and lens;
• read-only rule;
• explicit files to inspect first;
• max time or max command count;
• output schema;
• "do not modify files";
• "do not run network or credentials-heavy commands unless the prompt says so";
• fallback instruction: if blocked, write what was checked and what evidence is missing.

Worker output schema:

# <repo> - <lens>

## Highest-Leverage Finding
<one paragraph>

## Evidence
- <file/command/log references>

## Architecture or Workflow Insight
<compound lesson>

## Follow-Up AOSwarm Candidate
<prompt-ready task, or "none">

## Verification Command
<command or "not applicable">

## Confidence
High | Medium | Low, with reason

Morning HTML Report

Write outputs to:

reports/nightly/YYYY-MM-DD/
  index.html
  dreaming.md
  night-shift-summary.md
  workers/
    <repo>-<lens>.md
  run.json

index.html must be self-contained, light-mode, and open automatically at the end of the run on macOS with open <path> unless disabled.

Required report sections:

1. Run status: completed, partial, or failed.
2. Provider health: Claude, Codex, Gemini availability, fallbacks used, rate limits.
3. Claude remote-control health: before count, after count, sessions started.
4. Repo coverage: selected repos, skipped repos, reason.
5. Top insights: cross-repo compound findings.
6. Architecture findings: grouped by repo and severity.
7. AOSwarm queue: candidate ao spawn or ao batch-spawn prompts, gated for human approval.
8. Research leads: docs, GitHub, X/Twitter categories worth studying, with verification status.
9. Failure ledger: every partial or failed worker.

X/Twitter Study Categories

Use X/Twitter only as a discovery index. Study these categories, then verify elsewhere:

• Karpathy-style autoresearch loops: editable surface, locked metric, results log, keep/revert.
• Parallel experiment waves: many hypotheses per decision instead of serial hill-climbing.
• Worktree-isolated coding agents: separate branches/worktrees to prevent file collisions.
• Reflection/heartbeat loops: agents summarize progress and recover from crashes or compaction.
• Strategy evolution: program.md, strategy.md, results.tsv, and prompt-as-parameter systems.
• Non-ML transfers: growth, market analysis, prompt optimization, product architecture, backtesting.
• Goodhart defenses: independent evaluators, anti-reward-hacking checks, evaluator audits.
• Human approval gates: morning review before ticket creation or code execution.
• Knowledge stores: markdown memories, BM25/vector retrieval, and curated reusable lessons.

What Not To Do

• Do not run destructive commands.
• Do not push, merge, deploy, or create tickets unattended.
• Do not let workers edit code in the main checkout.
• Do not run unlimited workers because the machine is idle.
• Do not trust X/Twitter claims without verification.
• Do not hide rate-limit failures; they belong in the report.

Completion Criteria

A night-shift run is complete when:

• at least one scout worker or evidence-only scan has run;
• provider and Claude remote-session health are recorded;
• partial failures are captured;
• a morning HTML report exists and opens;
• AOSwarm follow-up candidates are prompt-ready but not dispatched without approval.