claude-code-arcane 1.0.0

package/skills/websocket-realtime-rooms/references/anti-patterns-checklist.md

@@ -0,0 +1,27 @@
+# Anti-patterns & Checklist — WebSocket Realtime
+
+## Anti-patterns
+
+- WS sin auth en handshake, broadcast global (`io.emit`), sin reconexion automatica
+- Sin ack/idempotencia, presence en memoria del nodo, sin backplane
+- Sin sticky sessions con Socket.IO, trust del cliente para userId
+- `CheckOrigin: return true`, buffer ilimitado, publish desde cliente directo
+- Sin versionado de schema de eventos, Close sin frame, ping en payload JSON
+
+## Checklist
+- [ ] Provider elegido con rationale
+- [ ] JWT en handshake pre-upgrade + subscribe token por canal
+- [ ] Rooms namespaced con tenantId
+- [ ] Sticky sessions en LB (si aplica)
+- [ ] Redis adapter/Pub-Sub backplane
+- [ ] Presence con TTL en Redis
+- [ ] Heartbeat + reconexion exponencial
+- [ ] client_msg_id + unique constraint (idempotencia)
+- [ ] Rate limit por conexion + payload size limit
+- [ ] Backpressure policy definida
+- [ ] Publish server-side only
+- [ ] Schema de eventos versionado
+- [ ] WSS + CheckOrigin estricto
+- [ ] Metricas + alertas
+- [ ] E2E test: connect -> join -> msg -> reconnect -> dedup
+- [ ] Mobile: AppState + NetInfo

package/skills/websocket-realtime-rooms/references/auth-security.md

@@ -0,0 +1,9 @@
+# Auth & Security — WebSocket Realtime
+
+- JWT en handshake (query `?token=` o header), `exp` corto (1h) + refresh
+- Subscribe token separado con ACL por canal (server-side validation)
+- `CheckOrigin` estricto, WSS obligatorio en prod (TLS 1.2+)
+- Rate limit pre-auth por IP + post-auth por user
+- `ReadLimit` 4-16KB, payload size max server-side
+- Sanitizar mensajes antes de broadcast (XSS)
+- Disconnect forzado en logout/password rotation

package/skills/websocket-realtime-rooms/references/client-implementation.md

@@ -0,0 +1,15 @@
+# Client Implementation — WebSocket Realtime
+
+## React — `useRoom` hook
+
+Centrifuge SDK: `getToken` para connection + `getToken` por subscription. Publish via HTTP al backend (canales read-only para clientes). Exponential reconnect built-in.
+
+## React Native
+
+Mismo hook + `AppState` listener (reconnect al foreground) + `NetInfo` (no reconectar sin red). WS muere en iOS background — aceptar y reconectar.
+
+## Observabilidad
+
+Metricas Prometheus: `ws_connections_active`, `ws_messages_sent_total`, `ws_publish_latency_seconds`, `ws_disconnects_total{reason}`, `ws_rate_limited_total`, `ws_backpressure_kicks_total`.
+
+Alertas: connections cae >30% en 5min, timeout disconnects > baseline, publish p95 > 500ms.

package/skills/websocket-realtime-rooms/references/heartbeat-reconnect-backpressure.md

@@ -0,0 +1,17 @@
+# Heartbeat, Reconexion, Backpressure
+
+## Heartbeat
+- Server ping cada 25-30s, timeout 60s
+
+## Reconexion
+- Exponential backoff 500ms->20s + jitter +/-30%
+- Centrifugo/Socket.IO built-in
+
+## Backpressure
+- Buffer >=32 msgs
+- Drop oldest (presence/cursors) o disconnect (chat sin perdida)
+
+## Rate Limiting
+- Mensajes: 10/seg sostenido, burst 20 (token bucket)
+- Joins: 5/seg. Payload max 8KB
+- Handshakes por IP: max N/min con Redis counter+TTL

package/skills/weekly-digest/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: weekly-digest
+description: "Generate a weekly stakeholder digest combining ClickUp/Jira, Git/GitHub, deploys and Slack activity."
+category: "agile"
+argument-hint: "[week: current|last|YYYY-WW]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit
+---
+# Weekly Digest Generator
+
+Reporte ejecutivo semanal combinando actividad de múltiples herramientas.
+
+## Secciones
+
+1. **Executive summary** — 3-5 oraciones alto nivel
+2. **Shipped this week** — features/fixes en prod (merged PRs "production", completed tickets "shipped", release tags)
+3. **In progress** — tickets In Progress, PRs abiertos, progreso vs sprint goal
+4. **Blockers & risks** — tickets bloqueados >3d, PRs sin review >2d, deploys fallidos, incidents
+5. **Metrics** — velocity (pts), PRs merged, bugs closed/opened, DAU/key product metrics (week-over-week comparison)
+6. **Upcoming** — próximos 7d: milestones, releases, events
+7. **Team updates** — nuevos miembros, ausencias, shout-outs
+
+## Data Sources (en paralelo)
+
+- **ClickUp:** searchTasks updated last 7 days
+- **Jira:** JQL `updated >= -7d`
+- **Git/GitHub:** `git log --since="1 week ago"`, `gh pr list --state merged`, `gh pr list --state open`, `gh issue list`, `gh release list`
+- **Deploys:** GitHub Actions runs last week (success/failed/duration)
+- **Analytics (opcional):** DAU/WAU, signups, conversions
+
+## Distribution
+
+| Canal | Método |
+|-------|--------|
+| Slack | `--post-to slack:#channel` (Block Kit, secciones colapsables) |
+| Email | `--post-to email:addr` (HTML con tabla métricas) |
+| Notion/Coda | `--post-to notion:<db_id>` (page nueva en db reportes) |
+| Sheet | `--save-to gsheet:<id>` (append row métricas, tracking longitudinal) |
+
+## Config
+
+`.claude/config/weekly-digest.yml`: default_day, default_hour, projects (name, jira_project/clickup_space, github_repo, slack channel), metrics_source (posthog/mixpanel/ga4), recipients.
+
+## Reglas
+
+- Ejecutivo = terse, max 1 página printed
+- Color coding (🟢🟡🔴) para scannability
+- Links everywhere — no texto largo
+- Comparisons week-over-week para contexto
+- Tone factual, no marketing
+- Timezone consistente

package/skills/worktree-isolation/README.md

@@ -0,0 +1,193 @@
+# worktree-isolation
+
+On-demand worktree isolation for the current directory. Regenerates per-worktree compose overrides + `.env.worktree`, or just prints the current allocation. Companion to [`worktree-isolation-setup`](../worktree-isolation-setup/), which is the one-time per-repo setup that wires everything to run automatically.
+
+This README explains **how worktree isolation works under the hood**. For usage, see [SKILL.md](SKILL.md).
+
+---
+
+## Install
+
+```bash
+npx skills add https://github.com/educabot/team-ai-skills --skill worktree-isolation
+```
+
+> The host repo is private — `npx skills add` clones via Git, so the machine needs GitHub credentials with read access (e.g. `gh auth login` or an SSH key on the account).
+
+After install, invoke with phrases like:
+
+- `isolate worktree`
+- `regenerate worktree ports`
+- `which ports is this worktree using?`
+
+If you also want a SessionStart hook that runs this automatically on every Claude Code session start, install the companion skill:
+
+```bash
+npx skills add https://github.com/educabot/team-ai-skills --skill worktree-isolation-setup
+```
+
+---
+
+## The problem
+
+You're working on a repo whose `docker-compose.yml` looks like:
+
+```yaml
+services:
+  db:
+    image: postgres:16-alpine
+    container_name: my-app-db
+    ports:
+      - "5432:5432"
+```
+
+You want to open a second worktree of the same repo (different branch, different feature) and run its stack in parallel. As soon as you `docker compose up -d` in worktree #2:
+
+- **Port collision**: both worktrees try to bind host port `5432`.
+- **Container name collision**: both try to create a container named `my-app-db`.
+- **Project name collision**: Compose derives `COMPOSE_PROJECT_NAME` from the directory name; if both worktrees live under directories called `repo`, they share a project name and start sharing volumes.
+
+You either (a) tear down worktree #1, (b) hand-edit ports for #2, or (c) live with conflicts. None of those scale.
+
+## The solution
+
+A small Python script that, run inside any worktree, generates per-worktree compose overrides and a `.env.worktree` env file with non-colliding ports and a unique project name. Same worktree path → identical output forever.
+
+This skill exposes the script. The companion [`worktree-isolation-setup`](../worktree-isolation-setup/) skill installs it as a `SessionStart` hook so it runs automatically on every Claude Code session start.
+
+---
+
+## How it works
+
+### 1. Computes a stable `worktree_id`
+
+```
+worktree_id = sha1(absolute_path_to_cwd)[:8]
+```
+
+Same worktree path → identical id forever. The id never changes unless you rename the directory.
+
+### 2. Locates compose files
+
+Globs `docker-compose*.yml` and `compose*.yml` in the cwd, **excluding** previously-generated `*.worktree.yml` overrides.
+
+If no compose files match, the script is a no-op.
+
+### 3. Generates per-compose-file overrides
+
+For every base compose file (e.g. `docker-compose.yml`), it writes a sibling `docker-compose.worktree.yml` containing:
+
+```yaml
+name: my-repo-3f785ada              # COMPOSE_PROJECT_NAME for this stack
+
+services:
+  db:
+    ports: !override                # Compose v2 syntax — replaces the list, doesn't merge
+      - "26680:5432"
+    container_name: my-app-db-3f785ada
+  server:
+    ports: !override
+      - "25154:8000"
+    container_name: my-app-server-3f785ada
+```
+
+Host ports are picked deterministically from a hash of `<worktree_id>:<service>:<container_port>` mapped into the 20000–29999 range. Same triple → same port across runs.
+
+The `!override` tag is critical — without it, Compose **merges** the list (appending the override's ports), causing the original `5432:5432` mapping to coexist with `26680:5432`, which still collides.
+
+### 4. Writes `.env.worktree`
+
+A shell-sourceable env file at the worktree root:
+
+```bash
+COMPOSE_PROJECT_NAME=my-repo-3f785ada
+COMPOSE_FILE=docker-compose.yml:docker-compose.worktree.yml
+WORKTREE_ID=3f785ada
+WORKTREE_SUFFIX=-3f785ada
+
+DB_5432_HOST_PORT=26680
+SERVER_8000_HOST_PORT=25154
+```
+
+The `COMPOSE_FILE` chain means `docker compose up -d` (no `-f` flags) automatically loads the base file plus the override.
+
+The per-port env vars exist for a reason: if the project ran [`worktree-isolation-setup`](../worktree-isolation-setup/) and its compose files use `${DB_5432_HOST_PORT-5432}`, sourcing `.env.worktree` makes those substitutions resolve to the worktree's allocated port without any override file at all. The override file is still emitted as a belt-and-suspenders safety net.
+
+### 5. Excludes generated files from git
+
+Adds `.env.worktree` and `*.worktree.yml` to `.git/info/exclude` (per-checkout, never committed). [`worktree-isolation-setup`](../worktree-isolation-setup/) additionally adds them to `.gitignore` so they're excluded across all checkouts of the repo.
+
+### 6. Idempotency
+
+Same worktree path → identical output. Re-running is a no-op unless:
+- A base compose file's mtime is newer than its override's
+- `--force` is passed
+
+---
+
+## Why both override files **and** env-var substitution?
+
+Both mechanisms accomplish the same goal — different host ports per worktree — but they fail in different ways. Belt-and-suspenders.
+
+| Mechanism | Strength | Failure mode |
+|---|---|---|
+| **Override file** (`*.worktree.yml`) | Works on raw, unmodified repos. No assumptions about compose file content. | Requires `COMPOSE_FILE` chaining (env var must be sourced or passed). Misses if user runs `docker compose -f docker-compose.yml up` explicitly. |
+| **Env-var substitution** (`${VAR-default}` in compose) | Works regardless of `COMPOSE_FILE`. Robust to explicit `-f` flags. | Requires the repo to have been prepared via [`worktree-isolation-setup`](../worktree-isolation-setup/) — won't work on raw compose files. |
+
+Run `worktree-isolation-setup` and you get both. Use this skill alone and you only get the override file — which is enough for most workflows but breaks if a user invokes Compose with explicit `-f`.
+
+---
+
+## Compose file chaining
+
+`COMPOSE_FILE` is a colon-separated list. Compose v2 reads each file in order and merges them, with later files overriding earlier ones:
+
+```
+COMPOSE_FILE=docker-compose.yml:docker-compose.worktree.yml
+```
+
+So:
+1. `docker-compose.yml` defines the canonical service set.
+2. `docker-compose.worktree.yml` overrides `name`, `ports`, `container_name`.
+
+**Multi-compose projects** (e.g. `docker-compose.yml` + `docker-compose.processing.yml`) get one override per base file, all chained:
+
+```
+COMPOSE_FILE=docker-compose.yml:docker-compose.worktree.yml:docker-compose.processing.yml:docker-compose.processing.worktree.yml
+```
+
+---
+
+## Port allocation strategy
+
+Deterministic hash → 20000–29999 range:
+
+```python
+host_port = 20000 + (sha1(f"{worktree_id}:{service}:{container_port}").digest_int % 10000)
+```
+
+- **Range**: 20000–29999 chosen to avoid (a) the privileged range below 1024, (b) common dev ports below 10000, (c) the ephemeral range usually starting at 32768 on Linux/macOS.
+- **Determinism**: same worktree path → same ports forever. You can copy-paste a curl command between sessions of the same worktree without it going stale.
+- **Collisions**: with N worktrees and P ports per worktree, the probability of any two worktrees colliding on any port is ~`N²·P / 10000`. For 5 worktrees × 3 ports each, that's ~0.75% — acceptable. Surfaces as a `docker compose up` failure. Workaround: rename the worktree directory (changes the hash, regenerates ports).
+
+---
+
+## What this skill doesn't do
+
+- Doesn't install the SessionStart hook globally — that's [`worktree-isolation-setup`](../worktree-isolation-setup/).
+- Doesn't modify the repo's compose files / `CLAUDE.md` / `.gitignore` — also [`worktree-isolation-setup`](../worktree-isolation-setup/).
+- Doesn't handle non-Docker dev servers (Next.js, uvicorn directly on host).
+- Doesn't clean up orphan stacks from deleted worktrees — `docker compose ls` and `docker compose -p <project-name> down -v` manually.
+
+---
+
+## File reference
+
+```
+skills/worktree-isolation/
+├── SKILL.md          # entry point — how to invoke
+├── README.md         # this file
+└── scripts/
+    ├── apply.py      # the script itself
+    └── lib.py        # compose parsing + port allocation + override generation
+```

package/skills/worktree-isolation/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: worktree-isolation
+description: On-demand worktree isolation for the current directory. Regenerates per-worktree docker-compose overrides + .env.worktree so multiple Claude Code worktrees can run their stacks in parallel without port or container-name collisions, and inspects the current allocation. Use when (1) the SessionStart hook didn't fire (new project, hook not installed, fresh clone), (2) docker-compose.yml changed mid-session and overrides need regenerating, (3) the user wants to inspect which host ports this worktree is mapped to. Trigger phrases include "isolate worktree", "regenerate worktree ports", "show worktree ports", "what ports is this worktree using", "worktree didn't isolate", "fix port collision", "aislar worktree".
+---
+
+# Worktree Isolation — On-Demand
+
+Manually apply or inspect worktree isolation for the current directory. Use this skill any time you want to:
+
+- **Regenerate** `.env.worktree` + `*.worktree.yml` overrides (e.g. after editing a base compose file)
+- **Inspect** which host ports + `COMPOSE_PROJECT_NAME` are allocated to this worktree
+- **Bootstrap** isolation when the SessionStart hook hasn't run (new clone, hook not installed)
+
+If you want the SessionStart hook to do this automatically on every session start, **and** you want the repo's compose files + `CLAUDE.md` parameterized so commands "just work" without needing to source `.env.worktree`, run the [`worktree-isolation-setup`](../worktree-isolation-setup/) skill once per repo first.
+
+For an in-depth explanation of how isolation works (hook lifecycle, override generation, port allocation, compose chaining), see [README.md](README.md).
+
+---
+
+## Sub-commands
+
+### `apply` (default — regenerate)
+
+```bash
+python3 scripts/apply.py --cwd "$PWD" --verbose --force
+```
+
+If the global hook+scripts are already installed at `~/.claude/scripts/worktree-isolation/`, prefer that path instead — it's the same code:
+
+```bash
+~/.claude/scripts/worktree-isolation/apply.py --cwd "$PWD" --verbose --force
+```
+
+After running, bring the stack up:
+```bash
+set -a; source .env.worktree; set +a
+docker compose up -d
+```
+
+`COMPOSE_FILE` in `.env.worktree` chains base + override files automatically — no `-f` flags needed.
+
+### `status` (inspect)
+
+```bash
+python3 scripts/apply.py --cwd "$PWD" --status
+```
+
+Prints the current `.env.worktree`. Use when the user asks about ports or `COMPOSE_PROJECT_NAME`.
+
+---
+
+## When to invoke
+
+- **"regenerate worktree ports"** / **"isolate worktree"** / **"my hook didn't fire"** → `apply --force`
+- **"which ports is this worktree using?"** / **"show worktree ports"** / **"what's my COMPOSE_PROJECT_NAME?"** → `status`
+- **"compose file changed, regenerate overrides"** → `apply` (without `--force`; mtime detection handles it, but `--force` is fine too)
+
+---
+
+## Port substitution in ad-hoc commands
+
+The repo's `CLAUDE.md` may hardcode legacy host ports in test commands. Substitute the legacy port for the worktree-allocated one from `.env.worktree`:
+
+```bash
+# .env.worktree shows POSTGRES_INTEGRATION_5432_HOST_PORT=28156
+DATABASE_URL=postgresql://rr_test:rr_test_pw@localhost:28156/rr_integration uv run pytest ...
+```
+
+This skill does not auto-rewrite `CLAUDE.md` or scripts (zero-touch on project files by design). To make a project natively isolation-aware, run [`worktree-isolation-setup`](../worktree-isolation-setup/).
+
+---
+
+## Edge cases
+
+- **No docker-compose files in cwd** → no-op.
+- **Service has `ports:` using `${VAR-default}` already** → the script captures `VAR` and exports it in `.env.worktree` (substitution picks up the new port automatically). The override file still rewrites the port too (belt + suspenders).
+- **Base compose file edited after a previous run** → `apply` (without `--force`) detects the mtime change and regenerates.
+- **Two worktrees collide on a port** (1/10000 chance per port) → currently surfaces as a `docker compose up` failure. Workaround: rename the worktree directory (changes the hash, regenerates ports).
+
+---
+
+## Out of scope
+
+- Does not install the SessionStart hook globally. Use [`worktree-isolation-setup`](../worktree-isolation-setup/) for that.
+- Does not modify the repo's compose files / `CLAUDE.md` / `.gitignore`. Use [`worktree-isolation-setup`](../worktree-isolation-setup/) for that.
+- Does not clean up orphan stacks from deleted worktrees. For now, `docker compose ls` and `docker compose -p <project-name> down -v` manually.
+- Does not handle non-docker dev servers (Next.js, uvicorn directly on host).

package/skills/worktree-isolation/scripts/apply.py

@@ -0,0 +1,178 @@
+#!/usr/bin/env -S uv run --script --quiet
+# /// script
+# requires-python = ">=3.11"
+# dependencies = ["pyyaml"]
+# ///
+"""Worktree isolation entry point.
+
+Two callers:
+  1. Claude Code SessionStart hook → `apply.py --quiet` (emits hook JSON).
+  2. worktree-isolation skill → `apply.py --verbose --force` or `--status`.
+
+Reads the project's docker-compose*.yml files, generates per-worktree override
+files (sibling .worktree.yml) with deterministic randomized host ports + suffixed
+container_names, writes .env.worktree, and registers the generated files in the
+per-worktree git exclude list.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+
+import yaml  # noqa: E402
+
+from lib import (  # noqa: E402
+    PortMapping,
+    collect_container_names,
+    collect_port_mappings,
+    ensure_git_exclude,
+    find_compose_files,
+    overrides_up_to_date,
+    override_path_for,
+    render_env_worktree,
+    render_override_yaml,
+    worktree_id,
+)
+
+
+def _build_summary(
+    project_name: str,
+    worktree: str,
+    compose_chain: list[tuple[Path, Path | None]],
+    mappings: list[PortMapping],
+) -> str:
+    lines = [
+        f"Worktree isolation active: project='{project_name}' (id={worktree}).",
+        "",
+        "Port mappings (legacy → worktree host):",
+    ]
+    for m in sorted(mappings, key=lambda x: (x.service, x.container_port)):
+        lines.append(
+            f"  {m.service}  container :{m.container_port}  →  host {m.new_host_port}  "
+            f"(was {m.original_host_port})"
+        )
+    lines += [
+        "",
+        "To bring up the stack from this worktree:",
+        "  set -a; source .env.worktree; set +a",
+        "  docker compose up -d",
+        "(COMPOSE_FILE in .env.worktree auto-chains base + override files.)",
+        "",
+        "When running ad-hoc commands (e.g. test commands in CLAUDE.md) that hardcode",
+        "legacy host ports like " + ", ".join(sorted({str(m.original_host_port) for m in mappings}))
+        + ", substitute the matching new host port from the table above before executing.",
+    ]
+    return "\n".join(lines)
+
+
+def _run(args: argparse.Namespace) -> int:
+    cwd = args.cwd.resolve()
+
+    if args.status:
+        env_file = cwd / ".env.worktree"
+        if not env_file.exists():
+            print(f"No .env.worktree at {cwd}. Run with --force to generate.", file=sys.stderr)
+            return 1
+        print(env_file.read_text())
+        return 0
+
+    compose_files = find_compose_files(cwd)
+    if not compose_files:
+        if args.quiet:
+            print(json.dumps({"continue": True}))
+        elif args.verbose:
+            print(f"No docker-compose files in {cwd}. Nothing to isolate.")
+        return 0
+
+    wid = worktree_id(cwd)
+    project_name = f"{cwd.name}-{wid}"
+    env_file = cwd / ".env.worktree"
+
+    compose_chain: list[tuple[Path, Path | None]] = []
+    all_mappings: list[PortMapping] = []
+    regenerated_any = False
+
+    for base in compose_files:
+        mappings = collect_port_mappings(base, wid)
+        container_names = collect_container_names(base)
+
+        if not mappings and not container_names:
+            # Nothing to override for this file — still include in chain for completeness? No,
+            # if there's nothing to override, the base alone is fine. Skip.
+            continue
+
+        override_path = override_path_for(base)
+
+        if not args.force and overrides_up_to_date(base, override_path, env_file):
+            compose_chain.append((base, override_path))
+            all_mappings.extend(mappings)
+            continue
+
+        override_yaml_data = render_override_yaml(mappings, container_names, project_name, wid)
+        with open(override_path, "w") as f:
+            f.write("# Auto-generated by ~/.claude/scripts/worktree-isolation/apply.py\n")
+            f.write("# DO NOT COMMIT. Regenerate with the worktree-isolation skill.\n")
+            yaml.safe_dump(override_yaml_data, f, sort_keys=False, default_flow_style=False)
+        compose_chain.append((base, override_path))
+        all_mappings.extend(mappings)
+        regenerated_any = True
+
+    if not compose_chain:
+        if args.quiet:
+            print(json.dumps({"continue": True}))
+        elif args.verbose:
+            print(f"No services with ports or container_name in {cwd}. Nothing to isolate.")
+        return 0
+
+    # Always write env file when we have a chain — covers fresh dirs even if overrides exist.
+    env_content = render_env_worktree(project_name, wid, compose_chain, all_mappings)
+    if not env_file.exists() or env_file.read_text() != env_content:
+        env_file.write_text(env_content)
+        regenerated_any = True
+
+    ensure_git_exclude(cwd, [".env.worktree", "*.worktree.yml", "*.worktree.yaml"])
+
+    summary = _build_summary(project_name, wid, compose_chain, all_mappings)
+
+    if args.quiet:
+        out = {
+            "hookSpecificOutput": {
+                "hookEventName": "SessionStart",
+                "additionalContext": summary,
+            }
+        }
+        print(json.dumps(out))
+    else:
+        print(summary)
+        if not regenerated_any:
+            print("\n(no changes — overrides already up to date)")
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Per-worktree docker-compose isolation.")
+    parser.add_argument("--cwd", type=Path, default=Path.cwd(), help="Working directory")
+    parser.add_argument("--quiet", action="store_true", help="Hook mode: emit JSON only")
+    parser.add_argument("--verbose", action="store_true", help="Skill mode: human output")
+    parser.add_argument("--force", action="store_true", help="Regenerate even if up-to-date")
+    parser.add_argument("--status", action="store_true", help="Print current .env.worktree only")
+    args = parser.parse_args()
+
+    try:
+        return _run(args)
+    except Exception as exc:  # noqa: BLE001 — fail loud; hook captures stderr
+        if args.quiet:
+            # Don't break the session — emit a minimal valid hook response and log to stderr.
+            print(json.dumps({"continue": True}))
+            print(f"worktree-isolation error: {exc}", file=sys.stderr)
+            return 0
+        raise
+
+
+if __name__ == "__main__":
+    sys.exit(main())