literary-critic / claude-arsenal
AGENTS.md0 starsChanged 27 days agoMITView on GitHub
This file is in context on every turn, so it holds only what a session needs before it knows what kind of session it is. The rest lives in claude-arsenal/references/: plain paths, opened on demand (table at the end). Paths starting arsenal/ are the host-owned tree; setting ARSENAL_HOME relocates all of them. claude-arsenal/ is the vendored bundle and never moves. - Finish the task. On an unattended run, carry the work through to its end; put status notes alongside the…
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 repository22 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- coverage-gapsSkill
- dep-upgradeSkill
- designSkill
- executionSkill
- explore-ideaSkill
- gate-checkSkill
- githubSkill
- initSkill
- litcriticSkill
- mutmut-reportSkill
- pin-checkSkill
- pypi-releaseSkill
- python-bootstrapSkill
- queue-addSkill
- queue-nextSkill
- queue-statusSkill
- reviewSkill
- session-endSkill
- shipSkill
- specifySkill
The file
We split this AGENTS.md into the rules it gives an agent
5 rules. About 0 are common, 1 is distinctive, and 4 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.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 22
Reports lead with the outcome: Add sections (done / not done / questions / next) only when they have content, and keep the whole report …
- Very specific: line 27
Name tasks by label: When you mention a task to the user, write its label followed by the id, e.g.
- Very specific: line 48
When a task is squarely covered by a section this repo did not install, say so once, then do what was asked.
- Very specific: line 153
Every change reaches the default branch through a PR, ad hoc work included.
- Very specific: line 159
Before merging, run bash claude-arsenal/bin/merge_ready.sh <pr>: it checks what the host's merge-policy requires against the head SHA.
≈ “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
Claude Arsenal
<!-- claude-arsenal v5.10.4 — imported via @claude-arsenal/AGENTS.md -->This file is in context on every turn, so it holds only what a session needs before it
knows what kind of session it is. The rest lives in claude-arsenal/references/: plain
paths, opened on demand (table at the end).
Paths starting arsenal/ are the host-owned tree; setting ARSENAL_HOME relocates all of
them. claude-arsenal/ is the vendored bundle and never moves.
How to work
- Finish the task. On an unattended run, carry the work through to its end; put status notes alongside the next tool call rather than ending the turn on them. Stop only when blocked or before a risky or irreversible action. When the request is a question or a problem description, the assessment is the deliverable — answer it before changing code.
- How often to ask is
autonomyinarsenal/config.toml:ask-often(confirm each step),ask-when-blocked(default),autonomous(never wait on the user for reversible work). - Reports lead with the outcome. Add sections (done / not done / questions / next) only when they have content, and keep the whole report short.
- Batch independent tool calls into one response; sequence only calls that depend on each other.
- Edit surgically. Change the lines that need changing rather than rewriting a file.
- Name tasks by label. When you mention a task to the user, write its label followed by
the id, e.g.
tag only green CI (t-1a2b3c4d); a bare id tells them nothing.
Session-start protocol
At the start of every session (fresh start, context compaction, or cold restart):
- Refresh the bundle.
a. If
claude-arsenal/bin/check_update.shexists, run it with--check-only(without it the script merges and commits) and surface what it reports. AnUNTAGGED UPSTREAM RELEASEis fixed upstream (make tag), not here. On a non-subtree install the report isINERT— the expected answer: say so once per session and open no work on it. b. Runpython3 .claude/skills/init/scripts/init.py --repo-path . --silentand report anything it refreshes, and eachNEW SETTINGline once (config-acknowledgedinarsenal/config.tomlsilences them). If it says the installed bundle is newer, report that and update the plugin; never pass--allow-downgrade. Skip (b) if (a) reportedVENDORED SKILL BEHIND BUNDLE. Skip (a) and (b) when the script is absent. c. Read the capability map:python3 .claude/skills/init/scripts/init.py --list-sections. When a task is squarely covered by a section this repo did not install, say so once, then do what was asked. →claude-arsenal/references/capability-map.md - Establish the GitHub channel —
bash claude-arsenal/bin/github_channel.sh --detectprintsgh,rest, ornone.nonemeans: perform every GitHub step below with your own GitHub tools. Skipping those steps is the one wrong answer. - Fetch the task issues — issues labelled
arsenal:task, open and closed (a closed issue is what marks a dependency satisfied), saved as JSON (e.g./tmp/arsenal-issues.json). Requestnumber,title,state,labels,assigneesand notbody: thearsenal-id:<id>label pairs an issue to its task. Also save open issues carrying neitherarsenal:tasknorarsenal:queue(number,title) for--open-issues. - Read the board —
git fetch --quiet origin, thenpython3 claude-arsenal/scripts/query_status.py --issues /tmp/arsenal-issues.json \ --open-issues /tmp/arsenal-unfiled.json. Report everything it flags. If the fetch fails, say so and treat the counts as unverified. - Create missing handles —
python3 claude-arsenal/scripts/handle_sync.py --issues /tmp/arsenal-issues.json; create each printed issue with every label the row lists and a visible`arsenal-task: <id>`body line. Resolve anambiguousrow before creating anything. →claude-arsenal/references/queue-seeding.md
4b. Import issues filed between sessions — fetch open issues with the import label
(default arsenal:queue, set by import-label), including body, then
python3 claude-arsenal/scripts/issue_import.py --issues /tmp/arsenal-import.json --apply.
Apply every change each row prints and commit the new task files.
→ claude-arsenal/references/queue-seeding.md
- Read handover — read
arsenal/session/handover.mdif it has real content; it is a snapshot, so re-read the board before resuming anything it names. Alsostatus/ideas.mdwhen the board'sideas:line counts exploring rows. After compaction mid-task, the task'stmp/<id>-notes.mdandgit statusare the state. So keep that file on any work longer than a few steps, queue task or not (tmp/<id-or-slug>-notes.md): a## Resumesection with Decided / Ruled out / Next step, refreshed after each decision. A hook re-injects that section after compaction. - Pick up work —
claude-arsenal/references/worker-loop.md. If the selector returns nothing and a plan exists, seed the queue from it (claude-arsenal/references/queue-seeding.md); otherwise report done or ask the user. Pass each dispatch the model fromarsenal_config.py --get models.workersas its ownmodelargument; ifmodels.orchestratornames a different model than yours, say so once. →claude-arsenal/references/worker-loop.md§ Credit guards - Before ending a session with open work — audit every claimed task and open PR (CI,
reviews, mergeability), print the table, then write
arsenal/session/handover.md./session-enddoes this in full. →claude-arsenal/references/github-automation.md
Task format
A task is a file — arsenal/tasks/<id>.md — with front matter and a body:
---
id: t-3f8a91c2
label: "extract surface probe"
title: "Extract the surface probe into its own script"
priority: 5
deps: [t-aaaa1111, t-bbbb2222]
requires: [surface:cli]
tags: [CLI]
workspace: BACKEND
max-attempts: 3
---
## Acceptance gate
```bash
bash tests/surface_probe_test.sh
```Task files are read from the default branch, so every agent computes the same order.
deps is the build order; priority encodes task size only (S=10, M=5, L=1, larger runs
sooner). The gate must be a fenced ```bash block — prose and inline commands never run
— and it is fixed for the life of the task: a task's own PR cannot amend it.
→ claude-arsenal/references/evidence-gates.md
Claiming — the contract
GitHub decides a claim: creating a ref is a compare-and-swap, so exactly one caller wins.
bash claude-arsenal/bin/claim_task.sh <task-id>
# won <ref> → yours; proceed
# lost → someone else has it; take the next task (normal, not an error)
# manual … → no scriptable channel: make that exact call with your GitHub tools;
# 201 = won, 422 = lost
# error: → misconfiguration; stop and surface itObey the result: claiming another ref, pushing -u, or bumping the attempt number to win
recreates the double-claims this prevents. After winning, self-assign, add
arsenal:claimed, and comment with the session id from CLAUDE_CODE_REMOTE_SESSION_ID
(falling back to CLAUDE_CODE_SESSION_ID); never invent one.
→ claude-arsenal/references/claiming-internals.md
Completion — merging is the update
Every change reaches the default branch through a PR, ad hoc work included; never push to
it directly. Open a task's PR with open_task_pr.sh: it writes Closes #<issue> and
archives the task file in the same diff, so the merge alone finishes the task. If it
refuses for want of an issue, pass ARSENAL_TASK_ISSUE=<n> or run handle_sync.py —
not ARSENAL_ALLOW_UNLINKED_PR=1.
Before merging, run bash claude-arsenal/bin/merge_ready.sh <pr>: it checks what the
host's merge-policy requires against the head SHA. Exit 0 means merge, without asking
the user a question the host already answered.
→ claude-arsenal/references/github-automation.md
Specs and plans
Idea work goes through explore-idea, spec work through specify, plan work through
design; another plugin's brainstorming or planning skill does not replace them, and no
plan is written before the annotated spec is approved. Hand every spec or plan to the user
as the HTML from create_reader.py. A diagram is a ```drawspec fence, not hand-drawn SVG
or ASCII art → claude-arsenal/references/diagrams.md.
References — read the one you need, when you need it
| File | Read it when |
references/worker-loop.md | Dispatching workers: the loop, worktree isolation, worker_postcheck.sh, per-task PRs, credit guards, every ARSENAL_* knob |
references/orchestrator-tick.md | Running the board unattended: one tick's steps, the merge preconditions |
references/queue-seeding.md | The queue is empty: seeding from a plan, importing filed issues, handle markers, a D-N divergence |
references/evidence-gates.md | Writing or trusting a gate: the fence rule, hardened execution, numeric evidence, unmeasured |
references/claiming-internals.md | A claim misbehaves: attempt refs, ref accumulation, on: push cost |
references/github-automation.md | Completion: merge-policy, the transitions GitHub runs, ending a session. Actions minutes short → references/ci-minutes.md |
references/quota-governance.md | The loop stopped before dispatch: quota windows, fail-open, the round cap |
references/pre-pr-review.md | About to open a PR: the cold-start adversarial review and its verdicts |
references/performance-tuning.md | The loop feels slow: recorded timings and their remedies |
references/state-layout.md | A lookup: where a file lives, what a task state means |
references/repo-housekeeping.md | Choosing a license, or publishing a package: the questions to ask, the metadata an index needs |
references/annotatable-reader.md | Handing over a spec or plan: which documents need a reader |
references/capability-map.md | A task looks like something a skill would do |
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.

