# Project Map

Read this first. If you're an AI agent or a new contributor and you need to
change something, find it here before searching the tree blindly.

| I want to change / understand... | Go to | Notes |
|---|---|---|
| The task/agent/validation file format itself | `schema/task.schema.json`, `schema/agent.schema.json`, `schema/validation.schema.json` | Normative. Any change here is a breaking protocol change — note it in `CHANGELOG.md`. |
| How the validation gate decides pass/fail | `scripts/validate.sh` | The only file allowed to write `approved`/`rejected` into a task. |
| How merging works, or the merge refusal rule | `scripts/merge.sh` | The only file allowed to write `merged`. Refuses if state isn't `approved`. |
| The CLI (`init`, `create-task`, `status`, `validate`, `merge`) | `bin/agentgit.js` | Thin wrapper — should never contain logic that isn't also expressible by hand-editing files. |
| Package metadata / npm distribution | `package.json` | `bin` entry points to `bin/agentgit.js`. |
| The protocol spec (human-readable) | `docs/en/protocol.md` / `docs/fr/protocole.md` | Explains the schemas; doesn't replace them. |
| Why AgentGit is scoped the way it is, vs. related tools | `docs/en/architecture.md`, `docs/en/comparison.md` (+ `fr/` equivalents) | Read before proposing scope changes — a lot of "why not X" is answered here. |
| CI / dogfooding | `.github/workflows/ci.yml` | Runs `scripts/validate.sh --self-check` on every push/PR. |
| Example `.agentgit/` state to look at or copy | `examples/.agentgit/` | A working config + agents + one sample task, for reference or as a starting point. |
| The landing page / public site | `index.html`, `sitemap.xml`, `robots.txt`, `llms.txt` | Static, deployable as-is (e.g. to Vercel). No build step. |
| Positioning diagram | `assets/positioning.svg` | Hand-authored SVG, used in `README.md` and `index.html`. |
| Contribution workflow, coding conventions | `CONTRIBUTING.md` / `CONTRIBUTING.fr.md` | |
| Security disclosure process | `SECURITY.md` | |
| Community conduct rules | `CODE_OF_CONDUCT.md` | |
| Version history | `CHANGELOG.md` | Keep a Changelog format. |

## Directory tree

```
agentgit/
├── README.md / README.fr.md        Entry point, positioning, quickstart
├── MAP.md                          This file
├── LICENSE, SECURITY.md, CODE_OF_CONDUCT.md, CONTRIBUTING(.fr).md, CHANGELOG.md
├── bin/agentgit.js                 CLI (optional convenience layer)
├── scripts/validate.sh             Validation gate (core differentiator)
├── scripts/merge.sh                Merge gate (refuses unless approved)
├── schema/*.schema.json            Normative file format
├── docs/en/, docs/fr/              Protocol, architecture, comparison
├── examples/.agentgit/             Working example state
├── assets/positioning.svg          Positioning diagram
├── index.html, sitemap.xml, robots.txt, llms.txt   Public site
└── .github/                        Issue/PR templates, CI workflow
```

## Rule for anyone editing this repo (human or agent)

If you add a file or a concept that isn't in the table above, add a row for
it in the same commit. This file is only useful if it stays accurate — an
out-of-date map is worse than no map.