stoa-platformstoa-platform/stoa/AGENTS.md

stoa

AGENTS.md9 starsChanged 7 months agoApache-2.0View on GitHub

This repo uses CLAUDE.md as the canonical AI agent contract. AGENTS.md exists as the cross-agent entry point for any AI coding assistant (Claude Code, Codex, Cursor, Aider, etc.). AI agents working in this repository must: 1. Read CLAUDE.md at the repo root for project rules, architecture, runtime versions, workflow, and GO/NOGO gates. It is the single source of truth — this file does not duplicate its content to avoid drift. 2. Read the component-scoped CLAUDE.md inside the directory you are…

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 repository27 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- cli/CLAUDE.mdCLAUDE.md
- control-plane-api/CLAUDE.mdCLAUDE.md
- control-plane-ui/CLAUDE.mdCLAUDE.md
- e2e/CLAUDE.mdCLAUDE.md
- portal/CLAUDE.mdCLAUDE.md
- stoa-gateway/CLAUDE.mdCLAUDE.md
- analyticsSkill
- cartoSkill
- ci-debugSkill
- ci-fixSkill
- competitive-watchSkill
- councilSkill
- decomposeSkill
- extractSkill
- fill-cycleSkill
- generate-backlogSkill
- impactSkill
- memory-consolidateSkill
- monitor-cdSkill
- parallel-reviewSkill
- pr-guardianSkill
- rewriteSkill
- roadmapSkill
- spec-drivenSkill
- sync-planSkill
- verify-megaSkill

The file

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

5 rules. About 0 are common, 2 are distinctive, and 3 are 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.
3
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Distinctive:
Read CLAUDE.md at the repo root for project rules, architecture, runtime versions, workflow, and GO/NOGO gates.
line 11
Very specific:
Read the component-scoped CLAUDE.md inside the directory you are editing (e.g.
line 14
Very specific:
Follow the same rules regardless of the tool brand.
line 20
Distinctive:
Write in English by default: pull request titles and descriptions, review comments, commit messages, code comments, docs and any public …
line 26
Very specific:
When touching an API operation exposed to agents, load the canonical rule in CLAUDE.md and .claude/docs/uac-llm-ready.md:
line 47

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

AGENTS.md — STOA Platform

This repo uses CLAUDE.md as the canonical AI agent contract. AGENTS.md exists as the cross-agent entry point for any AI coding assistant (Claude Code, Codex, Cursor, Aider, etc.).

Contract

AI agents working in this repository must:

Read CLAUDE.md at the repo root for project rules, architecture, runtime versions, workflow, and GO/NOGO gates. It is the single source of truth — this file does not duplicate its content to avoid drift.
Read the component-scoped CLAUDE.md inside the directory you are editing (e.g. stoa-gateway/CLAUDE.md, control-plane-api/CLAUDE.md, control-plane-ui/CLAUDE.md) when touching that service.
Load .claude/docs/<topic>.md on demand when a rule in CLAUDE.md references it. These docs are protocols, examples, and gotcha tables — never auto-loaded, only pulled in when the topic is in scope.
Follow the same rules regardless of the tool brand. The .claude/ storage path is a naming convention, not a tool lock-in; any AI agent is expected to honor the rules defined there.

Language

Write in English by default: pull request titles and descriptions, review comments, commit messages, code comments, docs and any public communication. See the Language section of CONTRIBUTING.md. Conversations with the maintainer outside the repository may use another language; what is committed or published stays in English.

Architecture (quick reference)

CONTROL PLANE (Cloud)                    DATA PLANE (On-Premise)
┌────────────────────────────┐           ┌──────────────────────┐
│ Portal  Console  API  Auth │  ←sync→   │ STOA GW webMethods   │
│ (React) (React) (Py) (KC) │           │ (Rust)  Kong/Envoy   │
└────────────────────────────┘           └──────────────────────┘

For component paths, runtime versions, RBAC roles, rules, skills, and repo map, see CLAUDE.md.

Agent-facing API doctrine

When touching an API operation exposed to agents, load the canonical rule in CLAUDE.md and .claude/docs/uac-llm-ready.md:

UAC describes.
MCP projects.
Smoke proves.

Historical note

The Python mcp-gateway/ service was retired in Feb 2026 and superseded by stoa-gateway/ (Rust). Any reference to mcp-gateway in older docs or comments is historical.

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