Getting it into your agent
One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.
npx agentmods add instructions/seanyao/roll/agents-mdgit clone --depth 1 https://github.com/seanyao/rollWhat it costs to keep this loaded
Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.
| Model | Per session | Once invoked |
|---|---|---|
| Fable 5 | $0.01862 | $0.01862 |
| Opus 5 | $0.00931 | $0.00931 |
| Sonnet 5 | $0.00372 | $0.00372 |
| Haiku 4.5 | $0.00186 | $0.00186 |
Grade A, and why
roll AGENTS.md scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 2d ago.
A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.
Nothing flagged
None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.
How it starts
The opening of the file, as written. The whole thing — 86 lines — stays where its author put it; the contents beside it link to each section on GitHub.
Roll — Agent 操作手册
roll 的引擎是 TypeScript（
packages/），CLI 全 TS-native；main即发布线。 The engine is TypeScript (packages/), the CLI is fully TS-native;mainships. 按"反馈闭环 + 能力域分层"设计。给在本仓干活的 agent / loop 读。
0. 这是什么（一句话）
roll 是一个按反馈闭环设计的 agent harness：把 LLM agent 当黑盒，用反馈闭环优化对它的控制力。它是一台分层的 TS 控制器——把目标拆成 cycle、调度 agent 执行、感知结果、按主干对账修正。
1. 当前形态
CLI 全 TypeScript：packages/cli/bin/roll.js → dispatch()，未知命令打 usage（无回落引擎）。发布为单一 npm 包 @seanyao/roll，CLI 经 esbuild 打平成 dist/roll.mjs。
| 包 | 能力域 |
|---|---|
spec |
类型 + i18n catalog（层间契约的单一真相） |
core |
领域逻辑：编排、backlog、对账、评分、成本、dossier（纯函数为主） |
infra |
副作用适配：git / gh / 文件系统 / 进程 |
cli |
命令面 + loop runner + 桥接 |
web |
站点 |
lib/ 是运行时伴生数据（价格快照、i18n 文案目录）。skills/ 是 submodule（见 §6）。分层与不变量详见 docs/architecture.md。
2. 沟通
- 用用户语言回答；代码/git/注释用英文；UI 输出跟随多语言设置（locale 单语呈现，不混排）。
- 简洁，讲结果（outcome），不复述实现、不走查代码。
- 自然、同事口吻；成功失败一致的温度。
3. 架构不变量（动手前必须守）
- 反馈闭环是脊柱：核心作动（编排）→ 控制平面传感/评分/限幅（可观测/Evals/Guardrails）→ 反哺。别把功能做成互不相干的孤岛。
- 能力域分层 = 每个能力域一个家：Orchestration / Sandboxing / Tool Use / Context Engineering / Observability / Evals / Guardrails。新代码先问"它属哪个域"，进那个域的包（6 包：spec/core/infra/daemon/cli/web），别又摊回多载体。
- 守黑盒边界（外层 harness）：token 级压缩、工具 schema 强制、单次 ReAct 委派内层 agent。
- event-driven，不中央编排：多 loop 独立、经 artifact 协调，单 loop 故障不塌全局。
- 主干即真相：Done ≡ 已合进
main分支；退出码不算数，事后对账。 - 失败要响（fail-loud）：连续失败 → PAUSE + 记录 + 问 owner；不做静默自愈/自动 fallback 链。
- 持久优先：状态从不可变事件流重建，不存独立缓存；写在前、原子 append。
- 有界且可逆：一 cycle 一小故事、fresh 上下文、TCR green-or-revert、feature 可整体回退。
- 反馈带 Goodhart 护栏：评分信号不自动激活，只生成"待人确认"候选；human-on-the-loop。
4. 标准
- TS：strict、禁
any、函数式、早返回。类型是层与层之间的契约——不退回 stdout 文本解析 / heredoc 生成脚本。 - TCR：Test → 绿则 commit / 红则 revert。无 WIP commit。
- 测试：单测覆盖每个公共入口；行为契约用 Vitest 冻结快照（
toMatchSnapshot）守护——见 docs/difftest-freeze-paradigm.md。 - Git：
main走 PR + 2 checks（fix/feat/refactor 一律建分支）；不--no-verify；不提交密钥；身份动态读git config。 - DoD：docs = code = product：凡改变用户可见行为、命令面、输出文案、站点或交付视图的 story/fix，同一交付必须更新所触及的 README/docs/guide/site/help；文档漂移按缺陷处理。
- DoD: docs = code = product: any story/fix that changes user-visible behavior, commands, output copy, site, or delivery views must update the touched README/docs/guide/site/help in the same delivery; doc drift is a defect.
- 不做：无关重构、投机抽象、改变现有命令的可观察行为而不带测试。
What this file has done since we first saw it
Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.
- 2d ago First seen · 86 lines · 1,862 tokens per session scan A ae0f9ed9aeb7
roll AGENTS.md is an instructions file published in the GitHub repository seanyao/roll (14 stars, last pushed 15d ago), licensed MIT. It adds 1,862 tokens to every session, about $0.0093 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.
Other instructions, from other repositories
nexus-agents CLAUDE.md
Claude Code instructions, protocols, agent behavior, governance rules, and canonical paths.
baerly-storage CLAUDE.md
Toolchain, verification matrix, module map, conventions, anti-patterns. The main agent entry point.
skills CLAUDE.md
Instructions for BCGen/skills: Install deps with pnpm install; lint everything with pnpm lint (skill lint + markdownlint over skills/).
archguardian copilot-instructions.md
Instructions for ysfAskri/archguardian, covering archguardian, project structure, build & test, key conventions and cli commands.
archguardian CLAUDE.md
Instructions for ysfAskri/archguardian, covering archguardian, project structure, build & test, key conventions and available skills.
recursive-spine CLAUDE.md
Claude Code instructions for slopstopper/recursive-spine, covering recursive-spine — rules codex, mission, house rules, tracking (recursive-spine convention) and ci gates.