Tame Claude Code with stagent

“Build me a v1 of this app.” You get 20 half-stubbed files, no clear deploy story, and the inevitable “almost done” loop. By the time you sit down to actually ship, your local branch and what's running in production have drifted onto two different roads — if production exists at all.

v1 means deployable, not just compiled. Without one workflow that runs all the way through deploy, the agent stops at “tests pass” or “code looks clean” and you do the deploy by hand a week later. The intent (“ship a v1”) and the agent's stopping condition (“code written”) never line up.

Six stages run in sequence: planning interview → executing (subagent writes code) → verifying (quick tests) → reviewing (adversarial code review) → qa-ing (Playwright user-journey tests) → deploy (Vercel CLI to production). The execute/verify/review/qa inner loop converges on a clean build before deploy runs; deploy is interruptible so you can supply env vars or run <c>vercel login</c> mid-flow.

You hand the agent a goal ('improve homepage conversion', 'make this slow query fast', 'pass this onboarding flow'), it does some work and reports 'done' — but nobody actually checked whether the goal was met. Either the success bar was never written down, or 'looks roughly fine' got waved through.

'Did some work' and 'goal achieved' are different things. 'Re-check before you tell me you're done' to an agent means 'glance at it once more, then say done' — not 'go back, re-run, compare against the bar, and iterate'. Without an evaluator standing between execute and complete, the agent always wins the argument with itself.

Briefing turns the goal into verifiable success criteria you sign off on. Then an execute → evaluate loop runs: the evaluator (a separate subagent that didn't write the code) checks the criteria against fresh evidence; PASS terminates, FAIL bounces back to execute with the gap spelled out — until the bar is actually cleared.

Asked to add a feature, the agent doesn't grep the codebase, doesn't check the official docs, just writes. The API version's wrong, an existing helper gets re-implemented, the new code clashes with the project's style.

Saying "look at the existing code first" lasts about 3 turns. By the 10th decision the agent's back to writing from memory — and it judges "have I looked enough?" by feel, not by listing evidence.

A subagent greps the codebase, reads related modules, and consults docs, then writes a plan that cites every finding by ID. A separate executor implements strictly to the plan, with a verify loop until clean.

Asked to understand a slice of an unfamiliar codebase — say “how does the rendering pipeline work end-to-end” — the agent serially Reads dozens of files in one window, runs out of context, and ends with shallow citations or hallucinated paths.

A single agent doing depth-first investigation hits its context ceiling fast on real codebases. By the time it's read 30 files the early ones have rolled out of memory, citations get fuzzy, and what should be 5 focused answers becomes one rambling 4000-word reply that misses half the question.

decompose splits the unknown into 3–8 well-scoped sub-questions. investigate fans out one read-only sub-investigator per question in parallel — each reads code only in its slice and returns a focused finding with file:line citations. synthesize stitches the per-task findings into one end-to-end answer that covers every question with evidence.

You ask for a fix to bug A. The agent also refactors B, renames C, and adds a helper for D. The PR is unreviewable, and a rollback takes the whole basket.

"Only change what's necessary" is too subjective. Mid-write the agent thinks "this would be cleaner if I tidied this up too" — that's responsibility from its angle, scope explosion from yours.

Pre-declared scope contract + hunk-level diff audit. Any change outside the declared scope is reverted automatically before it reaches the final diff.

You ask Claude to refactor a hot module 'same behavior, cleaner code'. It rewrites the whole file, your tests pass, and a week later prod breaks because Claude quietly dropped a retry, swallowed an exception, or changed timing. The behavior you cared about wasn't in the test suite to begin with.

A prompt can't make Claude pin down which behaviors must be preserved as executable checks before any edit, decompose the refactor into atomic rollback-able steps each with its own invariant subset, retry-with-rollback on per-step failure, then run a full invariant sweep at the end with auto-repair on regressions. Without those gates, the refactor is one big diff that either passes or breaks together — and 'tests pass' is not the same as 'invariants hold'.

Captures must-preserve behaviors as executable invariants, decomposes into atomic rollback-able steps, retries with rollback on per-step failure, and ends with a full invariant sweep that auto-repairs regressions.

Error? The agent adds `try/except: pass`. Assertion fails? It loosens the assertion. Test flakes? It adds a retry. The actual root cause is never found.

"Find the root cause, don't add try/catch" — the agent thinks it already analyzed and that the except is "robust". You can't convince it of an attitude.

Reproduce → diagnose with cited evidence → fix → independent re-validation. Each stage gates the next; no fix lands without a cited root cause.

You ask Claude to find bugs across the app. It scans a few files it picked at random, lists generic pitfalls (race conditions! null checks!), edits one or two of them, and stops. Your actual test / lint / type-check / static-analysis toolchain never runs; nothing is re-verified after the edits; and you have no idea whether one round was enough.

A prompt can't make Claude (a) auto-discover and run your project's actual detection toolchain across the whole repo, (b) emit findings as a structured ledger instead of prose, (c) verify every fix by replaying the exact detection commands plus regression checks, and (d) keep looping until verification is clean. Without those gates you get a one-round vibes-based audit that quietly leaves real bugs in the codebase.

Auto-discovers your project's real test / lint / type-check / static-analysis toolchain, runs it across the whole repo, applies surgical fixes, then replays the detection commands plus regression checks until verification is clean.

You say "test first." The agent says "got it." Then writes the implementation directly and leaves the test as a TODO.

There's no state machine actually checking that a failing test ran before code went in. "Promise to TDD" doesn't survive the first refactor.

Three stages: write a test that's proven failing in stderr → make the minimum change to pass it → refactor only with the whole suite green.

You ask Claude for 'a thorough end-to-end test suite covering every feature'. Back come a dozen tests scattered across unit / integration / e2e categories — half of them poking internal helpers instead of real user flows. When a test fails, Claude can't say whether the test is wrong or the app is buggy, and silently edits production code to make tests green.

A prompt can't pin down which flows count as 'the full user journey', which test category and framework each one belongs in, or the contract that the generator's only job is to make the suite itself green — with app-side bugs going to a separate ledger instead of blocking. Without those gates, Claude conflates test-side and app-side failures and over-edits production code to chase a pass.

Plan stage interviews scope, category, framework, and pass criteria; the writer subagent touches only test/; dry-run classifies each failure as test-side or app-side, looping until the suite itself runs cleanly. App bugs are logged separately and never block.

After a UI change the agent inspects the code and declares it done. Visual regressions only show up when YOU open the browser.

Code-only judgment can't catch alignment, contrast, or mobile reflow regressions. "Check it in the browser" is the right idea but nothing forces it to actually do it.

Translates fuzzy UI goals into machine-verifiable assertions, then scores 8 dimensions from real Playwright screenshots and loops until every dimension clears its threshold.

You ask Claude to 'make /api/search faster'. It immediately suggests adding a cache, memoizing a hot loop, and batching DB calls — implements all three at once and tells you 'should be much faster now'. Nobody ran the slow request before, nobody runs it after. Whether tail latency went down, stayed flat, or regressed, you never find out.

A prompt can't lock a measurement contract — repro script, primary metric (p50/p95/p99), watchdog metrics that must NOT regress, statistical significance threshold, run counts — before any code is touched. It can't constrain Claude to fix one hotspot at a time, re-measure with identical parameters, gate accept/reject mechanically (improvement AND significance AND watchdog budgets), and auto-revert + try the next candidate when a fix fails the gate. Without those, perf work compounds into plausible-looking changes that nobody can prove improved anything.

Locks a measurement contract (repro / metrics / threshold / runs) before any code change, baselines with profiler runs, fixes one hotspot at a time, re-measures with a significance test, and auto-reverts + tries the next candidate on reject.

Asking Claude 'is this app release-ready?' produces a confident-sounding summary — but there was never a real checklist to grade against. Half-relevant rules get cited (privacy policy! analytics consent!), the regulations that actually bind this release — driven by market, age target, deployment region, SDK set — get skipped. Severity isn't classified and no certificate survives for the next reviewer.

A prompt can't tell Claude which regulations apply. Whether COPPA, GDPR, App Store / Play Store policies, or industry-specific rules bind this release depends on facts spread across the manifest, store listing, and privacy text. Without a discovery pass that infers the applicable regs first, Claude either over-cites generic rules or misses the specific clauses that block release.

discover_scope derives a numbered regulatory checklist from market / age / region / SDK; audit walks every C-ID with cited evidence; fix auto-resolves CRITICAL+HIGH; loops until zero violations and ships a release certificate.