sarathi — Production Software Engineering with AI Agents

A disciplined, adaptive workflow for building production software with AI coding agents.

sarathi helps AI coding agents and software teams turn accepted intent into the smallest safe working increment, preserves the decisions and evidence needed to review it, decomposes work that is too complex to reason about safely as one unit, and adapts the remaining work from real feedback.

Why sarathi?

In the Mahabharata, Krishna serves as Arjuna's sarathi—his charioteer and counsel. He does not replace Arjuna's agency; he helps him see the situation clearly, reason through doubt, and act with purpose. sarathi takes its name from that partnership: it helps engineers and AI agents navigate complex software decisions and reach production with evidence, discipline, and human judgment intact.

Its enduring delivery loop is:

accepted intent -> smallest safe increment -> working behavior -> evidence -> feedback -> adapt

Specifications, designs, plans, and code preserve the decisions made along that loop; they do not form a one-way waterfall. Lean combines design with planning, Standard keeps all four stages explicit, and High-assurance adds risk-boundary decomposition and more review points. Every retained stage receives full assurance. Approval policy and work outcome are separate. See sarathi's enduring model and delivery assurance profiles.

What You Get

• Slash-command prompts for specs, designs, plans, code, verification, review, and assessment.
• A native sarathi skill for agents that support skills.
• Automatic checkers for specs, designs, plans, and links from requirements to tests.
• A repeatable HTML project-status view showing current work, linked tests, feedback, and approvals.
• Installers for Windows, macOS, Linux, and WSL.
• User-scoped installs by default, with project-scoped installs when needed.
• Change history in CHANGELOG.md and release/tagging guidance in docs/release-process.md.

Extra checks for specific risks are listed in docs/cross-cutting-concerns.md. Prompt authors should use docs/process-maintenance.md to keep shared rules from bloating every command prompt.

Quick Install

Install Sarathi for the current user with one command:

uvx --from sarathi-sdlc sarathi-sdlc install

uvx runs the installer temporarily; the installed skills and prompts remain available. Restart or reload your agent tools after installation. A user install skips the separate project-local checkers/ copy by default because every installed Sarathi skill already contains its checkers.

When an update notice appears, review and explicitly approve the reported version before installing it. Replace X.Y.Z with that exact approved version:

uvx --from sarathi-sdlc==X.Y.Z sarathi-sdlc install

Verify manifest.json reports the approved version, then restart or reload the agent tools. Agents must never update Sarathi automatically.

Preview the destinations without writing files:

uvx --from sarathi-sdlc sarathi-sdlc install --dry-run

Add -v or --verbose to show destinations, per-tool actions, companion-install details, reload guidance, and informational notes.

Install project-local assets, including a top-level checkers/ copy, or select tools:

uvx --from sarathi-sdlc sarathi-sdlc install \
  --target /path/to/product --scope project
uvx --from sarathi-sdlc sarathi-sdlc install --tools codex,claude-code

Keep The Installer CLI

Install sarathi-sdlc permanently only when you want its installer, version, and update commands to remain on your PATH:

uv tool install sarathi-sdlc
sarathi-sdlc install
sarathi-sdlc --version
sarathi-sdlc check-update

Alternatively, use pipx install sarathi-sdlc. After upgrading the package, rerun sarathi-sdlc install to refresh copied skills and prompts. Installed skills check PyPI at most once per 24 hours and report newer releases without blocking work or updating automatically. Set SARATHI_UPDATE_CHECK=0 to disable that check.

An upgrade rebuilds Sarathi's bundled docs/, prompts/, and checkers/ subdirectories, so retired bundled files do not remain. It preserves other files in the installed sarathi folder and only removes the retired standalone srs-authoring bundle when it exactly matches the historical Sarathi-owned files. Recognizable older unprefixed stage aliases are moved intact to a sibling sarathi-retired-stage-skills/ archive outside skill discovery; unrelated generic skills are not moved.

Install From A Source Checkout

Clone the repository and run from its root when developing or testing an unreleased change.

Preview the install without writing files:

.\scripts\install.ps1 -DryRun

scripts/install.sh --dry-run

Install for the current user:

.\scripts\install.ps1

scripts/install.sh

Installers report only the target, selected tools, scope, and completion status by default. Use -v in PowerShell or -v/--verbose in a shell to show destination paths, per-tool actions, companion-install details, reload guidance, and informational notes.

Install into a specific project workspace from the checkout instead:

.\scripts\install.ps1 -TargetRoot D:\path\to\product -Scope project

scripts/install.sh --target /path/to/product --scope project

Install only selected tools:

.\scripts\install.ps1 -Tool codex,claude-code

scripts/install.sh --tools codex,claude-code

By default, Windows installs also refresh WSL targets when WSL is available, and WSL installs also refresh Windows targets when powershell.exe is available. Use -NoCrossInstall or --no-cross-install to stay in the current environment.

Supported Targets

• Codex: installs the sarathi skill and direct prompt commands under ~/.codex/prompts. Invoke direct prompts as /prompts:spec-create, /prompts:design-create, etc. after restarting Codex.
• GitHub Copilot: installs prompt files for VS Code Copilot Chat and first-class agent skills for Copilot CLI/agent surfaces. User scope installs prompts under the VS Code user prompt folder and skills under ~/.copilot/skills/sarathi plus ~/.agents/skills/sarathi. Project scope installs prompts to <project>/.github/prompts and skills to <project>/.github/skills/sarathi plus <project>/.agents/skills/sarathi. The installer also creates agent-neutral, explicit-only command skills such as sarathi-code-review, sarathi-code-verify, and sarathi-code-assess under the same skill roots.
• Claude Code: installs slash commands and the sarathi skill.
• Gemini CLI: installs command TOML files.
• Claude and Pi: exports prompt packs under .ai-prompts/ for manual import or use.
• Checkers: project-scoped package installs copy checkers/ into the target workspace. Implicit user-scoped package installs skip that separate copy unless --with-checkers is provided; every installed skill still contains its self-contained checker bundle. Source installers retain -NoCheckers and --no-checkers for explicitly skipping the copy.

Installed skill bundles are self-contained: the installer assembles each sarathi skill copy from the canonical docs/, prompts/, and checkers/ sources, plus SKILL.md and agent config. Prompt commands or explicit command skills are also installed separately where host tools can expose them directly. Only the top-level sarathi skill permits implicit invocation, and only for Sarathi or managed delivery-workflow intent—not an ordinary code-generation request. Every sarathi-* command skill must be named explicitly.

Every dry or real install prints the destination folders before doing work.

Prefixed command skills are expected only on agent skill surfaces where the installer exposes them; Codex-only, Claude Code, and Gemini installations use their native explicit commands. If an agent reports that bundled prompts/spec-create.prompt.md, checkers/check_spec.py, or another required file under the main sarathi skill is missing, the bundle is incomplete or was copied from the wrong folder. Re-run the installer, or install from this repository's skills/sarathi folder after updating to a version where that source folder is self-contained.

Commands

The prompt set uses four verbs:

• create: write or revise a document or code slice.
• verify: run repeatable checks and report what they prove and do not prove.
• review: independently judge quality and look for counterexamples.
• assess: run verify first, then review.

The core stage names are:

Generate the live status page and its linked static process guide directly with:

python checkers/render_workflow_status.py . --output docs/sdlc-status.html

See docs/workflow-status.md for discovery rules, evidence semantics, deterministic output, guide publication, and CI freshness checks. The page leads with engineering state—what works, what is reusable, what remains shared or target-owned, what is deferred, coding blockers, and one next action—before showing document, approval, and review state. Completion claims always name their exact scope.

Exact invocation syntax depends on the host tool:

• Agent skill surfaces: explicitly invoke $sarathi-code-review, $sarathi-code-assess, or another prefixed command skill. Ordinary coding requests do not activate these skills.
• Codex direct prompts: /prompts:code-review, /prompts:code-assess, and so on.
• GitHub Copilot CLI: reload skills with /skills reload, then explicitly select the prefixed Sarathi command skill using the syntax supported by that version.
• VS Code Copilot Chat: use the installed prompt file from the prompt picker, or ask in natural language with the stage name.
• Claude Code and Gemini: use their native command mechanisms.

Workflow Model

The core model is accepted intent, the smallest safe increment, evidence, feedback, and adaptation. Specifications use a needs-to-evidence requirements model: problems and stakeholder needs lead to features, use cases, functional and supplementary requirements, acceptance tests, and journeys. Designs turn accepted requirements and constraints into an implementable, evolvable technical model. Plans structure delivery through impact analysis, breakdown or a PR dependency graph, sequencing, integration, safety, and proof. Code plus tests produce working behavior through short Red-Green-Refactor cycles. Repeatable checks and independent review gate every stage; they are not deferred until implementation ends.

Work uses three levels. The paired terms below are retained as machine-readable values for compatibility:

• Product/system: broad product or platform scope.
• Feature/component: one user-facing capability, subsystem, component, integration, or screen family.
• Slice/change: the smallest implementable unit, usually PR-sized.

Documents say plainly whether the work is ready to implement and, when it is not, what specific question remains.

$sarathi-code-create runs from approved requirements and a specific implementation plan that is ready to implement.

Start implementation when the approved requirements, design, and one specific plan make the next change clear and safe. If the work is too complex to understand and review as one unit, split it along a natural product or technical boundary until each part is clear, testable, and safe to integrate. A split does not automatically require another spec or design. See docs/work-decomposition.md.

ID Format

Specs and plans use descriptive slug-only IDs: KIND-AREA-NAME, for example FR-AUTH-SIGNIN, AT-AUTH-SIGNIN, JT-AUTH-ONBOARDING, PR-AUTH-SIGNIN, and WAVE-AUTH-BOUNDARY. Design entities keep the shorter KIND-SLUG form, for example COMP-AUTH and IFACE-AUTH. Design test obligations use TEST-AREA-NAME, for example TEST-AUTH-POLICY. Numeric placeholders such as FR-AUTH-10 are rejected by the checkers; meaningful digit-first terms such as FR-AUTH-2FA and FR-PAY-3DS are valid.

For older numbered IDs, see docs/slug-id-migration.md.

Policy And Evidence

Detailed workflow behavior is owned by the command prompts and shared documents rather than repeated here:

• project entry, delivery assurance, and approval/YOLO policy;
• document contracts, locations, and human-first formatting;
• work decomposition, feedback and learning, and work-in-progress state;
• test ownership, risk-triggered checks, and review/verification; and
• simplicity, cleanup, simplification, and result reporting.

The selected command prompt says which references apply. Checkers provide repeatable evidence about structure, links, approval-record freshness, and declared test results; they do not prove correct meaning, stakeholder consent, or production readiness.

Repository Layout

docs/      user-facing documentation and review notes
prompts/   source command prompt definitions
skills/    skill-specific definitions and metadata
checkers/  repeatable structure and link checks
scripts/   installers for Windows, macOS, Linux, and WSL
tests/     checker tests

Do not treat .github/prompts as source in this repository. It is only an install target for GitHub Copilot project-scoped prompts.

More Detail

• Changelog: CHANGELOG.md
• Release process: docs/release-process.md
• Static process guide and example tree: docs/sarathi.html
• Cross-scope test and integration ownership: docs/test-ownership.md
• Review checklist: docs/review-verification-checklist.md
• Document locations and persistent review records: docs/document-locations.md
• Slug ID migration: docs/slug-id-migration.md
• Approval gates: docs/approval-gates.md
• Agent-facing repository guidance: AGENTS.md