agentleFS
Sign inStart free
manhquydevmanhquydev/flow-skill/AGENTS.md

flow-skill

AGENTS.md9 starsChanged 28 days agoMITView on GitHub

Session entry for Claude, Codex, Antigravity, and Cursor contributors working in this repo. Root CLAUDE.md is a symlink to this file. On Windows, if core.symlinks=false, git may materialize a text file whose contents are the target name AGENTS.md — still read this file. Do not confuse root CLAUDE.md with skills/flow/law/CLAUDE.md (build-session law for a project run; different home, out of scope here). Flow owns the gates and the receipts, never the runtime. Constitution: docs/adr/0001-discipline-layer-identity.md. Do not grow a runtime, daemon,…

  • 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 31,774 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

3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    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. Distinctive:

    Do not grow a runtime, daemon, agent loop, tool-execution wrapper, or server without reopening that ADR.

    line 13
  2. Distinctive:

    Process token: Every flow byte runs because a hosting agent or the operator invoked it, and flow terminates when that returns.

    line 48
  3. Very specific:

    Eval STOP: Do not modify the live _eval_engine_run body or _run_with_timeout in skills/flow/runner/flow.sh.

    line 50

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

Agent standing orders

Session entry for Claude, Codex, Antigravity, and Cursor contributors working in this repo. Root CLAUDE.md is a symlink to this file. On Windows, if core.symlinks=false, git may materialize a text file whose contents are the target name AGENTS.md — still read this file. Do not confuse root CLAUDE.md with skills/flow/law/CLAUDE.md (build-session law for a project run; different home, out of scope here).

Identity

Flow owns the gates and the receipts, never the runtime. Constitution: docs/adr/0001-discipline-layer-identity.md. Do not grow a runtime, daemon, agent loop, tool-execution wrapper, or server without reopening that ADR.

One home per fact

Point; do not copy. If a fact already has a home, link it.

FactHome
InstallREADME.md (short front door)
Command tableskills/flow/references/command-dispatch.md
Skill dispatch + semantic gateskills/flow/SKILL.md
Build-session / card lawskills/flow/law/CLAUDE.md
UI lawskills/flow/law/DESIGN.md
Semantic gate challengesskills/flow/references/gate-rules.md
Architecture layersdocs/system-architecture.md
Quality numbersdocs/quality-metrics.md
Release / dual versionsdocs/release-process.md
Suite registrytests/manifest.txt
Word budgetsdocs/doc-budgets.txt
Identity / process-tokendocs/adr/0001-discipline-layer-identity.md

Layout (pointers)

  • skills/flow/ — installable skill (runner, harness, templates, law, references, eval)
  • npm-wrapper/ — installer CLI; bundled skill tree is generated by scripts/sync.mjs (gitignored). Parity is tarball --compare, not git diff of that tree.
  • tests/ — bash suites listed in tests/manifest.txt; run via bash tests/run_all.sh
  • docs/ — architecture, quality-metrics, release-process, journals, adr/
  • website/ — retired from repository; maintained in standalone successor repository manhquydev/flowskill-website.

Homeless standing orders

These have no other home. Keep them here only.

  1. Process token. Every flow byte runs because a hosting agent or the operator invoked it, and flow terminates when that returns. Full invariant: the identity ADR.
  2. Eval STOP. Do not modify the live _eval_engine_run body or _run_with_timeout in skills/flow/runner/flow.sh. If a change requires either, stop and report.
  3. Locate by content. Find code by searching content, not by plan-file line numbers (they drift).
  4. No billable live claude calls unless the operator explicitly checkpoints. Replay and fixtures are the offline path.
  5. Do not invent a second home for a fact that already has one.

Commands (entry only)

Full verb table: skills/flow/references/command-dispatch.md. Everyday: /flow (status), /flow next, /flow card, /flow check C-NNN, /flow doctor. Codex: $flow. Mechanical ground truth is bash skills/flow/runner/flow.sh <cmd> (exit 0/1).

Conventions

  • bash 3.2-safe; zero new runtime deps; degrade loudly, never lower a gate.
  • Skill product and npm installer share one SemVer (docs/release-process.md).
  • New bash suites: tests/test_*.sh and a tests/manifest.txt row in the same change.
  • A wave that adds a gate-enforced rule adds ≥1 hollow/sound eval fixture pair (ADR).
  • docs/doc-budgets.txt is enforced in preflight/CI; advisory during a /flow run.

Test-evidence protocol

Match evidence to the surface you changed. Do not default to the full 3-OS suite.

ChangeEvidence
One bash suite / runner slicethat suite; add tests/test_manifest_runner.sh if the registry moved
sync.mjs / npm-wrappercd npm-wrapper && npm test
Pack / install pathbash scripts/pack-rehearsal.sh
Docs / budgetsbash scripts/check-doc-budgets.sh and tests/test_doc_budgets.sh
Version / release surfacebash scripts/check-release-coherence.sh
Cross-cutting runner / harnessbash tests/run_all.sh

CI source of truth is GitHub Actions bash-suite (ubuntu/macos/windows) under all-checks-passed. Pushes to research branches do not run GHA (on.*.branches: [master]).

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.

Check your setup, free