agentleFS
mrdaioffmrdaioff/baby-brain/AGENTS.md

baby-brain

AGENTS.md0 starsChanged 2 months agoMITView on GitHub

Read by: Codex, Cursor, Amp, Command Code, Zed, Jules, Aider, and any other CLI that reads AGENTS.md. The repository's rules live in .agents/agent.md — the single canonical source shared by every AI coding CLI. Edit that file and run npm run sync:agents. Never edit this file directly; changes here are overwritten and fail CI. This is the single canonical source of repository-wide rules for any AI coding agent working here — Claude Code, Codex, Copilot, Gemini, Cursor, or whatever exists…

The file

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

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

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

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

    If the target file does not exist yet, create it.

    line 46
  2. Very specific:

    Every file in knowledge_base/ and brand/ needs YAML front matter.

    line 93
  3. Very specific:

    When any part of the hosted pipeline misbehaves, go to TROUBLESHOOTING.md before reading the workflow source.

    line 111
  4. Very specific:

    A content pipeline: If you publish, the brand/ → knowledge_base/ → draft path is worth automating.

    line 150

≈ “Common” is an estimate: at least 1 in 5 of the 42,283 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
<!-- GENERATED FILE — DO NOT EDIT. Source of truth: .agents/agent.md Regenerate: npm run sync:agents CI gate: .github/workflows/check-agent-sync.yml -->

Read by: Codex, Cursor, Amp, Command Code, Zed, Jules, Aider, and any other CLI that reads AGENTS.md. The repository's rules live in .agents/agent.md — the single canonical source shared by every AI coding CLI. Edit that file and run npm run sync:agents. Never edit this file directly; changes here are overwritten and fail CI.


Agent Instructions

This is the single canonical source of repository-wide rules for any AI coding agent working here — Claude Code, Codex, Copilot, Gemini, Cursor, or whatever exists next year. Every instruction file at the repo root (CLAUDE.md, AGENTS.md, GEMINI.md, .github/copilot-instructions.md) is generated from this file. Edit this one, then run npm run sync:agents. See .agents/README.md for how that works and how to add a new CLI.

If _system/install.yml is missing or says tier: unset, stop and read .agents/skills/install/SKILL.md first. This repo has not been set up yet.


The rule this repo exists to enforce

Everything below is machinery. This is the part that matters:

The repo is the source of truth. Read it before you work; write to it after.

Concretely, every session:

  1. Before working on a unit of client work, read that folder's context.md. All of it. It exists so you do not re-derive what a previous session already established, and so you do not contradict a decision that was already made.
  2. After doing anything meaningful — a build, a decision, a bug fixed, a validation passed, an open item closed — update context.md and open-items.md without being asked. Then commit and push.
  3. When something important surfaces in conversation and is not written down anywhere, write it down and say so in chat.

An agent's own memory does not count. Every CLI has some private store — a memory directory, an auto-derived preferences file, a session cache. Each one is invisible to every other tool and to the human's next session on a different machine. Those stores are a cache of this repo, never the authority. When something true and portable ends up in one, move it into the relevant committed file and delete the private copy, so there is exactly one version to keep correct. See .agents/memory/index.md.

Where to route a new fact:

The fact is aboutIt goes in
How to work in general — git, verification, destructive actions.agents/working-agreements.md
A tool's behaviour or a gotcha you just hit.agents/tooling.md
Which commercial context something belongs to.agents/work-contexts.md
This repo's own rules or architecture.agents/agent.md (then npm run sync:agents)
The state of a specific piece of client workprojects/<slug>/context.md

If the target file does not exist yet, create it. Do not skip the update because the file is missing.


Start here

Four companion files carry context this one does not. Read them at the points below.

FileRead it when
.agents/working-agreements.mdBefore your first commit or destructive action. How to work here, with the reasoning behind each rule.
.agents/work-contexts.mdAny time a client, project, or call is involved — if you run under more than one commercial identity, routing to the wrong one is a real error.
.agents/tooling.mdBefore working with any external tool or API. Task-scoped operating knowledge.
.agents/memory/index.mdAt session start. Where committed state lives, and why a CLI's private memory is not authoritative.

Skill playbooks live under .agents/skills/<name>/SKILL.md. Read the relevant one before doing that kind of task.


What this repository is

A personal knowledge system that captures what you produce and what you consume, keeps the two strictly separated, extracts reusable concepts from both, and tracks the client work you do with them. Plain Markdown, YAML front matter, and folders — versioned in git so the whole thing is greppable, diffable, and portable.

It is deliberately not an app. Nothing here needs a server to be useful.


Architecture

The content tiers

brand/ — First-party only. Things you said, wrote, decided, or believe. Raw meeting transcripts in artifacts/, plus voice, opinions, and positioning. Transcripts follow YYYY-MM-DD_HHmmss_Topic_Name.md.

library/ — Third-party only. Newsletters, podcasts, videos, articles, social posts. Kept strictly separate from brand/.

The separation is the point. Mix them and you can no longer tell your own position from something you read once, which makes everything downstream — quoting, attribution, content generation — unreliable. The librarian skill's whole job is getting this routing right, using the alias list in _system/config.yml to decide whether a speaker is you.

knowledge_base/ — Reusable concepts extracted from both tiers, organised by domain. Entries carry a lifecycle: emergent → validated → canonical, defined in _system/knowledge_graph/taxonomy.yaml and governed by the knowledge-base-governance skill. Cross-references use [[wiki-link]] syntax — see .agents/conventions/wiki_links.md.

projects/ — One folder per unit of work: a client engagement, an internal build, a research thread. This directory may have been renamed during install; _system/config.yml records what it is called here. It supersedes any external tracker. Each folder holds context.md (the snapshot of what is true now — under 400 lines, no dated narrative), and gains log/YYYY-MM.md (dated entries, one file per month, append-only), calls.md, open-items.md and README.md only once each has something to hold. The project-creation skill covers what a new one needs to be discoverable.

services/ — A catalog of concrete, sellable offerings drawn from real scoped work, with a status lifecycle (idea → pitched → scoped → delivered → proven). Distinct from knowledge_base/, which holds theory. Governed by services-catalog.

intake/ — The drop point. Files land in inbox/, get processed, and move to processed/.

Front matter

Every file in knowledge_base/ and brand/ needs YAML front matter. Knowledge base nodes use type, domain, status, source, tags, related_concepts, date. scripts/lint-frontmatter.mjs enforces this, and it runs in CI if you installed Tier 1.


Install tiers

What is present in this repo depends on the tier chosen at install. Check _system/install.yml.

Tier 0 — files and conventions. The folders, the skills, the instruction files. You file things by hand with your agent's help. No accounts, no cost, nothing to break.

Tier 1 — hosted ingestion. Drop a file in intake/inbox/, push, and a cloud agent files it without you present. The chain: ingest-content.yml detects the push and opens a GitHub issue mentioning the agent → the agent processes it per the librarian skill and opens a PR whose body contains Fixes #<issue-number> → auto-merge.yml merges it → ingest-cleanup.yml moves the file to processed/.

The Fixes #<issue-number> line is load-bearing. Without it nothing merges and nothing closes.

Beyond Tier 1 — automated capture. Content can also arrive without anyone touching the repo: a transcript filed the moment a call ends, an article saved from a phone, a newsletter forwarded to an address that lands in intake/.

That is deliberately not shipped as code here. It binds tightly to one specific recorder, scraper and job runner, and it was the one component nobody could verify without paid accounts. docs/automated-capture.md covers whether it is worth building at all, the architecture, and the constraints that cost a day each to discover. Point an agent at that rather than letting it invent one.

When any part of the hosted pipeline misbehaves, go to TROUBLESHOOTING.md before reading the workflow source. The failure modes are non-obvious and they are already written down.


Skills

Lazy-loaded playbooks. Invoke by name or match to the task.

SkillUse it for
installFirst-time setup, or adding/removing a tier later.
librarianIngesting any content — a transcript, a newsletter, an article. Owns the first-party/third-party routing decision.
knowledge-base-governanceCreating a concept, or promoting one between lifecycle states.
project-creationCreating a new unit of client work so it is discoverable everywhere it needs to be.
services-catalogKeeping services/ current when you scope, pitch, or deliver something.
session-teardownClosing a session, worktree, or branch without losing unfinished work.
anti-ai-writingAny generated prose. Applies to every writing task.

.claude/skills/ is a generated, read-only mirror of .agents/skills/ so Claude Code's native loader finds them without a second copy to maintain. Never hand-edit anything under .claude/skills/ — edit the source and run npm run sync:agents. Other CLIs read .agents/skills/<name>/SKILL.md directly.


Commands

npm run sync:agents         # regenerate every generated agent file from its source
npm run sync:agents:check   # CI gate — exits 1 on drift
node scripts/lint-frontmatter.mjs   # validate YAML front matter
node scripts/repo-health-scan.js    # structural health check, tier-aware
node scripts/rollup-open-items.mjs  # aggregate open items across projects

Extending this

This template ships the skeleton, not your business. The pieces most people add next:

  • Domain skills. The audit checklist for your kind of work, the strategy process you run for a new client, the way you write. Copy the shape of an existing SKILL.md: front matter with a name and a description that says when to reach for it, then the protocol, then the anti-patterns. The anti-patterns section earns its keep — it is where you record what went wrong last time.
  • A content pipeline. If you publish, the brand/ → knowledge_base/ → draft path is worth automating. That is very specific to where you publish, so it is not shipped here.
  • More ingestion sources. Everything downstream of intake/ is source-agnostic, so a new source only has to land a file there. docs/automated-capture.md has the pattern and the traps.

You do not need to design these from scratch. Describe what you want to your agent and point it at the existing skills as the shape to follow — that is what the conventions in this repo are for.

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.