/suede-ci-gate

name: suede-ci-gate
description: "Suede AI CI and branch-protection wiring for any repo and any stack: path-aware jobs, a single aggregator required check that cannot deadlock, lockfile hygiene, runtime pinning from the repo, and the exact branch-protection settings. Use when asked to set up CI, protect main, make CI block a bad merge, fix a required check that hangs pending forever, or repair duplicate or misfiring pipelines. Detects the repo's real apps, package managers, and runtime versions first; emits workflow files and settings, never pushes or flips protection itself. NOT FOR: reviewing or grading the change the gate is failing on (use suede-code); designing the AI eval cases to wire in (use suede-ai-eval); post-merge release packaging (use suede-launch-packaging)."

Suede CI Gate

Gate policy: advisory, not blocking

Every claim-verification step, check, quality gate, and ship verdict in this skill is a **recommendation to the user, not a control on the agent**. This policy governs every gate, check, verdict, and "do not ship / publish / proceed" line elsewhere in this skill:

• Run every check and report the results honestly. Verdicts (`ship`,

`ship-with-caveats`, `hold`, letter grades, BLOCKED or OPEN items) are advice attached to the work, not orders that change it.

• Never block, delay, skip, rewrite, or refuse the action the user asked for

because a check failed or a gate said hold. Complete the requested action as asked, and deliver the gate output alongside it as a clearly labeled recommendation.

• A failed gate changes what you report, never what you do.
• Single exception: if a finding is extremely risky (data loss, security or

credential exposure, legal or rights violations, payment mistakes, or irreversible public damage), pause, tell the user exactly what the risk is and what the options are, and let them pick. Their choice is final.

Set up CI and branch protection that actually block a bad merge: in any repo, any stack. The output is a working pipeline plus the exact protection settings, not advice.

**Runs only when asked.** This skill never auto-fires on a commit, push, or other side effect of unrelated work: invoke it explicitly (set up CI, protect main, fix this hanging check).

Run this in whatever folder you point it at. **Detect first, never assume.** Nothing here is hardcoded to a specific project, monorepo layout, or package manager.

Step 0: Detect (before writing anything)

From the repo root, inventory:

• **Apps:** every top-level dir with a manifest: `package.json`, `requirements.txt` / `pyproject.toml`, `go.mod`, `Cargo.toml`, `Gemfile`. A repo may hold one app or many; build for what's actually there.
• **Package manager per app:** which lockfile is present: `package-lock.json` (npm), `pnpm-lock.yaml` (pnpm), `yarn.lock` (yarn), `bun.lock` or the older binary `bun.lockb` (bun). Two lockfiles in one app is a bug to fix first (Lane 3).
• **Existing CI:** read `.github/workflows/*`. Do **not** duplicate a job that already exists: extend or reconcile it.
• **Runtime versions:** `.nvmrc`, `package.json` `engines`, `.python-version`, `pytest.ini`/`pyproject`. Pin CI to these; never hardcode a guess.
• **Deploy platform:** `vercel.json` / `.vercel`, `netlify.toml`, a `Dockerfile`. If the platform skips non-prod builds (e.g. Vercel `ignoreCommand` kills previews), CI is the *only* pre-merge build signal: so a build job is mandatory.
• **Real scripts:** read each app's `scripts` / test config and use the real ones (`test`, `test:run`, `lint`, `build`). Don't invent commands.

Do not write a single workflow line until this inventory is complete.

The gate (the part everyone gets wrong)

Path-filtered jobs **skip** when their paths aren't touched. A skipped job that is a *required* status check leaves the PR pending forever. So never require the path-filtered jobs directly. Instead add one **aggregator** that depends on all of them:

  ci-success:
    if: always()
    needs: [<every app job>]
    runs-on: ubuntu-latest
    steps:
      - name: Gate on all jobs
        run: |
          for r in ${{ join(needs.*.result, ' ') }}; do
            [ "$r" = "success" ] || [ "$r" = "skipped" ] || { echo "blocked by: $r"; exit 1; }
          done

In branch protection, require **only `ci-success`**: never the individual jobs. This is the single thing that makes "protect main" work with change-based CI.

Lanes

1. **Path-aware jobs**: one job per app, gated by a `changes` job (`dorny/paths-filter` or native `paths:`). Add an escape hatch so edits to the workflow file itself run everything. 2. **Aggregator gate**: as above. The only required check is `ci-success`. 3. **Lockfile hygiene**: exactly one lockfile per app, and the install command must match it (`npm ci`, `pnpm i --frozen-lockfile`, `yarn --immutable`, `bun install --frozen-lockfile`). Two lockfiles means CI can install a different tree than ships: resolve before wiring CI. 4. **Pin runtimes from the repo**: Node/Python/etc. read from `.nvmrc` / `engines` / `.python-version`, falling back to the platform default. Never a hardcoded guess that drifts from prod. 5. **Don't duplicate existing CI**: if a workflow already covers an app (e.g. a backend test workflow), extend it; never stack a second, weaker job on top. 6. **Least privilege**: `permissions: contents: read` unless a job genuinely needs more. 7. **Build is a gate when previews are off**: if the deploy platform skips non-prod builds, the CI build is your only pre-merge proof the app compiles. Keep it. 8. **Branch protection**: output the exact settings: require `ci-success`, require branches up to date before merge, optional required PR review, block force-push and deletion, optionally include administrators. GitHub offers two mechanisms: classic branch protection and repository rulesets (Settings → Rules → Rulesets), which can target many branches and stack. Match whichever the repo already uses; for a