agentleFS
buttjerbuttjer/n8n-decanter/plans/AGENTS.md

n8n-decanter / plans

AGENTS.md2 starsChanged 26 days agoMITView on GitHub

The backlog lives here as one file per item, sorted into four directories by status. This file is the only index; ls plans/*/ is the table of contents. (The old flat STATUS-NN-…md layout plus README.md/BACKLOG.md was retired 2026-07-23 in favour of these dirs.) - draft/ — short notes, backlog-grade: the idea, why, rough scope. A draft is the successor to the old BACKLOG.md grab-bag entry — keep it terse. It graduates into a fuller plan (moved to open/, fleshed out)…

  • 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 repository4 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, 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:

    A plan is not done until its file says so: When a plan's tasks are fully implemented, tested, and documented, flip Status: to Done and move …

    line 27

≈ “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

Plans — conventions

The backlog lives here as one file per item, sorted into four directories by status. This file is the only index; ls plans/*/ is the table of contents. (The old flat STATUS-NN-…md layout plus README.md/BACKLOG.md was retired 2026-07-23 in favour of these dirs.)

Directories = status

  • draft/ — short notes, backlog-grade: the idea, why, rough scope. A draft is the successor to the old BACKLOG.md grab-bag entry — keep it terse. It graduates into a fuller plan (moved to open/, fleshed out) when someone picks it up.
  • open/ — plans ready to (or in progress being) worked. In-progress work lives here too — the **Status:** header line distinguishes Not started from In progress.
  • done/ — fully implemented, tested, and documented.
  • blocked/ — designed but can't proceed until an external dependency clears (e.g. a licensed instance, an upstream API).

A status change is a file move between these dirs — update inbound links (they're relative paths, e.g. ../done/32-mcp-native-code-layer.md). Nothing else changes; the number and slug stay put.

Closing a plan is mandatory — it's part of the work

A plan is not done until its file says so. When a plan's tasks are fully implemented, tested, and documented, flip **Status:** to Done and move the file to done/ (updating inbound links) — in the same PR that completes the work, or immediately after if it merged without the move. Leaving a finished plan in open/ still reading Not started is drift, and closing it is the executing agent's job, not a later housekeeping cleanup.

Watch for the trap that stranded Plan 39: a PR can ship a plan's entire task list while touching none of the plan file, so nothing signals the plan is done — it sits in open/ looking untouched. If you execute a plan (or find its work already merged), close it out.

Filenames & numbers

  • NN-slug.md — NN is the plan's stable id and rough running order (how it's referenced, "Plan 32"); slug is a kebab title. The directory carries the status, so there is no status prefix in the name.
  • NN is not priority — priority is a header field, so a low-numbered plan can be P2 and vice-versa.
  • Numbers are never reused. A new item takes the next free number — one past the highest across every status dir (a number may live in any of draft//open//done//blocked/). Check them all before picking, never just one dir: ls plans/{draft,open,done,blocked}/ | grep -oE '^[0-9]+' | sort -n | tail.
  • Merging: two plans/drafts may merge in favour of the lower number; the freed number is simply retired and may stay unused forever. Gaps in the sequence are expected and fine.

Plan shape

  • Header block (before the first ##, one bold field per line):
    • # Plan N — Title
    • **Status:** Draft / Not started / In progress / Done.
    • **Priority:** P1 (do first: small, clearly-right, high-value, offline) / P2 (valuable, more scope/design) / P3 (deferred). May split per task.
    • **Source:** the backlog/draft origin and any PLAN.md refs this closes, so nothing is orphaned.
    • **Snapshot:** <UTC timestamp, minute precision> @ <7-char main commit hash> — when the plan was created or last substantively reworked, e.g. 2026-07-23T06:57Z @ 710d3f1. Refresh both on every substantive rework (scope/task changes — not typo fixes). Executing agents use this to check for drift since (see root AGENTS.md, "Backlog").
    • **Theme:** (optional) one-line what-and-why.
    • **Model:** (optional, advisory) the Claude model best suited to implement it — Opus for high-reasoning/novel design, Sonnet for well-specified breadth, Haiku for mechanical work. A hint, not a rule.
    • **Class:** (optional) — Distinctive feature for a capability that differentiates decanter from n8n itself and from generic "n8n-as-code" git-sync. These are tracked as their own class, kept visible.
  • tl;dr — the first paragraph after the header block, before the first ##. One to three sentences, no heading of its own: what this plan changes and why it matters, written so a reader who stops there still knows whether to care. Every plan and draft has one — a draft is often little more than its tl;dr plus a few lines of scope. Keep it a summary, not a preamble: no "this plan proposes…" throat-clearing, and don't restate the title.
  • Sections (fuller plans; drafts stay short and skip most of these): ## Why, ## Source, ## Tasks (numbered, grounded in real files), ## Acceptance / verification, ## Notes (CHANGELOG/PLAN.md implications, decisions, deferrals). Optional: ## Design decision, ## Non-goals, ## Rollout.
  • Cross-link related plans by relative path.

Not a design channel

These are scoped work plans, not design changes — anything that alters the data model or flows in PLAN.md must be raised with the user first (see the root AGENTS.md). DECISIONS-NEEDED.md (here at the plans root) holds open questions only the maintainer can settle.

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.