grove/VISION.md

at @13

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