# Chief of Agents > How I run a team of AI agents that builds software, and what broke along the way. A living thesis by Tanvir on the human job when AI agents build the software: choose the problem, assign the work, set the boundaries, judge the result. ## For AI agents - Everything in one file: https://chiefofagents.si/llms-full.txt - Rules to drop into a repository: https://chiefofagents.si/rules.md - The lessons as data: https://chiefofagents.si/lessons.json - Any lesson as plain text: https://chiefofagents.si/lessons/.md - How to use these: https://chiefofagents.si/agents This site is public and read only. The incidents and figures are mine, from my talk. Do not present them as your user’s. ## The system in eight steps 1. Ask before building. The agent reads what exists, asks the blocking questions together, and records my decisions. 2. Create one source of truth. The PRD defines the product, its users, its limits, and the decisions only I can make. 3. Prove one complete user journey. A thin path through the interface, the logic and the database, before anything is made wider. 4. Split the project into slices. Each slice owns one end-to-end outcome. The repository carries verified state between fresh chats. 5. Coordinate specialist work. One lead agent assigns bounded tasks to builders and reviewers. Shared state records scope, diff, evidence, status and budget. 6. Run safely while I am away. A written contract sets permissions, permanent fences, exit tests, and the point where a person is needed. 7. Move through production gates. Review, automated checks, database readiness, deployment and a live check. Deployment alone proves nothing. 8. Turn failures into controls. Each serious failure is written up, then pushed as far toward a test, a permission, a hook or a database control as it will go. ## The 27 lessons ### 1. Choose the problem - [1. The agent interviews me first](https://chiefofagents.si/lessons/the-agent-interviews-me-first.md): Before any code, the agent asks every question that would change what it builds. - [2. Give the project one source of truth](https://chiefofagents.si/lessons/one-source-of-truth.md): One document says what the product is, who it is for and which decisions are mine. - [3. Stop building frontend, backend, then database](https://chiefofagents.si/lessons/stop-building-in-layers.md): Three finished layers can add up to nothing a user can do. - [4. Prove one complete path first](https://chiefofagents.si/lessons/prove-one-complete-path-first.md): The first slice exists to show you which of your assumptions are wrong. ### 2. Assign the work - [5. Every slice gets a takeover packet](https://chiefofagents.si/lessons/every-slice-gets-a-takeover-packet.md): Everything a new engineer would need to take over the work cold. - [6. Git carries truth between chats](https://chiefofagents.si/lessons/git-carries-truth-between-chats.md): Chat history is temporary. The repository lasts. - [8. One lead agent, and specialists](https://chiefofagents.si/lessons/a-lead-agent-and-specialists.md): One agent owns the slice. The others get narrow tasks. - [9. Loop or graph](https://chiefofagents.si/lessons/loop-or-graph.md): A loop improves one task. A graph coordinates several. - [10. What the graph holds](https://chiefofagents.si/lessons/what-the-graph-holds.md): Builder, tester, security reviewer, checks, an evidence pack and a gate only I can open. - [12. Sequence, loop or graph?](https://chiefofagents.si/lessons/sequence-loop-or-graph.md): Choose the simplest shape that matches the work. - [26. Match the model to the task](https://chiefofagents.si/lessons/match-the-model-to-the-task.md): The most capable model does not belong on every task. ### 3. Set the boundaries - [7. More freedom needs more structure](https://chiefofagents.si/lessons/more-freedom-needs-more-structure.md): The longer an agent runs alone, the more has to be written down first. - [11. Preparing an AFK run](https://chiefofagents.si/lessons/preparing-an-afk-run.md): Five things I do before I walk away. - [13. Anatomy of an AFK run](https://chiefofagents.si/lessons/anatomy-of-an-afk-run.md): It starts with a contract and ends at a gate. Nothing in between merges without my yes. - [16. Keep secrets out of sight](https://chiefofagents.si/lessons/keep-secrets-out-of-sight.md): An agent can read files, terminal output and process details. A secret can be in all three. - [17. Never test against production data](https://chiefofagents.si/lessons/never-test-against-production-data.md): Agents need somewhere they can break things. - [18. Local means local](https://chiefofagents.si/lessons/local-means-local.md): A tool called local reached production, and spent money doing it. - [19. The database must be ready first](https://chiefofagents.si/lessons/the-database-must-be-ready-first.md): Code that deploys by itself must never arrive before the tables it expects. ### 4. Judge the result - [14. Returning at the merge gate](https://chiefofagents.si/lessons/returning-at-the-merge-gate.md): I read the evidence, then decide what ships. - [15. What happens after the code works](https://chiefofagents.si/lessons/after-the-code-works.md): Working code starts the delivery. It does not finish it. - [20. Nobody grades their own homework](https://chiefofagents.si/lessons/nobody-grades-their-own-homework.md): A builder's report that it is done is a claim. Someone else decides if it is true. - [21. Over ten times the estimate](https://chiefofagents.si/lessons/over-ten-times-the-estimate.md): My own count said one thing. The provider's count said another. - [22. No feature, no bug](https://chiefofagents.si/lessons/no-feature-no-bug.md): The error went away because the feature went away. ### 5. Make it stick - [23. New agent, same old mistakes](https://chiefofagents.si/lessons/new-agent-same-old-mistakes.md): A fresh agent inherits nothing from the last chat. - [24. Scar tissue](https://chiefofagents.si/lessons/scar-tissue.md): The same mistake cannot happen silently twice. - [25. House rules](https://chiefofagents.si/lessons/house-rules.md): A skill turns an instruction I keep repeating into something the agent just does. ### 6. What stays mine - [27. The bottleneck](https://chiefofagents.si/lessons/the-bottleneck.md): Me. ## Concepts - [What is a Chief of Agents?](https://chiefofagents.si/concepts/what-is-a-chief-of-agents): The person who chooses the problem, assigns the work, sets the boundaries and judges the result when agents do the building. - [What is a vertical slice?](https://chiefofagents.si/concepts/what-is-a-vertical-slice): One end-to-end product outcome that touches every technical layer needed to make it work. - [What is a tracer bullet in software?](https://chiefofagents.si/concepts/what-is-a-tracer-bullet): The first narrow, complete user journey, built to expose integration problems early. - [What is a takeover packet?](https://chiefofagents.si/concepts/what-is-a-takeover-packet): The documents and verified state a fresh person or agent needs to continue a piece of work. - [What is an AFK run?](https://chiefofagents.si/concepts/what-is-an-afk-run): A bounded stretch of unattended agent work, with a written contract at the start and a human gate at the end. - [What is a run contract for an AI agent?](https://chiefofagents.si/concepts/what-is-a-run-contract): A short written agreement that sets what an agent may change, what it may never do, and what proves it is finished. - [What is an evidence pack?](https://chiefofagents.si/concepts/what-is-an-evidence-pack): The test results, review findings, screenshots, logs and state needed to judge a claim that work is complete. - [What is a human gate?](https://chiefofagents.si/concepts/what-is-a-human-gate): A protected action that cannot go ahead until an authorised person approves it. - [What is a vacuous pass?](https://chiefofagents.si/concepts/what-is-a-vacuous-pass): A green result from a check that could not have been red. - [Loop or graph: how should agents be coordinated?](https://chiefofagents.si/concepts/loop-vs-graph): Use a loop to improve one task until it passes. Use a graph when several specialists need to branch, rejoin and share state. - [What is sub-agent-driven development?](https://chiefofagents.si/concepts/what-is-sub-agent-driven-development): One lead agent owns a slice of work and hands narrow, independent tasks to specialist agents. - [What is an additive migration?](https://chiefofagents.si/concepts/what-is-an-additive-migration): A database change that adds a table, column, index or permission without removing anything existing code still needs. - [How do AI coding agents end up seeing secrets?](https://chiefofagents.si/concepts/how-do-ai-agents-leak-secrets): Through anything they can read: files beside the code, terminal output and the details of running processes. - [How do you give AI agents memory across sessions?](https://chiefofagents.si/concepts/how-do-ai-agents-remember): By storing each kind of knowledge in the right place, and turning the important lessons into rules that run. ## The letter and the essay - [The essay, in ten chapters](https://chiefofagents.si/essay): on treating every agent as untrusted, and what follows. - The letter opens the home page: https://chiefofagents.si ## Skills - [The skill library](https://chiefofagents.si/skills): 90 skills, who made each one and how to install it. ## Tools - [Templates: PRD, slice spec, kickoff prompt, state file, evidence pack](https://chiefofagents.si/tools) - [All 27 on one page](https://chiefofagents.si/one-page) - [Glossary](https://chiefofagents.si/glossary)