Opinionated Guardrails

Think of the guardrails like the bumpers in a bowling alley. You came here to knock down pins (ship software), not to spend the night fishing your ball out of the gutter. The bumpers stay up by default so you can throw with confidence.

A few of the most important ones, in plain language:

• No pushing straight to main. "Main" is the official, real version of your project. Every change has to go through a pull request first, which is a polite "here's what I changed, please look before it becomes official."
• Small changes, often. Sparkle nudges agents to keep each PR small so you (and the reviewer) can actually understand it.
• A spending cap. Each agent session has a built-in cost limit. If a job starts running away, Sparkle pauses it and asks you before spending more.
• A readiness score. Before anything ships, Sparkle grades it. A high score goes; a low score gets blocked so you don't release something half-built.

You don't have to memorize any of this. The rules just quietly do their job in the background, the same way a good co-pilot watches the instruments so you can fly.

Here's the leverage: you can point a fleet of parallel-agents at a problem and trust that none of them will nuke your main branch or empty your wallet while you grab coffee. The rules that earn their keep:

• PR-or-nothing. No direct pushes to main, no force-push to main, ever, enforced at the hook level. Agents land work through reviewed PRs or they don't land it at all.
• Fresh branches only. Every worktree is born from current origin/main. Branching off another agent's unfinished feature branch is blocked by default, so you never build a tower on top of sand.
• Land or split. When a branch grows past a size threshold, Sparkle nudges the agent to ship it or break it up. Small scoped PRs review fast and revert clean.
• $5 per-session cost cap. Blow past it and the agent pauses and fires a caution approval instead of silently grinding through your usage building something you didn't ask for.
• Production Readiness Gate. A 0 to 100 score gates the ship: 70 or above is allowed, 50 to 69 needs your explicit confirm, below 50 is blocked. No more "the agent said it was done" surprises in front of real users.

Use them as a floor, not a ceiling. Knowing you, you'd rather ship fast than babysit a runaway, and these are exactly the rails that let you do that.

The substance, terse:

• No direct pushes to main; feature branch + PR required. No force-push to main, ever, enforced at the hook level, so you never silently drop commits other agents already built on.
• Every worktree from fresh origin/main. Branching off a feature branch is blocked by default. Agents refresh before they reason: decisions cite current origin/main, not a stale local view.
• Serialized merges. One orchestrator owns main at a time, so two agents never merge simultaneously and corrupt the integration branch.
• Ephemeral worktrees. Auto-deleted on merge. No graveyard of abandoned branches turning into landmines for the next agent.
• Production deploys only through main. A manual vercel --prod is blocked by hook.
• Risk-tiered approvals. Safe runs auto, caution prompts in-app, dangerous interrupts and pushes and texts and emails you. See Approvals.
• Production Readiness Gate, 0 to 100. 70 or above ships, 50 to 69 confirms, below 50 blocks.
• Per-session $5 cost cap. Exceed it and the agent pauses for a caution approval.
• roborev reviews every commit. Commit small and often; issues get flagged in real time instead of accumulating into an un-bisectable CI failure.
• Write-guarded worktrees. Agent worktrees live outside the project tree with a write-guard, so a "helpful" or compromised agent cannot escape its directory.
• Credentials never pass through Sparkle. Claude Code authenticates with your own binary; your keys never touch Sparkle's logs, telemetry, or classifier training data. (This one is architectural, not a toggle.)

Every rule here is a scar from someone else's mistake, turned into a rule so it never happens to you. Somebody once pushed broken code straight to the live website. Somebody once let an AI spend wildly overnight. Somebody once shipped something that looked finished but wasn't. The guardrails mean you get the benefit of those lessons for free, without ever having to live through them. You can be brave precisely because the floor is padded.

Guardrails are what turn "vibe coding" from a party trick into a way to actually ship. The failure mode of AI building isn't that the agent can't write code, it's that it confidently does the wrong thing at scale. A 200-line unreviewed change that breaks CI in a way nobody can bisect. A runaway session. A merge collision between two agents. These rules pre-empt the exact disasters that make people swear off parallel agents. With them on, you get the speed without the 2am cleanup.

You've enforced most of these by hand on every serious team: protected branches, required reviews, deploy gates, spend alerts. The value here is that they apply to autonomous agents by default, at the orchestration layer, not as tribal knowledge you hope a junior absorbs. The agent physically cannot force-push main or skip the readiness gate. That's a stronger guarantee than a CONTRIBUTING.md nobody reads.

Talk is cheap. Show me the code.

The code is open. The rules marked modifiable are MIT-licensed and editable; the architectural ones (credentials never transiting Sparkle, the OSS-export leak-check) are load-bearing and stay.

The old black-screen terminal has no idea what "too risky" or "too expensive" or "not ready" even means. It can't warn you, because it was never built to care. Type the command to wipe everything and it wipes everything, no second question asked. Sparkle adds the judgment the terminal never had, so a wrong move gets caught before it becomes a bad day.

On a raw terminal, the only guardrail is your own discipline at the moment you hit enter, which is exactly when you're moving fast and not thinking about it. Sparkle moves the discipline into the system so it's always on, even at 2am, even when you've delegated the typing to ten agents.

A 1980s terminal enforces nothing: it will force-push to main, ship an untested branch, or burn unlimited spend without a word. Sparkle's contribution is not a prettier shell, it's a policy layer wrapping the same real git and Claude Code underneath, with hooks and approvals that make the dangerous defaults safe and the safe path the path of least resistance.