stellar-raven
AGENTS.md17 starsChanged 2 days agoApache-2.0View on GitHub
Shared instructions for Codex, Claude Code, and other coding agents. This file holds only rules that change an agent's next action. Architecture, evidence, and procedures live in the linked files. Human contributors start with CONTRIBUTING.md. A Cloudflare Workers MCP server that exposes search and execute over Lumenloop, Stellar Light/Scout, Stellar Docs (Mintlify), and pinned ecosystem skills. Model-written JavaScript runs in a networkless Dynamic Worker. Host adapters own all service traffic, policy, and secrets. The repo is self-contained, including usage collection…
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 33,315 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 repository9 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- audit-reviewabilitySkill
- cloudflare-observability-reviewSkill
- golden-truthSkill
- improvements-pipelineSkill
- live-drift-resolutionSkill
- retrieval-system-auditSkill
- run-evalsSkill
- truth-maintenanceSkill
The file
We split this AGENTS.md into the rules it gives an agent
10 rules. About 0 are common, 4 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Distinctive: line 40
Run a gate command bare. A pipe hides its exit status.
- Very specific: line 41
Never put a model-calling eval command in a gate sweep.
- Very specific: line 46
Do not start a second Wrangler process.
- Very specific: line 82
Start each reviewer or parallel lane as a background child with its first task on the launch line, and wait with hc wait --children any or …
- Very specific: line 109
Run every tier at high effort.
- Distinctive: line 123
Forward-only: Prefer the best current design.
- Very specific: line 132
Secrets stay host-side: Never print or commit a credential or expose one to the sandbox.
- Very specific: line 147
Never reference a retired sibling repo as a live path.
- Distinctive: line 156
Every requested independent review finished and every finding was reconciled.
- Distinctive: line 159
Add a rule here only after recurring friction.
≈ “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.
Files
AGENTS.md — stellar-raven-codemode
Shared instructions for Codex, Claude Code, and other coding agents. This file holds only rules
that change an agent's next action. Architecture, evidence, and procedures live in the linked
files. Human contributors start with CONTRIBUTING.md.
Project and source-of-truth map
A Cloudflare Workers MCP server that exposes search and execute over Lumenloop, Stellar
Light/Scout, Stellar Docs (Mintlify), and pinned ecosystem skills. Model-written JavaScript runs in
a networkless Dynamic Worker. Host adapters own all service traffic, policy, and secrets.
| Need | Read |
| Product scope and status | PLAN.md |
| Request, catalog, scoring, sandbox, and auth design | ARCHITECTURE.md |
| Connection and local setup | README.md |
| Deploy and operate | docs/operations.md |
| A repeatable task procedure | .agents/skills/<name>/SKILL.md (.claude/skills is a symlink to that directory) |
| Open work and owner decisions | .agents/TODO.md |
| Round ledgers, and which note goes where | .agents/rounds/, .agents/README.md |
| Dated evidence and decision records | research/ (evidence, not an instruction layer) |
The repo is self-contained, including usage collection under usage/. The owner keeps private
folders outside it; usage/README.md names them. Never depend on them, and never commit production
counts. CLAUDE.md imports this file; do not duplicate rules there.
Commands and verification
- Install with
npm ci. Itspreparescript installs a pre-commit hook that scans staged files for secrets. - Fresh clone: follow "Run locally" in
README.md.npm run typegenneeds the placeholder.dev.varsfirst; without itEnvhas no secret members andnpm run typecheckfails. - Baseline for a code change:
npm run typecheck,npm test, andnpm run build. Addnpm run test:smokewhen you touchsrc/executororsrc/demo:npm testexcludestest/smoke/**, and that lane is the only one that runs those paths in the assembled Worker. - CI runs more gates per area. The "Checks" table in
CONTRIBUTING.mdmaps each area to its command; run the matching one when you toucheval/,improvements/,catalog/,ecosystem-skills/, orusage/. The selected skill names any further gate. - Run a gate command bare. A pipe hides its exit status.
- Never put a model-calling eval command in a gate sweep. Those commands cost money and need
their own authorization (the
run-evalsskill). - Scan before committing:
npm run secrets:scan -- --tree. - Generated files are rebuilt by their scripts, never edited by hand
(
scripts/README.mdlists them). - Do not start a second Wrangler process. Reuse the terminal that runs
npm run dev(manual testing) ornpm run dev:eval(eval lanes), and read its bound URL from that terminal (hc ls, thenhc read <t>).
Spend and evidence
"Spend" is the size of the work: how long a task takes, what it costs, and where it runs.
- Decide with the least spend that can decide. Scope each task and eval to the smallest run that answers the question. Before you start, state the decision it changes, the expected time and cost, and the stop rule. Call the result as soon as the evidence is solid. Do not add confirmation rounds, extra looks, or re-checks that buy little information.
- Cost counts. Correctness wins only when the alternative is far less correct. A path that is much cheaper and only slightly less correct can be the better product.
- Run here, on
hc, first. Development tests and evals run against the localwrangler devserver with the subscription CLI agents (Claude Code, Codex, Grok) ashcchildren. Use an API-billed path (Cloudflare AI Gateway, a provider API) only when no CLI path can do the job, and record why. - Eval and test models. Claude Sonnet 5.5, GPT-6.1 Terra, and Grok 4.7. Add Claude Opus 5.5 and GPT-6.1 Sol where they help. Leave out Haiku and GPT-6 Luna.
- A paid method needs its own written authorization. A diagnostic budget does not transfer to headline collection.
- File and response size come second. Trim bloat where it is cheap; do not spend effort on it for its own sake.
.agents/model-roster.md has the model IDs and launch lines. The
run-evals skill has the measurement procedure. Scores are evidence for a scoped decision, not
the decision; an established upstream defect goes to improvements/.
Coordination
The owner runs agents under herdr-core (hc); $HC_TERMINAL_ID is set inside it. Without it, work
in one session and state in the pull request that the independent review is outstanding.
- The global
herdr-coreskill holds thehccontract (hc --skill). Address a lane by the--nameyou gave it. - Start each reviewer or parallel lane as a background child with its first task on the launch
line, and wait with
hc wait --children anyorall. Do not sleep or poll. The roster has the exact lines. - Terminal ownership is recursive. Control only your own terminal and the children you started. Never interrupt, kill, rename, take over, or send input to a parent, a sibling, an unrelated terminal, or another agent's children; the one exception is the report your parent asked for. Idleness, staleness, a finished handoff, or a cleanup request does not transfer ownership. Record the terminal IDs you create; unknown provenance means not owned. Ask the owning agent to reconcile its terminal. If that agent is unknown or gone, ask the user for an exception that names the exact target. Every sub-agent follows the same rule.
- Screen history is not a record. A reviewer writes its findings to a Markdown file and sends you
only the path (
hc send <your terminal ID> '<path>'in its task). - Durable working state lives in the repository, never in an external tracker: own-repo work in
.agents/TODO.md, a multi-lane round in.agents/rounds/<YYYY-MM-DD>-<slug>.md. - A requested independent review is a completion gate. The reviewer runs to completion, and every finding is reconciled before the work is final.
Model routing for repo-work fan-out
| Tier | Use for |
| Codex frontier | Hard implementation, dense analysis, security review |
| Codex workhorse | Routine implementation, bounded verification |
| Claude Fable | Product, API, documentation, taste |
| Claude Opus | The stable Claude fallback |
| Grok | Vendor-diverse assumption attack |
Run every tier at high effort. Escalate to xhigh only for a subtle change or after a high pass
missed a real finding, and reserve max for frontier work or a failed high pass. ultra
delegates to subagents; treat it as a separate topology. The roster maps each tier to a model
ID; when a CLI catalog changes, update the roster only.
The independent reviewer:
- differs from the author and from the orchestrator;
- comes from the tier that matches the change. When that tier is the author, the orchestrator, or unavailable, take the next best match, then Claude Opus;
- is recorded with its tier, model, effort, and the reason a matched tier was skipped.
Hard rules
- Forward-only. Prefer the best current design. Add no compatibility shim, dual format, or deprecation path only to preserve deployed behavior. A deviation needs evidence.
- The manifest is the exposed surface (ADR-0003). Model code never owns endpoints, arguments,
auth, or exposure. Never emit a reference to a non-exposed operation or a retired skill. Two
guards enforce it:
assertNoNonExposedRefsInTexton emitted text inprebuild, andassertNoNonExposedRefson manifest entries at catalog rebuild and innpm test.npm run builddoes not rebuild the catalog, sonpm testand CI catch a hand-edited manifest, not the build. - Skill and tool IDs resolve by exact match. Keep soft-empty, error, and data responses distinct.
- Secrets stay host-side. Never print or commit a credential or expose one to the sandbox.
globalOutboundstaysnull. - The paid Lumenloop research trigger and its account-scoped reads stay unexposed. Enabling them takes the exposure change, partner-detail persistence, a budget gate, and dedup in one reviewed change.
- Partner-tier Lumenloop details are never committed. Inventory keeps name-only stubs, and skill sync stays keyless.
- A paid or side-effecting model operation needs host-side request-context approval, elicitation, and budget enforcement before it ships.
- Mintlify admin credentials are maintenance-only, never a runtime or sandbox surface. A docs
search change needs a read-only A/B win and a general mechanism, not a per-query exception
(
docs/stellar-docs.md, "Maintenance"). - Skills are timeless: no todo IDs, run stamps, or dated state in skill text.
- Solo, a retired task tracker, is not a live path. Add no
solo://reference, Solo todo, or Solo scratchpad. Leave Solo references in dated records unchanged. - Never reference a retired sibling repo as a live path. Prior art under
eval/corpus/is read-only; it is the routing eval's label source. The QA battery lives undereval/qa/corpus/and does not read it.
Definition of done
- The diff is scoped and keeps unrelated work in a dirty tree.
- Proportionate tests and the required gates pass. Failures are reported, not hidden.
- Generated files came from their scripts, and the secrets scan passed.
- Every requested independent review finished and every finding was reconciled.
- Documentation describes current behavior and links dated research, not history.
Add a rule here only after recurring friction. A specialized instruction goes in the nearest skill or directory-level guide.
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.

