sarathi — Build Production Software with AI Agents

Sarathi helps coding agents turn approved requirements into the smallest safe working change through clear requirements, design, planning, coding, automatic checks, and independent review. It keeps the next step clear and adjusts 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 basic loop is:

approved requirements -> smallest safe change -> checks and review -> feedback -> adapt

Requirements, designs, plans, and code may change as the team learns. Lean combines design with planning. Standard keeps a separate design. High-assurance splits risky work into smaller changes with more review points. Every stage that remains is checked and independently reviewed. Approval rules are chosen separately. 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

Optional: Keep The Installer Command

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/ folders while preserving other files in the installed sarathi folder. It removes the retired srs-authoring bundle only when that bundle exactly matches Sarathi's historical files. It moves recognized older unprefixed stage aliases, unchanged, to a sibling sarathi-retired-stage-skills/ archive outside skill discovery. It does not move unrelated generic skills.

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

Commands combine a stage (spec, design, plan, or code) with one of four actions:

• 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 automatic checks, then an independent 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 details. The page starts with what works, what can be reused, what remains, what blocks coding, and the next action. It then shows document, approval, and review status. Every completion claim says exactly what is complete.

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 approved requirements, useful changes, checks, review, and feedback. Requirements explain the problem, user needs, behavior, constraints, acceptance tests, and important user journeys. Designs explain how the system will meet them. Plans say what will change, in what order, and how it will be tested. Code is built in short Red-Green-Refactor cycles. Each stage is checked and independently reviewed before the work moves on.

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