Agents
An agent here is a sub-agent: a separate agent with its own context. The main session starts it for one task and gives it a prompt. The sub-agent does the task and returns one report, which the main session reads as the result. Its work does not fill the context of the main session. A skill or another agent can also start a sub-agent.
Each source is a Markdown file in agents/. Its frontmatter holds name, the name that a caller uses; description, the text from which the frontend selects the agent for a request; tools, the neutral tools that the agent can call; and model, a model tier (large, medium or small). An agent with no model uses the model of its caller. Some agents also set effort, skills (the skills that load at the start), isolation: worktree, omitClaudeMd: true (the agent does not load CLAUDE.md), permissionMode: plan or cacheTtl: 1h. The body is the instruction text of the agent. Most bodies prescribe the exact shape of the report.
harness install copies each agent to ~/.claude/agents/ for Claude Code, with the model tier and the tools written as Claude Code names them. It renders each agent for OpenCode, with an "Under OpenCode" section before the body, for oh-my-pi, and for Antigravity, with an Antigravity tier as its model. Architecture gives the map of the tools and model tiers. The sections below come in five groups: the builder-critic loop, pull requests and CI, Julia diagnosis and tests, research, and the general-purpose agents.
julia-builder
The builder of the builder-critic loop. A task file holds a plan that is split into parts, and each part is one pull request. The builder builds one part. The build-part skill starts it and runs the loop. Call it directly only for a part that you have already chosen.
The builder reads its part's spec bundle, which its caller writes with spec-bundle.py: the part's rows and sections, the plan's §V and §L, and the sections that §L names. It reads nothing else of the task file. It works in a worktree that its caller creates. It writes the tests first, then the code, and verifies each clause of the part's Done when, the part's acceptance criteria. It writes and runs one mutant for each guard, branch, comparison and decided edge case of its change. It closes each surviving mutant, or gives a reason to keep it. Its report lists every mutant with its verdict.
As the last step of every round, it rereads each line of text that its diff adds or changes, or that the diff makes false: comments, docstrings, messages, CHANGELOG.md, KNOWN_ISSUES.md and the docs. It checks each claim and fixes the false ones. Its report lists the lines that it checked and fixed. Then it commits and returns Verdict: ready for critic. After each critic round, the caller starts a new builder on the same worktree. After a FAIL, the new builder fixes the blocking defects and records other defects in the repository's KNOWN_ISSUES.md. After a PASS, it rereads the text of the whole branch, runs julia-branch-verifier and opens the pull request.
It runs no command longer than 5 minutes. A longer run goes to its caller under Left for the dispatcher. The dispatcher is the session that runs the build-part or build-reviewed skill. The builder never merges, and it does not edit the task file. Use julia-pr-shepherd to take the pull request to green CI.
julia-critic
The critic of the builder-critic loop. It judges one built part against the part's Done when and returns Verdict: PASS or FAIL, with the defects. The build-part skill starts it. It reads the same spec bundle as the builder, and edits nothing in the worktree.
In round 1, the first critic round, two critics judge the whole part independently, and neither sees the builder's report. A critic writes its own evidence table and runs every check itself. It runs the new tests on the base, runs each named mutant, and probes the edges of each clause. It writes its probes only to a scratch directory for its round. A verify round is a later critic round that checks only the fix: it judges only the fix diff, against the earlier blocking defects and their reproducers.
Each blocking defect has a reproducer and one cause, for example wrong result, spec or fix regression. The dispatcher uses the cause to decide whether the loop continues. The critic does not run the full suite, does not start a sub-agent, and does not comment on a pull request. Use julia-pr-reviewer for a pull request that exists.
python-builder
The builder of the builder-critic loop for a part in a Python repository. The build-part skill starts it in place of julia-builder when the part's spec says **Language:** python, or, without that line, when the repository holds a pyproject.toml and no Project.toml. It has the tiers and the steps of julia-builder, with a gate of its own, and reads the same spec bundle.
Its gate is the one that the plan's §V names; in the Harness that is harness test, with the parts that a change reaches while it edits and the full suite once before it reports, and ruff format --check, ruff check and basedpyright, which the pre-commit hook also runs. The lines that it adds or changes meet the strict profile with the generated records removed. It runs the named mutants and its own with harness mutate, and breaks a file that is not Python by hand. After a PASS it rereads the text of the whole branch, pushes the branch and opens the pull request; it starts no sub-agent.
python-critic
The critic of the builder-critic loop for a part in a Python repository, in place of julia-critic. It has the rounds, the blocking rules, the causes and the report of julia-critic. It runs the parts of harness test that the diff reaches, the three checks of the strict profile and the spec's checks, runs each named mutant and its own doubted ones with harness mutate, and checks each idiom of the python-code rule on the lines of the diff. It edits nothing in the worktree, does not run the full suite, and does not start a sub-agent.
advisor
The advisor decides one question in an autonomous loop, in place of a question to the user. Only the dispatcher of the build-part skill calls it; a builder or a critic never does. Typical questions: a builder stops on a decision that its section does not make, a clause is ambiguous, or a finding may be out of scope.
It reads the part's sections and every decision that the task file records. It checks a claim itself before a decision rests on it. It returns the decision, the reasons, the rejected options, a confidence (high, medium or low), and whether the decision is reversible inside the pull request. A low decision parks the part for the user.
It edits nothing. It does not decide a decision part, a weaker Done when, a change to a public API beyond the part, or an action outside the pull request. Use arbitrator when the loop does not converge.
arbitrator
The arbitrator rules on the course of a builder-critic loop that does not converge. The dispatcher of the build-part skill calls it on one of four triggers: a second FAIL, a stop after a PASS that asks for a code change, a defect class that already failed another part, or a blocked loop.
It reads the whole loop: every builder's and critic's report, the diffs of each round, the suite runs and the decisions. It gives each blocking defect a cause and measures the progress from round to round. Then it chooses one move from a fixed list, for example continue, redesign, test round, fresh build or park. It returns the move, the decision text for the task file, a confidence, and whether the move parks the part for the user.
It edits nothing and does not ask the user. Use advisor for one question in a loop that converges.
part-builder
The builder for a part whose part-tier cell is reviewed, in any language. The build-reviewed skill starts it, and starts a new one for each later round: the fix after the critic, and the finish, the last builder round, which opens the pull request. Each new builder gets the last builder's report as the handoff note.
It reads its part's sections and the plan's §V and §L, the plan's verification and loop sections, which name the gate: the suite and the checks that the change must pass. It writes the tests first, then the code, and verifies each clause. Like julia-builder, it runs a mutant for each guard, branch, comparison and decided edge case of its change, and lists each one with its verdict. It also rereads the text of its change as the last step of every round. It commits and returns Verdict: ready for critic. After the critic's report, it fixes the blocking defects and records other defects. On Round: finish it does what §L says. In a package repository, it runs julia-branch-verifier and opens the pull request.
It runs no command longer than 5 minutes and does not edit the task file. Use julia-builder or python-builder for a part of part tier build, and worker for a task with no part and no critic.
part-critic
The critic for a part of part tier reviewed. The build-reviewed skill starts it once per part. It judges the part blind against its Done when and returns PASS or FAIL.
It writes its own evidence table, runs the gate that §V and §L name, breaks each named mutant in a copy, and probes each clause's domain. It writes probes only under a scratch directory. A defect blocks only when it is a failure inside a clause's domain, a test that cannot fail, a surviving named mutant, or a hidden failure. Every other defect goes into the report for the record.
It edits nothing in the directory of the work and does not start a sub-agent. Use julia-critic or python-critic for a part of part tier build, and julia-pr-reviewer for a pull request that exists.
julia-pr-shepherd
The shepherd takes a pull request on a Julia package from review to a pushed fix. Use it with a request such as "review and fix PR #NN" or "take PR #NN all the way". Start it from a directory in the package's checkout; it then works in a worktree of its own.
It checks first that the pull request is open, is not a draft, and accepts a push. Then it starts julia-pr-reviewer, which posts the review. It fixes the findings of severity blocker, bug and correctness-risk, and starts changelog-scribe for a changelog entry. It commits the paths by name, pushes, and posts one comment that answers each finding. It does not wait for CI: its report names the runs of the push and the gh run watch command for each, and its caller waits. The prompt cache of a sub-agent expires after 5 minutes, so a sub-agent that waits for CI must write its whole context to the cache again.
It never merges and never approves. It makes one fix round only, and it stops on a design decision. Use julia-pr-reviewer when you want only a review.
julia-pr-reviewer
The reviewer reviews a pull request on a Julia package and posts the review. Use it with a request such as "review PR #NN", "is this PR ready to merge" or "why is CI red on this PR". julia-pr-shepherd also starts it.
It works in a worktree of its own at the head of the pull request. It takes the file list from git diff, because gh pr view --json files stops at 100 files. It reads the CI jobs, not only the workflow result, and measures each figure that the pull request claims once more. It reviews blind: it treats the author's description of the change as a claim to check. It writes only the review body and its probes, under a scratch directory, and posts the review with gh.
It returns a findings table with file:line and evidence, and the CI verdict. It does not edit code. Use julia-pr-shepherd to fix the findings, and the julia-package-audit skill for a sweep of a whole package.
julia-branch-verifier
The verifier checks and fixes a topic branch of a Julia package before its pull request exists. julia-builder and part-builder start it before they open a pull request.
It finds the diff against the merge base and the set of changed symbols. Then it runs a seven-point pass on the diff only, for example correctness, type piracy, type instability, avoidable allocations, stale comments and history outside CHANGELOG.md. A finding counts against the branch only when its source is in the changed lines, or when the branch made it wrong. It fixes what it can, under the rules of the julia-surgical-fix skill.
It returns a verdict, the exact paths to stage, and a block for the pull-request body. It does not stage, commit, push or open the pull request, and it does not run Pkg.test(). For a missing changelog entry it names changelog-scribe. Use julia-pr-reviewer after the pull request exists.
ci-triage
This agent reads the GitHub Actions results of one or more repositories. It separates real regressions from failures that are already known. Use it with a request such as "why is CI red" or "check CI across the packages". julia-pr-shepherd also starts it.
It uses gh and reads the jobs of each run, not only the run's result. Its source lists many traps, for example a check that is missing instead of failed, or a corrupted cache on one operating system. It never reports green for a repository that it could not read.
It returns one verdict per repository: green, FAIL, expected red, no runs or drift. An expected red is a real answer, not a hedge: a red check that an entry of the repository's KNOWN_ISSUES.md explains. It writes only its query files, in one scratch directory, and changes nothing else. Use julia-pr-reviewer for the content of one pull request.
julia-load-doctor
This agent finds out why a Julia package does not load, and proposes the smallest fix. Use it with a request such as "using X fails" or "the pre-commit hook says loads FAILED". A package that does not load blocks every commit that stages a .jl file, because pre-commit runs a load test.
It reproduces the failure and reads the first error, not the last. It puts the cause into one of six classes: a missing manifest, a stale manifest, an undeclared dependency, a name moved to an extension, an upstream regression, or code that needs a rewrite. The two manifest classes are environment states: their fix is an instantiate or an update, and nothing is committed, because Manifest.toml is gitignored. A stale pin inside [compat] also shows a [compat] lower bound that is too low, and the agent reports that bound as a second finding. Before it blames upstream, it checks whether the manifest is out of date. It probes in a scratch environment outside the repository.
It returns the cause class, the file:line, the minimal fix, and whether the fix is local or needs an upstream release. It diagnoses only and edits nothing.
julia-test-runner
This agent runs Julia tests and returns only the verdict, so that the test output stays out of the main context. Use it with a request such as "run the tests" or "run that one testset". The build-part and build-reviewed skills start it for the full suite and for the long runs of a builder.
It runs a selection of test files with run-tests.jl, or the full suite, with --check-bounds=auto when allocations are in scope. It can also use a warm Kaimon session, or the testrunner command for one test file and line range. It reports the Julia version and the check-bounds setting. Under --check-bounds=yes it says that the run is no evidence for an allocation bound.
It returns pass or fail per testset, with each failure quoted in full. It does not edit source, change a tolerance or skip a testset. Use julia-perf-analyst for speed or allocation questions.
julia-perf-analyst
This agent answers a Julia performance or allocation question by measurement. Use it with a request such as "why does this allocate", "did this change help" or "reproduce the allocation figure from that PR". It follows the julia-performance skill, which it loads.
It first reproduces the reported number. If the number does not reproduce, it reports that and stops. It measures each variant in a fresh process, after a warm-up, with the median over repeats. It uses --check-bounds=auto and prints the resolved package versions next to each reading. Then it applies only the change under test, and only after that looks for the cause.
It returns a table of allocations and times, the method, the cause with file:line, and a conclusion. "Not reproducible" is a complete answer. Use the julia-package-audit skill for a static sweep with no measurement.
literature-scout
This agent searches the literature and returns a triaged list of candidates with DOIs. Use it with a request such as "find papers on X", "is there prior work on this" or "track down this citation".
It searches the structured indexes first, for example Crossref, OpenAlex and arXiv, and publisher pages last. For a paper behind a paywall it uses the link resolver that the tree instructions name. It marks each candidate as new, already in a .bib file, already in the library, superseded or retracted. It proposes a citation key in the scheme AuthorSurname:Year.
It returns a table of candidates, BibTeX entries for the new ones, a retrieval worklist, and what it did not find. It writes no prose review and has no write tools. If a fetched page tells it to act, it quotes the text and stops. It sends every request anonymously: no name, email address, mailto= parameter or API key, and no new account or key. An index that rate-limits it or asks for contact details counts as a failed source.
latex-verifier
This agent checks the mathematics of a .tex manuscript claim by claim, and writes a Julia script that checks each claim. Use it with a request such as "check the derivation in this paper" or "verify the proof in section 3". It loads the math-verify and latex-revision skills.
It lists and numbers all claims first. For each claim it decides what a check is and what makes the check fail. It writes the check in Julia, runs it, and runs a control that can fail too. It iterates in a Kaimon session and takes each result for its report from a fresh process, as math-verify says. It puts each script into the paper's scripts/ directory and cites it with \script{}.
It returns a verdict per claim (holds, fails, holds under a condition, or inconclusive) and the scripts. It does not change prose, the structure or the change markings. For one statement with no paper, use the math-verify skill.
editor
The editor takes one unit of a book or a paper, such as a chapter, an appendix or a section, from its brief to a verified commit. A session that writes a book or a paper starts one editor per unit, in the background, and names the brief template of a writer, the shared files that the editor may edit, the log directory and whether it commits. The editor loads no CLAUDE.md; it reads the instruction files of Papers/ and Books/ and of the manuscript itself, and it loads the math-verify and latex-revision skills.
It fills the brief and starts a writer in the foreground. Then it verifies the unit itself: it reads every page in the PDF, redoes every proof, reads and runs every script and its controls, reads the sources of every claim called new, and builds once. It starts literature-scout to check the identifiers of new bibliography entries. Its findings go to a new writer, never to the first one through SendMessage: a send resumes the writer in the background, the editor's turn then ends, and the end of its turn ends its run. It starts at most three writers per unit, merges the writers' rows into the shared files, starts changelog-scribe, and commits the paths by name.
It edits no file that a writer owns, and it leaves a run of more than ten minutes, such as a whole verification suite, to its caller. Its cache lives one hour, because it waits for each writer with the unit read into its context. It returns one report with a Verdict: line.
writer
The writer writes one unit of a book or a paper from a brief, or fixes the editor's findings on it. The editor starts it in the foreground, one writer at a time in a checkout. A fix round is a new writer, which gets the brief, the findings and the report of the writer before it.
It loads no CLAUDE.md; it reads the instruction files of Papers/ and Books/ and of the manuscript, and it loads the math-verify and latex-revision skills. It edits only the files that its brief names, and returns the rows for a shared file as text. Every claim gets a script in scripts/ with a control that must fail. It reads a source before it calls a result new, runs its scripts and one LaTeX build at a time, and reads every page that it wrote in the PDF.
It never stages or commits, and it starts no sub-agent. It returns one report with a Verdict: line: the pages, the scripts with their check counts, the new bibliography entries, the rows for the shared files and, in a fix round, what it did about each finding.
reader
A lean read-only agent: it searches, reads and returns the conclusion. Use it in place of a general-purpose agent for a search whose answer is a list, a location or a short verdict. A workflow script can name it as the agent of a read-only stage. It has no model, so it uses the model of its caller.
It loads no CLAUDE.md, memory or skill list, so it starts with a small context. It runs only read-only shell commands. It cites each fact as path:line, separates what it read from what it infers, and says what it did not search. It does not treat a truncated search as a negative result.
It changes nothing. Use exhaustive-auditor when you publish a claim about every instance, about no instance, or about the absence of something. Use worker when files change.
worker
A lean agent for one bounded task that reads, edits and runs commands: a stage of a fan-out, a mechanical change in a named set of files, or a scripted check. Use it in place of a general-purpose agent when the prompt specifies the task fully. A workflow script can name it as the agent of a stage. It has no model, so it uses the model of its caller.
It loads no CLAUDE.md, so the caller names the rules that the task needs. It touches only what the task names, and edits files only with Edit and Write. It does not stage, commit or push unless the prompt says so. It puts temporary files under a scratch directory, never in a repository.
It returns what it changed, what it ran and what that returned. Use reader when nothing changes, and a julia-* agent when the task needs that agent's protocol.
exhaustive-auditor
This agent audits a bounded scope completely, for a claim that you publish in a review, an issue or a paper. Use it with a request such as "is this function dead code" or "list every use of X in this package". It is slow and expensive, and it needs an explicit scope.
It sweeps the whole scope with a text search, then reads and classifies each hit. A comment, a keyword argument and a real call can match the same pattern. It adds julia-methods.jl, which lists the definitions of a name without loading the package, and julia-callers.jl, which lists callers in a Kaimon session. It runs in plan mode and changes nothing.
It returns the scope, the verdict, the classified hits, and every limitation that could make the verdict false. The verdict is "cannot be established" unless it read or swept every path of the scope. For a quick check, use reader.
changelog-scribe
This agent writes the CHANGELOG.md entry for a change that is already made. Use it with a request such as "write the changelog entry" or "does this need a changelog entry". julia-pr-shepherd starts it, and julia-branch-verifier names it for a missing entry.
It reads the top of the file first, because the convention differs from tree to tree: version headings for a package, dated passes for a paper, a research log for a project. It writes one entry in that convention: what changed and why it matters to a user. For a format pass, a typo or a rename with no effect, it reports "no entry needed".
It edits CHANGELOG.md and no other file. Under OpenCode, a path rule limits its edits to that file. It does not stage or commit, and it does not change a version number. Use the julia-release skill for a release.