AI-Ready Repository Reference Architecture

An AI-ready repository needs more than good source code and a capable model. It needs a structure that turns engineering intent into safe, repeatable agent behavior.

This reference architecture separates six concerns that are often mixed together: repository rules, agent roles, reusable skills, stack guidance, verification, and governance.

Reference Structure

repository/
├── AGENTS.md
├── .agents/
│   ├── planner.agent.md
│   ├── implementer.agent.md
│   ├── reviewer.agent.md
│   └── skills/
│       ├── verify-repository/
│       │   └── SKILL.md
│       ├── investigate-bug/
│       │   └── SKILL.md
│       ├── implement-feature/
│       │   └── SKILL.md
│       ├── review-change/
│       │   └── SKILL.md
│       └── update-dependency/
│           └── SKILL.md
├── docs/
│   ├── architecture.md
│   ├── testing.md
│   ├── agent-security.md
│   ├── agentic-workflow.md
│   └── stacks/
│       ├── react-typescript.md
│       ├── spring-boot.md
│       └── python.md
├── evals/
│   ├── expected-behavior.md
│   ├── planner-scenarios.md
│   ├── implementer-scenarios.md
│   └── reviewer-scenarios.md
└── application code + build configuration

1. Repository Contract: AGENTS.md

The root contract contains the rules that should remain true regardless of feature, language, or framework.

It should cover:

• how agents inspect the repository before acting;
• change-discipline expectations;
• architecture preservation;
• testing and verification expectations;
• security rules;
• how stack-specific guidance and skills are discovered.

Keep it stable. If a rule only applies to one recurring task, it probably belongs in a skill. If it applies only to Spring Boot, React, or Python, it belongs in stack guidance.

2. Agent Roles

Separate analysis, change execution, and independent review.

Agent	Purpose	Suggested tools
Planner	Understand the change, architecture, risks, and verification approach	search, read
Implementer	Make the approved change and verify it	search, read, edit, execute
Reviewer	Independently inspect the change and verification evidence	search, read, execute

The Reviewer intentionally has no edit tool. Findings return to the Implementer instead of being silently fixed during review.

3. Human-Gated Handoffs

Request
  -> Planner
  -> human reviews plan
  -> Implementer
  -> verification
  -> Reviewer
  -> human approves or sends findings back

Handoffs should preserve context while keeping a human decision between materially different authority levels.

4. Skills for Repeatable Procedures

Skills are not another place to store architecture documentation. They encode reusable procedures.

verify-repository

Discover the real quality gates from manifests, build wrappers, scripts, CI configuration, and repository documentation. Run them and report exact results.

investigate-bug

Reproduce, isolate, collect evidence, identify root cause, add regression coverage, implement the smallest fix, and verify.

implement-feature

Use the approved plan, reuse existing patterns, implement a narrow vertical slice, update tests, and verify.

review-change

Prioritize correctness, security, broken contracts, architecture, tests, verification evidence, and concrete maintainability risk.

update-dependency

Perform narrow upgrades using the existing package/build manager and lockfile strategy without turning one update into a broad dependency refresh.

5. Stack-Aware Guidance

Generic instructions should not force one architecture onto every stack.

Stack guides provide a baseline while allowing repository-specific architecture to take precedence.

React + TypeScript

• detect package manager from lockfiles and repository scripts;
• preserve existing component/state/data-fetching patterns;
• keep business rules out of presentation code where the current architecture does so;
• run configured lint, typecheck, test, and build gates.

Spring Boot

• detect Maven versus Gradle;
• prefer checked-in wrappers;
• preserve controller/service/repository and transaction conventions;
• protect Spring Security behavior;
• run repository-defined verification tasks.

Python

• detect environment/package tooling from pyproject.toml, lockfiles, and scripts;
• preserve typing, async, fixture, and module conventions;
• use the project's existing Ruff/mypy/pytest or equivalent configuration;
• avoid replacing the environment manager with a familiar default.

6. Verification as a Repository Contract

The agent should discover how the repository proves correctness rather than assume a universal command.

repository evidence
    -> aggregate verification target if present
    -> otherwise configured build/lint/type/test gates
    -> exact pass/fail evidence
    -> no completion claim while required gates fail

For multi-stack changes, verify each affected stack and the contract between them.

7. Security and Least Privilege

Agent tool access should be role-based.

Do not enable broad external systems in a generic repository by default. MCP integrations, deployment tools, cloud CLIs, database access, and production mutations should be added only when needed and with the smallest practical scope.

Default human approval should remain around:

• destructive commands;
• dependency changes;
• authentication/authorization changes;
• CI/CD and production configuration;
• external tools with mutating capability;
• deployment, release, merge, or production operations.

8. Behavioral Evaluations

Repository instructions and agent definitions are executable governance. They need regression tests of their own.

A lightweight evaluation suite should include scenarios such as:

• Planner must not edit or execute;
• Implementer detects Gradle instead of assuming Maven;
• Python changes preserve the existing environment manager;
• Reviewer catches an authorization regression;
• multi-stack changes validate both sides of the contract;
• Reviewer does not manufacture findings when the change is sound.

9. Adoption Pattern

Do not copy a demo application's architecture into a real repository. Copy the agent layer and adapt it.

1. Add or adapt AGENTS.md.
2. Add role-specific agents with least-privilege tools.
3. Add only the skills your teams actually repeat.
4. Add the stack guides relevant to the repository.
5. Document the real architecture and test strategy.
6. Identify the repository-native verification gates.
7. Add behavioral evaluation scenarios.
8. Run a small real feature through Planner -> Implementer -> Reviewer and inspect where context or controls are missing.

10. Readiness Checklist

• Repository-wide engineering contract exists.
• Architecture and toolchain can be discovered from repository evidence.
• Agent roles have explicit tool boundaries.
• Common procedures are reusable and not duplicated everywhere.
• Stack-specific conventions are documented.
• Verification is discoverable and repeatable.
• Human gates remain around consequential actions.
• External tools use least privilege.
• Agent behavior can be evaluated for regressions.

Reference Implementation

A working version of this model is available in agentic-development-starter.

For the reasoning behind the model, read The AI-Ready Repository: Designing Codebases for Coding Agents. To try the workflow, continue with Build an AI-Ready Repository with GitHub Copilot.