Agent Playbook

A portable, tool-agnostic file structure playbook for LLM agents in software projects.

Agent behavior is code. It should be versioned, reviewed, modular, and readable by both humans and machines. The src/ folder is the single source of truth for everything an LLM agent needs to operate within a project — permissions, instructions, skills, memory, commands, and documentation artifacts.

Overview

Every team using LLM agents invents their own folder structure. Instructions live in random .md files, prompts are buried in config, and memory is nowhere. When the runtime changes or someone new joins the project, nothing is discoverable.

This playbook gives agents — and the humans working alongside them — a consistent, predictable home. It defines where agent instructions, rules, skills, memory, commands, and documentation live, consistently across any project and any runtime.

Features

• AGENTS.md — Primary instruction file and manifest. Every runtime loads this first.
• src/rules/ — Modular, composable instruction files.
• src/skills/ — Auto-invoking workflows triggered by events or file patterns.
• src/commands/ — Explicit slash commands.
• src/agents/ — Subagent personas invoked by @mention.
• src/memory/ — Persistent, append-only memory across sessions.
• docs/ — Task-scoped documentation with standardized layout (PRD, SPEC, ARCHITECTURE, TASKS).

Core Principles

• Co-location — Agent files live alongside the code they govern.
• Modularity — Each concern lives in its own folder, adopted incrementally.
• Composability — Rules, skills, and agents mix and match across projects.
• Portability — Works with any LLM runtime: Claude, Cursor, Copilot, custom.
• Progressive disclosure — Start with one AGENTS.md. Add folders as needed.

Folder Structure

agent.md/              # ← this repository
├── src/           # Maintained agent asset library
├── docs/              # Task-scoped documentation
├── pages/             # GitHub Pages source
│   ├── _config.yml    # GitHub Pages configuration
│   ├── index.md       # GitHub Pages entry point
│   └── PLAYBOOK.md    # Full playbook specification
└── LICENSE

Quick Start

The minimum viable setup is a single file:

AGENTS.md

Write your agent instructions. Add folders only when you have a reason to.

Playbook setup

AGENTS.md
.agents/
├── rules/
│   └── general.md
└── memory/
    └── MEMORY.md

Full setup

Add skills/, commands/, agents/, and docs/ as the project matures.

Usage

Library

This repository maintains its primary reusable agent assets in src/:

• Rules — src/rules/formatting-markdown.md
• Skills — src/skills/on-new-example/SKILL.md
• Commands — src/commands/validate.md
• Agents — src/agents/spec-reviewer.md
• Memory — src/memory/MEMORY.md

Real project layout

project-root/
├── AGENTS.md                  # Primary instruction file + table of contents
├── .agents/
│   ├── rules/                 # Modular instruction files
│   │   ├── code-style.md      # TypeScript conventions
│   │   ├── testing.md         # Test coverage requirements
│   │   └── security.md        # OWASP top-10 awareness
│   ├── skills/                # Auto-invoking workflows (trigger → action)
│   │   ├── on-new-file/       # Auto-scaffold test files
│   │   │   └── SKILL.md
│   │   └── on-test-fail/      # Diagnose CI failures
│   │       └── SKILL.md
│   ├── commands/              # Custom slash commands
│   │   ├── review.md          # /review — structured code review
│   │   └── scaffold.md        # /scaffold — generate boilerplate
│   ├── agents/                # Subagent personas
│   │   ├── architect.md       # @architect — system design advisor
│   │   └── security-auditor.md # @security — OWASP-focused review
│   └── memory/                # Persistent agent memory
│       ├── MEMORY.md          # Long-term memory
│       └── YYYY-MM-DD.md      # Daily notes
├── docs/                      # Project-scoped documentation
│   ├── ARCHITECTURE.md
│   ├── ROADMAP.md
│   └── YYYY-MM-DD-task-name/
│       ├── PRD.md
│       ├── SPEC.md
│       ├── ARCHITECTURE.md
│       ├── DESIGN.md
│       └── TASKS.md
├── src/
├── package.json
└── README.md

Development

This repo uses itself to govern its own development — the src/ folder is the maintained set of playbook-conformant assets used for that work.

# No build step required. All content is plain Markdown.
# Fork, edit, and open a pull request.

Enable repository-managed Git hooks once per checkout:

git config core.hooksPath .githooks

The pre-commit hook runs Markdown lint fixes before each commit.

Contributing

1. Fork the repository.
2. Create a feature branch (git checkout -b feat/your-feature).
3. Commit your changes following Conventional Commits.
4. Open a pull request.

Before writing code, create a task folder: mkdir docs/$(date +%Y-%m-%d)-my-feature and use TASKS.md as your checklist.

References

• Docs site — GitHub Pages documentation
• PLAYBOOK.md — Full playbook specification
• Agent PDLC — Lifecycle diagram for working with an agent
• Library — Maintained playbook-conformant assets

License

MIT — see LICENSE for details.

---

This playbook is intentionally tool-agnostic. Runtimes may extend it provided they do not break compatibility with the core specification.