@dsalazardev/ai-hub-cli 0.0.0-stage → 0.1.0

package/skills/shared/git-workflow/references/gitmoji.md

@@ -0,0 +1,157 @@
+# gitmoji — the full set, and the tooling that has to accept it
+
+The commit rule lives in `../SKILL.md`: **every commit opens with a gitmoji, then the
+Conventional Commits header.** This file is the lookup table and the tooling escape hatches — read
+it when you need the right glyph for an intention, or when a parser in the repo rejects the format.
+
+```text
+<gitmoji> type(scope)!: imperative subject
+```
+
+The gitmoji says *what kind of intention* this is at a glance in `git log --oneline`; the `type`
+still drives the SemVer bump. They are two different jobs and neither replaces the other — a commit
+with 💥 but no `!`/`BREAKING CHANGE:` footer still releases as a MINOR, because tooling reads the
+type, not the picture.
+
+## Picking one
+
+Match the **intention**, not the file that changed. If two fit, take the more specific one (🚑️ over
+🐛 for a production hotfix; 🩹 over 🐛 for a trivial non-critical fix). The `semver` column is
+gitmoji's own hint, not a substitute for the type → bump table in `../SKILL.md`.
+
+The everyday dozen, mapped to the conventional types:
+
+| Type       | gitmoji | Type        | gitmoji |
+|------------|---------|-------------|---------|
+| `feat`     | ✨      | `perf`      | ⚡️      |
+| `fix`      | 🐛      | `ci`        | 👷      |
+| `docs`     | 📝      | `build`     | 📦️      |
+| `refactor` | ♻️      | `style`     | 🎨      |
+| `test`     | ✅      | `revert`    | ⏪️      |
+| `chore`    | 🔧      | breaking    | 💥      |
+
+## The full set
+
+Canonical source: <https://gitmoji.dev> (machine-readable at `https://gitmoji.dev/api/gitmojis`).
+The same 75 rows are enforced as data by the gitmoji guard, and a test compares this table against
+it — if the two ever disagree, CI says so.
+
+| Emoji | Code | SemVer | Intention |
+|-------|------|--------|-----------|
+| 🎨 | `:art:` | — | Improve structure / format of the code |
+| ⚡️ | `:zap:` | patch | Improve performance |
+| 🔥 | `:fire:` | — | Remove code or files |
+| 🐛 | `:bug:` | patch | Fix a bug |
+| 🚑️ | `:ambulance:` | patch | Critical hotfix |
+| ✨ | `:sparkles:` | minor | Introduce new features |
+| 📝 | `:memo:` | — | Add or update documentation |
+| 🚀 | `:rocket:` | — | Deploy stuff |
+| 💄 | `:lipstick:` | patch | Add or update the UI and style files |
+| 🎉 | `:tada:` | — | Begin a project |
+| ✅ | `:white_check_mark:` | — | Add, update, or pass tests |
+| 🔒️ | `:lock:` | patch | Fix security or privacy issues |
+| 🔐 | `:closed_lock_with_key:` | — | Add or update secrets |
+| 🔖 | `:bookmark:` | — | Release / Version tags |
+| 🚨 | `:rotating_light:` | — | Fix compiler / linter warnings |
+| 🚧 | `:construction:` | — | Work in progress |
+| 💚 | `:green_heart:` | — | Fix CI Build |
+| ⬇️ | `:arrow_down:` | patch | Downgrade dependencies |
+| ⬆️ | `:arrow_up:` | patch | Upgrade dependencies |
+| 📌 | `:pushpin:` | patch | Pin dependencies to specific versions |
+| 👷 | `:construction_worker:` | — | Add or update CI build system |
+| 📈 | `:chart_with_upwards_trend:` | patch | Add or update analytics or track code |
+| ♻️ | `:recycle:` | — | Refactor code |
+| ➕ | `:heavy_plus_sign:` | patch | Add a dependency |
+| ➖ | `:heavy_minus_sign:` | patch | Remove a dependency |
+| 🔧 | `:wrench:` | patch | Add or update configuration files |
+| 🔨 | `:hammer:` | — | Add or update development scripts |
+| 🌐 | `:globe_with_meridians:` | patch | Internationalization and localization |
+| ✏️ | `:pencil2:` | patch | Fix typos |
+| 💩 | `:poop:` | — | Write bad code that needs to be improved |
+| ⏪️ | `:rewind:` | patch | Revert changes |
+| 🔀 | `:twisted_rightwards_arrows:` | — | Merge branches |
+| 📦️ | `:package:` | patch | Add or update compiled files or packages |
+| 👽️ | `:alien:` | patch | Update code due to external API changes |
+| 🚚 | `:truck:` | — | Move or rename resources (e.g.: files, paths, routes) |
+| 📄 | `:page_facing_up:` | — | Add or update license |
+| 💥 | `:boom:` | major | Introduce breaking changes |
+| 🍱 | `:bento:` | patch | Add or update assets |
+| ♿️ | `:wheelchair:` | patch | Improve accessibility |
+| 💡 | `:bulb:` | — | Add or update comments in source code |
+| 🍻 | `:beers:` | — | Write code drunkenly |
+| 💬 | `:speech_balloon:` | patch | Add or update text and literals |
+| 🗃️ | `:card_file_box:` | patch | Perform database related changes |
+| 🔊 | `:loud_sound:` | — | Add or update logs |
+| 🔇 | `:mute:` | — | Remove logs |
+| 👥 | `:busts_in_silhouette:` | — | Add or update contributor(s) |
+| 🚸 | `:children_crossing:` | patch | Improve user experience / usability |
+| 🏗️ | `:building_construction:` | — | Make architectural changes |
+| 📱 | `:iphone:` | patch | Work on responsive design |
+| 🤡 | `:clown_face:` | — | Mock things |
+| 🥚 | `:egg:` | patch | Add or update an easter egg |
+| 🙈 | `:see_no_evil:` | — | Add or update a .gitignore file |
+| 📸 | `:camera_flash:` | — | Add or update snapshots |
+| ⚗️ | `:alembic:` | patch | Perform experiments |
+| 🔍️ | `:mag:` | patch | Improve SEO |
+| 🏷️ | `:label:` | patch | Add or update types |
+| 🌱 | `:seedling:` | — | Add or update seed files |
+| 🚩 | `:triangular_flag_on_post:` | patch | Add, update, or remove feature flags |
+| 🥅 | `:goal_net:` | patch | Catch errors |
+| 💫 | `:dizzy:` | patch | Add or update animations and transitions |
+| 🗑️ | `:wastebasket:` | patch | Deprecate code that needs to be cleaned up |
+| 🛂 | `:passport_control:` | patch | Work on code related to authorization, roles and permissions |
+| 🩹 | `:adhesive_bandage:` | patch | Simple fix for a non-critical issue |
+| 🧐 | `:monocle_face:` | — | Data exploration/inspection |
+| ⚰️ | `:coffin:` | — | Remove dead code |
+| 🧪 | `:test_tube:` | — | Add a failing test |
+| 👔 | `:necktie:` | patch | Add or update business logic |
+| 🩺 | `:stethoscope:` | — | Add or update healthcheck |
+| 🧱 | `:bricks:` | — | Infrastructure related changes |
+| 🧑‍💻 | `:technologist:` | — | Improve developer experience |
+| 💸 | `:money_with_wings:` | — | Add sponsorships or money related infrastructure |
+| 🧵 | `:thread:` | — | Add or update code related to multithreading or concurrency |
+| 🦺 | `:safety_vest:` | — | Add or update code related to validation |
+| ✈️ | `:airplane:` | — | Improve offline support |
+| 🦖 | `:t-rex:` | — | Code that adds backwards compatibility |
+## Tooling that has to accept the format
+
+Emoji-first is what gitmoji itself prescribes and what `gitmoji -c` writes, but a **strict
+Conventional Commits parser anchors the type at position 0** and will reject the header. Two honest
+ways out, in order of preference:
+
+**1. Teach the parser about the prefix.** commitlint, with the emoji allowed before the type:
+
+```js
+// commitlint.config.js
+export default {
+  extends: ['@commitlint/config-conventional'],
+  parserPreset: {
+    parserOpts: {
+      // <emoji> type(scope)!: subject
+      headerPattern: /^(?:\S+\s)?(\w+)(?:\(([^)]*)\))?(!)?: (.+)$/,
+      headerCorrespondence: ['type', 'scope', 'breaking', 'subject'],
+    },
+  },
+};
+```
+
+semantic-release / conventional-changelog take the same `parserOpts` under
+`@semantic-release/commit-analyzer` and `@semantic-release/release-notes-generator`. Set it in
+**both** or the bump and the changelog disagree about the same commit.
+
+**2. Put the emoji after the header** — `feat(api): ✨ add cursor paging`. Every conventional parser
+accepts it unmodified, and the guard accepts it too. Prefer this in a repo whose release pipeline
+you do not own.
+
+What **not** to do: drop the type and commit `✨ add cursor paging` (gitmoji's own minimal form).
+It is valid gitmoji and useless for releases — nothing can derive the bump, so the version has to be
+hand-picked, which `../SKILL.md` forbids for a reason.
+
+## Related
+
+- `gitmoji-cli` (`npm i -g gitmoji-cli`, then `gitmoji -c`) prompts for the emoji and writes the
+  commit. Optional — the convention is the rule, the CLI is one way to type it.
+- On Claude Code, ai-hub wires a `gitmoji-guard` PreToolUse hook that denies a `git commit` whose
+  message has no gitmoji, with the corrected message in the refusal. It only judges messages it can
+  actually read (`-m`, heredoc) and never blocks an editor commit, a `-F` file, or `--amend
+  --no-edit`. Opt out per project with `.ai-hub/.no-gitmoji`.

package/skills/shared/git-workflow/references/interactive-rebase.md

@@ -0,0 +1,89 @@
+# Interactive rebase — cleaning history before review
+
+The everyday path is one clean conventional commit per change. Reach for this only when a branch has
+accumulated scratch commits you need to collapse, reorder, reword, or drop before a PR. This is a
+private-branch operation: only rewrite history nobody else has built on.
+
+## Start the rebase
+
+```bash
+git rebase -i HEAD~4        # edit the last 4 commits
+git rebase -i main          # replay everything since main; clean the whole branch narrative
+```
+
+Git opens a todo list, oldest commit first. Each line starts with a verb you can change:
+
+| Verb         | Effect                                                            |
+|--------------|-------------------------------------------------------------------|
+| `pick`       | keep the commit as-is                                             |
+| `reword` (r) | keep the changes, edit the message (fix a non-conventional subject) |
+| `edit` (e)   | pause at this commit to amend its content                        |
+| `squash` (s) | fold into the previous commit, **combine** both messages         |
+| `fixup` (f)  | fold into the previous commit, **discard** this message          |
+| `drop` (d)   | delete the commit entirely (its changes are removed)             |
+| reorder      | move a line up/down to reorder commits                           |
+
+Typical cleanup: turn two `wip` commits into `fixup` lines under the real commit they belong to, and
+`reword` the survivor into a proper `type(scope): subject`.
+
+```text
+pick   a1b2c3d feat(auth): add PKCE flow
+fixup  d4e5f6a wip
+fixup  7g8h9i0 wip more
+```
+
+## Autosquash — the disciplined way
+
+If you mark fixups *as you go*, the rebase organizes itself:
+
+```bash
+git commit --fixup a1b2c3d          # creates "fixup! feat(auth): add PKCE flow"
+git commit --squash a1b2c3d         # same, but keeps the message for editing
+git rebase -i --autosquash main     # auto-orders the fixup!/squash! lines under their targets
+```
+
+Set `git config --global rebase.autosquash true` to make `--autosquash` the default.
+
+## The conflict loop
+
+A rebase replays commits one at a time, so a conflict can surface on any of them:
+
+```bash
+# rebase stops, reports a conflict
+git status                  # see which files conflict
+# edit the files, resolve the <<<<<<< markers
+git add <resolved-files>
+git rebase --continue       # advance to the next commit
+# repeat until the rebase finishes
+```
+
+Escape hatches:
+
+```bash
+git rebase --skip           # drop the current commit and continue (rare; you lose its changes)
+git rebase --abort          # bail out entirely — branch returns to its pre-rebase state
+```
+
+## Push the rewritten branch
+
+A rebase rewrites hashes, so the remote branch diverges. Push with the lease, never bare force:
+
+```bash
+git push --force-with-lease     # refuses if the remote moved since your last fetch
+```
+
+If `--force-with-lease` is rejected, someone pushed to your branch — fetch and reconcile before you
+overwrite anything. Do not escalate to `--force`.
+
+## Recovery — you have a net
+
+Every commit you "lost" to a rebase is still reachable until git garbage-collects it. `reflog` records
+where `HEAD` has been:
+
+```bash
+git reflog                          # find the SHA from before the rebase, e.g. HEAD@{5}
+git reset --hard a1b2c3d            # restore the branch to that exact state
+```
+
+This recovers a botched rebase, a wrong `drop`, or a reset you regret. The reflog makes interactive
+rebase safe to experiment with on a *private* branch — never on shared history.

package/skills/shared/github-actions/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: github-actions
+description: "Use when authoring or fixing GitHub Actions CI/CD — workflows under .github/workflows, triggers, job matrix, caching, token permissions, OIDC cloud deploys, environment gates, reusable workflows. NOT the Dockerfile or image build strategy (that is `docker`), NOT the branching model (that is `git-workflow`), NOT release readiness (that is `ship`)."
+tags: [github-actions, ci-cd, workflows, oidc, caching]
+recommends: [docker, git-workflow, ship, deployment, secure-coding, aws-essentials, vercel]
+origin: ai-hub
+---
+
+# GitHub Actions CI/CD
+
+A workflow is config that runs on an event. Before you write a single step, decide three things: **which events** fire the workflow, **what permissions** the token needs, and **where credentials come from**. Get those wrong and you have a fast pipeline that leaks secrets or a secure one nobody can trigger. Everything after that — checkout, install, test, build — is just steps.
+
+This skill owns the workflow layer — the `.github/workflows/*.yml` files, their triggers, jobs, matrix, caching, secret/OIDC handling, environments and deploy gates. Route the rest out:
+
+| Not this skill | Goes to | Because |
+| --- | --- | --- |
+| The `Dockerfile`, image build strategy | `../docker/SKILL.md` | The workflow may *call* `docker build`; designing the image is not this skill. |
+| Branching model, PR hygiene, merge vs rebase, commit conventions | `../git-workflow/SKILL.md` | That is the source-control model, not the CI config layer. |
+| Release readiness checklist, changelog, the shipping decision | `../ship/SKILL.md` | Whether to release is a decision; this skill only automates the mechanics. |
+| Blue/green, canary, rollback *theory* | `../deployment/SKILL.md` | Actions triggers the deploy; the strategy is deployment's. |
+| Choosing the host and its deploy primitives | `../vercel/SKILL.md`, `../aws-essentials/SKILL.md` | Actions *triggers* the deploy; the host owns the target. |
+| Triaging SAST/CVE findings, threat modeling | `../secure-coding/SKILL.md` | This skill runs a scanner *as a job*; it does not interpret the report. |
+
+## Decide the trigger first
+
+Pick the event(s) for each job class before writing YAML — the trigger decides what context and secrets the run gets.
+
+| Event | Use it for | Why |
+| --- | --- | --- |
+| `pull_request` | lint, test, build-check | Runs on the merge ref; from forks it gets **no secrets** (safe). |
+| `push` (to `main`) | deploy, publish artifacts, build the release | The trusted ref with full secrets/OIDC. |
+| `workflow_dispatch` | manual ops, one-off backfills, manual deploys | Human-triggered with inputs; auditable. |
+| `schedule` (cron) | nightly builds, dependency audits, cache warmers | Cron in UTC; no human in the loop. |
+| `release` / `push` tags | publish to a registry, cut a GitHub Release | Fires on the tag, not every commit. |
+| `workflow_call` | reusable workflow invoked by others | Library of jobs; never runs on its own. |
+| `pull_request_target` | label/comment bots that need write on forks | **Runs trusted with secrets** — never check out PR head here. |
+
+Do **not** run the same heavy job on both `push` and `pull_request` for the same commit — you pay runner minutes twice. Use `pull_request` for the checks and a separate `push: branches: [main]` job for deploy.
+
+## Anatomy of a CI workflow
+
+The minimal good CI: scoped trigger, read-only token, concurrency that cancels stale PR runs, built-in cache.
+
+```yaml
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read            # least privilege; widen per-job only when needed
+
+concurrency:
+  group: ci-${{ github.ref }}      # one run per branch/PR
+  cancel-in-progress: true         # newer push kills the stale run (PR feedback)
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6        # first-party, current major
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: npm                     # built-in lockfile-keyed cache
+      - run: npm ci                       # not install — fails on a stale lockfile, reproducible
+      - run: npm run lint
+      - run: npm test
+```
+
+Why those three lines are not optional:
+- `permissions: contents: read` at the top — **default token permissions may be write**, and a leaked write token can push tags or publish packages. Widen per job and only to what that job needs (`packages: write` to publish, `id-token: write` for OIDC), never at the top.
+- `concurrency` + `cancel-in-progress: true` — without it every push to an open PR leaves the old run finishing and billing. One group per ref keeps at most one running + one pending.
+- `actions/checkout@v6`, `setup-node@v6` are the current majors (checkout v6.0.2, setup-node v6.4.0). Old majors run on Node 20, removed from runners in **September 2026**; JS actions are forced onto **Node 24** by default since June 2026.
+
+## Caching
+
+Two mechanisms, in order of preference:
+
+1. **Built-in `cache:` on `setup-*`** — `setup-node`, `setup-python`, `setup-go`, etc. cache the package manager's store keyed on the lockfile. Free, one line. Use it.
+2. **`actions/cache@v4`** — for anything else (build output, custom tool dirs, compiled artifacts).
+
+The cache key is the whole game. A cache is **immutable once written for a key** — if your key never changes, you cache stale deps forever.
+
+```yaml
+# Bad — fixed key never invalidates; you restore yesterday's broken node_modules forever
+- uses: actions/cache@v4
+  with:
+    path: ~/.npm
+    key: npm-cache
+
+# Good — key changes when the lockfile changes; restore-keys gives a warm partial hit
+- uses: actions/cache@v4
+  with:
+    path: ~/.npm
+    key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+    restore-keys: |
+      ${{ runner.os }}-npm-
+```
+
+`restore-keys` is a prefix fallback: an exact-key miss still restores the most recent cache whose key starts with the prefix, so a one-package change does not cold-start. Monorepo keys, Docker layer caching (`type=gha`), and runner-minute cost tradeoffs live in `references/caching-and-matrix.md`.
+
+## Matrix
+
+Run one job definition across combinations — OS x version is the common case.
+
+```yaml
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false            # see all combos' results, not just the first failure
+      max-parallel: 4
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        node: [20, 22, 24]
+        exclude:
+          - os: macos-latest      # don't pay the macOS multiplier on every version
+            node: 20
+        include:
+          - os: ubuntu-latest     # one extra cell: lint only on the canonical combo
+            node: 24
+            lint: true
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with: { node-version: "${{ matrix.node }}", cache: npm }
+      - run: npm ci && npm test
+```
+
+Set `fail-fast: false` when you want every combination's verdict (a compatibility matrix); leave it `true` (default) when one failure should abort the rest to save minutes. macOS and Windows runners bill at a multiple of Linux minutes — `exclude` the cells you do not need.
+
+## Secrets and OIDC — the security heart
+
+The rule: **no long-lived cloud keys in repo secrets.** Use OIDC. GitHub mints a short-lived JWT per run; AWS/Azure/GCP exchange it for a token scoped to that job, valid for minutes. Nothing static to steal — by 2026, static CI credentials are a compliance violation in regulated orgs.
+
+```yaml
+# Bad — static AWS keys live in the repo forever; one leak = standing access
+- uses: aws-actions/configure-aws-credentials@v4
+  with:
+    aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
+    aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+
+# Good — OIDC: no stored keys, the role is assumed for this run only
+permissions:
+  id-token: write       # required for GitHub to mint the OIDC JWT
+  contents: read
+steps:
+  - uses: aws-actions/configure-aws-credentials@<full-40-char-sha>
+    with:
+      role-to-assume: arn:aws:iam::123456789012:role/gh-deploy
+      aws-region: eu-west-1
+```
+
+Hard rules:
+- **Never `echo` a secret** or pass it to an untrusted step. Secrets are masked in logs, but a third-party action or a crafted `printf` can exfiltrate them.
+- **Scope the cloud trust to repo + ref (+ environment).** The common 2026 misconfig is a trust policy with `repo:ORG/*` — that lets *any* repo in the org assume your prod role. Scope `sub` to `repo:ORG/REPO:ref:refs/heads/main` or `environment:production`.
+- **Gate prod with an `environment` + required reviewers** so a human approves before the deploy job runs.
+
+Per-cloud trust setup (AWS role, GCP Workload Identity Federation, Azure federated credentials), the over-permissioned-trust footgun, and a full deploy-on-tag workflow with approval are in `references/oidc-deploys.md`.
+
+## Supply chain and least privilege
+
+- **SHA-pin third-party actions to a full 40-char commit SHA, not a tag.** Tags are mutable: the **tj-actions/changed-files compromise (2025)** retargeted *all* tags to malicious code that dumped secrets. A SHA is the only immutable reference. GitHub now offers repo/org/enterprise policy to *enforce* full-SHA pinning across the whole tree.
+
+  ```yaml
+  # Bad — mutable tag; whoever controls the repo can repoint v1 at anything
+  - uses: some-org/some-action@v1
+  # Good — immutable, with a comment recording the human-readable version
+  - uses: some-org/some-action@a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0  # v1.4.2
+  ```
+
+  First-party `actions/*` and `github/*` may stay on a major tag (GitHub controls them), but pinning everything is the stronger posture.
+- **`pull_request_target` + checking out the PR head = remote code execution with your secrets.** That trigger runs in the *base* repo's trusted context. If you then `checkout` `github.event.pull_request.head.sha`, you execute a fork's code with full secret access. Never combine them.
+
+## Reuse: workflow vs composite action
+
+Both kill copy-paste; pick by scope.
+
+| You need to reuse... | Use | Note |
+| --- | --- | --- |
+| whole jobs with their own `runs-on` / `services` / matrix | reusable workflow (`on: workflow_call`) | `secrets: inherit` to forward; set `concurrency` *inside* it. |
+| a set of steps that run inside one existing job | composite action | Lives at `.github/actions/<name>/action.yml`. |
+
+```yaml
+# caller — reuse a whole job
+jobs:
+  test:
+    uses: ./.github/workflows/reusable-test.yml
+    secrets: inherit
+```
+
+Gotcha: `concurrency` on the job that *calls* a reusable workflow does not behave as you expect — declare it inside the called workflow.
+
+## Deploy job pattern
+
+A deploy depends on the build, gets its own environment gate, and must **never** be cancelled mid-release.
+
+```yaml
+deploy:
+  needs: build              # only deploy a green build
+  runs-on: ubuntu-latest
+  environment: production   # required-reviewer gate lives on the environment
+  concurrency:
+    group: deploy-production
+    cancel-in-progress: false   # NEVER interrupt a release
+  permissions:
+    id-token: write
+    contents: read
+  steps:
+    - uses: actions/checkout@v6
+    - uses: aws-actions/configure-aws-credentials@<full-40-char-sha>
+      with:
+        role-to-assume: arn:aws:iam::123456789012:role/gh-deploy
+        aws-region: eu-west-1
+    - run: ./scripts/deploy.sh
+```
+
+`cancel-in-progress: false` here is the opposite of the CI default: cancelling a half-finished deploy can leave prod in a broken state.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+| --- | --- | --- |
+| Third-party action pinned to a tag (`@v1`) | tj-actions 2025: tags got repointed to secret-stealing code | Pin to a full 40-char SHA, comment the version |
+| `permissions: write-all` or no `permissions:` block | Default token may be write; a leak can push/publish | Top-level `contents: read`, widen per job |
+| Static cloud keys in repo secrets | Standing credentials; one leak = lasting access | OIDC `id-token: write` + `role-to-assume` |
+| OIDC trust scoped to `repo:ORG/*` | Any org repo can assume your prod role | Scope `sub` to repo + ref + environment |
+| No `concurrency` block | PR runs pile up and bill; deploys race | `cancel-in-progress: true` for CI, `false` for deploy |
+| Cache key with no lockfile hash | Restores stale deps forever (immutable per key) | `key: ...-${{ hashFiles('**/lock') }}` + restore-keys |
+| `pull_request_target` + checkout PR head | Runs fork code with your secrets (RCE) | Use `pull_request`; never check out untrusted head with secrets |
+| Same heavy job on `push` **and** `pull_request` | Double-bills runner minutes per commit | `pull_request` for checks, `push: [main]` for deploy |
+| `echo`-ing a secret to debug | Crafted steps/actions exfiltrate the masked value | Never print secrets; use OIDC short-lived tokens |
+
+## Verify
+
+After writing or editing workflows, run the static check on the repo:
+
+```bash
+skills/github-actions/scripts/verify.sh .
+```
+
+It globs `.github/workflows/*.{yml,yaml}`, runs `actionlint` if present, and independently flags unpinned third-party actions, missing `permissions:`, an OIDC nudge for jobs using cloud secrets, and the `pull_request_target` + PR-head footgun. It exits non-zero only on a hard error, so it works as a CI gate.

package/skills/shared/github-actions/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — github-actions
+
+`cases.yaml` is a routing-and-capability spec, not an automated test runner. Read `should_trigger` / `should_not_trigger` as a judgement set: feed each prompt to the skill router and check it lands here for the trigger cases and routes to the named sibling (docker, git-workflow, ship, deployment, vercel) for the non-trigger cases — the non-obvious ones (caching by symptom, concurrency by symptom, OIDC instead of stored keys) are the ones worth watching. For `capability`, have the agent produce the hardened CI+deploy pipeline from the scenario and score it against the `must_include` rubric — every bullet should be present (SHA-pinned third-party actions, read-only default permissions, built-in cache, version matrix, gated OIDC deploy job, tuned concurrency). To sanity-check the artifact the skill emits, run `scripts/verify.sh <repo>` against a repo containing the generated workflows; it is read-only and exits non-zero only on a hard error.

package/skills/shared/github-actions/evals/cases.yaml

@@ -0,0 +1,45 @@
+skill: github-actions
+
+should_trigger:
+  - prompt: "Set up CI to lint and test my Node app on every pull request."
+    why: "Core CI authoring — trigger, permissions, checkout/setup, lint/test job."
+  - prompt: "Our GitHub Actions builds take 9 minutes, mostly npm install — make them faster."
+    why: "Symptom-led, never names 'caching'; the fix is built-in setup-node cache / actions/cache."
+  - prompt: "Run the test suite against node 18, 20 and 22."
+    why: "Matrix build across language versions — strategy.matrix with fail-fast tuning."
+  - prompt: "Deploy to AWS from CI but I don't want to store AWS access keys in GitHub."
+    why: "Non-obvious: the answer is OIDC id-token:write + role-to-assume, not a secret."
+  - prompt: "Every push spawns a new run and the old ones keep finishing — stop the duplicates."
+    why: "Non-obvious symptom phrasing; the feature is concurrency with cancel-in-progress."
+  - prompt: "After the tj-actions thing I want to pin all our actions properly — how?"
+    why: "Supply-chain hardening — SHA-pinning third-party actions; oblique reference to the 2025 compromise."
+  - prompt: "Munta el desplegament continu amb GitHub Actions cap a producció amb aprovació."
+    why: "Catalan; continuous deploy to production with an environment approval gate."
+
+should_not_trigger:
+  - prompt: "Write a multi-stage Dockerfile for this service."
+    route_to: "docker"
+    why: "Image authoring and build strategy; the workflow may call docker build but does not design the image."
+  - prompt: "What branching strategy should we use, trunk-based or git-flow?"
+    route_to: "git-workflow"
+    why: "Branching/merge model is git-workflow, not the CI config layer."
+  - prompt: "Is this ready to release? Draft the changelog and decide the version bump."
+    route_to: "ship"
+    why: "Release readiness and changelog are the shipping decision, not workflow authoring."
+  - prompt: "Design a blue-green rollback strategy for our deploys."
+    route_to: "deployment"
+    why: "Deploy strategy theory (blue/green, canary, rollback) belongs to deployment; Actions only triggers it."
+  - prompt: "Configure the Vercel project's build command and environment variables."
+    route_to: "vercel"
+    why: "Host-side project configuration; the host owns the deploy target, Actions only triggers it."
+
+capability:
+  - scenario: "I have a Node 20 service in a GitHub repo. Give me a hardened CI + deploy pipeline that tests on a matrix of node versions and deploys to AWS on tag pushes without static credentials."
+    must_include:
+      - "First-party actions on current majors (checkout@v6, setup-node@v6); third-party actions pinned to a full 40-char commit SHA."
+      - "Top-level permissions set to contents: read, widened per job only where needed."
+      - "Built-in npm cache via setup-node (cache: npm) keyed on the lockfile."
+      - "A test job using strategy.matrix across multiple node versions."
+      - "A separate deploy job with needs: build and environment: production for the approval gate."
+      - "OIDC auth in the deploy job: permissions id-token: write plus role-to-assume, and no static AWS access keys in secrets."
+      - "concurrency groups: cancel-in-progress true for CI, false for the deploy/release job."

package/skills/shared/github-actions/references/caching-and-matrix.md

@@ -0,0 +1,92 @@
+# Caching and matrix recipes
+
+Deep patterns for cache keys, Docker layer caching, matrix shaping, and runner-minute cost. The SKILL.md covers the common case; reach for this when a monorepo, a Docker build, or a large matrix makes the simple version waste minutes.
+
+## Cache keys beyond the simple case
+
+A cache entry is **immutable per key**. Once written, that key returns the same bytes until the key string changes. So the key must encode everything that should invalidate the cache.
+
+```yaml
+# Multiple lockfiles (monorepo) — hash all of them so any change rotates the key
+key: ${{ runner.os }}-deps-${{ hashFiles('**/package-lock.json', '**/pnpm-lock.yaml') }}
+restore-keys: |
+  ${{ runner.os }}-deps-
+```
+
+`restore-keys` is an ordered prefix-fallback list. On an exact-key miss, GitHub restores the newest cache whose key starts with the first prefix that matches, then the next, etc. That turns a "one dependency changed" cold start into a warm partial hit — you re-resolve only the delta.
+
+Per-workspace caches in a monorepo: put the package path in the key so each package gets its own entry instead of one giant shared cache that thrashes:
+
+```yaml
+key: ${{ runner.os }}-${{ matrix.pkg }}-${{ hashFiles(format('packages/{0}/package-lock.json', matrix.pkg)) }}
+```
+
+## Docker layer cache via buildx + gha backend
+
+For image builds inside a workflow, cache layers with the GitHub Actions cache backend (`type=gha`) so unchanged layers do not rebuild. The *image design* itself is the docker skill's concern — this is only the caching wiring.
+
+```yaml
+- uses: docker/setup-buildx-action@<full-40-char-sha>
+- uses: docker/build-push-action@<full-40-char-sha>
+  with:
+    context: .
+    push: false
+    cache-from: type=gha
+    cache-to: type=gha,mode=max
+```
+
+`mode=max` caches all layers (including intermediate build stages), not just the final image — bigger cache, far more hits on multi-stage builds.
+
+## Matrix shaping
+
+`include` adds cells or extra variables; `exclude` removes specific combinations. They compose: the matrix is built, `exclude` prunes, then `include` appends.
+
+```yaml
+strategy:
+  fail-fast: false
+  max-parallel: 6
+  matrix:
+    os: [ubuntu-latest, macos-latest, windows-latest]
+    node: [20, 22, 24]
+    exclude:
+      - { os: windows-latest, node: 20 }   # drop an unsupported combo
+      - { os: macos-latest, node: 20 }
+    include:
+      - { os: ubuntu-latest, node: 24, coverage: true }  # one cell does coverage
+```
+
+- `fail-fast: false` — every cell reports, even after one fails. Use it for compatibility matrices where you want the full grid of results.
+- `fail-fast: true` (default) — first failure cancels the rest. Use it to save minutes when any failure is a stop-the-line event.
+- `max-parallel` — cap concurrent cells when a shared resource (a test DB, a rate-limited API) cannot take the full fan-out.
+
+Dynamic matrix from a previous job (e.g. only the packages that changed): a setup job emits JSON via `$GITHUB_OUTPUT`, and the matrix consumes it with `fromJSON`:
+
+```yaml
+jobs:
+  discover:
+    runs-on: ubuntu-latest
+    outputs:
+      pkgs: ${{ steps.set.outputs.pkgs }}
+    steps:
+      - id: set
+        run: echo "pkgs=$(./scripts/changed-packages.sh)" >> "$GITHUB_OUTPUT"
+  test:
+    needs: discover
+    strategy:
+      matrix:
+        pkg: ${{ fromJSON(needs.discover.outputs.pkgs) }}
+    runs-on: ubuntu-latest
+    steps: [...]
+```
+
+## Runner-minute cost
+
+GitHub bills minutes by runner OS with a multiplier on hosted runners:
+
+| Runner | Relative cost |
+| --- | --- |
+| Linux (`ubuntu-latest`) | 1x — the baseline |
+| Windows | ~2x |
+| macOS | ~10x |
+
+So: do the bulk of the matrix on Linux, and only add macOS/Windows cells where the platform difference actually matters (native modules, platform-specific builds). `exclude` the cheap-to-skip combinations rather than running the full cartesian product on every OS. A matrix of `3 OS x 4 versions = 12` cells with a 10x macOS multiplier costs far more than `8 ubuntu + 2 macos + 2 windows` shaped with `exclude`.