agentleFS
degdeg/beads-utils/AGENTS.md

beads-utils

AGENTS.md2 starsChanged 6 days agoMITView on GitHub

Project context, the script catalog, coding conventions, and how to run and test everything live in CLAUDE.md — read it first; it is the canonical doc for this repo. This file holds only generic agent-execution guidance. Per-script design notes live in .claude/rules/, one plain Markdown file per area; Claude Code loads them by path, and any other agent should read the matching one before changing a script. (The beads issue-tracker section below is auto-generated by bd; don't hand-edit it.) Shell…

  • Commits and pushes
  • 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 repository8 other files it gives its agents.

The file

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

8 rules. About 0 are common, 5 are distinctive, and 3 are very specific to this project.

  • ≈0

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

    Use bd for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists

    line 52
  2. Very specific:

    Run bd prime for detailed command reference and session close protocol

    line 53
  3. Very specific:

    Use bd remember for persistent knowledge — do NOT use MEMORY.md files

    line 54
  4. Distinctive:

    File issues for remaining work: - Create issues for anything that needs follow-up

    line 62
  5. Distinctive:

    Verify: - All changes committed AND pushed

    line 73
  6. Distinctive:

    NEVER stop before pushing - that leaves work stranded locally

    line 78
  7. Distinctive:

    NEVER say "ready to push when you are" - YOU must push

    line 79
  8. Distinctive:

    If push fails, resolve and retry until it succeeds <!-- END BEADS INTEGRATION -->

    line 80

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

Agent Instructions

Project context, the script catalog, coding conventions, and how to run and test everything live in CLAUDE.md — read it first; it is the canonical doc for this repo. This file holds only generic agent-execution guidance. Per-script design notes live in .claude/rules/, one plain Markdown file per area; Claude Code loads them by path, and any other agent should read the matching one before changing a script. (The beads issue-tracker section below is auto-generated by bd; don't hand-edit it.)

Non-Interactive Shell Commands

Shell commands like cp, mv, and rm may be aliased to cp -i / mv -i / rm -i (Oh-My-Zsh's common-aliases does this), and an agent shell that sources the user's profile inherits them. The prompt then waits on stdin nobody will answer, and the command hangs until the tool times out.

Bypass the alias rather than adding -f:

command cp source dest      # or /bin/cp
command mv source dest
command rm file
command cp -R source dest   # recursive forms too

-f is not a reliable fix. Checked on macOS against the aliases: mv -f and rm -f do override the -i, but cp -f still prompts, and with no answer it silently skips the copy, so a script carries on as if it had succeeded.

Other commands that may prompt:

  • scp - use -o BatchMode=yes for non-interactive
  • ssh - use -o BatchMode=yes to fail instead of prompting
  • apt-get - use -y flag
  • brew - use HOMEBREW_NO_AUTO_UPDATE=1 env var
<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:ca08a54f -->

Beads Issue Tracker

This project uses bd (beads) for issue tracking. Run bd prime to see full workflow context and commands.

Quick Reference

bd ready              # Find available work
bd show <id>          # View issue details
bd update <id> --claim  # Claim work
bd close <id>         # Complete work

Rules

  • Use bd for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
  • Run bd prime for detailed command reference and session close protocol
  • Use bd remember for persistent knowledge — do NOT use MEMORY.md files

Session Completion

When ending a work session, you MUST complete ALL steps below. Work is NOT complete until git push succeeds.

MANDATORY WORKFLOW:

  1. File issues for remaining work - Create issues for anything that needs follow-up
  2. Run quality gates (if code changed) - Tests, linters, builds
  3. Update issue status - Close finished work, update in-progress items
  4. PUSH TO REMOTE - This is MANDATORY:
    git pull --rebase
    bd dolt push
    git push
    git status  # MUST show "up to date with origin"
  5. Clean up - Clear stashes, prune remote branches
  6. Verify - All changes committed AND pushed
  7. Hand off - Provide context for next session

CRITICAL RULES:

  • Work is NOT complete until git push succeeds
  • NEVER stop before pushing - that leaves work stranded locally
  • NEVER say "ready to push when you are" - YOU must push
  • If push fails, resolve and retry until it succeeds
<!-- END BEADS INTEGRATION -->

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.