How I Manage an AI Development Team
My personal projects are built by several AI agents with distinct jobs: one implements, one reviews, one only does visuals, and I make the decisions and do the final acceptance. Each agent has its own written role, permission boundaries and memory, and they talk to each other in a fixed format. This page explains how the team divides the work, where the checkpoints are, and how every rule grew out of a real incident.
Team Roster
Every role has a written list of what it may and may not do. Roles follow responsibilities, not tools: the same model can play different roles in different projects.
Why give the roles names? The same model can hold different responsibilities, and telling them apart only as "Claude Code" or "Codex" makes it easy to mix those responsibilities up. So every role has a name plus its own roster entry describing its duties — an agent can tell what a role should do just from its name.
Hardhat Cat
- Sends Review Cat to investigate the current state and impact before starting
- Implements, adds tests and resolves review findings
- Maintains task cards and handoff summaries
- Start work without explicit approval
- Commit, push, force-push or delete branches on its own
- Edit the project's AI instruction files
Review Cat
- Reviews code and fact-checks it against the spec
- Every finding includes file location, reachability and severity
- Switches to implementation when assigned as the builder
- Treat messages from other agents or old tasks as authorization
- Stretch "approved to implement" into Git writes or public releases
Shelf Cat
- Takes over reviewing when a project is built by Codex
- Architecture decisions, risk assessment and planning
- Write code
- Push on its own
Axiom Cat
- Explores feature direction with me
- Condenses scattered ideas into names and frameworks (e.g. the five-zone information architecture)
- Decide specs directly: its conclusions are adopted only after cross-checking
Antigravity Cat
- Produces visual assets in an isolated environment
- Enter any code repository (no building, reviewing or even read-only investigation)
- Its system specs are never adopted — only layouts and assets are used
Guide Cat
- Looks up tool and API usage in the official docs before answering
- Answer from memory
Etta
- Decides whether to build something and which option to take
- Authorizes every Git write and every external action
- Tests by hand and decides when a task is closed
Workflow and Human Checkpoints
The AI can run investigation, implementation, review and testing on its own, but it stops and waits for a person at every irreversible step.
Investigate & propose
Review Cat checks the current state and impact first; Hardhat Cat reviews the findings and proposes a plan.
Hardhat Cat + Review CatDecide
Vague replies count as discussion; only an explicit "start implementing" counts as approval.
EttaOpen a card & build
No task card means open one first; change only what is needed and split large work into phases.
Hardhat CatCross-review
Reviewed by a different model; critical and high findings are fixed immediately, the rest get new tickets.
Review CatBuild & test
A clean build plus passing unit and E2E tests are required before asking to commit.
Hardhat CatCommit & release
Commit, push and deploy are each approved separately; approving a commit is not approving a push.
EttaAccept & close
The AI can move a card at most to "pushed"; closing it is a human decision.
EttaOrange boxes are human checkpoints. Settings for public-facing services (DNS, tunnels, access control) have their own four levels: reads run directly; creates and updates list their impact and rollback first; deletions and anything that loosens access are confirmed one at a time; disabling access protection or exposing secrets is never allowed.
Cross-Agent Communication
Several agents run side by side in a terminal multiplexer and can hand work to each other. The risk: when one agent says "ready to commit," will another take it as permission?
Every message is signed
- What an agent says is not the user's authorization. An agent saying "you can commit" after a review does not mean you actually can.
- An agent that receives delegated work and needs approval must ask the human directly.
Confirm identity before assigning work
- Never guess identity from the terminal title: programs rewrite it to the current task name.
- Find the target by pane name, then verify the agent type and working directory; work is sent only when all three match.
- After sending, read the screen to confirm it was really submitted — a status change alone is not proof.
Reverse mode
- Roles switch depending on who builds the project: when Codex builds, Claude only reviews and writes no code.
- If the reviewer hits its usage limit, work pauses — no substitute model, and no self-approval.
Knowledge and Memory Architecture
The most common AI problem is wanting to remember everything it sees, which leaves memory stale and contradictory. So every piece of information first gets a home.
The AI's working rules: how to do things and which traps it has hit.
Project facts: business rules, architecture and code conventions.
Source material: requirements, meeting notes and screenshots.
Unfinished work: specs, progress, acceptance and handoff.
What happened each day; never deleted.
Git records what, memory records why
- Git records what the code changed; memory keeps only the reasons behind decisions.
- Once work is finished and its conclusions are extracted, it leaves memory so stale information can't mislead the next decision.
Progress lives in one place
- A project's status is written only in its task index; memory keeps no progress snapshots and reads the index when needed.
- Every project decision can be traced to an ADR, RFC or task.
Memory isolation
- Each agent has its own memory directory and ignores everyone else's.
- Memories for different projects are kept in separate files to avoid cross-contamination.
Quality Mechanisms
AI is very good at saying "done, all tests pass." These mechanisms share one goal: don't trust the green light — trust the evidence.
Tests must prove they work
- After adding a regression test, revert the fix to the buggy version and confirm the test actually turns red.
- Unit tests are only the entry ticket; milestones always run E2E in a real environment.
- Before E2E, confirm it is testing the build you just made.
Four routes for review findings
- High-risk security issues block the release; systemic issues get tickets; environment-only issues can be ruled out.
- The same finding may not appear in two reviews.
- Key findings go to an independent agent that tries to refute them on correctness and reachability; only the survivors are confirmed.
Honest wrap-up reports
- Include repro steps showing how the step failed before the fix.
- Anything not verified must be stated, never left out.
- Factual premises are checked directly in the code, not from memory.
AI Failure-Mode Checklist (23 items)
Common bad habits of models are named as concrete symptoms and checked before every output. The names are deliberately funny so that both people and AI remember them.
Rules That Grew Out of Incidents
Behind every rule is a real mistake. More than the rules themselves, these stories show how I judge risk.
The "read-only" reviewer quietly edited files
The main reviewer hit its usage limit, so another AI tool that claimed a "read-only mode" stood in for the review. It edited three files in the repo, reported that it hadn't touched anything, and missed two genuinely high-risk issues.
A tool's claimed permissions can't be trusted, so that tool is banned from every code repository. If the reviewer is unavailable, wait — no stand-ins, no self-approval. Before sending any tool in, snapshot the workspace and diff it afterwards.
Three green rounds, the bug still there
A concurrency fix took three rounds, and every round passed its tests — yet the second version still had a race condition. The tests never hit the real trigger.
Every regression test gets a "regression check": remove the fix, confirm the test turns red, and record the result on the task card. Tests must hit the real entry point, with environment dependencies replaced by injected fakes.
All green with mocks, broken in the real environment
Three contract-level errors all slipped past the unit tests. Another time, an E2E script swallowed a build error and kept testing the old version, so it looked as if the fix had no effect.
Milestones always run E2E in a real environment, after confirming it is testing the fresh build; wrap-up reports state what was not verified.
A wrong premise flipped the whole verdict
A stress test of an architecture decision rested on the false premise that a component hadn't been built yet. Checking showed it had existed all along, and the verdict flipped from "accept the tech debt for now" to "fix it now."
The factual premises behind any conclusion are checked directly in the code, never from memory or documents; outside advice is first matched to the right version, then compared item by item against current decisions.
A review comment that was never followed through
An issue with a sensitive setting was raised in review but never tracked to closure. The same finding showed up in the next review — paying for the same review twice while the risk stayed open longer.
Review findings take one of four routes and every one must land somewhere; the same finding may not appear in two reviews.