agent-grounds/grund

> **Keep your agents grounded** — docs, values, and code as one knowledge graph, checked on every commit.
1 · Declare
Write a spec in docs/functional-spec/
# FS-login: Login
## format: Username format
### format.1: Surrounding whitespace
Trim surrounding whitespace.
2 · Cite
Cite it from the code in src/login.py
def clean_username(username):
# §FS-login.format.1
return username.strip()


3 · Read
Look it up before you change the code
$ grund FS-login.format.1
### format.1: Surrounding whitespace
Trim surrounding whitespace.
4 · Check
Misspell format , and CI fails
$ grund check
… not found: FS-login.fromat.1; …


Default structure
grund init lays a project out in layers, each citing the one that explains it, under
rules it writes commented out in grund.toml until you adopt them:
| | Kind | Home | Cites |
|-----------|-------------|---------------------------------------------------------|-----------------------------------------|
| Why | GRUND | docs/grund.md | |
| Where | GOAL | docs/goals.md | should cite GRUND or GOAL |
| What | FS | docs/functional-spec/ | should cite GOAL or FS; **never** AR |
| | REQ | docs/requirements/ | should cite GRUND or GOAL; **never** AR |
| How | AR | docs/architecture/ | should cite FS or GOAL |
| Proof | e2e | tests/e2e/ | **must** cite FS; avoid AR |
| | integration | tests/integration/ | should cite AR |
| Code | code | any other file | should cite FS or AR |
| Decisions | DF | docs/decisions/functional/ | should cite FS or GOAL |
| | DA | docs/decisions/architectural/ | should cite AR or FS |
| Plan | RM | docs/roadmap.md | |
Every rule grund check holds a project to, what each one means underneath, and the
finding it reports is listed in
Schema and links.
grund schema prints the ones a repository is held to on one screen, read from its
grund.toml alone; examples/schema/ shows its table and Mermaid output.
Agent instructions
init also writes the structure into your agent's instructions, a managed block in
AGENTS.md that grund init --check keeps current. For example, grund's own
AGENTS.md tells an agent how to read a citation:
> A § is a pointer to a fact, not a file path. Resolve it with grund and climb only as far as needed:
>
> - grund — the lead (heading-less, cut at the first child section). The cheap first read for a bare § citation.
> - grund --toc — the lead plus the nested section map. Use to choose which subsection to fetch next.
> - grund --full — the entire body. Escalate to this when narrower reads aren't enough.
Where each kind lives in this repository:
> - GRUND: Why: project motivation
> - GOAL: Where: project direction and outcomes
> - FS: What: behavior, requirements, and constraints
> - REQ: Hard requirements: what grund must never break
> - AR: How: high-level implementation, structure, and design
> - …
How it writes:
> - **Cite as you write.** Place § at the point a claim or behavior is made — on the doc-comment for a whole behavior, inline beside the clause it enforces.
> - …
> - **Inline citation style.** Inline notes: ≤ 1 line preferred, hard cap 3 lines; ≤ 100 columns. A note is one comment block: a blank line splits it, an empty comment line does not. Doc-comments (///, //!, /** */, a docstring, a Go, Ruby, shell, SQL or Lisp comment right above a definition) are documentation, not notes: they are never measured, so cite in-sentence there.
> - **Always cite the most-specific point.**
And the table's rules, as it reads them:
> must/never are grund check errors; should/avoid are suggestions (grund check --suggestions). …
>
> - Each **FS** declaration should cite GOAL or FS; never cite AR.
> - Each **REQ** declaration should cite GRUND or GOAL; never cite AR.
> - …
> - Each file in **tests/e2e/** must cite FS; avoid citing AR.
For an agent without the managed block, the loop fits in one rule for its system prompt: