agentleFS
orin-dxorin-dx/agent-plugins/AGENTS.md

agent-plugins

AGENTS.md1 starsChanged yesterdayMITView on GitHub

This guide defines the top-level repository guidelines for AI coding agents (Claude Code, AGY, Cursor, Copilot, Codex) working on or utilizing the Wisp Plugins repository (orin-dx/wisp-plugins). All hard rules for plugin and agent authoring live in one place: 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…

1 other project uses a version of this.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 1

    1. orin-dx/wisp-plugins★ 1100% same

    Edited · 0

    None found.

    Wrote their own version · 0

    None found.

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repository3 other files it gives its agents.

The file

We split this AGENTS.md into the rules it gives an agent

1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

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

    line 9

≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

Wisp Plugins 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 the Wisp Plugins repository (orin-dx/wisp-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, verification that tells the wrong behavior from the correction, with no fixed test order.
  • shared/harness-authoring.md: Cross-harness change classification, native workflow boundaries, and required counterpart review.
  • docs/adr/README.md: Index of accepted architectural decisions, each with a guardrail. Read the record before changing what its guardrail names; shared/references/architecture/decision-records.md says when and how to write one.
  • shared/references/tooling/cli.md: Capability-aware preferences for modern CLI tools, with repository-native commands and safe fallbacks taking priority.

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              <-- opus/high  — refutation that decides a finding
    └── 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, mason, and muse 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 spec-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.

Agents are organized by cognitive mode (enumeration, tracing, adversarial, systemic, behavioral, judgment, repair) — not by pipeline position. See shared/constitution.md for the model/effort tier rules.


3. Quick Checklist for Adding New Plugins

  1. Use mason — run scaffolder to generate the full directory structure and stubs.
  2. 4-part agent structure — every agent body: <constitution> (copied byte-for-byte from an existing agent), <goal>, <judgment>, <output>. No <role> or <backstory> body sections. No success_criteria checklists.
  3. EARS in output only — WHEN/IF/WHILE/WHERE notation belongs only in <output> contracts and never-do rules.
  4. Progressive context loading — one <load_first> block per agent, naming only the focused references needed for its cognitive phase.
  5. Schema-first handoffs — define shared/schemas/<name>@<version>.json before writing the agent that produces it.
  6. Abstract tool language — "use your file reading tool", never view_file, read_file, or Bash tool.
  7. Instruction economy — keep one actionable rule per item, remove repeated rationale, and number only order-dependent work.
  8. Radical candor — state material concerns, evidence, consequence, and confidence directly; do not soften blockers, manufacture praise, or overstate certainty.
  9. Reference routing and quality — organize by cognitive concern, use language filenames only for language-specific evidence, and state outcome, applicability, evidence, refutation, and disposition.
  10. Verification evidence — match checks to risk; require generators and oracles, independently derived semantic candidates, fresh state, terminal results, and explicit gaps when relevant.
  11. Cross-harness review — preserve identity, skill routes, artifact contracts, evidence, and acceptance intent in Claude/AGY and Codex sources; native wording and delegation may differ.
  12. Manifest registration — add an entry to root marketplace.json and validate: jq . marketplace.json.
  13. Legal attribution — set author in plugin.json to the {name, email} object shown in CONTRIBUTING.md.

4. Validation

just check

just --list shows each check as its own recipe (just manifests, just test, just versions, just skills-doc, just reference-size, just marketplace-check, just mermaid) for running a subset while editing; run the full set before release. just fmt/just fmt-check format with oxfmt; not yet part of just check until the repo has a baseline format pass. To bump a version, edit plugins/<id>/plugin.json (the ecosystem's is marketplace.json's top-level version), add the matching top CHANGELOG.md entry, and run just claude-manifests-sync && just marketplace-sync; never hand-edit the README **Version:** line, badge, marketplace entry, or Claude or Codex manifest versions. Generated Codex files in .agents/plugins/ and dist/codex/ must match their authored sources; never edit them directly — run just marketplace-sync after a Codex source change.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.