Autopilot

/sonic-autopilot runs a full authority-site build start to finish in one session, hands-off. It is the zero-touch lane on top of the standard pipeline.

Why one session matters

The sandbox started in Step 1 must stay alive for the entire build. Autopilot never stops it and never exits until the build is done. Each page is built by a fresh sub-agent so it gets a clean context. That is the trick that lets Sonic build 150 pages without its own context window filling up, while the sandbox keeps running in the parent session.

The setup steps (1 through 6)

Autopilot front-loads the same brand-first work as the standard build, then hands the repetitive page-building to a loop.

1. Sandbox. Start a local WordPress site with sonic-sandbox, capture its localhost URL, and leave it running for the whole build.
2. Brand Philosophy 🧭. A real discussion seeded with your brand notes. Output BRAND-BRIEF.md.
3. Visual Identity 🎨. Decide colors, type, and imagery. Output STYLE-GUIDE.md with a responsive section.
4. Homepage + Sonic Boom 💥. Build and deploy the homepage with the 6-section architecture, lay the responsive foundation once in the shared theme stylesheet, generate the hero image, and test at 320 / 768 / 1440.
5. One template page 📄. A single complete service page that sets the bar.
6. Research scope and write the plan 🔭. Research the niche and SERP (using sonic-research for live SERP, People-Also-Ask, and local-pack data when the scraper is enabled), propose a page count and cluster map, then write build-plan.json and initialize progress.json with the homepage and template already marked done.

In full-auto mode the sign-off pauses become self-reviews. The brand-philosophy discussion still happens; only the approvals are skipped.

The Loop

This is the heart of autopilot. It reads build-plan.json and progress.json, finds every page not yet done, and builds them one at a time:

1. Launch a fresh sub-agent for exactly ONE page. It receives the page's {id, title, slug, cluster}, the sandbox URL, and the page-builder plus image settings. It follows the sonic-autopilot-page brief: read the brand brief and style guide, build and deploy that one page reusing the theme's responsive foundation (never re-deriving it), run seo-qa on just that page, and report back done plus QA, or failed plus a reason.
2. On return, update progress.json for that page, commit (git commit -m "autopilot: <slug>"), and print one line: [n/total] <title> ✓.
3. Guardrails. If SONIC_AUTOPILOT_MAX_PAGES is hit, stop and report (resumable). If 3 pages fail in a row, stop, something systemic is wrong (sandbox down, missing artifact), and the operator is told to check the log rather than burning the whole plan.

A fresh sub-agent per page means clean context every single time. If sub-agents are not available, autopilot falls back to building sequentially and trims its own context every ~8 pages.

Resume

Autopilot is fully resumable. Set SONIC_AUTOPILOT_RESUME=1 and it skips steps 1 through 6, reads the existing build-plan.json and progress.json, restarts the sandbox, and jumps straight to the loop for pages not yet done. Every major step is appended to .sonic/autopilot/autopilot.log, so any run is diagnosable.

Configuration (environment)

Autopilot is driven by environment variables:

Variable	Effect
SONIC_AUTOPILOT_INTAKE	JSON intake: niche, location, page builder, image style and provider, brand notes, brief, model, content language.
SONIC_AUTOPILOT_PROMPT	If set, the authoritative build brief. Overrides generic assumptions, even for non-standard builds like directories.
SONIC_SCRAPER_ENABLED	1 makes the mcp-scraper tools available, so sonic-research can harvest live SERP data in Step 6.
SONIC_AUTOPILOT_FULL_AUTO	1 skips the sign-off pauses and self-reviews instead.
SONIC_AUTOPILOT_RESUME	1 resumes an interrupted build straight into the loop.
SONIC_AUTOPILOT_MAX_PAGES	Caps the plan and this run's loop to N pages.

Finish

Autopilot prints a summary (pages built, failed, remaining, plus 3 to 5 sample sandbox URLs) and keeps the sandbox running so you can review. It never deploys to a live host. Going live is a separate, human-gated sonic deploy.

Autopilot hard rules

Never stop the sandbox mid-build. Never deploy to a live host. Never skip Brand Philosophy or the responsive foundation. One fresh sub-agent per page, update progress and commit after every page, log every step.