# aayudha docs

> Your coding agent can write a feature in an afternoon. Whether that feature does what you promised, is safe to merge, and helps anyone at all is a different question. aayudha is the delivery team around the agent you already use: Claude Code, Codex, Cursor, or Amp. It answers that question with evidence at every step, from a fuzzy idea to a number that moved.

Every page below is Markdown; the same path ending in .html is the page for people. Start with the first group, then read the How it works pages for the mechanics.

## Start here

- [Ship what you promised, and prove it](index.md): What aayudha is, the problem it solves, and the real run it was proven on.
- [Your first hour](start.md): Install aayudha, run the guided tour, file your first story with checkable promises, and ask what to do next.
- [When to use what](when-to-use-what.md): Start from your situation (a vague idea, a bug, a ready pull request, an incident) and find the verb to run.
- [Adopt at your own pace](adopt.md): Three adoption levels, each a complete stopping point, with what each costs and gives.

## The story

- [Prologue: your Monday](journey.md): The real 12 October run, told to you: from a vague goal to a measured release in nine chapters.
- [1. The goal](journey-1-shape.md): Shaping a Goal with a measured baseline and a target, using the grill interview.
- [2. The plan](journey-2-break-down.md): Breaking the Goal into an Initiative, Features, and small stories with slice and plan.
- [3. The promises](journey-3-ready.md): Writing checkable promises for each story and freezing them as Ready.
- [4. The build](journey-4-build.md): How the agent builds a Ready story in its own worktree and opens a pull request.
- [5. The gate says no](journey-5-prove.md): How the merge gate, proof packs, and a reviewer of another vendor sent work back until it was right.
- [6. The yes](journey-6-ship.md): How a person's approval and ship merge a proven pull request, with a record of who approved what.
- [7. The release](journey-7-release.md): How shipped work moves from dev to a rolling snapshot after a full gate.
- [8. The number](journey-8-learn.md): Measuring the Goal against its baseline, then retro and evolve to learn from the work.
- [9. The telling](journey-9-explain.md): Explaining the work to a boss or auditor with brief and tell, every claim checked.
- [Epilogue: built with itself](built-with-itself.md): How aayudha builds and proves itself, and what is still unfinished.

## Guides

- [How aayudha unpacks a vague ask](unpack.md): How a vague request such as "make it slick" is unpacked into checkable promises before anything is built.
- [A pull request is ready](guide-review.md): What happens when a pull request is ready: the merge gate, the reviewer app, fix rounds, and ship.
- [Hand work to an agent](guide-build.md): Building a Ready story yourself or handing it to another agent's cloud, and preparing its environment.
- [Prove a behaviour change](guide-prove-behaviour.md): Proving a behaviour change with a feature map and behaviour checks that drive your product like a person.
- [Keep things moving with loops](guide-loops.md): Setting up scheduled and event loops on each agent, and which host can start on which GitHub event.
- [Run it alone: the solo founder](guide-solo-founder.md): Working alone: what you still do by hand, the solo-mode bypass, the inbox, provisional Decisions, and earned autonomy.
- [From MVP to scale, with a lean team](growth.md): An illustrative path from a two-founder MVP to a widely used product: team stages, product streams, and what the agent twins carry at each stage.
- [Bring in analytics and errors: PostHog and Sentry](guide-integrations.md): When and how to connect PostHog and Sentry read-only: setup, config, key scopes, what each verb reads, and what aayu never does.
- [Did it work, and what do we learn?](guide-learn.md): Measuring whether a release moved the Goal, running retro, and evolving skills with ratchets.
- [Troubleshooting](troubleshooting.md): Symptoms, exit codes, and fixes for install, tour, Ready, the merge gate, ship, hand-offs, and loops.

## Skills

- [Every skill, one page each](skills/index.md): Every verb on its own page: what it is for, the prompt and command, what you get back, its seat and twin, its gates, and what only a person does.
- [init`: set up a repository](skills/init.md): Sets up a repository for aayudha: labels, issue forms, config, and the records branch; more on request.
- [install`: put aayudha into your agent](skills/install.md): Installs the aayudha skills, tools, and hooks into your agent, and sets up its cloud environment and loops.
- [doctor`: find out what is wrong with your setup](skills/doctor.md): Checks your machine and setup, and says exactly what to fix.
- [grill`: turn an idea into a work item](skills/grill.md): Interviews you, one question at a time, until an idea is a complete work item, then files it on GitHub.
- [survey`: understand code nobody documented](skills/survey.md): Reads a codebase nobody documented, says what it does with a citation for every claim, and drafts the backlog to modernise it.
- [slice`: split a Feature into small stories](skills/slice.md): Splits a Feature into small stories, each with checkable promises, the parts of the code it touches, and its order.
- [plan`: plan a story one layer at a time](skills/plan.md): Plans a story one layer at a time: what changes, how it is tested, and how to roll it back.
- [decide`: record a choice and who made it](skills/decide.md): Records a real choice with its options and a recommendation; only a person with the authority accepts it.
- [chart`: design the data or AI behind a change](skills/chart.md): Before a data or AI change is planned, works out with you which decisions it serves, which data or evidence answers them, and how to prove it right.
- [scope`: plan what a release contains, and keep it](skills/scope.md): Plans what a release contains, freezes it once a person accepts it, and stops later changes beyond the budget unless a person decides.
- [ready`: freeze what done means](skills/ready.md): Checks that a work item is complete and freezes exactly what was agreed, so later edits are visible.
- [research`: gather references and user research for a Feature](skills/research.md): Collects design references and user research for a Feature.
- [wireframe`: sketch one screen per state](skills/wireframe.md): Sketches the screens a Feature needs, from its research and promises.
- [mockup`: style the wireframes with your design system](skills/mockup.md): Turns wireframes into mockups that use your design system.
- [prototype`: build the design as working UI behind a flag](skills/prototype.md): Builds a working prototype behind a flag and compares it with the design.
- [review`: critique a pull request's screens](skills/review.md): Critiques a pull request's screens with a model and with fixed accessibility checks.
- [polish`: fix what the design review found](skills/polish.md): Applies a design critique to a pull request and reviews it again.
- [baseline`: capture reference screenshots of a commit](skills/baseline.md): Captures reference screenshots of a commit to compare later changes against.
- [build`: turn a Ready story into a pull request](skills/build.md): Writes the code for a Ready story in small checked steps, one layer at a time, and opens a pull request.
- [verify`: run the fixed checks before the gate does](skills/verify.md): Runs the fixed checks (tests, security, secrets, dependencies, accessibility, speed) and records the results.
- [inspect`: get a second opinion from another vendor](skills/inspect.md): A model from another vendor, or an agent app you choose, reviews the pull request against every promise; aayu reads its reply as merge, fix, or rebuild.
- [proof`: find and check the evidence for a change](skills/proof.md): Stores, fetches, and checks the proof packs that hold the evidence for each change.
- [ship`: merge a proven pull request](skills/ship.md): Merges a proven pull request after your yes, and writes down who approved what, on which evidence.
- [release`: promote merged work to a snapshot or a stable release](skills/release.md): Moves shipped work up to a snapshot or stable release, after a full gate, and schedules the measurement.
- [experiment`: design an A/B test before you release](skills/experiment.md): Designs an A/B test for a Feature: what you expect, what you measure, and how many people you need.
- [readout`: read out an experiment's lift](skills/readout.md): Reads out an experiment once it has enough people, and writes down the measured lift.
- [retro`: learn from how the work went](skills/retro.md): Compares plans with what happened and files what to improve as feedback you can accept or reject.
- [measure`: find out whether the Goal's number moved](skills/measure.md): Measures a Goal against its baseline, the same way as before, and writes the result into the Goal.
- [evolve`: stop the agents repeating a mistake](skills/evolve.md): Turns accepted feedback into a test for a skill, then a skill change that passes it, for a person to review.
- [counsel](skills/counsel.md): Asks the founder's sage for a steer on anything, with the evidence behind it and the next step; it advises and never approves or decides.
- [brain](skills/brain.md): Keeps the product's lasting knowledge as linked notes that link to issues and outlive any one person.
- [status`: see where every Goal stands](skills/status.md): Rolls up progress, risk, proof, open decisions, and cost for each Goal, Initiative, and Feature.
- [audit`: hand an auditor a report they can reproduce](skills/audit.md): Writes a report anyone can reproduce: checks, proof, waivers, deadlines, bypasses, and any write that skipped the log.
- [brief`: explain the work to one audience](skills/brief.md): Explains a piece of work to one audience in a short page, where every claim is checked against its sources.
- [tell`: write docs and release notes from proven work](skills/tell.md): Writes docs, release notes, and launch copy in your brand's voice, linking only work that is proven.
- [triage`: sort incoming reports](skills/triage.md): Sorts incoming reports into feedback, bugs, and incidents by label, without editing what people wrote.
- [respond`: handle a production incident](skills/respond.md): Helps handle an incident: proposes a fix from your runbook, runs it only after a person approves, and keeps the timeline.
- [investigate`: find what broke in production](skills/investigate.md): Works out what went wrong in production from your telemetry and the code that was actually deployed, and suggests a fix for a person to approve.
- [slo`: agree how reliable is reliable enough](skills/slo.md): Sets how reliable the product must be for its users, measures how much room for failure is left, and holds back risky releases when it runs out.
- [runbook`: write down how to fix a known failure](skills/runbook.md): Writes down how to spot and fix each known production problem with the approved actions, so whoever is on call can follow it.

## Your agent

- [aayudha in your agent](hosts.md): aayudha works inside the agent you already use.
- [aayudha in Claude Code](hosts-claude-code.md): Claude Code gets aayudha as a plugin: every verb as a slash command and skill, `/aayudha:home` and `/aayudha:next` for where the work stands, the aayudha MCP server, and the hooks that keep agents inside the rules.
- [aayudha in OpenAI Codex](hosts-codex.md): Codex, in the terminal and in the IDE extension, reads aayudha's skills, `AGENTS.md`, and MCP server.
- [aayudha in GitHub Copilot](hosts-copilot.md): If Copilot is your team's only AI tool, aayudha runs inside it.
- [aayudha in Amp](hosts-amp.md): Amp gets aayudha as a project plugin: palette commands for the main verbs, your journey at the start of every thread, and the hooks.
- [aayudha in Cursor](hosts-cursor.md): Cursor reads aayudha's skills, `AGENTS.md`, and MCP server, and runs its hooks.
- [Make it yours](make-it-yours.md): Changing aayu's colours, symbols, and voice in your terminal and docs.

## How it works

- [How it works](how-it-works.md): This track is for engineers.
- [Architecture](how-architecture.md): aayudha is one static Go binary, `aayudha` (alias `aayu`), plus a set of skills that it copies into your coding host.
- [The verb registry and code generation](how-registry.md): Every command aayudha has is declared once, as Go data, in `internal/verbs/registry.go`.
- [Trust model and identities](how-trust.md): aayudha lets agents open issues, push branches, and write records, and it is designed so that an agent never certifies or approves its own work: CI builds the proof that counts, a person's `ship` checks where it came from and records it, a…
- [The ledger branch](how-ledger.md): The ledger is an orphan branch named `ledger` in the product's own repository.
- [Proof packs](how-proof-packs.md): A proof pack is one `pack.json` file, plus the artifacts it names, that records what CI observed about one exact commit of one story.
- [The merge gate](how-merge-gate.md): The merge gate is one GitHub Actions workflow, `aayudha-merge-gate.yml`, that runs on every non-draft pull request.
- [Code review in the merge gate](how-review.md): An agent wrote the change; something other than that agent must read it before it merges.
- [Floors in detail](how-floors.md): A floor is a deterministic check with a fixed threshold that `aayu verify` runs on a commit: a pinned tool, a number, and a comparison.
- [Verify skills, feature maps, and behaviour checks](how-verify-maps.md): A feature map is a list of what a product can do, kept in the repository, with a behaviour check for each capability.
- [The model gateway and lanes](how-models.md): Every verb that needs judgement runs in a **lane**: a named class of model work, such as `build` or `review`, with a settled default model for each host.
- [The eval harness](how-evals.md): Skills are prompts, and a prompt can get worse without anyone noticing.
- [Hand-offs, agent environments, and loops](how-agents.md): aayudha 0.2 lets the agent you work in hand a story to another agent, prepares the cloud environment that agent builds in, and starts recurring work on a schedule.
- [Configuration, secrets, and the audit trail](how-config-and-audit.md): Three parts of aayudha decide what it is allowed to do and let you check, later, what it actually did.
- [Releases and the supply chain](how-releases.md): A release moves code from `dev`, where pull requests land, to `rolling`, a snapshot for early adopters, and then to `main`, where every commit is a signed, versioned release.
- [Security and the threat model](how-security.md): aayudha lets agents open issues, push branches, run tools, and write records.
- [Extending aayudha](how-extending.md): aayudha grows in four ways: a new verb, a new floor, a new host, or a new integration.

## Concepts

- [The delivery loop](concepts-loop.md): The seven steps every change takes, who does what at each, where the gates and floors sit, and how the loops run.
- [Your agentic team](concepts-team.md): The fourteen seats and their twins, who answers for what, who owns which layer, which model does the work, and how a seat goes from solo to paired.
- [Seats and pairing](concepts-seats.md): A delivery team works because everyone knows their job.
- [The nine layers](concepts-layers.md): Every application, however small, has the same kinds of parts: screens, an API, business rules, data, and so on.
- [Proof packs](concepts-proof.md): When an agent says "done", how do you know? A **proof pack** is the answer.
- [Floors](concepts-floors.md): A **floor** is a fixed check with a fixed threshold.
- [The human pass and solo mode](concepts-human-pass.md): Agents do most of the work in aayudha, but some decisions belong to people: merging a change, accepting a decision, publishing, releasing.
- [dev, rolling, main](concepts-ladder.md): Every change climbs the same three-rung ladder before it reaches everyone.

## Reference

- [aayudha](overview.md): Your coding agent can write a feature in an afternoon.
- [Project reference](reference.md): The reference for people who work on aayudha itself, or want every detail in one place.
- [Getting started](getting-started.md): This guide installs `aayudha` (alias `aayu`), checks the machine, and connects a product repository to Amp, Cursor, or Claude Code.
- [Verbs](verbs.md): aayudha has 40 verbs and 19 plumbing commands.
- [Glossary](glossary.md): Terms used across the build plan (docs/BUILD-PLAN.md), the docs, and the binary.
- [Threat model](threat-model.md): This expands BUILD-PLAN.md §0.1 (WP0.5).

## Clouds

- [Getting started on Azure](getting-started-azure.md): aayudha reads Application Insights for `grill` baselines and `aayu measure --live`, and can keep proof media in a private Blob Storage container.
- [Getting started on AWS](getting-started-aws.md): aayudha reads CloudWatch RUM for `grill` baselines and `aayu measure --live`.
- [Getting started on Google Cloud](getting-started-gcp.md): aayudha reads the Google Analytics 4 BigQuery export for `grill` baselines and `aayu measure --live`, and can keep proof media in a private Cloud Storage bucket.

## Project

- [Contributing](contributing.md): Thanks for helping.
- [Security policy](security.md): This file covers two things: how to report a vulnerability in `aayudha`, and what the maintainer does when the tool itself is compromised (the tool-incident plan, WP0.1).
- [Constraints](constraints.md): The defaults every product repository starts with.
- [Layers](layers.md): Generated from `internal/verbs/registry.go` by `go generate ./...`.
- [RACI](raci.md): Generated from `internal/verbs/registry.go` and `internal/verbs/raci.go` by `go generate ./...` (WP5.1).