@mmerterden/multi-agent-pipeline 11.0.0 → 11.2.0

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

@@ -0,0 +1,65 @@
+# Examples — descriptions & shape
+
+## Descriptions: the discovery lever
+
+**Bad (vague — rarely triggers):**
+```yaml
+description: Helps with navigation
+```
+Why it fails: no "when", no trigger words, no platform — the router can't tell what task this matches.
+
+**Good (what + when + triggers + platform):**
+```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."
+```
+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):**
+```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."
+```
+
+### Recipe
+`<what it covers/does> + <concrete when/trigger phrases> + <platform> + <implied boundary vs siblings>`
+
+---
+
+## Shape: reference vs workflow
+
+**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
+```
+A reference (knowledge) skill should describe *the rule and where the canonical example lives*, not script the keystrokes.
+
+**Right — reference stays descriptive:**
+```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`.
+```
+
+**Right — workflow earns its numbered steps** (deterministic/irreversible spine):
+```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).
+## Verification
+- `git log -1` shows clean message, no AI trailer, correct 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`."

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

@@ -0,0 +1,43 @@
+# Label intent check — does a title carry its own meaning?
+
+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.
+
+## 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.
+
+## 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.
+
+## 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.

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

@@ -0,0 +1,83 @@
+// 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).'],
+  ['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.
+
+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 FINDING = {
+  type: 'object', additionalProperties: false,
+  properties: {
+    severity: { type: 'string', enum: ['blocker', 'major', 'minor', 'nit'] },
+    location: { type: 'string' }, problem: { type: 'string' }, fix: { type: 'string' },
+  }, 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 })))
+
+phase('Synthesis')
+const SYNTH = {
+  type: 'object', additionalProperties: false,
+  properties: {
+    remaining: { type: 'array', items: { type: 'object', additionalProperties: false,
+      properties: { ...FINDING.properties, lenses: { type: 'string' } },
+      required: [...FINDING.required, 'lenses'] } },
+    clearsBar: { type: 'boolean' },
+    verdict: { type: 'string' },
+  }, 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 }
+)

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

@@ -0,0 +1,67 @@
+# Skill skeletons
+
+Two skeletons — pick by layer. Both stay lean; push detail into one-level-deep bundled files.
+
+Frontmatter fields used in this toolkit: `name`, `description` (required-quality), `user-invocable`, `argument-hint` (optional), `allowed-tools`.
+
+---
+
+## Reference skill (descriptive — knowledge)
+
+No numbered procedures. Principles + pointers + heuristics.
+
+```markdown
+---
+name: <aspect-noun>          # e.g. navigation — NO platform prefix
+description: <what it covers + when to reach for it + trigger words. Say "iOS/SwiftUI" so the router can disambiguate.>
+user-invocable: true
+allowed-tools: Read, Grep, Glob, Bash, Edit, Write
+---
+
+# <name> — <short title>
+
+> **Layer:** reference (knowledge)
+> **Use when:** <trigger>   **Hand off to:** <sibling skill>
+
+## Scope
+In / out, 1–2 lines.
+
+## Invariants            <!-- non-negotiables + the why -->
+## Conventions & golden paths   <!-- point to canonical files; don't paste code -->
+## Decision rules        <!-- if X do A; when unsure, ask/verify -->
+## Pitfalls              <!-- known traps -->
+## Escape hatches        <!-- when this doesn't apply → which skill -->
+```
+
+---
+
+## Workflow skill (imperative — action)
+
+Has a numbered procedure, but only for the deterministic/irreversible spine. Cite reference skills for judgment. Always include a verification gate.
+
+```markdown
+---
+name: <verb-phrase>         # e.g. branch-and-pr
+description: <what it does + when to run it + trigger words (iOS/SwiftUI).>
+user-invocable: true
+argument-hint: [<step> | ...]
+allowed-tools: Bash, Read
+---
+
+# <name> — <short title>
+
+> **Layer:** workflow (action)
+> **Use when:** <trigger>   **Don't use when:** <hand off>
+
+## Scope
+In / out, 1–2 lines.
+
+## Invariants            <!-- hard rules / guardrails -->
+## Conventions & golden paths   <!-- base branch, auth, canonical commands -->
+## Decision rules        <!-- branch when…, escalate when… -->
+## Procedures            <!-- IMPERATIVE: only deterministic/irreversible steps -->
+1. ...
+## Verification          <!-- IMPERATIVE: prove it worked (build/run/test) -->
+## Pitfalls
+## Escape hatches
+```

package/pipeline/skills/skills-index.md

@@ -3,11 +3,12 @@
 > Auto-generated by `pipeline/scripts/build-skills-index.mjs`  -  do not hand-edit.
 > Regenerate with `node pipeline/scripts/build-skills-index.mjs`.
 
-**223 skills** across 5 groups.
+**228 skills** across 5 groups.
 
 | Group | Name | Platform | Description |
 |-------|------|----------|-------------|
 | external | `accessibility-compliance-accessibility-audit` |  -  | You are an accessibility expert specializing in WCAG compliance, inclusive design, and assistive technology compatibility. Conduct audits, i |
+| external | `agent-introspection-debugging` |  -  | \| |
 | external | `agentflow` |  -  | Orchestrate autonomous AI development pipelines through your Kanban board (Asana, GitHub Projects, Linear). Manages multi-worker Claude Code |
 | external | `alarmkit` |  -  | Implement AlarmKit alarms and countdown timers for iOS and iPadOS with Lock Screen, Dynamic Island, StandBy, and paired Apple Watch system U |
 | external | `android_ui_verification` |  -  | Automated end-to-end UI testing and verification on an Android Emulator using ADB. |
@@ -28,6 +29,7 @@
 | external | `authentication` |  -  | Implement iOS authentication flows with AuthenticationServices and LocalAuthentication. Use when building Sign in with Apple, passkey/WebAut |
 | external | `avkit` |  -  | Create media playback experiences using AVKit. Use when adding video players with AVPlayerViewController, enabling Picture-in-Picture, routi |
 | external | `background-processing` |  -  | Schedule and execute background work on iOS using BGTaskScheduler. Use when registering BGAppRefreshTask for short background fetches, BGPro |
+| external | `backlog` |  -  | The engineering backlog registry for deferred-but-approved work in this codebase. Every job the user defers ('defer it', 'add it to the list |
 | external | `callkit-voip` |  -  | Implement VoIP calling with CallKit and PushKit. Use when building incoming/outgoing call flows, registering for VoIP push notifications, co |
 | external | `ci-cd-pipelines` |  -  | CI/CD pipelines: GitHub Actions workflows, Docker multi-stage builds, environment management, secret management, deployment strategies |
 | external | `clean-code` |  -  | This skill embodies the principles of \"Clean Code\" by Robert C. Martin (Uncle Bob). Use it to transform \"code that works\" into \"code th |
@@ -43,6 +45,7 @@
 | external | `core-motion` |  -  | Access Core Motion accelerometer, gyroscope, magnetometer, device-motion, pedometer, activity-recognition, altitude, headphone motion, batch |
 | external | `core-nfc` |  -  | Read and write NFC tags using CoreNFC. Use when scanning NDEF tags, reading ISO7816/ISO15693/FeliCa/MIFARE tags, writing NDEF messages, hand |
 | external | `coreml` |  -  | Integrate Core ML models in iOS apps for on-device machine learning inference. Covers model loading (.mlmodel, .mlpackage, .mlmodelc), predi |
+| external | `council` |  -  | \| |
 | external | `cryptokit` |  -  | Use Apple CryptoKit for Swift cryptographic primitives. Use when hashing with SHA-2 or SHA-3, generating HMACs, encrypting with AES-GCM or C |
 | external | `css-modern` |  -  | Modern CSS: container queries, nesting, @layer, Grid/Flexbox patterns, custom properties, animations, and transitions |
 | external | `database-patterns` |  -  | Database patterns: SQL best practices (PostgreSQL), indexing, query optimization, migrations, schema design, ORMs (SQLAlchemy, Prisma, Drizz |
@@ -181,7 +184,9 @@
 | external | `rest-api-design` |  -  | REST API design: HTTP methods, status codes, pagination, versioning, rate limiting, caching headers, OpenAPI documentation |
 | external | `retrofit-networking` |  -  | Build networking layers on Android with Retrofit, OkHttp, and Kotlin Coroutines. Covers suspend functions in API interfaces, OkHttp intercep |
 | external | `room-database` |  -  | Implement Room database persistence on Android with @Entity, @Dao, @Database, Flow-based reactive queries, TypeConverters for complex types, |
+| external | `search-first` |  -  | \| |
 | external | `shareplay-activities` |  -  | Build shared real-time experiences using GroupActivities and SharePlay. Use when implementing shared media playback, collaborative app featu |
+| external | `skill-creator` |  -  | Author and refine skills for a plugin/toolkit efficiently. Use when creating a new skill, trimming or splitting an existing one, writing a s |
 | external | `speech-recognition` |  -  | Transcribe speech to text using Apple's Speech framework. Use when implementing live microphone transcription with AVAudioEngine, recognizin |
 | external | `spm-build-analysis` |  -  | Analyze Swift Package Manager dependencies, package plugins, module variants, and CI-oriented build overhead that slow Xcode builds. Use whe |
 | external | `storekit` |  -  | Implement, review, or improve in-app purchases and subscriptions using StoreKit 2. Use when building paywalls with SubscriptionStoreView or  |