g1t/apps/docs/src/content/docs/guides/outcomes.md
| 1 | --- |
| 2 | title: Hand off an outcome |
| 3 | description: Write what should be true, let an agent plan the issues, and follow g1t agents as they land them. |
| 4 | --- |
| 5 | |
| 6 | You do not have to split work into issues yourself. Write the outcome you |
| 7 | want on a repository's **Plan** page. An agent reads the repository and |
| 8 | proposes the issues that would get there, with acceptance checks and the |
| 9 | order they have to land in. You read the plan, keep what you want, and open |
| 10 | it. g1t agents then work on the issues, as many at once as the dependencies |
| 11 | allow, and the outcome page shows each one until it lands. |
| 12 | |
| 13 | Planning and g1t agents work in any workspace with |
| 14 | [its own model provider](/guides/models/), and in those g1t's hosted models |
| 15 | are open to. The agents' runs are charged to the workspace; see |
| 16 | [usage and billing](/guides/usage-and-billing/). Only members of the |
| 17 | repository's workspace can plan work for it or see its plans. |
| 18 | |
| 19 | ## Write a brief |
| 20 | |
| 21 | 1. Open the repository and choose the **Plan** tab. |
| 22 | 2. Write what should be true when the work is done, in plain words. Say what |
| 23 | you want, not how to split it. A brief can be up to 8,000 characters. |
| 24 | 3. Choose **Plan it**. |
| 25 | |
| 26 | ```text |
| 27 | The greeter should support a --lang flag for Spanish and French, a --shout |
| 28 | flag that upper-cases the greeting, and a --version flag. Each should be |
| 29 | documented in the README and covered by tests. |
| 30 | ``` |
| 31 | |
| 32 | An agent reads the repository in a sandbox and writes the plan. This takes |
| 33 | a minute or two, and the page fills in when it is done. Nothing is opened |
| 34 | yet. If the planner cannot write a plan, the page says why and you can try |
| 35 | again. A plan that has not come back after 20 minutes is marked as failed. |
| 36 | |
| 37 | ## Read the plan |
| 38 | |
| 39 | A plan proposes up to 12 issues. For each one it shows: |
| 40 | |
| 41 | | | | |
| 42 | | --- | --- | |
| 43 | | Title and labels | What the issue is. | |
| 44 | | **Starts at once**, or **After** | Whether it depends on nothing, or which earlier issues have to merge first. | |
| 45 | | Acceptance checks | The commands a pull request for it must make pass, taken from how the repository is tested. | |
| 46 | | Files | The files it will most likely change. | |
| 47 | | **What the agent will be told** | The issue's description, in full. An agent given the issue works from this text. | |
| 48 | |
| 49 | The planner adds a dependency wherever two issues would collide, so that |
| 50 | the second starts from the result of the first. An issue can only depend on |
| 51 | issues earlier in the plan. |
| 52 | |
| 53 | ## Open it |
| 54 | |
| 55 | Untick any issue you do not want, then choose one of: |
| 56 | |
| 57 | | Choice | What happens | |
| 58 | | --- | --- | |
| 59 | | **Open these and assign g1t agents** | The issues are opened and queued for g1t agents. Agents start at once on every issue that depends on nothing, working in parallel, and on the others as what they depend on merges. | |
| 60 | | **Only open the issues** | The issues are opened, each blocked by the ones it depends on. Nobody is put to work on them. | |
| 61 | |
| 62 | A dependency on an issue you unticked is dropped with it. A plan is applied |
| 63 | once. |
| 64 | |
| 65 | ### How queued issues start |
| 66 | |
| 67 | An issue queued for a g1t agent starts when: |
| 68 | |
| 69 | - every issue it depends on has closed, normally because a pull request for |
| 70 | it merged; and |
| 71 | - the repository has room. At most six g1t agents make changes in one |
| 72 | repository at once. The rest wait their turn, which also leaves sandboxes |
| 73 | free for checks and reviews. |
| 74 | |
| 75 | Each queued issue says so in its conversation, for example "queued this for |
| 76 | g1t-agent, to start once #41 has merged". From there each issue is |
| 77 | [seen through](/guides/g1t-agents/#seeing-it-through) like any other a g1t |
| 78 | agent works on: checks, review, revision, and merging under the |
| 79 | repository's rules. |
| 80 | |
| 81 | ## Follow the outcome |
| 82 | |
| 83 | Once applied, the plan's page becomes the outcome page. It refreshes on its |
| 84 | own while anything is still moving. |
| 85 | |
| 86 | At the top: |
| 87 | |
| 88 | | | | |
| 89 | | --- | --- | |
| 90 | | Landed | How many of the plan's issues have landed, of the total. | |
| 91 | | Agents at work | Issues being worked on, checked, reviewed or tested in the merge queue now. | |
| 92 | | Needs you | Issues that are waiting for a person. | |
| 93 | | Agents have cost | What the runs on the outcome's pull requests have cost the workspace so far. | |
| 94 | |
| 95 | Below that is the plan as a graph: issues that start at once in the first |
| 96 | column, then each step that depends on the one before, with lines from each |
| 97 | issue to the ones waiting on it. Each issue links to its pull request, or to |
| 98 | the issue when there is none yet, and shows its state: |
| 99 | |
| 100 | | State | Meaning | |
| 101 | | --- | --- | |
| 102 | | Blocked | Waiting for the issues it depends on to land. | |
| 103 | | Waiting for an agent | Queued, and waiting for an agent to be free. | |
| 104 | | Open | Nobody is working on it. | |
| 105 | | Agent working | A g1t agent is making the change. | |
| 106 | | Checking | The acceptance checks are running. | |
| 107 | | In review | A g1t agent is reviewing the change. | |
| 108 | | Revising | The agent was sent back by the checks, a review or a person. | |
| 109 | | Catching up | The agent is merging in the branch it will land on, which has moved. | |
| 110 | | In the merge queue | It is being tested with the changes ahead of it. See [the merge queue](/guides/merge-queue/). | |
| 111 | | Ready to merge | Everything the repository asks for is met. | |
| 112 | | Needs you | g1t stopped and is waiting for a person. The reason is shown with it. | |
| 113 | | Landed | Its pull request merged. | |
| 114 | | Closed | Closed without landing. | |
| 115 | |
| 116 | ### Agents talking |
| 117 | |
| 118 | Questions and handoffs between the agents on the outcome's pull requests, |
| 119 | newest first, each with where it stands: waiting to be read, read, answered |
| 120 | (or taken on, for a handoff), or declined. See |
| 121 | [talking to agents](/guides/talking-to-agents/#agents-asking-each-other). |
| 122 | |
| 123 | ### What happened |
| 124 | |
| 125 | The events on the outcome's issues and pull requests since the plan was |
| 126 | written, newest first: pushes, checks, reviews, merges, and issues that g1t |
| 127 | agents opened for work they found outside their own task. |
| 128 | |
| 129 | ## From the API or an agent |
| 130 | |
| 131 | The same flow is three operations. They are members only. |
| 132 | |
| 133 | | Tool | Route | | |
| 134 | | --- | --- | --- | |
| 135 | | `plan_work` | `POST /repos/{owner}/{name}/plans` | Start a plan. Body: `brief`. Returns `planId` at once. | |
| 136 | | `get_plan` | `GET /repos/{owner}/{name}/plans/{plan}` | The plan, its `status` and the issues it proposes. | |
| 137 | | `apply_plan` | `POST /repos/{owner}/{name}/plans/{plan}/apply` | Open its issues. Body: `assign`, `keep`. | |
| 138 | |
| 139 | ```sh |
| 140 | # 1. Start a plan. |
| 141 | curl -X POST https://api.g1t.sh/repos/acme/greeter/plans \ |
| 142 | -H "Authorization: Bearer $G1T_TOKEN" \ |
| 143 | -H "Content-Type: application/json" \ |
| 144 | -d '{"brief": "The greeter should support a --shout flag, documented and tested."}' |
| 145 | |
| 146 | # 2. Read it until status is "ready". |
| 147 | curl https://api.g1t.sh/repos/acme/greeter/plans/pln_01… \ |
| 148 | -H "Authorization: Bearer $G1T_TOKEN" |
| 149 | |
| 150 | # 3. Open issues 1 and 3 and put g1t agents on them. |
| 151 | curl -X POST https://api.g1t.sh/repos/acme/greeter/plans/pln_01…/apply \ |
| 152 | -H "Authorization: Bearer $G1T_TOKEN" \ |
| 153 | -H "Content-Type: application/json" \ |
| 154 | -d '{"assign": true, "keep": [1, 3]}' |
| 155 | ``` |
| 156 | |
| 157 | A plan's `status` is `planning`, `ready`, `failed` or `applied`. Each |
| 158 | proposed issue has `title`, `body`, `labels`, `checks`, `files`, |
| 159 | `dependsOn` (positions in the plan, counting from 1) and, once applied, |
| 160 | `number`. `keep` takes positions counting from 1; leave it out to open |
| 161 | every issue. |
| 162 | |
| 163 | Once a plan is applied, `get_plan` also returns: |
| 164 | |
| 165 | | Field | | |
| 166 | | --- | --- | |
| 167 | | `progress` | Each opened issue with `state` (the values in the table above, written `blocked`, `waiting`, `open`, `working`, `checking`, `reviewing`, `revising`, `catching_up`, `queued`, `ready`, `needs_you`, `landed`, `closed`), a `detail` sentence, `blockedBy`, `pull` and `agent`. | |
| 168 | | `exchanges` | The questions and handoffs between the agents on its pull requests. | |