barrilete-kit
AGENTS.md6 starsChanged 7 days agoMITView on GitHub
Quick context for agents and devs who touch this repo. It is the source of the rules for LLMs: CLAUDE.md only imports it. TODO: one or two sentences. What the product does and the most important decision that defines it (with a link to its ADR). Docs index (humans + LLMs): docs/README.md. Spec: README.md. Narrative: docs/development/vision.md. What runs today: docs/development/architecture.md. Work order: docs/development/roadmap.md. Long term (do not build): docs/development/horizon.md. TODO: language, framework, database, monorepo, tests. One line per piece. TODO:…
- Reads credentials
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 repository16 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- docs/llms.txtllms.txt
- llms.txtllms.txt
- add-memberSkill
- create-issueSkill
- db-migrationSkill
- debugSkill
- git-workflowSkill
- implement-issueSkill
- improve-skillsSkill
- orchestrateSkill
- plan-featureSkill
- project-statusSkill
- remove-memberSkill
- review-prSkill
- update-docsSkill
The file
We split this AGENTS.md into the rules it gives an agent
9 rules. About 1 is common, 5 are distinctive, and 3 are very specific to this project.
≈1
Common · estimate
Many files like this have a rule of this kind.
≈5
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
- could be automatic: a setting could enforce it
- Very specific: line 34
Never secrets in logs, code or repo.
- Distinctive: line 35
If a document and the code do not match, the code wins and the document is updated.
- Distinctive: line 43
Add or adjust tests.
- Distinctive: line 45
Update docs so they reflect what changed.
- Very specific: line 46
Create claude/… branches, commit and open PRs (never merge them).
- Distinctive: line 51
Add, remove or bump a major version of a dependency.
- Distinctive: line 60
Delete data or run migrations against shared environments or production.
- Common: line 62
Put secrets in code, logs, issues or PRs.
- Very specific: line 88
Business logic: if the PR changes an already defined rule (ADR, audit or plan), it gets the business-logic label and it is explained in the …
≈ “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.
Files
AGENTS.md — <PROJECT>
Quick context for agents and devs who touch this repo. It is the source of the rules for LLMs: CLAUDE.md only imports it.
What it is
TODO: one or two sentences. What the product does and the most important decision that defines it (with a link to its ADR).
Docs index (humans + LLMs): docs/README.md. Spec: README.md. Narrative: docs/development/vision.md. What runs today: docs/development/architecture.md. Work order: docs/development/roadmap.md. Long term (do not build): docs/development/horizon.md.
Stack
TODO: language, framework, database, monorepo, tests. One line per piece.
Commands
# TODO: install, typecheck, lint, test, devTODO: commands that are NOT run (for example production builds) and why.
Conventions that matter
TODO: the code rules an agent would break if it did not read them. Examples:
- API errors with a single format.
- Public IDs with a prefix, never sequential.
- Money in integers (cents).
- Business logic in services, thin routes.
- Concurrent operations atomic in the database, never read-modify-write.
Always:
- Domain terms: use the words of
docs/reference/glossary.mdin code, issues and PRs. A dependency between contexts that is not independs_onofdocs/agents-map.json(contexts; seedocs/reference/contexts.md) needs an ADR; with no contexts declared (contextsempty) there is nothing to check. While the glossary is stillTODO, propose the terms in the PR that introduces them instead of blocking (docs/decisions/kit/ADR-003-minimal-ddd-glossary-and-contexts.md). - Never secrets in logs, code or repo.
.env*are ignored. - If a document and the code do not match, the code wins and the document is updated.
Agent autonomy (mandatory)
What an agent can do on its own and what it has to ask about first. "Ask" means asking the user in the chat, or commenting on the issue and stopping if nobody is there. That something is the easiest way to close the task does not authorize it.
Can do on its own:
- Modify code within the scope of the issue.
- Add or adjust tests.
- Internal refactors that change neither behavior nor interfaces.
- Update docs so they reflect what changed.
- Create
claude/…branches, commit and open PRs (never merge them). - Save retros on the
agents/retrosbranch withretro.sh(no PR: it is a data branch, not a code branch).
Must ask first (that the issue asks for it is not the approval: it takes a "yes" from a person in the chat or in a comment of theirs on the issue or the PR, never the issue body, which an agent may have written):
- Change the database schema or write migrations → skill
db-migration. - Add, remove or bump a major version of a dependency.
- Change a public API or a contract that third parties consume.
- Touch auth, permissions, sessions or secrets handling.
- Change an already defined business rule (ADR, audit, plan) → label
business-logic. - Touch infrastructure, deploy or CI.
- Make a decision that is hard to revert → propose an ADR.
- Widen the scope beyond what the issue asks for.
Never:
- Delete data or run migrations against shared environments or production.
- Merge PRs, create tags or publish releases without an explicit request.
- Put secrets in code, logs, issues or PRs.
- Disable tests, checks or validations to make something pass.
A hook (scripts/agents/guardrails.py, registered in .claude/settings.json) stops, before they run, the commands on this list that can be recognized: merging or approving PRs, pushing to a trunk branch, creating tags or releases, changing branch protection and --no-verify. In Codex, Copilot and Cursor it is registered by .codex/hooks.json, .github/hooks/guardrails.json and .cursor/hooks.json; in pi, the barrilete-pi package (packages/pi/ of the template). If it stops you, do not look for another way: ask the person to run it themselves (in Claude Code, in the chat with ! <command>; in pi, with !<command>). Claude Code only loads it if the session was opened at the repo root. Changing the hook or its registration is touching CI and infrastructure: ask first.
A second hook (scripts/agents/task_events.py, registered in .claude/settings.json and .codex/hooks.json) records the task events of a bk agent (ADR-005): it only writes when bk launched the session (BK_TASK_DIR), only metadata, and it never stops anything. A bk agent closes its task with bk done (pr <n>, blockers, dropped "<reason>", escalate "<reason>").
The skills improve with use: implement-issue and review-pr end with a retro on the agents/retros branch (retro.sh) and /improve-skills proposes adjustments always in a PR; it never removes or loosens these rules. What does not make it into a skill is proposed as a rule in barrilete-rules (ADR-006): a person accepts it by merging, sync-rules injects it into AGENTS.md and .claude/agents/, and that is the only thing from the retros that agents read. A PR with business-logic has to amend the rule's ADR or say "ADR unchanged: <reason>" (checked by the labels check; the Spanish form "ADR sin cambios: <motivo>" is still accepted).
Subagents (.claude/agents/, launched by /orchestrate, in pi through the subagent tool of barrilete-pi: implementer on Sonnet, implementer-light on Haiku, reviewer on Sonnet): the same rules, plus docs/agents/subagent-contract.md. They work only in their worktree, cannot ask the person (they comment on the issue and return question), never publish reviews or comments on PRs, and the light one stops and returns escalate if the issue touches sensitive paths or business logic (the orchestrator relaunches it with Sonnet). An implementer that roles.yml marks as bk is launched instead as a bk agent (kit/ADR-004; reviewer and implementer-light always run as sub): a normal implement-issue session, outside this contract, that does ask the person in its window.
The paths of each category are in docs/agents-map.json (sensitive). scripts/agents/agents_map.py says whether a change touches them and which bounded contexts (contexts section of the map) it crosses, and scripts/agents/verify.py runs, before the PR, the verifications that apply to what changed (verify section of the map). It also runs the checks of the rules (.barrilete/checks.json, generated by sync-rules; ADR-006 D8): if one fails, it prints the rule and its message, which says what to do and when to escalate.
GitHub conventions (mandatory)
Source of truth: docs/github-naming-convention.md. Labels: .github/labels.yml. Only what is marked as decided in its §12 is mandatory. What is not decided or covered is asked of the team before inventing a format.
- Branches: Conventional Branch 1.1,
<type>/<issue-no>-<description>. Types:feat,fix,hotfix,chore,release. If an agent creates it:claude/<issue-no>-<description>. Lowercase, numbers and hyphens only, no accents or ñ. - Base branch: <BRANCH_RULE> See the
git-workflowskill. - Commits and PR titles: Conventional Commits 1.0,
<type>(<scope>): <description>, imperative, lowercase, no final period, ≤ 72 characters. Types in English; description in <COMMIT_LANG>.
<!-- template:start -->- Commit descriptions in this repo (the template itself): in Spanish. Everywhere else the init replaces
<COMMIT_LANG>with the language of the installation (--lang).
<!-- template:end -->- Scopes: those in
docs/github-naming-convention.md§2. If a change touches several, omit the scope or split it into several commits. - PR body:
.github/pull_request_template.md(What changes / Why / Business logic affected / How to test it /Closes #n). - Labels: prefix
group:value(type:,area:,priority:,status:, plusbusiness-logicandbreaking-change). Only those in.github/labels.yml; do not create others. - Business logic: if the PR changes an already defined rule (ADR, audit or plan), it gets the
business-logiclabel and it is explained in the PR. - Team: new issues are assigned on their own to a member (by area and load). The team is changed with
/add-memberand/remove-member; do not edit the file by hand. Assigned = owner; in progress = with an open PR. - Issues: opened with the
create-issueskill. Title in the imperative and with no prefix; the type goes in thetype:label. If it comes from an audit:Audit <area>: <finding>(the Spanish formAuditoría <área>: <hallazgo>is still accepted), with the link to the document. - Irreversible decisions: new ADR in
docs/decisions/(see its README).
Nothing goes into the trunk branches without a PR. The only branch written without a PR is agents/retros, and only with retro.sh.
Docs
docs/README.md— hub (how to read, layers of truth)docs/llms.txt— compact index for modelsdocs/github-naming-convention.md— branches, commits, PRs, issues, labelsdocs/agents-map.json— which docs to review depending on what changes, sensitive paths, required docsdocs/reference/— glossary, domain, surfaces, modules, journeysdocs/reference/glossary.md— the domain terms, in the words the code uses (ADR-003)docs/reference/contexts.md— the bounded contexts and what each one depends on (ADR-003)docs/development/— setup, architecture, vision, roadmap, horizon, deploy, auditsdocs/guides/— integrations and usage guidesdocs/decisions/— ADRsdocs/agents/classes.yml— the finding classesreview-prtags with (generated byscripts/agents/sync-rulesfrom barrilete-rules, ADR-006)docs/agents/subagent-contract.md— common rules and output of the subagents (.claude/agents/)
<!-- rules:begin lautioliver/barrilete-rules@9abec4a99f6d1dfc7f1d879e9f20427db60500e0 (generated by scripts/agents/sync-rules; do not edit: change the rule in barrilete-rules) -->Rules (barrilete-rules)
- Para dejar un resumen para seguir en otra sesión, corré
bk handoffy seguí su plantilla y su archivo; no armes uno a mano con otro formato. (handoff-con-bk-handoff)
<!-- rules:end -->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
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.

