@mmerterden/multi-agent-pipeline 12.6.0 → 12.8.0

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-analysis
 language: en
-description: "Standalone feature-spec analysis (v3 template). Platform-agnostic concept layer with repo-driven convention extraction and per-platform Pass B render. 23 main sections + 3 footer in Full mode; 7 sections in Lite mode (auto for small features). Collects Figma / Swagger / Confluence / Jira / Standards / Firebase / repo inputs, then stops. Does not chain into dev or create branches."
+description: "Standalone feature-spec analysis (v3 template). Platform-agnostic concept layer with repo-driven convention extraction and per-platform Pass B render. 23 main sections + 3 footer in Full mode; 7 sections in Lite mode (auto for small features). Collects Figma / Swagger / Confluence / Jira / Standards / Firebase / repo inputs, then stops. Does not chain into dev or create branches. Use when a feature needs a written specification before any code, from Figma, Swagger, Confluence, Jira or repo inputs."
 user-invocable: true
 argument-hint: "[\"<analysis-name>\"] [--lite | --full] [--no-cache] [--preview-conventions]"
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-analysis-resolve
 language: en
-description: "Resolve the Section 20 Risks and Open Questions of an analysis v3 document one row at a time. Proposes up to 3 source-labeled answer candidates per row (from evidence / from repo / AI reasoned), merges the chosen answer into the target body section, and updates the doc in place with a changelog bump. Companion to multi-agent-analysis."
+description: "Resolve the Section 20 Risks and Open Questions of an analysis v3 document one row at a time. Proposes up to 3 source-labeled answer candidates per row (from evidence / from repo / AI reasoned), merges the chosen answer into the target body section, and updates the doc in place with a changelog bump. Companion to multi-agent-analysis. Use when an analysis document's open questions and risks need answering row by row before development starts."
 user-invocable: true
 argument-hint: "[path/to/analysis/<feature>-<platform>.md] [--autonomous]"
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-autopilot
 language: en
-description: "Launch any task in autopilot mode: skips every confirmation, runs end-to-end autonomously."
+description: "Launch any task in autopilot mode: skips every confirmation, runs end-to-end autonomously. Use when a task should run end to end with no confirmation prompts."
 user-invocable: true
 argument-hint: '"task"  -  issue URL, Jira ID, free-text, or #id (for resume)'
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-build-optimize
 language: en
-description: "Wrapper that dispatches to xcode-build-orchestrator on iOS repos. Benchmarks the current Xcode build, runs compilation / project / SPM analyzers, produces a recommend-first optimization plan in .build-benchmark/, and re-benchmarks after the developer approves changes. Fails fast on non-iOS stacks."
+description: "Wrapper that dispatches to xcode-build-orchestrator on iOS repos. Benchmarks the current Xcode build, runs compilation / project / SPM analyzers, produces a recommend-first optimization plan in .build-benchmark/, and re-benchmarks after the developer approves changes. Fails fast on non-iOS stacks. Use when an iOS build is slow and needs measuring before anything is changed."
 user-invocable: true
 argument-hint: "(none - operates on current repo)"
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-create-jira
 language: en
-description: "Create a standards-compliant Jira issue (Task / Bug / Story): asks the type, mines project conventions, drafts from a standard template with auto-sizing sections, full preview + explicit approval before create."
+description: "Create a standards-compliant Jira issue (Task / Bug / Story): asks the type, mines project conventions, drafts from a standard template with auto-sizing sections, full preview + explicit approval before create. Use when a Jira Task, Bug or Story has to be written to the project's own conventions."
 user-invocable: true
 argument-hint: "[\"<free-text description>\"] [figma-url] [swagger-url]  -  all optional, asked interactively when missing"
 ---

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

@@ -24,7 +24,7 @@ The scope decides which **inventory targets** (Phase 0 step 5) the run must audi
 | screen name | `boarding-pass` | Every target whose `screen` matches (case/separator-insensitive) |
 | `screen@variant` | `boarding-pass@expired` | One target |
 | target id | `scenario-case:boardingpassoutcome-expired` | One target, exactly |
-| Figma URL(s) | `https://figma.com/design/…?node-id=1-2` | Only the frames those URLs name |
+| Figma URL(s) | `https://figma.com/design/...?node-id=1-2` | Only the frames those URLs name |
 | `--resume` | `--resume` | The unaudited remainder of the most recent run for this repo + module |
 | combinations | `seat-map summary@semi-success` | Union of the above, space- or newline-separated |
 

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-dev
 language: en
-description: "Fast development mode: Init → Dev (Opus) → Test → Commit → Report. Analysis, planning, and review phases are skipped."
+description: "Fast development mode: Init → Dev (Opus) → Test → Commit → Report. Analysis, planning, and review phases are skipped. Use when the work is already scoped and only development, test and commit are needed."
 user-invocable: true
 argument-hint: '"task" [autopilot]  -  issue URL, Jira ID, or free-text + optional autopilot'
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-dev-autopilot
 language: en
-description: "Fastest mode: Dev (Opus) plus Autopilot. Init → Dev → Commit → Report with zero confirmations."
+description: "Fastest mode: Dev (Opus) plus Autopilot. Init → Dev → Commit → Report with zero confirmations. Use when a change is well understood and should go from start to commit with no questions asked."
 user-invocable: true
 argument-hint: '"task"  -  issue URL, Jira ID, or free-text'
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-dev-local
 language: en
-description: "Fast mode + local  -  Init → Dev(Opus) → Commit → Report, no worktree."
+description: "Fast mode + local  -  Init → Dev(Opus) → Commit → Report, no worktree. Use when a change should be developed on the current branch without creating a worktree."
 user-invocable: true
 ---
 

package/pipeline/skills/shared/core/multi-agent-dev-local-autopilot/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-dev-local-autopilot
 language: en
-description: "Fastest + local  -  Dev(Opus) + autopilot, no worktree, zero interaction."
+description: "Fastest + local  -  Dev(Opus) + autopilot, no worktree, zero interaction. Use when a change should be developed on the current branch with no worktree and no prompts."
 user-invocable: true
 ---
 

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-diff-explain
 language: en
-description: "Map Phase 4 triage findings to branch diff lines. Read-only post-hoc command, used after review to answer 'which finding lines up with which code change'."
+description: "Map Phase 4 triage findings to branch diff lines. Read-only post-hoc command, used after review to answer 'which finding lines up with which code change'. Use when a review finding has to be traced to the exact lines that caused it."
 user-invocable: true
 argument-hint: "[#task-id | --triage <path> | --state <path>] [--branch <name>] [--base <name>]"
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-finish
 language: en
-description: "Continue already-done LOCAL work through the pipeline tail: Review → Build+Test → Commit/PR → Report (technical analysis + Jira test-scenario comment). No dev phase."
+description: "Continue already-done LOCAL work through the pipeline tail: Review → Build+Test → Commit/PR → Report (technical analysis + Jira test-scenario comment). No dev phase. Use when local work is already done and only review, build, commit and reporting remain."
 user-invocable: true
 ---
 

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-forget
 language: en
-description: "Remove a saved /multi-agent routine (created by /multi-agent:save): deletes its local-only command and its registry entry. Asks which one and confirms."
+description: "Remove a saved /multi-agent routine (created by /multi-agent:save): deletes its local-only command and its registry entry. Asks which one and confirms. Use when a saved routine is no longer wanted and should be removed."
 user-invocable: true
 argument-hint: "[name]"
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-garbage-collect
 language: en
-description: "Sweep leftover /tmp scratch (picker state, review diffs, channel payloads, analysis drafts) from past runs. Dry-run first; confirms before deleting."
+description: "Sweep leftover /tmp scratch (picker state, review diffs, channel payloads, analysis drafts) from past runs. Dry-run first; confirms before deleting. Use when scratch files from earlier runs need clearing out."
 user-invocable: true
 argument-hint: "[--older-than=<minutes>] [--yes]  -  dry-run unless confirmed"
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-help
 language: en
-description: "Multi-agent pipeline usage guide  -  renders in EN or TR per prefs.global.outputLanguage (falls back to promptLanguage for backward compatibility)."
+description: "Multi-agent pipeline usage guide  -  renders in EN or TR per prefs.global.outputLanguage (falls back to promptLanguage for backward compatibility). Use when asked what the pipeline can do, which mode to pick, or what a command means."
 user-invocable: true
 argument-hint: "[topic]  -  optional; calling with no argument prints the full guide in the user's language"
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-issue
 language: en
-description: "List unassigned GitHub issues, pick one, auto-assign, and launch the multi-agent pipeline."
+description: "List unassigned GitHub issues, pick one, auto-assign, and launch the multi-agent pipeline. Use when a GitHub issue should be picked up and started without knowing its number in advance."
 user-invocable: true
 argument-hint: "[autopilot]  -  optional: run the pipeline without confirmations"
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-jira
 language: en
-description: "List open Jira issues, pick one, and launch the multi-agent pipeline."
+description: "List open Jira issues, pick one, and launch the multi-agent pipeline. Use when a Jira issue should be picked up and started without knowing its key in advance."
 user-invocable: true
 argument-hint: "[autopilot]  -  optional: run the pipeline without confirmations"
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-kill
 language: en
-description: "Stop the given task, then remove its worktree and branch. Asks for confirmation."
+description: "Stop the given task, then remove its worktree and branch. Asks for confirmation. Use when a running or stuck task should be stopped and its worktree removed."
 user-invocable: true
 argument-hint: "#id  -  task ID to delete (e.g. #2)"
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-language
 language: en
-description: "Toggle outputLanguage (assistant explanations). promptLanguage is fixed to English. External payloads stay English."
+description: "Toggle outputLanguage (assistant explanations). promptLanguage is fixed to English. External payloads stay English. Use when the assistant should explain itself in a different language."
 user-invocable: true
 argument-hint: "[en|tr]  -  sets outputLanguage; omit for interactive picker; use 'output en|tr' for explicit form"
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-local
 language: en
-description: "Full pipeline in local mode  -  no worktree, runs directly on the current branch."
+description: "Full pipeline in local mode  -  no worktree, runs directly on the current branch. Use when the full pipeline should run on the current branch without creating a worktree."
 user-invocable: true
 ---
 

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-local-autopilot
 language: en
-description: "Full pipeline + local + autopilot  -  no worktree, no confirmations, all 8 phases run end-to-end on the current branch."
+description: "Full pipeline + local + autopilot  -  no worktree, no confirmations, all 8 phases run end-to-end on the current branch. Use when the full pipeline should run on the current branch with no worktree and no prompts."
 user-invocable: true
 argument-hint: '"task"  -  issue URL, Jira ID, free-text, or #id (for resume)'
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-log
 language: en
-description: "Show the agent-log.md for the given task. With no ID, shows the most recent task."
+description: "Show the agent-log.md for the given task. With no ID, shows the most recent task. Use when asked what a task did, or to read its log."
 user-invocable: true
 argument-hint: "[#id]  -  optional: task ID (e.g. #3). If omitted, the most recent task is used."
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-manual-test
 language: en
-description: "Switch to the active task's branch and prepare it for manual testing in Xcode. Phase 5 standalone (the UI Bug Hunter lives at multi-agent-test)."
+description: "Switch to the active task's branch and prepare it for manual testing in Xcode. Phase 5 standalone (the UI Bug Hunter lives at multi-agent-test). Use when a finished change needs trying by hand on a device or simulator."
 user-invocable: true
 argument-hint: "[#id]  -  optional: task ID. Defaults to the latest task if omitted"
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-prune-logs
 language: en
-description: "Delete per-task project logs under ~/.claude/logs/multi-agent (filter by age/project/task). Audit trail + metrics are preserved. Dry-run first; confirms before deleting."
+description: "Delete per-task project logs under ~/.claude/logs/multi-agent (filter by age/project/task). Audit trail + metrics are preserved. Dry-run first; confirms before deleting. Use when task logs have built up and need trimming by age, project or task."
 user-invocable: true
 argument-hint: "[--older-than=<days>] [--project=<name>] [--task=<id>] [--yes]"
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-purge
 language: en
-description: "⚠️ Wipes every worktree, branch, log, and state file. Irreversible; asks for double confirmation."
+description: "⚠️ Wipes every worktree, branch, log, and state file. Irreversible; asks for double confirmation. Use when every worktree, branch, log and state file should be wiped and the pipeline reset."
 user-invocable: true
 ---
 

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-refactor
 language: en
-description: "Analyse the project: extract adapted best-practices, hunt real bugs + improvement areas, check upstream drift of derived skills, research the companion dev-toolkit MCP server against current MCP practice, draft one 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, research the companion dev-toolkit MCP server against current MCP practice, draft one plan, take approval, develop, then ask whether to sync. Use when asked to review a project for bugs, gaps or improvements, or to check whether derived skills have drifted from upstream."
 user-invocable: true
 argument-hint: 'bugs | best-practices | drift | dev-toolkit | security | tests | performance | docs | ci | deps'
 ---
@@ -73,19 +73,27 @@ The upstream mapping is **configuration, never hardcoded** (it can reference pri
   "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
+  "upstreamVersionSource": "marketplace.json",             // which manifest is authoritative; default marketplace.json
+  "upstreamLocalClone": "<optional path>",                 // working copy of the upstream repo, preferred over the cache
+  "upstreamRepoUrl": "<optional https url>"                // used when neither a clone nor the marketplace is available
 }
 ```
 
+**The plugin cache is a mirror, not the authority.** `~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/` holds only what the last `claude marketplace update` fetched. Treating it as the current upstream version is how this step reported "up to date" while the derivation was four releases behind: the cache sat at 0.2.1 and upstream was at 0.4.1. Resolve in the order below, and never let the cache alone produce an "up to date" verdict.
+
+**Which manifest carries the version** is `upstreamVersionSource`, default `marketplace.json` - that is what a marketplace consumer resolves. Some upstreams keep per-plugin `plugin.json` versions deliberately unused, so reading those records a version nobody ships. One entry here was recorded at 0.7.0 from `plugin.json` while the upstream marketplace said 0.6.0 and its CHANGELOG said plainly that `plugin.json` is not used.
+
 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).
+2. For each entry, resolve the current upstream version, stopping at the first source that answers:
+   - **`upstreamLocalClone`** if set: read `<clone>/.claude-plugin/<upstreamVersionSource>`, and report when the clone is itself behind its remote so a stale working copy is not silently trusted.
+   - **`upstreamRepoUrl`**: read the same manifest over the API (`gh api` / `WebFetch`). A private upstream can 404 for the active account even though it exists; that is unreachable, not "no drift".
+   - **Plugin cache**: last resort. When it is the only source that answered, report **`unverified (cache only)`**, never "up to date", and add a plan item to configure `upstreamLocalClone`.
+   - If nothing 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.
+   - equal, from an authoritative source -> "up to date" (no drift)
+   - equal, from the cache only -> "unverified (cache only)"
+   - newer -> **drift**: read the CHANGELOG entries between the two versions, and diff each `upstreamSkills` SKILL.md (+ templates) against our `localPath` copy. Summarize what changed, ignoring entries that touch only skills outside `upstreamSkills`.
 4. Emit the drift table (plan band D):
 
 ```

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-resume
 language: en
-description: "Resume a stopped or failed task from the phase where it left off."
+description: "Resume a stopped or failed task from the phase where it left off. Use when a task stopped or failed and should carry on from where it left off."
 user-invocable: true
 argument-hint: "[#id]  -  optional: task ID (e.g. #2). If omitted, the most recent paused task is used."
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-review
 language: en
-description: "Run parallel review on a branch diff or a Pull Request: 2 models on Claude Code (Fable + Sonnet), 3 models on Copilot CLI (GPT + Opus + Sonnet). On PR input, posts per-finding inline comments + approve/needs-work. With no input (interactive), lists open GitHub + Bitbucket PRs to multi-select."
+description: "Run parallel review on a branch diff or a Pull Request: 2 models on Claude Code (Fable + Sonnet), 3 models on Copilot CLI (GPT + Opus + Sonnet). On PR input, posts per-finding inline comments + approve/needs-work. With no input (interactive), lists open GitHub + Bitbucket PRs to multi-select. Use when a branch diff or a pull request needs reviewing before it merges."
 user-invocable: true
 argument-hint: "[#N | repo#N | PR-URL | branch]  -  PR by number/URL, repo+number, or branch (GitHub + Bitbucket Server). If omitted: interactive PR picker, else current branch."
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-review-issue
 language: en
-description: "Assess whether a GitHub issue is ready for multi-agent development: fetch it, grade scope / acceptance criteria / repro / design / API / stack readiness, then (after confirm) post the gaps as an issue comment. Read-only on code."
+description: "Assess whether a GitHub issue is ready for multi-agent development: fetch it, grade scope / acceptance criteria / repro / design / API / stack readiness, then (after confirm) post the gaps as an issue comment. Read-only on code. Use when deciding whether a GitHub issue is specified well enough to hand to development."
 user-invocable: true
 argument-hint: "[#N | repo#N | GitHub issue URL]  -  optional; with no argument, pick from open issues"
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-review-jira
 language: en
-description: "Assess whether a Jira issue is ready for multi-agent development: fetch it, grade scope / acceptance criteria / repro / design / API / stack readiness, then (after confirm) post the gaps as a Jira comment. Read-only on code."
+description: "Assess whether a Jira issue is ready for multi-agent development: fetch it, grade scope / acceptance criteria / repro / design / API / stack readiness, then (after confirm) post the gaps as a Jira comment. Read-only on code. Use when deciding whether a Jira issue is specified well enough to hand to development."
 user-invocable: true
 argument-hint: "[JIRA-KEY | Jira URL]  -  optional; with no argument, pick from your open Jira issues"
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-routines
 language: en
-description: "List your saved /multi-agent routines (from /multi-agent:save) with what each one does, rendered in outputLanguage."
+description: "List your saved /multi-agent routines (from /multi-agent:save) with what each one does, rendered in outputLanguage. Use when asked which saved routines exist or what one of them does."
 user-invocable: true
 ---
 

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-save
 language: en
-description: "Save a recurring job as a reusable /multi-agent:<name> command. Reviews the conversation + your CLAUDE.md for candidate routines, you pick one and name it; stored local-only, never synced."
+description: "Save a recurring job as a reusable /multi-agent:<name> command. Reviews the conversation + your CLAUDE.md for candidate routines, you pick one and name it; stored local-only, never synced. Use when a job keeps recurring and should become its own reusable command."
 user-invocable: true
 argument-hint: "[name]"
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-scan
 language: en
-description: Skill security scan: walks local skill directories against a tiered pattern catalog.
+description: "Skill security scan: walks local skill directories against a tiered pattern catalog. Use when local skill directories need checking for unsafe or unexpected content."
 user-invocable: true
 argument-hint: "[--strict] [--target <path>]  -  optional: --strict enables CI failure mode, --target picks a custom directory"
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-search
 language: en
-description: Log search across every agent-log.md with smart ranking and filters. Optional --semantic flag queries the per-repo triage corpus.
+description: "Log search across every agent-log.md with smart ranking and filters. Optional --semantic flag queries the per-repo triage corpus. Use when something has to be found across past task logs."
 user-invocable: true
 argument-hint: "<query> [--project <slug>] [--since 7d|YYYY-MM-DD] [--phase <N>] [--semantic] [--json|--tsv]"
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-setup
 language: en
-description: "First-run setup wizard: keychain token discovery, Git Identity onboarding, and pipeline preparation."
+description: "First-run setup wizard: keychain token discovery, Git Identity onboarding, and pipeline preparation. Use when the pipeline is being set up for the first time, or tokens and git identity need onboarding."
 user-invocable: true
 ---
 

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-stack
 language: en
-description: "Select the active stack for this repo by enabling the matching marketplace plugin(s) in .claude/settings.json (ios/android/mobile/backend/frontend/fullstack/all)."
+description: "Select the active stack for this repo by enabling the matching marketplace plugin(s) in .claude/settings.json (ios/android/mobile/backend/frontend/fullstack/all). Use when a repo's stack changed or the wrong plugins are enabled for it."
 user-invocable: true
 ---
 
@@ -9,7 +9,7 @@ user-invocable: true
 
 Stack skills ship as plugins in the `{owner}/multi-agent-plugins` marketplace. Selecting a stack = **enabling the matching plugin(s)** in the current repo's `.claude/settings.json` `enabledPlugins`. The `ai-common-engineering-toolkit` (accessibility audit, humanizer, Firebase) is always enabled alongside the stack plugin.
 
-This replaces the old `stack-swap.sh` mechanic that physically moved skill directories. No SessionStart hook, no directory shuffling — enablement is declarative, per-repo, and versioned.
+This replaces the old `stack-swap.sh` mechanic that physically moved skill directories. No SessionStart hook, no directory shuffling - enablement is declarative, per-repo, and versioned.
 
 ## Usage
 
@@ -44,7 +44,7 @@ multi-agent-stack all              # all four stack toolkits + common
 
 ## Notes
 
-- Enablement is per-repo and declarative — commit `.claude/settings.json` so teammates get the same stack.
+- Enablement is per-repo and declarative - commit `.claude/settings.json` so teammates get the same stack.
 - Restart the conversation to pick up newly enabled plugins.
 - Pipeline Phase 1 stack detection is independent (it reads project files); `stack` only sets which plugin skill set is active.
 - The old `stack-swap.sh` skill-dir swap has been removed; stack selection is entirely plugin enablement.

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-status
 language: en
-description: "Show every multi-agent task's ID, phase, branch, and status."
+description: "Show every multi-agent task's ID, phase, branch, and status. Use when asked what is running, or for an overview of every task."
 user-invocable: true
 ---
 

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 the dev-toolkit MCP server."
+description: "One-shot sync of the entire multi-agent ecosystem: Claude Code, Copilot CLI, pipeline repo, website, and the dev-toolkit MCP server. Use when work is finished and should be propagated across Claude Code, Copilot CLI, the repos, the website and the dev-toolkit server."
 user-invocable: true
 argument-hint: 'release | dev-toolkit | "change description"'
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-test
 language: en
-description: "UI Bug Hunter  -  iOS Simulator (simctl) + Android Emulator (adb). Auto-detects platform. Screenshot + tap + analyze on the booted device. The Phase 5 Manual Test flow lives at multi-agent-manual-test."
+description: "UI Bug Hunter  -  iOS Simulator (simctl) + Android Emulator (adb). Auto-detects platform. Screenshot + tap + analyze on the booted device. The Phase 5 Manual Test flow lives at multi-agent-manual-test. Use when a running app should be driven on a simulator or emulator to hunt UI bugs."
 user-invocable: true
 argument-hint: '[scenario]  -  e.g. "dark mode" | "accessibility" | "dynamic type" | "screenshot tr" | "store-ready" | (empty = full sweep)'
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-uninstall
 language: en
-description: "Uninstall the pipeline from Claude Code + Copilot CLI. Keychain access tokens are always left untouched; --all-data also clears pipeline settings and logs. Asks for double confirmation."
+description: "Uninstall the pipeline from Claude Code + Copilot CLI. Keychain access tokens are always left untouched; --all-data also clears pipeline settings and logs. Asks for double confirmation. Use when the pipeline should be removed from Claude Code and Copilot CLI."
 user-invocable: true
 argument-hint: "[--dry-run] [--all-data] [--claude] [--copilot] [--target=<path>]"
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-update
 language: en
-description: "Update the pipeline to the latest version: git pull, install, migrate."
+description: "Update the pipeline to the latest version: git pull, install, migrate. Use when the installed pipeline is behind and should be brought to the latest version."
 user-invocable: true
 argument-hint: ""
 ---

package/pipeline/skills/shared/external/accessibility-compliance-accessibility-audit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: accessibility-compliance-accessibility-audit
-description: "You are an accessibility expert specializing in WCAG compliance, inclusive design, and assistive technology compatibility. Conduct audits, identify barriers, and provide remediation guidance."
+description: "You are an accessibility expert specializing in WCAG compliance, inclusive design, and assistive technology compatibility. Conduct audits, identify barriers, and provide remediation guidance. Use when auditing a product against WCAG, or when a barrier needs diagnosing and remediating."
 risk: unknown
 source: community
 date_added: "2026-02-27"

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

@@ -22,7 +22,7 @@ changes the diagnosis, and report honestly  -  before retrying.
 - 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
+## Phase 1 - Capture
 
 Write the failure state down before acting:
 
@@ -32,7 +32,7 @@ Write the failure state down before acting:
 - What is repeating (same error? different each time?).
 - Environment assumptions (cwd, branch, service up, auth present).
 
-## Phase 2 — Diagnose
+## Phase 2 - Diagnose
 
 Match the symptom to a cause before choosing an action:
 
@@ -45,7 +45,7 @@ Match the symptom to a cause before choosing an action:
 | 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
+## 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,
@@ -56,7 +56,7 @@ 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
+## Phase 4 - Introspection report
 
 Emit a short structured record:
 

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

@@ -1,6 +1,6 @@
 ---
 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."
+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. Use when development should be driven from a Kanban board rather than from a single prompt."
 risk: safe
 source: community
 date_added: "2026-04-02"

package/pipeline/skills/shared/external/android-jetpack-compose-expert/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: android-jetpack-compose-expert
-description: "Expert guidance for building modern Android UIs with Jetpack Compose, covering state management, navigation, performance, and Material Design 3."
+description: "Expert guidance for building modern Android UIs with Jetpack Compose, covering state management, navigation, performance, and Material Design 3. Use when building or reviewing Compose UI, state handling or navigation."
 risk: safe
 source: community
 date_added: "2026-02-27"

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

@@ -1,6 +1,6 @@
 ---
 name: android_ui_verification
-description: Automated end-to-end UI testing and verification on an Android Emulator using ADB.
+description: "Automated end-to-end UI testing and verification on an Android Emulator using ADB. Use when an Android build needs driving on an emulator to verify its UI end to end."
 risk: safe
 source: community
 date_added: "2026-02-28"

package/pipeline/skills/shared/external/api-patterns/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: api-patterns
-description: "API design principles and decision-making. REST vs GraphQL vs tRPC selection, response formats, versioning, pagination."
+description: "API design principles and decision-making. REST vs GraphQL vs tRPC selection, response formats, versioning, pagination. Use when choosing between REST, GraphQL and tRPC, or shaping response formats, versioning and pagination."
 risk: unknown
 source: community
 date_added: "2026-02-27"

package/pipeline/skills/shared/external/api-security-best-practices/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: api-security-best-practices
-description: "Implement secure API design patterns including authentication, authorization, input validation, rate limiting, and protection against common API vulnerabilities"
+description: "Implement secure API design patterns including authentication, authorization, input validation, rate limiting, and protection against common API vulnerabilities. Use when designing or reviewing an API's authentication, authorization, input validation or rate limiting."
 risk: unknown
 source: community
 date_added: "2026-02-27"

package/pipeline/skills/shared/external/app-store-changelog/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: app-store-changelog
-description: Generate user-facing App Store release notes from git history since the last tag.
+description: "Generate user-facing App Store release notes from git history since the last tag. Use when release notes have to be written from the commits since the last tag."
 risk: safe
 source: "Dimillian/Skills (MIT)"
 date_added: "2026-03-25"

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

@@ -23,7 +23,7 @@ _(nothing yet)_
 ### Entry template
 
 ```
-#### <id> — <title>
+#### <id> - <title>
 - state: deferred | ready | in-progress | done
 - origin: <task / PR / finding / conversation that spawned it>
 - unblock: <condition that makes it actionable, or "none">