@mmerterden/multi-agent-pipeline 20.6.0 → 20.7.0

package/pipeline/skills/shared/external/skill-creator/audit.md

@@ -1,59 +1,63 @@
-# Multi-architect audit - adversarial quality gate for a skill
-
-The [checklist](checklist.md) is the self-review floor. This is the **high-confidence
-gate**: a panel of N independent reviewers, each a *distinct lens*, reads the skill
-against the rubric + ground truth, then a synthesizer dedups and rules. You **loop
-fix → re-audit until it passes** (no blockers/majors). Run it before shipping a new
-or substantially-changed skill, or whenever a skill must be trusted.
-
-Use the [Workflow tool](scripts/audit-panel.js) to fan the panel out - it returns
-`{remaining, clearsBar, verdict}`.
-
-## The loop (run to convergence)
-1. **Panel** - N agents, one lens each, read-only. Each returns specific findings
-   (severity · file:location · problem · concrete fix). Empty if its lens is clean.
-2. **Synthesize** - dedup overlaps; **drop false positives** (verify each against the
-   real files/repo before keeping); classify blocker / major / minor / nit;
-   `clearsBar = no blockers and no majors remain`.
-3. **If not clean** - apply the do-now set (blockers + majors + cheap high-value
-   minors), then run a **fresh** panel (see "Fresh each round") and repeat.
-4. **Stop** when `clearsBar` is true. The later/nit list is optional polish.
-
-## Rules that make it trustworthy
-- **Fresh panel each round.** After a fix, re-run the panel anew so agents read the
-  *current* files - do not reuse a prior run's cached results (they reflect the old
-  state and will report fixed issues as open / miss regressions).
-- **Verify before keeping.** Every finding must be confirmed against the actual file
-  or repo. The synthesizer drops anything it can't reproduce. Prefer findings that
-  cite a line and a reproduction.
-- **Ground-truth, not vibes.** Give the panel the rubric ([SKILL.md](SKILL.md) +
-  [checklist.md](checklist.md)), an exemplar skill, and the real source the skill
-  describes (e.g. the iOS repo). Agents read; they don't assume.
-- **Watch for regressions.** A fix can break something - the red-team lens and the
-  fresh re-audit exist to catch it (e.g. a broadened check that now false-positives).
-- **clearsBar gates the merge.** Don't merge with an open blocker/major.
-
-## Lenses - pick the set for the task
-One distinct lens per agent (+ a synthesizer). Two ready-made sets:
-
-**General skill audit** - discovery · leanness · shape/layer · scripts · accuracy-vs-source · domain-correctness · wiring · boundaries · red-team → synthesis.
-
-**Prompt-engineering audit** (when the concern is *prompt quality* - descriptions,
-instructions, triggering):
-1. **description-as-discovery** - what + when + trigger words + example; would it activate on a real task?
-2. **disambiguation** - distinct from siblings; a reader can tell when to pick this vs a neighbor.
-3. **trigger coverage** - the real user phrasings (and synonyms) are covered.
-4. **instruction clarity** - steps are unambiguous, ordered, single-interpretation; no vague directives.
-5. **degrees of freedom / layer fit** - reference=descriptive (no numbered procedure), workflow=spine, tool=thin-index; freedom matches the task.
-6. **progressive disclosure / leanness** - SKILL.md is an index; detail bundled one level deep; no duplication.
-7. **token efficiency** - every line is load-bearing; nothing restates what the model already knows.
-8. **consistency** - terminology, naming, paths, cross-references, examples all agree.
-9. **anti-patterns / misfire** - would the model over-apply it, skip a gate, hallucinate a path, or follow it into a wrong output?
-10. **red-team** - adversarially try to make it not trigger, trigger wrongly, or produce broken output; hunt overclaims (says X, the script doesn't).
-
-Scale the panel to risk: a quick check is ~3 lenses; a thorough gate is ~10.
-
-## Scope of fixes per round
-Fix **blockers + majors** always; fold in **cheap, high-value minors** while you're
-in the file. Defer speculative nits and pre-existing/out-of-scope drift to the
-"later" list (and `log()`/note them - don't silently drop coverage).
+# Multi-architect audit
+
+The checklist is what one author catches alone. The audit adds a panel of independent, read-only reviewers, each looking through one lens, and a synthesizer that turns their output into a decision. New skills and substantial changes go through it before merge.
+
+## The loop
+
+1. **Panel.** Every lens reviews the skill and returns findings, each with a severity, a `file:location`, the problem and a concrete fix. A clean lens returns an empty list.
+2. **Synthesis.** One agent merges duplicates, opens the real files to discard false positives, classifies the rest as blocker, major, minor or nit, and sets `clearsBar` to true only when no blocker and no major is left.
+3. **Fix.** If the bar is not cleared, apply the do-now set and start a **new** panel.
+4. **Stop** once `clearsBar` is true. Remaining nits are optional polish.
+
+### What to fix in a round
+
+- Always: every blocker and every major.
+- Also, when cheap and clearly valuable: minors.
+- Later, on a written list: speculative nits and drift that was already there or sits outside this change. Record them; never drop them silently.
+
+## Rules that keep the result trustworthy
+
+- **Fresh panel every round.** Cached results describe the files as they were; a resumed run audits the old version.
+- **Verify before keeping.** Each finding is checked against the file before it counts. Prefer findings that cite a line and a way to reproduce.
+- **Give the panel ground truth:** the rubric (skill-creator SKILL.md plus checklist.md), an exemplar skill of the same layer, and the actual source the skill describes.
+- **Watch the fixes.** A fix can break something else. The red-team lens and the fresh re-audit are there to catch that.
+- **`clearsBar` gates the merge.**
+
+## Lens sets
+
+Scale the panel to the risk: about three lenses for a quick check, about ten for a full gate.
+
+### General
+
+discovery, leanness, shape and layer, scripts, accuracy against the source, domain correctness, wiring, boundaries, red team, then synthesis.
+
+### Prompt engineering (the script's default ten)
+
+| Lens | Asks |
+|---|---|
+| discovery | Does the description alone get the skill loaded? |
+| disambiguation | Could it be confused with a sibling? |
+| triggers | Which real phrasings and synonyms are missing? |
+| clarity | Is every instruction unambiguous and actionable? |
+| layer | Does the degree of freedom fit the declared layer? |
+| leanness | Is SKILL.md an index with detail one level down? |
+| tokens | Which lines fail the cut test? |
+| consistency | Do terms, names, paths, cross-references and examples agree? |
+| misfire | Where would it over-apply, skip its gate, invent a path, or produce the wrong output? |
+| redteam | Make it fail to trigger, trigger wrongly, or break its output; find prose that claims what the script does not do. |
+
+## Running it with the script
+
+`scripts/audit-panel.js` is a Workflow-tool template (workflow name `skill-audit-panel`, phases Audit and Synthesis). It takes no arguments; edit its config block first:
+
+| Constant | Set to |
+|---|---|
+| `TARGET` | absolute paths of the SKILL.md and each bundled file and script |
+| `RUBRIC` | path to skill-creator's SKILL.md plus checklist.md |
+| `EXEMPLAR` | a known-good skill of the same layer |
+| `GROUND_TRUTH` | the real source the skill documents, with the key facts to check |
+| `LENSES` | label and brief pairs; defaults to the ten above |
+
+It runs one agent per lens in parallel (labelled `audit:<lens>`), tags each finding with its lens, and hands them all to a `synthesis` agent. The result is `{ remaining, clearsBar, verdict }`: the surviving findings with the lenses that raised them, the gate boolean, and a one-paragraph verdict.
+
+After applying fixes, launch it again as a new run. Do not resume the old one; resumed agents return cached results.

package/pipeline/skills/shared/external/skill-creator/checklist.md

@@ -1,32 +1,40 @@
 # Pre-ship checklist
 
-Run before considering a skill done.
+The floor for every skill. New or substantially changed skills also go through the audit loop in audit.md.
 
 ## Discovery
-- [ ] `description` says **what + when + trigger words**, third person, and names the platform (iOS/SwiftUI).
-- [ ] Description disambiguates from sibling skills (a reader can tell when to pick this vs a neighbor).
-- [ ] Tested: in a fresh task that should trigger it, does the model actually reach for it? If not, sharpen the description.
+
+- [ ] The description says what the skill does, when to use it, and lists trigger phrases, in third person.
+- [ ] It names the platform where that matters.
+- [ ] It separates this skill from its siblings.
+- [ ] Tried on a new task it ought to catch, the skill really fires.
 
 ## Leanness
-- [ ] `SKILL.md` reads like an index, ~1 page (hard cap ~500 lines).
-- [ ] Detail lives in bundled files **one level deep** - no nested-deeper references.
-- [ ] Every line survives "would Claude err without this?" - no over-explaining, no restating what the model knows.
-- [ ] Deterministic code is a **script**, not prose asking the model to regenerate it.
+
+- [ ] SKILL.md is roughly one page and works as an index, far below the 500-line cap.
+- [ ] Detail lives in bundled files exactly one level below SKILL.md.
+- [ ] Every line passes the cut test.
+- [ ] Anything deterministic ships as a script instead of prose the model must re-derive.
 
 ## Shape
-- [ ] Layer is explicit (reference or workflow) and matches the content.
-- [ ] **Reference** skill has **no numbered procedures** - heuristics + pointers only.
-- [ ] **Workflow** skill's numbered steps are **only** the deterministic/irreversible spine, and it has a **verification gate**.
-- [ ] Conventions **point to canonical files** rather than pasting code that will rot.
 
-## Naming & wiring
-- [ ] Name has **no platform prefix**; reference = aspect noun, workflow = verb-phrase; not vague/reserved.
-- [ ] Registered in the plugin manifest (`<plugin>/.claude-plugin/plugin.json` `skills` array) and the marketplace version bumped (`.github/plugin/marketplace.json`).
-- [ ] Listed in the `index` skill's route table.
+- [ ] The layer is declared and the content matches it.
+- [ ] Numbered procedures never appear in a reference skill.
+- [ ] A workflow skill's steps are only the deterministic spine, and it ends in a verification gate.
+- [ ] Conventions point at canonical files instead of pasting code that will go stale.
+
+## Naming and wiring
+
+- [ ] No platform prefix; noun for reference, verb phrase for workflow; not vague, not reserved.
+- [ ] Registered in the `skills` array of `<plugin>/.claude-plugin/plugin.json`.
+- [ ] Plugin version bumped in `.github/plugin/marketplace.json`.
+- [ ] A row in the plugin's `index` skill route table.
 
 ## House rules
-- [ ] No AI/Claude/Anthropic attribution anywhere in the skill or its examples.
-- [ ] Escape hatches name the skill to hand off to when this one doesn't apply.
 
-## High-confidence gate (new / substantially-changed skills)
-- [ ] Ran the multi-architect audit ([audit.md](audit.md)) and looped fix → re-audit until `clearsBar` (no blockers/majors).
+- [ ] Neither the skill nor its examples carry AI, Claude or Anthropic attribution.
+- [ ] Each escape hatch says which skill takes over.
+
+## Confidence gate
+
+- [ ] New or substantially changed: the multi-architect audit ran, fixes were applied, and a fresh panel returned `clearsBar: true`.

package/pipeline/skills/shared/external/skill-creator/examples.md

@@ -1,65 +1,65 @@
-# Examples - descriptions & shape
+# Examples
 
-## Descriptions: the discovery lever
+## Descriptions
+
+### Weak
 
-**Bad (vague - rarely triggers):**
 ```yaml
-description: Helps with navigation
+description: Helps with navigation stuff.
 ```
-Why it fails: no "when", no trigger words, no platform - the router can't tell what task this matches.
 
-**Good (what + when + triggers + platform):**
+No situation, no trigger words, no platform. The router has nothing to match a request against, so the skill stays unloaded.
+
+### Strong, reference layer
+
 ```yaml
-description: "In-app navigation for a SwiftUI iOS app - the coordinator-per-domain pattern, the tab shell, cross-domain navigation, deep links, and modals. Reach for this when adding a screen, a tab, a deep link, or a modal, or deciding how one screen reaches another."
+description: "Navigation for iOS / SwiftUI: NavigationStack paths, tab structure, deep links, sheets and full-screen modals, and where routing state lives. Use when adding a screen, a tab or a deep link, presenting a modal, or debugging a push that does nothing. Triggers: 'add a new screen', 'open this from a deep link', 'present as a sheet'."
 ```
-Why it works: states the domain, lists concrete triggers ("adding a screen, a tab, a deep link"), names the platform, and implies the boundary.
 
-**Workflow example (action + when to run):**
+Coverage, concrete situations, the platform, and quoted phrases a developer would type. The domain words keep it apart from sibling skills on state or overlays.
+
+### Strong, workflow layer
+
 ```yaml
-description: "Branch, commit, push, and open a PR for this repo. Owns the git/PR spine and house guardrails - type-first branch names, no AI attribution, no force-push, correct base branch. Reach for this whenever a change is ready to ship."
+description: "Creates a branch, commits, pushes and opens a pull request with the house guardrails: type-first branch names, conventional commit messages with no AI attribution, never a force push, and the correct base branch. Use when work is ready to ship. Triggers: 'open a PR', 'commit and push this', 'create a branch for this ticket'."
 ```
 
-### Recipe
-`<what it covers/does> + <concrete when/trigger phrases> + <platform> + <implied boundary vs siblings>`
+States the action, the guardrails that make it safe, when it applies, and how users ask for it.
 
----
+## Layer shape
 
-## Shape: reference vs workflow
+### Wrong: a reference skill written as keystrokes
 
-**Wrong - a reference skill drifting into a procedure:**
 ```markdown
-## Procedures
-1. Open the file
-2. Add the wrapper
-3. Register the route
-4. Build and run
+## Adding a tab
+1. Open AppTabView.swift.
+2. Add a case to the Tab enum.
+3. Add a .tabItem block under the last one.
+4. Build.
 ```
-A reference (knowledge) skill should describe *the rule and where the canonical example lives*, not script the keystrokes.
 
-**Right - reference stays descriptive:**
+A reference skill describes; it does not dictate. These steps go stale the first time the file changes.
+
+### Right: the rule plus where to look
+
 ```markdown
-## Decision rules
-- New screen in a domain → add `<Name>Screen` under its Presentation layer,
-  wrap content in the domain's container, route via the domain coordinator.
-  Canonical: `<repo>/Features/Profile/ProfileScreen.swift`.
+## Conventions
+- Tabs are cases of the root `Tab` enum; each case owns its own navigation path.
+  Canonical file: `App/Sources/AppTabView.swift`.
 ```
 
-**Right - workflow earns its numbered steps** (deterministic/irreversible spine):
+### Right: a workflow that earns its steps
+
 ```markdown
 ## Procedures
-1. Pre-flight: `git status` clean? on base branch?
-2. Branch: `git checkout -b <type>/<scope>/<desc>`
-3. Commit: stage; conventional message; strip any AI co-author trailer.
-4. Push; never force-push a protected branch.
-5. PR: `gh pr create --base <base> ...` (no AI footer).
+1. Pre-flight: `git status` is clean and the base branch is correct.
+2. Create `{type}/{scope}-{short-description}`.
+3. Commit with a conventional message; strip any AI co-author trailer.
+4. Push without `--force`; never to a protected branch.
+5. `gh pr create --base {base}` with no AI footer in the body.
+
 ## Verification
-- `git log -1` shows clean message, no AI trailer, correct author.
+- `git log -1` shows a clean message, no AI trailer, and the expected author.
 ```
 
----
-
-## Leanness: cut what the model already knows
-
-**Bloat:** "PDF files are documents that contain text and images. To read them you first need a library that can parse the binary format..."
-
-**Lean:** "Extract text from PDFs with `pdfplumber`."
+Every step is deterministic or irreversible, and the skill proves its result before it finishes.

package/pipeline/skills/shared/external/skill-creator/label-check.md

@@ -1,43 +1,55 @@
-# Label intent check - does a title carry its own meaning?
+# Label check
 
-A label (rule title, section header, principle/constraint name) is the handle a reader grasps *before* the body. If the handle leaks the wrong shape - ambiguous, one-sided, or off-topic - the reader forms the wrong model and the body has to fight it. This is a cheap test that catches that early: have **fresh subagents infer the rule from the label alone**, then compare against your intended meaning. Convergence = the label is self-carrying.
+A reader forms a model of a rule from its label before reading the body. If the label points the wrong way (ambiguous, covering only one side, or about something adjacent), that wrong model sticks. This test measures what a label actually conveys by asking agents that never see the body.
 
 ## When to run it
-- Naming a **strict rule** or constraint inside a skill (the kind a reader must obey).
-- A **section header** that gates non-trivial content (phase/principle/constraint names).
-- Any label meant to convey the **whole intent** of its body (not a summary - the intent).
-- Skip it for purely organizational labels ("Examples", "See also") - they carry no intent.
-
-## Inputs (collect first)
-1. **Candidate label** - the exact string under test.
-2. **Surrounding context** - one paragraph: which skill/doc, what adjacent labels cover, the domain concepts in play.
-3. **Intended meaning** - 1-3 sentences of ground truth (what the body says / what the reader should walk away believing). **Not** shown to the inference agents. If you can't state it in 3 sentences, the body is unclear - fix that first.
-
-## Procedure
-**One iteration = 5 parallel subagents**, each given ONLY the label + context (never the body), each forced to commit:
-```
-Context: <surrounding context - 1 paragraph>.
-The label under test is: **"<candidate label>"**
-You have NOT seen the body. From ONLY this label + context, what do you infer it
-enforces / requires / means? 1-2 concrete sentences, under 80 words. Commit - no
-hedging, no clarifying questions.
-```
-Launch all 5 in the **same** message (parallel) so they're independent by construction.
-
-**Convergence (per iteration), comparing the 5 inferences to the intended meaning:**
-- **PASS** - ≥4/5 cover *all* key intent beats (including the bidirectional / edge / scope beat, if the intent has one). Wording drift is fine.
-- **PARTIAL** - they consistently catch one side of a bidirectional rule but miss the other, or over-extend into an adjacent concern. Revise the label, re-run.
-- **FAIL** - inferences diverge wildly or miss the core beat. Revise, re-run.
-
-**Idempotency (after a PASS):** run **2 more rounds**, 5 fresh agents each (3×5 = 15 inferences), same prompt. Require **all 3 rounds PASS** with no new systematic miss - confirms the PASS wasn't luck. A regression in round 2/3 → treat as PARTIAL and iterate.
-
-**Termination:** converged (3/3 PASS) → apply the label. 3 iterations without a PASS → stop, hand back the best candidate + the persistent miss; don't force a label that won't stick.
+
+- Names of strict rules and constraints.
+- Section headers that gate non-trivial content.
+- Any label that is meant to carry the whole intent on its own, including top-level skill names.
+
+Purely organisational headers ("Examples", "Setup") do not need it.
+
+## Inputs
+
+1. The candidate label.
+2. One paragraph of the surrounding context, as a reader would meet it.
+3. The intended meaning in one to three sentences. This stays with you; the agents never see it. If you cannot state it in three sentences, fix the body before testing the label.
+
+## A round
+
+Launch five subagents **in one message**, so none anchors on another. Each receives only the label and the context paragraph, never the body, and is told to commit to what the label means in one or two sentences, under 80 words, with no hedging and no questions back.
+
+## Grading
+
+| Grade | Condition | Next |
+|---|---|---|
+| PASS | At least 4 of 5 inferences cover every key beat of the intent, including the bidirectional, edge or scope beat. Different wording is fine. | Idempotency rounds |
+| PARTIAL | The inferences consistently catch one side of a two-sided rule, or stretch into a neighbouring concern. | Revise, run again |
+| FAIL | Inferences diverge, or miss the core beat. | Revise, run again |
+
+## Idempotency
+
+After a first PASS, run two more rounds with five fresh agents each: 15 inferences in total. All three rounds must pass with no new systematic miss. A later round that regresses counts as PARTIAL.
+
+## Stopping
+
+- Three of three rounds pass: apply the label.
+- Three revisions without a PASS: stop, and hand back the best candidate together with the miss that kept recurring.
 
 ## Defaults
-5 agents/round · 3 rounds · 80-word inference cap · max 3 iterations before handing back. High-stakes labels (top-level skill names, protocol names) → 7 agents × 3 rounds; throwaway section headers → 3 × 2.
+
+| Stakes | Agents | Rounds |
+|---|---|---|
+| normal | 5 | 3 |
+| high (top-level skill names, protocol names) | 7 | 3 |
+| throwaway header | 3 | 2 |
+
+Word cap 80; at most 3 revision iterations.
 
 ## Anti-patterns
-- **Giving agents the body** - defeats the test (you're checking the label's *self-carrying* power).
-- **Running sequentially** - they'd anchor on each other; must be parallel.
-- **Tweaking one word on a FAIL** - step back and rethink the concept the label names, don't polish a wrong handle.
-- **Accepting "mostly right"** - a label that reliably misses a beat misleads every reader the same way. Fix it, or accept the rule is one-sided and split the body.
+
+- Showing the agents the body. That tests the body, not the label.
+- Running agents one after another; later ones anchor on earlier answers.
+- Changing one word after a FAIL. A FAIL means the concept behind the label is off; rethink it.
+- Accepting "mostly right". For a one-sided result, either fix the label or split the rule so each part has a label that fits.

package/pipeline/skills/shared/external/skill-creator/scripts/audit-panel.js

@@ -1,119 +1,110 @@
-// audit-panel.js - Workflow template for the multi-architect skill audit.
-//
-// Run with the Workflow tool. Edit the CONFIG block for your target, then launch.
-// Returns { remaining, clearsBar, verdict }. If clearsBar is false, apply the
-// `remaining` blockers/majors, then RE-RUN A FRESH copy (do NOT resume - agents
-// must read the current files). Loop until clearsBar. See ../audit.md.
-
 export const meta = {
-  name: "skill-audit-panel",
-  description: "Adversarial N-architect audit of a skill against the skill-creator rubric",
-  phases: [{ title: "Audit" }, { title: "Synthesis" }],
-};
-
-// ── CONFIG - edit these ──────────────────────────────────────────────────────
-const TARGET = `
-- <abs path to SKILL.md>
-- <abs path to each bundled file / script>
-`;
-const RUBRIC = `<abs path to reference/skill-creator/SKILL.md> + checklist.md`;
-const EXEMPLAR = `<abs path to a known-good skill of the same layer>`;
-const GROUND_TRUTH = `<abs path to the real source the skill describes (e.g. the iOS repo), with key facts>`;
-// Pick a lens set from audit.md (general or prompt-engineering). [label, brief] pairs:
-const LENSES = [
-  [
-    "discovery",
-    "description-as-discovery: what+when+trigger words+example; would it activate on a real task?",
-  ],
-  [
-    "disambiguation",
-    "distinct from sibling skills; a reader can tell when to pick this vs a neighbor.",
-  ],
-  ["triggers", "real user phrasings + synonyms are covered."],
-  ["clarity", "instructions unambiguous, ordered, single-interpretation; no vague directives."],
-  [
-    "layer",
-    "degrees of freedom match the layer (reference=descriptive / workflow=spine / tool=thin-index).",
+  name: 'skill-audit-panel',
+  description: 'Runs an independent, multi-lens review of a single plugin skill, scored on the skill-creator rubric',
+  whenToUse: 'Gate before shipping a skill that is new or heavily reworked; start a new run once each round of fixes lands',
+  phases: [
+    { title: 'Audit', detail: 'one read-only reviewer per lens' },
+    { title: 'Synthesis', detail: 'dedup, verify, classify, decide clearsBar' },
   ],
-  ["leanness", "SKILL.md is an index; detail bundled one level deep; no duplication or bloat."],
-  ["tokens", "every line load-bearing; nothing restates what the model already knows."],
-  ["consistency", "terminology, naming, paths, cross-refs, examples all agree."],
-  [
-    "misfire",
-    "would the model over-apply, skip a gate, hallucinate a path, or follow it to a wrong output?",
-  ],
-  [
-    "redteam",
-    "adversarially make it not trigger / trigger wrongly / produce broken output; hunt overclaims (says X, script does not).",
-  ],
-];
-// ─────────────────────────────────────────────────────────────────────────────
+}
 
-const COMMON = `
-You are auditing a skill. Read the CURRENT files and report ONLY genuine, specific,
-reproducible findings for YOUR lens. Verify against the rubric + ground truth - do
-not assume. Read-only; do NOT edit. If your lens is clean, return an empty array.
+const TARGET = [
+  '/abs/path/to/plugins/<plugin>/skills/<layer>/<skill>/SKILL.md',
+  '/abs/path/to/plugins/<plugin>/skills/<layer>/<skill>/reference.md',
+]
+const RUBRIC = '/abs/path/to/plugins/ai-common-toolkit/skills/knowledge/skill-creator/SKILL.md and checklist.md beside it'
+const EXEMPLAR = '/abs/path/to/an/exemplar/skill/in/this/layer/SKILL.md'
+const GROUND_TRUTH = '/abs/path/to/source/code/described/by/the/skill (name the key facts worth checking)'
 
-TARGET (the skill under audit):${TARGET}
-RUBRIC (the bar): ${RUBRIC}
-EXEMPLAR (known-good of this layer): ${EXEMPLAR}
-GROUND TRUTH (what the skill describes): ${GROUND_TRUTH}
-
-Each finding: severity (blocker|major|minor|nit), file:location, the problem, the concrete fix.
-`;
+const LENSES = [
+  { label: 'discovery', brief: 'Does the description alone get the skill loaded? What + when + trigger words + a sample trigger, third person, platform named.' },
+  { label: 'disambiguation', brief: 'Could a router confuse this skill with a sibling? Are the boundaries and hand-offs explicit in the description and header?' },
+  { label: 'triggers', brief: 'Which real phrasings and synonyms a user would type are missing from the description?' },
+  { label: 'clarity', brief: 'Is every instruction unambiguous and actionable, with no step that two readers would execute differently?' },
+  { label: 'layer', brief: 'Does the content match its declared layer (reference descriptive, workflow imperative with a verification gate, tool a thin index over a script)?' },
+  { label: 'leanness', brief: 'Is SKILL.md an index of about one page, with detail one level deep in bundled files and deterministic code in scripts?' },
+  { label: 'tokens', brief: 'Which lines fail the cut test because the model would act correctly without them?' },
+  { label: 'consistency', brief: 'Do terms, names, paths, cross-references and examples agree with each other and with the files that exist?' },
+  { label: 'misfire', brief: 'Where would the model over-apply the skill, skip its gate, invent a path, or produce the wrong output?' },
+  { label: 'redteam', brief: 'Try to make it fail to trigger, trigger wrongly, or break its output; hunt for prose that claims what the scripts do not do.' },
+]
 
 const FINDING = {
-  type: "object",
+  type: 'object',
   additionalProperties: false,
+  required: ['severity', 'location', 'problem', 'fix'],
   properties: {
-    severity: { type: "string", enum: ["blocker", "major", "minor", "nit"] },
-    location: { type: "string" },
-    problem: { type: "string" },
-    fix: { type: "string" },
+    severity: { enum: ['blocker', 'major', 'minor', 'nit'], type: 'string' },
+    location: { type: 'string', description: 'file:line or file#heading' },
+    problem: { type: 'string' },
+    fix: { type: 'string', description: 'a concrete change, not advice' },
   },
-  required: ["severity", "location", "problem", "fix"],
-};
-const LENS_SCHEMA = {
-  type: "object",
-  additionalProperties: false,
-  properties: { lens: { type: "string" }, findings: { type: "array", items: FINDING } },
-  required: ["lens", "findings"],
-};
+}
 
-phase("Audit");
-const results = await parallel(
-  LENSES.map(
-    ([lens, brief]) =>
-      () =>
-        agent(`${COMMON}\n\nYOUR LENS - ${lens}: ${brief}`, {
-          label: `audit:${lens}`,
-          phase: "Audit",
-          schema: LENS_SCHEMA,
-        }),
-  ),
-);
-const all = results.filter(Boolean).flatMap((r) => r.findings.map((f) => ({ ...f, lens: r.lens })));
+const LENS_RESULT = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['lens', 'findings'],
+  properties: {
+    lens: { type: 'string' },
+    findings: { type: 'array', items: FINDING },
+  },
+}
 
-phase("Synthesis");
-const SYNTH = {
-  type: "object",
+const SYNTHESIS = {
+  type: 'object',
   additionalProperties: false,
+  required: ['remaining', 'clearsBar', 'verdict'],
   properties: {
     remaining: {
-      type: "array",
+      type: 'array',
       items: {
-        type: "object",
+        type: 'object',
         additionalProperties: false,
-        properties: { ...FINDING.properties, lenses: { type: "string" } },
-        required: [...FINDING.required, "lenses"],
+        required: ['severity', 'location', 'problem', 'fix', 'lenses'],
+        properties: { lenses: { type: 'string', description: 'every lens that reported it, comma-separated' }, ...FINDING.properties },
       },
     },
-    clearsBar: { type: "boolean" },
-    verdict: { type: "string" },
+    clearsBar: { type: 'boolean' },
+    verdict: { type: 'string', description: 'one paragraph' },
   },
-  required: ["remaining", "clearsBar", "verdict"],
-};
-return await agent(
-  `${COMMON}\n\nYou are the SYNTHESIS architect. Below are ${all.length} raw findings from ${LENSES.length} lenses. Dedup overlaps (note which lenses raised each). DROP false positives - verify against the files before keeping; if you cannot reproduce it, drop it. Classify each survivor; set clearsBar=true ONLY if no blockers and no majors remain. One-paragraph verdict.\n\nRAW:\n${JSON.stringify(all, null, 2)}`,
-  { label: "synthesis", phase: "Synthesis", schema: SYNTH },
-);
+}
+
+const PREAMBLE = [
+  'You are one reviewer on an independent audit panel for a plugin skill. Stay read-only: do not edit any file.',
+  `Read the current state of every target file now; do not rely on anything you saw earlier:\n- ${TARGET.join('\n- ')}`,
+  `Rubric: ${RUBRIC}`,
+  `Exemplar of the same layer: ${EXEMPLAR}`,
+  `Ground truth the skill describes: ${GROUND_TRUTH}`,
+  'Report only genuine findings for your lens that you can reproduce by pointing at a line. Check each one against the rubric and the ground truth before reporting it.',
+  'Each finding needs a severity (blocker, major, minor, nit), a location, the problem, and a concrete fix. If your lens finds nothing, return an empty findings array.',
+].join('\n\n')
+
+phase('Audit')
+const lensOutputs = await parallel(LENSES.map((lensDef) => () =>
+  agent(`${PREAMBLE}\n\nYour lens: ${lensDef.label}. ${lensDef.brief}\nSet "lens" to "${lensDef.label}".`, {
+    label: `audit:${lensDef.label}`,
+    phase: 'Audit',
+    schema: LENS_RESULT,
+  })))
+
+const raw = lensOutputs
+  .filter(Boolean)
+  .flatMap((out) => out.findings.map((item) => ({ ...item, lens: out.lens })))
+log(`${raw.length} raw finding(s) from ${lensOutputs.filter(Boolean).length}/${LENSES.length} lenses`)
+
+phase('Synthesis')
+const synthesis = await agent([
+  'You synthesize an audit panel\'s findings for a plugin skill. Stay read-only.',
+  `Target files:\n- ${TARGET.join('\n- ')}`,
+  `Rubric: ${RUBRIC}`,
+  `Ground truth: ${GROUND_TRUTH}`,
+  `Raw findings (JSON):\n${JSON.stringify(raw, null, 2)}`,
+  'Merge duplicates and record every lens that raised each merged item in "lenses".',
+  'Open the cited file for each finding and drop any you cannot reproduce there.',
+  'Classify what survives as blocker, major, minor or nit.',
+  'Set clearsBar to true only when no blocker and no major remains.',
+  'Write a one-paragraph verdict.',
+].join('\n\n'), { label: 'synthesis', phase: 'Synthesis', schema: SYNTHESIS })
+
+return synthesis