skilldrop-cli 0.2.0

package/skills/runbook-generator/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "runbook-generator",
+  "version": "0.1.0",
+  "description": "Generate an operational runbook for a service — covering deploy/rollback, common incidents, on-call escalation, SLOs, dashboards, and dependencies. Use when the user is launching a new service, onboarding to on-call, or being asked for \"the runbook\" by SRE or production-readiness review.",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": [],
+  "tags": ["runbook", "operations", "on-call", "sre"],
+  "model": { "tier": "standard", "rationale": "Operational doc from service facts. Bounded synthesis." }
+}

package/skills/runbook-generator/templates/runbook.md

@@ -0,0 +1,109 @@
+# Runbook — {service-name}
+
+**Purpose:** {One sentence — what this service does}
+**Owner:** {team name} (primary), {team name} (secondary)
+**On-call escalation:** {PagerDuty rotation / Slack channel for paging}
+**Last reviewed:** {YYYY-MM-DD}
+
+> 📟 **Paged right now?** Skip to [Incident playbooks](#incident-playbooks) below.
+
+## Critical links
+
+| What | Where |
+|---|---|
+| Dashboard (golden signals) | {URL} |
+| Logs | {URL — e.g. Datadog query, CloudWatch link} |
+| Error tracking | {URL — Sentry / Bugsnag / Rollbar project} |
+| Source repo | {URL} |
+| Latest design doc | {URL} |
+| Change calendar | {URL — to check if a recent deploy is the cause} |
+
+## SLOs
+
+| SLI | SLO | Window |
+|---|---|---|
+| Availability | 99.9% | 30 days |
+| Latency p99 | < 100ms | 30 days |
+| Error rate | < 0.1% | 30 days |
+
+**Error budget:** {how much budget is left this period, link to dashboard}
+
+## Deploy
+
+```bash
+# Trigger CI/CD
+{exact command — e.g. `gh workflow run deploy-prod.yml --ref main`}
+
+# Confirm
+{exact command — e.g. `kubectl rollout status deployment/{service} -n {ns}`}
+```
+
+**Pre-deploy checklist:** {anything that must be true before deploying — error budget OK, no incidents open, …}
+
+## Rollback
+
+```bash
+# Last-known-good
+{exact command — e.g. `kubectl rollout undo deployment/{service} -n {ns}`}
+```
+
+**Rollback criteria:** {when to revert without further investigation — e.g. "error rate > 1% sustained 5 min after deploy"}
+
+## Incident playbooks
+
+The most common incidents, with how to recognize → mitigate → investigate.
+
+### 1. {Incident name — e.g. "High p99 latency"}
+
+**Symptom:** {alert text + dashboard pattern}
+**Immediate mitigation:**
+1. {Step — e.g. "Scale up: `kubectl scale deploy/{service} --replicas=20`"}
+2. {Step}
+
+**Investigate:**
+- {Where to look — log query, dashboard, …}
+
+**Escalate when:** {clear condition for paging the next tier}
+
+### 2. {Incident name — e.g. "Database connection saturation"}
+
+**Symptom:** {…}
+**Immediate mitigation:** {…}
+**Investigate:** {…}
+**Escalate when:** {…}
+
+### 3. {Incident name}
+
+{…}
+
+### 4. {Incident name}
+
+{…}
+
+### 5. {Incident name}
+
+{…}
+
+## Dependencies
+
+| Depends on | Type | Failure mode if it's down | Owner |
+|---|---|---|---|
+| {Service / vendor} | {sync API / async queue / data store} | {what happens — does this service degrade, refuse traffic, or break entirely?} | {team} |
+| {Service / vendor} | … | … | … |
+
+## Operations cookbook
+
+Common manual tasks (not incidents):
+
+- **Drain a node / pod:** `{command}`
+- **Replay a failed job:** `{command or runbook link}`
+- **Re-issue an API key:** `{procedure}`
+- **Triage a customer report:** `{escalation path}`
+
+## Known gaps
+
+- {Honest list of "we don't have a good answer for X yet" — better explicit than hidden}
+
+## Change log
+
+- {YYYY-MM-DD} — {what changed in the runbook itself, e.g. "added incident #5 after rollout 2026-04-12 incident"}

package/skills/slide-outliner/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: slide-outliner
+description: Outline an architecture review or technical pitch deck — slide titles, key points per slide, and speaker notes. Does NOT generate PowerPoint/Keynote files; produces a structured outline the user can paste into any deck tool. Use when the user is preparing for an architecture review, design review, sales pitch, partner meeting, or steering-committee presentation.
+---
+
+# slide-outliner
+
+You help the user plan a deck before they open PowerPoint, by producing a slide-by-slide outline with structure, key points, and speaker notes.
+
+## How to respond
+
+1. **Pin down audience + format + time.**
+   - **Audience:** engineering peers? execs? customers? regulators? Mix?
+   - **Format:** live presentation (with discussion) vs. read-ahead doc vs. async share?
+   - **Time:** 10 minutes? 30? 60? — this determines slide count more than anything else.
+
+   Rough guide: **1.5–2 minutes per slide** in a live setting with Q&A. So 30 minutes → 12–15 content slides max, including the cover and the close.
+
+2. **Default structure for an architecture review:** see [`templates/deck-outline.md`](templates/deck-outline.md). Sections in order:
+   1. **Cover** — title, presenter, audience, date
+   2. **Why we're here** — the question/decision/approval being sought (one slide)
+   3. **Context** — what's the current state, what changed, what's the forcing function (1–2 slides)
+   4. **Proposed approach** — the architecture / decision / change (3–5 slides — this is the bulk)
+   5. **Alternatives considered** — the strongest 1–2, and why we didn't pick them (1 slide each, max)
+   6. **Risks & mitigations** — pick the 3–4 the audience cares most about (1 slide)
+   7. **Cost, timeline, rollout** (1 slide)
+   8. **What we need from you** — the Ask (1 slide)
+   9. **Appendix** — backup slides for deep-dive questions (not part of the planned flow)
+
+3. **Per slide, produce:**
+   - **Slide title** (a sentence that *states the takeaway*, not a category label — "Postgres meets our latency target" beats "Database evaluation")
+   - **Key points** (3–5 bullets — what's actually on the slide)
+   - **Speaker notes** (2–3 sentences — what the presenter says that *isn't* on the slide)
+
+4. **Plan for Q&A.** Add an Appendix section with 3–5 "if they ask…" backup slides covering the topics most likely to come up:
+   - Cost detail / TCO
+   - Security & compliance
+   - Migration path / backwards compatibility
+   - Vendor risk / open-source health
+   - Why-not the obvious-but-rejected alternative
+
+5. **End with a slide-count check.** Tally the slides against the time budget. If you're over, suggest specific cuts. Don't leave the user to do the math.
+
+## Quality bar
+
+- **Slide titles assert, don't label.** ✅ "We can ship the migration in two quarters" — ❌ "Migration timeline".
+- **No slide has both "high-level overview" *and* "deep technical detail".** Pick one. If you need both, that's two slides.
+- **Speaker notes carry the narrative; slides carry the evidence.** Don't put your script on the slide.
+- **One idea per slide.** If the slide has two takeaways, split it.
+- **Appendix slides are labeled as such** so the presenter doesn't accidentally walk into them.
+
+## Anti-patterns to avoid
+
+- ❌ The "agenda" slide. Most audiences don't care; the cover already tells them.
+- ❌ "Thank you / questions?" as a slide. Land on a slide with content (usually the Ask) — questions will come anyway.
+- ❌ More than ~6 bullets on one slide. If you have 7, split or cut.
+- ❌ Backup slides indistinguishable from main slides — leads to accidental flow disruption.
+- ❌ A "team" slide unless someone in the audience actually needs to know who's in the room.

package/skills/slide-outliner/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "slide-outliner",
+  "version": "0.1.0",
+  "description": "Outline an architecture review or technical pitch deck — slide titles, key points per slide, and speaker notes. Does NOT generate PowerPoint/Keynote files; produces a structured outline the user can paste into any deck tool. Use when the user is preparing for an architecture review, design review, sales pitch, partner meeting, or steering-committee presentation.",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": [],
+  "tags": ["presentation", "deck", "outline", "stakeholder-communication"],
+  "model": { "tier": "standard", "rationale": "Outlines a deck to a time budget. Structuring, not deep reasoning." }
+}

package/skills/slide-outliner/templates/deck-outline.md

@@ -0,0 +1,131 @@
+# Deck outline — {Topic}
+
+**Audience:** {who's in the room}
+**Format:** {live presentation 30 min + Q&A / read-ahead doc / async share}
+**Slot:** {meeting / forum + date}
+**Target slide count:** {N main + ~5 appendix}
+
+---
+
+## Slide 1 — Cover
+
+**Title:** {Topic — usually mirrors the project name, as a phrase not a question}
+**Key points:**
+- Presenter(s) + role
+- Audience the deck is for
+- Date
+
+**Speaker notes:** *{Set the scene in one sentence: "We're here to get your decision on X."}*
+
+---
+
+## Slide 2 — Why we're here
+
+**Title:** {The decision / approval / input being sought, as an assertion}
+**Key points:**
+- The Ask (one line)
+- What's on the table today vs. out of scope
+- How this fits with prior decisions (link to ADR / prior review)
+
+**Speaker notes:** *{Anchor on the Ask. If you don't get past this slide, the audience still knows what you needed.}*
+
+---
+
+## Slide 3 — Current state
+
+**Title:** {Assertion about the current state — "Our checkout pipeline tops out at 50 RPS"}
+**Key points:**
+- 2–3 facts about the current system
+- The constraint or pain that's forcing the change
+
+**Speaker notes:** *{Establish the *why now*. Not "this could be better" — what's actually broken or about to be.}*
+
+---
+
+## Slide 4 — Proposed approach (overview)
+
+**Title:** {What we're proposing, as an assertion}
+**Key points:**
+- The one-sentence change
+- Architecture diagram (use `architecture-diagrams` skill if needed)
+- The 2–3 key design decisions
+
+**Speaker notes:** *{Stay shallow here — depth is in the next slides. If the diagram is unfamiliar, walk through it.}*
+
+---
+
+## Slides 5–7 — Proposed approach (detail)
+
+**Use one slide per major component or major decision.** Examples:
+- Slide 5: Data model change
+- Slide 6: Migration path from current state
+- Slide 7: Observability / how we'll know it's working
+
+*(Plan these from the actual proposal, not in advance.)*
+
+---
+
+## Slide 8 — Alternatives considered
+
+**Title:** {Why our pick beat the strongest alternative}
+**Key points:**
+- Alternative #1: what it was, one-line why not
+- Alternative #2: what it was, one-line why not
+- (Skip weaker alternatives — they belong in the appendix)
+
+**Speaker notes:** *{Show your work. An exec who's been pitched before will trust you more if you killed at least one obvious option for a non-obvious reason.}*
+
+---
+
+## Slide 9 — Risks & mitigations
+
+**Title:** {Top risk, framed as something we have a plan for}
+**Key points:**
+- Risk → mitigation (×3)
+- Honest "we don't know yet" callouts go here, not hidden
+
+**Speaker notes:** *{Don't pretend there are no risks. Audiences trust presenters who say "here's what could go wrong and here's how we'd respond."}*
+
+---
+
+## Slide 10 — Cost, timeline, rollout
+
+**Title:** {Headline number — "Q3 ship for $480k" or "12 weeks, 4 engineers"}
+**Key points:**
+- Effort estimate + confidence
+- Calendar timeline (gantt / phase strip)
+- Rollout phases with go/no-go criteria
+
+**Speaker notes:** *{Be honest about confidence. "Rough" + a transparent number is more credible than precise-looking fake numbers.}*
+
+---
+
+## Slide 11 — What we need from you
+
+**Title:** {The Ask, restated as an action}
+**Key points:**
+- Decision needed: {…}
+- Budget needed: {…}
+- People needed: {…}
+- By when
+
+**Speaker notes:** *{Close on this slide. Take questions here, not after a thank-you slide.}*
+
+---
+
+# Appendix (backup slides — only shown if asked)
+
+## A1 — Cost detail
+{TCO breakdown, vendor pricing, sensitivity}
+
+## A2 — Security & compliance
+{Threat model summary, data classification, regulatory implications}
+
+## A3 — Migration plan detail
+{Phased plan, rollback, customer-impact analysis}
+
+## A4 — Why not {the obvious alternative}
+{The deeper kill reason for the option people will ask about}
+
+## A5 — Open questions
+{What we're still working out — be explicit}

package/skills/sonar-onboard/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: sonar-onboard
+description: Scaffold a repo for Sonar compliance — supports both **SonarQube server** (self-hosted) and **SonarCloud** (SaaS), user picks at setup time. Generates `sonar-project.properties` with language-correct source/test/coverage paths, a CI workflow that runs the scanner on every push and PR and blocks merge on quality-gate failure, and a README snippet documenting the gate. One-shot setup; pair with `sonar-review` for per-change feedback. Use when the user says "set up Sonar", "add SonarQube to this repo", "wire up SonarCloud", "set up the quality gate", or asks to make a project Sonar-compliant for the first time.
+---
+
+# sonar-onboard
+
+Scaffolds the artifacts a repo needs to become Sonar-compliant: a `sonar-project.properties` keyed to the project's actual language and layout, a CI workflow that runs the scanner and enforces the quality gate, and a README block so the next contributor knows what the gate means and how to run a scan locally.
+
+This is a **one-shot setup skill**. For per-change feedback after the repo is onboarded, use [`sonar-review`](../sonar-review/SKILL.md).
+
+Supports both deployment models — the user picks one:
+
+| Mode | When it's right | Host | Key extras |
+|---|---|---|---|
+| **SonarQube server** | Self-hosted, on-prem or in own VPC. Enterprise / regulated orgs. | `https://sonar.<company>.com` (set per-org) | Project token + host URL |
+| **SonarCloud** | SaaS, hosted by SonarSource. Faster setup, no infra. | `https://sonarcloud.io` (fixed) | Project token + **organization key** |
+
+The choice changes three things: the properties file (SonarCloud needs `sonar.organization`), the GitHub Actions step (different action), and the secrets the user must add. Everything else is identical.
+
+## How to respond
+
+1. **Ask which mode** if the user hasn't said — it's the first question. One question, not two:
+
+   > Which Sonar are you using — **SonarQube server** (self-hosted) or **SonarCloud** (SaaS at sonarcloud.io)?
+
+   If they describe the host URL, infer: anything matching `sonarcloud.io` ⇒ SonarCloud; anything else ⇒ SonarQube server. Don't ask twice.
+
+2. **Collect the inputs.** Ask for whichever are missing. Cap at two more clarifying questions per turn; pick defaults for the rest and call them out:
+
+   | Input | Required for | Default if not given |
+   |---|---|---|
+   | **Project key** (e.g. `myorg_payments-api`) | both | `<repo-name>` (derive from `git remote get-url origin`) |
+   | **Organization key** (SonarCloud only, e.g. `my-org`) | SonarCloud | Required — ask if missing |
+   | **SonarQube host URL** (e.g. `https://sonar.company.com`) | SonarQube server | Required — ask if missing |
+   | **Primary language(s)** | both | Detect from repo (see step 3) |
+   | **CI system** | both | GitHub Actions (emit `gitlab-ci`/`jenkins`/`azure-pipelines` only if user names it) |
+   | **Coverage tool** | both | Detect from language (see step 4) |
+
+3. **Detect language(s)** from the working tree — don't ask if a probe will tell you:
+
+   | Marker file | Language | Default source dir |
+   |---|---|---|
+   | `package.json` | JavaScript / TypeScript | `src` |
+   | `pom.xml` | Java (Maven) | `src/main/java` |
+   | `build.gradle` / `build.gradle.kts` | Java / Kotlin (Gradle) | `src/main/java` or `src/main/kotlin` |
+   | `requirements.txt` / `pyproject.toml` / `setup.py` | Python | top-level package dir or `src` |
+   | `go.mod` | Go | repo root |
+   | `*.csproj` / `*.sln` | C# / .NET | project dirs |
+   | `Cargo.toml` | Rust | `src` |
+   | `composer.json` | PHP | `src` |
+   | `Gemfile` | Ruby | `lib` and `app` |
+
+   Multi-language is normal (e.g. TypeScript frontend + Python backend) — set `sonar.sources` to a comma-separated list and emit one combined `sonar-project.properties`. Don't generate one file per language.
+
+4. **Pick the coverage report path** based on language. These are the formats Sonar's importers expect:
+
+   | Language | Coverage report | Sonar property |
+   |---|---|---|
+   | JS / TS | `coverage/lcov.info` (Jest, Vitest default) | `sonar.javascript.lcov.reportPaths` |
+   | Java (Maven) | `target/site/jacoco/jacoco.xml` | `sonar.coverage.jacoco.xmlReportPaths` |
+   | Java (Gradle) | `build/reports/jacoco/test/jacocoTestReport.xml` | `sonar.coverage.jacoco.xmlReportPaths` |
+   | Python | `coverage.xml` (`pytest-cov --cov-report=xml`) | `sonar.python.coverage.reportPaths` |
+   | Go | `coverage.out` | `sonar.go.coverage.reportPaths` |
+   | C# | `coverage.opencover.xml` (coverlet) | `sonar.cs.opencover.reportsPaths` |
+
+   If the user has no coverage tool today, **don't fabricate a report path**. Omit the coverage property and add a `# TODO` comment in the properties file pointing them at the right one.
+
+5. **Generate `sonar-project.properties`** using [`templates/sonar-project.properties.tmpl`](templates/sonar-project.properties.tmpl). Fill placeholders; remove blocks that don't apply.
+
+   **For SonarCloud**, add this line (immediately after `sonar.projectKey`):
+   ```
+   sonar.organization={{ORG_KEY}}
+   ```
+   The organization key is mandatory for SonarCloud and rejected by SonarQube server — emit it for one and not the other.
+
+   **Exclusions** — add these by default; they save the next contributor from a noisy first scan:
+   ```
+   sonar.exclusions=**/node_modules/**,**/dist/**,**/build/**,**/.next/**,**/__pycache__/**,**/*.generated.*,**/vendor/**,**/migrations/**
+   sonar.test.exclusions=**/*.test.*,**/*.spec.*,**/test/**,**/tests/**
+   sonar.coverage.exclusions=**/*.test.*,**/*.spec.*,**/test/**,**/tests/**,**/*.stories.*,**/index.{js,ts}
+   ```
+   Trim language-irrelevant entries (e.g. drop `__pycache__` for a pure-JS repo).
+
+6. **Generate the CI workflow.** Default is GitHub Actions. Pick the template by mode:
+
+   | Mode | Template | Scan action | Gate action |
+   |---|---|---|---|
+   | SonarQube server | [`templates/github-actions-sonar-server.yml.tmpl`](templates/github-actions-sonar-server.yml.tmpl) | `sonarsource/sonarqube-scan-action@v3` | `sonarsource/sonarqube-quality-gate-action@master` |
+   | SonarCloud | [`templates/github-actions-sonarcloud.yml.tmpl`](templates/github-actions-sonarcloud.yml.tmpl) | `SonarSource/sonarcloud-github-action@master` | (built into scan action — `pollingTimeoutSec` controls wait) |
+
+   Both must:
+   - Trigger on `push` to default branch **and** `pull_request` (Sonar needs the PR event to comment on the PR).
+   - Use `actions/checkout@v4` with `fetch-depth: 0` (Sonar needs full history to attribute blame).
+   - Run the project's build + test + coverage **before** the scanner, otherwise coverage is empty.
+   - Reference `SONAR_TOKEN` from GitHub Secrets — never inline.
+
+   Mode-specific:
+   - **Server** also references `SONAR_HOST_URL` from Secrets, and runs a separate `sonarqube-quality-gate-action` step so the job fails on gate failure.
+   - **SonarCloud** doesn't need `SONAR_HOST_URL` (the action defaults to `https://sonarcloud.io`), and references `GITHUB_TOKEN` for PR decoration.
+
+   For GitLab / Jenkins / Azure DevOps, see [`reference.md`](reference.md) — only emit those if the user names them.
+
+7. **Generate the README snippet** using [`templates/readme-snippet.md`](templates/readme-snippet.md). Drop it under a `## Code quality` heading. It documents: what the gate enforces, the two required secrets, the local-scan command, and where to read findings (Sonar UI link).
+
+8. **List the secrets the user must add manually.** End your response with this exact block — the skill cannot set secrets and shouldn't pretend it can. The steps differ by mode:
+
+   **SonarQube server:**
+   ```
+   Manual steps you must do before the workflow runs green:
+   1. Create a SonarQube project at <SONAR_HOST_URL>/projects/create with key `<project-key>`.
+   2. Generate a project token (My Account → Security → Generate Token).
+   3. Add GitHub Secret `SONAR_TOKEN` with the token value.
+   4. Add GitHub Secret `SONAR_HOST_URL` with `<SONAR_HOST_URL>`.
+   5. (Optional) Tighten the Quality Gate in Sonar UI — defaults are listed in the README snippet.
+   ```
+
+   **SonarCloud:**
+   ```
+   Manual steps you must do before the workflow runs green:
+   1. Sign in at https://sonarcloud.io with the GitHub account that owns this repo.
+   2. Create / import the project: + → Analyze new project → pick the repo. Confirm organization is `<org-key>` and project key is `<project-key>`.
+   3. Disable "Automatic Analysis" on the project (Administration → Analysis Method) — the CI-driven scan and Automatic Analysis cannot both run.
+   4. Generate a token (My Account → Security → Generate Token).
+   5. Add GitHub Secret `SONAR_TOKEN` with the token value.
+   6. (Optional) Tighten the Quality Gate in SonarCloud UI — defaults are listed in the README snippet.
+   ```
+
+## Useful references in this skill
+
+- [`templates/sonar-project.properties.tmpl`](templates/sonar-project.properties.tmpl) — properties file skeleton (works for both modes; `sonar.organization` line is SonarCloud-only)
+- [`templates/github-actions-sonar-server.yml.tmpl`](templates/github-actions-sonar-server.yml.tmpl) — CI workflow for self-hosted SonarQube
+- [`templates/github-actions-sonarcloud.yml.tmpl`](templates/github-actions-sonarcloud.yml.tmpl) — CI workflow for SonarCloud
+- [`templates/readme-snippet.md`](templates/readme-snippet.md) — README section for the gate (mode-aware placeholders)
+- [`reference.md`](reference.md) — GitLab / Jenkins / Azure DevOps variants, quality-gate tuning, monorepo guidance, server vs cloud differences
+
+## Quality bar
+
+- **Properties file is keyed to the actual repo.** `sonar.projectKey`, `sonar.sources`, `sonar.tests`, and the coverage path must reflect what's on disk — not a generic example. A properties file that scans the wrong directories produces a green gate that means nothing.
+- **The workflow blocks merge on gate failure.** A scan that runs but doesn't fail PRs is decoration. The `sonarqube-quality-gate-action` step is non-negotiable.
+- **Coverage path exists or is marked TODO.** Pointing at a coverage file that the test step never produces gives Sonar 0% coverage and a false-failing gate. Either wire it up end-to-end or leave it explicit.
+- **`fetch-depth: 0` in checkout.** Shallow clones break Sonar's new-code-period detection. The first scan will look fine; the next ten PRs will mis-attribute issues.
+- **Secrets are referenced, never inlined.** No raw tokens or URLs in committed files. The token belongs in GitHub Secrets; the URL too, even though it's not technically secret — it keeps fork PRs from leaking the host.
+- **README snippet tells the next contributor what the gate enforces.** "Sonar must pass" is not enough — list the conditions (no new bugs, no new vulnerabilities, coverage on new code ≥ X%, duplication ≤ Y%).
+
+## When to use this skill
+
+- ✅ First-time Sonar setup on a repo (server or cloud)
+- ✅ Migrating between modes — SonarCloud → self-hosted (or vice versa). Re-scaffold with the new mode; remember to switch templates *and* the properties file.
+- ✅ Adding Sonar to a fork or a new service in a monorepo (one properties file per module — see `reference.md`)
+- ✅ Replacing an ad-hoc, locally-run scanner setup with a gate-enforcing CI workflow
+
+## When NOT to use this skill
+
+- ❌ Repo already has a working `sonar-project.properties` and a CI workflow that runs the scanner. Use `sonar-review` for per-change feedback instead.
+- ❌ User wants to disable rules or relax the gate to make a failing scan pass. That's a code-quality conversation, not a setup task — push back.
+- ❌ User wants language-specific deep config (custom rule profiles, Sonar plugins, branch analysis tuning). Out of scope; point at [`reference.md`](reference.md) and the Sonar docs.
+- ❌ User wants both SonarQube server *and* SonarCloud scanning the same repo. Pick one — running both means two gates, two histories, and two answers to "did the build pass?".
+
+## Anti-patterns to avoid
+
+- ❌ **Emitting `sonar.organization` for SonarQube server.** It's SonarCloud-only and the server rejects it. Conversely: omitting it for SonarCloud breaks the scan.
+- ❌ **Emitting a `sonar.login=...` line.** Deprecated since Sonar 10. Use `SONAR_TOKEN` env var, which both scan actions read automatically.
+- ❌ **Hard-coding the host URL in the properties file** (server mode). It belongs in CI env / the scan action input, so forks and local runs don't ship someone else's Sonar.
+- ❌ **Forgetting to disable SonarCloud's Automatic Analysis.** The CI scan and Automatic Analysis can't coexist; SonarCloud will fail one of them. The Manual Steps block must include this — it's the #1 cause of "scan ran but didn't update".
+- ❌ **Generating multiple `sonar-project.properties` files for a multi-language single project.** One project = one properties file with comma-separated `sonar.sources`.
+- ❌ **Skipping `pull_request` trigger.** A scan that only runs on `main` finds problems after they're merged — defeats the purpose.
+- ❌ **Inventing a coverage path because "Sonar wants one".** If the project doesn't generate coverage, omit the property and TODO it. A path that points at nothing produces a misleading gate.
+- ❌ **Recommending the user disable rules to pass the gate.** The gate exists to surface real issues. Suggest fixes or scope the gate to "new code" rather than turning rules off.
+- ❌ **Burying the manual steps.** The "Manual steps you must do" block is the most important output — the workflow can't run green without it. Don't summarize it; print it verbatim.

package/skills/sonar-onboard/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "sonar-onboard",
+  "version": "0.1.0",
+  "description": "Scaffold a repo for Sonar compliance — supports both **SonarQube server** (self-hosted) and **SonarCloud** (SaaS), user picks at setup time. Generates `sonar-project.properties` with language-correct source/test/coverage paths, a CI workflow that runs the scanner on every push and PR and blocks merge on quality-gate failure, and a README snippet documenting the gate. One-shot setup; pair with `sonar-review` for per-change feedback. Use when the user says \"set up Sonar\", \"add SonarQube to this repo\", \"wire up SonarCloud\", \"set up the quality gate\", or asks to make a project Sonar-compliant for the first time.",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": ["SONAR_HOST_URL"] },
+  "related": ["sonar-review"],
+  "tags": ["sonarqube", "sonarcloud", "sonar", "code-quality", "ci", "quality-gate", "scaffold", "dev-workflow"],
+  "model": { "tier": "light", "rationale": "Scaffolds config from detected language + a template. Deterministic fill-in; little judgment." }
+}

package/skills/sonar-onboard/reference.md

@@ -0,0 +1,151 @@
+# sonar-onboard — reference
+
+Long-form material that doesn't belong in `SKILL.md`.
+
+## SonarQube server vs SonarCloud — what actually differs
+
+The user picks one at setup. The differences are smaller than the marketing suggests, but the ones that matter are:
+
+| Aspect | SonarQube server | SonarCloud |
+|---|---|---|
+| Host URL | Set per-org (e.g. `sonar.company.com`) | Fixed at `https://sonarcloud.io` |
+| `sonar.organization` in properties | **Must not** be present | **Must** be present |
+| GitHub Action | `sonarsource/sonarqube-scan-action@v3` + separate gate action | `SonarSource/sonarcloud-github-action@master` (single step) |
+| Quality-gate action | `sonarsource/sonarqube-quality-gate-action@master` | Built into the scan action; separate action also works |
+| GitHub Secrets | `SONAR_TOKEN`, `SONAR_HOST_URL` | `SONAR_TOKEN` only (host is implicit) |
+| Branch analysis | Developer Edition+ only (Community Edition: no branches) | Included on all SonarCloud tiers |
+| PR decoration | Needs ALM integration set up server-side | Auto-enabled when scan runs |
+| Automatic Analysis | N/A | **Must be disabled** when using CI-driven scanning |
+| Pricing | Per-instance license | Per-LoC subscription, free for open-source |
+| Where the data lives | Your infra | SonarSource's (EU / US regions available) |
+
+Two failure modes are mode-specific and worth surfacing:
+
+- **SonarCloud + Automatic Analysis** — if both Automatic Analysis and the CI scan are enabled, SonarCloud rejects one (the second one to run). Symptom: random scan failures with "Project already analyzed". Fix: disable Automatic Analysis under Administration → Analysis Method.
+- **SonarQube server + Community Edition + branch scanning** — Community Edition has no branch analysis; setting `sonar.branch.name` makes the scanner emit a license warning and fall back to scanning as the default branch (so feature-branch PRs overwrite `main`'s history). Fix: either upgrade to Developer Edition, or remove the `branch.name` line and scan only on merge.
+
+## Non-GitHub CI variants
+
+Only emit these if the user explicitly names the CI system. Defaults to GitHub Actions.
+
+### GitLab CI
+
+```yaml
+sonarqube-check:
+  image:
+    name: sonarsource/sonar-scanner-cli:latest
+    entrypoint: [""]
+  variables:
+    SONAR_USER_HOME: "${CI_PROJECT_DIR}/.sonar"
+    GIT_DEPTH: "0"  # full history for blame
+  cache:
+    key: "${CI_JOB_NAME}"
+    paths: [.sonar/cache]
+  script:
+    - sonar-scanner
+  rules:
+    - if: $CI_PIPELINE_SOURCE == 'merge_request_event'
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+```
+
+GitLab passes `SONAR_TOKEN` and `SONAR_HOST_URL` via project-level CI/CD variables (Settings → CI/CD → Variables). Quality-gate enforcement requires the [GitLab MR decoration](https://docs.sonarsource.com/sonarqube/latest/devops-platform-integration/gitlab-integration/) setup on the Sonar side — the gate fails the pipeline automatically once decoration is wired.
+
+### Jenkins
+
+Requires the **SonarQube Scanner for Jenkins** plugin. In a `Jenkinsfile`:
+
+```groovy
+pipeline {
+  agent any
+  stages {
+    stage('Build + Test') { steps { sh 'mvn -B verify' } }
+    stage('SonarQube') {
+      steps {
+        withSonarQubeEnv('SonarQube-Server') {  // configured in Jenkins → System
+          sh 'sonar-scanner'
+        }
+      }
+    }
+    stage('Quality Gate') {
+      steps {
+        timeout(time: 5, unit: 'MINUTES') {
+          waitForQualityGate abortPipeline: true
+        }
+      }
+    }
+  }
+}
+```
+
+`abortPipeline: true` is the equivalent of the GitHub `quality-gate-action` — without it, the gate is decorative.
+
+### Azure DevOps
+
+Install the **SonarQube extension** from the marketplace, then in `azure-pipelines.yml`:
+
+```yaml
+steps:
+  - task: SonarQubePrepare@5
+    inputs:
+      SonarQube: 'SonarQube-ServiceConnection'
+      scannerMode: 'CLI'
+      configMode: 'file'
+  - script: '<build + test + coverage commands here>'
+  - task: SonarQubeAnalyze@5
+  - task: SonarQubePublish@5
+    inputs: { pollingTimeoutSec: '300' }
+  - task: sonarcloud-buildbreaker@2  # NOTE: also works for SonarQube server
+    inputs:
+      SonarQube: 'SonarQube-ServiceConnection'
+```
+
+## Quality gate tuning
+
+The skill emits the **Sonar way** default gate. Common project-specific adjustments:
+
+- **Loosen coverage on new code** (default 80%) — for projects with hard-to-test integration code, drop to 60% and note the exception in the README.
+- **Tighten duplication** (default 3%) — for libraries, 1% is reasonable; the dup gate catches copy-paste.
+- **Add a "security review" condition** — for compliance-driven projects, require all security hotspots (not just new ones) to be reviewed.
+
+Edit gates in Sonar UI: Quality Gates → `<gate-name>` → Conditions. Do **not** copy a gate config into source control — it lives server-side and applies per project.
+
+## Monorepo guidance
+
+For a monorepo with multiple deployable services, emit **one `sonar-project.properties` per service** at the service root, plus a root-level GitHub Actions workflow with a matrix:
+
+```yaml
+strategy:
+  matrix:
+    project:
+      - path: services/payments
+        key: myorg_payments
+      - path: services/billing
+        key: myorg_billing
+steps:
+  - uses: sonarsource/sonarqube-scan-action@v3
+    with:
+      projectBaseDir: ${{ matrix.project.path }}
+    env:
+      SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+      SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
+```
+
+Each service is a separate Sonar project with its own gate and history. Don't try to put a multi-module config in one properties file — Sonar's "modules" feature is deprecated.
+
+## Language-specific gotchas
+
+- **TypeScript** — set `sonar.typescript.tsconfigPath=tsconfig.json` if the project uses path aliases; otherwise Sonar can't resolve imports and over-reports "unused" findings.
+- **Java (Gradle)** — use the [Sonar Gradle plugin](https://docs.sonarsource.com/sonarqube/latest/analyzing-source-code/scanners/sonarscanner-for-gradle/) instead of the standalone scanner. It auto-detects sources, tests, and JaCoCo paths. The properties file then only needs `sonar.projectKey`.
+- **Python** — Sonar imports `coverage.xml`, not `.coverage`. Run `coverage xml` (or `pytest-cov --cov-report=xml`) explicitly; the default `.coverage` binary is ignored.
+- **Go** — coverage importer expects the raw `coverage.out` (Go's native format), not `cobertura` XML. Don't convert.
+- **C# / .NET** — use the [`dotnet-sonarscanner`](https://docs.sonarsource.com/sonarqube/latest/analyzing-source-code/scanners/sonarscanner-for-dotnet/) tool, not the generic scanner. Wraps `dotnet build` so analysis hooks into the compile step.
+
+## Why `fetch-depth: 0`
+
+Shallow clones (the GitHub Actions default) ship only the last commit. Sonar uses git blame to attribute issues to authors and the new-code period to scope the gate. Without full history:
+
+- All issues look like they were introduced in the latest commit → gate fails on existing debt.
+- Blame UI in Sonar shows the wrong author for every line.
+- "New code since previous version" becomes meaningless because the previous version isn't in the clone.
+
+Always `fetch-depth: 0`. The extra clone time is a few seconds; the analytical correctness is worth it.