vivarium-suite

Guided iteration loop for a vivarium model — take one model change from a research-spec doc through a staged artifact→component→observer build, InteractiveContext verification, review, and a PR. Use when the user asks to implement or iterate a model concept (a cause, risk, intervention, or observer) in an existing model repo from its vivarium-research documentation, or names a MIC ticket that points at one.

Use when the user asks about vivarium-suite CI — build status, Jenkins console logs, job structure, GitHub Actions runs, etc. Covers the GH Actions / Jenkins setup, the per-package Multibranch Pipeline layout, URL-to-jobFullName translation for the Jenkins MCP, and parallel matrix log interleaving.

SimSci Engineering team convention for drafting a Design Document on the IHME hub. Use whenever the user asks to e.g. "draft a design doc", "write a design document", "make a design doc", or "start a PRD".

Reference for the shared `make` targets used across vivarium repositories, centralized in `vivarium/build_utils/resources/makefiles/`. Use this when the task involves making a new conda environment, formatting code, running development checks, or type hinting. Use whenever the user asks what a `make <target>` does in a vivarium repo, mentions running `make` in this ecosystem, or whenever another skill or instruction says "run `make X`" and you need to know exactly what it does, its arguments, env vars, and side effects.

Internal building block invoked by /viv:code-reviewer (and framework-development's review phase): runs the multi-agent review fan-out + functional-correctness pass + per-finding confidence scoring + synthesis on a diff the caller has already gathered. Not a review entry point — to review a PR, use /viv:code-reviewer.

Use after a code review when some findings won't be addressed in the current PR — triages them into Jira ticket recommendations. Classifies each unaddressed finding (address-now / ticket / drop), groups ticket candidates by theme, checks the MIC backlog for duplicates via the `_duplicate_finder` sub-agent, then drafts and files tickets per team conventions, every write gated on explicit user approval. Trigger on "triage the findings", "file tickets for the rest", "turn these review comments into tickets", or when the user defers review findings after `/viv:code-reviewer`.

Propagate an adapted copy of a reference file or directory across several targets — monorepo libs and/or external repos — in parallel, then file one draft PR per repo. Use when the user wants to roll a piece of boilerplate or config out to many places at once. Not for a single-target edit (just edit it) and not when the change needs bespoke per-target design rather than adaptation of a shared reference.

Assess a finished run of an agentic workflow — did the multi-agent handoffs and tool invocations happen the way the workflow's definition says they should? Reads the Claude Code session transcripts and judges the trace against the workflow definition across coverage, ordering/gates, parallelism, handoff completeness, tool appropriateness, and result propagation. Trigger whenever the user wants to debug or verify the procedural correctness of a Claude session, especially ones with engineered orchestration or multi-agentic workflows.

Use when the user is performing post-install configuration for components shipped by this plugin — work that the plugin install itself doesn't perform.

Audit the repo's AI plaintext — the ai-tools plugin (skills, agents, commands, README) and CLAUDE.md — for drift against the upstream sources those docs mirror, then fix approved findings. Use when the user asks to "audit the skills", "check the AI docs for staleness", "run repo maintenance", or wonders whether the tooling docs are still accurate. Expensive (a fan-out over every unit with live upstream checks) — don't trigger it as a side effect of other work.

SimSci Engineering team conventions for everyday git/Jira/PR mechanics — branch naming from a MIC ticket, writing a Jira ticket against the team's hub doc, opening a PR with the repo's `.github/pull_request_template.md` via the GitHub MCP, and flagging the PR for team review in `#vivarium_dev`. Use whenever the user asks to "make a branch", "name this branch", "create a ticket", "write a Jira ticket", "open a PR", "flag a PR for review", "post my PR", or anything similar where the team convention is the answer.

Use BEFORE any design or feature work — picking an approach, scoping a change, fleshing out a sparse ticket, deciding whether something needs a design doc. Runs a structured brainstorm with one-question-at-a-time clarification, 2–3 approaches with explicit tradeoffs, ultimately producing a design artifact such as design-doc or JIRA ticket. Trigger on any task that involves reasoning about *what* to build or *how* to approach it, but not when the design is already settled and only execution remains.

Reference for the vivarium-ecosystem console scripts that a standard model-repo conda env puts on PATH — `simulate`, `psimulate`, `vipin`, the per-repo `make_artifacts`, and `update_gbd_round`. Use whenever the task involves running, restarting, expanding, or smoke-testing a vivarium simulation; launching one on the cluster; building or rebuilding a model's data artifact; extracting psimulate worker performance; or exporting a GBD round.

Reference for the vivarium pytest setup. Use this skill when running, debugging, or developing automated test coverage.

Split a bulk uncommitted diff into a sequence of small, reviewable commits — and, when scope warrants, into multiple PR-sized branches. Use when the user asks to break up uncommitted changes for review, or references PR-size limits. May also be surfaced as a suggestion when a large pending diff is about to be committed — but offer, don't impose, since a coherent refactor often should stay as one commit.

How to pick up the right Python environment in a vivarium repo, and how to create one if you need to. Use whenever you need to run tests, lint, scripts, or execute make commands, anything that imports the package. Also use when the user asks to "set up an environment", "use the shared env", "rebuild my env", or hits import/activation problems.

Search and retrieve content from the Vivarium Research documentation (vivarium-research.readthedocs.io). Use whenever the user asks, implicitly or explicitly, the specification for how something is modelled in Vivarium — a disease, risk factor, intervention, demographic process, or simulation-component design — or when they reference the Vivarium Research docs by name or URL.