opencode-skills-collection 4.0.45 → 4.0.46

package/bundled-skills/graceful-shutdown/SKILL.md

@@ -0,0 +1,379 @@
+---
+name: graceful-shutdown
+description: "Implement graceful shutdown for servers and workers: drain connections, finish in-flight work, release resources, and exit cleanly on SIGTERM/SIGINT."
+category: development
+risk: safe
+source: self
+source_type: self
+date_added: "2026-08-27"
+author: Prajeeth-12
+tags: [graceful-shutdown, signals, SIGTERM, SIGINT, drain, health-check, kubernetes, docker, production, resilience]
+tools: [claude, cursor, codex, gemini]
+license: "MIT"
+---
+
+# Graceful Shutdown
+
+## Overview
+
+A skill for implementing graceful shutdown in servers, workers, and long-running processes. Ensures in-flight requests complete, background jobs finish or checkpoint, database connections close cleanly, and the process exits with a proper status code. Essential for zero-downtime deployments in container orchestrators (Kubernetes, ECS, Docker Compose) and bare-metal process managers (systemd, PM2).
+
+## When to Use This Skill
+
+- Use when building an HTTP server that must not drop active connections during deploys
+- Use when writing a background worker that processes jobs from a queue
+- Use when deploying to Kubernetes, Docker, or any environment that sends SIGTERM before killing
+- Use when the user says "graceful shutdown", "drain connections", "handle SIGTERM", "zero downtime", or "don't kill active requests"
+- Use when implementing health check endpoints (`/healthz`, `/readyz`) for orchestrators
+
+## How It Works
+
+### Step 1: Register signal handlers early
+
+Trap `SIGTERM` (orchestrator shutdown) and `SIGINT` (Ctrl+C) at process startup. Set a flag so the application knows it is shutting down.
+
+```typescript
+let isShuttingDown = false;
+
+function onShutdownSignal(signal: string): void {
+  if (isShuttingDown) return; // prevent double-shutdown
+  isShuttingDown = true;
+  console.log(`Received ${signal}, starting graceful shutdown...`);
+  shutdown();
+}
+
+process.on("SIGTERM", () => onShutdownSignal("SIGTERM"));
+process.on("SIGINT", () => onShutdownSignal("SIGINT"));
+```
+
+### Step 2: Stop accepting new work
+
+Immediately stop the server from accepting new connections. For HTTP servers, call `server.close()`. For queue workers, stop polling for new jobs.
+
+```typescript
+async function shutdown(): Promise<void> {
+  // 1. Stop accepting new connections
+  server.close(() => {
+    console.log("Server closed — no new connections accepted");
+  });
+
+  // 2. Mark health check as not-ready so load balancers stop routing
+  //    (readiness probe returns 503 from this point)
+}
+```
+
+### Step 3: Drain in-flight work with a deadline
+
+Wait for active requests and background tasks to finish, but enforce a hard deadline so the process never hangs indefinitely.
+
+```typescript
+const DRAIN_TIMEOUT_MS = 25_000; // must be less than orchestrator's terminationGracePeriodSeconds
+
+async function drainAndExit(): Promise<void> {
+  const deadline = setTimeout(() => {
+    console.error("Drain timeout reached — forcing exit");
+    process.exit(1);
+  }, DRAIN_TIMEOUT_MS);
+  deadline.unref(); // don't keep the event loop alive just for the timer
+
+  try {
+    // Wait for active connections to finish
+    await waitForActiveConnections();
+
+    // Flush buffered data (logs, metrics, queues)
+    await flushBuffers();
+
+    // Close external resource handles
+    await closeResources();
+
+    console.log("Graceful shutdown complete");
+    process.exit(0);
+  } catch (err) {
+    console.error("Error during shutdown:", err);
+    process.exit(1);
+  }
+}
+```
+
+### Step 4: Implement readiness and liveness probes
+
+Orchestrators use these to decide whether to route traffic and whether to restart the container.
+
+```typescript
+import { createServer, IncomingMessage, ServerResponse } from "node:http";
+
+function handleHealthCheck(req: IncomingMessage, res: ServerResponse): void {
+  if (req.url === "/healthz") {
+    // Liveness: is the process alive and not deadlocked?
+    res.writeHead(200).end("ok");
+    return;
+  }
+
+  if (req.url === "/readyz") {
+    // Readiness: should traffic be routed here?
+    if (isShuttingDown) {
+      res.writeHead(503).end("shutting down");
+    } else {
+      res.writeHead(200).end("ready");
+    }
+    return;
+  }
+}
+```
+
+### Step 5: Track active connections
+
+Maintain a count of in-flight requests so you know when draining is complete.
+
+```typescript
+let activeConnections = 0;
+let drainResolve: (() => void) | null = null;
+
+function onRequestStart(): void {
+  activeConnections++;
+}
+
+function onRequestEnd(): void {
+  activeConnections--;
+  if (isShuttingDown && activeConnections === 0 && drainResolve) {
+    drainResolve();
+  }
+}
+
+function waitForActiveConnections(): Promise<void> {
+  if (activeConnections === 0) return Promise.resolve();
+  return new Promise((resolve) => {
+    drainResolve = resolve;
+  });
+}
+```
+
+## Examples
+
+### Example 1: Express.js server with graceful shutdown
+
+```typescript
+import express from "express";
+import { createServer } from "node:http";
+
+const app = express();
+const server = createServer(app);
+let isShuttingDown = false;
+let activeRequests = 0;
+
+// Track in-flight requests
+app.use((req, res, next) => {
+  if (isShuttingDown) {
+    res.setHeader("Connection", "close");
+    res.status(503).json({ error: "Server is shutting down" });
+    return;
+  }
+  activeRequests++;
+  res.on("finish", () => activeRequests--);
+  next();
+});
+
+// Health endpoints
+app.get("/healthz", (_, res) => res.send("ok"));
+app.get("/readyz", (_, res) => {
+  res.status(isShuttingDown ? 503 : 200).send(isShuttingDown ? "draining" : "ready");
+});
+
+// Application routes
+app.get("/api/data", async (req, res) => {
+  const data = await fetchData();
+  res.json(data);
+});
+
+// Graceful shutdown
+function shutdown(signal: string): void {
+  if (isShuttingDown) return;
+  isShuttingDown = true;
+  console.log(`${signal} received — draining ${activeRequests} active requests`);
+
+  server.close();
+
+  const forceExit = setTimeout(() => {
+    console.error("Forced exit — drain timeout exceeded");
+    process.exit(1);
+  }, 25_000);
+  forceExit.unref();
+
+  const poll = setInterval(() => {
+    if (activeRequests === 0) {
+      clearInterval(poll);
+      console.log("All requests drained — exiting cleanly");
+      process.exit(0);
+    }
+  }, 100);
+}
+
+process.on("SIGTERM", () => shutdown("SIGTERM"));
+process.on("SIGINT", () => shutdown("SIGINT"));
+
+server.listen(3000, () => console.log("Server ready on :3000"));
+```
+
+### Example 2: Python FastAPI with graceful shutdown
+
+```python
+import asyncio
+import signal
+from contextlib import asynccontextmanager
+from fastapi import FastAPI, Request, Response
+
+active_requests = 0
+is_shutting_down = False
+shutdown_event = asyncio.Event()
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Startup
+    loop = asyncio.get_event_loop()
+    loop.add_signal_handler(signal.SIGTERM, begin_shutdown)
+    yield
+    # Shutdown — wait for in-flight requests
+    if active_requests > 0:
+        try:
+            await asyncio.wait_for(shutdown_event.wait(), timeout=25.0)
+        except asyncio.TimeoutError:
+            print(f"Drain timeout — {active_requests} requests abandoned")
+    print("Shutdown complete")
+
+
+app = FastAPI(lifespan=lifespan)
+
+
+def begin_shutdown():
+    global is_shutting_down
+    is_shutting_down = True
+    print(f"SIGTERM received — draining {active_requests} requests")
+    if active_requests == 0:
+        shutdown_event.set()
+
+
+@app.middleware("http")
+async def track_requests(request: Request, call_next):
+    global active_requests
+    if is_shutting_down:
+        return Response("Service shutting down", status_code=503)
+    active_requests += 1
+    try:
+        response = await call_next(request)
+        return response
+    finally:
+        active_requests -= 1
+        if is_shutting_down and active_requests == 0:
+            shutdown_event.set()
+
+
+@app.get("/healthz")
+async def healthz():
+    return {"status": "ok"}
+
+
+@app.get("/readyz")
+async def readyz():
+    if is_shutting_down:
+        return Response("draining", status_code=503)
+    return {"status": "ready"}
+```
+
+### Example 3: Background worker with checkpoint
+
+```typescript
+import { parentPort } from "node:worker_threads";
+
+let isShuttingDown = false;
+let currentJob: { id: string; checkpoint: () => Promise<void> } | null = null;
+
+process.on("SIGTERM", async () => {
+  isShuttingDown = true;
+  console.log("Worker shutting down — finishing current job");
+
+  if (currentJob) {
+    await currentJob.checkpoint();
+    console.log(`Job ${currentJob.id} checkpointed`);
+  }
+
+  process.exit(0);
+});
+
+async function processJobs(queue: JobQueue): Promise<void> {
+  while (!isShuttingDown) {
+    const job = await queue.poll({ timeout: 5000 });
+    if (!job) continue;
+
+    currentJob = job;
+    await job.execute();
+    await queue.ack(job.id);
+    currentJob = null;
+  }
+}
+```
+
+## Best Practices
+
+- Always set a drain timeout shorter than the orchestrator's kill timeout (`terminationGracePeriodSeconds` in Kubernetes defaults to 30s — use 25s for your drain)
+- Return `Connection: close` header on responses sent during draining so HTTP/1.1 clients don't reuse the connection
+- Reject new requests with 503 during shutdown so load balancers learn faster
+- Unref your force-exit timer so it doesn't keep the event loop alive after all work is done
+- Flush async buffers (log transports, metric aggregators, write-ahead logs) before exiting
+- Use `process.exit(0)` for clean shutdown and `process.exit(1)` for timeout/error so orchestrators can distinguish the two
+- Test shutdown behavior explicitly — simulate SIGTERM in integration tests and verify no requests are dropped
+
+## Common Pitfalls
+
+- **Problem:** Kubernetes kills the pod before connections drain because `terminationGracePeriodSeconds` is too short.
+  **Solution:** Set it to at least drain timeout + 5s buffer. If your longest request takes 60s, use `terminationGracePeriodSeconds: 70` and drain timeout of 65s.
+
+- **Problem:** Load balancer keeps sending traffic after SIGTERM because readiness probe still returns 200.
+  **Solution:** Flip the readiness probe to 503 immediately on signal receipt — before starting to drain.
+
+- **Problem:** `server.close()` resolves instantly but connections remain open (keep-alive).
+  **Solution:** Track connections manually and destroy idle keep-alive sockets on shutdown. Active sockets with in-flight requests should drain normally.
+
+- **Problem:** Double shutdown from both SIGTERM and SIGINT (e.g., Docker sends SIGTERM then user hits Ctrl+C).
+  **Solution:** Guard with a `isShuttingDown` flag — ignore the second signal.
+
+- **Problem:** Deadlocked process never exits because drain waits forever.
+  **Solution:** Always have a hard force-exit timeout as the final backstop.
+
+## Kubernetes Configuration
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+spec:
+  template:
+    spec:
+      terminationGracePeriodSeconds: 30
+      containers:
+        - name: app
+          livenessProbe:
+            httpGet:
+              path: /healthz
+              port: 3000
+            initialDelaySeconds: 5
+            periodSeconds: 10
+          readinessProbe:
+            httpGet:
+              path: /readyz
+              port: 3000
+            initialDelaySeconds: 2
+            periodSeconds: 5
+```
+
+## Limitations
+
+- This skill does not replace environment-specific validation, testing, or expert review.
+- WebSocket and SSE connections require application-level close frames before severing — `server.close()` alone won't gracefully end them.
+- In clustered/multi-process setups (e.g., Node.js `cluster` module), each worker must handle signals independently.
+- Some cloud platforms (Heroku, Railway) send SIGTERM with very short grace periods (10-30s) — adjust drain timeouts accordingly.
+
+## Related Skills
+
+- `@api-rate-limit-handler` — Resilient retry and backoff for outbound requests
+- `@circuit-breaker` — When to stop retrying entirely and fail fast
+- `@error-handling` — Structured error handling patterns

package/bundled-skills/grok-delegate/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: grok-delegate
+description: Delegate coding tasks to the Grok Build CLI only when the user explicitly
+  requests it, while the orchestrator retains review and landing responsibility.
+risk: safe
+category: agent-orchestration
+source: https://github.com/amElnagdy/delegate-skills
+source_repo: amElnagdy/delegate-skills
+source_type: community
+date_added: '2026-08-26'
+license: MIT
+license_source: https://github.com/amElnagdy/delegate-skills/blob/master/LICENSE
+compatibility: Requires the `grok` CLI (Grok Build) installed and authenticated (`grok
+  login`, or `XAI_API_KEY`; beta access needs an eligible xAI subscription), Node
+  18+, and git. The orchestrating agent must be able to run shell commands and read
+  files. Shell examples assume bash/zsh (macOS/Linux, or Git Bash/WSL on Windows).
+metadata:
+  version: 0.5.0
+---
+# Grok Delegate
+
+## When to Use
+
+- You want to delegate a bounded coding task to a separate `grok` implementer (`Grok Build`) and then review its diff yourself.
+- The user explicitly asked for delegation to this implementer.
+
+You are the **orchestrator**. This skill lets you hand a bounded coding task to a separate
+**implementer** — the Grok Build CLI (`grok`) — then review what it produced and land it yourself. You
+write the brief and own the judgment; Grok does the typing under an explicit autonomy profile; you
+verify and commit.
+
+Nothing here is specific to one orchestrating agent. The loop needs only the ability to run a shell
+command and read a file, so it works the same whether you are Claude Code, Cursor, OpenCode with a
+selected model, or any comparable agent. (It is designed for Claude Code and Cursor; treat other
+orchestrators as designed-for, not yet proven.)
+
+## When NOT to use this
+
+- The task is small enough to just do inline — delegation overhead is not worth it.
+- The `grok` CLI is not installed, not authenticated, or the account lacks Grok Build beta access.
+- You want to write the code yourself, or you only need a review without an implementer run.
+
+## Prerequisites (check once)
+
+1. `grok version` succeeds. If not, install on any platform with
+   `npm i -g @xai-official/grok` (or use the installer from xAI's official Grok CLI docs) and
+   authenticate (`grok login`, or `grok login --device-auth` on headless hosts, or set
+   `XAI_API_KEY`).
+2. **Confirm which `grok` is on PATH.** `command -v grok` shows the active binary and `grok version`
+   its version — the relay records the version it ran into `result.json`, so a stale binary is visible
+   after the fact.
+3. You are in (or will point `--cd` at) the target git repository.
+
+## The loop
+
+Run these five steps per task. Steps 1, 4, and 5 are your judgment; 2 and 3 are mechanical.
+
+### 1. Write the brief
+
+Grok sees **only** the text you send — no orchestrator chat history, no shared context. Everything the
+task needs goes in the brief: the goal, the current state, what to change, what to leave untouched,
+the project's **actual** gate commands (discover them from the repo's CLAUDE.md/AGENTS.md/Makefile —
+do not assume), and a report contract. Tell Grok it will **not** commit (you will). Keep one task per
+brief. Full guidance and a template: [references/writing-the-brief.md](references/writing-the-brief.md).
+
+### 2. Dispatch
+
+Send the brief to Grok with the bundled helper. It wraps `grok -p`, captures the run, and writes a
+structured `result.json` — so your only job is "run a command, read a file." (`<skill-dir>` below is
+this skill's installed directory — the folder containing this `SKILL.md`, i.e. the directory you loaded
+the skill from. Claude Code prints it as "Base directory for this skill" when the skill loads; on other
+orchestrators use that same directory — if unsure where it landed, run
+`find ~ -name relay.mjs -path '*grok-delegate*'` and substitute the directory above it.)
+
+```bash
+node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
+# read-only (review/diagnosis; best-effort — verify touchedFiles): add --read-only
+# continue the previous Grok session:       add --resume-last  (send only the delta brief)
+# hard time limit (watchdog):               add --timeout 2h  (default: off; implementation runs routinely need 1-2h)
+# see all options:                          node .../relay.mjs --help
+```
+
+The helper defaults to a write-capable (`workspace-write`) autonomy profile — `--always-approve` plus
+`--sandbox workspace` — and writes its artifacts to a temp dir, so the repo under review stays clean.
+It **never commits** — see step 5. Mechanics, flags, and the `result.json` shape:
+[references/dispatch-and-poll.md](references/dispatch-and-poll.md).
+
+### 3. Wait for completion
+
+The helper blocks until Grok finishes, so back it with whatever your orchestrator offers and resume
+when it returns:
+
+- **Claude Code:** run the Bash call with `run_in_background: true`; you are notified on completion.
+- **Plain shell / other agents:** run it in the foreground for short tasks, or background it and poll
+  the result file — `… &` in bash/zsh (including Git Bash/WSL), or your shell's equivalent (`Start-Job`
+  in PowerShell, `start /b` in cmd). The run is done when `result.json` exists with a `status`. (A
+  pre-run usage error — bad args or an empty brief — instead exits with code 2 and a stderr message and
+  writes no result file, so check the exit code too. A missing `grok` binary exits 127 but *does* write
+  a `result.json` with status `grok_unavailable`.)
+
+Do not trust progress trackers over reality: a run is finished when `result.json` is written and the
+process has exited. Read the working tree, not a status line. The implementer's full report is
+the `finalMessage` field in `result.json` (also printed in full on stdout between the report markers).
+
+### 4. Review — do not trust the self-report
+
+Grok's `result.json` includes its own summary and gate claims. **Re-verify, don't accept:**
+
+- **Re-run the project's gates yourself** (the test/lint/build commands from step 1). Never take
+  "gates passed" on faith.
+- **Read the diff** against the brief: did Grok do what was asked, nothing more (scope creep) and
+  nothing less? `touchedFiles` in the result is your starting point.
+- **Run the relevant guard skills** on the diff if you have them installed (clean-code-guard,
+  test-guard, etc. from `guard-skills`) — this skill produces the work; those skills judge it.
+- For schema/migration changes, round-trip them; for removals, grep for dangling references.
+
+Full checklist: [references/review-and-land.md](references/review-and-land.md).
+
+### 5. Land it
+
+**The orchestrator commits.** Only after the gates pass and the diff holds:
+
+- Commit the verified work yourself, with a clear message.
+- If it needs changes, send a delta brief with `--resume-last` (don't restate the whole task) and
+  review again.
+
+## Autonomy model
+
+Grok's default permission mode is `ask`, which **blocks on approval prompts in a headless pipe**. The
+relay therefore always sets autonomy explicitly:
+
+| Relay flag | What Grok gets | Use when |
+| --- | --- | --- |
+| *(default)* | `--always-approve --sandbox workspace` | Normal implementation — writes scoped to the working tree |
+| `--read-only` | `--sandbox read-only --permission-mode plan` | Review / diagnosis — **best-effort, not enforced** (see caveat below) |
+| `--full-access` | `--always-approve --sandbox off` | Explicit opt-in when the task needs unrestricted tools |
+
+`--always-approve` alone would approve *all* tools (writes, shell, network) — closer to unrestricted
+than to a workspace-scoped write. Pairing it with `--sandbox workspace` is what keeps the default
+safe. Reach for `--full-access` only when the human asks for it.
+
+**`--read-only` is best-effort, not a hard guarantee.** The read-only sandbox restricts out-of-workspace
+filesystem/network access, not grok's own edit tool, and headless `plan` mode is advisory — a run
+verified here still wrote the working tree when told to. Use `--read-only` to *signal* review intent,
+but always confirm `touchedFiles` afterward; treat the diff, not the flag, as the guarantee. The relay
+automates a reporting tripwire: it compares parsed git porcelain and fingerprints the working-tree
+identity and index entries of Git-visible paths that were already dirty. `readOnlyViolation` is `true`
+when either signal proves a change, `false` when coverage is complete and detects none, and `null` when
+coverage is incomplete. Ignored paths, submodule internals, perfect restores, and attribution of
+concurrent changes remain outside it, so the diff
+review stays the guarantee.
+
+## Authorization model
+
+Delegation is something the human opts into. Once they have ("run this queue", "proceed"), committing
+verified, gate-passing work is the agreed contract — that is the whole point. Two limits on that
+mandate: **surface, don't absorb** (report Grok's design decisions, defensible-but-unasked turns, and
+non-blocking nitpicks rather than silently keeping them) and **stop for scope changes** (if correct
+completion needs going beyond the brief, ask — don't expand the mandate yourself). The full treatment
+is in [references/review-and-land.md](references/review-and-land.md).
+
+## References
+
+- [references/writing-the-brief.md](references/writing-the-brief.md) — how to write a brief Grok can
+  execute blind: structure, XML blocks, the report contract, embedding the real gate commands.
+- [references/dispatch-and-poll.md](references/dispatch-and-poll.md) — `relay.mjs` flags, the
+  `result.json` contract, backgrounding per orchestrator, and recovery when a run misbehaves.
+- [references/review-and-land.md](references/review-and-land.md) — the review checklist, the commit
+  boundary, and the rework cycle via `--resume-last`.
+- [references/multi-task-queues.md](references/multi-task-queues.md) — running a sequential queue:
+  carrying constraints forward, progress tracking, and the end-of-run coherence check.
+
+
+## Limitations
+
+- Docs-only import — executable `scripts/relay.mjs` not included; see upstream for full runtime. Requires `grok` CLI, Node 18+, git.
+- Relay never commits — it only returns structured result JSON; you review and land the commit.
+
+> Adapted from [amElnagdy/delegate-skills](https://github.com/amElnagdy/delegate-skills) (MIT) — docs-only, runtime not bundled.