agentleFS
angadhnangadhn/botference/.claude/skills/paper-review/SKILL.md

paper-review

Skill20 starsChanged 4 days agoMITView on GitHub

Set up and run the botference document-review interface (Google-Docs-style comments on rendered LaTeX/Markdown, bots replying in threads, apply/commit of accepted changes) in any repo — and follow the round protocol when the user asks for a review round or tags you from the review page.

29 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use paper-writing.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • MLNLP-WorldSkill

    paper-writing

    学术论文写作检查与优化助手。基于 MLNLP-World 社区整理的论文写作技巧,帮助检查和优化学术论文。Use when: (1) 检查论文 LaTeX 格式和排版, (2) 优化公式符号使用, (3) 改进图表设计, (4) 润色英文学术表达, (5) 检查参考文献格式, (6) 投稿前终稿检查, (7) 用户询问论文写作技巧或规范。

    Also in 6 projects that use this

The file

We split this skill into the rules it gives an agent

5 rules. 0 are common, 1 is distinctive, and 4 are very specific to this project.

  • 0

    Common

    Most of the 20 edited versions we read keep these.

  • 1

    Distinctive

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

    Run node review/init-config.mjs from <dir> (it inspects the directory: master file via \documentclass, sections via \input/\include order, …

    line 27
  2. Very specific:

    Add the gitignore block (see reference repo): review/site/ and review/state/* ignored EXCEPT state/users/ and state/threads.json.

    line 33
  3. Distinctive:

    Commit, Revert, model switching and permission answers stay owner-only forever — a grant never confers them.

    line 132
  4. Very specific:

    Read all users/*.json, diff against your ack.json entry (include entries with edited:true newer than your ack).

    line 173
  5. Very specific:

    Update ack.json last (crash mid-round → the round re-triggers).

    line 190

“Common” is measured: kept by at least 6 in 10 of the 20 edited versions of this file we could read. “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
SKILL.md

paper-review — GDocs-style review of rendered sources, with bots

The engine is built and battle-tested. Canonical engine: $BOTFERENCE_HOME/frontends/review/ (ships with botference). Architecture, decision history, and the unbuilt roadmap (CI rounds, cloud version): design.md next to this file. This file tells you how to USE the system.

Setting up a new project ("set up paper review in <dir>")

Preferred: botference review [dir] — one command does all of the below (engine copy, detection via scripts/review-detect.mjs with an echoed summary, gitignore, build, serve; --share, --hosted, --port N, --no-agents, --upgrade). Use the manual steps only when the launcher isn't available:

  1. Copy the engine from the reference implementation into <dir>/review/: build.mjs, server.mjs, chat.mjs, apply.mjs, submit.mjs, init-config.mjs, bridge-system-prompt.md, SCHEMA.md, assets/ (review.js, style.css). Never copy review.config.json, state/, suggestions.json, or site/ — those are per-project.
  2. Run node review/init-config.mjs from <dir> (it inspects the directory: master file via \documentclass, sections via \input/\include order, bib, abbreviations, todo macros, figures dir, a free port, and the bridge block). Show the user what was detected and get their confirmation before proceeding — never guess the master file silently.
  3. Add the gitignore block (see reference repo): review/site/ and review/state/* ignored EXCEPT state/users/ and state/threads.json; suggestions.json tracked. Conversation must travel through the repo; runtime files must not.
  4. node review/build.mjs, then commit review/ ("Add review interface"). Requires pandoc on PATH — check and tell the user if missing.

Running it

Sync note: the workspace copies of this skill at <vault>/botference/.claude/skills/paper-review/SKILL.md and <vault>/botference/.agents/skills/paper-review/SKILL.md are plain copies of this file — when you edit it (either copy in botference-main or those), update all four.

  • botference review — build + serve; agents are on by default when the machine can run them (python3 + a claude/codex CLI on PATH — the launcher prints agents: on (…) or an agents: off explanation). --no-agents forces off; --agents forces on (clear error if impossible).
  • botference review --share — hosted mode behind a cloudflared quick tunnel: respects REVIEW_PASSWORD or generates one, prints share this: <url> password: <pw>; Ctrl-C stops server + tunnel together. Missing cloudflared → install hint, keeps serving locally.
  • Manual (no launcher): node review/server.mjs — static + comment mirror, no bots; --chat adds the bot bridge (needs BOTFERENCE_HOME or the config's bridge.core_dir); --hosted adds the REVIEW_PASSWORD gate, rate limits, and owner-gated summons. The gate asks for a name and the password together (a name is not a credential — it only picks which users/<handle>.json the guest writes; asking on the gate is what makes hosted mode work on a phone, where the sidebar picker is inside a drawer). The server serves ONLY review/site/ + the figures dir (path-traversal guarded) — keep it that way.
  • Collaborator options: the owner's --share URL (read + comment; their agent summons queue for the owner to release), or clone the repo and run the identical botference review (agents auto-detected; without the CLIs they still read and comment), or plain node review/server.mjs — then node review/submit.mjs [--push] (commits only their own state/users/<handle>.json).
  • The server is long-lived and owned by the human; don't leave your own test servers running.

The interface contract (don't regress these)

  • Comments are the only surface for discussing the document. There is no chat-about-the-paper panel and there will not be one: it was tried, it was confusing, it is rejected. Anything about the text is an anchored margin thread. The one exception, added deliberately, is the task console — a bottom-docked, collapsible, owner-only, desktop-only bar for document-level instructions that have no anchor text: "apply all", "commit", "restructure section 3", "verify every citation resolves". Same strict routing (no @claude/@codex/@all, no agent). The Changes widget lives inside it, because committing is itself a document-level task. Interrupts (permissions/choices) render on the card, in the console for console-issued turns, or as sidebar toasts when off-page (120s default-deny).
  • Strict-but-social routing. @claude routes to Claude alone; the free-form footer handoff is disabled on review turns. To involve the other agent, @-tag it in your thread reply — the server converts that into a visible mention turn (depth cap 1 per thread per round). @all engages both.
  • Mentions fire only on explicit confirm (Done/Enter), never while composing.
  • Every author is visually distinct (stable accent color; Claude coral, Codex blue, humans hashed hues); resolved comments live in a reopenable resolved tab — and ANYONE may resolve/reopen ANY thread, attributed as "resolved by <handle>" (server-mediated; ownership boundary intact); humans can edit/delete their own entries (edited: true — treat an edited entry newer than your ack as new input); author filter chips; light/dark/system theme toggle.
  • Changes widget (inside the task console, owner-only) is the commit workflow: accept → ⚡ Apply (gathers every participant's accepts; the owner's explicit decision wins conflicts) → read → ✓ Commit (or ↩ Revert). Apply is deterministic AND author-agnostic (apply.mjs: unique-span replacement over bot cards and human suggestions, atomic bib append, JSON-aware edits for config-key targets, needs_manual_resolution on drift — never guessed). Apply and commit are always separate actions. Out-of-band source edits surface in the widget with a commit action.
  • Everything is commentable. Paragraphs, figures, headings, list items, block quotes, captions, table cells and the masthead title all carry a data-cid. blk-N is a POSITIONAL index over #paper p, #paper figure and every existing comment is anchored to one — so that selector is frozen, and each newly anchorable type has its own namespace (-hd-N, -misc-N). Never widen the blk selector.
  • Humans suggest too. The composer has Comment and Suggest modes. A human suggestion is an entry in that human's own users/<handle>.json (suggestions.json stays bot-owned), renders inline as del/ins in that human's colour through the same path as a bot card, and flows through the same accept → Apply → Commit. Its source span is resolved to something UNIQUE at compose time — widened with context if ambiguous, anchored on the enclosing macro for headings, aimed at the config title key when the masthead comes from there — and the UI shows what it locked onto. See SCHEMA.md.
  • Presence is coarse and private. Humans + agents in the top-right cluster; state computed from real interaction, in server memory only, never written to disk, symmetric for everyone, desktop-only.
  • Three tiers, not two. state/grants.json (owner-written) can let a named handle summon agents within a visible daily cap. Apply, Commit, Revert, model switching and permission answers stay owner-only forever — a grant never confers them.
  • Never invent a quota number. Neither provider exposes subscription (Pro/Max, ChatGPT plan) quota to anything scriptable; the Settings panel says so and points at /usage. Do not reverse-engineer internal endpoints to fake it.
  • Calm UI: no prompt()/alert()/confirm(), no scroll-jumps, layout reflows (nothing overlays content), engine files stay 100% document-agnostic (all specifics in review.config.json).

File ownership (never write another writer's file)

FileWriter
state/users/<handle>.jsonthat human's browser (via server) — comments, decisions, thread replies AND that human's suggestions
suggestions.jsonbots
state/threads.jsonbots
state/ack.jsonbots
state/apply.jsonapply.mjs (round ledger)
state/grants.json, state/grant-usage.jsonthe owner, via the server
site/, suggestions.jsbuild.mjs only
presencenobody — server memory only, never a file

The record of applied changes (state/apply.json)

Shape: {format: 2, round: {base, ids, files} | null, cards: {<id>: {mode, reason?, source_file?, sha?}}}. Each suggestion card has one mode: pending, accepted, rejected, flagged, applied or committed. A card with no entry is pending. format is the record's format number. Records saved before it existed have no format and still read normally; so does the even older {applied, flagged, round} shape.

Each paper carries its own copy of the review software. If that copy meets a record with a higher format number than it knows, or a shape it cannot read, it changes nothing, never writes over the record, and shows one line on the page saying the paper's software is older than its record. The cure: in the hub, turn the paper off and then on again, which updates its copy. Never edit this file by hand.

Round protocol (when summoned — by an @tag or "read my comments")

  1. Read all users/*.json, diff against your ack.json entry (include entries with edited:true newer than your ack). Those files now also carry humans' own user-suggestion entries — read them as proposals, and do not duplicate one a human already made. A DOCUMENT-LEVEL turn from the task console says so in its envelope: answer in the turn text, do not write a thread entry for it.
  2. Reply to each new comment in threads.json, as long as the comment needs and short enough to read in a margin card; no restating, no preamble. If a text change is warranted, add a suggestion card (current_text/proposed_text, reply_to) — see SCHEMA.md.
  3. Rejected cards get exactly one follow-up (concede or your single best counter-argument).
  4. Never edit document sources during a round. Source changes go through the user's Apply/Commit buttons only. Site styling/engine fixes the user asks for directly may be made in review/ files and committed with a clear message.
  5. Update ack.json last (crash mid-round → the round re-triggers).

Verification bar for any engine change

node --check all touched JS; rebuild; confirm served assets updated; never kill the human's running server (verify on a throwaway port); grep engine files clean of document-specific strings; if a change touches document sources, compile the document (e.g. latexmk -pdf) and inspect the output before claiming done.

Long-lived processes (servers, tunnels)

To serve or tunnel anything that must outlive your turn, use botference service start <name> -- <command…> — or the one-shot botference review --share --service / botference plan --share --service, which run the whole share (server + tunnel) as a managed service, print the share this: <url> password: <pw> line, and return control. Never bare background processes (&, nohup, setsid by hand): they die with your turn's process-group teardown. Manage what you started with botference service list|logs|stop.

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.