> ## Documentation Index > Fetch the complete documentation index at: https://docs.stackra.figentra.com/llms.txt > Use this file to discover all available pages before exploring further. # Working with agents > How AI agents work in this repository: one .agents/ source, delegation to tiered subagents, and the gates that decide what merges. 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](/constitution/delegation) and [Secrets](/constitution/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](/constitution/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](/adr/0119-merge-policy-and-release-authority)). > [!NOTE] > > 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](/agents/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](/agents/concurrent-sessions). ## Who blocks and who reports Gate order for a non-trivial change, from the plan to the merge: | Gate | Agent | Blocks | | - | - | - | | 1. Placement and decisions | `architecture-guardian` | Yes. A boundary violation, or a change that contradicts an accepted ADR without a superseding one | | 2. Security | `security-tenancy-reviewer` | Yes. Auth, secrets, isolation, webhooks, redaction | | 3. Tests | `test-engineer` | Yes. A red suite, or an untested failure path | | 4. Review | `code-reviewer`, `api-contract-reviewer`, `design-brand-reviewer` | No. They report findings ranked by severity | | 5. Accessibility | `accessibility-reviewer` | Critical and serious findings only | | 6. Release | `release-operations` | Yes. A human approves every release and deploy | The full roster, with tiers and models, is on [Roster](/agents/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 `, 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 AI review passed ([ADR 0230](/adr/0230-reviewer-identity-separate-from-builder)): the `stackra-reviewer` App (checked by its app identity, not a login) posted an unedited `AI-REVIEW: PASS base=` through `pnpm bot:review`, it is not the PR or head-commit author, and no counted `AI-REVIEW: FAIL ` exists; or the owner submitted an APPROVED review on the head SHA ending in `owner-approval`. 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 -- ` runs `gh` as the bot; `pnpm bot:git -- ` 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](/agents/rules-that-dont-rot). ## One source, projected to each tool Every AI artifact is authored once, in `.agents/`: ```text theme={"system"} .agents/ ├── hooks/ guard and reminder scripts ├── rules/ short always-on rules that point at these pages ├── agents/ roster definitions for agents the repository adds ├── skills/ project skills ├── specs/ spec-kit specs: sta--/, keyed by the Linear issue (ADR 0120) ├── plans/ working plans └── models.yaml tier to model mapping ``` 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](/adr/0016-agents-source-of-truth). ### 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. ```yaml theme={"system"} --- title: Short display name description: One line. Used by tools to judge relevance. always: true # load in every session applies_to: ["services/**"] # root-relative globs; relevant when a matching file is touched manual: false # true: never auto-attached, pulled in by name only --- ``` 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](/agents/roster)** > > Every agent, its tier and model, whether it blocks, and what it owns. > **[Hooks](/agents/hooks)** > > What each hook denies or reminds, and how they are wired. > **[Skills](/agents/skills)** > > Plugin and vendored skills, how to install them, and what is deliberately absent. > **[Spec lifecycle](/agents/spec-lifecycle)** > > requirements, design, tasks, and where a finding goes. > **[Concurrent sessions](/agents/concurrent-sessions)** > > Sharing one clone safely, worktrees, and phased work. > **[Rules that don't rot](/agents/rules-that-dont-rot)** > > Every rule names its check. Related: [Workflow](/guides/workflow), [Definition of done](/guides/definition-of-done), [Not built yet](/adr/0011-rejected-and-deferred-technologies). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.