sarathi-sdlc 0.1.0

Resumable, reviewable software delivery skills and prompts

Sarathi

Guided, resumable, reviewable software delivery

Sarathi is a set of reusable prompts, skills, and automatic checkers for spec-first software delivery with AI coding agents. It helps developers move from a product request to requirements, design, planning, implementation, tests, and review without losing clear links between intent and tests, resumability, or human review.

The workflow is driven by accepted documents and evidence:

request -> spec -> design -> plan -> code/tests/logging/errors/docs/build/deploy -> assess

Each stage can be created, verified, reviewed, or assessed independently. By default, the skill pauses for human input when important information is missing and pauses again after generating a document or code slice.

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.
• Repeatable workflow-status HTML views for the work tree and each plan's ordered learning waves, including linked tests, explicit feedback state, and current wave checkpoints.
• 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.

Shared lifecycle policy lives in docs/cross-cutting-concerns.md. Prompt authors should use docs/process-maintenance.md to keep new concerns from bloating every stage prompt.

Install From PyPI

Install the command in an isolated environment with uv:

uv tool install sarathi-sdlc
sarathi-sdlc install

Alternatively, use pipx:

pipx install sarathi-sdlc
sarathi-sdlc install

Preview the destinations without writing files:

sarathi-sdlc install --dry-run

Install into a specific project or selected tools:

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

Check the installed command version or look for an available release:

sarathi-sdlc --version
sarathi-sdlc check-update

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.

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

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. Copilot CLI does not treat prompt files as custom built-in slash commands, so the installer also creates direct stage skill aliases such as code-review, code-verify, and code-assess under the same skill roots.
• Claude Code: installs slash commands and the skill.
• Gemini CLI: installs command TOML files.
• Claude and Pi: exports prompt packs under .ai-prompts/ for manual import or use.
• Checkers: installs checkers/ into the target workspace unless skipped with -NoCheckers or --no-checkers.

Installed skill bundles are self-contained: each sarathi skill copy includes SKILL.md, agent config, bundled prompts/*.prompt.md, and bundled checkers/*.py. Prompt commands or stage skill aliases are also installed separately where host tools can expose them directly.

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

If an agent reports that spec-create, another stage prompt, or checkers/check_*.py are missing, the installed skill is incomplete or was copied from the wrong folder. A valid skill install should contain files such as prompts/spec-create.prompt.md and checkers/check_spec.py under the same sarathi skill directory. 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; this is the full gate.

The core stage names are:

Command	Purpose
/spec-create	Create or revise a Software Requirements Specification.
/spec-verify	Run automatic spec checks and report evidence.
/spec-review	Independently review spec quality.
/spec-assess	Run /spec-verify plus /spec-review.
/design-create	Create or revise a Software Design Document and ADRs as needed.
/design-verify	Run spec and design checks.
/design-review	Independently review design quality and spec fitness.
/design-assess	Run /design-verify plus /design-review.
/plan-create	Create a breakdown or implementation plan with PR slices and touch sets.
/plan-verify	Run checks for the spec, design, and plan.
/plan-review	Independently review plan readiness, slicing, assignment, and sequencing.
/plan-assess	Run /plan-verify plus /plan-review.
/code-create	Implement a code-ready plan with focused verification, including planned logging/error-handling/docs/build/deploy work.
/code-verify	Run planned tests, quality gates, and applicable logging/error-handling/build/docs/deployment checks.
/code-review	Independently review code, tests, operational work, quality gates, and consistency with earlier documents.
/code-assess	Run /code-verify plus /code-review.
/workflow-status	Render the work tree and ordered learning-wave status as read-only HTML.

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.

Exact invocation syntax depends on the host tool:

• Codex direct prompts: /prompts:code-review, /prompts:code-assess, and so on.
• GitHub Copilot CLI: stage names are installed as skill aliases where supported, so try /code-review or /code-assess after /skills reload. If the CLI surface rejects a stage slash name, invoke by natural language: "Use the sarathi skill to run the code-review stage."
• 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

Work uses three levels:

• Product/system: broad product or platform scope. Usually needs breakdown and is not directly code-ready.
• Feature/component: one user-facing capability, subsystem, component, integration, or screen family.
• Slice/change: the smallest implementable unit, usually PR-sized.

Documents declare one readiness value:

• Exploratory: still being shaped.
• Decomposable: valid parent document, but needs child work before implementation.
• Code-ready: precise enough for implementation.

/code-create should only run from a code-ready implementation plan.

Breakdown plans use WORK-* IDs to assign parent work to children; they are not another document type. A product plan normally maps each WORK-* allocation to a feature spec, design, and plan. A feature Breakdown plan normally maps each allocation to a slice spec, LLD, and Implementation plan. An eligible code-ready Lean slice instead uses one compact Lean Change Record. Product integration work may map directly to a slice child, but its test code remains slice-level code carrying product-owned test intent. 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 suffixes such as FR-AUTH-10 are rejected by the checkers.

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

Builds And Deployment

Builds and deployment are covered from the beginning:

• Specs capture externally relevant build, release, deployment, rollout, rollback, migration, smoke-check, and operational acceptance needs.
• Designs define deployable outputs, build/package strategy, release workflow, environments, configuration/secrets, promotion, deployment topology, validation, and ownership.
• Plans assign build scripts, package manifests, generated outputs, CI/CD config, IaC or deployment manifests, migration scripts, smoke checks, rollback checks, and release docs to child work or PRs.
• Code creates and verifies the planned build/deployment pieces. It should run the build, verify the expected build output, validate deployment scripts/manifests with dry-run or lint checks where possible, and avoid live production deployment unless explicitly requested.

Reviews stop when build or deployment intent is missing from the earlier document that should own it.

Test Environments

The process treats test environments as design and planning decisions:

• Specs capture externally relevant environment needs or non-goals when they affect acceptance, release safety, data, integrations, or operations.
• Designs always define the developer test environment and recommend additional environments when context warrants them: shared integration/test, staging or pre-production, production canary/smoke, and synthetic monitoring.
• Plans assign setup, data/secrets handling, reset/cleanup, deployment validation, smoke/ canary/rollback checks, and ownership for each planned environment.
• Code runs the planned environment checks. Live production checks require explicit user approval.

Not every product needs every environment. The design should explain which environments are required now, recommended later, deliberately deferred, or unnecessary, including residual risk.

Context-Driven Reviews And Tests

At every phase, agents should ask what the context implies beyond the user's first words. Depending on the domain, data, users, integrations, platform, and deployment risk, the process may need dedicated performance/load tests, security review or threat modeling, privacy/compliance review, accessibility audit, resilience or disaster-recovery checks, backup/restore rehearsal, migration rehearsal, localization review, abuse/fraud/safety review, cost guardrails, compatibility tests, or operational reviews.

Specs capture these as requirements, acceptance criteria, non-goals, assumptions, or open questions. Designs turn them into tactics, TEST- obligations, ADRs, or risks. Plans assign them to work items or PRs. Code runs the planned checks and stops to revise earlier documents if implementation reveals a material concern that was not planned.

User And Developer Documentation

Documentation is also covered from the beginning:

• Specs capture user and developer documentation audiences, tasks, onboarding, help, API/reference, examples, runbooks, troubleshooting, release notes, accessibility, and acceptance needs.
• Designs define the documentation architecture: source locations, generated vs. written docs, API/reference generation, examples, diagrams, publishing/versioning, ownership, and validation checks.
• Plans assign documentation work to PRs, including user guides, README/API docs, examples, runbooks, troubleshooting, migration notes, release notes, generated docs, and link/doc checks.
• Code updates and verifies the planned docs with the implementation. Public docs should match actual behavior and contracts, not describe unimplemented future behavior.

Reviews stop when documentation intent is missing from the earlier document that should own it.

Logging, Telemetry, And Error Handling

Diagnostics and failure behavior are covered across the lifecycle:

• Specs capture externally relevant human/agent/operator diagnostics, telemetry, application performance monitoring, support/debugging needs, privacy/redaction constraints, user-facing error behavior, and boundary error contracts as requirements or non-goals.
• Designs define structured logging, correlation IDs, events, metrics, traces, sinks, APM instrumentation, service/resource names, latency/throughput/error/saturation metrics, dashboards, SLO/SLI signals, exporter/provider choices such as OpenTelemetry or New Relic, retention/redaction, alert hooks, and how UI/API/domain/infrastructure errors are mapped, recovered, retried, degraded, or surfaced.
• Plans assign logging, telemetry, and error-handling work to PRs, including fixtures, APM setup, dashboards/alerts, pass/fail checks, and tests for representative success/ failure paths.
• Code implements and verifies the planned diagnostics and error handling without leaking secrets, stack traces, raw objects, or unstable internals to users, logs, APM providers, or agents.

Reviews stop when logging, telemetry, or error-handling intent is missing from the earlier document that should own it.

Delivery Profiles

Production work uses one feedback loop with review depth matched to risk: Lean for small, reversible changes; Standard as the ordinary default; and High-assurance for material security, privacy, safety, regulatory, financial, availability, migration, or irreversible data risk. Exploratory remains a separate non-production track. Profiles activate only extra checks for specific risks; they do not bypass readiness, tests, feedback, or human gates. See docs/assurance-profiles.md.

General Cleanup

Agents run a bounded cleanup pass at suitable handoff points, and always before ending a code slice, to remove odd issues and theater such as tautological tests, mock-only confidence, stale requirement-to-test links, superficial security work, debug leftovers, and misleading docs. Cleanup stays inside the current scope; larger discoveries become follow-up findings or revisions to earlier documents.

Simplify Pass

After cleanup when both apply, and before handoff for specs, designs, plans, and code slices, agents run a simplify pass. The pass removes over-engineered requirements, layers, abstractions, extension points, fixtures, checks, or code paths that are not justified by accepted scope, risk, constraints, or evidence. Necessary detail, reviewability, requirement links, and real boundaries stay intact; larger simplifications require changes to the controlling documents.

Simplicity is a hard assessment constraint. Process links and evidence must not become product architecture; work in an existing system reuses its compatibility suites by default; generalization normally waits for a second concrete consumer; and bounded slices default to at most three implementation PRs. Reviewers begin with deletion, deferral, collapse, and existing-evidence reuse. See docs/simplicity-first.md.

Feedback And Learning

Sarathi treats specs, designs, and plans as the current accepted understanding, not frozen handoffs. Approval means a document is sufficient and safe for the next learning step. Each code-ready slice names its learning target, appropriate stakeholder or observed-system feedback target, what result would change the plan, and a check for changes needed in parent documents. After assessment, the agent reports honest feedback status and checks whether the spec, design, remaining plan, code/integration, or process guidance must change.

Agent parallelism is encouraged inside a slice. Independent slices may share a bounded learning wave when feedback from one cannot materially change another, dependencies and touch ownership are explicit, WIP is capped, and ownership for combining work plus stop/replan rules are planned. Speculative later work stays exceptional and reversible. See docs/feedback-and-learning.md.

Breakdown plans use a WAVE-* only for near-term WORK-* children that share a feedback or integration checkpoint; unscheduled children have no wave. Implementation plans list the PRs for one child without assigning PRs to waves. The live status page shows that delivery sequence beside the work tree. .sdlc/wip.md identifies the active wave; a .sdlc/wave-checkpoints.yaml record matching the current plan closes a wave without pretending the enclosing plan is fully assessed or the next wave is automatically approved.

Human Gates And YOLO Mode

Default behavior is human-gated:

• If important input is missing, the agent asks one focused question at a time.
• After a document or code slice is generated, materially revised, reviewed, or assessed, the agent stops for human review.
• For UI-facing products, /spec-create asks whether a mock UI is required. If the spec records UI Mock Preference: Required, the mock UI file is a hard human gate: later planning, code, and production UI work must wait for explicit user approval of the mock.
• Reviews stop when they discover issues in an earlier spec, design, or plan.

The human review pause is a hard gate. A completed spec does not automatically flow into design; a completed design does not automatically flow into planning; a completed plan does not automatically flow into code; and an assessed code slice does not automatically flow into the next learning-dependent slice or release/deployment work until its feedback status and parent-document check are visible. The agent should end its turn with document paths, readiness/status, verification/review/assessment results, open questions, and the recommended next command.

You can opt into YOLO mode with phrases like:

yolo
use your judgment
make reasonable assumptions
proceed without questions

YOLO mode lets the agent make reasonable assumptions and continue, but it must record those assumptions, risks, and trade-offs. YOLO does not bypass readiness gates, planned touch sets, quality gates, safety constraints, or the default review pause unless you explicitly ask for end-to-end unattended continuation.

Approval Records

Projects can make approvals automatically checkable with local YAML files:

• .sdlc/approvals.yaml records local approvals, approvers, UTC timestamps, and SHA-256 hashes.
• .sdlc/gates.yaml optionally enables bounded auto-approval for low-risk modes such as internal prototypes.

Checkers support --require-approvals for later gate runs. The approval is valid only when the entry matches the gate, document path, status, UTC approved_at, and current file hash. Stale hashes fail. No ticketing system is required. This proves structure and freshness of a local record, not human identity, intent, or external consent; reports must show whether a gate was approved by a named user or by local auto-approval policy. Approval is permission for the next learning step, not proof that a document is final, correct, or informed by end-user feedback. Feedback source and status are recorded separately.

See docs/approval-gates.md.

Tests And Verification

Test responsibility is split by document and code stage:

• Specs define AT- acceptance criteria at product/system, feature/component, and slice/change scope; the criteria become narrower as the scope narrows. Specs also define JT- journey tests for long ordered stories that compose multiple AT- scenarios.
• Designs define the test architecture and explicit TEST-<AREA>-<NAME> executable test obligations for unit, component, contract, integration, UI, journey/e2e, quality, docs/build/deploy, migration, and operational checks.
• Designs also define the test environment strategy: developer environment always, plus shared integration/test, staging/pre-production, production canary/smoke, and synthetic monitoring when context warrants them.
• External systems should be tested against the real dependency or its official conformance surface whenever feasible. If a mock, fake, stub, local mirror, or locally re-declared interface replaces the real system, the documents must flag that as a risk and name the mitigation: real-boundary smoke/integration test, official conformance harness, type-conformance check, generated schema/client, vendor sandbox/emulator, captured real fixture, or explicit user-approved limitation. A primary integration seam should not be covered only by a self-authored double.
• Plans assign AT- acceptance coverage, JT- journey coverage, and TEST- obligations to PRs.
• Code writes the executable tests and implementation. This is where unit, component, contract, integration, UI, journey/e2e, quality, migration, build/deploy, docs, and operational test implementations are created when planned. A project may maintain a requirement-to-test inventory when its audit or assurance needs justify it; reviewers still inspect tests and their pass/fail checks.
• Code may also add implementation-local supplemental tests, such as helper, pure-core, parser, mapper, regression, characterization, table/property, adapter, or edge-case tests. These supplement, never replace, planned AT-/JT-/TEST- coverage; they stay within the current PR- and Planned Touch Set and use a clear pass/fail check. If they imply new externally visible behavior, contract, UX/NFR, or scope, revise the controlling document first.
• Test implementations are reviewed as code in /code-review and /code-assess: assertions, fixtures, helpers, mocks, data, selectors, determinism, readability, maintainability, and false-positive/false-negative risk are judged, not just whether the tests pass.
• Every executable test needs a clear pass/fail result: return value, state, persisted record, event, API response, DOM/accessibility output, screenshot/visual baseline, generated file, structured log, metric, trace, deployment signal, or captured external call as appropriate.
• Defect remediation updates earlier documents first when the defect reveals missing UX quality, unclear boundary contracts, missing logging/telemetry/error-handling intent, unrealistic mocks, or other latent spec/design/plan gaps.
• Documentation, logging/telemetry, error-handling, build, and deployment checks are assigned through the same spec/design/plan chain and verified during code creation, /code-verify, or /code-assess when planned. The same is true for environment-specific checks and context-driven reviews/tests such as performance, security, privacy, accessibility, resilience, migration, compatibility, cost, and operational checks. Production-facing telemetry should include APM/application-performance signals when warranted: latency, throughput, error rate, saturation/resource use, critical spans, trace propagation, dashboards, alerts, and SLO/SLI signals.

Use /code-verify when you simply want a confidence run after a change: planned tests, pre-commit/equivalent gates, logging/error-handling checks, build checks, documentation checks, deployment dry-runs or smoke checks where planned, and check_code.py. Use /code-review when you want independent judgment. Use /code-assess when you want both in one gate.

The checkers provide repeatable evidence about required structure and links:

python checkers/check_spec.py spec.md --json
python checkers/check_design.py design.md --json
python checkers/check_plan.py plan.md --spec spec.md --design design.md --json
python checkers/check_code.py --plan plan.md --tests-argv '["pytest","-q"]' --json

If python is unavailable, try python3, then uv run python.

Coverage targets and requirement-to-test inventories are project-level controls, not Sarathi defaults. When a project adopts them, document the purpose and owner in that project and review the resulting evidence; neither a percentage nor a mapping proves meaningful tests. Reviewability is judged by cohesive purpose, conceptual complexity, touch scope, evidence, and rollback. Sarathi does not impose source-file, module, diff, or PR line-count targets. TODO/FIXME/XXX/skip/xfail markers are surfaced with file, line, marker, and text. Do not add SDLC-specific annotations to app code. If markers remain, later progress requires explicit approval through code.markers.approved, keyed to the marker inventory hash.

The checkers do not prove that the work is correct. Assessment commands pair check results with independent review of requirements, design, plan quality, test implementation quality, pass/fail rigor, implementation fitness, logging/error-handling, documentation/build/deployment completeness, and consistency across stages.

Repository Layout

docs/      user-facing documentation and review notes
prompts/   source stage prompt definitions
skills/    native skill bundles
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
• Slug ID migration: docs/slug-id-migration.md
• Approval gates: docs/approval-gates.md
• Agent-facing repository guidance: AGENTS.md