# How to use this project ```figure ``` This page is the operating manual. It says who does what, what you actually type, what the agent will ask you back, and where each person stops. **The one thing to understand before anything else: the agent leads.** You are not expected to remember commands, skill names, or the order of steps. You describe what you want in ordinary language; the agent recognises which procedure that is, runs it, and comes back to you with the questions only you can answer. If you ever find yourself having to remember a name, that is a defect in the tool, not in you. ## Who does what Everyone writes into it, which is the point - and each role has a different job, a different page, and a different place where it stops. | | you own | you produce | what you never have to do | |---|---|---|---| | **[Product](product-work.md)** | what should be true, and for whom | behaviour, rules, what done means to a user | remember a command, or approve something you cannot read | | **[Development](dev-work.md)** | making that buildable and correct | contracts, the plan, the decisions the change forced | re-argue a decision that already carries a record | | **[The agent](agent-work.md)** | executing it faithfully | code, tests, a reconciled spec | invent anything - it stops and asks instead | Product owners and analysts write behaviour in their own words and the loop sharpens it into something buildable. Architects record the forks and what they cost. QA gets acceptance criteria that existed before the code. Developers get contracts instead of archaeology. The agent reads all of it as context and writes back into the same place. ## Where you enter | You are... | Go to | |---|---| | the person who decides what the product does | [Product Owner](product-work.md) | | the person who builds it | [Developer](dev-work.md) | | rolling this out across a team or a client | [Consultant](lead-work.md) | | after the exact sentence for a situation | [Anyone](working-with-specs.md) | | wondering what the agent does unprompted | [What it does by itself](agent-work.md) | | holding notes from a meeting | [Turning meetings into specs](discovery.md) | ## The loop, once, end to end Here is the whole thing with a real example, so the pages above have something to hang on. **1. Somebody wants something.** They say it plainly. Naming it first - "new feature", "new story" - is for the person typing rather than for the agent; the bare sentence works too: ``` > new feature: guests should be able to change their booking dates themselves ``` **2. The agent finds out what it does not know.** It checks whether a spec for this capability already exists, checks `docs/discovery/` for anything from a meeting on the subject, drafts what it can, and then asks you - only about things it genuinely cannot decide: > Two questions before this is buildable. **(1)** If a guest moves a booking to a more > expensive week, do they pay the difference, or keep the original price? **(2)** Is there a > cut-off - can they change a booking that starts tomorrow? **3. You answer, or you say who will.** Both are valid, and "I do not know yet" is a real answer that gets recorded rather than lost: ``` > they pay the difference. the cut-off is Maja's call, not mine - hold that question and > tell me when it starts blocking the work ``` **4. The spec cannot proceed until nothing is open.** What you parked is now a visible blocker with a name on it, not a forgotten thread. Anyone can ask: ``` > what is blocking booking-changes? ``` > One open item: a decision on the change cut-off (business, Maja). Everything else is > settled. **5. When it is settled, it gets built.** The agent plans, breaks it into tasks, implements, and then reconciles: the spec, the code and the tests must agree, and if building revealed the spec was wrong, the spec gets fixed - it is the truth, not a wish. **6. The pull request cannot merge if the spec and the code disagree.** Not as a convention. A guard compares them and fails the build. ## The skills, and when they fire The lifecycle ships as procedures the agent runs. Each one carries a description of **the situation it is for**, and the agent matches what you said against those descriptions - so you never have to know a name. You can still call one directly when you know exactly what you want. Both work. | you say | what runs | who usually says it | |---|---|---| | "guests should be able to change their dates" | `spec-specify` then `spec-clarify` | product | | "notes from today's meeting: ..." | `discovery-digest` | anyone | | "we agreed on Postgres, mainly for the reporting joins" | `adr-write` | dev or architect | | "we are charging per seat, not per user" | `bdr-write` | product | | "what breaks if we change the refund window?" | `spec-impact` | dev | | "how would we build this?" | `spec-plan`, then `spec-tasks` | dev | | "go ahead" | `spec-implement` | dev | | "I think that is done" | `spec-reconcile` | dev | | "is this ready to push?" | `pre-pr-review` | dev | | "we should fix that too, but not here" | `add-to-backlog` | anyone | | "what if we let hosts pre-approve repeat guests?" | `idea-write` | anyone | | "we do not have personas" | `personas-write` | product | | "let's start a sprint" / "the sprint is over" | `sprint-open` / `sprint-close` | whoever runs the team | | "when does billing ship?" | `timeline-update` | anyone | | "update me to the latest" | `update-to-latest` | whoever maintains it | If you ever have to remind the agent to use one of these, that skill's description is wrong and fixing it is the bug - not you remembering to carry a password. ## What is true for everyone **Say things in your own words.** There is no syntax. "we agreed on Postgres yesterday, write it up" works exactly as well as any command. **A deferral is an answer.** "Leave that to the technical side" gets recorded as a deferral with an owner. What is never acceptable is a question quietly dropped because nobody wanted to hold it. **Ask for a plain-language explanation of anything.** Any spec, any decision, any term: ``` > explain ADR-014 to me like I have never seen this repo ``` The person who has to approve something must never be in the position of approving what they cannot read. That is a rule of the standard, not a courtesy. **If you notice something and it is not this change, say so and keep going.** ``` > the export dies when it times out, there is no retry - not fixing it in this change, > write it down so we do not lose it ``` It lands in the backlog with its source and what "done" would mean. Noticing and not recording is the only failure here. **Nothing important lives in the chat.** A decision made in conversation and not written down did not happen. The agent writes it while it is fresh; that is the whole point of the project. ## The status of a piece of work, at a glance ``` in-refinement -> ready-to-develop -> in-development -> live ``` `in-refinement` means questions are still open, which is healthy and can last weeks. `ready-to-develop` is **earned mechanically** - a script checks that nothing is left open; it cannot be typed in by someone who is impatient. `live` means the spec, the code and the tests have been reconciled and the scaffolding is gone. The status is written by one step, `spec-reconcile`, and **checked by another**: the structure guard re-runs the clarify gate on every spec claiming `ready-to-develop` or `live` and fails the pull request when the gate refuses it. That check is what makes the sentence above true rather than aspirational - before it existed nothing read or wrote the field, so an impatient status was exactly as green as an earned one. ## When it does not fit **A one-line fix.** No spec round. Change it, and if behaviour moved even slightly, the spec moves in the same pull request - the guard will say so if you forget. **A refactor with no behaviour change.** No spec edit at all. The reconcile step confirms behaviour did not move. **An emergency at 3 a.m.** Fix it. Then write down what you learned, in the runbook, and file what it revealed. The standard is designed to survive being skipped once; what it does not survive is nobody coming back. The test is always substance, not paperwork: a contestable decision earns a record, a real behaviour change earns a spec edit, a rename earns neither.