epic: migrate qualifying skills to Claude Code dynamic workflows

[laurigates]

Tracking issue for the dynamic-workflow migration. Plan merged in #2162: docs/plans/dynamic-workflow-migration.md.

What was decided

47 candidate skills were evaluated by a 16-agent dynamic workflow (fan-out triage → per-group harness design → three adversarial lenses → synthesis). 18 were nominated; 21 refutations were raised; 6 were demoted by majority refutation.

Of 47, five ship a harness. The separating criterion:

The fan-out width must already be enumerable by something other than the model.

Every mover reads its N from a deterministic source that already exists. Every rejection either invented its N, or duplicated a bound a shell script already enforces — .claude/rules/offload-to-deterministic-substrate.md run backwards.

Two of the blog post's six shapes — tournament and loop-until-done — have no fit in this repo. That is recorded as a finding, not a gap to close later.

Sequencing

Groundwork gates everything. Nothing ships a .js before #2163.

#2163 (convention) ──┬──> #2164 (guard)
                     ├──> #2165 (fork conflict) ──> #2170 (test-analyze)
                     ├──> #2167 (verify-before-filing) <── #2166 (file-wave.sh)
                     ├──> #2168 (configure-all)
                     ├──> #2171 (blueprint-story-audit)
                     └──> #2172 (Tier B) ──> #2169 (evaluate-plugin-batch)

#2173 (Tier C) — independent, no .js, landable any time

Groundwork

• docs(rules): add workflow-vs-skill.md and the bundled-workflow layout convention #2163 — .claude/rules/workflow-vs-skill.md + CLAUDE.md + plugin-structure layout convention (blocks all harnesses)
• ci(scripts): add check-workflow-templates.sh guard for bundled workflow templates #2164 — scripts/check-workflow-templates.sh guard
• fix(compliance): resolve the context: fork pin vs skill-fork-context.md for parallel fan-out skills #2165 — resolve context: fork pin vs skill-fork-context.md (blocker for feat(testing-plugin): ship test-analyze classify-and-act harness template #2170)
• refactor(workflow-orchestration-plugin): extract file-wave.sh from verify-before-filing REFERENCE.md #2166 — extract scripts/file-wave.sh (blocker for feat(workflow-orchestration-plugin): ship verify-before-filing workflow harness template #2167)

Tier A — ship the harness

• feat(workflow-orchestration-plugin): ship verify-before-filing workflow harness template #2167 — workflow-verify-before-filing · composite · zero refutations
• feat(configure-plugin): ship configure-all parallel check harness template #2168 — configure-all · fan-out-and-synthesize · zero refutations
• feat(evaluate-plugin): ship evaluate-plugin-batch fan-out harness template #2169 — evaluate-plugin-batch · fan-out-and-synthesize · must ship capped
• feat(testing-plugin): ship test-analyze classify-and-act harness template #2170 — test-analyze · classify-and-act · zero refutations
• feat(blueprint-plugin): ship blueprint-story-audit discovery fan-out harness template #2171 — blueprint-story-audit · fan-out-and-synthesize

Tier B — batch-only templates

• feat(plugins): ship batch-only workflow templates for four skills (Tier B) #2172 — git-pr-feedback --all, evaluate-skill, git-issue --parallel, cold-read-gate (optional)

Tier C — schema/prose only, no .js

• refactor(plugins): apply the Tier C schema and prose deltas — no .js for three skills #2173 — execution-grounded-review, agents-analyze, workflow-wave-dispatch, parallel-agent-dispatch

What is deliberately not here

35 of 47 skills stay as they are, and the plan's §"Rejected, and why" is as load-bearing as its recommendations. Before proposing a harness for anything not listed above, read that section — six designs were killed there, including:

• code-review — 1 agent today → up to 69, on the flagship many-times-daily skill. context: fork already isolates the file set, and its "self-preference" check re-reads file:line against current source, which loop-integrity.md classifies as already-independent.
• workflow-checkpoint-refactor — its ceiling would live in JS locals that silently reset on every --continue, defeating the exact runaway the ceiling exists to prevent.
• evaluate-improve — the proposed tournament reproduces sorted[0]; grade_deterministic.py already resolved the ranking.
• blueprint-autopilot — the design calls recordManifest() as plain JS, but the workflow API has no filesystem, and blueprint-autorun.sh already performs that write.

Also out of scope by decision: no new skill in workflow-orchestration-plugin for the authoring convention. It is about a page, and belongs in the paths:-scoped rule rather than costing listing tokens in every session.

Commit scoping

Each shipped .js is feat(<plugin>): … (minor bump on the published plugin). The rule, the CLAUDE.md row, and the guard script are chore / ci. Per .claude/rules/docs-currency.md, each template lands in the same commit as its SKILL.md framing section — a .js with no framing is exactly the "script to run verbatim" the source blog post warns against.

[laurigates]

Verified errors in this epic's issue graph

Found while landing #2163 (PR #2204). Every claim below was checked against the files on disk at origin/main today; child issue bodies are left untouched — this comment is the record. Three of the four child issues cite plugin-compliance-check.sh line numbers that do not match the current script, which suggests they were written against an older revision.

1. #2164 — the "#2063 has no check of its own" premise is refuted, and checks 1+2 are vacuously green today

Its check 3 rests on "the #2063 fix currently has no check of its own". It does have one:

• scripts/plugin-compliance-check.sh — the cold-read-gate branch of check_skill_body(): comment block ~953–964, guard at ~965–971. It loops for token in 'run_in_background: false' 'task-completion result' and appends a hard error when either is missing, citing issue feedback(agent-patterns-plugin): cold-read-gate should specify synchronous execution + how to retrieve the reader's critique #2063 in both the comment and the failure message.
• .claude/rules/regression-testing.md:207 records the feedback(agent-patterns-plugin): cold-read-gate should specify synchronous execution + how to retrieve the reader's critique #2063 fix and names that same guard as its check — i.e. the repo already considers it landed.
• agent-patterns-plugin/skills/cold-read-gate/SKILL.md:52 carries run_in_background: false, so the guard is live rather than vacuously passing.

Re-implementing it in check-workflow-templates.sh would double-gate (offload-to-deterministic-substrate.md §Cautions). The genuinely-unguarded surface, if the batch template ships, is its verdict enum — not the #2063 tokens.

Separately: checks 1 and 2 have nothing to check today.

$ git ls-files '*-plugin/**/*.js' | wc -l
0
$ grep -rl 'Workflow harness (template)' --include='*.md' .
./docs/plans/dynamic-workflow-migration.md      # the plan itself; zero SKILL.md hits

So the script would pass on an empty set. The issue's own acceptance criterion acknowledges this ("zero templates = vacuously green"), but the consequence for sequencing is worth stating: #2164 should land with or after the first harness, not as parallel groundwork — otherwise the guard ships never having proved it can fail on real input, which is exactly the syntactic-vs-semantic gap .claude/rules/task-id-stability.md records from the #1417 follow-up.

2. #2165 — the context: fork pin is not at :826, and it does not list two skills

scripts/plugin-compliance-check.sh:826 hard-pins context: fork on agents-plugin/agents-analyze and testing-plugin/test-analyze.

Both halves are wrong.

• Real location: the comment block starts at 881; the for fork_skill in \ loop runs 899–913. Line 826 is inside the unrelated git-pr-feedback / feedback(git-plugin): git-pr-feedback should foreground verifying automated-reviewer (Gemini) claims before accepting #1545 guard.
• Real list — 8 skills, not 2: code-quality-plugin/code-review, agents-plugin/agents-analyze, testing-plugin/test-analyze, testing-plugin/test-full, documentation-plugin/claude-blog-sources, documentation-plugin/docs-generate, evaluate-plugin/evaluate-skill, code-quality-plugin/dry-consolidation.

evaluate-plugin/evaluate-skill matters: #2172 ships it a parallel() harness, so it hits the identical fork-vs-fan-out conflict #2165 exists to resolve — and no issue currently covers that. Whatever resolution lands must cover it too.

The framing is also inverted. test-analyze today carries context: fork with no parallel() harness — it is the single-subagent, verbose-output case .claude/rules/skill-fork-context.md explicitly endorses, which is why the pin exists. There is no conflict on main. The conflict is created by #2170 (which adds the harness), not discovered by #2165.

Decision (Lauri): fold #2165 into #2170 and close #2165. The resolution is inseparable from the change that causes it, and the hard constraint — rule + guard list edited in the same commit, never a silent frontmatter edit — belongs in the PR that touches the frontmatter. #2172 should carry the same resolution for evaluate-skill.

3. #2169 and #2173 — same stale-revision line numbers

• feat(evaluate-plugin): ship evaluate-plugin-batch fan-out harness template #2169: cites plugin-compliance-check.sh:818-821 for the comment sanctioning context: fork off for the parallel-fan-out skills. That comment is at 894–897 ("NOTE: the parallel-fan-out skills (git-plugin/git-pr-feedback, evaluate-plugin/evaluate-plugin-batch, code-quality-plugin/code-antipatterns) deliberately keep context: fork OFF …"). Lines 818–821 are the git-pr-feedback feedback(git-plugin): git-pr-feedback should foreground verifying automated-reviewer (Gemini) claims before accepting #1545 token loop.
• refactor(plugins): apply the Tier C schema and prose deltas — no .js for three skills #2173: cites plugin-compliance-check.sh:826 for agents-analyze's pin — same wrong line as fix(compliance): resolve the context: fork pin vs skill-fork-context.md for parallel fan-out skills #2165. Real: 899–913.

All three point into the same wrong neighbourhood, which is the tell that they were written against an earlier revision of the script. Prefer citing the guard's grep token or function branch over a line number; line numbers in this file drift every time a regression guard is inserted.

4. #2170 — the routing table appeared three times, not twice, and PR #2196 already collapsed it

a fixed category→agent-type table that is currently restated twice in prose

Before #2196 (3f586bf0, merged today) there were three copies at differing row counts, which is exactly the drift the consolidation was meant to stop:

Copy	Location (pre-#2196)	Rows
Command Flow → "Delegate to Subagents"	~80–86	7
"The command uses this decision tree to delegate"	~97–112	6
Step 3 → "Subagent Delegation Strategy"	~193–218	7

#2196 has already landed both of #2170's "two corrections baked in" prerequisites: the stale agent names are fixed (code-review→agents-plugin:review, system-debugging→agents-plugin:debug/performance, code-refactoring→agents-plugin:refactor, test-architecture→agents-plugin:test, cicd-pipelines→agents-plugin:ci, documentation→agents-plugin:docs), and the three copies are collapsed into one 8-row table under ## Subagent Routing, annotated "This table is the single source of truth for delegation … no other section restates it."

So #2170's first two acceptance boxes are already done; its remaining scope is the .js plus the context: fork resolution (per item 2 above, now folded in from #2165). The annotation #2170 asks for — "this table is the contract the workflow's category enum and AGENT_FOR map encode — edit them together" — is still worth adding when the harness lands, since the existing note predates the harness.

---

Verification for every claim above is reproducible from origin/main: grep -n 'fork_skill' scripts/plugin-compliance-check.sh, grep -n '2063' scripts/plugin-compliance-check.sh, git ls-files '*-plugin/**/*.js', git show 3f586bf0^:testing-plugin/skills/test-analyze/SKILL.md.