The model writes. Empirical keeps the contract, progress, proof, and exact next action in the repository, so a supported agent session can resume without reconstructing the work from chat.
The model writes. The harness remembers, checks, and gates.
A coding model can propose a change. Empirical gives that work durable instructions, selected work, an exact next action, permitted checks, verification rules, and stopping boundaries—without becoming a background process or keeping a stopped agent host running.
First time
Install once. Initialize this repository once. Then ask normally.
Follow the complete five-step route. Setup is reviewable before it writes anything.
01
Shell
Install package and integrations
Install empirical-sdd, then run empirical install and choose the coding-agent integrations you use.
02
In your agent
Invoke Init explicitly
Use $empirical-init in Codex or /empirical-init in Claude Code.
03
In your agent
Review setup
Apply, customize, or cancel the proposed settings. Cancel writes nothing, and Init creates no feature.
04
In your agent
Ask for the change normally
Repository mutations route automatically. Read-only questions stay read-only and do not create workflow state.
05
In your agent
Inspect, continue, or resume
Follow the selected exact action. A later supported session resumes from the same checkout and committed journal.
Shell · install
bun add --global empirical-sdd
empirical install
In your agent · Init
Codex $empirical-init
Claude Code /empirical-init
Returning
Open the same checkout and continue the selected work.
Open the checkout where the work was selected.
Ask for status or ask to continue.
Follow the exact phase, missing proof, question, or stopping point returned by Empirical.
In your agentContinue the active feature.
Without a harness
Chat history is the memory.
With Empirical
The repository is the resume point.
Without a harness
“Looks done” is a judgment.
With Empirical
Completion is derived from receipts.
Without a harness
A new session reconstructs context.
With Empirical
A new session resumes the exact revision.
Without a harness
Tracker status becomes folklore.
With Empirical
The local journal remains authoritative.
Chapter 02 · Files
Setup installs the harness. Work fills in the record.
This representative Schema-5 tree separates what Init writes from what may appear as work advances. Select any path for ownership detail; every short description remains visible without JavaScript.
Marker-ownedEmpirical manages only its bounded entry or block, preserving surrounding user content.
Agent/team-maintainedEmpirical scaffolds it; repository evidence and maintainers refine it.
ConditionalCreated only for a chosen agent, route, phase, or required policy.
OptionalCreated only after explicit configuration or when that outcome exists.
Use Up and Down to move through paths, or Home and End to jump. Selecting a path updates the ownership detail beside the tree.
01
Written during Init
02
May appear as work advances
Not persisted: the dynamic packet returned to an isolated reviewer. Only a submitted canonical result, its human-readable rendering, pointer, and receipt belong in the committed tree.
Chapter 03 · Boundaries
A workflow harness, with explicit edges.
Empirical makes progress inspectable and resumable. It does not replace the coding model, Git, CI, the developer's host, or the human authority required at protected boundaries.
Empirical does
Turn an ordinary change into governed work.
Route by risk into Fast or Complex.
Persist criteria, decisions, exact phase state, and living behavior.
Select risk-based checks and record real attempts.
Review the exact committed diff.
Integrate capability changes against an independent target.
Derive the highest completion level actually proven.
Empirical does not
Invent authority or hide uncertainty.
Self-initialize from an ordinary request.
Replace the model, Git, CI, test tools, or agent host.
Keep a sleeping or stopped host running.
Accept confidence, copied booleans, or stale results as evidence.
Infer permission to merge, release, deliver, or publish.
Accept chat credentials or let tracker prose mutate local state.
Lost chat→Continuity
Resume from repository state instead of reconstructing history.
Ambiguous request→Shared contract
Agree on observable outcomes and boundaries before “done.”
Confidence→Honest proof
Bind claims to exact source, commands, attempts, and results.
Scope drift→Reviewable scope
Keep decisions, diffs, failed attempts, and gaps visible.
Unsafe convergence→Safer integration
Isolate parallel work and replay capability changes independently.
Accidental publication→Bounded authority
Keep implementation, delivery, and publication distinct.
Chapter 04 · Workflow
The route follows risk, not prompt length.
Fast handles explicit, tiny, localized, reversible, contract-neutral changes. Material work uses the full Complex lifecycle. Both routes require proof before they can claim completion.
FastImplement → verified
Focused work, focused proof, no skipped evidence.
ComplexSpecify through independent Integrate
Durable contract, decisions, verification, review, and capability convergence.
Fast can insert Context when repository knowledge is stale or invalid. If a Fast attempt fails, the same selected feature promotes to Complex Specify with the failed attempt preserved.
The complete Complex loop
Complex8 phasesproof → convergence
01Specify
Freeze outcomes and boundaries.
02Design
Record the accepted approach.
03Plan
Make the change executable.
04Implement
Change the repository.
05 · conditionalContext?
Refresh knowledge only when stale or incomplete.
06Verify
Bind every criterion to a real outcome.
07Review
Judge the exact committed diff.
08Integrate
Replay deltas against an independent target.
Verify fails↩Return the failing output to Implement; keep the failed attempt visible.
Review requests changes↩Return the current diff to Implement, then verify and review the new source again.
Workflow in words. Complex moves from Specify to Design, Plan, and Implement. Context runs only when repository knowledge needs refinement. Verify failure or requested review changes returns to Implement. A passing exact review can advance to independent Integrate. Deliver and Publish remain separate authority.
01implementedthe requested source change exists
02verifiedthe acceptance criteria have current proof
05publishedan authorized immutable release is proven
Empirical reports the highest level demonstrated, not the level requested. Delivery and publication need their own policy, evidence, and authority.
Optional terminal film
Play one outcome. The static loop above remains the source of truth.
Success scenario selected. Playback is stopped.
Empirical · selected path
implement source changed
verify passed with current receipts
review approved exact diff
integrate capability delta applied
Chapter 05 · Proof
Passing checks, approving a diff, and integrating it are different claims.
Empirical keeps each boundary explicit, so one green signal cannot silently stand in for a different kind of proof.
01 · Evidence
What was attempted?
An acceptance criterion points to an exact automated attempt or explicit human step, then to an immutable receipt bound to source and environment. A source change makes old proof stale.
criterion→exact attempt→immutable receipt
02 · Review
Who judged this exact diff?
A fresh-context reviewer or configured review bot evaluates the exact committed base-to-head diff against every ordered criterion and accepted decision. The record distinguishes a non-author bot from the fresh-context fallback; neither is confused with test evidence.
exact committed diff→criterion-complete judgment
03 · Integration
What became shared behavior?
Reviewed capability deltas replay against an independent target. The resulting living specification and integration receipt demonstrate what converged beyond the feature checkout.
capability delta→independent target→receipt
Optional external projection
The tracker mirrors. The repository decides.
Empirical commits local progress first, then projects only configured milestones and approved safe evidence. An acknowledgement confirms the outbound effect; an unacknowledged effect can be retried. Neither can change the local phase or acceptance criteria.
Source of truthCommitted repository
one-way projection────────→← acknowledgement
External mirrorTracker
Tracker state cannot advance local work.
Best effort Provider failure leaves committed local progress intact and records pending or failed tracker health.
Strict required The documented opt-in exception gates work only when the resolved ticket rule requires it.
Chapter 06 · Help
Talk to your agent. Preserve the real outcome.
You do not need a phase-control CLI. Ask in ordinary language, and when progress stops, repair the stated boundary instead of erasing failed or unavailable evidence.
Inspect
In your agentWhere does the current Empirical feature stand?
In your agentShow me which acceptance criteria still lack evidence.
Continue
In your agentContinue the active feature.
Explain
In your agentWhy did this request take the Complex route?
In your agentWhy is this verification check required?
Recover
In your agentRun Empirical Doctor and explain any findings.
Bounded autonomy
In your agentImplement this autonomously through integrated; stop before delivery.
TroubleshootingWhen progress stops, keep the evidence honest.Show fixes
Symptom
What to do
Ordinary change requests do not activate Empirical
Invoke the agent-specific Init entry again for repair, then reload or reopen the agent if instructed. Files being current do not prove this host session loaded them.
Init reports drift or a collision
Empirical preserves unmanaged or unsafe content. Resolve the exact reported path, rerun Init, then ask Doctor to inspect again.
A new prompt resumes older work
This is deliberate: selected non-terminal work wins. Continue it, or review and approve the exact proposed worktree for unrelated work.
Evidence became stale after an edit
Run the current QA matrix again. Stale receipts cannot be edited, inherited, or overridden.
A check needs an unavailable environment or human step
Record the real unavailable or human outcome. It remains visible and may correctly block verification.
Tracker sync is pending or failed
The local journal remains authoritative. Retry the exact feature after access or provider state recovers; strict required work may remain gated.
Authentication is requested
Use negotiated OAuth or the documented host-secret file. Never paste credentials into chat. Secrets never belong in chat.
Chapter 07 · Docs
Start with the guide. Open the contract when precision matters.
Detailed and change-prone claims stay in the canonical Markdown references. Choose the path that matches what you need to learn, operate, or evaluate.