Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -125,7 +125,7 @@ Default vocabulary: `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-

### Domain docs

Single-context: one `CONTEXT.md` + `docs/adr/` at the repo root. See `docs/agents/domain.md`.
Single-context: one `GLOSSARY.md` + `docs/adr/` at the repo root. See `docs/agents/domain.md`.

## Canonical references

Expand Down
2 changes: 1 addition & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -132,7 +132,7 @@ Default vocabulary: `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-

### Domain docs

Single-context: one `CONTEXT.md` + `docs/adr/` at the repo root. See `docs/agents/domain.md`.
Single-context: one `GLOSSARY.md` + `docs/adr/` at the repo root. See `docs/agents/domain.md`.

## Canonical references

Expand Down
File renamed without changes.
24 changes: 12 additions & 12 deletions docs/agents/domain.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,13 @@

How the engineering skills should consume this repo's domain documentation when exploring the codebase.

**This repo is single-context**: one `CONTEXT.md` (not yet written) and one `docs/adr/` at the repo root. There is no `CONTEXT-MAP.md` — don't go looking for per-context docs.
**This repo is single-context**: one `GLOSSARY.md` and one `docs/adr/` at the repo root. There is no `GLOSSARY-MAP.md`, so don't go looking for per-context docs.

## Before exploring, read these

- **`CONTEXT.md`** at the repo root, or
- **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
- **`docs/adr/`** — read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
- **`GLOSSARY.md`** at the repo root, or
- **`GLOSSARY-MAP.md`** at the repo root if it exists: it points at one `GLOSSARY.md` per context. Read each one relevant to the topic.
- **`docs/adr/`**: read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.

If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved.

Expand All @@ -18,36 +18,36 @@ Single-context repo (most repos):

```
/
├── CONTEXT.md
├── GLOSSARY.md
├── docs/adr/
│ ├── 0001-event-sourced-orders.md
│ └── 0002-postgres-for-write-model.md
└── src/
```

Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
Multi-context repo (presence of `GLOSSARY-MAP.md` at the root):

```
/
├── CONTEXT-MAP.md
├── GLOSSARY-MAP.md
├── docs/adr/ ← system-wide decisions
└── src/
├── ordering/
│ ├── CONTEXT.md
│ ├── GLOSSARY.md
│ └── docs/adr/ ← context-specific decisions
└── billing/
├── CONTEXT.md
├── GLOSSARY.md
└── docs/adr/
```

## Use the glossary's vocabulary

When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `GLOSSARY.md`. Don't drift to synonyms the glossary explicitly avoids.

If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).
If the concept you need isn't in the glossary yet, that's a signal: either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).

## Flag ADR conflicts

If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:

> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_
> _Contradicts ADR-0007 (event-sourced orders), but worth reopening because…_
2 changes: 1 addition & 1 deletion docs/architecture/snapshot-model.md
Original file line number Diff line number Diff line change
Expand Up @@ -264,7 +264,7 @@ The PII story will need refinement with a real security review. Documented now s
| Write overhead | < 5ms per row | p99 latency added to agent writes by segment streaming |
| Snapshot storage | < 2× changed data | Amortized over many snapshots |

These are the binding v1.0 numbers — see [`CONTEXT.md`](../../CONTEXT.md) for the commitment vs target-under-verification vocabulary.
These are the binding v1.0 numbers — see [`GLOSSARY.md`](../../GLOSSARY.md) for the commitment vs target-under-verification vocabulary.
The point of committing to numbers publicly is so we don't ship a fast demo and a slow product.
As of 2026-07-11, `rollback` < 5s is a **target under verification** at the committed shape
(only measurement: 10.34 s on laptop-class hardware; cloud-class run tracked in
Expand Down
2 changes: 1 addition & 1 deletion docs/product/mvp-spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,7 @@ If a feature isn't in the demo path, it doesn't ship in MVP.
The 1M-row criteria are not yet verified at the committed shape:
snapshot measures green so far (18.81 ms @ 1M rows, laptop, approximated shape),
but rollback measures 10.34 s @ 1M rows on laptop-class hardware —
a **target under verification** per [`CONTEXT.md`](../../CONTEXT.md),
a **target under verification** per [`GLOSSARY.md`](../../GLOSSARY.md),
with the cloud-class run tracked in [issue #132](https://github.com/git-agentic/git.agentic/issues/132).
See [`benchmarks.md`](../architecture/benchmarks.md) for the measurements.
- **Narrative:** A blog post / video showing the broken-prompt demo that explains the wedge clearly enough that a hostile-but-fair YC partner gets it in under 90 seconds.
Expand Down
Loading