agentleFS
DTiapanDTiapan/battery/AGENTS.md

battery

AGENTS.md0 starsChanged 2 months agoMITView on GitHub

North star: solve real user pain (session amnesia, context rot, tool switch, machine migration) — not feature sprawl. Do not stack overlapping skills in one turn. Do not skip ADRs/roadmap for greenfield features. No feature merges without a scorecard row in docs/metrics/IMPROVEMENT_SCORECARD.md: baseline metric, post-change metric, target, pass/fail. Run uv run battery eval --real and/or --stress when retrieval is touched. Installed for this repo: product-manager-toolkit, roadmap-communicator, architecture-decision-records, hybrid-search-implementation, context-engineering, spec-driven-development, brainstorming, domain-modeling, implement, codebase-design, documentation-and-adrs, and others. Global Matt skills…

The file

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

1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

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

    Team: commit BATTERY.md to git

    line 49

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

Battery — Agent Working Agreement

North star: solve real user pain (session amnesia, context rot, tool switch, machine migration) — not feature sprawl.

Phase discipline (one phase → one skill)

PhaseRead firstSkill
Problem / prioritydocs/roadmap/PRODUCT_ROADMAP.md.agents/skills/product-manager-toolkit
Shape / exploredocs/adr/, docs/design/.agents/skills/brainstorming
Spec before codeNew ADR draft.agents/skills/spec-driven-development
Domain / termsADR + this file.agents/skills/domain-modeling
Module designSimilar modules in src/battery/.agents/skills/codebase-design
ImplementApproved ADR + ticket.agents/skills/implement
Debug / regressionsFailing test or eval~/.agents/skills/diagnose (global)
ReviewBefore merge~/.agents/skills/code-review (global)
Context setupSession start.agents/skills/context-engineering

Do not stack overlapping skills in one turn. Do not skip ADRs/roadmap for greenfield features.

Scratchpad (thinking out loud)

  • Active hypotheses: docs/scratchpad/ACTIVE.md
  • Promote stable decisions → ADR (docs/adr/)
  • Promote shipped work → roadmap (docs/roadmap/PRODUCT_ROADMAP.md)

Canonical docs (always ground here)

  1. docs/adr/README.md — architecture decisions
  2. docs/roadmap/PRODUCT_ROADMAP.md — priorities
  3. docs/metrics/IMPROVEMENT_SCORECARD.md — baseline → delta → pass/fail
  4. docs/design/battery-master-spec.md — system spec
  5. docs/design/cross-verification-audit.md — assumption ledger

Ship gate

No feature merges without a scorecard row in docs/metrics/IMPROVEMENT_SCORECARD.md: baseline metric, post-change metric, target, pass/fail. Run uv run battery eval --real and/or --stress when retrieval is touched.

Memory model (ADR-0007)

TierCategoriesInject by default?
Stable semanticrule, decision, preference, generalYes
Event episodicepisodicNo — handoff/search
Raw chat (future)chunked episodicOpt-in only

Portability

  • Team: commit BATTERY.md to git
  • Individual: battery profile export / battery profile import
  • Models: ONNX weights not in bundle (~90MB re-download)

Project skills (.agents/skills/)

Installed for this repo: product-manager-toolkit, roadmap-communicator, architecture-decision-records, hybrid-search-implementation, context-engineering, spec-driven-development, brainstorming, domain-modeling, implement, codebase-design, documentation-and-adrs, and others.

Global Matt skills remain in ~/.agents/skills/ per dev-phase-skills cursor rule.

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.