AGENTS.md

AGENTS.md is a generated markdown file that tells any AI coding tool how to participate in your project’s coordination system. It’s the bridge between the codepakt server and agents that start fresh without memory of the project.

Generate it

cpk generate

This creates two files inside .codepakt/:

• .codepakt/AGENTS.md — portable coordination protocol (readable by any agent)
• .codepakt/CLAUDE.md — Claude Code-specific instructions (uses @import)

On first run, it also creates root AGENTS.md and CLAUDE.md with references to the .codepakt/ versions.

Regenerate whenever agents change or you want to update the coordination protocol.

What it contains

Agent Protocol

A step-by-step workflow any agent should follow:

## Agent Protocol

1. `export CPK_AGENT=<your-name>`
2. `cpk task mine` — check existing work
3. `cpk task pickup` — claim next available task
4. Read task.context_refs for relevant docs: `cpk docs read <id>`
5. Do the work
6. `cpk task done <id> --notes "what you did"`
7. If blocked: `cpk task block <id> --reason "why"`
8. If you learned something: `cpk docs write --type learning --title "..." --body "..."`
9. Repeat from step 2

Active Agents

A snapshot of agents that have interacted with the project:

## Active Agents

- **backend** (working on T-002)
- **frontend** (idle)

File ownership model

codepakt owns the files inside .codepakt/. Your root files are yours.

my-project/
├── CLAUDE.md              ← YOU own (add @import + your own rules)
├── AGENTS.md              ← YOU own (pointer or custom content)
└── .codepakt/
    ├── AGENTS.md           ← codepakt owns — safe to regenerate
    ├── CLAUDE.md           ← codepakt owns — safe to regenerate
    ├── config.json         ← git-ignored
    └── data.db             ← git-ignored

Why it works

AI coding tools (Claude Code, Codex, Cursor, GitHub Copilot) all understand markdown. When an agent reads AGENTS.md at session start, it learns:

• The coordination protocol — exactly which CLI commands to run and when
• Which agent identity to use (--agent flag or CPK_AGENT value)
• Who the other agents are and what they’re working on

This means you don’t need to write a custom system prompt for each agent. The protocol lives in the file and stays in sync with the server state.

Keeping it current

AGENTS.md is a snapshot, not a live sync. Regenerate and commit whenever the team changes:

cpk generate
git add .codepakt/AGENTS.md .codepakt/CLAUDE.md
git commit -m "chore: regenerate coordination files"

Where to put it

The generated files live in .codepakt/ and are committed to git. Root files reference them:

• CLAUDE.md uses @import .codepakt/CLAUDE.md (Claude Code loads this automatically)
• AGENTS.md contains a pointer comment directing agents to .codepakt/AGENTS.md

Related

• cpk generate — full command documentation
• Agents & Coordination — how agents interact with the board