agentleFS
lautioliverlautioliver/barrilete-kit/AGENTS.md

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

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
  1. Very specific:

    Never secrets in logs, code or repo.

    line 34
  2. Distinctive:

    If a document and the code do not match, the code wins and the document is updated.

    line 35
  3. Distinctive:

    Add or adjust tests.

    line 43
  4. Distinctive:

    Update docs so they reflect what changed.

    line 45
  5. Very specific:

    Create claude/… branches, commit and open PRs (never merge them).

    line 46
  6. Distinctive:

    Add, remove or bump a major version of a dependency.

    line 51
  7. Distinctive:

    Delete data or run migrations against shared environments or production.

    line 60
  8. Common:

    Put secrets in code, logs, issues or PRs.

    line 62
  9. Very specific:

    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 …

    line 88

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

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, dev

TODO: 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.md in code, issues and PRs. A dependency between contexts that is not in depends_on of docs/agents-map.json (contexts; see docs/reference/contexts.md) needs an ADR; with no contexts declared (contexts empty) there is nothing to check. While the glossary is still TODO, 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/retros branch with retro.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-workflow skill.
  • 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:, plus business-logic and breaking-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-logic label 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-member and /remove-member; do not edit the file by hand. Assigned = owner; in progress = with an open PR.
  • Issues: opened with the create-issue skill. Title in the imperative and with no prefix; the type goes in the type: label. If it comes from an audit: Audit <area>: <finding> (the Spanish form Auditorí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 models
  • docs/github-naming-convention.md — branches, commits, PRs, issues, labels
  • docs/agents-map.json — which docs to review depending on what changes, sensitive paths, required docs
  • docs/reference/ — glossary, domain, surfaces, modules, journeys
  • docs/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, audits
  • docs/guides/ — integrations and usage guides
  • docs/decisions/ — ADRs
  • docs/agents/classes.yml — the finding classes review-pr tags with (generated by scripts/agents/sync-rules from 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 handoff y seguí su plantilla y su archivo; no armes uno a mano con otro formato. (handoff-con-bk-handoff)
<!-- rules:end -->

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.