Contributing to The Agentic Developer's Playbook

Thank you for helping build the canonical resource for agentic software engineering. This guide explains how to contribute effectively.

Contribution Tiers

Tier 1: Low Barrier (no prior approval needed)

Just open a PR:

  • Typo fixes and grammar corrections
  • Broken link repairs
  • New config examples in reference/configs/
  • New prompt templates in reference/prompts/
  • Updates to tested_with version pins in tool-specific files
  • Minor clarifications that don't change meaning

SLA: Merged within 48 hours.

Tier 2: Medium Barrier (review required)

Open a PR using the appropriate template:

  • New patterns in reference/patterns/ (must use _TEMPLATE.md)
  • New anti-patterns in reference/anti-patterns/ (must use _TEMPLATE.md)
  • New case studies (must use _TEMPLATE.md)
  • Version migration updates to curriculum modules
  • New troubleshooting entries
  • New entries in GLOSSARY.md

SLA: First review within 72 hours.

Tier 3: High Barrier (RFC process)

Open a GitHub Discussion (RFC category) before writing code:

  • New curriculum modules
  • Structural changes to the repository
  • Changes to the contribution model
  • New practice projects

SLA: Discussion opens within 1 week.

Content Standards

YAML Frontmatter (required on all content files)

---
title: Your Content Title
tested_with:
  claude-code: "1.0.x"    # omit if not tool-specific
  codex-cli: "0.2.x"      # omit if not tool-specific
last_updated: 2026-03-21
status: experimental       # experimental | proven | battle-tested
difficulty: intermediate   # beginner | intermediate | advanced
prerequisites: []          # list of module IDs, e.g., [02-project-memory]
---

Writing Style

  • Second person — address the reader as "you"
  • Lead with why — explain the reason before the steps
  • Concrete over abstract — show real examples, not theoretical descriptions
  • Define terms on first use — link to GLOSSARY.md for formal definitions
  • Copy-paste ready — every code block should work when pasted, with "Adapt this by..." notes
  • Include cost estimates — note rough token costs for expensive workflows

The Dual-Layer Rule

  • concepts.md = tool-agnostic principles (should rarely change)
  • claude-code.md / codex-cli.md = tool-specific implementations (updated with tool releases)
  • Never put tool-specific instructions in concepts.md

Pattern Maturity

Don't self-rate as "battle-tested." New submissions start as experimental. Maturity is earned through community validation:

  • Experimental — you've used it, it works for you
  • Proven — multiple contributors have validated it
  • Battle-Tested — used in production by teams, edge cases documented

File Naming

  • All lowercase
  • Hyphens, not underscores: fan-out-fan-in.md not fan_out_fan_in.md
  • Descriptive names: god-session.md not ap-001.md
  • Templates always named _TEMPLATE.md

Before Submitting

  • YAML frontmatter is present and complete
  • last_updated reflects today's date
  • tested_with versions are current (for tool-specific content)
  • All code examples are tested and runnable
  • Internal links use relative paths
  • No tool-specific content in concepts.md files
  • New terms added to GLOSSARY.md

Reporting Issues

Code of Conduct

Be respectful, be constructive, be honest. This project values accuracy over cheerleading — if something doesn't work, say so. If a pattern has limitations, document them.