aayudha

package module

v0.1.0 Latest Latest Go to latest Published: Oct 15, 2026 License: BSD-3-Clause Imports: 1 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/rahulnakmol/agentic-ayudha

Links

Open Source Insights

README ¶

agentic-ayudha

aayudha (alias aayu) is one static Go binary plus a set of host skills that run an agentic software delivery pod: twelve seats, nine application layers, and 32 verbs that take work from a grilled idea to a measured release, with proof packs and human gates along the way.

Status: pre-0.1. There is no v* release yet; v0.1.0 is the first. The build plan is docs/BUILD-PLAN.md; it is the source of truth for scope and sequencing.

Documentation: https://rahulnakmol.github.io/agentic-ayudha/, built from dev by aayu tell docs --site (WP8.2). New to aayudha? The site's guide (docs/guide) walks the journey from an idea to a measured release, with a real example.

Install

curl -fsSL https://raw.githubusercontent.com/rahulnakmol/agentic-ayudha/main/install.sh | sh
aayu doctor

Before v0.1.0 is released that line fails with a 404; install the latest rolling snapshot instead with go install github.com/rahulnakmol/agentic-ayudha/cmd/aayudha@rolling-2026-10-12.4 (Go 1.25 or newer; it installs aayudha, so add alias aayu=aayudha).

install.sh installs only a signed v* release: it checks the cosign signature of checksums.txt against this repository's release.yml workflow identity, then the archive's SHA-256. It runs on macOS, Linux, and Windows (Git Bash). docs/getting-started.md covers Scoop, Homebrew, and winget, and connecting Amp, Cursor, or Claude Code.

Hosts

Amp, Cursor, and Claude Code are the primary hosts. Skills ship as real copies (never symlinks) under .agents/skills/<verb>/SKILL.md and .claude/skills/<verb>/SKILL.md, installed by aayu install (WP3.2).

Branches

Branch	Role
`dev`	Default. Nightly integration; every feature PR targets it and squash-merges when CI is green.
`rolling`	Canary snapshots promoted from `dev` on the release schedule.
`main`	Stable releases promoted from `rolling`; every commit is tagged `v*`.
`ledger`	Orphan branch holding this repository's own proof packs and action segments.

See CONTRIBUTING.md for the PR flow and DCO sign-off, and SECURITY.md for reporting vulnerabilities and the tool-incident plan.

Governance: ETHOS.md (principles), GLOSSARY.md (terms), CONSTRAINTS.md (default floors, autonomy, budgets, and retention, generated), LAYERS.md (generated), AGENTS.md (guidance for coding agents), and docs/threat-model.md.

Verbs

The table is generated from internal/verbs/registry.go by go generate ./.... Do not edit it by hand; CI fails on drift.

Verb	Summary	Seat	Lane	Layers	Identity	Surfaces
`grill`	Interview a human until a work item of the given type is complete and passes validation, then write it as an issue.	Product Strategist	spec	all	bot	cli, skill, mcp
`slice`	Split a Feature into XS-L stories with observable criteria, dependencies, and a layer footprint; close XL items as split.	Product Strategist	plan	all	bot	cli, skill, mcp
`plan`	Plan a story: one checkpoint per layer, contracts, tests, instrumentation, and rollback.	Code Architect	plan	all	bot	cli, skill, mcp
`decide`	Record a Decision with options, evaluation, and recommendation; accept it, supersede it, or file a floor waiver.	Founder	spec	all	human	cli, skill, mcp
`triage`	Classify intake issues as Feedback, Bug, or Incident by label only; never edits bodies or touches non-intake issues.	Product Strategist	chore	none	bot	cli, skill, mcp
`build`	Build a Ready story or bug in a worktree with checkpoint commits per layer, verify each checkpoint, and open a PR.	AI Native Engineer (+SRE hat)	build	all	bot	cli, skill, mcp
`verify`	Run the deterministic floors (coverage, SAST, secrets, deps, a11y, perf) and record results in a proof pack.	AI Native Engineer (+SRE hat)	chore	all	bot	cli, skill, mcp
`inspect`	Adversarially review a PR against its plan, pack, and criteria; return a structured disposition: merge, fix, or rebuild.	Engineering Manager	review	all	bot	cli, skill, mcp
`ship`	Squash-merge a PR after a green merge gate and a human pass, write the Complete section, and clean up.	Engineering Manager	chore	all	human	cli, skill
`release`	Promote a Release along dev, rolling, main; stamp included stories released and trigger measurement.	DevOps & DevEx Tinkerer	chore	L09	human	cli, skill
`proof`	Push, get, verify, or list proof packs on the ledger branch; comment is the merge gate's pack check.	Quality Architect	chore	all	bot	cli, skill, mcp
`ready`	Validate a work item for Ready, label it status:ready, and post the Ready snapshot; --check is read-only.	Product Strategist	chore	all	bot	cli, skill, mcp
`research`	Gather pinned design references (URLs and IDs only) and user research for a Feature.	UX Researcher & Evolutionist	spec	L01	bot	cli, skill, mcp
`wireframe`	Produce wireframes for a Feature's states from its research and criteria.	UX Researcher & Evolutionist	build	L01	bot	cli, skill, mcp
`mockup`	Produce design-system mockups for a Feature from its wireframes.	UX Researcher & Evolutionist	build	L01	bot	cli, skill, mcp
`prototype`	Build a flagged, working prototype of a Feature with Code Connect mapping and a Figma screenshot diff.	UX Researcher & Evolutionist	build	L01, L02	bot	cli, skill, mcp
`review`	Critique UI with a model lane and a deterministic lane; dispositions recapture, rebuild, fix, or ship.	UX Researcher & Evolutionist	ui-review	L01	bot	cli, skill, mcp
`polish`	Apply a review critique to a PR's UI and re-run review.	UX Researcher & Evolutionist	build	L01	bot	cli, skill, mcp
`baseline`	Capture visual baselines for a commit SHA.	UX Researcher & Evolutionist	chore	L01	bot	cli, skill, mcp
`experiment`	Design an experiment for a Feature: hypothesis, metric, flag, and minimum sample size.	Revenue Architect	plan	L03, L08	bot	cli, skill, mcp
`readout`	Read out an experiment's lift once it reaches minimum sample and write the Result.	Revenue Architect	spec	L08	bot	cli, skill, mcp
`respond`	Respond to an incident: propose an ops catalog action, execute it only through human approval, keep the timeline.	AI Native Engineer (+SRE hat)	build	L07, L09	human	cli, skill
`status`	Roll up status, health, risk, proof coverage, decisions, and cost per Goal, Initiative, and Feature.	Engineering Manager	chore	all	bot	cli, skill, mcp
`audit`	Audit floors, proof coverage, waivers, decision SLAs, autonomy exceptions, and unlogged writes; write a reproducible report.	Auditor	review	all	bot	cli, skill, mcp
`retro`	Compare estimates with observed delivery, corrections, floor misses, and cost; file findings as Feedback issues.	Engineering Manager	spec	all	bot	cli, skill, mcp
`measure`	Measure a Goal or Initiative against its baseline from analytics exports or live cloud pulls and write the Result.	Revenue Architect	chore	L08	bot	cli, skill, mcp
`evolve`	Turn accepted retro Feedback into a failing eval case, then a skill diff that passes it, opened as an agent-authored PR.	AI Native Engineer (+SRE hat)	build	L05	bot	cli, skill, mcp
`brief`	Explain work to an audience in a chosen register and purpose as a grounded, accessible HTML brief.	Mentalist	spec	all	bot	cli, skill, mcp
`tell`	Write docs, guides, changelogs, release notes, launch copy, or brand copy that cite only proven Features; publish is human-only.	Marketer & Documenter	spec	L01	human	cli, skill, mcp
`init`	Set up a product repo: labels, issue types, forms, config, ledger branch, and optionally projects, gates, identity, integrations.	Founder	chore	L09	human	cli
`install`	Install skill copies, lock.toml, MCP registration, and hooks for each host; shows a diff unless --apply.	DevOps & DevEx Tinkerer	chore	L09	human	cli
`doctor`	Check tools, tokens, identity, config, host installs, and existing CI; --fix re-syncs copies after showing a diff.	DevOps & DevEx Tinkerer	chore	L09	human	cli, skill, mcp

Plumbing commands

Command	Summary	Seat
`config`	Show, validate, or initialise layered configuration.	DevOps & DevEx Tinkerer
`auth`	Show the human token and bot identity aayudha resolves, with scope warnings; set, delete, or list named secrets.	DevOps & DevEx Tinkerer
`actions`	Tail, search, or verify the hash chain of the actions log.	DevOps & DevEx Tinkerer
`models`	Show the resolved model for each lane and host.	DevOps & DevEx Tinkerer
`mcp`	Serve verbs as MCP tools over stdio.	DevOps & DevEx Tinkerer
`self-update`	Replace the binary with a signed, newer release; refuses downgrades and agents.	DevOps & DevEx Tinkerer
`upgrade`	Migrate repo config, lock, state, and skill copies to this binary's schema versions.	DevOps & DevEx Tinkerer
`version`	Print the binary version.	DevOps & DevEx Tinkerer
`halt`	Stop every agent lane, loop, and workflow in the repo until resume.	Founder
`resume`	Clear a halt.	Founder
`gc`	Prune stale worktrees and leases.	DevOps & DevEx Tinkerer
`uninit`	Remove what init created, by stored IDs.	DevOps & DevEx Tinkerer
`hook`	Entry point for host hooks; hooks call only `aayu hook <name>`.	DevOps & DevEx Tinkerer
`seat`	Add, remove, or list seats and their paired humans.	Founder
`lfs-agent`	git-lfs custom transfer agent for S3/R2 storage.	DevOps & DevEx Tinkerer
`next`	Print the single best next step for this repository: the exact command to run and why.	Engineering Manager
`tour`	Guided first run: check this machine, then set the repository up at Level 1 in a few prompts; refused for agents.	Founder
`completion`	Print the shell completion script, generated from the registry, for bash, zsh, fish, or PowerShell.	DevOps & DevEx Tinkerer

Licence

BSD-3-Clause. See LICENSE and THIRD_PARTY_NOTICES.md.

Documentation ¶

Overview ¶

Package aayudha embeds the source asset trees that ship inside the aayudha binary (docs/BUILD-PLAN.md ground rule 3). Owned by WP0.2.

Running `go generate ./...` from the repository root regenerates every artifact derived from the verb registry in internal/verbs (ground rule 4) and CONSTRAINTS.md from the embedded default configuration in internal/config (WP0.5), and the work-item issue forms from the schema in internal/workitems (WP2.2), and the docs guide's diagrams with the brief diagram renderer (internal/tell/gen, WP8.2).

Index ¶

Variables

Constants ¶

This section is empty.

Variables ¶

View Source

var Assets embed.FS

Assets holds skills/, work-items/, hosts/, and seats/ exactly as committed.

Functions ¶

This section is empty.

Types ¶

This section is empty.

Source Files ¶

View all Source files

embed.go

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
aayudha command Command aayudha (alias aayu) is the agentic-ayudha binary.	Command aayudha (alias aayu) is the agentic-ayudha binary.
examples
benefits-qa/analytics Package analytics turns the benefits-qa example's product events into an Application Insights export (layer L08, docs/BUILD-PLAN.md WP8.1): JSON lines in the Log Analytics shape (TimeGenerated, Name, UserAuthenticatedId) that `aayu measure --appinsights` reads.	Package analytics turns the benefits-qa example's product events into an Application Insights export (layer L08, docs/BUILD-PLAN.md WP8.1): JSON lines in the Log Analytics shape (TimeGenerated, Name, UserAuthenticatedId) that `aayu measure --appinsights` reads.
benefits-qa/analytics/simulate command Command simulate writes a synthetic Application Insights export of the benefits-qa example (docs/BUILD-PLAN.md WP8.1): a seeded population of fictional employees asking benefits questions through a channel.	Command simulate writes a synthetic Application Insights export of the benefits-qa example (docs/BUILD-PLAN.md WP8.1): a seeded population of fictional employees asking benefits questions through a channel.
benefits-qa/answer Package answer finds the plan passage that answers a benefits question (layer L05, docs/BUILD-PLAN.md WP8.1).	Package answer finds the plan passage that answers a benefits question (layer L05, docs/BUILD-PLAN.md WP8.1).
benefits-qa/api Package api is the benefits-qa example's HTTP boundary (layer L02, docs/BUILD-PLAN.md WP8.1): POST /api/ask takes a contracts.AskRequest and answers a contracts.AskResponse; GET /healthz reports readiness.	Package api is the benefits-qa example's HTTP boundary (layer L02, docs/BUILD-PLAN.md WP8.1): POST /api/ask takes a contracts.AskRequest and answers a contracts.AskResponse; GET /healthz reports readiness.
benefits-qa/ask Package ask is the benefits-qa example's question workflow (layer L03, docs/BUILD-PLAN.md WP8.1): screen the question (policy), retrieve the best plan passage (answer), ground it (policy), and shape the contract response, recording each step as a product event for analytics.	Package ask is the benefits-qa example's question workflow (layer L03, docs/BUILD-PLAN.md WP8.1): screen the question (policy), retrieve the best plan passage (answer), ground it (policy), and shape the contract response, recording each step as a product event for analytics.
benefits-qa/cmd/benefits-qa command Command benefits-qa serves the benefits-qa example (layer L02, docs/BUILD-PLAN.md WP8.1): the Ask page at /, POST /api/ask, and GET /healthz, over the embedded synthetic plan documents.	Command benefits-qa serves the benefits-qa example (layer L02, docs/BUILD-PLAN.md WP8.1): the Ask page at /, POST /api/ask, and GET /healthz, over the embedded synthetic plan documents.
benefits-qa/contracts Package contracts is the benefits-qa example's API contract (layer L06, docs/BUILD-PLAN.md WP8.1): the request and response of POST /api/ask as Go types, and ask.schema.json, the JSON Schema generated from them that clients integrate against.	Package contracts is the benefits-qa example's API contract (layer L06, docs/BUILD-PLAN.md WP8.1): the request and response of POST /api/ask as Go types, and ask.schema.json, the JSON Schema generated from them that clients integrate against.
benefits-qa/deploy Package deploy holds how the benefits-qa example is run (layer L09, docs/BUILD-PLAN.md WP8.1): serve.sh builds it and starts it detached on its synthetic seed data, the `[verify] seed` command aayudha's web floors run before they capture the Ask page.	Package deploy holds how the benefits-qa example is run (layer L09, docs/BUILD-PLAN.md WP8.1): serve.sh builds it and starts it detached on its synthetic seed data, the `[verify] seed` command aayudha's web floors run before they capture the Ask page.
benefits-qa/policy Package policy decides what the benefits-qa example may answer (layer L04, docs/BUILD-PLAN.md WP8.1).	Package policy decides what the benefits-qa example may answer (layer L04, docs/BUILD-PLAN.md WP8.1).
benefits-qa/store Package store holds the benefit plan passages the benefits-qa example answers from (layer L07, docs/BUILD-PLAN.md WP8.1).	Package store holds the benefit plan passages the benefits-qa example answers from (layer L07, docs/BUILD-PLAN.md WP8.1).
benefits-qa/web Package web is the benefits-qa example's Ask page (layer L01, docs/BUILD-PLAN.md WP8.1): a server-rendered page, styled only with the design-system tokens, that asks the question workflow and shows the answer with its sources, a referral to HR, or a refusal.	Package web is the benefits-qa example's Ask page (layer L01, docs/BUILD-PLAN.md WP8.1): a server-rendered page, styled only with the design-system tokens, that asks the question workflow and shows the answer with its sources, a referral to HR, or a refusal.
internal
actions Package actions is the single path for external writes (ground rule 6, WP1.5).	Package actions is the single path for external writes (ground rule 6, WP1.5).
audit Package audit builds aayudha's audit report (WP7.6): it reconciles GitHub's own event history (rule-suite bypasses, issue and PR timelines, workflow runs) against the actions segments on the ledger (ground rule 6) and reports solo-mode bypasses, founder-identity ledger writes, promotions, tag ruleset bypasses, human-fallback writes, unlogged writes, proof coverage, floors, waivers, decision SLAs, autonomy exceptions, and the licence scan.	Package audit builds aayudha's audit report (WP7.6): it reconciles GitHub's own event history (rule-suite bypasses, issue and PR timelines, workflow runs) against the actions segments on the ledger (ground rule 6) and reports solo-mode bypasses, founder-identity ledger writes, promotions, tag ruleset bypasses, human-fallback writes, unlogged writes, proof coverage, floors, waivers, decision SLAs, autonomy exceptions, and the licence scan.
autonomy Package autonomy computes the autonomy streak (WP5.7, V4): for each layer, the number of consecutive correction-free agent PRs merged on it, counted back from the newest.	Package autonomy computes the autonomy streak (WP5.7, V4): for each layer, the number of consecutive correction-free agent PRs merged on it, counted back from the newest.
brief Package brief implements `aayu brief` (WP7.3, WP7.4): a host-written Markdown draft, grounded in a work item's evidence, is checked deterministically (structure, citations, the register's lint, visuals), then rendered as one self-contained, accessible HTML page with a grounding footer, inline SVG diagrams and charts, labelled illustrations, and annotated screens from proof packs.	Package brief implements `aayu brief` (WP7.3, WP7.4): a host-written Markdown draft, grounded in a work item's evidence, is checked deterministically (structure, citations, the register's lint, visuals), then rendered as one self-contained, accessible HTML page with a grounding footer, inline SVG diagrams and charts, labelled illustrations, and annotated screens from proof packs.
cli Package cli is the aayudha command-line frame.	Package cli is the aayudha command-line frame.
config Package config loads and validates aayudha configuration.	Package config loads and validates aayudha configuration.
config/gen command Command gen regenerates CONSTRAINTS.md from the embedded default configuration (internal/config/defaults.toml, docs/BUILD-PLAN.md WP0.5).	Command gen regenerates CONSTRAINTS.md from the embedded default configuration (internal/config/defaults.toml, docs/BUILD-PLAN.md WP0.5).
decide Package decide holds the rules of `aayu decide` (WP5.6, V8): who may accept a Decision ([decisions] authority), its SLA clock in business hours (time), what lapses at the SLA (a page to the authority and an escalation comment that mentions [decisions] escalate_to) and at provisional_after_hours (a reversible Decision's recommendation applies provisionally, labelled decision:provisional, with a ratify-or-revert deadline in its body), and floor waivers (`decide --waiver`).	Package decide holds the rules of `aayu decide` (WP5.6, V8): who may accept a Decision ([decisions] authority), its SLA clock in business hours (time), what lapses at the SLA (a page to the authority and an escalation comment that mentions [decisions] escalate_to) and at provisional_after_hours (a reversible Decision's recommendation applies provisionally, labelled decision:provisional, with a ratify-or-revert deadline in its body), and floor waivers (`decide --waiver`).
delegate Package delegate hands a Ready story to another coding agent (WP5.5b): the Codex, Cursor, Claude Code, or Amp cloud agent, or its CLI on this machine in an aayu worktree.	Package delegate hands a Ready story to another coding agent (WP5.5b): the Codex, Cursor, Claude Code, or Amp cloud agent, or its CLI on this machine in an aayu worktree.
design Package design holds the deterministic half of the design verbs (WP6.5): research, wireframe, mockup, and prototype.	Package design holds the deterministic half of the design verbs (WP6.5): research, wireframe, mockup, and prototype.
doctor Package doctor implements `aayu doctor` (WP1.7): environment, identity, configuration, and coexistence checks.	Package doctor implements `aayu doctor` (WP1.7): environment, identity, configuration, and coexistence checks.
evals Package evals is the skill eval harness (WP3.4).	Package evals is the skill eval harness (WP3.4).
evals/cmd/eval command Command eval runs the skill eval harness outside go test (WP3.4).	Command eval runs the skill eval harness outside go test (WP3.4).
experiment Package experiment holds what `aayu experiment` and `aayu readout` (WP6.7) compute: the minimum sample size per arm for a conversion experiment, the lift between two arms with its two-proportion z-test, and the text both verbs write into an Experiment issue.	Package experiment holds what `aayu experiment` and `aayu readout` (WP6.7) compute: the minimum sample size per arm for a conversion experiment, the lift between two arms with its two-proportion z-test, and the text both verbs write into an Experiment issue.
github Package github is aayudha's GitHub API client (WP2.3): REST through go-github for issues, sub-issues, issue types, labels, comments, refs, and rulesets, and GraphQL through githubv4 only for Projects v2.	Package github is aayudha's GitHub API client (WP2.3): REST through go-github for issues, sub-issues, issue types, labels, comments, refs, and rulesets, and GraphQL through githubv4 only for Projects v2.
github/fake Package fake is an in-memory GitHub for tests of the verbs: the REST endpoints M2 uses (users, repositories, labels, issue types, rulesets, git refs/trees/commits, issues, comments, sub-issues) with enough fidelity that a verb's second run sees what its first run wrote.	Package fake is an in-memory GitHub for tests of the verbs: the REST endpoints M2 uses (users, repositories, labels, issue types, rulesets, git refs/trees/commits, issues, comments, sub-issues) with enough fidelity that a verb's second run sees what its first run wrote.
github/scratch Package scratch creates and deletes the aayu-scratch-* repositories that live tests (AAYU_LIVE=1) run against.	Package scratch creates and deletes the aayu-scratch-* repositories that live tests (AAYU_LIVE=1) run against.
grill Package grill holds what makes a grilled spec concrete (WP5.3b): the catalogues that decompose vague qualifiers ("high quality", "fast") into dimensions, the checks that a Story's or Bug's criteria leave no qualifier unresolved and record who stated or confirmed each one, and the read-only assessment of the repository that grounds the questions in facts.	Package grill holds what makes a grilled spec concrete (WP5.3b): the catalogues that decompose vague qualifiers ("high quality", "fast") into dimensions, the checks that a Story's or Bug's criteria leave no qualifier unresolved and record who stated or confirmed each one, and the read-only assessment of the repository that grounds the questions in facts.
hosts Package hosts adapts skills, hooks, and MCP registration to each host.	Package hosts adapts skills, hooks, and MCP registration to each host.
identity Package identity resolves human and bot GitHub identities.	Package identity resolves human and bot GitHub identities.
identity/cmd/protected-paths-gate command Command protected-paths-gate decides the protected-paths check from API responses the workflow saved to files (.github/workflows/protected-paths.yml).	Command protected-paths-gate decides the protected-paths check from API responses the workflow saved to files (.github/workflows/protected-paths.yml).
initrepo Package initrepo sets up a product repository (WP2.5 `aayu init`, WP2.6 extras) and takes it apart again (`aayu uninit`).	Package initrepo sets up a product repository (WP2.5 `aayu init`, WP2.6 extras) and takes it apart again (`aayu uninit`).
inspect Package inspect implements `aayu inspect` (WP4.8): an adversarial review of a pull request by the review lane's model (a different family from the builder's), against the story's Completion Goal and the PR's proof pack.	Package inspect implements `aayu inspect` (WP4.8): an adversarial review of a pull request by the review lane's model (a different family from the builder's), against the story's Completion Goal and the PR's proof pack.
integrations Package integrations holds what aayudha's provider adapters share (WP5.2): the reproducible baseline tuple, resolution of [integrations.<name>] for a read verb (WP1.3 scope refusal before any call), the provider-reported key scope that doctor and the adapters verify, and a transport that keeps every adapter read-only.	Package integrations holds what aayudha's provider adapters share (WP5.2): the reproducible baseline tuple, resolution of [integrations.<name>] for a read verb (WP1.3 scope refusal before any call), the provider-reported key scope that doctor and the adapters verify, and a transport that keeps every adapter read-only.
integrations/aws Package aws is the AWS adapter (WP7.2b): baselines from CloudWatch Logs Insights over a CloudWatch RUM app monitor's log group, and event pulls from CloudWatch RUM (GetAppMonitorData), signed with Signature Version 4 (the WP4.2 signer).	Package aws is the AWS adapter (WP7.2b): baselines from CloudWatch Logs Insights over a CloudWatch RUM app monitor's log group, and event pulls from CloudWatch RUM (GetAppMonitorData), signed with Signature Version 4 (the WP4.2 signer).