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

package/skills/shared/gcp-essentials/references/iam-and-auth.md

@@ -0,0 +1,94 @@
+# IAM & auth
+
+Depth for the IAM section of SKILL.md. Predefined roles, keyless CI, impersonation,
+drift detection.
+
+## Predefined roles for a typical product
+
+Prefer these Google-maintained roles over primitives or custom roles. Bind them to the
+service's dedicated SA at the narrowest resource scope the role supports.
+
+| Need | Role | Scope it to |
+|------|------|-------------|
+| Connect to Cloud SQL from the workload | `roles/cloudsql.client` | project |
+| Read/write objects in one bucket | `roles/storage.objectAdmin` | the bucket |
+| Read object content only | `roles/storage.objectViewer` | the bucket |
+| Read one secret's value | `roles/secretmanager.secretAccessor` | the secret |
+| Invoke a private Cloud Run service | `roles/run.invoker` | the service |
+| Push/pull container images | `roles/artifactregistry.writer` | the repo |
+| Write logs/metrics from the app | usually implicit on Cloud Run runtime SA | — |
+
+Bind at resource scope when possible — e.g. a secret, not the project:
+
+```bash
+gcloud secrets add-iam-policy-binding db-password \
+  --member="serviceAccount:api-sa@acme-prod.iam.gserviceaccount.com" \
+  --role="roles/secretmanager.secretAccessor"
+```
+
+## Workload Identity Federation for GitHub Actions (keyless)
+
+No JSON key downloaded, ever. GitHub's OIDC token is exchanged for short-lived GCP
+credentials.
+
+```bash
+# 1. A pool + an OIDC provider that trusts GitHub's issuer
+gcloud iam workload-identity-pools create github \
+  --location=global --display-name="GitHub Actions"
+
+gcloud iam workload-identity-pools providers create-oidc github-oidc \
+  --location=global --workload-identity-pool=github \
+  --display-name="GitHub OIDC" \
+  --issuer-uri="https://token.actions.githubusercontent.com" \
+  --attribute-mapping="google.subject=assertion.sub,attribute.repository=assertion.repository" \
+  --attribute-condition="assertion.repository=='acme/api'"
+
+# 2. Let the deploy SA be impersonated only from that repo
+PROJECT_NUM=$(gcloud projects describe acme-prod --format='value(projectNumber)')
+gcloud iam service-accounts add-iam-policy-binding \
+  deployer@acme-prod.iam.gserviceaccount.com \
+  --role="roles/iam.workloadIdentityUser" \
+  --member="principalSet://iam.googleapis.com/projects/${PROJECT_NUM}/locations/global/workloadIdentityPools/github/attribute.repository/acme/api"
+```
+
+In the workflow, use `google-github-actions/auth` with the provider resource name and
+`service_account` — never a `credentials_json` secret. The `attribute-condition`
+pinning the exact repo is the security boundary; without it any repo could mint
+credentials.
+
+## Service account impersonation
+
+Run a one-off command *as* a service account without holding its key. The caller needs
+`roles/iam.serviceAccountTokenCreator` on the target SA.
+
+```bash
+gcloud storage ls gs://acme-prod-uploads \
+  --impersonate-service-account=api-sa@acme-prod.iam.gserviceaccount.com
+```
+
+Use this to test that an SA actually has the access you think it does — least surprise
+before deploy.
+
+## IAM Recommender (catch drift)
+
+The Recommender flags roles a member has not used in 90 days, so you can prune
+over-grants. Review it on a schedule.
+
+```bash
+gcloud recommender recommendations list \
+  --project=acme-prod --location=global \
+  --recommender=google.iam.policy.Recommender \
+  --format="table(content.overview)"
+```
+
+## IAM Conditions
+
+Attach a condition to narrow a binding by time or resource attribute — e.g. access to
+objects under one prefix only.
+
+```bash
+gcloud projects add-iam-policy-binding acme-prod \
+  --member="serviceAccount:api-sa@acme-prod.iam.gserviceaccount.com" \
+  --role="roles/storage.objectViewer" \
+  --condition='expression=resource.name.startsWith("projects/_/buckets/acme-prod-uploads/objects/public/"),title=public-prefix-only'
+```

package/skills/shared/gcp-essentials/references/networking-and-sql.md

@@ -0,0 +1,74 @@
+# Networking & Cloud SQL
+
+Depth for the Cloud SQL and VPC parts of SKILL.md.
+
+## Cloud Run egress: Direct VPC egress, not the legacy connector
+
+To reach private IPs (a Cloud SQL private instance, an internal service) from Cloud
+Run, prefer **Direct VPC egress** over the older Serverless VPC Access connector —
+fewer moving parts, lower latency, no connector VM to size or pay for.
+
+```bash
+gcloud run deploy api --region=europe-west1 \
+  --service-account=api-sa@acme-prod.iam.gserviceaccount.com \
+  --network=projects/acme-prod/global/networks/default \
+  --subnet=projects/acme-prod/regions/europe-west1/subnetworks/default \
+  --vpc-egress=all-traffic
+```
+
+- `--vpc-egress=all-traffic` routes all outbound through the VPC. The older explicit
+  Direct-VPC-egress value is deprecated in favour of `all-traffic`.
+- `--vpc-egress=private-ranges-only` sends only RFC-1918 traffic through the VPC and
+  lets public traffic exit directly — use it when only the DB is private.
+
+The legacy `--vpc-connector` still works but is no longer the default recommendation;
+do not provision a new connector for greenfield work.
+
+## Cloud SQL private IP
+
+Disable the public IP and give the instance a private address on your VPC. This is the
+single biggest attack-surface reduction for a database.
+
+```bash
+# One-time: allocate a range and peer it (Service Networking)
+gcloud compute addresses create google-managed-services-default \
+  --global --purpose=VPC_PEERING --prefix-length=16 \
+  --network=projects/acme-prod/global/networks/default
+gcloud services vpc-peerings connect \
+  --service=servicenetworking.googleapis.com \
+  --ranges=google-managed-services-default \
+  --network=default --project=acme-prod
+
+# Create the instance with private IP, no public IP.
+# --edition=ENTERPRISE is required: POSTGRES_16+ defaults to Enterprise Plus, which
+# cannot run the shared-core db-f1-micro tier, so the create fails without it.
+gcloud sql instances create acme-db \
+  --database-version=POSTGRES_16 --edition=ENTERPRISE \
+  --region=europe-west1 --tier=db-f1-micro \
+  --no-assign-ip \
+  --network=projects/acme-prod/global/networks/default
+```
+
+PSC (Private Service Connect) is the alternative when you need the instance reachable
+from multiple VPCs or projects; enable it with `--enable-private-service-connect` and
+allow the consumer projects.
+
+## Cloud SQL Auth Proxy (for outside-VPC connections)
+
+The proxy gives short-lived client certs and TLS 1.3 without managing certificates. Use
+it for **local dev** or any non-serverless host — Cloud Run does **not** need it (it
+uses the `/cloudsql/...` socket via `--add-cloudsql-instances`).
+
+```bash
+# Local dev against a private-IP instance over the proxy
+./cloud-sql-proxy --private-ip acme-prod:europe-west1:acme-db
+# then connect your client to 127.0.0.1:5432
+```
+
+## Connection pooling
+
+Cloud SQL has a hard `max_connections` ceiling and Cloud Run can fan out to many
+instances, each opening its own pool — you will exhaust connections under load. Keep
+each instance's pool small (e.g. a few connections) and, for high concurrency, front
+the database with a pooler (PgBouncer / a managed proxy) rather than raising
+`max_connections`. Schema and query tuning beyond this is `postgresdb` territory.

package/skills/shared/gcp-essentials/scripts/verify.sh

@@ -0,0 +1,158 @@
+#!/usr/bin/env bash
+# verify.sh — offline static linter for GCP gcloud command blocks.
+#
+# Flags known-unsafe patterns in files that contain `gcloud` commands:
+#   - service-account JSON key creation
+#   - roles/owner or roles/editor bound to a serviceAccount member
+#   - bucket create missing --uniform-bucket-level-access or --public-access-prevention
+#   - Cloud SQL create using public IP (--assign-ip / no --no-assign-ip)
+#   - Cloud Run deploy/replace missing --service-account
+#
+# No network, no gcloud, read-only. Prints PASS/FAIL per check.
+# Exit 0 when the target is empty/clean, nonzero when any FAIL is found.
+#
+# Usage:
+#   bash verify.sh <file-or-dir> [<file-or-dir> ...]
+#   bash verify.sh                # defaults to the skill dir (SKILL.md + references/)
+
+set -uo pipefail
+
+# ---- collect target files -------------------------------------------------
+declare -a TARGETS=()
+if [[ $# -eq 0 ]]; then
+  here="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+  TARGETS=("$here")
+else
+  TARGETS=("$@")
+fi
+
+declare -a FILES=()
+for t in "${TARGETS[@]}"; do
+  if [[ -d "$t" ]]; then
+    while IFS= read -r f; do FILES+=("$f"); done < <(
+      find "$t" -type f \( -name '*.sh' -o -name '*.md' -o -name '*.bash' -o -name '*.txt' \) 2>/dev/null
+    )
+  elif [[ -f "$t" ]]; then
+    FILES+=("$t")
+  else
+    echo "WARN  no such file or directory: $t" >&2
+  fi
+done
+
+if [[ ${#FILES[@]} -eq 0 ]]; then
+  echo "PASS  no target files to lint (clean)"
+  exit 0
+fi
+
+fails=0
+
+# report FAIL <check> <file> <lineno> <line>
+report() {
+  printf 'FAIL  %-22s %s:%s: %s\n' "$1" "$2" "$3" "$4"
+  fails=$((fails + 1))
+}
+
+for f in "${FILES[@]}"; do
+  lineno=0
+  # Track context for multi-line `gcloud` commands joined by trailing backslash.
+  buf=""
+  buf_start=0
+  flush_buf() {
+    [[ -z "$buf" ]] && return
+    local cmd="$buf"
+    # --- Cloud Run deploy/replace must carry --service-account ---
+    if echo "$cmd" | grep -Eq 'gcloud[[:space:]]+run[[:space:]]+(deploy|services[[:space:]]+replace)'; then
+      if ! echo "$cmd" | grep -q -- '--service-account'; then
+        report "run-no-service-account" "$f" "$buf_start" "gcloud run deploy/replace without --service-account"
+      fi
+    fi
+    # --- bucket create must carry UBLA and PAP ---
+    if echo "$cmd" | grep -Eq 'gcloud[[:space:]]+storage[[:space:]]+buckets[[:space:]]+create'; then
+      if ! echo "$cmd" | grep -q -- '--uniform-bucket-level-access'; then
+        report "bucket-no-ubla" "$f" "$buf_start" "bucket create missing --uniform-bucket-level-access"
+      fi
+      if ! echo "$cmd" | grep -q -- '--public-access-prevention'; then
+        report "bucket-no-pap" "$f" "$buf_start" "bucket create missing --public-access-prevention"
+      fi
+    fi
+    # --- Cloud SQL create must not use public IP ---
+    if echo "$cmd" | grep -Eq 'gcloud[[:space:]]+sql[[:space:]]+instances[[:space:]]+create'; then
+      if echo "$cmd" | grep -Eq -- '--assign-ip([^a-z]|$)'; then
+        report "sql-public-ip" "$f" "$buf_start" "Cloud SQL create uses --assign-ip (public IP)"
+      elif ! echo "$cmd" | grep -q -- '--no-assign-ip'; then
+        report "sql-no-private" "$f" "$buf_start" "Cloud SQL create missing --no-assign-ip (defaults to public IP)"
+      fi
+    fi
+    buf=""
+  }
+
+  # For Markdown files, only lint inside fenced code blocks (```bash / ```sh /
+  # ```). Prose and anti-pattern table cells (which quote unsafe commands on
+  # purpose) must not trip the linter. Non-.md files are treated as all-code.
+  in_code=true
+  is_md=false
+  case "$f" in
+    *.md) is_md=true; in_code=false ;;
+  esac
+
+  while IFS= read -r line || [[ -n "$line" ]]; do
+    lineno=$((lineno + 1))
+
+    # Toggle fenced-code state for Markdown.
+    if $is_md && [[ "$line" =~ ^[[:space:]]*\`\`\` ]]; then
+      if $in_code; then in_code=false; else in_code=true; fi
+      flush_buf
+      continue
+    fi
+    if ! $in_code; then
+      continue
+    fi
+
+    # Skip prose/comment-only lines for keyword checks but still scan for the
+    # hard banned single-line patterns below.
+    stripped="${line#"${line%%[![:space:]]*}"}"   # ltrim
+    is_comment=false
+    [[ "$stripped" == \#* ]] && is_comment=true
+
+    # ---- single-line hard bans (checked on every non-comment line) ----
+    if ! $is_comment; then
+      # JSON key creation — never.
+      if echo "$line" | grep -Eq 'gcloud[[:space:]]+iam[[:space:]]+service-accounts[[:space:]]+keys[[:space:]]+create'; then
+        report "sa-json-key-create" "$f" "$lineno" "$stripped"
+      fi
+      # primitive owner/editor bound to a service account.
+      if echo "$line" | grep -Eq -- '--role=("?)roles/(owner|editor)\b' \
+         && echo "$line" | grep -q 'serviceAccount:'; then
+        report "primitive-role-on-sa" "$f" "$lineno" "$stripped"
+      fi
+      # primitive owner/editor in a member+role grant spanning the same command
+      # (covers the common case where role is on the same line).
+    fi
+
+    # ---- accumulate multi-line gcloud commands (backslash continuation) ----
+    if $is_comment; then
+      flush_buf
+      continue
+    fi
+    if [[ -n "$buf" ]]; then
+      buf="$buf $stripped"
+    elif echo "$stripped" | grep -Eq '^gcloud([[:space:]]|$)'; then
+      buf="$stripped"
+      buf_start=$lineno
+    fi
+    # End of a command when the line does not end in a backslash.
+    if [[ -n "$buf" && "${line%\\}" == "$line" ]]; then
+      flush_buf
+    fi
+  done < "$f"
+  flush_buf
+done
+
+echo "----"
+if [[ $fails -eq 0 ]]; then
+  echo "PASS  ${#FILES[@]} file(s) linted, no unsafe gcloud patterns found"
+  exit 0
+else
+  echo "FAIL  $fails unsafe pattern(s) found across ${#FILES[@]} file(s)"
+  exit 1
+fi

package/skills/shared/git-workflow/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: git-workflow
+description: "Use when naming or scoping a branch, writing or fixing a commit message, picking the gitmoji for a commit, untangling history (rebase versus merge versus squash), or cutting a versioned release — the portable git-convention layer for any repo. Covers gitmoji + Conventional Commits, SemVer tags, branch hygiene, force-push safety and gh pr/release mechanics. NOT the land-it decision and pre-ship checklist (that is `ship`), NOT an isolated checkout before coding (that is `worktrees`), NOT CI/CD release automation (that is `deployment`)."
+tags: [git, version-control, conventional-commits, gitmoji, semver, pull-request]
+recommends: [ship, worktrees, deployment, github-actions]
+origin: ai-hub
+---
+
+# git-workflow — the grammar and hygiene of version control
+
+Git history is a message to the next human who reads `git log`, runs `git blame` on a broken line,
+or bisects a regression at 2am. That human is usually future-you. **Every rule in this skill exists
+to make the next reader's job faster**, not to make this moment cheaper. A repo with legible branch
+names, conventional commits, and a clean linear narrative is a repo you can reason about; a repo with
+`wip`, `fix stuff`, and force-pushed shared history is one you fight.
+
+This is the **portable convention layer**. It is independent of any SDD phase or CI platform — it is
+the grammar that `../ship/SKILL.md`, `../worktrees/SKILL.md`, and `../deployment/SKILL.md` all lean on.
+It does not decide *whether to land* the work (that is ship) and it does not automate releases in a
+pipeline (that is deployment). It tells you how to name, commit, untangle, and tag — correctly.
+
+## Branch naming
+
+Name a branch from its *intent*, prefixed by its kind, as a kebab-case slug. Keep it short-lived:
+hours to days, not weeks. Long branches drift from `main` and turn into merge pain.
+
+| Prefix       | Use for                                      | Why                                              |
+|--------------|----------------------------------------------|--------------------------------------------------|
+| `feat/`      | a new capability                             | matches the `feat` commit type; signals a MINOR  |
+| `fix/`       | a bug fix                                     | matches `fix`; signals a PATCH                    |
+| `hotfix/`    | an urgent fix landing straight to production  | flags "skip the slow path" to reviewers          |
+| `chore/`     | tooling, deps, config — no product behavior  | keeps non-feature noise out of the feature log   |
+| `docs/`      | documentation only                            | reviewers can fast-track, no test gate needed    |
+| `refactor/`  | restructure without behavior change           | sets the expectation: tests stay green, no new behavior |
+
+Slug rules: derive it from the issue title or the one-sentence intent, lowercase, dash-separated, no
+spaces or `/` inside the slug. Optionally suffix the issue number.
+
+```text
+Bad   my-stuff            (kind unknown, intent unknown)
+Bad   your-name-branch-2  (names the author and a counter, not the work)
+Good  feat/oauth-pkce-flow
+Good  fix/expired-refresh-token-401
+Good  chore/bump-node-22
+```
+
+## Commit grammar — gitmoji + Conventional Commits
+
+Write every commit to **Conventional Commits 1.0.0**, opened by a **gitmoji**. The structure:
+
+```text
+<gitmoji> type(scope)!: subject
+
+body — what changed and why, wrapped, optional
+
+BREAKING CHANGE: description of the incompatible change
+Fixes #123
+```
+
+- The **gitmoji is mandatory** and comes first — the intention of the change, readable in one glyph
+  when you scan `git log --oneline`. `type` is what tooling reads; the emoji is what humans read.
+- `type` is mandatory. `scope` in parentheses is optional. `!` before the colon marks a breaking change.
+- Subject: imperative mood ("add", not "added"/"adds"), ≤72 chars, no trailing period.
+- Body explains *why*, not *what the diff already shows*. Separate from subject by a blank line.
+- Footers go last. `Fixes #123` / `Closes #123` in the body auto-closes that issue when the PR merges.
+
+Type → SemVer effect:
+
+| Type                              | SemVer bump | Notes                                              |
+|-----------------------------------|-------------|----------------------------------------------------|
+| `feat`                            | MINOR       | a new capability                                   |
+| `fix`                             | PATCH       | a bug fix                                           |
+| `docs`, `chore`, `refactor`, `test`, `build`, `ci`, `perf`, `style`, `revert` | none | allowed, but no implicit version bump              |
+| any type with `!` or a `BREAKING CHANGE:` footer | **MAJOR** | overrides the above regardless of type             |
+
+`BREAKING CHANGE` **must be uppercase** in the footer; the type/scope units are case-insensitive but
+write them lowercase by convention.
+
+Type → gitmoji, the everyday set (the full 75-emoji table, and *why* the emoji never replaces the
+type, are in **`references/gitmoji.md`**):
+
+| Type       | gitmoji | Type       | gitmoji | Type      | gitmoji |
+|------------|---------|------------|---------|-----------|---------|
+| `feat`     | ✨      | `refactor` | ♻️      | `build`   | 📦️      |
+| `fix`      | 🐛      | `test`     | ✅      | `style`   | 🎨      |
+| `docs`     | 📝      | `perf`     | ⚡️      | `revert`  | ⏪️      |
+| `chore`    | 🔧      | `ci`       | 👷      | breaking  | 💥      |
+
+Pick by **intention**, not by which file changed, and prefer the specific one: 🚑️ for a production
+hotfix, 🩹 for a trivial non-critical fix, 🔥 for a deletion, 🚚 for a rename, ⬆️ for a dep bump,
+🔖 for a release commit.
+
+```text
+Bad   fix stuff
+Bad   updates
+Bad   Fixed the login bug.            (past tense, capitalized, trailing period)
+Bad   fix(auth): reject expired refresh tokens        (no gitmoji)
+Bad   ✨ added a search endpoint                       (gitmoji but no type → no derivable bump)
+Good  🐛 fix(auth): reject expired refresh tokens
+Good  ✨ feat(api): add /v2/search endpoint with cursor paging
+Good  ♻️ refactor(parser): extract token scanner, no behavior change
+```
+
+A breaking change, both forms equivalent:
+
+```text
+💥 feat(api)!: drop the legacy /v1 search endpoint
+
+BREAKING CHANGE: /v1/search is removed; callers must migrate to /v2/search.
+```
+
+If the repo runs a **strict** conventional parser (commitlint, semantic-release) it anchors the type
+at position 0 and rejects the emoji prefix. Either widen its `headerPattern` — the config is in
+`references/gitmoji.md` — or move the emoji behind the header (`feat(api): ✨ add cursor paging`),
+which every parser accepts. Both forms satisfy this convention; dropping the gitmoji does not.
+
+**Authorship is always Daner Alejandro Salazar Colorado.** Never add a `Co-Authored-By: Claude` trailer, never a
+"Generated with" footer, never any line crediting an AI tool — in a commit *or* a PR body. The work
+is Daner Alejandro Salazar Colorado's; the agent is a tool, like the compiler.
+
+## History hygiene — rebase, merge, or squash?
+
+Decide by who else has the commits. The lease rule below is non-negotiable.
+
+| Situation                                            | Do this                                              | Why                                                        |
+|------------------------------------------------------|------------------------------------------------------|------------------------------------------------------------|
+| Private branch, only you have it, want linear history | `git rebase main`, then `git push --force-with-lease`| rebase rewrites hashes; safe because nobody built on them  |
+| Branch others have pulled / built on                  | `git merge main` — **never** rebase it               | rebase changes every hash; collaborators' work diverges    |
+| Noisy PR (many `wip` commits)                         | squash-merge into one gitmoji + conventional commit            | `main` gets one meaningful entry, not 9 scratch commits    |
+| Already pushed, shared, *and* you rewrote it          | **STOP** — coordinate, or `git revert` instead       | force-pushing shared history breaks everyone downstream     |
+
+After a rebase, push with `--force-with-lease`, never bare `--force`:
+
+```bash
+git push --force-with-lease   # refuses if the remote moved since you fetched — catches a teammate's push
+git push --force              # blindly overwrites — can erase a teammate's commits
+```
+
+The interactive cleanup loop (`rebase -i`, `fixup`/`squash`/`reword`/`drop`, `--autosquash`,
+the conflict→continue cycle, and recovery via `git reflog`) is a long branchy procedure — see
+**`references/interactive-rebase.md`** rather than reaching for it on every commit.
+
+## Releases
+
+Derive the version bump from the commit log, never by guessing. Scan the commits since the last tag:
+
+- any `BREAKING CHANGE:` / `!` → **MAJOR** (`v1.4.2` → `v2.0.0`)
+- otherwise any `feat:` → **MINOR** (`v1.4.2` → `v1.5.0`)
+- otherwise only `fix:`/others → **PATCH** (`v1.4.2` → `v1.4.3`)
+
+Tag with the `vMAJOR.MINOR.PATCH` form, annotated, then create the release with auto-generated notes:
+
+```bash
+git tag -a v2.0.0 -m "v2.0.0"
+git push origin v2.0.0
+gh release create v2.0.0 --generate-notes              # notes via the GitHub Release Notes API
+gh release create v2.0.0 --generate-notes --draft      # stage notes, publish later
+gh release create v2.0.0-rc.1 --generate-notes --prerelease
+```
+
+GitHub auto-assigns the "latest" label by semver order unless you set it. With release immutability
+enabled, **a published release's tag cannot be edited or deleted** — get the version right before you
+publish.
+
+```text
+Bad   added a feature + a breaking config change, tagged v1.5.0   (breaking change → must be MAJOR)
+Good  same changes → v2.0.0, bump derived from the BREAKING CHANGE footer in the log
+```
+
+Automating any of this on tag push (a `release.yml` workflow, OIDC to a registry) is **deployment** —
+see `../deployment/SKILL.md`. This skill covers the manual/local release act.
+
+## PR mechanics — then hand off to ship
+
+Open the PR with autofilled title/body from the commits, against the right base:
+
+```bash
+gh pr create --fill --base main          # title/body from commits; --base falls back to repo default
+```
+
+Put `Fixes #123` in the body to link and auto-close the issue on merge. A PR body should let the
+reviewer understand the change without reading every line of the diff.
+
+The **decision to land** — direct-merge vs PR vs park, the pre-ship safety checklist, the actual
+merge — belongs to `../ship/SKILL.md`. This skill only makes the branch, commits, and PR body clean
+enough to hand over. Setting up the isolated checkout *before* you start coding is
+`../worktrees/SKILL.md`.
+
+## Anti-patterns
+
+| Anti-pattern                                          | Why it hurts                                              | Instead                                              |
+|-------------------------------------------------------|-----------------------------------------------------------|------------------------------------------------------|
+| `git push --force` on a shared branch                 | silently erases teammates' commits                        | `--force-with-lease`, or don't rewrite shared history |
+| `git commit -m "wip"` / `"fix"` / `"updates"`         | the log carries zero signal for the next reader           | `<gitmoji> type(scope): imperative subject`           |
+| Commit message with no gitmoji                         | `git log --oneline` reads as a wall of undifferentiated text | pick the intention's emoji (`references/gitmoji.md`) |
+| Mixing unrelated changes in one commit                | can't revert or review one concern in isolation           | one logical change per commit                         |
+| Long-lived branch (weeks)                             | diverges from `main`, merge becomes a battle              | short-lived; rebase or merge `main` in often          |
+| Hand-computing the semver bump                        | breaking change shipped as a MINOR → broken downstream    | derive the bump from the commit log                   |
+| Rebasing a public/shared branch                       | rewrites hashes others built on                           | merge shared branches; rebase only private ones       |
+| Committing generated/secret files                     | leaks credentials, bloats history irreversibly            | `.gitignore`; rotate any secret that slipped in       |
+| `BREAKING CHANGE` lowercase                            | tooling won't detect it → wrong (too-low) bump            | uppercase `BREAKING CHANGE:` in the footer            |
+| PR with no description                                | reviewer reverse-engineers intent from the diff           | `--fill` plus a why, link the issue                   |
+| Tagging a release with no notes                       | users can't tell what changed                             | `gh release create --generate-notes`                  |
+| `Co-Authored-By: Claude` / "Generated with" footer    | forges authorship onto a tool                             | author is always Daner Alejandro Salazar Colorado; no AI attribution              |
+
+## Checklist — before a PR or a release
+
+- [ ] Working tree clean (`git status`), no stray or generated files staged.
+- [ ] Branch rebased on / merged with current `main`; no avoidable conflicts.
+- [ ] Every commit carries its gitmoji **and** a conventional header; `wip`/scratch commits squashed away.
+- [ ] No secrets, no AI-attribution trailers.
+- [ ] PR body explains the why and links the issue (`Fixes #`).
+- [ ] (Release) version bump **derived from the commit log**, tag is `vX.Y.Z`, annotated.
+- [ ] (Release) `gh release create vX.Y.Z --generate-notes`; version confirmed before publishing (immutable once published).

package/skills/shared/git-workflow/evals/README.md

@@ -0,0 +1,10 @@
+# Evals — git-workflow
+
+These are routing and capability checks for the `git-workflow` skill. Run them with the repo's eval
+harness: load `cases.yaml`, fire each `should_trigger` and `should_not_trigger` prompt at the router,
+and confirm the trigger ones select `git-workflow` while the negatives route to their stated sibling
+(`ship`, `worktrees`, `deployment`, `review`). For the `capability` entry, give the scenario to the
+skill and judge the produced commit plan, semver bump, and `gh release create` command against the
+`must_include` rubric — the bump is MAJOR, the breaking change uses an uppercase `BREAKING CHANGE:`
+footer, the push uses `--force-with-lease`, and there is no AI-attribution trailer. No code is
+executed and the skill emits no artifact, so this is a judgment pass, not a build.

package/skills/shared/git-workflow/evals/cases.yaml

@@ -0,0 +1,52 @@
+skill: git-workflow
+
+should_trigger:
+  - prompt: "Is this commit message conventional? 'fixed the login bug'"
+    why: Core Conventional Commits grammar check — past tense, no type, capitalized; the skill rewrites it.
+  - prompt: "Should I rebase or merge this feature branch before opening the PR?"
+    why: History-strategy decision — rebase private / merge shared — owned by the hygiene decision table.
+  - prompt: "My git log is full of wip commits, clean it up before review"
+    why: Non-obvious phrasing; routes to squash/interactive-rebase to collapse scratch commits.
+  - prompt: "What version should this release be — we added a new endpoint and a breaking config change?"
+    why: SemVer bump derived from the commit log; breaking change forces MAJOR.
+  - prompt: "Limpia el historial y deja los commits en formato convencional antes del PR"
+    why: Spanish trigger covering history cleanup plus conventional-commit formatting.
+  - prompt: "Name a branch for the OAuth PKCE work"
+    why: Branch-naming convention — feat/ prefix plus kebab slug from intent.
+  - prompt: "Which gitmoji goes on this commit — I deleted a deprecated module"
+    why: Gitmoji selection by intention (🔥 remove code, not ♻️ refactor); the commit-grammar layer owns the emoji.
+  - prompt: "Mi commitlint rechaza el commit por el emoji delante del type"
+    why: Spanish; the strict-parser escape hatch (widen headerPattern or move the emoji behind the header) lives in this skill.
+  - prompt: "Tag v2.1.0 and write the release notes"
+    why: Release mechanics — annotated tag plus gh release create --generate-notes.
+
+should_not_trigger:
+  - prompt: "I'm done and verified, land this work into main"
+    route_to: ship
+    why: The land/merge decision and pre-ship safety checklist are ship's phase, not the conventions layer.
+  - prompt: "Set up an isolated checkout so I don't dirty main before I start coding"
+    route_to: worktrees
+    why: Workspace isolation up front, before any code is touched.
+  - prompt: "Write a GitHub Actions workflow that publishes a release on tag push"
+    route_to: deployment
+    why: CI/CD release automation, not the manual/local release act.
+  - prompt: "Review this diff for bugs before we merge"
+    route_to: review
+    why: Adversarial diff reading, not git mechanics.
+  - prompt: "Containerize the app and deploy it to Coolify"
+    route_to: deployment
+    why: Build and deploy mechanics to a platform.
+
+capability:
+  - scenario: >
+      A private feature branch has 4 messy commits: one adds a feature, one removes a deprecated
+      config flag (a breaking change), and two are "wip". Produce (a) a clean conventional-commit
+      plan, (b) the correct semver bump for the next release, and (c) the gh release create command.
+    must_include:
+      - Collapses the two "wip" commits via squash or fixup and explains why (one meaningful entry in main).
+      - Identifies a feat commit and a BREAKING CHANGE footer written in uppercase.
+      - Every proposed commit message opens with a gitmoji (✨ for the feature, 💥 for the breaking removal) before the conventional header.
+      - Bump is MAJOR because of the breaking change, with a tag of the form vX.0.0.
+      - Uses gh release create vX.0.0 --generate-notes (or an equivalent that produces notes).
+      - Uses git push --force-with-lease (not bare --force) for the post-rebase push.
+      - Does NOT add a Claude Co-Authored-By or "Generated with" footer; authorship stays with the human contributor.