A complete walkthrough of how Bolts work in BoltOps — what makes a good one, how each of the six stages should run, and the tips and tricks our highest-velocity teams use to stay under a 4-hour median cycle time.
A Boltis the unit of work in BoltOps. It replaces tickets, stories, and t-shirt sizes with one consistent shape: a single 4–8 hour cycle that an AI agent (and a human reviewer) can take from intent to production in a single sitting. If it takes longer than a day, it isn’t a Bolt — it’s a project that needs to be split.
A Bolt ships a single, named outcome — a feature flag, an endpoint, a screen, a bug fix. If you can’t describe it in one sentence, you have two Bolts.
4–8 hours of agent + reviewer time. Short enough that context stays warm. Long enough that the work is real.
Every Bolt is anchored by a structured spec. No verbal hand-offs, no Slack threads as source of truth.
Your project’s CLAUDE.md is the rulebook the agent is held to — managed and versioned inside BoltOps, not rotting in your repo.
A good Bolt feels obvious in hindsight: one outcome, one owner, one afternoon. The five attributes below are what separate a Bolt that ships on the first pass from one that bounces back from review.
Good:“Add a copy-to-clipboard button to the share modal.”
Bad:“Improve sharing.”
If acceptance criteria can’t be written as pass/fail checks, the Bolt is too broad.
Three to seven bullet points the verifier can mechanically check. “Button renders,” “clicking copies the link,” “toast confirms success.” Vague criteria like “feels intuitive” belong in the design doc, not the Bolt.
Name the files, endpoints, and components the agent should touch — and the ones it must not. Bolts with named scope finish in one pass; Bolts without named scope grow tentacles.
Rule of thumb: if you can’t describe the change as a diff-of-roughly-this-shape in your head, split it. Most teams find the sweet spot is 1–3 files modified, < 400 lines of diff.
Before you drag a Bolt to Generate, you should already know who will review it. Bolts without a reviewer queue up and become tomorrow’s stale-context problem.
Titles that start with “Refactor…,” “Investigate…,” or “Improve…” are almost never single Bolts. Break them into discovery + implementation, or into named outcomes.
Every Bolt moves left-to-right through six stages on your board. Transitions are drag-and-drop; behind the scenes BoltOps dispatches agents, runs checks, and notifies reviewers automatically.
Who: PM, tech lead, or whoever spotted the work.
Output: A structured Intent Document with title, priority, user story, acceptance criteria, edge cases, and dependencies.
Click New Bolt, type a one-line title, and let Claude Assistdraft the rest from your project context. Edit, sharpen, and confirm. Most authors spend 5–10 minutes here. That investment is what makes the next three stages run unattended.
Tip:Write the title as a verb + object + outcome. “Add CSV export to the reports page” beats “CSV export.”
Who: One or more agents, dispatched automatically.
Output: Code, tests, and docs on a feature branch.
Dragging the Bolt into Generate spins up a Claude Code session wired to your CLAUDE.md. You can run multiple Paperclip agents in parallel — one writes the code, one writes the tests, one updates the docs — each with its own budget cap and approval gate.
Tip:Set a token budget per Bolt. Cheap Bolts tend to be well-scoped Bolts. If an agent burns 30% of budget before producing a diff, pause and tighten the intent — don’t just raise the cap.
Who: The verification engine. No humans required.
Output: A pass/fail report against your CLAUDE.md rules.
The engine runs lint, type check, tests, security scan, and CLAUDE.md compliance checks. If anything fails, the Bolt loops back to Generate with the failure log appended —before a human ever sees it.
Tip:Treat verification failures as cheap. Three auto-iterations is normal. The failure mode to watch for is a Bolt that passes every check but still feels wrong in review — that means your CLAUDE.md is missing a rule. Add it.
Who: Named reviewer, plus optional external stakeholders via Magic Link.
Output: Severity-rated feedback (blocker / nit / praise) or an approval.
Reviewers see a preview, the diff, the test report, and a summary. External reviewers (designers, partners, customers) can comment without an account using a signed Magic Link.
Tip:Rate feedback severity honestly. A “blocker” rating reopens an agent loop; a “nit” goes into the backlog. Mis-tagging nits as blockers is the #1 reason cycle time slips past 8 hours.
Who: The original agent, re-dispatched with feedback as new context.
Output: A revised diff, queued straight back to Verify.
Most Bolts iterate once. The platform average is 1.3 cycles from Review back to Verify. If a Bolt iterates four or more times, BoltOps surfaces it as a stuck Bolt— usually a sign that the original intent was ambiguous.
Tip:When you find yourself writing the same review comment twice in one week, that’s a CLAUDE.md rule, not a review comment. Promote it.
Who: Release Captain (a rotating role on your team).
Output: A merged PR with auto-generated description, test results, and change summary.
Shipped Bolts are coordinated into a Release Train. The Release Captain holds the scope gate — deciding what ships in the next deploy and what waits for the one after. Merge, and you’re live.
Tip:Run your Release Train on a fixed cadence (every 2 hours, twice a day, once a day — pick one). Predictable cadence beats “ship when ready” for every team over 3 engineers.
Every project in BoltOps has six configuration tabs. Spend 20 minutes setting them up properly when you create a project and the next hundred Bolts run themselves. You’ll find these tabs at /projects/{id}.
Purpose: Tell BoltOps where the code lives and how to branch.
Fields:Git repo URL (GitHub, GitLab, or Bitbucket — auto-detected); default branch; branch convention (default bolt/{number}-{description}); directory structure (path → description mappings); staging URL; production URL; CI/CD reference.
Tip: Use the Detect button to auto-fill from your README and package.json, then use Describe to have Claude annotate the directory structure. Two clicks, one tab done.
Purpose: The governance document every agent is held to. Versioned, history-tracked, never out of date.
Seven sections:Architecture overview · Coding standards · Domain boundaries · API conventions · Testing requirements · Deployment rules · Off-limits areas.
Edit inline, upload an existing .md file, or paste raw markdown. The editor auto-parses headings into sections, and every save creates a version with author + change notes.
Tip:Start small. Three sentences per section is enough to ship your first ten Bolts. Add rules as review comments repeat — let CLAUDE.md grow from real friction, not anticipated friction.
Purpose: Project-level membership and roles. Independent of the org-level role.
Five project roles: PM (authors Intents, runs reviews), Developer (dispatches Generate, fixes iterations), Reviewer (gates Review), QA (runs Verify, files findings), Stakeholder (read-only, can comment via Magic Link).
Tip:A person can hold different roles on different projects. Your Staff Engineer might be a Developer on the core app and a Reviewer on the customer site — let them.
Purpose: Wire the project to Paperclip so agents auto-dispatch on stage transitions.
Fields: Sync enabled toggle; Paperclip company mapping; default agent budget in cents; sync CLAUDE.md as skills; cost snapshots table (per-agent, per-project spend, updated daily).
Tip:Set the default budget at roughly 1.5× what an average Bolt actually costs. Tight enough that runaway loops trip the cap; loose enough that normal Bolts don’t get throttled.
Purpose: Group Bolts into named releases. Track planning, ready-to-ship, and shipped states.
Fields per release: version label; status (planning / ready / shipped); target ship date; actual ship date; attached Bolts; summary metrics (count, total diff size, total test runs).
Tip:Don’t plan releases more than 7 days out. Bolt cycle time is short enough that a 4-week release plan is fiction by week two. Two-day horizons stay accurate.
Purpose: Lets developers move Bolts through stages from their editor.
Fields: Git connection (GitHub App install, required); auto-create branches; auto-context (preload README + package.json into the agent session); auto-advance stages when CI passes or PRs open.
Tip: Enable all three auto-toggles in week one, then turn off any that surprise you. Most teams leave them all on permanently.
The org-level admin console lives at /admin with organization settings at /settings. Together they cover everything that applies to all projects: members, billing, connectors, and global toggles.
At:/admin — invite by email, assign one of six org-level roles, edit later, remove members.
Roles: Owner (full control + billing + delete org), Admin (manage members + settings), PM (author Intents, run reviews), Engineer (Generate, Verify, Iterate), QA (Verify and file feedback), Viewer (read-only).
Tip: Org role gates access; project role gates action. Keep org roles broad and project roles tight.
At:/settings → Billing. Five tiers, each with a hard ceiling on seats, Bolts, and projects.
Starter (3 seats, 25 Bolts/mo, 1 project) · Growth(25 seats, unlimited Bolts, 5 projects) · Pro(unlimited + RBAC + Workbench) · Studio(Pro + SSO/SAML + BYOK + 1-year audit) · Enterprise (SCIM, custom connectors, 99.9% SLA).
Subscription state, period end, and trial end are surfaced inline. The Stripe portal handles upgrades, downgrades, and payment-method updates.
Tip:Charter members get grandfathered pricing — check the is charter member badge before assuming a tier price.
At:/settings → Integrations. Every connector has a status (connected / disconnected / error / syncing) and a last-sync timestamp.
VCS: GitHub, GitLab, Bitbucket · Comms: Slack, MS Teams, Discord · Issue tracking: Jira, Linear, Asana · CI/CD: GitHub Actions, GitLab CI, Jenkins · Observability: Datadog, New Relic, Sentry · Auth: Okta, Azure AD · Agents: Paperclip, Claude Code.
Tip: Set up GitHub beforecreating projects — the project Workspace tab auto-detects the repo if the connector is already live.
At: /settings → Claude Integration. One-click Test connection verifies API key, model availability, and rate-limit headroom. Surfaces which model is wired up (Opus / Sonnet / Haiku) and the last successful call.
Tip: Run the test after any provider key rotation. Silent auth failures are the #1 reason Generate stalls.
At:/settings → Bolt Types. Define custom Bolt types beyond the defaults. Each type gets a label, a color, and a sequence of stages.
Useful when, e.g., a Bug Bolt should skip the Generate-Verify-Iterate loop and a Spike Bolt should end at Review. Reset-to-defaults is one click away.
Tip: Three types is plenty. Feature, Bug, Spike. More than five and the board becomes a costume party.
At:/settings → Orchestration. Org-wide defaults that every project inherits:
Direct orchestration (agents auto-dispatch on stage transitions) · Workbench enabled (IDE-driven moves) · Branch auto-creation · Auto-context detection · Auto-advance stages · Default branch naming pattern.
Tip:Set sensible org defaults, then let projects override only when they have a real reason. Drift between project configs is the most common source of “why did this Bolt behave differently” tickets.
1. Pick a plan tier → 2. Invite Owners and Admins → 3. Connect GitHub → 4. Test Claude integration → 5. Set org orchestration defaults → 6. Define Bolt types → 7. Invite the rest of the team. Most orgs are admin-ready in under 30 minutes.
A grab-bag of practices the highest-velocity teams converge on after a few weeks of running Bolts.
When in doubt, two Bolts beat one. A 6-hour Bolt that ships is worth more than a 14-hour Bolt that gets stuck in review on Friday afternoon.
Recurring review comments belong in CLAUDE.md. Every nit you promote is a comment you never have to type again — and a check the verifier now runs for free.
Intents that list the files and components in scope finish in a single Generate pass roughly 2× more often than open-ended intents. Be specific.
A 50k-token cap forces good scoping. Bolts that need a 200k cap are almost always two Bolts in a trench coat.
Designers, customers, and partners can review without an account. Pulling stakeholders into Review early is cheaper than discovering misalignment after Ship.
Any Bolt that iterates 4+ times surfaces on the Stuck dashboard. Triage it the same day — either re-scope, split, or kill it. Don’t let it linger.
Pick a Release Train interval and stick to it. Predictability is what lets stakeholders trust the system.
Weekly rotation. The captain is the scope-gate — deciding what ships and what waits. Rotating the role spreads context and prevents bottlenecks.
While one Bolt is in Verify, draft the next Intent. Keep the pipeline full — agents are cheap; idle reviewers are not.
Five failure modes we see on nearly every new team in their first two weeks. Recognising them early saves cycle time.
Symptom: Generate runs for 90 minutes; the diff touches 12 files. Cure: Split into three Bolts before you drag it out of Intent.
Symptom: “We talked about it in standup — just build it.” Cure: If it isn’t in the Intent Document, it doesn’t exist. Make Claude Assist draft it in 90 seconds.
Symptom: Reviewers keep typing the same comment. Cure: Promote the comment to a CLAUDE.md rule the same day.
Symptom: Every nit gets tagged blocker; cycle time creeps to 12 hours. Cure: Reserve blocker for ship-stoppers. Nits go to the backlog or to CLAUDE.md.
Symptom: No named reviewer; the Bolt sits in Review for two days. Cure: Assign the reviewer at Intent time. No reviewer, no Generate.
Symptom: 6+ iterations, still bouncing. Cure: Kill it. Rewrite the Intent from scratch. Sunk-cost is more expensive than the tokens.
Before you drag a Bolt out of Intent, run this list:
Nine boxes. If you can’t check all nine, the Bolt isn’t ready — and that’s a feature, not a bug. The 5 minutes you spend here is what makes the rest of the pipeline run unattended.
Join engineering teams that have replaced sprint ceremonies with AI-orchestrated workflows.
Get Started Free