Agents¶
Chapter 05 of the ResearchTools manual. Back to table of contents.
Agents are specialists Claude delegates to automatically based on context, or explicitly on
request ("use the scopus-auditor agent to…"). Twenty-two ship in this repo; most back a slash
command. Two of them (local-writer, local-coder) are local-delegation agents: a cheap
cloud wrapper that drives a local Ollama model over a Bash bridge (see "Local delegation").
Two are loop orchestrators: authoring-loop (ScholarEval-gated writing loop) and the
code loop in the loop-engineer skill (see "Loop engineering").
Format (repo convention): one flat markdown file per agent at .claude/agents/<name>.md,
opening with YAML frontmatter (name:, description:). This is what Claude Code's subagent
discovery scans; a sub-folder layout is invisible to it. Note the asymmetry with skills,
which ARE folder-based (skills/<name>/SKILL.md). The canonical .claude/agents/ files are
the single source of truth; per-tool mirrors are generated from them (see
"Using the agents outside Claude Code" below).
| Agent | Purpose | Command / trigger | Path |
|---|---|---|---|
scopus-researcher |
Autonomous literature review: search, validate, summarize, PRISMA + gap/coverage/Pareto matrices, hypotheses, LaTeX output | /litreview |
.claude/agents/scopus-researcher.md |
litreview-updater |
Incrementally refresh an existing review with new papers: windowed Scopus + Consensus search, delta dedup, validation/grading, preemption check (deliberation + scholar-evaluation), dated \added{} copy _up_YYYYMMDD.tex + CHANGELOG; unattended draft + REVIEW REQUIRED |
/litupdate |
.claude/agents/litreview-updater.md |
scopus-auditor |
Audit an existing review; validate every reference; executable improvement plan | /auditreview |
.claude/agents/scopus-auditor.md |
paper-auditor |
Full paper content audit (intro→future works) + Scopus validation + ScholarEval score + improvement plan | /auditpaper |
.claude/agents/paper-auditor.md |
thesis-auditor |
Full UQAC thesis audit (front matter, hypothesis flow, chapter structure, bilingual consistency, UQAC compliance) + ScholarEval score | /auditthesis |
.claude/agents/thesis-auditor.md |
thesis-proposal-auditor |
Audit a UQAC thesis proposal (≤35 pages body, testable hypotheses, suggested methodology, no full results) + ScholarEval score | thesis-proposal audit / by name | .claude/agents/thesis-proposal-auditor.md |
reviewer-response |
Point-by-point response letters + traceable changes-package markup in the paper |
/replyreviewer |
.claude/agents/reviewer-response.md |
bib-cleaner |
Validate, deduplicate, normalize and DOI-enrich a .bib file |
/bibclean |
.claude/agents/bib-cleaner.md |
submit-checker |
Pass/fail submission checklist against a target journal's requirements | /submitcheck |
.claude/agents/submit-checker.md |
talk-builder |
Accepted paper → conference talk: six opening questions first, build contract, talk_model.json, render (PowerPoint / Beamer / web), then the validate → notes → render → inspect loop until every page is clean |
/talk |
.claude/agents/talk-builder.md |
word-to-latex |
Faithful Word .docx → LaTeX conversion (pandoc + visual-fidelity patches) |
/word2latex |
.claude/agents/word-to-latex.md |
cover-paper |
Submission package: hidden Cover Letter in source, standalone Title Page PDF, Corresponding Author Profile PDF (recent papers from Scopus), Graphical Abstract via Canva MCP from the paper's figures (Elsevier/Springer spec + FigureLabs prompt) | by name (at submission) | .claude/agents/cover-paper.md |
narrative-cv-writer |
Draft/refresh/tailor the FRQ / tri-agency narrative CV to one grant competition: refresh the durable master contributions inventory (Scopus AU-ID two-step + extract-contributions, plus a grouped question for non-publication items), rank against the competition's own objectives via cv_select.py, draft the three sections through scientific-writing, render LaTeX/PDF + plain text, self-check the page budget and AI-usage score |
/cv |
.claude/agents/narrative-cv-writer.md |
wp-portfolio-agent |
One-shot migration of a researcher's final CIHR / Canadian Common CV XML export into their WordPress portfolio: parse, discover WP pages (first run only), preview and pause for approval, dry-run the push, push for real only after explicit approval, then verify the public pages. No Write/Edit tool: push_wp.py is the sole writer, gated by the anti-fabrication check and verified by a read-back after every PUT. Never publishes student data from the XML (D2) |
/portfolio |
.claude/agents/wp-portfolio-agent.md |
work-ugs-audit |
Grade a folder of undergraduate student reports (PDF) against the professor's rubric with local models only: prepare with the rubric kept whole and no confirmation step, run, batch verdict from numbers only, a calibrated second loop on request and a pause before a third. Read and Bash only, and blind to every report: it reads the rubric and the step ledger of the work folder and the driver's JSON lines, never a grade, an annotation or a page |
/work-ugs-audit |
.claude/agents/work-ugs-audit.md |
thesis-to-paper |
Integrate a thesis + its conference papers into one submission-ready journal manuscript (invited extension); pandoc reference conversion, figure pipeline, content-delta matrix, then /litreview + scientific-writing + /bibclean + /submitcheck + /auditpaper inline, with a multi-session checkpoint protocol |
by name / "extend this paper to a journal version" | .claude/agents/thesis-to-paper.md |
authoring-loop |
ScholarEval-gated authoring loop: define subject -> author (Fable 5) -> audit with scholar-evaluation (Sonnet/Haiku) -> loop to min_score or max_budget -> record learnings to memory via local-writer. Authoring counterpart of the loop-engineer code loop |
by name / "improve this to a ScholarEval target under a budget" | .claude/agents/authoring-loop.md |
abstract-writer |
Extract a paper's own content (extract-paper-idea skill) and draft or refresh its abstract, grounded in its own contribution/method/results/limitations rather than a paraphrase; for a UQAC thesis, drafts the Résumé (French) + Abstract (English) pair from the same extraction. No citations, no Scopus, no deliberation. Self-checks against composition_rules.md + the latex-hygiene AI-usage scanner; confirms before overwriting existing content |
/abstract |
.claude/agents/abstract-writer.md |
latex-writer |
Bilingual LaTeX authoring: papers (IEEE/Springer/Elsevier), Beamer slides, TiKZ diagrams, thesis | by context (writing) | .claude/agents/latex-writer.md |
local-writer |
High-token repetitive writing (docstrings, comments, Markdown docs, Obsidian summaries) via the resolver's writer-role model over a Bash bridge; NOT LaTeX text authoring. It is also the only agent allowed to read or write the two memories, the Obsidian vault (through the outbox) and the graphify code graph, enforced by vault-access-guard.py (chapter 07) |
by context / by name | .claude/agents/local-writer.md |
local-coder |
Runs ONE plan on a local model with the aider-setup kit and reviews the result: the dispatch prompt carries a PLAN: <path> line naming a plan whose header names executor, tier and the review bounds. The agent launches aider-plan.ps1 (the kit's writer model codes, the kit's reviewer audits, required), then reviews the written files under R35 and records findings as - [ ] audit: lines. The kit also starts without this agent. It writes and edits no code and runs no state-changing git; local-coder-dispatch-guard.py refuses a dispatch with no valid plan (rules R38 and R39, chapter 11) |
by context / by name | .claude/agents/local-coder.md |
professor-expertise-finder |
Find university professors closest to a set of expertise keywords in a user-supplied location (never hardcoded): reuse or build a verified department/faculty-list table, rank with a /5 rubric grounded in Scopus-verified recent approved-publisher articles (scopus AU-ID + publications mode) and each article's own stated contribution (extract-contributions), never a guessed title match. Test mode, exclusion lists, an optional reviewers reference file, and a batch allocation mode (no-reuse, one-university-per-evaluator, conflict-of-interest, all enforced by script) |
/expertfinder |
.claude/agents/professor-expertise-finder.md |
The four ScholarEval auditors (scopus-auditor, paper-auditor, thesis-auditor,
thesis-proposal-auditor) score the document before writing the plan; after the plan is
executed they re-run the scoring on the revised source and report a before/after ScholarEval
comparison (baseline vs post), hard-gated so execution only completes when the score improves.
latex-writer key rules¶
- TiKZ: relative positioning only (drawio2tikz-converted figures are the sanctioned absolute-coordinate exception); arrows perpendicular; no overlaps
- References: peer-reviewed only (IEEE, Springer, Elsevier, Taylor & Francis, Cambridge, Wiley, IET, IOP, ACM, MDPI, ASME, ACME, BioMed Central (BMC)); DOI via hyperref; any other publisher needs user confirmation
- Tables: rows = parameters, cols = concepts; bold headers; 10 % grey row shading
- Language: French default for UQAC thesis, English for scientific papers
- Avoid AI-detectable patterns: zero-width spaces, smart quotes, em dashes, perfect parallel lists
reviewer-response key rules¶
- Reviewer files assigned sequentially: first file = R1, second = R2, etc.
- Grammar-only fixes (G): applied directly, no markup
- Additions
\added[id=RN]{}, deletions\deleted[id=RN]{}, rewrites\replaced[id=RN]{}{}(changes package) - Reviewer colors: R1 blue, R2 red, R3 orange, R4+ purple (
\definechangesauthor) - Every proposed reference validated via Scopus;
[NO DOI]flagged in the summary when applicable
Local delegation (Ollama subagents)¶
local-writer and local-coder cut cloud cost by keeping the top model as orchestrator and
pushing token-heavy generation to local models on the GPU. Each agent runs on a cheap cloud
model (Haiku) that only frames the task and drives a local model over ollama_bridge.py,
which speaks Ollama's HTTP API and takes --role writer or --role coder instead of a model
name; the bulk text or code is generated locally and free. Claude Code has one API endpoint per
process and no per-subagent endpoint, so a subagent cannot be pointed at Ollama while the main
session stays on Anthropic. That, and not the subscription, is why the Haiku wrapper drives
the bridge, and only that small wrapper spends cloud tokens.
Requirements: Ollama running, and a qualified tag for the role you are about to use
(model_resolver.py --resolve --role coder). There is no fallback tag: an unqualified role
is an explicit stop, never a silent substitution of a weaker model. LiteLLM
(~/.litellm/ollama.yaml) is optional and only gives the bridge its keep-alive / context
tuning. local-writer never authors LaTeX prose (it may add % comments only); all
scientific and LaTeX redaction stays with latex-writer + scientific-writing on the
latest cloud Claude model.
aider-setup is a second, separate local-coding lane that needs no Claude Code at all — how it
differs from local-coder and the nightly run itself: chapter 14.
Loop engineering (local-model dev loop)¶
The loop-engineer skill runs a budget-bounded develop-and-improve loop: design → plan →
code → comment → test → review → score → correct, repeating until a composite quality gate
is met or a hard budget cap is hit. It keeps the best cloud model (Fable 5) as
orchestrator/judge, uses cheaper cloud tiers (Opus for plans, Sonnet for execution and
review) for the actions, and delegates code and comments to the local local-coder /
local-writer agents so the heavy generation is free.
The loop is a procedure the session follows through /loopdev [--score N] [--no-merge-pr], see
chapter 04. The driver flag --loop of loop_engineer.py is not wired, so there
is no --budget option: the stop bounds (max_rounds, max_tokens, plateau) are asked of the
owner and declared with loop_bounds.py init, see chapter 11. The default
stop gate is composite: tests green AND no CRITICAL/HIGH review findings AND aggregate score
>= min_score (default 90); a literal 100 is opt-in. The loop also stops at the first bound
reached. The score aggregates findings from the
installed reviewers (/code-review, /security-guidance, pr-review-toolkit,
systematic-debugging) plus the betterleaks / pip-audit hooks, with security as a hard floor
(any CRITICAL fails the gate regardless of the aggregate). The final merge to a protected
branch is human-gated: the loop stops at "ready to merge" and waits for your confirmation.
The loop diagram and the use-case diagram are in Architecture.md
("Layer 5 — Loop engineering").
The same loop applies to writing through the authoring-loop agent (the ScholarEval-gated
variant): define a subject, author with an authoring agent (/litreview, latex-writer,
/replyreviewer, …) on Fable 5, audit with the scholar-evaluation skill on Sonnet or Haiku
to get a score, loop until the ScholarEval target or the budget is reached, then record the
learnings to memory via local-writer. The five steps are documented in the loop-engineer
SKILL.md.
Obsidian knowledge-capture loop¶
Both loops read and write the Obsidian vault so learnings persist across iterations and projects
(Claude Code has no cross-project memory of its own; the vault is that broad memory).
local-writer is the single, serialized vault writer; local-coder reads only and hands it any
learning. Reads happen at plan time (baked into the plan by brainstorming / writing-plans on
the cloud tiers) and, during a run, only by the local agents (task start, checkpoints, error
recovery); executing-plans does not read. Writes land in 10_Projets/<projet>/ logs and
reusable 30_Ressources/ atomic notes through the outbox only - the SessionStart/SessionEnd
obsidian-outbox-flush.py hook is the sole write path, never a fallback. The ~/bin/obsidian
wrapper is for reads. Requires Obsidian open with the CLI enabled. Full design in docs/contributor-notes.md
section 5; routing in .claude/CLAUDE.md.
Calling an agent explicitly¶
Agents are normally triggered automatically by context. To invoke one directly, address it by name in your message:
Use the scopus-auditor agent to audit the review in paper_review/literature_review.tex
reviewer-response agent: --paper sn-article.tex --reviewers r1.txt --editor "Prof. Yin"
The slash commands /auditreview, /replyreviewer, /litreview, etc. are thin wrappers that
call these agents with the same argument syntax — use the commands for convenience and the
explicit agent names when you need finer control or want to chain agents in one message.
Using the agents outside Claude Code¶
install.ps1 regenerates per-tool mirrors from the canonical .claude/agents/*.md
files. Run it after adding or editing an agent, then commit the regenerated output. Add
-Personal to also copy the Copilot agent profiles to ~/.copilot/agents/, which makes
them available to Copilot CLI in every project (re-run after agent edits to refresh).
Every harness, the file each one receives, and the limits that stub or trim a mirror (Copilot caps an agent prompt at 30,000 characters, Codex budgets its skill list) are in chapter 09. Copilot prompts are generated for every task command, not only for the agents, so the count of prompt files follows the commands.
For global availability in Claude Code (any working directory), install-junctions.ps1
links each .claude/agents/<name>.md into ~/.claude/agents/ per file (symlink; hard-link
fallback when Developer Mode is off — re-run after a git pull that changes agents).
Skills keep their per-folder junctions.