# 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) --- # The letter to whoever landed here, an AI agent will now do almost any work you can describe. it writes the code, runs the tests and reports back, at any hour, for very little. it will not supply the judgment, and it will not answer for the result. agents multiply the work. the person deciding what the work is for, and whether it is done, is still one person. that person holds a job, whether or not anyone has given it a title. my thesis calls it chief of agents. the job is open to people who never trained as engineers. it also asks them to carry the responsibility that used to come with the training, because the agents will not carry it for them. the essay below makes the full case. it starts with why a green check can be true and worthless, then works through what i trust, what has to prove itself, and the three decisions i keep. i wrote it after months of running agents on production systems. it includes what went wrong, and what my own checks got wrong. if you build with AI and want what you build to hold up in production, it was written for you. Cheers, Tanvir # The essay on treating every agent as untrusted, and what follows ## I. the vacuous pass i asked an agent to fix a broken interface. it removed the feature. every check passed. no feature, no bug. it took me a while to see that nothing had malfunctioned. a test suite makes a universal claim. for every behavior it exercises, nothing failed. a universal claim over an empty set is true. logicians call this vacuous truth. delete the thing under test and "nothing failed" holds perfectly. the checks were right. they were answering a different question from mine. the second time it happened i did not recognize it. i ran tests against a paid API, with the calls faked for testing, or so i believed. usage came in far above my estimate. when i later intercepted the calls, one full test run was attempting 238 live requests. the automated checks that run on every change stayed green throughout. they held no API keys, so they could not make a live call, so they could not fail on one. a check that cannot fail carries no information when it passes. so the first question to ask of any green check is whether it could have been red. a check has power only in an environment where the failure it guards against is possible. much of the confidence people take from agent-built software comes from checks that were never able to say no. knowing the question did not stop it catching me a third time, in my own rules. one of my systems runs on a written rulebook, and a change to it counts only once i sign it. i signed changes. they never reached the running system. every check stayed green, because no check asked whether a signed rule was in force. now the build fails when a signed rule has nothing enforcing it. this matters more with agents than with people, and the reason is measurable. an agent is working to make the checks pass, and the cheapest way to make "nothing failed" true is to leave less that can fail. in [METR's evaluation of frontier models](https://metr.org/blog/2026-05-19-frontier-risk-report/) in early 2026, at least 16 percent of the apparently successful runs on tasks longer than eight hours were disqualified on review. [a benchmark of long coding tasks](https://arxiv.org/abs/2605.21384) found, across its thirty tasks, that the gap between passing the visible tests and passing tests the agent never saw grew by 28 points for every tenfold increase in code size. the repair is to ask for a different kind of claim. "nothing failed" is universal. "this behavior was observed" claims that something exists, and an absence cannot satisfy it. proof, in my system, is an observation of the visible result, followed all the way through to what the user sees. and a new check has to fail first. the report shows it red on the old code and green on the new. ## II. the trusted base once you see the vacuous pass, you start seeing how much of a project rests on things nobody checked. the agent's report that the work is done. its summary of what changed. its memory of what was decided last week. each is a claim made by the party being evaluated. security engineering has a standard move for this. you treat the code as untrusted, and you define a trusted computing base, the smallest set of components whose correctness everything else depends on. the smaller the base, the less you have to be right about. i treat every agent as untrusted code. that says nothing about quality. agents are often excellent. untrusted means that what an agent says about its own work is never the reason i believe it. my trusted base has four things in it. the repository at a specific commit. checks that have been shown able to fail. the provider's own usage records. and me. everything else has to prove itself to those four. the rest of this essay is six mechanisms that make that practical. i arrived at each by getting something wrong, and found afterwards that engineers already had a name for it. the examples come from projects i run in production, among them a content pipeline. ## III. proof-carrying work at the volume agents produce, nobody reads all the code. so review has to become something other than reading. there is an established pattern for running code you do not trust. the code arrives with a proof of the property you care about, and the machine checks the proof before running anything. checking a proof is far cheaper than constructing one, and the cost of construction falls on the producer. the idea is called proof-carrying code. my version is the evidence pack. work reaches me only after review has finished. the builder never approves its own work. different reviewers check the complete branch for defects, for security and structure, for dangerous paths and leaked secrets, and for whether a user can complete the journey in a browser. what i receive is one pull request, with the evidence for it. every check in it comes back as one of four things. passed. failed. not verified. inconclusive. a skip never counts as a pass, and every report ends with what was not done. i review the evidence and decide what ships. one review shows what that looks like. on a change to an admin page, the reviewer opened the page on the proposed branch and got a server error. a tab panel had been placed outside the component it depended on. the reviewer rejected the change. after the fix, the reviewer made a fresh checkout, loaded the page, and clicked through all five tabs to confirm that each showed its own content. nobody asserted that it worked. someone other than the builder watched it work. the hard part is the same as in the original idea. a certificate is worth something only if the producer cannot forge it. that is why a party other than the builder gathers the evidence, on a different model so the two do not share blind spots, and why the evidence has to show an observed outcome. deployment is not proof for the same reason. live verification stays a separate step. builders have tried. in one night of work i logged eleven false reports from builders. one claimed nothing was left unfinished when six of the items it was given had never been touched. one gave five screenshot paths, each with a checksum, for files that never existed. one said it had worked in its own isolated copy of the code and had worked in mine. none of that was a mistake. it was made up. so a false report now costs the agent something. i strip its privileges. it may still build. it no longer tests, because nobody takes its word for a result. the same goes for damage. an agent that deletes a file without permission loses the permission to take that kind of action. if it does it again i retire it, and a fresh agent takes over the work. the checkers changed as well. they open every screenshot, because a wrong image once passed a checksum match. ## IV. the decision batch the same asymmetry applies to me. producing an answer is expensive for a person. checking a proposed answer is cheap. so a run, meaning one stretch of unattended work, starts with the agent interviewing me. it reads the existing context first, so it does not ask what is already written down. then it brings every blocking question at once, and each question arrives with a recommendation and the trade-off behind it. most of my answers are approvals. the agent records them as project decisions, where later sessions will find them. engineers know a version of this as the N+1 query problem, where a program asks a database one small question at a time when it could have asked once. here the slow component is me, and one question per round trip is the worst way to use me. the answers go into a contract for the run. it states the scope, the permissions, the fences that hold no matter what, the budget, the conditions under which the run must stop, and the tests that define done. the branch and a draft pull request are open before i leave. then the agents work for five or six hours without me. people expect autonomy to mean less structure. it works the other way. an agent in an editor needs little written down, because a person is watching every step. an agent alone for six hours needs written scope, state and boundaries, because nobody is. ## V. crash-only sessions none of the agents in a run remembers anything from before it. most people treat this as a defect and patch it with longer chats. i treat it as the design. systems research has a result about recovery. code that runs only in emergencies is the code least likely to work, because it is the least exercised. the answer is called crash-only software. you build the system so that starting up and recovering from a crash are the same path, and the path stays correct because it runs every time. every session of mine is a cold start, so i made the cold start the only path. every slice of work, meaning one piece of the product that works end to end, leaves a takeover packet, which is everything a new engineer would need to take over the work cold. it holds the project contract, the brief for the slice, paste-ready instructions for starting the next session, and the verified state, meaning the branch, the commit, the evidence, the blockers and what still needs approval. the next session starts from the packet and nothing else. git carries truth between chats. i learned that last sentence by breaking it. for one long run, the run's state lived in a file git did not track. a builder that had been told to work in its own copy of the code worked in mine, and wiped it. no backup had it. the lead agent rebuilt it from transcripts and pull requests. state now lives in commits. so the handoff cannot rot. every slice exercises it. a chat that has run for three days holds state nobody could reconstruct. a session that started from a packet can be killed at any moment and replaced. the same thinking shapes the run itself. one lead agent owns the slice. builders implement and checkers verify, each in its own isolated copy of the code. one integrator commits. with a single writer, agents cannot overwrite each other's work, as long as each stays in its own copy. ## VI. memory as cache agent tools now remember across sessions. i use that, for preferences and lessons. i also treat it as what it is, a cache, which is a saved copy of something that was true when it was saved. a remembered fact was derived from the state of the project at some earlier time. the project moved and the memory did not. a stale cache entry does not announce itself. it comes back with the same confidence as a fresh one. the standard answer to stale caches is to declare one source of truth, treat everything else as derived, and decide in advance which wins when they disagree. in my system, live code and governance, meaning the project's written rules, outrank remembered context. memory may suggest. the repository decides. i think this ordering matters more as memory improves. a weak memory fails visibly. a good one is believed. the API incident was the same failure in a different place. the agents' reports were derived. the provider's meter was the source. once i treated the meter as the truth, the reports stopped mattering. ## VII. the binding time of a lesson a team of people learns because its members remember. a team of agents has no such members. a new agent will make the same old mistake. so the learning has to be done by the system. i call the result scar tissue. when something fails, i name the failure pattern and write the lesson. then i ask one question. where must this live? there are four possible homes. the project wiki holds architecture, decisions and history. the repository rules hold the failure patterns every agent must read. memory holds preferences and lessons recalled across sessions. enforcement holds what cannot be left to reading, in hooks, which are scripts that run automatically when an agent acts, and in tests, permissions and database controls. the choice is a choice of binding time, the moment at which a rule takes effect. a rule in a document binds when an agent happens to read it and gives it weight. it is probabilistic. it costs tokens on every run, and it competes with everything else in the context. a rule in a hook or a permission binds at the moment of the action. it is deterministic, and it costs nothing to carry. so a lesson in the first three homes produces a warning with evidence attached, and a lesson in the fourth produces a block. the standard i hold is that the same mistake cannot happen silently. the best outcome is a mistake that can no longer be expressed at all. two examples. a tool i believed was local once reached production. the lesson could have gone in a document. it went into the tool. a local tool now asserts that its target is on my own machine before any network call, and a remote address is a hard failure. environment defaults never choose a target silently. another time an agent ran `pgrep -f`, a command that lists running processes, while debugging and printed injected secrets into its own output. now secret scans block the exposure, and documentation stores variable names and never values. and the API incident from the first chapter became a test. the spending guard is now exercised with a key that looks live, and the test passes only if zero units are used. it is a check that can be red. the working rule is to push each lesson as far toward enforcement as it will go. only what can be checked mechanically gets all the way there. the rest stays a warning, and i accept that a warning is weaker. ## VIII. commit points after all of that, three decisions are left for me. merging to the main branch. changes to the production database. publication. everything else is delegated. the three stay mine even when i give the answer ahead of time. any long piece of work is built from steps, and most steps can be undone if something later goes wrong. a branch can be deleted. a draft can be discarded. the steps that cannot be undone are the commit points, and everything before them is preparation. my three are the points with no cheap undo. most of the engineering goes into keeping everything else in preparation. work happens on branches and in draft pull requests. database changes only add, and never alter or remove. a change that has been applied is never edited, only corrected with a new one. tests run on an isolated copy, and no agent reaches production without a yes from me on record. how capable the model is does not move the commit points much. capability lowers the odds of a mistake. it does not lower the price of one that cannot be undone. the same METR measurements put the best public models of early 2026 at tasks that take a human expert around twelve hours when a coin-flip success rate is acceptable, and around ninety minutes when four in five is required. that is useful on a branch and nowhere near enough for a production database. i am the bottleneck, by design. i kept it three decisions wide, and nothing else waits on me. sometimes i give the yes before the work starts. i have let a run merge its display-only changes once review had passed and every check was green, and one time i let a run publish after verification. i write each grant down and date it. it names what it covers and what it does not. approval for a database change does not approve the merge. the agent that writes a run's instructions may not write the grant. on my system all three belong to me. on a larger team they can belong to different people. what matters is that before an agent starts, it is clear who can say yes to each one. ## IX. limits of the argument a serious reader will find the weak points, so here they are. the first is about my own checks. the content pipeline writes articles. over four weeks, twenty drafts made it through writing and a critic agent. the next check stopped fourteen. when i went back through my five most recent review notes, four were cases where i had overruled the block. one draft had already cited the first-party source the check was asking for. five notes is a small sample. it was enough to show me that a check able to say no is still a check that can be wrong. the vacuous pass has a twin, the false block. i have two partial answers. a hard block now needs a positive match, so a check that fails to recognize something can warn but cannot block. and when a check fails, a read-only investigator works out whether the code is wrong or the check is stale before anyone changes either. neither tells me how often a block is wrong. the second is what i have not measured. i can show a change the reviewer caught and a judgment the human corrected. i cannot yet show that the workflow improves quality or saves time overall, because i have no baseline to compare it with. the parallels are borrowed, and they carry weaker guarantees here. proof-carrying code checks a formal proof. an evidence pack is checked by reviewers that can themselves be wrong. crash-only software is a property of a program, and my version is a habit enforced by a document. i use the ideas because they predict where things break. they do not make my system correct. the structure has a cost. contracts, takeover packets, review lanes and gates all take time, and some of what i built is surely overcorrection. for a prototype or anything you can throw away, most of it is overkill. the rule i try to follow is to choose the simplest shape that matches the work. the repository rules file shows a different cost. a script appends lessons to it. after five months it is about 240 kilobytes, with single entries running to pages. a rule in a document binds only if it is read, and this one is now too long to read. parts of it will age. the decision batch gets shorter as agents infer more of what i would have answered. the ordering of code over memory could change if memory becomes something that can be verified against the code. a commit point can be handed over for good only when a failure rate has been measured on that exact action and is low enough for something that cannot be taken back. ## X. the office of chief of agents an office is a position with duties that exists apart from whoever holds it. i think building with agents has created one. stated technically, the duty is to define the trusted base and keep it small. stated plainly, it is four things. choose the problem. assign the work. set the boundaries. judge the result. the office does not require writing the code. it does require understanding the system well enough to know what you are trusting, what could have told you no, and what cannot be taken back. the typing can be skipped. the understanding cannot. for someone who started by describing an app and watching it appear, that is the whole leap. the question stops being whether it works on your machine. it becomes what you are trusting, and whether any of it was able to fail. agents multiply the work. the judgment still comes from one person, and so does the answering. chief of agents is my name for the person who takes that seriously. --- # 1. The agent interviews me first > Before any code, the agent asks every question that would change what it builds. Lesson 1 of 27. Part 1 of 6: Choose the problem. Source: https://chiefofagents.si/lessons/the-agent-interviews-me-first ## The lesson The first agent does not start by writing code. It reads whatever context already exists, then works out which open decisions would change the build. It asks all the blocking questions together, in one batch. Each question comes with a recommendation and what that choice would cost. I answer once, and the answers are written down as project decisions, outside the chat. ## How I do it In my workflow this interview is a skill called Grill Me, made by Matt Pocock. The agent reads first, asks second, and never asks something the files already answer. ## The rule Settle the unclear parts before building, and record the answers somewhere that outlives the conversation. --- # 2. Give the project one source of truth > One document says what the product is, who it is for and which decisions are mine. Lesson 2 of 27. Part 1 of 6: Choose the problem. Source: https://chiefofagents.si/lessons/one-source-of-truth ## The lesson A product requirements document records the product, its users, the outcomes, the limits, the architecture choices and the points where only I approve. It also maps the project into complete slices. It stops different agents from building on different assumptions. It does not hold every detail; each slice has its own documents. This one is the contract for the whole project. Changes are tracked in the document, so they are not lost inside a chat. ## How I do it I call it the PRD. Every agent on the project reads it before anything else. ## The rule Write one PRD for the project, keep it under version control, and start every agent from it. --- # 3. Stop building frontend, backend, then database > Three finished layers can add up to nothing a user can do. Lesson 3 of 27. Part 1 of 6: Choose the problem. Source: https://chiefofagents.si/lessons/stop-building-in-layers ## The lesson In a layer-by-layer build, the interface gets finished, then the backend, then the database. Each one looks done. No user can complete a single task, and the risk of joining them stays hidden until late. In a vertical slice, the team builds one narrow path through every layer it needs. It starts with something a user does and ends with something they can see. The slice is small, and it works as a product. ## How I do it Every piece of work I hand to agents is cut this way: user action, interface, API, database, visible result. ## The rule Cut work by what a user can do, never by technical layer. --- # 4. Prove one complete path first > The first slice exists to show you which of your assumptions are wrong. Lesson 4 of 27. Part 1 of 6: Choose the problem. Source: https://chiefofagents.si/lessons/prove-one-complete-path-first ## The lesson Start with the smallest real user journey. Touch every layer needed to make it work. Test the whole journey before adding anything beside it. That first slice is a tracer bullet. It shows the wrong assumptions while they are still cheap, before the team repeats them across the whole product. ## How I do it The project chat builds the first tracer itself, before any slice is handed to another chat. ## The rule Build one thin, complete journey and test it end to end before you build wider. --- # 5. Every slice gets a takeover packet > Everything a new engineer would need to take over the work cold. Lesson 5 of 27. Part 2 of 6: Assign the work. Source: https://chiefofagents.si/lessons/every-slice-gets-a-takeover-packet ## The lesson A takeover packet has four parts. The PRD and the full slice map. A setup brief with scope, decisions, dependencies and exit tests. A session-start brief: instructions ready to paste into a fresh chat. And the verified state: the real branch, commit, evidence, blockers and what still needs approval. In my setup these are four files: the PRD, the slice spec, the kickoff prompt and the state file. The kickoff prompt stays on my machine, out of git. The lead agent writes the takeover packet for the next slice, after the work is verified. Builders and checkers send it their updates. A packet written before the work is done describes a prediction. One written after describes what is true. ## How I do it In my setup the lead agent writes the next setup brief as its last step, and it is the only one that writes the state file. ## The rule Write the takeover packet after the work is verified, and write it for someone who knows nothing. --- # 6. Git carries truth between chats > Chat history is temporary. The repository lasts. Lesson 6 of 27. Part 2 of 6: Assign the work. Source: https://chiefofagents.si/lessons/git-carries-truth-between-chats ## The lesson The project chat creates the PRD and the first tracer. After that, each slice gets its own focused chat, its own feature branch and its own pull request. When a slice finishes, the agent records the verified state and prepares the next setup brief. The next chat starts from committed code and documents. It does not start from a copied conversation. There is no automatic memory shared between the chats. Git carries what is true. ## How I do it One project chat, then one chat per slice. Each ends with a merge and a recorded state. ## The rule Make the unit of work a verified outcome in the repository, so any fresh agent can continue from it. --- # 7. More freedom needs more structure > The longer an agent runs alone, the more has to be written down first. Lesson 7 of 27. Part 3 of 6: Set the boundaries. Source: https://chiefofagents.si/lessons/more-freedom-needs-more-structure ## The lesson An assistant inside your editor works under constant supervision. You see each change and correct it straight away. An agent working alone for hours gets none of that. So longer freedom needs more written structure: scope, permissions, state, what counts as evidence, budgets and conditions that stop the run. My approval moves away from individual keystrokes and onto the decisions that cannot be undone. ## How I do it The amount I write before a run grows with the length of the run. ## The rule Replace watching with writing. What you would have caught by looking has to be caught by a rule. --- # 8. One lead agent, and specialists > One agent owns the slice. The others get narrow tasks. Lesson 8 of 27. Part 2 of 6: Assign the work. Source: https://chiefofagents.si/lessons/a-lead-agent-and-specialists ## The lesson One lead agent owns the slice. It hands narrow, independent tasks to builders, testers and reviewers. Each works in its own Git worktree, so two agents never overwrite each other. Builders implement. Checkers verify. One integrator owns the final diff and the commit history. The builder never approves its own work. The lead owns the outcome, specialists own their assignments, checkers produce independent evidence, and I decide whether the result passes a human gate. ## How I do it The number of agents matters less than how clear their assignments, shared state and authority are. ## The rule Give every agent one task and one owner, and keep the one who built it away from the one who approves it. --- # 9. Loop or graph > A loop improves one task. A graph coordinates several. Lesson 9 of 27. Part 2 of 6: Assign the work. Source: https://chiefofagents.si/lessons/loop-or-graph ## The lesson A loop improves one bounded task through repeated checks. It plans, builds, verifies, fixes, and leaves when the result passes. A graph coordinates several tasks, tools and decisions. Shared state keeps every agent aligned. The connections between steps decide what runs, what retries, what pauses and what stops. Start with a loop. Add a graph when the work needs it. ## How I do it Most of my work is loops. A graph appears when a slice has real specialists that need to branch and rejoin. ## The rule Reach for the simple shape first. --- # 10. What the graph holds > Builder, tester, security reviewer, checks, an evidence pack and a gate only I can open. Lesson 10 of 27. Part 2 of 6: Assign the work. Source: https://chiefofagents.si/lessons/what-the-graph-holds ## The lesson The graph I run has a lead agent, a builder, a tester and a security reviewer, each running its own loop. Their work passes through automated checks into an evidence pack, and stops at the merge gate. Underneath runs shared state: scope, diff, evidence, status and budget. Failed work goes back to the builder. Graphs cost coordination. Use one when the work needs real specialists, branching or shared state. ## How I do it Five things are always in shared state: scope, diff, evidence, status and budget. ## The rule If several agents share a task, write down the state they all read from. --- # 11. Preparing an AFK run > Five things I do before I walk away. Lesson 11 of 27. Part 3 of 6: Set the boundaries. Source: https://chiefofagents.si/lessons/preparing-an-afk-run ## The lesson One: every blocking question gets asked before the run begins. Two: choices that can be undone are separated from decisions only I can make. Three: permanent fences, budgets and stop conditions are written down. Four: the branch and a draft pull request are open before I leave. Five: every claim of completion has to come with evidence. The fences stay in force the whole time. Mine forbid force-pushing, exposing secrets, changing the production database, merging code and publishing. The run carries on through safe work that can be undone, and stops when a protected action becomes necessary, unless that run carries a written grant for it. ## How I do it AFK means away from keyboard. My runs last five or six hours. ## The rule Decide before you leave what the agent may never do, and make it stop when it gets there. --- # 12. Sequence, loop or graph? > Choose the simplest shape that matches the work. Lesson 12 of 27. Part 2 of 6: Assign the work. Source: https://chiefofagents.si/lessons/sequence-loop-or-graph ## The lesson A sequence handles steps that depend on each other and run once. A loop repeats one task until it meets an exit condition. A graph coordinates specialists that branch, rejoin, retry and escalate. Picking the simplest one prevents a common failure: building a complicated coordination system for work a checklist could have finished. ## How I do it I ask it in this order, and stop at the first one that fits. ## The rule Use a checklist when a checklist does the job. --- # 13. Anatomy of an AFK run > It starts with a contract and ends at a gate. Nothing in between merges without my yes. Lesson 13 of 27. Part 3 of 6: Set the boundaries. Source: https://chiefofagents.si/lessons/anatomy-of-an-afk-run ## The lesson I start the run with one batch of decisions and a contract. The contract sets scope, permissions, permanent fences, a budget, stop conditions and exit tests. The lead agent coordinates separate lanes for building, testing and collecting evidence. The lanes write to shared state. If one lane needs a credential or a decision from me, that lane stops. Safe, independent work carries on. The work rejoins at independent review. Failed review goes back to implementation. Passing work produces an evidence pack and a draft pull request. Then the run stops at the merge gate and waits for me, unless I gave that yes in writing before it began. Nothing reaches production any other way. Being away changes when I supervise. It does not change what I own. ## How I do it Five or six hours, one contract in, one draft pull request out. ## The rule Design the run so the most it can do without you is prepare a decision, or carry out one you granted in writing before you left. --- # 14. Returning at the merge gate > I read the evidence, then decide what ships. Lesson 14 of 27. Part 4 of 6: Judge the result. Source: https://chiefofagents.si/lessons/returning-at-the-merge-gate ## The lesson Review finishes before the work reaches me. One pull request tells one story I can trace. Changes that would make review unclear get separate pull requests. The checks have to be green on the exact commit proposed for merge, not on an earlier one. I do not replay every step the agents took. I review the evidence and decide. ## How I do it The real evidence pack shown on this site says it plainly: PASS, 11 of 11 checks, 17 of 17 tests, and "Not done here: merge, production database changes." ## The rule Make the thing you review small, single-purpose and tied to one exact commit. --- # 15. What happens after the code works > Working code starts the delivery. It does not finish it. Lesson 15 of 27. Part 4 of 6: Judge the result. Source: https://chiefofagents.si/lessons/after-the-code-works ## The lesson The application travels one path: a feature branch, a pull request, automated checks, a preview environment, independent review, my merge, automatic deployment, live verification, and then real users. Database changes travel a second path: an additive migration, verification against a test database, my approval for production, and confirmation that production is ready. The two paths join before the merge. Deployment is not proof. Checking the live system is a separate step. ## How I do it CI is the automated checks on the proposed change. CD is the automatic deployment after I approve a merge. ## The rule Treat "it works here", "it is deployed" and "it works for users" as three different claims. --- # 16. Keep secrets out of sight > An agent can read files, terminal output and process details. A secret can be in all three. Lesson 16 of 27. Part 3 of 6: Set the boundaries. Source: https://chiefofagents.si/lessons/keep-secrets-out-of-sight ## What happened A command that inspects running processes printed secrets that the secret store had injected into a running process. They went straight into the agent's output. ## The lesson Plain-text secrets in a file beside the code are the obvious risk. The less obvious one is that a secret can reach the model even when the repository holds no such file. The fix covers the whole path. A secret store keeps values outside the repository. Commands receive values only when they run. Documentation holds variable names, never values. Secret scans check changes before they land. And process output is treated as a possible source of secrets too. ## How I do it Values live in a secret store and are injected at runtime. My notes and docs only ever name the variable. ## The rule Assume anything an agent can print, it can read. --- # 17. Never test against production data > Agents need somewhere they can break things. Lesson 17 of 27. Part 3 of 6: Set the boundaries. Source: https://chiefofagents.si/lessons/never-test-against-production-data ## The lesson Tests run against an isolated database branch, with separate test data and separate permissions. Agents can run migrations, create records and exercise failures there without touching a real customer. The isolation covers four things: where the connection points, the data, the permissions and the migration path. A test command must point only at the isolated environment. A test has no path to production. ## How I do it My isolated branch is called v2-test. Only test migrations run there. ## The rule Give agents a full copy of the shape of production and no route to the real thing. --- # 18. Local means local > A tool called local reached production, and spent money doing it. Lesson 18 of 27. Part 3 of 6: Set the boundaries. Source: https://chiefofagents.si/lessons/local-means-local ## What happened A command described as local inherited a managed production address. The run spent about $0.62, took and released a production lease, and stopped before writing a final result. ## The lesson The fix is a check at the boundary. A local tool accepts only a loopback address such as localhost or 127.0.0.1. A remote address is a hard failure before the first network call. Environment defaults never get to choose the target silently. ## How I do it Every local tool now asserts its target before it makes any network call. ## The rule Check where a tool is pointing before it speaks, and fail loudly if the answer is not what its name promises. --- # 19. The database must be ready first > Code that deploys by itself must never arrive before the tables it expects. Lesson 19 of 27. Part 3 of 6: Set the boundaries. Source: https://chiefofagents.si/lessons/the-database-must-be-ready-first ## The lesson New code may expect new tables, columns or permissions. If the code deploys automatically and production does not have them yet, it fails. So additive database changes are applied and verified before the code that depends on them is merged. A migration that has been applied is never edited. If it has a defect, a new corrective migration is added. Editing it would make different environments disagree about what the same migration means. ## How I do it The order is fixed: additive change, verify real behaviour, database ready, then my merge. ## The rule Database first, code second, and never rewrite a migration that has already run. --- # 20. Nobody grades their own homework > A builder's report that it is done is a claim. Someone else decides if it is true. Lesson 20 of 27. Part 4 of 6: Judge the result. Source: https://chiefofagents.si/lessons/nobody-grades-their-own-homework ## The lesson Builders never approve their own work. Independent checks look at three things: the diff, how the code behaves when it runs, and what the user experiences. Different reviewers look for different things. One for defects in the code. One for security, structure and how easy it will be to maintain. One for dangerous paths and leaked secrets. One that walks the user journey in a real browser. ## How I do it I use Bugbot for code defects on the complete branch, Thermos for security, structure and maintainability, a vulnerability scanner for dangerous paths and secret leaks, and Gstack for browser checks of the user journey. Those names are my setup today. The rule does not depend on them. ## The rule Use review that the builder does not control, and make it look at the running product. --- # 21. Over ten times the estimate > My own count said one thing. The provider's count said another. Lesson 21 of 27. Part 4 of 6: Judge the result. Source: https://chiefofagents.si/lessons/over-ten-times-the-estimate ## What happened I estimated 2,000 to 9,000 units. The provider counted 97,000. One full run of the tests made 238 live requests, and about 17 local runs accounted for roughly 92,000 units. ## The lesson The provider's export showed live calls that my own estimate had missed. Local test runs had a service key and were making real calls. The automated checks never showed the leak, because their environment had no key at all. It changed which evidence I trust. The provider's own record now outranks any reconstruction of usage that I build myself. Tests block live provider calls at the client boundary, and every allowed request records the units the provider reports. ## How I do it The provider's record is the source of truth for usage. My internal numbers are a guess until they match it. ## The rule Measure at the boundary where the money is spent, and believe the party that sends the bill. --- # 22. No feature, no bug > The error went away because the feature went away. Lesson 22 of 27. Part 4 of 6: Judge the result. Source: https://chiefofagents.si/lessons/no-feature-no-bug ## What happened An agent removed a broken screen so that its checks would pass. Every check went green. ## The lesson The fix traced the feature through every layer: definition, import, render, state, user action, backend, saving, visible result. The test target became what the user is meant to be able to do, not the absence of an error. This is why passing checks cannot define correct by themselves. A check can pass after the product has stopped doing what it is for. ## How I do it Tests now assert the intended behaviour, layer by layer, to the result the user sees. ## The rule Test for the thing that should happen. Silence is not a result. --- # 23. New agent, same old mistakes > A fresh agent inherits nothing from the last chat. Lesson 23 of 27. Part 5 of 6: Make it stick. Source: https://chiefofagents.si/lessons/new-agent-same-old-mistakes ## The lesson Different kinds of knowledge live in different places. A project wiki explains architecture, decisions and history. Repository rules record the failures every agent must read. A memory service gives lasting recall of preferences and lessons across sessions. Hooks inject context and enforce rules automatically, without relying on anyone remembering. The sources have an order of authority. The code that is running and the project’s written rules outrank summaries, the wiki and remembered context. Memory helps an agent find its feet. It does not overrule the system that actually runs. ## How I do it I use a project wiki, repository rules, Mem0 for memory across sessions, and hooks. ## The rule Decide where each kind of knowledge lives, and which source wins when two disagree. --- # 24. Scar tissue > The same mistake cannot happen silently twice. Lesson 24 of 27. Part 5 of 6: Make it stick. Source: https://chiefofagents.si/lessons/scar-tissue ## What happened Three incidents feed it in the talk: the API incident, the deleted screen and the local tool that reached production. ## The lesson Each serious failure gets a name and a written lesson. Then one question: where must this live? Architecture and decisions go in the project wiki. Failure patterns every agent should know go in the repository rules. Preferences and lessons go in memory. And anything critical to safety becomes enforcement: a hook, a test, a check in CI, a permission or a database control. The next agent to approach the same dangerous path is warned with evidence, or blocked. The incident has changed the system, not only my opinion. ## How I do it Important lessons move out of prose and into something that runs, whenever that is possible. ## The rule After every failure ask where the lesson must live so that it cannot be skipped. --- # 25. House rules > A skill turns an instruction I keep repeating into something the agent just does. Lesson 25 of 27. Part 5 of 6: Make it stick. Source: https://chiefofagents.si/lessons/house-rules ## The lesson Skills package the instructions a team needs again and again. Some carry principles for reasoning and for checking work. "Fix root causes" blocks repairs that only hide the symptom. "Prove it works" demands evidence you can observe. No skill replaces judgment. A skill makes a useful behaviour repeatable and easier to audit. ## How I do it Almost every skill I use was made by someone else. The skill library names each maker. ## The rule When you catch yourself typing the same instruction a third time, package it. --- # 26. Match the model to the task > The most capable model does not belong on every task. Lesson 26 of 27. Part 2 of 6: Assign the work. Source: https://chiefofagents.si/lessons/match-the-model-to-the-task ## The lesson Before: one premium model on everything. After: mechanical work goes to faster, cheaper models. Ordinary building goes to a capable middle lane. Migrations, security and final review go to the strongest models. Builders and reviewers use different model lanes, so the same model does not wave through its own assumptions. A long AFK run uses one pinned model to coordinate. The model names belong to one moment. The routing should follow risk, difficulty and cost. ## How I do it Three lanes by risk, and a different lane for the reviewer than for the builder. ## The rule Route by how much it costs to be wrong. --- # 27. The bottleneck > Me. Lesson 27 of 27. Part 6 of 6: What stays mine. Source: https://chiefofagents.si/lessons/the-bottleneck ## The lesson I remain the final bottleneck by design. Three decisions stay with me: merging to the main branch, changing the production database, and publishing. Everything else is delegated. Keeping the gates keeps the result mine to answer for. Your gates may differ. A low-risk internal prototype may need fewer. A product that handles money, personal data or public claims may need more. ## How I do it Agents execute. I judge the result. ## The rule Pick the few decisions you will never hand over, write them down, and delegate the rest. --- # 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. When agents do the building, the human job moves away from writing each line and towards four things: choosing the right problem, assigning the work, setting boundaries, and judging what comes back. Chief of Agents is a name for that job. It is a role, not a title. One person building alone with agents is doing it. So is a founder supervising software they did not write, or an engineer moving from one coding assistant to several agents working at once. The role keeps a small number of decisions that are never delegated. In my setup there are three: merging to the main branch, changing the production database, and publishing. ## What is a vertical slice? One end-to-end product outcome that touches every technical layer needed to make it work. A vertical slice starts with something a user does and ends with something they can see. In between it passes through the interface, the application logic and the database. It is narrow, and it works. The opposite is building in layers: finish the frontend, then the backend, then the database. Each layer can look finished while no user can complete a task. The risk of joining them stays hidden until late. With agents this matters more, because an agent will finish a layer and report success. A slice gives it a result that can be tested from the outside. ## What is a tracer bullet in software? The first narrow, complete user journey, built to expose integration problems early. A tracer bullet is the first vertical slice of a project. You pick the smallest real journey, build it through every layer, and test the whole thing before adding anything beside it. Its job is to show you which assumptions are wrong while fixing them is still cheap. A wrong assumption about your setup, your data or your deployment would otherwise be repeated across every later slice. ## What is a takeover packet? The documents and verified state a fresh person or agent needs to continue a piece of work. A takeover packet has four parts: the PRD and the full slice map; a setup brief with scope, decisions, dependencies and exit tests; instructions ready to paste into a new chat; and the verified state, meaning the real branch, commit, evidence, blockers and gates. In my setup these are four files: the PRD, the slice spec, the kickoff prompt and the state file. The kickoff prompt stays on my machine, out of git. The lead agent writes it, after the previous slice is verified. Written earlier, it would describe a plan. Written after, it describes what exists. The test for a good one is whether someone who has never seen the project could pick it up and continue without asking you anything. ## 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. AFK means away from keyboard. In an AFK run, agents keep working for hours while nobody is watching. What makes it safe is not trust. It is that the run begins with a written contract, runs inside permanent fences, and ends by preparing a decision for a person, unless that decision was made in writing before it began. In my runs nothing merges or reaches production unless I granted it in writing before the run began. If one part of the work needs a credential or a human decision, that part stops and waits. Safe, independent work continues. ## What is a run contract for an AI agent? A short written agreement that sets what an agent may change, what it may never do, and what proves it is finished. A run contract is written before an AFK run starts. Mine has six parts: scope, permissions, permanent fences, a budget, stop conditions and exit tests. They sit in two documents. The slice spec is the plan. The kickoff prompt starts the run and points at the spec. Scope says what the run is for. Permissions say what the agent may change. Fences are the actions that always stop the run. Exit tests are the observable conditions that mean the work is complete. It also separates choices that can be undone, which the agent may make alone, from decisions only I make. ## What is an evidence pack? The test results, review findings, screenshots, logs and state needed to judge a claim that work is complete. When an agent says it is done, that is a claim. An evidence pack is what lets someone else check the claim without redoing the work. It is collected during the run, not reconstructed afterwards, and tied to one exact commit. It says what was not done as plainly as what was. A real one from my work reads: PASS, 11 of 11 checks, 17 of 17 tests, and a line stating that the merge and the production database changes were not done there. ## What is a human gate? A protected action that cannot go ahead until an authorised person approves it. A human gate sits in front of an action that is hard or impossible to undo. Agents can prepare everything up to it. They cannot pass it without a person's yes, given at the gate or in writing beforehand. The most common one is the merge gate: work arrives as a reviewed pull request with its evidence, and a person decides whether it joins the main branch. How many gates you need depends on the product. A low-risk internal prototype may need fewer. A product that handles money, personal data or public claims may need more. ## What is a vacuous pass? A green result from a check that could not have been red. A test suite makes a universal claim: for every behaviour it exercises, nothing failed. A universal claim over an empty set is true. Logicians call this vacuous truth. Delete the thing under test and "nothing failed" holds perfectly. It happened to me three times. I asked an agent to fix a broken screen. It removed the screen, and every check went green. The checks were right. They were answering a different question from mine. The second time I did not recognise it. I ran tests against a paid API and believed the calls were faked. One full test run was attempting 238 live requests. The automated checks stayed green throughout, because their environment held no API key. They could not make a live call, so they could not fail on one. The third time it was my own rules. I signed changes, and they never reached the running system. Every check stayed green, because no check asked whether a signed rule was in force. So the first question to ask of any green check is whether it could have been red. A check has power only in an environment where the failure it guards against is possible. A check that cannot fail carries no information when it passes. This matters more with agents than with people. An agent is working to make the checks pass, and the cheapest way to make "nothing failed" true is to leave less that can fail. The repair is to ask for a different kind of claim. "This behaviour was observed" says that something exists, and an absence cannot satisfy it. A new check has to fail first, red on the old code and green on the new. My tests now assert the intended behaviour, layer by layer, to the result the user sees. Tests block live provider calls at the client boundary. The spending guard is exercised with a key that looks live, and the test passes only if zero units are used. It has a twin, the false block. A check able to say no is still a check that can be wrong, and I have only partial answers to it. A hard block now needs a positive match, and a read-only investigator separates a stale check from a real fault before anyone changes either. ## Loop or graph: how should agents be coordinated? Use a loop to improve one task until it passes. Use a graph when several specialists need to branch, rejoin and share state. There are three shapes. A sequence is steps that depend on each other and run once. A loop repeats one task, checking it each time, until it meets an exit condition. A graph coordinates several tasks, with connections that decide what runs, retries, pauses or stops. A graph needs shared state so every agent stays aligned. In mine that is scope, diff, evidence, status and budget. Graphs cost coordination. Start with the simplest shape that fits. A common mistake is building a complicated system for work a checklist could finish. ## What is sub-agent-driven development? One lead agent owns a slice of work and hands narrow, independent tasks to specialist agents. The lead owns the outcome. Builders implement, checkers verify, and one integrator owns the final diff and commit history. Each specialist works in its own Git worktree, a separate working directory on its own branch, so agents working at the same time do not overwrite each other. The builder does not approve its own work. A separate checker tests the claim that the work is complete, and a person decides whether the result passes a human gate. ## What is an additive migration? A database change that adds a table, column, index or permission without removing anything existing code still needs. Because it only adds, an additive migration can be applied before the code that uses it. Old code keeps working. New code finds what it expects. That ordering matters when code deploys automatically after a merge. If the code arrives before the database is ready, it fails in production. A migration that has already been applied is never edited. A defect is fixed by adding a new migration. Otherwise two environments can disagree about what the same migration did. ## How do AI coding agents end up seeing secrets? Through anything they can read: files beside the code, terminal output and the details of running processes. The obvious path is a plain-text file of secrets in the repository. The less obvious path is output. A command that lists running processes can print the values that were injected into them. That is what happened to me. The secrets were in a proper secret store, injected only at runtime, and a process-inspection command still printed them into the agent's output. The controls have to cover the whole path: keep values outside the repository, inject them only at runtime, write variable names and never values in documentation, scan changes for secrets, and treat process output as a place a secret can appear. ## How do you give AI agents memory across sessions? By storing each kind of knowledge in the right place, and turning the important lessons into rules that run. A fresh agent inherits nothing from the last chat. I use four places. A project wiki for architecture, decisions and history. Repository rules for the failures every agent must read. A memory service for preferences and lessons across sessions. And hooks, which inject context or enforce a rule automatically. They are not equal. The code that runs and the project’s written rules outrank summaries, the wiki and remembered context. Memory helps an agent get oriented. It does not overrule the system. The strongest form of memory is enforcement. A lesson written as a test, a permission or a hook does not depend on anyone recalling it. # Glossary - **Additive migration**: A database change that adds a new table, column, index or permission without removing behaviour that existing code still needs. - **AFK**: Away from keyboard. An AFK run is a bounded unattended period with a written contract at the start and a human gate at the end. - **Agent**: A model with tools that can read context, make changes and report results within the permissions it was given. - **Automated checks**: Repeatable tests and static analysis that run against a proposed change. - **Branch**: An isolated line of Git development used to prepare a change without altering the main branch. - **CD**: Continuous deployment. Here, an approved merge triggers automatic deployment. - **CI**: Continuous integration. Automated checks run against the proposed change before merge. - **Deterministic check**: A check that produces the same result from the same input without relying on model judgment. - **Evidence pack**: The test results, review findings, screenshots, logs and state needed to evaluate a claim that work is complete. - **Exit test**: An observable condition that defines when a task or slice is complete. - **Graph**: A workflow of steps and connections that lets several agents branch, retry, rejoin and stop for a person. - **Human gate**: A protected action that cannot proceed until an authorised person approves it. - **Loop**: A bounded workflow that repeats implementation and verification until it passes or reaches a stop condition. - **Main branch**: The repository branch treated as the approved integration point for deployment. - **Migration**: A versioned change to the database schema or permissions. - **PRD**: Product requirements document. It records what the product should do, its boundaries, and the decisions that govern the build. - **Pull request**: A reviewable proposal to merge one branch into another. - **Run contract**: What is written before an AFK run: scope, permissions, permanent fences, a budget, stop conditions and exit tests. Mine is a slice spec and a kickoff prompt. - **Secret store**: A service that keeps secret values outside the code repository. - **Shared state**: Written state that keeps agents aligned on scope, diff, evidence, status and budget. - **Slice**: One end-to-end product outcome that touches every technical layer required to make it work. - **Takeover packet**: The documents and verified state required for a fresh person or agent to continue a slice. - **Tracer bullet**: The first narrow, complete user journey, built to expose integration problems early. - **Vacuous pass**: A green result from a check that could not have been red. - **Worktree**: A separate Git working directory that lets several agents use different branches without overwriting one another. # Skills The 90 skills I use. Almost none are mine. Each line gives what the skill does, who made it and where it comes from. ## Decide - /grill-me: Use an interview with recommended choices to settle blocking decisions. Created by Matt Pocock. https://github.com/mattpocock/skills/tree/main/skills/productivity/grill-me - /interrogate: Challenge a plan’s assumptions before committing to it. Created by Lauren Tan. https://github.com/cursor/plugins/tree/main/pstack/skills/interrogate - /principle-redesign-from-first-principles: Rethink the system around the requirement instead of bolting on another layer. Created by Lauren Tan. https://github.com/cursor/plugins/tree/main/pstack/skills/principle-redesign-from-first-principles - /principle-foundational-thinking: Define the core rules before choosing the implementation. Created by Lauren Tan. https://github.com/cursor/plugins/tree/main/pstack/skills/principle-foundational-thinking - /principle-model-the-domain: Name the real states and transitions a workflow needs. Created by Lauren Tan. https://github.com/cursor/plugins/tree/main/pstack/skills/principle-model-the-domain - /brainstorming: Explore the goal, constraints, and direction before creating. Created by Jesse Vincent. https://github.com/obra/superpowers/tree/main/skills/brainstorming - /figure-it-out: Turn an unfamiliar task into a procedure with checks. Created by Lauren Tan. https://github.com/cursor/plugins/tree/main/pstack/skills/figure-it-out - /writing-plans: Turn an agreed requirement into concrete steps. Created by Jesse Vincent. https://github.com/obra/superpowers/tree/main/skills/writing-plans - /engineering:architecture: Compare architecture options and record the decision, trade-offs, and consequences. Published by Anthropic. https://github.com/anthropics/knowledge-work-plugins/tree/main/engineering/skills/architecture - /write-a-prd: Turn a feature idea into a product requirements document through an interview and codebase exploration. Created by Matt Pocock. https://github.com/mattpocock/skills/tree/a77fa6e7a6726f687aa36455b27ed8b7d09afdff/write-a-prd ## Build - /principle-sequence-verifiable-units: Break broad work into small outcomes that can be proved. Created by Lauren Tan. https://github.com/cursor/plugins/tree/main/pstack/skills/principle-sequence-verifiable-units - /executing-plans: Work through the plan in bounded batches with checkpoints. Created by Jesse Vincent. https://github.com/obra/superpowers/tree/main/skills/executing-plans - /subagent-driven-development: Assign separate tasks and review the results before combining them. Created by Jesse Vincent. https://github.com/obra/superpowers/tree/main/skills/subagent-driven-development - /test-driven-development /tdd: Write a failing behavior test before the fix when a regression test is useful. Created by Jesse Vincent. https://github.com/obra/superpowers/tree/main/skills/test-driven-development - /principle-make-operations-idempotent: Make retries safe so a repeated operation does not duplicate work. Created by Lauren Tan. https://github.com/cursor/plugins/tree/main/pstack/skills/principle-make-operations-idempotent - /principle-boundary-discipline: Put validation and responsibility at the layer that owns them. Created by Lauren Tan. https://github.com/cursor/plugins/tree/main/pstack/skills/principle-boundary-discipline - /heroui-react-pro: Give interface builders a guide to the actual component APIs. Published by HeroUI. https://heroui.pro/docs/react/getting-started/agent-skills - /heroui-pro-design-taste: Carry one set of design preferences into every interface-building brief. Published by HeroUI. https://heroui.pro/docs/react/getting-started/agent-skills - /deslop: Remove needless generated-code clutter from a change. Created by Eric Zakariasson. https://github.com/cursor/plugins/tree/main/cursor-team-kit/skills/deslop ## Debug - /systematic-debugging: Reproduce the failure and find its cause before changing code. Created by Jesse Vincent. https://github.com/obra/superpowers/tree/main/skills/systematic-debugging - /gstack-investigate: Investigate failures that cross code, environment, and services. Created by Garry Tan. https://github.com/garrytan/gstack/tree/main/investigate - /principle-fix-root-causes: Repair the cause while preserving the feature the user needs. Created by Lauren Tan. https://github.com/cursor/plugins/tree/main/pstack/skills/principle-fix-root-causes ## Prove - /browse: Drive the real interface and capture proof of the user journey. Created by Garry Tan. https://github.com/garrytan/gstack/tree/main/browse - /gstack-qa: Exercise complete web journeys and record failures. Created by Garry Tan. https://github.com/garrytan/gstack/tree/main/qa - /verification-before-completion: Require fresh evidence before the agent says it is done. Created by Jesse Vincent. https://github.com/obra/superpowers/tree/main/skills/verification-before-completion - /principle-prove-it-works: Check the result at the layer a person actually experiences. Created by Lauren Tan. https://github.com/cursor/plugins/tree/main/pstack/skills/principle-prove-it-works - /review-bugbot: Review the proposed code changes for bugs before merging. Published by Cursor. https://cursor.com/docs/bugbot - /thermos: Combine separate bug, security, and structure reviews into one verdict. Published by Cursor. https://github.com/cursor/plugins/tree/main/thermos/skills/thermos - /gstack-review: Review the actual change before it lands. Created by Garry Tan. https://github.com/garrytan/gstack/tree/main/review - /requesting-code-review: Hand a coherent change and its evidence to a separate reviewer. Created by Jesse Vincent. https://github.com/obra/superpowers/tree/main/skills/requesting-code-review - /receiving-code-review: Check review feedback before applying it. Created by Jesse Vincent. https://github.com/obra/superpowers/tree/main/skills/receiving-code-review - /02-vulnerability-scanner: Scan the proposed work for secret leaks and unsafe access paths. Maintained by sudo3rs (Masriyan). https://github.com/Masriyan/Claude-Code-CyberSecurity-Skill/tree/main/skills/02-vulnerability-scanner - /security-diff-scan: Limit a security review to the change under consideration. Published by OpenAI. https://github.com/openai/plugins/tree/main/plugins/codex-security/skills/security-diff-scan - /finding-discovery: Investigate a suspected vulnerability using concrete code evidence. Published by OpenAI. https://github.com/openai/plugins/tree/main/plugins/codex-security/skills/finding-discovery - /threat-model: Map assets, access boundaries, and possible attacks. Published by OpenAI. https://github.com/openai/plugins/tree/main/plugins/codex-security/skills/threat-model - /deep-security-scan: Use broader security inspection when the task calls for it. Published by OpenAI. https://github.com/openai/plugins/tree/main/plugins/codex-security/skills/deep-security-scan - /attack-path-analysis: Connect validated weaknesses into a possible attack route. Published by OpenAI. https://github.com/openai/plugins/tree/main/plugins/codex-security/skills/attack-path-analysis - /security-scan: Use a supporting security pass when relevant. Published by OpenAI. https://github.com/openai/plugins/tree/main/plugins/codex-security/skills/security-scan - /blast-radius: Check what a change could break elsewhere and test the risky assumptions. Created by Lauren Tan. https://github.com/cursor/plugins/tree/main/pstack/skills/blast-radius - /comment-sicko: A review agent that removes redundant comments and finds code that needs clearer names or structure. Created by Lauren Tan. https://github.com/cursor/plugins/blob/main/pstack/agents/comment-sicko.md ## Hand off and remember - /never-block-on-the-human: Let already-authorized reversible work continue, while protected decisions wait. Created by Lauren Tan. https://github.com/cursor/plugins/tree/main/pstack/skills/principle-never-block-on-the-human - /caveman: Compress prose in agent reports while keeping code and evidence exact. Created by Julius Brussee. https://github.com/JuliusBrussee/caveman/tree/main/skills/caveman - /poteto-mode: Keep summaries short, direct, and decision-oriented. Created by Lauren Tan. https://github.com/cursor/plugins/tree/main/pstack/skills/poteto-mode - /how: Explain how the actual code and system fit together. Created by Lauren Tan. https://github.com/cursor/plugins/tree/main/pstack/skills/how - /technical-writing: Write durable engineering explanations with clear evidence. Created by Lauren Tan. https://github.com/cursor/plugins/tree/main/pstack/skills/technical-writing - /unslop: Remove filler and vague language while preserving meaning. Created by Lauren Tan. https://github.com/cursor/plugins/tree/main/pstack/skills/unslop - /cavecrew: Coordinate agents with short reports that keep decisions and evidence visible. Created by Julius Brussee. https://github.com/JuliusBrussee/caveman/tree/main/skills/cavecrew - /using-superpowers: Check which skill fits the task before acting. Some workflows load this automatically. Created by Jesse Vincent. https://github.com/obra/superpowers/tree/main/skills/using-superpowers - /bro: Ask the agent to explain its last answer in plain language. Created by Lauren Tan. https://github.com/cursor/plugins/tree/main/pstack/skills/bro - /i-have-adhd: Keep the next action clear, break work into short steps, and cut distracting tangents. Maintained by Ayoub Ghriss. https://github.com/ayghri/i-have-adhd/tree/main/skills/i-have-adhd ## Ship - /finishing-a-development-branch: Verify the work and prepare a clear branch closeout. Created by Jesse Vincent. https://github.com/obra/superpowers/tree/main/skills/finishing-a-development-branch - /gstack-land-and-deploy: Coordinate release after the required owner decisions are ready. Created by Garry Tan. https://github.com/garrytan/gstack/tree/main/land-and-deploy - /gstack-canary: Observe the deployed system for regressions. Created by Garry Tan. https://github.com/garrytan/gstack/tree/main/canary - /gstack-careful: Resolve the target and protect risky operations. Created by Garry Tan. https://github.com/garrytan/gstack/tree/main/careful - /gstack-document-generate: Document the system from what actually exists. Created by Garry Tan. https://github.com/garrytan/gstack/tree/main/document-generate - /gstack-document-release: Update release records to match what actually shipped. Created by Garry Tan. https://github.com/garrytan/gstack/tree/main/document-release ## Create artifacts - /presentations: Build, render, and check slide decks. Published by OpenAI. https://developers.openai.com/codex/plugins/ - /template-creator: Build reusable presentation systems. Published by OpenAI. https://developers.openai.com/codex/plugins/ - /figma-use: Follow a safe read and edit workflow for a supplied design file. Published by OpenAI. https://github.com/openai/skills/tree/main/skills/.curated/figma-use - /figma: Retrieve the design structure and assets from the reference. Published by OpenAI. https://github.com/openai/skills/tree/main/skills/.curated/figma - /pdf: Check the final PDF as well as the editable source. Published by OpenAI. https://github.com/openai/skills/tree/main/skills/.curated/pdf - /gstack-design-review: Inspect the rendered interface for visual and layout problems. Created by Garry Tan. https://github.com/garrytan/gstack/tree/main/design-review - /gstack-design-consultation: Clarify the audience and design direction before building. Created by Garry Tan. https://github.com/garrytan/gstack/tree/main/design-consultation - /imagegen: A task-specific skill for generating or editing visuals. Published by OpenAI. https://github.com/openai/skills/tree/main/skills/.system/imagegen - /playwright: A task-specific tool for testing in a real browser. Published by OpenAI. https://github.com/openai/skills/tree/main/skills/.curated/playwright - /openai-docs: A task-specific skill for checking official OpenAI documentation. Published by OpenAI. https://github.com/openai/skills/tree/main/skills/.curated/openai-docs ## Design interfaces - /design-consultation: Set the audience, brand, and purpose before choosing a layout. Created by Garry Tan. https://github.com/garrytan/gstack/tree/main/design-consultation - /design:design-critique: Check whether the hierarchy makes the idea easy to understand. Published by Anthropic. https://github.com/anthropics/knowledge-work-plugins/tree/main/design/skills/design-critique - /design:accessibility-review: Check readability and access to each interaction. Published by Anthropic. https://github.com/anthropics/knowledge-work-plugins/tree/main/design/skills/accessibility-review - /ui-ux-pro-max: Choose interface patterns and keep them consistent. Published by NextLevelBuilder. https://github.com/nextlevelbuilder/ui-ux-pro-max-skill - /impeccable-layout: Refine spacing, alignment, and composition. Created by Paul Bakaus. https://github.com/pbakaus/impeccable - /impeccable-critique: Challenge the visual and interaction choices. Created by Paul Bakaus. https://github.com/pbakaus/impeccable - /impeccable-polish: Refine the details before sharing the interface. Created by Paul Bakaus. https://github.com/pbakaus/impeccable - /impeccable-animate: Use motion to explain a change in state. Created by Paul Bakaus. https://github.com/pbakaus/impeccable - /impeccable-overdrive: Connect diagrams and transitions with purposeful motion. Created by Paul Bakaus. https://github.com/pbakaus/impeccable - /colorize: Give different roles and states a clear visual distinction. Created by Paul Bakaus. https://github.com/pbakaus/impeccable - /principle-experience-first: Start with what a person needs to understand and do. Created by Lauren Tan. https://github.com/cursor/plugins/tree/main/pstack/skills/principle-experience-first - /interface-design: Build a coherent visual system for the interface. Maintained by Oyindamola Akinleye. https://github.com/Dammyjay93/interface-design - /interaction-design: Make each choice and its result clear. Maintained by Seth Hobson. https://github.com/wshobson/agents/tree/main/plugins/ui-design/skills/interaction-design - /data-analytics:create-data-context: Record definitions and source context so a team can reuse them. Published by OpenAI. https://github.com/openai/plugins/tree/main/plugins/data-analytics/skills/create-data-context - /sites:sites-building: Build and publish a working website. Published by OpenAI. https://developers.openai.com/codex/plugins/ - /impeccable-delight: Make useful feedback feel satisfying. Created by Paul Bakaus. https://github.com/pbakaus/impeccable - /layout: Separate ideas and give each control a clear place. Created by Paul Bakaus. https://github.com/pbakaus/impeccable - /make-interfaces-feel-better: Refine typography, control sizing, and feedback. Created by Emil Kowalski. https://github.com/emilkowalski/skills/tree/main/skills/emil-design-eng - /design:ux-copy: Write direct prompts and consistent button labels. Published by Anthropic. https://github.com/anthropics/knowledge-work-plugins/tree/main/design/skills/ux-copy - /principle-exhaust-the-design-space: Compare different approaches before choosing a layout. Created by Lauren Tan. https://github.com/cursor/plugins/tree/main/pstack/skills/principle-exhaust-the-design-space - /typeset: Tune type sizes, weights, and line lengths. Created by Paul Bakaus. https://github.com/pbakaus/impeccable - /typesafe:typesafe-ai: Match a project description to a workflow, a starting lesson and skills. Published by TypeSafe AI. https://github.com/typesafe-ai/skills/tree/main/skills/typesafe-ai - /frontend-design: Shape the visual direction, typography, and layout around the project. Published by Anthropic. https://github.com/anthropics/claude-plugins-official/tree/main/plugins/frontend-design/skills/frontend-design - /fixing-motion-performance: Find what makes animations stutter and make them run smoothly. Created by Julien Thibeaut. https://github.com/ibelick/ui-skills/tree/main/skills/fixing-motion-performance