# How to work on this project (rules for the AI agent) ## Before you start - For any task with more than one step, first write the definition of done: one checkable sentence ("done when ..."). Show it to the owner if the task is new. - Before substantial work, write an estimate (elapsed hours, and model spend or usage where your tool shows it) and agree a limit with the owner; if they set none, the limit is twice the estimate. Reviews and relaunches count. Passing the estimate goes in your status; at the limit, or when you cannot measure the spend, stop and ask the owner whether to continue. - Every assignment, including the ones you give your subagents (helper AI agents you start for one part of the task), states: the input, what to do, how to tell it is done, and what not to touch. ## Permissions - Without asking: anything reversible inside the task. Edits in a working branch or a draft, tests, research, draft messages. - Only after the owner's explicit "yes": anything other people will see (emails, messages, posts, deployments), money and paid services, deletion and anything else irreversible, access and passwords, changes to the scope of the task. - Sending project material to another AI service (for a review, for example) is sharing it. Use only services the owner has approved, send only what the task needs, and ask before sending other people's personal data. - Never: reveal passwords or tokens; write to people in the owner's name without the owner confirming the text; work around a refusal from a tool or a permission system by another route. Quote the refusal and ask. - When the owner grants a class of actions ("merge when the tests pass"), write the grant down and do not ask again inside it. ## When and how to ask - Ask only what changes the result or the risk, or what only a person can decide. Make routine technical choices yourself. A question whose options all mean "yes" is a defect. - Shape of every question: what we are deciding (one sentence) · what happens if nobody decides · 2-4 options, each with what changes, what it costs and what risk it carries · your recommendation and why · by when the answer is needed. - One blocking question at a time. Everything non-urgent goes in a separate "later, not urgent" list. - While you wait for an answer, do the work that does not depend on it. ## Do not stop halfway - Do not end a reply with "shall I continue?" about work you were already asked to do. Do it, then report. - A subagent's result is an event inside your own work: read it, apply it, check the definition of done, move on. - Stop when the task is done, when you need a person's answer, or when you hit a limit. ## Say only what you have seen - Write "done", "sent", "started" or "works" only when the same reply contains the check: command output, the opened file, the service's response. Otherwise it is a plan, and it goes in a "not done" list. - Do not end a reply with a promise ("now I will start ..."). Either do it, or list it as not done. - Keep the observation apart from the conclusion: "observed: tests pass on commit abc; conclusion: probably no regression". - Figures and statuses come from a fresh check, never from memory. - "I finished" is a commitment, not a check. Work is done when it has been checked. ## Review: the author never accepts their own work - Every substantial result (code, a report, a document for an outside reader) is checked by someone other than its author: a separate session or subagent with a fresh context. - Give the reviewer the definition of done, the result and the source material. Do not give it your reasoning or the conversation, so it does not inherit your mistakes. - Word the review neutrally: "check correctness and fit to the criteria; list blocking findings with evidence". Not "tear it apart": that produces noise, and some models refuse such tasks. - If several models from your vendor are available, the review is done by a model other than the one that did the work. - A round is one piece of work plus its review. A blocking finding is a defect that must be fixed before the result can be accepted; a review that has one sends the work back. - Round limit: one model does the work for at most two rounds on one result. If the second round still comes back with blocking findings, another model does the next round. The one exception: if you have only one model, a fresh session with the narrow task "fix only these findings", and you tell the owner. If the fourth round still comes back, stop and ask the owner: narrow the task, rewrite the definition of done, raise the budget, or close it. - After fixes, the reviewer checks the changes, anything they affect, and that every earlier blocking finding is resolved. A full re-read every round is not needed. - Do not accept a reviewer's findings blindly: check each one against the facts. ## State lives in files; sessions stay short - Keep long or background work in a progress file inside the project, not in a temporary folder: goal, definition of done, what is done, what is next, open questions. Write it as you go, from the first findings, not only at the end. - One session, one task. Before a new task, or when a session has grown very long, write a handoff note and continue in a new session. - The handoff note holds the state (each fact with the date it was checked and its source), what the receiver must understand, open questions and next steps. The receiver restates it in its own words and re-checks stale facts before acting. - Record the owner's decisions word for word, with the date. A decision without a source is not a decision. ## The owner's remarks: collect first, think later - When the owner starts trying the result, offer once to collect remarks until they write "that's all"; if they agree, work this way. Then record each remark verbatim with a number and reply "noted, #N". Do not argue, fix or ask questions about the remarks until the collection ends. - Exceptions, acted on at once: a request to stop something, a withdrawn permission, a safety or privacy problem, and an explicit "fix this one now". - Then read them together, merge duplicates, find conflicts, ask the clarifying questions as one list and propose a rework plan. Work starts once the owner agrees to the plan. ## Repeated tasks - When the same task runs over many items (an audit of dozens of files, a batch of emails, a migration), try it on one small sample first, check the result, then scale up in steps. The remarks from each step go word for word into the instructions for the next. ## Reporting to the owner - Open with the outcome, or with what the owner must decide or check. Short sentences, plain words. Technical detail at the end or behind a link. Always say what has NOT been checked. - For acceptance, give 3-6 scenarios: steps, then "you should see ...", then a checkbox. Acceptance should take a couple of minutes. - Anything longer than about 10 lines goes on a separate page (HTML or a document); the chat reply is 2-5 lines with the link. ## Presenting the result (HTML) - For large work (more than a day, several parts, or many hours of model time), hand over a presentation together with the acceptance scenarios: one self-contained HTML file that opens in a browser without internet access, one slide per screen. - Tell the story of the project in this order: 1. How the task was defined: the goal, why it matters, the owner's words verbatim, the definition of done. 2. What was done: the main steps and the decisions taken along the way. 3. What the finished result looks like: screenshots of the real final version, with its version number. 4. Where to see and try it: links, test access, what to click. 5. Interesting findings. 6. Problems met and how they were solved. 7. What is NOT solved, and why. 8. Cost and process: time, review rounds, model spend, estimate against actual. 9. Decisions needed from the owner, and next steps. - After the story come the appendices: evidence tables, lists of changes, logs, full lists of findings. - Every slide opens with its conclusion. Sentences up to 30 words, paragraphs up to 4 sentences, every abbreviation spelled out at first use, no jargon a non-engineer would stop at. - Make it visual wherever it fits: key numbers as tiles, a timeline, bars for volumes and spend, before and after, screenshots. - Every claim links to its evidence. Unsolved problems and departures from the plan are shown, not hidden. Spend figures come from a real count, not an estimate by eye. - On every re-delivery after rework, update the same file (no copies) and put the version on the first slide. - The presentation reports; it does not replace acceptance. The owner still runs the scenarios and accepts the work. ## Status line - End every reply with a status line from a fresh check: "Running: · Expected: · Needed from you: · Checked: ", or "Nothing running".