agent-plugins AGENTS.md

Orin DX AI Agent & Skill Specification (AGENTS.md)

This guide defines the top-level repository guidelines for AI coding agents (Claude Code, AGY, Cursor, Copilot, Codex) working on or utilizing orin-dx/agent-plugins.

---

1. Authoritative Sources

All hard rules for plugin and agent authoring live in one place:

• shared/constitution.md: EARS-format authoritative constraints. The fence all plugin development must stay inside. Read this first and last.
• shared/agent-best-practices.md: Principles behind the constitution, explained with examples. Authoring-time only — never loaded by agents at runtime.
• shared/debugging-laws.md: Core proof laws, read-only investigation rules, Red-to-Green verification standards.
• shared/references/modern-cli-tools.md: Global preference directive for modern CLI tools (bat, zoxide, ripgrep, fd, eza, delta, jq, fzf, gh).

---

2. Directory Layout Standard

plugins/<plugin-id>/
├── plugin.json                   <-- Plugin Manifest (id, version, skills, agents)
├── README.md                     <-- Purpose, trigger phrases, agent table, install
├── CHANGELOG.md                  <-- Semver history
├── skills/
│   └── <plugin-id>/
│       └── SKILL.md              <-- Skill definition (dispatch matrix, pipeline)
└── agents/
    ├── recon.md                  <-- haiku/low  — deterministic enumeration
    ├── scanner.md                <-- sonnet/med — pattern matching
    ├── adversary.md              <-- sonnet/med — adversarial verification
    └── exit-gate.md              <-- opus/high  — binding judgment

A plugin defaults to one skill directory named after the plugin id, as above. IF the plugin's scope covers several genuinely independent, heterogeneous intents on the same artifact — not a linear pipeline invoked as one flow — skills/<plugin-id>/ may split into skills/<skill-name>/SKILL.md per skill instead. courier, scribe, weaver, and mason are examples. The skill-routing key is the directory name, not the frontmatter name: field. A new skill name defaults to a single lifecycle-stage word; only go to a specific compound name (audit-spec, not scribe-audit) when the bare word is ambiguous or collides with another plugin's existing skill name. See shared/constitution.md's Plugin Structure and Skill Names sections.