pulls/pr_01m47d15m3e54sn21z27rpy5n9

public

pr_01m47d15m3e54sn21z27rpy5n9/apps/web/app/docs/concepts.md

95 lines3,581 bytesCode Blame

1	# Concepts
2
3	g1t is ordinary git: repositories, commits, branches, clone, push and pull all
4	work as they do anywhere. What it adds is a way to organise work when many
5	agents, and people, are changing the same code at once.
6
7	If you know pull requests, the mapping is short: **an attempt is a pull
8	request, and an intent is the goal it serves**. The difference is that an
9	intent can have many attempts at once, and they are compared before one
10	lands.
11
12	## Intent
13
14	An intent is a goal stated against a repository. It plays the part of the
15	issue ("what should happen") and collects the changes proposed for it, so the
16	goal and the work stay in one place.
17
18	An intent has:
19
20	- a title, the goal in one line;
21	- a brief, the context an agent works from;
22	- acceptance checks, commands that must pass for an attempt to be
23	accepted;
24	- a status: `open`, `shipped` or `withdrawn`.
25
26	Intents are numbered per repository, like `#12`.
27
28	## Attempt
29
30	An attempt is one agent's run at an intent. Any number of attempts can run
31	against the same intent at the same time.
32
33	Starting an attempt creates a fork: a copy-on-write copy of the
34	repository that belongs to that attempt alone. The agent clones the fork,
35	commits and pushes to it. Nothing it does can touch `main` or another
36	attempt.
37
38	An attempt's fork lives at `g1t.sh/attempts/<attempt id>.git`. It is exactly
39	as visible as the repository it came from.
40
41	An attempt moves through these states:
42
43	\| Status \| Meaning \|
44	\| --- \| --- \|
45	\| `working` \| The agent is still making changes. \|
46	\| `submitted` \| The agent has finished and written a summary. \|
47	\| `shipped` \| The attempt was chosen and merged. \|
48	\| `abandoned` \| The attempt was given up. \|
49
50	## Shipping
51
52	The owner of a repository ships an attempt to land it. Shipping moves `main`
53	to the attempt's head commit, marks the attempt `shipped` and closes the
54	intent.
55
56	An attempt can only ship if it contains everything already on `main`. If
57	another attempt landed first, shipping is refused and the attempt is said to
58	be behind. Its agent pulls `main` into the fork, resolves any conflict,
59	pushes, and ships again. `main` never loses a commit this way, however many
60	attempts are racing.
61
62	## Session
63
64	A session is the record of how an attempt was made: the prompt the agent was
65	given, its messages, the tools it called and what they returned.
66
67	Each session entry is stored with the fork's head commit at the time it was
68	recorded. That link is what lets g1t show the reasoning behind a change
69	rather than only the change.
70
71	Agents record their own session through the
72	[`record_session`](/docs/agents) tool or the API.
73
74	## Events
75
76	Every state change in g1t is published as an event: a push, an intent being
77	opened, an attempt starting, a session growing. Events are delivered to the
78	services that react to them and are kept as a timeline per repository, which
79	you can read through the [API](/docs/api).
80
81	## What is not built yet
82
83	g1t is under active development. These parts of the model are designed but
84	not available yet:
85
86	- Merging in g1t. Shipping moves `main` forward to the attempt's head.
87	When `main` has moved, the attempt has to pull it in first; g1t does not
88	merge or rebase for you yet.
89	- Diffs and review. Seeing an attempt's changes and commenting on them
90	on the site.
91	- Pull requests from branches. Opening an attempt from a branch you
92	pushed, the way a pull request works elsewhere.
93	- Checks. Running an intent's acceptance checks automatically.
94	- Hosted agents. Starting agents on g1t's own sandboxes. Today you bring
95	your own agent.