agentleFS
Sign inStart free
theagentplanetheagentplane/control-plane/AGENTS.md

control-plane

AGENTS.md4 starsChanged 30 days agoMITView on GitHub

The control plane is the shared HTTP service of the AgentPlane suite. It stores what Chronicle records (traces, spans, envelopes), serves it back (query, visualization, replay reads), and holds the governance state TokenOps enforces (budgets, policies, segments and the shared ledger). Agents and browsers talk HTTP; only this process opens the database. This file is read by AI coding agents (Claude Code, Codex, Cursor, Copilot and others). Humans may find it useful too. - The entities (Trace, Span, Envelope, ids,…

  • 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,700 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 repository2 other files it gives its agents.

The file

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

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

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    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:

    Before changing architecture,: read the ADRs: structure, public interfaces, data formats, dependencies or anything shared with another …

    line 26
  2. Distinctive:

    Do not invent reasoning: If you do not know why something was decided or which alternatives were weighed, ask.

    line 32
  3. Very specific:

    Must work on Windows and Linux.

    line 66
  4. Distinctive:

    Keep one change as one thing: Do not mix unrelated changes into a pull request.

    line 77

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

The control plane is the shared HTTP service of the AgentPlane suite. It stores what Chronicle records (traces, spans, envelopes), serves it back (query, visualization, replay reads), and holds the governance state TokenOps enforces (budgets, policies, segments and the shared ledger). Agents and browsers talk HTTP; only this process opens the database.

This file is read by AI coding agents (Claude Code, Codex, Cursor, Copilot and others). Humans may find it useful too.

Source of truth

  • The entities (Trace, Span, Envelope, ids, enums) come from agentplane-primitives (pinned ==0.2.*). Never define a local copy of an entity. A gap there is an issue in that repository.
  • Chronicle's design is in chronicle docs/rfcs/chronicle-technical-design.md, section 10.2 lists what this service must do for it.
  • The HTTP request and response wrappers belong to this repository (primitives ADR 0003).
  • trace_id is the only run identifier. There is no run_id (chronicle ADR 0009).

Architecture decisions

Decisions that shape this repository are recorded as ADRs in docs/adr/.

  • Before changing architecture, read the ADRs: structure, public interfaces, data formats, dependencies or anything shared with another repository. Do not undo an accepted decision silently. If a change conflicts with one, say so and propose a new ADR that supersedes it.
  • When asked to record a decision, or when you make one that meets the criteria in docs/adr/README.md, write an ADR: copy docs/adr/template.md, use the next free number, keep it to about a page, and add it to the index.
  • Do not invent reasoning. If you do not know why something was decided or which alternatives were weighed, ask. Leave the status as Proposed: the people named as deciders accept it.
  • Never rewrite an accepted ADR. Supersede it with a new one.

Database rules

  • SQLAlchemy Core only, and Alembic owns the schema. The tables are defined once in control_plane.db.tables; every schema change is a new Alembic revision in control_plane/db/migrations/versions. Never edit an applied revision.
  • No sqlite3 import outside the engine factory (db/engine_utils.py), and no raw SQL strings. The database is chosen by CONTROL_PLANE_DATABASE_URL; code must work on any dialect SQLAlchemy supports. Dialect-specific behaviour lives in the engine factory only.
  • Every table is tenant-scoped (tenant_id in the key) and every query filters on it.
  • A revision must not use dialect-specific SQL; use op.batch_alter_table for SQLite.

Layers

Each layer imports only from the ones before it.

LayerPackageRule
Settings and auth typessettings, authNo I/O.
DatabasedbTables, engine, migrations. The only place that knows a dialect.
RepositoriesrepositoriesThe only code that runs queries. One repository per concept.
APIapiFastAPI routers. Validate with primitives models; no SQL.
Interfacesweb, cliThe browser page and the command line.

Code layout and style

  • src layout, typed package (py.typed), Python 3.10 to 3.13 (no syntax newer than 3.10).
  • One concept per file, with a module docstring that says what it is. Folders are named for what they hold; helper modules are suffixed for what they are (*_utils.py, *_types.py). __init__.py re-exports the public names with __all__.
  • Types and functions live apart: no functions in model modules, no models in utils.
  • Must work on Windows and Linux. On Windows use python -m pytest.
  • Tooling: uv, ruff (line length 100), mypy --strict, pytest. Run the checks listed in CONTRIBUTING.md before you finish.

Change size

  • Estimate before writing code: lines added plus removed, not counting generated files, lockfiles, migrations or pure moves and renames.
  • If the estimate is above 400 lines, stop and plan. Propose to the user a short plan that splits the work into logical components (each reviewable on its own, passing CI, in order), and wait for agreement before implementing. Open one pull request per component.
  • Keep one change as one thing. Do not mix unrelated changes into a pull request.
  • Staying above 400 lines is acceptable for boilerplate, mechanical changes or generated code, or when the maintainer has decided on one change (as for the 1.0 rework), but say why in the pull request description and keep the work reviewable commit by commit.

Related repositories

chronicle (edge SDK: record, save, replay) · primitives (shared schemas) · control-plane (storage, query, UI) · tokenops (cost governance)

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