@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/cicd/google-cloud/references/vpc.md

@@ -0,0 +1,312 @@
+# VPC Configuration
+
+VPC networks, subnets, and firewall rules for GCP infrastructure.
+
+## Network Operations
+
+### List Networks
+
+```bash
+# All networks in project
+gcloud compute networks list
+
+# With details
+gcloud compute networks list --format="table(name,subnetMode,autoCreateSubnetworks)"
+```
+
+### Create Network
+
+```bash
+# Custom subnet mode (recommended)
+gcloud compute networks create $NAME \
+  --subnet-mode=custom \
+  --mtu=1460 \
+  --bgp-routing-mode=regional
+
+# Legacy (auto-create subnets)
+gcloud compute networks create $NAME \
+  --subnet-mode=legacy \
+  --auto-create-subnetworks
+```
+
+### Delete Network
+
+```bash
+gcloud compute networks delete $NAME
+```
+
+---
+
+## Subnet Operations
+
+### List Subnets
+
+```bash
+# All subnets in region
+gcloud compute networks subnets list --region=us-central1
+
+# In specific network
+gcloud compute networks subnets list \
+  --filter="network:$NETWORK" \
+  --region=us-central1
+```
+
+### Create Subnet
+
+```bash
+gcloud compute networks subnets create $SUBNET \
+  --network=$NETWORK \
+  --region=us-central1 \
+  --range=$IP_RANGE \
+  --purpose=REGIONAL_MANAGED_PROXY \
+  --enable-flow-logs \
+  --logging-flow-sampling=0.5 \
+  --logging-metadata=include-all
+```
+
+### Describe Subnet
+
+```bash
+gcloud compute networks subnets describe $SUBNET \
+  --region=us-central1 \
+  --format="yaml(ipCidrRange,purpose,privateIpGoogleAccess,secondaryIpRanges)"
+```
+
+---
+
+## Cloud Run with VPC
+
+### Deploy Cloud Run with VPC
+
+```bash
+gcloud run deploy $SERVICE \
+  --image=$IMAGE \
+  --region=us-central1 \
+  --network=$NETWORK \
+  --subnet=$SUBNET
+```
+
+### Update Existing Service VPC
+
+```bash
+gcloud run services update $SERVICE \
+  --region=us-central1 \
+  --network=$NETWORK \
+  --subnet=$SUBNET
+```
+
+### Cloud Run Job with VPC
+
+```bash
+gcloud run jobs create $JOB \
+  --image=$IMAGE \
+  --region=us-central1 \
+  --network=$NETWORK \
+  --subnet=$SUBNET
+
+# Update existing job
+gcloud run jobs update $JOB \
+  --region=us-central1 \
+  --network=$NETWORK \
+  --subnet=$SUBNET
+```
+
+---
+
+## Cloud SQL Connection Standard
+
+**1Above standard:** Connect via direct VPC + private IP. Do NOT use Cloud SQL Auth Proxy (`--add-cloudsql-instances`).
+
+### Connection string format
+
+```
+postgresql://<user>:<password>@<PRIVATE_IP>:5432/<database>?sslmode=no-verify&connect_timeout=5
+```
+
+### Cloud SQL instance private IPs (GCP project: cosmic-heaven-479306-v5)
+
+| Instance | Private IP |
+|----------|------------|
+| ai-dev   | 10.58.0.11 |
+
+### Cloud Run deploy flags
+
+```bash
+--network=default \
+--subnet=default \
+--vpc-egress=private-ranges-only
+# Do NOT add: --add-cloudsql-instances
+```
+
+### Why sslmode=no-verify?
+
+`ai-dev` has `requireSsl: true` + `TRUSTED_CLIENT_CERTIFICATE_REQUIRED`.
+`sslmode=no-verify` encrypts the connection without requiring client certificates — consistent with all existing services (a1-research-dev, etc.).
+
+### Reference service
+
+Check `a1-research-dev` DATABASE_URL in Secret Manager as the canonical example.
+
+---
+
+## VPC Connectors (Serverless VPC Access)
+
+### Create VPC Connector
+
+```bash
+gcloud compute networks vpc-access connectors create $CONNECTOR \
+  --region=us-central1 \
+  --network=$NETWORK \
+  --range=$IP_RANGE
+```
+
+### List VPC Connectors
+
+```bash
+gcloud compute networks vpc-access connectors list --region=us-central1
+```
+
+### Use Connector with Cloud Run
+
+```bash
+gcloud run services update $SERVICE \
+  --region=us-central1 \
+  --vpc-connector=$CONNECTOR
+```
+
+---
+
+## Firewall Rules
+
+### List Firewall Rules
+
+```bash
+# All rules
+gcloud compute firewall-rules list
+
+# For specific network
+gcloud compute firewall-rules list --filter="network:$NETWORK"
+
+# With details
+gcloud compute firewall-rules describe $RULE
+```
+
+### Create Firewall Rule
+
+```bash
+# Allow SSH from anywhere (dev only)
+gcloud compute firewall-rules create allow-ssh \
+  --network=$NETWORK \
+  --allow=tcp:22 \
+  --source-ranges=0.0.0.0/0 \
+  --target-tags=$TAG
+
+# Allow internal traffic
+gcloud compute firewall-rules create allow-internal \
+  --network=$NETWORK \
+  --allow=tcp,udp,icmp \
+  --source-ranges=$IP_RANGE \
+  --direction=INGRESS
+
+# Allow health checks
+gcloud compute firewall-rules create allow-health-check \
+  --network=$NETWORK \
+  --allow=tcp:80,tcp:443 \
+  --source-ranges=35.191.0.0/16,130.211.0.0/22 \
+  --target-tags=$TAG
+```
+
+---
+
+## Private Google Access
+
+### Check if Subnet Has Private Google Access
+
+```bash
+gcloud compute networks subnets describe $SUBNET \
+  --region=us-central1 \
+  --format="value(privateIpGoogleAccess)"
+```
+
+### Enable Private Google Access on Subnet
+
+```bash
+gcloud compute networks subnets describe $SUBNET \
+  --region=us-central1 \
+  --set-private-ip-google-access
+```
+
+---
+
+## Shared VPC (Host Project)
+
+### List Shared VPC Networks
+
+```bash
+gcloud compute shared-vpc list-host-projects
+gcloud compute networks list --project=$HOST_PROJECT
+```
+
+### Enable Shared VPC on Service Project
+
+```bash
+gcloud compute projects enable-shared-vpc $SERVICE_PROJECT
+
+# Attach service project to host
+gcloud compute shared-vpc associated-projects add $SERVICE_PROJECT \
+  --host-project=$HOST_PROJECT
+```
+
+---
+
+## VPC Peering
+
+### Create VPC Peering
+
+```bash
+# From network A
+gcloud compute networks peerings create $PEERING_NAME \
+  --network=$NETWORK_A \
+  --peer-project=$PROJECT_B \
+  --peer-network=$NETWORK_B \
+  --export-custom-routes \
+  --import-custom-routes
+```
+
+### List Peerings
+
+```bash
+gcloud compute networks peerings list --network=$NETWORK
+```
+
+---
+
+## Useful Queries
+
+### Find Subnet by IP Range
+
+```bash
+gcloud compute networks subnets list \
+  --filter="ipCidrRange:$IP_RANGE" \
+  --regions=us-central1
+```
+
+### Find Resources Using Specific Network
+
+```bash
+# Cloud Run services
+gcloud run services list \
+  --filter="metadata.annotations.run.googleapis.com/network-name:$NETWORK"
+
+# Cloud Run jobs
+gcloud run jobs list \
+  --filter="metadata.annotations.run.googleapis.com/network-name:$NETWORK"
+```
+
+### Check VPC Flow Logs Status
+
+```bash
+gcloud compute networks subnets describe $SUBNET \
+  --region=us-central1 \
+  --format="value(logConfig.enable)"
+```

package/skills/cicd/google-cloud/release-check.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const WEEK_MS = 7 * DAY_MS;
+const here = dirname(fileURLToPath(import.meta.url));
+
+function readJson(path, fallback = {}) {
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return fallback; }
+}
+
+function frontmatterValue(text, key) {
+  const frontmatter = /^---\n([\s\S]*?)\n---/.exec(text)?.[1] ?? '';
+  const match = new RegExp('^' + key + ':\\s*([^\\n]+)$', 'm').exec(frontmatter);
+  return match?.[1].trim().replace(/^['"]|['"]$/g, '') ?? null;
+}
+
+function repositoryOf(source) {
+  const value = String(source ?? '').trim();
+  const match = /^(?:git@github\.com:|https:\/\/github\.com\/)?([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?)(?:\.git)?$/.exec(value);
+  return match?.[1] ?? null;
+}
+
+function stableVersion(value) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(String(value ?? '').trim());
+  return match ? match.slice(1).map(Number) : null;
+}
+
+function newer(left, right) {
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] !== right[index]) return left[index] > right[index];
+  }
+  return false;
+}
+
+function writeCache(path, value) {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(value));
+  } catch { /* A read-only cache must not block skill use. */ }
+}
+
+function main(now = Date.now()) {
+  if (process.env.ONEABOVEIO_NO_UPDATE_CHECK) return;
+  const skill = readFileSync(join(here, 'SKILL.md'), 'utf8');
+  const name = frontmatterValue(skill, 'name');
+  const localVersion = stableVersion(frontmatterValue(skill, 'release-version'));
+  if (!name || !localVersion) return;
+
+  const lock = readJson(join(process.env.HOME || homedir(), '.agents', '.skill-lock.json'));
+  const entry = lock.skills?.[name];
+  const repository = repositoryOf(entry?.sourceUrl || entry?.source);
+  if (!repository) return;
+
+  const cacheRoot = process.env.XDG_CACHE_HOME || join(process.env.HOME || homedir(), '.cache');
+  const cachePath = join(cacheRoot, '1aboveio-skills', 'release-check.json');
+  const all = readJson(cachePath);
+  const cache = all[repository] && typeof all[repository] === 'object' ? all[repository] : {};
+
+  if (!cache.lastCheck || now - cache.lastCheck >= DAY_MS) {
+    const result = spawnSync('gh', ['api', 'repos/' + repository + '/releases/latest', '--jq', '.tag_name'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 1500,
+    });
+    cache.lastCheck = now;
+    if (result.status === 0 && stableVersion(result.stdout)) cache.latestTag = result.stdout.trim();
+    else delete cache.latestTag;
+    all[repository] = cache;
+    writeCache(cachePath, all);
+  }
+
+  const latestVersion = stableVersion(cache.latestTag);
+  if (!latestVersion || !newer(latestVersion, localVersion)) return;
+  if (cache.notifiedTag === cache.latestTag && cache.notifiedAt && now - cache.notifiedAt < WEEK_MS) return;
+
+  cache.notifiedTag = cache.latestTag;
+  cache.notifiedAt = now;
+  all[repository] = cache;
+  writeCache(cachePath, all);
+  const command = `npx skills@1.5.23 add '${repository}#${cache.latestTag}' --global --agent universal claude-code --skill ${name} --yes`;
+  process.stdout.write(
+    `UPDATE_AVAILABLE: A newer 1AboveIO skills release (${cache.latestTag}) is available; this skill is `
+      + `v${localVersion.join('.')}. Ask once whether to refresh ${name}. On approval run \`${command}\`. `
+      + 'The refreshed instructions apply next session. Either way, continue the current task and do not ask again this session.\n',
+  );
+}
+
+try { main(); } catch { /* Update checks are advisory and always fail silent. */ }

package/skills/cicd/google-cloud/scripts/create-sa.sh

@@ -0,0 +1,36 @@
+#!/bin/bash
+# Create Service Account with Standard Roles
+# Usage: ./create-sa.sh [sa-name] [display-name] [roles...]
+
+set -e
+
+SA_NAME="${1:-my-sa}"
+DISPLAY_NAME="${2:-$SA_NAME}"
+PROJECT_ID="${PROJECT_ID:-your-project-id}"
+
+# Optional roles (default: cloudsql.client, secretmanager.secretAccessor)
+shift 2
+ROLES=("${@:-roles/cloudsql.client roles/secretmanager.secretAccessor)}")
+
+SA_EMAIL="${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com"
+
+echo "Creating Service Account: $SA_NAME"
+echo "Email: $SA_EMAIL"
+echo "Roles: ${ROLES[*]}"
+
+# Create SA
+gcloud iam service-accounts create "$SA_NAME" \
+  --display-name="$DISPLAY_NAME" \
+  --project=$PROJECT_ID
+
+# Grant roles
+for ROLE in "${ROLES[@]}"; do
+  echo "Granting $ROLE..."
+  gcloud projects add-iam-policy-binding $PROJECT_ID \
+    --member="serviceAccount:$SA_EMAIL" \
+    --role="$ROLE"
+done
+
+echo ""
+echo "Service Account created successfully!"
+echo "Email: $SA_EMAIL"

package/skills/cicd/google-cloud/scripts/gcp-config.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+# Project: ${PROJECT_ID:-your-project-id}
+# Region: us-central1
+
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+log_info() { echo -e "${GREEN}[INFO]${NC} $1"; }
+log_warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }
+log_error() { echo -e "${RED}[ERROR]${NC} $1"; }
+
+# Configuration
+PROJECT_ID="${PROJECT_ID:-your-project-id}"
+PROJECT_NUMBER="${PROJECT_NUMBER:-your-project-number}"
+REGION="us-central1"
+
+# Set project
+gcloud config set project $PROJECT_ID
+
+# Validate project
+if ! gcloud projects describe $PROJECT_ID &>/dev/null; then
+  log_error "Project $PROJECT_ID not accessible"
+  exit 1
+fi
+
+log_info "Project $PROJECT_ID configured successfully"

package/skills/cicd/google-cloud/scripts/grant-iap.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+# Grant IAP Access to Service Account
+# Usage: ./grant-iap-access.sh [service-account-email] [backend-service-name]
+
+set -e
+
+SA_EMAIL="${1:-e2e-runner@${PROJECT_ID:-your-project-id}.iam.gserviceaccount.com}"
+BACKEND_SERVICE="${2:-my-backend-service}"
+PROJECT_ID="${PROJECT_ID:-your-project-id}"
+
+echo "Granting IAP access to: $SA_EMAIL"
+echo "Backend service: $BACKEND_SERVICE"
+
+# Grant IAP access on backend service
+gcloud iap web add-iam-policy-binding \
+  --project=$PROJECT_ID \
+  --resource-type=backend-services \
+  --service=$BACKEND_SERVICE \
+  --member="serviceAccount:$SA_EMAIL" \
+  --role="roles/iap.httpsResourceAccessor"
+
+echo ""
+echo "IAP access granted successfully!"
+echo ""
+echo "Next: Use signed JWT to access IAP-protected service:"
+echo ""
+cat << 'EOF'
+SERVICE_URL="https://${BACKEND_SERVICE}-${HASH}-uc.a.run.app"
+SIGNER_SA="signer-sa@${PROJECT_ID}.iam.gserviceaccount.com"
+
+NOW="$(date +%s)"
+cat > /tmp/iap-jwt.json <<JSON
+{"iss":"${SIGNER_SA}","sub":"${SIGNER_SA}","aud":"${SERVICE_URL}/*","iat":${NOW},"exp":$((NOW+600))}
+JSON
+
+gcloud iam service-accounts sign-jwt /tmp/iap-jwt.json /tmp/iap-jwt.jwt \
+  --iam-account="${SIGNER_SA}"
+
+TOKEN="$(cat /tmp/iap-jwt.jwt)"
+curl -i "${SERVICE_URL}/" -H "Authorization: Bearer ${TOKEN}"
+EOF

package/skills/cicd/google-cloud/scripts/setup-secrets.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+# Setup Secrets for Service
+# Usage: ./setup-secrets.sh [service-name]
+
+set -e
+
+SERVICE_NAME="${1:-my-service}"
+PROJECT_ID="${PROJECT_ID:-your-project-id}"
+ENVIRONMENTS=("dev" "staging" "prod")
+
+for ENV in "${ENVIRONMENTS[@]}"; do
+  SECRET_NAME="${SERVICE_NAME}-database-url-${ENV}"
+  
+  echo "Creating secret: $SECRET_NAME"
+  
+  # Create secret (ignore if exists)
+  gcloud secrets create "$SECRET_NAME" \
+    --replication-policy="automatic" \
+    --project=$PROJECT_ID 2>/dev/null || true
+  
+  # Add version placeholder (user should update with actual value)
+  echo -n "postgresql://user:pass@host/${SERVICE_NAME}-${ENV}" | \
+    gcloud secrets versions add "$SECRET_NAME" \
+      --data-file=- \
+      --project=$PROJECT_ID
+done
+
+# Create shared secret key
+SHARED_SECRET="${SERVICE_NAME}-shared-secret"
+echo "Creating shared secret: $SHARED_SECRET"
+
+gcloud secrets create "$SHARED_SECRET" \
+  --replication-policy="automatic" \
+  --project=$PROJECT_ID 2>/dev/null || true
+
+# Generate random key
+openssl rand -hex 32 | \
+  gcloud secrets versions add "$SHARED_SECRET" \
+    --data-file=- \
+    --project=$PROJECT_ID
+
+echo ""
+echo "Secrets created successfully!"
+echo ""
+echo "Grant access to Cloud Run SA:"
+echo "  gcloud secrets add-iam-policy-binding ${SERVICE_NAME}-database-url-dev \\"
+echo "    --member=\"serviceAccount:${PROJECT_ID}-run@developer.gserviceaccount.com\" \\"
+echo "    --role=\"roles/secretmanager.secretAccessor\""

package/skills/cicd/mergify/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) 2026 1AboveIO

package/skills/cicd/mergify/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: mergify
+description: "Mergify merge queue and stacked PRs (`mergify stack`): config, rules, queue status, delivery. Use whenever a merge queue or stack is involved, including plain asks ('watch #123 till it merges', 'where is #412 in the queue', 'push this stack'): `gh pr view`/`gh pr checks` cannot see a dequeue; use `mergify queue show` and the bundled watcher. Also: a hook saying 'use mergify stack push', a missing Change-Id; authoring or debugging `.mergify.yml`, queue rules, merge protections, batch size, the ruleset making merges queue-only; enqueue policy (`@mergifyio queue` vs `auto_merge_conditions`); a push dequeuing a queued PR; bypass actors; freezing a branch. Failures: a PR stuck, queued but never merging, or merged unqueued; CI green on GitHub but unmet in Mergify; a batch going red or bisecting; a queue check missing rather than failing. Outranks the vendor mergify-* skills. NOT for pushing a PR in a repo without stack hooks (github-flow), workflow YAML (github-actions), or GCP deploy pipelines (cloud-deploy)."
+release-version: 0.36.0
+---
+**Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
+# Mergify Merge Queue
+
+Default setup: hybrid enqueue (auto when ready + approved + `gate` green; `@mergifyio queue`
+otherwise), batches of 3 with a 10-second wait, one required `gate` check, queue-only merges
+through the ruleset, no checks timeout, no CI rerun on push to `main`, and
+[stack-ready](references/configuration.md#stack-ready): Mergify's ruleset bypass `exempt` for GitHub-native stacks.
+Requires mergify CLI **2026.10.5 or newer** ([stacks.md](references/stacks.md#cli-version)).
+
+**Find your task below, then read that row's target.** This page routes; the references act.
+
+## Routing
+
+| Your task | Read | The rule you must not miss |
+|---|---|---|
+| **Get an open or just-pushed PR merged** | [`references/watch-contract.md`](references/watch-contract.md#enqueue-before-you-watch) | Enqueue, *then* watch — the watch never enqueues, so a watch started on a PR nothing will enqueue can only end `STALLED`. A push to an already-queued PR dequeues it (`pull-request-updated`): the verdict is stale, re-validate before re-enqueuing. Several ready at once? Enqueue them together — next row. |
+| **Deliver several ready PRs at once (a stack, an epic's units, a burst)** | [`references/watch-contract.md`](references/watch-contract.md#batch-delivery--enqueue-the-whole-ready-set-together) | Enqueue the whole ready set **together**, then watch: PRs riding one batch cost one CI run, and a red batch bisects to the culprit while the rest carry on. "If possible" is the point — a lone PR, or stragglers still waiting on review/CI/conflict, never hold the batch window open. |
+| **Push, open, or update a PR in a stack repo** (hook says "Use 'mergify stack push'", `Change-Id` missing) | [`references/stacks.md`](references/stacks.md) | Push with `scripts/stack-push.mjs`. One commit = one PR; amend to fix. Never `--no-verify`. |
+| A stacked PR gets no CI, conflicts after its parent lands, or is dequeued "could not be retargeted onto … `main`" | [`references/configuration.md`](references/configuration.md#stack-ready), then [`references/traps.md`](references/traps.md) | Make the repo stack-ready (native stacks: Mergify's ruleset bypass `exempt`; `Depends-On` stacks also need PR CI on every base, commits kept, auto-delete head branches); then `mergify stack push --force-rebase` for a stuck tip. |
+| Author or change `.mergify.yml` | [`references/configuration.md`](references/configuration.md) | [Rule 1](#rule-1--fetch-the-docs-before-writing-config): never write config from memory; finish with `validate` **and** `simulate`. |
+| **Watch a PR through the queue** | [`references/watch-contract.md`](references/watch-contract.md) | **[Rule 2](#rule-2--never-hand-roll-a-watcher): run the bundled watcher, never hand-roll one.** A watch observes a *progression*, not one state. |
+| **The queue feels slow, or is it worth it?** | [`references/diagnosis.md`](references/diagnosis.md#measuring-a-slow-queue) | Measure first-try merge rate and same-SHA requeues from the event log, then fix the flaky queue check. Never move a queue-only check onto the PR lane, and never rerun CI on push to `main` ([rules](references/configuration.md#the-queue-run-is-the-integration-run)). |
+| Check status — "where is my PR?", "why is it stuck?" | [`references/diagnosis.md`](references/diagnosis.md#querying-pr-and-queue-status) | `mergify queue show <number> -v` names the single blocking condition (bare number, never a URL; the CLI takes `--repository <owner/repo>`, never `--repo`; the bundled watcher below takes `--repo`); nothing else in the toolchain does. `gh pr checks` is CI truth, never queue truth. |
+| A PR merged without ever being queued | [`references/branch-protection.md`](references/branch-protection.md) | Make the queue mandatory with the ruleset's `update` rule; a required status check alone does not. |
+| Set up, audit, freeze, or protect a branch | [`references/configuration.md`](references/configuration.md#setup-checklist), then [`references/branch-protection.md`](references/branch-protection.md) | Bypass is granted per *ruleset*, never per rule — so Mergify bypasses the required check too. |
+| A batch keeps going red, bisects, or hangs on a check | [`references/traps.md`](references/traps.md) | An *absent* check reads as permanently unmet. That is not the same as failing. |
+| Something broke and you want the known landmines | [`references/traps.md`](references/traps.md) | Each one has been hit in production; skim it before debugging from first principles. |
+
+**Templates** — both required. The `.mergify.yml` decides what the queue *does*;
+the ruleset is what stops anyone bypassing the queue entirely.
+
+- [`assets/templates/mergify.yml`](assets/templates/mergify.yml) — copy to the
+  repo root as `.mergify.yml` and fill in the placeholders.
+- [`assets/templates/ruleset.json`](assets/templates/ruleset.json) — the GitHub
+  branch ruleset that makes the queue mandatory.
+
+**Scripts** — run these rather than reimplementing what they do:
+
+| Script | Use |
+|---|---|
+| [`scripts/watch-pr-delivery.mjs`](scripts/watch-pr-delivery.mjs) | Watch an enqueued PR to a terminal verdict. See [Rule 2](#rule-2--never-hand-roll-a-watcher). Also profiles the CI it waited on and warns when one job runs over 5 minutes ([CI profile](references/watch-contract.md#ci-profile)). |
+| [`scripts/stack-push.mjs`](scripts/stack-push.mjs) | Push a stack: `--trunk origin/main`, PR bodies kept, PR numbers reported, `--enqueue` for the whole set. See [stacks.md](references/stacks.md). |
+| [`scripts/audit.mjs`](scripts/audit.mjs) | Audit a `.mergify.yml` and its workflows against this skill's defaults — the shape `config validate` cannot check. |
+
+## Non-Negotiable Rules
+
+### Rule 1 — Fetch the docs before writing config
+
+Never write `.mergify.yml` from memory:
+
+```bash
+curl -s https://docs.mergify.com/mergify-configuration-schema.json -o /tmp/mergify-schema.json
+```
+
+Pages: `https://docs.mergify.com/merge-queue/rules`, `/merge-queue/batches`,
+`/merge-protections/setup`, `/commands`; index at `https://docs.mergify.com/llms.txt`.
+Finish with both:
+
+```bash
+mergify config validate                                              # schema
+mergify config simulate https://github.com/<owner>/<repo>/pull/<n>   # behaviour
+```
+
+### Rule 2 — Never hand-roll a watcher
+
+Watch a PR through the queue only with the bundled watcher; never poll `gh pr view` yourself.
+
+```bash
+node ~/.agents/skills/mergify/scripts/watch-pr-delivery.mjs --repo <owner/repo> --pr <number>
+```
+
+- Enqueue first; the watch never enqueues.
+- When it ends, read the last log line (`{"ciProfileSummary":true,…}`), not just the exit code,
+  and pass any slow job to the user.
+- State machine, labels, dequeue reasons: [`references/watch-contract.md`](references/watch-contract.md).
+
+### Rule 3 — Enqueue the whole ready set together
+
+When several PRs against the same base are ready (a stack, an epic's units, a burst), enqueue
+them all in one pass, then watch them together. Never enqueue serially. Never hold a ready PR
+for a straggler, except a `resolve-issues` chain line: enqueue only its deepest PR. A stack:
+`scripts/stack-push.mjs --enqueue`. Grouping rules:
+[`references/watch-contract.md`](references/watch-contract.md#batch-delivery--enqueue-the-whole-ready-set-together).
+
+## Related Skills
+
+- [github-flow](../github-flow/SKILL.md) — delivers a change in every flow; calls this skill to
+  enqueue and watch in the merge-queue flow
+- [github-actions](../github-actions/SKILL.md) — the CI workflows the queue gates on
+- [cloud-debug](../cloud-debug/SKILL.md) — when a Cloud Build job is failing
+- [resolve-issues](../../engineering/resolve-issues/SKILL.md) (and its `rush-issues` shortcut) — consumes this skill's delivery
+  watch contract when it delivers merge-ready PRs through Mergify
+- `mergify-config`, `mergify-merge-queue`, `mergify-merge-protections`, `mergify-ci`,
+  `mergify-stack` (vendor plugin skills) — reference for raw CLI invocation. They document
+  *how to call* the commands; this skill decides *what the config should say* and owns the
+  GitHub-side enforcement. On any conflict, this skill wins.
+