Add change-propagation skill and worker agent (#142)

* Add change-propagation skill and _propagate_target worker

Add an agentic workflow that propagates an adapted copy of a reference
file/directory across several targets (monorepo libs and/or external
repos) in parallel, then files one draft PR per repo.

- skills/change-propagation/SKILL.md: the lead. Parses a natural-language
  reference + target list, confirms the parse, fans out one stateless
  _propagate_target worker per target, converges proposals (one
  vivarium-suite PR for libs, one PR per external repo), gates all
  durable writes on a single bulk approval, and files draft PRs via
  team-conventions. Includes dry-run mode, per-target failure isolation,
  and shared-root + write-denial fallbacks.
- agents/_propagate_target.md: per-target worker. Adapts (never copies)
  the reference; monorepo targets run in an isolated git worktree and
  verify with the package's full make check, external targets adapt
  read-only through the GitHub MCP; propose-only, no writes before
  approval.
- README.rst: register both units; document the writing worker in the
  security model and the skill-spawns-worker delegation path. Also repair
  a pre-existing mangled ticket-triage/commit-splitter Skills entry.
- CHANGELOG.rst: 0.18.0 entry.

Implements MIC-6975.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Address PR review feedback

- Unify target handling: every target (lib, shared root file, external repo)
  gets a local checkout the worker edits; the lead integrates the worktrees
  directly instead of workers serializing file content back.
- External targets now get a local clone, not a GitHub-MCP-only path.
- Delegate shared-root-file changes to a worker too.
- Soften "never copy verbatim" (a verbatim copy is sometimes right); drop the
  redundant sandbox framing in the worker.
- Trim: remove dry-run mode, the flag-for-review step, and the key-disciplines
  section; stop reproducing team-conventions mechanics; collapse the brief and
  converge prose per review suggestions.
- Shorten the CHANGELOG bullet.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Refine change-propagation skill from MIC-7099 dogfooding

Adjustments learned from running the skill on MIC-7099 (classifiers):

- Verification scales to blast radius: full `make check` for code, but a
  parse + targeted-validity check (e.g. trove-classifiers) for metadata-only
  edits, instead of building an env per lib for zero signal.
- Add a `target_basis` brief field and state plainly that workers have no
  network/GitHub access, so the lead pre-fetches any per-target source
  (e.g. an archived repo's historical setup.py) in step 1.
- Lead sanity-checks each worker's returned content before integrating
  (a worker can report `adapted` while truncating its own output); note an
  optional independent verify pass for correctness-critical runs.
- Allow lighter structured-proposal integration for small, uniform, disjoint
  edits instead of mandating per-worker worktree integration.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* Manual edits for succinctness.

Co-authored-by: Patrick Nast <130876799+patricktnast@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: Steve Bachmeier <23350991+stevebachmeier@users.noreply.github.com>
Co-authored-by: Patrick Nast <130876799+patricktnast@users.noreply.github.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Co-authored-by: Steve Bachmeier <23350991+stevebachmeier@users.noreply.github.com>

Author: 3 people

tools/ai-tools/CHANGELOG.rst

@@ -1,3 +1,7 @@
+**0.22.0 - 06/25/26**
+
+ - Add ``change-propagation`` skill to copy boilerplate across libs
+ 
 **0.21.0 - 06/25/26**
 
  - Add ``workflow-assessment`` skill to investigate workflow correctness post-hoc

tools/ai-tools/README.rst

@@ -103,6 +103,10 @@ handed to the ``ticket-triage`` skill (see Skills below), to compile and file no
   commands, README, root ``CLAUDE.md``) for drift against upstream
   sources via per-unit ``_claim_auditor`` sub-agents; fixes are gated on
   user approval.
+- ``change-propagation`` — propagate boilerplate across several targets (monorepo libs and/or external
+  repos) in parallel, one ``_propagate_target`` worker per target, then
+  converge them into one draft PR per repo — every durable write gated on
+  one explicit approval.
 - ``workflow-assessment`` — post-hoc audit of an agentic workflow run
   against its own definition: fans out the ``_trace_extractor`` sub-agent
   over the run's session transcripts and grades coverage, ordering/gates,
@@ -174,6 +178,7 @@ same main session — not as a sub-agent — so ``_review-core`` can spawn the
 review be reused by other main-session commands without duplicating the
 fan-out.
 
+
 Security model and recommended deny rules
 =========================================
 
@@ -218,6 +223,14 @@ Code:
   files — but running a test suite executes arbitrary project code, so this is a
   broader grant than the read-only git agents above. It is spawned only by the
   ``/viv:framework-development`` slash command.
+- ``_propagate_target`` (spawned by the ``change-propagation`` skill) also
+  **writes** and runs the test suite: for a monorepo target it adapts files
+  into a ``libs/<pkg>/`` subtree and runs that package's ``make check`` inside
+  an **isolated git worktree** (its verification sandbox). Its prompt constrains
+  it to write only within its assigned target and to **never** push, branch,
+  commit, or open a PR — every durable write is the lead skill's, after explicit
+  approval. For an external target it uses only read-only GitHub MCP calls and
+  writes nothing.
 - The ``/viv:code-reviewer``, ``/viv:model-regression-debugger``, and
   ``/viv:framework-development`` slash command bodies (running in the main
   session) gather PR/repo context through the GitHub MCP server (a plugin

tools/ai-tools/agents/_propagate_target.md

@@ -0,0 +1,126 @@
+---
+name: _propagate_target
+description: "Use when: adapting a reference file/dir into one propagation target (a monorepo lib or an external repo) and reporting the result back to the lead. Spawned by the change-propagation skill, one worker per target."
+tools:
+  # Edits files and runs the target's checks inside a local checkout — a git
+  # worktree for a monorepo target, a clone for an external repo.
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - Bash
+user-invocable: false
+---
+
+You own **one propagation target**. You take a reference (a file or a small
+set of files) and produce an **adapted** version of it for your target —
+reconciled with what the target already has — then report the result back to
+the lead.
+
+Your working directory is the **local checkout** the lead provisioned for this
+target: a git worktree of `vivarium-suite` for a monorepo target, a clone of
+the repo for an external target. You edit in it and leave your changes there;
+the lead integrates that checkout and does all durable git (branch, commit,
+push, PR) after the user approves.
+
+## Input
+
+The lead's brief gives you:
+
+- **`target`**: the single target — a monorepo lib (its `libs/<pkg>/` path), a
+  shared monorepo root file, or an external repo (`owner/repo`).
+- **`substrate`**: `monorepo` or `external`.
+- **`reference_files`**: the reference file set — for each, its path and its
+  content (the lead has already resolved these from the reference source).
+- **`source_package`**: the package/repo the reference was taken from, and a
+  note on what in it is **source-specific** (its package name, its
+  `python_versions.json`, its paths, its CHANGELOG/version) versus the
+  **generalizable** boilerplate you are meant to carry over.
+- **`target_basis`** *(optional)*: source material specific to **this** target
+  that the lead has already gathered for you. When present, use it as the seed for
+  your target's version; fall back to the shared `reference_files` when absent.
+- **`intent`**: one or two sentences on what the propagation is for, so you
+  can judge what "adapted correctly" means for an ambiguous case.
+
+## Approach
+
+1. **Understand the reference.** Read every `reference_file`. Separate the
+   generalizable boilerplate from the source-specific values called out in
+   `source_package`. Carry the boilerplate over, rewriting source-specific
+   values for your target where they appear — though for some files a verbatim
+   copy is exactly right; it depends on the reference.
+
+2. **Read the target's current state** so you adapt rather than overwrite. For
+   each reference file, find the target's existing counterpart if there is one.
+
+3. **Adapt.** For each file, produce the version the target *should* have:
+   - **No counterpart exists** → create it, rewriting any source-specific
+     values for the target.
+   - **A counterpart exists and is already equivalent** → no change.
+   - **A counterpart exists and differs** → reconcile: bring across the
+     boilerplate's intent while preserving target-specific content the
+     reference doesn't know about. If the existing file and the reference
+     **genuinely conflict** (the target has a deliberately different version
+     that can't be merged without a judgment call), do **not** force it —
+     record it as a conflict and leave the file unchanged.
+
+4. **Write the adapted files into your checkout, then verify — proportionate to
+   what the change can actually break.** Match the check to the blast radius,
+   and say which depth you ran and why:
+   - **Code changes** (anything affecting imports, behavior, or the build) →
+     run the package's full `make check` from `libs/<pkg>/` in the background
+     (slow — lint + mypy + fast tests + docs), or the external repo's checks
+     when an env is available; otherwise note it's unverified and relies on CI.
+   - **Metadata-only changes** (classifiers, URLs, description, authors, a
+     lint-config tweak that can't change imports) → a full `make check` builds
+     an env for zero signal. Instead confirm the file parses and run a targeted
+      validity check , and note that the suite was deliberately skipped.
+   When a check fails, determine whether **your change caused it** or it is a
+   **pre-existing** failure (check against the unmodified target if in doubt)
+   and report which.
+
+5. **Decide your status:**
+   - `adapted` — you produced at least one file change.
+   - `no-op` — the target already matches the reference; nothing to change.
+   - `conflict` — at least one file needs a human judgment call.
+   - `failed` — an adaptation-caused check failure you can't fix within your
+     target, or the target is unreadable.
+
+6. **Report to the lead** (see "Output"). Leave your edits in the checkout —
+   the lead integrates it directly; you don't serialize file contents back.
+
+## Output
+
+Send the lead a structured report with these sections (use "none" where empty):
+
+```
+## Target
+<owner/repo or lib name> — substrate: <monorepo|external> — status: <adapted|no-op|conflict|failed>
+
+## Changed files
+- <path> — <created|modified|deleted>
+
+## Verification
+<make check pass | make check fail (adaptation-caused|pre-existing) + detail | unverified — relies on repo CI>
+
+## Conflicts
+- <path> — <what the target has vs what the reference wants, and why it needs a human call>
+
+## Notes
+- <anything the lead must know: source-specific values you rewrote, assumptions, partial results>
+```
+
+## Constraints
+
+- **Leave durable git to the lead.** No push, branch, commit, or PR — you edit
+  in your checkout; the lead integrates it and does all durable git after the
+  user approves.
+- **Adapt where it matters.** Rewrite source-specific values (package name,
+  versions, paths) for the target — but a verbatim copy is fine when that's
+  what the file calls for.
+- **Stay in your target.** Edit only your own checkout; never reach into
+  another target's.
+- **Don't force a conflict.** When the target has a deliberately different
+  version, report it as a conflict for a human call — do not silently
+  overwrite it.

tools/ai-tools/skills/change-propagation/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: change-propagation
+description: 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.
+---
+
+# Change propagation
+
+Take a **reference** — an existing file or small directory that already
+embodies the thing you want everywhere — and propagate an **adapted** version
+of it into a set of **targets**, in parallel, then file pull requests. The
+targets are a mix of monorepo libs (`libs/<pkg>/`) and external GitHub repos.
+Adaptation is the point: each target's existing files are reconciled with the
+reference and the source's own identity (package name, `python_versions.json`,
+paths, version) is rewritten, not necessarily copied verbatim.
+
+You are the **lead**. You resolve the reference and the target list, fan out
+one `_propagate_target` worker per target, converge their proposals into
+per-repo branches, gate everything on one explicit approval, and file the
+PRs.
+
+## Process
+
+You **MUST** complete these in order. Track them with `TaskCreate`.
+
+### 1. Parse and confirm the input
+
+Read `$ARGUMENTS` as natural language naming a **reference source** and a
+**target list**. Resolve and classify, then **echo your parse back and wait
+for confirmation before spawning anyone** — this is a cheap gate that catches
+a misread reference or target before any work fans out.
+
+- **Reference source** → a concrete file set. If it's a directory, list the
+  files you'll carry. Identify the **source package/repo** so workers know
+  what is source-specific versus the generalizable boilerplate.
+- **Target list** → classify each entry:
+  - a monorepo lib by name or path (`config-tree`, `libs/engine`) →
+    `monorepo` substrate;
+  - an `owner/repo` (`ihmeuw/vivarium`) → `external` substrate.
+- **Per-target source material.** If adapting a target needs more than the
+  shared reference — e.g. each target's *own* pre-migration file, recovered
+  from an archived external repo or older git history — resolve that **here**,
+  while you (the lead) still have GitHub/network access. Workers don't; they
+  only ever see what you put in their brief (see step 2).
+- **Optional MIC key.** If the user names a motivating ticket (`MIC-####`),
+  use it for branch names and PR linkage. If not, offer to file one.
+
+### 2. Fan out one worker per target
+
+Spawn one `_propagate_target` worker per target, **in parallel**. Brief each
+worker with: its single `target`, the `substrate`, the `reference_files`
+(path + content), the `source_package` note, the `intent`, and — when the
+adaptation needs material specific to that target — the `target_basis` you
+gathered in step 1.  Then:
+
+- **Monorepo workers** each run in their own **isolated git worktree** — spawn
+  them with the Agent tool's `isolation: "worktree"`, so the worker's working
+  directory *is* a fresh checkout, cut from the same base you'll branch the
+  integration branch from. They adapt into `libs/<pkg>/` (or a shared root
+  file) and verify proportionate to the change — full `make check` for code, a
+  parse + targeted-validity check for metadata-only edits (see the worker's
+  step 4) — leaving the result in the worktree for you to integrate directly.
+- **External workers** each work in a **local clone** of the target repo that
+  you provision — it's outside the monorepo, but the worker still gets a real
+  checkout to edit in and to run the repo's checks against when an env is
+  available.
+
+### 3. Collect and converge
+
+Each worker returns `{target, substrate, status, proposed files, verification,
+conflicts, notes}`. Account for **every** target — a dead or garbled worker
+is reported as *not propagated*. **Don't trust a worker's self-report
+blindly** — sanity-check what it actually produced (the right file changed, the
+content is plausible and complete, nothing truncated or dropped) before you
+integrate it; a worker can report `adapted` while having mangled its own
+output. For a correctness-critical propagation, an independent verification
+pass per target — a second agent checking each adapted file against the intent
+— is worth the cost. Then converge by substrate: one PR for the monorepo
+(integrate every monorepo worker's worktree onto a single `vivarium-suite`
+branch — their subtrees are disjoint, so they union cleanly), and one PR for
+each external repo. For **small, uniform, disjoint** edits — one field added to
+each `pyproject.toml`, say — you needn't juggle N worktrees: a worker can
+return its adapted content or a diff and you apply them onto one branch
+yourself. Reserve full per-worktree integration for substantial, multi-file
+per-target changes.
+
+Sort targets into what you'll file versus what you'll hold:
+
+- `adapted` → goes into the PR set.
+- `no-op` (already matches the reference) → **no PR**; report as already
+  current. Never open an empty PR.
+- `conflict` → **held by default**; surface the divergence for a human call.
+  The user can include it (apply anyway), drop it, or resolve it manually.
+- `failed` / `make check` failure → **held by default**; surface it.
+  Distinguish an *adaptation-caused* failure (the change is bad) from a
+  *pre-existing* one (the lib was already broken — the user may want to
+  propagate anyway). One bad target never blocks the rest.
+
+A reference may also include a **shared root file** (root `pyproject.toml`
+lint config, `CLAUDE.md`, a root workflow). Delegate it to its own worker like
+any other target; integrate its worktree onto the same `vivarium-suite` branch
+alongside the per-lib changes.
+
+### 4. Present the plan and gate on one bulk approval
+
+Show the consolidated plan in one place: per target, its status and proposed
+change (diffs are fine to render); the held set (conflicts, failures, no-ops)
+with reasons; and the PR set you intend to file (one `vivarium-suite` PR +
+one per external repo, each a **draft**). Then take **one bulk approval** to proceed.
+
+### 5. (after approval) File the PRs
+
+Hand all PR mechanics to `/viv:team-conventions` — branch naming, the PR
+template, draft status, and the `#vivarium_dev` review flag live there. File
+one `vivarium-suite` PR for the integrated monorepo branch and one PR per
+external repo.
+
+### 6. Report
+
+List, per target: the filed PR (key/URL) or the reason it was held (conflict,
+failure, no-op, worker death). Confirm every target from step 1 is accounted
+for. Stop — committing further, merging, and un-drafting are the user's call.