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