agentleFS
Sign inStart free
andyridsandyrids/icm-spec/AGENTS.md

icm-spec

AGENTS.md2 starsChanged 3 months agoApache-2.0View on GitHub

This project contains a plugin for implementing spec-driven development alongside Interpretable Context Methodology (ICM). ICM orchestrates agent workflows through workspaces with folder structure, markdown and scripts. Workspaces use dedicated pipelines containing stages with a specific input, process and output. Conditional and unconditional review gates MUST be respected to allow human inspection and feedback loops. Five layers. Layers 0 to 2 route; layers 3 and 4 carry content. Load a layer only when the work has reached it - reading ahead…

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

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

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Every file above carries context-hierarchy, context-hierarchy-role and immutable as tabled, plus recommended-context-tokens where a target …

    line 37

≈ “Common” is an estimate: at least 1 in 5 of the 36,368 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

icm-spec plugin

This project contains a plugin for implementing spec-driven development alongside Interpretable Context Methodology (ICM).

ICM orchestrates agent workflows through workspaces with folder structure, markdown and scripts.

Workspaces use dedicated pipelines containing stages with a specific input, process and output. Conditional and unconditional review gates MUST be respected to allow human inspection and feedback loops.

Context hierarchy

Five layers. Layers 0 to 2 route; layers 3 and 4 carry content. Load a layer only when the work has reached it - reading ahead is how a stage acquires context it was designed not to have.

LayerRolePathimmutableBudget
0Global identityAGENTS.mdfalse900
1Workspace routingCONTEXT.mdfalse300
2Stage routingICM/*/CONTEXT.mdfalse500
2Stage contractICM/*/stages/**/CONTEXT.mdfalse500
3Reference materialICM/_config/reference-*.md, both READMEstrue2500
3Reference materialspecs/**/*.mdfalse-
4Working artifactplans/*.mdfalse-
4Working artifactICM/*/stages/**/output/*.mdfalse-

Frontmatter

Every file above carries context-hierarchy, context-hierarchy-role and immutable as tabled, plus recommended-context-tokens where a target is given. Beyond those:

  • Budgets are a signal, not an enforced limit. A file that outgrows one is worth a look - it may have started doing another layer's job. Specs are unbudgeted - a spec is as long as the behaviour it declares.
  • Layer 3 carries tags: [keyword, ...]. immutable: true marks the factory configuration, amended deliberately, not in passing. Specs are not part of it: the pipeline exists to amend them, and stage 01 owns every change.
  • plans/*.md carries status - planned | in-progress | done | blocked | cancelled - plus the query fields depends, specs, authors, issues and pr, contracted in plans/README.md. Every coverage and ripple check reads them.
  • ICM/*/stages/**/output/*.md carries status: in-progress | in-review | done. It is ephemeral scratch, gitignored.

Design principles

  1. One stage, one job - each workspace stage handles a single step of a workflow.
  2. Plain text as the interface - stages communicate through plain text.
  3. Layered context loading - agents only load context relevant for the current stage.
  4. Output is an edit surface - intermediate stage output can be opened, read, edited & saved.
  5. Configure the factory, not the product - new deliverables can use the same configuration.

Stage contracts and handoffs

Each stage in an ICM workspace (ICM/*) defines a contract with three parts; what it reads (inputs), what it does (process) and what it writes (outputs). This contract is provided in every ICM/*/stages/**/CONTEXT.md.

Download now (ZIP)

  • 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 28,693 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 repository10 other files it gives its agents.

Does it work?

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

Reviews can't be read right now.

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.

Check your setup, free