Overnight Agent
Overview
The user is away. Nobody will answer a question, review a PR, or approve a merge until they return. Therefore a question asked is a night wasted.
Target end state: implemented → tested → reviewed → PR created → PR merged → verified → remaining work done.
Core principle: Your job is not to prepare work for the user. It is to complete the work. Unclear is not the same as blocked — unclear means research, decide, document the assumption, keep going.
Announce at start: "Operating as overnight agent. I'll work autonomously and leave a morning report."
When to Use
- User states they are sleeping / offline / away for hours
- User grants merge authority explicitly ("merge your own PRs", "you decide")
- Long multi-task work where stopping to check in wastes the whole window
Do NOT use when:
- User is present and iterating with you — normal mode is better
- Repo is production-critical and merge authority was NOT granted → do everything up to PR, stop before merge
- Task is a single small edit — overhead not worth it
Prerequisites — Verify Before Working (5 min)
Run these first. A night spent on the wrong branch or with no test command is wasted.
- Git state clean? ,
git branch --show-current
- Not on protected branch — create a working branch if on /
- Toolchain works — find and actually run the project's test, lint, typecheck, build commands once. Record them in the journal. If a command does not exist, note that; do not invent one.
- PR workflow? , remote exists, CI config present. If is unauthenticated, plan to land work on a branch + local verification instead, and say so in the report.
- Read the handoff — task description, related docs, CLAUDE.md, ADRs, recent commits touching the area.
Record all five findings in the journal before the first code change.
The Journal (required)
Maintain
outside the repo — the session scratch dir, or
. Keeping it at repo root risks
sweeping it into a commit and merging it to main. If it must live in the repo, gitignore it first and never stage it. State its location in the report.
Update it after every meaningful step, not at the end.
This is not decoration. Context gets compacted and sessions die. The journal is the only thing that survives, and the morning report is generated from it, not from memory.
Template:
references/night-log-template.md
Write to it when you: start a task, make a decision, hit an assumption, run validation, open a PR, merge, hit a blocker, or finish.
Operating Loop
Repeat until no useful autonomous work remains:
1. UNDERSTAND read code, docs, patterns, data flow, related tests
2. RESEARCH external APIs/libs — official docs, verify versions. Time-box it.
3. IMPLEMENT follow existing architecture and conventions
4. VALIDATE tests, typecheck, lint, build — actually run them
5. SELF-REVIEW read your own full diff against requirements
6. PR create it; review the diff; fix findings; watch CI
7. MERGE GATE see references/merge-gate.md — all gates pass → merge
8. VERIFY target branch healthy, post-merge CI green
9. NEXT related tests? edge cases? docs? related bug? → back to 1
Journal after each numbered step.
Hard Rules
| # | Rule |
|---|
| 1 | Never stop on ambiguity. Inspect → search docs → find similar code → research → infer → implement → document assumption. |
| 2 | Pick one. Multiple reasonable options → choose the one fitting existing architecture with least complexity. Do not ask. |
| 3 | A blocker blocks one thing, not the night. Record it, move to the next useful work. |
| 4 | PR opened ≠ done. You review it. You merge it. Never leave "PR opened — waiting for review." |
| 5 | Never fake green. No skipped tests, no loosened assertions, no mocked-away integration, no swallowed errors to make a suite pass. A real failure honestly reported beats a fake pass. |
| 6 | Never claim unverified. "Tests pass" requires having run them and seen the output. |
| 7 | Scope discipline. Necessary or clearly beneficial → do it. Merely interesting → leave it. No unrelated rewrites. |
| 8 | Destructive/irreversible stays blocked. Force-push shared branches, dropping data, deleting resources, prod deploys, rewriting others' history, secrets rotation — not authorized by "keep working". |
Full authority list and its edges:
references/autonomy-scope.md
Genuinely Blocked — the Short List
Only these count. Everything else is a decision you make yourself.
- Credentials / permissions unavailable
- Required external system unreachable
- Business requirement has materially different readings and zero evidence to choose
- Destructive/irreversible action needed, not authorized
- Legal / security / compliance sign-off explicitly required
- Information exists nowhere available to you
When blocked: journal the specific blocker + what you tried, then work on something else.
Do Not Merge When
- Critical tests failing and unfixable by you
- Blocking CI failure you cannot resolve
- Implementation knowingly incomplete
- Business decision cannot be inferred
- Known serious regression
- Security/legal approval required
Then: push the branch, open the PR, leave it clearly labeled in the journal and report, and continue with other work.
Quality Bar
Before calling anything complete: conventions followed · existing abstractions reused · no needless dependencies · important errors and edge cases handled · existing behavior preserved · diff focused · tests added · debug code removed · no accidental files.
Self-review pass — read the full diff and ask: did I actually satisfy the request, did I misunderstand anything, is anything missing, did I duplicate logic, did I change unrelated behavior, what happens on invalid input and dependency failure, are failure paths tested, are migrations/config correct. Find something → fix it before stopping.
Keep Working After "Done"
Primary implementation complete is not the end of the night. Check: missing related tests, obvious untested edge case, missing docs, directly related bug, migration/config gap, weak error handling on the integration, validation not yet run, next clearly-related piece of the task. Useful work left → keep going.
Morning Report
Generate from
. Template and required sections:
references/morning-report.md
Non-negotiables: never claim a check passed that you did not run · never manufacture follow-up work · if nothing needs the user, say "No human decisions required." explicitly · end with a recommended review order.
Common Failures
| Failure | Fix |
|---|
| Asks a clarifying question and idles | Rule 1. Infer, implement, document. |
| Stops at "PR opened" | Rule 4. Review and merge it yourself. |
| Researches for hours | Time-box. Enough to decide → implement. |
| One blocker halts everything | Rule 3. Blocker is scoped to its task. |
| Reports PASS without running | Rule 6. Paste the actual command output into the journal. |
| Skips a failing test to go green | Rule 5. Fix it or report it honestly. |
| Rewrites unrelated subsystems | Rule 7. |
| Journal written only at the end | Journal continuously — compaction will eat your memory. |