sarathi — Production Software Engineering with AI Agents

A disciplined, adaptive workflow for turning accepted intent into production code, reviewable evidence, and better next decisions.

Open live project status
The delivery loop Spec Design Plan Code + tests
The quality model Create Verify Review Assess

Enduring model: accepted intent → smallest safe increment → working behavior → evidence → feedback → adapt.

The documents preserve decisions along the loop. They are not a one-way waterfall, and approval means safe enough for the next learning step rather than frozen forever.

1. Deliver in a learning loop

Each stage answers a different question and keeps the next increment grounded.

Spec Accepted intent
How is the required behavior defined? Problem, stakeholders, scope and non-goals; needs → features; use cases with main, alternate and failure flows; functional and supplementary requirements; black-box acceptance tests and journeys; traceability to observable evidence
Design Technical model understood
How is the solution shaped? Architecture, responsibilities, boundaries, interfaces, data, decisions, quality attributes, and test approach
Plan Delivery structured
How will delivery be structured? Impact map; Breakdown child outcomes or Implementation PR graph; dependencies, sequence, integration, safety, and proof
Code + tests Evidence
Does the behavior work? Red: observe the behavioral test fail; Green: make the smallest change; Refactor with focused and affected tests green; record exact results
Evidence and feedback confirm or revise the specification, design, and remaining plan

Observed results return to the specification, design, or plan only when they change accepted needs, boundaries, risks, or remaining work.

2. Decompose to make complex work understandable

Keep the work together only while a competent engineer can understand, explain, review, and safely plan it as one coherent unit.

Can the work be understood as one coherent unit?
Capability or outcomeSeparate useful behavior
Responsibility or dataClarify ownership
Interface or dependencyIsolate the connection
Risk or migrationMake the difficult step reviewable
Integrate evidence and return to the delivery loop

Yes: keep the work together. No: split along a natural product or technical boundary. Stop when each part is understandable, testable, and safe to integrate. A split does not automatically require more documents.

3. Test and review throughout delivery

Test intent matures across the stages, and every stage passes through repeatable checks plus independent judgment.

Test evidence thread

Spec Define observable acceptance and important failure cases
Design Choose the test architecture, environments, and boundary proof
Plan Assign test obligations and the first expected failures to delivery
Code + tests Red → Green → Refactor; run focused and affected suites; record exact results

Quality gate at every stage

Create Write or revise the document or working change
Verify Run repeatable checks and state exactly what they prove
Review Independently judge clarity, correctness, simplicity, and safety
Assess Combine the check results with independent judgment

A stage is not accepted merely because its automatic checks are green. Independent review judges meaning, test adequacy, simplicity, and safety; assessment combines both before the next stage proceeds.

4. Preserve continuity

A new engineer or agent should be able to resume from evidence rather than chat history.

Intent and decisions: accepted specifications, designs, and plans Working evidence: behavioral tests, commands, results, and assessments Current position: a short WIP snapshot with one executable next action

The WIP note is navigation, not product truth. Important claims are checked against source documents and working evidence before delivery continues.

5. Match assurance to risk

Every production change keeps the same safety floor; actual risk determines the depth of proof.

LeanSmall, reversible, and low risk
StandardThe ordinary default or unclear risk
High assuranceStronger evidence for material consequences
ExploratoryTimeboxed learning outside production

High assurance adds evidence for concrete risks. It does not require the whole project to be designed up front.

6. Keep supporting rules in their place

Practical authoring rules support the delivery model without replacing it.

Readable documents: explain the product and technical change before metadata Honest status: state engineering reality and exact completion scope before process state Existing systems: reuse proven behavior and make ownership explicit Traceability: preserve links in documents and records, not production code Safe start: code begins from accepted intent and a bounded plan ready to implement Production boundary: live deployment requires explicit user approval

Inspect and adapt: after each reviewed increment, continue, revise, stop, combine, split, or reorder the remaining work according to observed evidence and feedback.