skilldrop-cli 0.16.3__py3-none-any.whl

skilldrop_cli/data/packs/dev-team/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." }
+}

skilldrop_cli/data/packs/dev-team/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.

skilldrop_cli/data/packs/dev-team/skills/sonar-onboard/templates/github-actions-sonar-server.yml.tmpl

@@ -0,0 +1,50 @@
+name: SonarQube
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  sonarqube:
+    name: Scan + quality gate
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          # Full history is required for accurate blame and new-code-period detection.
+          fetch-depth: 0
+
+      # ─── BUILD + TEST + COVERAGE ───────────────────────────────────────────
+      # Replace this block with the project's actual build/test commands.
+      # The scanner imports the coverage report produced here — if this step
+      # doesn't generate it, Sonar reports 0% coverage on new code.
+      #
+      # Examples:
+      #   JS/TS:    npm ci && npm test -- --coverage
+      #   Java:     mvn -B verify
+      #   Python:   pip install -r requirements.txt && pytest --cov --cov-report=xml
+      #   Go:       go test ./... -coverprofile=coverage.out
+      #
+      - name: Build, test, and produce coverage
+        run: |
+          {{BUILD_TEST_COMMAND}}
+
+      # ─── SCAN ──────────────────────────────────────────────────────────────
+      - name: SonarQube scan
+        uses: sonarsource/sonarqube-scan-action@v3
+        env:
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
+
+      # ─── QUALITY GATE ──────────────────────────────────────────────────────
+      # Fails the job (and therefore the PR check) when the gate fails.
+      # Without this step, scans run but never block merge — defeats the point.
+      - name: Quality gate
+        uses: sonarsource/sonarqube-quality-gate-action@master
+        timeout-minutes: 5
+        env:
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}

skilldrop_cli/data/packs/dev-team/skills/sonar-onboard/templates/github-actions-sonarcloud.yml.tmpl

@@ -0,0 +1,53 @@
+name: SonarCloud
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  sonarcloud:
+    name: Scan + quality gate
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          # Full history is required for accurate blame and new-code-period detection.
+          fetch-depth: 0
+
+      # ─── BUILD + TEST + COVERAGE ───────────────────────────────────────────
+      # Replace this block with the project's actual build/test commands.
+      # The scanner imports the coverage report produced here — if this step
+      # doesn't generate it, SonarCloud reports 0% coverage on new code.
+      #
+      # Examples:
+      #   JS/TS:    npm ci && npm test -- --coverage
+      #   Java:     mvn -B verify
+      #   Python:   pip install -r requirements.txt && pytest --cov --cov-report=xml
+      #   Go:       go test ./... -coverprofile=coverage.out
+      #
+      - name: Build, test, and produce coverage
+        run: |
+          {{BUILD_TEST_COMMAND}}
+
+      # ─── SCAN ──────────────────────────────────────────────────────────────
+      # The SonarCloud action runs the scanner AND waits for the gate, in one step.
+      # Host URL defaults to https://sonarcloud.io — do not override unless you
+      # know what you're doing.
+      - name: SonarCloud scan
+        uses: SonarSource/sonarcloud-github-action@master
+        env:
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+          # GITHUB_TOKEN is used to decorate the PR with findings.
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      # ─── QUALITY GATE ──────────────────────────────────────────────────────
+      # Fails the job (and therefore the PR check) when the gate fails.
+      - name: Quality gate
+        uses: SonarSource/sonarqube-quality-gate-action@master
+        timeout-minutes: 5
+        env:
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+          SONAR_HOST_URL: https://sonarcloud.io

skilldrop_cli/data/packs/dev-team/skills/sonar-onboard/templates/readme-snippet.md

@@ -0,0 +1,38 @@
+## Code quality
+
+This repo is gated by **{{SONAR_FLAVOR}}** ({{SONAR_FLAVOR}} = `SonarQube` for self-hosted, `SonarCloud` for SaaS). Every push to the default branch and every pull request runs a scan; the PR check fails if the quality gate fails.
+
+**What the gate enforces** (Sonar default — tune in the Sonar UI per project):
+
+| Condition | Threshold |
+|---|---|
+| New bugs | 0 |
+| New vulnerabilities | 0 |
+| New security hotspots reviewed | 100% |
+| Coverage on new code | ≥ 80% |
+| Duplicated lines on new code | ≤ 3% |
+| Maintainability rating on new code | A |
+| Reliability rating on new code | A |
+| Security rating on new code | A |
+
+The gate measures **new code** (since the previous version), not the whole codebase — so existing debt doesn't block your PR, but new debt does.
+
+**Required GitHub secrets:**
+
+<!-- For SonarQube server, keep both. For SonarCloud, keep only SONAR_TOKEN. -->
+- `SONAR_TOKEN` — project token from {{SONAR_FLAVOR}} (My Account → Security → Generate Token)
+- `SONAR_HOST_URL` — e.g. `https://sonar.company.com`  *(SonarQube server only; omit for SonarCloud)*
+
+**Run a scan locally** (against the same {{SONAR_FLAVOR}} project):
+
+```bash
+export SONAR_TOKEN=<your-token>
+# SonarQube server only:
+export SONAR_HOST_URL=<your-sonar-host>
+# SonarCloud: omit SONAR_HOST_URL — it defaults to https://sonarcloud.io
+sonar-scanner
+```
+
+Findings appear at:
+- **SonarQube server:** `${SONAR_HOST_URL}/dashboard?id=<project-key>`
+- **SonarCloud:** `https://sonarcloud.io/dashboard?id=<project-key>`

skilldrop_cli/data/packs/dev-team/skills/sonar-onboard/templates/sonar-project.properties.tmpl

@@ -0,0 +1,31 @@
+# SonarQube project configuration.
+# Host URL and auth token are passed via env vars (SONAR_HOST_URL, SONAR_TOKEN),
+# not committed here — keeps the file portable across forks and local runs.
+
+sonar.projectKey={{PROJECT_KEY}}
+sonar.projectName={{PROJECT_NAME}}
+sonar.projectVersion=1.0
+
+# SonarCloud ONLY — required, set to your SonarCloud organization key.
+# Delete this line for self-hosted SonarQube server.
+sonar.organization={{ORG_KEY}}
+
+# Source layout — comma-separate for multi-language repos.
+sonar.sources={{SOURCES}}
+sonar.tests={{TESTS}}
+
+# Encoding (UTF-8 unless the project has a documented exception).
+sonar.sourceEncoding=UTF-8
+
+# Coverage report — paths are relative to the repo root.
+# Each language has its own importer; uncomment the one(s) you generate.
+# {{COVERAGE_PROPERTY}}={{COVERAGE_PATH}}
+# TODO: wire up coverage in your test step, then uncomment the line above.
+
+# Exclusions — keep the gate honest by skipping generated, vendored, and migration code.
+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}
+
+# New-code period — issues in code changed since this reference are what the gate enforces.
+# Defaults to "previous_version"; override in the Sonar UI per-project if needed.

skilldrop_cli/data/packs/dev-team/skills/sonar-review/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: sonar-review
+description: Run a Sonar scan against the just-changed code on the current branch and produce a structured compliance report — quality-gate verdict (PASS / FAIL), then severity-tagged findings (🟥 blocker / 🟧 critical / 🟨 major / ⚪ minor / ⚪ info) scoped to changed files, each with file:line, the Sonar rule ID, the category (bug / vulnerability / security hotspot / code smell), why it matters, and a concrete fix. Works against both **SonarQube server** (self-hosted) and **SonarCloud** (SaaS) — mode is detected from `sonar-project.properties`. Sister skill to `devils-advocate`, but enforces Sonar's rule catalog and the project's quality gate rather than a hand-rolled lens sweep. Use after writing code, before pushing or opening a PR, when the user says "is this Sonar-compliant?", "run Sonar on this", "will the quality gate pass?", or any pre-merge compliance check.
+---
+
+# sonar-review
+
+You run a Sonar scan against the user's just-changed code and produce a structured pre-merge compliance report. The artifact is a markdown review the user acts on — not raw scanner output, not a quiet "scan complete".
+
+This skill is the **Sonar-flavored counterpart to [`devils-advocate`](../devils-advocate/SKILL.md)**: same shape (severity-tagged findings, file:line evidence, concrete fixes, verdict on top), but the rules come from Sonar's catalog and the verdict comes from the project's quality gate, not your judgment.
+
+Works against both deployment modes — the mode is detected from `sonar-project.properties`, not asked:
+
+| Mode | Detection | Host | Token env |
+|---|---|---|---|
+| **SonarQube server** | No `sonar.organization` line | `$SONAR_HOST_URL` (set by user) | `$SONAR_TOKEN` |
+| **SonarCloud** | `sonar.organization=<key>` present | `https://sonarcloud.io` (fixed) | `$SONAR_TOKEN` |
+
+The API endpoints are identical between the two — only the host differs. If the user is jumping in cold and the repo isn't wired up, run [`sonar-onboard`](../sonar-onboard/SKILL.md) first.
+
+## How to respond
+
+1. **Detect the mode.** First thing — read `sonar-project.properties` and check for a `sonar.organization=` line:
+   - **Present** ⇒ SonarCloud. Host is `https://sonarcloud.io` (don't read `$SONAR_HOST_URL`).
+   - **Absent** ⇒ SonarQube server. Host comes from `$SONAR_HOST_URL`.
+
+   Use the detected mode for every subsequent step. Don't ask the user — the properties file is the source of truth.
+
+2. **Verify the environment before scanning.** Checks differ by mode:
+
+   | Check | Applies to | If missing |
+   |---|---|---|
+   | `sonar-project.properties` at repo root | both | Stop. Tell the user to run `sonar-onboard` first — there's no project config to scan against. |
+   | `sonar-scanner` on `PATH` | both | Stop. Print the install hint (see step 3). Do not attempt to install it. |
+   | `SONAR_TOKEN` env var set | both | Stop. Tell the user to export it from their Sonar account → Security → Tokens. |
+   | `SONAR_HOST_URL` env var set | **server only** | Stop. Tell the user to export it (e.g. `export SONAR_HOST_URL=https://sonar.company.com`). |
+
+   These are non-negotiable. Don't fabricate findings, don't run a partial scan, don't fall back to a local linter — the artifact this skill produces is a *Sonar* report or it's nothing.
+
+3. **Install hint** if `sonar-scanner` is missing — print verbatim, don't drive the install:
+
+   ```
+   sonar-scanner CLI not found on PATH. Install it:
+     macOS:    brew install sonar-scanner
+     Linux:    https://docs.sonarsource.com/sonarqube/latest/analyzing-source-code/scanners/sonarscanner/
+     Docker:   docker run --rm -v "$(pwd):/usr/src" sonarsource/sonar-scanner-cli
+   Then re-run this skill.
+   ```
+
+4. **Identify the change under review.** Same precedence as `devils-advocate`:
+   - User has shown you a diff or named files — that's the scope.
+   - Git working tree has unstaged + uncommitted changes — `git diff` is the scope.
+   - User says "the feature I just built" — run `git diff origin/main...HEAD` (or `HEAD~1` if no upstream).
+
+   The scope is the **set of changed files**, not the whole repo. The scan itself runs against the whole project (Sonar needs the full graph for accurate cross-file analysis), but **findings you report are filtered to changed files only** — anything else is out-of-scope noise.
+
+5. **Set the host variable for the run.** Same logic, both modes:
+
+   ```bash
+   if grep -q '^sonar.organization=' sonar-project.properties; then
+     SONAR_HOST="https://sonarcloud.io"  # SonarCloud is fixed
+   else
+     SONAR_HOST="$SONAR_HOST_URL"        # server reads env var
+   fi
+   ```
+
+   Use `$SONAR_HOST` for both the scanner CLI and the API calls below.
+
+6. **Run the scan.** From the repo root:
+
+   ```bash
+   sonar-scanner \
+     -Dsonar.host.url="$SONAR_HOST" \
+     -Dsonar.token="$SONAR_TOKEN" \
+     -Dsonar.branch.name="$(git rev-parse --abbrev-ref HEAD)"
+   ```
+
+   Note on `sonar.branch.name`: SonarCloud accepts it on all tiers; SonarQube Community Edition does not. If you see `License not valid for branch analysis`, drop the flag and re-run — the scan will overwrite the default branch's history (acceptable for a local pre-merge check, not for CI).
+
+   If the project uses Maven, Gradle, or `dotnet-sonarscanner`, prefer those wrappers (they hook into the compile step) — check `sonar-project.properties` and the build files to decide. See [`reference.md`](reference.md).
+
+   The scan typically takes 30s–3min. **Wait for it.** Do not summarize before results land — a "should pass" guess is worse than waiting.
+
+7. **Fetch the gate status and issues from the Sonar API.** After the scan finishes, the scanner writes `.scannerwork/report-task.txt` with a `ceTaskUrl` — poll it until `status=SUCCESS`, then fetch (same endpoints for server and cloud — only `$SONAR_HOST` differs):
+
+   ```bash
+   PROJECT_KEY=$(grep '^sonar.projectKey=' sonar-project.properties | cut -d= -f2)
+   BRANCH=$(git rev-parse --abbrev-ref HEAD)
+
+   # Quality gate
+   curl -s -u "$SONAR_TOKEN:" \
+     "$SONAR_HOST/api/qualitygates/project_status?projectKey=$PROJECT_KEY&branch=$BRANCH"
+
+   # Issues (scoped to new code in this branch)
+   curl -s -u "$SONAR_TOKEN:" \
+     "$SONAR_HOST/api/issues/search?componentKeys=$PROJECT_KEY&branch=$BRANCH&inNewCodePeriod=true&ps=500"
+
+   # Security hotspots
+   curl -s -u "$SONAR_TOKEN:" \
+     "$SONAR_HOST/api/hotspots/search?projectKey=$PROJECT_KEY&branch=$BRANCH&inNewCodePeriod=true"
+   ```
+
+   Filter the issues list to changed files (compare each issue's `component` field against the diff). See [`reference.md`](reference.md) for the exact JSON shapes.
+
+8. **Map Sonar severities to the report's severity markers.** Keep the mapping consistent across reports:
+
+   | Sonar severity | Marker | Meaning in the report |
+   |---|---|---|
+   | `BLOCKER` | 🟥 **Blocker** | Will ship a bug or security issue. Must fix before merge. |
+   | `CRITICAL` | 🟧 **Critical** | High-impact bug, hotspot, or vulnerability that needs review before merge. |
+   | `MAJOR` | 🟨 **Major** | Code smell or quality issue that will hurt within months. Fix before merge if reasonable. |
+   | `MINOR` | ⚪ **Minor** | Quality nit. Fine to defer. |
+   | `INFO` | ⚪ **Info** | Optional. List only if there are < 5 of them; otherwise summarize the count. |
+
+   **Do not invent severity.** Sonar's catalog assigns it — copy it. The mapping is mechanical, not judgmental.
+
+9. **Sweep the five lenses.** Sonar categorizes every finding into one of these — group the report by lens, same as `devils-advocate`. Each lens file describes what to look for and how to phrase the fix:
+
+   | Lens | File | Sonar issue type |
+   |---|---|---|
+   | 1. Bugs | [`lenses/bugs.md`](lenses/bugs.md) | `BUG` |
+   | 2. Vulnerabilities | [`lenses/vulnerabilities.md`](lenses/vulnerabilities.md) | `VULNERABILITY` |
+   | 3. Security hotspots | [`lenses/security-hotspots.md`](lenses/security-hotspots.md) | `SECURITY_HOTSPOT` (separate API) |
+   | 4. Code smells | [`lenses/code-smells.md`](lenses/code-smells.md) | `CODE_SMELL` |
+   | 5. Coverage + duplication | [`lenses/coverage-and-duplication.md`](lenses/coverage-and-duplication.md) | Quality-gate condition failures |
+
+10. **For every finding, write four parts** (same shape as `devils-advocate`):
+
+   - **Where:** `file:line` — quote 5–15 chars of the offending line.
+   - **Rule + category:** `[BUG · javascript:S2228] Console logging should not be used`. The rule ID is what the user clicks in the Sonar UI to read the catalog page.
+   - **Why it matters:** one sentence — what the rule prevents *in this scenario*. ✅ "Mutable shared state in `parseConfig` will desync between requests under concurrent load." ❌ "Avoid shared state."
+   - **Fix:** ✅ "Wrap the cache in `Object.freeze()` on line 23, or move the mutable copy inside `parseConfig` (preferred — matches the pattern in `parseUserConfig`:51)." ❌ "Refactor to avoid mutation."
+
+11. **Open with the gate verdict, not the findings.** The first thing the user sees:
+
+   ```
+   Quality gate: ❌ FAIL — coverage on new code is 71% (gate requires ≥ 80%), 1 new vulnerability.
+   Findings on changed code: 1 blocker · 3 critical · 7 major · 4 minor.
+
+   The blocker is a SQL-injection-shaped query construction at api/users.ts:142 (rule javascriptsecurity:S3649) — parameterize before merging. The vulnerability and the coverage shortfall are what's failing the gate; the major findings are all in the new payment-handler module and are fixable with the patterns used elsewhere in the codebase.
+   ```
+
+   If the gate passed, lead with that and still report findings (a passing gate doesn't mean zero issues — it means the *new code* met the conditions; minor findings may still be worth fixing).
+
+12. **Use [`templates/report.md`](templates/report.md)** for the output structure:
+
+    ```markdown
+    # Sonar review: {feature / PR title}
+    _Scope: {N changed files} · Branch: {branch} · Scanned: {YYYY-MM-DD HH:MM}_
+    _Sonar project: [{project-key}]({sonar-url}/dashboard?id={project-key}&branch={branch})_
+
+    ## Quality gate
+    {PASS / FAIL} — {one-line reason}
+    {2-sentence summary, lead with what failed the gate}
+
+    ## Findings on changed code
+    {counts table}
+
+    ### 1. Bugs
+    ### 2. Vulnerabilities
+    ### 3. Security hotspots
+    ### 4. Code smells
+    ### 5. Coverage + duplication
+
+    ## Pre-existing issues touched (FYI)
+    {issues in files you changed that pre-date this branch — for awareness, not blocking}
+
+    ## Suggested order to address
+    1. Fix anything failing the quality gate (blockers + vulnerabilities + coverage)
+    2. Review the security hotspots — Sonar can't auto-decide, you have to mark them
+    3. Major findings, especially anything in load-bearing or security-adjacent code
+    4. Minors as time allows
+    ```
+
+13. **End with the Sonar dashboard link.** The full picture — including pre-existing debt, history, and the gate's detailed conditions — lives in the Sonar UI. Always end with `Full report: ${SONAR_HOST}/dashboard?id=<project-key>&branch=<branch>` — `$SONAR_HOST` is the value you set in step 5 (so the link works whether the project is on SonarQube server or SonarCloud).
+
+## Useful references in this skill
+
+- [`lenses/bugs.md`](lenses/bugs.md) — how to phrase Bug findings
+- [`lenses/vulnerabilities.md`](lenses/vulnerabilities.md) — Vulnerability findings (CWE / OWASP-tagged)
+- [`lenses/security-hotspots.md`](lenses/security-hotspots.md) — Hotspots need human review, not auto-fix
+- [`lenses/code-smells.md`](lenses/code-smells.md) — Maintainability findings
+- [`lenses/coverage-and-duplication.md`](lenses/coverage-and-duplication.md) — Gate conditions that aren't issues
+- [`templates/report.md`](templates/report.md) — Report skeleton
+- [`reference.md`](reference.md) — Sonar API shapes, Maven/Gradle/dotnet variants, scoping to PR diffs
+
+## Quality bar
+
+- **Verdict comes from the gate, not from you.** The quality gate is the source of truth. ✅ "Gate FAIL — 1 new vulnerability." ❌ "Looks risky to me." If the gate passed, say PASS even if you'd personally flag issues.
+- **Findings are scoped to changed files.** The repo has pre-existing debt; this skill is a pre-merge check, not a backlog dump. Pre-existing issues in *touched* files go in a separate "FYI" section — issues in untouched files don't appear at all.
+- **Every finding cites `file:line` and the Sonar rule ID.** `javascript:S2228` is a click-through to the Sonar UI catalog. Strip either and the finding becomes unactionable.
+- **Severity is Sonar's, not yours.** Don't downgrade a `CRITICAL` because you disagree, and don't upgrade a `MINOR` to make the report scarier. If you disagree with the catalog, raise it in the lens body, don't rewrite the severity.
+- **Fixes name a concrete change.** A patch line, a function rename, a missing test case — not "consider refactoring".
+- **Don't recommend disabling rules to pass the gate.** That's a code-quality conversation. Suggest fixes or scoping (Sonar-scoping comments like `// NOSONAR` should be rare and justified in the code, not as a default).
+- **Security hotspots are flagged for review, not "fixed".** Hotspots ask "is this safe?" — the resolution is a human decision (mark Safe, At Risk, Acknowledged). The fix you write is *the evidence the user needs to make that call*, not a code patch.
+
+## When to use this skill
+
+- ✅ After implementing a feature, before opening a PR ("is this Sonar-compliant?")
+- ✅ When CI shows a failed Sonar gate and the user wants the findings explained locally before pushing again
+- ✅ Before merging a long-lived branch back to main — final gate check
+- ✅ Sanity check after rebasing onto main, to catch newly-applied rules
+
+## When NOT to use this skill
+
+- ❌ Repo isn't set up for Sonar (no `sonar-project.properties`). Run `sonar-onboard` first.
+- ❌ User wants a code review broader than Sonar's catalog covers (architecture, idiomatic concerns, test-design). Use `devils-advocate` instead — different lens.
+- ❌ User wants to fix the *whole codebase*'s Sonar debt. This skill is per-change; for a debt-paydown plan, query the Sonar UI directly.
+- ❌ Repo only has linters (ESLint, Pylint, golangci-lint) and no Sonar. Different tool, different catalog — running this skill would produce nothing.
+- ❌ Repo isn't wired to *either* SonarQube server or SonarCloud — no `sonar-project.properties` means there's nothing to scan against. Run `sonar-onboard` first.
+
+## Anti-patterns to avoid
+
+- ❌ **Guessing the gate result.** Always wait for the actual scan + API call. A "should pass" prediction without the scan is the worst possible output — it builds false confidence.
+- ❌ **Reporting issues from untouched files.** The user opened a PR for one feature; flooding them with debt from other files is noise. Scope strictly to changed files; pre-existing-in-touched-files go in the FYI section.
+- ❌ **Translating rule IDs into prose.** Keep `javascript:S2228` literal — that's the click-through key. ❌ "Use of console logging" ✅ "[javascript:S2228] Use of console logging".
+- ❌ **Suggesting `// NOSONAR` as the default fix.** That's "make the linter shut up", not compliance. Reserve for documented exceptions with a comment explaining why.
+- ❌ **Auto-fixing the code.** This skill produces a *report*. The user (or another agent / skill) decides what to change. Auto-fixes hide the learning and the audit trail.
+- ❌ **Hiding the FAIL.** If the gate fails, lead with FAIL. Don't bury it under "but here's what's good" — the user opened this skill to know whether they can merge.
+- ❌ **Treating security hotspots as bugs.** Hotspots are *review-required*; the resolution is human judgment. Show the evidence, then ask the user to mark Safe / At Risk / Acknowledged — don't patch them silently.

skilldrop_cli/data/packs/dev-team/skills/sonar-review/evals/eval_queries.json

@@ -0,0 +1,34 @@
+[
+  {
+    "query": "Run a Sonar review on this branch",
+    "should_trigger": true
+  },
+  {
+    "query": "What does the quality gate say about my changes?",
+    "should_trigger": true
+  },
+  {
+    "query": "Give me the Sonar findings for the files I changed",
+    "should_trigger": true
+  },
+  {
+    "query": "Check Sonar compliance before I open the PR",
+    "should_trigger": true
+  },
+  {
+    "query": "Set up Sonar in this repository",
+    "should_trigger": false
+  },
+  {
+    "query": "Review this code adversarially for edge cases the first pass missed",
+    "should_trigger": false
+  },
+  {
+    "query": "Run the full pre-merge gate and reviewer panel",
+    "should_trigger": false
+  },
+  {
+    "query": "Write the postmortem for last night's incident",
+    "should_trigger": false
+  }
+]

skilldrop_cli/data/packs/dev-team/skills/sonar-review/evals/evals.json

@@ -0,0 +1,16 @@
+{
+  "skill_name": "sonar-review",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Run a Sonar review on my current branch before I open the PR.",
+      "assertions": [
+        "The verdict is taken from the quality gate itself, not from the reviewer's own judgment — PASS is reported as PASS even if other issues are visible",
+        "Findings are scoped to files changed on the branch; pre-existing repo debt is not dumped into the report",
+        "Findings are severity-tagged and each carries file:line, the Sonar rule ID, why it matters, and a concrete fix",
+        "Findings are grouped into the lenses (bugs, vulnerabilities, security hotspots, code smells, coverage/duplication)",
+        "Server vs cloud is auto-detected from sonar-project.properties rather than assumed"
+      ]
+    }
+  ]
+}