Skip to main content

07.07Operating method

A git repository as a second brain for AI coding agents

How AR Labs uses one git repository as memory for AI coding agents: layered documents, one per concern, and one instruction file for Claude Code and Codex.

On this page
  1. How it works
  2. Progressive disclosure
  3. One instruction file for two agent programs
  4. Where the design is heading
  5. What exists today

AR Labs keeps one git repository as the second brain for its coding agents (AI agents that write code, such as Claude Code or Codex): plain-text files about our goals and work that an agent reads each session. A coding agent starts every session with an empty context window, so whatever it needs to know about the company, a project or a decision has to be found and read again. The company's strategy, every project's goals and approach, research, working notes and the agents' own instructions all live in the repository, arranged so that an agent can reconstruct exactly the context a request needs and no more. The repository is the memory of VOX, the lab's working system; this page is for anyone setting up a codebase or knowledge base that agents must navigate on their own.

How it works

The repository has a small number of top-level areas, each with a different job:

Area Holds
Company Vision, mission, roadmap, activity map, the strategy agent and its procedures
Working The current-focus dashboard, dated goal indexes and exploratory notes
Projects Our own products, infrastructure and content
Clients Client engagements, organised by delivery stage
Library Research and reference material not tied to one project
Agent configuration Skills, rules, agent definitions and hooks

The rule that separates projects from clients is simple: work delivered for a client goes under clients; everything we build for ourselves goes under projects.

Progressive disclosure

Within any area, documents are layered so that the most general and constraining information loads first and each layer narrows what matters in the next. The pattern is called progressive disclosure. The figure opens one project folder and stacks its four levels in loading order, each marked with how often it changes, from rarely at the top to hours or days at the bottom.

Six repository areas with Projects highlighted, zooming into one project's four levels: AGENTS.md, STRATEGY.md, plan or task graph, and tasks, each labelled with how often it changes. The repository has six areas: company, working, projects, clients, library and agent configuration. Zooming into one project shows its documents in loading order. Level 1, AGENTS.md (with CLAUDE.md as a link to it), says what success looks like and rarely changes. Level 2, STRATEGY.md, says how the project is pursued now and changes with pivots. Level 3 depends on the project type: a task graph, a build log, a content plan or research findings, changing over days or weeks. Level 4 is individual tasks, changing over hours or days. Each concern has one authoritative document; others point to it. The repository as a second brain PROGRESSIVE DISCLOSURE · THE MOST GENERAL, MOST CONSTRAINING DOCUMENT LOADS FIRST; EACH LEVEL NARROWS THE NEXT FIGURE PROGRESSIVE DISCLOSURE DRAWN BY AR LABS SHEET 1 / 1 Company Working Projects Clients Library Agent config THE REPOSITORY ONE PROJECT AGENTS.md What does success look like? LEVEL 1 rarely changes STRATEGY.md How are we pursuing it right now? LEVEL 2 changes with pivots Plan, build log or task graph What is being worked on? LEVEL 3 days to weeks Tasks The atoms of execution LEVEL 4 hours to days LOAD IN THIS ORDER HOW OFTEN IT CHANGES LEVEL 3 BY PROJECT TYPE software with a task graph: the task graph itself software without one: a build log content: a plan research: findings CLAUDE.md is a link to AGENTS.md, so Claude Code and Codex read one instruction file. Each concern has one authoritative document; every other document points to it.
The most general, most constraining document loads first; each level narrows the next.

Level 1 is the project's entry file, which states the outcome and changes rarely. Level 2 is a strategy file, mandatory for every project, holding the current approach and a dated log of pivots with their reasons. Level 3 depends on the project type: a task graph (all tracked tasks and the dependencies between them) for software tracked in Beads, Steve Yegge's open-source issue tracker for coding agents; a build log for other software; a content plan; a research findings file. Level 4 is the individual work items. Each level links explicitly to the next, so an agent follows a chain rather than searching.

A few rules keep the layers trustworthy across the whole repository. Each concern has exactly one authoritative document, and other documents point to it rather than restating it. A fact lives in the document that loads when the fact is relevant. Documents state current truth and leave the history to git, so there are no inline edit dates or notes about what an earlier draft said. The full set, with the reasons behind each, is on progressive disclosure for project documentation.

One instruction file for two agent programs

We run both Claude Code and OpenAI's Codex in the same repository. Each is an agent program: it wraps a model with its tools and reads standing instructions from a file. Codex reads AGENTS.md, an open convention for agent instructions; Claude Code reads CLAUDE.md. In each maintained folder AGENTS.md is the authoritative file and CLAUDE.md is a relative symbolic link to it, so both agent programs read one document and nothing has to be kept in sync by hand. A navigation skill gives Codex the same entry procedure Claude Code gets from its own configuration: load identity and writing rules, read the root conventions, then walk down the ancestor instruction files to the area the request concerns. Reading a project's index does not activate every tool or methodology it mentions; those load only when the task needs them.

Where the design is heading

A single repository fuses three layers that want to be separate: the brain (skills, rules, agent definitions), the state (task records and memory) and the content (projects, clients, strategy). Fused, a product cannot leave the repository without leaving its tooling behind. We plan to make the brain installable in any repository, to serve task state and memory to any repository as services, and to move each product into its own repository with its own small set of entry documents.

That move will not trade versioning away. Project documents always live in some properly versioned git repository, committed rather than ignored. Storage is private, versioned and complete; publication is a deliberate, derived and scrubbed act, such as a public mirror without internal planning files. The first extraction of a product into its own repository, with its history preserved, has been done; the rest of the plan, including serving task state as a service, is not yet built.

What exists today

The monorepo, the progressive-disclosure hierarchy, mandatory strategy files and the shared AGENTS.md and CLAUDE.md arrangement are in daily use by Claude Code and Codex sessions. The portable brain and state services described above are designs.