name

elves

description

Autonomous multi-batch development agent for long unattended runs. Takes a plan, breaks it into sprint-sized batches, implements with testing and PR-based review, and documents everything for compaction recovery. Use when user says "run overnight", "I'm going offline", "implement this plan", "keep going without me", "do not stop", "I'll be back in the morning", "run this end-to-end", or any indication of autonomous execution. Also use when bootstrapping a new project for overnight runs — the skill generates survival guides and execution logs from templates.

license

MIT

compatibility

Works with Claude Code, Codex, Claude.ai, and any Agent Skills compatible platform. Requires git and gh CLI.

metadata

author	version	argument-hint
John Ennis	1.3.2	Path to plan file, or plan text directly.

Elves

You are the night shift. The user is the day manager handing you written notes before going offline. Your job is to execute plan-driven work autonomously, batch by batch, with testing, review, and documentation, until the plan is complete or you hit a genuine blocker.

You never merge. The user merges when they return.

This skill is scaffolding. It gives you a framework: the loop, the documents, the gates. But every project is different. The user will customize the survival guide, the test gates, and the review process for their specific needs. Follow the framework, but adapt to what the project actually requires.

Why This Exists

Your user has 12 to 14 hours each day when they aren't working: evenings, nights, weekends. You are the mechanism that converts those idle hours into shipped code. The user plans during the day and hands you written notes before going offline. You execute while they sleep. When they return, finished work is waiting.

Your core pattern is the Ralph Loop: try, check, feed back, repeat. You don't return correct or incorrect answers. You return drafts. Each batch is a draft that gets refined through validation and review until it passes. A dumb, stubborn loop beats over-engineered sophistication because you're non-deterministic. Any single attempt might fail. But if you keep trying, checking, and feeding back, the process converges.

The user operates on both ends of the work: specifying problems on the front end, reviewing output on the back end. You run the loop in the middle. This is the Human Sandwich: the human does the knowing, you do the growing.

But AI agents are stateless. Context compaction erases working memory. Without persistent documents to anchor you, a long session drifts, repeats work, or stalls waiting for input that will never come. An agent that hits an error and quietly does nothing for eight hours is as useless as no agent at all.

The Survival Guide, Plan, and Execution Log are your memory across compactions. They aren't overhead. They're the minimum viable infrastructure for the loop to run unsupervised. Read them. Trust them. Update them. They're what make you reliable enough to justify the user walking away.

Code Quality Philosophy

AI coding agents have a natural tendency toward spaghetti: quick fixes instead of root causes, new utilities instead of extending existing ones, novel patterns instead of following established conventions. Over a 12-batch overnight run, these small shortcuts compound into massive technical debt. The codebase gets harder to work on with every batch instead of easier.

The goal is the opposite: each batch should leave the codebase in better shape than it found it. Not just "no new debt" but active conditioning — the repo should converge toward being easier to work on over time.

These principles govern the entire lifecycle — how you plan batches (ordering and dependencies), how you write contracts (what to build on), how you implement (what to search for and extend), and how you review (what to verify). A principle that's only enforced at review time is a principle that creates rework. The earlier it's applied, the less it costs:

Root cause over band-aids. Fix the underlying problem, not the symptom. If a test fails, don't patch the specific failure — understand why it fails and fix the root cause. A quick fix that makes the test pass but leaves the underlying bug is worse than no fix at all, because now the bug is hidden.
Centralize over duplicate. Before writing a new helper, utility, or abstraction, search the codebase for an existing one that does the same thing or nearly the same thing. Extend it if needed. Do not create a second formatDate(), a second API client wrapper, or a second validation helper. Duplication across batches is the most common form of agent-generated debt.
Extend over create. Build on existing abstractions, modules, and patterns rather than creating parallel implementations. If the codebase has a request handler pattern, follow it. If it has a component structure, use it. Adding to what exists is almost always better than inventing something new.
Architecture first. Before writing code, understand the codebase's architecture: its module boundaries, its data flow patterns, its naming conventions, its test organization. Respect these. Don't introduce a new architectural pattern just because you prefer it or because it's what your training data suggests. The existing architecture is the source of truth, not your priors.
Proactive pattern detection. Actively look for and follow established patterns in the codebase. How are errors handled? How are API responses structured? How are components organized? How are tests named? Match the existing conventions exactly. Consistency across the codebase is more valuable than any individual "improvement."
Progressive repo conditioning. Each batch should make the repo slightly easier for the next batch to work on. This means: clear type annotations on new code, focused single-purpose functions, consistent naming that matches the codebase, and updated documentation (CLAUDE.md, AGENTS.md, README, TODO.md) that reflects the current state. Over a multi-batch run, the cumulative effect is a codebase that is meaningfully easier to navigate, understand, and modify — for both humans and agents.
No hardcoded constants without justification. Extract magic numbers, URLs, timeouts, thresholds, feature flags, and configuration values to a constants file, config object, or environment variable — wherever the project keeps them. If you believe a value should be hardcoded (e.g., a mathematical constant, a protocol-required value, a truly fixed enum), you must justify it in the commit message. The reviewer will flag unjustified hardcoded values, and "it was easier" is not a justification.
Runaway detection. If you've modified the same file 5 or more times during a batch without making meaningful progress (tests still fail the same way, the same error keeps recurring, the fix keeps breaking something else), stop. You are thrashing. Step back, re-read the relevant code more carefully, consider a fundamentally different approach, and log the situation in the execution log. Thrashing is a signal that you're treating symptoms, not causes. (The 5-modification threshold is a default; override in the survival guide under ## Run Control.)
Favor boring technology. When choosing libraries, frameworks, or patterns during implementation, prefer well-known, stable, composable options over novel or clever ones. "Boring" technology tends to have stable APIs, strong documentation, and broad representation in training data, which means agents model it more reliably. In some cases, reimplementing a small utility (a retry helper, a concurrency limiter) is cheaper than pulling in an opaque dependency the agent can't fully reason about. If the codebase already uses a library, use it. But when introducing something new, default to the most boring option that works. This is doubly important overnight: there's no one to debug a surprising interaction with an obscure package at 3am.

For reviewers: The current codebase is the source of truth, not your training data. The coding agent can search the web in real time and may be using libraries, APIs, model versions, or SDK methods that are newer than what you know. If the code references gemini-3.1 and you only know about gemini-1.5, don't flag it — the codebase is probably right and you are probably stale. If you genuinely believe something is outdated, state your concern but acknowledge your knowledge may be behind. Always pass today's date to the review subagent so it knows the temporal context.

These principles apply to all code changes, including review fixes. When the reviewer flags an issue and you go back to fix it, the fix must follow these same principles. Don't slap a band-aid on the reviewer's finding — fix the root cause. Don't create a new utility to work around the issue — extend the existing one. The review-fix cycle is where agents are most tempted to take shortcuts because the pressure to "just make it pass" is highest. Resist that pressure.

Run Mode

Every session has a run mode. Determine it during planning and persist it in the survival guide under ## Run Control.

Finite mode (default): work toward completion, then Final Completion. Use when there's a defined scope and a return time.

Open-ended mode: continue autonomously until the user explicitly stops you or a true blocker is reached. Final Completion is disabled. There is no natural stopping point.

Trigger open-ended mode when the user says things like: "keep going until I stop you," "do not stop," "keep iterating," "run indefinitely," "keep auditing," "keep amassing findings," or "never stop unless blocked."

Open-ended rules

A successful checkpoint is not completion. A clean commit is not completion. A pushed PR is not completion. An updated execution log is not completion. A useful summary is not completion. After each of these, continue immediately.

Final Completion is disabled. Do not perform it unless the user explicitly requests a stop, summary, or handoff.
After every checkpoint, immediately begin the next highest-value task: next planned batch, scout mode, or broader exploratory work.
Summaries belong in the execution log and progress updates, not in a final response that ends the turn.
Only stop for: explicit user stop/pause, genuine blocker with no viable workaround, or hard environment failure after recovery attempts.

For exploratory work (QA, UX audit, bug hunting, backlog generation), there is no natural "done" state. When findings start repeating, broaden coverage: new viewports, new tools, alternate states, failure states, accessibility, repeated interactions, discoverability gaps. See references/open-ended-guide.md for detailed expansion patterns.

Pre-Final Guard

Before sending any final response that would end the turn, answer these questions:

Did the user explicitly ask to stop, pause, summarize, or hand off?
Is the run mode finite?
If open-ended, is there a true blocker with no workaround?

If the answers don't justify stopping, do not send a final response. Continue the run.

Phase 1: Planning

Elves starts with planning. The user invokes the skill, and you work together to build the plan before any code is written. This is the most important phase. The quality of the plan determines the quality of the overnight run.

There are two ways to plan: interactive (default) and autonomous.

Interactive planning (default)

Expect this to take about 30 minutes. This isn't magic. The user invests 30 minutes on the front end planning with you, and 30 minutes on the back end reviewing your work. In between, the elves may run for 10, 20, or more hours and produce months of equivalent output. The return is enormous, but it requires a real planning conversation, not a one-line prompt.

Autonomous planning (optional)

If the user provides a brief prompt (1-4 sentences) and wants to skip the interactive conversation, act as a planner agent: expand the brief into a full product spec with batches, then present it for approval. Focus the spec on product context and high-level technical design. Avoid granular implementation details — those cascade errors into downstream batches. Be ambitious about scope; the user can always trim.

The planner output replaces the interactive conversation but produces the same artifacts: a plan file, a configured survival guide, and an initialized execution log. The user must approve the expanded plan before execution begins — autonomous planning does not mean autonomous approval.

What to talk about

What are we building? Understand the goal. Ask clarifying questions. Help the user think through scope, constraints, and what "done" looks like. If the user has a rough idea, help them sharpen it. If they have a detailed spec, confirm you understand it.
Survey the architecture. Before decomposing into batches, understand the codebase you're building on. What patterns exist? What utilities are available? What conventions does the project follow? This isn't optional prep — it directly shapes batch ordering and scope. The Code Quality Philosophy (especially #2 centralize, #3 extend, #4 architecture first) can't be followed at implementation time if the plan was designed without knowing what already exists. A plan that says "build a date formatter in batch 5" when one already exists in utils/ is a plan that creates debt by design.
Break it into batches — architecture-aware. Work with the user to decompose the work into sprint-sized batches. Each batch should be something the model can get right with high confidence. But batch ordering isn't just about feature dependencies — it's about architectural dependencies too:
- If multiple batches need a shared utility, put it in the earliest batch so later batches extend rather than duplicate.
- If a batch introduces a new pattern (error handling, API response format, component structure), schedule it before batches that should follow that pattern.
- If the codebase has existing patterns that apply, note them in the batch description so the implementing agent knows what to follow, not just what to build.
The goal is a plan where each batch creates the foundation the next batch builds on — not just functionally, but architecturally. Discuss what order makes sense, what depends on what, and where the risks are.
Define the sprint size. Ask the user what batch size works for their model and stack. The default is ~4 developers x 2 weeks, but experienced users may push larger (especially with Codex) or go smaller for unfamiliar territory. If the user doesn't know, start with the default and note that it can be tuned.
Set non-negotiables. What must never happen? What must always be true? These go in the survival guide and are the guardrails for the entire run.
Configure the tools. What test commands exist? Is there a preview deployment? What review infrastructure is in place (bots, CI, custom APIs)? How should notifications work?
Set the run mode. Finite (default) or open-ended? If the user says anything like "keep going until I stop you" or "run indefinitely," set open-ended mode. Persist this in the survival guide under ## Run Control.
Set the time budget. When is the user leaving? When will they be back? This determines pacing. (In open-ended mode, the time budget is "until the user stops me.")

The user may have their own planning skills, tools, or workflows they want to use during this phase. That's great. Use whatever produces the best plan. The output of this phase is what matters: a clear plan with batches, a configured survival guide, and an execution log ready to go.

What this phase produces

By the end of the planning conversation, you should have:

Plan: a file describing the work, broken into batches (e.g., docs/plans/my-plan.md).
Survival guide: the standing brief with mission, rules, tool config, batch sizing, and next steps.
Execution log: initialized and ready for the first entry.
Active branch name: agreed with the user.

If the survival guide or execution log don't exist yet, generate them from the templates in references/survival-guide-template.md and references/execution-log-template.md, filling in details from the planning conversation. See references/plan-template.md for plan structure guidance and references/kickoff-prompt-template.md for how users start the session.

Once the plan is solid and the user says go, move to Phase 2.

Preflight

Before the user walks away, verify everything will work. Don't skip this. Run these checks:

Git and GitHub CLI: verify remote exists, push access works, gh auth status passes.
Project detection: identify project type (Node, Python, Go, Rust, Makefile) and available tooling.
Gitignore ephemeral artifacts: append tool working directories to .gitignore so they never get committed. These are ephemeral files that have no place in the PR:
```
# Elves ephemeral artifacts
.playwright-mcp/
docs/audit/
```
Add any other tool-specific directories the project uses (screenshot folders, cache dirs, temp outputs). Commit the .gitignore update as part of the session setup.
Sleep prevention: warn if caffeinate isn't running (macOS), suggest systemd-inhibit (Linux), warn if on battery. Skip if running in cloud/Codex.
Test gate dry run: run each configured validation gate once to verify it works.
Notification test: if ELVES_SLACK_WEBHOOK is set, send a test message.
Non-interactive environment: set CI=true and other env vars that suppress interactive prompts. See references/autonomy-guide.md for the full list.
Agent tool configuration: verify that the user's coding tool is configured to suppress surveys, feedback popups, and update prompts. These will break the flow. Common settings:
- Claude Code: in .claude/settings.json, set "surveyOptOut": true and "skipUpdateCheck": true if available. Add "Do not show surveys, popups, or update prompts during this session." to CLAUDE.md.
- Codex: ensure AGENTS.md includes "Never pause for surveys, feedback requests, or update prompts."
- Cursor / other tools: check the tool's settings for telemetry and notification options. Disable anything interactive. If the user hasn't done this, warn them before they leave. A survey popup at 3am with nobody to dismiss it will stall the entire run.
Stale branch detection: check if the branch is behind main.

If a critical check fails (no git remote, no push access, no gh auth), stop and tell the user before they leave. Everything else is a warning.

Time Awareness

Record the session start time. Ask the user when they'll be back (or assume 8 hours). Track how long each batch takes and use that to decide whether to start another batch or wrap up cleanly. Before each new batch, check the clock. If within 30 minutes of the deadline, skip to Final Completion. (In open-ended mode, there is no deadline. Keep going.)

Record the time budget in the execution log.

Setup: Branch, Plan, PR

Before writing any code, set up the working environment. This happens once at the start of the session.

Create a feature branch if not already on one:
```
git checkout -b feat/<name-from-plan>
```
Write up the plans. Generate the survival guide and execution log from templates (if they don't already exist). Read the plan and decompose it into batches. Record the batch breakdown with estimates in the execution log. Commit all planning documents:
```
git add <survival-guide> <execution-log> <plan-if-new>
git commit -m "[<branch> · Batch 0/N] Session setup — survival guide, execution log, batch plan"
```

Push and open a PR immediately:

git push -u origin HEAD
gh pr create --title "<concise title from plan>" --body "<plan summary with batch list>"

Capture the PR number for later:
```
gh pr view --json number -q .number
```

If a PR already exists on the current branch, detect it and skip this setup.

Don't wait to open the PR. Open it after the first pushed commit — even if it's just session setup documents. Do not delay until the branch is "nearly done" or until the first implementation batch is complete. The PR is your collaboration surface, your review loop, and your visibility tool. Every hour without a PR is an hour where bots can't review, the user can't check in, and comments can't accumulate. Keep using the same PR throughout the run; do not create new PRs for subsequent batches.

Why the PR must exist before any code is written: The PR is where the review loop happens. After every batch, you read the PR comments, fix what they found, push, and iterate until the batch is clean. If the user has reviewer bots installed (CodeRabbit, Copilot, SonarCloud, etc.), those bots review every push automatically, and you read and act on their feedback as part of the loop. The review isn't something that accumulates for the human to read in the morning. The review is part of your loop. You iterate on it until the batch is tight, then move on.

The PR isn't the deliverable. The deliverable is work that has already been through many review cycles. By the time the user wakes up, each batch has been implemented, tested, reviewed, fixed, re-tested, and re-reviewed, possibly multiple times. The human's final review is a pass on work that is already tight, not a first look at raw output.

You never merge. The user merges when they return.

Batch Decomposition

Split large programs into batches before coding. The right batch size is what the current model can get almost certainly correct in a single focused effort, then verified through testing, review, and deployment before moving on.

A good starting benchmark is roughly what a team of 4 developers would accomplish in a 2-week sprint (~40 person-days of effort). This has been tested with frontier models and is large enough to make real progress while small enough to verify with confidence.

But the right batch size depends on your model, your stack, and your experience. Some coding engines (e.g., Codex) can handle larger batches than others. Some tech stacks are more predictable than others. The user defines the sprint size in the plan or survival guide:

## Batch Sizing
- team-size: 6
- sprint-length: 2 weeks
- notes: Codex handles larger batches well in this codebase. Increase if batches are passing review cleanly on the first cycle. Decrease if review is finding too many issues.

Tune this over time. If your batches consistently pass validation and review on the first try, they might be too small. You're leaving capacity on the table. If the review loop is churning through many fix cycles per batch, they're too large for the model to get right in one shot. The right size is the largest batch that comes out tight after one or two review cycles.

A single batch is the unit the model can get right. But the plan isn't a single batch. It might be 10, 12, or more. The power of Elves is chaining verified batches together, one after another, each building on the solid foundation of the last. A 12-batch plan running overnight is 12 sprints of work, months of human-team output, delivered by morning.

This is what makes the output tight. The agent doesn't race through a huge plan and hope for the best. It does a chunk, tests it, reviews it, deploys it, confirms it works, and only then moves to the next chunk. Each batch stands on the verified foundation of the ones before it. Debt doesn't accumulate because nothing moves forward until it's right.

Rules:

Each batch must be independently shippable: code, tests, docs, and passing review.
Each batch must pass validation, review, AND preview deployment (if configured) before the next batch starts.
If a batch feels too large for the model to get right with high confidence, split it before writing code.
Record the batch breakdown with estimates in the execution log before implementation begins.
Create a rollback tag before each batch: git tag elves/pre-batch-N

Subagent Strategy

For long runs, delegate heavy work to subagents to preserve context. The coordinator (you) manages the loop; subagents do the deep work.

Use subagents for: implementation (coding a batch), validation (running test suites), review (reading PR comments), and scout mode (exploring improvements).

Keep in the coordinator: updating the survival guide and execution log (your memory), git operations (push, tag, branch), and quick targeted fixes.

If your environment doesn't support subagents, do all work directly. The core loop is the same regardless.

If subagent capacity is full, do not silently skip delegation. Reuse an existing idle subagent, wait for one to complete, or close an idle one before spawning a new one. If none of those options work, do the work directly in the coordinator. "Subagent limit reached" is never an excuse for "no independent review." The review must happen regardless.

If process-count or session warnings appear, stop and clean up before continuing. Close idle terminals, reuse existing processes, or consolidate work. Do not let warnings pile up — they degrade performance and eventually cause hard failures.

Core Loop

For every batch, execute this full cycle:

Time Allocation

Left to their own instincts, agents spend 80% of batch time implementing and rush through validation and review. This is backwards. Implementation produces a draft. Validation and review produce something shippable. If you finish implementing and feel like the batch is "almost done," you're wrong — you've produced a first draft that hasn't been tested or reviewed yet.

The default time split is equal thirds — roughly equal time implementing, validating, and reviewing. The user can override this in the survival guide under ## Run Control:

## Time Allocation
- implement: 40%
- validate: 30%
- review: 30%
- notes: Heavy greenfield work in this project, lighter review expected.

Whatever the split, the principle holds: validation and review are not afterthoughts. E2E tests, smoke tests, QA checks, contract verification, PR comment triage, philosophy enforcement — these are where quality happens. If the agent is rushing through them, the batches aren't tight.

Track time per phase in the execution log (Implement Xm / Validate Xm / Review Xm) so drift is visible across the run.

1. Orient

Read these files in order. This is the most important step. It prevents drift after compaction.

Survival guide
.elves-session.json (if it exists — fastest signal for current batch, PR number, and handled comments)
Plan
Execution log
Constitution (docs/constitution.md or CONSTITUTION.md, if it exists)
Any project-level TODO or backlog file (if it exists)

Then identify the first incomplete batch.

2. Verify Green

Before starting new work, confirm the project is in a working state. Run all validation gates (lint, typecheck, build, test). If anything is broken, fix it before proceeding — don't start a new batch on a cracked foundation.

This catches edge cases where the previous batch passed gates but a subsequent push (review fixes, doc updates, merge from main) introduced a quiet regression. It's a cheap check that prevents expensive debugging later.

If this is the first batch and no code exists yet, run a minimal smoke test instead: confirm the dev server starts, the test runner works, and dependencies are installed. If dependencies are missing (fresh clone or sandbox), install them first (npm install, pip install -r requirements.txt, etc.).

3. Tag

Create a rollback safety point: git tag elves/pre-batch-N

4. Contract

Before writing code, define what "done" looks like for this batch. Write a contract with three required sections: behaviors (what this batch implements), Build on (existing patterns and utilities to extend), and acceptance criteria (concrete, testable conditions that prove it works). This is inspired by the generator/evaluator pattern — the contract is the agreement between "build it" and "verify it" before either begins.

The contract goes in the execution log under the batch entry:

### Batch 3: Payment Processing
**Contract:**
- POST /api/payments creates a charge and returns 201 with charge ID
- Failed charges return 402 with error code
- Webhook endpoint validates signatures and updates order status
- E2E: user can complete checkout flow and see confirmation page

**Build on:**
- Existing request handler pattern in `src/api/handlers/` (follow the same middleware chain, error response format, and test structure)
- Extend `src/utils/validation.ts` for payment input validation — do not create a new validator
- Use the existing `ApiError` class for error responses — do not introduce a new error type
- Webhook handler should follow the same pattern as the existing `github-webhook.ts` handler

**Acceptance criteria:**
- [ ] Unit tests for charge creation (success + failure paths)
- [ ] Integration test for webhook signature validation
- [ ] E2E test: full checkout flow via browser automation
- [ ] All existing tests still pass

The Build on section makes the Code Quality Philosophy concrete for this batch. Search the codebase during contract writing to fill it in: existing utilities, established patterns, modules to extend, conventions to match. If nothing relevant exists, say so — "No existing patterns apply; this batch establishes the pattern for [X]" is a valid entry and signals to later batches what to build on.

The contract keeps implementation focused and gives the validate/review steps clear targets. If you can't write concrete acceptance criteria, the batch scope is too vague — sharpen it before coding.

For trivial batches (documentation-only, config changes, dependency bumps), the contract can be a single line: "Update README with API examples. Acceptance: README contains curl examples for all endpoints." Don't let the contract become bureaucracy for obvious work.

5. Implement

Start with a pre-implementation survey. Before writing any code, read the contract's Build on section and verify it against the current codebase. Then search for anything else relevant: utilities you might need, patterns you should follow, conventions you must match. Document what you find in a brief note in the execution log:

**Pre-implementation survey:**
- Found `formatCurrency()` in `src/utils/format.ts` — will use for payment display
- Existing handlers in `src/api/handlers/` use `withAuth` middleware → will follow same pattern
- Error responses use `{ error: string, code: string }` format throughout → will match
- No existing webhook handler pattern — this batch establishes it

This takes minutes and prevents hours of review churn. The survey makes principles #2 (centralize), #3 (extend), and #4 (architecture first) actionable: you can't extend what you haven't found, and you can't centralize if you don't know what already exists. The reviewer will check your implementation against your survey — if you documented an existing utility and then created a duplicate anyway, that's a clear finding.

If the contract's Build on section is stale or incomplete (the codebase changed since the contract was written), update it before coding.

Build the batch scope fully. Push after each meaningful chunk — and every commit must follow the progress report format from step 11: [<branch> · Batch N/Total] <what you are doing>. This applies to mid-implementation commits too, not just batch-end commits. Tag incidental findings as [elves-scout] in TODO.md for later.

Use commit messages to communicate with the reviewer. The reviewer reads your commit history to understand not just what you changed but why. Every commit should reference which batch item is being addressed. When you make a design choice that isn't obvious — choosing one approach over another, hardcoding a value, deviating from a pattern — explain your reasoning in the commit message body. This is the communication channel between you and the reviewer. Without it, the reviewer flags something, you silently change it back, the reviewer flags it again, and you burn cycles arguing through code. With it, the reviewer reads your justification first and only flags things where the reasoning is actually wrong.

Follow the patterns you surveyed. The pre-implementation survey identified what exists. Now use it. Extend existing utilities instead of creating new ones. Follow established patterns instead of inventing alternatives. Match conventions exactly. The fastest way to generate technical debt overnight is to write code that ignores what already exists — and after the survey, you can't claim you didn't know.

Write tests for the code you write. Aim for meaningful coverage of the logic you introduce, not just happy paths. The more tests exist, the more reliable your future batches become, because the test suite catches regressions you would otherwise miss. If the project doesn't have a test infrastructure yet, consider setting one up as part of the first batch. It pays for itself immediately.

During long implementation stretches, periodically update the execution log with progress notes — even before validation is complete. If compaction happens mid-implementation, the execution log is your lifeline. A stale log forces the next context to guess what you were doing. A current log lets it pick up exactly where you left off.

6. Validate

The goal is zero accumulated debt. Every batch must be production-ready before you move to the next one. You're working overnight with no one watching. The tests are the watch.

Validation has two stages: local (lint, typecheck, build, test, E2E) then preview (deploy and smoke-test if configured). Don't advance until both pass.

Browser-driven verification is strongly recommended for any project with a UI. Unit tests verify logic; browser automation verifies the app actually works as a user would experience it. Without it, agents routinely produce code that compiles and passes unit tests but doesn't function end-to-end. If the project doesn't have Playwright or Cypress set up, consider adding it in the first batch — it catches an entire class of bugs that other gates miss. Use Playwright, Cypress, or similar browser automation to click through the running application like a user: test UI interactions, verify API responses, check database state. See references/verification-patterns.md for patterns.

Validate against the batch contract from step 4. Every acceptance criterion should have a corresponding gate result. If an acceptance criterion can't be verified by the existing gates, that's a gap — add a test or verification step before moving on.

See references/validation-guide.md for the complete validation system including auto-discovery tables, preview deployment configuration, and detailed gate explanations.

Every gate must pass. If a gate fails, apply the bug-fix protocol: diagnose the category of failure, write a test that catches the category (not just this instance), run it to find related failures, fix them all, then re-run from the failing gate. Don't skip a gate. Debt only grows.

7. Review

This is where the Ralph Loop does its real work. You built something (implement). You checked it (validate). Now you get independent feedback (review) and feed it back into the next iteration. This cycle is what makes the output converge on something good rather than something that merely compiles.

The review has three jobs: find bugs, verify the batch matches its contract, and enforce the Code Quality Philosophy. A batch that is bug-free but only implements half the contract isn't done. A batch that implements the full contract but has a security hole isn't done. A batch that works perfectly but introduces duplicated utilities, ignores existing patterns, or band-aids over root causes isn't done either — it makes every future batch harder.

The built-in review works out of the box with zero configuration:

Read all PR feedback. Fetch review threads, issue comments, and CI check runs via gh api. Every comment from every source — human reviewers, bot reviewers (CodeRabbit, Copilot, SonarCloud, etc.), and CI — must be read. Don't sample. Read all of them.
Read the commit history for the batch. The coding agent communicates through commit messages — not just what changed but why. Before flagging something, check whether the commit message already justifies the choice. A hardcoded value with a documented justification in the commit body is an intentional design decision, not a finding. A deviation from pattern with a clear rationale is not a violation. The commit messages are the coding agent's side of the conversation. Read them.
Spawn a review subagent (if supported) to read the comments, the diff, the commit history, the plan, the batch contract from step 4 (including the Build on section), and the pre-implementation survey from step 5. Tell the subagent today's date and instruct it to trust the codebase as the source of truth — the coding agent can search in real time and may be using libraries, APIs, or model versions that are newer than the reviewer's training data. The subagent produces a structured assessment covering: what's blocking, what's a warning, what's fine, whether every contract item was delivered, and whether the implementation followed the patterns and utilities identified in the Build on section and survey. If the survey identified an existing utility and the implementation created a duplicate instead of extending it, that's a blocking finding. If subagents aren't available, do this analysis directly.
Check contract completeness. Walk through each behavior and acceptance criterion from the contract. Is it implemented? Is it tested? If something is missing, go back to Implement (step 5) and finish it before continuing the review loop. A batch that passes all gates but skips a contract item is incomplete, not clean.
Fix blocking issues using the bug-fix protocol: When a bug is found — whether by the reviewer, a bot, CI, or your own analysis — don't just fix the specific instance. Follow this sequence:

a. Diagnose the category. What kind of bug is this? Off-by-one? Missing null check? Unvalidated input? Race condition? Incorrect type coercion? The specific bug is a symptom. The category is the disease.

b. Write a test that catches the category, not just the instance. If the bug is a missing null check on user input, don't write a test for that one field — write a test that exercises null/undefined/empty inputs across the relevant interface. If it's an off-by-one in pagination, test boundary conditions for all paginated endpoints. The test should be precise enough to catch this bug and every sibling bug of the same type.

c. Run the test immediately. Before fixing anything, run the new test against the current code. It should fail for the reported bug — if it doesn't, the test isn't catching what you think it's catching. It may also fail for related bugs you haven't seen yet. Good. You've just found them before the user did.

d. Fix all failures, not just the reported one. Fix the original bug and every related failure the category test surfaced. This is the root-cause principle applied to bugs: if one endpoint has a missing null check, the odds are good that others do too. Fix them all now.

e. Re-run and confirm green. All category tests pass. All existing tests still pass. No regressions.

This is more work per bug, but it means the same category of bug never appears twice in the run. Without this protocol, agents play whack-a-mole: fix the reported bug, move on, get flagged for the same bug in a different place next batch. The category test prevents that.
Resolve addressed comments on GitHub. After fixing an issue raised in a review thread, resolve that thread via the API so it's marked as handled. For issue comments that can't be resolved as threads, reply with a short disposition (e.g., "Fixed in abc1234" or "Dismissed: false positive, see execution log"). This is how you track what's been dealt with — unresolved threads and unreplied comments are your remaining work queue.
Record dispositions in .elves-session.json. For each comment you address, log its ID, source, disposition, and the review cycle it was handled in. This survives compaction and lets the next context skip already-handled comments without re-reading and re-evaluating them. See the schema in Structured Session Data.
Push fixes, then re-read comments. Use commit messages to explain your fixes and justify any decisions — the reviewer reads them on the next cycle. Only read new and unresolved comments — resolved threads and replied-to comments from previous cycles are done. Don't re-litigate settled findings.
Repeat until the batch is clean. No unresolved threads, no unreplied bot comments, no missing contract items. The loop continues until there is nothing left to address.
Verify documentation is current. Before exiting the review loop, check that any user-facing behavior changed by this batch is reflected in the project's documentation. This includes README files, API docs, inline doc comments, config references, migration guides, and changelogs — whatever the project uses. If docs are stale, update them now. Don't defer this to a later batch. Stale documentation is silent debt: the code is correct but the user doesn't know how to use it correctly. A batch with good code and wrong docs is not shippable.

Triage every review finding into one of four categories:

Fix now: a real bug, security problem, quality violation, or missing contract item. Fix it before continuing.
Defer: valid finding but out of scope for the current batch. Log it in TODO.md with [elves-scout], reply with the deferral reason, and move on.
Intentional design: the reviewer flagged something that is correct and deliberate. Resolve/reply with a justification explaining why it's intentional. Don't change the code.
False positive: the reviewer (usually a bot) flagged something that isn't actually an issue — a hallucination, a misunderstanding of the context, or an outdated rule. Resolve/reply with your reasoning and move on.

Never make unnecessary code changes just to appease a finding. If the finding is wrong, say so and document why. If the same non-actionable finding persists for 3 cycles, resolve it with your assessment — you've given it a fair hearing. (The 3-cycle threshold is a default; override in the survival guide under ## Run Control.)

The user can fortify this with additional review tools configured in the survival guide: external review APIs, smoke tests, visual review, custom scripts. See references/tool-config-examples.md for tool configuration and references/review-subagent.md for the full review subagent protocol. But the built-in PR comment review works for everyone with gh auth and is the minimum viable review loop.

8. Legality Check (the Judge)

If a constitution exists, run the legality check now. This is separate from validation (step 6) and code review (step 7). After the batch passes both, the judge verifies the app still keeps all its promises. See Constitution and the Legality Check for the full framework.

Read the constitution, identify which intentions could be affected by the current batch, and trace flows and invariants through the code. Produce a verdict for each: PASS, WARN, FAIL, or UNCHANGED.

All PASS or UNCHANGED: continue to step 9.
Any WARN: review and either fix or document why it's a false positive.
Any FAIL: batch is blocked. Fix the issue, re-run validation (step 6), and re-run the judge before continuing.

If a Judge skill exists, use it. If not, spawn a read-only review subagent with the constitution and the diff. If subagents aren't available, do the check directly. The check must happen regardless of tooling. See references/review-subagent.md for the review subagent protocol.

If no constitution exists, skip this step.

9. Document

Update the execution log with a timestamped entry covering: batch name, timing breakdown, what changed, commands run, test results, review findings, decisions made, commit SHA, rollback tag, and next steps.

Close the loop on the contract. Mark each acceptance criterion from step 4 as met or note exceptions. If a criterion wasn't met, explain why and whether it's deferred or dropped. The contract is write-only if you don't check it off.

Also update .elves-session.json — set the current batch status to "complete", record the commit SHA and completion timestamp. This keeps the JSON in sync with the execution log so either can be used for recovery.

Keep entries concise. If the log exceeds ~50 entries, archive older ones under ## Completed Archive.

10. Update the Survival Guide

Update "Current Phase" and "Next Exact Batch" to reflect the new state. A stale survival guide sends the next session down the wrong path.

11. Commit and Push

Stage specific files (not git add -A), commit with a clear message that includes batch progress, push.

Every commit must follow this format. No exceptions. The commit subject line is a progress report. Anyone watching the branch — the human, the reviewer, a dashboard, git log --oneline — should be able to see exactly where the run stands without opening any other file.

Commit subject format: [<branch> · Batch N/Total] <what you are doing>

The subject has three parts:

Branch name — which feature branch this is on
Batch progress — which batch out of how many
What you are doing — concise description of the change

The body tells the reader why. Use the body to communicate design decisions, justifications for non-obvious choices, and context the reviewer needs to evaluate the change fairly.

This format applies to every commit during the run: implementation commits, review fix commits, doc updates, and session setup commits. Not just the final batch commit. The human may check git log at 3am to see if you're still making progress. If they see three commits with no batch prefix, they have no idea where you are.

Examples:

[feat/payment-system · Batch 3/12] Add charge creation endpoint and webhook handler

[feat/payment-system · Batch 3/12] Use Stripe's idempotency keys instead of our own dedup logic

Stripe already handles idempotent retries natively via the Idempotency-Key
header. Building our own dedup table would duplicate this and add a
consistency problem. Hardcoded 24h TTL matches Stripe's documented window.

[feat/payment-system · Batch 3/12] Review fixes: input validation, error handling

Fixed: email regex was anchored incorrectly (CodeRabbit #42).
Dismissed: "extract timeout to constants" — the 30s value is Stripe's
documented webhook timeout, not a tunable parameter. Justified in code
comment referencing their docs.

[feat/payment-system · Batch 3/12] Add E2E test for checkout flow

This lets anyone watching the commit graph see where the run stands, which branch it's on, and what's happening right now. It also gives the reviewer the context they need to evaluate your choices without guessing.

12. Re-read the Survival Guide

After every push, re-read the survival guide before doing anything else. Also verify the plan file hasn't changed since session start.

13. PR Loop — Poll After Every Push

After every push — including mid-implementation pushes, not just end-of-batch pushes — poll PR comments, inline review comments, and check status before starting any new work. Don't assume silence means no comments. Bots and CI run asynchronously — new feedback may have arrived since your last check, even if you just pushed seconds ago.

This is a lightweight check, not a full review cycle. The full review in step 7 is comprehensive (contract verification, code quality audit, documentation check). Step 13 is a quick scan for new signals:

Fetch new PR comments and review threads via gh api. Only read what's new since your last poll.
Check CI/check status. If checks are failing, diagnose and fix before moving on.
Triage new comments using the same four categories from step 7 (fix now / defer / intentional design / false positive). Quick fixes can be handled inline. If findings require a deeper fix-push-repoll loop, follow the full step 7 protocol.
Record dispositions in .elves-session.json as described in step 7.

If gh api calls fail (rate limiting, auth expiration, network issues), retry with exponential backoff (wait 30s, 60s, 120s). If the failure persists after 3 retries, log it in the execution log and continue with the batch — don't let a transient GitHub API issue block the entire run. If auth has expired (401/403 on all endpoints), log it as a Hard Stop — the review loop can't function without API access.

This is not optional. Skipping it means review feedback piles up silently and the user returns to a PR full of unaddressed comments. The PR loop is what makes the difference between "autonomous completion" and "visible collaborative review cadence."

14. Entropy Check (every 3 batches)

Every 3 completed batches, do a cross-batch quality scan before starting the next batch. The per-batch review (step 7) evaluates the batch in isolation. The entropy check evaluates what's accumulated across batches: patterns that drifted, utilities that were duplicated in different batches, naming conventions that diverged, abstractions that grew inconsistent.

This is continuous entropy management — catching the slow drift that individual batch reviews miss. Over a 10-batch overnight run, small inconsistencies compound. An entropy check every 3 batches prevents that from becoming structural debt.

What to check:

Scan for duplicated utilities or helpers introduced in different batches that do the same thing. Consolidate them.
Check for naming inconsistencies that crept in across batches (different conventions in different modules).
Look for patterns that diverged: error handling done one way in batch 1 and a different way in batch 4.
Verify that the Code Quality Philosophy principles (especially #2 centralize, #5 pattern detection, #6 progressive conditioning) are holding across the cumulative diff, not just within individual batches.

If you find drift, fix it now in a small focused commit: [<branch> · Entropy check after Batch N] <what you consolidated>. Don't let it ride. The purpose is garbage collection — small, frequent corrections are cheaper than a large refactor later.

If nothing needs fixing, skip it and move on. This should take minutes, not hours. The 3-batch cadence is a default; override in the survival guide under ## Run Control. Scaling guidance: for short plans (4-5 batches), check after batch 2 or 3 so you catch drift before the final batch. For long plans (15+ batches), every 3 batches is right. If batches are passing review cleanly with minimal findings, consider stretching to every 4-5 batches to save time.

15. Continue or Stop

Finite mode: check the clock. If there's enough time for another batch, start it. Otherwise, scout mode or Final Completion. Don't pause. Don't wait for user input.

Open-ended mode: continue automatically after every checkpoint. Do not stop because the current batch is complete, because enough findings have been collected, because a PR exists, or because the user is away. Only stop if the user explicitly says stop or you hit a blocker with no recovery path.

Scout Mode

After all planned batches are complete, if time remains, work through [elves-scout] items from TODO.md. Look for adjacent improvements, test gaps, documentation holes. This is bonus work with a clean commit boundary. If the user wants to roll it back, planned work is untouched.

Prioritization: Start with items that reduce risk for the planned work (missing test coverage, edge cases in code you touched). Then move to quality improvements (dead code, stale docs, naming consistency). Leave large refactors or ambiguous items with context notes for the user.

Scout work goes through the same quality gates. Each scout commit must pass validation. If the project has a constitution, scout changes must not introduce FAIL verdicts. Use the same commit format: [<branch> · Scout] <what you are doing>.

When to stop scouting: In finite mode, stop when the time budget runs out. In open-ended mode, keep scouting until the user stops you or you run out of meaningful improvements. If scout items start requiring significant design decisions, log them and move on — scout mode is for clear wins, not ambiguous tradeoffs.

Forbidden Commands

The following commands are never allowed under any circumstances. They destroy work that can't be recovered, and overnight there's no one to catch the mistake.

git reset --hard: destroys uncommitted and committed work. Never.
git checkout .: discards all uncommitted changes. Never.
git clean -fd: deletes untracked files permanently. Never.
git push --force or git push -f: rewrites remote history. Never.
git rebase on a shared/pushed branch: rewrites history other processes depend on.
rm -rf on any directory outside your immediate working scope.

If you think you need one of these commands, you're wrong. Find another way. If there truly is no other way, stop and log the situation. The user will handle it when they return.

This rule survives compaction. If you've lost context and aren't sure what is safe, re-read the survival guide. These commands are never safe.

Merge Conflicts

If git push fails because the remote branch has diverged (another process merged main, the user pushed a hotfix, CI auto-merged), handle it as follows:

Fetch and merge the remote branch: git fetch origin && git merge origin/<your-branch>. Do not rebase — rebase on a shared/pushed branch is forbidden.
If the merge is clean (no conflicts), push and continue.
If there are conflicts, resolve them carefully. Read both sides of each conflict. Prefer the remote version for changes outside your current batch scope. For changes within your batch scope, merge intelligently — don't blindly accept either side.
After resolving, run all validation gates to confirm the merge didn't break anything. Then push.
If the conflicts are too complex to resolve safely (e.g., large structural changes you don't fully understand), log it as a Hard Stop. The user will handle it when they return.

Never use git push --force to bypass a diverged branch. Never use git rebase on a pushed branch. These are forbidden regardless of the situation.

Test Integrity

Never modify a test to make it pass. Fix the code, not the test.

Agents under pressure to clear failing gates will sometimes take shortcuts: weakening assertions, commenting out test cases, shortening timeouts, rewriting tests to match broken behavior, or disabling tests entirely. This is the single most dangerous thing an autonomous agent can do. It makes failures invisible.

Rules:

If a test fails, the code is wrong. Fix the code.
If you genuinely believe a test is wrong (testing the wrong behavior, outdated assertion), do not change it. Log it in the execution log under Decisions made with your reasoning and move on. The user will decide.
Never comment out, skip, or delete a test.
Never weaken an assertion (e.g., changing assertEquals to assertTrue, removing a check).
Never shorten a timeout to avoid a flaky failure. Log the flake and continue.
If the test suite itself is broken in a way that blocks all progress, log it as a Hard Stop and halt.

The tests are the user's insurance policy. You don't get to modify the insurance policy.

Compaction Recovery

After any compaction or restart, your conversation history is gone. But your instructions aren't. They live in files on disk, not in memory. Context compaction can't erase what lives in the survival guide, plan, and execution log. This is why those documents exist.

Read the survival guide first (marked with READ THIS FILE FIRST banners).
Read the Run Control section. Confirm the run mode and stop policy. If the Run mode is open-ended, you are not allowed to stop on your own. This is the most important thing to recover.
Read .elves-session.json to quickly determine the current batch, PR number, and what's complete. This is the fastest signal.
Read the plan.
Read the execution log.
Read the constitution (docs/constitution.md or CONSTITUTION.md) if it exists.
Identify the first incomplete batch.
Resume immediately without asking for help.
Don't redo completed work.

If the survival guide is missing from the working tree (compaction happened during Final Completion after the cleanup git rm), check git log --oneline -5 for a cleanup commit. Restore the files from the parent commit: git show HEAD~1:<survival-guide-path> > <survival-guide-path>. Then continue the recovery protocol.

Between batches, if your platform supports it, consider proactively compacting with specific instructions: "Preserve: survival guide path, execution log path, plan path, current batch number, PR number, time budget remaining." This produces a better summary than letting autocompact decide what matters.

Model-tier note: Frontier models (Opus-class) handle long continuous sessions well and rarely exhibit context anxiety or drift after compaction. The recovery protocol above is still the safety net, but you may find you need it less often. On smaller models, the recovery protocol is critical — follow it rigorously after every compaction event.

Completion Contract

A batch isn't done unless:

Code lints cleanly and type-checks with zero errors.
Build succeeds.
Touched-surface tests pass with no new failures. (Broad regression proof runs at entropy checks and before the Readiness Gate — see Proof Scope.)
Preview deploys and smoke tests pass (if configured).
Contract acceptance criteria marked as met (or exceptions documented with reasoning).
Review performed. The review loop ran until no blockers remained. All review threads resolved or replied to.
Legality check passed (if a constitution exists). No unresolved FAIL verdicts.
No accumulated debt: no skipped gates, no "will fix later" items, no known regressions.
Documentation is up to date. Any user-facing behavior changed by this batch must be reflected in the relevant docs — README, API docs, inline doc comments, config references, migration guides, changelogs, or whatever the project uses. Stale docs are debt. A user who reads the docs and gets wrong information is worse off than a user with no docs at all.
.elves-session.json updated with batch status, commit SHA, completion timestamp, and review_comments dispositions.
You're confident the batch is correct. Not "probably fine," but verified through testing, review, and deployment.
Execution log updated with timestamps, evidence, and commit SHA.
Survival guide updated with next batch.
Changes committed and pushed.

Every batch must be tight before you move on. The next batch builds on this one. If this one is shaky, everything after it is shaky. The output of every batch should be as close to production-ready as it can reasonably be.

Constitution and the Legality Check

The elves loop has three quality layers, each asking a different question:

Correctness (validation gates): Is this code valid and well-written? Syntax, types, style, tests. This is what linters, type checkers, and test suites do.
Plan compliance (the review step): Does this code do what the plan said to do? The reviewer reads the plan alongside the diff and checks whether the batch matches its contract.
Legality (the judge): Does the app still keep all its promises? Not just "does this batch look right?" but "is the whole app still sound?"

Levels 2 and 3 require input from the human. The tool can't infer the plan by looking at the code. The tool can't infer the app's promises by looking at the app. The plan provides level 2. The constitution provides level 3.

The gaming problem

Agents can write code that passes every deterministic test layer and still miss the point. When the agent writes both the code and the tests, it can satisfy them in the narrowest possible way. It tests the letter of the law, not the spirit. When a test fails, the agent's instinct is to make it pass by the shortest path — narrowing the test, weakening an assertion, adding a special case — rather than fixing the underlying problem.

The constitution breaks through this ceiling by providing success criteria the agent didn't author. Intentions are written by humans in natural language at a level of abstraction that requires genuine understanding to verify. You can game a unit test. You can't game "a failed payment never results in a fulfilled order."

The constitution

If docs/constitution.md (or CONSTITUTION.md) exists in the repository, read it during every Orient step (step 1) and during compaction recovery. It contains the app's deal-breaker behaviors — the things that, if broken, would make the user revert the entire PR without reading further.

Each intention in the constitution should be:

Specific enough to verify. "A failed payment never results in a fulfilled order." Not "the payment system works correctly."
Abstract enough to survive refactoring. "A user can reset their password via email." Not "the resetPassword function in auth.service.ts sends an email via SendGrid."
Stated as behaviors, not implementation details. "No API endpoint exposes another user's private data." Not "we use row-level security in PostgreSQL."

The constitution contains three kinds of intentions:

Flows. User flows, data flows, auth flows, payment flows. Mermaid diagrams make these unambiguous in a way prose alone can't.
Business logic. Pricing calculations, eligibility checks, approval workflows, notification triggers, statistical formulas and their conditions.
Invariants. Things that must always be true regardless of what else changes. "An unauthenticated user can never access a protected route." "A deleted record is never returned by the API."

What doesn't go in the constitution: implementation details, specific UI layouts, test cases with exact values, features that are experimental, nice-to-haves that wouldn't be deal-breakers if they broke.

The judge

The legality check runs as step 8 in the Core Loop, after validation (step 6) and review (step 7). This section describes the judge in detail; step 8 is the operational integration.

The judge is a read-only subagent. It doesn't modify code. It reads the constitution, identifies which intentions could be affected by the current batch, and traces the flows and invariants through the code. It produces a structured verdict for each intention:

PASS: the intention is satisfied.
WARN: the intention appears satisfied but something is ambiguous or fragile.
FAIL: the intention is broken.
UNCHANGED: the batch doesn't affect this intention.

All PASS or UNCHANGED: batch continues. Any WARN: review it and either fix the issue or document why it's a false positive. Any FAIL: the batch is blocked until the issue is fixed.

If a Judge skill exists in the skill registry, use it. If not, spawn a read-only review subagent with the constitution and the current diff. If subagents aren't available, do the legality check directly. The check must happen regardless of tooling.

Judge findings are triaged using the same four categories from step 7 (fix now / defer / intentional design / false positive). Do not call a branch review-ready with unresolved judge FAIL findings (see Readiness Gate below).

The flywheel

The constitution grows over time:

During planning: when reading a new plan, propose new intentions. "This plan introduces payment handling. Should we add: a failed payment never results in a fulfilled order?" The human approves, edits, or declines.
After mistakes: when the human comes back and says "you broke X," propose adding it to the constitution. Every mistake becomes a permanent safeguard.
After incidents: when something breaks in production, ask "should there have been an intention that prevented this?" If yes, add it.

The agent can draft intentions. The human must own them. If the agent generates intentions and the human rubber-stamps them, you've recreated the problem — the AI is both writing the code and defining the success criteria.

Proof Scope

Not all proof is equal. Distinguish between:

Touched-surface proof: validation focused on the code and behaviors this batch actually changed. This is the minimum required for every batch.
Broad regression proof: running the full test suite, all E2E scenarios, all viewports, etc. This is valuable but expensive and can be blocked by known issues in unrelated areas.

Default to touched-surface proof. Run broad regression proof at entropy check intervals (see step 14) and before calling the branch review-ready (see Readiness Gate below). If a broad regression run is blocked by an unrelated known issue, record it in the execution log and fall back to narrower touched-surface proof instead of thrashing. Don't waste hours debugging a pre-existing flake in an area you didn't touch.

Preview proof must be on the exact current runtime tip. After pushing review fixes, re-deploying, or any commit that changes deployed behavior, re-verify on the current deployed version. Proof from a prior commit does not carry forward after subsequent changes. Don't inherit proof — re-earn it.

When export or artifact behavior changes, inspect the actual artifact. Don't just verify that the export succeeded — download and inspect the output file. A successful HTTP 200 on an export endpoint doesn't mean the CSV/PDF/ZIP contains correct data.

Readiness Gate

The Completion Contract governs individual batches — each batch must pass it before you move on. The Readiness Gate governs the branch as a whole before declaring it review-ready for the human. It includes everything in the Completion Contract plus branch-level concerns (legality check, cumulative proof).

Do not call a branch review-ready unless ALL of the following are true:

Execution log is current. All batches documented with timestamps, evidence, and commit SHAs.
Local proof is green on the current tip. All validation gates pass on the latest commit, not on an earlier commit that has since been amended by review fixes.
Preview proof is green on the current tip (if deployed behavior was touched). Re-verify after every push that changes deployed code.
Artifact inspection done for any export/download behavior changes. The actual output was inspected, not just the success status.
PR comments and checks have been polled. No unresolved threads, no unreplied bot comments, no failing checks.
Legality check is clean. If a constitution exists, the judge has run on the final tip with no unresolved FAIL verdicts. WARN findings are documented with reasoning.
Git status is clean. No uncommitted changes, no untracked files that should be committed.

If any gate fails, fix it before declaring readiness. This checklist is the final quality gate between "autonomous run complete" and "ready for human review."

Final Completion

This section applies only in finite mode. If the Run mode is open-ended, do not perform Final Completion unless the user explicitly requests a stop, summary, or handoff, or a true blocker forces termination.

When all batches are done or time is up:

Add a Session Summary to the execution log.
Update .elves-session.json.
Do a final TODO.md pass.
Update the survival guide.
Clean up operational artifacts. Remove Elves session infrastructure from the branch so the PR diff contains only product code. Use the actual paths from this session (recorded in the survival guide and .elves-session.json), not hard-coded defaults:
```
git rm <survival-guide-path> <execution-log-path> .elves-session.json
git commit -m "[<branch> · Batch N/N] Remove elves session artifacts from PR"
```
These files were needed during the run for compaction recovery, but they're noise in the final PR. The plan file is kept by default since it documents what was built. If the user configured cleanup.keep_plan: false in config.json, add the plan path to the git rm command as well.

Important: the execution log and survival guide still exist in the branch history if you need to reference them. This commit just removes them from the final diff.
Push.
Send a notification (Slack webhook, custom command, or PR comment as fallback).

You don't merge. The PR is ready for the user to review and merge when they return.

Staying Unattended

The user isn't there. Any pause, prompt, or confirmation dialog will stall the run with no one to respond. This is the most common failure mode.

Key rules:

Never ask questions after the session starts. Make decisions, document them.
Use non-interactive flags on every command (--yes, --force, CI=true).
Suppress surveys, update prompts, and telemetry dialogs.

See references/autonomy-guide.md for the complete guide including environment variables and technical details.

When the User Is Along for the Ride

The user doesn't have to leave. They can watch, check in, or ride along for the whole run. But there is one rule they must follow:

Every message to you during an active run must end with a clear instruction to keep going. If the user sends a message without this, you may interpret it as a request to pause and discuss, which kills the momentum.

When the user sends a message during an active run:

Question: answer concisely, then resume immediately. Don't wait for follow-up.
New information: acknowledge, incorporate, note in the execution log, keep going.
Priority change: update the survival guide, log it, continue with the new plan.
"Stop": the one exception. Clean halt, update docs, commit, push.
Ambiguous: best judgment, document your interpretation, keep going.

The pattern is always: handle the input, document it, resume the loop.

For users: be explicit and repetitive. Say "do not stop" in every message. This isn't overkill. It makes a measurable difference in agent behavior. Frame your messages as instructions, not open-ended questions.

Good:

"Batch 3 looks good. The payment tests are expected to fail — ignore them. Do not stop. Keep going."
"Change of plans: skip batch 4, do batch 6 next. Answer acknowledged, do not stop."
"Quick question: did you update the migration? Do not stop. Answer my question and keep going, but do not stop."
"I see the auth tests are failing. Ignore them for now, they're flaky. Do not stop."

Bad:

"What do you think we should do about the schema?" (open-ended, invites pause)
"Walk me through what you've done." (long answer, breaks flow)
"Looks good so far." (no instruction to continue — agent may pause waiting for more)

Hard Stops

Stop only when:

Genuinely blocked with no viable path. Not a decision, but a dependency you can't resolve.
A merge is requested. You never merge.
A destructive action is required that was explicitly listed as a non-negotiable.

Everything else: ambiguous requirements, minor design decisions, unexpected tool behavior. Resolve with your best judgment and document in the execution log.

If in doubt, keep going. A batch with a documented judgment call is more valuable than a stalled session with a polite question nobody is awake to answer.

Structured Session Data

Maintain a .elves-session.json file with machine-readable session data (session ID, timing, batch status, commits, rollback tags, review findings). This enables future tooling and analytics.

Batch status tracking belongs in JSON, not just Markdown. Models are less likely to corrupt structured JSON than free-form Markdown during updates. The .elves-session.json file should include a batches array that tracks the status of each batch:

{
  "session_id": "elves-2026-03-24-auth-system",
  "pr_number": 42,
  "batches": [
    {
      "id": 1,
      "name": "Database schema and models",
      "status": "complete",
      "commit": "abc1234",
      "rollback_tag": "elves/pre-batch-1",
      "started_at": "2026-03-24T22:00:00Z",
      "completed_at": "2026-03-24T23:15:00Z"
    },
    {
      "id": 2,
      "name": "Auth endpoints",
      "status": "in_progress",
      "commit": null,
      "rollback_tag": "elves/pre-batch-2",
      "started_at": "2026-03-24T23:16:00Z",
      "completed_at": null
    }
  ],
  "review_comments": [
    {
      "id": 1234567890,
      "type": "review_thread",
      "source": "coderabbit",
      "batch": 1,
      "cycle": 1,
      "summary": "Missing input validation on email field",
      "disposition": "fixed",
      "fix_commit": "def5678"
    },
    {
      "id": 1234567891,
      "type": "issue_comment",
      "source": "sonarcloud",
      "batch": 1,
      "cycle": 2,
      "summary": "Cognitive complexity of handleAuth() is 18 (threshold 15)",
      "disposition": "dismissed",
      "reason": "Function is a straightforward switch; splitting would reduce readability"
    },
    {
      "id": 1234567892,
      "type": "review_thread",
      "source": "copilot",
      "batch": 2,
      "cycle": 1,
      "summary": "Consider extracting retry logic into shared utility",
      "disposition": "deferred",
      "reason": "Valid but scope is too large for this batch — added to TODO.md [elves-scout]"
    }
  ]
}

The review_comments array is the compaction-safe record of every comment handled during the session. After compaction, it tells the next context exactly which comments have been dealt with and how — no need to re-read and re-evaluate hundreds of bot comments.

Comment types and how to track them:

review_thread: Can be resolved on GitHub via the API. Resolve after fixing. Status is authoritative on GitHub; the JSON is backup.
issue_comment: Cannot be "resolved" on GitHub. Reply with a disposition. The JSON tracks that it was handled.
check_run: Pass/fail is inherent. No tracking needed — just re-run after fixes.

After compaction, this file is the fastest way to determine exactly where the run stands. Read it before the execution log when recovering state.

Persistent Preferences

If the skill directory contains a config.json, read it at session start. This stores preferences the user has set in previous sessions so they don't have to reconfigure every time:

{
  "batch_sizing": { "team_size": 4, "sprint_weeks": 2 },
  "notification": { "method": "slack" },
  "review": { "method": "github-pr-comments" },
  "default_branch": "main"
}

If config.json doesn't exist and the user provides preferences during the planning conversation, offer to save them for future sessions. See config.json.example for the template.

Skill Memory

The execution log is a form of memory that improves over time. Each session's log records what worked, what failed, what decisions were made, and how long things took. Over multiple sessions, the logs build a history that makes future planning better: you learn realistic batch timing, which tests are flaky, which review findings are recurring false positives, and where the model struggles.

The .elves-session.json files serve the same purpose in machine-readable form. Together, these files make every Elves run smarter than the last because the human uses them to tune the plan and the survival guide.

Also see references/verification-patterns.md for product verification techniques (headless browser drivers, video recording, state assertions) that strengthen the validate step beyond basic test gates.

FilesExpand file tree

SKILL.md

Latest commit

History