alxshelepenok/grove
A formal workflow protocol that keeps AI coding agents on track through machine-enforced invariants, verified evidence, and structured context. Designed to keep deep, long-running projects coherent across sessions, agents, and months.
安装Install
dsh plugin --profile web add github:alxshelepenok/grove把 alxshelepenok/grove 加入你的 DSH 配置（web profile）即可启用。
READMEREADME
Code grows. Context windows don't. Plant a Grove 🌳
Graph-driven Reasoning Over Verified Evidence. A formal workflow protocol that keeps AI coding agents on track through machine-enforced invariants, verified evidence, and structured context. Designed to keep deep, long-running projects coherent across sessions, agents, and months.
We no longer just write code.
We hold the reins of a train running at 20 commits a day, making sure it doesn't derail.
What this gives you:
- Atomic progress: every task is mechanically proven, not just claimed.
- Hierarchy over compression: context is strictly structured, never lossily summarized.
- Absolute reproducibility: every action is recorded, so any step, decision, or assumption can be replayed and retraced.
- Continuity across agents: if an agent stops mid-goal, another agent on another client or model resumes from verified state.
- Total ownership: every goal, decision, task, question, and assumption is stored in a persistent historical graph that belongs entirely to you.
Grove enforces rules as deterministic invariants stored in a single checksummed lockfile. The agent cannot declare work done without falsifiable evidence, start unready tasks, or hallucinate progress.
Instead of lossy prompt compression or summarization, Grove structures project state into a typed reasoning graph with machine-checkable edges. It routes exactly the execution packet needed for the current step, and nothing more.
Works with Claude Code, Codex, Gemini CLI, Cursor, Windsurf, Cline, GitHub Copilot, and any other agent. Grove includes a CLI, a built-in MCP server, and a drop-in agent skill bundle so you can integrate it into your workspace immediately.
[!IMPORTANT] A note on the desktop app shown below. It exists to make the graph, the evidence, and the health of a project visible at a glance, but it is still experimental and has not been tested on macOS yet. The CLI and the MCP server are the stable, tested interfaces. The UI is implemented without any JavaScript framework, mostly plain HTML, CSS, and Tauri, which keeps it fast, and the graph is rendered with WebGL.
|
|
|
| The reasoning graph, explored live. | The same view at 143 nodes, history included. | All an agent needs for one work item, nothing more. |
|
|
|
| Work items tracked from proposal to done. | Goals, work, and content health per area. | Work grouped by theme, with the critical path. |
Agents lose context as projects grow
Long-running agents suffer from context amnesia. Decisions, assumptions, and dependencies drift out of view as the session grows. A related failure is unreliable self-reporting: the agent declares work complete without sufficient evidence. This happens not out of deception, but because nothing in the environment prevents it.
Standard task trackers inherently trust the executor. When a human checks a box in Jira, the work is assumed done. That is a reasonable default for humans. For autonomous agents it is a silent failure mode. Premature "done" declarations compound across long sessions into structural errors, until the codebase no longer matches what anyone believes it to be, and nobody can say why a given line exists.
This is not theoretical. Grove evolved from a crude Markdown hypothesis into a protocol that today manages Merlin Guild, a closed-source production project of 200k+ lines of Rust and TypeScript, heavy on blockchain and cryptography. It scales because the protocol does not rely on the agent remembering or obeying the workflow correctly.
Structure instead of compression
The obvious response to context amnesia is more tooling: summarization, compaction, retrieval. All of these compress context, and compression loses information while hoping the loss does not matter.
Grove does not compress context. It structures it.
As a project evolves, its work is continuously organized into areas, goals, questions, assumptions, decisions, and executable work items. This hierarchy gives the agent a way to identify the context relevant to the current step instead of repeatedly carrying the entire project history into its context window.
The result is not just better continuity; it also reduces token usage. The agent no longer loads unrelated project context simply to recover where it is and why the current task exists.
Map the entire codebase in a single prompt
What happens when you point a frontier model at a raw codebase with Grove attached?
Without a protocol, an agent skims the files, hallucinates a quick summary, and loses the plot after a few steps. With Grove, it maps the territory. In a real-world test on a complex codebase, a single prompt initiated a 5-hour autonomous Discovery session.
The agent burned through its context window limit, but the result was a fully populated reasoning graph: 44 Areas, 47 Goals, and 89 Work items targeting test coverage gaps and logic bugs. It didn't just dump a flat to-do list; it formally declared its open unknowns as Questions and grouped related efforts into Themes.
Here is the exact prompt used to bootstrap the project:
Load the Grove skill and connect to the MCP server. Study the skill fully to understand the protocol constraints.
Your objective is to run a complete Discovery phase across the entire codebase. Do not write implementation code yet, your job is project analysis and graph construction.
- Break the project down into Areas. Note that a single package may contain multiple logical areas.
- Iterate through each Area and create Goals to address missing test coverage and explicit logic bugs.
- For each Goal, create Work items strictly formatted according to the Grove protocol.
- Group related work into Themes.
- Declare open unknowns as Questions and formalize architectural choices as Decisions where necessary.
Because Grove enforces a Definition of Ready (DoR), the agent couldn't fake progress. Over the next day, the agent systematically executed the delivery phase, turning 75 tasks to Done. The remaining tasks correctly stalled in proposed or ready states, waiting for human answers to the blocking Questions the agent had raised.
One project state, multiple interfaces
The unit of memory is not the conversation. It is the project.
The unit of progress is not the agent's claim. It is verified evidence.
Grove replaces polite prompt instructions with a strict, mechanically enforced protocol. Agents interact with project state through the CLI, MCP, and desktop interfaces. The protocol itself enforces the rules:
- A work item cannot be marked done without an evidence record.
- Work cannot start until every precondition is machine-verified.
- Goal progress cannot be updated by hand; fitness deltas are applied atomically at close time or not at all.
The state either satisfies the protocol, or Grove refuses to advance it. An agent cannot advance protocol state by merely claiming that work is complete.
Give agents only the context they need
Grove forces the agent to decompose the product into a strict typed hierarchy. Instead of a raw list of tasks, every piece of planning context lives explicitly in a node taxonomy. Nothing hides in side documents or the agent's internal state:
| Node | ID | What it holds |
|---|---|---|
| Area | A-NN |
Permanent scope skeleton above goals; never archived. |
| Goal | G-NN |
Outcome with a measurable fitness function. |
| Theme | T-NN |
Optional grouping of related work items. |
| Work | W-NN |
Executable unit with Definition of Ready + Definition of Done. |
| Decision | D-NN |
ADR: immutable once accepted, superseded only with recorded rationale. |
| Question | Q-NN |
Open unknown, declared instead of pretended away. |
| Assumption | B-NN |
Falsifiable hypothesis with a validation method and result. |
| Discovery | Y-NN |
Reusable, evidence-backed knowledge distilled from finished work. |
Typed edges connect these nodes into a graph, with blocks remaining acyclic. This structure lets Grove answer both why does this task exist? and what breaks if I change it? without relying on the agent's internal state.
Once this graph exists, the routing promised above becomes mechanical. grove next picks the current step; grove packet emits exactly its context. Nothing irrelevant enters the context window.
Before touching a line of code, the agent queries the causality cone. grove packet W-NN --cone maps the backward cone (everything that must finish first, in topological contraction order), the forward cone (the blast radius if this item changes), and a fragility score per affected goal.
Turn reasoning into reusable knowledge
Grove introduces a unified methodology for AI-driven software development, informed by Dual-Track Agile, Hypothesis-Driven Development, ADRs, Continuous Discovery, Cynefin, and the Mikado method. These influences are integrated into a single workflow designed around the constraints of autonomous LLM agents and enforced through machine-checkable invariants.
Most AI workflows are tiny waterfalls: specify everything, then build everything. Grove runs discovery and delivery in parallel, each track feeding the other:
- Discovery takes open unknowns and operationalizes them. A question becomes a falsifiable assumption; validated outcomes become curated discoveries.
- Delivery executes ready work items and writes verified code on top of those assumptions.
The joints are mechanical. Questions are asked against goals; assumptions target work and gate it; discoveries guide the next goals; finished work distills back into discoveries. When a test falsifies an assumption, the plan reshapes at once; dependent work cannot proceed on a broken foundation.
Knowledge has a lifecycle
Grove does not treat distilled knowledge as permanent truth. Discoveries can become stale as the project evolves; reactivating one requires a fresh anchor. Distillation debt is tracked rather than silently accumulating, while goal fitness is re-derived on every close.
The dashboard reflects actual protocol state after every mutation, not intended state. Grove assumes that a project keeps moving: knowledge changes, assumptions are invalidated, and unfinished reasoning accumulates. The protocol makes those changes visible instead of letting them disappear into project history.
Ideas behind the protocol
- Discovery and Delivery run in parallel (Dual-Track Agile, Cagan). A work item cannot enter Delivery until every open question and unvalidated assumption that blocks it is resolved in Discovery.
- Every executable unit has explicit acceptance criteria before code is written (HDD, Definition of Ready). The DoR is not a checklist anyone can override; it is a boolean conjunction the CLI evaluates on every
status=progresstransition. - Long-lived design choices are first-class artifacts (ADR, Nygard). Decisions are immutable once accepted. They cannot be quietly revised; they can only be superseded by a new decision with a recorded rationale.
- Open unknowns are first-class artifacts; agents declare them rather than pretend to know (Continuous Discovery; Cynefin). A question tagged
chaotichalts the agent and requires human resolution. - Assumptions are falsifiable gates, not comments. An assumption in state
invalidated_blockingprevents any dependent work item from becoming ready. The agent cannot proceed by ignoring it. - Refactoring uses a Mikado-style dependency graph distinguishing causation, sequencing, implementation, and inquiry. This makes the blast radius of a change explicit before the first line is touched.
- Verified goals archive only after distillation: their validated assumptions, answered questions, and accepted decisions become Discoveries (Y), curated domain axioms that are never archived and that feed future packets.
- Areas (A) are a permanent scope skeleton above goals. Every goal belongs to exactly one area, enforced by the CLI at creation (I₁₃); areas are never archived, so the structure outlives any single goal.
Beyond spec-driven development
Spec-driven development makes specifications explicit. Grove goes one step further: it makes the development process itself executable and verifiable.
A specification describes what the system should do. Grove additionally models the state of the work around it: what is proven, what is assumed, what is blocked, what is ready, what is done, and on what evidence. These are not instructions for the agent to follow; they are protocol state that gates what the agent is allowed to do next.
This changes the workflow from document-driven execution to state-driven execution. There is no single specification to regenerate the project from and no fixed waterfall per feature. Discovery and delivery run continuously, and when an assumption is falsified, the graph and the execution plan change with it. Every state transition is mechanically gated rather than relying on the agent to follow the process correctly.
Specifications remain useful. In Grove, they can live as decisions, acceptance criteria, and other structured project knowledge attached to the work. What changes is what enforces them: the specification describes the intended outcome; the protocol determines whether the project is allowed to advance.
Let evidence decide when work is done
A task cannot even start until a Definition of Ready passes. This is a strict boolean conjunction evaluated by the protocol on every status=progress transition, not a checklist anyone can override. Once ready, Grove emits an execution packet: exactly the context the step needs (the work item, its acceptance criteria, its open questions, its assumption chain, and the decisions that constrain it) and nothing more.
Closing requires falsifiable evidence: test outputs, commit hashes, build logs. A self-reported finished is not accepted. The transition to done is atomic; goal fitness deltas and status re-derivation are applied in the same write, or not at all.
Versioned reasoning, not just versioned code
All state lives in .grove/state.lock, a single line-oriented text file with a SHA-256 checksum rewritten on every mutation. Any manual edit, rogue script, or bad merge is detected on the next protocol operation, and all state transitions are blocked until the file is repaired.
The lockfile can live inside the project repository, so the history of project reasoning evolves alongside the code, or outside it in a separate directory or repository. Both topologies are supported. When committed to version control, the lockfile's history becomes the history of the project's reasoning, not just its code.
Merge conflicts and race conditions
A typical race occurs when two branches advance project state independently:
- Branch
Amerges intomainand advances the project state. - Branch
Bwas created earlier and still contains the previous state checksum. - Merging the branches produces a checksum mismatch.
Grove detects the divergence instead of silently accepting inconsistent state.
Resolution is mechanical:
- Resolve textual conflicts, keeping records from both sides.
- Run
grove repair --confirmto re-canonicalize and re-checksum the state. - Run
grove checkto surface any invariant violations. - Run
grove renumberif ID collisions occurred between branches.
Parallel work
For parallel worktrees, grove init --id-stride/--id-offset allocates disjoint ID ranges so collisions do not happen in the first place.
On a single machine, concurrent mutations are protected by an exclusive flock, while claimed work is protected by session tokens.
Multi-machine writes to a single lockfile are out of scope by design. Remote state transitions must be routed through a single canonical writer, such as a primary CI agent.
Executable history, not just an audit trail
Git versions code. Grove versions the reasoning that produced it. Most agent harnesses and SDD (Spec-Driven Development) tools lose the "why" the moment a task is closed. Grove records every action into a persistent, executable journal, giving you something unprecedented: a full undo and replay at the level of project decisions.
Every mutation appends one JSON line to .grove/journal.log holding the command, the UTC timestamp, the session token that wrote it, and the exact inverse of the change.
{"v":1,"ts":"2026-07-19T12:35:19Z","cmd":"set","inv":{"op":"set_status_plain","id":"B-01","old_status":"testing"},"session":"host:0123456789abcdef"}
Because every record carries its own inverse, the journal is executable. grove undo replays these inverses in reverse order, restoring the exact prior state down to goal statuses, fitness deltas, and session claims. Git rolls back the implementation; Grove rolls back the hypothesis, the assumption status, and the goal fitness that justified it.
This unlocks true project replay. You can take the state at t=0 and replay the journal to see exactly how the project arrived at its current shape. It acts as a git blame for decisions: instead of just seeing who wrote a line of code, you retrace what assumption was validated, what evidence forced a pivot, and why a specific path was chosen.
The journal also captures the agent's invisible work. When the Definition of Ready (DoR) guard rejects a transition, the journal records the exact conjuncts that failed. Audit records such as gate runs, rejections, and undos are never inverted and never truncated. This captures what the agent attempted, not only what it changed.
This persistent trail powers grove log and grove stats: reconstructing cycle times, DoR first-pass rates, and content health at any point in history. Because it is written in plain JSON lines, it requires no special permissions to read, serving as the raw material for building your own metrics or conducting post-mortem analyses of agent failure patterns.
Continue when the agent disappears
A work item in progress carries an exclusive session token (only the session that claimed it can mutate it). If a provider goes down mid-goal, or a tough refactor calls for a different model, another agent on another client takes over via grove handoff. Alternatively, it adopts the session via grove resume.
All reasoning and proof live in the lockfile, so grove next and grove packet rebuild the working context instantly. The invariants keep the new agent honest; the rest of the progress cannot be faked.
The real test of agent-driven development is exactly this: when the agent stops mid-goal, the next one picks the project up without reconstructing intent from chat logs.
Preserve why the work exists
The result is not only continuity for agents. It is explainability for the people who own the project.
You can answer why a piece of code exists, what it depends on, what assumptions it rests on, and what evidence justified it months after the original work was completed.
Getting started
Grove is designed to be installed once and then used as the persistent workflow layer for your project.
The installation guide covers the CLI, MCP server, desktop application, and agent skill bundle. Then run grove init in your project root to create the checksummed state file. Connect the MCP server, add the signed skill, and bootstrap your first session with a prompt template. From then on, grove next drives every session.
Not sure if Grove fits your workflow? The Gemini Notebook holds the full documentation. Start with a simple question, like "How does Grove stop an agent from marking work done without evidence?" or "When is Grove the wrong tool for my project?"
Where it fits
Grove is most useful when work is long-running, reasoning-heavy, and performed by autonomous agents.
Security and research workflows: security work stretches over months and runs on hypotheses: most leads die, some become critical paths. Grove fits this shape natively. Every closed item carries evidence, so the audit trail is the project itself - the append-only journal, immutable decisions, and evidence-bound closes answer "who concluded what, when, and on which basis" without a separate reporting process. Priorities stop being a feeling: the critical path, per-goal fitness, and DoR gates decide what runs next, formally.
Architecture and compliance work: assumptions in Grove carry a validation method and a result; decisions carry rationale; discoveries anchor invariants to concrete surfaces. "Do we still meet our SLOs" becomes a question the state answers through goal fitness metrics, and "why is it built this way" stays answerable months later - each architectural choice points to the questions, assumptions, and evidence that produced it.
Long refactors and multi-session features: the Mikado-style dependency graph and the causality cone make blast radius explicit before the first edit, and session continuity lets the work survive agent and provider changes.
Grove is usually the wrong tool for short-lived prototypes, one-prompt tasks, and projects where the code will not outlive the session.
Grove is not a task manager, code-context tool, or multi-agent orchestrator. It is a protocol for maintaining verified project state for autonomous agents.
Protocol invariants
I₁: ∀ w ∈ W with status = progress, DoR(w) ≡ ⊤.
I₂: ∀ w with type = spike ∧ status = done,
produces(w) ⊆ D ∪ Q ∪ B ∪ Y ∧ produces(w) ≠ ∅.
I₃: ∀ w with status = done, ∃ ev ∈ Evidence, satisfies(ev, AC(w)).
I₄: |{ w ∈ W : status(w) = progress }| ≤ WIP_LIMIT (default 2).
I₅: ∀ (n₁, blocks, n₂) ∈ E, terminal⁺(n₁) before status(n₂) may transition to progress.
I₆: ∀ t ∈ T, status(t) = done ⟺ ∀ w ∈ WI(t), status(w) ∈ { done, rejected, archived }.
I₇: graph (N, E ∩ (· × {blocks} × ·)) is a DAG.
I₈: ∀ q ∈ Q with cynefin(q) = chaotic, status transitions only via human.
I₉: ∀ w ∈ W with type = feature, DoR(w) ⇒
∀ b ∈ BChain(w), status(b) ∈ { validated, invalidated_acceptable }.
I₁₀: status transition w → done is atomic with applying fitness deltas
to each g ∈ goals(w) and re-deriving status(g). Either both succeed or
neither does. The CLI rejects status=done unless deltas are staged
in the same call (or pre-staged via `grove fitness` since the last
status mutation of w).
I₁₁: ∀ w ∈ W with status = progress, the session that set it is the only
session permitted to mutate w until terminal(w) or w leaves `progress`
(e.g. `revert` or another guarded status change). Persisted as header
attrs `session` and `session_at` (UTC); `check` rejects a missing token
(`grove resume` adopts; see protocol §2.6).
I₁₂: ∀ y ∈ Y: (≥1 provenance edge: (w, produces, y) ∨ (y, distills, d/q/b))
∧ (surface(y) ≠ ∅ ∨ why(y) ≠ ∅) ∧ tags(y) ≠ ∅ (≥1 glossary term).
`proposed → active` is refused while any conjunct fails; `stale → active`
only via `grove revalidate` paid with a fresh anchor.
I₁₃: ∀ g ∈ G: ∃ a ∈ A with area(g) = a.id, recorded as the mandatory `area`
field and enforced at creation (`grove add g --area=A-NN`); re-partition
via `grove set G-NN area=A-NN`. An area-less goal in the lock is a
violation, never silently repaired.
with terminality:
terminal(w ∈ W) ⟺ status(w) ∈ { done, rejected, archived }
terminal⁺(g ∈ G) ⟺ status(g) = verified (strict for blocks edges)
terminal(g ∈ G) ⟺ status(g) ∈ { verified, declined }
terminal(d ∈ D) ⟺ status(d) ∈ { accepted, rejected, superseded }
terminal(q ∈ Q) ⟺ status(q) ∈ { answered, deferred, dropped }
terminal(b ∈ B) ⟺ status(b) ∈ { validated, invalidated_acceptable, invalidated_blocking }
terminal(t ∈ T) ⟺ status(t) = done
terminal(y ∈ Y) ⟺ status(y) = superseded
terminal(a ∈ A) ⟺ ⊥ (areas have no lifecycle)
terminal⁺ is the strict variant used for blocks edges: a declined goal does not unblock dependents. Other relations use the lax terminal.
assumptions(w) ≜ { b ∈ B | (b, targets, w) ∈ E }
BChain(w) ≜ assumptions(w) ∪ { b ∈ B | ∃ q, (q, asks, w) ∈ E ∧ (b, tests, q) ∈ E }
produces(w) ≜ { n ∈ D ∪ Q ∪ B ∪ Y | (w, produces, n) ∈ E }
goals(w) ≜ as recorded in `goals` field of w
WI(t) ≜ { w ∈ W | theme(w) = t }
FAQ
How does the state file work?
All state lives in .grove/state.lock, a single line-oriented text file with a SHA-256 checksum on every write. Any manual edit is detected immediately on the next protocol operation, and all state transitions are blocked until the file is repaired. The agent never reads or writes the file directly; it interacts only through Grove interfaces (CLI, MCP).
This design makes the entire workflow auditable and diff-friendly. Every transition is a single atomic write. The lockfile can be committed to version control; its history is the history of the project's reasoning, not just its code.
How does an agent work with Grove efficiently? Does it need to read the whole skill and write essays into the lock?
No on both counts. The skill's index.md is the minimal safe contract - one screen, complete for operation; every other page is depth you open only when the task touches its topic. And when a command's shape is unclear, the CLI itself is the instructor: refusals like add g: --area is required or DoR ≢ ⊤; see grove dor W-NN say exactly what is missing. Even an agent that never opened the skill cannot corrupt state, because the invariants (DoR gates, evidence gates, the checksum) are enforced by the protocol, not by the document - partial reading degrades process quality, never integrity.
Writing works by compression, not by transcription. The agent deliberates in its own context for as long as it needs, then stores only the conclusions: one acceptance criterion per line, one sentence per hypothesis, a compact context/options block on a decision node. Dozens of small CLI calls are normal and cheap - they batch into a single shell invocation per node (add + fields + fitness). What never belongs in the lock is the reasoning itself: if a fact does not change what a future agent does, it is not recorded. And grove next / grove packet exist precisely so the agent never re-reads the state file to plan.
License
GNU Affero General Public License v3.0 (AGPL-3.0). Copyright (c) 2026 Alex Shelepenok. Free to use, study, modify, and redistribute under the license terms, including network use: offering Grove as a network service requires offering its source. See LICENSE for the full text.
相关推荐Related
- deepseek-ai/deepseek-harness DeepSeek Harness: Everything is a Plugin.
- deepseek-ai/deepseek-harness DeepSeek Harness (dsh) — 由 DeepSeek AI 开发的开源 agent harness（智能体框架）。一切皆插件：核心 + 插件 + 技能 = 可热插拔的 AI 编程工作台。DeepSeek Harness: …
-
nexu-io/open-design
🎨 Best DeepSeek Harness Design Plugin. The open-source Claude Design alternative. 🖥️ Local-first desktop app. 🖼️ Your…
-
ruvnet/ruflo
🌊 The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build c…
-
amruthpillai/reactive-resume
A one-of-a-kind resume builder that keeps your privacy in mind. Completely secure, customizable, portable, open-source a…
-
esengine/DeepSeek-Reasonix
DeepSeek-native AI coding agent for your terminal. Engineered around prefix-cache stability — leave it running.
-
volcengine/OpenViking
Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
-
Molunerfinn/PicGo
:rocket: The Ultimate Image Uploader for Efficient Creators. Supports Obsidian, Typora, VS Code etc. and 60+ image hosti…