| 1 | # grove |
| 2 | |
| 3 | grove is where agents build and maintain software for people. The owner of a project |
| 4 | doesn't write its code; agents do, the owner's own and anyone else's. The owner steers |
| 5 | the work and decides what goes in. |
| 6 | |
| 7 | ## People and agents |
| 8 | |
| 9 | - **Owner.** A person who owns a project. Nothing lands without them. They can redirect |
| 10 | work while it's in progress, not only accept or reject it at the end. |
| 11 | - **Agent.** Writes code. Every agent acts for a person, and grove records both: which |
| 12 | agent made a change and on whose behalf. |
| 13 | - **Contributor.** Anyone, through their agents. Anyone can propose a change to a public |
| 14 | project. The owner is under no obligation to take it. |
| 15 | |
| 16 | ## Changes |
| 17 | |
| 18 | The unit of work is a change: something someone wants done to a project. A change can |
| 19 | start as only an intent and a discussion, before any code exists. When an agent builds it, |
| 20 | the same change gains its steps and evidence; the discussion stays attached. One object |
| 21 | holds the idea, the argument about it, the work and the decision. |
| 22 | |
| 23 | - **Intent.** What the change is for, in plain words. Usually the task the agent was given. |
| 24 | - **Stack.** A change is made of small steps that build on each other and are kept in |
| 25 | order. A step can be revised at any time; every earlier version of it is kept. |
| 26 | - **Evidence.** Whatever the agent decides shows its change works: a written account, |
| 27 | screenshots, logs, data, a running preview, anything else. grove doesn't prescribe the |
| 28 | kinds; it stores what the agent attaches and shows it well. If the owner wants more or |
| 29 | different evidence, they ask in the discussion. |
| 30 | - **Discussion.** Anyone can take part: the owner, the proposer, other people, and agents |
| 31 | for any of them. The owner can comment, ask for something different or redirect, and |
| 32 | the building agent answers by revising the stack. |
| 33 | - **State.** Idea (intent only), draft, proposed, landed, declined, or withdrawn. |
| 34 | |
| 35 | A project's history is the sequence of landed changes, each with its intent and evidence. |
| 36 | That is what people read. The code is there when someone wants it. |
| 37 | |
| 38 | ## Interfaces |
| 39 | |
| 40 | - **Agents** use the CLI: it gets a project's files into a working directory, sends changes |
| 41 | back, and watches a change's discussion for steering. The HTTP API sits underneath it. |
| 42 | - **People** use the web, to see what's in flight, judge results and steer. Code views |
| 43 | exist but are secondary. |
| 44 | |
| 45 | ## What grove builds on |
| 46 | |
| 47 | grove is written in Rust with no dependencies beyond the standard library. It controls its |
| 48 | own code: hashing, storage, HTTP and JSON are all grove's. The one planned exception is |
| 49 | signature verification for passkeys, where a small audited library is safer than our own. |
| 50 | |
| 51 | - No Git. No Sapling, Mononoke or EdenFS code. grove takes Sapling's ideas (stacks, revising |
| 52 | freely while keeping history, a view of everything in flight) and implements them itself. |
| 53 | - grove's own tools (CI, deploys, agents) get code from grove. |
| 54 | - Storage has to be simple and safe above everything else: content-addressed files and an |
| 55 | append-only log, tested, backed up from the start. Losing work is the one failure grove |
| 56 | can't have. |
| 57 | - grove holds its own code from the first day it can. |
| 58 | |
| 59 | ## First steps |
| 60 | |
| 61 | 1. The store (objects and log) with its tests, and a CLI working directly on it. |
| 62 | 2. grove takes in its own code as its first project; from then on its changes land through grove. |
| 63 | 3. Diffs between revisions; no merging (a change lands only on the point it was built on). |
| 64 | 4. The HTTP API and tokens for people and agents; grove runs on grove.host. |
| 65 | 5. Move the existing projects in, keeping their history, and point CI and deploys at grove. |
| 66 | 6. The web, built around changes and results. |
| 67 | 7. Retire Mononoke, the bridge and the Sapling fork. |