plan: plan a story one layer at a time
An agent that starts coding without a plan touches more than it should, and nobody can review it until it is
done. plan writes one checkpoint per layer the story touches: what changes, the tests
that prove it, and how to roll it back, checked and kept on the ledger before any code exists.
| Field | Value |
|---|---|
| In plain words | Plans a story one layer at a time: what changes, how it is tested, and how to roll it back. |
| Journey stage | Break it down |
| Accountable seat | Code Architect (Vishwa) |
| Does the work | Vishwa, the Accountable seat's twin, in the plan model lane, with the seat's paired human when it has one |
| Consulted | Engineering Manager (Drona), Quality Architect (Yama), Data & AI Architect (Shuka), Production Engineer (Shesha) |
| Informed | AI Native Engineer (Nakul) |
| Layers it can touch | every layer |
| Who reasons | your agent's own model, inside the skill |
| Writes as | the bot identity (a GitHub App); without one, your identity, tagged as human fallback |
| Where it runs | the aayu command, a skill in your agent, an MCP tool (read-only unless [mcp] expose_writes is on) |
| The skill your agent reads | skills/plan/SKILL.md |
When to use it
- A story is sliced and you want its build order, tests, and rollback agreed before
buildstarts. - A story touches stored data, domain policy, or the platform, and a person must review the plan first.
- A data or AI story has a chart note: the plan builds its checkpoints from it.
The story is not written yet? Start with grill or slice. A choice between designs
is decide.
Run it
Ask your agent with the story's number. It reads the story's layers and criteria, drafts the plan, has aayu check
it, and records it once every problem is fixed.
Use the plan skill to plan story 42, and tell me if any of its layers needs a person to review the plan.
aayu plan <story>
| Input | Required | What it does |
|---|---|---|
<story> |
yes | Story or bug to plan, or a Feature to write its technical design for. |
--draft |
no | JSON file with the plan the host's model wrote (evals/schemas/plan.json), or a Feature's technical design (contracts, layers, story order, rollback); without it plan reports what to plan. |
--create |
no | Write the validated plan to the ledger (specs/<story>/plan.json) and the story, or a Feature's design (specs/<feature>/design.json); without it plan only validates. |
--approve |
no | Record the Engineering Manager's plan-time review of a plan that touches an [autonomy] never layer (human identity only). Person only. |
--solo-bypass |
no | Solo mode only (one human, no bot App): record that a never-layer plan proceeds with no plan-time review, after your story comment starting "Solo-mode bypass:"; a bypass, never an approval. Person only. |
The final step is aayu plan 42 --draft plan.json --create.
What you get back
A plan at specs/<story>/plan.json on the ledger, the branch where aayudha keeps its records. It holds one
checkpoint per layer in build order, each with its contracts, tests, instrumentation, the criteria it proves, and
its rollback; a stored-data checkpoint must name its down migration or restore step. When your product defines SLOs,
the plan also says how the change rolls out and what rolls it back.
You should see aayu plan <story> --draft plan.json report no problems, then the plan on the ledger. A risky
layer without a review stops ship later; see ship problems.
Gates
It checks these before it acts, and stops when one fails:
- validator: The work item passes stage validation for its type.
- halt: The repository is not halted (aayu halt).
The story must pass the Ready check before it can be planned: when it does not, plan stops with exit 4 and
names the aayu ready <story> --check command that lists the problems.
What only a person does
--approve: Record the Engineering Manager's plan-time review of a plan that touches an [autonomy] never layer (human identity only).--solo-bypass: Solo mode only (one human, no bot App): record that a never-layer plan proceeds with no plan-time review, after your story comment starting "Solo-mode bypass:"; a bypass, never an approval.
By default the risky layers are domain policy (L04), stored data (L07), and the platform (L09). A person in the
Engineering Manager seat reviews such a plan and runs aayu plan <story> --approve. Working
alone, post a story comment that starts Solo-mode bypass:, then run --solo-bypass; see
the human pass and solo mode.
What's next
- Build the story checkpoint by checkpoint:
build. - See three risky plans recorded honestly in the story: the plan.
- Every skill.