@mmerterden/multi-agent-pipeline 11.1.0 → 11.3.0

package/pipeline/skills/shared/core/multi-agent-refactor/SKILL.md

@@ -1,57 +1,99 @@
 ---
 name: multi-agent-refactor
 language: en
-description: "Analyse the project, score it, draft an improvement plan, take approval, develop, then ask whether to sync."
+description: "Analyse the project: extract adapted best-practices, hunt real bugs + improvement areas, check upstream drift of derived skills, draft one plan, take approval, develop, then ask whether to sync."
 user-invocable: true
-argument-hint: 'security | tests | performance | docs | ci | deps'
+argument-hint: 'bugs | best-practices | drift | security | tests | performance | docs | ci | deps'
 ---
 
 # Multi-Agent Refactor
 
-**One command. Analyze -> Score -> Plan -> Approval -> Develop -> Sync.**
+**One command. Best-practices + Bug hunt + Upstream drift -> Score -> Plan -> Approval -> Develop -> Sync.**
 
-Analyzes the current project in depth, scores it across 10 categories, plans all improvements, takes approval from the user, applies them, and asks about sync when done.
+Deep-analyses the current project, extracts the global best-practices worth adopting (adapted to our stack), hunts real bugs and improvement areas, checks whether any skills we derived from an upstream source have drifted, scores everything, drafts a single prioritized plan, takes approval, applies the approved items, and asks about sync when done.
 
-**Input**: $ARGUMENTS (optional  -  the area to focus on: "security", "performance", "tests", etc.)
+**Input**: $ARGUMENTS (optional  -  area to focus on: "security", "performance", "tests", "bugs", "best-practices", "drift", etc.)
 
 ## Flow
 
 ```
-Step 0: RESEARCH   Search competing projects on GitHub + Reddit, collect good ideas
-Step 1: SCAN       Scan the project structure (files, LOC, dependencies, CI, tests)
-Step 2: ANALYZE    In-depth analysis across 10 categories
-Step 3: SCORE      Each category out of 10, total /100
-Step 4: PLAN       List all improvements + competitor ideas in priority order
-Step 5: ASK        "Shall I start developing?"  -  take approval from the user
-Step 6: IMPLEMENT  Apply approved improvements in order (lint, test, commit)
-Step 7: VERIFY     Confirm all tests + lint pass
-Step 8: ASK SYNC   "Shall I run multi-agent-sync?"  -  take approval from the user
+Step 0:  BEST-PRACTICES  Research the field, extract the best approaches, ADAPT them to our stack -> plan band A
+Step 0b: DRIFT           Check upstream-derived skills for updates we have not pulled -> plan band D
+Step 1:  SCAN            Scan the project structure (files, LOC, dependencies, CI, tests)
+Step 2:  ANALYZE         10 categories + an explicit BUG HUNT (real defects, not just scores) -> plan bands B, C
+Step 3:  SCORE           Each category out of 10, total /100
+Step 4:  PLAN            Merge bands A (best-practice) + B (bugs) + C (improvements) + D (drift), priority-ordered
+Step 5:  ASK             "Shall I start developing?"  -  take approval
+Step 6:  IMPLEMENT       Apply approved items in order (lint, test, commit)
+Step 7:  VERIFY          Confirm all tests + lint pass
+Step 8:  ASK SYNC        "Shall I run multi-agent-sync?"  -  take approval
 ```
 
-## Step 0: RESEARCH  -  Competitor Analysis
+Plan bands (all four feed the single Step 4 table):
+- **A - Best-practice**: the best field approaches, adapted so they actually fit this repo.
+- **B - Bug**: real defects found in the code (correctness, security, data-loss, crashes).
+- **C - Improvement**: quality/perf/DX gaps surfaced by the 10-category analysis.
+- **D - Drift**: upstream updates to skills we derived from an external source.
 
-Before starting development, research similar projects:
+## Step 0: BEST-PRACTICES  -  research the field, adapt to us
 
-1. **GitHub Search**: `multi-agent pipeline AI development` + `Claude Code pipeline` + `AI coding agent`
-   - Find repos with stars:>10
-   - Read their READMEs
-   - Extract unique features
-2. **Reddit Search**: multi-agent discussions in `r/ClaudeAI`, `r/ChatGPT`, `r/LocalLLaMA`
-3. **For each competitor, record**:
-   - Unique features we do NOT have
-   - Ideas worth adopting
-   - Things they do better than us
-   - Things we do better than them
-4. **Include in the plan**: Add high-impact + low-effort ideas to the PLAN step (P1 priority)
+Do not copy features blindly. The goal is the best *approaches*, reshaped so they are applicable to THIS project's stack, size, and constraints.
+
+1. **Identify the domain** (read README + package/build manifests): kind of project, stack, users.
+2. **Research the best-in-class** for that exact domain:
+   - **GitHub**: search the domain terms + `stars:>50`; read the top repos' READMEs, architecture docs, CI configs, test layout.
+   - **X / Twitter**: search the domain terms + "best practices" / "we switched to" / "lesson learned"; capture what practitioners recommend right now (WebFetch/WebSearch on `x.com` / `twitter.com` threads).
+   - **Reddit**: relevant subreddits for real-world pain points and adopted patterns.
+   - **Web**: "<domain> best practices <current-year>", official style guides, platform guidance.
+3. **For each candidate approach, record**: what it is + source, the concrete benefit, the **adaptation** (exactly how it looks in OUR repo: which file/dir/script and what changes), effort (L/M/H), impact (L/M/H/Critical).
+4. **Discard** approaches that do not fit our stack/scale/constraints  -  and say WHY.
+
+Output (plan band A):
+```
+| Source | Approach | Adaptation to our repo | Effort | Impact | In plan? |
+|--------|----------|------------------------|--------|--------|----------|
+| <repo> | <what>   | <concrete change here> | Low    | High   | Yes (P1) |
+| <repo> | <what>   | does not fit: <reason> | -      | -      | No       |
+```
+Roll the high-impact + low/med-effort survivors into the Step 4 plan as band-A items.
+
+## Step 0b: DRIFT  -  upstream-derived skill check
+
+Some skills/components in this project (or in the marketplace plugins it ships) were derived from an upstream source. Upstream keeps evolving  -  it fixes bugs and adds features. This step detects upstream drift so we can decide whether to pull the improvements back.
+
+The upstream mapping is **configuration, never hardcoded** (it can reference private sources, so it stays out of the shipped skill). Read it from `~/.claude/multi-agent-preferences.json` at `global.derivedSkillSources` (an array). Each entry:
+
+```jsonc
+{
+  "label": "<human name for this derivation>",
+  "localPath": "<repo-relative dir where our derived copy lives>",
+  "upstreamMarketplace": "<installed marketplace name>",   // resolved under ~/.claude/plugins/cache/<marketplace>/
+  "upstreamPlugin": "<plugin name>",
+  "upstreamSkills": ["<skill-a>", "<skill-b>"],            // the upstream skills we took
+  "derivedFromVersion": "<x.y.z>",                         // the version we last synced from
+  "upstreamRepoUrl": "<optional https url>"                // used only if the marketplace is not installed locally
+}
+```
+
+Procedure:
+1. If `global.derivedSkillSources` is missing or empty -> **skip** this step and report "no derived-skill sources configured". Never invent a source.
+2. For each entry, resolve the current upstream version:
+   - **Preferred**: read the newest installed version under `~/.claude/plugins/cache/<upstreamMarketplace>/<upstreamPlugin>/*/` (its `.claude-plugin/plugin.json` `version`), plus that version's `CHANGELOG.md`.
+   - **Fallback**: if the marketplace is not installed locally and `upstreamRepoUrl` is set, `WebFetch` the upstream `plugin.json` + `CHANGELOG.md`.
+   - If neither is reachable, record "upstream unreachable" and move on (do not fail the run).
+3. Compare the resolved upstream version to `derivedFromVersion`:
+   - equal -> "up to date" (no drift)
+   - newer -> **drift**: read the CHANGELOG entries between the two versions, and diff each `upstreamSkills` SKILL.md (+ templates) against our `localPath` copy. Summarize what changed.
+4. Emit the drift table (plan band D):
 
-Output format:
 ```
-| Source | Idea | Effort | Impact | Include in plan? |
-|--------|------|--------|--------|------------------|
-| ralph-loop | Symlink distribution | Low | High | Yes |
-| atelier | Persistent Brain | High | Very high | No (roadmap) |
+| Derivation | Our copy (localPath) | Derived-from | Upstream now | Drift | What changed upstream |
+|------------|----------------------|--------------|--------------|-------|-----------------------|
+| <label>    | <path>               | 0.2.1        | 0.3.0        | YES   | <changelog + diff summary> |
 ```
 
+5. For each drifted entry, add a band-D plan item: "port upstream <plugin> <version> changes into <localPath>". Do not auto-apply  -  it goes through Step 5 approval; after porting, bump the entry's `derivedFromVersion`.
+
 ## Step 1: SCAN
 
 ```
@@ -65,7 +107,9 @@ Output format:
 - Git status: branch count, last commit date, tags
 ```
 
-## Step 2: ANALYZE  -  10 Categories
+## Step 2: ANALYZE  -  10 categories + BUG HUNT
+
+### 2a. 10 categories (quality lens)
 
 | # | Category | What is checked |
 |---|----------|-----------------|
@@ -80,6 +124,23 @@ Output format:
 | 9 | **Dependency Management** | Outdated deps, vulnerability scan, lockfile, version pinning |
 | 10 | **DevEx** | Onboarding time, script ergonomics, error messages, debug tooling |
 
+### 2b. BUG HUNT (real defects, not scores)
+
+Category scores measure quality; they do not find the bug that ships. Run an explicit defect hunt IN ADDITION to the scoring:
+
+- Dispatch focused review agents over the highest-risk surfaces: recently changed files, error/edge-path handling, concurrency, external input parsing, resource cleanup, off-by-one boundaries.
+- For each candidate defect, record: **file:line**, the concrete failure scenario (inputs/state -> wrong output/crash), and severity.
+- **Verify before reporting**: only list a bug you can trace to a real failure path; drop the plausible-but-unprovable ones.
+
+Output (plan band B) - every confirmed defect becomes a P0/P1 item:
+```
+| # | Severity | File:line | Defect | Failure scenario |
+|---|----------|-----------|--------|------------------|
+| 1 | Blocking | src/x.ts:42 | unchecked nil deref | empty response -> crash |
+```
+
+Improvement areas surfaced by 2a that are not outright bugs become band-C items.
+
 ## Step 3: SCORE
 
 Each category is scored out of 10. Output format:
@@ -103,45 +164,46 @@ Each category is scored out of 10. Output format:
 +---------------------+-------+
 ```
 
-## Step 4: PLAN
+## Step 4: PLAN  -  one merged, prioritized table
 
-List all the improvements found:
+Merge all four bands into a single plan. Tag each row with its band (A best-practice / B bug / C improvement / D drift).
 
 ```
-| # | Priority | Category | Improvement | Impact |
-|---|----------|----------|-------------|--------|
-| 1 | P0 | Security | Remove hardcoded API key | Critical |
-| 2 | P0 | Testing | Missing edge case tests | High |
-| 3 | P1 | CI/CD | Add Node matrix | Medium |
-| 4 | P1 | Documentation | Functions missing JSDoc | Medium |
-| 5 | P2 | DevEx | npm script naming | Low |
+| # | Priority | Band | Category | Item | Impact |
+|---|----------|------|----------|------|--------|
+| 1 | P0 | B | Security | Remove hardcoded API key (src/x:12) | Critical |
+| 2 | P0 | B | Testing | Fix nil-deref on empty response (src/y:42) | High |
+| 3 | P1 | A | CI/CD | Adopt matrix build (adapt: .github/workflows/ci.yml) | Medium |
+| 4 | P1 | D | Skills | Port upstream <plugin> 0.3.0 fixes into <localPath> | Medium |
+| 5 | P2 | C | DevEx | Rename npm scripts for consistency | Low |
 ```
 
 Priority levels:
 - **P0**: Bug, security hole, broken functionality  -  fix without fail
-- **P1**: Clear quality improvement  -  should be done
+- **P1**: Clear quality improvement or high-value adopted best-practice / drift port  -  should be done
 - **P2**: Nice-to-have  -  if there is time
 
-## Step 5: ASK  -  Approval from the User
+## Step 5: ASK  -  approval from the user
 
 After showing the plan, ask:
 
-> "I found X improvements (P0: N, P1: M, P2: K). Shall I start developing?"
+> "I found X items (P0: N, P1: M, P2: K) across bugs, best-practices, improvements, and upstream drift. Shall I start developing?"
 
 Options:
 - "Yes, do all of them"
 - "Do only the P0 ones"
 - "Do only P0 + P1"
+- "Only the bugs (band B)"
 - (the user can make a specific selection)
 
 **NEVER start developing without approval.**
 
 ## Step 6: IMPLEMENT
 
-Apply approved improvements in order:
+Apply approved items in order:
 
-1. For each improvement:
-   - Make the change
+1. For each item:
+   - Make the change (for band D, port the upstream diff into `localPath`, then bump that entry's `derivedFromVersion`)
    - Run the relevant tests
    - If successful, move to the next
    - If it fails, revert and notify the user
@@ -167,7 +229,7 @@ echo "Test: PASS/FAIL (X/Y passed)"
 
 ## Step 8: ASK SYNC
 
-After all improvements are applied, ask:
+After all approved items are applied, ask:
 
 > "Development complete. Shall I run multi-agent-sync?"
 
@@ -178,14 +240,17 @@ Options:
 
 ## Focus filter
 
-If $ARGUMENTS is specified, focus on that category only:
+If $ARGUMENTS is specified, focus on that band/category only:
 
 | Input | Focus |
 |-------|-------|
+| `bugs` | Bug hunt only (band B) |
+| `best-practices` | Field research + adapted plan only (band A) |
+| `drift` | Upstream derived-skill drift only (band D) |
 | `security` | Security analysis only |
 | `tests` | Test coverage and quality only |
 | `performance` | Performance optimization only |
 | `docs` | Documentation only |
 | `ci` | CI/CD pipeline only |
 | `deps` | Dependency updates only |
-| (empty) | All 10 categories (default) |
+| (empty) | Everything (default) |

package/pipeline/skills/shared/core/multi-agent-sync/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-sync
 language: en
-description: "One-shot sync of the entire multi-agent ecosystem: Claude Code, Copilot CLI, pipeline repo, website, and remote-control."
+description: "One-shot sync of the entire multi-agent ecosystem: Claude Code, Copilot CLI, pipeline repo, and website."
 user-invocable: true
 argument-hint: 'release | "change description"'
 ---
@@ -10,35 +10,30 @@ argument-hint: 'release | "change description"'
 
 **Single command. Full ecosystem sync. No argument required.**
 
-When invoked, it synchronizes all 6 targets in order. It detects what changed, updates only the stale ones, and reports the result.
+When invoked, it synchronizes all targets in order. It detects what changed, updates only the stale ones, and reports the result.
 
 **Input**: $ARGUMENTS (optional  -  `release` or a change description to apply to all targets)
 
-## Targets (always all 6)
+## Targets
 
 | # | Target | Path | Direction |
 |---|-------|-----|-----|
-| 0 | Figma source (opt-in) | `prefs.global.figmaSource.path` -> `pipeline/skills/figma-ios/` + `figma-common/` | <- upstream |
 | 1 | Claude Code (source of truth) | `~/.claude/commands/multi-agent.md` + `~/.claude/commands/multi-agent/` + `~/.claude/agents/` + `~/.claude/scripts/` | source |
 | 2 | Copilot CLI | `~/.copilot/copilot-instructions.md` + `~/.copilot/skills/` | <- from Claude |
 | 3 | multi-agent-pipeline repo | `~/multi-agent-pipeline/pipeline/` | <- from Claude (genericized) |
 | 4 | Website | `{owner}/{website-host}` | <- version + features |
-| 5 | Remote Control | `{owner}/remote-control` | <- pipeline references |
 
 ## Default Behavior (no argument)
 
 Run all steps automatically:
 
 ```
-Step 0: FIGMA_SYNC  (opt-in) pipeline/scripts/sync-figma-source.sh
-                    -- incremental pull from upstream if figmaSource.path is set
 Step 1: DETECT      Compare timestamps, find stale targets
-Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 37 sub-command skills)
+Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 36 sub-command skills)
 Step 3: REPO        Claude Code -> pipeline repo (genericized, personal data scrub)
 Step 4: WEBSITE     Version + phase/model counts -> {website-host} (i18n + projects.ts)
-Step 5: REMOTE      Pipeline references -> remote-control README
-Step 6: Commit      Commit + push all changed repos
-Step 7: Report      Summary: synced targets, changed files, deploy status
+Step 5: Commit      Commit + push all changed repos
+Step 6: Report      Summary: synced targets, changed files, deploy status
 ```
 
 If nothing is stale -> report "All targets up to date" and stop.
@@ -118,22 +113,6 @@ git push origin main  # Vercel auto-deploy
 ```
 
 
-## Remote Control Sync (Step 5)
-
-```bash
-REMOTE_DIR="$HOME/remote-control"
-[ ! -d "$REMOTE_DIR" ] && gh repo clone {owner}/remote-control "$REMOTE_DIR"
-cd "$REMOTE_DIR" && git pull origin main
-```
-
-| File | To sync |
-|-------|--------------|
-| `README.md` | Pipeline feature description |
-| `src/index.ts` | Help text / chip labels (if any) |
-
-Update only if the pipeline's public-facing features changed.
-
-
 ## Release Flow
 
 When invoked with the `release` argument:
@@ -146,9 +125,8 @@ When invoked with the `release` argument:
 5. Commit + TAG  git commit + git tag v{VERSION}
 6. PUSH          git push --tags -> release.yml auto-publish
 7. WEBSITE       Version + features -> {website-host}
-8. REMOTE        Update remote-control references
-9. COPILOT       Copilot CLI instructions + skills sync
-10. Report        Summary: version, touched repos, deploy status
+8. COPILOT       Copilot CLI instructions + skills sync
+9. Report        Summary: version, touched repos, deploy status
 ```
 
 

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/compose-components/SKILL.md

@@ -251,27 +251,27 @@ fun AppTheme(
 
 ```kotlin
 private val LightColorScheme = lightColorScheme(
-    primary = Color(0xFFE31837),
+    primary = Color(0xFF6750A4),
     onPrimary = Color.White,
-    primaryContainer = Color(0xFFFFDAD6),
-    onPrimaryContainer = Color(0xFF410002),
-    secondary = Color(0xFF775653),
+    primaryContainer = Color(0xFFEADDFF),
+    onPrimaryContainer = Color(0xFF21005D),
+    secondary = Color(0xFF625B71),
     onSecondary = Color.White,
-    secondaryContainer = Color(0xFFFFDAD6),
-    onSecondaryContainer = Color(0xFF2C1513),
-    surface = Color(0xFFFFFBFF),
-    onSurface = Color(0xFF201A19),
+    secondaryContainer = Color(0xFFE8DEF8),
+    onSecondaryContainer = Color(0xFF1D192B),
+    surface = Color(0xFFFFFBFE),
+    onSurface = Color(0xFF1C1B1F),
     error = Color(0xFFBA1A1A),
     onError = Color.White,
 )
 
 private val DarkColorScheme = darkColorScheme(
-    primary = Color(0xFFFFB4AB),
-    onPrimary = Color(0xFF690005),
-    primaryContainer = Color(0xFF93000A),
-    onPrimaryContainer = Color(0xFFFFDAD6),
-    surface = Color(0xFF201A19),
-    onSurface = Color(0xFFEDE0DE),
+    primary = Color(0xFFD0BCFF),
+    onPrimary = Color(0xFF381E72),
+    primaryContainer = Color(0xFF4F378B),
+    onPrimaryContainer = Color(0xFFEADDFF),
+    surface = Color(0xFF1C1B1F),
+    onSurface = Color(0xFFE6E1E5),
 )
 ```
 

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).