# AgentGit Protocol Specification (v1, pre-alpha) ## Directory layout Every repository orchestrated by AgentGit gets a `.agentgit/` directory: ``` .agentgit/ ├── config.yaml # orchestrator settings for this repo ├── agents.json # registered agents and their current status ├── tasks/ │ └── .json # one file per task — see schema/task.schema.json ├── validations/ │ ├── .json # written ONLY by scripts/validate.sh │ └── .log # captured stdout/stderr of the validation run ``` Schemas live in `schema/*.schema.json` and are the normative definition — this document explains them, it doesn't replace them. ## Two levels of access 1. **The file format is the source of truth.** Any agent, in any language, can participate by reading and writing these JSON files directly and running ordinary `git` commands. No SDK, no import, no required runtime. 2. **The CLI (`bin/agentgit.js`, published as the `agentgit` npm package) is a convenience layer**, not a dependency. `npx agentgit create-task "..."` does exactly what hand-editing `.agentgit/tasks/AG-N.json` would do. If your agent runtime can already read files and run `git`, it can already speak AgentGit. ## Task lifecycle ``` draft → assigned → in_progress → submitted → validating → approved → merged ↘ rejected → in_progress (rework) (blocked, cancelled: side states from any point before merged) ``` Only `scripts/validate.sh` may move a task to `approved` or `rejected`. Only `scripts/merge.sh` may move a task to `merged`, and it refuses to run unless the task is already `approved`. This is the one rule the whole protocol exists to enforce: **no task is merged on an agent's word alone.** Both gate scripts commit the state change they write immediately, on whatever branch is currently checked out. An orchestrator calling `scripts/merge.sh` must do so while still on the task's own branch — the script reads the task file, then switches to the target branch itself. Switching to the target branch first will make the task file unreadable to it (it may only be committed on the source branch at that point). ## Branch convention One branch per task, named from `branch_pattern` in `config.yaml` (default: `agent/{agent_id}/{task_id}`). Agents never commit directly to the target branch (`main` by default). ## What is explicitly NOT part of the protocol Task decomposition strategy, scheduling/priority logic, dashboards, and multi-repo coordination are application-layer concerns, deliberately left out of the core — the same scoping choice made by related protocols like gnap. Keeping the core to "files + two gate scripts" is what keeps it portable across languages and runtimes. See `docs/en/architecture.md` for where AgentGit chose to draw that line and why.