Skip to content

AGENTS.md

Latest commit

 

History

History
58 lines (42 loc) · 3.56 KB

AGENTS.md

File metadata and controls

58 lines (42 loc) · 3.56 KB

AGENTS.md

This is the context file for this repository -- the one about context engineering. CLAUDE.md is symlinked to this file for Claude Code compatibility. For usage notes and an overview of what's here, read the README.

What This Project Is

A public companion repo to Rethinking Team Topologies for AI-Augmented Development. Working examples of context file structures (single-file, context directory, cascading, agents) alongside reference copies of the context-setup plugin (which has since moved!). Patterns you understand are here, IDE helpers you can install from ordovera/ordovera-plugins.

Structure

  • examples/ -- All patterns and templates, organized by complexity level
    • single-file/ -- Four single-file AGENTS.md examples at different complexity levels
    • directory/ -- Full context directory with six template files
    • cascading-files/ -- Global, project, and subdirectory cascading examples
    • agents/ -- Agent-as-workflow pattern with two example agents and shared config
    • agent-teams/ -- Multi-agent teams with optional Jira integration (activation, team structure, phases, templates)
  • examples/claude-config/ -- Working skills and hooks configuration (copy to .claude/)
  • plugins/ -- Reference copies of Claude Code plugins (install from ordovera/ordovera-plugins instead)
    • context-setup/ -- Scaffold, audit, align, optimize MCP tools, usage diagnostics, and upgrade context files
  • evolution.md -- What changed since the June 2025 article

Standards

  • No emojis, no decorative symbols
  • kebab-case filenames
  • Direct, practitioner voice -- not academic, not marketing
  • Conventional commits (feat/fix/docs/etc)
  • All markdown must pass markdownlint (MD013 disabled for line length)
  • Example files use [bracket] placeholders -- no fictional companies or products

Navigation

Read different files depending on the task:

  • Adding or editing examples: read the target directory's README.md first, then the existing examples for the pattern
  • Understanding the repo's purpose and framing: README.md
  • Understanding what changed since the article: evolution.md
  • Understanding cross-agent coordination: examples/agents/README.md and examples/agents/shared-config.json
  • Setting up agent teams with Jira: examples/agent-teams/README.md
  • Setting up skills and hooks via copy: examples/claude-config/README.md
  • Installing skills via plugin: install from ordovera/ordovera-plugins; local plugins/context-setup/ is a reference copy

File Format Convention

Every example file follows the same structure:

  1. Title and intro -- what this example is, when to use it (2-3 sentences)
  2. Fenced template -- the actual AGENTS.md content the reader would copy, wrapped in backtick fences
  3. Notes section -- explains why the template is structured this way, when to graduate to something more complex

Files containing nested markdown code blocks use 4-backtick outer fences (````) to avoid parsing issues. Template content uses [bracket] placeholders describing the kind of content that belongs there.

Do NOT

  • Add fictional company names, product names, or branded examples
  • Add application code -- this is a documentation-only repo
  • Modify example templates without updating the corresponding README if structure changes
  • Add new top-level sections without updating the root README file tree