astack: how I work with AI coding agents

Over time I wrote down the rules I kept repeating to my AI coding agents: how to plan, how to build, how to check the work and when to stop and ask me. Those rules now live in one public repository, astack, under the MIT licence.

What it is

astack is a single plugin. It holds skills, agents, rules and hooks for planning, coding, review, tickets and documentation. There are 52 skills at the moment, from planning and test driven development to code review, bug diagnosis, ticket writing and docs. There is also a small CLI, written in TypeScript, that runs on Node 22 or Bun. It starts and checkpoints sessions, shows a board, checks the install and checks a plan.

It builds for Claude Code, Codex, Cursor, Grok Bot and other Agent Skills clients. Grok Build uses the Claude Code build. I keep one source, and a capability map decides what each client receives, so I never maintain five copies of the same instruction.

The entry point is /astack:mode. Cursor and other flat builds use /astack-mode. With no argument it reads the plan, the tracker and git, then does the next step. You can also say what you want in plain words, such as "I am building X" or "merge when green", and it picks the route.

The daily loop

Most days follow the same path.

1. Plan. For unclear work I start with a planning session. It asks for the goal and the one decision the work drives. Each question comes with one recommendation.
2. Build. Work happens on a branch or a worktree, never on the default branch. A feature grows one slice at a time, and each slice starts with a test that fails. A bug fix starts with one written line: "Root cause: X because Y". If I cannot write that line, I do not understand the bug yet.
3. Run the gates. Lint, type check, tests and doc checks. They run again after the clean up and after each fix, and the counts go in the pull request.
4. Clean the diff. A pass removes the noise agents tend to leave behind, such as redundant comments and needless code.
5. Review. The review looks at two things: does the code meet the standards, and does it do what the spec asked.
6. Open the PR. The session that owns the ticket opens it.
7. Harden. A hardening pass looks for real problems. Each finding has to be reproduced before it counts.
8. Merge. Only with an explicit grant, either in the profile or from me in that turn.
9. Plan the next session.

One plan session is one pull request. Bigger work is split into steps, workers build them in parallel worktrees, and the main thread lands the commits in plan order. That keeps each pull request small enough for a person to read.

The principles

A short set of rules applies everywhere. Four of them do most of the work.

"Measure a claim before you make it." An agent that says the tests pass should have just run them. An agent that says a page is faster should have a number.

"Walk the journey as a real person." Green tests are not the same as a working feature. Somebody has to click through it the way a user would.

"Ask only for a choice that belongs to you." I do not want to be asked things the agent can find out by itself. I do want to be asked about the decisions that are mine to make.

"Give the result first." The answer comes before the story of how it was reached.

A few design choices

Replies are written in Simplified Technical English, the ASD-STE100 standard, and a hook enforces it. Short sentences and a controlled vocabulary make agent output easier to scan and harder to misread. The README is written the same way. A minimal hook profile turns this check off if you prefer, but the workflow guards stay on.

The agent stops and asks before anything I would not want done without me: a merge with no grant, paid infrastructure, an account, a secret, a production write with no grant, or a destructive reset. Those gates are in the rules, not left to the agent's judgement on the day.

The gates in the hardening profile mirror the blocking CI jobs, and a check keeps the two in step. If the agent's local checks drift from CI, that is caught rather than discovered later in a failed build.

The public repo started from a fresh first commit. Private config stays outside the repo.

Credit

astack did not start from nothing. Some of its text is adapted from Lauren Tan's pstack, Matt Pocock's skills and the Cursor team kit, all under MIT. The NOTICE file credits them.

Trying it

There is no tagged release yet. Releases are coming, and the README describes how to install from a signed release tag once one exists. Until then, the source on GitHub is the best place to read the skills and the workflow, and to take whatever is useful for your own setup.