Agentic Coding Playbook

Practical, tool-agnostic playbook for federal employees building software with AI coding agents.

Note: This playbook represents best practices. Tailor to your agency's ATO requirements and policies.

Agentic Coding Ecosystem

This repository is part of a three-repo ecosystem:

Your journey: After getting your environment running (Quickstart), use this Playbook to set up your projects with good defaults, then share what you learn in Patterns.

---

Quick Start

# 1. Copy the project plan template into your repo
cp templates/PROJECT_PLAN.md /path/to/your-repo/PROJECT_PLAN.md

# 2. Fill out PROJECT_PLAN.md — project name, tech stack, compliance level

# 3. Validate the plan
make validate-plan PLAN=/path/to/your-repo/PROJECT_PLAN.md

# 4. Check your environment
make doctor

# 5. Tell your AI agent: "Bootstrap this project from PROJECT_PLAN.md"

The agent reads your plan and sets up everything: AGENTS.md, coding standards, directory structure, CI/CD, risk assessment, and security docs. See PLAYBOOK.md for the full walkthrough.

---

What This Is

A set of markdown files, templates, and validation tools that help AI coding agents follow secure-by-default practices when assisting federal employees with software development. Drop these files into any repository to establish consistent behavioral standards across the full development lifecycle.

A practical, living approach to secure AI-assisted development for federal teams — usable across single-agent and multi-agent ("swarm") workflows, and spanning backend, frontend, accessibility/Section 508, and the full development lifecycle. It is grounded in current federal requirements and security and software-development best practices; it is not authoritative federal policy, and it does not replace your agency's own authorization decisions.

The Two-Layer Contract

Agent behavioral rules are split into two layers:

• Universal contract — this repository's AGENTS.md, the Federal AI Agent Behavioral Best Practices. It applies to every project and is the single source of truth for the universal rules (core principles, identity, least privilege, data protection, prompt-injection defense, meta-constraints, engineering discipline). It is not copied into individual projects — that would let copies drift.
• Project layer — a thin AGENTS.md in each project (see templates/AGENTS.md.template) that declares the universal contract as a prerequisite and adds only project-specific rules.

Making the universal contract available

Because the universal contract is not vendored per-project, each project expects it to be provided by the environment at a conventional location:

~/.agentic-coding-playbook/AGENTS.md      # (override with $AGENTIC_CODING_PLAYBOOK_HOME)

The supported way to provision it is the agentic-coding-patterns acq provisioning kit, applied by the acq wrapper, which selects a sandbox backend and makes the contract available to agents in a sandboxed environment:

https://github.com/GSA-TTS/agentic-coding-patterns/tree/main/integrations/isolation/acq-kits

If the home path is unavailable, projects bootstrapped by this playbook ship a self-contained probe (scripts/ensure-contract.py) that populates a git-ignored fallback cache at .agents/cache/AGENTS.universal.md from the pinned release, warning that the copy is a fallback. Presence is a deterministic, fail-closed check enforced at session start, in a pre-commit hook, and in CI — if the contract cannot be obtained, work does not proceed. See ADR-0002 and ADR-0003.

Who This Is For

---

The Playbook Path

Full details: PLAYBOOK.md

---

Skills — Executable Best Practice Procedures

Skills convert best practices into step-by-step workflows that any AI coding agent can follow. The behavioral contract (AGENTS.md) uses the AGENTS.md standard, supported by 25+ AI coding tools.

---

Developer Tools

All validation and generation tools live in the scripts/playbook_validator/ Python package (560 tests).

make help              # Show all available commands
make setup             # Install dependencies + pre-commit hooks
make test              # Run all tests
make lint              # Ruff lint + format check
make validate          # Run all document validators
make doctor            # Check environment readiness
make ci                # Reproduce full CI locally

Prerequisites: Python 3.12+, pip install -e ".[dev]"

---

Framework Alignment

Every practice maps to one or more authoritative sources:

Full catalog of 42 federal AI guidance documents: docs/FEDERAL-AI-LANDSCAPE.md

---

Repository Structure

agentic-coding-playbook/
├── AGENTS.md                        # Universal agent behavior rules (AGENTS.md standard)
├── PLAYBOOK.md                      # Step-by-step guide: setup → deploy
├── CONTEXT-GUIDE.md                 # Agent entry point — routes to right docs
├── INDEX.yaml                       # Machine-readable document index
├── Makefile                         # Developer commands (make help)
├── pyproject.toml                   # Python config (ruff, pytest, PyYAML)
├── docs/
│   ├── AGENT-INSTRUCTIONS.md        # Detailed tooling reference
│   ├── CODING_PRACTICES.md          # Secure coding standards
│   ├── SECURITY-CONTROLS.md         # 35 NIST 800-53 controls mapped
│   ├── FEDERAL-AI-LANDSCAPE.md      # Federal AI guidance catalog
│   └── ...                          # See docs/README.md for full index
├── data/
│   └── federal-ai-landscape.yaml    # Machine-readable guidance registry
├── scripts/
│   ├── playbook_validator/          # Python validation package (560 tests)
│   └── tests/                       # TDD test suite
├── skills/                          # 12 executable compliance procedures
├── templates/                       # PROJECT_PLAN.md, AGENTS.md.template
├── examples/                        # Completed AGENTS.md example
└── checklists/                      # 62-item pre-deployment checklist

---

Where this applies

• Agentic workflows: single-agent and multi-agent / swarm approaches. (Note: multi-agent patterns add threat surface — inter-agent prompt injection, wider tool/credential blast radius — and our guidance there is still maturing.)
• Across the stack: backend, public-facing and frontend work, and accessibility / Section 508.
• Security baseline: written against a FIPS Moderate baseline; adapt the controls to your own system's impact level and ATO.
• Lifecycle: the full software development lifecycle.

What this is not

• Not authoritative federal policy and not a substitute for your agency's security authorization (ATO) process. Confirm any requirement against its current authoritative source (NIST, OMB, your agency) — this repo is a practical snapshot, not the system of record.
• Not a foundation for FIPS High or classified systems. Consult your agency's security team for those contexts.
• Not procurement guidance — see OMB M-25-22.
• Community-maintained and evolving. Methods here are community-tested, not guaranteed; provided as-is under CC0 1.0 with no warranty.

---

Contributing

We welcome contributions from the federal agentic-coding community.

• Fix it directly — Submit a PR
• Questions — Open a GitHub issue or start a discussion
• Not sure how? — Open an issue to discuss

See CONTRIBUTING.md for details. This project uses conventional commits and automated releases via release-please. Documentation follows our accessibility statement (Section 508).

Share What You Learn

Discovered a useful workflow or pattern? Consider contributing it to the Patterns repo so others can benefit.

License

CC0 1.0 Universal — public domain. Federal employees may freely use, modify, and distribute this playbook.