Night shift

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.

Worker	Looks for	Output
Architecture mapper	module boundaries, dependency direction, data flow, service boundaries, ownership gaps	boundary map, coupling risks, missing docs
Testability auditor	missing contracts, brittle fixtures, flaky setup, unverified workflows	highest-value tests and exact invariants
Performance scout	N+1 queries, redundant IO, cache gaps, bundle size, long jobs	bottleneck hypotheses and verification commands
Tooling/DX auditor	broken scripts, unclear setup, missing one-command checks	repo setup friction and script candidates
Security/data-flow reviewer	secrets handling, auth checks, tenant boundaries, unsafe input	risk scenarios and mitigation candidates
Agent-readiness reviewer	AGENTS.md quality, codebase maps, local commands, acceptance criteria	what future agents need to move faster
Cross-repo pattern miner	duplicated helpers, divergent APIs, repeated architecture motifs	consolidation or standardization candidates
Research scout	current docs, GitHub examples, X/Twitter leads, AOSwarm patterns	verified external ideas and links

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.