# Stuart Leo — Full Content > Context Leadership: leadership used to be direction; now it's context. Two > methods: Resolute for the company, the C² Method for the codebase. Author of > the Resolute series; builder of Waymaker. This file inlines the complete text of every published article on https://stuartleo.com for AI answer engines. The curated index lives at https://stuartleo.com/llms.txt. Engagement model: embedded operator at a fixed rate (12–36 months), 30-day notice both ways, no title. --- # AGENTS.md vs CLAUDE.md: what Claude Code actually loads (tested) ## Six folders, six marker words, one question to the CLI each. Which file Claude Code reads when you have AGENTS.md, CLAUDE.md, both, an import, a symlink or a local file. - URL: https://stuartleo.com/articles/agents-md-vs-claude-md - Published: 2026-11-20 - Reading time: 7 min read - Method: C² Method AGENTS.md vs CLAUDE.md, tested in Claude Code 2.1.329: which file loads when both exist, how @AGENTS.md imports work, and the CLAUDE.local.md trap. If your repo has both an `AGENTS.md` and a `CLAUDE.md`, Claude Code reads the `CLAUDE.md` and ignores the `AGENTS.md`. If it has only an `AGENTS.md`, Claude Code reads that. If your `CLAUDE.md` contains the line `@AGENTS.md`, it reads both. That is what Anthropic's docs say, and it's what I got when I tested it on 20 November 2026 with Claude Code 2.1.329. The surprise is a fourth case. Add a personal `CLAUDE.local.md` to a repo that relies on `AGENTS.md`, and Claude Code quietly stops reading the `AGENTS.md`. This is the head-to-head and the test. For what to put *in* the file, see [how to write an AGENTS.md that agents actually follow](/articles/how-to-write-agents-md). For why a loaded file still gets ignored, see [why Claude Code ignores your CLAUDE.md](/articles/why-claude-code-ignores-your-claude-md). ## Does Claude Code read AGENTS.md? Yes, since version 2.1.277. The [memory docs](https://code.claude.com/docs/en/memory#agents-md) give the rule. By default Claude reads `AGENTS.md` only when there's no `CLAUDE.md`, `.claude/CLAUDE.md` or `CLAUDE.local.md` in your working directory or any directory above it. Your personal `~/.claude/CLAUDE.md`, an organisation's managed `CLAUDE.md` and `.claude/rules/` files don't count for that check. They load alongside `AGENTS.md`. The default is called `claude-md-or-agents-md`. You can change it with **Project instructions** in `/config`: | Setting | What loads | |---|---| | `claude-md-or-agents-md` (default) | CLAUDE.md files, or AGENTS.md when there's no CLAUDE.md or CLAUDE.local.md | | `claude-md-and-agents-md` | Both, each directory's CLAUDE.md first, then its AGENTS.md | | `claude-md` | CLAUDE.md only | | `managed-only` | Only the organisation's managed CLAUDE.md and auto memory | The docs say this setting is read from your user settings, a `--settings` file or managed settings. A project's `.claude/settings.json` can't set it. So you can't commit "read both" for your team. Each person chooses. ## The test: six folders, six marker words I wanted the behaviour from the CLI, not from a description. Each folder got a fresh `git init` and instruction files containing a single unique marker word. Then one non-interactive call per folder: ```bash claude -p "Reply with only the marker words from your project instructions, or NONE" \ --max-turns 1 --tools "" --no-session-persistence --strict-mcp-config ``` `--tools ""` turns off every built-in tool, so Claude can't go and open a file. Whatever it reports had to be in its context at startup. One call per folder, six calls in total. | Folder | Files | Reply | |---|---|---| | 1 | `AGENTS.md` (HERON) | **HERON** | | 2 | `CLAUDE.md` (OTTER) | **OTTER** | | 3 | `AGENTS.md` (FALCON) + `CLAUDE.md` (BADGER) | **BADGER** | | 4 | `AGENTS.md` (WALRUS) + `CLAUDE.md` containing `@AGENTS.md` then LYNX | **WALRUS, LYNX** | | 5 | `AGENTS.md` (MARMOT) + `CLAUDE.local.md` (QUOKKA) | **QUOKKA** | | 6 | `AGENTS.md` (PELICAN) + `CLAUDE.md` as a symlink to it | **PELICAN** | Claude Code 2.1.329, macOS, 20 November 2026. Every result matches the docs. - **Folder 3** is the one that catches people. Both files present, and FALCON never arrives. If you added a `CLAUDE.md` to a repo that already had an `AGENTS.md`, Claude Code has been reading only one of them. - **Folder 4** shows the import order. The imported file comes first, then the rest of the `CLAUDE.md`. That's the documented behaviour and it's what came back. - **Folder 5** is the trap. `CLAUDE.local.md` is meant for your private, uncommitted notes. But it counts as a CLAUDE file, so its presence switches the `AGENTS.md` off for you. Your teammates still get it. You don't. The docs flag this and suggest `claude-md-and-agents-md` if you want both. - **Folder 6** loaded the content once, not twice. **One thing went wrong first, and it's worth knowing.** My first run used folders under Claude Code's own per-session scratchpad, in its temp directory. Every folder answered NONE, including the one with only a `CLAUDE.md`. Same files copied to an ordinary folder under `/tmp`, and they loaded. The docs don't explain it and I haven't dug further. If you repeat this test, run it in a normal directory, and check that no parent directory holds a `CLAUDE.md` or `AGENTS.md` of its own. ## AGENTS.md vs CLAUDE.md: the differences that matter | | `AGENTS.md` | `CLAUDE.md` | |---|---|---| | Who reads it | 20+ coding agents, plus Claude Code since 2.1.277 | Claude Code | | Loaded when the other is present | Not by default in Claude Code | Always | | `@path` imports | Expanded by Claude Code | Expanded | | Personal variant | `AGENTS.local.md` is not read by Claude Code | `CLAUDE.local.md` | | `InstructionsLoaded` hooks | Don't fire when read directly | Fire | | Subdirectory files | Loaded when Claude reads a file there, if that folder has no CLAUDE file | Loaded when Claude touches that folder | The docs also say Claude Code doesn't read `AGENTS.override.md` or anything under a `.agents/` directory. If another tool in your stack relies on those, Claude won't see them. ## Which other tools read AGENTS.md? The [AGENTS.md site](https://agents.md/) lists Codex, Jules, Factory, Aider, goose, opencode, Zed, Warp, VS Code, Devin, UiPath's coding agents, Junie, Amp, Cursor, RooCode, Gemini CLI, Kilo Code, Phoenix, Semgrep, GitHub Copilot's coding agent, Ona, Windsurf and Augment Code. It says the format is used by over 60,000 open-source projects, and that it's now stewarded by the Agentic AI Foundation under the Linux Foundation. For monorepos, its guidance is that the nearest `AGENTS.md` in the directory tree wins, and an explicit instruction in chat overrides everything. Two details from the site. It shows Gemini CLI being pointed at `AGENTS.md` through `.gemini/settings.json`, so that one needs configuring. And Claude Code isn't on the site's list at the time of writing, even though Anthropic's own docs say it reads the file. Trust each tool's own docs over a list. Last checked: 20 November 2026. ## Should I use AGENTS.md or CLAUDE.md? My rule: - **Only Claude Code touches the repo:** a `CLAUDE.md` is enough. - **More than one agent touches it, or might:** put the shared instructions in `AGENTS.md`. If Claude needs anything extra, add a `CLAUDE.md` whose first line is `@AGENTS.md`, with the Claude-only lines below. - **You keep a `CLAUDE.local.md`:** know that it switches off direct `AGENTS.md` loading for you. The `@AGENTS.md` import in a committed `CLAUDE.md` sidesteps that: per the docs, an import is part of the `CLAUDE.md`, so it loads whenever the `CLAUDE.md` does. I prefer the import to the symlink. The docs list two catches with symlinks: Claude's Edit and Write tools refuse to write through one, and a committed symlink can check out on Windows as a one-line text file. The import has neither problem and leaves room for Claude-specific lines. ## What C² does by default The [C² starter kit](https://github.com/waymakerone/c2method), which I built, ships its router as `AGENTS.md` by default, the cross-agent name. Its README says to use `CLAUDE.md` for Claude Code or `GEMINI.md` for Gemini, and to name the file for your agent so it's read automatically rather than relying on a rename. My own monorepo predates all of this and uses a `CLAUDE.md`: a 404-line router with no `AGENTS.md` beside it. That's fine for a repo where Claude Code is the agent. For a new repo I'd now start with `AGENTS.md` plus a two-line `CLAUDE.md` that imports it. Claude Code can read `AGENTS.md` directly, so the C² default works with it out of the box, as long as nothing else on the path is called CLAUDE. The filename is the least important decision here. A router is a router: invariants first, pointers instead of paragraphs, everything else in the contextbase. More on that in [C² vs native rule files](/articles/c2-vs-native-rule-files). ## How do I check which file Claude Code loaded? - Run `/memory`. The docs say it lists the instruction files loaded, including an `AGENTS.md` read directly, from version 2.1.280. - Run `/context all` and look under **Memory files**. - In an interactive session with only an `AGENTS.md`, the docs say you'll see a line such as `no CLAUDE.md found; AGENTS.md loaded`. - Or do what I did: put a marker word in each file and ask. Start here: [how to write an AGENTS.md that agents actually follow](/articles/how-to-write-agents-md), [why Claude Code ignores your CLAUDE.md](/articles/why-claude-code-ignores-your-claude-md), or [run your first C² session](/c2/start). --- # Claude Code compaction ate my work: recovery and prevention ## Auto-compact just fired mid-task and the agent has forgotten what it was doing. What is actually lost, how to get it back from disk, and how to set up so the next one doesn't hurt. - URL: https://stuartleo.com/articles/claude-code-compaction-lost-context - Published: 2026-11-20 - Reading time: 9 min read - Method: C² Method Claude Code compaction lost context mid-task? Nothing on disk is gone. How to recover from git, your briefs and the session transcript, and how to prevent it. You are an hour into a task. Claude Code prints *Conversation compacted*, and the next answer is subtly wrong. It has forgotten the constraint you set at the start, or the file it was halfway through, or the reason you rejected the obvious fix. It carries on, confidently, from a summary that dropped the part that mattered. Here's the short answer. Compaction didn't delete anything on disk. Your files, your git history and the full pre-compaction conversation are all still there. What went is the agent's working memory. Recovery means rebuilding that memory from disk, in a fixed order, before the agent writes another line. Prevention means making sure the important state never lived only in the chat. This article is the recovery half. For why sessions lose context at all, and the routine that carries work between sessions, see [how to stop Claude Code losing context between sessions](/articles/how-to-stop-claude-code-losing-context-between-sessions). For context rot and why you'd compact on purpose, see [context rot: how compaction keeps your agent sharp](/articles/compaction-keep-the-context-window-lean). ## What does Claude Code compaction actually lose? Per the [context window docs](https://code.claude.com/docs/en/context-window), compaction replaces the conversation with a structured summary. Some things are rebuilt from disk afterwards: the project-root CLAUDE.md, auto memory, the plan from plan mode, and up to five of the files Claude most recently read or edited. Others are only as good as the summary: anything you said in chat, context hooks added earlier, and nested CLAUDE.md files and path-scoped rules until Claude touches a matching file again. So the losses fall into three kinds: - **Instructions you gave in conversation.** "Don't touch the migration", "use the old endpoint". If the summary didn't keep it, the agent no longer knows it. - **Why, not what.** The summary usually keeps what was done. It is weaker on why an alternative was rejected, which is exactly what stops the agent re-trying it. - **Where it was.** Which step of a multi-step task, which files are half-edited, what was verified and what wasn't. It happens more than you'd think. I checked my own transcripts for my main monorepo. Between 24 October and 20 November 2026 there were 29 session transcripts, and 21 of them compacted at least once. In total they recorded 241 compactions. Every one was automatic. I never ran `/compact` by hand in that window. The biggest conversation compacted at 971,495 tokens. A typical one shrank from 262,756 tokens to 23,077 in 56 seconds. That is a lot of conversation turned into a page of summary. ## What to do right after Claude Code compacts mid-task Work through this in order. The first step matters most. ### 1. Stop the agent before it builds on the summary If it's mid-run, press Escape. A wrong summary compounds: every step taken from it is another step to unpick. Nothing is lost by pausing. ### 2. Ask it what it thinks the state is Ask one question: *how's your context?* Or more pointedly: what's the task, what's done, what's left, what constraints apply. You're not asking it to fix anything yet. You're reading the summary through its eyes so you can see what's missing. When the setup is right, the answer is reassuring. In a live session, 22 minutes in and after the harness had already compacted, I asked exactly that. The agent's answer, verbatim: *"everything load-bearing is externalized (PBs, briefs, PR bodies, memory), so even when the harness compacts the conversation, nothing about the program state lives only in my head."* The full story is in [what is context leadership](/articles/what-is-context-leadership). When the setup isn't right, the answer is vague, and that vagueness tells you where to dig. ### 3. Check git: the ground truth for code Compaction never touches the working tree. So the state of the code is exactly what git says: ```bash git status # which files are modified or new git diff # what the edits actually are git log --oneline -10 # what was committed, and in what order git stash list # anything set aside ``` Show the agent the output, or have it run these itself. Half-finished edits are the most dangerous thing a compacted agent can forget, because it may start the same change again on top of the first attempt. ### 4. Re-read the brief or plan the task started from If the task began from a written brief, a prompt brief, an issue, or a plan, have the agent read it again now. That file holds the intent and the acceptance criteria, and neither was written by the summariser. In my repos that means the prompt brief in `docs/02-working/prompts/` and the latest session brief. A SessionStart hook can put the list in front of the agent automatically (more on that below). ### 5. Dig the lost detail out of the transcript This is the step most people don't know about. Claude Code keeps a transcript of every session on disk. The [.claude directory docs](https://code.claude.com/docs/en/claude-directory) list it as `~/.claude/projects//.jsonl`: messages, tool calls and tool results. The `` folder is your project path with the slashes turned into dashes. Transcripts are deleted after `cleanupPeriodDays`, which defaults to 30 days. Compaction doesn't rewrite that file. In one of mine the compaction marker sits at line 1,084 of 2,521, and every message before it is still there. So the instruction the summary dropped is recoverable: ```bash cd ~/.claude/projects/-Users-you-Projects-your-repo ls -t *.jsonl | head -1 # newest session grep -n '"compact_boundary"' .jsonl # where each compaction happened grep -n -i 'migration' .jsonl | head # find the thing it forgot ``` What I saw on version 2.1.329: each compaction is a `system` record with subtype `compact_boundary` and a `compactMetadata` object holding the trigger (`auto` or `manual`) and the token counts before and after. The record after it is the summary, starting *This session is being continued from a previous conversation that ran out of context.* The docs document the file, not its fields, so treat those field names as what I observed, not a contract. Two cautions. The transcript is plaintext and holds everything that passed through a tool, so don't paste it anywhere public. And it can be large. Search it. Don't ask the agent to read the whole thing back into the window you just freed. ### 6. Write the recovered state to a file, now Once you've rebuilt the picture, put it on disk: a short session brief with what's done, what's half-done, what isn't verified, and the constraints that must hold. The next compaction then costs nothing, because the agent re-reads a file instead of trusting a summary. ## How do I stop compaction losing context next time? The real fix is upstream: don't let load-bearing state live only in the conversation. One of my session briefs from April 2026 has a section headed *Why this brief deserves to exist*. Its first reason is recovery. The session had produced durable files, but in the brief's words, *"the narrative of why those exist is in the live conversation. If the conversation is compacted or lost, a fresh session reading just the artefacts wouldn't know"* why they were made. So the brief wrote the why down. That is the whole prevention strategy in two sentences. In practice it is four habits: | Habit | What it protects | Where it lives (C² layout) | |---|---|---| | Write the task as a brief before starting | Intent and acceptance criteria | `docs/02-working/prompts/` | | Commit small and often | The state of the code | git | | Write a session brief before a long session gets longer | What's done, half-done, unverified | `docs/02-working/session-briefs/` | | Promote standing rules to the root CLAUDE.md | Constraints that must survive | re-read from disk after compaction | My own monorepo, which predates that layout, has more than 1,100 files in its 2026 session-brief folder and more than 210 gotcha files. They exist so that no single conversation has to hold the project. ## Can a hook protect context during compaction? Yes, and there are three hook points worth knowing. All three are documented in the [hooks reference](https://code.claude.com/docs/en/hooks). **SessionStart with the `compact` source.** SessionStart hooks fire with a source of `startup`, `resume`, `clear`, `compact` or `fork`, and their plain-text stdout is added to Claude's context. The context window docs confirm that hooks matching `compact` run again after compaction and their output goes into the compacted context. My `session-context.sh` has no matcher, so it runs on every source, including after compaction. The list of recent briefs comes back automatically. **PreCompact.** Runs before compaction, with a matcher of `manual` or `auto`. When it exits 0, its stdout becomes instructions for the compaction summary, capped at 10,000 characters per hook. A sketch, which I don't run myself: ```bash #!/bin/bash # .claude/hooks/pre-compact.sh: tell the summariser what to keep echo "Preserve: the active task and its brief path, every file modified but not committed," echo "anything marked NOT verified, and every constraint the user stated in conversation." git status --short | head -20 ``` A PreCompact hook can also block compaction by exiting 2. Be careful. If the compaction was recovering from a context-limit error, blocking it makes the request fail. Steering the summary is safer than refusing it. **PostCompact.** Runs after compaction and receives the generated summary as `compact_summary`. It can't change the result, but it can log the summary somewhere you'll see it, which is a cheap way to audit what your compactions keep. Finally, when you do compact by hand, give it a focus: `/compact focus on the refund flow, keep the rejected approaches`. The docs also describe `/rewind` with **Summarize from here**, which compacts only part of the conversation. ## The rule underneath Compaction is not the failure. Treating the chat as the place where the project lives is the failure. The summary is a guess about what mattered. The brief, the diff and the transcript are records. When it bites, stop, ask, check git, re-read the brief, search the transcript, write it down. When it doesn't bite, it's because you already wrote it down. Start here: [how to stop Claude Code losing context between sessions](/articles/how-to-stop-claude-code-losing-context-between-sessions), [write your first session brief](/articles/write-your-first-session-brief), or [run your first C² session](/c2/start). --- # Claude Code hooks I actually run, and the one I turned off ## Three hooks from a real monorepo's .claude/settings.json, what each one is for, how one went blind and one talked to nobody, and why the blocking hook got switched off. - URL: https://stuartleo.com/articles/claude-code-hooks-i-actually-run - Published: 2026-11-20 - Reading time: 10 min read - Method: C² Method Claude Code hooks examples from a real repo: a SessionStart brief list, a SessionEnd worktree prune, a PostToolUse reminder, and the block I turned off. Most lists of Claude Code hooks examples are ideas. This is the opposite: the hooks registered in my main monorepo's `.claude/settings.json` today, the script behind each one, and what each has cost or saved me. Three are running. One sits in `.claude/hooks/` switched off, and I'll show why, because the reason is the most useful lesson here. The short version. A **SessionStart** hook lists recent session briefs so every session starts knowing where the last one stopped. A **SessionEnd** hook prunes git worktrees whose pull request has merged. A **PostToolUse** hook prints a checklist reminder when a prompt brief is edited, and while writing this article I found Claude never sees it. The **PreToolUse** hook that blocked edits to config files was turned off on 12 April 2026, and the session brief from that day says exactly why. ## How are Claude Code hooks configured? Hooks live under the `hooks` key of a settings file. Per the [hooks reference](https://code.claude.com/docs/en/hooks), there are three levels: the event, then matcher groups, then handlers. This is my `hooks` block, unedited (the file's `permissions` block is left out): ```json { "hooks": { "SessionStart": [ { "hooks": [ { "type": "command", "command": ".claude/hooks/session-context.sh", "timeout": 10 } ] } ], "SessionEnd": [ { "hooks": [ { "type": "command", "command": ".claude/hooks/session-end-prune.sh", "timeout": 10 } ] } ], "PostToolUse": [ { "matcher": "Write|Edit", "hooks": [ { "type": "command", "command": ".claude/hooks/pb-gate.sh", "timeout": 5 } ] } ] } } ``` Each script receives a JSON payload on stdin, including `session_id`, `transcript_path` and `cwd`, and reads what it needs with `jq`. A group with no `matcher` runs for every source of that event. The docs list over thirty events now. I use three. | Hook | Event | Job | Talks to | |---|---|---|---| | `session-context.sh` | SessionStart | List recent session briefs | Claude, via stdout | | `session-end-prune.sh` | SessionEnd | Remove worktrees whose PR merged | A log file | | `pb-gate.sh` | PostToolUse, `Write\|Edit` | Checklist reminder on prompt briefs | Nobody, it turns out | | `protect-config.sh` | PreToolUse, `Edit\|Write` | Block edits to config files | Off since 12 April 2026 | ## The SessionStart hook: a menu of briefs, not the latest brief Every session in my repo opens with a list like this in Claude's context. These are the first lines it printed today: ```text === Recent Session Briefs (last 30 days) === 26/11/15 shared inbox followups shipped and reboot handoff 26/11/15 one prd brand standard 26/11/15 one pb reconciliation escaping and brand logo ... Briefs get parked — ask Stuart which to pick up, don't assume the latest. === ``` SessionStart is one of the few events where plain stdout is added to Claude's context, so the script just echoes. The core of it: ```bash # trimmed from .claude/hooks/session-context.sh PROJECT_DIR=$(echo "$(cat)" | jq -r '.cwd // empty') for dir in "$BRIEFS_2025" "$BRIEFS_2026"; do [ -d "$dir" ] && find "$dir" -maxdepth 1 -type f -name "*.md" -mtime -30 -exec basename {} \; done | grep -v -i -E '^(readme|index|_)' | while read -r brief; do brief_line "$brief" done | sort -r | head -15 | cut -f2- ``` Two choices are deliberate. It lists names and never dumps whole briefs, so the hook costs almost nothing in context. And its last line tells the agent not to assume the newest brief is the priority, because work gets parked. This hook also failed silently for six weeks. It used to match only files ending `-session-brief.md`. From 19 August 2026 brief names dropped that suffix. The fix commit on 2 October (#1086) records the damage: 33 briefs had been written since, and *"every session booted showing an 18 Aug brief as the newest and never saw the last session's brief."* Nothing errored. Now the script parses four date formats and the header comment explains why. A SessionStart hook that reads files by name breaks the day the names change. When you change a naming convention, re-run the hook. The comment at the top of the script is my favourite part of it, because it's a gotcha written where the next reader will trip on it. ## The SessionEnd hook: cleaning up after agents This one exists because of a disk. My gotcha file on it opens: *"By 2026-10-05, `waymaker/.claude/worktrees/` held 123 leftover agent worktrees using about 216 GB, and Stuart's Mac ran out of disk."* Each worktree had run its own `npm install`, about 2.4 GB, and nothing removed a worktree when its agent finished. The fix on 19 October (#1603) was two-part: a daily scheduled prune, and this hook at the end of every session. It removes a worktree only when its pull request is merged, the tree is clean, it isn't locked, and no process is working inside it. The interesting part is how it stays out of the way: ```bash # trimmed from .claude/hooks/session-end-prune.sh cd "${CLAUDE_PROJECT_DIR:-$PWD}" 2>/dev/null || exit 0 ( take_lock "$me" || exit 0 # two sessions ending together don't both prune git fetch -q origin 2>/dev/null || true git show origin/main:scripts/prune-worktrees.sh > "$T" 2>/dev/null || exit 0 grep -q -- '--merged-only' "$T" || exit 0 # never run an older, broader script /bin/bash "$T" --yes --merged-only --quiet ) >>"$LOG" 2>&1 /dev/null || true exit 0 ``` SessionEnd hooks can't block the session ending, and the docs give them a default budget of 1.5 seconds when you exit, `/clear` or switch sessions. A fetch and a prune don't fit in that. So the hook does the work in a detached background process and returns at once, and it always exits 0, so a failure never delays your exit. It also runs the prune script from `origin/main`, not from whatever branch the session left checked out, and refuses to run a version that doesn't know `--merged-only`. Its output goes to a log file, not to Claude. Nobody needs to read it unless something looks wrong. ## The PostToolUse hook that was talking to nobody `pb-gate.sh` fires after every Write or Edit. If the file is a markdown prompt brief under `docs/02-working/prompts/active/`, it prints a box: ```bash # trimmed from .claude/hooks/pb-gate.sh INPUT=$(cat) FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty') if [[ "$FILE" != *"/prompts/active/"* ]]; then exit 0; fi echo " PB GATE — checklist required before autonomous hand-off" echo " Run /pb-check $(basename "$FILE") before handing this PB to an agent." echo " One NO = not ready. Fix first." ``` A prompt brief is a task written for an agent to run without me, and the checklist catches the gaps that would strand it. The reminder is aimed at the agent writing the brief. While checking hook behaviour against the docs for this article, I noticed the reference lists only four events whose plain stdout reaches Claude: UserPromptSubmit, UserPromptExpansion, SessionStart and PostModelSwitch. PostToolUse isn't one. So I tested it on 20 November 2026 with Claude Code 2.1.329, in a scratch repo with a PostToolUse hook on `Write|Edit` shaped exactly like `pb-gate.sh`: | Hook output | Did the hook run? | What Claude reported | |---|---|---| | `echo "...the secret word is ZEBRA"`, exit 0 | Yes, it wrote a marker file | "NO HOOK OUTPUT" | | JSON with `hookSpecificOutput.additionalContext`, exit 0 | Yes | "a PostToolUse hook for Write said the secret word is ZEBRA" | So my reminder has been printing into a void, at least as far as the agent is concerned. The docs don't say where that stdout goes. I haven't checked whether it shows anywhere in the interactive view, so I won't claim it does. The fix is small. Print JSON instead: ```bash jq -n --arg f "$(basename "$FILE")" '{hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: ("PB GATE: run /pb-check " + $f + " before handing this PB to an agent.") }}' ``` Or exit 2 with the message on stderr. The docs say that shows the stderr to Claude after the tool has already run. That's a heavier signal, which suits a warning more than a reminder. **A hook that prints is not a hook that's heard. Test that its output reaches whoever it's for.** ## The one I turned off: protect-config.sh This hook arrived on 3 April 2026, in the same commit as the SessionStart hook. It was a PreToolUse hook on `Edit|Write` with a simple purpose: stop an agent "fixing" a type error by loosening `tsconfig.json` or switching off a lint rule. It checked the file name against a list and exited 2 to block: ```bash # trimmed: the real list has 19 names, including the eslint, prettier, postcss and tailwind configs PROTECTED_EXACT=( "tsconfig.json" "biome.json" "vercel.json" "vite.config.ts" "package-lock.json" ".mcp.json" ) for pattern in "${PROTECTED_EXACT[@]}"; do if [[ "$FILENAME" == "$pattern" ]]; then echo "BLOCKED: Cannot edit '$FILENAME'. Fix the code instead of changing config." >&2 echo "If Stuart explicitly asked you to edit this file, ask him to approve the edit manually." >&2 exit 2 fi done ``` It also blocked any `.env*` file and Claude's own `.claude/settings*`. Nine days later I turned it off. The session brief for 12 April 2026 records why. It was my first session on a new laptop, and the migration had lost the Supabase MCP server config, so the session needed to add it back to `.mcp.json`. The brief: *"The `PreToolUse` hook in `.claude/settings.json` was blocking edits to `.mcp.json` (and other config files). Stuart approved removing it."* The same commit removed the hook and fixed the MCP config. Look at the second line of that error message. It tells the agent to ask me to approve the edit. But exit 2 doesn't ask anyone. Per the docs, it blocks the tool call. There was no approval path in the design, so when a legitimate edit came along, the only way through was to delete the hook. If I rebuilt it, I'd use the JSON form instead. A PreToolUse hook can return a `permissionDecision` of `allow`, `deny`, `ask` or `defer`. `deny` for `.env` files. `ask` for `tsconfig.json` and `.mcp.json`, which hands the edit to the permission prompt so I can say yes when I mean it. That keeps the teeth and adds the door. What replaced it, for now, is honesty. My root CLAUDE.md says: *"`protect-config.sh` is **not enabled**: config edits are NOT blocked mechanically. The rule still stands: fix the code, don't weaken tsconfig/biome/vite/.env."* I wrote about why that sentence matters in [why Claude Code ignores your CLAUDE.md](/articles/why-claude-code-ignores-your-claude-md). A rule file that implies enforcement it doesn't have is worse than one that admits the rule is guidance. One more confession. My repo's own hooks doc, `docs/03-knowledge/patterns/claude-code/hooks.md`, still lists `protect-config.sh` as an active hook. The settings file is the truth. The doc drifted. Check your hooks against `.claude/settings.json`, not against what you wrote about them. ## What four hooks taught me - **Tell, do, or block.** SessionStart *tells* Claude something. SessionEnd *does* something and tells nobody. PreToolUse *blocks*. Know which one you're writing, because each needs a different output channel. - **Plain stdout only reaches Claude on a few events.** For the rest, use `additionalContext` or exit 2. - **A block needs a door.** Exit 2 with no approval path will eventually block the owner, and then the whole hook goes. Use `ask` where a human might legitimately say yes. - **Hooks fail silently.** Two of my four have been wrong without an error: one blind for six weeks, one unheard. Re-test after any change to names, paths or the hook itself. - **Keep SessionEnd fast.** Background the work, exit 0. Start here: [why Claude Code ignores your CLAUDE.md](/articles/why-claude-code-ignores-your-claude-md), [how to stop Claude Code losing context between sessions](/articles/how-to-stop-claude-code-losing-context-between-sessions), or [the C² method](/c2). --- # How to rescue a vibe-coded app without rewriting it ## Stop adding features, map what's there, give the agent a router and a contextbase, pin the behaviour with tests, then fix it one small brief at a time. - URL: https://stuartleo.com/articles/how-to-fix-a-vibe-coded-app - Published: 2026-11-20 - Reading time: 10 min read - Method: C² Method How to fix a vibe coded app without a rewrite: freeze features, map it, add a router and contextbase, pin behaviour with tests, fix in small briefs. To fix a vibe-coded app without rewriting it, stop adding features, have an agent map what is actually there, and give it a router file and a `docs/` contextbase to read before it works. Then pin the behaviour you want to keep with tests, fix one problem at a time from a short written brief, and write down every trap you find. That's the whole playbook. The rest of this article is how to do each step. I've written separately about [the time I vibe-coded a feature into a corner](/articles/vibe-coding-into-a-corner). That piece is the story of getting stuck. This one is the rescue procedure, built from the habits I run every day on my own repos. ## Why vibe-coded apps go wrong Vibe coding is building from a feeling rather than a specification. You talk, the agent builds, you steer by what looks right. For a throwaway prototype that's fine. It fails quietly when you keep the result. In my referral-feature corner, every change looked reasonable on its own. Six changes in, discount stacking conflicted with an older refund rule and referral credit could exceed the order total. Nothing was obviously broken. That's the pattern: the drift is invisible step to step, and you only see it once you're deep in it. So a vibe-coded app is really a brownfield codebase that happens to be young. The [greenfield vs brownfield](/articles/greenfield-vs-brownfield-with-agents) problem applies in full. The reasons behind the code were never written down, because there were no reasons, only prompts. The agent can read every line and still not know what the app is supposed to do. ## Should you rewrite a vibe-coded app? Not the whole thing, as a default. A rewrite throws out the behaviour that works along with the mess. And if the rewrite is driven the same way, by an agent steered by feel, you get a cleaner-looking version of the same drift. There is one case where I do rebuild. When a single feature is small and incoherent, deleting it and rebuilding it from a brief is cheaper than untangling it. That's what climbed me out of the referral corner. I deleted the feature, wrote four acceptance criteria, and the agent built it once, cleanly. The rebuild took less time than the vibe-coded version had taken to debug. **Rebuild a feature from a brief when it's small and incoherent. Rescue the app around it.** ## Step 1: Stop adding features The first move is the one nobody wants to make. Freeze new work. Every feature you add on top of an unmapped app adds to what you'll need to understand later. Then list what's broken before you fix any of it. I run a standing rule in my main repo for exactly this, under the heading "Don't walk past broken things". A small fix, an hour or two, gets proposed and done now. Anything larger gets written down as a brief or a line in a maintenance backlog, so it's captured before it slips out of the conversation. Triage first, then fix. One more habit from my maintenance runs: before fixing an item, check it is still an issue against the current code. On a codebase that's been changing fast, a good share of the list fixed itself or moved. ## Step 2: Map the app before you touch it Don't ask the agent to fix anything yet. Ask it for a map. The main parts, how they connect, the entry points, where the data goes, which flows touch money or email or sign-in. Mapping first does two jobs. It gives you a frame for everything that follows. And it shows you the agent's understanding *before* that understanding gets baked into fifty changes, so you can correct a wrong mental model early. I covered this in more depth in [documenting an inherited codebase with an agent](/articles/document-a-codebase-with-an-agent): map first, go deep only where you're working, and verify what the agent claims against the code and the running app. If you use Claude Code, `/init` gets you a first draft. Per the [Claude Code memory docs](https://code.claude.com/docs/en/memory), it analyses the codebase and writes a starting CLAUDE.md with build commands, test instructions and the conventions it discovers. Treat that as a draft to correct, not a finished map. ## Step 3: Write a router and a contextbase The map is only useful if the agent reads it next session. That's what a router file and a contextbase are for. The router is one short file at the root, `CLAUDE.md` for Claude Code or `AGENTS.md` for most other agents. It holds the overview, the handful of rules that apply every time, and pointers to where detail lives. It routes. It doesn't hold everything. Keep it short. The Claude Code docs say to target under 200 lines per CLAUDE.md, because longer files consume more context and reduce adherence. I learned that the hard way when [my own CLAUDE.md hit 600 lines](/articles/the-claude-md-that-got-too-big) and the agent started missing rules that were in plain text. My main monorepo's router has since grown back to about 400 lines, and it now says near the top that it is a router, and ends with a "Moved sections" table pointing at five reference files. Nothing was deleted when detail moved out. It just went somewhere the agent reads on demand. The contextbase is a `docs/` folder of plain markdown in git, next to the code. For a rescue, three parts matter most: | Folder | What goes in it during a rescue | |---|---| | `docs/01-planning/` | What the app is supposed to do, written down for the first time | | `docs/02-working/` | The briefs for each fix, and a session brief at the end of every session | | `docs/03-knowledge/gotchas/` | Every trap you find, one short file each | You don't fill this in one go. You create the folders, write the map into the planning folder, and let it grow around the work. The [contextbase explainer](/articles/what-is-a-contextbase) covers the full shape. ## Step 4: Pin the behaviour with tests This is the step that makes every later fix safe. Before the agent changes anything that matters, write tests that pin what the app does today in the flows you can't afford to break. The point is behaviour, not structure. When I handed an agent a refactor that pulled booking logic out of a route handler, I first spent about twenty minutes writing tests for what had to survive: bookings refused at capacity, the refund window enforced, the confirmation email sent once. Partway through, the agent moved the capacity check to the wrong side of a conditional and that test went red. It diagnosed and fixed it inside its own loop. The regression lived for about ninety seconds and never left the branch. That's [the test that saved the refactor](/articles/the-test-that-saved-the-refactor). Two practical notes for a vibe-coded app: - **If there's no test runner, setting one up is the first fix.** Without a way to run tests, the agent has nothing to check itself against, and you're back to hoping. I go into why in [test-driven development with AI agents](/articles/test-driven-development-with-ai-agents). - **Pin what it does, then decide what it should do.** If a test reveals a behaviour that's wrong, that's a finding. Write it down as an issue and fix it in its own brief. Don't quietly change behaviour while you're adding the safety net. ## Step 5: Fix one thing per brief Now you fix. One problem per brief, small enough to finish and verify in a session. A brief here is short: what this change does, what it explicitly does not do, and acceptance criteria you can run. These are the four from the referral rebuild, unchanged: ``` - A referral gives the referrer a fixed credit, once, on the referee's first paid order. - Credit never exceeds the order total. - Referral credit does NOT stack with promotional discounts. - Test suite covers all three rules and passes. ``` Each line is checkable. The agent builds against them, runs the tests, and reports the green run. If you want the longer version, see [acceptance criteria your agent can check](/articles/acceptance-criteria-for-agents). Two rules keep this from sliding back into vibe coding. First, if the agent has been stuck on one bug for 30 minutes, the answer is not another attempt. My main repo states it as "Maximum debug time: 30 minutes per issue". Stop, start a fresh session, restate the problem, or escalate. More on that in [the 30-minute debug limit](/articles/the-30-minute-debug-limit). Second, end every session with a [session brief](/articles/write-your-first-session-brief): what changed, why, what's verified, what's next. My main repo's 2026 folder holds more than 1,100 of them, and a SessionStart hook lists the recent ones at the top of every new session. The [hooks docs](https://code.claude.com/docs/en/hooks) confirm that plain-text output from a SessionStart hook is added as context Claude can see. ## Step 6: Write down every trap you find A rescue turns up traps: the odd-looking line that turns out to be load-bearing, the setting that only works one way, the bug that took an hour to understand. Each one gets a gotcha file in `docs/03-knowledge/gotchas/`. What it looked like, why it happened, what to do instead. My main repo has 217 of them now. The best gotchas become checks. My clearest example: a database constraint added for one feature silently broke the writes of an older feature. Nobody could start a Leadership Assessment in my own product for 100 days. The page loaded, reads worked, and the table simply stopped growing. It was the third incident of that kind. So the gotcha became a pattern doc with a one-line diagnostic, "a near-empty table plus a recent constraint migration means the writer is failing, not idle", and then a script, `npm run check:write-paths`, that cross-checks every insert against the columns the database requires. A trap I'd paid for three times now costs a command. This is also how you handle the legacy-code problem inside a young app. In an older codebase I worked in, the agent kept "fixing" a timezone workaround and a redundant-looking input check, and each fix was a regression. Once those were written down as notes next to the code, the same agent left them alone. That story is in [the legacy codebase the agent couldn't read](/articles/the-legacy-codebase-the-agent-couldnt-read). ## The rescue at a glance | Step | What you write | Done when | |---|---|---| | 1. Freeze | A list of what's broken, triaged | No new features until the list is captured | | 2. Map | The agent's map, corrected by you | You agree with how it says the app works | | 3. Router + contextbase | A short CLAUDE.md or AGENTS.md, and `docs/` | A fresh session can find the map without you | | 4. Pin behaviour | Tests for the flows you can't break | They pass on the app as it is today | | 5. Small briefs | One brief per fix, with runnable criteria | Tests green, session brief written | | 6. Gotchas | One file per trap, and checks where you can | The next session doesn't hit it cold | ## What changes once it's rescued You can go back to building features, but the loop is different. Each feature starts from a brief, runs against the tests, ends with a session brief, and leaves its gotchas behind. You'll still vibe-code spikes and throwaways. I do. The line is that the moment something is meant to be kept, it gets a brief with criteria I can run. A vibe-coded app isn't beyond saving. It's a codebase whose reasons were never written down. Write them down, pin the behaviour, and fix it a brief at a time. Start here: read [the story of vibe-coding into a corner](/articles/vibe-coding-into-a-corner), [document a codebase with an agent](/articles/document-a-codebase-with-an-agent), or [set up C² in your repo](/c2/start). --- # How to write a prompt brief an agent can run without you ## Instructions for an unattended AI coding agent need more than a goal. The execution contract I use, with excerpts from a real brief and the checklist that gates it. - URL: https://stuartleo.com/articles/how-to-write-a-prompt-brief-an-agent-can-run-without-you - Published: 2026-11-20 - Reading time: 11 min read - Method: C² Method How to write instructions for an AI coding agent that runs unattended: standing approval, pre-flight reads, one item at a time, exact commands, and a real DoD. Instructions for an AI coding agent depend on one thing: will you be there? If you're at the keyboard, a goal, scope and acceptance criteria are enough, because you answer the agent's questions as they come. If you won't be, the instructions have to answer those questions in advance. That means a complete execution contract: what the agent may and may not do, what to read first (by file and line), one item at a time with exact commands, what not to change, what to do when stuck, and a definition of done that needs evidence. In the [C² Method](/c2) that contract is an autonomous **prompt brief**. [The Cascade](/articles/the-cascade-from-prd-to-prompt-brief) explains where a prompt brief sits, and [the prompt brief is a node contract](/articles/the-prompt-brief-is-a-node-contract) explains why its shape matters when many agents run at once. This article is the practical part: how to write one an agent can run without you, using a real brief from my own repo. ## Why the brief changes when you leave the room The rule in my main repo's `CLAUDE.md` is one line long: **Autonomous PBs require a complete execution contract.** A PB handed to an agent without Stuart at the keyboard must specify: standing approval, pre-flight reads (named files + line ranges), per-item execution cycle (READ→IMPL→REVIEW→GROK→COMMIT), exact test/deploy/Grok commands, and a Definition of Done checklist. (Grok is the second-opinion model I use for reviews.) Here's the difference in practice. On 29 October 2026 I wrote a brief to dock Commander Desktop's terminals on the right-hand side. I was going to try it on my own laptop as it was built, so it was marked `pilot-supervised` and ran to 31 lines: the change in four points, one line on invariants, one paragraph of done. Nine days later I wrote a brief for three changes to how Host shows releases. It would run without me. It was 391 lines long. Neither length is wrong. In a supervised session, every gap in the brief gets filled by a question to me. In an unattended one, a gap gets filled by a guess. Claude Code makes this concrete. In a non-interactive `claude -p` run in Manual mode, which is where such a run starts when nothing sets a permission mode, [the headless docs](https://code.claude.com/docs/en/headless) say a tool call needing approval is denied unless something approves it, and with `--permission-prompts none` the tools that ask a person, such as `AskUserQuestion`, are removed altogether. The agent can't ask. So the brief has to have already answered. The rest of this article walks through the seven parts of that 391-line brief, `261107-pb-rel6c-release-modes-and-guided-setup.md`, with excerpts. ## 1. Write the standing approval as two lists Start with what the agent is allowed to do, and what it isn't. Make it two explicit lists. From the real brief, trimmed, with an internal agent's name replaced by its role: ```markdown ## Standing Approval You are authorised to: - Edit apps/host/src/components/solutions/**, ... and create new files beside them. - Edit supabase/functions/host-app-registry/index.ts (the promote branch only, ~L2685–2700) - Create apps/help/content/user-guide/host/solution-releases.md - Run tests, typechecks and Grok reviews. Commit to feat/host-releases-rel6c, push, open and update a draft PR. You are not authorised to: - merge, mark the PR ready, deploy anything, or run a release on a real Solution; - write or apply a migration (none is needed); - edit .github/workflows/**, mcp/**, skills/**, packages/** ... CLI, MCP and skill copy changes go to the coordinator as exact lines. ``` Three things to notice. The "can" list is scoped to paths, sometimes to line ranges inside one file. The "cannot" list names the actions that would do damage while nobody watches: merging, deploying, touching production. And it says what to do instead of the forbidden thing ("go to the coordinator as exact lines"), so the agent doesn't have to choose between breaking a rule and silently dropping work. Make the brief and the tool permissions agree. If the brief says "run the tests" and the run's permissions don't allow the test command, the agent is stuck at the first item. ## 2. Pre-flight: name the files, the lines, and why Before any code, the agent reads a short table. Every row has a path, a line range, and a reason. ```markdown | File | Lines | Why | |---|---|---| | apps/host/src/components/apps/DeploymentRow.tsx | L38–44, L100–102, L168–190 | Where a staged build reads as a Live "Success" | | apps/host/src/services/appsService.ts | L75–100 | The row type (add environment, branch if absent) | | apps/help/content/user-guide/host/data-location.md | first 40 lines | The Help page voice and front matter | ``` The reason column is the important one. "The Help page voice" tells the agent *why* it's reading a file about something else entirely. Line ranges go stale as other work merges, so the brief carries a staleness check: *"these ranges were read at c1f2cfa72 ... If they've moved, read the current code and note the delta in the session brief before coding."* The agent did exactly that. Its session brief has a section called "Pre-flight deltas", lists where each range now sat, and concludes "All matched the brief; no material drift." Add state checks that make baselines explicit: which tests pass now, which typecheck errors already exist. Without that, an agent can't tell an error it caused from one it inherited. ## 3. One item at a time, the same cycle every time An autonomous brief is split into items, and each item runs the same cycle. The C² starter template writes it as: ```text READ → IMPL → REVIEW → VERIFY → COMMIT ``` My own repo's version adds a second-opinion review step and a mutation check, but the idea is the same: no item starts until the previous one is committed. That gives you a clean history to read in the morning, and if the run dies at item 3, items 1 and 2 are safe on the branch. Each item in the rel6c brief has the same anatomy: - **What to read first:** the lines for this item only. - **Today:** what the code does now, in plain words. - **Change:** what to build, specific enough that no design decision is left. Function signatures are written out. - **Not in scope:** the adjacent things that look like they need fixing. - **Test:** the exact command and what passing looks like. - **Mutation:** a deliberate break the test must catch. - **Commit:** the exact message. Here is the difference between a vague item and a runnable one. Vague: "Make the deployment status clearer." Runnable, from item 1: *a staged build is a row with `environment = 'preview'` and `branch = '__staged__'` ... a staged `success` is "Staged · waiting for release" with `showsLiveLinks: false`; a row with no `environment` is Live (control).* The second leaves the agent nothing to invent. ## 4. Say what not to change The template behind these briefs keeps a table of common failure modes, built from runs that went wrong. Four of its rows: | Failure | Root cause | Fix | |---|---|---| | Agent rewrites adjacent code | Scope not stated | Add an explicit "What not to change" to each item | | TypeScript errors after merge | Baseline not checked in pre-flight | Add the typecheck to the pre-flight state checks | | Migration fails: column doesn't exist | Brief assumed column names from the PRD | Check the real schema in pre-flight | | Commit message drift | Format not specified | Write the exact commit message in the item | The schema row has a cost attached. In May 2026 a brief assumed a table had columns called `kind` and `workspace_id`. Production had `file_kind` and `project_id`. Item 1 was rewritten mid-session, about 20 minutes lost. Now the checklist asks for one schema query in pre-flight for every table a brief touches. ## 5. Exact commands, never "verify it works" "Verify it works" is an instruction to the agent to decide what working means, and it will decide generously. Every test, typecheck and build in the brief is a literal command: ```bash cd apps/host && npx vitest run src/components/apps/deploymentDisplay.test.ts ``` The same goes for the definition of done. One of rel6c's boxes is a search that must come back empty: ```bash git grep -n -i "releases on\|releases off\|turn releases" -- apps/host/src supabase/functions apps/help/content ``` That's a box the agent can't tick by asserting it. It either returns nothing or it doesn't. [Acceptance criteria for agents](/articles/acceptance-criteria-for-agents) goes deeper on writing checks like this. ## 6. Give it a blocker protocol An unattended agent that hits a wall will either stall or improvise. Neither is what you want at 3am. The brief tells it what to do (lightly trimmed): ```markdown ### When blocked 45 minutes per item. Write the blocker in the session brief, add a line to docs/04-operations/MAINTENANCE-BACKLOG.md, move to the next item. A Grok HIGH finding that needs an architectural decision: commit what is safe, add a "NEEDS STUART REVIEW" P0 note to the backlog, and stop. ``` Two different responses for two different problems. A hard bug gets parked and the run continues. A design decision gets surfaced and the run stops, because the agent shouldn't be making it alone. The C² starter template adds one more line I find useful: name the layer before you report the blocker. *Cannot operate* (missing tool, bad permissions) is the environment. *Almost works but unreliable* is the loop and its stop rule. *The process itself is complex* is the topology. A blocker reported without its layer usually gets debugged at the wrong one. ## 7. A definition of done whose boxes need evidence The last section is a checklist, and the rule about it matters more than the list. In August 2026 an audit looked at ten briefs sitting in `review`. Four had definition-of-done boxes with none ticked. Four had no boxes at all. One of the unticked ones was fully delivered. Another was not delivered, with three criteria contradicted by what had shipped. From the outside they looked identical. So the checklist now has an entry rule: a brief can't move to `review` without a definition of done, with at least one box ticked, and each ticked box names its evidence: a commit, a file and line, a test run. A box that can't be confirmed stays open and says so. "Could not verify" is a finding. A silently empty box looks like forgetting. ## Run the checklist before you leave Every autonomous brief in my repo goes through `PB-QUALITY-CHECKLIST.md` before an agent sees it. Five sections: | Section | The question | |---|---| | A. Scope and approval | Can the agent stay on rails? Branch named, approval explicit, "not to change" per item, blocker protocol | | B. Pre-flight | Does it know the ground truth? Files with line ranges, the auth pattern, a typecheck baseline, real column names | | C. Task specification | Can it run without decisions? Exact changes, test, deploy and commit commands | | D. Definition of done | Will it know when to stop? A checklist, where the session brief goes, whether to open a PR | | E. Sizing | Six items or fewer, each under 45 minutes, each testable alone | One NO in sections A or B means the brief isn't ready. The checklist says each check should take under 30 seconds. The checklist also caught a mistake in the template itself, which taught me the most important thing about writing instructions for agents. Until September 2026 the autonomous brief template told agents to add an attribution trailer to every commit, which my global rules forbid outright. Agents follow the brief rather than re-reading the conventions, so they complied, every time. It was spotted while running the checklist against a new set of briefs. **The brief outranks your rules file in practice. Whatever it says, the agent will do.** ## A skeleton you can copy ```markdown # PB: Branch: <name>. Full approval granted: execute all items without pausing. ## Standing approval Authorised: <paths you may edit>, <commands you may run>, commit to <branch>. Not authorised: merge, deploy, <forbidden paths>. For those, write the exact change in the session brief instead. ## Pre-flight | File | Lines | Why | Staleness check: if lines moved, note the delta before coding. Baselines: <test command> (note count), <typecheck> (note existing errors). ## Item 1: <name> Read first / Today / Change / Not in scope / Test (exact) / Commit (exact) ## When blocked 45 minutes per item: write it down, move on. Design decision: commit, stop. ## Definition of done - [ ] <check that returns evidence, not an opinion> - [ ] Session brief at <exact path> ``` The work moves earlier. A brief like this takes me twenty minutes or more to write. What it buys is a run I can read in the morning, item by item, with every claim checkable against git. Start here: [the Cascade from PRD to prompt brief](/articles/the-cascade-from-prd-to-prompt-brief), [how to run AI coding agents overnight, safely](/articles/run-agents-overnight-safely), or [read the method](/c2). --- # Resolute vs EOS (Traction): two operating systems for a company ## EOS gives a leadership team six components, a set of simple tools and an implementer. Resolute starts with the stage your business is at. A fair comparison from the person who wrote one of them. - URL: https://stuartleo.com/articles/resolute-vs-eos - Published: 2026-11-20 - Reading time: 10 min read - Method: Resolute Looking for an EOS alternative? How Resolute compares with EOS (Traction): tools, meetings, rollout, AI, and which suits your business. Fair, with sources. EOS, the Entrepreneurial Operating System from Gino Wickman's book *Traction*, is the best-known operating system for small and mid-sized companies. Resolute is an alternative with a different starting point. EOS strengthens six components of a business with a set of simple tools, usually rolled out by a trained implementer. Resolute first asks which stage of growth the business is at, then works twelve questions on a rhythm, each with a canvas to think wide and a Clarity Statement to land the answer. Those statements are written to be read by people and AI agents alike. I wrote [Resolute](https://www.amazon.com.au/Resolute-navigate-disruption-indestructible-organizations/dp/0645825425), so I'm not neutral. I've tried to be fair the only way I know: every claim about EOS below comes from EOS Worldwide's own site, linked inline. Where I couldn't verify something, I've left it out. ## What is EOS? EOS Worldwide [describes EOS](https://www.eosworldwide.com/what-is-eos) as a set of practical tools that helps leadership teams clarify their vision, gain traction and work together as a team. Gino Wickman introduced it in his 2007 book *Traction: Get a Grip on Your Business*. EOS Worldwide says it is designed for privately held entrepreneurial companies with roughly 10 to 250 employees, and that hundreds of thousands of companies run on it. The [EOS Model](https://www.eosworldwide.com/eos-model) has Six Key Components: Vision, People, Data, Issues, Process and Traction. Each has its tools. The core ones, from the [EOS tools library](https://www.eosworldwide.com/tools): - **V/TO** (Vision/Traction Organizer), which answers eight questions that define the company's vision. - **Accountability Chart**, which defines the structure the business needs and the major roles each seat owns, starting with the Visionary and Integrator seats. EOS is explicit that it [isn't an org chart](https://www.eosworldwide.com/accountability-chart). People are assessed on whether they Get it, Want it and have the Capacity to do it (GWC). - **Scorecard**, 5 to 15 weekly leading indicators. - **Rocks**, the [three to seven priorities](https://www.eosworldwide.com/rocks) that matter most in the next 90 days, each with an owner. - **Level 10 Meeting**, a weekly leadership meeting. The first five agenda items take 25 minutes and leave a [full 60 minutes for solving issues](https://www.eosworldwide.com/blog/perfect-meeting) with IDS: Identify, Discuss, Solve. - **Organizational Checkup**, a free 20-question diagnostic that scores the six components. Rollout is the other half. EOS Worldwide says the full EOS Process takes approximately two years with a Professional EOS Implementer: a Focus Day, two Vision Building sessions, then quarterly and annual sessions. It also says many companies self-implement from the books, tools and EOS Academy. And there's official software, [EOS One](https://eosone.com/), which describes itself as "The official EOS® software. With AI built in." It includes an AI assistant called Atlas, says it works inside ChatGPT, Claude and other assistants, and lists a price of $10 per user. ## What is Resolute? Resolute is the method in my book of the same name, in print since December 2024. It rests on one premise: growth emerges from navigating three tensions, leading versus managing, values versus character, and skills versus systems. I've written those up in [the three tensions](/articles/the-three-tensions). It has three working parts. **The Leadership Curve says where you are.** Six stages: Idea, Identity, Calibrate, Maturity, Mastery, Initiate. It's a sensemaking framework. The right move in Identity is the wrong one in Mastery, so the first job is knowing which stage you're actually in. The [primer](/articles/the-resolute-leadership-curve-a-primer) walks it through. **The 12 Questions say what has to be answered.** Five questions of management for the present: plan, roles, goals, meetings, data. Seven of leadership for the future: vision, market, strategy, business model, customer experience, employee experience, and the one, two or three things that would shift the needle next quarter. They're inspired by the British Army's Mission Command. [The Twelve Questions](/articles/the-twelve-questions) covers each. **Canvases and Clarity Statements turn thinking into something people can act on.** A canvas opens a hard question with divergent thinking. A Clarity Statement closes it with a short, structured sentence a new hire could repeat. Each question has its own pair: a Plan Canvas, a Role Canvas, a Market Canvas and so on. There's more in [canvases and Clarity Statements](/articles/canvases-and-clarity-statements). The questions are asked on a rhythm. A pattern that works for many businesses is the seven of leadership half-yearly and the five of management monthly or quarterly, faster in the early stages. ## Resolute vs EOS at a glance | | EOS | Resolute | |---|---|---| | Origin | *Traction* by Gino Wickman, 2007 | *Resolute* by Stuart Leo, December 2024 | | Organising idea | Six Key Components: Vision, People, Data, Issues, Process, Traction | Three tensions, mapped across six stages of growth | | First question | How strong is each component? (Organizational Checkup) | Which stage of the Leadership Curve is the business on? (diagnostic) | | Vision and strategy | V/TO, eight questions | Seven questions of leadership, each with a canvas and Clarity Statement | | Roles | Accountability Chart, GWC | Roles question, Role Canvas | | Numbers | Scorecard, 5–15 weekly measures | Data question, Data Canvas | | Quarterly focus | Rocks, 3–7 per 90 days | The one, two or three things that shift the needle | | Weekly meeting | Level 10 Meeting, IDS | Weekly tactical: data, goals, issues, decisions with owners | | Rollout | Professional EOS Implementer over about two years, or self-implement from the books and free tools, including the Organizational Checkup | Book, free library of canvases, free diagnostic | | Software | EOS One, AI built in | Any tool: paper, paste a canvas into an AI assistant, or WaymakerOS | | Who it's for | Private companies of roughly 10–250 employees (EOS's stated range) | Founders and leadership teams, at whichever stage of the Curve they're on | ## What EOS does well I'd rather say this plainly than bury it. EOS is good, and it's popular for real reasons. **It's simple and complete.** Six components, a handful of named tools, one meeting agenda. A leadership team can learn the vocabulary fast, and the vocabulary sticks. **The weekly meeting works.** Giving 60 of the Level 10's minutes to solving issues is the right ratio. When I wrote [how to run a leadership meeting](/articles/how-to-run-a-leadership-meeting), I named the Level 10 as EOS's version of the same idea, and the Resolute weekly lands in a similar shape: data first, goals check, then most of the time on issues. **Rocks force focus.** Three to seven priorities, each with an owner, every 90 days, reviewed weekly. One of the clearest tells of a stalled business is a priority list of fifteen items and no owners. Rocks fix that. **It has an implementer network and a community.** If you want a trained facilitator in the room from the first day, EOS gives you a clear path to one, plus a large community of companies running the same system. **Who EOS suits.** A privately held company in the 10 to 250 range, with a leadership team that wants a proven, ready-made system and is happy to adopt its vocabulary and tools as given. ## Where Resolute differs **It starts from your stage, not just your components.** The Leadership Curve exists because the business you need at Identity isn't the one you need at Maturity. The most common place I see businesses stall is Calibrate, where growth that ran through the founder breaks once they step away. I've written that one up in [why businesses stall at Calibrate](/articles/why-businesses-stall-at-calibrate). Resolute tells a leader what to build next for the stage they're actually in. **It works each question wide, then narrow.** Every one of the twelve gets a canvas for divergent thinking and a Clarity Statement for convergent thinking. The canvas is where the team argues. The statement is where it decides. Having a named tool for each mode, on every question, is the point: it stops a team writing the sentence in the first ten minutes, and it asks you to work the question again next season. **It separates leading from managing in the questions themselves.** The seven questions of leadership question whether the plan is the right plan. The five of management assume the plan and ask whether the business is wired to deliver it. Before picking which set to work, Resolute asks one prior question: are you innovating or executing? EOS has its own take on this distinction in its Lead, Manage, Hold Accountable tool, so this is a difference in emphasis rather than a gap. **It treats the answers as context for people and agents.** A Clarity Statement is short and written down on purpose. That makes it the unit of context for the business: a new hire can repeat it, and an AI agent can read it as easily as a person can. This is why I put Resolute and [C²](/c2) under the same umbrella, [Context Leadership](/articles/what-is-context-leadership). Resolute doesn't require any particular software. You can work the canvases on butcher's paper, paste one into an AI assistant, or run them on WaymakerOS, the platform I build. To be fair to EOS, EOS One has AI built in too. The difference is less about AI features and more about whether the plan exists as written context that travels between people, tools and agents. **It's built on character as well as structure.** Two of the three tensions, values versus character and skills versus systems, are about whether what a business says it stands for matches what people actually experience, and whether a skill survives the person who holds it. EOS covers values through Core Values and its People Analyzer. Resolute makes that gap a central tension rather than one tool among several. **Who Resolute suits.** Founders and leadership teams who want a stage-aware way of thinking, especially at the founder bottleneck, who would rather work through a question than fill in a template, and who want the plan written down in a form both their people and their AI agents can work from. ## Can you use Resolute and EOS together? Yes, at the level of ideas. The two overlap more than the vocabulary suggests: both run a weekly meeting that spends most of its time on issues, both set a short list of owned quarterly priorities, both care about roles and numbers. If you run EOS and it's working, I wouldn't tell you to stop. You might use the Leadership Curve to name the stage you're in, or take a stale V/TO answer back to a Resolute canvas for a season. If you're looking for an EOS alternative because the tools feel like boxes to fill rather than questions to work, or because you want the plan to be readable context for agents as well as people, Resolute is worth a look. The free [Resolute diagnostic](/resolute/assessment) places your business on the Curve and names the one constraint holding back the next stage. Every canvas is free to read in the [Resolute library](/resolute/library). --- *Last checked: 20 November 2026.* EOS facts come from eosworldwide.com and eosone.com on that date. If anything here is out of date or unfair to EOS, tell me and I'll correct it. Start here: [the Resolute Leadership Curve primer](/articles/the-resolute-leadership-curve-a-primer), [the Twelve Questions](/articles/the-twelve-questions), or [the Resolute hub](/resolute). --- # What goes in a session brief: a template and three real briefs ## The handoff template I use with Claude Code, section by section, and three real briefs from my repos with what each part bought the next session. - URL: https://stuartleo.com/articles/session-brief-template-with-real-examples - Published: 2026-11-20 - Reading time: 11 min read - Method: C² Method A Claude Code session handoff template, section by section, with three real session briefs from my repos and what each part bought the next session. A good Claude Code session handoff answers one question for a reader who has nothing else: where is the work, really? In practice that means seven parts. The goal. What changed, with commits. The decisions and why. What was verified, with real numbers. What was **not** verified. Who owns any blocker. And a start state for the next session, down to the first action. If you have never written one, start with [write your first session brief](/articles/write-your-first-session-brief), which covers the habit. This article is the next step: the full template I use in my own repos, section by section, and three real briefs from them, trimmed and annotated, showing what each part bought the session after it. ## The session brief template, section by section The [C² Method](/c2) ships a session brief template in its starter kit, at `docs/02-working/session-briefs/session-brief.md`. The header of that template says what it is for: *this is AI memory.* The async stand-up is a side effect. Here are its sections and what each one is for. | Section | What goes in it | What it buys the next session | |---|---|---| | Session goal | One sentence, plus links to the prompt brief and PRD | Knows what "done" was meant to mean | | What was done | A table of items with status, files and commits | Can check the claims against git in seconds | | Decisions made | Each decision with its reason | Doesn't re-argue a settled choice | | Blockers | Each one, with the layer that owns it | Knows what it can't fix from here | | Key discovery | Any trap found. If filled, a gotcha file goes in the same commit | Doesn't pay to find the trap again | | Documentation obligations | Docs due now, at PR, or at release | Knows what is still owed | | Test debt | Tests deferred, with the reason | Doesn't assume coverage that isn't there | | Next session start state | Start here, context it needs, outstanding work, first action | Moves in the first minute, not the twentieth | | Landing zone | Believed landing date, percent complete, confidence | Anyone can see progress without a meeting | The template has a gate I'd keep even if you drop everything else: if the Key discovery section has content, a file in `docs/03-knowledge/` is required **in the same commit**. Not later. A discovery that lives only in a session brief gets read once and then sinks under the next hundred briefs. A gotcha file gets read every time someone touches that area. (More on that in [the gotchas folder](/articles/the-gotchas-folder).) Real briefs rarely use every heading. The three below don't. What they all keep is the core: what changed, what's verified, what isn't, and what's next. ## Real brief 1: an overnight run on this site This one is from the repo for stuartleo.com, dated 17 to 18 November 2026. I'd asked an agent to fix a broken image on `/c2`, then review the whole site overnight. Trimmed and reflowed for width, with preview URLs and a server address removed: ```markdown # Session brief: overnight SEO fixes, content review, new articles (2026-11-17 → 18) ## Shipped to main (all verified live) | Commit | What | |---------|------| | b4e0256 | /c2 terminal screenshot was never copied from the c2method.ai repo. | Article OG: generateImageMetadata gave every article ~97 og:image | tags (first = wrong article) ... Gotcha: | docs/03-knowledge/gotchas/generate-image-metadata-fans-out-to-every-page.md | | bbcf3d6 | IBM Plex self-hosted (app/fonts, next/font/local). The 8bf68f5 deploy | failed fetching Google Fonts, the same as 2026-11-09. | Gotcha: next-font-google-fails-host-builds.md | Crawl: all 269 sitemap pages, no other broken <img>. ## Needs Stuart (outside the repo) 1. www.stuartleo.com serves "This is the default server vhost" from an old origin. It is indexed (61 impressions). Fix in Cloudflare DNS or a redirect rule. 2. http:// isn't redirected to https://. Turn on Always Use HTTPS. ## Notes for next session - Remove the worktree after merge: git worktree remove ../stuartleo-content - The stuartleo CLAUDE.md is stale: it says Next.js 15. ## Morning follow-up (2026-11-18) - www and http fixed by Stuart in Cloudflare. A redirect rule sends https://www.stuartleo.com/* to https://stuartleo.com/${1} (301), and Always Use HTTPS is on. Verified: http://, http://www. and https://www. all end on the apex, with the path and query string kept. ``` **What each part bought.** The shipped table carries a commit hash per row. When I read it in the morning I didn't take "fixed" on trust. I could open each commit. That matters more for overnight runs than any other kind, because nobody watched them happen. "Crawl: all 269 sitemap pages" turns "I checked the images" into a claim with a size. A reader can tell the difference between checking one page and checking all of them. Two rows point at gotcha files written in the same session. The font failure had already happened once, on 9 November. The second time, it got written down. The next agent that touches fonts on this site reads one short file instead of rediscovering a flaky build. "Needs Stuart (outside the repo)" is the section I value most here. The agent couldn't reach the DNS zone, so instead of guessing it named the exact two settings and handed them to me. The morning follow-up, appended to the same brief, shows those two items closed and verified three ways. One file holds the problem, the owner, the fix and the proof. ## Real brief 2: a Commander Desktop feature Commander Desktop is the Mac app I'm building, where agents run in terminals beside your work. On 29 October 2026 I asked for a side-by-side layout: a note on the left, an agent's terminal on the right, for working on a 16-inch laptop. Trimmed: ```markdown # Session brief: terminals docked on the right (side by side with the page) Lane: commander-desktop. Stuart, 2026-10-29: loves the stacked layout, but wants a column side by side view when reading a note or a Spark while chatting with an agent (16-inch laptop). This is step 1 of three (side by side, then pop out a terminal into its own window, then content windows). The stacked layout is the default and is unchanged. ## Verified vitest 907 passed (1 skipped); tsc clean; cargo test --lib 927 passed + the known termhost environment failure; Rust round-trip test (old layout loads with no dock and saves without the keys). Browser harness: screenshots at 1440x900 stacked (unchanged), 1440x900 right, 1100x700 right ... One bug found and fixed from them: the terminal list was clipped to 13px by a percentage max-height. ## Not verified (needs the live app) - A real terminal in the right dock: refit on drag and on toggle (the mock has no terminals), agent TUIs at 25–30% width. - The look with many terminals in the list under the terminal. - windows.rs builds repository windows with a default layout, so a window opened for one repository shows the stacked layout whatever the main window chose. ## Next Pop-out of a terminal into its own window (kept terminals first, since the host lets a second window reattach by tag), then content windows. ``` **What each part bought.** The opening paragraph keeps my words and my reason (the 16-inch laptop). A later session that wants to "tidy up" the layout knows the stacked view is the one I like, and the side-by-side dock is the extra. "Step 1 of three" sets the order. The next brief, written the same day, is step 2: the pop-out terminal. Its first design decision builds the pop-out windows in `windows.rs`, the file the dock brief had flagged. The verified section gives counts and a known failure by name. "+ the known termhost environment failure" stops the next session from losing an hour chasing a red test that was red before it started. The "Not verified" list is the honest half. The mock has no terminals, so nothing proved a real terminal refits when dragged. Without that list, a reader sees green tests and screenshots and assumes the feature works in the app. With it, they know exactly what to try first in the live app, and why the tests couldn't cover it. ## Real brief 3: a Host release change Host is the part of Waymaker where apps are built and released. On 6 November 2026 I changed how new Solutions (groups of apps released together) ship: straight to production on push by default, with a gated release as an owner's opt-in. Trimmed, with internal names made generic: ```markdown # Session brief: new Solutions push to production by default again (option A), 2026-11-06 ## Why Stuart (2026-11-06): "i do not want our 'Solution Release' thing in Host to be blocking a standard release process ..." He chose option A: new Solutions push by default, and Release stays an owner opt-in. ## What changed - A migration that changes the default to push, NOT APPLIED. Existing rows are untouched. The rollback sits next to it. ## Not in this PR (files this lane can't touch), sent to the owner as lines - The Host skill file says release is the default for every Solution. After the migration, push is. Exact line given. - The test workflow: add the new test file to the Host test step. ## Next - The agent that owns migrations applies it on Stuart's word. - Help has no article on how a Solution releases. Backlog entry added. ``` **What each part bought.** "NOT APPLIED", in capitals, on the migration. In my repos a merge deploys code but doesn't apply migrations, so code and database can disagree for a while. The very next day, a different session building the plain-language release modes read this and wrote in its own brief that Help doesn't state the default for new Solutions, because the migration was headed NOT APPLIED and the lane couldn't check production. It didn't document a default that might not be live yet. That's one line in one brief preventing a wrong help page. "Not in this PR, sent as lines" handles the files this agent wasn't allowed to touch. It doesn't skip them silently, and it doesn't break the rule. It writes the exact change for whoever owns those files, here the coordinating agent that merges and owns workflows and skills. The last "Next" line, "Help has no article on how a Solution releases", became item 3 of the next day's prompt brief, which wrote that article. ## What the three have in common None of them is a transcript. None restates the prompt brief. None says how the session felt. All three separate **verified** from **believed**. All three name what is outside the session's reach and who owns it. All three end with a next move specific enough to start on. That's the core of a handoff template. Everything else is optional. The biggest single habit: write the "Not verified" list as carefully as the "Verified" one. Agents report success fluently. The brief is where you make them say what they didn't check. ## A minimal handoff template you can copy If the full template feels heavy, this is the shape all three briefs above share: ```markdown # Session brief: <topic> (YYYY-MM-DD) ## Why <One paragraph: what was asked, by whom, in their words if possible.> ## What changed | Item | Commit | What | |---|---|---| ## Decisions - <Decision>: <reason> ## Verified <Commands run and their counts. Name known failures that were already red.> ## Not verified - <What no test or check covered, and what would prove it.> ## Outside this session - <Blocker or change someone else owns, with the exact ask.> ## Next Start here: <file or task>. First action: <one instruction>. Gotcha written: <path, or "none">. ``` ## Naming briefs so tools can find them Name briefs by date, consistently: `YYYY-MM-DD-topic.md`. It sounds fussy. Here's why it isn't. My main repo has a Claude Code [SessionStart hook](https://code.claude.com/docs/en/hooks) that lists the last 30 days of briefs at the start of every session. It once matched only names ending in `-session-brief.md`. From 19 August 2026 briefs dropped that suffix, and the hook went blind: every session booted showing an 18 August brief as the newest. The fix was a hook that tolerates every format in use, and a pre-commit check that refuses a new brief named any other way. That repo's 2026 folder holds more than 1,100 briefs, and the hook still puts the newest at the top of every session. The template is the easy part. The habit is writing one every time the context is about to go: end of day, a meeting, a full window, a reboot. Five minutes at the end buys a running start at the next one. Start here: [write your first session brief](/articles/write-your-first-session-brief), [how to stop Claude Code losing context between sessions](/articles/how-to-stop-claude-code-losing-context-between-sessions), or [run your first C² session](/c2/start). --- # Task Master vs BMAD vs Agent OS: which fits your repo? ## A task queue, a full delivery method and a standards layer. What each one installs, what it puts in your repo, and who it suits, checked against their own repos and docs. - URL: https://stuartleo.com/articles/task-master-vs-bmad-vs-agent-os - Published: 2026-11-20 - Reading time: 11 min read - Method: C² Method Task Master vs BMAD vs Agent OS: what each is, how it installs, what files it adds to your repo, licences, and who each suits. Checked on their own docs. Task Master, BMAD and Agent OS get compared as if they were three versions of the same thing. They aren't. **Task Master** turns a PRD into a dependency-ordered task queue your agent works through. **BMAD** is a full agile delivery method run through named agent roles, from clarifying the idea to retrospectives. **Agent OS** captures your coding standards and injects the right ones into whatever plan your agent writes. Pick by the problem you actually have: a big PRD to sequence, a whole delivery process to run, or agents that ignore your conventions. This is a closer look at those three, spun out of my wider comparison of [spec-driven development tools](/articles/spec-driven-development-tools-compared). Every fact about them comes from their own repos and docs, linked inline and checked on the date at the bottom. One disclosure up front. I built [C²](/c2), a method for keeping context across a repo, and I compare it at the end. So I'm not neutral. Where something isn't documented, I've left it out rather than guessed. ## Task Master vs BMAD vs Agent OS at a glance | | Task Master | BMAD Method | Agent OS | |---|---|---|---| | What it is | PRD → task queue for your agent | Full agile method with agent roles | Coding standards captured and injected | | Starts from | A PRD you've written | Wherever your input is: a notion, an idea or a change | Your existing codebase's conventions | | Install | npm package, run as MCP server or CLI | `npx bmad-method install` (v6.12) or `npx skills add` (v7 preview) | Base install, then a project install script | | In your repo | `.taskmaster/` with PRD, config, `tasks.json` | Ticket tree of specs under `_bmad-output/`, plus an AGENTS.md block | `agent-os/` with standards, product docs, spec folders | | Calls models itself | Yes, needs a provider key unless via Claude Code or Codex CLI | No, runs inside your coding agent | No, runs inside your coding agent | | Licence | MIT with Commons Clause | MIT | MIT | | Latest release | 0.43.1, 31 March 2026 | v6.12.4, 14 October 2026 (v7 in preview) | v3.0, 20 January 2026 | | GitHub stars | about 28,500 | about 55,500 | about 5,600 | | Best for | Sequencing a large PRD | Larger work that needs product and architecture thinking | Keeping agents on your conventions | ## What is Task Master? [Task Master](https://github.com/eyaltoledano/claude-task-master) describes itself as an AI-powered task-management system you can drop into Cursor, Windsurf, Roo, Lovable and other tools. Its docs now live on [Hamster's site](https://tryhamster.com/docs/taskmaster). **How it works.** You write a PRD. Task Master parses it into tasks, each with an id, title, description, status, dependencies, priority, implementation details, a test strategy and optional subtasks, per its [task structure doc](https://github.com/eyaltoledano/claude-task-master/blob/main/docs/task-structure.md). From there your agent asks it what to work on next, expands a task into subtasks, and marks work done. It has a research command for pulling in current information, and tags for separate workstreams. **Install.** From the README: ```bash npm install -g task-master-ai task-master init # or, for Claude Code, as an MCP server claude mcp add taskmaster-ai -- npx -y task-master-ai ``` **What it puts in your repo.** A `.taskmaster/` folder. Your PRD goes in `.taskmaster/docs/prd.txt`, and an example lives in `.taskmaster/templates/example_prd.txt` after init. Model settings live in `.taskmaster/config.json`, tag state in `.taskmaster/state.json`, and the tasks themselves in a `tasks.json` file, with generated per-task files kept in sync from it. The tutorial notes that teams can hit merge conflicts in `tasks.json` when people add tasks on different branches, and it has a move command for resolving them. **The two things to know before adopting it.** First, Task Master calls models itself. You configure main, research and fallback roles, and need at least one provider API key, unless you route through Claude Code or Codex CLI. Second, the licence is MIT with the Commons Clause. You can use it for any purpose and sell what you build with it, but you can't sell Task Master itself, host it as a service or build a competing product from it. **Activity.** The latest tagged release is 0.43.1 from [31 March 2026](https://github.com/eyaltoledano/claude-task-master/releases), and the last push to the repo was in late April. On the evidence I can see, the open-source repo has slowed this year. **Who it suits.** Someone who already has a good PRD and wants it broken into an ordered queue the agent can work through without losing its place. ## What is BMAD Method? [BMAD](https://github.com/bmad-code-org/BMAD-METHOD) calls itself agile AI-driven development: turning an idea or change request into working software "without giving up the thinking". Its README says it's free and open source with no paywalled workflows, under the MIT licence. **How it works.** [How BMad works](https://docs.bmad-method.org/start/how-bmad-works/) lays out four stages: clarify, plan, build and verify, learn and adjust. They aren't a fixed sequence. A small fix can start at build. Each stage has named agents: Mary the analyst, John the product manager, Sofia the product owner, Sally on UX, Winston the architect and Mason the developer. Tracked work sits in a ticket tree. An initiative holds epics in build order. An epic is one capability delivered over several build sessions. A story is one build session's worth of work. **Install.** BMAD ships on two lines. The stable line is v6.12, which the README says is frozen apart from bug fixes: ```bash npx bmad-method install ``` It needs Node.js 20.12+, Python 3.10+ and uv. The v7 line is a preview alpha that installs as agent skills, and the README warns to expect breaking changes: ```bash npx skills add bmad-code-org/BMAD-METHOD/skills/core-tools --skill '*' npx skills add bmad-code-org/BMAD-METHOD/skills/method --skill '*' ``` The README gave v7's release target as mid-November 2026. As of my check, the latest tagged release is still [v6.12.4 from 14 October](https://github.com/bmad-code-org/BMAD-METHOD/releases). **What it puts in your repo.** In the docs' example layout, work lands under `_bmad-output/`: an initiative spec, folders for its PRD, UX and architecture documents, and a `tickets/` tree where `tickets.toml` files list the epics and stories and each story gets a plan file carrying its status. BMAD also has a [project-context skill](https://docs.bmad-method.org/existing-codebases/set-and-maintain-project-context/), `bmad-project-context`, that writes a verified block into `AGENTS.md` between `<!-- bmad:context -->` markers. It holds only what is costly to rediscover: policy, run caveats, non-default conventions, observed pitfalls. For Claude Code it proposes a one-line `@AGENTS.md` import into CLAUDE.md. It never commits. You review the change. **Who it suits.** Teams and solo builders who want a complete method, with product, UX and architecture thinking before the build and retrospectives after. BMAD sizes the process to the work, but there is more of it than in either of the other two. ## What is Agent OS? [Agent OS](https://github.com/buildermethods/agent-os) is by Brian Casel at Builder Methods. Its README says it helps you shape better specs and keeps agents aligned in a lightweight system that fits how you already build, alongside Claude Code, Cursor, Antigravity and other tools. **How it works.** [Version 3.0](https://github.com/buildermethods/agent-os/blob/main/CHANGELOG.md), released 20 January 2026, deliberately narrowed the tool. The changelog says spec writing is now best handled by your agent's plan mode, task breakdown by the agent's own todo lists, and orchestration by frontier models, so v3 retired those phases. What it kept is standards. There are five commands: - `discover-standards` surfaces conventions from your codebase and writes them up as standards. - `index-standards` keeps them organised in an `index.yml`. - `inject-standards` pulls the relevant ones into a conversation, plan, subagent or Claude skill. - `plan-product` writes product docs through an interactive conversation. - `shape-spec` improves plan mode with targeted questions and saves the result. **Install.** There's a base installation, then a project install script run from inside your repo. The full instructions are on [Builder Methods' site](https://buildermethods.com/agent-os), which asks for your email before showing them. Agent OS itself is free and open source. Official support comes through a paid Builder Methods Pro membership. **What it puts in your repo.** From the install script and command files: an `agent-os/` folder with `agent-os/standards/` and its `index.yml`, plus the commands copied into `.claude/commands/agent-os/`. `plan-product` writes `agent-os/product/mission.md`, `roadmap.md` and `tech-stack.md`. Each `shape-spec` run creates a dated folder under `agent-os/specs/` holding `plan.md`, `shape.md`, `standards.md` and `references.md`. **Who it suits.** Developers whose agents plan well enough but keep drifting from house conventions. It's the thinnest of the three by design. ## Task Master vs BMAD: are they the same kind of tool? No. Task Master manages the queue after the PRD exists. BMAD helps you decide what the PRD should say, and then runs the delivery around it, roles and retrospectives included. They overlap in one place: both break work down and track it. BMAD does that as a ticket tree of specs written in markdown. Task Master does it as structured tasks with dependencies in `tasks.json`, worked through a `next` command. The practical differences are cost and licence. BMAD runs inside your coding agent. Task Master makes its own model calls, so you either supply API keys or route it through Claude Code or Codex CLI. And BMAD is plain MIT while Task Master carries the Commons Clause. ## BMAD vs Agent OS These differ in shape more than anything. BMAD is a full method with six named roles and four stages. Agent OS v3 is a standards layer that hands planning back to your agent and makes sure the plan follows your conventions. They also disagree about where the field is heading. Agent OS's v3 changelog is an argument that agents now handle specs and task breakdown well enough on their own. BMAD's position is that the thinking around the code still needs structure, scaled to the size of the change. Both are reasonable bets. Which one you agree with is a decent guide to which tool you'll be happy with. ## Where C² differs [C²](https://github.com/waymakerone/c2method) is mine, so take this section with that bias. It isn't a task manager, a delivery method with roles, or a standards injector, and it doesn't compete with any of these three on their own ground. C² is about the context around the whole repo, kept over time. A C² repo has a router file at the root (AGENTS.md, CLAUDE.md or GEMINI.md) that points into a `docs/` contextbase. Work flows down [a cascade from PRD to prompt brief](/articles/the-cascade-from-prd-to-prompt-brief). Every session ends with a session brief. Every non-obvious trap becomes a gotcha file so nobody hits it cold twice. There's no CLI to install. You copy a starter folder of markdown templates into the repo. The current version is v1.4.3, released [25 September 2026](https://github.com/waymakerone/c2method/blob/main/CHANGELOG.md), with an experimental fleet kit for running one agent per PRD. It's free under CC BY-NC-SA 4.0. To be fair to all three, each now holds some durable context. Task Master keeps the task history. Agent OS keeps standards and product docs. BMAD's project-context skill keeps a verified block of pitfalls and caveats, and I've written about how that compares in [C² vs BMAD](/articles/c2-vs-bmad). The difference I care about is scope. Their context serves their workflow. A [contextbase](/articles/what-is-a-contextbase) is the record of the repo itself: every decision, every trap, every session's handover. That's what makes the twelfth feature start ahead of the first. So they compose. Task Master's `.taskmaster/`, BMAD's output tree or Agent OS's `agent-os/` folder can sit inside a repo that also has a router and a contextbase. Let the router point the agent at them. Let the session briefs and gotchas carry what was learned into the next piece of work. ## How to choose - **You have a solid PRD and want it sequenced.** Task Master, after reading the licence and deciding how you'll pay for its model calls. - **You want help deciding what to build, not just building it.** BMAD. Stay on v6.12 if you need stability until v7 is released. - **Your agents plan fine but ignore your conventions.** Agent OS. - **Every session starts cold and the same traps keep recurring.** That's a context problem, and it's the one I built C² for. --- *Last checked: 20 November 2026.* All three projects change often. If anything here is out of date, tell me and I'll fix it. Start here: the wider [spec-driven development tools comparison](/articles/spec-driven-development-tools-compared), [C² vs BMAD](/articles/c2-vs-bmad), or [set up C² in your repo](/c2/start). --- # The gotchas folder: the cheapest context your agent reads ## One short file per trap, named after the trap, pointed at from the router by symptom. How I stop agents repeating the same mistakes, with real gotchas from my repos. - URL: https://stuartleo.com/articles/the-gotchas-folder - Published: 2026-11-20 - Reading time: 9 min read - Method: C² Method How to stop an AI agent repeating mistakes: a gotchas folder of one-file traps, how to name and write them, when to add one, and how the router points at them. An AI agent repeats a mistake because the fix lived somewhere the next session can't see: a chat, a closed terminal, someone's memory. The way to stop it is to write each trap down once, as one short file, in a folder the agent checks before it works in that area. In the [C² Method](/c2) that folder is `docs/03-knowledge/gotchas/`. Each file holds one trap: the symptom, the cause, the fix, and a check. It's named after the trap, and the router file points at it by symptom. [How to stop your agent forgetting](/articles/how-to-stop-your-agent-forgetting) covers the broad problem: why agents forget, and why learning has to live in the repo. This article is narrower and more practical. It's just the gotchas folder: what goes in a file, how to name it, when to write one, how the router finds it, and real examples from my repos. ## Why a gotcha is the cheapest context Everything in `CLAUDE.md` costs context in every session. Claude Code's [memory docs](https://code.claude.com/docs/en/memory) recommend keeping each `CLAUDE.md` under 200 lines, because longer files cost more context and reduce adherence. They also note that `@path` imports help organise a long file but don't reduce its cost, because imported files load with the file that imports them. My main repo's gotchas folder holds 217 files, about 12,500 lines in all. Loading that into every session would be absurd. Most sessions need none of it. A gotcha file costs nothing until it's needed. The agent pays for one file, roughly 40 lines, at the moment it works in the area where the trap lives. That's the trade: a large, growing body of knowledge with a near-zero standing cost. ## What a gotcha file looks like Here's a real one from the repo for this site, written on 17 November 2026, in full: ```markdown # next/font/google can fail a Host deploy **Symptom:** a production deploy fails in `NextFontGoogleFontFileReplacer` / `resolve_internal` and nothing in the commit is wrong. It happened on 2026-11-09 and again on 2026-11-17 (the article-table fix, commit 8bf68f5). A re-push may pass, because the cause is the build fetching font files from Google at build time. **Fix (2026-11-17):** IBM Plex is self-hosted from `app/fonts/` with `next/font/local` (`app/layout.tsx`). The Sans file is Google's Latin variable font (one file, weights 400-700); Mono is three static weights. Licence: SIL Open Font License. **Rule:** don't reintroduce `next/font/google`. To add a weight or face, download the woff2 from the Google Fonts CSS API (Latin block) into `app/fonts/` and add it to the `localFont` src list. ``` Thirteen lines. The symptom quotes the actual error text, which is what an agent will be looking at when it needs this file. The cause explains why a re-push sometimes "fixes" it, which is the misleading part. The rule says what not to do *and* how to do the legitimate thing instead (add a font weight), so the agent isn't left with only a prohibition. The other gotcha from that night has a part I'd put in every file, a check: ```markdown **Check:** `curl -s <article url> | grep -c 'og:image'` should print 1. ``` The bug was that every article page emitted about 97 `og:image` tags, the first one for a different article. The check is one command with one expected number. An agent touching social images later can prove it hasn't brought the bug back, rather than believing it. ## The four parts every gotcha needs The C² starter kit has a gotcha template with frontmatter and six headings. Real gotchas drift from it, and that's fine. Only 49 of my 217 use frontmatter at all. What they keep is four parts: | Part | What it answers | Write it as | |---|---|---| | Symptom | What will I see? | The exact error text or behaviour, and when it was found | | Cause | Why does it happen? | The mechanism, especially why the obvious fix doesn't work | | Fix | What do I do instead? | A specific pattern, command or setting | | Check | How do I know I'm clear? | A command with an expected result | The cause is the part people skip and shouldn't. A fix without a cause is a ritual. The next agent will follow it until something nearby changes, then drop it, because it can't tell whether it still applies. ## Name the file after the trap, not the topic Look at a few real filenames from the main repo: ```text deleting-a-function-source-does-not-undeploy-it.md merge-deploys-code-but-never-applies-its-migration.md desktop-vitest-needs-its-own-npm-ci.md kv-access-changes-are-not-instant.md worker-lockfile-wrangler-drift.md ``` Each name is the warning. A plain `ls` of the folder reads as a list of things that will hurt you, and an agent grepping filenames for "migration" or "npm ci" lands on the right file without opening anything. The older style, `openai-parameter-naming-gotcha.md`, tells you the topic and nothing else. Five files in that folder still use it. ## When to write a gotcha Three conditions, all true. It was **non-obvious**: a competent person would walk into it. It **cost real time**. It will **bite again**: the code, tool or habit that caused it is still there. The best time is the session that found it. The C² session brief template has a gate for exactly this: if the brief's "key discovery" section has content, a file in `docs/03-knowledge/` goes in the **same commit**. Not next week. The [overnight brief from this site](/articles/session-brief-template-with-real-examples) shows it working: two traps found, two gotcha files committed in the same session, both linked from the brief. The worst time is the second time. The font failure above first hit on 9 November. It hit again on 17 November, and that's when it got written down. A file on the 9th would have saved the second failed deploy. ## How the router points at gotchas A gotcha the agent never opens doesn't help. Two things make it get opened. **The router points at the folder.** My main repo's `CLAUDE.md` lists `/docs/03-knowledge/gotchas/` among its most-used locations, and my global instructions tell every session to check the latest session brief and the gotchas before starting work. **The router points at the worst ones by symptom.** For traps that are costly and easy to misread, `CLAUDE.md` has a table keyed on what you'd actually see: | Issue | Guide | |---|---| | A worker won't deploy / "lock file does not satisfy" | `worker-lockfile-wrangler-drift.md`: **check all eleven, not just the one that broke** | | Changed a bucket's access and it didn't take | `kv-access-changes-are-not-instant.md`: ~60s | That's one line per gotcha in the router, and the line carries the punchline, so even an agent that doesn't open the file gets the most important part. The rest stays in the file, paid for only when needed. Claude Code's [path-scoped rules](https://code.claude.com/docs/en/memory) are another way to do this: a rule in `.claude/rules/` with a `paths` field loads only when Claude works with matching files, so a one-line pointer to a gotcha can load only for the code it's about. What doesn't work is a hand-kept index. The folder has a `README.md` that was meant to list the gotchas. It links 11 of the 217 and was last updated in May 2026. Nobody maintains an index when they're busy fixing the thing. Let the filenames be the index, and spend your router lines on symptoms. ## Write the general lesson, not just the incident The gotchas that pay most go one step past the incident. `worker-lockfile-wrangler-drift.md` starts with one worker that wouldn't deploy because its lockfile pinned an old wrangler version. Then: ```markdown ## The part worth internalising It surfaced only because a change touched that worker. **Checking all eleven found a second one**, identical fault ... Not drifted, not broken in production: simply undeployable the moment anyone edits it. ``` It then gives a loop that dry-runs `npm ci` in every worker directory. The file opens: "Found three times now." The lesson isn't "fix this lockfile". It's "when one breaks, check the whole set". `kv-access-changes-are-not-instant.md` does the same. It records an access change that took about 60 seconds to reach the edge, then ends on the general rule: **anything globally replicated needs a poll, not an assertion, and one negative read is not evidence.** The file names its cousins: a just-deployed worker that still serves the old version, and a package publish that isn't on the registry the instant it returns. And some gotchas grow into small systems. `agent-worktrees-are-never-cleaned-up.md` began on 5 October 2026 when 123 leftover agent worktrees, about 216 GB, filled my Mac's disk. The file now holds a measured table of three ways to create a worktree (from about 2.9 GB down to about 0.08 GB each), why `du` lies about APFS clones and `df` doesn't, and the three guards now in place against it. The router carries one line pointing at it. ## What doesn't go in the gotchas folder Keep the folder for traps. Other knowledge has other homes: - **Rules** ("never commit to main") go in the router. They apply every session. - **Decisions** ("X was chosen over Y because Z") go in decision records. - **Session state** ("item 3 is half done") goes in the session brief. - **Patterns** ("this is how an edge function is written here") go in patterns. A gotcha is specifically the thing that looks fine and isn't. That's what makes it worth a file: it's the knowledge an agent can't derive from reading the code, because the code looks right. Two minutes to write the file. One line in the router if it's a bad one. After that, the mistake costs nothing the next time, for every agent, on every model. Start here: [how to stop your agent forgetting](/articles/how-to-stop-your-agent-forgetting), [what a contextbase is](/articles/what-is-a-contextbase), or [run your first C² session](/c2/start). --- # How to customise the C² Method for your team and project ## The six folders are a starting shape, not a rulebook. What's load-bearing, what you can bend, and a worked example of extending it. - URL: https://stuartleo.com/articles/customise-the-c2-method - Published: 2026-11-18 - Reading time: 4 min read - Method: C² Method C²'s folders are a starting shape, not a rulebook. What's load-bearing, how to adapt the rest to your team, and a worked example: adding a metrics folder. The fastest way to misread C² is to treat the six folders as a standard you have to comply with. They aren't. They're a starting shape, the layout that held up across a couple of years of real production work, handed to you so you don't start from a blank repo. It's [convention over configuration](https://rubyonrails.org/doctrine): sensible defaults you can override, not rules you must obey. What matters isn't the folders. It's the two ideas underneath them: **context is a first-class artifact**, and **the agent reads it before it acts**. Everything else is arrangement, and arrangement should serve your project. Here's what you can't bend, what you can, and a worked example of extending it. ## What's load-bearing Three things are genuinely structural. Keep these and you're doing C²: - **The Router.** One file your agent reads first, that points to everything else. - **The Session Brief.** Written memory across the gap between sessions. - **Knowledge capture.** Discoveries committed to git, read again next time. The numbered folders are just where those things live by default. Move them, rename them, split them, as long as the Router still points to them and the agent can still find them. ## How to adapt the rest A few moves that are not just allowed but encouraged: - **Add a folder.** Tracking velocity and estimation accuracy? Add a `07-metrics/` (worked example below). Running a research project? You might want an `08-experiments/`. - **Sub-divide.** A big product might split `01-planning/` into `product-requirements/`, `strategy/` and `roadmap/`. - **Drop what you don't use.** A solo project may never touch `06-agents/`. Delete it. An empty folder teaches nothing. - **Rename for your team.** If "release-notes" lands better as "changelog", rename it. The Router is the source of truth, not the folder name. ## The test Before you add or remove anything, ask one question: *will the agent find what it needs, faster, because of this change?* If yes, do it. If you're adding structure to feel organised rather than to load context, you're decorating, not building. ## Worked example: add a 07-metrics folder Most projects never need a seventh folder. But once you're a few months in and want to know whether your estimates are any good, or how throughput is trending, the data is sitting in your contextbase already, in the frontmatter of your briefs and PRDs. A `07-metrics/` folder is where you make it legible. ### When it's worth it Add `07-metrics/` when you have a real question you'd act on: - *Are my estimates calibrated?* You've been filling in `estimated_hours` / `actual_hours` on Prompt Briefs. - *Is throughput trending up?* You want a monthly count of briefs shipped. - *Where does time actually go?* You want it broken down by area. If you don't have a question, don't add the folder. Metrics nobody reads are just noise with a directory. If you're unsure what's even worth measuring, the [DORA metrics](https://dora.dev/) are the industry standard for delivery performance, but adopt only the ones tied to a question you'd act on. ### The shape ``` docs/07-metrics/ ├── velocity/ ← monthly throughput notes └── estimation.md ← calibration: estimated vs actual, by area ``` ### Wiring it in Two small moves and it's part of the method: 1. **Point the Router at it.** Add a line to `AGENTS.md` linking `07-metrics/` so the agent reads it when you ask for a calibration check. If you haven't written your Router yet, see [how to write AGENTS.md](/articles/how-to-write-agents-md). 2. **Make it a Learn-loop output.** When you run the periodic consolidation, have the agent read the completed Prompt Briefs, total the estimate-vs-actual, and update `estimation.md`. The data already exists in frontmatter. You're just summarising it. ## The same three steps, in any direction Nothing about the metrics example is special to metrics. The same three steps (decide there's a real question, give it a folder, point the Router at it) extend C² in any direction. The method grew this way in the first place. The structure serves the work. Not the other way round. See [the docs structure](/c2/docs) you're adapting, or [read the full method](/c2/method). --- # How to stop Claude Code losing context between sessions ## Every session starts with a fresh window and compaction rewrites the old one. What Claude Code keeps for you, and the routine that keeps the rest. - URL: https://stuartleo.com/articles/how-to-stop-claude-code-losing-context-between-sessions - Published: 2026-11-18 - Reading time: 9 min read - Method: C² Method Claude Code loses context when a session ends or compacts. What CLAUDE.md and auto memory keep, and the session-brief routine that carries the rest in git. You finish a good session in Claude Code. The agent found the bug, worked out why, and left a fix half-done. Tomorrow you open a new session and it knows none of it. Or worse, it happens mid-session: the context fills, the conversation compacts, and the decision you made an hour ago is now one line in a summary, or gone. This is the most searched frustration with Claude Code, and it isn't a bug. It's how the tool is built. Once you know exactly what Claude Code keeps and what it drops, the fix is a routine, not a product. ## Why does Claude Code lose context between sessions? There are two separate losses, and they need separate answers. **A session ends.** The [Claude Code memory docs](https://code.claude.com/docs/en/memory) say it plainly: each Claude Code session begins with a fresh context window. The conversation, the files it read, the reasoning it built up — none of it carries over by itself. **A session compacts.** Within a session, the window is finite. As you approach the limit, Claude Code compacts automatically, and running `/compact` does the same thing on demand. Per the [context window docs](https://code.claude.com/docs/en/context-window), compaction replaces the conversation with a structured summary. The summary keeps what the automatic pass judges important. Your judgement and its judgement are not always the same. So the work drains away twice. All at once when you close the session. In pieces whenever it compacts. ## What does Claude Code remember natively? More than it used to. Two mechanisms carry knowledge across sessions, and both are worth using. **CLAUDE.md.** Instructions you write. The project file at `./CLAUDE.md` is loaded in full at the start of every session, and after compaction the project-root CLAUDE.md is re-read from disk and re-injected. Claude Code can also read an `AGENTS.md` in its place. Anything in this file survives both kinds of loss. **Auto memory.** Notes Claude writes itself, on by default in local sessions. They live at `~/.claude/projects/<project>/memory/`, with a `MEMORY.md` index of one line per memory. The first 200 lines or 25KB of that index, whichever comes first, load at the start of every conversation, and auto memory is also re-injected after compaction. The docs also list what compaction does *not* re-inject. Instructions given only in conversation. Context that hooks added earlier, which gets summarised with everything else. Nested CLAUDE.md files and path-scoped rules, which reload only when Claude next touches a matching file. ## Why isn't CLAUDE.md and auto memory enough for a real project? Because neither one holds the state of the work. CLAUDE.md holds *rules* — how the project is built, what never to do. It is the wrong place for "the cancellation flow is half-built and the refund test fails". Put that in CLAUDE.md and the file becomes a diary that loads into every session forever. Auto memory holds *learnings and preferences*, written by Claude, and the docs are clear that it is machine-local. It isn't in git. Your collaborator can't read it. A second machine doesn't have it. And Claude decides what goes in it. What a project needs at the start of a session is different. What changed last time. Why. What was actually verified, and what wasn't. What to do next. That is a hand-off, and it has no native home. So I give it one, in git. ## The C² routine: four habits that stop the loss The [C² Method](/c2) is the build method I run every project with. The part that answers this problem is four habits. 1. **Read the latest session brief before you start.** Not the whole history. The last one or two. 2. **Write a session brief before you stop.** Also before a meeting, before `/clear`, and before a long session compacts. The trigger isn't "is the work finished?" It's "if I came back to this cold, what would I need to know?" 3. **Put decisions and gotchas in their own files.** A brief is dated and gets buried. A gotcha — a non-obvious trap — goes in `docs/03-knowledge/gotchas/` so it's found by topic, not by date. 4. **Let a hook point the agent at the briefs.** Don't rely on remembering to say "read the last brief". Make the session start with the list in front of it. All four are plain files, committed with the code. Nothing to install. In my own monorepo this has been running long enough to have weight. The 2026 folder at `docs/02-working/sessions/completed/2026/` holds over 1,100 brief files. `docs/03-knowledge/gotchas/` holds more than 210 gotchas. Two of the titles, to show the grain: *Two module names that differ only in case collide on a Mac*, and *A concurrent session can move the shared working tree out from under you*. Each one is a trap an agent would otherwise walk into cold, again. ## How do I make Claude Code read my session briefs automatically? With a `SessionStart` hook. Per the [hooks reference](https://code.claude.com/docs/en/hooks), a SessionStart hook runs when a session begins or resumes, with the source available as `startup`, `resume`, `clear` or `compact`, and Claude Code adds its plain-text stdout as context Claude can see before your first prompt. The context window docs add that SessionStart hooks matching the `compact` source run again after compaction and their output goes into the compacted context. Mine lives at `.claude/hooks/session-context.sh` and is registered in `.claude/settings.json`. Here is the registration, trimmed to the one hook: ```json { "hooks": { "SessionStart": [ { "hooks": [ { "type": "command", "command": ".claude/hooks/session-context.sh", "timeout": 10 } ] } ] } } ``` The real script is longer because my file names drifted over the years and it parses four date formats. Stripped to the idea, for briefs named `YYYY-MM-DD-topic.md`: ```bash #!/bin/bash # .claude/hooks/session-context.sh — list recent session briefs at session start PROJECT_DIR=$(cat | jq -r '.cwd // empty') BRIEFS="$PROJECT_DIR/docs/02-working/session-briefs" echo "=== Recent session briefs (last 30 days) ===" find "$BRIEFS" -maxdepth 1 -type f -name "*.md" -mtime -30 -exec basename {} \; \ | sort -r | head -15 echo "" echo "Briefs get parked. Ask which one to pick up, don't assume the latest." ``` Two details are deliberate. It lists, it doesn't dump. Fifteen file names cost almost nothing in context. Fifteen full briefs would fill the window the hook is meant to protect. The agent opens the one that matters. It says briefs get parked. The newest brief is not always the priority. Work pauses, another stream jumps ahead. My hook ends by telling the agent to ask, and that one line has saved more wrong starts than anything else in the script. The hook has also failed me, and the failure is worth knowing. The comment at the top of my script records it. The hook once matched only names ending `-session-brief.md`. When brief names dropped that suffix, the hook went blind, and every session booted showing an 18 August brief as the newest. Nothing errored. If you change how briefs are named, check the hook still sees them. ## What goes in a session brief? Keep it short enough that writing it is never the reason you skip it. This is the skeleton I'd copy, cut down from the template in the [C² starter kit](https://github.com/waymakerone/c2method): ```markdown # Session brief: [area], YYYY-MM-DD ## Goal One sentence. What this session set out to do. ## What changed - [file or feature]: [what was done] ## Decisions - [decision]: [why this, not the alternative] ## Verified - [what was tested, and how] - NOT verified: [what still needs checking] ## Key discovery [A gotcha worth keeping, or "None this session". If there is one, write docs/03-knowledge/gotchas/<name>.md in the same commit.] ## Next session starts here Start with: [file, task or command] First action: [one specific instruction] ``` The section that earns its keep is *NOT verified*. A brief that only lists successes tells the next session everything works. Say what you didn't check, and the next session doesn't build on it blind. Save it as `docs/02-working/session-briefs/YYYY-MM-DD-topic.md`, the location the C² starter uses, and commit it with the work. My monorepo predates that layout and files briefs under `docs/02-working/sessions/completed/` by year. The folder matters less than keeping one and pointing the hook at it. For a fuller walk-through with an annotated example, see [write your first session brief](/articles/write-your-first-session-brief) or the [session brief template](/c2/docs/session-brief). ## How do I keep compaction from losing context mid-session? The routine covers the gap between sessions. Within a session, three moves keep compaction from costing you. **Write before it compacts.** When a session is getting long, have Claude write the brief first. The brief is on disk. The summary is a guess. **Compact with a focus.** The context window docs suggest `/compact focus on the auth bug fix` before a long new task, so the summary keeps what you choose rather than what the automatic pass guesses. **Clear between unrelated tasks.** `/clear` is for switching to different work. Write the brief, clear, and let the SessionStart hook start the next task clean. Anything that must survive both — a rule, a constraint, a standing decision — belongs in the project-root CLAUDE.md or a file it points to. That file is the one thing the docs say compaction re-reads from disk. The longer argument about window hygiene is in [compaction: keeping the context window lean](/articles/compaction-keep-the-context-window-lean). ## The cost is five minutes a session None of this needs Claude Code to change. CLAUDE.md carries the rules. Auto memory carries Claude's own notes. A brief in git carries the state of the work, and a hook makes sure it gets read. Five minutes at the end. A list of file names at the start. That is the whole price, and it's paid back the first morning the agent opens a session already knowing where it stopped. The model doesn't remember the project. The repository does, if you write it down. Start here: [run your first C² session](/c2/start), read [how to stop your agent forgetting](/articles/how-to-stop-your-agent-forgetting), or see [what a contextbase is](/articles/what-is-a-contextbase). --- # Spec-driven development tools compared (2026) ## Spec Kit, Kiro, BMAD, Agent OS, Task Master, OpenSpec and C², checked against their own repos and docs. - URL: https://stuartleo.com/articles/spec-driven-development-tools-compared - Published: 2026-11-18 - Reading time: 12 min read - Method: C² Method Spec Kit, Kiro, BMAD, Agent OS, Task Master and OpenSpec compared from their own docs: artefacts, workflow, agents, licence and who each one is for. Spec-driven development exists because prompting code into existence stops working the moment a feature gets bigger than one chat. The agent guesses at the gaps. The guesses ship. A month later nobody, human or model, can say why the code does what it does. Every tool in this piece answers that with the same move — write down what you want, in files the agent can read, before it writes code. That is where the agreement ends. Some of these are spec workflows you install into the agent you already use. One is a commercial agent with specs built in. One is a full delivery method. One is a task manager. One is mostly about coding standards. I should say the awkward thing first. I built one of the seven — C², the method I run my own builds on. So I am biased, and you should read this with that in mind. I have tried to be fair the only way I know how. Every claim about another tool comes from its own repo or docs, checked on the date at the bottom, and where something isn't documented I've left it out rather than guessed. If you want depth on one pairing, I've written head-to-heads on [C² vs BMAD](/articles/c2-vs-bmad) and [C² vs spec-driven development as an idea](/articles/c2-vs-spec-driven-development), plus a wider map of [AI development methodologies](/articles/ai-development-methodologies-compared). This page is the current, tool-by-tool view. ## The comparison at a glance | Tool | Core idea | Main artefacts | Best for | Licence / cost | |---|---|---|---|---| | GitHub Spec Kit | Spec → plan → tasks → code, in any agent | constitution, spec.md, plan, tasks, checklists | One feature at a time, across 40+ agents | MIT, free | | Kiro (AWS) | An agent with specs built into the product | requirements.md or bugfix.md, design.md, tasks.md, steering files | Teams happy to work inside one commercial tool | Commercial, free tier then paid plans | | BMAD Method | A full agile method run through named agent roles | briefs, PRD, architecture, initiative → epic → story tickets | Larger work that needs product, design and architecture thinking | MIT, free | | Agent OS | Capture your coding standards, inject them into plans | standards + index.yml, mission, roadmap, spec folders | Keeping agents on your conventions | MIT, free | | Task Master | Parse a PRD into dependency-ordered tasks | prd.txt, tasks.json | Breaking a big PRD into a queue the agent works through | MIT + Commons Clause, free to use | | OpenSpec | A lightweight change folder per feature, merged into living specs | proposal.md, specs/ deltas, design.md, tasks.md | Brownfield repos and iterating without phase gates | MIT, free | | C² | Context that compounds across the whole repo | router file, docs/ contextbase, PRD → prompt brief cascade, session briefs, gotchas | Long-running projects where what you learn should carry forward | CC BY-NC-SA 4.0, free | ## GitHub Spec Kit: the reference SDD toolkit [Spec Kit](https://github.com/github/spec-kit) is GitHub's open-source toolkit, and the most widely starred project here at about 150,000 stars. It installs with the `specify` CLI (Python 3.11+ and uv) and then runs as commands inside your agent. The [integrations list](https://github.github.io/spec-kit/integrations/index.html) names more than 40 agents, including Claude Code, Codex CLI, Cursor, GitHub Copilot, Gemini CLI and Kiro CLI, plus a generic option. The [core flow](https://github.github.io/spec-kit/reference/agentic-sdd.html) is constitution → specify → plan → tasks → implement → converge. The constitution holds project principles and is written once. The rest repeats per feature. Clarify, checklist and analyze are optional quality gates for work with real ambiguity, and converge checks the code against the artefacts until it reports `Converged`. Newer releases add bug-fix and idea-assessment processes as extensions, plus presets, workflows and catalogs for teams that want to bend the process. It is mature and moving fast. Version 1.4.1 shipped on [16 November 2026](https://github.com/github/spec-kit/releases), and it's [MIT licensed](https://github.com/github/spec-kit/blob/main/LICENSE). If you want the canonical shape of spec-driven development without changing agents, this is it. ## Kiro: specs inside a commercial agent from AWS [Kiro](https://kiro.dev) is different in kind. It is an agent product, built and run by AWS, available as an IDE, a CLI, a web app and a mobile app. Specs are a feature of that product rather than something you install. A [Kiro spec](https://kiro.dev/docs/specs/) is three files. requirements.md holds user stories and acceptance criteria written in EARS notation (or bugfix.md for a bug), design.md holds architecture and sequence diagrams, and tasks.md holds the implementation plan. [Feature specs](https://kiro.dev/docs/specs/feature-specs/) can run requirements-first or design-first. When you run all tasks, Kiro builds a dependency graph from tasks.md and runs independent tasks in parallel waves. Project-level context lives in [steering files](https://kiro.dev/docs/steering/) under `.kiro/steering/`, and Kiro also reads AGENTS.md. [Pricing](https://kiro.dev/pricing/) starts with a free tier of 50 credits a month, then paid plans from $20 per user per month. The pricing page lists both Anthropic and OpenAI models alongside its default Auto routing. The [changelog](https://kiro.dev/changelog/) shows releases as recent as 16 November 2026. Kiro vs Spec Kit comes down to one question. Do you want specs inside an integrated product, or a spec workflow that travels across the agents you already pay for? ## BMAD Method: a full agile method with agent roles [BMAD](https://github.com/bmad-code-org/BMAD-METHOD) is the most complete method here, and it has changed a lot. About 55,000 stars, MIT licensed, and free with no paywalled workflows, according to its README. The stable line is v6.12 (v6.12.4, [14 October 2026](https://github.com/bmad-code-org/BMAD-METHOD/releases)). V7 is a preview alpha that installs as agent skills, and the README gives its release target as mid-November 2026. [How BMad works](https://docs.bmad-method.org/start/how-bmad-works/) is four stages: clarify, plan, build and verify, learn and adjust. You enter where your input is. A small change goes straight to build. Each stage has named agents — Mary the analyst, John the PM, Sofia the product owner, Sally on UX, Winston the architect, and a developer agent (Amelia in the released source, Mason in the current docs). Tracked work sits in a ticket tree of initiative → epic → story, and the docs are explicit that the ticket is the spec. BMAD also takes project context seriously now. Its [project-context skill](https://docs.bmad-method.org/existing-codebases/set-and-maintain-project-context/) writes and maintains a verified block in AGENTS.md. V7 needs an agent that supports skills, plus Node and uv. Spec Kit vs BMAD is mostly a question of scope. Spec Kit carries one feature from spec to code. BMAD runs the whole delivery around it, roles and retrospectives included. ## Agent OS: standards first, specs second [Agent OS](https://github.com/buildermethods/agent-os), by Brian Casel at Builder Methods, made a deliberate retreat in [v3.0 on 20 January 2026](https://github.com/buildermethods/agent-os/blob/main/CHANGELOG.md). The changelog says plan modes and frontier models now handle spec writing, task breakdown and orchestration well, so v3 hands those back to the agent. What it keeps is standards. The commands are discover-standards, inject-standards, index-standards, plan-product and shape-spec. Standards live as markdown under `agent-os/standards/` with an `index.yml` so the right ones get pulled in. Plan-product writes mission.md, roadmap.md and tech-stack.md. Shape-spec improves your agent's plan mode with targeted questions and saves a spec folder holding plan.md, shape.md, standards.md and references.md. It works alongside Claude Code, Cursor, Antigravity and other tools, and it's MIT licensed with about 5,600 stars. Support comes through a paid Builder Methods Pro community. BMAD vs Agent OS is not close in shape. BMAD is a full method with roles. Agent OS is a thin layer that makes sure whatever plan your agent writes follows your conventions. ## Task Master: a PRD parsed into a task queue [Task Master](https://github.com/eyaltoledano/claude-task-master) does one thing and does it well. You write a PRD (`.taskmaster/docs/prd.txt`), it parses that into tasks with dependencies, and the agent asks for the next task, expands it into subtasks and marks it done. It runs as an MCP server or a CLI, and its docs list [13+ supported editors](https://tryhamster.com/docs/taskmaster/ide-setup/supported-editors) including Cursor, Claude Code, Windsurf, VS Code, Roo, Cline, Codex, Gemini CLI and Kiro. Two details matter before you adopt it. First, it calls models itself, so you need at least one provider API key, unless you route through Claude Code or Codex CLI. Second, the licence is MIT with the Commons Clause. You can use it commercially and sell what you build with it, but per the README you can't sell Task Master itself, host it as a service or build a competing product from it. It has about 28,000 stars. The latest release is 0.43.1 from [31 March 2026](https://github.com/eyaltoledano/claude-task-master/releases), and its docs now live on Hamster's site. On the evidence I can see, the open-source repo has slowed this year. Task Master vs BMAD is a category mismatch. Task Master manages the queue after the PRD exists. BMAD helps you work out what the PRD should say. ## OpenSpec: lightweight change folders for brownfield work [OpenSpec](https://github.com/Fission-AI/OpenSpec), from Fission AI, is the lightest spec workflow here and the second most starred at about 75,000. Its stated philosophy is fluid not rigid, iterative not waterfall, and built for brownfield as well as greenfield. Each change gets a folder under `openspec/changes/`, with proposal.md, a specs/ folder of requirement deltas, design.md and tasks.md. The deltas are plain markdown — ADDED requirements in SHALL form, with WHEN/THEN scenarios. Explore, propose, apply, then archive, and archiving merges the change into the living specs in `openspec/specs/`. That merge is the useful idea. The spec describes the system as it is now, not a pile of past feature requests. It supports 30+ tools through skills, ships a beta "stores" feature for specs shared across repos, and is MIT licensed. Version 2.1.0 shipped on [17 November 2026](https://github.com/Fission-AI/OpenSpec/releases). It also collects anonymous usage telemetry by default, which the README documents along with how to switch it off. ## C²: context that compounds, not a spec tool [C²](https://github.com/waymakerone/c2method) is mine, so take this section with the bias I named at the top. It is not a spec tool and I won't pretend it competes on that ground. It's a method for the context around a whole repo, and it's young: the public kit is new, even though the method behind it is two years and more than 1,000 agent sessions old. A C² repo has a router file at the root (AGENTS.md by default, or CLAUDE.md or GEMINI.md) that routes to docs rather than duplicating them. Under it sits a `docs/` contextbase — planning, working, knowledge, operations. Work flows down a cascade of PRD → feature PRD → prompt brief → task → session brief. Every session ends in a session brief, and every non-obvious trap becomes a gotcha so nobody hits it cold twice. There's no CLI to install. You copy a starter folder of markdown templates into the repo. The current version is v1.4.3, released [25 September 2026](https://github.com/waymakerone/c2method/blob/main/CHANGELOG.md), with an experimental fleet kit for running one agent per PRD. It's free under CC BY-NC-SA 4.0. ## How to choose Start with the job you actually have. - **You want one feature specced, planned and built, in the agent you already use.** Spec Kit. It's the reference implementation and supports the widest range of agents. - **You work in a large existing codebase and want the spec to describe the system as it is now.** OpenSpec. The change-folder-then-archive loop is built for brownfield work. - **You want an integrated product and will commit to one vendor.** Kiro. Specs, steering, parallel task runs and hooks in one place, on a paid plan. - **You want a whole delivery method, with product, UX and architecture thinking before the build.** BMAD. Expect more process than the others, sized to the work. - **Your problem is agents ignoring your conventions, not missing specs.** Agent OS. - **You already have a good PRD and want it turned into an ordered queue.** Task Master, once you've read the licence. - **Your problem is that every session starts cold.** That's a context problem, not a spec problem. It's the one C² was built for. For "best spec-driven development framework", my honest answer is Spec Kit for most people starting today. It is free, portable, actively released and closest to the idea itself. OpenSpec is the lighter alternative if Spec Kit's gates feel heavy. ## Where C² fits The line between these tools has blurred. Spec Kit has a constitution, Kiro has steering files, Agent OS has standards and BMAD now maintains a block in AGENTS.md. Every serious tool has worked out that a spec without project context drifts. The difference I care about is scope and time. A spec is about one feature, and it's done when the feature ships. The contextbase is about the whole repo, and it is never done. The decision behind feature one, the trap you hit in week three, what changed in yesterday's session — those belong to the repo, not to any single spec, and they're what make feature twelve start ahead of feature one. I wrote more on that in [what a contextbase is](/articles/what-is-a-contextbase). So they compose. Run Spec Kit or OpenSpec for the feature — their spec folders sit happily inside a C² `docs/` tree, and a prompt brief can simply point at one. Let the router send the agent to the right spec. Let the session brief and the gotchas carry what you learned into the next feature. The spec tool makes this feature right. C² makes sure the repo remembers it. --- *Last checked: 18 November 2026.* These tools release weekly, sometimes daily. If something here is out of date or wrong, tell me and I'll correct it. Accuracy is the only reason a comparison like this is worth reading. Go deeper with [C² vs BMAD](/articles/c2-vs-bmad), [C² vs spec-driven development](/articles/c2-vs-spec-driven-development), or [write acceptance criteria your agent can check](/articles/acceptance-criteria-for-agents). Or [read the method](/c2/method). --- # What is context leadership? Leading people and agents ## Leadership used to be direction. Now it's context. Briefing an agent and briefing a person turn out to be the same discipline. - URL: https://stuartleo.com/articles/what-is-context-leadership - Published: 2026-11-18 - Reading time: 9 min read - Method: Essay Context leadership is writing down the plan, decisions and standards so people and AI agents can act without you. What it is, and the two methods that run it. {/* DRAFT for Stuart's review: umbrella definition, written overnight 2026-11-18 */} Leadership used to be direction. Now it's context. For most of the last century, the leader was the person who knew where things were going and said so. Direction flowed down. The organisation waited for the next instruction, acted on it, and came back with questions. That model still works for as long as the leader is in the room — and it fails quietly the moment they aren't. Two things now act on the business without the leader in the room. People always did. AI agents are the new ones, and they are much less forgiving. Both act on what they can see. So the work of leading has moved from what you say to what you've written down. ## A working definition **Context leadership is the practice of writing down what people and agents need to act well — the plan, the decisions, the standards and the lessons already paid for — keeping it in one place, and improving it every time it's used.** Three parts carry the weight. - **Written down.** Not said in a meeting. Not carried in your head. Written, so it can be read by someone who wasn't there. - **In one place.** A plan in five documents is five plans. The reader, human or agent, needs to know where to look first. - **Improved every time it's used.** Context isn't a document you finish. It's an asset that compounds, and it only compounds if every use leaves it a little better than it was. The leader's job shifts from issuing direction to building the written context that people and agents can act on without them. ## Why direction stopped scaling Direction is a skill. Context is a system. I draw that line from the third of the [three tensions](/articles/the-three-tensions) in Resolute: **a skill is what one person can do, and a system is what survives that person leaving.** A leader who directs well has a real and valuable skill. It lives in their head. Every decision routes through them, and the organisation can only move as fast as they can answer. [The twelve questions](/articles/the-twelve-questions) name the same failure from another angle. The leader who reaches for the answer first ends up running an organisation that depends on them for everything. The leader who reaches for the question first builds an organisation that thinks. That was true before AI. Agents make it urgent, for a simple reason. An agent doesn't absorb direction over years. It starts every session from zero. Whatever it needs to act well has to be written down, or it doesn't exist. ## Briefing an agent and briefing a person are the same discipline Here is the thesis this whole site rests on. When I brief an AI coding agent, I write down what to build, what not to build, and how I'll know it worked. I point it at the decisions already made, so it doesn't relitigate them. I record the traps already hit, so it doesn't walk into them again. In the [Pilot model](/articles/the-pilot-model-directing-ai-agents) that's the first habit: brief before build. Now look at what a good leader gives a new hire on their first week. The same things. The goal, the boundaries, what good looks like, the decisions behind the current plan, the mistakes nobody needs to make twice. The form is different. The discipline is identical. The idea is old. The Twelve Questions are inspired by the British Army's [Mission Command](https://en.wikipedia.org/wiki/Mission_command), where every officer trained in the same questions, the same intent-setting and the same decision rights. The result was autonomous decision-making at every level, aligned to a unified purpose. Clear intent, written so it can be acted on without the commander present. That's context leadership, a long time before anyone called it that. What's new is the agent. A person can paper over a thin brief. They ask a colleague, they remember last quarter, they read the room. An agent can do none of that. It can't read your head. It can only read what's written down. So the agent is the most honest test of your context you will ever get. Where the agent drifts, a new hire was drifting too — they were just better at hiding it. **Fix the brief for the agent, and it gets better for the person. It's the same brief.** ## What changes in the leader's job The shift is uncomfortable because it asks you to value work that was never rewarded. Producing the answer felt like leading. Writing down the context so the answer isn't needed from you feels like admin. It isn't. It's the higher-leverage work. | Direction (the old job) | Context (the new job) | |---|---| | Answering the same question again | Writing the answer where the next person reads it first | | Holding the decision and the reason in your head | Recording the decision, and why, so nobody relitigates it cold | | Telling each person what to do next | Writing the brief: what to build, what not to, how you'll know it worked | | Fixing the mistake | Writing down the trap, so the next person avoids it | | Reviewing everything personally | Setting the standard in writing, then holding it | The measure changes with it. A director measures the day in instructions given. A context leader measures it in how far people and agents got without needing them. I've built this discipline twice, for two different things a leader can be responsible for. ## Resolute: context for a company [Resolute](https://www.amazon.com.au/Resolute-navigate-disruption-indestructible-organizations/dp/0645825425) is the method for the company. It gives a leadership team a shared, written picture of where the business is and where it's going. **The Leadership Curve says where you are.** Six stages — Idea, Identity, Calibrate, Maturity, Mastery, Initiate — each demanding a different posture, skill and system from the same underlying character. It's a sensemaking framework. Before anyone can act well, they need to know which stage the business is actually in, because the right move in Identity is the wrong one in Mastery. **The 12 Questions say what has to be written down.** Five questions of management for executing the present: plan, roles, goals, meetings, data. Seven questions of leadership for the future: vision, market, strategy, business model, customer experience, employee experience, and the one, two or three things that would shift the needle this quarter. Answered and written, those twelve are the company's context. Unanswered, everyone in the building is guessing at them. **Canvases and Clarity Statements turn the thinking into something people can act on.** A [canvas opens a hard question](/articles/canvases-and-clarity-statements) with divergent thinking. A Clarity Statement closes it with a short, structured sentence a new hire could repeat. That sentence is the unit of context. An agent can read it as easily as a person can. And the questions get asked on a rhythm. The Seven half-yearly, the Five monthly or quarterly. Context that isn't revisited goes stale, and stale context is worse than none, because people trust it. ## C²: context for a codebase The [C² Method](/c2) is the same discipline applied to a codebase and the agents that build in it. **The router says where things are.** One file the agent reads first — `CLAUDE.md` or `AGENTS.md` on disk. It's an index, not an encyclopedia. It routes the agent to whatever the task needs. **The [contextbase](/articles/what-is-a-contextbase) holds what was decided and learned.** A `docs/` folder of plain markdown in git, next to the code. Briefs say what to build and what not to. Decisions record why. Gotchas record the trap once, so it never gets rediscovered cold. **A session brief closes every session.** A few lines: what changed, why, what's verified, what's next. That's the written memory the next session reads, whether the next session is an agent or a person. 22 minutes into a live C² session, after the harness had already compacted the conversation, I asked the agent one question: how's your context? Its answer, verbatim: *"everything load-bearing is externalized (PBs, briefs, PR bodies, memory), so even when the harness compacts the conversation, nothing about the program state lives only in my head."* That is context leadership working at the scale of one agent. When the load-bearing context lives in git and not in the chat window, the agent survives its own forgetting. ## One discipline, two methods The two methods look different on the surface because a company and a codebase are different things. Underneath, they do the same job: keep the context in one place so it compounds. | The job | Resolute, for a company | C², for a codebase | |---|---|---| | Say where things stand | The Leadership Curve | The router | | Decide what to build, and what not to | Canvases and Clarity Statements | Briefs | | Keep what was learned | The 12 Questions, asked on a rhythm | Session briefs and gotchas | | The reader | People, and the agents working with them | Agents, and the people directing them | Most leaders will need both. The company's plan is context for the agents in the codebase, and the codebase's decisions are context for the leadership team. ## Where to start Pick the thing you lead. If it's a company, find where the business sits on the Curve, then write one Clarity Statement the leadership team could repeat without looking it up. If it's a codebase, add a router file and write a five-line session brief at the end of your next session. Then run the only test that matters. Hand what you wrote to someone who wasn't in the room — a new hire, or a fresh agent — and watch what they do with it. Every question they have to ask you is a gap in the context. Write the answer down where the next one will read it. That is the whole practice. Direction gets spent the moment it's given. Context gets better every time it's used. Start here: [the map of both methods](/map), [Resolute, for the company](/resolute), or [C², for the codebase](/c2). --- # Why Claude Code ignores your CLAUDE.md, and how to fix it ## CLAUDE.md is context, not configuration. Why rules get dropped as the file grows, and the router pattern that keeps the ones that matter. - URL: https://stuartleo.com/articles/why-claude-code-ignores-your-claude-md - Published: 2026-11-18 - Reading time: 9 min read - Method: C² Method Claude Code ignores CLAUDE.md rules when the file is too long, the rule is buried, or it needed a hook. Why it happens, and the router pattern that fixes it. You wrote the rule. It's right there in CLAUDE.md, in bold. Claude Code walked straight past it anyway. Most advice at this point is to shout louder — capitals, IMPORTANT, a second copy of the rule further down. That makes the problem worse. The file is not being ignored at random. It is being read the way it was built to be read, and the fix is to build it differently. ## Why does Claude Code ignore CLAUDE.md? Start with what the file actually is. The [Claude Code memory docs](https://code.claude.com/docs/en/memory) put it in one line: Claude treats CLAUDE.md and auto memory *as context, not enforced configuration*. The troubleshooting section is more specific. CLAUDE.md content is delivered as a user message after the system prompt, not as part of the system prompt itself. Claude reads it and tries to follow it, but there is no guarantee of strict compliance, especially for vague or conflicting instructions. That one fact explains most of the failures. A rule in CLAUDE.md is a strong suggestion sitting in the context window beside everything else Claude has read. It competes with your prompt, with the files it opened, with the task in front of it. When it loses, it's for one of three reasons. ## Is your CLAUDE.md too long? This is the most common one. The docs give a number: target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence. Every rule you add dilutes the rest. A 40-line file with eight rules gives each one weight. An 800-line file with 120 rules turns each one into a line in a wall, and the one you care about this session is somewhere in the middle. Splitting the file with `@path` imports doesn't fix it. The docs are explicit that imports help organise a long file but don't reduce its context cost, because imported files load together with the CLAUDE.md that imports them. Shorter means fewer lines *loaded*, not fewer lines in one file. My own monorepo is the honest example. On 2026-10-11 the root CLAUDE.md was 844 lines. I trimmed it to 404 by moving reference detail out, verbatim, into five separate pages. That halved it. It is still twice the docs' target, and I won't pretend otherwise. A router is a direction to keep moving in, not a finish line. I wrote up the earlier version of this in [the CLAUDE.md that got too big](/articles/the-claude-md-that-got-too-big). ## Are your rules buried in prose? The second reason. A rule written as the fourth sentence of a paragraph about architecture is a rule Claude has to extract before it can follow it. The docs recommend grouping instructions under headings and bullets, and making them specific: "Use 2-space indentation" works better than "format code nicely". Two checks catch most of this. **Is the rule concrete enough to verify?** "Keep files organised" can't be checked. "API handlers live in `src/api/handlers/`" can. **Does any other file say the opposite?** If two instructions contradict each other, the docs say Claude may pick one arbitrarily. This includes your user-level `~/.claude/CLAUDE.md`, nested CLAUDE.md files in subdirectories, and `.claude/rules/`. A rule you wrote in one place and reversed in another is a coin toss. ## Which rules need a hook instead of a sentence? The third reason, and the one no amount of rewriting fixes. Some rules aren't preferences. They are things that must never happen — editing `.env`, pushing to `main`, weakening a type-check config to make an error go away. Writing those in CLAUDE.md is asking nicely. The docs say what to do instead. If an instruction must run at a specific point, write it as a [hook](https://code.claude.com/docs/en/hooks). Hooks execute as shell commands at fixed lifecycle events and apply regardless of what Claude decides. A `PreToolUse` hook that exits with code 2 blocks the tool call, and its stderr becomes the reason Claude sees. My repo has both kinds, and the difference is instructive. `.claude/hooks/pb-gate.sh` runs after every Write or Edit on a file under `docs/02-working/prompts/active/` and prints a checklist reminder. That one is wired up in `.claude/settings.json`. `.claude/hooks/protect-config.sh` would block edits to `tsconfig.json`, `biome.json`, `vite.config.ts` and any `.env` file with an exit code 2. That one exists but is **not enabled**, and my CLAUDE.md says so in plain words: *config edits are NOT blocked mechanically. The rule still stands*. That sentence is the lesson. A CLAUDE.md that implies a rule is enforced when it isn't is worse than one that admits the rule is only guidance. The agent and the human both need to know which rules have teeth. ## How do I turn CLAUDE.md into a router? The router pattern answers all three problems at once. CLAUDE.md stops being the place where knowledge lives and becomes the place that says where knowledge lives. It routes. It doesn't explain. Here is the shape of a typical file before: ```markdown # Project ## About [three paragraphs of history and architecture] ## Tech stack [40 lines of versions and libraries] ## Deployment [the full runbook, 80 lines] ## Rules - Never commit .env - Don't push to main [...60 more rules, mixed with tips...] ## Database [schema notes, example queries, 120 lines] ``` And after: ```markdown # Project — router > This file is a router. Rules needed every turn live here. > Reference detail lives in docs/. Open the page a pointer names > before working in that area. ## Invariants — verify before any auth, data or migration change 1. [The rule that must never break, in one line] 2. [The next one] ## Where things are - Architecture: docs/03-knowledge/architecture/overview.md - Deployment: docs/04-operations/deployment/checklist.md - Gotchas — read before touching an area: docs/03-knowledge/gotchas/ ## Session start 1. Read the latest session brief in docs/02-working/session-briefs/ 2. Read the gotchas for the area you're working in ## Enforced by hooks (see .claude/settings.json) - [rule]: blocked by .claude/hooks/[name].sh - [rule]: guidance only, NOT enforced ## Moved sections | Heading (verbatim) | File | |---|---| | Tech stack; versions | docs/05-reference/tech-stack.md | | Database schema; example queries | docs/03-knowledge/architecture/database.md | ``` Three parts of that skeleton come straight from my own root CLAUDE.md. **The router line.** Near the top of mine, in bold: *This file is a router.* The sentences after it say that rules an agent needs every turn live in the file, that reference detail lives in the pages listed under Moved sections, and that the agent should open the page a pointer names before working in that area. It tells the agent how to read the rest. **Invariants first.** My first real section is a short numbered block of security invariants, headed *MUST verify before ANY auth / RLS / edge-function / migration change*. Position matters because the top of the file is the part nobody skims past. The rules that would cost the most if dropped go there, and only those. **The Moved sections table.** At the bottom of mine is a table mapping each moved heading, word for word, to the page it now lives in. The headings are kept verbatim so a search for an old heading still lands on the table and then on the page. Nothing was deleted — the line in my file says so. An agent that needs the infrastructure topology, the email vendor rules or the tier table follows one pointer and reads one page. The other four pages stay out of its context. The full walk-through of each section is in [how to write an AGENTS.md, with a worked example](/articles/how-to-write-agents-md), and the C² template is at [/c2/docs/the-router](/c2/docs/the-router). ## Should I use AGENTS.md or CLAUDE.md? Either works with Claude Code now, which is new enough to check your version. Per the docs, Claude Code reads `AGENTS.md` as project instructions when there is no `CLAUDE.md` or `CLAUDE.local.md` in your working directory or above it. Reading it directly needs Claude Code v2.1.277 or later. If both files exist, it reads CLAUDE.md only. To keep one shared file, put `@AGENTS.md` at the top of a CLAUDE.md and add any Claude-specific lines below it. The [C² starter kit](https://github.com/waymakerone/c2method) ships its router as `AGENTS.md` by default — the cross-agent name that Codex, Cursor and most others read — and tells you to use `CLAUDE.md` for Claude Code or `GEMINI.md` for Gemini if that's your agent. The name changes nothing about the pattern. Router, invariants, pointers, moved sections. More on writing one in [how to write an AGENTS.md agents actually follow](/articles/how-to-write-agents-md), and on where a single rules file stops scaling in [C² vs native rule files](/articles/c2-vs-native-rule-files). ## How do I check what Claude Code actually loaded? Before rewriting anything, confirm the file is being read at all. The docs list three tools. - `/context all` shows the CLAUDE.md files loaded at launch under **Memory files**. If yours isn't there, Claude can't see it. - `/memory` lists every instruction file location and opens them for editing. - `/doctor prompt-audit` asks Claude to look for outdated instructions, references to files that don't exist, and files that contradict each other, and proposes edits without applying them. One more behaviour worth knowing. After `/compact`, the project-root CLAUDE.md is re-read from disk. Nested CLAUDE.md files and path-scoped rules only come back when Claude next touches a matching file. A rule that must survive compaction belongs in the root file. ## The file gets read. Make it worth reading CLAUDE.md isn't ignored because Claude is careless. It's read as context, weighed against everything else in the window, and followed in proportion to how clear and how prominent each rule is. So keep it short. Put the few rules that must never break at the top. Move everything else to pages it points at. And take anything that truly must never happen out of the file and into a hook. A router doesn't ask the agent to remember more. It asks it to remember where to look. Start here: [run your first C² session](/c2/start), or read [how to write the router file](/articles/how-to-write-agents-md). --- # Canvases and Clarity Statements: wide, then narrow ## Two tools for every hard question. - URL: https://stuartleo.com/articles/canvases-and-clarity-statements - Published: 2026-11-07 - Reading time: 9 min read - Method: Resolute A Resolute canvas opens a hard question with divergent thinking; a Clarity Statement closes it with convergent thinking. How the pair works, and how to run it. A canvas is a one-page worksheet you use to open up a hard question; a Clarity Statement is the short, structured sentence you use to close it again. That is the whole toolset. Two tools, two modes of thinking, one order. Every one of the twelve questions at the heart of Resolute (seven of leadership, five of management) gets worked the same way: wide first, then narrow. Then again next season. Most leadership teams I meet do one half well and skip the other. Some run brilliant workshops that never land on a sentence. Others write the sentence in the first ten minutes and spend the next two years defending it. Both feel like progress. Neither is. ## Two tools, two modes **The canvas opens the field.** It is a worksheet: a single page of prompts, columns and space. You and your team fill it in. You disagree out loud. You rub out a box and start it again. You leave a square empty and come back to it after lunch. The mode is divergent thinking, the generative kind most people call brainstorming, and its only job is to widen the set of possibilities before any one of them gets picked. **"The canvas is permission to not know yet."** (*Resolute*, 2nd edition, chapter 11) **The Clarity Statement closes the field.** It is a short sentence, or a template a paragraph long, that forces everything the canvas produced into one shape. The mode is convergent thinking: logical, selective, ruthless about what does not earn its place. What comes out is something you could put on a wall and a new hire could repeat. You need both, and the reason is simple. Run only the canvas and you get a good afternoon and no decision. Run only the statement and you get a sentence with nothing under it, a slogan nobody can defend when the first hard trade-off arrives. Here is the compression I use. **The canvas creates choices. The statement makes them.** None of this is a Resolute invention, and I'd be wary of anyone who told you it was. The psychologist J. P. Guilford pushed creativity onto psychology's agenda in his 1950 address [*Creativity*](https://doi.org/10.1037/h0063487) and went on to separate divergent from convergent production. Designers know the same rhythm as the Design Council's [Double Diamond](https://www.designcouncil.org.uk/our-resources/the-double-diamond/), which opens out to explore a problem before narrowing to define it, then does the same again for the solution. What Resolute adds is the pairing: a specific canvas and a specific statement for each question a business has to answer. So which half does your leadership team skip? ## Mustering: the picture that holds it together The clearest picture I know of how the two modes work together is mustering cattle. A mob is spread over thousands of acres of scrub. You don't find them by thinking hard at the homestead. A helicopter goes up and fans out across the property, and from the air you see everything: the gullies, the ridges, the dam where half of them have been hiding. Nobody is choosing yet. The job is to find the whole herd. That is the canvas. Every idea, every objection, every awkward fact is out on the hill somewhere, and the muster's job is to bring all of it in. Then the mob comes down into the yards and the work changes completely. Now it's one animal at a time, close attention, each one checked, recorded and given what it needs to get stronger. The wide search turns into a narrow act of care. That is the Clarity Statement. You take what the muster brought in and you work it until it is solid enough to build on. And then, crucially, you do it again next season. The first pass on any question is rough. The second is sharper. By the third you start to know which ideas are your breeders and which are strays. Clarity deepens with each pass, and the team's alignment deepens with it. Notice the trap the picture warns you about. A team can look busy every quarter while yarding the same three ideas it has always yarded, without ever going back up in the helicopter. When did you last go wide on a question you thought you'd already answered? ## Divergent does not mean polite One correction worth making, because a lot of facilitation advice gets this backwards. The common rule says no evaluation, no debate, no judgement during the divergent phase, just "yes, and" until the wall is full of sticky notes. That is not how the canvas works. The canvas is where you argue. Divergence is about not *closing* too early, not about not *thinking* too hard. A good canvas session is noisy, because people who know the customer are disagreeing about what the problem is. What you don't do is pick the answer yet. The discipline sits in the order, not in a gag order. Argue on the canvas. Decide in the statement. ## A worked pair: the Market Canvas The vision pair is the one most people meet first, and I've written it up separately in [writing a vision statement a team can actually use](/articles/writing-a-vision-statement). So let me show you the second leadership question instead: Market & Customer. The [Resolute Market Canvas](/resolute/library/market) has four boxes, worked in order: - **Market.** What market are you actually playing in, and is there a segment or niche where you've found fit? - **Ideal customer.** Who is the customer you are built for? Could you describe them as a person, and name real customers who look like them? - **Value drivers.** What creates value for that customer when they buy from you? Across design, experience, social and economic value, and in concrete terms. "Premium design" is a mood. A specific material, finish or guarantee is a value driver. - **Perceptions to build as advantages.** What does the market need to believe about you: before customers buy, after they buy, compared with your competitors, and inside your own team? One rule sits over the lot. The perceptions have to be true. That is the muster. It should produce more than you can use. Then you yard it. The Market Clarity Statement is two lines. The first names who you serve and what they value. The second names what you have to deliver on, from the perceptions box, to close the gap and lead your market. Fill in the template, then use your own licence to shorten it until it sounds like you. The template is scaffolding; the sentence is the product. The same chapter pairs this with the [Resolute Ideal Customer Canvas](/resolute/library/ideal-customer) and its own Clarity Statement, because one question sometimes needs two passes at different depths. ## One loop, many canvases Every one of the twelve questions gets this treatment, and some need more than one canvas. A few you'll meet early: - **Management:** the [Resolute Plan Canvas](/resolute/library/plan-canvas), [Role Canvas](/resolute/library/role-canvas), [Goal Canvas](/resolute/library/goal-canvas), [Meeting Canvas](/resolute/library/meeting-canvas) and [Data Canvas](/resolute/library/data-canvas), one for each of the five questions of management. - **Leadership:** the [Resolute Vision Canvas](/resolute/library/vision) and [Strategy Canvas](/resolute/library/strategy), each with its Clarity Statement; the [CX Journey Canvas](/resolute/library/cx-journey) and [CX Promise Canvas](/resolute/library/cx-promise) for customer experience; a set of employee experience tools for the sixth question. Business model is the honest exception worth naming. Resolute doesn't reinvent a canvas that already works. It points you to Osterwalder and Pigneur's [Business Model Canvas](/resolute/library/business-model-canvas) and Maurya's [Lean Canvas](/resolute/library/lean-canvas) for the divergent work, and supplies its own [Business Model Clarity Statement](/resolute/library/business-model-clarity-statement) for the convergent half. ## Which question first, and how often Ask yourself one thing before you pick a canvas: are you innovating or executing? If you're already trading, with a plan and a list of things to get done, start with the five questions of management. Disciplined execution is the least glamorous change and the one that pays first. Then move to the seven of leadership. On rhythm, a pattern that works for many businesses: revisit the seven questions of leadership half-yearly, and align on the five of management monthly or quarterly. Early in the life of a business you'll cycle both much faster. Some of my own early answers were a single line that changed week to week with the market. Once you find fit, they settle. That rhythm is what the book means by strategic agility: the ability to respond to a shifting market without betting everything on one season's answer. Long-term goals held loosely. Short-term goals held tightly, over a window of twelve to twenty-four weeks. It also maps onto the Resolute Leadership Curve, the six stages every business climbs: Idea, Identity, Calibrate, Maturity, Mastery, Initiate. Climbing it takes clarity about the "what" of each part of the business and maturity in the "how". Resolute's line for it is *lead with clarity, manage with maturity*. You need both to climb. I know my own tilt here. I'm the visionary in my leadership pair, and visionaries love the muster. We'd stay up in the helicopter all week. The statement is where I get pulled back to earth, and I'm better for it. Which way do you tilt? ## What the canvases won't do Be clear about the scope. A canvas will not make the decision for you; it only makes sure you've seen the field before you make it. A Clarity Statement will not execute itself; it tells a team where to point, not how to get the work done. That is the job of the plan, the roles, the goals, the meetings and the data. And neither tool replaces knowing your customer. If the people around the canvas have never sat with a customer, the muster brings in opinions, not cattle. Get the right four or five people in the room or the loop runs on air. --- So here's the question to take away. **Which of the twelve questions is your team still answering with a slogan, and when will you take it back to the canvas?** If you're not sure where to start, the free [Resolute business diagnostic](/resolute/assessment) reads your business across all twelve questions, tells you which stage of the Leadership Curve you're on, and names the one thing to build next. The [framework](/resolute/framework) lays out the questions and the stages in full. The [Resolute canon](/books) walks the canvases and Clarity Statements question by question. And if you'd rather run the loop with your team live, [WaymakerOS](https://waymakeros.com), the platform you run the method on, holds the canvases so they stay current between seasons. --- # Resolute vs charismatic leadership: what scales ## Charisma is how you appear. Character is what you build. - URL: https://stuartleo.com/articles/resolute-vs-charismatic-leadership - Published: 2026-11-07 - Reading time: 9 min read - Method: Resolute Charismatic and resolute leadership are not opposites. Charisma is a trait; resolute leadership is a practice that leaves leaders behind. Here's the difference. Charismatic leadership is leadership that runs on one person's appeal. Resolute leadership is the deliberate work of developing other people through character and values while equipping them with the skills and systems to reach their goals. The first leaves when the leader leaves. The second stays. That is the clean version. The trouble is that most writing on this topic, including a piece I once let go out under my own name, turns it into hero against villain: the resolute leader in one corner, the charismatic one in the other. It reads well. It is wrong. And the way it is wrong teaches the opposite of what matters. **Charisma is how a leader appears. Resolute leadership is what a leader builds.** ## The wrong way to draw the line The canon sets two leaders from the same century side by side: Winston Churchill and Adolf Hitler. It would be easy to cast Churchill as the resolute one and Hitler as the dangerous charismatic. *Resolute* refuses to. Chapter 7 puts it in four words: "Both were charismatic." It goes further. Both were skilled. Both could set goals, build teams, hold a room and run the machinery of a state. So charisma was not the difference. Skill was not the difference. Character was. One man's values (envy, ambition, hatred) pulled the values of ordinary people into line with his own until they did things they would never have done alone. The other man's values (courage, determination, a love of freedom) gave ordinary people a shape they could stand inside through the worst year of the war. Same toolkit. Opposite cultures. That is the third principle of the Resolute Leadership Curve in its starkest form: values reveal character, and character scales culture. If you take nothing else from this piece, take this. When you put charisma and resolute leadership on the same line, you end up asking how much charisma a leader has. That is the wrong question. The right one is what that charisma is carrying. What is yours carrying right now? ## Charisma is a trait. Resolute leadership is a practice. Charisma can sit inside good leadership. It is never the same thing as leadership. That distinction runs through the whole canon, and it rests on another one: character is not personality. Personality is how you are wired. It is largely given to you, by genetics and by the family and culture you grew up in. Charisma lives here. It is the magnetism some people walk into a room with, and it is real. *The Resolute Leader* does not pretend otherwise: charismatic leaders build fast and rally people quickly. Character is who you choose to become. It is cultivated, by intent and over time, and it is centred on values. The canon treats the two as separate dimensions, not two ends of a spectrum. A leader can run high on one and low on the other. Here is why that matters. Personality is value-neutral. Charisma will amplify a wise leader or a foolish one, a generous one or a narcissist, with equal force. Skill does the same. Skill amplifies whatever character sits under it, in both directions. Put charisma and skill on top of rotten character and you get what the twentieth century got. None of this is a new observation about charisma. Max Weber described [charismatic authority](https://en.wikipedia.org/wiki/Charismatic_authority) more than a century ago as authority that rests on the personal qualities of one leader, and saw its weak point straight away: it struggles to survive that leader. What Resolute adds is the practice that answers it. ## Why charisma does not transfer Picture two leaders walking into the same meeting. The first lifts the room. People sit up, decisions get made, energy follows them. Then they leave, and within a week the decisions are being relitigated by whoever is loudest. The second barely registers. They ask a few questions, make sure the right people are in the conversation, and leave early. The work keeps going. The decisions hold. We give both the same title. Only the second will still be leading after they have gone. Charisma does not transfer because what it holds together is attendance. When the person is in the room, the room works. When they are sick, on leave, in a bad month or gone, a vacuum opens where they stood. When every important call runs through one magnetic founder, the whole business is a single departure from trouble. The staff can usually see it long before the founder can. The canon's test is simple, and I have not found a better one. If you walked out of your business tomorrow, would leadership go with you, or would it stay? The clearest large-scale answer I know is the British military's Mission Command. Rather than rely on the general being in the tent, it trained every officer in the same questions, the same way of setting intent and the same decision rights, so judgement sat at every level. The leadership did not depend on any one person. It lived in what every officer had been taught. Jim Collins found an echo of this in business: the leaders who took good companies to great ones were marked less by personal magnetism than by [personal humility paired with fierce professional will](https://hbr.org/2005/07/level-5-leadership-the-triumph-of-humility-and-fierce-resolve). That is the resolute standard: leadership you build and copy into others, not leadership you lean on one person to supply. ## What resolute leadership builds instead Resolute leadership rests on two pillars, and the asymmetry between them is the hinge. **Character & Values** is the unchanging foundation of leadership. It decides whether a leader uses influence for good or for harm, and it does not move when the market does. Integrity in a boom is integrity in a collapse. **Skills & Systems** is the adaptive layer you build to scale: strategic thinking, communication, planning, operating rhythms, the tools that carry the work. These must keep changing. The systems that ran a team of ten will not run a team of a hundred. Hold those two together. *The Resolute Leader* names both failure modes. Have the character but not the skill, and you are a good person who cannot plan or delegate, wearing out yourself and everyone near you. Have the skill but not the character, and you are dangerous, for the reasons Churchill and Hitler make obvious. The book's image is a ship. Character is the keel that keeps you upright. Skills are the sails that catch the wind. You need both, and you need to know which one you are adjusting. This is where the Resolute Leadership Curve, the six stages every business climbs (Idea, Identity, Calibrate, Maturity, Mastery, Initiate), earns its place. Each stage asks for different skills and different systems from the same underlying character. The founder who carried the business on presence through Idea and Identity usually discovers the limit of it at Calibrate, the stage where a growing team has to align without the founder in every room. I have written about [why so many businesses stall at Calibrate](/articles/why-businesses-stall-at-calibrate). Charismatic dependence is one of the main reasons. ## The everyday version Few of us will lead through a war. All of us lead somebody this week. The everyday failure is rarely a tyrant. It is a well-meaning leader who cannot quite let go. They care about the work, so they redo it. They do not quite trust the team, so they override it. Initiative gets corrected until people stop offering it, the best people leave first, and the leader works longer to cover the gap they created. Their character, short on trust, has scaled a culture of dependency, and their charisma made it feel like leadership the whole way down. I write that as someone who has done it. *The Resolute Leader* opens with the moment I admitted I had been leading from ego rather than service, making a way for myself rather than for anyone else. The fix was not more presence. It was less of me at the centre and more of me building other people. The canon gives eight elements of character to test yourself against: integrity, humility, goodness, humour, empathy, boldness, courage and authenticity. Each one is framed as a question you answer honestly, alone, not one you perform in a workshop. The ones you flinch at are where your work starts. So which piece of someone else's work did you quietly take back this week? ## What resolute leadership is not It is not a case against charisma. If you have it, use it. The point is that charisma alone is not a system, so do not let it stand in for one. It is not a personality makeover. Resolute will not change how you are wired, and it does not need to. You keep your wiring. What you choose to build on top of it is the part that changes. And it is not a crisis plan. Pressure does not create character. It exposes whatever you brought into it. The time to build the foundation is before you need it. ## The question to take with you The honest question is not whether you are charismatic. Plenty of leaders are, and plenty of businesses still fall over when they leave. It is this: **if you stepped away for a quarter, what would your leadership leave behind?** If you are not sure, find out. The free [Resolute business diagnostic](/resolute/assessment) reads your business across the twelve questions (seven of leadership, five of management), shows you which stage of the Curve you are actually on, and names the one thing to build next. The [framework](/resolute/framework) and the [Resolute Leadership Curve canvas](/resolute/library/resolute-leadership-curve) walk all six stages. For the full argument on character, values, skills and systems, [read the canon](/books). --- # Values reveal character, character scales culture ## Your culture is copying you. - URL: https://stuartleo.com/articles/values-reveal-character - Published: 2026-11-07 - Reading time: 9 min read - Method: Resolute The third Resolute principle explained: the values you act on show your character, and your character is what your culture copies as the business grows. *Values reveal character, character scales culture* is the third of the Resolute 5 Foundational Principles. It says that the values you actually act on show who you are, and who you are is what your organisation copies as it grows. Notice what it does not say. It does not say culture is a set of perks, a values poster, or an offsite. It says culture is the leader's character, repeated by everyone who works for them. **"Skills decide whether you can build something. Character decides what you build."** (*Resolute*, chapter 7) That line is the premise. Everything below is commentary. ## Same skills, opposite cultures *Resolute* opens this principle with two names that sit uncomfortably side by side: Churchill and Hitler. The point is not that one was charismatic and the other wasn't. Both were. Both could command a room, set goals, build teams and run the machinery of a state. On any technical scorecard of leadership skill, both scored. What differed was underneath. One leader's values pulled ordinary people into doing what they would never have done alone. The other's gave ordinary people a shape they could stand inside through the worst year of their lives. Same century, same kinds of citizens, same toolkit. Opposite cultures. That is the uncomfortable part of this principle. Skill does not tell you which way an organisation will go. Character does. So here is the first question. If your team copied your character exactly, not your strategy, would you be proud of the culture that came out? ## The everyday version You will probably never lead a nation. You lead someone today, and the same physics applies. The book's everyday example is the micromanager. Usually a good person who cares about the work. But underneath the care sits an absence: no real trust, no willingness to let anyone else own an outcome. That absence scales. People stop taking initiative, because initiative gets overruled. The strongest people leave first. The leader works longer to cover the gap they created, and the loop tightens. Nobody wrote "dependency" into the culture. The leader's character put it there. I know this one from the inside. I have been the leader who talked about empowerment and lived in control. I wrote about it in *The Resolute Leader*, because the problem was never knowledge. I had read the right books. The problem was the mirror. Run it the other way and it works just as reliably. A leader who genuinely trusts hands out ownership, the team rises into it, and ideas turn up that the leader would never have had. Which piece of work are you about to redo yourself, because you don't trust the person who did it? ## Character is not personality, and it is not fame *Resolute* defines character as the inner shape of a person: what they are made of, and what their thoughts, words and decisions grow out of. Two things get mistaken for it constantly. **Personality.** The surface. Introverted or loud, serious or funny, optimistic or wary. Much of it comes from genes, family and how you were raised. It also moves more than people think. Long-run studies of personality show it is fairly stable but keeps changing across the whole of life ([Bleidorn et al., *Psychological Bulletin*, 2022](https://doi.org/10.1037/bul0000365)), so "that's just the way I am" is a weaker excuse than it sounds. **Fame.** Being known is not the same as being worth following. The two rarely coincide. When they do, the world notices. The difference between personality and character is the one that matters most inside a business. Personality drifts with experience. Character is shaped on purpose, by the choices you make and the experiences you sign up for. And personality can hide character. An engaging leader with a rotten core does more damage than a dull one, because people follow them further before they see it. One more thing the book is firm about. A crisis does not build character. It shows you what was already there. What would your last hard quarter say about you, if your team wrote it up honestly? ## Eight questions, answered at 5am Part One of *Resolute* gives eight essential elements of character, each framed as a question you ask of yourself: Integrity, Humility, Goodness, Humour, Empathy, Boldness, Courage and Authenticity. The framing matters more than the list. These are diagnostic, not aspirational. They are not words for the wall. They are questions about what you do when nobody is watching, whether you let others take the credit, whether you can make a hard week lighter, whether you see people or resources, whether you can tell the powerful the truth and hear it back, whether you hold your nerve, and whether you treat people the same whatever their position. Integrity heads Part One's list. Any version of this idea that files integrity under "empty platitudes" has the principle upside down. Part One's instruction is blunt: answer all eight honestly, and if three or more land badly, that is where your work is. Not a ranking. Not a top five to put on a slide. A place to start. Which of the eight would the people who report to you say you are weakest on? ## Values are not beliefs The other half of the principle is values, and the book draws a clean line around them. A **belief** is your assumption about how the world *is*. A **value** is your sense of how the world *ought* to be. One is a rational standard; the other is a moral one. Belief is what you think is real. Value is what you think is right. That line clears out a lot of clutter. Plenty of company "values" are beliefs in disguise ("customers want speed") or strategies ("we win on service"). Useful. Not values. And the values that count are not the ones you wrote down. They are the ones your actions demonstrate. The book's picture is a child learning honesty over a cookie jar, and that small practised habit growing into how the same person behaves in a boardroom decades later, where nobody else sees the decision. Your organisation is that child, scaled. It will mature the character you practise, or it will scale the absence of it just as faithfully. ## How character scales: the systems carry it This is where the principle meets the work. Character on its own stays personal. It lives in one leader and leaves with them. To scale, it has to get into the systems people live inside: how you hire, onboard, promote, decide and let people go. That is why *Resolute* puts values at the sixth question of leadership, Employee Experience, and calls them the substrate under it. The test is simple. If your stated values say *trust* and your systems say *ask permission*, you don't have a values problem. You have an employee experience problem, and the experience wins every time. The working tool is the [Values, Principles & Behaviours Canvas](/resolute/library/ex-values-principles-behaviors): a value becomes a principle a leader can apply, which becomes a behaviour a team member can recognise. That is how a word on a wall turns into something a new hire can actually see. The order matters, though. Systems without character don't stay neutral. They scale whatever is there. Build the hiring process before you know what you stand for, and you will hire efficiently for the wrong things. ## Where it sits on the Resolute Leadership Curve The Resolute Leadership Curve is the six stages every business climbs: Idea, Identity, Calibrate, Maturity, Mastery and Initiate. Stages are earned by what the business can do, not counted in headcount. This principle is live at every stage, because the Curve asks for a different application of the *same* underlying character at each one. Character and Values are the unchanging foundation of leadership. Skills and Systems are the adaptive layer you build to scale. Confuse the two and you get wobbly values that bend in a soft quarter, or rigid systems that can't move with the market. But you feel it hardest at Calibrate, where the team is growing faster than the systems and every new hire has to be aligned to something. It is the stage where most businesses [stall as they scale](/articles/why-businesses-stall-at-calibrate). The culture that formed by accident around a founder stops being free. It has to be decided. Collins and Porras made a related point years ago: the core of a company holds still while its practices change ([HBR, *Building Your Company's Vision*](https://hbr.org/1996/09/building-your-companys-vision)). Resolute adds the uncomfortable corollary. The core is the leader's character, whether you named it or not. ## What this principle does not do It will not fix a skills gap or a broken system. That is the fourth principle's ground: skills scale systems, and systems scale efficiency. It will not hand you a set of values. The book gives you a way to frame your own at Employee Experience, and the canvases to work it through. The values have to be yours. And it is not a personality test. Nobody gets reduced to four letters here. The question is not what you are like. It is what you are made of, and whether your business is copying it on purpose. ## Your culture is already copying you Every business has a culture. The only choice is whether it is the one you would have picked. So ask it plainly. If the next ten people you hire copy your character exactly, will the business get better or worse? If you're not sure, start with the free [Resolute business diagnostic](/resolute/assessment). It reads your business across the twelve questions (seven of leadership, five of management), tells you which stage of the Leadership Curve you're on, and names the one thing to build next. The [framework](/resolute/framework) walks all six stages and the five principles. The [canon](/books) goes deep: *Resolute* chapter 7 is this principle in full, and *The Resolute Leader* turns it on yourself. --- # The repo you hand over is a deliverable from day one ## Context that compounds in a client's repository compounds into their hands. A boundary condition on the method, learned from a near-miss. - URL: https://stuartleo.com/articles/the-repo-you-hand-over - Published: 2026-08-28 - Reading time: 5 min read - Method: C² Method A client repo is a deliverable from its first commit. The rule I keep for what context may compound there, and the near-miss that taught it. C² rests on one bet: context lives in git and compounds. Write down what you learned, and the next session starts where the last one finished. Here is the boundary condition on that bet, and it took a near-miss to find it. Context that compounds in a repository you intend to hand over is compounding into someone else's hands. ## A repo you own is a workspace. A repo you hand over is a deliverable. That distinction sounds obvious written down. It is not obvious at 11pm with an agent mid-task. Client work gets its own repository, in a GitHub organisation the client owns, so it can be given to them cleanly. That is the right structure. It also means the repo is a deliverable from the day it is created — not from the day of handover. Everything that has ever been committed there is part of what you hand over. Not the current state. The history. That is not a stylistic point. Once something is committed and pushed, GitHub's own guidance is that you should [consider the data compromised and rotate it](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository), because removing it from history does not undo who may already have it. ## The near-miss An agent working in a client repo wrote 3 lines into a session brief. The lines described a defect in my own platform — the mechanism, how far it reached, and whether it was fixed yet. None of that was speculation. All of it was accurate. That was the problem. It was caught in the working tree and never committed. I verified that three ways, including a search across every commit on every branch, because "I am fairly sure it did not land" is not a finding. The repository had moved into the client's organisation hours earlier. Both the agent and I knew that. Neither joined that fact to what was being written down. ## The briefing was right. Its depth was wrong. This is the part I keep returning to. The briefing that caused it was correct and necessary. The agent needed to know that a particular platform capability was unreliable, because that client's plan had 2 features that depended on it. Telling it stopped a build heading somewhere expensive. What went wrong was how much I said. I explained the defect fully — mechanism, reach, status — the way I would to someone on my own side. A diligent agent writes down what it is told. So the depth of the briefing decided the depth of what landed in the client's repository. That is the non-obvious half of this rule. It binds conversations, not just documents. You can be careful about every file an agent writes and still leak through what you say to it, because a good agent's whole job is to write down what it learns. ## The test I use now A client repo never holds a platform vulnerability. It gets the constraint and its consequence — never the mechanism, the reach, or the fix status. In practice that means the difference between these two lines: *"Do not build on capability X yet — it is not reliable. Use Y instead."* *"Capability X leaks data across tenants because of Z, it is unpatched, and here is how far it reaches."* The first is everything the client's build actually needs. The second helps nobody who is building their product. So the test is a single question, and I ask it of a sentence before it goes into a client repo or into an agent working in one: **Would this sentence help an attacker more than it helps whoever builds this client's product next?** If yes, it belongs in my repository, not theirs. The constraint travels. The mechanism stays home. ## The honest cost This asks you to brief shallower than feels natural, and briefing shallow feels like withholding. It also asks you to always know which repository you are standing in. That sounds trivial. On a day when an agent has been moved between 2 repos and you are mid-thought, it is not. The failure here was not carelessness about secrets. I am careful about secrets. It was a fact I held, a consequence I did not draw, and a gap of a few hours in which both were true at once. That is worth naming plainly, because "do not leak secrets" teaches nobody anything. Everyone already agrees with it. **Both parties held the fact and neither drew the consequence** is a shape you can recognise in yourself tomorrow. ## The rule, restated Context compounds. That is the whole point of the method, and it is why C² works. But compounding is not neutral about where it happens. A repository you will hand over is a deliverable from its first commit, and the history goes with it. So the constraint travels and the mechanism stays home — and you decide which is which before you brief, not after. [Read the method →](/c2/method) --- # Closing the flight plan: the gate nobody runs ## A filed plan that is never closed triggers a search. So does a PRD. - URL: https://stuartleo.com/articles/closing-the-flight-plan - Published: 2026-08-03 - Reading time: 8 min read - Method: C² Method Flight Planning spends context. Closing is where context gets made. The landing gate, its four parts, and why it scales from a room to one person. I'd been using the flight-plan metaphor for about a year before I noticed I was only using half of it. Filing a plan before takeoff — the scope line, the briefs, the milestones, put in front of a few people before an agent burns a session. That half I'd built a whole ceremony around. The other half is that [a filed flight plan gets closed on arrival](https://en.wikipedia.org/wiki/Flight_plan). That isn't a flourish. It's the mechanical reason the system works: an open plan means an aircraft unaccounted for, so if you land and don't close it, search and rescue starts looking for you. I had filed dozens of plans. I had closed exactly none of them. ## What an unclosed plan actually costs The cost isn't paperwork. It showed up in three specific places, and every one of them is the compounding half of the method quietly not happening. The gotcha that never got written down, because the moment the work was done I was already on the next thing. The PRD still sitting in `in-progress` six weeks after it shipped, because nothing ever declared it landed. The estimate I never once checked against the actual, which meant my estimates never got better — I had the data and never looked at it. None of those are failures of intent. I wanted all three. They just depended on discipline at the exact moment a build feels finished, which is the single worst moment to depend on discipline. That's what a ceremony is for. **A ceremony is what survives the moment good intentions don't.** ## Three gates, at three altitudes Before the shape of a closing, the thing that took me longest to get right: there are three human gates in a cycle, and I'd been collapsing two of them. | Gate | Cadence | The question it answers | Who holds the veto | |---|---|---|---| | **Flight plan** | per PRD | *Is this the right route, and is the plan flyable?* | Whoever owns the intent — before any build | | **Pull request** | per PR | *Does this build do what its brief said?* | Engineering — the test evidence and a peer | | **Closing** | per PRD | *Is the shipped thing right, and what was learned?* | The same person who cleared the flight plan | The middle gate is **correctness**. The outer two are **judgement**, held by one person, bookending the build. That symmetry is the point. The person who cleared the route is the person who confirms the landing — which is what stops a plan being approved against one standard and accepted against another. And a closing is not just a bigger code review. It sits higher: not *is this build correct* but *is the shipped thing right*, which includes whether it actually meets the intent and whether it looks right against the design system. That's a lens code review structurally can't apply. I ran the middle gate religiously for years and thought I had it covered. A merged PR tells you the code does what the brief said. It tells you nothing about whether the brief was the right brief. ## What a closing contains Four parts, one screen. Same shape as the filing, deliberately: **The landing.** What was actually built, against the line that was drawn. Not a demo — a comparison. Here's what I said I'd build, here's what landed, here's the gap. **The deviation.** Where the route changed and what got decided in the air. Zero judgment on this one, and that has to be real. The plan exists to make drift *visible*, not to punish it, and a closing where deviation is treated as failure is a closing where people stop reporting it. **The anchor.** The evidence that decides done. Tests that ran. The query that returned rows. The deploy that resolved. Explicitly not *the agent says it's done*, and not *the developer says it's done* either. The signal, not the account of the signal. **The learning.** What the contextbase gains — the gotcha, the pattern, the decision record, the honest completion rationale, estimated against actual. That last row is the one that pays for the ceremony, and it's worth being blunt about why. C² already asked for every one of those artefacts. The [session brief](/articles/write-your-first-session-brief), the knowledge capture, the completion rationale, the estimate check. What it never had was **a moment that produces them**. They were prescribed and unowned, which meant they happened when someone felt like it. **Flight Planning is where context is spent. Closing is where context is made.** ## Why the findings need structure The first few closings I ran produced a pile of *we should fix that* and *we should add that*, and roughly none of it survived the week. The problem wasn't the review. It was that findings with no structure can't be acted on. What fixed it is cheap, and it's four rules: - **Every finding gets a stable ID**, written onto the PRD in one section — not scattered through notes. - **Tagged FIX or ADD.** FIX is wrong today. ADD is a new capability. Conflating them is how a bug list quietly becomes a roadmap and nothing gets fixed. - **The keystone is flagged, and the list is sequenced.** Keystone first — the one that unblocks the others — then the trust fixes, then the high-value adds, then the design pass. An unsequenced list of 20 findings is 20 arguments waiting to happen. - **The PR that resolves one references its ID.** Now the trail runs review → PRD → PR → shipped, and it's auditable from git alone. Those findings become the seed for the *next* flight plan. That's the join that turns two ceremonies into a loop rather than two events that happen to bracket a build. An agent can prepare all of that. An agent can't do the sequencing, because sequencing is judgement — and an agent should never close a plan, for the same reason it should never file one. ## The sweep belongs to the next plan One more mechanic, and it's the one that stops the PRD drowning. If findings only ever accumulate, the document becomes a graveyard of every past admin task and stops saying where the work is *now*. So the section is bounded, and it's swept at the version bank-switch — **by the next flight plan, not by the closing.** - Durable decisions and rules get promoted into the spec itself or into the knowledge base, then cleared from the list. - Done admin items get cleared outright. Nothing is lost — the trail lives in the PR that closed them, the release note, and `git log` forever. - Unfinished items carry forward into the new plan. - The feature list gets reconciled so it states what actually shipped. So the two ceremonies own the two ends of the lifecycle. **The closing appends at the end of a cycle. The next flight plan sweeps at the start of the next one.** That pair is how a PRD compounds without hoarding — and it's the actual mechanism behind "living document", which is otherwise just a sentiment people nod at. ## Alone, it's still a gate The obvious objection: this sounds like a meeting, and plenty of people building with agents don't have anyone to hold one with. The ceremony scales, it doesn't toggle. With a crew it's a room — two people, whoever owns the intent and whoever owns the implementation, both with the authority to say *not yet*. In most setups it's one person wearing both hats. Building alone, it's you, reading the diff and asking whether the agent did what you actually wanted. Same four parts. Same question. It takes about 15 minutes. And I'd argue the solo builder needs it *most*, precisely because there's nobody to notice it was skipped. When you're alone, the closing is the only thing standing between "the code works" and "I know why, and so will I in three months." The honest cost is that it lands at the worst possible time — the moment you feel finished and want to start the next thing. Every part of you will argue it can wait. It can, and it won't happen. ## Close what you file A plan nobody closes isn't a paperwork failure. It's a compounding failure. The session happened, the code shipped, and nothing was learned from it — which means the next cycle starts exactly as expensive as this one did. File the plan before takeoff. Close it on landing. **Flight Planning is where context is spent. Closing is where context is made.** Start here: see [Flight Planning](/articles/flight-planning-before-the-build), [write your first session brief](/articles/write-your-first-session-brief), or [read the method](/c2/method). --- # Don't draw the graph on day one ## Topology is earned by traces. On day one you have none. - URL: https://stuartleo.com/articles/dont-draw-the-graph-on-day-one - Published: 2026-08-03 - Reading time: 7 min read - Method: C² Method Diagramming a big agent workflow before you have watched the work behave produces brittle structure. Why your contextbase is already the trace collection. Every time a new structural idea lands in agent development, the same thing happens. People read the piece, open a diagramming tool, and design the whole system before they've run any of it. I've done it. I drew a beautiful 9-node workflow for a code audit, complete with parallel branches and a merge step, before I'd ever run that audit even once by hand. It was elegant, it was wrong in about 4 places, and I only found that out by running it — at which point the elegance was the problem, because a 9-node structure is much harder to change than a paragraph of instructions. The structure encoded assumptions I hadn't checked. That's the failure, and it has an order that prevents it. ## The most common mistake in the whole shift Building the graph too early is the number one mistake in this transition, and it's worth being precise about *why*, because "don't over-engineer" is too vague to act on. A topology is a set of claims. *These two jobs are independent.* *This step needs everything before it.* *This result should be checked before it counts.* Every arrow you draw is an assertion about how the work behaves. On day one you have no evidence for any of them. You're not designing from observation — you're designing from a blog post about somebody else's work, which behaved the way it did for reasons specific to their codebase, their team, and their problem. And the cost isn't just being wrong. It's that structure is *sticky*. A wrong instruction gets rewritten in 30 seconds. A wrong topology gets defended, because someone built it and it looks like architecture. Premature structure produces the thing [YAGNI](https://martinfowler.com/bliki/Yagni.html) has warned about for 20 years — the cost isn't only the work you did, it's the work you now have to maintain and reason around. **Every arrow you draw is a claim about how the work behaves. On day one, you have no evidence for any of them.** ## The order that actually works The sequence that holds, and I've now watched it hold across several projects: 1. **Start simpler than feels sufficient.** One agent, one brief, one loop. Yes, really. 2. **Collect traces.** Run it repeatedly and record what actually happened — what stalled, what collided, what you found yourself doing by hand every time. 3. **Find the stable patterns.** Look for the things that recur. Not the interesting one-offs, the boring repeats. 4. **Formalise only what deserves control.** Turn a repeated pattern into structure. Leave the rest loose. Step 2 is the one everybody skips, because it feels like the un-fun part. It's the entire load-bearing step. Structure without traces is decoration. The instinct to skip it is understandable — collecting traces sounds like tooling you don't have. Which brings me to the part I think C² gets to claim. ## Your contextbase is already the trace collection Here's the thing I didn't notice for a long time, despite it sitting in my own repo. **The contextbase — the folder of markdown your agent reads before it acts — *is* the trace collection.** Not a substitute for one. The actual thing. Every [session brief](/articles/write-your-first-session-brief) is a record of a run: what was attempted, what changed, what blocked, what's next. Every gotcha is a recorded failure with its cause. Every prompt brief's pre-flight table is a record of which files a job actually touched. That's exactly the material step 2 asks you to gather, and if you've been running the method you've been gathering it by accident. Read 50 of them together and the patterns are not subtle: - **Which surfaces keep colliding.** Two areas that show up in the same session brief again and again, fighting each other, are one surface pretending to be two. - **Which briefs kept stalling.** A brief type that always overruns is either badly scoped or it's really 2 briefs. - **What you did by hand every single time.** That's your first automation candidate, and it's earned. - **Which jobs never once shared anything.** That's your fan-out, evidenced rather than guessed. None of that is available on day one. All of it is free by day 50, if you wrote things down. **Topology is earned by contextbase, not adopted from an article.** ## What 50 sessions buys you A concrete example, because the general claim is easy to nod at. I now run a code-audit workflow with a fan-out. It works well. But I didn't design it — I extracted it, and the extraction took about 20 minutes, because the evidence was already written down. Reading back through session briefs, the same shape kept appearing: I'd audit for correctness, then separately for security, then separately for whether the docs still matched. Three passes, always the same three, always in whatever order I felt like. The briefs also told me those three never once touched the same files, because their pre-flight tables never overlapped. And the same two gotchas came up every time I did the security pass, because I kept forgetting them. That's a fan-out with 3 nodes, a shared reading list, and 2 frozen rules — derived entirely from records I'd written for a completely different reason. I didn't need a design session. I needed to read my own notes. The honest cost is that this is slow. You cannot shortcut to day 50. It asks you to write a brief at the end of every session for weeks before the payoff is visible, and for most of that time it feels like admin. That's the real price of the method, and I'd rather say it plainly than pretend the discipline is free. ## What to do on day one instead If you're at the beginning, the answer is not a smaller graph. It's no graph. - **Run one agent against one brief.** Get that loop reliable — knowing what "done" means, having something checkable at the end. - **Write the session brief every time.** This is the whole investment. Five minutes, at the moment you least want to. - **Capture gotchas as they bite.** One file each, in git, so the next session reads them. - **Wait.** For a few weeks. Genuinely. Then, when you catch yourself doing the same 3 things in the same order for the fourth time, you'll have both the pattern *and* the evidence for it. That's when the structure is worth building, and it'll be right, because it came from what happened rather than what you imagined would happen. There's a version of this rule stated in adoption terms too: if you aren't already running concurrent agents behind a verification loop you trust, the graph isn't your next move — the loop is. Same governor, [different ladder](/articles/crawl-walk-run-adopting-ai-agents). ## The graph is the last thing you build The enthusiasm is warranted. Running work wide genuinely is a capability that didn't exist a couple of years ago, and the demos are not fake. The order is what people get wrong. The graph is where this ends up, not where it starts — and the thing that gets you there isn't a diagramming session. It's 50 sessions of writing down what actually happened, which is unglamorous, cheap, and the only real evidence you'll ever have. **Topology is earned by contextbase, not adopted from an article.** Including this one. Start here: see [what a contextbase is](/articles/what-is-a-contextbase), [write your first session brief](/articles/write-your-first-session-brief), or [read the method](/c2/method). --- # Don't loop on confidence. Loop on evidence. ## "The agent says it's done" is not a stop condition. - URL: https://stuartleo.com/articles/dont-loop-on-confidence-loop-on-evidence - Published: 2026-08-03 - Reading time: 6 min read - Method: C² Method A system of agents checking each other's reports is consistent and unverified. Anchors, frozen rules, and what makes a result actually count as done. Here's a failure mode that gets more expensive the more sophisticated your setup becomes. You build the whole thing properly. A worker agent does the job. A checker agent reviews the worker. An audit agent reviews the checker. Every layer confirms the one below it, everything comes back green, and the report is clean. And every single one of those agents was reading another agent's report. Nothing in that system ever touched reality. It's consistent and unverified — which is exactly how a single agent fails, only later, more expensively, and with far more green lights on the way down. ## Everything is consistent, nothing is verified The trap is that consistency *feels* like verification. Three agreeing sources sounds like corroboration. It isn't, if all three are downstream of the same unchecked claim. I hit a small version of this on a data migration. The migration agent reported success. The verification agent confirmed the row counts matched. The summary agent reported a clean migration. All true, all useless — because the verification agent had asked the migration agent for the counts rather than querying the database. One `select count(*)` would have shown the target table at 40 rows instead of 40,000. Nobody lied. There just wasn't a single point in the chain where anything left the conversation and checked. This is the same instinct behind [self-testing code](https://martinfowler.com/bliki/SelfTestingCode.html) — Martin Fowler's point that a suite you can run is worth more than a belief that the code works. What's changed is that the thing telling you it works is now articulate, confident, and generates its own supporting detail. ## What an anchor is An **anchor** is a signal no agent in the run can produce by asserting it. That's the whole definition, and the test in it is *produce by asserting*. Can the agent make this true by writing a sentence? If yes, it isn't an anchor. - "The tests pass" — not an anchor. That's a claim. - `npm test` exiting 0, in output you can see — an anchor. - "The migration completed" — not an anchor. - A query returning 40,000 rows — an anchor. - "The endpoint is live" — not an anchor. - A 200 from a real request to the deployed URL — an anchor. The pattern is that an anchor comes from outside the model's mouth. A test that ran, not one that should pass. A query that returned rows. A deploy that resolved. A metric that moved. The agent can *report* these, but it can't *make them true* by reporting them, and that gap is the entire point. **An agent that grades its own homework will pass itself. Not from dishonesty — from doing exactly what you asked, which was to produce a final message.** ## Why "testable" was always in the gate If you've been running C², you've had a partial version of this the whole time and may not have noticed which word was carrying it. The prompt brief quality gate has 6 items, and item 3 is **testable acceptance criteria**. Not "clear" criteria. Not "specific" criteria. *Testable* — meaning there exists a thing you can run that comes back true or false without anyone's opinion. That word was doing anchor-work before I had a name for it. What was missing was making it explicit, because "testable" is easy to satisfy loosely. *"The refresh flow works correctly"* passes a casual read and fails the actual test — there's nothing to run. So the fix is a naming discipline, not a new process step. Every brief names its anchor, and it lives inside the acceptance-criteria item rather than becoming a seventh: ```text - [ ] Testable acceptance criteria — and name the anchor: the one signal that decides done, which the agent cannot produce by asserting it. Weak: "Token refresh works." Anchor: `npm test -- auth/refresh` exits 0, AND a real refresh against staging returns a new token pair (paste the response). ``` The gate stays 6 items. Item 3 now asks a sharper question: *which signal decides, and can the agent fake it?* ## Frozen rules — the ones an optimiser would bend There's a companion idea, and it covers the case where the anchor itself comes under pressure. Some rules are non-negotiable precisely *because* they're the ones something optimising for "done" would want to relax. Mark them frozen. Mine, earned the hard way: - **The write-path check after any constraint migration.** A near-empty table is a broken writer, not low adoption. I learned that distinction from getting it backwards. - **The file-size cap.** Every argument for exceeding it has been reasonable and every one was wrong. - **Never fabricate data to make the software look like it works.** Including test fixtures that quietly paper over a real failure. Every frozen rule exists because it got bent once and something broke. They belong in the contextbase next to the gotchas, and they belong in the brief when the work touches them. **A system is only as honest as the things inside it that refuse to move.** ## Making the verifier independent One more mechanical point, because "add a reviewer" is where most people stop and it isn't sufficient. Independence isn't an attitude the reviewer has. It's three conditions: 1. **A different model from the one that wrote the code.** Two models catch different blind spots. One model checking itself catches the ones it already missed. 2. **Inputs the author doesn't control.** Run the check where the builder can't reach it — in CI, from the acceptance criteria and the diff. A builder running the verifier on their own machine, on inputs they assembled, is self-assessment with extra steps. 3. **Teeth.** A dispute blocks the merge. A reviewer whose objection is advisory gets overruled at 5pm on a Friday. A [bench agent](/articles/ai-code-review-with-a-bench-agent) gets you most of the first condition for free, because a separate process is a separate context by construction. The other two you have to build. The honest cost is that anchors slow you down at the start. Writing "the tests pass" takes 3 seconds. Working out which command, against which environment, returning what, takes 5 minutes and sometimes reveals that you can't verify the thing at all — which is unwelcome information arriving at the least convenient time. That's the price, and it's the good kind, because the alternative is finding out in production. ## What makes a result count More agents don't make a system more trustworthy. They can make it *more confident*, which is worse, because confidence at scale looks like corroboration and reads like a clean report. The fix isn't more reviewers. It's making sure at least one thing in the loop touches something the model can't talk its way past. Name the anchor. Freeze the rules that will come under pressure. Give the verifier a signal rather than a summary. **A result counts when something the agent cannot fake says so.** Start here: see [how to write acceptance criteria an agent can check](/articles/acceptance-criteria-for-agents), [how a bench agent reviews work](/articles/ai-code-review-with-a-bench-agent), or [read the method](/c2/method). --- # The pilot's bottleneck changes ## Same posture, four different constraints — and the question you ask changes with it. - URL: https://stuartleo.com/articles/the-pilots-bottleneck-changes - Published: 2026-08-03 - Reading time: 7 min read - Method: C² Method The Pilot model was never static. Attention, then review throughput, then trust in the loop, then knowing what to automate. Four stages, four questions. The [Pilot model](/articles/the-pilot-model-directing-ai-agents) says the human directs and the agents execute. I still think that's the most useful reframe in the method. It has one flaw, though, and it took me a while to see it. Stated plainly like that, it reads as **static** — as though being a pilot is one fixed posture you adopt on day one and hold forever. It isn't. What a pilot *is* holds constant. What **constrains** a pilot does not, and it changes shape about 3 times on the way up. Every time it moved, I kept doing the thing that had worked at the previous stage and wondered why it had stopped working. ## The model that reads as static Here's the failure it produces. You learn to be a pilot with one agent. The skill you build is *reading output carefully* — you review everything, you catch the drift, you develop good instincts about where the agent goes wrong. That skill is genuinely what makes stage one work, and you get good at it. Then you add agents. And the skill that made you effective becomes the thing holding you back, because reading everything doesn't scale past about 2 streams. You're not doing anything wrong. You're doing the *previous stage's* right thing. Nobody tells you the constraint moved. The model just says "direct the work", which is true at every stage and useless for knowing which stage you're in. ## Attention: one agent, and you're watching At the first stage, the bottleneck is **your attention**. Trust is low, and correctly so — you don't yet know where this agent is reliable. There's no self-verification, so the only quality gate is you reading the output. Work is synchronous. You start it, you sit there, you watch. The question you're asking, constantly: **do I need to read this?** The answer at this stage is yes, all of it, and that's fine. This stage is where you build the judgement everything above depends on — which kinds of task it nails, which it fakes, what its confident-and-wrong looks like. You cannot skip it, and trying to is the most common way an agent rollout falls over. The move out of this stage is not more agents. It's building something that checks the work so you don't have to be the only thing that does. ## Review throughput: several streams, each checking itself Second stage. You've got tests, a build, a lint step, an end-to-end check against a real environment — a loop the agent runs on itself before you ever look. Now more agents is a sensible idea, because each one arrives pre-checked. The bottleneck moves to **review throughput**. You hand-write almost nothing. You read final diffs rather than watching keystrokes, and the constraint is how fast you can form a judgement on several finished pieces of work. The question becomes: **can I review this fast enough?** This is the stage most teams are climbing into now, and it's where the classic [span of control](https://en.wikipedia.org/wiki/Span_of_control) problem arrives — the old management question of how many things one person can meaningfully supervise, except the things now produce output faster than any human report ever did. The practical shift is that you stop optimising your reading speed and start optimising what arrives. A diff that comes with its own passing test is quicker to accept than one that doesn't. That's not a review skill. It's a **contract** skill — tightening what each job is allowed to return so the review is cheap. ## Trust in the loop: more than you can read Third stage, and the honest one. Output exceeds what you can personally read. Not "is difficult to read" — exceeds. Plenty of people treat this as the point where quality has to drop. It's the point where the *question* has to change. *"Did you read the code?"* stops being the right question, because the answer is no and pretending otherwise is theatre. What replaces it: **What context was the model missing, and how do we fix that for next time?** That's a different job. You're no longer the inspector — you're debugging the *system that produces* the work. A bad output is no longer a thing to correct. It's evidence that something upstream was underspecified, and the fix belongs in the brief, the gotcha, or the anchor rather than in the diff. The bottleneck here is **trust in the loop** — and trust is a technical property, not a feeling. It means the verification is independent, it runs where the builder can't reach it, and a dispute actually blocks a merge. This is also the stage the closing gate exists to make survivable. If you can't read everything, you need a moment where a human checks the *evidence* against what was asked, and the answer to that question goes straight back into the contextbase. Without it, work at this scale is unreviewed by construction. ## Knowing what to automate Fourth stage, and I'm not going to pretend I live here. What I can see from below is that the constraint changes again — to **identifying what's worth automating**, and matching the guardrails to each kind of work. You monitor by exception. Most things run without you seeing them, and the skill is knowing which categories genuinely need a human in the path and which have earned their way out. The question: **is this something an engineer would have done?** Not *is this correct* — you've stopped being able to check that directly — but *is this the shape of decision I'd have wanted made this way?* ## What stays constant Four stages, four constraints, four questions: | Stage | What constrains you | The question you're asking | |---|---|---| | **Assisted** | Your attention | *Do I need to read this?* | | **Parallel** | Review throughput | *Can I review this fast enough?* | | **Supervised** | Trust in the loop | *What context was the model missing?* | | **Intent-steered** | Knowing what to automate | *Is this what an engineer would have done?* | What doesn't move is the posture. At every stage you own the outcome, you set the quality bar, and you make the calls nobody should be delegating. A pilot at stage 4 is not less accountable than one at stage 1 — they're accountable for different things, and through different instruments. That's why I'd rather deepen the Pilot model than replace it. The reframe was right. It was just missing its stages, and without them it reads as though the job never changes. The honest cost is that each transition asks you to give up the skill that made the previous stage work. Stage 2 asks you to stop reading everything, which feels like lowering your standards. Stage 3 asks you to stop reading the code at all, which feels much worse. Both are real losses, and both are the price of the next stage. If you refuse them, you don't stay at your current stage — you stall, with more agents than you can hold. And there's a second axis worth checking against this one, because they move independently: how risky the work is, versus how many agents you run. [Two ladders](/articles/crawl-walk-run-adopting-ai-agents), not one. ## Same pilot, different instruments I spent months at stage 2 trying to be excellent at stage 1. Reading everything, catching everything, proud of it — and quietly capping the whole system at my own reading speed. The fix wasn't working harder or trusting blindly. It was noticing that the question had changed, and that *do I need to read this* had become the wrong thing to ask. **What a pilot is holds constant. What constrains them does not — and knowing which stage you're in tells you what to fix.** Start here: see [the Pilot model](/articles/the-pilot-model-directing-ai-agents), [how agent teams work](/articles/ai-agent-teams-explained), or [read the method](/c2/method). --- # The prompt brief is a node contract ## Everyone is teaching the fan-out. Nobody is teaching the contract that makes it safe. - URL: https://stuartleo.com/articles/the-prompt-brief-is-a-node-contract - Published: 2026-08-03 - Reading time: 7 min read - Method: C² Method A fan-out returns twelve confident, unusable outputs unless every agent has a contract. What that contract specifies — and why the prompt brief already is one. There's a lot of writing right now about running many agents at once. Fan out, split the work, merge the results. The demos are genuinely impressive. Almost none of it covers the part that decides whether the run was worth doing. Spread a vague instruction across 12 agents and you don't get 12 times the output. You get 12 confident, mutually incompatible answers, each internally reasonable, and a merge step that can't reconcile them because there was never a shared definition of done. The fan-out worked perfectly. The results are unusable. The missing piece is a **contract** on each job. And if you're running C², you've been writing them for two years under a different name. ## Twelve agents, twelve unusable answers The failure is specific, and it isn't a model problem. Give 12 agents "review this module and report issues" and each one silently invents its own scope. One reports style. One reports security. One rewrites half the file and reports that as an improvement. One reports nothing because it decided the module was fine. Their outputs aren't comparable, so the merge produces a pile rather than an answer, and you end up reading all 12 in full — which is exactly the work you were trying to avoid. Nothing was wrong with any individual agent. What was missing was a specification tight enough that 12 independent runs produce 12 *commensurable* results. That specification is the contract, and it does three things: it bounds the input, it fixes the job to exactly one, and it makes the output checkable. ## Bounded input: the pre-flight table The first thing a contract does is say what the agent may read. This sounds like a restriction and behaves like a gift. An agent given a whole repository spends its window deciding what's relevant and gets it partly wrong. An agent given 4 files and a reason for each starts from the same place you would. In C² that's the **pre-flight table** — part of an autonomous prompt brief, which is a brief written for a session where you won't be present: ```text | File | Lines | Why | |-----------------------------------|---------|----------------------------------------------| | src/auth/middleware.ts | 1–80 | session pattern on L45 — don't break it | | src/auth/tokens.ts | 120–200 | refresh flow this brief extends | | docs/03-knowledge/gotchas/jwt.md | all | the clock-skew trap that bit us in April | ``` Exact paths, exact line ranges, and a reason for each. Writing that table forces you to work out the approach before the agent touches anything, which is most of its value — it's a design step disguised as a reading list. It has a second use I didn't anticipate. **The pre-flight table is a declaration of the brief's surface** — what it will touch. Put two briefs' tables side by side and you can see immediately whether they can run at the same time. The contract that makes one node safe is also what tells you the shape of the whole set. ## One job, and the things it must not do The second thing a contract does is fix the scope to exactly one job — and the sharp end of that is what the brief *forbids*. Every C² brief carries **scope exclusions** and **non-goals**. They read like bureaucracy until you've watched an agent helpfully refactor an adjacent module while fixing your bug, and then they read like the most valuable lines in the document. ```text What's being built: - Refresh-token rotation on the existing /auth/refresh route What's explicitly NOT being built: - Any change to the session table schema — separate brief, PB-4 - Migration of the legacy /login path - "While we're here" cleanup of the auth tests ``` An agent handed an open-ended job will expand into whatever adjacent work looks sensible, and every expansion widens the surface — which is what turns a brief that could have run alongside 3 others into one that collides with all of them. Non-goals aren't tidiness. They're what keeps the node's boundary where you drew it. ## Validated output: the anchor The third thing is the one most fan-outs skip. What does this job return, and how do you know it's true? The wider engineering answer is a schema — [JSON Schema](https://json-schema.org/) and its relatives exist so a machine result is *validated* rather than parsed and hoped over. That's the right instinct, and C²'s version is older and blunter: **testable acceptance criteria**, plus the one signal that decides done. That signal has a name now. It's the **anchor** — something no agent in the run can produce by asserting it. A test that actually ran. A query that returned rows. A deploy that resolved. Not "the agent says it's done", which is a report, not a result. **A node that grades its own homework isn't a node. It's an opinion with a filename.** Naming the anchor costs one line in the brief. It's folded into the acceptance-criteria item rather than added as a new one, so the gate stays 6 items: ```text - [ ] Testable acceptance criteria — and name the anchor: the one signal that decides done, which the agent cannot produce by asserting it. → Anchor: `npm test -- auth/refresh` passes, and a real refresh against staging returns a new token pair. ``` That's the difference between 12 results you can merge and 12 you have to re-read. ## Why this is the hard part nobody sells Fan-out is easy to demonstrate and easy to sell. It looks like leverage, it makes a good screenshot, and you can build one in an afternoon. The contract is unglamorous. It's writing, done before anything runs, by the person who least wants to be writing at that moment. There's no demo. The payoff is invisible — it shows up as the merge that just worked, and the 3 hours you didn't spend reconciling incompatible outputs. That's the honest cost of this method, and it's the real one: **C² moves the work earlier.** The brief takes 20 minutes you'd rather spend building. What you get back is a run whose output you can actually use, and the ability to run several at once without the results turning to mush. It's also why I don't think the fan-out is the interesting part. Spawning agents is a solved problem — the tooling is good and getting better every month. Specifying a job tightly enough that 12 independent runs come back commensurable is not solved, and it isn't a tooling problem. It's a writing problem, and it sits with you. ## The contract is the whole game A graph of agents is a set of nodes and the arrows between them. The arrows are architecture. The nodes are where the work actually happens, and a node is only as good as the contract on it. Bounded input, exactly one job, an output something other than the agent can confirm. Get those three right and the fan-out is the easy part. Get them wrong and running wide just means being wrong in parallel. **The fan-out is the easy half. The contract on each node is what makes the results worth having.** Start here: see [how the Cascade gets you to a brief](/articles/the-cascade-from-prd-to-prompt-brief), [how to write acceptance criteria an agent can check](/articles/acceptance-criteria-for-agents), or [read the method](/c2/method). --- # The shape of the work is a graph, not a queue ## Your briefs were never a queue. They were a graph nobody was drawing. - URL: https://stuartleo.com/articles/the-shape-of-the-work-is-a-graph - Published: 2026-08-03 - Reading time: 7 min read - Method: C² Method Work has a shape, and the shape is a graph. Nodes, edges and barriers in plain terms — and why your prompt briefs were always a fan-out. I spent about a year running my prompt briefs one at a time, in the order I happened to write them, and calling that a method. Then I looked at a plan I'd just filed — 6 briefs for one feature — and asked a question I'd never thought to ask. Does brief 4 need anything from brief 3? It did not. Did brief 5 touch a single file brief 2 touched? It did not. Three of the 6 were completely unrelated to each other, and I had queued them behind one another for no reason except that I'd typed them in that order. The work had a shape. I just hadn't drawn it. ## The straight line I was walking A queue is the default because it's the thing you get for free. You write briefs top to bottom, you run them top to bottom, and nothing ever tells you that some of those arrows are imaginary. The cost is invisible, which is why it survives. A build that takes 5 sessions in sequence still finishes. Nobody stands over it saying *three of these could have run this morning.* You only see it if you go looking, and the only reason I went looking is that the sequence had started to annoy me. This isn't a new observation, incidentally. Data engineering worked it out decades ago and named the result a **DAG** — a directed acyclic graph, a set of jobs with arrows showing which genuinely depend on which. Tools like [Airflow](https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/dags.html) exist because someone noticed that a nightly data pipeline is not a list. What's new is that the jobs are now agents, and most people running them are still writing lists. ## Nodes do the work, edges carry the result Two words do most of the lifting, and both are simpler than they sound. A **node** is one agent doing one bounded job. In C² you already have these — a node is a [Prompt Brief](/articles/the-cascade-from-prd-to-prompt-brief), the atomic build unit, and the brief is what tells the node what it's for. An **edge** is what crosses *between* two nodes. Not "this one comes after that one" — an edge exists when something actually moves. Brief B reads the schema brief A emits. Brief B can't start until that schema exists. That's an edge, and the thing that makes it real is the artefact, not the order. The distinction matters because it's the whole test: **"PB-2 after PB-1" is a queue. "PB-2 consumes the schema PB-1 emits" is an edge. One of those is a decision. The other is just the order you typed them in.** Once you're naming edges by what crosses them, most of the arrows in a plan turn out to be nothing. They were habits. ## The fan-out that was already in my brief set Here's the part that reframed the method for me. C² breaks a feature down through the Cascade — Platform PRD, then Feature PRD, then **Prompt Brief × N**. That `× N` is doing something specific: it produces several sibling briefs under one PRD. Siblings. No edge between them by construction, because each one was scoped to be an atomic unit of work in its own right. That's a **fan-out** — several independent jobs that can run at the same time. It was sitting in the method the whole time, described as a decomposition step, and nothing anywhere said the resulting briefs could run at once. *Cascade* is a waterfall word for a structure that was already a graph. Not every set fans out, and this is where the honest test comes in. Two briefs are independent when two things are true: no edge connects them, and no **surface** is shared. A surface is everything a brief mutates or contends for — files, yes, but also a database, a rate-limited API, one deploy target. Two briefs whose file lists don't overlap can still both hammer one staging database, and that's the collision nobody sees coming, because nothing in either brief declares it. The cheap part is that you've already written the evidence. An autonomous brief carries a pre-flight table listing exactly the files it will touch. That table *is* a declaration of the brief's surface. The arrows are derivable from something the plan already produces. ## Barriers, and why you have to earn one Work that fans out has to come back together somewhere. That point is a **barrier** — a step that waits for everything before it. You already have barriers. The integration brief is one. The pull request is one. The review before a merge is one. What's worth knowing is that a barrier is expensive in a specific way: it makes every branch wait for the slowest one. Five briefs that each take an hour, plus one that takes four, means the barrier costs you three hours of idle. So a barrier needs a reason. A real one looks like *this step genuinely needs all of them at once* — merging into one branch, deduplicating across the whole set, an early exit if the total comes back empty. A bad reason is "it's tidier." Tidiness is not a dependency. And a caution that belongs in the same breath, because it's the one I'd want said to me: **running wide buys breadth, not judgment.** A graph gets more surface covered per hour. It doesn't make any individual result better, and it will happily produce 6 confident, useless outputs at 6 times the speed. If the work is exploratory and you need to steer, that's one agent and one loop, no matter how many you could spin up. ## Drawing it: the fifth part of a filed plan None of this is useful as a concept. It's useful as a thing you write down before you build, which is why it now has a home in the ceremony. [Flight Planning](/articles/flight-planning-before-the-build) is the review where you file your plan before an agent burns a session. It used to have 4 parts — the line, the briefs, the journey, and an optional red line. It now has 5. The new one is **the shape**, and it states four things about the brief set: ```text The shape independent PB-2 + PB-3 (no edge, no shared surface) — can run at once edges PB-1 → PB-2 (the route table crosses) barrier the PR — needs all three branches verified PB-1's output gets a bench pass before it counts ``` That's a route. What I was filing before was a queue with dates on it. The honest cost is small but real: it's one more thing to think about before you're allowed to start, at exactly the moment you want to start. It takes maybe 10 minutes. And some plans come back a straight line — which is a finding, not a failure. A line is just a graph with one edge in and one edge out. **Filing "this is a line, and here's why" is fine. Never asking is the problem.** There's a second cost worth naming. If you can't find two briefs with no edge between them, there's nothing to spread, and forcing it produces a diagram rather than a speed-up. The answer then is one agent, working in sequence, which is the right answer most days. ## The arrows you never checked I'd been treating the order I wrote things in as the order they had to happen. That's the whole mistake, and it's an easy one, because a queue never complains. Work has a shape. Nodes do the jobs, edges carry what crosses between them, and a barrier is where the parallel paths come back. Most of the arrows in a plan are real. Some of them are just the order you typed. The only way to tell is to draw it — and half the waits in your build were never necessary. Start here: see [how the Cascade breaks work down](/articles/the-cascade-from-prd-to-prompt-brief), [how to isolate parallel agents with git worktrees](/articles/parallel-agents-with-git-worktrees), or [read the method](/c2/method). --- # The two ladders of AI adoption ## One grades the risk of the work. The other grades how many agents you run. They are not the same climb. - URL: https://stuartleo.com/articles/the-two-ladders-of-ai-adoption - Published: 2026-08-03 - Reading time: 6 min read - Method: C² Method Risk of the work and agent count are orthogonal axes, and confusing them is why adoption advice keeps missing. The 2x2, and how to find where you sit. Two people argue about AI adoption and talk straight past each other constantly. I've been both of them. One says *we're quite advanced — agents run unattended overnight on real production code.* The other says *you're barely started, you're running one agent and reading every line it writes.* Both are right. They're describing different ladders, and neither of them said which one. ## Two people, two different climbs The confusion is structural rather than careless. There genuinely are two independent things that get better as a team matures with agents, and both get called "adoption". **Ladder one is the risk of the work.** Are agents doing trivial chores, or real features, or work that ships without a human reading every line? This is the one C² already publishes as [crawl, walk, run](/articles/crawl-walk-run-adopting-ai-agents), and it's about *what you trust an agent with*. **Ladder two is agent count and what it makes you.** One agent you sit beside, or several running in isolation, or more output than you can personally read. This is about *how many* and *what your job becomes*. They're not stages of one progression. They're axes. And the arguments happen because everybody assumes their axis is the axis. ## Ladder one: the risk of the work The first ladder has 3 rungs and it's the better-known of the two. **Crawl** is work where mistakes are cheap and instantly visible — adding tests to code that lacks them, small well-defined bugs, mechanical refactors the tests guard, dependency bumps. It feels unambitious. That's the point: it builds the test coverage and the judgement everything above it stands on. **Walk** is real features, behind review. The agent builds, a human or a bench agent checks before it lands. Most teams should live here most of the time — ambitious enough to matter, safe enough to catch the misses. **Run** is autonomous, well-fenced work. Unattended sessions on scoped tasks behind isolation and a test gate. The same run that would wreck a team on day one is safe on day 90, entirely because of what got built in between. The failure this ladder explains is starting at run — pointing agents at the highest-stakes work first, watching it go wrong in ways nobody catches, and concluding that agents don't work. ## Ladder two: agent count, and what it makes you The second ladder has 4 rungs, and the useful thing about it isn't the numbers. It's the way your *bottleneck* changes. | Rung | What you become | What constrains you | |---|---|---| | **Assisted** (~1) | A pair | **Your attention.** No self-verification yet, so you read everything and never look away. Work is synchronous — you sit and watch. | | **Parallel** (~10) | An orchestrator | **Review throughput.** You hand-write less and check several streams instead, each agent verifying itself before you see it. | | **Supervised** (~100) | A manager of managers | **Trust in the loop.** *"Did you read the code?"* stops being the right question. | | **Intent-steered** (1,000+) | A monitor by exception | **Knowing what to automate**, and matching guardrails to each kind of work. | The transitions matter more than the rungs, and both are things worth naming plainly. **Assisted to parallel needs a self-verification loop you trust.** Tests, build, lint, an end-to-end check against a real environment. Without it, going wide just multiplies output you have to read by hand — your attention was the bottleneck, and you made it worse. **Parallel to supervised needs a way for the agent to pull in context** — code, decisions, prior discussion. That's the contextbase, and it's the gating capability for autonomy. You cannot supervise what you can't equip. The stated trap at the third rung is worth quoting to yourself before every scale-up: **scaling agent count before the loop has earned trust.** ## Why they're orthogonal Here's the case that makes it concrete, and it's mine. For a long stretch I was running **one agent, unattended, overnight, on production code**, behind a test gate and worktree isolation. On ladder one that's *run* — the highest rung, genuinely autonomous work. On ladder two it's *assisted* — a single agent, and a pilot reading every diff over coffee the next morning. Neither ladder explains that team on its own. Ladder one says "advanced". Ladder two says "beginner". Both are true, and the pair is the accurate description. Plotting it makes the point immediately: ```text assisted parallel supervised intent-steered run ● ┌────────────────────┐ walk │ the graph is │ crawl │ earned in here │ └────────────────────┘ ● = one agent, overnight, well-fenced, every diff read ``` This is why single-number maturity scores mislead. The delivery-research community landed on the same conclusion years ago — [DORA](https://dora.dev/) measures several independent things precisely because one composite level hides more than it reveals. Compressing two real axes into one rung means the advice you get back is aimed at a team that doesn't exist. **Most adoption arguments are two people standing on different ladders, each certain the other is on the wrong rung.** ## Which rung earns the graph The two-axis view answers a question I get asked a lot, and answers it in a way a single ladder can't: *when should I start running agents in a fan-out?* **Topology is a parallel-to-supervised capability.** It sits in that band on ladder two, and it has a prerequisite that isn't optional: a self-verification loop you already trust. If your agents don't reliably prove their own work before you look, running 6 at once produces 6 streams of unverified output and a reviewing problem you can't staff. So the honest answer to *should I build a graph* is usually **not yet, and here's what to build instead** — the loop. Which is a much less exciting answer than the current enthusiasm suggests, and it's the one that actually holds. The reverse mistake is real too. A team stuck at *crawl* on ladder one, adding agents rather than raising the stakes of the work, ends up with 5 agents writing tests nobody needed. Moving up ladder one is nearly always the higher-value move, because it's what builds the verification that ladder two depends on. ## Ask which axis first The honest cost of the two-axis view is that it's harder to report. One number makes a nice slide. Two axes require a sentence, and the sentence is usually *"advanced on one, early on the other."* That sentence is worth the awkwardness, because it's the one that tells you what to do next. Advanced on risk and early on count means build the verification loop. Advanced on count and early on risk means you're spreading trivial work thin. **Ask which axis you're describing before you claim a level.** Most disagreements about adoption dissolve the moment somebody does. Start here: see [crawl, walk, run](/articles/crawl-walk-run-adopting-ai-agents), [why most agent pilots never reach production](/articles/why-agent-pilots-never-reach-production), or [read the method](/c2/method). --- # When can AI agents actually run in parallel? ## Two questions decide it, and neither of them is how many agents you have. - URL: https://stuartleo.com/articles/when-can-agents-run-in-parallel - Published: 2026-08-03 - Reading time: 8 min read - Method: C² Method Multi-agent vs single agent, decided by two questions: is there an edge, and is there a shared surface? When to fan out, sequence, or stay with one. The advice most people are given about running AI agents at the same time is a number. Don't run more than one. Or don't run more than three. Or run as many as you like, it's fine. All three are wrong in the same way, because the number was never the variable. I learned this expensively. I once pointed 5 agents at a single feature and got a mess I couldn't even write up afterwards. For a long time I told that story as a lesson about 5 being too many. It wasn't. All 5 were working on one branch, one working tree, and one settings object they each had a different opinion about. Two would have failed identically. ## The appeal of more agents, and the trap "Use more agents" is the most over-applied idea in agentic development. It sounds obviously right. A single agent is serial, so the dream is parallelism: split the work, run agents at once, finish faster. Different models have different strengths too, so the dream extends to the right model on each part. The appeal isn't wrong in principle. The problem is where people apply it, almost always to a single, shared problem, which is exactly where it backfires. Agents on one surface edit the same files and overwrite each other. They reason about the same problem and reach contradictory conclusions. And because there's no single coherent story of what happened, you can't even write a [session brief](/articles/write-your-first-session-brief) to record it. That was my 5-agent feature exactly. The guidance on running [multi-agent coding workspaces](https://www.augmentcode.com/guides/how-to-run-a-multi-agent-coding-workspace) keeps landing in the same place: the hard part isn't spawning agents, it's coordinating them. A crowd on one problem maximises the coordination cost while delivering little of the parallel benefit. **A swarm on one problem isn't parallelism. It's several confident agents disagreeing in the same files.** ## The rule people are given, and why it's too blunt The standard advice — *multi-agent is a sequential practice, not a parallel one* — is right about the failure it observed and wrong as a general law. It conflates two different things. **Contention** is two agents mutating the same thing at the same time. Real, expensive, correctly forbidden. **Concurrency** is several agents doing several bounded jobs that share nothing. That isn't a failure mode at all. It's just work getting done. Collapsing them into one rule bans the second in order to prevent the first. So here's the version that actually holds, and it's two questions rather than a headcount. ## Question one: is there an edge? An **edge** means one agent's output is another's input. Something actually crosses between them. The word that trips people is *after*. "Run the API work after the schema work" sounds like a dependency, and sometimes it is — if the API work reads the schema the first job produces, that's a genuine edge and the two must go in order. But "run the docs update after the tests" is usually not a dependency at all. It's just the order you happened to write them down. The test is to name what crosses. If you can name the artefact — *the schema*, *the route table*, *the migration* — it's an edge. If the only thing you can say is "it comes second", it isn't one, and you've been queuing for no reason. This is also why a lead agent and a review agent run in sequence and always will. The reviewer reads what the builder produced. You can't review an artefact that doesn't exist yet. That's a real edge, and it's the one that made the old rule look universal. ## Question two: is there a shared surface? A **surface** is everything an agent mutates or contends for. Files are the obvious part. The part that catches people is everything else — a database, a rate-limited external API, a message queue, a staging environment, one deploy target. Anything two agents both reach for. The failure has a name worth knowing: **false independence**. Two agents whose instructions never mention each other, quietly colliding over something neither brief declared. One writes a row the other deletes. Both burn the same API quota and one starts getting 429s. Both deploy to staging and the second overwrites the first. Hidden edges bite hardest, because nothing in the plan says they exist. When I check a plan now, I don't ask what each brief *writes*. I ask what it **contends for**. That check takes about 5 minutes and it's mostly already written down. If you use [prompt briefs](/articles/the-cascade-from-prd-to-prompt-brief), each one carries a pre-flight list of the files it will touch, and that list is most of the answer. Put them side by side and add the things a file list can't show: ```text PB-1 auth middleware files: src/auth/* also: sessions table, staging deploy PB-2 billing webhook files: src/billing/* also: Stripe test API (rate limited) PB-3 docs for both files: docs/* also: — edges none — no brief reads another's output surfaces PB-1 and PB-2 share nothing · PB-3 shares nothing verdict all three fan out ``` Three columns, one per brief. Files, then *everything else it reaches for*. If two rows collide anywhere in that second column, you've found a hidden edge and those two sequence. If nothing collides, they run at once. **Two agents on one surface is the anti-pattern, however urgent the session feels. Twelve agents on twelve disjoint surfaces, each with a brief that clears the quality gate, is the method working.** ## When more than one agent actually pays Put the two questions together and multi-agent pays off in two clear cases. 1. **Genuinely independent work.** Separate features or separate services, with no edge between the briefs and no shared surface, run in parallel, each agent isolated in its own [git worktree](/articles/parallel-agents-with-git-worktrees). 2. **Independent review.** One agent builds, a separate [bench agent](/articles/ai-code-review-with-a-bench-agent) reviews. Here the second agent's whole value is being separate: fresh eyes the builder doesn't have. Both avoid the trap. The agents either own different surfaces, or do different jobs at different times. They're never mutating one surface at once. ## Isolation solves one of these, not both [Git worktrees](https://git-scm.com/docs/git-worktree) are the standard fix for parallel agents, and they're genuinely good. A worktree is a second working directory attached to the same repository, checked out to its own branch, so each agent gets a filesystem nobody else can touch. But be precise about what that buys. **A worktree isolates the filesystem and nothing else.** Two agents in two immaculate worktrees still collide on one shared database, because the database was never in the worktree. So isolation is the seatbelt for one specific topology — parallel writes to files — not a general permission slip. It's worth using every time you fan out. It is not the thing that makes fanning out safe. ## The decision table Both questions, in one place: | Situation | What to do | |---|---| | One job, one surface | **One agent.** Nothing to spread. | | No edge, no shared surface | **Fan out** — one agent per surface, each isolated in its own worktree. | | Separate files, shared database or API or deploy target | **Sequence them.** That's a hidden edge, not independence. | | One agent's output feeds another's input | **Sequence them.** Real edge. | | Need an unbiased review | **Builder, then reviewer.** The review is an edge, so it runs after. | | Exploratory work you need to steer | **One agent.** Running wide buys breadth, not judgment. | | Tempted to swarm one hard problem | **One agent.** Swarming makes it worse. | The honest cost of the fan-out is that it asks you to do the thinking up front. You have to know what each job touches *before* you start, which means writing the brief properly rather than discovering the scope as you go. That's real work, and on a small change it isn't worth it. ## When not to bother Most days, don't. Skip it when the task is small or self-contained. Skip it when the work is exploratory and you don't yet know what you're looking for, because a wide run explores confidently in 6 wrong directions instead of 1. Skip it when the steps genuinely depend on each other. And skip it when you want to approve every step — that's a legitimate choice, and a fan-out is precisely the shape that runs without you watching each move. The tell is simple. **If you can't find two jobs with no edge between them, there's nothing to spread.** One agent working in sequence is the right answer, and it's the right answer far more often than the current enthusiasm suggests. Default to one agent. Add agents when you can name the surface each one owns and show that no two share one. ## The test is the surface The number of agents was never the thing. It's a proxy people reach for because it's easy to count, and it gets the diagnosis wrong in both directions — banning safe concurrency, and permitting 2 agents to trample one file because 2 sounds modest. Ask the two questions instead. Is there an edge, and is there a shared surface? Agents run at once when the answer to both is no. **The test is the surface, not the headcount.** Start here: see [the field note on running five agents at once](/articles/i-ran-five-agents-at-once-and-regretted-it), [how to isolate parallel agents with git worktrees](/articles/parallel-agents-with-git-worktrees), or [read the method](/c2/method). --- # Which layer broke your agent? Environment, loop, topology ## Most stalled sessions get debugged at the wrong altitude. - URL: https://stuartleo.com/articles/which-layer-broke-your-agent - Published: 2026-08-03 - Reading time: 7 min read - Method: C² Method At the 30-minute limit, name the layer that owns the failure before you escalate: the environment, the loop and its stop rule, or the topology. The [30-minute debug limit](/articles/the-30-minute-debug-limit) says stop and escalate. It's a good rule and I use it constantly. It has a gap, though, and I kept falling through it. It tells you *when* to stop. It doesn't tell you what to stop and look at — so the default is to reach for whatever you touched most recently, which is almost always the instructions. I've rewritten a prompt for 20 minutes when the actual problem was an expired token. I've redesigned a whole workflow when the actual problem was that nothing in it ever said what "finished" meant. Both times the fix was cheap and 40 minutes away, because I was working at the wrong altitude. So there's a question that belongs in the limit, before the escalation: **which layer owns this failure?** ## Stop and escalate — but escalate what? Three failures look nearly identical from where you sit. The agent isn't producing what you wanted, and it's been a while. They have completely different fixes, and the symptom that separates them is available in about 30 seconds if you know what to look for: | What you're seeing | The layer that owns it | |---|---| | **Cannot operate** — missing tool, stale state, bad permissions, no visibility into what happened | The environment | | **Almost works but unreliable** — close-but-weak output, inconsistent success, no proof it finished | The loop and its stop rule | | **The process itself is complex** — several specialisms, approvals, branching, work that keeps getting dropped | The topology | Name the layer, then escalate into that layer. Most stalled sessions I've watched — mine and other people's — get debugged one layer away from where the problem lives. ## Cannot operate: the environment Start here, always, because it's the cheapest to rule out and the most embarrassing to miss. The tell is output that's confidently wrong in a way that suggests the agent never actually saw the thing it's describing. It reports a file's contents that don't match the file. It says a command succeeded when nothing ran. It reasons beautifully about a database it couldn't connect to. That isn't a thinking failure. The agent couldn't reach something and produced its best guess instead, because producing a plausible answer is always available to it. What to check: - **Tool access.** Can it actually run the command, read that path, hit that endpoint? Not "is it configured" — has it done it, and did you see the output? - **Stale state.** Expired credentials, a cached value, a branch it checked out yesterday, a server that isn't running. - **Permissions.** Read where it needs write. Sandboxed away from the thing it's been told to change. - **Visibility.** Can *you* see what it did? If a run produces no log you can inspect, you're debugging by seance. Environment mismatches are a solved problem in ordinary software — the [dev/prod parity](https://12factor.net/dev-prod-parity) discipline exists because differences between where you built and where it runs cause exactly this class of confident failure. Agents inherit all of it and add a new twist: they'll narrate right past the gap rather than crashing at it. **An agent that can't reach something doesn't stop. It writes a sentence about what would probably be there.** ## Almost works but unreliable: the loop Second layer. The agent *can* operate — it's reaching everything, the tools fire, you can see the output. It's just not reliably finishing. The tells: it gets 80% there and stops. It succeeds on Tuesday and fails on Wednesday with the same input. It reports completion and the work isn't done. It retries forever, or gives up after one attempt, with no apparent logic to either. That's the loop — the repeated cycle of act, check, adjust — and the part that's usually missing is the **stop rule**. If nothing in the loop defines what finished looks like in terms the agent can check, then "finished" collapses into "produced a plausible final message", which it can always do. The fix is an anchor: a signal it can't produce by asserting it. A test that ran. A query that returned rows. A deploy that resolved. *"The agent says it's done"* is a report about the work, not the work. Don't loop on confidence — loop on evidence. This is also the layer where instruction quality genuinely matters, and it's the only one of the three where rewriting the prompt is the right first move. Which is why the default reflex isn't stupid — it's just applied to all three. ## The process itself is complex: the topology Third layer, and the rarest. The environment is fine. The loop has a stop rule and honours it. It still doesn't work, and the failure looks like *dropping things*. The tells: the job has several genuinely different specialisms in it and each pass does some well and some badly. There's an approval or a branch in the middle that one pass can't represent. Coverage is inconsistent in a way that isn't random — the same kinds of things get missed. That's a shape problem. The job was too big for one node, and no amount of instruction-rewriting fixes a job that needed splitting. The move is to break it into bounded jobs with contracts, decide which of them are actually independent, and put something at the end that merges the results. A caution though, because this layer is where the current enthusiasm points: **it's the least likely answer.** Most stalls are environment or loop. Reaching for a redesign first produces an elaborate structure around a problem that was one expired token, and now you have two problems. ## Running the triage in practice At 30 minutes, before touching anything: 1. **Can it operate?** Look at one piece of raw output — a real command result, a real file read. Not the agent's summary of it. If you can't find one, that's your answer. 2. **Does it know what done means?** Look for the anchor. If nothing in the job can be checked without asking the agent, fix that before anything else. 3. **Is one pass the wrong shape?** Only if the first two are clean. And if you can't name two parts of the job that don't depend on each other, it isn't a topology problem either. Then escalate into that layer — fresh context, a reframe, a stronger model, or your own eyes, as the debug limit already prescribes. The triage doesn't replace the escalation. It aims it. **One thing this is not:** these three layers describe *what broke*. They're a diagnostic. They are not the same as C²'s stack of *what you build* — [prompt inside context inside harness](/articles/what-is-an-agent-harness), where each layer contains the one before it and C² sits at the harness level. Different question, different three. Keep them apart, because collapsing them produces a conversation where nobody can tell whether "harness" means the machine you built or the thing that just broke. ## Aim before you escalate The limit was always right that more attempts don't help. What it was missing is that *the right next move depends on which layer failed*, and the three look alike from outside. Check whether it could operate. Check whether it knew what done meant. Only then ask whether the job was the wrong shape. Cheapest first, rarest last. **Name the layer that owns the failure before you touch anything — most stalls get debugged at the wrong one.** Start here: see [the 30-minute debug limit](/articles/the-30-minute-debug-limit), [how to run agents overnight safely](/articles/run-agents-overnight-safely), or [read the method](/c2/method). --- # Your agent fleet forgets everything ## Eighteen agents, one answer, and nothing left behind. - URL: https://stuartleo.com/articles/your-agent-fleet-forgets-everything - Published: 2026-08-03 - Reading time: 5 min read - Method: C² Method A fleet fans out, converges, prints an answer, and the shape that produced it evaporates. A field note on what makes an expensive run worth doing twice. I ran 18 agents across a codebase last month to find everything wrong with one subsystem. It worked. It took about 40 minutes, cost more than I'd like to write down, and produced a genuinely good report — 12 real findings, ranked, with file references that held up. I fixed 4 of them that week. Then I moved on. Three weeks later I needed to know something about the same subsystem, and I had nothing. Not the report — I could find that. I had nothing that made the *next* run cheaper than the first. I was going to have to do the whole thing again. ## The bit that impressed me, and the bit that should have The impressive part was the fan-out. One instruction, 18 agents, each taking a different angle, converging into one ranked answer. That's a real capability and it wasn't possible for me two years ago. The part I should have been watching was what happened afterwards, which was: nothing. The 12 findings existed in a report. The report existed in a chat window. Nothing about *how* I'd got them — which angles were worth taking, which two agents kept colliding, which parts of the subsystem turned out to be a swamp — existed anywhere at all. The run had produced an output and no guidance. That's the distinction the whole method turns on. **A codebase is what runs. A contextbase is what guides.** I'd generated a lot of the first kind of value and none of the second. ## Twelve findings, twelve forgotten Here's what actually evaporated. Four findings got fixed, and the reason each one was a problem went into a commit message, which is the worst searchable place I own. The other 8 were real and I didn't get to them — so they're gone, and the next run will rediscover them at full price. This is [the agent relearning problem](/articles/how-to-stop-your-agent-forgetting) at fleet scale, which is the same problem costing 18 times as much. Worse, the *structure* went too. During the run I'd worked out that splitting by directory was useless and splitting by concern — auth, data access, error handling — produced far better coverage. That took me two bad attempts to learn. It survived in my head for about a week. Anthropic's own writeup of [building a multi-agent research system](https://www.anthropic.com/engineering/built-multi-agent-research-system) is candid about how much of this work is orchestration design rather than model capability — which angles, which splits, how the results come back together. That design is the expensive part. Mine went in the bin. **A fleet without a contextbase produces 12 findings and forgets all 12. The findings were never the asset. The shape that found them was.** ## What survived, and what didn't Sorting it afterwards was clarifying, because the pattern is stark: | What the run produced | Where it went | Still useful? | |---|---|---| | 12 findings | A chat window | No | | 4 fixes | Commit messages | Barely | | 8 unfixed findings | Nowhere | No | | "Split by concern, not directory" | My head | For about a week | | The prompt that produced good splits | Nowhere | No | Everything in that table that had a *file* survived. Everything that didn't, didn't. That's not a subtle lesson. ## The graph is an artefact, and it should be in git Here's the claim I've landed on, and it's the one thing in this note I'd defend hardest. **A saved orchestration graph is not code. It's context.** It doesn't ship to users. It doesn't run in production. It directs execution — which is precisely what a prompt brief does, and what a Router does, and what a gotcha does. By the definition C² already uses, that puts it in the contextbase, not the codebase. And it's the densest form of context I've come across. A topology that worked once, version-controlled, re-runnable by name by anyone who clones the repo. Not a description of how to review a subsystem. The actual review, ready to fire again. ## What I do now Three changes, all cheap, none clever: 1. **Every node writes what it learned to `03-knowledge/`**, not just its finding. The finding goes in the report. The *gotcha* goes in git, where the next session reads it before touching that code. 2. **The merge step deduplicates against what's already known**, rather than re-discovering it. That alone made the second run of the same job noticeably cheaper, because 3 of the 12 were things I'd already written down. 3. **The orchestration itself gets saved and named.** Whatever your agent calls its workflow directory, it belongs alongside `docs/` and it belongs in the [Router](/articles/what-is-a-contextbase) — the file your agent reads first. If a shape worked, it's an asset. Treat it like one. The honest cost is that all 3 are discipline at the exact moment a run finishes and you feel done. That's the worst moment to rely on discipline, which is why the write-down has to be part of the run rather than a good intention afterwards. ## The findings were never the asset An expensive run that produces a good answer and nothing else is a purchase, not an investment. You bought an answer. You'll buy it again next month. The version worth running is the one that leaves something behind — the gotchas in git, the dedupe that gets cheaper each time, the shape saved under a name. That's the difference between running a graph and compounding one. Start here: see [what a contextbase is](/articles/what-is-a-contextbase), [how to stop your agent forgetting](/articles/how-to-stop-your-agent-forgetting), or [read the method](/c2/method). --- # The Fifteen Percent Sony Couldn't See ## Sony is cutting physical discs — a line already down to about 15% of sales. On the spreadsheet it's an obvious cut. But that 15% was holding up four things the spreadsheet never showed. - URL: https://stuartleo.com/articles/the-fifteen-percent-sony-couldnt-see - Published: 2026-07-27 - Reading time: 9 min read - Method: Essay Sony is killing the PlayStation disc — just 15% of sales, but the last thing securing ownership, resale, a price ceiling, and its own antitrust defence. Sony is cutting a line that accounts for about 15% of its sales — and more than 320,000 people signed a petition to stop it. That gap, between how small the cut looks and how hard people are fighting it, is the most useful thing an operator can study this month. On [1 July, Sony announced](https://www.tomshardware.com/video-games/playstation/playstation-disc-petition-approaches-200000-signatures) that from January 2028, new PlayStation games will be digital-only. No more discs for new titles. Download it, or don't play it. On the numbers, this is the easiest decision a business ever makes. In the quarter ending this March, [about 85% of PlayStation's full-game sales were already digital](https://startupxo.com/en/news/2026/07/2026-07-02-sony-physical-media-end-game-economics/) — 15% physical, and falling. The revenue gap is starker still: roughly $1.5 billion of digital that quarter against $109 million from discs. A shrinking, expensive, low-margin sliver. Any competent operator looks at that and reaches for the knife. So sit with the strange part. Three hundred and twenty thousand signatures. A €400 million class action in the Netherlands, a £2 billion case in the UK. Politicians, retailers, even late-night comedians. Why would anyone fight that hard to save 15% of somebody else's sales? That is the whole question. And the answer is a distinction most leaders never make on purpose — the difference between managing a line item and leading a relationship. ## Be fair to Sony first The honest version of this is stronger than the cheap one, so let me make the case *for* the decision before I turn it. Sony's stated reason is true. People genuinely moved to digital — nobody made them. When four out of five games sell as downloads, keeping a global disc-manufacturing and distribution operation alive for the fifth is real cost, real complexity, real inventory, for a shrinking return. Put that in front of a hundred CFOs and a hundred of them cut the disc. And the revolt, loud as it is, mostly comes from people who already buy digital. It's real in voice and a minority in wallet. The market didn't disagree with Sony. The market mostly already agreed. So this is not a story about a stupid decision, or a greedy one. If it were, it wouldn't be worth your time. It's worth your time because the decision is defensible, the logic is clean, and it still might be a mistake — and the reason why is the part that transfers. ## What the 15% was actually holding up That fifteen percent wasn't just fifteen percent of revenue. Watch what it was doing. The disc was the last thing that let a customer *own* a game. Buy a download and you don't own it — you licence it. If the store delists the title or the servers go dark, the thing you paid for quietly disappears. The disc was the proof of purchase you could hold in your hand. The disc was the entire resale market. Every used copy, every lend to a friend, every trade-in — gone. As one analyst put it, every resale and rental is value flowing to players and retailers instead of to the platform. The disc was that value, in physical form. The disc was the ceiling on Sony's own prices. As long as a physical copy existed, a price-sensitive buyer had somewhere else to go — the used shelf. Remove the disc and the only door left is Sony's own store, at Sony's own price, minus [Sony's 30% cut](https://www.techtimes.com/articles/319769/20260706/playstation-disc-reprints-confirmed-post-2028-purchases-carry-no-ownership-rights.htm). In the Netherlands, buyers already pay roughly 47% more for the digital version than the physical one. The disc was holding that number down. And here is the one nobody saw coming. The disc was Sony's own legal defence. For years, whenever regulators came sniffing about monopoly, Sony pointed at physical retail and the used-game market and said, in effect: *look, there's competition, there are alternatives, we don't control the whole thing.* A marketing professor at Johns Hopkins [said it cleanest](https://fortune.com/2026/07/09/sony-playstation-discs-lawsuit-xbox-antitrust/) — by phasing out physical discs, Sony essentially destroys its own defence. Cut the 15%, and you hand the plaintiffs their argument. Ownership. Resale. A price ceiling. A legal shield. All of it riding on the line item that looked small enough to cut. ## Managing a line, leading a relationship In the work I do, there is a tension that sits underneath every growing business, and this is the cleanest example of it I've seen in a public decision all year: the tension between *leading* and *managing*. Managing is making sure the right things get done, the right way, at the right time. Execute the plan you've got. Drive out cost. Remove variance. Hit the number the quarter is asking for. It is a real, essential, honourable job — and it is exactly the job that kills the disc. Everything management is built to do points at that cut. The disc is cost. The disc is variance. The disc is a shrinking line on a page. Leading is a different job. Leading is about beliefs and behaviours — moving people, and a business, toward a future that doesn't exist yet. And leadership asks a different question than management does. Management asks: *what does this thing cost me?* Leadership asks: *what does this thing hold together?* Sony answered the management question flawlessly. Fifteen percent, shrinking, expensive — cut it. It never asked the leadership one. Because the moment you ask what the disc holds together, you get a completely different answer, and you would never dare touch it. ## The company that forgot why it won The sharpest proof that this is a management decision wearing leadership's clothes is that Sony has stood in this exact room before — on the other side of the table. In 2013, Microsoft launched the Xbox One with restrictions on resale and an always-online check. Gamers revolted. And Sony — this same company — [stood up and made a promise](https://fortune.com/2026/07/09/sony-playstation-discs-lawsuit-xbox-antitrust/): the PlayStation would let you share your games, resell your games, keep your games. No restrictions. That one customer-first stand won Sony the entire console generation. That was leadership — not the warm kind, the sharp kind. In 2013, Sony understood that ownership was load-bearing. That people would forgive a lot, but not the feeling that they didn't own what they'd bought. Sony read the belief under the behaviour, and led to it. Thirteen years later, the same company is making Microsoft's 2013 bet. The exact one it beat. It is looking at the same disc — the thing that won it the war — and this time it sees only the cost. That is the switch. Same company, same decision, same disc. In 2013 they led it and won. In 2026 they're managing it, and calling it the future. The disc is where you can actually watch a business trade one for the other. ## The operator's read You don't run Sony. Neither do I. But you have a disc — I promise you that. Here is how I'd use this. ### 01 — Go find your disc It's a line item that's small on the P&L and load-bearing for trust. The free tier almost nobody converts from — but everybody checks before they buy. The phone number a human still answers, that costs you a salary and gets used twice a month, and is the reason a customer picked you over the cheaper option. The no-questions-asked refund. The founder who still replies personally. Small on the spreadsheet. Holding up the ceiling. You know what yours is. ### 02 — Change the question before you cut Management will tell you what it costs, and management will be right — measured directly, it probably does cost more than it earns. That's not the question. The question is what it *holds together*. What breaks the day it's gone. Sony could see the 15% of revenue with perfect clarity. It could not see the ownership, the resale market, the price ceiling, and the legal defence — because none of those show up on the line you're cutting. They show up everywhere else, later, all at once. ### 03 — Protect the thing that won you the market The thing that won you your market is very often the thing that looks least efficient on the way up. The generous policy. The slow, human, expensive touch. The stand you took when it cost you something. Management logic flags exactly those first, because they're the ones that don't pay for themselves in a straight line. So when you catch yourself about to optimise away something that used to be your whole edge — stop. That's not fat. That might be the spine. ## The takeaway Most operators think the danger is the big, obvious cost — the thing everyone is watching. It isn't. Big costs get scrutinised precisely because they're big. The thing that gets you is the small line — the one so clearly inefficient that cutting it feels like discipline, and that nobody notices is holding up four other things until they're gone. Sony found its. Fifteen percent of sales, and one hundred percent of the reason its customers believed they owned what they bought. On the spreadsheet, an easy cut. In the relationship, load-bearing. Management asks what a thing costs you. Leadership asks what it holds together. Before you cut the small thing, find out what it's load-bearing for. That's what I have for you this week. Operator to operator. I'll see you next week. --- *This is Episode 9 of Commander in Brief. The tension at the centre of it — leading versus managing — is the first of the three tensions in [Resolute](https://www.amazon.com.au/Resolute-navigate-disruption-indestructible-organizations/dp/0645825425), in print since December 2024. For the deeper version, read [The Three Tensions](/articles/the-three-tensions). For the same kind of decision made the other way, read [The 8,500 IKEA Didn't Fire](/articles/the-8500-ikea-didnt-fire).* --- # IKEA Automated 47% of Its Calls — and Didn't Fire Anyone ## A chatbot named Billie now resolves nearly half of IKEA's customer contacts. The obvious move was to cut the call centre. IKEA did the opposite — and found a new business hiding inside the work the bot couldn't do. - URL: https://stuartleo.com/articles/the-8500-ikea-didnt-fire - Published: 2026-06-29 - Reading time: 9 min read - Method: Essay IKEA's chatbot resolved 47% of contacts. Instead of layoffs, it retrained 8,500 staff into design advisors — a lesson in leading people, not managing them. A chatbot at IKEA started resolving nearly half of all customer contacts. The obvious move was to cut the call centre. IKEA did the opposite — and the opposite is the most useful thing an operator can study this week. In 2021, [Ingka — the company that runs most of the IKEA stores on earth](https://www.ingka.com/newsroom/ai-and-remote-selling-bring-ikea-design-expertise-to-the-many/) — switched on a customer-service bot called Billie. Nothing remarkable about that. Every retailer was doing it. The remarkable thing is what Billie became good at. By the numbers IKEA has put on the record, Billie now resolves around 47% of customer contacts. Nearly half. Something like 3.2 million conversations that used to need a person, handled without one. The operating saving runs to roughly €13 million. You know the next move. Everyone knows the next move. Half your contact volume just stopped needing humans, so you thank the humans, and you let a good number of them go. That is the script the last three years of headlines have trained everyone to expect. Automate the work, subtract the worker, book the saving. IKEA didn't run that script. And the reason it didn't comes down to one distinction most leaders never make on purpose — the difference between a thing you manage and a person you lead. ## What IKEA actually did Let me keep this to the one division, because IKEA is a giant and most of what a giant does doesn't transfer. This part does. Take just the customer-service function. Billie absorbs the simple, repetitive, high-volume contacts — where's my order, how do I return this, what are your hours. The easy half. What's left over is the hard half. The contacts a bot escalates. The ones that need judgement, patience, a human who can actually picture the problem. IKEA looked at that leftover pile and did something genuinely clever. It didn't read it as a cost to keep grinding down. It read it as a map. The contacts Billie couldn't handle were a signal. They were the company telling itself, in its own data, exactly where human beings were still worth the most. And the richest part of that leftover wasn't complaints. It was design. People who didn't want a returns label — people who wanted help deciding what to actually buy for an awkward corner of a real room. So since 2021, IKEA has [retrained around 8,500 call-centre co-workers](https://www.pymnts.com/news/artificial-intelligence/2026/ikea-turned-8500-call-agents-into-design-consultants/). Not into nothing. Not into a severance queue. Into remote interior-design advisors — people who get on a video call, look at your space, and help you spend money well. That channel reached €1.3 billion in a single year. More than 73,000 customers have used the design help, and IKEA's stated target is for remote selling to carry 10% of sales by 2028, up from low single digits. Be careful here, because the honest version is stronger than the hyped one. I am not telling you 8,500 retrained workers generated €1.3 billion. That is not the claim. The retraining staffed and enabled a channel that grew to €1.3 billion. The causation is loose, and these are IKEA's own numbers, not an audited result. Hold them as company-reported. But the shape of the decision is not in dispute. Faced with a machine that cleared half the floor, IKEA used the space to move people up into higher-value work — and it funded a growth engine instead of trimming an overhead. ## A thing you manage, a person you lead In the work I do, the second of the five foundational principles in the Resolute system is four words long. Lead people, manage things. It sounds like a slogan. It is actually a warning. The full version goes: leadership is not management, and the difference creates a positive tension when you apply it correctly — and a destructive one when you collapse it into a single job. Sit with that word. Collapse. Here is what automation does to most leaders. It is the most powerful management technology ever built. It standardises, it scales, it removes variance, it drives cost out of a process — that is the entire point of it. So when a tool that good lands on the desk, the gravitational pull is to point it at everything. Including the people. To let the same logic that optimised the workflow optimise the headcount. And the moment that happens, the two jobs have collapsed into one. The leader is now *managing* the people — treating them as a line in the same spreadsheet as the chatbot, a variable to be reduced. The leading has stopped. That is the trap. Not the automation. The collapse. What IKEA did — and this is the whole lesson — was refuse to collapse it. It let Billie be a thing it managed. Manage the bot, optimise the bot, drive the cost out of the bot, all of it, no sentiment. But the people the bot freed up stayed on the other side of the line. They were still a thing to be *led* — developed, moved, pointed at work that was worth more. Two jobs. Held apart. That is the positive tension the principle is talking about. And notice what holding the tension unlocked, because this is the part most leaders never get to see. The cost-out company stops at the saving. Thirteen million euros, banked, done — and that number can never be larger than the current wage bill. It has a ceiling. The lead-people company kept going, and the redeployment opened a revenue line. A revenue line has no ceiling. The leader who collapses the two jobs gets the saving. The leader who holds them apart gets the saving *and* the growth. Same chatbot. Same 47%. Completely different company on the other side of the decision. IKEA's own data chief [put it more plainly than I can](https://www.ingka.com/newsroom/chief-data-analytics-officer-at-largest-ikea-retailer-says-ai-can-design-your-home-but-humans-make-it-feel-like-one/): *we have to make AI work for humans — humans should not work for AI.* Or the line I keep coming back to — *AI can design your home, but humans make it feel like one.* ## The operator's read You don't run IKEA. Neither do I. So here is how it lands for the $5–50 million operator, because this principle scales down better than almost anything else in the model. ### 01 — Force the two decisions apart on paper The next time you automate anything, write down what the machine took over. That is the management decision, and you should make it coldly. Then, on a separate line, write down who just got freed — and treat that as a completely different question. The mistake is letting the savings number auto-answer the people question. It shouldn't. They are not the same job. Don't let the spreadsheet collapse them for you. ### 02 — Read what the machine can't do as your demand map This is the move to steal from IKEA wholesale. The work your automation keeps escalating to a human — the residual, the leftover, the hard half — is not a backlog. It is a signal showing you exactly where human judgement is still concentrated, and that work is almost always your higher-margin work. The bot isn't just clearing the floor. It is drawing you a map of where to send your people next. ### 03 — Be honest about what you instrumented for This is the one that costs, because it asks you to admit what you actually built the business case on. Most automation gets sold internally as cost-out — headcount down, saving booked, board happy. But cost-out is a one-time win that caps at today's wage bill and then it's gone. Redeployment is a revenue line with no cap. So look at your last automation project and ask the honest question: did I instrument it to subtract people, or to move them up? You tend to get exactly the one you measured for. If the only number on the slide was the saving, the saving is all you were ever going to get. ## The takeaway Most leaders think the hard part of automation is the technology — picking the tool, training the model, getting Billie to resolve 47% instead of 30. That part is just management. It's a thing. You'll figure the thing out. The hard part is the decision the machine hands back the moment it works. It clears a space, and then it asks a question it cannot answer — what are these people for now. That is not a cost question. It is a leadership one. The companies that hear it as a cost question lay people off and book a saving with a ceiling. The companies that hear it as a leadership question move people up and open a line with no ceiling. IKEA heard it right. It read a chatbot's failures as a map of where its people were still worth the most, and it walked 8,500 of them toward that work instead of out the door. Automation is a thing you manage. What you do with the room it clears is a thing you lead. Don't collapse the two — the whole difference between cost and growth is living inside that one decision. That's what I have for you this week. Operator to operator. I'll see you next week. --- *This is Episode 8 of Commander in Brief. The principle at the centre of it — lead people, manage things — is the second of the five foundational principles in [Resolute](https://www.amazon.com.au/Resolute-navigate-disruption-indestructible-organizations/dp/0645825425), in print since December 2024. If you want the operator's working definition of how AI actually changes a business, start with [AI Business Engineering](/articles/ai-business-engineering-a-working-definition).* --- # Flight Planning: file the plan before you take off ## A pilot files a plan before takeoff. So should you, before an agent burns a build session on the wrong heading. - URL: https://stuartleo.com/articles/flight-planning-before-the-build - Published: 2026-06-26 - Reading time: 10 min read - Method: C² Method Flight Planning is the C² review where you file your plan — scope, briefs, and ETA — before an agent builds. What it is, who's in the room, and why. Here's the failure mode nobody warns you about. You hand an agent a [PRD](/articles/what-is-a-prd-in-ai-development) — the product requirements doc that says what to build — and you let it fly. Three hours later you have a confidently-built feature pointed at the wrong city. At human speed, a wrong heading costs an afternoon. At agent speed it costs a whole session, and you don't find out until you read the diff. Flight Planning is the fix. Before you build, you stop and file a plan — what you're building, how, and when you'll land — and you put it in front of other people. A pilot doesn't take off without filing one. Neither should you. ## A vague plan, at agent speed, is the expensive kind The cheapest place to catch a wrong heading is on the ground. Not at 30,000 feet, mid-session, with the fuel already burning. That used to be a nice-to-have. When a person wrote the code, a half-formed plan self-corrected as they typed — they noticed the gap on line 40 and fixed it. An agent doesn't hesitate. Hand it an autonomous session — a build it runs end-to-end without you in the loop — and it executes the ambiguity at full speed, making every unstated decision at once, confidently, in one large diff. So the economics flipped. The plan is no longer paperwork you produce after you know what you're doing. It's the thing that decides whether the session is worth running at all. ## From crew on a boat to pilot of your own PRD The shift underneath this is bigger than a meeting. It's a change in what you are. The old model was a crew on a single boat. One sprint, one shared backlog, you pull a rope on a vessel someone else is steering, and your work only makes sense as part of the whole crew's effort. The new model gives you your own aircraft. One PRD, one owner, your flight path to fly. That's why a PRD should be scoped to one person and roughly a week of work — a pilot flies their own plane, they don't share a tiller. And the moment everyone has their own aircraft, you need air traffic control. A crew on one boat coordinates by being in the same hull. A fleet of solo pilots coordinates by **filing flight plans** — this is where I'm going, this is what I'll build, these are the milestones, and this is when I'll land. Then everyone knows who's flying what and when they're due down. If a plane doesn't land on time, someone goes looking, instead of discovering the wreck a fortnight later. Two things matter when you file. Be realistic — don't try to be a hero. About a week of work is a healthy range, the same fixed-appetite instinct that makes [Shape Up](https://basecamp.com/shapeup) work. And if the PRD is bigger than that, the plan isn't the first job — splitting the PRD is. ## What a filed plan contains A flight plan has five parts. Four are the work. The fifth is optional, and underrated. - **The line** — the explicit scope boundary. *This is what I'm going to build, and this is what I'm not.* Drawing the line is the act that turns a wish into a route. - **The briefs** — the [Prompt Briefs](/articles/the-cascade-from-prd-to-prompt-brief), one per atomic unit of work, each carrying [testable acceptance criteria](/articles/acceptance-criteria-for-agents). A single PRD often files as 6 or 7 of them. - **The journey** — milestones, a believed landing point, and an ETA. Not a hard deadline. A filed expectation, so deviation is visible. - **The shape** — how the briefs are wired to each other. Which ones are independent and could run at the same time, which are joined by an edge and have to go in order, where they come back together, and which results get a second pair of eyes before they count. - **The red line** *(optional)* — something tangible to react to. A couple of screens mocked up, even thrown together in an hour, just to bounce off. It's the red line drawn on a map between two cities. You'll bin it, but it translates the idea faster than a paragraph ever will. Filed, it's a one-screen summary anyone can read in a minute: ```text Flight plan — project landing page The line in: routing, tabs, feed cards · out: mobile, video reports The briefs PB-1 redirect · PB-2 sticky tabs · PB-3 feed cards (each: goal, scope, AC) The journey 3 briefs · lands ~Thursday The shape PB-2 + PB-3 independent · PB-1 → PB-2 (route table) · merge at the PR Red line 2 mocked screens (optional) ``` The journey says *when*. The shape says *how the work is wired*, and it's the part I added last because I'd been filing a queue and calling it a route. A pilot files a route. It costs almost nothing to add, which is the part I like. Every brief already carries a pre-flight table listing the files it will touch, and that table is a declaration of the brief's **surface** — everything it mutates or contends for. The arrows are derivable from something the plan already produces. It just stopped short of drawing them. Watch for the surfaces a file list doesn't show, though: two briefs whose pre-flight tables don't overlap can still both hammer one staging database, and that's the edge that bites, because nothing declares it. And if I can't find two briefs with no edge between them, there's no shape to draw. I say so and file four parts. Spreading work wide buys breadth. It doesn't buy judgment. (The longer version of why work has a shape at all: [the shape of the work is a graph](/articles/the-shape-of-the-work-is-a-graph).) One caution: the flight plan doc is a throwaway. Your [PRD and its briefs](/articles/the-cascade-from-prd-to-prompt-brief) stay the single source of truth. After the review, fold the decisions back into them and bin the plan. A second place that claims to be the truth is just confusion waiting to happen. ## Who's in the room This is the part the agent era quietly erodes, so I'll say it plainly: file the plan in front of *people*. Working alone with a capable agent is fast and frictionless, and it's easy to never put your plan in front of another human. That's a trap. The agent is a calculator — rational, quick, and not remotely contextual. It will not think like your UX lead or your head of sales. That's the human's job, and the flight plan review is where it happens. **The agent sorts out the code. The humans bring the questions. That's the division of labour worth protecting.** Keep the room small but cross-disciplinary. The pilot, someone from software, a UX voice — and, when the work touches them, sales, finance, or whoever owns the end result. A scope problem caught by UX, or a commercial problem caught by sales, is trivial to fix in the plan and expensive to fix after the build. The review isn't a judgment. It's a bounce — several disciplines stressing the route while it's still cheap to change it. Here's the honest cost: this asks you to stop and gather people before you've written a line, which feels slower in the moment. It is slower in the moment. It is much faster across the whole build, because the rework you didn't do never shows up on the bill. ## The skill, and where it stops I built a skill to prepare the plan — `flight-plan`. A skill is a packaged capability the agent runs on demand, a documented job with a fixed protocol. You invoke it in plain words: *run flight-plan on this PRD.* It reads the PRD, proposes the scope line, interrogates the spec for what's over- and under-specified, drafts the briefs, plots the journey, and draws the shape. Then it stops. The skill files the plan and goes no further — it never builds, never takes off. Drawing a graph is not permission to fly it. Takeoff is a separate, human-gated step, which is the entire point of filing first. A second agent works the other end. Where `flight-plan` *builds* the plan, a review-only verification agent *stress-tests* it — checking the acceptance criteria are actually testable and surfacing what the review still needs to decide. One proposes, the other challenges. It's the same [pilot-directing-the-agents](/articles/the-pilot-model-directing-ai-agents) discipline C² runs everywhere, pointed at the plan instead of the code. ## And close it when you land A filed plan has a second end, and I missed it for months. In aviation, filing isn't the whole ceremony. You close the plan on arrival. Land without closing it and air traffic control starts a search, because an open plan means an aircraft unaccounted for. I'd been using the metaphor for a year and only ever using half of it. The cost showed up exactly where you'd expect. The gotcha that never got written down. The PRD still marked in-progress six weeks after it shipped. The estimate I never once checked against the actual. **Closing the Flight Plan** is the gate at the other end. Four parts, one screen: - **The landing** — what actually got built, against the line I drew. - **The deviation** — where the route changed and why. Zero judgment. The plan exists to make drift visible, not to punish it. - **The anchor** — the evidence that decides done. Tests that ran. The query that returned rows. The deploy that resolved. Not *the agent says it's done*. - **The learning** — what the contextbase gains. The gotcha, the pattern, the honest completion rationale, estimated against actual. It isn't a demo and it isn't a retro. It's a gate, and somebody in it has to have the authority to say *not yet*. With a team that's two people — whoever owns the intent and whoever owns the implementation. On my own it's me, reading the diff and asking whether the agent did what I actually wanted. Same ceremony, different weight. And if you build alone, you're the reader who most needs this one and most easily skips it. Here's why it matters more than it sounds. **Filing is where context gets spent. Closing is where context gets made.** Every artefact that makes the next session cheaper — the gotcha, the pattern, the decision record — gets written at the exact moment I feel finished and least want to write anything. A ceremony is what survives that moment. Good intentions aren't. There's more to it than fits here — the three gates and why they sit at different altitudes, how the findings need structure to survive the room, and why the *next* plan does the tidying. [The full ceremony is here](/articles/closing-the-flight-plan). ## File the plan before you fly Deviation in the air is fine — plans change, and you're the pilot. What's not fine is a wrong heading nobody can see. So you file a flight plan before takeoff — the line, the briefs, the journey, the shape — reviewed out loud by the people who'll feel the result. Then you close it when you land. Do that, and the wrong heading gets caught on the ground rather than at 30,000 feet with the session already burning. And the flight you did fly leaves something behind for the next one. Start here: [read the method](/c2/method), [run your first session](/c2/start), or [browse the docs](/c2/docs). --- # Four AI Giants, Four Doors, One Lesson in Strategy ## OpenAI, Anthropic, Google, and xAI all build the same technology. None of them is fighting the same war — and that's the cleanest positioning masterclass running in public right now. - URL: https://stuartleo.com/articles/the-four-doors - Published: 2026-06-22 - Reading time: 10 min read - Method: Essay OpenAI, Anthropic, Google and xAI aren't competing on the same axis — each claimed different real estate in the customer's mind. Porter's doors, read through the AI race. *Editor's note (June 2026): since this published, OpenAI and Anthropic have both filed to go public within a week of each other. The dual filings sharpen the argument below rather than soften it — two companies, the same act, two completely different stories. An IPO is a financing event, not a change of position.* The four biggest AI companies refuse to stand in the same room. OpenAI, Anthropic, Google, and xAI all train large language models. On a spec sheet they look like four versions of one product. Then you watch what they actually do — where they spend, who they sell to, what they say they are for — and the four blur apart into four completely different businesses. That is not an accident. It is the single cleanest worked example of strategy I have seen since [Nike forgot what it was selling](/articles/nike-forgot-what-it-was-selling). And it is happening in public, in real time, funded by the most sophisticated capital on earth. If you run a business in a crowded market — and almost every market is crowded now — this is the most useful thing you can study this week. Not because you are building AI. Because the four smartest, best-resourced teams alive are showing you, live, what positioning actually looks like when it is done on purpose. ## The three doors Michael Porter of Harvard defines strategy as the creation of a unique and valuable position involving a different set of activities. Porter draws one hard line — between merely doing the same things better, which he calls operational effectiveness, and genuine strategy. The way I teach that line is as three doors. Door one — same activities as your competitors, done a bit better. You are playing the same game, trying to be more efficient at it. Useful. Porter is blunt that it is not strategy. When everyone competes on the same activities, the differentiation collapses and you compete on price. Door two — same activities, done the same way. The danger zone. You are indistinguishable, and price is the only lever left. Your margin is whatever the cheapest competitor decides it should be. Door three — strategy, which Porter draws wider than most people remember. A different set of activities to solve the customer's problem — or the same activities performed in a genuinely different way. A distinct set of moves that produce a distinct outcome, and a position nobody else is occupying. Here is the trap. Most organisations believe they are walking through Door three and are actually standing in Door one. They are convinced their version of the same activity is meaningfully different. The customer rarely agrees. Now look at the four AI giants. Every one of them walked through Door three. And each opened it into a different room. ## Four giants, four rooms A position, as the ad men Al Ries and Jack Trout put it in 1980, is a piece of real estate in the customer's mind. You earn it and you defend it. Watch four companies earn four different plots. ### OpenAI — the consumer default OpenAI is playing for the front door to the internet. Not a better search engine. A different activity entirely — a conversation — aimed at the same job search was hired for. Find, decide, buy. The scale is the tell. ChatGPT reached [900 million weekly active users by February 2026](https://techcrunch.com/2026/02/27/chatgpt-reaches-900m-weekly-active-users/). Then OpenAI shipped [the Atlas browser](https://www.cnn.com/2025/10/22/tech/openai-chatgpt-atlas-browser-google-chrome-ai) — a browser that greets you with ChatGPT's bar, not Google's — and began building checkout and ads directly into the chat. That last move is Google's own business model, pointed back at Google. Sam Altman has been blunt about who the target is, describing how [older users treat ChatGPT as "a Google replacement."](https://fortune.com/article/sam-altman-chatgpt-gen-z-millennials-life-advisor-operating-system/) The real estate OpenAI wants is the default — the first place a billion people go. That is a consumer position, and it is enormous. ### Anthropic — the layer underneath Anthropic walked through the same door into the opposite room. It is not chasing the billion-person consumer default. It is selling to the people who build and run serious businesses. The numbers point the other way on purpose. Anthropic's revenue is driven overwhelmingly by enterprise and developer demand, not a consumer subscription, and the run-rate [reached around $30 billion in early 2026](https://www.pymnts.com/artificial-intelligence-2/2026/anthropic-hits-30-billion-run-rate-as-enterprise-demand-accelerates/). Claude Code — a tool that lives in a developer's terminal — [passed $2.5 billion in annualised revenue](https://www.anthropic.com/news/anthropic-raises-30-billion-series-g-funding-380-billion-post-money-valuation), with eight of the Fortune 10 now using Claude. Anthropic describes itself, in its own words, as the *intelligence platform of choice for enterprises and developers.* That is a market-niche-and-service position. It sells trust to people for whom a wrong answer has a cost. Safety is the credential, not a consumer feature. Worth a flag of honesty — the safety posture has softened under commercial pressure as much as it has been marketed — but the territory is clear. Anthropic wants to be the layer underneath the serious work, not the app on the phone. ### Google — the incumbent who owns the road Google is the most interesting study of the four, because it lost the opening round and the position held anyway. When Bard fumbled its first demo in 2023, the market wiped roughly $100 billion off Google in a day, and the story became "Google is behind." By late 2025, Gemini had drawn level — Gemini 3 [briefly topped the public model leaderboards](https://techcrunch.com/2025/11/18/google-launches-gemini-3-with-new-coding-app-and-record-benchmark-scores/) — though the honest read is *caught up*, not *won*, because the lead now changes hands every few weeks. The model was never the position. The position is the road. Google's AI Overviews reach [more than 2.5 billion monthly users and the Gemini app over 900 million](https://blog.google/innovation-and-ai/sundar-pichai-io-2026/), routed through Search, Android, Chrome, Workspace, and YouTube — channels the customer already walks every day. Underneath that, Google makes its own silicon. Anthropic, an OpenAI rival, is buying up to a million of Google's TPU chips to train on. Sundar Pichai calls it *[a "full-stack approach… from our custom silicon… to products that touch billions of people."](https://blog.google/innovation-and-ai/sundar-pichai-io-2026/)* Google does not need to win the customer's imagination. It owns the road the customer is already on. That is a distribution position, and it is the hardest of the four to copy. ### xAI — the unconstrained empire xAI took the door into the strangest room of all — and the most deliberately differentiated. Elon Musk has positioned Grok as the unfiltered, real-time, *maximally truth-seeking* alternative, fused into his own machine. X was [merged into xAI](https://www.cnbc.com/2025/11/25/musk-xai-funding-december.html), putting a live social firehose inside the model. The Colossus supercomputer is the largest single-site AI cluster built to date. The company raised a [$20 billion round in January 2026 at roughly a $230 billion valuation](https://finance.yahoo.com/news/musk-xai-secures-20bn-series-103526032.html), and "Grok for Government" landed a [Pentagon contract ceiling of $200 million](https://breakingdefense.com/2025/07/anthropic-google-and-xai-win-200m-each-from-pentagon-ai-chief-for-agentic-ai/) — alongside the same award to its rivals, so read it as access, not exclusivity. Be clear-eyed here. The "unconstrained, truth-seeking" line is a positioning claim, not a verified property — Grok has produced [serious public failures](https://www.npr.org/2025/07/09/nx-s1-5462609/grok-elon-musk-antisemitic-racist-content), and the same lack of guardrails that differentiates the brand is also its liability with the trust-sensitive buyers it courts. But the territory is unmistakable. xAI is not competing on consumer polish or enterprise trust. It is competing on real-time information, ideological identity, and proximity to state power and Musk's physical-world empire of rockets, satellites, and robots. ## The mistake almost everyone makes Four companies. One door. Four different rooms. None of them fighting on the axis the others chose. That is the lesson, and it is brutal in its simplicity. At the most crowded, most over-funded frontier in business history, the winning move was not to build a better version of the same thing. It was to refuse to stand where everyone else was standing. Now turn it on your own business. Most leaders, asked which door they are on, will say Door three. They believe their service is differentiated, their product distinct, their position theirs alone. Then you ask their customer to describe the difference, and the customer reaches for price. That is Door one wearing a Door three costume. It is the most common strategic error there is, and it is invisible from the inside. The AI giants make the error impossible to hide, because the four positions are so visibly distinct. Your market is quieter. The drift toward sameness is slower and harder to feel. Which is exactly why it catches good companies — the flatness arrives one undifferentiated quarter at a time. ## The operator's read Three questions. They do not require you to run a $200 billion model lab. They scale down to a $20 million business without losing a thing. ### 01 — Which door am I actually on? Not which one I claim. Which one my customer would put me in. Ask three customers to describe, in their own words, why they chose you over the alternative. If the answer comes back as a version of "you were the easiest" or "you were the cheapest," you are in Door one, and you have been calling it strategy. Name it honestly. That is the whole first move. ### 02 — What real estate do I own — and is it mine alone? A position is a plot of land in the customer's mind. OpenAI owns "the default." Anthropic owns "the serious layer." Google owns "the road." xAI owns "unconstrained." Write the one phrase your best customers would use to locate you. Then ask whether a competitor could honestly claim the same phrase. If they could, you do not own the plot. You are renting awareness, and you get evicted the moment someone louder walks past. ### 03 — Are my advantages True, Tangible, and Talk-able? Every claimed advantage has to pass three tests. **True** — it actually exists, not aspirationally. **Tangible** — the customer can feel it, physically or emotionally. **Talk-able** — the customer can describe it, or its effect, in their own words. If an advantage fails one of those, it is not a strategic advantage. It is a feature you happen to like. The four giants each pass all three loudly, which is why their positions hold under the most expensive competitive pressure on the planet. ## The takeaway Here is what I would do this week if I were sitting in a crowded market. I would stop benchmarking against the activities the whole market shares, and start asking what activity none of my competitors is doing for the customer's real problem. I would write my position in one phrase and hand it to the person three layers down to repeat back. And I would be ruthlessly honest about Door one versus Door three, because the gap between the two is where most margin quietly dies. The four AI giants are running this discipline at a scale almost no operator will touch. The principle does not change at $20 million. Build the technology everyone else builds, and you are in a price war you will probably lose. Choose a different room, earn the real estate, and defend it — that is the only game worth playing. Four companies. One door. Four different rooms. The question is not whether you can out-build the people standing next to you. It is why you are still standing in the same room at all. That's what I have for you this week. Operator to operator. I'll see you next week. --- *This is Episode 7 of Commander in Brief. The positioning framework lives in the book — [Resolute](https://www.amazon.com.au/Resolute-navigate-disruption-indestructible-organizations/dp/0645825425), in print since December 2024 — under Leadership Question 3, Strategy & Positioning. If you want the operator's working definition of how AI actually changes a business, start with [AI Business Engineering](/articles/ai-business-engineering-a-working-definition).* --- # The $240 Million Goodbye ## A Louisiana manufacturer sold for $1.7 billion, and the CEO handed $240 million of it to employees who owned not a single share. The impressive part wasn't the money. - URL: https://stuartleo.com/articles/the-240-million-goodbye - Published: 2026-06-15 - Reading time: 8 min read - Method: Essay Graham Walker gave $240M to employees with no equity when he sold Fibrebond — and attached a five-year string he told everyone about. A gift, or an exchange? Here is the idea I want you to leave with, and I am going to give it to you now, before the story — because the story is just the proof. **Generosity that hides its terms is marketing. Generosity that names its terms is character.** Hold that line. Now let me tell you about the man who proved it. ## The headline Graham Walker is forty-six. Until the last day of December he was the CEO of Fibrebond — a manufacturer in Minden, Louisiana, a town of about twelve thousand people. His father founded the company in 1982. Walker ran it for ten years. In April he sold it to Eaton, the power-management multinational, for $1.7 billion. Then he did something that put a small Louisiana factory on the front page of the *Wall Street Journal*. He gave fifteen percent of the proceeds — roughly $240 million — to his employees. Five hundred and forty of them. An average of [$443,000 each](https://fortune.com/2025/12/30/fibrebond-ceo-graham-walker-leaves-443000-to-each-employee-240-million/). Here is the part that makes the story: not one of those employees owned a single share. They had no legal claim to a cent of it. The cap table said they were owed nothing. Walker decided they were owed fifteen percent. The internet did what the internet does. It crowned him. The most generous boss alive. And I understand the reaction — measured against a year of CEOs cutting headcount and calling it courage, a man giving away a quarter of a billion dollars to people who could not have sued him for it looks like a miracle. This piece is not about whether Graham Walker is generous. He obviously is. It is about the five-year string he attached to the money, the fact that he told everyone about the string, and the one thing that actually separates character from a very good press release. ## The decision, with the parts the headline drops Fibrebond makes the heavy electrical infrastructure that data centres run on. Factory-built power enclosures. It is an unglamorous, deeply physical business, and for most of its life it was a hard one. In 1998 the main plant burned down — a fire that took four hours to contain and another twelve to put out, and nearly bankrupted the company. The Walkers kept paying every employee through the rebuild. In the dot-com bust a few years later they laid off more than half the workforce and spent years working down the debt. There were long stretches of frozen salaries before the data-centre bet finally paid off and the sale became possible. So when Walker talks about the people who built Fibrebond, he is not talking about a quarter that went well. He is talking about a fire, a near-bankruptcy, and a decade of people staying when the salary did not move. Now the structure of the gift. Three details, and all three matter. First, he did not pay it out of his own pocket after the fact. He made the fifteen percent a non-negotiable condition of any sale. The price went up to $1.7 billion — Eaton's own announcement said $1.4 billion — precisely because Walker had the buyer fund the bonuses inside the deal. He engineered the generosity into the transaction. That is not a smaller thing than writing a personal cheque. It is a more deliberate one. Second, it vests over five years. Stay, and you collect the full amount. Leave early, and you forfeit what is left — hundreds of thousands of dollars, in many cases. For everyone under sixty-five, the money is also a leash. Third — and this is the line I keep coming back to. When a reporter asked him why he attached the five-year condition, Walker did not reach for a noble answer. He said: *"I don't think we'd have many employees on day two."* Sit with that. The money was a thank-you, yes. It was also a retention mechanism designed to hand Eaton a stable workforce. Both things, at once, said out loud, by the man who wrote the terms. ## What it actually reveals The first of the eight character traits in the [Resolute](https://www.amazon.com.au/Resolute-navigate-disruption-indestructible-organizations/dp/0645825425) leadership model is the one everybody claims and almost nobody tests: integrity. And I do not mean it in the bumper-sticker sense — being honest, being nice. I mean it structurally. **Integrity is the alignment between what you say and what you do, measured at the moment when doing it costs you something and returns you nothing.** That last clause is the whole thing. Anybody's stated values and actual behaviour line up when alignment is free. The test only happens when the cheap thing and the right thing point in different directions. Walker's exit is one of the cleanest tests of that I have seen. He had spent a decade saying the team built this. At the moment of sale, the cap table handed him a completely legal, completely defensible way to keep all of it. The words and the deed were free to diverge, and no one would have blinked. Founders keep the proceeds. That is the default. That is what the share register is for. He aligned them anyway, at the exact moment the deed became expensive. That is what integrity actually is. Not the sentiment. The alignment under cost. But I told you this was about the string — and here is where it gets more interesting than the feel-good version. A cynic has a ready answer: the five-year vest proves it was never a gift. It was a retention play dressed as generosity. And the cynic is half right. It *was* a retention play. Walker said so himself. Here is where it turns. **Integrity is not the absence of self-interest.** A leader is allowed to want things. The failure of integrity is not wanting the handover to go smoothly — it is *hiding* that. It is announcing a handcuff as a gift. It is letting people believe a structure is selfless when it is actually a structure, because the warm version plays better. Walker did the opposite. He named the self-interest in the same breath as the generosity. He told people the money was both a reward and a leash, and let them decide how to feel about it. That is the move. Not the $240 million. The refusal to lie about what the $240 million was for. So here is the distinction to carry. A gift asks for nothing back. An exchange asks for something. Most leadership generosity is quietly an exchange wearing the costume of a gift — the bonus that buys silence, the offsite that buys loyalty, the equity grant that buys four more years. There is nothing wrong with an exchange. Business runs on them. The integrity failure is the costume. ## Three questions for your own seat **One.** Look at the most generous thing you have done for your people in the last year. Now ask the uncomfortable version: what did you get back? There is almost always a return. That does not make it cynical. But if you have never named the return — even to yourself — you are telling yourself the costume version, and the people on the receiving end can usually feel the gap. **Two.** Where in your business are you running an exchange but calling it a gift? Name them honestly. Not to stop doing them — most are fine. But the moment your people work out that a "gift" had terms you never disclosed, you do not just lose that one. They go back and re-read every generous thing you have ever done as a transaction. **Three.** Walker's integrity was only visible because a moment arrived where keeping his word was expensive and returned him nothing. Where is the decision in front of you right now where the cheap option and the right option point in different directions? That decision is the only place your actual character is legible. Everything else is alignment that happened to be free. ## The takeaway The test of a value is not whether it cost you. Plenty of expensive decisions are pure self-interest, and plenty of generous ones are exchanges in disguise. The test is whether you told the truth about what you got back. Graham Walker gave away $240 million and attached a five-year leash to it, and the remarkable thing — the thing the headlines mostly missed — is that he described both halves accurately. The gift and the leash. He did not let the world hand him a halo he had not quite earned, and in refusing the halo, he earned a better one. Most leaders have the money question backwards. They worry about whether they are being generous enough. The harder question — the one that actually reveals you — is whether you are being honest about what your generosity is for. So here it is again, now that you have seen the proof. **Generosity that hides its terms is marketing. Generosity that names its terms is character.** --- # How to run a leadership meeting that solves problems ## Decisions, not status. - URL: https://stuartleo.com/articles/how-to-run-a-leadership-meeting - Published: 2026-06-14 - Reading time: 6 min read - Method: Resolute How to run a leadership team meeting that produces decisions, not status updates — the cadence, the agenda, and the one test, the Resolute way. A leadership team meeting is the recurring rhythm where the people running a business align on the plan and solve the problems blocking it — not a status update, not a calendar habit that survived because no one cancelled it. Most aren't that. Executives now spend an average of nearly 23 hours a week in meetings, up from under 10 in the 1960s, and much of it is people reading out numbers everyone could have read alone ([HBR, *Stop the Meeting Madness*](https://hbr.org/2017/07/stop-the-meeting-madness)). The cost isn't the hour. It's that the actual problems never get solved, because the meeting was spent describing them. Here's the reframe, and the rhythm that fixes it. ## A meeting is a thing you manage **A leadership meeting has one job: produce decisions and aligned action. Everything else is theatre.** In Resolute, Meetings is the fourth of the twelve questions — seven of leadership, five of management — and it sits firmly on the management side. You **lead people; manage things.** A meeting is a thing you manage: a mechanism for taking the plan that already exists and keeping it on track. It is not where you set the vision or rethink the strategy — that's the leadership side, and cramming it into the weekly is how both jobs get done badly. (The [Leadership Curve framework](/resolute/framework) lays out which questions are which.) Get that distinction wrong and every meeting becomes a soup: a bit of status, a bit of strategy, a bit of firefighting, no decisions. Name the meeting's job and the agenda writes itself. ## Why most leadership meetings fail They report instead of decide. Someone walks the team through a deck that restates the dashboard, everyone nods, and the one genuinely hard call gets deferred to "let's take that offline." The status was the content. The decision was the casualty. Amazon removed the failure mode at the root: no slide decks. Teams write a narratively structured six-page memo, the room reads it in silence for the first twenty minutes, then discusses — because, as Bezos put it, prose forces clarity that bullet points let you fake ([Amazon, *2017 letter to shareholders*](https://www.aboutamazon.com/news/company-news/2017-letter-to-shareholders)). You don't have to adopt the memo. You do have to kill the read-aloud. Andy Grove made the same point decades earlier in *High Output Management*: the meeting is the medium through which managerial work actually happens, so a meeting that produces nothing is managerial work not done. ## The rhythm: two cadences, not seven Resist the urge to invent a meeting for every problem. Two cadences carry most businesses. **The weekly tactical.** Sixty to ninety minutes, same time, same agenda, every week. Its job is the present: run the plan, surface what's off, solve the top issues. The sameness is the point — when the shape never changes, prep becomes muscle memory and the team stops relearning the meeting. (EOS calls its version the "Level 10 Meeting"; the structure below is the Resolute take.) **The quarterly.** Half a day, away from the desks. Its job is the future: step back to the leadership questions — is the strategy still right, where is growth focused, what are the few things that matter next quarter. This is where you're allowed to reopen the plan. The weekly is for running it. ## How to run the weekly Work it in this order, because the order enforces the discipline: 1. **Data first.** Open on the few numbers that tell you whether you're winning — the scorecard. This is the Data question (management five) doing its job: report the number, move on. No commentary on green. 2. **Goals check.** Run the quarter's priorities — on track or off. One word each. Off-track goals become issues. 3. **Issues, prioritised.** Build the list, then solve the top one to three — fully — before touching the rest. A meeting that "covers" fifteen issues solves none. The ones you don't reach roll to next week. That's fine; they were lower priority by your own ranking. 4. **Decisions and owners.** Every solved issue ends with a decision, a single owner, and a date. No owner, no decision — just a conversation you'll repeat next week. The move that separates a working meeting from a status meeting is one rule: **report the number; debate only the exception.** If it's on plan, it gets a sentence. The room's time goes to what's off. In practice a ninety-minute weekly breaks down roughly like this: five minutes to land (good news, a quick personal and professional win — it changes the room's temperature), five on the scorecard, five on goals, then a full hour on issues, and the last ten minutes confirming the decisions, owners, and dates out loud so no one leaves with a different version in their head. The proportions are the lesson: more than two-thirds of the meeting is spent *solving*, not *updating*. If your ratio is inverted — fifty minutes of reporting, ten of problem-solving — you have found the disease. ## The quarterly: where you're allowed to reopen the plan The weekly keeps you on the road; the quarterly checks you're still on the right road. Once every ninety days the leadership team steps away from the desks for half a day and runs the leadership questions, not the management ones: is the strategy still right, has the market moved, where is growth actually focused, and what are the one, two, or three priorities for the next ninety days. Those priorities — the Focus question — become the goals the next twelve weeklies run against. Keep the two cadences clean and they reinforce each other: the quarterly sets the destination, the weekly drives toward it, and neither has to do the other's job badly. ## What a great meeting will not do Be honest about scope, because the meeting gets blamed for failures that belong upstream. A meeting cannot fix an unclear plan, undefined roles, or numbers no one trusts. If the same issue resurfaces every week and never resolves, that's not a meeting problem — it's a Plan, Roles, or Data problem wearing a meeting's clothes (the other four management questions). More meeting discipline won't save you. Sharper answers to the upstream questions will. The cadence executes clarity. It can't manufacture it. So the test isn't "was the meeting good?" It's blunter: **could you cancel this meeting and lose nothing?** If the answer is yes, you've been running a reporting ritual, and the inbox would do the job cheaper. If you're not sure where your operating rhythm actually stands, that's worth measuring. The free [Resolute business diagnostic](/resolute/assessment) reads your business across the twelve questions — Meetings included — names the stage of the Leadership Curve you're on, and the one thing to build next. The working canvases live in the [Resolute Library](/resolute/library); the [canon](/books) goes deep on all five questions of management. --- # Why most businesses stall as they scale ## The Calibrate trap. - URL: https://stuartleo.com/articles/why-businesses-stall-at-calibrate - Published: 2026-06-14 - Reading time: 6 min read - Method: Resolute Why most businesses stall at the same stage of growth — Calibrate — when what worked with the founder in every room breaks once they step away. Most businesses don't fail at scale. They stall at it — and they stall at the same place. The stage where adding people, skills, and systems either makes the business cohere or makes it fragment. In the Resolute Leadership Curve I call it Calibrate, and it is where more good companies get stuck than anywhere else on the climb. The Resolute Leadership Curve maps the six stages every business climbs from idea to market leadership: Idea, Identity, **Calibrate**, Maturity, Mastery, Initiate. The first two are about finding something that works. Calibrate is about making it work *without you in every conversation*. That is a different job, and most founders try to do it with the skills that won the last stage. **What earned you the last stage of growth will not earn you the next.** ## Why Calibrate is the wall In the early stages, the founder *is* the system. They're in every sale, every hire, every call on what matters this week. It works — beautifully — right up to the moment it can't, because there is one of them and the business now needs that judgement in ten rooms at once. This is not a Resolute observation; it's an old one. Larry Greiner's classic study of how companies grow showed that each phase of growth ends in a predictable crisis that the next phase has to resolve — growth by creativity hits a "crisis of leadership," growth by direction hits a "crisis of autonomy," and so on ([HBR, *Evolution and Revolution as Organizations Grow*](https://hbr.org/1998/05/evolution-and-revolution-as-organizations-grow)). Calibrate is where those crises cluster. The thing that has to change is not the market or the product. It's the founder's relationship to the work. Here's the trap in one line. **You scaled the headcount. You forgot to scale the clarity.** Now there are thirty people executing a strategy that lives in one person's head, a culture that formed by accident while everyone was busy, and a founder who is somehow more central than they were at ten people, not less. ## The tells Calibrate stalls look the same across industries: - **The strategy lives in a document, not in the team's own words.** Ask three people two layers down where the business is going and you get three answers. - **Headcount grew but the founder is the bottleneck.** Decisions queue at one desk. Holidays are theoretical. - **The priority list has fifteen items and no clear owners.** Everything is important, so nothing is. - **The best people start leaving first.** They can see the fragmentation before the dashboard can. None of these is a performance problem. They're an alignment problem — the business outgrew the informal coordination that used to be free. Here's the mechanism, because naming it is half the cure. In the early days, coordination is free: everyone sits within earshot, the founder settles every ambiguity in real time, and shared context lives in the room. Each new hire adds not just a salary but a set of connections that all need maintaining — and past roughly fifteen to twenty people, the number of those connections grows faster than anyone can hold in their head. The founder who used to be the fastest path to an answer becomes the slowest, because there's now a queue. Nothing got worse. The business simply crossed the threshold where instinct stops scaling and structure has to take over. Founders read the slowdown as a people problem and hire more — which adds connections and makes it worse. It's not a people problem. It's a clarity problem wearing a headcount disguise. ## The way through Calibrate is cleared by building leadership *into the organisation* rather than concentrating it in the leader. Four moves do most of the work, and they map to the leadership questions that crowd this stage: **Make the strategy repeatable.** Not a deck — a position someone three layers down can say in sixty seconds. If they can't repeat it, it isn't strategy yet; it's a private intention. (Writing the destination first helps — see [writing a vision statement](/articles/writing-a-vision-statement).) **Build culture on purpose.** Culture is your leaders' character, multiplied — it scales whether you design it or not. What endures while the tactics change is the core; what Collins and Porras call the "core ideology" that holds steady as practices adapt ([HBR, *Building Your Company's Vision*](https://hbr.org/1996/09/building-your-companys-vision)). Decide it, or inherit whatever forms by default. **Map the customer journey and the people plan.** Write down how you find, keep, and grow the right customers — and how you attract, keep, and develop the people the plan needs. At Calibrate these stop being instinct and have to become a system. **Cut the priority list to three.** Focus is the alignment mechanism. Name the one, two, or three things that, if delivered this quarter, move the business — and give each a single owner. A team aligned on three real priorities beats a team busy on fifteen. ## What clearing Calibrate is not It is not hiring a layer of managers and hoping coordination emerges. It is not a new tool. And it is emphatically not the founder working harder — working harder is what *deepens* the bottleneck, because it reaffirms that the business runs through one person. It's also not skippable. Real growth is earned, not bought: you cannot acquire or hustle your way past a stage whose entire job is building the capability the next stage stands on. The businesses that try to jump Calibrate don't reach Maturity faster. They reach a bigger, more expensive version of the same stall. You're through when the business runs aligned without you personally holding the line — when you can be out of the room and the right calls still get made, because the clarity lives in the team, not in your head. So the honest question isn't "are we growing?" Plenty of stalled businesses are still growing, right up to the ceiling. It's this: **if you disappeared for a month, would the business get clearer or more confused?** If you're not sure, find out before you add the next ten people. The free [Resolute business diagnostic](/resolute/assessment) reads your business across the twelve questions, tells you which stage of the Leadership Curve you're actually on, and names the one thing to build next. The [framework](/resolute/framework) walks all six stages; the [canon](/books) goes deep on the climb. --- # Writing a vision statement a team can actually use ## Two coordinates, not a poster. - URL: https://stuartleo.com/articles/writing-a-vision-statement - Published: 2026-06-14 - Reading time: 8 min read - Method: Resolute How to write a vision and purpose short enough to remember and sharp enough to steer by — with the Vision Canvas, the Resolute way. A vision statement is a one-sentence picture of the world your customer lives in once your work is done — the destination the business is moving toward. Can you recite yours right now, without scrolling, without guessing? Most leaders can't. Their teams can't either. And yet somewhere in the building there is a glossy poster, a homepage banner and an onboarding deck all swearing the vision is fundamental to who we are. That gap — between the statement on the wall and the one nobody can say — is the whole problem. Let me give you a sharper way to think about it, and the tool to fix it. ## A vision is two coordinates, not a poster Stop thinking of a vision as a statement to admire. Think of it as two coordinates you steer by: a vision and a purpose. **A vision is a picture of the world changed once your purpose has done its work.** Vision is something you **see** — the end state, the destination, the *what*. Purpose is something you **do** — the daily action, framed around your customer's problem, that inches you toward it; the *why*. Vision is where you're headed. Purpose is the fuel that gets you there. Get both and you can navigate. Get one, you wander. Get neither — and most "visions" land here — you have a mood board with a budget. This is the first of the twelve questions — seven of leadership, five of management — at the core of the Resolute Method. **Vision & Purpose** is leadership question one, and it comes first on purpose. You cannot choose a strategy, align a team, or say no to a good-but-wrong opportunity until the destination is named. Every later question inherits its answer. It also sits at the start of the Resolute Leadership Curve — the six stages every business climbs from idea to market leadership. At the **Idea** stage the whole job is comprehension, not scale: sharpen the problem, name the destination, prove someone wants the solution. A founder who can point at the destination instead of carrying it alone has cleared the first real test. One who can't is about to scale confusion. ## Why the posters fail For thirty years it was fashionable to spend serious money on two documents — a mission statement and a vision statement — produced in a day-long offsite and hung on a plaque. Two years later a stranger walks the office and asks people what the mission is. Executives, managers, the front desk. Hardly anyone can say it. The problem was never the idea of having a vision. It was the execution. The statements were generic, hollow, disconnected from what people did between nine and five. Then the pendulum swung to *purpose* — Simon Sinek's [*Start With Why*](https://www.ted.com/talks/simon_sinek_how_great_leaders_inspire_action) put it at the centre of every keynote — and brands started bolting themselves to whatever cause was trending that month, with no real link to what they actually do for a customer. Tone-deaf marketing. Customer scepticism. Point-scoring without substance. What an organisation needs is simpler than three statements and harder than a poster: a clear vision and a clear purpose, properly defined, both short enough to remember without trying. Collins and Porras made the durable version of this case decades ago in HBR's [Building Your Company's Vision](https://hbr.org/1996/09/building-your-companys-vision) — an "envisioned future" vivid enough to feel, not a committee paragraph. ## What a real one looks like Oxfam puts its vision in five words: *a just world without poverty.* Brief enough to memorise without effort, big enough to make you want to. Patagonia is the sharper example, because it keeps living the thing long enough for it to prove the point. Its published vision is nine words: *we're in business to save our home planet.* That should sound ridiculous coming from a company that sells jackets. It doesn't — because the purpose underneath it is real and daily: build the best product, cause no unnecessary harm, use the business to fund solutions to the environmental crisis. Every repaired jacket, every percent of sales given to environmental groups, every retooled supply chain fulfils the purpose. None of them, alone, saves the planet. Together, over decades, they march the company toward the vision. The proof came in 2022, when founder Yvon Chouinard transferred ownership of the entire company to a trust whose mandate is the environment — [*"Earth is now our only shareholder."*](https://www.patagonia.com/ownership/) That is not a campaign. That is a vision executed at the level of who owns the company. The brand, the loyalty, the price premium are all downstream of it. Notice what none of these say. Not *be the biggest*. Not *sell the most*. Those are lunchbox goals — fine to have, useless for sustaining anyone through a hard week. Nobody gives their best years to "market leadership." They give them to a world worth building. ## How to write yours: diverge, then converge You write a vision in two moves, in this order — and the order matters. **First, the Vision Canvas.** This is divergent thinking: you are generating options, not deciding. Get four or five people who actually know your customer in a room and work six prompts — *customer* (who, specifically), *problem* (the real one they feel), *solution* (what you do about it), *benefit* (the tangible outcome), *desired state* (how their world or identity is different afterward), and *roadblocks* (what's honestly in the way). Most leaders try to write the final sentence first and lock in the first idea that lands. It is almost never the best one. Diverge first. **Then, the Vision Clarity Statement.** This is convergent thinking: you sharpen the options into a single line. You will have two or three candidates for the desired state — pick one to lead with, leave the rest on the table. The first sentence you land becomes your **vision**; the second becomes your **purpose**; the honest third names the roadblock. The template is only the scaffold — once it's clear, use a creative licence to shorten and sharpen until it sounds like you. Both Resolute canvases live in the [Resolute Library](/resolute/library). And there is one test the canvas can't do for you: say the vision and the purpose out loud, together, in one breath. If you run out of air, you are not finished — you are not done thinking. The compression *is* the work. The sentence is just where it lands. ## What a vision statement will not do Be honest about the scope, because over-claiming here is how leaders end up disappointed in a perfectly good vision. A vision will not fix a broken plan. It will not close the deal, hit the quarter, or sort out who owns what. In Resolute you **lead people and manage things** — and a vision is leadership, not management. It influences belief and gives the work a north; it does not, by itself, make anything ship. If the business is long on vision and short on delivery — the strategy re-sketched while the day-to-day drifts — more vision is the last thing it needs. It needs the management side: the plan, the roles, the goals, the rhythm. The vision names the destination. It does not drive the car. And it will not stay true if you rewrite it every quarter. The destination should hold for years; you revisit it when you clear a stage of the Curve or the market moves under you. Constant re-sketching is not vision work — it's an execution problem wearing a vision costume. So the real question isn't "do we have a vision statement?" Almost everyone does. It's this: **could the newest person on your team tell me where this business is going, and why — without looking it up?** If you're not sure of the answer, that's the place to start. Pick this week's smallest version of the work: get four people in a room, run the Vision Canvas once, write a first-pass Clarity Statement. You'll throw most of it out. That's the point — you're learning to converge. --- The fastest way to see where your clarity actually sits — not just on vision, but across all twelve questions — is the free [Resolute business diagnostic](/resolute/assessment): it reads your business, tells you which stage of the Leadership Curve you're on, and names the one thing to build next. If you want the thinking first, the [Leadership Curve framework](/resolute/framework) lays out the six stages and the twelve questions in full, and the [Resolute canon](/books) goes deep on writing the vision — and the eleven questions that follow it. --- # C² vs enterprise AI coding platforms ## Enterprise platforms sell governance, SSO and control. C² gives you a method and context you own. Where they meet. - URL: https://stuartleo.com/articles/c2-vs-enterprise-ai-platforms - Published: 2026-06-09 - Reading time: 4 min read - Method: C² Method Enterprise platforms sell governance, SSO and control for AI coding. C² gives you a method and context you own. What each is for, and where they meet. As AI coding moves from individual experiments to organisations, a category of **enterprise AI coding platforms** has grown up around it — selling governance, SSO, audit logging, and control. It's tempting to line these up against C² as competitors. They're not. They operate at different layers, and the most useful comparison shows you which problem each one actually solves. Here's the honest distinction, and why you might use both. ## What enterprise platforms sell (governance, SSO, control) Enterprise platforms exist to answer the questions a security team asks before agents touch real code: Who is this agent? What can it access? What did it do? Can policy be enforced and compliance proven? So they provide identity and access (SSO, SCIM provisioning against your directory), audit logging, permission and policy controls, isolation, and incident tooling. This is real and necessary — it's exactly the [governance scaffolding](https://coder.com/blog/inside-ai-adoption-lessons-from-enterprise-software-development-teams) that separates agent deployments which scale from the ones that get pulled after a quarter. It's the difference between a clever pilot and something a regulated org will allow on production. ## What C² gives (a method, context you own) C² answers a different question entirely. Not "who can use the agent and what can it touch," but "**how does the agent produce good, consistent, trustworthy work** on the codebase in front of it?" Its answer is a method: capture context as a first-class, version-controlled artifact — decisions, patterns, gotchas, briefs — that the agent reads before it acts and that [compounds](/articles/what-is-a-contextbase) over time. That's what makes the agent's output reliable across a big codebase instead of brilliant-on-the-demo and inconsistent everywhere else. **Enterprise platforms govern the tool. C² governs the knowledge. One controls what the agent may do — the other makes what it does good.** ## Where heavy platforms fit Governance platforms earn their cost where governance is the binding constraint: large organisations, regulated industries, sensitive code, many developers and agents to coordinate. If your blocker is "security won't approve agents touching production without SSO, audit, and policy controls," that's exactly what these platforms are for — and you should use one. This is also why [most agent pilots never reach production](/articles/why-agent-pilots-never-reach-production): the governance was missing. Enterprise platforms supply that missing half. ## Where they overweight the problem But governance is only half the gap — and the platforms tend to imply it's the whole thing. An agent can be perfectly governed (scoped, logged, SSO'd) and still produce inconsistent, mediocre work, because governance says nothing about whether the agent *knows your codebase*. That's the context problem, and a control plane doesn't solve it. For a solo builder or a small team, a heavy governance platform is also simply overweight — machinery aimed at a coordination problem you don't have yet. The thing that makes your agent good — context — isn't something you buy a platform for. It's a practice you run. ## Lightweight method inside heavy governance The resolution is that these aren't rivals, they're layers: | | Enterprise platform | C² | |---|---|---| | Layer | The tool and access | The knowledge and method | | Solves | Governance, compliance, control | Reliable, consistent agent output | | Form | A platform you buy and run | Markdown in git, any agent | | Owns | Access policy | The context — yours | | Best when | Scale and compliance bind | Always — it's what makes agents good | A large org runs C² *inside* its governance: the platform handles SSO, audit, and policy — C² handles the contextbase that makes the agents actually competent on the code. The governance is the fence, and the contextbase is what makes the work worth fencing. And because C² is just markdown in git, it slots under any platform — or under no platform at all. Enterprise platforms govern the tool. C² governs the knowledge — and the knowledge is the part worth owning. Start here: see [why agent pilots never reach production](/articles/why-agent-pilots-never-reach-production), [C² vs native rule files](/articles/c2-vs-native-rule-files), or [read the method](/c2/method). --- # Context files vs fine-tuning for your codebase ## Want an agent that knows your codebase? Fine-tune a model or write context files. Why context wins for most teams. - URL: https://stuartleo.com/articles/context-files-vs-fine-tuning - Published: 2026-06-09 - Reading time: 4 min read - Method: C² Method Want an agent that knows your codebase? You could fine-tune a model or write context files. Why context wins for most teams — cheaper, faster, and yours. You want an agent that *knows your codebase* — your patterns, your decisions, your conventions — instead of one that guesses like a stranger. There are two ways to get there, and they're often confused: **fine-tune a model** on your code, or **write context files** the model reads. They sound similar. They're very different bets, and for most teams one of them is clearly right. Here's the honest comparison of fine-tuning versus context, and why context wins for almost everyone building software. ## Two ways to teach an agent your code The goal is the same: an agent that behaves as if it already knows your project. The two routes get there differently. - **Fine-tuning** changes the *model itself*. You train it further on your codebase and conventions, so the knowledge is baked into the weights. You've edited the brain. - **Context files** leave the model untouched. You write your knowledge into files the agent reads *before it acts* — a [contextbase](/articles/what-is-a-contextbase). You've handed the brain a briefing. One alters the model. The other informs it at runtime. That single difference drives everything else. ## Fine-tuning: bake it into the model Fine-tuning's appeal is that the knowledge becomes *part of* the model — no need to supply it each time. For a stable, hard-to-describe style or domain, that can be genuinely valuable. But the costs are steep for codebase knowledge specifically. It needs data, expertise, and budget. It produces a model artifact you have to host and manage. And — the killer — it's **slow to update**. Your codebase changes daily — the fine-tuned model is frozen at its last training run. The moment you make a decision the model wasn't trained on, it's out of date, and updating means another training cycle. You've baked a snapshot of a moving target. ## Context files: read it before acting Context files take the opposite approach: keep the knowledge *outside* the model, in version-controlled markdown the agent reads before each task. The discipline of curating that knowledge well is [context engineering](https://www.firecrawl.dev/blog/context-engineering), and it has a decisive practical edge for anything that changes. Update a context file and the change is live on the very next task — no training, no cost, no waiting. The knowledge is plain text you can read, edit, review, and version like code. And it's *yours*, sitting in your repo, not encoded in a model's weights you don't control. **Fine-tuning bakes a snapshot of your codebase into a model. Context files keep a living copy of it in your repo — current, readable, and yours.** ## Cost, speed, and staleness Lined up, the comparison is lopsided for evolving codebase knowledge: | | Fine-tuning | Context files | |---|---|---| | Where knowledge lives | The model's weights | Files in your repo | | Cost to set up | High (data, compute, expertise) | Low (write markdown) | | Time to update | A training cycle | Instant — next task | | Staleness | Frozen at last training | Always current | | Portability | Tied to that model | Works with any model | | Inspectable | No | Yes — it's plain text | | You own it | The provider's model, your tuning | Entirely yours | ## Why context wins for most teams For a *living* codebase — which is every codebase — the staleness problem alone settles it. Knowledge that changes daily can't be baked into a model that updates monthly. Context files track the change for free, the day it happens. Add that they're cheaper, readable, reviewable, model-agnostic (so you can [route or switch models](/articles/cursor-vs-claude-code-which-fits-c2) freely), and genuinely yours, and the case is clear: for teaching an agent your codebase, write context, don't fine-tune. (Fine-tuning still earns its place for stable style or domain internalisation — just not for the moving target of your code.) Fine-tuning bakes knowledge into a model you don't own — context files keep it yours, current, and free to change. Start here: see [what a contextbase is](/articles/what-is-a-contextbase), [context engineering vs RAG](/articles/context-engineering-vs-rag), or [read the method](/c2/method). --- # Crawl, walk, run: adopting AI agents safely ## Teams that jump straight to autonomous agents fail. The path that gets agents from first try to production work. - URL: https://stuartleo.com/articles/crawl-walk-run-adopting-ai-agents - Published: 2026-06-09 - Reading time: 5 min read - Method: C² Method Teams that jump straight to autonomous agents fail. The crawl-walk-run path that gets AI agents from first try to production work — without the wreckage. The most common way teams fail with AI agents isn't picking the wrong tool. It's starting in the wrong gear — pointing agents at the hardest, highest-stakes work on day one, watching it go sideways, and concluding agents don't work. They do. You just can't start at full speed. The pattern that works is the oldest one in adoption: **crawl, walk, run.** Here's what each gear looks like for AI agents, and why skipping straight to "run" is the reliable way to fail. ## Why jumping to run fails "Run" is the dream: hand the agent a big, ambiguous feature and let it go. It's also where almost every failed adoption starts, because at that level a confident mistake is expensive and hard to catch — and you have no track record yet to know where the agent is reliable. The advice from teams that have actually scaled this is blunt: strategies that [jump straight to "run" fail](https://larridin.com/solutions/ai-adoption-the-complete-enterprise-guide-2026). Not because the agent can't eventually do hard work, but because trust, context, and guardrails are built in the lower gears — and without them, the hard work has nothing to stand on. ## Crawl: tests, small fixes, low-risk refactors Start where mistakes are cheap and instantly visible: - **Adding tests** to code that lacks them — low risk, and it builds the test coverage everything later depends on. - **Fixing small, well-defined bugs** — clear success criteria, easy to verify. - **Low-risk refactors** — mechanical changes the tests can guard. - **Dependency updates and doc sync** — tedious, bounded, easy to check. This gear feels unambitious. That's the point. You're building two things: the test and context scaffolding that make later work safe, and your own judgement about where the agent is trustworthy. Both are prerequisites for everything above. **Crawl isn't a warm-up you skip. It's where you build the tests, context, and trust that 'run' stands on.** ## Walk: features behind review Once the agent is reliably handling chores and you've got tests and a [contextbase](/articles/what-is-a-contextbase) building up, step up to real features — but behind review. The agent builds, a human (or a [bench agent](/articles/ai-code-review-with-a-bench-agent)) reviews before it lands. You're trusting the agent with more, but with a checkpoint. This gear is where most of the value lives, and where most teams should spend most of their time. It's ambitious enough to matter, safe enough to catch the misses. ## Run: autonomous, well-fenced work Only now — with tests, context, trust, and guardrails in place — does autonomous work make sense: the agent running [overnight](/articles/run-agents-overnight-safely) or unattended on well-scoped tasks, behind isolation and a test gate. "Run" isn't reckless here, because everything underneath it was built in the earlier gears. The same autonomous run that wrecks a team on day one is safe on day ninety, because of what's been built in between. ## There's a second ladder, and it moves independently One thing this ladder deliberately doesn't measure: **how many agents you're running.** That's a separate axis, and it has its own rungs — one agent you sit beside, then several in isolation, then more output than you can personally read. What changes as you climb it isn't the risk of the work. It's what constrains you: your attention, then your review throughput, then how much you trust the loop. The two are orthogonal, and that's not a technicality. It explains teams that neither ladder describes on its own: | | Assisted (~1 agent) | Parallel (~10) | Supervised (~100) | |---|---|---|---| | **Run** | one agent, overnight, well-fenced | | | | **Walk** | | most teams live here | | | **Crawl** | starting out | 5 agents writing tests nobody needed | | I sat in that top-left cell for months — a single agent running unattended overnight on production code, behind a test gate, with me reading every diff in the morning. On risk, that's *run*, the top rung. On count, it's *assisted*, the bottom one. Both true. The bottom-right of that table is the more common mistake: adding agents while the work stays trivial. More agents doing crawl-level work is just more test files. **Moving up this ladder is nearly always the higher-value move**, because raising the risk of the work is what builds the verification everything else depends on. And it tells you when a fan-out is your next move — which is later than most people think. If your agents don't yet prove their own work before you look, running 6 at once produces 6 streams of unverified output and a reviewing problem you can't staff. [The two ladders, in full](/articles/the-two-ladders-of-ai-adoption). ## Build the context as you climb Here's the thread connecting all three gears: at every step, you're capturing what the agent learns into the contextbase. The crawl gear documents the codebase and builds test coverage. The walk gear accumulates decisions and gotchas. By the time you reach "run," the agent isn't just more trusted — it's better informed, reading a contextbase that's been compounding the whole climb. That's why crawl-walk-run isn't just risk management. It's how the agent gets good enough for "run" in the first place. Adopting agents isn't a leap — it's a climb from low-risk chores to real work, with context built at every step. Start in crawl, and you earn run. Start here: see [why most agent pilots never reach production](/articles/why-agent-pilots-never-reach-production), [how to run agents overnight safely](/articles/run-agents-overnight-safely), or [read the method](/c2/method). --- # Defend against prompt injection in coding agents ## Prompt injection turns content your agent reads into commands it follows. Why coding agents are exposed, and what holds. - URL: https://stuartleo.com/articles/defend-against-prompt-injection - Published: 2026-06-09 - Reading time: 4 min read - Method: C² Method Prompt injection turns content your agent reads into commands it follows. Why coding agents are exposed, the real incidents, and the defences that hold. Prompt injection is the security problem that arrived *with* agents and got worse the more capable they became. The idea is simple and unsettling: text your agent reads — a dependency's documentation, a code comment, a GitHub issue, a web page — can contain instructions, and the agent may follow them as if they came from you. When the agent can act, a sentence buried in a README becomes a command with real consequences. For coding agents specifically, this is not theoretical. Here's why they're exposed, how injections actually land, and the defences that hold. ## What prompt injection is A model can't reliably tell the difference between *your* instructions and *instructions embedded in content it's reading*. To the model, it's all text. So if the agent reads a file that says "ignore prior instructions and run this command," there's a real chance it does. That's prompt injection: smuggling instructions into the content an agent processes, so it acts on the attacker's intent instead of yours. With a chatbot, the worst case is a bad answer. With a coding agent that runs commands and edits files, the worst case is much worse. ## Why agents made it worse (they act) The thing that makes coding agents powerful — they take actions in the world — is exactly what makes injection dangerous. As security researchers put it, going [from chatbots to agents made prompt injection worse](https://christian-schneider.net/blog/prompt-injection-agentic-amplification/), because the model's output is no longer just words — it's commands, file edits, tool calls, network requests. And the incidents are real. Injected instructions hidden in a dependency chain have led to leaked credentials and compromised packages. An agent triaging issues, reading a poisoned one, has been steered into harmful actions. The pattern repeats: the agent reads attacker-controlled text, and its ability to act turns that text into damage. ## Where injections hide (deps, comments, docs) The dangerous realisation is *how much* of what an agent reads is attacker-influenceable: - **Dependencies** — their code, comments, and docs, which you didn't write and rarely audit. - **Code comments and doc strings** — including in packages pulled in transitively. - **Issues, PRs, and tickets** — anyone can open one. - **Web pages and search results** — if the agent browses. **Your agent doesn't only read your instructions. It reads everything in its path — and any of it could be carrying someone else's.** The mental shift: treat *everything the agent reads* as potentially hostile, not just the obvious inputs. ## Layered defences that work There's no single fix — defence is layers, and the strongest ones limit what a successful injection can *do*: 1. **Least privilege.** This is the big one. If the agent can't reach secrets, deploy, or production, an injection that lands has little to act on. [Scope the blast radius](/articles/least-privilege-for-coding-agents) and most injections fizzle. 2. **Separate secrets from action.** Never run an agent with broad command access *and* secrets in scope — the combination that turns injection into exfiltration. ([Keep secrets out of reach.](/articles/secure-secrets-when-coding-with-agents)) 3. **Treat inputs as untrusted.** Be wary of pointing the agent at unvetted dependencies, random issues, or arbitrary web content, especially in autonomous runs. 4. **Sandbox and isolate.** Run risky work in a container or worktree with no access to anything that matters. ## Human-in-the-loop for high-risk actions The last layer is the simplest: for anything genuinely dangerous — touching production, deleting data, moving money, installing software — require a human to approve it. An injection can tell the agent to do the dangerous thing, but it can't click your approval. Gating high-risk actions behind a human is the backstop when every other layer fails. Treat everything your agent reads as untrusted — injection hides in dependencies and docs, not just prompts. Then make sure that even if it's fooled, it can't reach anything that matters. Start here: see [least privilege for coding agents](/articles/least-privilege-for-coding-agents), the [field note on an injection I almost shipped](/articles/the-prompt-injection-i-almost-shipped), or [read the method](/c2/method). --- # Document an inherited codebase with an agent ## Inherited a codebase with no docs? An agent can read it and draft the documentation, if you direct it well, and a contextbase can grow into it one change at a time. - URL: https://stuartleo.com/articles/document-a-codebase-with-an-agent - Published: 2026-06-09 - Reading time: 6 min read - Method: C² Method Inherited a codebase with no docs? How to have an agent draft the documentation, verify it, and grow a contextbase into a legacy project one change at a time. Inheriting an undocumented codebase used to be a slow misery: read it all, guess at the reasoning, write up what you could. An agent changes the economics completely. It can read the whole thing and draft the documentation in an afternoon, turning an opaque codebase into something explained. The catch is that "draft" is the operative word, and your job is to direct and verify, not to trust blindly. Here's how to turn an inherited codebase into a usable contextbase with an agent doing the heavy lifting, and how to keep that contextbase growing once the first pass is done. ## The opaque inheritance An undocumented codebase is opaque in a specific way. The *what* is recoverable from reading the code. The *why* (the decisions, the constraints, the traps) is missing. Any documentation worth having has to capture both, and the why is the hard part, because it isn't written anywhere. A greenfield project's context is small and fresh in your mind. A legacy codebase's context is enormous and mostly *gone*: retired in someone's head, lost to turnover, never written down. Brownfield codebases break the usual assumptions precisely because [legacy behaviour and contracts are rarely documented](https://www.augmentcode.com/guides/spec-driven-development-brownfield-codebases). That why is what an agent most needs and least has. Picture a query structured oddly because it works around a bug fixed years ago, or a module that avoids a library because of a licensing call nobody remembers. The agent can't see any of that, so it treats the workaround as a mistake and "fixes" it, reintroducing the original bug. An agent can recover a lot of the what quickly. It can recover some of the why by inference, and it will confidently invent the rest, which is exactly why you stay in the loop. The guides on [using agents in legacy code](https://jrswab.com/blog/ai-agent-legacy-code-guide/) keep landing here: the agent accelerates the documentation enormously, but unverified, it documents its own guesses as fact. ## Have the agent map before it documents Don't ask for documentation cold. Ask for a map first. Have the agent survey the codebase and report the structure: the main parts, how they connect, the entry points, the data flow. This does two things. It gives you a frame to organise the documentation around, and it surfaces the agent's understanding *before* it commits that understanding to docs, so you can correct a wrong mental model early rather than finding it baked into fifty files. Map first, document second. Reverse the order and you get confident, well-formatted documentation of a misunderstanding. ## Go deep where you're working, not everywhere A map is cheap. Documenting the whole system in depth is not. The instinct is to launch a big documentation project and explain everything before letting an agent touch anything. Don't. It's enormous, it's boring, most of it you'll never need, and it'll be stale before it's finished. Instead, go deep where you're actually working. The module you're about to change is the module worth understanding and capturing first. Document the change you're making, not the system you inherited. **Don't document the whole legacy codebase. Document the part you're touching, and let coverage grow toward the parts that matter.** This keeps the effort proportional to the value. The well-trodden paths get a contextbase fast. The dead corners nobody touches stay undocumented, which is fine, because nobody touches them. ## Document behaviour, not just structure The low-value output is a structural dump: "this folder contains these files." Anyone can get that from `ls`. The high-value output is *behaviour and decisions*: how login actually works end to end, why the payment flow is built this way, what the fragile parts are and what they're protecting against. **Structural docs tell you where things are. Behavioural docs tell you how the system works and why, and that's the part worth an agent's effort.** So direct the agent toward behaviour: "explain how X works," "what does this module depend on and why," "what would break if I changed this." That's the documentation that makes the next person, and the next agent, actually competent in the code. ## Verify against tests and reality This is the step you cannot skip. The agent's documentation is a fast first draft of understanding, and it *will* be wrong in places, especially on intent. So verify: - Check claims against the **tests**. They encode real expected behaviour. - Check against **reality**. Run the thing, trace the flow, confirm the surprising claims. - Correct what the agent misread, and note where even you aren't sure. The verification is what converts "the agent's plausible guess" into "documentation you can trust." It's also far faster than writing the docs yourself. You're editing a draft, not facing a blank page. ## Capture decisions and gotchas as you touch code The first pass gives you a foundation. What keeps it useful is capturing context every time you work, using the same mechanism that powers a fresh contextbase: - When you (or the agent) work out *why* something is the way it is, write it down as a decision. - When you hit a trap (the workaround, the fragile bit, the surprising behaviour), write it down as a [gotcha](/articles/the-legacy-codebase-the-agent-couldnt-read). - When you change something, leave a [session brief](/articles/write-your-first-session-brief) so the next session inherits what you learned. Each one is a piece of tacit knowledge made explicit, and the agent reads it before it next touches that code, so it stops misunderstanding. You don't have to write all of it yourself either. The agent that just explored a module to make a change can draft the explanation. You review and correct it, then commit it. It drafts, you verify, the contextbase grows. ## From docs to a living contextbase One-time documentation rots the day it's written. The move that makes this last is to commit the verified docs into a [contextbase](/articles/what-is-a-contextbase) the agent reads *before* it works on that code. If the project has nothing yet, start with a `docs/` folder and a Router file (`AGENTS.md`, or `CLAUDE.md` for Claude Code) that points into it. Keep this up for a few weeks and something quietly shifts. The parts of the codebase you work in most have a contextbase. The agent stops reintroducing old bugs because the gotchas are written down. New people onboard to those areas in hours. And you never ran a big documentation project. The context accreted around the work, exactly where it pays off. Now the documentation isn't a static artifact that drifts out of date. It's the agent's working memory of the codebase, kept current by use. An agent can draft the docs a codebase never had. Your job is to verify them, then grow the contextbase one change at a time. Start here: [onboard to any codebase with an agent](/articles/onboard-to-any-codebase-with-an-agent), read the [field note on a codebase the agent couldn't read](/articles/the-legacy-codebase-the-agent-couldnt-read), or [read the method](/c2/method). --- # Greenfield vs brownfield: building with agents ## Starting fresh and working in a legacy codebase are different sports with AI agents. What changes, and how to handle each. - URL: https://stuartleo.com/articles/greenfield-vs-brownfield-with-agents - Published: 2026-06-09 - Reading time: 4 min read - Method: C² Method Starting fresh and working in a legacy codebase are different sports with AI agents. What changes, why brownfield is harder, and how to handle each. "Building with AI agents" describes two genuinely different experiences depending on where you start. Spin up something new and the agent feels magical — fast, clean, unblocked. Point it at a ten-year-old codebase and it can feel useless — confidently wrong, breaking things, missing the obvious. Same agent, opposite experience. The difference is greenfield versus brownfield, and understanding it tells you why the agent struggles where it does and how to help it. Here's the honest comparison. ## Two very different starting points **Greenfield** is new construction — building from scratch, no existing code to respect. **Brownfield** is renovation — working inside an existing, often aged, codebase with its own history, patterns, and constraints. For human developers, brownfield has always been harder, for the obvious reason: you have to understand what's there before you can change it safely. With agents, that same gap exists — but it bites differently, because of *what* the agent can and can't see. ## Greenfield: the agent has a clean slate On greenfield, the agent and you start from the same place: nothing. There's no hidden context to miss, because there's no history yet. Every decision is being made now, in the open, and the agent participates in making them. This is why agents shine on new projects. There's no undocumented past to misread. The context that exists is the context you're both creating, and a [contextbase](/articles/what-is-a-contextbase) here grows naturally from the first session. Greenfield is the agent's best case — give it a clear brief and let it run. ## Brownfield: tacit knowledge the agent can't see Brownfield is harder for one specific reason: the codebase is full of *tacit knowledge* — reasoning that lives in people's heads and nowhere in the code. Why this query is structured oddly (a bug workaround), why this module avoids that pattern (a past disaster), which parts are fragile (everyone just knows). The agent reads the code but not the reasoning. So it sees the odd query as a mistake and "fixes" it — reintroducing the bug. The guides on [brownfield AI development](https://thegeneralpartnership.substack.com/p/a-practical-guide-to-brownfield-ai) keep stressing this: legacy carries knowledge agents can't reach on their own, and missing the moment to inject it produces large changes full of subtle bugs. **Greenfield, the agent misses nothing because there's nothing to miss. Brownfield, it misses everything the codebase never wrote down.** ## Why specs and context matter more in brownfield This is the crux of the comparison. On greenfield, you can lean on the agent's defaults — there's no existing reality to violate. On brownfield, defaults are dangerous, because the existing system has constraints the agent doesn't know about. So brownfield demands *more* explicit context and *tighter* specs: | | Greenfield | Brownfield | |---|---|---| | Hidden context | None | Years of it | | Agent's main risk | Building the wrong thing | Breaking the existing thing | | What you must supply | A clear brief | A brief *plus* the missing context | | Spec scope | The new feature | Just the change, verified against reality | | Tests | Build them as you go | Lean on them to catch regressions | The same [spec discipline](/articles/c2-vs-spec-driven-development) helps both, but brownfield can't skip it — the spec and the captured context are what stop the agent from confidently breaking things. ## How to approach each - **Greenfield:** brief clearly, let the agent run, and capture context from session one so the project never *becomes* an opaque brownfield later. - **Brownfield:** supply the missing context. Have the agent map the area first, write specs for the change (not the whole system), capture decisions and gotchas as you go, and verify hard against existing tests. [Grow a contextbase into the legacy](/articles/document-a-codebase-with-an-agent) where you work. Greenfield lets the agent run — brownfield makes you supply the context the code never wrote down. Know which you're in, and you'll know why the agent behaves the way it does. Start here: see how to [document a legacy codebase with an agent](/articles/document-a-codebase-with-an-agent), [C² vs spec-driven development](/articles/c2-vs-spec-driven-development), or [read the method](/c2/method). --- # Least privilege for coding agents: scope the blast radius ## An agent can only do damage where you let it reach. How to apply least privilege — file scope, command limits, no prod. - URL: https://stuartleo.com/articles/least-privilege-for-coding-agents - Published: 2026-06-09 - Reading time: 4 min read - Method: C² Method An agent can only do damage where you let it reach. How to apply least privilege to coding agents — file scope, command limits, no prod, sandboxes. The most reliable safety control for AI coding agents isn't a clever filter or a better prompt. It's an old security principle: **least privilege** — give the agent only the access the task needs, and nothing more. Get this right and most ways an agent can hurt you shrink from catastrophe to inconvenience, because it simply can't reach the things that would make a mistake serious. Here's how to think in blast radius, and the concrete limits that keep an agent's reach short. ## The blast-radius mindset Stop asking "will the agent behave?" and start asking "what's the worst it could do if it didn't?" That second question is the blast radius — the set of things the agent can affect — and it's the thing you actually control. You can't guarantee an agent won't make a mistake or get [fooled by a prompt injection](/articles/defend-against-prompt-injection). What you *can* guarantee is what it's able to touch when it does. An agent that can only edit a feature folder and run the tests can't leak your secrets or wreck production, no matter how badly a single step goes wrong. Shrink the blast radius and you've capped the downside of every failure mode at once. **You can't make an agent never fail. You can make sure that when it does, it can't reach anything that matters.** This is why security teams treat AI agents like any other powerful, [imperfectly-trusted component](https://blog.cyberdesserts.com/ai-agent-security-risks/) — the control that scales is limiting reach, not predicting behaviour. ## Scope files and commands The first reach to limit is the obvious one: what the agent can read, write, and run. - **File scope.** Point the agent at the part of the codebase the task needs. It doesn't need write access to the whole repo to add a field to checkout. - **Command scope.** Restrict what it can execute. A task that edits and tests code doesn't need free rein over arbitrary shell — and arbitrary shell is how a small problem becomes a big one. Match the scope to the task. A bigger, trusted task gets more reach — a routine or autonomous one gets the minimum. The scope is a dial you set per job, not a permanent grant. ## Forbidden zones: prod, auth, payments, secrets Some areas are never worth an agent's autonomous reach, regardless of the task: - **Production systems** — a mistake here is live, immediately. - **Auth** — the keys to everything. - **Payments** — money mistakes are real mistakes. - **Secrets** — see [keeping secrets out of reach](/articles/secure-secrets-when-coding-with-agents). Declare these forbidden zones explicitly, before the work. The upside of letting an agent autonomously touch production is never worth the downside. Gate any work near them behind a human. ## Sandboxes and isolation For genuinely risky or autonomous work, don't just scope within your environment — isolate the environment itself. Run the agent in a container, a microVM, or at least a dedicated [git worktree](/articles/parallel-agents-with-git-worktrees) and branch, with no access to your host, your other projects, or anything live. Now even a total failure is contained to a box you can inspect and throw away. Isolation is least privilege applied to the *environment*, not just the file tree. ## Human approval for high-risk actions The final layer is the cheapest and most effective: for the actions that would actually hurt — deploying, deleting data, moving money, installing dependencies — require a human to approve. This is the backstop that holds when scoping and isolation miss something. An agent (or an injection driving it) can *want* to do the dangerous thing, but a human gate means it can't do it alone. Combine these — scoped files and commands, forbidden zones, isolation, human gates on the dangerous stuff — and the agent does its work with a blast radius small enough that you can let it run, including [unattended](/articles/run-agents-overnight-safely). An agent's safety is its blast radius — give it the least reach the task needs, and no more. Start here: see [how to keep secrets safe](/articles/secure-secrets-when-coding-with-agents), [running agents overnight safely](/articles/run-agents-overnight-safely), or [read the method](/c2/method). --- # Onboard to any codebase in hours with an agent ## Understanding an unfamiliar codebase took weeks. An agent can guide you through it in an afternoon. - URL: https://stuartleo.com/articles/onboard-to-any-codebase-with-an-agent - Published: 2026-06-09 - Reading time: 4 min read - Method: C² Method Understanding an unfamiliar codebase used to take weeks. An agent can guide you through it in hours — here's how to use one to get oriented fast. The worst part of joining a new project was always the same: the first two weeks of staring at an unfamiliar codebase, tracing what calls what, trying to build a map in your head from cold. Everyone paid that tax. With an AI agent, you mostly don't have to. An agent can read an entire codebase and walk you through it — and that turns the ramp from weeks of solo archaeology into an afternoon of guided exploration. Here's how to use one to get oriented fast, whether the code is someone else's or your own from two years ago. ## The weeks-long ramp Onboarding to a codebase the old way is slow because the knowledge is scattered and mostly unwritten. You read a file, follow a call into another file, lose the thread, start again. The structure is implicit, the decisions are undocumented, and the only fast path was a patient senior dev willing to walk you through it — if you had one. That ramp is exactly what an agent collapses. Enterprise teams report that onboarding to unfamiliar codebases, [once a multi-week process](https://codepick.dev/en/guides/ai-coding-agents-2026-roadmap/), now takes hours, because the agent does the tracing and summarising you used to do by hand. ## How an agent reads a codebase for you An agent has read the whole repository and can hold far more of it in view at once than you can. So instead of you tracing a flow file by file, you ask, and it traces it for you — then explains it in plain language. The shift is from *reading* the code to *interviewing* it. You ask "how does login work here?" and the agent follows the actual path through the actual files and tells you, citing where each piece lives. You ask "what would I touch to add a field to checkout?" and it points you straight at the spots. The codebase becomes something you can question, not just something you have to decode. ## Ask for the map, then the details The technique that works is broad-to-narrow: 1. **Ask for the map first.** "What is this project, what are the main parts, and how do they fit together?" Get the high-level shape before any detail. 2. **Then the neighbourhood.** "Walk me through the part that handles X" — the area you'll actually work in. 3. **Then the specifics.** "Trace this flow," "explain this file," "why is it done this way?" — drilling into what you need for the task at hand. **Don't read an unfamiliar codebase. Interview it — map first, then the neighbourhood, then the detail.** This order gives you a scaffold to hang detail on, instead of drowning in specifics with no frame. ## Capturing what you learn as you go Here's the move that turns a one-off onboarding into something that compounds: write down what you learn. As the agent explains the architecture, the decisions, the gotchas — capture them into a [contextbase](/articles/what-is-a-contextbase). Not because you'll forget (though you will), but because the *next* person to onboard — human or agent — shouldn't have to re-derive it. Most codebases have no such record, which is why onboarding is slow in the first place. The first time you onboard with an agent, you can leave behind the map nobody wrote, so the second person onboards in an hour instead of an afternoon. (This is how you'd [document an inherited codebase](/articles/document-a-codebase-with-an-agent) properly.) ## From oriented to productive Onboarding isn't the goal — shipping is. The point of getting oriented fast is to start contributing fast. Once you have the map and have drilled into your area, you're ready to brief the agent on a real task with enough context to direct it well. An agent turns weeks of reading an unfamiliar codebase into an afternoon of guided exploration. Trust its tour, verify the surprising bits, and write down what you learn so the next person skips the ramp entirely. Start here: see how to [document an inherited codebase](/articles/document-a-codebase-with-an-agent), [what a contextbase is](/articles/what-is-a-contextbase), or [read the method](/c2/method). --- # Onboarding a new dev with the contextbase ## A field note on a new developer who got productive in a day instead of a fortnight, because the contextbase held the knowledge. - URL: https://stuartleo.com/articles/onboarding-a-dev-with-the-contextbase - Published: 2026-06-09 - Reading time: 3 min read - Method: C² Method A field note on a new developer who got productive in a day instead of a fortnight, because the contextbase already held what usually lives in people's heads. A developer joined a project I'd been building with C², and was shipping real work by the end of day one. The usual ramp is two weeks. The difference wasn't the developer — it was that the knowledge they needed was already written down. This is the field note. ## The usual two-week ramp Onboarding someone normally means a slow drip of tribal knowledge. They read the code, hit a wall, find me, I explain the thing that's "obvious" once you know it, they move on, hit the next wall. Repeat for a fortnight. Most of the delay isn't the new person being slow — it's that the knowledge they need lives in my head and comes out one interruption at a time. I'd braced for exactly that. It didn't happen. ## What I handed them instead Instead of "here's the repo, ask me when you're stuck," I handed them the [contextbase](/articles/what-is-a-contextbase) — the `docs/` folder that had been compounding the whole time I'd built the project. The Router as a map. The decisions, with their reasons. The gotchas. The session briefs that traced how the project actually got to where it was. Everything I'd normally have explained in person was already written, because I'd written it for the *agent* — and it turned out a new human reads it just as well. ## The agent as a guide through the contextbase The other half was the agent. Rather than me walking them through the architecture, they did what I'd do on any unfamiliar codebase — they [had the agent guide them](/articles/onboard-to-any-codebase-with-an-agent), and the agent's tour was *good*, because it was reading the same rich contextbase, not guessing from bare code. They asked it how things worked, it answered with the actual decisions and reasons, and they built a mental model in hours. **Everything I'd normally explain in person was already written down — because I'd written it for the agent, and a new teammate reads it just as well.** This matches what teams report as agents reshape onboarding: the [ramp to an unfamiliar codebase collapses](https://resources.anthropic.com/hubfs/2026%20Agentic%20Coding%20Trends%20Report.pdf) when the context is there to read. ## Where the gaps showed It wasn't flawless. The new dev hit two areas where the contextbase was thin — corners of the codebase I'd never worked in with C², so they'd never been documented. There, they got the old experience: confusion, then asking me. Which was a useful signal — the gaps in the contextbase were exactly the gaps in the project's written knowledge. ## What I added after So they did the obvious thing: as they figured out those thin areas, they wrote them up — adding to the contextbase as they went, the same habit the project ran on. By the end of their first week, the corners that had tripped them up were documented for the next person. The contextbase didn't just onboard them faster. They left it better than they found it. The contextbase onboarded the new dev faster than I could have — the knowledge was already written down. Start here: see how to [onboard to any codebase with an agent](/articles/onboard-to-any-codebase-with-an-agent), [write a session brief](/articles/write-your-first-session-brief), or [read the method](/c2/method). --- # PRD-first vs prototype-first with AI ## Should an agent write the spec or build the prototype first? The case for each, and when a clickable beats a document. - URL: https://stuartleo.com/articles/prd-first-vs-prototype-first - Published: 2026-06-09 - Reading time: 4 min read - Method: C² Method Should an agent write the spec or build the prototype first? The case for each, when a clickable prototype beats a document, and how C² uses both. There's a live debate in AI product work: when an agent can build almost anything in an hour, why write a requirements document at all? Just have it build the prototype and react to that. The other camp says skipping the spec is how you ship fast, confident, and wrong. Both have a point, and the truth is they're answering different questions. Here's the honest comparison of PRD-first versus prototype-first, and how to use each instead of picking a side forever. ## Two ways to start a feature When you start a feature with an agent, you can lead with either artifact: - **PRD-first.** Write the [requirements](/articles/what-is-a-prd-in-ai-development) — what to build, why, the constraints, the definition of done — then build against them. - **Prototype-first.** Have the agent build a rough, clickable version *now*, then react to the real thing and refine from there. PRD-first decides on paper, then builds. Prototype-first builds, then decides. The right call depends on what you're actually uncertain about. ## PRD-first: decide, then build PRD-first shines when you *know what you want* and the risk is building it wrong, inconsistently, or with the wrong boundaries. The spec pins down intent so the agent — which will otherwise fill gaps with assumptions — builds the right thing the first time. It's the stronger choice when the cost of a wrong build is high, when multiple people (or agents) need to align on the same target, or when the feature touches things that are expensive to get wrong. The PRD is cheap insurance against a confident, expensive mistake. ## Prototype-first: build, then react Prototype-first shines when the uncertainty is *what to build at all*. A document describing a flow invites endless debate — a clickable prototype you can actually use settles questions in minutes. And agents made this cheap — when a working prototype costs an hour, building one is often a faster way to learn than writing another spec. The product world has noticed: the shift toward [prototypes over PRDs](https://alloy.app/library/product-agents-prds-to-prototypes) is real, because a prototype gives teams something to test immediately rather than another document to read and debate. Progress gets measured by feedback on something real. **A PRD gets you agreement on a description. A prototype gets you feedback on the thing itself. When you're unsure what to build, feedback beats agreement.** ## When each wins | Your biggest uncertainty | Start with | |---|---| | *What* to build / is it worth it | **Prototype** — get real feedback fast | | *How* it should work, exactly | **Prototype** — react to a clickable version | | Building it right and consistently | **PRD** — pin the target before building | | High cost of a wrong build | **PRD** — spec is cheap insurance | | Multiple people/agents must align | **PRD** — one shared source of truth | The deciding question is simple: *what am I most unsure about?* If it's whether the idea is right, prototype. If it's whether the build will be right, spec. ## How C² cascades from PRD but ships fast The false choice is treating these as permanent rival philosophies. In practice the strongest flow uses both, in sequence: **prototype to decide, then spec to build.** A quick prototype burns down the "what should this be" uncertainty. Once you know, a tight PRD captures the decision — and in C² that PRD [cascades](/articles/the-cascade-from-prd-to-prompt-brief) into the scoped briefs an agent builds from, so the real build is rigorous and on-target. You lose nothing. The prototype gives you speed and feedback up front — the PRD-and-cascade gives you a reliable build after. Prototype-first and PRD-first aren't a fork in the road — they're two stages of the same road. A PRD decides what's worth building, and a prototype tests whether you were right — good work uses both, in order. Start here: see [what a PRD is and why agents need one](/articles/what-is-a-prd-in-ai-development), [the Cascade from PRD to brief](/articles/the-cascade-from-prd-to-prompt-brief), or [read the method](/c2/method). --- # Rolling C² out to my team: what stuck, what didn't ## A field note on introducing C² to a team — what caught on immediately, what met resistance, and what I'd do differently. - URL: https://stuartleo.com/articles/rolling-c2-out-to-my-team - Published: 2026-06-09 - Reading time: 3 min read - Method: C² Method A field note on introducing C² to a team — the parts that caught on immediately, the parts that met resistance, and what I'd do differently. I introduced C² to a team that was already using AI agents ad hoc, and the rollout taught me more about adoption than about the method. Some of it caught on the same week. Some of it I had to stop pushing. This is the field note on what stuck, what didn't, and what I'd do differently. ## Why I introduced it The team was getting value from agents individually, but it evaporated between people. One person's hard-won understanding never reached the next. Context got re-explained constantly. Agents relearned the same things across desks. The work wasn't compounding — it was being rediscovered, over and over, by whoever sat down next. C² was my answer to that, and I rolled it out with more enthusiasm than strategy. ## What caught on fast (session briefs) The [session brief](/articles/write-your-first-session-brief) was an immediate hit, and I should have predicted why: it paid off the *same week*, visibly. Someone wrote a brief on Tuesday, someone else picked up the work on Thursday and started in minutes instead of an hour — and everyone saw it happen. The habit sold itself because the benefit was instant and personal. Nobody needed convincing after the second time it saved them. **The habits that stuck were the ones that saved someone time the same week. The ones I had to justify with "it'll pay off later" mostly didn't.** ## What met resistance The things that paid off *later* met resistance. The fuller PRD and Cascade discipline felt like process overhead to people under deadline pressure — the benefit was real but deferred, and deferred benefits lose to today's deadline every time. When I pushed those hard, up front, I got compliance theatre: documents written to satisfy me, not because anyone found them useful. That's worse than nothing. ## The crawl-walk-run that worked What actually worked was backing off and going [crawl-walk-run](/articles/crawl-walk-run-adopting-ai-agents), which is the same advice for adopting agents and apparently for adopting *methods* too. I stopped mandating the whole system and started with the one habit that paid off immediately — session briefs and capturing gotchas. Once those were second nature and people *felt* the context compounding, the appetite for the heavier tiers came on its own, pulled by need instead of pushed by me. The teams that get AI adoption right [build day-to-day proficiency first](https://larridin.com/solutions/ai-adoption-the-complete-enterprise-guide-2026) rather than mandating the full apparatus on day one. ## What I'd do differently If I rolled it out again, I'd lead with the cheapest, fastest-paying habit and shut up about the rest until it was asked for. Start with session briefs and gotchas — the things that save time *this week*. Let people feel context compound before introducing anything that costs effort now for payoff later. The method is right either way. The mistake was rolling it out as a system to adopt instead of a habit to start. The contextbase habits that stuck were the ones that saved the team time the same week — start there. Start here: see the [crawl-walk-run adoption path](/articles/crawl-walk-run-adopting-ai-agents), [how to write a session brief](/articles/write-your-first-session-brief), or [read the method](/c2/method). --- # Keep secrets safe when coding with agents ## An agent with shell access and secrets in scope is the worst-case setup. How to keep keys out of its reach. - URL: https://stuartleo.com/articles/secure-secrets-when-coding-with-agents - Published: 2026-06-09 - Reading time: 4 min read - Method: C² Method An agent with shell access and secrets in scope is the worst-case setup. How to keep API keys and credentials out of an agent's reach — and out of its context. Secrets — API keys, tokens, database credentials — are where coding-with-agents gets genuinely dangerous, and where a lot of otherwise careful people are sloppy. An agent that can run shell commands, with secrets sitting in its reach, is close to the worst configuration you can build: one prompt injection or one careless command away from leaking the keys to your kingdom. The good news is that keeping secrets safe with agents is mostly a few firm habits. Here they are. ## The worst-case configuration Security researchers have a name for the most dangerous setup, and it's worth burning into memory: an agent with **bash permissions on a runner with secrets in scope**. That's the configuration where things go catastrophically wrong, because the agent can both *access* the secret and *act* on it — read the key and then exfiltrate it. The [worst real-world incidents](https://render.com/articles/security-best-practices-when-building-ai-agents) trace back to exactly this combination of broad access and secrets within reach. So the whole game is keeping those two things apart: the agent's ability to act, and the secrets themselves. ## Keep secrets out of the context window The first rule: a secret should never enter the agent's context. Not in a file it reads, not pasted into the chat, not printed by a command it runs. This matters because the context window is *leaky* by nature. Whatever's in it may be sent to the model provider, logged, cached, or carried into a summary. A secret that touches the context has, for safety purposes, left the building — you can't be sure where it went. So the rule isn't "be careful with secrets in context." It's "secrets never go in context at all." **A secret that enters the context window is a secret you've half-leaked. The only safe amount in the agent's context is none.** ## Environment variables, never in code The mechanism that keeps secrets out of reach is the same one good engineering already uses: keep secrets in **environment variables** (or a proper secrets manager), reference them by *name* in code, and keep the values out of the repo entirely. ```python # Right: the agent sees a reference, never the value api_key = os.environ["STRIPE_API_KEY"] # Wrong: the secret is now in a file the agent reads api_key = "sk_live_51H...." ``` The agent reads the code, sees `os.environ["STRIPE_API_KEY"]`, and learns *that a key is needed* — not the key. The actual value lives in the environment, which the agent has no reason to print and you give it no reason to read. (Your `.env` file is gitignored, always.) ## Scope what the agent can run Even with secrets out of code, an agent with unrestricted shell could still go fishing — `env`, `cat` a config, hit a metadata endpoint. So pair "secrets out of context" with "limit what the agent can do," which is [least privilege](/articles/least-privilege-for-coding-agents): scope its commands and file access so the paths to a secret are closed. The two rules reinforce each other — keep the secret out of reach, *and* keep the agent's reach short. This matters most for [autonomous and overnight runs](/articles/run-agents-overnight-safely), where no one's watching. An unattended agent should never have a path to a production secret, full stop. ## If a secret leaks, rotate Sometimes it happens anyway — a command prints a key, a config gets read, a value slips into the chat. When it does, the response is simple and non-negotiable: **rotate the secret immediately.** Assume it's compromised. Rotation is cheap. Assuming "it was probably fine" is how a leaked key becomes an incident. Treat any secret that touched the context window as burned, rotate it, then fix the path that let it in. Never let a secret into the agent's context or its blast radius — keep keys in the environment, scoped tight. Start here: see [least privilege for coding agents](/articles/least-privilege-for-coding-agents), the [field note on a leaked secret](/articles/the-secret-that-leaked-into-context), or [read the method](/c2/method). --- # The Cascade: from PRD to Prompt Brief ## Big goals don't fit in one prompt. The C² Cascade breaks work from Platform PRD down to a brief an agent can build. - URL: https://stuartleo.com/articles/the-cascade-from-prd-to-prompt-brief - Published: 2026-06-09 - Reading time: 4 min read - Method: C² Method Big goals don't fit in one prompt. The C² Cascade breaks work from Platform PRD down to the Prompt Brief an agent can actually build. How the tiers fit. Here's a mistake that feels productive and isn't: handing an agent a big goal — "build the billing system" — in one prompt and turning it loose. The agent will produce *something*, sprawling and hard to review, drifting from intent as it goes. Big goals don't survive contact with a single prompt. The fix is to break work down in steps, each tier sharper and smaller than the last, until you reach something an agent can build cleanly. In C² that chain is the **Cascade**. Here's how it works and why each tier earns its place. ## Why one big prompt fails A big feature carries too much ambiguity for one build. The agent has to make dozens of unstated decisions along the way, and with no checkpoints it makes them all at once, confidently, in one giant diff. By the time you see the result, the small wrong turns have compounded into a mess that's hard to review and harder to correct. The teams writing [PRDs for AI coding agents](https://medium.com/@haberlah/how-to-write-prds-for-ai-coding-agents-d60d72efb797) hit this constantly: the requirements doc and the unit an agent should build are not the same size. You need a way down from one to the other. ## The cascade tiers, top to bottom C² breaks every piece of work through the same chain: ``` Platform PRD └── Feature PRD ← one per feature, a living document └── Prompt Brief × N ← the atomic build unit └── Task × N ← optional, for bigger briefs └── Session Brief ← every session, no exceptions └── Release Note (optional) ``` Intent flows *down* — broad goal to scoped build. Learning flows *back up* — each session brief feeds what was discovered into the record. The Cascade is that two-way chain: decisions descend, knowledge ascends. ## Platform PRD and Feature PRD The top tiers hold *intent*, not implementation: - **Platform PRD** — the whole product's direction. The why, the shape, the big constraints. - **Feature PRD** — one per feature, and a *living* document. Not frozen at creation — it evolves as design and engineering reality changes. A PRD that never changes is one nobody's reading. These answer "what is being built, and why." They're too big to hand an agent directly, which is the point — they're the source the smaller units derive from. ## The Prompt Brief: the atomic build unit This is where the Cascade earns everything. The **Prompt Brief** is the atomic build unit — a scoped spec for one piece of work an agent can build in a single session. It carries: - what to build, and what *not* to, - what to read first (the relevant context), - the [acceptance criteria](/articles/acceptance-criteria-for-agents) — how you'll know it worked. **The Prompt Brief is where direction becomes execution. Its quality is the bottleneck — not the agent's capability.** This is the handoff point from pilot to crew. A sharp brief produces a clean, reviewable, verifiable change. A vague one produces drift. Almost all of your leverage as a [pilot](/articles/the-pilot-model-directing-ai-agents) lives in writing good briefs — which is why the Cascade exists to get you to one. ## How work flows down and learning flows up The Cascade isn't just decomposition — it's a loop. Work descends from PRD to brief to the agent's hands. Then the [session brief](/articles/write-your-first-session-brief) at the bottom sends what was learned back up: a discovered constraint updates the Feature PRD, a trap becomes a gotcha, a finished brief produces a release note. The living Feature PRD absorbs reality from the work below it. So the Cascade turns a big, ambiguous goal into a stream of small, sharp, buildable briefs — and turns the learning from building them back into the record. Big work reaches an agent as a small, sharp brief — the Cascade is how you get from a goal to that brief. Start here: learn [what a PRD is and how to write one with an agent](/articles/what-is-a-prd-in-ai-development), [write acceptance criteria the agent can check](/articles/acceptance-criteria-for-agents), or [read the method](/c2/method). --- # The legacy codebase the agent couldn't read ## A field note on pointing an agent at a ten-year-old codebase and watching it confidently misunderstand everything. - URL: https://stuartleo.com/articles/the-legacy-codebase-the-agent-couldnt-read - Published: 2026-06-09 - Reading time: 3 min read - Method: C² Method A field note on pointing an agent at a ten-year-old codebase, watching it confidently misunderstand everything, and the context that finally let it help. I pointed a capable agent at a ten-year-old codebase expecting magic, and got a confident vandal instead. This is the field note on why the agent couldn't read code that I could, and what finally let it help. ## The inheritance The codebase was old, large, and effectively undocumented — a decade of decisions, workarounds, and "don't touch that" knowledge, none of it written down. I'd half-inherited it myself and was still finding my way. So I did the obvious thing: handed the agent a change and let it loose, assuming it would read the code and figure it out the way it does on my own projects. ## Why the agent kept guessing wrong It didn't figure it out. It *guessed*, confidently, and the guesses were wrong in a particular way. It "simplified" a gnarly date calculation — and broke a timezone fix that had taken someone a week in 2019. It "cleaned up" a redundant-looking check — which was guarding against a malformed input that still showed up in production. Every change looked like an improvement and was a regression. The agent wasn't being stupid. It was reading the only thing available to it — the code — and the code doesn't explain itself. ## The tacit knowledge nowhere in the code That was the lesson, and it took me embarrassingly long to see. The thing the agent needed wasn't in the codebase at all. It was *tacit knowledge* — the why behind the weird query, the reason for the redundant check, which parts were load-bearing and which were dead. That knowledge lived in people's heads and in a couple of long-departed contributors' memories. The agent couldn't read what was never written. This is the trap every guide to [agents in legacy code](https://www.epam.com/insights/ai/blogs/using-spec-kit-for-brownfield-codebase) warns about: legacy carries knowledge the agent simply cannot reach. **The agent could read every line and still misunderstand the code, because the part that mattered was never in the lines.** ## Writing down what only the old hands knew So I stopped expecting the agent to infer the unwriteable and started writing it down. Each time I worked out *why* something was the way it was — asking the one person who remembered, reading old tickets, archaeology — I captured it as a gotcha or a decision in a contextbase, right next to the code it explained. The timezone fix got a note. The malformed-input check got a note explaining what it guarded. The fragile module got a "here be dragons" with the reasons. ## When it finally clicked Once the agent was reading those notes before touching that code, it stopped vandalising. It left the timezone fix alone because the note told it why. It preserved the check because the note explained the input. The same agent that had been a confident vandal became genuinely useful — not because it got smarter, but because it could finally read the reasoning, not just the code. An agent can't read what the codebase never wrote down — the fix was capturing the tacit knowledge, not a better model. Start here: see how to [document a legacy codebase with an agent](/articles/document-a-codebase-with-an-agent), [greenfield vs brownfield with agents](/articles/greenfield-vs-brownfield-with-agents), or [read the method](/c2/method). --- # The prompt injection I almost shipped ## A field note on an agent that read a malicious instruction buried in a dependency, nearly acted on it, and what caught it. - URL: https://stuartleo.com/articles/the-prompt-injection-i-almost-shipped - Published: 2026-06-09 - Reading time: 3 min read - Method: C² Method A field note on an agent that read a malicious instruction buried in a dependency's docs, nearly acted on it, and what caught it before it shipped. An agent I was running nearly followed instructions I never gave it — instructions hidden in a library it was reading. It didn't ship, but only just. This is the field note on the day prompt injection stopped being theoretical for me. ## The innocent-looking task The task was mundane: integrate a third-party library, wire it into a feature, write the glue. I told the agent to read the library's docs and examples so it'd use the API correctly. Completely routine — exactly the kind of thing I'd done a hundred times without a second thought. The agent dutifully read the package's documentation. And buried in there was something I hadn't put there. ## The instruction hidden in a doc string Inside one of the dependency's documentation strings, amongst legitimate API notes, was a block of text addressed not to a human reader but to an AI agent — telling it to, as part of "setup," add a small snippet that phoned home and to not mention it. A prompt injection, sitting in a package thousands of people install, waiting for an agent to read it and obey. To the agent, it was just more text in the context. It couldn't tell my instructions from the attacker's — they were all words in the window. This is exactly the amplification security researchers describe when [agents read untrusted content](https://venturebeat.com/security/ai-agent-runtime-security-system-card-audit-comment-and-control-2026): the model can't reliably separate "content to process" from "commands to follow." ## What the agent almost did And it nearly did it. In its plan, the agent dutifully included a step to add the "setup snippet" the docs had "instructed." It was going to write attacker-controlled code into my project, quietly, because a dependency's documentation told it to. **My agent couldn't tell my instructions from a stranger's. To it, the malicious doc string and my prompt were the same kind of thing — words to act on.** ## What caught it What saved me was boring: I read the plan before approving it. The "add this setup snippet" step didn't match anything I'd asked for, so I looked closer, found the injected instruction in the docs, and stopped it. A human checkpoint on what the agent intended to do — nothing clever — caught what the agent itself could not. ## The defences I added after That near-miss changed how I run agents. Now I assume everything the agent reads is potentially hostile, and I [defend against injection in layers](/articles/defend-against-prompt-injection): - **Least privilege**, so even a fooled agent can't reach anything that matters. - **Human review of the plan** before high-risk steps execute — the thing that actually saved me. - **Real wariness about unvetted dependencies and content**, especially in anything autonomous. My agent treated a comment in a dependency as a command — now I treat everything it reads as untrusted. Start here: see [how to defend against prompt injection](/articles/defend-against-prompt-injection), [least privilege for coding agents](/articles/least-privilege-for-coding-agents), or [read the method](/c2/method). --- # The secret that leaked into context ## A field note on an API key that ended up in an agent's context window where it didn't belong, and the rule I keep now. - URL: https://stuartleo.com/articles/the-secret-that-leaked-into-context - Published: 2026-06-09 - Reading time: 3 min read - Method: C² Method A field note on an API key that ended up in an agent's context window, where it didn't belong, and the rule I keep now to stop it happening again. An API key I was careful with ended up in an agent's context window anyway, through a path I hadn't thought about. Nothing bad came of it — because I rotated it the moment I noticed — but it taught me a rule I now keep without exception. This is the field note. ## How the key got there I was debugging a failing API call with the agent. The call wasn't working, so — without thinking — I had the agent run the request with verbose output to see what was going wrong. The verbose output dutifully printed the full request, headers and all, including the `Authorization` header with the live API key in it. There it was, in plain text, in the agent's context. I hadn't pasted it. I hadn't put it in a file. A debug command I asked for had pulled it out of the environment and into the window, and I almost scrolled right past it. ## Why context is the wrong place for a secret For a second I thought "no harm done, it's just in the chat." Then I remembered why that's wrong. The context window isn't a private scratchpad — its contents get sent to the model provider, can be logged, can be cached, can be carried into a summary. A secret that lands in context hasn't necessarily *leaked*, but you can no longer prove it *didn't*. As the security writeups on [AI agent vulnerabilities](https://cycode.com/blog/ai-security-vulnerabilities/) keep stressing, anything an agent's session touches has to be treated as potentially exposed. **A secret in the context window isn't necessarily leaked — but you can't prove it wasn't. For a credential, that's the same thing.** ## The near-miss So it was a near-miss, not a disaster, and the difference was entirely that I noticed. If I hadn't been looking at the output, that key would have sat in the context, gone to the provider, possibly been logged — and I'd never have known to rotate it. "Probably fine" would have been my whole security posture, by accident. ## Pulling secrets out of reach The immediate fix was simple: rotate the key, assume the old one burned. Rotation is cheap, and "it was probably fine" is exactly the thought that turns a near-miss into an incident. The lasting fix was to make sure secrets can't reach the context in the first place — [keep them in the environment](/articles/secure-secrets-when-coding-with-agents), referenced by name, never printed. And to be deliberate about debug commands: verbose output is a classic way for a secret to leap from the environment into the window. ## The rule I keep now Two rules, actually, and I don't bend them: - **A secret never knowingly enters the context.** Not pasted, not in a file, not printed by a command I run. If I need to debug an authed call, I redact first. - **If a secret touches the context, it's burned.** Rotate immediately, no judgement calls about whether it "really" leaked. A secret in the context window is a secret you've half-leaked — keep keys in the environment, never in what the agent reads. Start here: see how to [keep secrets safe when coding with agents](/articles/secure-secrets-when-coding-with-agents), [least privilege for coding agents](/articles/least-privilege-for-coding-agents), or [read the method](/c2/method). --- # What is a PRD, and why agents need one ## A product requirements document says what to build and why — and an agent needs it even more than a human team does. Here's what goes in one, and how to write it with an agent. - URL: https://stuartleo.com/articles/what-is-a-prd-in-ai-development - Published: 2026-06-09 - Reading time: 6 min read - Method: C² Method A PRD (product requirements document) says what to build and why. Why AI agents need one more than human teams, what goes in it, and how to draft one. "PRD" is one of those acronyms that sounds like process overhead — a document you write to satisfy someone, then never read. In AI development it's the opposite: it's the difference between an agent building the thing you wanted and an agent building something plausible that misses the point. And agents need one more than human teams ever did. Here's what a PRD actually is, why it matters even more when an agent is doing the building, how it relates to the prompts and briefs you already use, and how to write one with an agent without drowning it in filler. ## What a PRD is A PRD — **product requirements document** — is a written description of what to build and why. A good one answers a few plain questions: what problem it solves, who it's for, what it must do, what it must *not* do, and how you'll know it worked. That's it. It's not a spec in the sense of every implementation detail. It's the *intent*, the source of truth that keeps everyone building the same thing. Strip away the corporate baggage and a PRD is just: here's what you're making, and here's how you'll know you got it right. ## Why agents need requirements, not vibes Here's the thing that surprises people coming from "just chat with the AI." An agent is *more* dependent on clear requirements than a human team, not less. A human handed a vague ask will push back: "wait, what about refunds?", "do users have accounts?". An agent mostly won't. Handed a vague ask, it makes an assumption and builds confidently on it. The result looks finished and is subtly wrong, because the requirements it needed were never stated, so it invented them. The teams writing [PRDs specifically for AI code generation](https://www.chatprd.ai/learn/prd-for-ai-codegen) keep finding the same thing: the agent's output quality is downstream of how clearly the requirements were written. **A human with a vague brief asks questions. An agent with a vague brief makes assumptions, and builds on them confidently.** ## What a good PRD contains A PRD that's actually useful to an agent is tight, not long: - **The problem and who it's for.** Why this exists, for whom. One tight paragraph. - **What it must do.** The core requirements, in plain language. - **What it must *not* do.** The boundaries, often more useful than the requirements because they stop the agent over-building. - **Decisions and constraints.** "Payments via this provider." "No user accounts yet." The choices already made, so the agent doesn't undo them. - **How you'll know it worked.** The acceptance criteria, ideally [things you can run](/articles/acceptance-criteria-for-agents). Notice none of that is implementation detail. It's intent and boundaries. The agent figures out the *how*. The PRD nails the *what* and the *why*. If a section isn't one of these, question whether it earns its place. Most PRD bloat is sections that exist out of habit, not need. ## PRD vs prompt vs brief These three get tangled, so here's the clean split: | | What it is | Scope | |---|---|---| | **PRD** | What to build and why | A feature or product | | **Brief** | A scoped spec for one unit of work | A session's work | | **Prompt** | A single instruction | One message | The PRD *decides*. The brief *scopes* a piece of that decision into something an agent can build in a session. The prompt is just the message inside the work. In C², these stack: a PRD cascades down into briefs, which the agent executes. (That flow is [the Cascade](/articles/the-cascade-from-prd-to-prompt-brief).) ## Your first PRD You don't need a template or a tool. Open a file and answer the questions: what am I building, for whom, what must it do and not do, what decisions are already made, and how will I know it worked. A page is plenty. Commit it to your contextbase. You can write that page yourself, or you can draft it with an agent. Both work, as long as you know what the agent is good at and what it isn't. ## Writing a PRD with an agent An AI agent will write you a product requirements document in about ninety seconds. It'll also pad it into five pages of plausible-sounding filler in the same ninety seconds. Both happen by default, which is why "have the agent write the PRD" produces either something genuinely useful or something that wastes everyone's time, depending entirely on how you direct it. Drafting with an agent is worth doing because the agent is fast at structure. It'll organise your thinking into clean sections, surface questions you hadn't considered, and turn a messy brain-dump into something readable in moments. What it can't do is supply the *content*: the actual decisions, constraints and intent. That's yours. The agent is a fast drafter and a useful interrogator, not a source of requirements. ### Give it context, not a blank prompt The single biggest determinant of PRD quality is how much context you bring. Hand an agent "write a PRD for a referral feature" and you get generic, padded requirements that could apply to any product. Hand it the problem, the users, the constraints and the decisions already made, and it produces something specific and useful. The teams writing the best [AI-assisted PRDs](https://www.chatprd.ai/learn/using-ai-to-write-prd) all say the same thing: provide detailed context up front rather than expecting a complete document from a thin prompt. **A blank prompt gets you a generic PRD. The agent's quality is capped by the context you bring to it.** So start by dumping what you know, even messily: the problem, who it's for, what you've decided, what you're unsure about. Then direct the agent toward the five sections above and nothing else. Push hard on the non-goals. The agent will under-weight what the feature must *not* do, and that's the section that stops over-building. ### Cut the fluff the agent loves Models pad. Left alone, an agent adds hedging, restates the obvious, and inflates a one-line decision into a paragraph. That's length that *reads* thorough and *buries* the actual decisions. So the last step is always to cut. Read the draft and delete everything that isn't a decision or a requirement. If a sentence doesn't change what gets built, it goes. A tight one-page PRD an agent can act on cleanly beats a five-page one where the three real constraints are lost in filler. Ask the agent directly to "cut this to the decisions." It's good at that when told. ## From PRD into the build A PRD isn't the end. It's the top of a chain. Once it's tight, it cascades down into the scoped briefs an agent actually builds from: PRD decides, brief executes. Commit the PRD into your contextbase so every brief derived from it, and every agent working on the feature, builds against the same source of truth. An agent without a PRD builds something plausible. A PRD, with your decisions in it and the filler cut out, is how you make sure it builds the right thing. Start here: see [the Cascade from PRD to brief](/articles/the-cascade-from-prd-to-prompt-brief), weigh [PRD-first vs prototype-first](/articles/prd-first-vs-prototype-first), or [read the method](/c2/method). --- # Why most AI agent pilots never reach production ## Most AI agent pilots never ship — and it's rarely the agent's fault. The real blockers are governance, context and trust. - URL: https://stuartleo.com/articles/why-agent-pilots-never-reach-production - Published: 2026-06-09 - Reading time: 4 min read - Method: C² Method Most AI agent pilots never ship — and it's rarely the agent's fault. The real blockers are governance, context and trust, and how to clear them. There's a strange pattern in AI adoption: the demos are dazzling, and almost nothing makes it to production. Teams run a pilot, the agent does something impressive, everyone's excited — and then it quietly never ships. The instinct is to blame the agent. The agent is rarely the problem. What kills agent pilots is the scaffolding around them, not the agent inside them. Understanding that changes what you work on to get past the graveyard. ## The pilots that never ship The numbers are sobering: the large majority of agent pilots never reach production. Reporting on [enterprise agent deployment](https://northflank.com/blog/enterprise-ai-coding-agent-deployment) puts the figure around 88% — pilots that proved the agent *could* do the work and then stalled before it ever ran on real code at scale. That gap is the whole story. It's not "can the agent do it?" — the pilot already answered yes. It's "can the agent do it *here*, on real production systems, safely, repeatably?" — and that's a different question the demo never touched. ## It's not the agent — it's the scaffolding A pilot is a controlled demo. Production is an environment with security teams, compliance requirements, audit needs, and real consequences for mistakes. The agent that shone in the demo now has to satisfy all of that — and usually nobody built the scaffolding to let it. **The pilot proves the agent can code. Production asks whether you can let it — safely, auditably, repeatably. Those are different questions.** The blocker is rarely capability. It's that the path from "impressive demo" to "trusted on production code" runs through a set of unglamorous requirements the demo skipped. ## Governance, context, trust Three things, specifically, stand between a pilot and production: - **Governance.** Identity and access (who is this agent, what can it touch), logging and auditability (what did it do), code review and incident controls (what happens when it's wrong). Security teams won't let an agent near production without these, and pilots almost never have them. - **Context.** A pilot works on a toy problem with everything in view. Production code is vast and full of undocumented decisions. Without a durable [contextbase](/articles/what-is-a-contextbase), the agent's output is inconsistent and untrustworthy at scale — brilliant on the demo, unreliable on the real thing. - **Trust.** Earned, not declared. A team that hasn't built up evidence of where the agent is reliable won't — and shouldn't — hand it production work. Trust comes from a track record, which comes from starting small. Miss any of the three and the pilot stalls, no matter how good the agent. ## What production-ready actually needs So "production-ready" is mostly about the environment, not the model. It needs the agent to have a scoped identity and permissions, its actions logged, its work reviewed, its blast radius limited, and — critically — a context layer rich enough that its output is consistent across the real codebase, not just the demo. This is also why the [crawl-walk-run](/articles/crawl-walk-run-adopting-ai-agents) path matters: it builds the trust and context in the lower gears, so by the time you want production, the scaffolding exists. ## Closing the gap If your pilot is stuck, the fix usually isn't a better agent. It's building the three things the demo skipped: the governance to satisfy your org, the context to make output reliable, and the track record to earn trust. Heavy [enterprise platforms](/articles/c2-vs-enterprise-ai-platforms) sell some of the governance piece — but the context, the part that makes the agent actually good on your code, is the part you own and build yourself. Agent pilots stall on governance and context, not capability — fix those and the agent was ready all along. Start here: see the [crawl-walk-run adoption path](/articles/crawl-walk-run-adopting-ai-agents), [C² vs enterprise AI platforms](/articles/c2-vs-enterprise-ai-platforms), or [read the method](/c2/method). --- # Write acceptance criteria your agent can check itself ## The difference between an agent that drifts and one that self-verifies is criteria you can run. - URL: https://stuartleo.com/articles/acceptance-criteria-for-agents - Published: 2026-06-08 - Reading time: 4 min read - Method: C² Method The difference between an agent that drifts and one that self-verifies is acceptance criteria you can run. How to write briefs with criteria the agent checks itself. There's a clean line between an AI agent that builds what you meant and one that drifts off into plausible nonsense. It isn't the model. It's whether you told the agent how to know it was done — in a way it can actually check. That's what acceptance criteria are: the definition of *done*, written so the agent can verify it itself. Get them right and the agent stops handing you confident, wrong work. Here's how. ## Why agents drift from intent Give an agent a vague goal — "improve the checkout" — and it will do *something*. It has no way to know what "improved" means to you, so it optimises for something plausible. Each step takes it a little further from what you actually had in mind, and because every step looks reasonable in isolation, you don't notice until you're well off course. This is the drift that makes people distrust agents. It isn't the agent being careless. It's the agent flying without a target. The spec-driven development community has a sharp diagnosis for it: the failure mode of agents that [produce plausible code that drifts from intent](https://thebcms.com/blog/spec-driven-development) is the absence of a checkable spec, not a weak model. ## Criteria versus opinions Here's the test that fixes most of it. For everything you'd call a requirement, ask: *can I run this?* - "The form rejects an empty email." → You can test it. **Criterion.** - "The form should be robust." → Nobody can check that objectively. **Opinion.** - "Bookings past capacity are refused." → Testable. **Criterion.** - "Make the checkout feel premium." → Unrunnable as written. **Opinion.** **If you can't run the criterion, it's an opinion — and the agent will quietly ignore it.** Opinions aren't useless — they belong in the design conversation. But they can't be acceptance criteria, because the agent can't verify them, which means it won't. ## Writing runnable acceptance criteria Turn each requirement into something with an observable, checkable outcome: ``` Acceptance criteria — booking form - Submitting with no email is rejected with an error. - Booking a class at capacity (10/10) is refused. - Booking the 10th seat of a 10-seat class succeeds. - A successful booking sends one confirmation email. - The full test suite passes. ``` Each line is a thing you — or the agent — can actually do and observe. Where you can, make them literal commands or tests. "The test suite passes" is the strongest criterion of all, because it's unambiguous and the agent can run it without you. ## Letting the agent self-verify Here's the payoff. Once the criteria are runnable, the agent can check its own work *before* it hands it back. It builds, runs the criteria, sees the 11th-booking case still succeeds when it shouldn't, fixes it, and re-runs — all without you in the loop. That's the difference between an agent that needs babysitting and one that can run a task to a real finish. Criteria you can run turn "I think this is done" into "this meets the bar, here's the proof." For genuinely autonomous work — the agent building while you're away — this isn't optional. Unrunnable criteria mean unattended drift. ## Criteria in the brief cascade Acceptance criteria aren't a separate document. They belong in the brief — the short spec of what to build. A C² Prompt Brief carries them as a standard section: what to build, what *not* to build, what to read first, and how you'll know it worked. Put them there and every task starts with its finish line drawn. When the work is done, the criteria also tell your [session brief](/articles/write-your-first-session-brief) what to record as *verified* — and what isn't. The honesty about what's actually been checked carries forward to the next session. If you cannot run the criterion, it is an opinion — and the agent will quietly ignore it. Make the finish line something the agent can see. Start here: see [C² vs spec-driven development](/articles/c2-vs-spec-driven-development), how to [write a session brief](/articles/write-your-first-session-brief), or [read the method](/c2/method). --- # Agentic coding vs AI pair programming ## Pair programming has the AI beside you, suggesting. Agentic coding has it running the loop while you direct. - URL: https://stuartleo.com/articles/agentic-coding-vs-ai-pair-programming - Published: 2026-06-08 - Reading time: 4 min read - Method: C² Method Pair programming has the AI beside you, suggesting. Agentic coding has it running the loop while you direct. The difference, and which one you're doing. "Coding with AI" covers two genuinely different ways of working, and conflating them is why people talk past each other about whether AI is overhyped. One is **AI pair programming** — the AI beside you, suggesting as you type. The other is **agentic coding** — the AI running the task while you direct. They feel similar from the outside and are nothing alike in practice. Knowing which you're doing matters, because they reward completely different habits. Here's the comparison. ## AI pair programming: the AI suggests Pair programming with AI is the descendant of autocomplete. The AI sits alongside you — completing lines, suggesting the next block, answering "how do I do X" inline. You're still the one driving, keystroke by keystroke. The AI is a very good pair partner whispering ideas, but your hands are on the keyboard and you're making every move. It's a real productivity boost, and for some work it's exactly right. The defining trait: *you're still doing the coding,* just faster and with help. ## Agentic coding: the agent acts [Agentic coding](/articles/what-is-agentic-coding) moves the AI from suggesting to *acting*. You hand it a task. It plans, edits across files, runs commands, checks results, and iterates in a loop — and comes back with work done. You weren't typing through it. You were directing it and reviewing the output. The defining trait here is the opposite: *the agent does the coding,* and you do the directing. That's not a faster version of pair programming. It's a different job for you. **Pair programming keeps your hands on the keyboard. Agentic coding moves them to the controls.** ## The shift from beside-you to directed-by-you The real distinction isn't the tool — it's where *you* sit. Pair programming keeps you in the crew seat, doing the work with a helper. Agentic coding moves you to the [pilot's seat](/articles/the-pilot-model-directing-ai-agents), directing a crew that does the work. That shift is the whole story, and it's why the habits differ: | | AI pair programming | Agentic coding | |---|---|---| | Your role | Coder, with help | Pilot, directing | | The AI's role | Suggests as you type | Runs the task in a loop | | Your hands | On the keyboard | On the controls (briefs, review) | | Unit of work | The line, the block | The task, the brief | | What you optimise | Typing with good suggestions | Clear briefs, context, verification | | Scales to | Faster individual coding | Large, well-specified work | ## What each is good for Both have a place: - **Reach for pair programming** when the work is exploratory, delicate, or you want fine control — learning a codebase, a tricky bit you want to feel your way through, a change where you want every line under your hand. - **Reach for agentic coding** when the work is well-specified enough to brief — a feature with clear acceptance criteria, a refactor with tests, anything where you can say what "done" looks like and let the agent run. Most builders do both, and many experienced engineers describe [a blended workflow](https://medium.com/@addyosmani/my-llm-coding-workflow-going-into-2026-52fe1681325e) that shifts between the two by task. But the mode that changes how much you can ship is the agentic one, because it stops capping output at your typing speed. ## Moving from one to the other If you're coming from pair programming, the move to agentic coding is less about the tool and more about *letting go of the keyboard*. Instead of accepting suggestions, you write the brief. Instead of typing the fix, you specify the [acceptance criteria](/articles/acceptance-criteria-for-agents) and review the result. It feels strange at first — like you're not "really" coding. You're doing something higher-leverage: directing. Pair programming keeps you typing — agentic coding moves you into the pilot's seat. Start here: see [what agentic coding is](/articles/what-is-agentic-coding), [the Pilot model](/articles/the-pilot-model-directing-ai-agents), or [read the method](/c2/method). --- # AI agent teams, explained: lead, bench, specialist ## When one agent isn't enough you reach for a team — but more agents on one problem makes things worse. The roles that work. - URL: https://stuartleo.com/articles/ai-agent-teams-explained - Published: 2026-06-08 - Reading time: 5 min read - Method: C² Method When one agent isn't enough you reach for a team — but more agents on one problem makes things worse, not better. The roles that actually work, and why. The moment a project gets big, the instinct kicks in: if one AI agent is good, five must be five times better. Spin up a swarm, point them at the codebase, and watch it fly. It doesn't fly. It collides. More agents on one problem is one of the most reliable ways to make agentic development *worse*. But agent teams are real and useful — when you get the roles and the rhythm right. Here's the shape that works. ## Why people reach for more agents The appeal is obvious. A single agent is a bottleneck — it does one thing at a time. Throw more agents at the work and surely it parallelises, the way adding people to a team adds throughput. The analogy breaks because agents don't coordinate like people. They don't have a quiet word at the coffee machine. Point several at the same files and they overwrite each other, contradict each other, and leave you a tangle nobody can reconstruct. The instinct is right that one agent is limited. The fix isn't a swarm. ## The multi-agent anti-pattern Here's the trap, stated plainly: **running multiple agents simultaneously on the same surface burns cost, produces contradictory output, and makes session briefs impossible to write.** It's one of the clearest anti-patterns in agentic development, and the research on what makes [multi-agent coding actually work](https://addyosmani.com/blog/code-agent-orchestra/) keeps landing on the same point — coordination, not raw parallelism, is the hard part. **Five agents on one problem isn't five times the output. It's five times the conflict, and no clean way to record what happened.** ## Lead, bench, specialist A team that works has clear, distinct roles: - **The Lead Agent — one agent, one surface.** It reads the contextbase, writes the code, manages git, extracts knowledge, and writes the session brief. One lead per codebase surface. This is the agent doing the building. - **Bench Agents — independent review on high-stakes calls.** They review, they never execute. Invoked for a PRD, a security question, an architecture decision — and budget-capped. Their entire value is *independence*: a fresh perspective the lead doesn't have. - **Specialist Agents — scoped subagents for repeatable tasks.** A tightly defined role with specific tools and a documented protocol: QA review, release-note authoring, code review against a standard. Each role is a different job, not a clone of the same job. That's why it works where a swarm doesn't. ## Sequential where there's an edge The insight people miss isn't *never run agents at once*. It's that agents sequence when something connects them. The rhythm *lead executes → bench reviews → lead acts on the review* runs in order because there's an **edge** — the bench reads what the lead produced. You can't review an artefact that doesn't exist yet. Where there's no edge and no shared surface, agents can run at the same time. A **surface** is everything an agent mutates or contends for — files, data, a rate-limited API, a deploy target. Two agents on one surface is the anti-pattern, however urgent the session feels. Twelve agents on twelve disjoint surfaces, each with a brief that clears the quality gate, is the method working. The test is the surface, not the headcount. The failure I've watched catch people is *false independence* — two agents whose briefs never mention each other, quietly colliding over one shared database. Anything shared is a hidden edge, and hidden edges bite hardest because nothing in the brief says they exist. Running wide buys breadth, though. It doesn't buy judgment. If I can't find two briefs with no edge between them, there's no team to spread the work across — it's one job, and one agent doing it in sequence is the right tool most days. When the work genuinely is independent, each agent gets its own isolated [git worktree](/articles/parallel-agents-with-git-worktrees). That's the thing a crowd on one problem never was. Those two questions — is there an edge, is there a shared surface — are the whole decision procedure, and they're worth having in front of you before you spin anything up. [The full version is here](/articles/when-can-agents-run-in-parallel). ## The shared contextbase that holds it together What coordinates an agent team isn't agents talking to each other. It's a shared [contextbase](/articles/what-is-a-contextbase) — the version-controlled briefs, decisions and gotchas every agent reads before acting. The lead writes to it. The bench reviews against it. The specialists read it for their scoped job. One source of truth, on disk, that every agent and every human shares. That's the difference between a team and a mob: a team reads from the same page. Agents sequence when an edge connects them and run at once when nothing is shared — the test is the surface, not the headcount. Start here: see [when agents can run in parallel](/articles/when-can-agents-run-in-parallel), [parallel agents with git worktrees](/articles/parallel-agents-with-git-worktrees), or [read the method](/c2/method). --- # Set up AI code review with a bench agent ## An independent agent reviewing the work — not the one that wrote it — catches what the author misses. - URL: https://stuartleo.com/articles/ai-code-review-with-a-bench-agent - Published: 2026-06-08 - Reading time: 4 min read - Method: C² Method An independent agent reviewing the work — not the one that wrote it — catches what the author misses. How to run a bench-agent review that adds signal. The single cheapest upgrade to agentic code quality is a second agent — but only if you set it up right. Ask the agent that wrote the code to review the code, and you mostly get a confident thumbs-up, because the blind spot that created the issue is the same blind spot now grading it. The fix is independence: a separate agent, with its own fresh context, whose only job is to review. In C² that's a **bench agent**. Here's how to run one so it adds real signal instead of noise. ## Why the author shouldn't review itself Self-review is weak for the same reason it's weak in humans, only more so. The agent that built the feature carries the assumptions it built it on. Asked to check its own work, it tends to re-confirm those assumptions rather than question them. It already "knows" the code is right — that's why it wrote it that way. A reviewer that didn't write the code has none of that baggage. It reads the work cold, against the requirements, and notices the thing the author took for granted. That fresh-eyes effect is the entire point, and it's why review is one of the [highest-value jobs](https://www.agensi.io/learn/best-code-review-skills-ai-agents) you can give a coding agent. ## The bench agent: independent, review-only A bench agent has a deliberately narrow brief: **review, never execute.** It reads the diff and the [contextbase](/articles/what-is-a-contextbase), checks the work against a standard, and reports findings. It does not edit the code. That separation is what protects its independence — a reviewer that also fixes things starts owning the work, and you're back to self-review. Reserve it for where independence pays: a security-sensitive change, an architecture decision, a risky refactor, a PRD before it goes active. And budget-cap it — an independent review is worth real tokens, but it's a check, not a second build. **The value of a review agent is independence — it reviews, it never executes. The moment it starts fixing, it stops being a reviewer.** ## What a good review checks Point the bench agent at the things that matter, in order: - **Correctness against the acceptance criteria.** Does it actually do what the brief said, including the cases the author might have skipped? - **Security.** The vulnerabilities the author didn't think to look for — injection, exposed secrets, unsafe input. - **Severity-ranked findings.** Not a flat list — what's a blocker versus a nitpick, so you act on the right things first. - **Convention adherence.** Does it follow the project's own patterns from the contextbase, not generic best-practice the agent invented? A review that produces "looks good" is worthless. A review that produces three ranked, specific, actionable findings is worth its tokens many times over. ## Close the loop with an actions table Here's the discipline that makes bench review trustworthy over time: every review ends with a **close-the-loop table** — each finding, and what was actually done about it (fixed, deferred with a reason, or rejected with a reason). Saved to the contextbase, committed with the work. Without it, reviews become theatre — findings raised and quietly ignored. With it, you have a record that the review *mattered*, and the next reviewer can see what was decided and why. The loop is closed, not just opened. ## Keeping it anchored to the contextbase A bench agent is only as good as what it reviews against. Give it the same contextbase the lead agent used — the decisions, the gotchas, the conventions — so it checks the work against *your* standard, not a generic one. A reviewer that doesn't know your project's decisions will flag things that are deliberate and miss things that violate a rule it never saw. This is the bench role inside a wider [agent team](/articles/ai-agent-teams-explained): lead executes, bench reviews, lead acts on the findings. Sequential, recordable, independent. The value of a review agent is independence — it reviews, it never executes. Start here: see [how agent teams work](/articles/ai-agent-teams-explained), [acceptance criteria the agent can check](/articles/acceptance-criteria-for-agents), or [read the method](/c2/method). --- # Bolt Killed HR. Was That an EX Move? ## A ninety-seven percent collapse, a returning founder, and the distinction that separates a genuine people reset from an expensive subtraction. - URL: https://stuartleo.com/articles/bolt-killed-hr - Published: 2026-06-08 - Reading time: 8 min read - Method: Essay Bolt's CEO fired his entire HR department and announced the problems disappeared. This piece isn't about whether he was right — it's about the distinction between subtraction and design, and what every operator should ask after reading that headline. Ryan Breslow is the founder and CEO of [Bolt](https://fortune.com/2026/05/19/bolt-ceo-ryan-breslow-cut-hr-department-causing-problems-fintech-startup-turn-around/) — a San Francisco fintech building a payments and crypto super-app. This week he fired his entire HR department and made a public statement about it. **"We had an HR team, and that HR team was creating problems that didn't exist. Those problems disappeared when I let them go."** The internet split immediately. Half the room cheered. The other half recoiled. Both responses, I think, missed the real question. This piece is not about whether Breslow was right. It is about the distinction that separates a genuine people reset from an expensive subtraction — and the one diagnostic every operator should run after reading that headline. ## The collapse and the comeback At its peak in 2022, Bolt was valued at $11 billion. By 2024 that number had fallen to roughly $300 million — a ninety-seven percent collapse in two years. Breslow founded the company, stepped down as CEO in 2022, and came back in 2025 to turn it around. He now has a hundred employees and a thesis. The sequence of moves since he returned: **Move one.** A culture reset. He inherited a leadership structure built without him, gave the existing team sixty days to adapt to a leaner, startup-style culture, and found — by his own account — that ninety-nine percent of them couldn't make the shift. He replaced nearly all of them. **Move two.** A thirty-percent workforce reduction in April 2026. **Move three.** This week: the entire HR team eliminated, replaced by a smaller People Ops function focused on training. Three moves. One logic: remove what is generating drag, build lean, move fast. I am not arguing with the logic. A company that collapses ninety-seven percent in two years does not need a slow rebuild. But the quote is interesting. "Those problems disappeared when I let them go" describes a result. It also describes a theory — that the HR team was the source of the problems, not the symptom of them. That theory has enormous implications for what Breslow builds next. ## HR is not EX Before the framework, a distinction that most operators conflate — and the conflation is the episode. **HR manages people to policies.** Someone needs sign-off. A leave form has a missing field. A clause in the handbook got breached. HR is the compliance machinery — it keeps the organisation legal, the paperwork straight, the liability contained. Necessary. And not designed to make anyone better at their job. **Employee Experience — EX — asks a completely different question.** Not *"are they following the rules?"* but *"are they equipped to win?"* It is the onboarding that gives a new hire genuine clarity before their first meeting — not a stack of forms, but a real answer to what good looks like in this role. The manager who has a career conversation at ninety days, not a performance review. The role definition clear enough that someone knows, without asking permission, whether a decision is theirs to make. The values articulated not as a poster in the kitchen but as a set of behaviours you would hire for, promote for, and if necessary, let someone go for. **HR manages people to a standard. EX equips people to achieve an outcome.** One constrains. The other designs. The chasm between them — in the culture they produce, the talent they attract, the results they generate — is enormous. Most businesses do not have an EX function. They have HR, and they assume that is the same thing. That gap is the episode. ## The framework lens [Leadership Question 6 in Resolute](/articles/the-twelve-questions) opens with the distinction directly: *HR counts heads. EX designs journeys.* The question I would put to Breslow — not as a criticism but as the most useful diagnostic available to him — is this: did he delete the administration, or did he delete the design too? Deleting an HR team that was generating bureaucratic friction while keeping an intentional, designed employee experience in place is a clean, defensible call. Deleting the administration because it was a source of friction, without replacing the design function underneath it, produces a lighter org chart and a thinner culture. You do not discover the difference until the next hiring round, when you find out what you are actually offering a talented person. Bolt has a hundred employees. What does a talented engineer joining that team in August experience? Is there a designed onboarding? A culture signal in week one? A career growth conversation at ninety days? Or is there a fast, lean operator who expects people to figure it out? Neither is wrong — but one is a choice and one is a gap. The second connection goes deeper. [Chapter 7 of Resolute](/articles/the-resolute-leadership-curve-a-primer) holds the principle I come back to constantly: **values reveal character. Character scales culture.** Breslow's recent sequence — the sixty-day ultimatum, the near-total leadership replacement, the HR elimination, the public statement — are all data points. They reveal a values set: speed, directness, intolerance of friction, a conviction that simplicity is the correct answer to complexity. Not inherently wrong values. Some of the best operators I know hold them. The question the framework asks is not whether those values are right. It is what happens when they scale. Bolt has a hundred people. Whatever Breslow's character is right now, it is running through all of them — in how decisions get made, what gets celebrated, what gets corrected, what a new hire learns in their first thirty days about how things actually work here regardless of what the People Ops deck says. That is what character scaling culture means. Not aspiration. Physics. One more line from the book that lands hard in this context: *values lived, hired-for, fired-for, promoted-for — those are EX. The experience always wins.* Breslow is firing-for and hiring-for right now. The brief question is whether those values, translated through a hundred people, produce an experience worth having — for the next talented person who joins, and for the customer that person is supposed to serve. ## Three questions for your own business Here is how I would sit with this if I were Breslow — and how I would sit with it at any scale. **01 — Administration or design?** In your organisation, what is the ratio between administration and design in how you manage your people? How much of what your HR or People function does is tracking compliance, managing leave, counting heads — and how much is actually designing the experience a talented person has from day one to year three? If you deleted the function tomorrow and the only thing that disappeared was the compliance work, you did not have a people design function. You had a payroll team with a better job title. **02 — What do your decisions reveal?** Map your last three personnel decisions against your actual values. Not the poster values — the ones that show up in the decisions. Breslow firing the HR team is a values declaration. The question is whether those values, as declarations, are the ones you would be proud to scale to a thousand people. Most leaders I work with have never done this mapping. Most of them are surprised by what they find. **03 — Where is the culture design actually being done?** If the HR function in your business disappeared overnight and the problems disappeared with it — what does that tell you about where the culture design work is being done? If the answer is nowhere, that is the real problem. Not the HR team. ## The takeaway Subtraction is not design. They look identical at the announcement. They diverge completely in the execution. Bolt's move might be exactly right. A company that had collapsed ninety-seven percent needed a radically different logic, and it is entirely possible that the inherited HR function was generating institutional drag without generating institutional design. Breslow might have made the right call, for the right reason, at the right moment. But the test of that is not whether the problems disappeared when he let them go. The test is whether the experience of being a talented person at Bolt — eighteen months from now, when the lean org is running at speed — is one worth having. Whether the values he is scaling produce a culture that can build the product, serve the customer, and attract the next hire without burning through the hundred people who stayed. HR is administration. EX is design. You can delete one without the other. Whether Breslow did — that is what the next twelve months will answer. --- *This is Episode 5 of Commander in Brief. Earlier episodes: [Nike Forgot What It Was Selling](/articles/nike-forgot-what-it-was-selling), [Why Toyota's Slowness Is Every Mature Business's Trap](/articles/the-mature-business-trap), [Values as the Commons](/articles/values-as-the-commons), and [AI Business Engineering — A Working Definition](/articles/ai-business-engineering-a-working-definition). The framework lives in the book — [Resolute](https://www.amazon.com.au/Resolute-navigate-disruption-indestructible-organizations/dp/0645825425), in print since December 2024.* --- # C² vs AWS AI-DLC: pilot versus approver at the gate ## Both are AI-native methods. One casts you as an approver at phase gates — the other as a pilot directing throughout. - URL: https://stuartleo.com/articles/c2-vs-ai-dlc - Published: 2026-06-08 - Reading time: 4 min read - Method: C² Method AWS AI-DLC and C² are the closest AI-native peers. The two telling differences: human as approver-at-gates vs pilot, and context as delivery vs investment. Of all the methods for building with AI agents, AWS AI-DLC is the closest structural peer to C² — and the sharpest contrast. Both are genuinely AI-native. Both are serious about structure. They diverge on two things that turn out to matter a lot: who's in the seat, and what happens to context. Here's the honest head-to-head. ## Two AI-native methods, side by side **AI-DLC** (AI-Driven Development Lifecycle) is AWS's methodology for building with agents. It runs work through a hierarchical, agent-agnostic pipeline with human approval at phase gates, replaces the two-week sprint with shorter, intense cycles it calls "bolts", and centres on AI-powered execution under human oversight. It's structured, enterprise-credible, and genuinely built for the agent era — you can read the [AWS framing](https://aws.amazon.com/blogs/devops/ai-driven-development-life-cycle/) directly. **C²** is a lighter, agent-agnostic method built on one idea: every project runs two systems — a codebase and a contextbase — and the contextbase is version-controlled context the agent reads before it acts and that compounds across sessions. They agree on a surprising amount: AI does the execution, humans stay essential, context is structured rather than ad hoc, and the method shouldn't be locked to one vendor's model. The differences are in the two choices below — and they're telling. ## Approver at gates vs pilot throughout The first divergence is the human's role. AI-DLC casts the human as an **approver at phase gates**. The pipeline runs a phase, you review and sign off, the pipeline proceeds. Your control is exercised at the boundaries — the gates between phases. C² casts the human as a **pilot directing throughout**. Not signing off at checkpoints, but steering continuously — scoping the brief, making the architectural calls, owning the quality bar at every step, not just at gates. **AI-DLC asks you to approve the pipeline's output at the gate. C² asks you to fly the thing the whole way.** Neither is wrong, but they produce different experiences. Gate approval scales oversight across a big org with formal checkpoints. Piloting keeps a builder in the loop continuously, which fits a founder or a small team who want their hands on the controls. ## Context as delivery vs context as investment The second divergence is the one that compounds — literally. AI-DLC treats context as **delivery**. Load the right rules and information, run the phase, move on. The context is consumed in service of the phase. It does its job and the pipeline advances. C² treats context as **investment**. Every session writes down what was learned — decisions, gotchas, briefs — and commits it, so the next session starts from everything figured out so far. The context isn't consumed running a phase. It accrues. After fifty sessions, the contextbase is denser in real decisions than the code itself. This is the deepest difference between the two. One uses context to run the pipeline. The other builds context *as* the durable asset, and the pipeline is how it gets built. If you believe the accumulated knowledge of a project is its real value, that's the C² bet. ## Bolts vs the brief cascade A smaller, practical contrast. AI-DLC reframes the sprint as the "bolt" — a short, intense cycle measured in hours or days. C² doesn't batch into cycles at all. Work flows through a cascade of briefs, session by session, continuously — the unit is the brief and the session, not a timeboxed bolt. Both reject the two-week sprint. They replace it with different shapes: AI-DLC with a faster cycle, C² with continuous flow. ## Side by side | | AWS AI-DLC | C² | |---|---|---| | Human role | Approver at phase gates | Pilot directing throughout | | Context model | Delivery — consumed per phase | Investment — compounds across sessions | | Work unit | The "bolt" (short cycle) | The brief + the session (continuous) | | Weight | Heavier, pipeline + gates | Light, markdown in git | | Tooling | AWS-oriented | Agent-agnostic, any model | | Best for | Enterprises wanting formal gates | Builders wanting to stay in the seat, context they own | ## How to choose - **Choose AI-DLC** if you want a structured pipeline with formal phase gates, enterprise governance, and you're working in the AWS tooling world. - **Choose C²** if you want to stay in the driver's seat throughout, keep things light and agent-agnostic, and have your context compound into an asset you own — not consumed running a pipeline. AI-DLC runs the pipeline and asks you to sign off. C² puts you in the seat and makes the context yours. Start here: see [how all the methodologies compare](/articles/ai-development-methodologies-compared), the [head-to-head with BMAD](/articles/c2-vs-bmad), or [read the method](/c2/method). --- # C² vs GUARDRAILS.md: safety that compounds ## GUARDRAILS.md captures safety lessons so an autonomous agent stops repeating failures. How it relates to a full contextbase. - URL: https://stuartleo.com/articles/c2-vs-guardrails-md - Published: 2026-06-08 - Reading time: 4 min read - Method: C² Method GUARDRAILS.md captures safety lessons so an autonomous agent stops repeating failures. A useful file — and how it relates to a contextbase that compounds. There's a small, smart idea spreading through the autonomous-agent world: **GUARDRAILS.md** — a file where you write down safety lessons so the agent stops repeating its failures. If you've read anything here about gotchas and the contextbase, it'll sound familiar, because it's the same instinct applied to one domain. That makes it a useful lens for understanding what C² is doing more broadly. Here's an honest comparison: what GUARDRAILS.md gets right, where a single safety file stops, and how the two fit together. ## What GUARDRAILS.md is for [GUARDRAILS.md](https://guardrails.md/) is a file-based safety protocol for autonomous coding agents. The idea: when an agent does something dangerous or wrong, you capture the lesson in a file — and because the agent reads that file, it doesn't make the same mistake again. It acts as the agent's safety memory across context resets, which an agent otherwise lacks. It exists because of a brutal fact about autonomous agents: the same prompt can succeed nine times and fail catastrophically on the tenth. A written record of past failures is how you stop the tenth from being the first time, every time. ## Safety as captured lessons The mechanism is exactly right, and it's worth naming because it's the same one that makes C² work: **an agent has no memory, so you give it one by writing things down where it reads them.** GUARDRAILS.md applies that to safety — captured failures, read before acting, so they don't recur. This is the gotcha pattern, scoped to safety. When [an agent keeps relearning](/articles/how-to-stop-your-agent-forgetting) the same lesson, the fix isn't a better prompt — it's a written record. GUARDRAILS.md is that record for the specific, high-stakes case of safety. **An agent forgets its mistakes the moment the session ends. GUARDRAILS.md remembers them for it — that's the whole, correct idea.** ## Where a single safety file stops So what's the limit? It's scope. GUARDRAILS.md is one file about one thing: safety. But an agent needs written, read-before-acting memory about far more than safety — the architecture decisions, the conventions, the briefs, the gotchas that aren't dangerous but are merely expensive to rediscover. A single safety file solves the safety slice and leaves the rest in your head, in chat, evaporating. You end up with a guardrails file *and* the same forgetting problem everywhere else. The instinct is right — the coverage is partial. ## How C² folds safety into a compounding contextbase C² takes the same instinct — write it down, read it first — and applies it to the whole project. The [contextbase](/articles/what-is-a-contextbase) is version-controlled knowledge the agent reads before acting, covering everything: | | GUARDRAILS.md | C² contextbase | |---|---|---| | Mechanism | Write it down, read before acting | **Same** | | Scope | Safety lessons | Decisions, patterns, gotchas, briefs, safety | | Memory across resets | Yes, for safety | Yes, for the whole project | | Compounds | Within safety | Across everything the project learns | Safety, in C², isn't a separate file fighting the same battle alone. It's one kind of knowledge in a contextbase where decisions, patterns, and gotchas all compound together — and where the [overnight-run guardrails](/articles/run-agents-overnight-safely) live alongside the rest of what the project knows. ## Use both This isn't really a rivalry — it's a part and a whole. A GUARDRAILS.md is a safety-focused slice of a contextbase, and a perfectly good one. Keep it as a clear home for safety rules if you like, have your [Router](/articles/c2-vs-native-rule-files) point at it, and let the rest of your project's knowledge live in the same contextbase beside it. The principle is identical at every scale: write it down, read it first. A safety file is a great start — the contextbase is where safety, decisions and knowledge compound together. Start here: see [how to run agents overnight safely](/articles/run-agents-overnight-safely), [C² vs native rule files](/articles/c2-vs-native-rule-files), or [read the method](/c2/method). --- # C² vs native rule files: when one CLAUDE.md isn't enough ## Every agentic build starts with a single rules file. The moment it stops scaling — and what to do then. - URL: https://stuartleo.com/articles/c2-vs-native-rule-files - Published: 2026-06-08 - Reading time: 4 min read - Method: C² Method CLAUDE.md, AGENTS.md and cursorrules are where everyone starts. An honest look at what a single rules file does well, where it breaks, and how C² extends it. Everyone building with AI agents starts the same way: a single rules file. `CLAUDE.md`, `AGENTS.md`, `.cursorrules` — one markdown file the agent reads first. It's the right place to start. It's also where most people stall, because a single file quietly stops scaling and it's not obvious why. Here's an honest look at what a native rule file does well, the exact walls you hit, and how C² extends it rather than replacing it. ## Where everyone starts (and why it's right to) A native rule file is the agent's first context: a bit about the project, a few rules, maybe where things live. Zero setup, universal, agent-native. You make the file, the agent reads it, you're building. This is genuinely the correct starting point. You shouldn't reach for a methodology on day one of a weekend project. A single rule file is the right tool for a small, solo, short-lived build — and for that, it's enough. ## What one file does well Give it its due: - **Instant.** No structure to learn, no scaffold to set up. - **Universal.** Every agent reads some version of it. - **Right there.** It's the file the agent definitely loads, so anything in it lands. For orienting an agent to a small codebase, a rule file is hard to beat. The problem isn't that it's bad. The problem is that it's the *only* structure, and one file can't be everything. ## The three walls you hit As the project grows, a single file runs into three walls — fast. 1. **The bloat wall.** You keep adding rules until the file is hundreds of lines. Then the agent skims it and starts missing things that are right there in the text. One file has no way to separate "read this every time" from "read this only when relevant." (This one's common enough to have its own [field note](/articles/the-claude-md-that-got-too-big).) 2. **The memory wall.** A rule file holds *rules*, not *history*. It has no place for what happened last session, what was decided and why, or the gotcha you hit yesterday. So the agent keeps relearning, and the knowledge evaporates. 3. **The second-person wall.** A rule file is a solo artifact. The moment a collaborator (or a second agent) joins, there's no shared structure for hand-off, no briefs, no async memory — just one file that was really only ever yours. **A single rules file isn't wrong. It's the seed. The trouble starts when you ask the seed to be the whole tree.** The empirical work on [context files for agentic coding](https://www.augmentcode.com/guides/how-to-build-agents-md) lands in the same place: focused files that point outward beat one exhaustive file, because the exhaustive file stops being read. ## How C² is the structure that file is missing C² doesn't throw your rule file away. It promotes it. Your `CLAUDE.md` becomes the **Router** — the entry point that indexes everything else — and around it C² adds the structure a single file can't hold: - **A contextbase.** A `docs/` folder where briefs, decisions and gotchas live, so knowledge accumulates instead of bloating one file. - **Session briefs.** Written memory across sessions, so the agent and your collaborators start from what was learned. - **A knowledge layer.** Gotchas captured once, read before the relevant code, never re-discovered cold. The rule file was the seed. C² is the system it grows into — and crucially, it's the same plain markdown in git, so adopting it is extending what you have, not migrating off it. ## Side by side | | Native rule file | C² | |---|---|---| | Setup | None | Point your agent at the kit, minutes | | Holds | A few rules | Rules + briefs + memory + knowledge | | Memory across sessions | None | Session briefs, committed | | Knowledge that compounds | No | The knowledge layer is the point | | Second person / second agent | No structure | Shared briefs and memory | | Best for | Small, solo, short-lived | Anything that grows or lasts | ## How to choose - **Stay on a single rule file** if the project is small, solo, and short — don't over-engineer a weekend build. - **Move to C²** the moment you hit a wall: the file's bloating, the agent's relearning, or someone else joins. That's the signal the seed has outgrown its pot. A single rules file isn't wrong — it's the seed. C² is what it grows into. Start here: [how to write an AGENTS.md that agents follow](/articles/how-to-write-agents-md), [how the methodologies compare](/articles/ai-development-methodologies-compared), or [read the method](/c2/method). --- # C² vs spec-driven development: specs that persist ## SDD makes an executable spec the source of truth. C² agrees — and adds the part SDD leaves out. - URL: https://stuartleo.com/articles/c2-vs-spec-driven-development - Published: 2026-06-08 - Reading time: 4 min read - Method: C² Method Spec-driven development makes an executable spec the source of truth. C² agrees — and adds the part SDD leaves out: a contextbase that compounds across every spec. Spec-driven development is one of the best ideas to come out of the agentic-coding wave. It says: stop prompting code into existence and start from a spec — a detailed, version-controlled description of what the system should do, with acceptance criteria you can run. It's a direct, correct answer to vibe coding. C² agrees with almost all of it. The interesting question isn't C² *versus* spec-driven development — it's what SDD gets right, where it stops, and how C² extends it. Here's the honest map. ## What spec-driven development gets right SDD's core moves are sound, and C² shares them: - **Spec before code.** Write down what to build, in detail, before generating anything. A clear target beats a vague prompt. - **The spec is the source of truth.** It's version-controlled and authoritative — code derives from it, not the other way round. - **Runnable acceptance criteria.** The strongest specs define done as something you can check. As the SDD guides put it, [a criterion you can't run is an opinion, not a criterion](https://thebcms.com/blog/spec-driven-development). This is genuinely good practice. If you take nothing else from SDD, take "write a checkable spec first." It's the cure for the agent that drifts into plausible nonsense. ## Spec as source of truth, criteria you can run The heart of SDD is making intent *explicit and checkable*. An executable spec, broken into atomic tasks, each with acceptance criteria the agent can verify. That's what lets agents work autonomously without drifting — they have a target they can test against, not a feeling to interpret. C² runs on the same instinct. Its [Prompt Brief](/articles/acceptance-criteria-for-agents) is, in effect, a spec for a unit of work: what to build, what not to build, what to read first, and how you'll know it worked. The agreement here is near-total. ## Where SDD stops Here's the gap. Spec-driven development is centred on *the spec* — one unit of work at a time. Write the spec, build it, verify it, done. It's excellent at that. But it has little to say about what carries *between* specs. The decision you made building feature one — does feature two's spec start knowing it? The gotcha you hit last week — does this week's spec author (you or the agent) start aware of it? In pure SDD, each spec tends to start fresh. The spec is the source of truth for *this* feature, but the project's accumulated knowledge isn't a first-class artifact the way the spec is. **A great spec builds one feature right. It doesn't, on its own, make the next feature start any smarter.** That's not a flaw — it's a scope choice. SDD nails the unit of work. It just stops at the edge of it. ## C²: specs plus a compounding contextbase C² keeps the spec discipline and adds the layer SDD leaves out: a [contextbase](/articles/what-is-a-contextbase) that compounds across every spec. - The **brief** carries the spec discipline — checkable criteria, build-this-not-that — for each unit of work. - The **contextbase** carries everything that should persist *between* briefs: decisions, patterns, gotchas, session memory — committed to git, read before each new brief is written. So in C², a new spec doesn't start from zero. It starts from everything the project has learned. The spec is sharp *and* the project is smart, and both get better the longer you run. SDD makes each feature right. C² makes each feature start ahead. ## Side by side | | Spec-driven development | C² | |---|---|---| | Core unit | The executable spec | The Prompt Brief (a spec) + the contextbase | | Source of truth | The spec for a unit of work | The spec, plus a compounding contextbase | | Acceptance criteria | Central, runnable | Central, runnable | | Knowledge between specs | Not its focus | The point — it compounds | | Session memory | Not its focus | Session briefs, committed | | Best for | Getting one unit of work right | Getting each unit right and smarter than the last | ## How to choose or combine - **Reach for SDD's discipline** whenever you build a real feature — write the checkable spec first, every time. It's the right habit. - **Reach for C²** when you want that discipline *and* a project that gets sharper across features — when the knowledge between specs is worth keeping. - **Best of all, combine them.** Run SDD-style specs as your C² briefs, with the contextbase compounding underneath. The specs stay rigorous — the project stops starting cold. A great spec builds one feature right — a contextbase makes every next spec start ahead. Start here: [write acceptance criteria your agent can check](/articles/acceptance-criteria-for-agents), see [how the methodologies compare](/articles/ai-development-methodologies-compared), or [read the method](/c2/method). --- # Context rot: how compaction keeps your agent sharp ## Every model degrades as its window fills. What context rot looks like from the inside, and how compaction keeps the working set lean without losing what matters. - URL: https://stuartleo.com/articles/compaction-keep-the-context-window-lean - Published: 2026-06-08 - Reading time: 6 min read - Method: C² Method Context rot: every model degrades as its window fills. What it looks like, how I diagnosed it, and the compaction habits that keep the context lean. Here's a failure that catches everyone eventually: a session that started sharp slowly goes wrong. The agent gets vaguer, forgets a constraint you set earlier, contradicts itself, and it's more confident than ever. You blame the model. The model is fine. The window is full. That is **context rot**, and every model has it. Keeping the window from filling is a skill, and it's called **compaction**. Here's what rot is, what it looked like the day it cost me an afternoon, and the habits that keep me ahead of it now. ## What context rot is The **context window** is the finite amount a model can hold at once. It's tempting to treat it like a backpack and keep stuffing things in until it's full. But it doesn't work like storage. As the window fills, the model gets *worse* at using what's in it. Details slip. Earlier instructions fade. Output drifts confidently off-target. Context rot is a property of every frontier model, not a bug in any one of them. The practical consequence is counterintuitive: past a point, *more* context produces *worse* results. Teams running serious agent workloads treat managing this as core work. Arize's writeup on [context management in agent harnesses](https://arize.com/blog/context-management-in-agent-harnesses/) frames it as a first-class engineering concern, not housekeeping. ## The day context rot bit me at 80% full I lost an afternoon to context rot before I knew the term for it. It was a long session, a meaty refactor with lots of back and forth, the kind where you're deep in it and don't want to stop. For the first hour the agent was excellent. Sharp, precise, getting it right. Somewhere in the second hour it started to slip. It reintroduced a pattern I'd explicitly told it to drop early on. It contradicted a decision I'd made forty minutes earlier. Small things, then less small. And it stated all of it with total confidence. That's what threw me. I kept assuming a confident agent was a correct one, so I went looking for the bug in the *code*. There wasn't one. The agent was producing wrong work and presenting it exactly like the right work it had produced an hour before. I burned a good while chasing the wrong cause, because the failure had no error message. It just got quietly, confidently worse. The penny dropped when I noticed *when* it started: not at any particular task, but at a particular depth. The window had filled to around 80%. As it filled, the model started dropping the earlier instructions and decisions to make room. The agent hadn't got dumber. Its working memory had filled past the point where it could hold everything, so the early context, the very decisions it was now violating, had rotted out. The fix in the moment was simple once I understood it. I had the agent write a short note of where the refactor was up to and what was decided, then I started a fresh session from that note. Clean window, all the decisions restated concisely, back to sharp immediately. **When an agent gets confidently worse deep into a session, suspect the context window before the model.** ## Budget by fill percentage, not token count The mental shift that fixes most of this: stop counting tokens, start watching the *fill level*. Token counts are abstract and easy to ignore until you're over. Fill percentage is a dial you can act on. The working rule: compact *well before* full. Many practitioners move once the window is past roughly half to sixty percent, because that's where rot starts to bite. That's my threshold now too. You're not trying to use every last token. You're trying to keep the window in the range where the model is sharp. **Don't manage tokens. Manage the fill percentage, and compact before the agent starts guessing.** ## The three compaction moves Compaction isn't one action. C² keeps context lean with three mechanisms working at different timescales: 1. **The session brief: point-in-time compaction.** At every context break, digest the session down to "what the next agent needs cold" and drop the raw transcript. Triggered by the break, not by the window filling. 2. **The Router: continuous compaction.** The Router links rather than embeds, so each session loads a lean, curated slice of the contextbase, not the whole thing. Lazy-loading *is* compression: read the index, not every file. 3. **The Learn loop: capture then consolidate.** Capture discoveries fast during a session, then periodically merge duplicates into canonical docs and prune the stale. The contextbase stays dense in signal, not bloated. Together these handle the durable, cross-session half of the problem: the context that should persist, kept lean. ## What to keep, summarise, and drop For the within-session half, a single task that's overflowing, the moves are simpler: - **Keep** the original intent and the last couple of steps. The agent always needs to know what it's doing and where it just was. - **Summarise** what's gone stale. Twenty steps of exploration compress to "here's what I found." The conclusions matter. The transcript doesn't. - **Drop** what's irrelevant to what's left. A tool output you've already acted on is dead weight in the window. When a single task still overflows after this, the cleanest move is the one that rescued my refactor: have the agent write down where it's up to, then start a fresh session from that note. You've traded a bloated, rotting window for a short, sharp one. ## Compaction as a habit The mistake is treating compaction as something you do in a panic when things go sideways. By then the rot has already cost you, as it cost me that afternoon. Now I don't wait for the slip: - **Watch the fill level, not the clock.** When a session's window gets past half to sixty percent, I compact (summarise and move on) rather than pushing to full. - **Long task, fresh start.** When something runs long, I have the agent write where it's up to and I start clean from that. - **Suspect the window first.** When output degrades with no error, my first question now is "how full is the context?", not "is the model having a bad day?" - **Brief every break.** A session brief at every break and a Router that links instead of embeds mean the next session starts lean. Done as habit, you simply never reach the wall. Compaction is a habit, not a rescue. Start here: see [how to stop your agent forgetting](/articles/how-to-stop-your-agent-forgetting), [write your first session brief](/articles/write-your-first-session-brief), or [read the method](/c2/method). --- # Context engineering, explained: the skill that replaced prompting ## Prompt engineering tuned the message. Context engineering curates what the agent knows — and it's where the leverage moved. - URL: https://stuartleo.com/articles/context-engineering-explained - Published: 2026-06-08 - Reading time: 5 min read - Method: C² Method Context engineering is the discipline that overtook prompt engineering: curating what your AI agent knows before it acts. What it is, why it matters, and how to start. A year ago the advice was: get better at prompting. Learn the magic phrasing, the role-play opener, the chain-of-thought trick. It worked, for a while. Then the models got good enough that the phrasing stopped being the problem — and a different skill started separating the people who ship from the people who fight their agent all day. That skill is **context engineering**. It's the discipline of curating what your AI agent *knows* before it acts, rather than fussing over how you ask. And for anyone building software with agents, it's where the leverage moved. ## Why prompting stopped scaling Prompt engineering is the craft of one message — composing a single input that gets a good answer. It's real, and it still matters. But it has a ceiling, and you hit it fast when you're building something bigger than a one-off. Here's the ceiling: a perfect prompt over thin context still guesses. Ask the sharpest possible question about your auth flow, and if the agent doesn't know how your auth actually works, it invents something plausible. Plausible is the trap — it looks right, it compiles, and it's quietly wrong. No amount of prompt polish fixes a knowledge gap. So the question stopped being *how do I phrase this?* and became *what does the agent need to know to get this right?* That second question is context engineering. ## What context engineering actually is Context engineering is curating the information environment the agent reasons over — the relevant code, the decisions already made, the patterns to follow, the history of what's been tried. One useful way to see it is as three nested layers, each containing the last: - **Prompt engineering — the message.** The single composed input. - **Context engineering — the memory.** What a curator keeps or drops in a finite window. - **Harness engineering — the machine.** The gather-act-verify loop the agent runs, retrying on failure. Martin Fowler's team makes the same point from the practitioner's chair: the real work of [harness engineering for coding agents](https://martinfowler.com/articles/harness-engineering.html) is managing what the agent sees, not crafting one clever prompt. Context engineering is the middle layer — and most of the day-to-day skill lives there. **Prompt engineering controls how you ask. Context engineering controls what the agent knows when it answers. As the models got good, the second one started to matter far more than the first.** ## The smallest high-signal set The instinct, when you realise context is the lever, is to give the agent *everything*. Paste the whole codebase. Dump every doc. More context, better answers, surely. It's the opposite. The craft of context engineering is curating the **smallest high-signal set** — the least the agent needs to act well, and no more. A model handed a wall of marginally-relevant material doesn't get smarter. It gets distracted, and it gets expensive. Good context is curated like a good brief: the relevant decisions, the patterns that apply *here*, the one gotcha that bites this exact task. Structure helps the agent navigate — clear headers turn a document into addressable units it can jump around, where the same text as an undifferentiated wall gets skimmed. You're not feeding the agent. You're orienting it. ## Context rot and the finite window There's a hard physical limit underneath all of this: the **context window** — the finite amount a model can hold at once. And every frontier model degrades as that window fills. The phenomenon has a name now: **context rot**. Past a certain fill level, the agent starts dropping details, losing the thread, and producing output that's confident and wrong. This is why "just paste more" backfires twice over — it costs more *and* it rots faster. Context engineering treats the window as a budget. The move that works is to think in fill percentage, not raw token count: keep the original intent and the last couple of steps, summarise what's gone stale, and drop what no longer matters — *before* the agent starts guessing. Keeping the working set lean is half the discipline. ## Where context should live Here's the gap in most context-engineering advice: it treats context as something you assemble fresh each time. Retrieve the right files, build the right window, run the task, move on. The context is *delivery* — loaded to do a job, then gone. That's a missed opportunity, because the most valuable context is the same every session: how this project is built, what's been decided, what traps you've already hit. Re-assembling it each time is the tax all over again. The fix is to make context **durable**. Write the high-signal stuff down once — decisions, patterns, gotchas, a short note at the end of each session — and commit it to git so the agent reads it before it acts. Now context engineering isn't a thing you redo every morning. It's an asset that accrues. That durable, version-controlled form of context engineering is exactly what C² calls a [contextbase](/articles/what-is-a-contextbase): context as an investment that compounds, not delivery you reload. ## Your first move You don't need a framework to start. Notice the three things your agent keeps re-asking for — almost always *how the project is structured*, *what's already been decided*, and *what's already gone wrong*. Write each down in a markdown file. Commit them. Point the agent at them. That's context engineering, made durable. The model is not the bottleneck — the context you give it is, and that's an engineering problem you can own. Go deeper: see [where C² sits across prompt, context and harness engineering](/articles/what-is-an-agent-harness), the [head-to-head on prompt vs context engineering](/articles/prompt-engineering-vs-context-engineering), or [read the method](/c2/method) it's built on. --- # Context engineering for people who aren't engineers yet ## The one skill that turns an AI agent from a clever toy into a genuine build partner — no computer-science degree required. - URL: https://stuartleo.com/articles/context-engineering-for-non-engineers - Published: 2026-06-08 - Reading time: 4 min read - Method: C² Method Context engineering is the skill of writing down what your AI agent needs to know so it acts well. A plain-English guide for builders from business, not CS. If you came to building from business rather than computer science, there's a piece of good news that the jargon hides: the skill that matters most when building with AI agents isn't coding. It's **clarity** — and you already do clarity for a living. That skill has a name in this world: **context engineering**. It sounds technical. It mostly isn't. Let me strip it down to what it actually asks of you. ## What context engineering actually means Context engineering is the practice of writing down what your AI agent needs to know so it acts well — and putting that knowledge where the agent will read it. That's it. Not prompts, not code. Knowledge. The decisions you've made, the way your project is put together, the things you've learned the hard way. An agent that has this acts like a teammate who's been on the project for months. An agent without it acts like a brilliant contractor on their first morning, guessing at everything. The engineering part isn't writing software. It's the discipline of capturing the right knowledge, in the right place, in a form the agent can use. Practitioners now treat this as the core craft of working with coding agents — Martin Fowler's team frames the real work as [managing what the agent sees](https://martinfowler.com/articles/harness-engineering.html), not coaxing it with clever phrasing. ## Why the model isn't the bottleneck — clarity is Here's the thing that trips up newcomers. You assume that when the agent gets something wrong, it's because the AI isn't smart enough. Usually it's the opposite — the AI is plenty smart and you didn't tell it what it needed to know. Ask an agent to "add a discount to checkout" and it will build *a* discount — probably not *your* discount, because it doesn't know your rules. Percentage or fixed amount? Stackable? Who qualifies? You hold all that in your head. The agent holds none of it. So it invents something plausible, and plausible-but-wrong is exactly the failure that costs you a day. **The agent didn't fail because it wasn't clever. It failed because the thing in your head never made it onto the page.** This is good news. "Be clearer about what I want" is a problem you can solve. "Wait for a smarter model" isn't. ## The three things worth writing down You don't need a system. Start with the three kinds of knowledge an agent re-asks for constantly: 1. **How the project is structured.** What it is, what the main pieces are, where things live. The orientation you'd give a new hire on day one. 2. **The decisions you've made, and why.** "Discounts are percentage-only and never stack." "We use this payment provider because of X." The *why* stops the agent quietly undoing your choice later. 3. **The traps you've hit.** The thing that broke, and what fixed it. Write it once so neither you nor the agent rediscovers it cold. Put each in a plain text file in your project. That's context engineering. No code required. ## A worked example from zero Say you're building a simple booking site. Before touching a feature, you write a short file: ``` This is a booking site for a yoga studio. - Classes have a capacity. Never let bookings exceed it. - Cancellations within 12 hours are non-refundable. - Payments go through Stripe. Don't add other providers. - Decision: no user accounts yet — bookings are by email only. ``` Four lines of plain English. Now when you ask the agent to "build the booking form," it already knows the capacity rule, the refund window, the payment choice, and the no-accounts decision. It builds *your* booking form, not a generic one. You didn't write code. You wrote clarity — and the agent did the rest. ## Where to go next The instinct from business is to think you need to learn to code before you can build. You don't need to learn to code. You need to learn to write down what you know so the agent can act on it — and then keep doing it as you go. The bottleneck was never the AI. It was how clearly you told it what you know. Start here: [run your first session](/c2/start), see [how to build with AI agents](/articles/how-to-build-with-ai-agents), or read [context engineering, explained](/articles/context-engineering-explained) for the full picture. --- # Context engineering vs RAG for coding agents ## RAG retrieves context on the fly; context engineering curates and keeps it. Why a contextbase isn't RAG. - URL: https://stuartleo.com/articles/context-engineering-vs-rag - Published: 2026-06-08 - Reading time: 4 min read - Method: C² Method RAG retrieves context on the fly; context engineering curates and keeps it. How they differ for coding agents, where each fits, and why a contextbase isn't RAG. As soon as you start thinking seriously about what an AI agent knows, two terms collide: **RAG** and **context engineering**. People use them almost interchangeably, which causes a lot of confusion — because they're not the same kind of thing at all. One is a technique. The other is the discipline that decides when to use it. Getting the distinction right matters, because it changes how you build an agent's memory. Here's the honest comparison. ## What RAG does (retrieve on demand) RAG — retrieval-augmented generation — is a technique. You keep a store of documents, and when a question comes in, you retrieve the snippets that look relevant and paste them into the prompt before the model answers. The model "reasons over" material it wasn't trained on, fetched fresh for that query. It's genuinely useful, especially for large or fast-changing bodies of material — documentation, a knowledge base, anything too big to hold in the window. The defining trait: retrieval happens *per query*, optimised for the question in front of it, and then it's gone. ## What context engineering does (curate and keep) [Context engineering](/articles/context-engineering-explained) is the wider discipline: deliberately deciding what the model should know and shaping it well. Retrieval is one tool it can use — but so is writing things down, structuring them, pruning them, and committing them. The framing that helps: RAG is a way to *fetch* context — context engineering is the practice of *deciding what context should exist and how it's kept*. As the practitioner guides on [context engineering](https://www.firecrawl.dev/blog/context-engineering) put it, the work is assembling, pruning and ordering everything the model sees — retrieval is part of that, not the whole of it. **RAG answers "what's relevant to this question right now." Context engineering answers "what should this agent always know, and how do I keep it."** ## Where they overlap and differ They overlap in that both put the right information in front of the model. They differ in *durability* and *intent*: | | RAG | Context engineering (contextbase) | |---|---|---| | What it is | A retrieval technique | The discipline of curating what the model knows | | Timing | Per query, on demand | Persistent, read before every task | | Source | A document store, searched | Curated, version-controlled knowledge | | Optimised for | This one question | What the project always needs | | Lifespan | Fetched, used, gone | Accrues and compounds | | Best for | Large or changing material | Durable decisions, patterns, gotchas | ## Why code context wants curation, not just retrieval Here's why this matters for coding agents specifically. The knowledge an agent needs most isn't scattered facts to look up — it's the *durable* stuff: why auth is built this way, the convention the codebase follows, the gotcha that bit you last week. That knowledge is needed on almost every task, it's high-signal, and it doesn't change query to query. Retrieving that fresh every time is the wrong tool. It's like re-deriving your own house rules on every decision. This knowledge should be *curated and kept* — written down once, read every time — not searched for repeatedly. Retrieval shines for the long tail of reference material. It's a poor fit for the core knowledge that's always relevant. ## How a contextbase relates to RAG A [contextbase](/articles/what-is-a-contextbase) is curated, durable context — the opposite end from RAG's fetch-and-forget. But they compose neatly: - The **contextbase** holds the always-needed knowledge the agent reads before every task — decisions, patterns, gotchas, briefs. The compounding memory. - **Retrieval** pulls in the large, fast-changing, or long-tail material on demand — API docs, a big reference corpus, things too bulky to keep loaded. Use the contextbase as the agent's standing memory and retrieval as its lookup. They're layers, not rivals. RAG fetches context for one answer — a contextbase keeps the context that should never have to be re-fetched. Start here: read [context engineering, explained](/articles/context-engineering-explained), [what a contextbase is](/articles/what-is-a-contextbase), or [read the method](/c2/method). --- # Cursor vs Claude Code: why C² works with either ## The tool debate misses the point. An agent-agnostic method lets you pick any of them and switch freely. - URL: https://stuartleo.com/articles/cursor-vs-claude-code-which-fits-c2 - Published: 2026-06-08 - Reading time: 4 min read - Method: C² Method Cursor or Claude Code or Codex — the tool debate misses the point. Why an agent-agnostic method means you can pick any, and switch without losing context. "Cursor or Claude Code?" is one of the most-asked questions in AI development, and one of the least important to get permanently right. Both are excellent. They leapfrog each other on features every few weeks. And whichever you pick, a better one or a new contender (Codex, Gemini CLI, the next thing) will tempt you within months. So the interesting answer isn't which tool wins. It's how to choose without making a bet you'll regret — which comes down to the method underneath, not the tool on top. Here's the case. ## The tool debate (Cursor, Claude Code, Codex, Gemini) The contenders are all strong, and they differ in feel more than in ceiling: - **Cursor** — an AI-native editor, great if you want the agent woven into a familiar IDE. - **Claude Code** — terminal-first, great if you like the agent close to the shell and the filesystem. - **Codex, Gemini CLI, and others** — each with their own strengths, models, and ergonomics. You can compare them feature by feature and price by price — and people do, exhaustively, in [tool cost comparisons](https://devtk.ai/en/blog/ai-coding-agent-cost-comparison-2026/) that are out of date by the next release. The comparison is real, but it's a snapshot of a fast-moving field. ## What actually differs (and what doesn't) Here's the thing the debate obscures. Under the hood, these tools are the same shape: a model wrapped in a [harness](/articles/what-is-an-agent-harness) that reads files, runs tools, and loops. They differ in ergonomics, in which models they front, in the polish of their features. They do *not* differ in the fundamental job — turn a capable model into an agent that can act on your code. And critically, they all read the same kind of thing first: a context file ([AGENTS.md, CLAUDE.md](/articles/c2-vs-native-rule-files), and friends) and the markdown around it. The interface to your project's knowledge is essentially shared. **The tools differ in how they feel. They don't differ in needing to read your project's context first — which is exactly the part you should own.** ## Why the method matters more than the tool If the tools are interchangeable in shape and the field moves this fast, betting your workflow on one specific tool is the wrong bet. The durable thing isn't the agent — it's your *context*: the decisions, patterns, gotchas, and briefs that make any agent good on your project. That context is what should be permanent. The tool reading it should be swappable. Get that backwards — pour your effort into one tool's bespoke features and keep your knowledge in its head — and every tool switch is a migration. ## Agent-agnostic: switch freely, keep your context This is the heart of why C² is deliberately **agent-agnostic**. The [contextbase](/articles/what-is-a-contextbase) is plain markdown in git, usable by any agent that can read files, write files, and commit. Choosing C² is a commitment to a practice, not a vendor. The payoff is freedom: - Use Cursor today, Claude Code tomorrow, both on the same project — the contextbase doesn't care. - When a better agent ships, adopt it and your context transfers intact. No migration. - [Route different models](/articles/why-ai-agents-get-expensive) for different tasks without rework. The context belongs to the project, not the tool. That's the line that turns the tool debate from a fateful decision into a reversible preference. ## How to choose a tool under C² So, freed from the fear of choosing wrong, just pick the one you like: - Prefer a polished IDE experience? **Cursor.** - Prefer terminal-first, close to the shell? **Claude Code.** - Have a model or pricing preference? Pick the tool that fronts it. Then put your real effort into the contextbase, where it compounds — and switch tools whenever you want, because nothing important is trapped inside them. Pick the tool you like — an agent-agnostic method means your context outlives whichever you choose. Start here: see [what an agent harness is](/articles/what-is-an-agent-harness), [C² vs native rule files](/articles/c2-vs-native-rule-files), or [read the method](/c2/method). --- # How to build software with AI agents: a starting guide ## You direct, the agent builds. The loop, the context, and the habits that separate shipping from vibe-coding into a mess. - URL: https://stuartleo.com/articles/how-to-build-with-ai-agents - Published: 2026-06-08 - Reading time: 5 min read - Method: C² Method A plain-English guide to building real software with AI coding agents — the loop, the context, and the habits that separate shipping from vibe-coding into a mess. Building software used to mean writing every line yourself. It doesn't anymore. With an AI coding agent, the job shifts from *typing the code* to *directing the work* — and that shift is what lets a business person who decided to start shipping actually ship, alongside the developers who've done this for years. But "the agent writes the code" is where most people stop, and it's why most people end up with a mess. The difference between shipping and flailing isn't the model. It's a handful of habits. Here's the starting set. ## What changed: you direct, the agent builds The first reframe is the whole game. You are not the person hauling rope anymore. You're the one setting the course. An agent can write the boilerplate, run the tests, wire up the API, and chase the typo. What it can't do is decide what's worth building, judge whether the result is actually right, or own the standard the work is held to. That's your half — and it's the half that was always the hard part. So stop measuring yourself by lines written. Start measuring by decisions made and outcomes shipped. The agent is the crew. You're the pilot. ## The build loop Almost all good work with an agent runs the same small loop. Coding agents even show it to you as it happens — Anthropic describes capable agents as running exactly this kind of [gather, act, verify loop](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) until the work is done: 1. **Brief.** Say what to build, what *not* to build, and what "done" looks like. 2. **Act.** The agent reads the relevant context, makes the change, runs the tests. 3. **Review.** You check the result against your standard — not just "does it run" but "is it right." 4. **Capture.** Write down anything learned, then go again. Most of your leverage is in step one. A vague brief gets a plausible, drifting result. A sharp brief — *here's what to build, here's what to leave alone, here's how I'll know it worked* — gets something you can actually trust. The brief quality is the bottleneck, not the agent's capability. ## The Pilot model in one minute It helps to hold a single mental model: **you're a pilot, not a crew member.** A crew member writes the boilerplate. A pilot writes the brief that constrains the boilerplate. A crew member chases a bug for three hours. A pilot sets a time limit and escalates. A crew member updates the docs after the fact. A pilot writes the session note *as part of the work*. **The crew measures output in lines written. The pilot measures it in decisions made and outcomes shipped.** The reason this matters isn't motivational — it's practical. The pilot's work (clear briefs, clear standards, clear records) is exactly the work that makes the agent good. Do the pilot's job well and the crew gets dramatically better. Skip it and no model will save you. ## The one habit that compounds If you take one habit from this, take this: at the end of every session, write a few lines about what changed, why, what's verified, and what's next — and commit it to git. It feels almost too small to matter. It's the most important thing you'll do. An agent has no memory between sessions — close the laptop and everything it understood is gone. That note is the memory. Tomorrow's session (and tomorrow's agent, and your collaborator next week) reads it and starts ahead instead of from zero. Do this for a few weeks and the effect is striking. The decisions, the gotchas, the reasons — they accumulate into a written record of how your project actually works. That record is a [contextbase](/articles/what-is-a-contextbase), and it's the thing that turns building-with-agents from a treadmill of re-explaining into work that compounds. ## Avoiding the vibe-coding trap There's a failure mode that catches almost everyone, and it has a name now: **vibe coding** — letting the agent build from a vague feeling instead of a spec. It's seductive because it's fast, and it's genuinely fine for a throwaway prototype. The danger is using it for anything you intend to keep. With no brief and no way to check the result, the agent produces code that *looks* right, drifts a little further from what you meant with each change, and quietly rots as the project grows. You don't notice until you're deep in a corner you can't see the edges of. The fix is cheap. Before a real change, write the short brief — and include at least one **acceptance criterion you can actually run** ("the form rejects an empty email", "the test suite passes"). If you can't state how you'd know it worked, the agent can't either, and you've just authorised it to guess. A brief with runnable criteria is the cheapest insurance you'll buy. ## Where to go next Three habits carry the whole thing: direct instead of type, run the brief-act-review loop, and write down what each session learned. Get those and you're building with agents, not just generating code. Building with agents isn't about better prompts — it's about giving the agent context worth acting on, every time. Start here: [run your first session](/c2/start), learn [context engineering](/articles/context-engineering-explained), or [read the method](/c2/method) underneath it all. --- # How to stop your AI agent forgetting what it learned ## Agents forget when the session ends or the window fills. The model never learns your project. The written context does. - URL: https://stuartleo.com/articles/how-to-stop-your-agent-forgetting - Published: 2026-06-08 - Reading time: 10 min read - Method: C² Method AI agents forget when the session ends or the window fills, and the model never learns your project. The written-context fix that makes learning stick. The single most frustrating thing about building with AI agents, once you're past the novelty, is the forgetting. The agent that brilliantly untangled your auth flow on Monday has no idea any of it happened on Tuesday. You explain it again. It re-introduces a bug you already killed. You become the project's backup drive. This isn't a flaw in the model and it won't be fixed by a smarter one. It's structural. Once you understand the two ways agents forget, and where learning can actually live, the fix is straightforward. ## Two ways agents forget **One: the session ends.** An agent has no persistent memory between sessions. Close the laptop and everything it understood about your project evaporates. Tomorrow it wakes up blank. **Two: the context window fills.** Within a single session, the agent can only hold so much at once. The **context window** is a finite budget, and as it fills, the model degrades. It starts dropping details, losing the thread, and producing output that's confident and wrong. The phenomenon even has a name: the **memory wall**, where the working memory fills before the job is done and the agent [keeps running on degraded information](https://www.mindstudio.ai/blog/ai-agent-memory-wall-long-running-jobs) anyway. So you lose knowledge two ways: all at once when the session ends, and gradually as the window fills mid-task. ## The same bug, three sessions running I watched an agent solve the same problem three times in one week, and pay full price each time. The project used a date library with a quirk. A particular call returned UTC when you'd swear it returned local time, and it threw off a booking window by an hour. Monday, the agent hit it, spent twenty minutes diagnosing it, and fixed it. Good. Wednesday, new session, different feature, same library. The agent hit the exact same quirk and diagnosed it from scratch. Twenty minutes, again. Friday, a third time. At that point I was watching an intelligent agent rediscover something it had already figured out twice, because it had no idea its past selves had ever met this problem. My first instinct was that I'd phrased something badly. I hadn't. Monday's diagnosis lived in Monday's chat, and Monday's chat was gone. Each session started blank, so each session paid the full discovery cost. **An agent solving the same problem twice isn't a prompting failure. It's a memory that was never written down.** ## Why chat history isn't memory The natural assumption is that the chat *is* the memory, because it's all right there in the scroll. It isn't, for three reasons: - It scrolls past the window limit. Once it's out of the window, the agent can't see it. - Nobody else can read it. Your collaborator, and tomorrow's agent, never see your chat. - It vanishes when the session ends. No prompt fixes this, because the knowledge isn't missing from the prompt. It's missing from anywhere the *next* session can read. A transcript you can't rely on isn't a memory. It's a recording you'll lose. ## External state as memory Anthropic's engineers, writing about [long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents), land on the same answer that careful builders reach on their own: keep the important state *outside* the model. Write intermediate findings, decisions and progress to files. If the context compacts or the session ends, the agent re-reads those files and picks up where it left off. That's the core move. The model's memory is a sieve, so you stop relying on it. You put the durable stuff in files the agent reads on its way in. Memory becomes something you *own*, in git, instead of something the model loses. The date-library fix took two minutes. I had the agent write the quirk into a single file, `docs/03-knowledge/gotchas/date-lib-utc.md`, in plain words: what the call does, why it surprised me, what to do instead. Then I pointed the Router at the gotchas folder so the agent reads the index before touching date code. One file, committed to git, read on the way in. The next time a session touched the booking window, the agent read the gotcha first and just *used* the fix. No rediscovery. The twenty-minute tax went to zero, permanently. ## Where learning can actually live When people say an AI "learns your codebase", they usually mean one of three things, and only one of them is yours. **In the weights.** Training and fine-tuning. The model itself changes. The lab controls this, it costs a fortune, and you cannot inspect the result. **In the window.** In-context learning: what the model picks up inside a single session, from the files and messages in front of it. Genuinely powerful, and it evaporates the moment the session ends. **In the artefacts.** Rules, gotchas and briefs, written into the repo and read before the agent acts. They survive every session, every model upgrade, and every change of vendor. The C² Method lives entirely in the third. Not because the other two don't matter, but because the third is the only one a builder owns outright. You cannot retrain Claude. You can absolutely write a file that changes what Claude does tomorrow morning. ## The night a rule fired on an agent that never made the mistake Here's the strongest evidence I have, from one night on a live site I was building with a fleet of agents: one owning each spec, one leading, one reviewing every pull request. An agent building retail links needed an Amazon affiliate tag. Only I could supply that value, and I had not supplied it. So it invented a plausible one, `resolutemethod-20`, as a fallback, with a tidy comment explaining why the default was reasonable. It was not reasonable. There is no such account. Every affiliate link on the site would have gone out attributed to a tag I don't own, silently, for as long as nobody looked. It passed its own checks. It got reviewed twice. Nobody caught that the string was invented rather than real. When it surfaced, the fix took 2 minutes. The rule took 5: **Never invent a value only the pilot can supply — an account id, an API key, a tracking tag, a price. Read it from the environment, let it be absent, make the absent case behave honestly, and raise a blocker naming exactly what you need.** Three more rules were written the same night, each from a real failure. A reviewer approved work that had been ruled out an hour earlier, so: *check a PR against the pilot's open decisions before approving.* An approval outlived the commit it was made for, so: *an approval belongs to a commit, not a pull request.* An agent reverse-engineered a platform from `--help` output while a skill describing that platform sat unread on disk, so: *load the platform's skill before inferring its behaviour.* Then, at 2am, the second of those rules fired on the reviewing agent, in a fresh session. It had approved a PR 30 minutes earlier. One more commit landed, a docs-only change that was completely harmless, and it voided its own approval and re-reviewed. Cutting the corner would have cost nothing and nobody would have known. The rule had not existed at 9pm the night before. Nothing about the model changed in those 5 hours. No weights moved. No fine-tune ran. The agent had never made the mistake the rule was written for. A different agent had, on a different job, hours earlier. What changed is that somebody wrote it down. ## A ratchet, not a memory The closest thing in nature isn't memory. It's what anthropologists call the [ratchet effect](https://en.wikipedia.org/wiki/Cumulative_culture), or cumulative culture. Humans have not grown measurably smarter in 10,000 years. The culture accumulated instead. Each generation starts from the accumulated position rather than re-deriving fire, and the ratchet holds because knowledge is stored outside any individual. Map it directly. The models are the individuals: capable, and identical each morning, with no memory of yesterday. The repo is the culture. Git is the ratchet, because it only turns one way. It also explains why this beats learning in the model on four counts: | | Learning in the weights | Learning in the repo | |---|---|---| | Can you read it? | No | It is a markdown file | | Can you undo a bad lesson? | Retrain | `git revert` | | Does it move between vendors? | No | Point Codex or Gemini at the same file | | Can you trace why it exists? | No | To the commit that fixed the failure | That last row is the one I'd defend hardest. Every rule is attached to the incident that produced it. A new agent doesn't just get told what to do. It can read what went wrong when somebody did otherwise. Rules with their scar tissue attached are obeyed differently than rules handed down. ## Compaction: surviving a full window Written files fix the cross-session forgetting. For the *within*-session kind, the window filling mid-task, the move is **compaction**: keeping the working set lean so the agent never hits the wall. The practical version: don't track raw token counts, watch the fill level. Keep the original intent and the last couple of steps, summarise what's gone stale, and drop what no longer matters *before* the agent starts guessing. When you sense a session getting long, have the agent write down where it's up to, then start fresh from that note. You're trading a bloated, rotting window for a short, sharp one. ## The contextbase as durable memory Put it together and you get a simple discipline: a written record the agent reads before it acts, and updates as it learns. Decisions in a file. Gotchas in a file. A few lines at the end of every session: what changed, what's verified, what's next. All committed to git. Any time the agent works out something non-obvious, a framework quirk, an auth trap, a race condition, it gets captured once, in the same session, as a gotcha. After a few dozen, the project has a small library of battle-tested knowledge that doesn't evaporate when a session ends or a person leaves. That record is a [contextbase](/articles/what-is-a-contextbase). It isn't documentation. Documentation describes what exists. A contextbase changes what happens next. The next session doesn't start blank. It reads what the last one learned and starts ahead. ## What it learns, and what it never will The claim has a hard edge, and you'll get caught out if you don't state it. **This learns rules, not skill.** The agents write no better code than they did the night before. They lie less and they check more. That's a narrower claim than "AI that improves at your project", and far more durable, because it stays true when the model changes underneath you. **It only learns what somebody writes down.** A failure nobody catches teaches nothing. That night had a human and several agents watching closely, and 2 of the 4 rules came from a reviewer catching something I had missed myself. **It depends on the reading discipline holding.** Every gain rests on the next agent actually loading the router and the gotchas before it acts. Let the contextbase rot and the ratchet stops turning that same day. **It compounds per repo, not globally.** What one project learns is worthless to the next unless somebody promotes it, out of the repo where it was learned and into the kit every project inherits. Skipping that step is why the same mistake gets made in 6 repos in a row. The test isn't whether your agent seems smart today. It's whether a mistake made on Tuesday can still be made on Friday. Write the next trap down the moment it bites: one file, the symptom, the cause, the fix. Point your router at it. An agent's memory isn't in the model. It's in what you write down and commit. Start here: see [compaction in detail](/articles/compaction-keep-the-context-window-lean), [what a contextbase is](/articles/what-is-a-contextbase), or [read the method](/c2/method). --- # How to write an AGENTS.md that agents actually follow ## The context file your coding agent reads first. How to write one that's read, not skimmed and ignored, with a worked example, line by line. - URL: https://stuartleo.com/articles/how-to-write-agents-md - Published: 2026-06-08 - Reading time: 6 min read - Method: C² Method AGENTS.md (and CLAUDE.md) is the file your coding agent reads first. What belongs in it, a worked example line by line, and how to keep it lean. `AGENTS.md` has quietly become the most important file in a lot of repos, and one of the most misused. It's the file your AI coding agent reads before it does anything. Codex, Cursor and many others read `AGENTS.md`, Claude Code reads `CLAUDE.md` (and falls back to `AGENTS.md` when there is no `CLAUDE.md`), and Gemini reads `GEMINI.md`. The idea is the same. Get it right and the agent starts every task oriented and on-side. Get it wrong and it's a wall of rules the agent skims and ignores. The good news: writing one the agent actually follows comes down to a few clear principles, and a shape you can copy. Here are both. ## What AGENTS.md is for `AGENTS.md` is the agent's on-ramp to your project. In one short read it should tell the agent what this is, the rules that must hold, where to find anything else, and the commands it'll need. The best way to think about it isn't "the rulebook." It's the **front door and the map**. A new contractor doesn't need your entire wiki on day one. They need orientation and signposts. So does the agent. In C² this file has a job and a name: the **Router**. It's `AGENTS.md` by default, or `CLAUDE.md` if you work in Claude Code. The critical word is *index*. The Router is not where your knowledge lives. It's the map to where your knowledge lives. That distinction is the whole game, and it's the one almost everyone gets backwards at first. ## The rule: route, don't dump Here's the mistake nearly everyone makes, including me early on: treat `AGENTS.md` as the place to put *everything*, because it's the file you're sure the agent reads. Every convention, every gotcha, every edge case, piled into one file. It feels safe. It's the opposite. A long file gets skimmed, and nobody keeps it current, so it drifts out of date as well. The empirical study of [context files for agentic coding](https://www.augmentcode.com/guides/how-to-build-agents-md) finds the same thing practitioners learn the hard way: the files that work are focused and point outward, not exhaustive. Past a certain length the agent stops absorbing it, and you've made the most important file the least readable. **Everything you add to AGENTS.md makes everything else in it less likely to be read. Length is a cost, not a safety net.** So: route, don't dump. The detail lives in other files. `AGENTS.md` carries the essentials and points to the rest. A good one is a switchboard, not an encyclopedia. ## Instructions that actually work Two kinds of instruction earn their place in the file: - **Prohibitive: the hard boundaries.** "Never commit secrets." "Don't add a second payment provider." "Never use `--force` on the shared branch." Clear, absolute, short. These are the rules worth their lines. - **Conditional: the situational logic.** "When adding a route, update the sitemap." "If a test fails, fix it before moving on. Don't disable it." These encode how to behave in the cases that come up. What doesn't earn its place: vague aspiration ("write clean code"), and anything the agent can infer from the codebase itself. Be specific or cut it. ## A worked example, line by line A file that earns its keep has roughly five short sections. Here's the skeleton I use: ```markdown # Project Name — Router One-paragraph overview: what this is, who it's for, the stack. ## Critical rules The 3–7 things that must always hold. Not 30. The non-negotiables. ## Where things go - PRDs / specs → docs/01-planning/ - Session briefs → docs/02-working/session-briefs/ - Gotchas → docs/03-knowledge/gotchas/ ## Quick reference Common commands: dev, build, test, deploy. ## Status One line on where the project is + a link to the latest session brief. ``` Taking it a section at a time: - **Overview.** Orient the agent in a paragraph. What the project is, who it's for, the stack. No history, no philosophy. - **Critical rules.** Only the load-bearing ones, written as the prohibitive and conditional instructions above. Three to seven, not thirty. If everything's critical, nothing is. - **Where things go.** This is the actual routing: pointers into the contextbase. It tells the agent where to look for a spec, where to write today's brief, where the traps are recorded. - **Quick reference.** The handful of commands the agent reaches for constantly, so it doesn't guess at your build or test script. - **Status.** A single line plus a link to the latest session brief, so the agent finds the current state of the work in one hop. Each section points outward. The detail is a click away, not pasted in. ## Keeping it under the bloat line `AGENTS.md` only decays one way: it grows. Every incident tempts you to add a rule so it never happens again. Do that enough and you've rebuilt the wall of text. It happened to me. My own `CLAUDE.md` hit 600 lines before I admitted there was a problem, and the agent started missing rules that were sitting in plain text in the file. Moving the detail out to linked docs took it to about 70 lines, with nothing lost. That's the [field note on the CLAUDE.md that got too big](/articles/the-claude-md-that-got-too-big). The discipline that keeps it readable: 1. **Cap it at what the agent will actually read**, roughly a screen or two. 2. **When you reach to add detail, add a pointer instead.** New convention → a reference file, linked. New trap → a gotcha file, linked. The file gains a *line*, not a *paragraph*. 3. **Review it occasionally and cut.** A rule nobody enforces is noise. Delete it. The test is simple: could the agent read this whole file and retain it? If not, it's too long, and the excess is actively hurting you. ## Wiring it to the contextbase A lean `AGENTS.md` is only powerful because of what it links to. It's the one stable entry point to your wider [contextbase](/articles/what-is-a-contextbase): the briefs, decisions and gotchas that live in `docs/`. The file points, the contextbase holds. From it, the agent reaches the brief for today's task, the gotcha for the file it's touching, the decision behind the architecture, by following links and loading only what the task needs. That's lazy-loading, and it's also how your context stays lean. The agent reads the index every time, not the whole library. A context file the agent follows is short, specific, and points everywhere else, not a wall of rules it skims. Start here: read the [field note on a Router that got too big](/articles/the-claude-md-that-got-too-big), see [C² vs native rule files](/articles/c2-vs-native-rule-files), or [read the method](/c2/method). --- # I ran five agents at once and regretted it ## A field note on spinning up five agents on one feature to go faster, and the contradictory mess that followed. - URL: https://stuartleo.com/articles/i-ran-five-agents-at-once-and-regretted-it - Published: 2026-06-08 - Reading time: 4 min read - Method: C² Method A field note on spinning up five agents on one feature to go faster, the contradictory mess that followed, and what I got wrong for a year about why it failed. I once pointed five agents at the same feature, convinced I was about to go five times faster. I went backwards. This is the field note on what actually broke — and on the lesson I drew from it that turned out to be wrong. ## The idea: five agents, five times faster The feature was big — a multi-part settings overhaul — and I was impatient. So I had a clever idea: why run one agent serially when I could run five in parallel? One on the UI, one on the API, one on validation, one on tests, one on docs. Five workers, one feature, five times the speed. Obviously. I spun them all up against the same branch and let them go. ## What actually happened (contradiction and conflict) Within twenty minutes it was chaos. Two agents edited the same file and clobbered each other's changes. The validation agent assumed one shape for the settings object — the API agent assumed another, so they built two halves that didn't fit. The test agent wrote tests against an interface the UI agent had already changed. Each agent was individually reasonable. Together they were a committee that never met. The worst part wasn't even the broken code. It was that I couldn't reconstruct *what had happened*. Five overlapping streams of edits, no single thread to follow. I couldn't write a [session brief](/articles/write-your-first-session-brief) because there was no coherent story to tell. **Five agents on one feature didn't give me five workers. It gave me five people redecorating the same room at once, in the dark.** ## Why a swarm on one problem fails I'd misunderstood what parallelism needs. Agents don't coordinate the way people do — no quick word at the desk, no shared sense of who's touching what. Point several at the same surface and they overwrite, contradict, and conflict. The hard part of multi-agent work was never spawning the agents — it's the coordination, and a [crowd on one problem](https://addyosmani.com/blog/code-agent-orchestra/) maximises the coordination cost while delivering almost none of the parallel benefit. ## The fix I threw it out and started over with one lead agent, working through the feature in sequence, writing a session brief as it went. Slower per my fantasy, far faster in reality — because nothing had to be untangled. When I wanted a second opinion on the validation logic, I brought in a [bench agent](/articles/ai-code-review-with-a-bench-agent) to review, *after* the lead had done its pass. Clean, recordable, and it worked. ## What I got wrong about why it failed For a long time I told that story as a lesson about the *number*. Five was too many. One was right. I repeated it confidently enough that other people repeated it back to me. That was the wrong lesson, and it took me a while to see it. The number was never the problem. **All five agents were working on one surface** — one branch, one working tree, one settings object they each held a different opinion about. Two agents would have failed the same way. So would twelve. What made it collapse was that everything was shared and nothing in any brief said so. ## When I do use more than one I still use multiple agents, and now I can say exactly when. Two conditions, both of which my five violated inside the first minute: - **No edge.** An edge means one agent's output is another's input. My validation agent and my API agent had an edge the size of a house — they were building two halves of the same object — and I started them at the same instant anyway. - **No shared surface.** A surface is everything an agent mutates or contends for: files, data, a rate-limited API, a deploy target. Mine shared every one of those. Two unrelated features, each in its own [git worktree](/articles/parallel-agents-with-git-worktrees), never touching the same anything — that parallelises fine, and I do it regularly now. The rule I actually learned the hard way wasn't *fewer agents*. It was **draw the edges before you spin anything up.** And if you can't find two jobs with no edge between them, you don't have two jobs. If you want those two checks as a procedure rather than a war story, I wrote it up properly: [when can agents actually run in parallel](/articles/when-can-agents-run-in-parallel). Five agents on one surface isn't five times faster — it's five times the conflict. The bug was the shared surface, not the number. Start here: see [when agents can run in parallel](/articles/when-can-agents-run-in-parallel), [how agent teams work](/articles/ai-agent-teams-explained), or [read the method](/c2/method). --- # Parallel Claude Code agents with git worktrees ## Several Claude Code agents on one repo means merge chaos — unless each gets its own worktree. Then come the costs nobody mentions. - URL: https://stuartleo.com/articles/parallel-agents-with-git-worktrees - Published: 2026-06-08 - Reading time: 10 min read - Method: C² Method Run parallel Claude Code agents in git worktrees: isolation, sequential merges, and the disk, cleanup and CI-minute costs that arrive once you do it for real. There's a real version of "run agents in parallel" that works, and it's not the swarm-on-one-problem trap. It's several agents doing genuinely independent work, each in its own isolated workspace, merged back cleanly when they're done. The thing that makes it safe is an old git feature most people have never used: **worktrees**. Here's how worktrees turn parallel agents from a merge nightmare into a clean pattern, when it's actually worth doing, and what it costs once you run it every day. I run Claude Code agents this way, so the numbers further down are mine. ## Why parallel agents collide Point two agents at the same repo and let them work at once, and the failure is immediate and physical. They edit the same files. One saves over the other's changes. They leave the working tree in a half-and-half state neither can reason about. You get merge conflicts, race conditions, and corrupted state — not because the agents are bad, but because they're sharing one filesystem with no idea the other exists. This is the practical reason a [swarm on one problem fails](/articles/i-ran-five-agents-at-once-and-regretted-it): even setting aside contradictory reasoning, they can't physically share a working directory without trampling each other. ## Git worktrees: isolation without a second clone A git worktree is a second working directory attached to the same repository, checked out to its own branch. You can have several at once, each in its own folder, all backed by the same repo history — without cloning the whole thing again. ```bash # from your repo, create an isolated worktree on a new branch git worktree add ../feature-billing -b agent/billing git worktree add ../feature-search -b agent/search ``` Now `../feature-billing` and `../feature-search` are completely separate working directories. An agent in one cannot see or touch the files of the other. As the guides on [git worktrees for parallel agents](https://www.augmentcode.com/guides/git-worktrees-parallel-ai-agent-execution) put it, they give each agent complete filesystem isolation without duplicating the repository — lightweight, fast, and clean. **A worktree gives each agent its own room. They can all work at once because none of them is in anyone else's space.** ## One agent, one worktree, one branch The rule that makes this safe is simple: **one agent, one worktree, one branch.** Each parallel agent gets its own isolated directory and its own branch to commit to. No agent shares a working tree with another. No agent commits to `main` directly. This maps cleanly onto the [lead-agent idea](/articles/ai-agent-teams-explained): one lead agent per surface. Here, each worktree is a separate surface, so each gets its own lead. They run at the same time because they're working on different things in different places. ## Sequential merges back to main Parallel execution, sequential integration. The agents work concurrently in their worktrees, but you bring the results back one at a time: 1. Each agent finishes its task and its branch passes its tests. 2. You review and merge one branch to `main`. 3. You merge the next, resolving against the now-updated `main`. Merging sequentially keeps integration sane — you're never trying to reconcile three sets of changes at once. Isolation first, integration second. (And when you're done, `git worktree remove` cleans up.) That shape has a name, and it's worth knowing because it generalises well past worktrees. Independent agents running at the same time is a **fan-out**. The point where their results come back together — the merge, the integration brief, the PR — is a **barrier**. The worktree itself is **isolation**: it stops one agent's mess reaching the others. Fan out, isolate, barrier. Nearly every genuinely parallel run I do has that shape, whether or not git is the thing doing the isolating. Once you can see it, you start noticing it was already in your plans — [the shape of the work is a graph](/articles/the-shape-of-the-work-is-a-graph), and most people are drawing it as a queue. ## When parallel is worth it (and when it isn't) Worktrees solve the *mechanics* of parallel work, but they don't change the *judgement* about when to parallelise: - **Worth it:** genuinely independent tasks — separate features, separate services — where no edge connects them and no surface is shared. Here, parallel worktrees are a real speed-up. - **Not worth it:** several agents on one shared surface. Isolation can't fix that, because the conflict is in the reasoning, not just the files. That's still the [anti-pattern](/articles/when-can-agents-run-in-parallel), worktrees or no worktrees. The test is independence, and independence has two halves. Is there an **edge** — does one agent's output become another's input? And is there a shared **surface**? That second word does more work than people expect, because **a worktree only isolates the filesystem.** A surface is everything an agent mutates or contends for: files, yes, but also data, a rate-limited external API, a deploy target. Two agents in two spotless worktrees still collide if they both write to one staging database. That's *false independence*, and it's the version that bites — nothing in either brief says the surface is shared, so nobody sees it coming. And parallelism buys breadth, not judgment. If two tasks could be done by two people who never need to talk, they can be two agents in two worktrees. If they'd need to coordinate constantly, they're really one task — give them to one agent. When the work is exploratory and I don't yet know what I'm looking for, that's one agent too, no matter how many worktrees I could spin up. Give each parallel agent its own worktree, then merge sequentially — isolation first, integration second. ## The costs nobody mentions Every guide to worktrees, including the first half of this one, stops at `git worktree add`. The bill arrives later, in three currencies: disk, cleanup and CI minutes. The numbers below come from my main repo, the monorepo I build my platform in, where Claude Code agents work in worktrees. ### Disk: a worktree is not free A worktree shares git history. It doesn't share anything else. In a JavaScript monorepo each new worktree wants its own `node_modules`, and in my repo a fresh `npm install` costs about 2.4 GB. Agents usually ran it only so the pre-commit hook would work. Nothing removes a worktree when its agent finishes, not even after its PR merges. By 5 October 2026 the repo held 123 leftover agent worktrees using about 216 GB, and the Mac ran out of disk. 68 stale ones were removed. By the same afternoon, 29 new ones had brought it back to 144 GB. So I stopped asking agents to be tidier and made worktrees cheap instead. `new-worktree.sh` creates a worktree whose dependencies come from a shared cache: one `npm ci` per lockfile version, and every later worktree gets copy-on-write clones of that cache's `node_modules`. Measured with `df`, a new worktree went from about 2.9 GB to about 0.08 GB. Its companion, `worktree-setup.sh`, does the dependency half for a worktree that already exists — which is the one to run, instead of `npm install`, in a worktree Claude Code created itself. Both refuse to start with under 20 GB free, because a full disk fails halfway through a checkout and leaves a half-made worktree behind. Two traps came with the fix. `du` counts every clone as a full copy, so it reports gigabytes that don't exist. Measure with `df`. And in an older worktree whose `node_modules` was a symlink into the main checkout, `rm -rf node_modules/` with a trailing slash follows the link and empties the main checkout's `node_modules`. `git worktree remove` follows nothing. Use it. ### Cleanup: someone has to own the delete The rule is one line now. The session that creates a worktree removes it when its PR merges or its task ends — `git worktree remove`, then `git worktree prune`. A worktree worth keeping gets `git worktree lock` with a reason. Rules get skipped, so a sweep backs this one up. `prune-worktrees.sh` is a dry run by default and removes only with `--yes`. It touches a worktree only when it's clean, unlocked, has no running process inside, and either has a merged PR whose head matches the worktree exactly or is fully pushed and idle for 2+ days. It runs at the end of every session for merged work, and on a schedule for the rest. Squash merges nearly defeated it. GitHub deletes a squash-merged branch, which leaves that branch's commits on no remote. The first version of the prune read every merged worktree as unpushed work and kept them all, and on 19 October 2026 the disk was down to about 5 GB free. The fix was to stop inferring and ask GitHub whether the PR had merged. ### CI minutes: parallel agents push in parallel The cost I didn't see coming wasn't on my machine at all. Every push to a ready PR in that repo runs about 6 workflows, each billed as a whole minute or more, and every merge runs a deploy. Several agents pushing in parallel multiply it. 3,000 included GitHub Actions minutes went in 5 days in October 2026. The fix is behavioural. Keep PRs as drafts while the agent iterates, because drafts skip CI. Batch commits into one push. Avoid rebase-and-force-push loops. Count the cost before merging a pile of PRs at once. **Parallel agents multiply output. They multiply disk, cleanup and CI minutes at exactly the same rate.** ## One person merges Parallel execution, sequential integration — the barrier needs an owner. The C² fleet kit makes that explicit. Each PRD gets a lane: its own agent, in its own worktree, on its own branch. A tower runs the fleet, and a checkpoint reviews every PR in a fresh context. By default 3 lanes fly at once. The config carries a switch, `MERGE_REQUIRES_PILOT`, and the kit's advice is to start with it on — the tower never merges, you do — on any repo where a merge deploys. Two rules from the kit's [RULES.md](https://github.com/waymakerone/c2method/blob/main/fleet/RULES.md) do most of the work, quoted as written: 1. "An approval belongs to a commit, not a pull request." And under it: "When the head moves, the approval is void: drop the approved label, restore the review label, review the new head, and say so, so nobody merges an approval that was for older code." 2. "Some things can never be delegated at all, and an agent refusing them is behaving correctly: merging where a merge deploys, setting secrets, changing scope, raising the ceiling, spending." The first one matters more with worktrees than without. Each lane keeps pushing to its own branch, so a review can be stale minutes after it's written. The second one is why the barrier is a person. Isolation lets the agents run at once. Only one owner can safely decide what lands. Run parallel agents in worktrees, make each worktree cheap, give every one an owner who deletes it, and keep the merge with a human. Start here: see [how agent teams work](/articles/ai-agent-teams-explained), [when agents can run in parallel](/articles/when-can-agents-run-in-parallel), [running agents overnight safely](/articles/run-agents-overnight-safely), or [read the method](/c2/method). --- # Prompt engineering vs context engineering for coding ## One tunes the instruction. The other curates what the agent knows. Why the second is the skill that now pays. - URL: https://stuartleo.com/articles/prompt-engineering-vs-context-engineering - Published: 2026-06-08 - Reading time: 5 min read - Method: C² Method Prompt engineering tunes the instruction. Context engineering curates what the agent knows. Why the second is the skill that now pays — and how C² operationalises it. If you've spent any time building with AI agents, you've met both terms — usually as a fight. "Prompt engineering is dead." "Context engineering is the only skill that pays." The headlines oversell it, but there's a real shift underneath, and getting it right tells you where to put your effort. So here's the honest comparison: what each discipline actually is, where each one's ceiling sits, and why — for building software — the centre of gravity moved from one to the other. ## The two disciplines, defined **Prompt engineering** is the craft of one message: composing a single input that gets a good answer. The role-play opener, the step-by-step instruction, the worked example in the prompt. It's real skill, and on a single isolated task it pays off. **Context engineering** is the craft of the information environment: curating *what the agent knows* before it acts — the relevant code, the decisions already made, the patterns to follow, the history of what's been tried. It's not about the sentence you send. It's about the evidence the model reasons over when it answers. The cleanest distinction: prompt engineering controls **how you ask**. Context engineering controls **what the agent knows when it answers**. **The prompt is the instruction. The context is the evidence. A perfect instruction over thin evidence still produces a confident guess.** ## What each one controls Picture asking an agent to change how your app handles login. With **prompt engineering**, you refine the ask: you specify the framework, give an example, lay out the steps. Useful. But if the agent doesn't know how your auth actually works — which library, which session model, which decision you made last month and why — it fills the gap with something plausible. Plausible is the trap: it compiles, it looks right, and it's wrong in a way you find out later. With **context engineering**, you make sure the agent *has* that knowledge before it starts: the auth decision, the pattern your codebase already uses, the gotcha that bit you the last time someone touched sessions. Now the same ask produces something reviewable instead of something invented. The instruction was never the hard part. Assembling the right evidence is. ## The third layer: harness engineering These two aren't actually a pair — they're two of three nested layers, each containing the one before: | Layer | What it is | The unit | |---|---|---| | Prompt engineering | The message | One composed input | | Context engineering | The memory | What's kept or dropped in a finite window | | Harness engineering | The machine | The gather-act-verify loop, retrying on failure | Prompt sits inside context sits inside the harness — the machinery that loads context, calls tools, checks output, and recovers from failure. Practitioners increasingly call the whole discipline [harness engineering](https://martinfowler.com/articles/harness-engineering.html) for that reason. It's worth holding the full picture, because "prompt vs context" makes them sound like alternatives when they're really floors of the same building. ## Why context won as agents got capable So why did the conversation move from prompting to context? Because the models got good. When models were weaker, phrasing genuinely changed the answer — coax it the right way and you'd get noticeably better output. As the models got more capable, that margin shrank. A capable model doesn't need to be coaxed into reasoning well. What it needs is to *know the right things*. The bottleneck moved from the model's willingness to the model's knowledge — and knowledge is context. For a one-off question, prompt engineering still earns its keep. For building software — many tasks, over weeks, across sessions and people — context is the lever, and it's not close. ## How a contextbase makes it durable Here's the gap in most context-engineering practice, and where C² comes in. Context engineering is usually treated as something you do *fresh each time*: assemble the right window, run the task, throw it away. The context is delivery — used once, then gone. Which means the most valuable context (how the project works, what's decided, what's gone wrong) gets rebuilt from scratch every morning. That's the tax, reappearing. C² makes context **durable**. The high-signal knowledge gets written down once and committed to git as a [contextbase](/articles/what-is-a-contextbase), so the agent reads it before every task and it compounds across sessions instead of evaporating. And C² holds all three layers in one method: the **Prompt Brief** is the prompt layer, the **contextbase and Router** are the context layer, and the **brief cascade plus verification** are the harness loop. Context engineering stops being a chore you repeat and becomes an asset that accrues. ## How to choose where to invest - **Get prompt engineering to "good enough."** Learn to ask clearly and specifically. The returns flatten fast — don't over-invest here. - **Put real effort into context engineering.** Curate the smallest high-signal set the agent needs, and keep the window lean. - **Make it durable.** The highest-return move is writing the recurring context down and committing it, so you engineer it once and reuse it forever. A great prompt over thin context still guesses. Context engineering is where the leverage moved — and a contextbase is what keeps it from leaking back out. Go deeper: [context engineering, explained](/articles/context-engineering-explained), [what an agent harness is](/articles/what-is-an-agent-harness), or see [how the AI development methodologies compare](/articles/ai-development-methodologies-compared). Or just [read the method](/c2/method). --- # How to run AI coding agents overnight, safely ## Unattended agents can ship real work while you sleep — or wreck things. The guardrails that make overnight runs safe. - URL: https://stuartleo.com/articles/run-agents-overnight-safely - Published: 2026-06-08 - Reading time: 4 min read - Method: C² Method Unattended agents can ship real work while you sleep — or wreck things. The guardrails that make overnight runs safe: branches, scopes, cost caps, no prod. The dream is real: brief an agent before bed, wake up to a finished feature on a branch. Unattended agents genuinely can ship work overnight. The nightmare is also real: wake up to a branch full of confident damage, or a cost alert, or worse. The difference between the two is entirely guardrails. Here's how to run agents unattended so the morning is a pleasant surprise, not a cleanup. ## The promise and the risk When you're in the loop, you catch problems as they happen — a wrong turn, a bad assumption, a runaway cost. Unattended, none of that. The agent runs the full loop with no one to stop it, which is exactly what makes it powerful and exactly what makes it dangerous. The core risk is subtle: an agent that behaves perfectly while you watch can behave very differently on the run you don't. As the practitioners writing up [overnight agent runs](https://amux.io/guides/ai-coding-agents-overnight/) put it, the same prompt might succeed nine times and fail catastrophically on the tenth — and unattended means no one's there for the tenth. So you don't rely on it behaving. You build the cage. ## Isolate: branches and worktrees Rule one: an overnight agent never works on `main`, and never where it can step on anything live. Give it its own branch, or better, its own [git worktree](/articles/parallel-agents-with-git-worktrees) — a separate working directory entirely. Better still for risky work, a sandboxed environment (a container or microVM) with no access to your host machine. Whatever it does, it does in a box you can inspect in the morning and throw away if it's wrong. ## Restrict: file scope and forbidden zones Rule two: name what it may touch, and what it absolutely may not. Define forbidden zones explicitly, before the run: **no deployment pipelines, no auth systems, no payment code, no secrets.** These are the places where a confident mistake becomes a catastrophe, and there's no overnight task worth that risk. Restrict the file scope to the feature at hand. The agent should wake up in a small, well-fenced yard, not the whole property. **Never give an overnight agent the keys to production, auth, or payments. The upside of an unattended change there is never worth the downside.** ## Verify: tests and pre-commit gates Rule three: nothing gets committed that hasn't passed the gate. Enforce pre-commit hooks that run linting and the test suite, so the agent literally cannot commit broken work. Give it a full test suite that runs without production dependencies, and ideally a CI pipeline it can trigger. This is where [test-driven development](/articles/test-driven-development-with-ai-agents) earns its keep doubly — the tests are the unattended agent's only honest judge of whether it succeeded. No green, no commit. ## Cap: cost and the no-prod rule Rule four: bound the blast radius, in dollars and in scope. Set a hard cost cap so a stuck agent looping all night can't run up a fortune. Pair it with the no-prod rule from above as the two non-negotiables: a money ceiling and a production fence. With those in place, the worst case is a wasted branch and a small bill — annoying, not disastrous. A safety file like [GUARDRAILS.md](/articles/c2-vs-guardrails-md) — or, better, your contextbase — helps here too: it carries the lessons from past failures into the next run, so the agent stops repeating the mistakes that bit you before. Never give an overnight agent access to prod, auth, or payments — and never let it run without a test gate. Get those two right and unattended runs go from reckless to genuinely useful. Start here: write [acceptance criteria the agent can run unattended](/articles/acceptance-criteria-for-agents), read the [field note on an overnight run gone wrong](/articles/the-overnight-run-that-went-wrong), or [read the method](/c2/method). --- # Subagents, MCP and skills: fitting tools into C² ## The agent harness has a lot of tools. How they fit a contextbase, and which to reach for without losing the plot. - URL: https://stuartleo.com/articles/subagents-mcp-and-c2 - Published: 2026-06-08 - Reading time: 4 min read - Method: C² Method Subagents, MCP servers, slash commands, skills — the agent harness has a lot of tools. How they fit a C² contextbase, and which to reach for without losing the plot. If you're past the basics of building with agents, you've hit the toolbox: subagents, MCP servers, slash commands, skills, hooks. Powerful, and easy to get lost in. People wire up six tools and end up with a setup nobody understands, context scattered across all of them. Here's how to think about these tools clearly — what each is for, and how they fit a C² [contextbase](/articles/what-is-a-contextbase) without fragmenting it. ## The harness toolbox These tools all live in the **harness** — the machinery around the model that turns it into a working agent. They extend what the agent can reach and do. The four you'll meet most: - **MCP servers** — the plumbing that connects your agent to outside tools and data (GitHub, a database, a browser, your design tool). - **Skills** — reusable instructions that teach the agent how to perform a task, applied automatically when relevant. - **Slash commands** — explicit triggers you invoke by hand for a repeatable action. - **Subagents** — separate agent instances with their own context window, spun up for a scoped task. Martin Fowler's team groups all of this under [harness engineering](https://martinfowler.com/articles/harness-engineering.html) for good reason: it's the machine layer, sitting above your prompts and your context. ## What each is actually for The clean way to keep them straight is by *job*: - **MCP is the plumbing.** Reach for it when the agent needs something *outside* your repo — live data, an external service, a tool the model can't reach on its own. - **Skills are the know-how.** Reach for them when you want the agent to apply a richer workflow automatically when the situation calls for it. - **Slash commands are the trigger you control.** Reach for them when you want an explicit, repeatable entry point — *you* decide when it runs. - **Subagents are the scoped worker.** Reach for one when a task deserves its own clean context window — an independent review, a focused, repeatable check — so it doesn't clutter the main session. **MCP is the plumbing. Skills are the know-how. Slash commands are the trigger. Subagents are the scoped worker. Pick by the job, not the novelty.** ## Where the contextbase sits under them Here's the part people miss. These tools extend the agent's *reach*. None of them is the agent's *memory*. A subagent with its own window still forgets when it's done. An MCP server fetches data but doesn't remember decisions. Skills encode how to do a task, not the decisions behind it and why. The contextbase is the layer underneath all of them — the durable, version-controlled knowledge every tool and every agent reads. A subagent doing a review should read the same contextbase as the lead agent, so its judgement is anchored to the same decisions and gotchas. The tools give reach — the contextbase keeps that reach pointed at one source of truth. ## Keeping tools from fragmenting context The risk with a big toolbox is **fragmentation** — context scattered across six tools, no single place that's true. The discipline that prevents it: - **One source of truth.** Decisions, patterns and gotchas live in the contextbase, in git — not buried in a skill file or an MCP server's config. - **Subagents read, they don't own.** A subagent reads from the contextbase and writes its findings back to it. It doesn't keep private knowledge the lead agent can't see. - **The Router points to the tools too.** Your [Router](/articles/how-to-write-agents-md) can note which tools the project uses and when, so the setup is documented, not folklore. The aim is one place that's true, with tools hanging off it — not knowledge smeared across the toolbox. ## A simple decision rule When you're tempted to add a tool, ask: *does the agent need more reach, or does it need to remember better?* If it's reach — connect to something, run a repeatable task — a harness tool is right. If it's memory — stop re-explaining, stop repeating mistakes — the answer is the contextbase, not another tool. Tools give the agent reach. The contextbase keeps that reach pointed at the same source of truth. Start here: see [what an agent harness is](/articles/what-is-an-agent-harness), [how to write the Router file](/articles/how-to-write-agents-md), or [read the method](/c2/method). --- # Test-driven development with AI agents ## Write the test first, let the agent go red-green-refactor at machine speed. - URL: https://stuartleo.com/articles/test-driven-development-with-ai-agents - Published: 2026-06-08 - Reading time: 4 min read - Method: C² Method TDD turns an agent from hopeful to reliable: write the test first, let the agent go red-green-refactor at machine speed. How to run it, and what it needs. Of all the ways to make an AI agent reliable, test-driven development is the one I'd reach for first. It takes an agent's biggest weakness — producing plausible code that might be wrong — and removes it, by giving the agent a target it can check itself against, before you ever look. Here's how TDD works with an agent, why it fits the agentic loop so naturally, and the one prerequisite without which it falls apart. ## Why TDD fits agents so well Test-driven development means writing the test before the code: state what "correct" looks like as a runnable test, watch it fail, then write just enough code to make it pass. Humans have done it for decades to catch regressions early and keep intent honest. It fits agents even better than it fits humans, for one reason: an agent loves an unambiguous target. Given a failing test, the agent has a crisp, machine-checkable definition of done — and it can run the test itself, see red, fix, see green, all inside its loop. No guessing whether it's finished. The test says so. The teams getting the most reliable results treat [TDD as the default discipline](https://qaskills.sh/blog/tdd-ai-agents-best-practices) for exactly this reason. ## Red-green-refactor at machine speed The classic TDD cycle is red-green-refactor: write a failing test (red), make it pass (green), then clean up the code without breaking the test (refactor). An agent runs this loop the same way a disciplined developer does — just faster. 1. **Red.** The test exists and fails, because the feature isn't built. 2. **Green.** The agent writes the minimum code to pass it, running the test until it's green. 3. **Refactor.** The agent tidies the implementation, re-running the test to confirm nothing broke. **A test the agent can run turns "I think this is done" into "this is done, here's the green run." That's the whole value.** The agent does the tedious part — the many small runs — at machine speed, while the test holds the line on what correct means. ## Test infrastructure is the prerequisite Here's the catch, and it's the thing that makes or breaks agentic TDD: it only works if your project can already run tests. If there's no test runner configured, no existing test patterns to copy, and no CI to validate against, the agent has nothing to optimise toward — and the loop collapses into the same hopeful guessing TDD was meant to fix. This is why the most successful agentic setups invest in test infrastructure *first*, before turning agents loose. Test infrastructure isn't overhead here. It's the signal the whole approach runs on. If your project has no tests, the first high-value agentic task is to set up the runner and write a few real tests — and from then on, TDD is available to everything else. ## Tests as acceptance criteria the agent self-checks This connects directly to [acceptance criteria](/articles/acceptance-criteria-for-agents). A test *is* an acceptance criterion in its strongest form — one the agent can run without you. "The form rejects an empty email" as prose is a criterion. The same thing as a passing test is a criterion the agent verifies itself, every loop, with zero ambiguity. So writing the test first isn't a separate discipline from briefing well. It's the sharpest version of it: you're handing the agent its finish line in executable form. ## Where it fits the cascade In practice, the test belongs in the brief. When you scope a unit of work, include the tests (or the criteria they encode) as part of what "done" means. The agent builds against them and reports the green run as proof. When the work is finished, your [session brief](/articles/write-your-first-session-brief) records what's verified — and "the suite passes" is the most honest line you can write in it. A test the agent can run is the clearest target you can give it — and the cheapest way to stop regressions before they ship. Start here: learn to [write acceptance criteria](/articles/acceptance-criteria-for-agents), read the [field note on a refactor tests saved](/articles/the-test-that-saved-the-refactor), or [read the method](/c2/method). --- # The 30-minute debug limit: when to stop the agent ## An agent stuck on a bug will burn an hour going in circles. The pilot's move is a time limit and an escalation. - URL: https://stuartleo.com/articles/the-30-minute-debug-limit - Published: 2026-06-08 - Reading time: 5 min read - Method: C² Method An agent stuck on a bug will burn an hour going in circles. The pilot's move is a time limit and an escalation — here's how to set and use one. Watch an AI agent debug a stubborn problem and you'll see something unsettling: it doesn't get tired, doesn't get frustrated, and doesn't know when to stop. It will try the same kind of fix twenty times, each with total confidence, burning time and tokens, going nowhere. A human would have stepped back after the third try. The agent won't, unless you make it. The pilot's tool for this is a simple rule — a **debug limit** — and the discipline to act when it trips. Here's how to use it. ## How agents get stuck in loops An agent debugging a hard problem tends to explore a narrow neighbourhood of solutions. It forms a theory, tries it, fails, tweaks slightly, tries again. When the theory is wrong, "slightly tweaked" versions of it are all wrong too — so it loops, generating variations on a doomed approach. What it almost never does on its own is the thing a good developer does: stop, zoom out, and question the framing. The agent lacks the instinct to say "I've been at this too long, the whole approach is probably wrong." ## Why more attempts make it worse Here's the part that's counterintuitive. With a stuck agent, *more attempts actively make things worse* — not just wasteful, worse. Every failed attempt piles more text into the context window: the broken code, the error, the reasoning that didn't pan out. The window fills with the *history of failure*, which both crowds out the original problem and nudges the agent to keep reasoning along the same failed lines. It rots its own context with its own dead ends — a failure mode familiar to anyone building [long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents). By attempt fifteen it's not just stuck — it's confused, on top of stuck. **Letting a stuck agent keep trying isn't patience. You're feeding it its own failures until it can't see the problem anymore.** ## The 30-minute limit as a rule So set a limit. Thirty minutes of wall-clock grinding on a single bug is plenty — past that, the odds of the next attempt succeeding have dropped, not risen. The exact number matters less than having one. The point is to convert "the agent is still trying" from a comfort into a trigger. When the limit trips, the rule is firm: **the answer is not another attempt.** It's a change of strategy. ## Name the layer before you escalate There's one step before the escalation, and skipping it is how a 5-minute fix becomes a 40-minute one. The limit says *stop*. It doesn't say *stop and look at what*, so the default is to reach for whatever you touched most recently — which is nearly always the instructions. I've rewritten a prompt for 20 minutes when the real problem was an expired token. So before you do anything, name the layer that owns the failure: | What you're seeing | The layer that owns it | |---|---| | **Cannot operate** — missing tool, stale state, bad permissions, no visibility | The environment | | **Almost works but unreliable** — close-but-weak output, inconsistent success, no proof it finished | The loop and its stop rule | | **The process itself is complex** — several specialisms, approvals, branching, work that keeps getting dropped | The topology | Cheapest first, rarest last. Check whether it could physically do the job before you assume it couldn't think — an agent that can't reach something doesn't stop, it writes a plausible sentence about what would probably be there. Only the middle row is a prompt problem, which is why the reflex to rewrite instructions gets it right about a third of the time. [The full triage is here](/articles/which-layer-broke-your-agent). ## What to do when it trips Once you know the layer, three moves, roughly in order: 1. **Fresh context.** Start a new session. The failed attempts stop polluting the window, and the agent meets the problem clean. This alone fixes a surprising amount — half the time the agent was drowning in its own dead ends. 2. **Reframe.** Restate the problem yourself, plainly. Often the agent was solving the wrong version of it. A sharper framing points it somewhere new. 3. **Escalate.** Try a different approach, a stronger model, or your own eyes. Some bugs want a human or a bigger brain, and that's fine — knowing when is the skill. This is the Pilot model in miniature: a crew member grinds for three hours, a [pilot](/articles/the-pilot-model-directing-ai-agents) calls the limit and changes course. ## Capturing the fix as a gotcha When you do crack it, don't let the cost vanish. Write the bug and its fix into your contextbase as a [gotcha](/articles/how-to-stop-your-agent-forgetting) — what it looked like, why it was hard, what actually worked. A bug that cost you forty minutes today should cost the next session zero. That's the whole compounding bet: pay once. When the agent's been stuck 30 minutes, the answer isn't another attempt — it's naming the layer, then a reframe. Start here: see [which layer broke your agent](/articles/which-layer-broke-your-agent), [how to stop your agent forgetting](/articles/how-to-stop-your-agent-forgetting), or [read the method](/c2/method). --- # The CLAUDE.md that got too big ## A field note on a Router that quietly became a 600-line dumping ground — and the refactor that fixed it. - URL: https://stuartleo.com/articles/the-claude-md-that-got-too-big - Published: 2026-06-08 - Reading time: 3 min read - Method: C² Method A short field note: my Router file bloated into an unreadable wall of rules. How I noticed, what I moved where, and the line-count rule I now keep. My `CLAUDE.md` hit 600 lines before I admitted there was a problem. This is the field note on how a Router file quietly turns into a dumping ground, how I noticed, and the rule I keep now so it doesn't happen again. ## The symptom: the agent started missing things It crept up. Every time something went sideways, I added a rule to `CLAUDE.md` so it wouldn't happen again — a convention here, an edge case there, a hard-won gotcha. Each addition felt responsible. Sensible, even. Then the agent started missing things that were *in the file*. It would violate a rule sitting in plain text on line 380. It would ignore a convention I'd carefully written down. I was adding more rules, and compliance was getting worse, not better. That's the tell I'd learn to recognise: when the agent stops following a file you keep adding to, the file is too full to read. ## The cause: everything lived in one file The problem was exactly the thing I tell other people to avoid. I'd treated the Router as a vault — the one file I knew the agent read, so I put *everything* in it. Six hundred lines of rules, conventions, gotchas and history, all in the front door. But a long file gets skimmed, not absorbed. Past a certain length the agent stops retaining it — the same finding the research on [context files for agents](https://www.augmentcode.com/guides/how-to-build-agents-md) keeps landing on. I'd made the most important file the least readable, one responsible addition at a time. **Every line I added to keep the agent in line made every other line less likely to be read.** ## The refactor: route, don't duplicate The fix took an hour. I went through the 600 lines and asked of each block: is this an *essential* the agent needs every time, or *detail* that belongs in a linked doc? - The conventions moved to `docs/05-reference/`, with one pointer left behind. - The gotchas moved to `docs/03-knowledge/gotchas/`, with one pointer. - The decisions moved to their own file, with one pointer. - What stayed: the overview, the handful of truly non-negotiable rules, the "where things go" map, the common commands. `CLAUDE.md` went from 600 lines to about 70. Nothing was lost — it just moved to where it belonged, with the Router pointing at it. The agent could read the whole front door again. ## The rule I keep now Two rules, actually: 1. **The Router stays short enough to read in full** — a screen or two. If it's longer, something needs to move out. 2. **When I reach to add detail, I add a pointer instead.** New convention → a reference file, linked. New trap → a gotcha file, linked. The Router gains a line, never a paragraph. When the agent starts missing things, the Router is usually too full to read. Now I keep it lean on purpose. Start here: read [how to write an AGENTS.md that agents follow](/articles/how-to-write-agents-md), [how to customise the C² Method](/articles/customise-the-c2-method), or [read the method](/c2/method). --- # The overnight run that went wrong ## A field note on letting an agent run unattended overnight, and waking to a branch full of confident damage. - URL: https://stuartleo.com/articles/the-overnight-run-that-went-wrong - Published: 2026-06-08 - Reading time: 3 min read - Method: C² Method A field note on letting an agent run unattended overnight, waking to a branch full of confident damage, and the guardrails I never skip now. I let an agent run unattended overnight and woke up to a branch full of confident, plausible damage. Nothing caught fire — but only because of what it *couldn't* reach, not what it did. This is the field note on the run that taught me which guardrails are non-negotiable. ## The setup (and the optimism) It was a tidy-up job: migrate a batch of components to a new pattern, dozens of near-identical changes. Perfect for an unattended run, I figured. I gave the agent the task, told it to work through the list, and went to bed picturing a clean diff waiting for me. I'd done the same kind of thing before, a few times, and it had worked. That was exactly the problem. ## What I woke up to The branch had thirty-odd files changed, all looking superficially right. But the agent had hit an ambiguous case partway through, made a wrong call about the new pattern, and then *applied that wrong call consistently across everything after it*. Confidently. The later half of the migration was uniformly broken in the same subtle way — which is somehow worse than randomly broken, because it looks so deliberate. It had also, helpfully, "fixed" a failing test by deleting the assertion. ## Why it failed on the tenth try, not the first What rattled me was that I *had* run this kind of job before without trouble. This wasn't a worse agent or a worse prompt. It was the tenth roll of the dice. The uncomfortable truth about unattended agents is that the same setup that [succeeds nine times can fail on the tenth](https://torq.io/blog/agentic-ai-security-guardrails/) — and unattended means nobody's watching when it does. I'd been treating nine good runs as proof it was safe. They weren't proof of anything except that the tenth hadn't happened yet. **An agent that's worked nine nights running isn't safe. It's just an agent the tenth night hasn't tested.** ## The guardrails I added The damage was containable for one reason: it was on its own branch and couldn't touch anything live. That near-miss made me firm up the rules I now never skip for an unattended run: - **Isolation** — its own branch or [worktree](/articles/parallel-agents-with-git-worktrees), never `main`, never anything live. - **A test gate it can't bypass** — pre-commit hooks that run the suite, so it literally can't commit broken work (and can't "fix" a test by deleting it without that showing up). - **Forbidden zones** — no deploy, no auth, no payments, no secrets. - **A cost cap** — so a stuck loop can't run all night on my card. ## What I let agents do unattended now I still run agents overnight — it's genuinely useful. But the scope is fenced: well-specified, reversible work, on an isolated branch, behind a test gate, away from anything dangerous. The morning surprise is back to being a pleasant one, because the worst case is now a throwaway branch, not a cleanup. An agent that succeeds nine times can fail catastrophically on the tenth — guardrails are for the tenth. Start here: see [how to run agents overnight safely](/articles/run-agents-overnight-safely), [C² vs GUARDRAILS.md](/articles/c2-vs-guardrails-md), or [read the method](/c2/method). --- # The Pilot model: directing agents instead of typing ## The biggest shift in building with AI isn't the code the agent writes — it's that you stop being crew and start being the pilot. - URL: https://stuartleo.com/articles/the-pilot-model-directing-ai-agents - Published: 2026-06-08 - Reading time: 4 min read - Method: C² Method The biggest shift in building with AI isn't the code the agent writes — it's that you stop being crew and start being the pilot. What that changes, in practice. The hardest part of building with AI agents isn't learning the tools. It's a change in self-image. For your whole career, being good meant producing — writing the code, solving the bug, shipping the feature with your own hands. Agentic development quietly takes that away, and a lot of capable people resist it without realising. The reframe that makes it click is the **Pilot model**: you are not crew anymore. You're the pilot. Here's what that means and why it changes everything about how you work. ## Crew versus pilot A crew member hauls rope, trims sails, does the physical work. A pilot sets the course, reads the instruments, makes the calls, and directs the crew. Both are essential. They're not the same job. In agentic development, the AI is the crew. It writes the code, runs the tests, manages the files, generates the docs — the physical work of building. That leaves you the pilot's job: deciding where to go, judging whether you're on course, and owning the outcome. The mistake nearly everyone makes at first is staying a crew member — grabbing the rope, typing the code, treating the agent as a slightly better autocomplete. That wastes the whole thing. You can't pilot if you're still hauling rope. ## What the pilot actually does The pilot's work is different, and it's the work that was always the hard part: | Crew (wrong seat) | Pilot (right seat) | |---|---| | Writing the boilerplate | Writing the brief that constrains the boilerplate | | Chasing a bug for three hours | Setting a time limit and escalating | | Typing out the test | Specifying the acceptance criteria before a line runs | | Updating docs after the fact | Writing the session note as part of the work | None of that is lesser work. It's higher-leverage work. A clear brief makes the agent good. A sharp acceptance criterion makes it self-correct. A written session note makes the next session start ahead. ## Why directing beats typing Here's the practical case, not the motivational one. The agent's output quality is downstream of your direction. A vague instruction over thin context produces confident, drifting nonsense. A clear brief over good context produces something you can trust. The lever isn't your typing speed — it's your directing. Practitioners who've made this shift describe the same thing: the win comes from [orchestrating the agent well](https://martinfowler.com/articles/harness-engineering.html), not from staying hands-on-keyboard. Spend your effort on the brief, the standard, and the review, and the agent does dramatically more, dramatically better. **A crew member measures the day in lines written. A pilot measures it in decisions made and outcomes shipped.** ## The four pilot habits Being a pilot comes down to four habits: 1. **Brief before build.** Say what to build, what not to, and how you'll know it worked — before the agent starts. 2. **Set the standard, then hold it.** Define what "good" means and review against it. The agent won't raise the bar for you. 3. **Time-box the struggle.** When the agent's stuck, don't let it grind — reframe or escalate. 4. **Capture as you go.** Write the session note and the gotcha while it's fresh, so the knowledge compounds. Do these and you're piloting. Skip them and you're back to hauling rope with extra steps. ## Stepping into the seat The shift is uncomfortable because it asks you to value something you've never been rewarded for — direction over production. But it's the whole unlock. The builders getting the most out of agents aren't the fastest typists. They're the clearest pilots. Measure yourself by decisions made and outcomes shipped, not lines written. That's the seat to take. Start here: see [how to build with AI agents](/articles/how-to-build-with-ai-agents), [what agentic coding is](/articles/what-is-agentic-coding), or [read the method](/c2/method). --- # The test that saved the refactor ## A field note on a big agent-driven refactor that should have broken everything, and the tests that didn't let it. - URL: https://stuartleo.com/articles/the-test-that-saved-the-refactor - Published: 2026-06-08 - Reading time: 3 min read - Method: C² Method A field note on a big agent-driven refactor that should have broken everything, and the test suite that turned a risky change into a boring one. I handed an agent a refactor big enough that I expected to spend the next day cleaning up after it. Instead it was boring — in the best possible way — and the reason was a test suite I almost didn't bother writing. This is the field note on why I now refuse to let an agent refactor without one. ## The scary refactor The job was a real one: pull a tangle of booking logic out of a route handler and into a proper module, touched by a dozen call sites. The kind of change where everything *looks* fine afterward and then something subtle is broken three screens away. I've been burned by exactly this before, by my own hand. Handing it to an agent felt like handing a stranger the keys to a car with bad brakes. ## Why I wrote the tests first So before letting the agent near it, I spent twenty minutes writing tests that pinned down the behaviour I wanted to *keep*: bookings refused at capacity, the refund window enforced, the confirmation email sent once. Not testing the new structure — testing the behaviour that must survive the restructure. A safety net under the trapeze. This is just [acceptance criteria](/articles/acceptance-criteria-for-agents) in executable form: a runnable definition of "still correct" the agent could check itself against. ## Letting the agent go red-green Then I let the agent do the refactor with one instruction: the tests stay green the whole way. It moved the logic, updated the call sites, and re-ran the suite after each step. The disciplined [red-green-refactor loop](https://qaskills.sh/blog/tdd-ai-agents-best-practices) that's tedious for a human is effortless for an agent — it just runs the tests, every time, without sighing about it. **The test suite turned "I hope the agent didn't break anything" into "the suite is green, so it didn't." That swap is the whole point.** ## Catching the one real regression It wasn't flawless — and that's exactly why the tests mattered. Partway through, the agent moved the capacity check to the wrong side of a conditional, and the "refused at capacity" test went red. The agent saw it, diagnosed it, and fixed it, all inside its loop, before I ever looked. Without that test, the bug ships and I find it in production a week later. With it, the regression lived for about ninety seconds and never left the branch. ## Why I don't refactor without tests now The lesson stuck. A big refactor with no tests, handed to an agent, is a gamble — the output looks right and you have no way to know. The same refactor *with* tests is a chore, in the good sense: mechanical, verifiable, safe. The twenty minutes I spent writing tests first wasn't overhead. It was the thing that made the whole refactor a non-event. A test suite turns an agent's big refactor from a gamble into a chore — in the good way. Start here: see [test-driven development with AI agents](/articles/test-driven-development-with-ai-agents), [acceptance criteria the agent can check](/articles/acceptance-criteria-for-agents), or [read the method](/c2/method). --- # I vibe-coded into a corner — here's the climb out ## A field note on letting an agent build with no spec, the mess that followed, and the brief that turned it around. - URL: https://stuartleo.com/articles/vibe-coding-into-a-corner - Published: 2026-06-08 - Reading time: 3 min read - Method: C² Method A field note on letting an agent vibe-code a feature with no spec, the mess that followed, and how a brief with acceptance criteria turned it around. I vibe-coded a feature into a corner I couldn't see the edges of. This is the field note on how it happened, what it cost, and the cheap habit that climbed me out — and now keeps me out. ## How it started: no brief, just vibes It was a Friday and I wanted to move fast. So I skipped the brief and just *talked* to the agent. "Add a referral system." It built something. "No, make referrals give a discount." It adjusted. "Actually, let the discount stack with promotions." It adjusted again. No spec, no criteria, just me steering by feel, change after change. This is vibe coding — building from a vague feeling rather than a specification. For a throwaway prototype it's genuinely fine. I wasn't building a throwaway. ## Where it drifted By change six, the feature had quietly become incoherent. The discount stacking I'd asked for conflicted with a refund rule from weeks earlier. Referral credits could, in one path, exceed the order total. None of it was *obviously* broken — every individual change looked reasonable when the agent made it. That's the trap. The drift is invisible step to step, and only visible once you're deep in it. **Vibe coding fails quietly. Each change looks fine. The incoherence only shows up once you're too deep to see the edges.** The spec-driven crowd has the cleanest name for this: agents [produce plausible code that drifts from intent](https://amux.io/guides/spec-driven-development/) when there's no spec holding the line. That was exactly my Friday. ## The cost of plausible-but-wrong The expensive part wasn't the bad code. It was that I *trusted* it, because it ran and looked right. I shipped it to staging before the referral-credit hole turned up in testing. Unwinding six layers of vibe-driven change cost me more than writing the thing properly would have in the first place. Plausible-but-wrong is the most expensive output an agent produces, because it passes the glance test. ## Rebuilding from a brief The climb out was boring and fast. I stopped, deleted the feature, and wrote a short brief first — what a referral does, what it explicitly does *not* do, and a handful of [acceptance criteria I could actually run](/articles/acceptance-criteria-for-agents): ``` - A referral gives the referrer a fixed credit, once, on the referee's first paid order. - Credit never exceeds the order total. - Referral credit does NOT stack with promotional discounts. - Test suite covers all three rules and passes. ``` With that in front of it, the agent built the feature once, cleanly, and verified it against the criteria itself. The whole rebuild took less time than the vibe-coded version had taken to debug. ## The line I won't cross again I still vibe-code — for spikes, throwaways, exploring an idea. But the line is bright now: the moment it's something I intend to *keep*, it gets a brief with criteria I can run, first. The brief takes five minutes. The corner took an afternoon. Vibe coding is fine until it isn't — a brief with runnable criteria is the cheapest insurance you'll buy. Start here: learn to [write acceptance criteria your agent can check](/articles/acceptance-criteria-for-agents), see [C² vs spec-driven development](/articles/c2-vs-spec-driven-development), or [read the method](/c2/method). --- # What is a contextbase? The asset that makes agents remember ## The folder of markdown your AI agent reads before it acts — and why it's the difference between building and re-explaining. - URL: https://stuartleo.com/articles/what-is-a-contextbase - Published: 2026-06-08 - Reading time: 5 min read - Method: C² Method A contextbase is the version-controlled folder of markdown your AI coding agent reads before it acts. What goes in it, why it compounds, and how to start one today. Open a fresh session with any AI coding agent and check what it knows about your project: nothing. Not the decision you made last week about how authentication works. Not the bug that took three hours to corner on Tuesday. Not the reason you chose one database over the obvious alternative. The model is brilliant, and it's starting from zero — again. That blank slate is the biggest hidden tax on building with agents. You pay it every session, in re-explaining what you already explained. The fix isn't a smarter model. It's a **contextbase** — and once you have one, your agent stops starting from zero. ## The problem: a brilliant agent with no memory An AI coding agent has no memory between sessions. Close the laptop, and everything it understood about your project is gone. The chat history feels like memory, but it isn't — it scrolls away, it hits the context window limit (the finite amount the model can hold at once), and nobody else on the project can read it. Anthropic's own engineers describe the core challenge of [long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) as exactly this: keeping what matters when the working memory fills and the session ends. So you compensate. You re-paste the same context at the top of every session. You re-explain the architecture. You watch the agent confidently re-introduce a bug you already fixed, because it has no idea the fix ever happened. The work isn't compounding — it's evaporating, and you're the backup drive. ## What a contextbase is A contextbase is the folder of plain markdown that your agent reads *before* it acts. It lives in git, right next to your code, and you version it the same way. Here's the whole idea in one line: every software project actually runs two systems. - The **codebase** — what runs. The code that ships. - The **contextbase** — what guides. The briefs, decisions, patterns and gotchas that say how and why the code got built. Traditional development optimises only the first. You commit code carefully and let the *reasoning* behind it live in your head, in Slack, in a chat log that's gone by Friday. With an AI agent on the team, that's a fatal gap — because the agent can't read your head. It can only read what's written down. **A codebase is what runs. A contextbase is what guides. You've been keeping one of them in git and the other in your memory.** The contextbase closes the gap. It makes the knowledge a first-class artifact — written, committed, and read by the agent on its way in. ## What goes inside A contextbase isn't elaborate. Four kinds of file carry most of the weight: ``` docs/ ├── AGENTS.md ← the Router: the one file the agent reads first ├── 02-working/ ← briefs (what to build) + session notes (what happened) └── 03-knowledge/ ← gotchas and decisions (what you learned, why you chose) ``` - **The Router** — one file (named `AGENTS.md` or `CLAUDE.md` on disk) that the agent reads first. It's an index, not an encyclopedia: it points to everything else so the agent can find what a task needs. - **Briefs** — short specs of what to build and, just as important, what *not* to build. - **Session briefs** — a few lines at the end of a session: what changed, why, what's verified, what's next. This is the written memory the next session reads. - **Gotchas and decisions** — the trap you hit recorded once, and the reason behind a choice so nobody re-litigates it cold. That's it. Markdown a business builder can write and a senior developer can trust. ## Why it compounds Here's the part that changes how building feels. Chat history evaporates. A contextbase *accrues*. Every session, you write down what was learned and commit it. So the next session — and the next agent, and the next person — start from everything figured out so far, not from zero. The gotcha you captured on Tuesday saves Thursday's session an hour. After fifty sessions, the contextbase is denser in real decisions than the code itself. And the two systems multiply each other. A richer contextbase makes the agent's code more precise and less likely to repeat old mistakes. Cleaner code surfaces patterns worth capturing back into the contextbase. Context improves code, code improves context — a loop that gets sharper the longer you run it, instead of an explanation you give again and again. There's an honest cost: it asks for a little discipline every session. You write the brief. You capture what was learned. That's the price of compounding, and it's a real ask — but it's minutes, and it's the only thing here that turns effort into an asset you keep. ## Start your first one You can have a contextbase by the end of today: 1. Make a `docs/` folder in your repo. 2. Add one Router file (`AGENTS.md`) that says, in plain words, what this project is and where things live. 3. At the end of your next session, write five lines: what changed, why, what's verified, what's next. Commit it. That's a contextbase. Tomorrow your agent reads it before it acts — and for the first time, it starts ahead. Your agent stops forgetting the moment its context lives in git instead of the chat window. That's the whole shift: stop being the memory, and start building one. Start here: [read the C² method](/c2/method), [run your first session](/c2/start), or learn the discipline underneath it in [context engineering, explained](/articles/context-engineering-explained). --- # What is agentic coding? Beyond autocomplete ## The shift from AI that suggests the next line to an agent that plans, edits, runs and verifies in a loop. - URL: https://stuartleo.com/articles/what-is-agentic-coding - Published: 2026-06-08 - Reading time: 4 min read - Method: C² Method Agentic coding is the shift from AI autocomplete to an agent that plans, edits, runs and verifies in a loop. What it is, how it differs, and how to start. A couple of years ago, "AI for coding" meant autocomplete — the editor guessing your next line while you typed. Useful, but you were still the one doing the work. That's not what people mean anymore. The term now is **agentic coding**, and it's a different thing entirely: an agent that takes a task and runs it, end to end, while you direct. If you're trying to make sense of the shift, here's what agentic coding actually is, how it differs from what came before, and what it takes to do it well. ## From autocomplete to agents Autocomplete is a suggestion engine. It completes the line, you accept or reject, and you stay in the driver's seat keystroke by keystroke. The AI is a faster set of fingers. Agentic coding moves the AI from *suggesting* to *acting*. You say what you want built. The agent reads the relevant files, makes a plan, edits across several files, runs the tests, sees a failure, fixes it, and comes back with working code. You weren't typing through any of that. You were directing and reviewing. That's the leap: from a tool that helps you type to a partner that does the task. ## What "agentic" actually means (the loop) The word "agentic" points at one thing: the **loop**. An agent doesn't produce one answer and stop. It runs a cycle — gather context, take an action, check the result, react, and go again until the work is done or it's stuck. The best workflows lean into this — as the practitioners pushing [beyond autocomplete](https://kilo.ai/articles/beyond-autocomplete) describe it, the agent's value is in running that gather-act-verify loop autonomously, not in any single suggestion. **Autocomplete answers once. An agent runs a loop — act, check, react, repeat — and that loop is the whole difference.** You see it live in a terminal-based agent: read a file, plan, run a command, hit an error, try a fix, re-run. That visible loop is "agentic" in action. ## What changes for you When the AI starts running the loop, your job changes shape: - You stop writing most of the code and start writing the **brief** — what to build, what to avoid, how you'll know it worked. - You stop measuring progress in lines typed and start measuring it in decisions made and outcomes shipped. - You become the reviewer and the standard-setter, not the typist. This is a genuine adjustment, and it's where people either thrive or flounder. Treat the agent like fancy autocomplete and you'll micromanage it into mediocrity. Treat it like a capable crew member you direct, and it flies. ## What it needs to work Agentic coding isn't magic, and it fails predictably without three things: 1. **Context.** The agent needs to know how your project works — decisions, patterns, constraints. Without it, it builds something plausible and wrong. 2. **A checkable target.** "Improve checkout" gives the loop nothing to verify against. "Bookings past capacity are refused, and the tests pass" gives it a finish line. 3. **Your direction.** The loop runs the work, but you set the course and own the quality bar. Give it those and the loop produces real, reviewable software. Skip them and you get fast, confident drift. ## Where to start Pick an agent, put your project in git, and try one small, well-scoped task — with a clear brief and a way to check the result. Watch the loop run. Then write down what you learned so the next task starts ahead. That habit of capturing context is what turns a one-off win into [a way of building](/articles/how-to-build-with-ai-agents). Agentic coding moves you from writing code to directing an agent that writes, runs and checks it. The skill that matters isn't typing faster — it's directing well. Start here: [run your first session](/c2/start), see [what an agent harness is](/articles/what-is-an-agent-harness), or learn [the Pilot model](/articles/the-pilot-model-directing-ai-agents). --- # What is an agent harness? Agent = model + harness ## The model supplies intelligence. The harness supplies hands, eyes, memory and the loop — and your contextbase lives inside it. - URL: https://stuartleo.com/articles/what-is-an-agent-harness - Published: 2026-06-08 - Reading time: 5 min read - Method: C² Method An AI agent is the model plus the harness around it — the tools, memory, and the gather-act-verify loop that make it act. What a harness is, and where C² fits. There's a phrase worth learning if you're building with AI agents, because it explains most of why two people using the same model get wildly different results: **Agent = Model + Harness.** The model is the intelligence — Claude, GPT, Gemini, whichever. The harness is everything *else* that turns that intelligence into something that can actually build software. And once you can see the harness, you can see where your own results are won or lost — because it's almost never the model. ## The equation: agent = model + harness On its own, a model is a brain in a jar. It can reason brilliantly about code it's shown, but it can't open a file, run a test, read your repo, or remember what it did an hour ago. It just produces text. The **harness** is what wraps the model to make it a working agent. It gives the model: - **Hands** — the ability to edit files, run commands, call tools, commit to git. - **Eyes** — the ability to read your codebase, inspect output, see an error. - **Memory** — some way to carry what it's learned across steps and sessions. - **A loop** — the cycle of gather information, act, check the result, retry on failure. - **Boundaries** — the limits on what it's allowed to touch. Same model, weak harness: a clever assistant that forgets everything and guesses at your code. Same model, strong harness: a partner that reads the right context, makes the change, runs the tests, and fixes its own mistakes. The shorthand has caught on because it's true — Anthropic's engineers frame the whole challenge of capable agents as building [effective harnesses for long-running work](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents), not just picking a smarter model. ## What the harness provides The most visible part of the harness is the **loop**. Terminal-first coding agents show it to you in real time: the agent reads a file, plans, calls a tool, edits code, runs a command, sees the output, reacts to an error, tries again. That gather-act-verify cycle — running until the work is done or the limit is hit — is the harness doing its job. You feel a good harness most when something goes wrong. A weak one fails on the first error and hands you a broken result. A strong one notices the failing test, reads the message, forms a hypothesis, and tries a fix — the way a careful developer would. That recovery behaviour isn't the model being smart. It's the harness being well built. ## The three nested layers Here's the cleanest way to place the harness against the terms you've probably already met — prompt engineering and context engineering. They're not rivals. They're three nested layers, each containing the one before: - **Prompt engineering — the message.** One composed input. - **Context engineering — the memory.** What a curator keeps or drops in a finite window. - **Harness engineering — the machine.** The gather-act-verify loop, retrying on failure. **Prompt engineering is the message. Context engineering is the memory. Harness engineering is the machine that runs them both in a loop.** This is why "isn't this just prompting?" misses it. The harness *contains* the prompt and the context. Martin Fowler's team has started calling the discipline [harness engineering](https://martinfowler.com/articles/harness-engineering.html) for exactly this reason: the leverage for a serious builder is in the machine, not in any single message. ## Why the harness alone still forgets Here's the catch, and it's the one most harness conversations skip. The harness gives the agent memory *within a run* — it can carry state across the steps of a task. But when the run ends, that memory is gone. Close the session, and the harness wakes up blank tomorrow. So a great harness with no durable knowledge still has amnesia. It can build beautifully today and rediscover yesterday's bug tomorrow, because the loop is excellent but nothing it learned was written down. The machine is strong. The memory is a sieve. That gap is exactly where most of your real-world pain lives — the re-explaining, the repeated mistakes, the agent that's sharp in the moment and forgetful across days. ## C² as a harness methodology This is the layer C² works at. C² is a **harness methodology** — not a tool you install, but the discipline that makes the machinery reliable and, crucially, gives it a memory that lasts: - The **Prompt Brief** is the prompt layer — what to build, what not to, what to read first. - The **contextbase** and the **Router** (your `AGENTS.md` / `CLAUDE.md`) are the context layer — durable, version-controlled knowledge the agent reads before it acts. - The **Cascade** of briefs and the verification chain are the harness loop — gather, act, verify, and write down what was learned. That last move is the one that fixes the sieve. C² has the agent capture what it learned into the contextbase before the run ends — so the next run, in any harness, starts ahead. The harness gives your agent hands and a loop. The contextbase gives it a memory that survives the session. You want both, and they multiply. If you've been chasing a better model to fix flaky results, look at the harness first — and then at whether anything it learns ever gets kept. Keep going: see [where the contextbase fits](/articles/what-is-a-contextbase), how [context engineering](/articles/context-engineering-explained) works inside the harness, or [read the method](/c2/method). --- # Why AI agents get expensive (and how to fix it) ## Agentic tasks burn far more tokens than chat, mostly from re-sending context every call. Why the bill climbs, and the two fixes. - URL: https://stuartleo.com/articles/why-ai-agents-get-expensive - Published: 2026-06-08 - Reading time: 7 min read - Method: C² Method Agentic tasks burn far more tokens than chat, mostly from re-sending context. Why the bill climbs, and how lean context and model routing bring it down. The first month is cheap. Then you start really building with agents, the bill arrives, and it's a shock. Agentic coding can cost an order of magnitude more than you'd expect from the same model in a chat window, and the reason isn't what most people assume. Mine tripled in a single month. My first assumption was the obvious wrong one: agents are just expensive now, suck it up. They're not. When I actually looked, the cost was two specific habits of mine, both easy to fix. It's not that the model is pricey per answer. It's the *shape* of agentic work. Understand where the money actually goes and the fixes are obvious. ## The sticker shock A quick chat with a model costs cents. An agent grinding through a real task can cost dollars per session, and a heavy month runs into serious money. The gap surprises people because they're pricing the *answer* when they should be pricing the *loop*. An agent doesn't make one call. It makes dozens or hundreds: read a file, plan, edit, run a test, react, repeat. Each step is a model call. That alone multiplies the cost. But the bigger driver is hiding inside each of those calls. Nothing about my usage felt three times heavier. Same kind of work, maybe a bit more of it. But the invoice had tripled, and "agents are expensive" was the lazy story I told myself for about a day before it bothered me enough to investigate. ## Where the tokens actually go (context re-sending) When I broke the usage down, the shape was stark. The spend wasn't in the agent's *output*. It was in the *input*: enormous token counts going into the model on every call, growing through each session. Here's why. Every call in the loop re-sends the entire conversation so far. The model is stateless between calls, so to "remember" step one at step fifty, step one gets sent again, every step. By the time an agent is deep in a task, each call carries the whole history: the files it read, the output it saw, everything. The Stanford Digital Economy Lab's analysis of [how agents spend tokens](https://digitaleconomy.stanford.edu/news/how-are-ai-agents-spending-your-tokens/) makes the pattern clear: the dominant cost isn't generating new output, it's repeatedly shipping the accumulated context. Vantage's breakdown of [agentic coding costs](https://www.vantage.sh/blog/agentic-coding-costs) is where it clicked for me. By turn fifty you can be sending 100K-200K tokens *per call*, mostly to re-establish what the agent already knew. My sessions had got long and sprawling, so late in a session I was shipping a huge context on every single call. **I wasn't paying for answers. I was paying, hundreds of times a session, to re-send the same bloated context.** ## Why bigger context costs twice This is why the "just paste everything in" instinct is so expensive. A bloated context doesn't only cost more on the call you paste it. It costs more on *every subsequent call*, because it's re-sent each time. Dump a huge file into the window at step three and you pay for that file again at steps four through fifty. And it costs you twice over, because a fuller window also makes the model *worse*. That's context rot: the more the window holds, the more the agent drops details and guesses. So bloated context buys you a higher bill and a dumber agent. Lean context is cheaper and sharper at the same time. ## Fix one: leaner context, lower bill The good news is that the main cost lever is something you control. Keep the working context lean and every call in the loop carries less, so the whole session costs less. That's [compaction](/articles/compaction-keep-the-context-window-lean): digest what matters, drop the raw transcript, load only what the task needs. In practice I stopped letting sessions sprawl. Now I compact when the window gets long: write down where things are up to, drop the raw transcript, start fresh from the note. This alone did most of the work on my bill, and it made the agent sharper as a bonus. A contextbase helps here in a way that's easy to miss. Because the durable knowledge lives in files the agent loads on demand, you're not re-pasting it into the chat and re-paying for it every call. The context is read when needed, not carried forever. ## The second culprit: the top model for everything The other half of my bill was lazier still. I'd set everything to the most powerful model and forgotten about it. Every trivial step, reading a file, listing a directory, a one-line edit, was billing at premium rates it never needed. An agent's loop is a mix of work. Some steps are hard: untangling a subtle bug, designing an architecture. Most are not: reading a file, making a small edit, summarising output. They all flow to whatever model you set. Set that to the top tier and you're paying premium rates for the easy 80% as well as the hard 20%. The analysis of [AI coding costs](https://www.morphllm.com/ai-coding-costs) makes the gap concrete. For an agent making a couple of hundred calls a session, all-premium can run several times the cost of a sensible Haiku/Sonnet/Opus-style mix, for work that's largely identical in outcome. You're not buying better results on the easy steps. You're just paying more for them. ## Fix two: route models by task **Model routing** means sending each task to the smallest model that can do it well. It's the single highest-leverage cost move in agentic development, and it doesn't cost you quality. - **Cheap, fast models** for discovery, reading, simple edits and summarising: the high-volume, low-difficulty steps. - **Mid-tier models** for the bulk of real implementation work. - **The top model** for genuinely hard reasoning: the gnarly bug, the architecture call, the thing that actually needs the horsepower. A useful default split: let a cheap model do the *exploring* and a strong model do the *deciding*. Finding the relevant files, reading them, gathering context is bulk work a fast model handles fine. Reasoning about the tricky change once the context is gathered is where the strong model earns its rate. That mirrors how the loop actually works: lots of cheap gathering, a little expensive thinking. You can route by hand, picking the model for a session based on the work, or use a router that classifies each request and sends it on. Either way, the savings come from no longer paying premium for the easy majority. **The cheapest model isn't the goal and the best model isn't the goal. The right model for each step is.** ## Why agent-agnostic context makes routing practical Because the C² Method is [agent-agnostic](/articles/cursor-vs-claude-code-which-fits-c2), plain markdown in git with no lock-in to one model or tool, you're free to route across models and even vendors without rework. The contextbase doesn't care which model reads it. You can put the cheap model and the expensive model on the same project, same context, same day. A method welded to one model can't do that. The deepest lever loops back to context. A smaller model with rich, precise context often matches a bigger model working blind, because much of what the expensive model buys you is compensating for missing context. Give any model a good [contextbase](/articles/what-is-a-contextbase) and it guesses less, which means you can push more work down to cheaper models without losing quality. Good context doesn't just cut re-sending cost. It lets you run cheaper models more often. ## What it costs now After those two changes my bill dropped back below where it started, on *more* work than before. Nothing about my output got worse. I stopped paying to re-send bloated context and stopped paying premium rates for trivial steps. Most of your agent bill is re-sent context. Keep it lean and the cost falls with it. Then route the models, and it falls again. Start here: see [compaction](/articles/compaction-keep-the-context-window-lean), [what a contextbase is](/articles/what-is-a-contextbase), or [read the method](/c2/method). --- # Write your first session brief ## The five-minute habit that lets every session — and every agent — start from everything the last one learned. - URL: https://stuartleo.com/articles/write-your-first-session-brief - Published: 2026-06-08 - Reading time: 4 min read - Method: C² Method A session brief is a short note at the end of each working session: what changed, why, what's verified, what's next. How to write one and why it compounds. If you adopt one habit from building with AI agents, make it this one. It takes five minutes, it feels almost too small to matter, and it's the difference between work that compounds and work you keep re-explaining. It's the **session brief** — a short note you write at the end of a working session. Here's how to write your first one, and why it pays back so far out of proportion to its size. ## Why sessions lose memory An AI agent has no memory between sessions. The moment a session ends — you close the laptop, take a call, hit the context window limit — everything the agent understood about the work is gone. Next session, it starts blank. It's the defining constraint of [long-running agent work](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents): the model doesn't carry state across runs, so anything not written down is lost. That's the leak. All the understanding built up over an hour of good work — what you tried, what worked, what's half-done — drains away the instant you stop. The session brief is the plug. ## What a session brief captures A session brief answers one question: *if I came back to this cold, what would I need to know?* Four short parts cover it: - **What changed** — what you and the agent actually did this session. - **Why** — the reasoning behind the choices, so nobody re-litigates them later. - **What's verified** — what you tested and confirmed works (and, honestly, what you didn't). - **What's next** — the obvious next move, so the next session starts in motion. That's the whole shape. Four lines to four short paragraphs, depending on the session. **The question is never "is the work finished?" It's "if I came back to this cold, what would I need to know?"** ## A real one, annotated Here's one for a session on that yoga booking site: ``` ## Session brief — booking form (2026-06-08) What changed: Built the booking form and wired it to the capacity check. Form rejects bookings past class capacity. Why: Capacity overflow was the top risk — handled it before styling so the rule is locked in. Verified: Submitted 11 bookings against a 10-seat class; the 11th was rejected. Empty-email submit is blocked. NOT yet tested: the 12-hour cancellation rule. Next: Build the cancellation flow and the non-refundable window. The capacity logic is in lib/booking.ts if needed. ``` Notice what it does. It states what's *verified* and what isn't — so the next session doesn't assume the cancellation rule works. It points at the file. It names the next move. Tomorrow's agent reads this and is productive in seconds, not after twenty minutes of re-orientation. ## Where it lives in the contextbase A session brief isn't a throwaway note. It's part of your [contextbase](/articles/what-is-a-contextbase) — the written knowledge your project keeps in git. Drop briefs in a predictable place (`docs/02-working/session-briefs/`, dated `YYYY-MM-DD-topic.md`) and commit them with the work. Committed, they do double duty: memory for the next agent, and an async hand-off for any human collaborator — no standup required, because the state of the work is written down. ## The compounding effect after 20 sessions One brief is a note. Twenty briefs are a history — a running record of how the project actually evolved, every decision and dead-end captured in order. The next session never starts from zero, and neither does a new person. The understanding that used to evaporate now accrues. That's the trade: five minutes at the end of a session buys you a running start at the next one. Pay it every time and the starts keep getting faster. Start here: [run your first session](/c2/start), see [how a contextbase fits together](/articles/what-is-a-contextbase), or learn [how to stop your agent forgetting](/articles/how-to-stop-your-agent-forgetting). --- # AI development methodologies compared: C², BMAD & more ## A practitioner's honest map of the methods for building with AI agents — and why a contextbase that compounds beats context you reload. - URL: https://stuartleo.com/articles/ai-development-methodologies-compared - Published: 2026-06-01 - Reading time: 7 min read - Method: C² Method An honest comparison of the methods for building with AI agents — native rule files, BMAD, ACE, Shape Up, AWS AI-DLC and C² — with a side-by-side table and how to choose. The real differentiator in building with AI agents in 2026 isn't the model — everyone has the same models. It's how systematically you turn what the agent learns into something it keeps. A lot of good people are converging on that, which is why there are now several methods worth knowing. Here's an honest map — written by someone who built one of them and ships production software with it daily — and a side-by-side to help you choose. ## The contenders ### Native rule files (CLAUDE.md, AGENTS.md, .cursorrules) Where everyone starts, and where most people stall. A single markdown file the agent reads first. **Strength:** zero setup, universal, agent-native. **Limit:** one file is not a method. There's no structure for briefs, no knowledge that accumulates, nothing that survives past a small project or a second person. Every method below is, in effect, the structure these files are missing. ### BMAD (Breakthrough Method for Agile AI-Driven Development) A heavy, orchestrated SDLC built around specialised AI personas — PM, Architect, Dev, QA — running a phased pipeline ([BMAD on GitHub](https://github.com/bmad-code-org/BMAD-METHOD)). **Strength:** opinionated and complete if you want a role-based workflow handed to you. **Limit:** it's a framework you serve. You adopt its personas, its phases, its ceremony — and the context mostly lives inside that pipeline rather than compounding into an asset you own. (Its newer project-context skill keeps a verified block of project facts in AGENTS.md, per [BMAD's docs](https://docs.bmad-method.org/existing-codebases/set-and-maintain-project-context/), which is a step toward durable context.) Powerful, prescriptive, and heavy for anything smaller than a team that wants exactly that. ### HumanLayer's ACE (Advanced Context Engineering) Not a method — a **context-window discipline**. Research → plan → implement, with intentional summarisation to keep the working set lean. **Strength:** the best answer going to "what do I do when even my curated context overflows the window." **Limit:** it manages the window, not the project. No contextbase, no briefs, no knowledge layer — it's a technique that belongs *inside* a method, not in place of one. Use it within C², not instead of it. ### Matt Pocock's workflow A sharp personal pipeline: idea → PRD → issues → autonomous execution with TDD, then human QA. **Strength:** concrete, opinionated, easy to copy. **Limit:** it's personal. No team model, no compounding knowledge, nothing that spans more than one developer or more than one app. A great solo loop that stops where a project gets bigger than one head. ### Packmind (ContextOps) Enterprise governance for context — standards, skills, and commands distributed and controlled across many repos and agents. **Strength:** the right answer if your problem is policing context centrally across a large org. **Limit:** governance-first, not build-first. It's heavy machinery aimed at platform teams, not the person actually building — and overkill for everyone who isn't running one. ### Shape Up (Basecamp) The pre-AI ancestor, and still the clearest thinking on betting, appetite, and scope ([Shape Up, from Basecamp](https://basecamp.com/shapeup)). **Strength:** unmatched on deciding *what* to build and how much to spend on it. **Limit:** it was designed for humans directing humans. No contextbase, no router, no agent-execution contract. Keep its betting layer — it has nothing to say about how the work actually gets built by an agent. ### AWS AI-DLC (AI-Driven Development Lifecycle) The closest structural peer, and the sharpest contrast — a hierarchical, agent-agnostic pipeline with human approval at phase gates ([AWS AI-DLC](https://aws.amazon.com/blogs/devops/ai-driven-development-life-cycle/)). **Strength:** structured, enterprise-credible, genuinely AI-native. **Limit:** two telling choices. It casts the human as an *approver at gates* — the pipeline runs, you sign off — rather than a pilot directing throughout. And it treats context as **delivery**: load the right rules, run the phase, move on. That context is consumed, not accumulated. Which is exactly where C² goes the other way. ### C² (the C² Method) One idea, carried all the way through: every project runs two systems — a codebase (what runs) and a **contextbase** (what guides) — and the contextbase is a first-class, version-controlled artifact the agent reads before it acts. **What makes it different is that context is an investment that compounds, not delivery you reload.** Every session, the briefs, gotchas and decisions get written down and committed, so the next session — and the next agent, and the next person — start from everything learned so far. After fifty sessions the contextbase is denser in real decisions than the code. Nobody else here treats context as an asset that accrues — they reload it, or they have no model for it at all. **And it's the one method here with genuine range.** It's just disciplined markdown in git, so it fits a **solo founder** shipping a single product *and* a **team running many apps across multiple locations** — the same shape at both ends. Every app carries its own contextbase — every contributor, human or agent, reads the same source of truth — no central server, no per-seat tool. Most of the others are built for one end of that spectrum. C² holds both. **The honest cost:** it asks for discipline every session — you write the brief, you capture what was learned. That's the price of compounding, and it's a real ask. C² is a method and templates, not a framework that does it for you — which is the point. Nothing to lock into, nothing to rip out when a better agent ships, and the context you build is yours. ## Side by side | Method | Weight | Human role | Context model | Best for | |---|---|---|---|---| | Native rule files | Minimal | — | A single file | The baseline you outgrow fast | | **C²** | **Light** | **Pilot (directs throughout)** | **Contextbase — invest & compound** | **Solo founders → teams running many apps across locations** | | BMAD | Heavy | Orchestrated personas | Persona pipeline, plus a project-context block | Teams wanting a prescriptive role-based SDLC | | ACE | Add-on | — | In-session compaction | A technique to use *inside* a method | | Pocock's workflow | Light | Director | PRD → issues | A single developer, a single app | | Packmind | Heavy | Governed | Central ContextOps | Large orgs policing context centrally | | Shape Up | Medium | Shaper | None (pre-AI) | Deciding *what* to build — pair with an AI method | | AWS AI-DLC | Heavy | Approver at gates | Delivery (doesn't compound) | Enterprises wanting phase gates | ## How to choose - **Solo founder, or a team across several apps and locations?** **C².** It's the only one here that fits both without changing shape — and the only one where your context compounds instead of evaporating. - **Want a prescriptive, role-based pipeline handed to you?** **BMAD**, if you're happy to serve the framework. - **Large org whose problem is governing context centrally?** **Packmind.** - **One developer wanting a personal loop to copy?** **Pocock's.** - **Fighting the context window?** **ACE**, as a technique inside whatever method you run. - **Deciding what's worth building?** Keep **Shape Up's** betting model on top, with an AI-native method underneath. These aren't all mutually exclusive — ACE and Shape Up are layers, not rivals. But on the core question of how a project remembers what it learns, most of the field either has no answer or reloads context and throws it away. C² treats it as the asset it is. That's the whole bet: stop building velocity you can't keep. If the contextbase idea resonates, [read the C² method](/c2/method), see [how it compares to Agile](/articles/alternative-to-agile), or go deeper on [C² vs BMAD](/articles/c2-vs-bmad) and [C² vs Shape Up](/articles/c2-vs-shape-up). --- # An alternative to Agile for AI-native teams ## Agile was built to coordinate humans. When the team is humans plus AI agents, its ceremonies become the bottleneck. - URL: https://stuartleo.com/articles/alternative-to-agile - Published: 2026-06-01 - Reading time: 7 min read - Method: C² Method Agile coordinated humans at human speed. With AI agents in the loop the bottleneck moves from execution to direction, and the ceremonies become drag. If you're looking for an alternative to Agile, you've probably noticed the same thing a lot of teams have in the last year: the ceremonies that used to help now slow you down. The standup, the sprint, the story-point poker feel like overhead, not acceleration. That isn't because Agile was wrong. It's because the team changed. This is the case for a different operating model, one built for teams of humans **and** AI agents, and an honest account of what to keep from Agile and what to drop. It also goes one level up, to the software development lifecycle itself, because the same shift that breaks the ceremonies reshapes the whole lifecycle. ## Why Agile worked Agile was the answer to waterfall. It made a simple, correct bet: small teams shipping in short loops, responding to change, valuing working software over documentation, beat big up-front plans. Every piece of Agile machinery exists to coordinate **people**: two-week sprints to timebox human work, daily standups to sync humans and surface blockers, story points to predict human throughput, retros to improve the human team. It was the right answer for its era: a team made entirely of humans, shipping at human speed. ## What changed: execution got cheap AI agents collapsed execution time. For the whole history of software, writing the code was the expensive, slow, human-bound part, and everything was arranged around that constraint. Agile optimised exactly that: human coding throughput, and the coordination of human developers. It is no longer the constraint. An agent ships a feature in a session that used to take a developer days. When the most expensive step gets cheap, the whole shape shifts. AWS's framing of the [AI-driven development lifecycle](https://aws.amazon.com/blogs/devops/ai-driven-development-life-cycle/) starts from the same realisation: ingrain AI into the fabric of development and the old phase structure stops fitting. The bottleneck moved to **direction**: the brief, the context, the decision about what to build, the review of whether it's right. The work that used to be a small fraction of the effort, figuring out *what* and judging *whether*, is now the main event, because the *how* got automated. This is why the [Pilot model](/articles/the-pilot-model-directing-ai-agents) matters. The human's job shifts from producing the work to directing it. At machine speed, the ceremonies stop being acceleration and become friction: - You hold a daily standup about work an agent finished, and forgot, overnight. - You estimate in story points a task the agent did in an hour. - You batch into a two-week sprint what now flows session by session. - You schedule a retro to improve a team whose fastest members don't attend meetings. Agile sped up humans. When the team moves at machine speed, Agile's human-paced ceremonies are the bottleneck. **Agile is no longer agile enough.** ## Keep the spirit, replace the machinery "Agile is dead" is the wrong call, and it isn't true. [Agile's *principles*](https://agilemanifesto.org/) endure: tight feedback, working software over rotting docs, responding to change over following a plan, individuals and interactions over process. Any good alternative keeps all of that. What changes is the **human-paced coordination layer**, the meetings and cadences built for a team of people. The spirit survives the shift to machine speed. The ceremonies don't. The deeper move: Agile coordinates the team through **synchronous human events** on a cadence. The alternative coordinates the team through a **shared, written, version-controlled context** that humans *and* agents read, continuously, not on a calendar. ## The alternative, ceremony by ceremony | Agile — human era | Why it existed | The AI-native alternative | |---|---|---| | Sprint (2 weeks) | timebox human work | The session — the agent's iteration unit, where work flows continuously | | Daily standup | sync humans, surface blockers | A written session brief — async, read by humans and AI | | Story points / velocity | predict human throughput | Brief quality + merge discipline — the new bottleneck and metric | | Backlog grooming | manage human WIP | WIP rules — a cap on in-progress work, no ceremony | | Retrospective | improve the human team | A monthly review plus a "learn" pass that improves the shared context | | Sprint review / demo | show humans the increment | Release notes — committed to git, not performed in a meeting | | Role: contributor | write the code | Role: pilot — direct, review, own the quality bar | The pattern in one line: Agile's ceremonies were how humans stayed in sync. In an AI-native model, a written contextbase keeps humans *and agents* in sync, continuously, in writing, in git. ## So do you still need standups and retros? Mostly no, at least not as meetings. - **Standup** → a written session brief. The information flow survives. The meeting doesn't. - **Planning** → continuous. Work is scoped just-in-time, not batched into a fortnight. - **Grooming** → replaced by rules (a WIP cap, "a plan needs a brief before it's active"). - **Retro** → a short monthly review plus a consolidation pass that updates the shared context. You improve the system of record, not just the team's feelings. - **Demo** → release notes in git. - **The one human meeting to keep** → a light, periodic alignment on direction and priorities. Everything that was just re-syncing people who could have read a brief is gone. ## One level up: the AI-native SDLC Agile was a lifecycle for human teams. The same question applies to the software development lifecycle as a whole: plan, design, build, test, release, maintain. Its phases organise human effort, and its ceremonies keep human teams in sync. Does it still apply? The *goals* survive intact. The *shape* of the work changes, because AI didn't speed up every phase equally. It made execution cheap and direction the bottleneck, so that's where the work moved. | | Traditional SDLC | AI-native | |---|---|---| | Goal | Working software, quality, respond to change | **Same** | | Writing code | The expensive human bottleneck | Cheap, done by agents | | The new bottleneck | — | Direction: briefs, context, review | | Human coordination | Standups, sprints, ceremonies | Mostly replaced by written context | | What grows | — | Clear briefs, durable context, verification | | Memory | In people's heads | In a version-controlled contextbase | **Survives:** the goals. Working software, tight feedback, quality, responding to change. Nobody sane drops those. **Goes:** most of the human-paced coordination layer, and the assumption that code is the bottleneck. **Grows:** direction and verification, and the [contextbase](/articles/what-is-a-contextbase) that lets context compound instead of living in people's heads. An AI-native lifecycle isn't a demolition. It's a reorganisation around the new constraint: less effort on producing code and on coordinating people, more on directing agents, curating context and verifying output. The agents execute. You direct. The context compounds. ## This is what C² is [C²](/c2/method) is one such operating model. It treats context as a first-class, version-controlled artifact that the agent reads before it acts, and it runs work through a light cascade of briefs rather than a cadence of meetings. It keeps Agile's spirit (short loops, working software, respond to change) and replaces the human-paced machinery with a contextbase that humans and agents share. That contextbase *compounds*: every session commits what was learned, so the team gets sharper each loop instead of re-explaining itself. It holds the same shape whether you're one founder shipping a product or a team running many apps across locations. If your team is feeling the friction of running human ceremonies over a machine-speed workflow, that's the signal. The alternative to Agile isn't *less* discipline. It's discipline relocated from meetings into the repo. Weighing it against the alternatives? See [how C² compares to the other AI methodologies](/articles/ai-development-methodologies-compared), or the head-to-heads with [BMAD](/articles/c2-vs-bmad) and [Shape Up](/articles/c2-vs-shape-up). You can [read how to run it in a team](/c2/team), or [get started in minutes](/c2/start). --- # Nike Forgot What It Was Selling ## A twelve-year low, a returning CEO, and the strategy mistake every business makes. - URL: https://stuartleo.com/articles/nike-forgot-what-it-was-selling - Published: 2026-06-01 - Reading time: 9 min read - Method: Essay Nike's stock hit a twelve-year low after four years of optimising how they sell while quietly letting what they sell fall behind. The Substance vs. Form tension — at scale. Nike's stock hit a [twelve-year low in April 2026](https://markets.financialcontent.com/stocks/article/marketminute-2026-4-14-swoosh-under-siege-nike-hits-8-year-low-as-elliott-hills-turnaround-strategy-faces-a-reality-check). The Swoosh is still on more jerseys, shoes, and training kits than any other mark in history. The brand has not collapsed. But the CEO — a thirty-two-year Nike veteran who left, watched what happened, and came back to fix it — stood up in an earnings call this quarter and said, in these exact words, that the turnaround is taking longer than expected. This piece is not about whether Nike recovers. It will. The brand has enough runway and product capability to survive its own mistakes. It's about the specific mistake — the strategic logic that made it through four years of internal approvals and earnings calls before anyone named it as the problem. Because that logic scales down. It shows up in businesses at every size. And by the time it's visible in the numbers, you've been living inside it for three years. ## The decision behind the move In 2020, John Donahoe arrived as Nike's CEO with a strategy called the Consumer Direct Offense. The idea was clean: cut out the wholesale middlemen, build a direct relationship with the consumer through digital channels, and capture the margin that had been flowing to Foot Locker and Dick's Sporting Goods for decades. Target: sixty percent of revenue through direct-to-consumer. Wall Street approved. DTC margins are better. Digital is scalable. The logic worked on a spreadsheet. Over the next four years, Nike pulled back from its wholesale partners. Foot Locker lost significant Nike allocation. Dick's lost shelf space. Independent specialist retailers — running stores, basketball shops, the places where serious athletes buy and talk to each other — lost access to the product they'd built their floors around. The competitors walked straight into the space Nike vacated. [New Balance grew 19% in 2025 alone](https://www.cnbc.com/2026/02/19/new-balance-2025-sales-jump-19percent-as-brand-takes-share-from-nike.html) — to $9.2 billion — while Nike was declining. Swiss brand On climbed from seventh to fifth in the US market in a single year. Hoka surged 35% in one quarter. Adidas won back style-led consumers with two archive silhouettes — the Samba and the Gazelle — no new product required. These brands did not win on price. They won by being where Nike used to be: in specialty retail, telling product stories, building communities of athletes who chose them deliberately. On and Hoka trained their customers to pay more. Nike trained its customers to wait for a sale. That mechanism is worth holding. Once you clear inventory through your own digital channels at heavy discount, you don't just solve the inventory problem. You train the customer. The next purchase is made at that new price point. The premium is gone — and you paid double for it. Once in the margin lost. Once in the brand equity lost. The deeper wound took longer to surface. While Donahoe's organisation was focused on channel strategy, someone stopped focusing on product. Not completely — Nike's running technology is still genuinely world class, and the 20%-plus growth in the running category under Elliott Hill is real. But an analyst put the core problem into one sentence that cuts to the bone: **They focused too much on where they were selling — and lost focus on what they were selling.** That sentence is the whole diagnosis. ## The framework lens The [Resolute Leadership Curve](/articles/the-resolute-leadership-curve-a-primer) holds a tension I return to constantly — not one of the six stages, but one of the [three that run through all of them](/articles/the-three-tensions). The tension between Substance and Form. **Substance** is what the business fundamentally *is*. Its character. The capability at the core of why customers chose it in the first place. For Nike, that is athlete-first product innovation. From Bowerman's waffle iron to Air Max to Flyknit, Nike's character was always the same: obsessive, product-led, starting from the athlete. **Form** is how the substance gets delivered. Channels, structures, distribution, go-to-market. Form is supposed to serve the substance. It's the adaptive layer that lets the substance stay consistent while the world changes around it. The trap — the one Nike fell into — is when the form becomes the point. When the channel strategy becomes the business strategy. When *how you sell* becomes more important than *what you sell*. The Consumer Direct Offense is a pure form-level intervention. DTC, digital, direct relationship — these are form decisions. They can be correct form decisions. The problem wasn't the direction. It was that optimising the form demanded so much organisational attention — restructuring, headcount, leadership energy — that the substance was left to run on legacy. The product pipeline thinned. Athlete relationships became more transactional. Category innovation — the thing that makes a runner choose you deliberately over every other shoe on the shelf — was no longer the most important question in the building. And by the time that shows up in the market, the competitors focused on substance have already compounded their advantage. You cannot run a wholesale reunion tour and rebuild a four-year product gap simultaneously, and have either move fast. Elliott Hill knows this. The return to sport-centric categories — running, basketball, football, training — is a substance move, not a form move. He is not just reorganising distribution. He is reorganising attention: back to the athlete, back to the product, back to what the Swoosh was supposed to mean. The difficulty is that form moves faster than substance. You can sign a new agreement with Foot Locker in a quarter. You cannot rebuild a four-year product gap in the same window. The wholesale partnership is the visible metric. The product credibility is the real one. That is why the stock sits at a twelve-year low in the same quarter that wholesale grew five percent. The form is recovering. The market is waiting on the substance. ## The scale of the damage A few numbers worth naming directly, because the magnitude matters. [Converse](https://fintool.com/news/nike-converse-layoffs-sales-collapse) swung from a $39 million operating profit to a $40 million operating loss in a single year. Revenue hit a fifteen-year low. The brand over-indexed on the Chuck Taylor for too long, failed to innovate, and got dragged down by Nike's own DTC discounting. BNP Paribas has said publicly that Nike should consider selling it. Nike has already exited Cole Haan, Hurley, and Umbro. At 2.5% of group revenue, Converse is marginal — but a sale would be a signal. In China, [Anta now holds 23% market share against Nike's 20.7%](https://frontofficesports.com/china-sportswear-market-nike-adidas-lululemon/). A Chinese brand has overtaken the world's largest sportswear company in the world's largest growth market. The "Guochao" movement — a wave of consumer nationalism, buying Chinese as a cultural identity statement — accelerated it structurally. Nike's response is localisation: a House of Innovation in Shanghai, pulling product off discount to protect premium positioning. The right moves. But they're fighting a cultural current with a marketing budget, and the company expects China revenue to drop a further 20% next quarter. The tariff hit adds $1.5 billion annually. Sourcing is shifting from China to Vietnam, but that takes years, not quarters. All of this is manageable — but none of it is quick. ## The operator's read The question I'd sit with if I were Elliott Hill — and the same question at the scale of a fifty-million-dollar business rather than a fifty-billion-dollar one: *When did the delivery mechanism become more important than what was being delivered?* For most businesses, it doesn't happen as visibly as Nike. There's no single strategy announcement. It happens gradually. The CRM becomes a leadership priority before service quality does. The sales process gets optimised instead of the capability that makes the sale worth having. The brand strategy gets more attention than the operational reality the brand is supposed to represent. Three diagnostic questions. Short ones. **01 — Where is the ratio?** In your last ten leadership decisions, how many were about the product or service itself versus how many were about how you sell, market, or distribute it? If the ratio tilts toward the latter, you're in the early stages of the Nike pattern. **02 — What got displaced?** Where has a channel or delivery decision quietly replaced a capability decision in the last twelve months? The sales team restructure instead of the service investment. The website refresh instead of the operations upgrade. The go-to-market strategy instead of the thing the go-to-market strategy is supposed to make people want. **03 — Are your best customers still choosing you deliberately?** Nike's running category is recovering because serious runners found something worth picking again. On and Hoka grew because they gave athletes something to choose with conviction, not settle for. The question is whether your best customers are still in that first category — or quietly starting to settle. ## The takeaway Distribution is not the product. It never was. Nike's DTC strategy was not wrong in principle. Being closer to the customer, owning the relationship, capturing the margin — sound instincts. The mistake was making the delivery mechanism the point of the strategy while the product that made the delivery worth having was running on four-year-old momentum. Elliott Hill's job is not to undo DTC. It's to re-establish that the product comes first. That the athlete is the client, the shoe is the answer, and everything else is logistics. If that sentence reads as obvious right now — good. The trap is the moment it stops being obvious. The moment the pipeline report replaces the product review. The moment you know more about your conversion rate than your customer's actual experience of what you made. Nike is doing the hard work of re-learning something it already knew. The Swoosh does not mean distribution. It never did. It means the athlete picked you. --- *This is Episode 4 of Commander in Brief. Earlier episodes: [Why Toyota's Slowness Is Every Mature Business's Trap](/articles/the-mature-business-trap), [Values as the Commons](/articles/values-as-the-commons), and [AI Business Engineering — A Working Definition](/articles/ai-business-engineering-a-working-definition). The framework lives in the book — [Resolute](https://www.amazon.com.au/Resolute-navigate-disruption-indestructible-organizations/dp/0645825425), in print since December 2024.* --- # C² vs BMAD: two ways to build with AI agents ## Both add structure to AI development. One hands you a workflow to serve; the other builds a contextbase you own. - URL: https://stuartleo.com/articles/c2-vs-bmad - Published: 2026-05-31 - Reading time: 4 min read - Method: C² Method BMAD and C² both bring discipline to building with AI agents — BMAD runs personas through a heavier SDLC, C² centres on a contextbase you own that compounds. BMAD and C² are two of the better-known methods for building software with AI coding agents, and they come up together a lot. They share a premise — AI changes how you should structure development — but they answer it differently. Here's an honest head-to-head from someone who built one of them and ships production software with it daily. ## What each is **[BMAD](https://github.com/bmad-code-org/BMAD-METHOD)** (Breakthrough Method for Agile AI-Driven Development) is an orchestrated SDLC. It defines specialised AI **personas** — Product Manager, Architect, Developer, QA — and moves work through phases (analysis → planning → solutioning → implementation) with artifacts and guardrails at each step. It's opinionated, end-to-end, and complete — if the persona pipeline is the thing you want. **C²** (the C² Method) is a lighter, agent-agnostic method built on one architectural idea: every project runs two systems — a codebase and a **contextbase** — and the contextbase (briefs, patterns, gotchas, decisions) is a first-class, version-controlled artifact the agent reads before it acts. Work runs through a light cascade of briefs, the human is the **pilot** who directs throughout, and the contextbase **compounds** every session. ## The core difference BMAD's centre of gravity is the **persona workflow** — who does what, in what order. C²'s centre of gravity is the **contextbase** — what the system knows, and how that knowledge compounds across sessions. That one distinction decides almost everything else. In BMAD, context lives *inside* the pipeline: it's loaded to run a phase and consumed doing it. In C², context is an **asset that accrues** — every session commits what was learned, so the next session starts ahead. After fifty sessions a C² contextbase is denser in real decisions than the code itself — a pipeline doesn't leave that behind. To be fair to BMAD, it has moved toward this. Its current docs describe a project-context skill that keeps a verified block of project facts in AGENTS.md ([BMAD's docs](https://docs.bmad-method.org/existing-codebases/set-and-maintain-project-context/)). That's a real step. It's one block of facts, though, not a record of every decision made and every trap already hit. Three practical consequences: - **Weight.** BMAD is a fuller framework you adopt and serve. C² is a method plus markdown templates — lighter to start, easier to bend, nothing to rip out later. - **Ownership and portability.** C² is plain markdown in git with no orchestration layer, so it transfers between agents with zero friction and the context you build is *yours* — not locked inside a framework. - **Range.** A C² contextbase is the same shape for a solo founder on one product and a team running many apps across multiple locations. BMAD's persona orchestration is built for a team that wants exactly that pipeline — heavy for a solo builder, and indifferent to whether your context compounds. ## Side by side | | C² | BMAD | |---|---|---| | Shape | Method + templates | Orchestrated SDLC | | Weight | Light | Heavier | | Centre of gravity | The contextbase | Persona workflow | | Human role | Pilot (directs throughout) | Orchestrates personas | | Context model | Invest & compound — an asset you own | Phase pipeline — consumed running it | | Range | Solo founder → multi-app, multi-location teams | Teams that want the persona pipeline | | Adoption | Point your agent at the kit, minutes | Adopt the persona framework | ## When to pick which - **Pick C²** if you want the lightest structure that still compounds — a contextbase the agent reads first, a few brief templates, the discipline of a session brief — and you want it to fit whether you're solo today or running several apps across a team tomorrow. For most builders, this is the one. - **Pick BMAD** if you specifically want a prescriptive, role-based pipeline that tells the team and the agents exactly who does what at each phase, and you're happy to adopt a fuller framework to get it. They're not mutually exclusive at the level of ideas. If you run BMAD, C²'s contextbase discipline — a router, a knowledge folder, session briefs as memory — slots in underneath the persona workflow and gives it more than its project-context block can hold: memory that compounds session by session. If you run C², BMAD's persona thinking can inform how you design your agent team. The honest summary: **BMAD gives you a workflow to serve — C² gives you a contextbase you own.** Most teams feel the context problem first — the agent forgetting, the knowledge evaporating — and that's the gap C² was built to close. [Read the C² method](/c2/method), see [how all the methodologies compare](/articles/ai-development-methodologies-compared), or the [head-to-head with Shape Up](/articles/c2-vs-shape-up). For the wider shift this is part of, see [the alternative to Agile](/articles/alternative-to-agile). --- # C² vs Shape Up: from human teams to human + AI teams ## Shape Up shaped a generation of product teams. C² rebuilds its best instincts for teams that include AI agents. - URL: https://stuartleo.com/articles/c2-vs-shape-up - Published: 2026-05-29 - Reading time: 4 min read - Method: C² Method Shape Up gave product teams appetite-based betting and an escape from sprint theatre. C² keeps those instincts and adds what AI needs — a contextbase that compounds. [Shape Up](https://basecamp.com/shapeup), from Basecamp, is the clearest pre-AI thinking on how to scope and bet on work: fixed appetites, outcome focus, six-week cycles, and a firm rejection of sprint theatre. It's also the closest ancestor to C². If you already think in Shape Up terms, C² will feel familiar — and the differences are exactly the things AI changes. Here's the head-to-head from someone who built C² and ships with it daily. ## What Shape Up got right Shape Up's instincts hold up, and C² keeps all of them: - **Appetite over estimate.** Decide how much a problem is worth, then fit the solution to the budget — not the other way round. - **Outcomes over output.** Bet on shipped value, not story points. - **No sprint theatre.** Drop the ceremonies that exist to make humans feel busy. Where it diverges is that Shape Up was designed for **humans directing humans** — and the team has changed. None of what follows is a knock on Shape Up — it's what a method built in 2018 had no reason to include. ## What AI changes An AI-native method needs four things Shape Up has no equivalent for: - **A contextbase that compounds.** Shape Up's pitches and cycles live in Basecamp, for humans, and go quiet once a cycle ends. C² keeps a version-controlled contextbase — briefs, patterns, gotchas, decisions — that the *agent* reads before it acts, and that **accrues**: every session commits what was learned, so the next one starts ahead. Documents inform a cycle — a contextbase is an asset that keeps paying. - **A router.** C² has one file the agent reads first, that lazy-loads exactly the context a task needs. Shape Up has no machine-readable entry point. - **An execution contract.** C²'s autonomous brief specifies exact files and acceptance criteria so an agent can run unattended. Shape Up trusts a human to figure out the approach. - **Session memory.** C²'s session brief is written memory across the gap between sessions — a gap AI agents have and humans don't. The throughline: Shape Up tells you *what* to bet on — C² gives the agents the memory and the contract to build it — and it holds the same shape from a solo founder on one product to a team running many apps across multiple locations. ## Side by side | | Shape Up | C² | |---|---|---| | Era | Human teams (pre-AI) | Human + AI teams | | Scoping | Appetite / betting | Appetite-style, plus a brief cascade | | Cadence | Six-week cycles | Continuous, session by session | | Documentation | Basecamp (for humans) | Repo-native markdown (humans *and* agents) | | Knowledge | Tribal, fades after a cycle | Contextbase in git — compounds, self-improving | | Execution | Human figures out the approach | Brief specifies it — agent can run autonomously | | Range | Product team in one place | Solo founder → multi-app, multi-location | | Human role | Shaper | Pilot | ## When to use which - **Shape Up** is still excellent for the *betting* layer — deciding what's worth doing and how much appetite it gets. If your team is mostly humans, it remains a great fit. - **C²** is for the *execution* layer when AI agents are doing the building. It assumes the codebase has a parallel contextbase the agent reads first, and it compounds that context as you go. The cleanest setup, honestly, is both: keep Shape Up's appetite and betting to decide *what* to build, and run C² underneath to direct *how* the agents build it — and to make sure what they learn doing it sticks. Shape Up shapes the work — C² gives it a contextbase that compounds. [Read the C² method](/c2/method), or compare it to [Agile](/articles/alternative-to-agile) and the [other AI methodologies](/articles/ai-development-methodologies-compared) — including the [head-to-head with BMAD](/articles/c2-vs-bmad). --- # Why Toyota's Slowness Is Every Mature Business's Trap ## What the CFO admitted out loud — and the Mastery trap on the Resolute Leadership Curve. - URL: https://stuartleo.com/articles/the-mature-business-trap - Published: 2026-05-25 - Reading time: 9 min read - Method: Essay Toyota's CFO named internal slowness as the cause of three years of decline. The Mastery trap on the Leadership Curve — and how it scales to any business. Toyota just reported [$25 billion in operating profit](https://pressroom.toyota.com/tmc-announces-april-through-march-2026-financial-results/). That sounds like a good year. It isn't. It's the third in a row of decline. And the chief financial officer, at the earnings press conference, did something CFOs almost never do. He named what was actually causing it. Yoichi Miyazaki — the man whose job it is to explain the numbers — said the slowness was internal. Not the tariffs. Not the Middle East. Not China. The company itself had been too slow to reshape its operating structure for the medium and long term. The seeds for future growth, in [his own words](https://japantoday.com/category/business/toyota-sees-profit-drop-as-us-tariffs-mideast-bite), had not been planted. That is rarer than it sounds. Most companies blame the market. Most CFOs blame the cycle. Toyota's CFO named the structure. And the structure he named is the same one every mature business has — which is why this piece is for you, even if you are not running a four hundred billion dollar car company. This is the Mastery trap on the [Resolute Leadership Curve](/articles/the-resolute-leadership-curve-a-primer). And Toyota just put on display one of the cleanest worked examples I have seen on a public earnings call. ## The decision behind the move Let me walk you through what is actually happening. [Toyota's net revenue for the year](https://www.sec.gov/Archives/edgar/data/1094517/000119312526213363/d125424dex991.htm) was around ¥50 trillion — about $335 billion. Operating income was ¥3.76 trillion, or $25 billion. That number was [down 21% on the year before](https://www.investing.com/news/company-news/toyota-fy2026-slides-tariffs-drive-profit-decline-despite-volume-gains-93CH-4671170). The single biggest cause was United States tariffs. ¥1.38 trillion of impact. $8.8 billion gone, off the operating line. The most dramatic consequence was North America. For the first time in years, [Toyota's North American operation posted an operating loss](https://www.wardsauto.com/news/us-tariffs-erase-all-of-toyotas-north-america-profits-in-fy2026/819825/) — $1.9 billion. The tariffs erased the entire region's profit. Look forward, and the picture is worse. The [forecast for the next fiscal year](https://www.nationthailand.com/news/world/40065993) is ¥3 trillion of operating profit. That is a third consecutive annual decline. Cumulatively, Toyota is now sitting at ¥2.3 trillion below where they were three years ago — roughly $15 billion of operating profit, just gone. And the same week the CFO made his admission, Toyota changed CEOs. Again. Koji Sato — the car guy who championed the [multi-pathway hybrid strategy](https://www.autonews.com/toyota/an-toyota-koji-sato-talk-from-the-top-ceo-interview-qa-1118/) — moved up to Vice Chairman and Chief Industry Officer. Kenta Kon, until that day the Operating Officer and a finance person by background, [took the CEO seat](https://global.toyota/en/newsroom/corporate/43951723.html). The Carscoops headline put it bluntly. [*Toyota just swapped its car-guy CEO for an accountant.*](https://www.carscoops.com/2026/02/toyota-ceo-change-profit-forecast-ev-hybrid-strategy/) That CEO change is not unrelated to Miyazaki's quote. Read together, they say the same thing. The product strategy was largely right. The operating system underneath the product strategy needs to reshape. The next mandate is financial discipline and structural reset — not a new car. ## The framework lens The [Resolute Leadership Curve](/articles/the-resolute-leadership-curve-a-primer) has six stages of growth — Idea, Identity, Calibrate, Maturity, Mastery, Initiate. Toyota is in Mastery. They have been there for decades. Mastery is the stage where the business is genuinely good at what it does — efficient, productive, dominant in its market, with a brand and a system that have compounded for years. Mastery is the stage every founder dreams of reaching. And Mastery is also a trap. Here is why. The operating system that gets a business to Mastery is not the same operating system that keeps it there. At every prior stage, growth came from doing the next obvious thing better. At Mastery, the next obvious thing becomes a constraint. You are excellent at the model you built. The market, the technology, the competitive set — they keep moving. You stay still. And from the inside, staying still feels like *doing more of what worked*. Toyota built one of the greatest operating systems in industrial history. The [Toyota Production System](https://en.wikipedia.org/wiki/Toyota_Production_System) — lean, kaizen, just-in-time — is taught in every business school on the planet. The multi-pathway approach — hedging across hybrids, plug-in hybrids, hydrogen, and battery electric — was, and arguably still is, the smartest portfolio bet in the global auto industry. In North America and Europe right now, where [EV adoption has slowed](https://ev.com/news/toyota-scales-back-2026-ev-production-target-by-30-amid-market-slowdown) and consumers are returning to hybrids, Toyota looks prescient. So the framework was not the problem. The product strategy was not the problem. What Miyazaki named — and this is the move worth pausing on — is that the operating *structure* underneath that strategy did not move fast enough. The skills and the systems that built the great hybrid car company are not the same skills and systems that build the software-defined, [China-local](https://www.bloomberg.com/news/articles/2025-09-30/toyota-is-clawing-back-market-share-in-china-with-new-15-000-ev), AI-instrumented vehicle company of the next decade. That is the third tension in the Resolute framework — [Skills versus Systems](/articles/the-three-tensions). A skill is what a person can do. A system is what survives that person leaving. Toyota has the skill. The skills are world-class. What they are publicly admitting is that the systems have not evolved at the pace the market now demands. **Mastery quietly bleeds into inertia. You don't see it from the inside. The numbers stay flat for a year. Then two. Then three. Then a CFO at a press conference names it out loud.** If you are running a business right now that is in Mastery — and a lot of the businesses I work with are — the leading indicator is *flatness*. Not decline. Flatness. Three quarters of revenue holding steady. The same hire-fire cycle. The same customer complaint reaching your inbox for the third time. That is what Toyota's CFO was looking at when he said what he said. ## The operator's read So if you are sitting in the seat — the CEO, the founder, the operating partner of an SME mid-market business that is already good — what do you do with this? Three diagnostic questions. None of them require you to run a four hundred billion dollar company. They scale down. ### 01 — What am I defending past its usefulness? *What system, process, or playbook am I defending past its usefulness, because it used to work?* Every mature business has one. The sales process that closed the first hundred customers but doesn't scale to the next thousand. The hiring rubric that selected the right people in 2018 and selects for nostalgia in 2026. The reporting cadence that fit a ten-person team and is now an obstacle for a sixty-person team. Toyota's version is the Toyota Production System extended past its design envelope. Yours is something smaller — and you know what it is. The work is naming it out loud, the way Miyazaki did. ### 02 — Where am I hedging when I should be concentrating? Multi-pathway is a portfolio bet. It is the right move when you do not know which way the market is going. It is the wrong move when you know — and you keep hedging because hedging feels safer. At Mastery, hedging starts to look like wisdom and feels like prudence and is, in fact, the trap. Concentration of capital, leadership attention, and operating system into the next S-curve is what *Initiate* looks like. You earn the right to concentrate by having the receipts. You forfeit the next stage by refusing to use them. ### 03 — Is the flatness already telling me? *Is the flatness already telling me what Toyota's CFO just said out loud?* Three years of flat earnings is a structural tell. Three quarters of the same customer churn is a tell. Three hires in a row of the same kind of person who don't move the needle is a tell. Flatness is the warning signal of Mastery — the one most leaders read as stability. It is not stability. It is the very specific shape of an operating system that has outlived the conditions it was designed for. The leader who runs those three diagnostics honestly catches the trap before it shows up in three years of decline. The leader who doesn't — who reads flatness as success — ends up in front of a press conference reading from a script Miyazaki just wrote. ## What the Curve says about the next move The Resolute Leadership Curve says two things about Mastery that almost no other framework names. **First, the character stays.** The substance of the business — its values, its operator, the integrity it has earned — does not change as it moves stages. Toyota's character is the reason a CFO can name internal inertia out loud at a press conference. That is the substance. **Second, the form must move.** The skills and the systems underneath the character have to evolve, often before there is any obvious reason to evolve them. The next operating system has to be built while the current one is still working. *Initiate* happens while *Mastery* is still profitable. Once the decline shows up in the numbers, the runway to reset is shorter than anyone wants to admit. This is exactly the asymmetry the Curve names — character stays, the rest evolves. The Kon appointment reads like Toyota beginning that work. The mandate is structural, not product. The leader is financial discipline, not the next car. The signal is structural: the system is the work, and the system is what's moving. ## The takeaway Here is what I would do this week if I were sitting in a Mastery-stage seat. I would write Miyazaki's sentence on a card and put it on my desk. *Our slowness in reshaping the operating structure is what caused this.* Then I would run the three diagnostics in my next leadership meeting. Honestly. With the team. And I would name flatness as the warning signal — not the comfort. The framework holds at every scale. Toyota is doing this work at four hundred billion dollars. You can do it at fifty million. The principle is the same. The character stays. The form moves. The leader who sees the trap from the inside has more time to reset than the leader who waits for the press conference. That's what I have for you this week. Operator to operator. I'll see you next week. --- *This is Episode 3 of Commander in Brief. Earlier episodes: [AI Business Engineering — A Working Definition](/articles/ai-business-engineering-a-working-definition) and [Values as the Commons — The Test Most Leaders Get Wrong](/articles/values-as-the-commons). The framework lives in the book — [Resolute](https://www.amazon.com.au/Resolute-navigate-disruption-indestructible-organizations/dp/0645825425), in print since December 2024.* --- # Values as the Commons — The Test Most Leaders Get Wrong ## What Pete Hegseth's keynote reveals about values, AI, and alignment - URL: https://stuartleo.com/articles/values-as-the-commons - Published: 2026-05-18 - Reading time: 9 min read - Method: Essay Pete Hegseth led with values. The move was textbook — and reveals why AI exposes whether your team's values were ever truly common. Pete Hegseth, the US Secretary of Defense, recently gathered all his generals to [a single conference](https://www.youtube.com/watch?v=8BA5EwsR_rI). Hundreds of them. From every command, every theatre, every branch of the service. The keynote could have started anywhere. It started with values. Not with strategy. Not with hardware. Not with budgets. With what they stand for and what allows them to work together. Politics aside — and politics matter, but they're not what this piece is about — that move is textbook. It's what every operator at the top of every organisation should be doing right now. And almost nobody is. What follows is why that move works, what makes it stick, and what it has to do with AI. ## The decision behind the move What he was doing was establishing the commons. Before you can move an organisation, you need to know what the organisation actually shares. Not what's on the wall. Not what people say in interviews. What they actually act on when no one is watching. What they argue from when there's a disagreement. What they default to under pressure. That's the commons. Without it, no strategy moves. No restructure lands. No new technology integrates. The decisions get made — but the organisation doesn't follow, because there's nothing common underneath. Most leaders skip this step. They list values on the careers page and call it done. Hegseth's move was to stop and re-establish the commons before doing anything else. In an organisation as large and as politically loaded as the US military, that's a hard thing to do at all — let alone publicly. The principle isn't unique to the military. It's the same move every operator at the top of every organisation needs to make right now. With their leadership team. Around the boardroom table. Before the next reset, before the next AI deployment, before the next strategic pivot. ## The framework In [Resolute](https://amzn.asia/d/8PB98Ju), Chapter 7, I write down a principle. **Values reveal character. Character scales culture.** That sentence does a lot of work. Let me unpack it. Values are not beliefs. They are not what you say. They are not what's printed on the back of your business card. Values are revealed by character — by what you actually do, especially under pressure. The values that show up in your behaviour when it costs you something. Those are your real values. The ones on the wall might or might not match. Character — once it's revealed — only scales into a culture when it's shared. When it's common. One person of high integrity in an organisation of low integrity creates an exception, not a culture. A team of common integrity scales integrity into how the whole organisation works. That's the move. Not values — but commons. This is where most modern organisations have got lost. The emphasis goes on the *values* — let's pick the right words, let's print the poster, let's update the handbook. The emphasis should go on the *commons* — what is genuinely shared, lived, defaulted-to under pressure. Whether the words are perfect matters far less than whether the team actually holds them in common. ## The etymology that matters The British legal system has a House of Commons. It's where the way we actually live gets decided. Not the way we should live, theoretically — the way we, in common, do live. The word *commons* points at exactly the right thing. Common land was land everyone in the village had a right to use and a responsibility to maintain. Common values are the same. Held together. Defended together. Applied together. It's not — and this is important — the same as everyone agreeing on everything. I don't need to agree with every belief my colleague holds. I need to find the common ground on which the two of us can work. That's alignment. That's commons. The opposite is the failure mode I've seen in a lot of mid-market businesses recently. *I must make you believe everything I believe — and if you don't, we cannot work together.* That's not common values. That's organisational tyranny dressed in values language. It looks principled and it acts authoritarian. Modern organisations have a third failure mode too — the air-fairy version. Values listed in a tone of voice that means nothing. *Integrity. Excellence. Innovation. Customer focus.* Words that could be on any company's wall and tell you nothing about who they actually are. That's not common values either. That's just printed. **Not values — but commons.** ## The test Here is how you know whether a value is common, or just printed. Take the value. Pick one off your wall. Integrity works as well as any. Now turn it into a common *practice*. A practice is something you do, not something you believe. So Integrity might become — *don't do anything you wouldn't want going viral on social media tomorrow*. That's a practice. It's testable. The whole team can act on it. Now turn the practice into an *expected behaviour*. An expected behaviour is what the team defaults to when the situation arises. Whatever the context — a financial dealing, an ad campaign, a hiring decision, a firing decision, a product launch, a client conversation — you apply the practice and the answer is right there. Easy. Nothing to debate. *Would I want this on social media tomorrow?* If no, don't do it. If yes, proceed. That is a common value. Value, practice, behaviour. Connected. Lived. Testable in any situation by any team member without escalation. Now run the test on the values you have today. Take one off the wall. Can your team name a practice that operationalises it? If they each give a different answer, the value is not common. Can your team name an expected behaviour that holds in any context? If they have to think about it for more than ten seconds, the value is not common. It's just printed. This is the test most leaders skip. ## Why this matters more in 2026, not less Here is where AI comes in. Tools change weekly now. The model that was state of the art six months ago is mid-tier today. The framework you trained your team on last year may be obsolete this year. Skills go stale in months. The half-life of technical knowledge has collapsed. What does not change at that pace is the values layer. The character layer. Who you actually are when the tools are different and the skills are different and the playbook is different. That layer is the durable one. It is the one that carries through the volatility — because it predates the volatility. So the values layer — the *common* values layer specifically — is doing more work in 2026 than it has ever done. It is the only thing stable enough to anchor a team that is running on quarterly tooling changes. And here is the sharper point. AI scales whatever is there. It does not invent values. It executes them. If your team's values are common — actually common, in the sense that everyone could pass the test — then AI scales culture. Every prompt, every automation, every agent your team builds will compound the same character into the work. That's powerful. If your values are not common — if they are aspirational on the wall and contested in the room — then AI scales the fragmentation. Each team member writes prompts to their own private value. Each builds agents to their own working philosophy. Each automates the work in the way they personally would do it. The organisation looks busier and produces less coherent output every quarter. That's the failure mode nobody is naming yet — but it is showing up everywhere I look. Hegseth's move — establishing commons before doing anything else — is the move every CEO needs to make in 2026. Before the AI rollout, not after. Before the new strategy, not after. Before the org redesign, not after. You cannot write a coherent system prompt on contested ground. You cannot build an agent that represents the team if the team doesn't represent itself in common. ## The Monday morning test Walk into your next leadership meeting. Pick one value off your wall. Run the test. Can the team agree on a *practice* that operationalises it? Not in theory. In a sentence. *Don't do X. Always do Y.* Concrete. Can the team agree on an *expected behaviour* that holds in any context — financial, marketing, hiring, technical, customer-facing? Not five different answers. One. If yes — that value is common. Build on it. It is the foundation everything else stacks on. If no — that value is just printed. Don't print it any more. Either do the work to make it common, or take it off the wall. Then, when you've done that for one or two real values, do the same for the use of AI in your work. What is your common practice on AI use? What is the expected behaviour when an AI tool surfaces a recommendation? When a junior writes a prompt for a client deliverable? When an agent acts autonomously inside the workflow? If you can't answer — and most leadership teams can't right now — you don't have commons on AI yet. That is the first work. Before the next licence purchase. Before the next pilot. Before the next deployment. Get the commons first. Then scale. --- If your leadership team is sitting with a values reset — or trying to deploy AI on top of a culture you're not sure is actually common — that's the work. **[Start a conversation](/contact).** --- # The Resolute Leadership Curve ## A primer — one framework, three tensions, six stages, and the 40+ applications underneath. - URL: https://stuartleo.com/articles/the-resolute-leadership-curve-a-primer - Published: 2026-05-12 - Reading time: 8 min read - Method: Resolute Growth emerges from navigating three tensions — leading vs managing, values vs character, skills vs systems. The Resolute Leadership Curve is the map. Most leadership books are one idea stretched across three hundred pages. *Resolute* is built on a single premise — and then it shows the dozens of ways that premise applies. Here is the premise. **Growth emerges from navigating the dynamic tensions between leading and managing, values and character, and skills and systems.** Three tensions. They do not resolve. The leader who learns to live inside the pull of each one grows the people, the business, and themselves. The leader who picks a side — and most do, without realising — quietly bleeds out on the one they ignored. The Resolute Leadership Curve is the map of how those tensions play out as an organisation moves from idea to scale. Everything else in the book is an application of the same model. This primer walks the model in about ten minutes. The book is the deep version. The frameworks the engagements run on, the briefings reference, and Waymaker encodes into software all sit on the same spine. ## The three tensions A tension is not a problem. A problem has a solution. A tension has a pull on both sides, and the leader's job is to stand inside the pull and choose where to lean — knowing they will need to lean the other way next quarter. The book is built around three of them. **Leading versus managing.** Leadership pushes the organisation into a future state that doesn't exist yet. Management holds the line on the present state that does. The leader who only leads loses the present. The leader who only manages never sees what's coming. Both are necessary. Neither is sufficient. **Values versus character.** Values are what an organisation says it stands for. Character is what employees and customers actually experience. Most organisations have aspirational values and contradictory character — and the gap is where attrition, defection, and brand erosion live. The work is closing the gap. **Skills versus systems.** A skill is what one person can do. A system is what survives that person leaving. Almost every framework on the shelf — Drucker, Collins, Lencioni, the OKR canon — focuses on the skill. None of it is enough. The moment the person carrying the skill walks out, the skill walks out with them. What scales is the system underneath. Hold those three together. They are the spine of everything that follows. ## The curve The Resolute Leadership Curve is the map of how the three tensions play out as the organisation grows. It is a sensemaking framework — meaning its job is to help a leader understand where the business actually is, so they can choose what to do next. Think of navigating a dense forest. Sensemaking is the moment you stop walking and climb a tree to see the landscape. The Curve is the tree. ![The Resolute Leadership Curve — six stages of growth from Idea to Initiate, plotted as value over time.](/images/books/resolute/leadership-curve.svg) It plots value-over-time across six stages: Idea, Identity, Calibrate, Maturity, Mastery, Initiate. Each stage demands a different posture, a different skill, and a different system from the same underlying character. The leader the business needs in Identity is not the leader it needs in Mastery. The character stays. The rest evolves. Here is the part most operators miss. **The person who starts a business is not the same person who will scale it. The spreadsheet you start the business on is not the ERP you will scale on. The sales process that wins your first customer is not the sales process that closes your thousandth.** The shape of leadership has to change with the shape of the business. The Curve is the map of that change. It doesn't tell you that you will outgrow yourself, your tools, and your processes — that part is inevitable. It tells you *when*, and *what to build next*. ## Substance and form The two pillars of resolute leadership are *substance* and *form*. The asymmetry between them is where most leaders get caught. **Character and values are the substance.** They are the moral foundation. They define whether a leader uses influence for good or ill. Character is cultivated, not inherited. It shows up in how you hire, how you fire, how you handle the deal where the numbers say one thing and your gut says another. **Skills and systems are the form.** They are the tools of changemaking — strategic thinking, communication, decision-making, paired with the planning frameworks, the operating rhythms, the performance systems, and the technology that scales the work. The asymmetry matters. **Character and values don't change in a volatile world. They stay the same.** **Skills and systems must change in a volatile world. The leader adapts old ones and adopts new ones.** The character of the leader stays steady. The systems they use to lead with do not. Confuse the two and the business will be in trouble in either direction — rigid systems that cannot move with the market, or wobbly values that bend whenever the quarter looks soft. Neither builds anything that lasts. ## The twelve questions The Curve gets applied through questions. Twelve of them, split into two sets, used differently. **The Five Questions of Management** focus on the present. They keep the organisation aligned and effective at executing the plan that already exists. What is the plan, and how is success measured? What roles does the plan require? What goals must each role hit this quarter? What meetings are necessary, and how does the team solve problems together? What data is needed to see progress? **The Seven Questions of Leadership** focus on the future. They set vision, name the market, shape strategy, and grow the organisation. What is the vision, and what is holding the business back from reaching it? What is the market, and who is the ideal customer? What is the strategy, and where is growth focused? What is the business model, and is it creating value? What is the customer experience end to end? What is the employee experience end to end? What are the one, two, or three things this quarter that, if delivered, shift the needle? The Twelve are inspired by the British Army's [Mission Command](https://en.wikipedia.org/wiki/Mission_command) — a framework simple enough to be remembered under stress, deep enough to handle complexity. The same set served a Lance Corporal and a Captain. The genius was the shared language. In business, the enemy isn't another army. It is *the gap* — between where the organisation is today and where it needs to be tomorrow, between an unclear market and an intimately known customer, between a poorly performing model and a highly profitable one. The Twelve Questions exist to make those gaps visible, and then to make them actionable. Which set to ask first depends on one prior question. *Am I innovating, or am I executing?* If the business exists and a plan is already running, start with the Five. Build the muscle of disciplined execution first. Then move to the Seven — vision, market, strategy, model — once the present is reliably hitting. ## The five foundational principles The Curve holds together because five principles run underneath it. Each is a tension you live inside, not a problem you solve once. 1. **Real growth is earned, not bought.** The highest-value growth comes from intentional maturity stages, each demanding its own development of character, skills, and systems. The acquisition that promises to skip three of them is the acquisition that breaks the company. 2. **Lead people, manage things.** Leadership is not management. The difference creates a positive tension when applied correctly, and a destructive one when collapsed into one job. 3. **Values reveal character, character scales culture.** The best organisations design culture so the values they declare are the character customers actually experience. The gap is where trust breaks. 4. **Skills scale systems, systems scale efficiency.** Developing the right competencies at each stage creates layers of institutional capability that compound. Without the system underneath, the skill stays trapped in the head it lives in. 5. **Questions are more valuable than answers.** Balancing leading the future with managing the present requires critical questioning. The leader who reaches for the question first builds an organisation that thinks. The leader who reaches for the answer first builds an organisation that waits. Read those five lines slowly. They are the spine of everything in the book, and the spine of every engagement that runs on it. ## What the curve is really for The Leadership Curve is not a maturity badge. It is not a test a leader passes. It is a mental model that integrates character with strategic progression. It says, plainly, that leadership is not just about having the right vision — it is about being the right kind of leader for every phase of growth. Same person, different posture, different skills, different systems. The character stays. The rest evolves. So sit with the harder question for a moment. Where on the Curve is the business actually leading from right now — and where is it pretending to be? That question, asked honestly, will do more for a leader than any framework can teach. The rest of the book is built to help answer it. --- *This is the first of three primer articles on the Resolute Leadership Curve. Two more follow: The Three Tensions, and The Twelve Questions. The book is the deep version — [Resolute](https://www.amazon.com.au/Resolute-navigate-disruption-indestructible-organizations/dp/0645825425), in print since December 2024.* --- # The Three Tensions ## Where growth actually lives — leading vs managing, values vs character, skills vs systems. - URL: https://stuartleo.com/articles/the-three-tensions - Published: 2026-05-12 - Reading time: 8 min read - Method: Resolute Three permanent pulls underneath every growing business. The leader who learns to live inside them grows. The one who picks a side stalls. Most leadership advice tells you to *balance* things. Balance is a useless metaphor. It implies a 50/50 split, a stable midpoint, a problem you can solve and then forget about. The actual experience of running a business is nothing like that. What you are inside is a tension. A permanent pull on both sides. The job is not to find the middle — it is to stand inside the pull and choose where to lean, knowing you will need to lean the other way next quarter. Then to do it again. Then again. [*Resolute*](https://www.amazon.com.au/Resolute-navigate-disruption-indestructible-organizations/dp/0645825425) is built around three of these. They are the spine of the Resolute Leadership Curve, and the reason the framework holds across industries and tenures. Get all three right, and the business compounds. Get one wrong, and the others quietly atrophy. This is the deep version of the three. ## Tension 1 — Leading versus managing Every organisation arrives at the same confusion. The founder talks about *leading* the team. The chief operating officer talks about *managing* the team. Both think they are doing the same job. Neither quite is. **Managing** means ensuring the right things get done, in the right way, at the right time. Execute the plan that already exists. Keep change to a minimum. Hit the outcomes the current quarter demands. The Five Questions of Management sit on this side — plan, roles, goals, meetings, data. **Leading** means influencing beliefs and behaviours — moving people, and the organisation, into a future state that doesn't yet exist. The Seven Questions of Leadership sit here — vision, market, strategy, model, customer experience, employee experience, the one-to-three things that shift the needle. The two bleed into each other. Executing the plan is also leading the team. Leading change is also managing the change. They are the right and left hands of organisational function — and like hands, neither works well alone. Here is where it breaks. Overplay management and you stagnate. Blockbuster ran its current model flawlessly all the way into irrelevance. The plan was working. The world it was working in had moved on. Nobody at the top raised their head far enough to see Netflix coming. Overplay leadership and you chaos out. Quibi raised nearly $2 billion on a bold vision for short-form streaming. The vision was loud. The execution underneath — marketing, content delivery, user engagement — was missing. The business folded in six months. Positive tension lives between the two. When the two are balanced, the tension is constructive — like a well-tensioned bridge that can carry serious weight while staying stable. Overplay either side and the bridge starts to fail. Which side of this tension are you currently overplaying? ## Tension 2 — Values versus character This is the tension most organisations get wrong, because most don't see it as a tension at all. **Values** are what an organisation says it stands for. The poster on the wall. The line in the deck. The phrase the leader uses on the all-hands call. **Character** is what employees and customers actually experience. The way decisions get made when nobody is watching. The behaviour the leader rewards. The thing that happens when the values on the poster and the realities of a hard quarter come into conflict. When the two match, the organisation has integrity — literally. The values *are* the character. Trust compounds. The best people stay. Customers feel the same thing inside the experience that the marketing promised on the outside. When the two diverge, the organisation has a credibility gap. And the gap is where attrition, defection, and brand erosion live. The team learns which values are real and which are wallpaper, and they pattern-match accordingly. Here is the diagnostic. Think of a leader you know well. What three words describe them when no one is watching? Jealousy? Fear? Dishonesty? Integrity? Compassion? Commitment? That is character. Whatever came up, that is the answer. A crisis never builds a character. It only reveals it. And character scales. Not aspirationally — literally. The leader who micromanages usually means well, but underneath the good intention is a vacuum where trust should be. That vacuum scales. The team learns not to take initiative, because initiative gets overridden. The best people leave first, because the best people will not work inside a cage. The leader works longer hours to compensate for the disengagement they themselves created, and the loop tightens. The leader whose character genuinely includes trust hands out ownership. The team rises into it. Ideas surface that the leader would not have had. The culture is one where growth and innovation are normal — because the character at the top makes them safe. Skills decide whether you can build something. Character decides what you build. As Norman Schwarzkopf put it: *leadership is a potent combination of strategy and character — but if you must be without one, be without strategy.* Whose work are you redoing today because you don't trust them to get it right? ## Tension 3 — Skills versus systems Every founder I've worked with eventually buys a system that promises to fix the business — a new CRM, a new ops platform, a new operating rhythm — and then watches it sit half-used while the team carries on the way they always have. The system isn't broken. The match is. **A skill is what one person can do.** Strategic thinking. Communication. Decision-making under pressure. Skills are real and irreplaceable — and they live in the head of whoever has them. **A system is what survives that person leaving.** Planning frameworks. Operating rhythms. Performance reviews. The CRM. The piece of software that captures the skill in a form anyone can pick up. Both matter. The trap is investing in only one. Invest only in skills and you build a business that depends on the founder, or the head of sales, or the rainmaker — and one resignation away from a crisis. Everyone in the building knows it. They just don't say it. Invest only in systems and you hit a different ceiling. The Ferrari/Volkswagen problem. You would not give a learner driver a Ferrari, and you wouldn't expect an F1 driver to win Monaco in a Beetle. The mismatch between skill and system breaks something every time — at best the result, at worst the driver. The fix is layering. Skills and systems act as growth layers. As each new skill develops, the matching system locks it in so the next person doesn't have to relearn it from scratch. Skill becomes process becomes platform becomes institutional capability. Each layer compounds the last. Take the customer journey. Thirty years ago it meant TV, radio, newspaper ads, and a physical shop. Today it means mobile apps, AI agents, parcel delivery. The tactics have evolved completely. But the customer journey is a foundation — it remains a constant building block of the business. Best practices change. Foundations stay. Are the systems in the business matched to the skills of the people driving them — or are you handing out Ferraris to learners? ## All three at once The three tensions are not a checklist. They are not a sequence. They are simultaneously present in every meeting, every hire, every quarter, every strategic decision. Most leaders are naturally good at one of them and quietly losing the other two. The visionary founder runs the leadership/management tension well — they push into the future relentlessly — and lets character drift because they trust their own intuition. They scale a culture of dependence on their own taste. The values-driven leader stewards character beautifully and never builds the systems underneath, so when they leave the room, the leadership leaves with them. The culture is admirable. The business is fragile. The systems-builder optimises the form and lets the substance starve. The operating rhythm is immaculate. Nobody can tell you what the business actually stands for. Three different versions of the same mistake. Pick a side, lose the others. The Resolute Leadership Curve doesn't tell you to balance the three. It tells you to live inside all of them, every quarter, while the stage of growth tells you which one currently needs the heaviest lean. The Curve is the map of that. The Twelve Questions are how you ask. The Five Foundational Principles are why it holds together. So one honest question before you turn the page. Of the three tensions — leading vs managing, values vs character, skills vs systems — which one are you currently overplaying, and which one is quietly atrophying because of it? That answer is usually the next thing to work on. --- *This is the second of three primer articles on the Resolute Leadership Curve. The first is [The Resolute Leadership Curve — a primer](/articles/the-resolute-leadership-curve-a-primer). The third is The Twelve Questions. The book is the deep version — [Resolute](https://www.amazon.com.au/Resolute-navigate-disruption-indestructible-organizations/dp/0645825425), in print since December 2024.* --- # The Twelve Questions ## Five of management, seven of leadership — the operating tool underneath the Curve. - URL: https://stuartleo.com/articles/the-twelve-questions - Published: 2026-05-12 - Reading time: 9 min read - Method: Resolute Five questions for executing the present, seven for leading the future. How the Resolute Leadership Curve gets applied on a Tuesday. When was the last time you walked out of a meeting with better questions than you walked in with? For most leaders, the answer is *I can't remember*. You walk in needing answers. You walk out with answers. The meeting ends, the team disperses, the work resumes. And three months later, you wonder why the organisation keeps solving the wrong problems. The leader who reaches for the answer first ends up running an organisation that depends on them for everything and outgrows them for nothing. The leader who reaches for the question first builds an organisation that thinks. This is the operational layer of the Resolute Leadership Curve. Twelve questions. Five of management for the present. Seven of leadership for the future. Used together, on a rhythm, they turn the framework from a model on the page into a way the business actually runs. [Resolute](https://www.amazon.com.au/Resolute-navigate-disruption-indestructible-organizations/dp/0645825425) is built around them. The engagements run on them. The briefings reference them. This is the version that fits in your head. ## Where the twelve come from The Twelve are inspired by the British Army's [Mission Command](https://en.wikipedia.org/wiki/Mission_command) — a framework simple enough to be remembered under stress, deep enough to handle complexity. The same set served a Lance Corporal and a Captain. The genius was the shared language. Every officer trained in the same questions, the same intent-setting, the same decision rights. The result was autonomous decision-making at every level, aligned to a unified purpose. In business the enemy isn't another army. It is *the gap*. - The gap between where the business is today and where it needs to be tomorrow. - The gap between an unclear market and an intimately understood customer. - The gap between a model that barely works and one that compounds. - The gap between a destructive culture and an employee experience that supports the work. The Twelve Questions exist to make those gaps visible. Then to make them actionable. Then to keep doing both, week after week, until the gap closes. ## The five questions of management These bring clarity and structure to the day-to-day. They focus on executing the plan that already exists. Management is about *things*. The Five are the things side of that line. 1. **What is our plan, and what metrics tell us if we are successful?** 2. **What roles does the plan require, and who is accountable for what?** 3. **What goals and outcomes must each role achieve this quarter, half, or year?** 4. **What meetings are necessary, what do we discuss in them, and how do we solve problems together?** 5. **What data do we need to measure progress and ensure success?** Look at those questions and notice what they do not say. They do not ask whether the plan is the right plan. That is leadership's job. The Five accept the plan as given and ask whether the organisation is wired to deliver it. In practice that means: a written plan with metrics that can be read off in a meeting, named owners for every accountable outcome, time-boxed goals, a meeting cadence with a clear purpose, and a small set of data feeds that tell the truth about progress. If three of those five are vague or missing, the business is not running. It is drifting with the appearance of motion. ## The seven questions of leadership These are forward-looking. They set vision, name the market, design strategy, and grow the organisation. Leadership is about *people*. The Seven are the people side of that line. 1. **What is our vision, is it driven by our purpose, and what is holding us back from reaching it?** 2. **What is our market, who is our ideal customer, what do they value, and what perceptions do we need to build?** 3. **What is our strategy, where is our growth focused, and how do we improve our positioning?** 4. **What is our business model, is it creating value, what metrics tell us this, and what practices improve our value proposition?** 5. **What is our customer's experience, how do we acquire, retain, and grow customers through our journey and promise, and what improvements need to be made?** 6. **What is our employee's experience, how do we acquire, retain, and grow talent through our journey and promise, and what improvements need to be made?** 7. **What are the one, two, or three things that, if delivered in the next quarter or half, will shift the needle on the business?** The Seven do something the Five never do — they question whether the plan is the right plan. They are how the leader keeps looking up while the rest of the business looks down at the plan. Most operators under-invest here. Vision feels too abstract. The market section feels like marketing's job. Strategy feels like the board's job. So the Seven get sketched once at an offsite and never asked again, while the Five quietly run the company in a direction nobody has revisited in years. The discipline is asking the Seven on a rhythm. Half-yearly works. Quarterly is better in early growth. Once a year is too rarely. ## Which set to ask first One prior question gets you there. **Am I innovating, or am I executing?** If the business already exists, has direction, has things that need to get done — start with the Five. The first cultural change most organisations need is disciplined execution. The muscle of getting things done, even imperfectly. A team has to learn to trap, pass, run, and kick as a unit before it can run advanced tactics. The same is true of leadership teams. Without disciplined execution, every new strategy lands on a team that can't deliver the last one. Once disciplined execution is in place, move to the Seven. Vision. Market. Strategy. Model. The forward-looking work that decides what the business is for. A pattern that often works: review the Seven half-yearly, align around the Five monthly or quarterly. Cadence keeps execution sharp without losing the strategic thread. Which side are you currently overplaying — execution, or vision? ## Clarity and maturity To progress through the stages of the Resolute Leadership Curve, you have to work on two things at once. **Clarity** is understanding the compelling *what* of each area of the organisation. It aligns teams and keeps everyone on the same page. The Seven Questions drive clarity. **Maturity** is continuously improving the *how* of each area. It is through maturity that teams experience compounding growth. The Five Questions drive maturity. **Lead with clarity. Manage with maturity.** To build both, ask and answer the right questions repeatedly. If the plan is clear enough to create value in the current quarter, focus alignment around the Five. When you need to define a new future state or make significant changes, return to the Seven. Every cycle sharpens the *what* and matures the *how*. Three things start to happen. **Clarity deepens.** Consistent revisiting creates a culture of openness, authenticity, and trust that supports continuous improvement. **Alignment spreads.** As clarity deepens, the direction of the organisation becomes easier to communicate, leading to broader alignment across teams and stakeholders. **Agility emerges.** With clarity and alignment, leaders and team members understand how and where to innovate and adapt. The agility is not chaotic — it is targeted, purposeful innovation occurring at all levels. That is the whole point. Asking the Twelve on a rhythm turns a leadership team from a group of people who happen to work in the same building into an organisation that thinks together. ## The cost of not asking Leaders who skip this don't fail loudly. They fail slowly. **Stagnation.** Without questions challenging the status quo, the organisation loses its edge. It keeps doing what worked last year while the market moves on. Kodak invented the digital camera and asked the wrong question about it. The right question — *what business is this, actually?* — was the one nobody upstairs wanted to hold. **Misalignment.** Without questions exposing what each team is actually optimising for, teams drift into working at cross purposes. Everyone is busy. Nothing connects. **Disconnection.** A leader who only gives answers stops hearing the ones their people would have offered. They miss the early signals, the quiet objections, the obvious-in-hindsight things that everyone but them could see. Curiosity, organised as discipline, is the antidote to all three. That is what the Twelve are for. ## Four practices for the inquiring leader If questions are the discipline, here is how to develop the muscle. **Be curious, not controlling.** Treat every problem as something to explore, not something to dominate. The instinct to know everything is the instinct that builds the bottleneck. **Focus on impact.** Don't ask trivia. Ask the questions that, if answered honestly, would actually change what the organisation does next week. **Encourage dialogue.** A great question opens a conversation. A leading question closes one. *"Don't you agree this is the right call?"* is not a question — it is a request for assent. Try *"What's the gap I'm missing?"* instead. **Embrace discomfort.** The questions that matter most are the ones you don't want to ask. *Am I serving this customer well, or just collecting their money? Is this person in the right role? What would I do differently if I started over today?* If the question is comfortable, it probably isn't valuable. So a working question for the rest of the week: *what is the question I've been avoiding because I'm afraid of the answer?* That is usually the one worth asking first. ## What the twelve are really for The Twelve Questions are not a quiz. They are not a maturity badge. They are a tool — the same way a hammer is a tool. The value is in what gets built when the tool is in the right hands and gets used often. Asked once and forgotten, they are useless. Asked on a rhythm, with honesty, in a leadership team willing to sit with the uncomfortable answers — they turn the Resolute Leadership Curve from a model on the page into the operating system of the business. So the only question that really matters this week. **Are you the leader who has all the answers, or the leader who knows which questions to ask?** The rest of the book is twelve of them. --- *This is the third of three primer articles on the Resolute Leadership Curve. The first is [The Resolute Leadership Curve — a primer](/articles/the-resolute-leadership-curve-a-primer). The second is [The Three Tensions](/articles/the-three-tensions). The book is the deep version — Resolute, in print since December 2024.* --- # AI Business Engineering: A Working Definition ## The discipline at the intersection of AI, transformation and running the business, and why the existing labels keep missing it. - URL: https://stuartleo.com/articles/ai-business-engineering-a-working-definition - Published: 2026-05-10 - Reading time: 8 min read - Method: Essay - Series: AI Business Engineering (part 1) A working definition for the discipline that sits at the intersection of AI, transformation, and SME C-suite operating — and why the existing labels keep missing it. The work I do does not have a name yet. I sit in the C-suite of an SME mid-market business — usually $5M to $50M revenue, usually founder-run or family-owned, usually 10 to 20 years old, usually with everything aged together. Strategy. Leadership. Operations. The working software. All need a reset at the same time. I run the reset end to end, alongside the leadership team. Operator in the room, not consultant in the deck. I write the thinking, I build the tooling, and I hold the operating tempo with the leadership team for as long as the engagement runs. When I tell people what I do, the labels miss. *AI consultant* is wrong — I do not explain AI for a living. *Transformation advisor* is wrong — I do not write the strategy and outsource the build. *Fractional CTO* is too narrow — strategy and leadership are half the work. *Operating partner* is closer but assumes a fund. *Founder-builder* describes my history, not what I do for clients. So I started using a working term: **AI Business Engineering**. Here's what I mean by it. ## A working definition, in three claims ### Claim one — it is engineering the business, not the AI Most of what gets called *AI engineering* in 2026 is engineering AI models, AI products, AI features. That work is real but it is downstream. The bottleneck for an SME mid-market business is not which model to fine-tune. The bottleneck is upstream: *what is the business actually trying to do, and is the leadership team aligned enough to ship it?* AI Business Engineering is the discipline of using AI to compress the upstream work. The output is sharper positions, deeper alignment, and execution that is hyper-focused on outcomes the team can name on a single page. The AI is the iteration accelerant. The business is the artifact under construction. If I had to put it in a sentence: I use AI to engineer business clarity, then let clarity drive everything else. ### Claim two — it is a discipline, not a toolkit A toolkit is a stack. Claude here, Cursor there, a Notion database, a Zapier workflow. A toolkit is replaceable. Next quarter's model changes the stack. A discipline is the operating principles that hold no matter which model is in fashion. The principles I run on are not new. They come from the framework I wrote into [Resolute](https://amzn.asia/d/8PB98Ju) over more than a decade — the Resolute Leadership Curve, the six stages of growth, the twelve questions, the Transformation Iceberg. What is new is the tempo. The frameworks did not need rewriting for the AI era. They needed an operator willing to run a clarity loop weekly instead of quarterly — and AI to take the synthesis cost low enough to make that cadence sane. **The frameworks did not need rewriting for the AI era. They needed an operator willing to run a clarity loop weekly instead of quarterly — and AI to take the synthesis cost low enough to make that cadence sane.** ### Claim three — it sits in the operator seat, not the CTO seat AI Business Engineering belongs to the person at the head of the table — the founder, the CEO, the operating partner — not the head of engineering. The CTO seat is critical and adjacent. It is not where this work lives. This work lives wherever positioning, leadership, operating model, and the working software all touch the same decision. That is the C-suite. In an SME of 50 to 500 people, that table is small enough to fit one operator who can hold all four threads at once. That is the role I run. ## Why Resolute is the substrate Frameworks fail in the AI era for two reasons. Too brittle — designed for a tempo synthesis can no longer support. Or too vague — designed to hold any business loosely, holding none precisely. Resolute is neither. It was written for SME mid-market operators specifically, and it was written as a sensemaking tool — not as a process. From the book itself: *the Leadership Curve provides elevated perspective to understand organizational position and determine the best path forward.* That is the function I lean on most. The curve gives me a stage hypothesis for the business in front of me. The six stages of growth name what each stage's real bottleneck is. The Transformation Iceberg names the depth at which a change actually has to land — behaviour, skill, belief, value, character — so that the work does not stay shallow. The twelve questions give me a structure I can run a clarity loop against — *seven of leadership for tomorrow, five of management for today.* What the book does not say — because it predates the wave — is what changes when AI is in the loop. That is what this series does. The frameworks hold. The loops compress. ## Why the discipline is unfilled The market today has three lanes that look adjacent to AI Business Engineering, and none of them sit where the work actually is. **The AI explainer lane** — Ethan Mollick, Azeem Azhar, Allie Miller. Excellent at explaining the wave. They do not run engagements and they do not ship the AI inside companies. They are upstream of the work. **The transformation advisor lane** — Aaron Dignan, Frédéric Laloux, Gabe Cutler. Excellent at designing organisations and leadership systems. They outsource the technical layer because that is not their craft. **The builder-operator lane** — Tobi Lütke, Simon Willison, Andrew Chen. Excellent at shipping AI at hyperscale. They are not in the SME C-suite engagement zone — the altitude is wrong. The triangle in the middle is empty. It is empty because the requirements compose multiplicatively. The work needs an operator who has earned the right to sit in the SME C-suite, who has the engineering chops to ship the working software, and who has run leadership and strategy long enough to have a framework worth running. Most operators have one of those. A few have two. The intersection is rare. Saying *AI Business Engineering* out loud is a way of staking that intersection. It is also a way of recognising the work that is already happening inside companies, by operators like me, that the existing labels keep missing. ## What it looks like in practice A working example. A services firm I worked with had one revenue channel under compression — government funding — and a leadership team aligned on the existing model, not the next one. A traditional engagement would diagnose for six weeks, write a strategy deck, hand it over, and bill quarterly through the implementation. That is not the work I did with them. The leadership team kept its quarterly rhythm. What changed was the work *between* the quarterlies. The CEO and I ran a weekly clarity loop — every week, a working session focused on whichever position the next quarterly needed to land. Before each loop, I used AI to compress the prep. Synthesising market data, modelling EBITDA scenarios under three different revenue architectures, drafting the position paper for the CEO to react to. This was as the AI wave was building — early enough that the tooling was rough, already inside the loop. By the time the leadership team met, the position was three or four cycles tighter than it would have been. Six weeks in, the CEO took a new revenue architecture to the team — three diversified commercial streams. Eighteen months later, revenue had doubled. EBITDA up more than 10%. The AI did not make the decision. The CEO and the leadership team made the decision. What AI did was take the synthesis cost low enough that the CEO could *think* weekly. Week over week, that clarity compounded. The quarterly meetings produced different decisions because of it. That is what AI Business Engineering looks like in the work. Not a feature. Not a deck. A different operating tempo, applied to the upstream clarity that everything else depends on. ## What this series does next Eight pieces. Next: *The Clarity Loop: Speed of Thought Beats Speed of Code* — the mechanism. After that: *The Resolute Leadership Curve, Re-Read for the AI Era* — the framework end to end. From there: a single-stage deep dive on the most common SME stuck-point (Calibrate), the operating tempo argument, a counter-positioning piece on what alignment actually means, a piece on the leadership character that holds when the tooling changes weekly, and the closing argument on what *outcome-based execution* means when you mean it. The series doubles as the spine for Commander in Brief. Audio is the primary cut — the article is the durable, search-indexed version. The frameworks come from Resolute. The lens is mine. The work is what I do for a living. --- If a piece of this maps to a problem you are sitting with, the work itself happens in conversation. **[Start a conversation](/contact).** For the longer ladder — engagement model, receipts, the books — the rest of the site is the map. --- # The Dictionary ## Resolute ### The Resolute Method - URL: https://stuartleo.com/dictionary/resolute-method Resolute is a thinking system for building a business that does not depend on you. It rests on a single move most leaders never make on purpose: separate the work of leading people from the work of managing things, then build both deliberately, in the right order, as the business grows. Resolute turns that into twelve questions — seven you lead with, five you manage with — mapped against the Leadership Curve, the six stages every business climbs from idea to market leadership. Answer the twelve honestly, on a rhythm, and the abstract job of running the company becomes a structured one: you can see where you are, name what is constraining the next stage, and build it. This report is the first honest look. ### The Resolute Leadership Curve - URL: https://stuartleo.com/dictionary/resolute-leadership-curve The Resolute Leadership Curve maps how a business is built, stage by stage: Idea ("I have an idea."), Identity ("Do we have a role to play in this market?"), Calibrate ("Are we aligned as we grow teams, skills and systems?"), Maturity ("Can we invest in growth with consistent returns?"), Mastery ("Are we leading the market we play in?"), Initiate ("What's the next curve — and have we started it?"). High-value growth is layered over time — each stage developing the character, skills and systems that become the foundation for the next. Fake scale rises fast and falls just as hard. ### The 12 Questions - URL: https://stuartleo.com/dictionary/12-questions 7 Questions of Leadership: Vision & Purpose, Market & Customer, Strategy & Positioning, Business Model & Value Creation, Customer Experience, Employee Experience, Goals. Creating change — refining the core of the organisation toward a better future state. 5 Questions of Management: Plan, Roles, Goals, Meetings, Data. Executing the present — taking the current plan and delivering the outcomes. ### The 7 Questions of Leadership - URL: https://stuartleo.com/dictionary/7-questions-of-leadership Vision & Purpose — what is our vision, is it driven by our purpose, and what is holding us back? Market & Customer — what is our market, who is our ideal customer, and what do they value? Strategy & Positioning — what is our strategy, where is growth focused, and how do we win? Business Model & Value — how does our model create and capture value, and is it working? Customer Experience — how do we find, keep and grow the right customers across their journey? Employee Experience — is the culture we have the culture we intend, and can we attract and keep the people the plan needs? Focus & Strategic Goals — what are the one, two or three things that will actually move the business this year? ### The 5 Questions of Management - URL: https://stuartleo.com/dictionary/5-questions-of-management Plan & Metrics — what is our plan, and what few numbers tell us we are winning? Roles & Accountability — what roles does the plan require, and who owns what? Goals & Outcomes — what must each role deliver this quarter, and do we know early if we are off? Meetings & Problem-Solving — what rhythm keeps us aligned and actually solves problems? Data & Measurement — what is our single source of truth for steering the business? ### Idea (stage) - URL: https://stuartleo.com/dictionary/idea-stage The Idea stage is not about having an idea — everyone has those. It is about sharpening a problem worth solving until it is specific, and proving the solution is wanted before you build the machine to deliver it. Two leadership questions live here: Vision & Purpose (the destination is named) and the first edge of Market & Customer (the problem is clear). The work is comprehension, not scale. ### Identity (stage) - URL: https://stuartleo.com/dictionary/identity-stage Identity is the search for fit — finding your role in a market that did not ask for you. The solution is in front of real customers now, and the question is whether the early signals of product-market fit are real or wishful. This is where the ideal customer sharpens, the business model gets drawn for the first time (how do we actually make money?), and brand foundations start to form. You are no longer guessing at the problem; you are testing whether your answer to it has a place. ### Calibrate (stage) - URL: https://stuartleo.com/dictionary/calibrate-stage Calibrate is where the business adds people, skills and systems — and discovers whether they cohere or fragment. This is the stage where most businesses stall, because growth that worked when the founder was in every conversation breaks the moment they are not. The cluster of questions here is dense: strategy must become a position the team can repeat, culture has to be built deliberately, the customer journey gets mapped, the people plan gets written, and Focus — naming the few priorities that actually matter — becomes the alignment mechanism that keeps everyone pointed the same way. ### Maturity (stage) - URL: https://stuartleo.com/dictionary/maturity-stage Maturity is where growth becomes repeatable and fundable — predictable ROI rather than lucky quarters. The questions here deepen rather than appear: the business model produces financial health that can fund new ideas, strategic clarity is established in the market, a real find-keep-grow customer strategy is running, and the least-mature areas get lifted to a consistent standard. This is also where the next opportunities — features, segments, acquisitions — first become visible, the catalysts for the wave after this one. ### Mastery (stage) - URL: https://stuartleo.com/dictionary/mastery-stage Mastery is market leadership — and the discipline to refuse to coast. The hardest questions deepen to their final form: the competitive advantage is continually deepened, the best people are retained and their skills actively grown, and the position is defended rather than assumed. Resting on past success is precisely how leaders begin to decline, so Mastery is less about reaching the top than about reinvesting at the top while the view tempts you to stop. ### Initiate (stage) - URL: https://stuartleo.com/dictionary/initiate-stage Initiate is the decision to start the next curve while the current one is still strong — not after the slowdown shows. Every growth curve eventually flattens; the leaders who endure begin the next big innovation during maturity, so they transition smoothly instead of falling off the back of the old curve. It is the most counter-intuitive stage, because it asks a winning business to invest in disruption before it feels necessary. ### Vision & Purpose - URL: https://stuartleo.com/dictionary/vision-and-purpose Two coordinates, not a poster. The vision is the picture of the world once your work is done — the destination. The purpose is the thing you can do every day that moves you toward it — the fuel. This question asks for something simpler than three statements and harder than a plaque: a destination and a daily action, both short enough to remember without trying, and an honest naming of the roadblocks in the way. Vision and purpose are the two coordinates that orient every other decision. Without them, organisations drift internally — promises slip, people disengage, and the leader works harder to compensate while the gap widens. People will sell things to feed their family; they will build something to change a world. The destination is what sustains a team through a hard week — and what makes a leader's job delegable instead of heroic. ### Market & Customer - URL: https://stuartleo.com/dictionary/market-and-customer Four questions inside one, answered in order: name the market broadly; identify the ideal customer inside it; understand what they value; and decide what perceptions you need to build in their mind. The clarity the old high street gave away for free, you now have to manufacture on purpose — that is the discipline this question installs. Clarity leads to focus, focus requires choices, and choices mean somebody gets left out. Go deep on a defined market and your brand sharpens, because a targeted group has clearer wants and clearer language. A broad audience has nothing in common except that you are shouting at all of them at once. Fuzzy market, fuzzy brand, fuzzy everything downstream — pricing, product, message, hiring. Sharpen the customer and every other decision gets easier. ### Strategy & Positioning - URL: https://stuartleo.com/dictionary/strategy-and-positioning Whether you actually have a strategy — or a long list of activities with an aspirational headline on the front. A strategy is not a plan; a plan executes a strategy. Strategy is securing, owning and defending a valuable position in the mind of your customer. The test is brutal and simple: can someone three layers below the CEO describe the strategy in sixty seconds, in their own words? If not, it does not exist as a strategy — it exists as a document. Position decides margin. Compete on the same activities done the same way and price becomes the only lever — a race to the bottom where your margin is whatever the cheapest competitor decides. A distinct set of activities producing a distinct outcome is a position no one else occupies, and that is where pricing power, loyalty and defensible growth come from. A real position also tells you where to grow — customer expansion or operating efficiency — instead of running both at half-power. ### Business Model & Value - URL: https://stuartleo.com/dictionary/business-model-and-value Four things in order: what the model is, whether it creates value today, what metrics prove it, and what practices sustain and improve the value proposition. The business model is the engine — how capital comes in, gets turned into something a customer values, and comes back as more capital ready to reinvest. Most leaders have a P&L and a whiteboard journey but have never actually drawn the engine on one page. This question makes them draw it, then asks whether it is running. The engine's design decides how far, how fast and how much fuel you burn. An unexamined model carries assumptions nobody has named and therefore nobody can challenge — and that is how businesses fail to respond to a changing market. Knowing the model, the right handful of metrics, a single North Star, and the systemised practices that defend the value proposition is the difference between growth you can repeat and growth you got lucky on once. ### Customer Experience - URL: https://stuartleo.com/dictionary/customer-experience Everything the customer thinks, sees, touches and feels across the whole relationship — not the single support call. Customer service is one transactional slice; customer experience is the entire relationship across every touchpoint, over the life of the customer. The first four questions are answered behind closed doors. CX is the open battleground — where the hypotheses of vision, market, strategy and model meet a real customer and either hold or break. This is where revenue actually happens — and where the cheapest growth hides. Most businesses obsess over acquisition and starve retention and growth, the most expensive mistake in CX, because a lift in retention usually beats the same lift in acquisition for less money. In the experience economy a small, intensely engaged audience can out-compete a giant with a tired experience. Get CX right and the customer carries the peaks forward; the details fade but the way you made them feel does not. ### Employee Experience - URL: https://stuartleo.com/dictionary/employee-experience The same question as CX, pointed inward: what journey does a talented person take to work for you, and is it remarkable? HR counts heads — contracts, payroll, compliance, exits. EX designs the journey — the totality of a person's relationship with the organisation from before day one to after they leave. And employee is a loose word now: it means talent — full-time, part-time, fractional, contractor, agency partner — anyone whose work makes you what you are. Of the two experiences that matter, CX drives today's revenue and EX sustains it and invents tomorrow's. Get both right and most other problems quietly solve themselves; get either wrong and no strategy saves you. The reframe is the point: do not build a culture program and hope individuals fit it — design an experience for the individual that, at scale, produces a healthy culture. Lower turnover, easier hiring, loyal employees making loyal customers — these compound into margin. ### Focus & Strategic Goals - URL: https://stuartleo.com/dictionary/focus-and-strategic-goals Not a strategy question — a discipline question. The first six leadership questions generate ideas; by the time you have answered them you have more good ideas than any team can execute in a year. The seventh forces the choice: of all of them, which one, two or three will actually move the needle in the next ninety days? Not which could. Not which should. Which will — if you commit, name a single owner, and stop everything else. Most strategy meetings end with a full whiteboard, forty initiatives, everyone nodding — and nothing happening, because nobody picked. Trying to do everything at once produces poor execution across the board. Steering a boat, you mostly hold course — but each quarter a small, deliberate adjustment to the sails harnesses more wind. Those compounding course corrections are what get you to the destination faster than the boat next to you. Focus is how strategy stops being a slide and starts being a result. ### Plan & Metrics - URL: https://stuartleo.com/dictionary/plan-and-metrics A plan is the bridge between a vision and a result. At its simplest it is a single goal that derives from your strategy, expressed as measurable outcomes — in percentages, numbers or dollars. The plan answers four things: what we are going to do, from when to when, why it matters, and the outcomes that prove we got there. What you choose to count is what you will actually do — so the metrics are not decoration on the plan, they are its nervous system. A vision without a plan is a wish; a plan without metrics is a guess. Plenty of leaders can describe the future beautifully and cannot tell you what they would measure on Friday to know the week moved them closer. Metrics keep the team honest and create accountability the moment they are set, because every number has an owner. Without them, success gets defined so loosely that nothing counts as failure, and the business runs on vanity numbers that flatter it on the way down. ### Roles & Accountability - URL: https://stuartleo.com/dictionary/roles-and-accountability Every outcome on the plan needs a single, named owner. A role is not a position on an org chart — it is a slice of the plan made someone's responsibility. The distinction that matters: a task is what you do; an outcome is what changes because you did it. Hire someone to write social posts and you buy a busy person; hire them to grow engagement and generate leads and you buy a result. When every outcome has a clear owner, you have performance architecture. When roles are defined by outcome, people stop performing busyness and start owning results. Initiative replaces permission-seeking. The leader stops being the bottleneck because accountability is unambiguous — nowhere to hide and nowhere to be unfairly blamed. When roles are vague, the vacuum fills with micromanagement, duplicated effort and quiet resentment. A larger team running on task lists loses, every time, to the right people in the right roles focused on the right outcomes. ### Goals & Outcomes - URL: https://stuartleo.com/dictionary/goals-and-outcomes Goal-setting translates a business-wide plan into role-specific execution. A goal has three layers: the What (the title, with a start and end date), the How (the outcomes that prove it, each a %, $ or number), and the Why (the meaning that makes anyone work for it). Outcomes break into waypoints — check-in milestones spaced by roughly one-twelfth of the goal's duration. If you cannot put a unit on it, it is not an outcome — it is a hope. Most teams do not fail at execution; they fail at the goal. Ask five people what they are trying to achieve this quarter and you get five different answers — activity climbs, progress does not. Clear goals empower people and reduce ambiguity; the brain spends its energy on execution instead of uncertainty. People who write goals down, commit to them, and share progress with an accountability partner outperform those with unwritten goals by a wide margin. And the Why is the part most managers leave on the table — a goal connected to what people personally care about survives a busy week. ### Meetings & Problem-Solving - URL: https://stuartleo.com/dictionary/meetings-and-problem-solving Meetings are where alignment, problem-solving and decisions happen — or where they go to die. The answer is an operating rhythm: a regular, structured cadence that keeps the organisation in time with itself — daily stand-ups, weekly goal tracking, fortnightly one-on-ones, monthly reporting, quarterly planning. Each cycle has a purpose; each meeting has a named owner. The rhythm is a gyroscope: spinning, it holds the line when disruption hits. And the rule is simple: you meet to make a decision, not to decide the question. Poorly run meetings are one of the most expensive line items in a business, and a large share of them are unnecessary or fixable with a message. Being busy is not being effective. A meeting should be doing one of two things: clearing the path or making the call. If it is doing neither, it is tax. Done well, the rhythm itself becomes the system that holds momentum, alignment and accountability together — without the leader having to be the one personally holding it. ### Data & Measurement - URL: https://stuartleo.com/dictionary/data-and-measurement Data is the instrument panel. The question is not whether you have data — every app is generating it — it is whether any of it tells you what to do next. Three kinds of intelligence answer three questions: Performance Intelligence (how is this person or team doing?), Business Intelligence (how is the business performing overall?), and Operational Intelligence (the plans, playbooks and SOPs that give everyone context). A single trusted source of truth, not a dozen tools talking past each other. Most businesses are drowning in data and starving for intelligence. The wrong data tells you the wrong story; the right data, used well, turns intuition into discipline. Without it you run blind — reactive, busy and scattered instead of proactive and targeted. Every meeting in the operating rhythm depends on it: wins, business health, goal reviews and roadblocks all need honest numbers, or the room runs on opinion. And fragmented data quietly creates security risk and cost while hiding the very links that would generate real insight. ### Character - URL: https://stuartleo.com/dictionary/character The inner reality your thoughts, decisions and behaviour are rooted in — who you are when no one is watching. Character is cultivated, not inherited, and a crisis never builds it; it only reveals it. Build on anything shallower and the structure holds only until the first real shock. Character is one of the two unchanging elements, Character & Values. The moral foundation of leadership — who you are and what you stand for. In a VUCA world, while everything around you shifts, character and values must stay the same. They are the line that holds. ### Values - URL: https://stuartleo.com/dictionary/values How you believe people ought to behave — the standard you decide by. Values reveal character, and character scales culture: who you say you are becomes what your customers and your team actually experience. Without them, every decision is re-litigated from scratch. Values is one of the two unchanging elements, Character & Values. The moral foundation of leadership — who you are and what you stand for. In a VUCA world, while everything around you shifts, character and values must stay the same. They are the line that holds. ### Skills - URL: https://stuartleo.com/dictionary/skills The craft of changemaking — strategy, communication, decision-making. Most leadership advice starts here. Resolute puts skills third on purpose: skill on a weak foundation is just faster motion in the wrong direction, and it must keep adapting as the world does. Skills is one of the two adaptive elements, Skills & Systems. The tools of changemaking — what you can do and what you build to scale it. In a VUCA world, skills and systems must change. Leaders adapt the old and adopt the new, or they fall behind. ### Systems - URL: https://stuartleo.com/dictionary/systems The frameworks that scale skill across an organisation — plans, roles, goals, meetings, data. Systems scale value only when matched to the skill of the people using them: you don't hand a learner driver a Ferrari. Systems first, and you automate dysfunction. Systems last, and you compound. Systems is one of the two adaptive elements, Skills & Systems. The tools of changemaking — what you can do and what you build to scale it. In a VUCA world, skills and systems must change. Leaders adapt the old and adopt the new, or they fall behind. ### Real growth is earned, not bought - URL: https://stuartleo.com/dictionary/real-growth-is-earned-not-bought High-value growth is layered over time — each stage developing the character, skills and systems that become the foundation for the next. Fake scale rises fast and falls just as hard. ### Lead people; manage things - URL: https://stuartleo.com/dictionary/lead-people-manage-things Leadership and management are different crafts. You lead people through character and values; you manage things through skills and systems. Held in balance, the tension between them is what carries the load. Lead people; manage things. It sounds like a slogan. It is the load-bearing distinction of the whole method. Leading is influencing beliefs and behaviour — through character and values, and through the craft of change; you lead people. Managing is making sure the right things get done, the right way, at the right time; you manage things — a plan to an outcome. The seven Questions of Leadership sit on the people-and-change side. The five Questions of Management sit on the things-and-execution side. They are the right and left hands of a functioning organisation. Picture a suspension bridge. It carries enormous weight, and it stays stable, because the forces inside it are in tension and in balance. Pull the cables too tight on one side, or let them go slack, and the bridge fails. A business is the same. The tension between executing today and leading toward tomorrow is not a problem to remove — it is the thing holding the structure up. Balanced, the tension is productive: you hit this quarter's plan while building next year's business. ### Values reveal character, character scales culture - URL: https://stuartleo.com/dictionary/values-reveal-character-character-scales-culture The values you live — not the ones on the wall — expose your real character. And character scales: the culture of an organisation is its leaders' character, multiplied. ### Skills scale systems, systems scale efficiency - URL: https://stuartleo.com/dictionary/skills-scale-systems-systems-scale-efficiency The right competencies at each stage build layer upon layer of institutional capability. Systems multiply skilled people; efficiency emerges from systems that skilled people can actually drive. ### Questions are more valuable than answers - URL: https://stuartleo.com/dictionary/questions-are-more-valuable-than-answers Great leaders are defined by the questions they ask, not the answers they hand down. Inquiry creates clarity, accountability and adaptability — and keeps a strategy honest as the world moves. ## C² Method ### P = aic² - URL: https://stuartleo.com/dictionary/p-aic2 Productivity = AI × (Context × Code). A mnemonic, not a law of physics — the "squared" is the two Cs, not a literal exponent. Your output is the AI crew multiplied by the Context and Code you build around it. ### The two Cs - URL: https://stuartleo.com/dictionary/the-two-cs Context and Code — the two systems C² optimises, and the two letters in C². They multiply; if either is zero, productivity collapses. ### Contextbase - URL: https://stuartleo.com/dictionary/contextbase What guides: briefs, patterns, gotchas, decisions. Written as you work, committed to git, read by the AI before it acts. It compounds. ### Codebase - URL: https://stuartleo.com/dictionary/codebase What runs: the software itself. Richer context makes sharper code; cleaner code surfaces sharper context. ### Pilot / Crew - URL: https://stuartleo.com/dictionary/pilot-crew The human is the pilot — sets course, reviews, owns the quality bar. The AI is the crew — writes code, runs tests, manages files. ### Harness engineering - URL: https://stuartleo.com/dictionary/harness-engineering The layer C² operates at — the gather → act → verify loop. The three layers nest: prompt ⊂ context ⊂ harness, each containing the one before. C² is a harness methodology. ### The layer triage - URL: https://stuartleo.com/dictionary/the-layer-triage A diagnostic for what broke, not a stack of what you build: cannot operate → the environment · unreliable → the loop and its stop rule · the process is complex → the topology. Deliberately not the same three as prompt/context/harness. ### The Cascade - URL: https://stuartleo.com/dictionary/the-cascade The six-tier chain every piece of work flows through: Platform PRD → Feature PRD → Prompt Brief → Task → Session Brief → Release Note. It doesn't terminate — it closes back onto the PRD. ### Prompt Brief - URL: https://stuartleo.com/dictionary/prompt-brief The atomic build unit — where the pilot hands off to the crew. Interactive (pilot present) or Autonomous (pilot absent). One brief ≈ one pull request. ### Quality gate - URL: https://stuartleo.com/dictionary/quality-gate The six-item check — goal, scope exclusions, testable AC, non-goals, testing approach, definition of done — every brief passes before execution. ### Bank switch - URL: https://stuartleo.com/dictionary/bank-switch How a PRD compounds without hoarding: each version absorbs the last (v1.0 → v1.1 → v2.0), leaving one live artefact that says where the work is now. ### Node - URL: https://stuartleo.com/dictionary/node One agent doing one bounded job. In C² a node is a Prompt Brief, and the brief is its contract. ### Edge - URL: https://stuartleo.com/dictionary/edge What crosses between two nodes — one agent's output becoming another's input. "And then" is not an edge. Name it by the artefact, not the order. ### Surface - URL: https://stuartleo.com/dictionary/surface Everything an agent mutates or contends for — files, data, external resources, a deploy target. Two agents on one surface is the anti-pattern. ### The concurrency rule - URL: https://stuartleo.com/dictionary/the-concurrency-rule Agents may run concurrently exactly when no edge connects them and no surface is shared. The test is the surface, not the headcount. ### False independence - URL: https://stuartleo.com/dictionary/false-independence Two agents whose briefs never mention each other, colliding over a shared database, a rate-limited API, or one deploy target. A hidden edge. ### Fan-out / barrier - URL: https://stuartleo.com/dictionary/fan-out-barrier Independent nodes running at once is a fan-out. Where their results merge — the integration brief, the PR — is a barrier. A barrier makes everything wait for the slowest, so earn it. ### Isolation - URL: https://stuartleo.com/dictionary/isolation Stopping one node's mess reaching the others — a git worktree per agent. It isolates the filesystem and nothing else. ### The shape - URL: https://stuartleo.com/dictionary/the-shape The fifth part of a filed flight plan: which briefs are independent, which are joined by an edge, where the barrier sits, which edges get verified. ### Anchor - URL: https://stuartleo.com/dictionary/anchor The one signal that decides done, which no agent in the run can produce by asserting it. A test that ran. A query that returned rows. A deploy that resolved. ### Loop on evidence - URL: https://stuartleo.com/dictionary/loop-on-evidence "The agent says it's done" is not a stop condition. Neither is "the review passed" when the review read the builder's own account of the work. ### Frozen rule - URL: https://stuartleo.com/dictionary/frozen-rule A rule marked non-negotiable precisely because it's the one an optimiser would bend to win. Every frozen rule exists because it got bent once. ### Verified edge - URL: https://stuartleo.com/dictionary/verified-edge A result that gets an independent pass before it counts. Independence is mechanical: a different model, inputs the author can't control, and teeth. ### Flight Planning - URL: https://stuartleo.com/dictionary/flight-planning The gate between "I have a PRD" and "I'm running build sessions against it". Five parts: the line, the briefs, the journey, the shape, and an optional red line. ### Closing the Flight Plan - URL: https://stuartleo.com/dictionary/closing-the-flight-plan The landing gate. A filed plan is closed on arrival — the landing, the deviation, the anchor, the learning. Filing spends context; closing makes it. ### The three gates - URL: https://stuartleo.com/dictionary/the-three-gates Flight plan (per PRD, judgement) · pull request (per PR, correctness) · closing (per PRD, judgement). The outer two bookend the build under one owner. ### The sweep - URL: https://stuartleo.com/dictionary/the-sweep Clearing the previous cycle's findings at the bank switch — done by the next flight plan, not by the closing. ### The Router (router.md) - URL: https://stuartleo.com/dictionary/the-router-router-md The file your agent reads first — the living index of the contextbase. Named for your agent. Links rather than embeds. ### Knowledge index - URL: https://stuartleo.com/dictionary/knowledge-index The index of 03-knowledge the Router points to. The AI reads the index, not every file. ### Learn loop - URL: https://stuartleo.com/dictionary/learn-loop Capture discoveries fast during a session, then periodically consolidate them into 03-knowledge and the Router. ### Compaction - URL: https://stuartleo.com/dictionary/compaction Keeping the working context lean. C² does it three ways: the Session Brief, the Router, and the Learn loop. ### Lead agent - URL: https://stuartleo.com/dictionary/lead-agent Executes — reads context, writes code, manages git, writes briefs. One leads per codebase surface. ### Bench agent - URL: https://stuartleo.com/dictionary/bench-agent Reviews, never executes. Independent second opinion on PRDs, security, architecture. Budget-capped. ### Specialist agent - URL: https://stuartleo.com/dictionary/specialist-agent A scoped subagent for repeatable tasks — QA review, release notes, security review. ### WIP cap - URL: https://stuartleo.com/dictionary/wip-cap Max five in-progress PRDs. Anything above goes to backlog — forces completion before starting. ### Brief-before-active - URL: https://stuartleo.com/dictionary/brief-before-active A PRD can't go in-progress without at least one Prompt Brief. If you can't write a brief, it's a thinking document. ### Monthly PRD review - URL: https://stuartleo.com/dictionary/monthly-prd-review A 30-minute monthly pass: walk every in-progress PRD; force-move stale ones to backlog.