# Repo knowledge base

> What agents must know about your project lives in your repo — notes in `docs/agents/` with `AGENTS.md` as the index — and the Software Factory reads it and keeps it up to date through PRs.

URL: https://www.ghosty.studio/en/docs/factory/knowledge

The decisions, pitfalls and vocabulary the code doesn't say by itself live **in your own repo**, not in Ghosty:

- **Versioned** and reviewed through PRs, like any code.
- **Any agent** reads it: Claude Code, Codex, Cursor or goose read `AGENTS.md` on their own.
- No external index that goes stale.

## The format

```text
AGENTS.md              ← index: commands, architecture, conventions and the "Conocimiento" section
docs/agents/
  payments.md          ← one note per topic
  time-zones.md
  glossary.md
```

Each note is short: **what** it is, **why** it was decided that way and **how** to apply it. In `AGENTS.md`, one line per note:

```markdown
## Conocimiento
Short notes in `docs/agents/`: decisions, pitfalls and glossary the code doesn't say by itself.

- [Payments](docs/agents/payments.md) — amounts are in cents; Stripe is the source of truth
- [Time zones](docs/agents/time-zones.md) — everything is stored in UTC and shown in Mexico City time
```

"Prepare repo" already adds the "Conocimiento" section to the `AGENTS.md` it writes.

## How the factory uses it

| Role | What it does with the base |
|---|---|
| `@plan` | Gets the list of notes on every turn, reads the ones on topic and cites them in the plan. If the request settles a decision that isn't written down, the plan says "Note: `docs/agents/<topic>.md`". |
| `@build` | If the plan asks for a note, if its change settles a convention or if it finds a pitfall, it writes or updates the note **in the same PR** plus its line in `AGENTS.md`. |
| `@check` | If the PR contradicts a note, or the note the plan asked for is missing, that's a finding. |

So the base grows with every request, and every change to it goes through your review.