A Claude Code plugin for computational-biology analysis repos where humans and coding agents work side by side.
Both follow the analysis template's CONVENTIONS.md: versioned task directories, output paths that survive a git
worktree being removed, and a shared AnnData zarr working object per dataset that grows by additive write-back
only. The plugin adds what only agents do: one task per session, git worktree and pull request.
| Part | What it does |
|---|---|
skills/analysis-workflow/ |
The agent's side: task lifecycle in a worktree, sign-off, PRs, environments, setting up repos. Loaded on demand. |
skills/declare-inputs/, skills/trace-lineage/ |
What a task consumed, written to its inputs.yaml from its code; and how an artifact was made, as a graph and a summary. |
hooks/ |
Always-on core rules and the main checkout's environment at session start; guards that stop a rule being broken by accident, each of which you can lift for a session. |
src/analysis_workflow/ |
The Python package and its analysis-workflow command: task paths, writes to shared stores and their records, tracing (as a tree, or as a graph of tasks drawn by Graphviz, a conda package of the analysis repo), layout checks; the task template. |
It assumes analysis repos made from analysis_template (pixi-managed) and code repos from the scverse cookiecutter (uv-managed). Nothing in it is specific to a dataset, an analysis or a compute environment.
Start each analysis task as its own session, from the analysis repo's main checkout. Pull it first: the worktree
branches from origin's default branch but runs on the main checkout's environment.
claude --worktree <task>- The agent works on that worktree's branch, in a new task directory
analysis/<dataset>/<topic>/agent_<task>_vN/; a later answer to the same question gets the next version, in a new session. Earlier task directories are never edited. - It asks you which working object is current and agrees what the task delivers (by default your
deliverablessetting), then works in scripts; outputs go to the task directory. - Results reach shared storage only after you sign off, inside a
writesblock that records in the store which task wrote them. - It opens a PR whose body holds the details; the task README summarizes each PR. Once it is merged and its batch
jobs have finished, leave with
/exitand remove the worktree.
A rule is broken only with your approval. When a guard refuses something you want done, the agent passes on the
command that lifts it for that session, /analysis-workflow:allow <guard>, which only you can run; the PR notes
the exception (the template's CONVENTIONS.md).
You work the same way, in human_ task directories in the main checkout (the template's CONVENTIONS.md). A task that changes the environment locks, installs and tests
it in a temporary checkout beside the main one; after its merge you pull and run pixi install there. With no
analysis repo yet, ask Claude to start an analysis project: the skill sets one up.
The plugin, once per machine, from the quadbio marketplace. The
skill is then available everywhere; the hooks and session-start rules act only in repos that enable the plugin in
their committed .claude/settings.json. Every repo made from
analysis_template does, and depends on the package in its
pixi.toml (its lock pins the commit; pixi update moves it). To adopt an existing repo, ask Claude to adopt the
conventions.
Settings, saved with /plugin configure analysis-workflow@quadbio:
| Setting | Default | Meaning |
|---|---|---|
deliverables |
a figure |
What a task delivers unless you choose otherwise at its start; recorded in the task README. Blank: the agent asks. |
uv sync --group dev
uv run pytest
uv run pre-commit run --all-files
claude plugin validate .
claude --plugin-dir . # try the skill and hooks from this checkoutFor live package edits in an analysis repo, depend on the checkout instead:
analysis-workflow = { path = "../analysis-workflow", editable = true }.
Bump version in .claude-plugin/plugin.json and merge: the marketplace follows main, and users update when the
version changes.
MIT