agentleFS
nuncaeslupusnuncaeslupus/literary-critic/claude-arsenal/AGENTS.md

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…

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

    Reports lead with the outcome: Add sections (done / not done / questions / next) only when they have content, and keep the whole report …

    line 22
  2. Very specific:

    Name tasks by label: When you mention a task to the user, write its label followed by the id, e.g.

    line 27
  3. Very specific:

    When a task is squarely covered by a section this repo did not install, say so once, then do what was asked.

    line 48
  4. Very specific:

    Every change reaches the default branch through a PR, ad hoc work included.

    line 153
  5. Very specific:

    Before merging, run bash claude-arsenal/bin/merge_ready.sh <pr>: it checks what the host's merge-policy requires against the head SHA.

    line 159

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

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 autonomy in arsenal/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):

  1. Refresh the bundle. a. If claude-arsenal/bin/check_update.sh exists, run it with --check-only (without it the script merges and commits) and surface what it reports. An UNTAGGED UPSTREAM RELEASE is fixed upstream (make tag), not here. On a non-subtree install the report is INERT — the expected answer: say so once per session and open no work on it. b. Run python3 .claude/skills/init/scripts/init.py --repo-path . --silent and report anything it refreshes, and each NEW SETTING line once (config-acknowledged in arsenal/config.toml silences them). If it says the installed bundle is newer, report that and update the plugin; never pass --allow-downgrade. Skip (b) if (a) reported VENDORED 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
  2. Establish the GitHub channel — bash claude-arsenal/bin/github_channel.sh --detect prints gh, rest, or none. none means: perform every GitHub step below with your own GitHub tools. Skipping those steps is the one wrong answer.
  3. 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). Request number,title,state,labels,assignees and not body: the arsenal-id:<id> label pairs an issue to its task. Also save open issues carrying neither arsenal:task nor arsenal:queue (number,title) for --open-issues.
  4. Read the board — git fetch --quiet origin, then python3 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.
  5. 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 an ambiguous row 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

  1. Read handover — read arsenal/session/handover.md if it has real content; it is a snapshot, so re-read the board before resuming anything it names. Also status/ideas.md when the board's ideas: line counts exploring rows. After compaction mid-task, the task's tmp/<id>-notes.md and git status are 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 ## Resume section with Decided / Ruled out / Next step, refreshed after each decision. A hook re-injects that section after compaction.
  2. 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 from arsenal_config.py --get models.workers as its own model argument; if models.orchestrator names a different model than yours, say so once. → claude-arsenal/references/worker-loop.md § Credit guards
  3. 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-end does 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 it

Obey 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

FileRead it when
references/worker-loop.mdDispatching workers: the loop, worktree isolation, worker_postcheck.sh, per-task PRs, credit guards, every ARSENAL_* knob
references/orchestrator-tick.mdRunning the board unattended: one tick's steps, the merge preconditions
references/queue-seeding.mdThe queue is empty: seeding from a plan, importing filed issues, handle markers, a D-N divergence
references/evidence-gates.mdWriting or trusting a gate: the fence rule, hardened execution, numeric evidence, unmeasured
references/claiming-internals.mdA claim misbehaves: attempt refs, ref accumulation, on: push cost
references/github-automation.mdCompletion: merge-policy, the transitions GitHub runs, ending a session. Actions minutes short → references/ci-minutes.md
references/quota-governance.mdThe loop stopped before dispatch: quota windows, fail-open, the round cap
references/pre-pr-review.mdAbout to open a PR: the cold-start adversarial review and its verdicts
references/performance-tuning.mdThe loop feels slow: recorded timings and their remedies
references/state-layout.mdA lookup: where a file lives, what a task state means
references/repo-housekeeping.mdChoosing a license, or publishing a package: the questions to ask, the metadata an index needs
references/annotatable-reader.mdHanding over a spec or plan: which documents need a reader
references/capability-map.mdA task looks like something a skill would do

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.