Agent Protocol

A practical engineering protocol for AI coding agents.

AI coding agents are good at writing code. The harder problem is getting them to work like disciplined engineers.

Agent Protocol provides repository-level rules for making coding agents:

• plan complex work before changing code,
• stay inside the requested scope,
• prefer simple solutions,
• fix root causes instead of symptoms,
• respect existing architecture,
• verify changes before claiming completion,
• and learn from meaningful corrections.

The Loop

Understand → Inspect → Plan → Implement → Verify → Review → Report

When something goes wrong:

Stop → Understand → Re-plan → Fix → Verify

Philosophy

The goal is not to make an AI agent write more code.

The goal is to make the smallest correct change — and prove that it works.

Repository Structure

AGENTS.md
README.md
LICENSE
templates/
  PROJECT_RULES.md
  todo.md
  lessons.md
examples/
  nextjs/PROJECT_RULES.md
  swift/PROJECT_RULES.md
docs/
  workflow.md
tasks/
  todo.md
  lessons.md

AGENTS.md defines how the agent works.

PROJECT_RULES.md templates define constraints specific to a repository.

tasks/todo.md tracks substantial work when explicit planning is useful.

tasks/lessons.md stores durable lessons from meaningful mistakes and corrections.

This separation keeps engineering behavior, project architecture, temporary work, and accumulated knowledge from becoming one giant prompt.

Quick Start

1. Copy AGENTS.md into your repository root.
2. Copy templates/PROJECT_RULES.md and customize it for the project.
3. Create tasks/todo.md and tasks/lessons.md from the templates when useful.
4. Add repository-specific build, test, architecture, and scope constraints.
5. Let your coding agent inspect these files before substantial work.

Examples

The examples/ directory contains small project-specific rule sets for Next.js and Swift repositories.

Scope of v0.1.0

The first release intentionally contains no CLI, installer, package, or enforcement layer. It focuses on a small, portable engineering protocol that can be adopted without tooling.

Status

Agent Protocol is experimental. The protocol will evolve based on real repository use and recurring failure patterns.

License

MIT.