How we build software with Coding agents.

AI-native by default, inside the repository.

The team handbook has a value that says: "Any process an agent can run, an agent runs. Humans stay in the loop only where their judgement is irreplaceable." This page is what that value looks like in the code we ship every day.

The agent is exactly as good as what we wrote down. A rule that lives in someone's head does not exist for the agent. A rule that lives only in prose loses to the code sitting next door.

So the real product of our engineering process is the harness around the model: the context files, the skills, the hooks and the one gate. Code is what falls out of it.

Eight operating rules.

Each one has a consequence you will feel in your first week.

A feature travels one pipeline.

Every hop is a skill you invoke with a slash, and each skill names the next one at the end of its own instructions.

Design work starts as a conversation the agent runs.

/grilling walks a design tree in rounds. It asks the whole open frontier at once, numbered, each question with a recommended answer already attached, and it dispatches a sub-agent to read the code whenever the answer is a fact rather than a preference. /interview is the same tree one question at a time. /grill-mvp adds an anti-over-engineering lens; /grill-with-docs writes the outcome into ADRs and the glossary; /zoom-out maps the modules and callers before you decide anything.

The output is never prose. It is a numbered list of decisions with file and line. The architecture grilling of 2026-07-15 closed with 9 decisions; the Studio Copilot grilling of 2026-08-06 closed with 15 plus an ADR.

How the agent is allowed to ask you

These rules came from corrections, and they hold in every skill.

• Questions go through the AskUserQuestion tool, never as plain text.
• Decision questions carry no code jargon: three to five plain sentences with a domain example first, options described by their observable consequence. Evidence with file:line goes in a findings table before the question, not inside it.
• Never cite a section number or a decision code back at us. "The wrapper doc says X, but the starter doc says Y", never "PRD_1 §3.7 contradicts PRD_2 §2.1".
• An architectural choice arrives as a pros and cons table per option first, then the question.
• The agent gives the design that is best on the merits even when it contradicts our own written rules, says where it diverges, recommends one, and lets us choose.
• If you interrupt with a clarifying question, the agent answers it in prose and ends the turn. Re-asking in the same message reads as being railroaded.
• Explain like an engineer: image versus container, bind mount, HMAC. An analogy is at most one line.

The PRD is a Linear issue. Then it gets grilled against the code.

/to-prd

Synthesises the conversation into one issue on the Platform team with the Feature label; the description is the PRD. It never writes it to disk and it does not interview you (that already happened). Before creating anything it asks for status and priority, and never offers Done or Canceled.

/grill-prd

Extracts every factual premise from the PRD, fans out parallel read-only agents to check each one, and reports premise, verdict, evidence and impact before rewriting the issue. Its own rule: "Never assert code is missing without two independent signals." This step earns its cost. On one PRD, 66 premises were audited: 41 held and 17 changed scope. On the browser-deployment design, six of the ADR's claims fell before a line was written.

/to-issues

Cuts the PRD into tracer-bullet vertical slices: each one a narrow, complete path through schema, service, contract and UI. Wide refactors are the exception and go out as expand and contract batches. It creates the sub-issues in dependency order so blocked-by links use real identifiers, labels each afk (an agent can run it alone) or hitl (a human decides something inside it), and quizzes you on granularity before publishing.

For readers who are not engineers: /to-summary renders a PRD as a self-contained HTML brief and /eval-me scopes a client job into three buckets: already in the platform, to build, third-party to configure.

One worktree per feature. Two workflows that do not improvise.

Never git worktree add by hand. scripts/wt-new.sh <issue-id> branches off a freshly fetched origin/next, prints the absolute toplevel to cd into, clears the sparse-checkout a plugin leaks into every new worktree, copies the git-ignored .env, and reports the port offset. Each worktree gets its own Postgres database, its own Redis logical DB and its own api/web/studio ports on the one shared docker infra, so two features run side by side.

scripts/verify.sh before every commit.

Four things the script does that typing the commands does not: it runs from the toplevel of the checkout it lives in and prints it, so a stray cd cannot verify the wrong checkout; it never mixes Nx targets in one run, because that starves the vitest workers and studio's specs die on timeout; it retries a red test project alone before reporting; and it scans every phase log for a "failed" line, because Nx can print that and still exit 0.

Nothing moves to Done on a feeling.

/close-feature

First it runs the code-simplifier agent over the whole diff, before QA, so what gets tested is what gets merged. Then it brings the local stack up and walks one Playwright acceptance flow per user story in the PRD. A failure is triaged with you as a bug or a gap: a bug enters a fix loop of at most three attempts, and if the same error appears twice in a row the loop exits early instead of spending the third. Gaps accumulate. No bypasses: if a test fails because of a guard, the guard stays. Pre-close checks run test, lint and typecheck plus the web e2e suite. If everything passes, the Feature issue moves to Done, the PR opens ready for review (the push happens only after you confirm) and the archive skill runs. If gaps remain, the Feature stays open and /to-issues creates the gap sub-issues.

/archive-completed-feature

Refuses unless the issue is Done. It writes docs/archive/<slug>.md, a dense historical summary of what shipped and what was decided, and appends one line to docs/HISTORY.md, which is append-only and ascending by close date.

The model changes; the context files stay.

This is where a new rule goes, in escalating order.

Two more pieces of context every session gets. docs/CONTEXT.md is the glossary and product model, and skills speak in its vocabulary. And the assistant runs in the Explanatory output style, so it explains the why of what it does while it works.

Most of what the agent produces in a day is prose.

Wiki pages, PRDs, Linear updates, ADRs, commit messages. The rules:

Each of these is a memory file. The method matters more than the bug.

The short list.

Everything above, compressed.

1. 01 Grill before you build. Decisions come out as a numbered list with evidence.
2. 02 The PRD is a Linear Feature issue on Platform. Sub-issues are tracer-bullet slices in dependency order.
3. 03 Two independent signals before you say something is missing. Otherwise write "unverified".
4. 04 One worktree per feature via scripts/wt-new.sh. Repo-relative paths in every brief.
5. 05 scripts/t.sh while you work; scripts/verify.sh before you commit. Never the four commands by hand.
6. 06 Do not re-run a suite to read its own failure. Grep tmp/t/ and tmp/verify/.
7. 07 A written rule beats the neighbouring files. If the local pattern contradicts the rule, say so.
8. 08 Never push without an explicit yes. Never --no-verify. Never comment out a guard to make a test pass.
9. 09 Never hand-edit libs/contract/** or a committed migration. A hook will stop you; the message tells you the right path.
10. 10 New Angular component: its own folder, .html template, CVA, DaisyUI semantic tokens, a row in libs/ui/components/CLAUDE.md.
11. 11 Verify UI in a real browser (Playwright MCP), logged in as placeholder user in Stackbone Demo.
12. 12 Questions through AskUserQuestion, in plain language, with the trade-off table first and no section IDs.
13. 13 Answer a clarifying question, then stop.
14. 14 Chat in Spanish; code, docs and commits in English; Linear updates in English for a business reader.
15. 15 No slop in anything a human reads. No em dashes.
16. 16 Done means every user story passed in a browser. Then archive it and tell the business.
17. 17 Write the lesson down the same day, with a Why. If it keeps breaking, make it a hook.