Skip to main content
AI agents write, review and plan a large share of the work here. This section is the operating manual for that. The laws behind it live in Delegation and Secrets. Nothing here is optional background reading: the hooks and rules described in these pages run in every session.

​
The working model

The main session coordinates. Subagents do the work.
1

Main session decides

The main session reads the request, classifies it, picks the agents and the model tier, and writes a self-contained brief for each. It reviews results and reports. It does not hold large file contents, long diffs or implementation detail.
2

Subagents execute, each with an explicit tier

Every task goes to a subagent, and the delegation names the model tier. An executor gets a brief that carries the goal, the files in scope, what has been ruled out and what done means. It does not get the conversation. The brief template is in Delegation.
3

Gates decide, not the agent that did the work

An agent’s report is evidence, not a verdict. Before acting on a report, check its claims in the code. A blocked task usually means the brief left something out. Fix the brief rather than retrying into the same wall.
4

The lead lands it

Executors never write to git. The lead (Claude) commits, pushes and merges through the merge gate (pnpm pr:merge); the owner merges the release pull request and approves every production promotion and deploy (0119).
This is a standing preference of the maintainer, not a suggestion: all work is delegated to subagents with an explicit model tier, and the main session is kept for coordination. A long single conversation that does the work itself is the failure mode. See Concurrent sessions for how to keep sessions small.

​
Caps and shape of a delegation

  • One task per agent run. A change to a shared interface, or one that touches two packages, is one task. A half that leaves the repository in a broken state is not a valid task.
  • One agent per package at a time. Two parallel agents never edit the same directory.
  • Parallel fan-out is capped at five concurrent executors. The lead enforces this for spec waves (/speckit.implement); no script does yet.
  • Run independent agents in a single message so they start together. Do not delegate a check you can run in one command yourself.
  • Executors do not use git stash, git add -A, force-push or --no-verify. See Concurrent sessions.

​
Who blocks and who reports

Gate order for a non-trivial change, from the plan to the merge: The full roster, with tiers and models, is on Roster. The delivery-orchestrator enforces this order and writes no code.

​
How a change merges

Required approvals are 0 and the Quality Gate is the only required check (owner decision A1, ADR 0119). An agent merges only with pnpm pr:merge <n>, which squash-merges as the stackra-bot GitHub App (--delete-branch, --match-head-commit, never --admin) when all of these hold:
  • the newest Quality Gate run on the head SHA is green, and the PR is open and not a draft;
  • the newest trusted review comment for that SHA is AI-REVIEW: PASS <head sha> on its first line (posted by stackra-bot or the owner; AI-REVIEW: FAIL <sha> blocks). A new push needs a new review;
  • a PR labelled design or risk:R3 also has the owner’s approval on the head SHA, or the owner-approved label.
The bot helpers run under Infisical (/agents, env dev) and never print the token except pnpm bot:token, which writes it alone to stdout for piping. pnpm bot:gh -- <args> runs gh as the bot; pnpm bot:git -- <args> runs git with the bot as author and committer (stackra-bot[bot], 344982495+stackra-bot[bot]@users.noreply.github.com) and pushes over https through gh auth git-credential, with nothing written to .git/config. A rule with no failing check is a comment. Where an agent’s charter and the actual check disagree, the charter is the bug. See Rules that don’t rot.

​
One source, projected to each tool

Every AI artifact is authored once, in .agents/:
The assistant folders, .claude/ and .opencode/, are projections of this tree. Edit .agents/, never the projection. The mechanism is one canonical .agents/ source projected to tool folders; the adoption plan describes how it is wired and checked. The decision is recorded in ADR 0016.

​
Rule frontmatter

Files in .agents/rules/ carry neutral, tool-agnostic frontmatter. It is deliberately not any one assistant’s vocabulary, so the projection can translate it for each tool.
Precedence when more than one is set: manual beats always beats applies_to. A rule that sets none of the three is treated as always. Choose honestly: a rule that only matters in services/** says so with applies_to rather than loading into every unrelated session. Write applies_to as an array, never a |-joined string; a joined string is one literal pattern and matches nothing.

​
Root files

AGENTS.md at the repository root is the lean, always-loaded summary: the layout table, the rules pnpm validate enforces, and what done means. CLAUDE.md contains one line, @AGENTS.md, and nothing else, so a second copy can never drift. Everything longer belongs on a docs page that a rule links to.

​
What is in this section

Roster

Every agent, its tier and model, whether it blocks, and what it owns.

Hooks

What each hook denies or reminds, and how they are wired.

Skills

Plugin and vendored skills, how to install them, and what is deliberately absent.

Spec lifecycle

requirements, design, tasks, and where a finding goes.

Concurrent sessions

Sharing one clone safely, worktrees, and phased work.

Rules that don't rot

Every rule names its check.
Related: Workflow, Definition of done, Not built yet.