aiblueprint-cli 1.4.87 → 1.4.89

package/agents-config/skills/apex/templates/README.md

@@ -0,0 +1,195 @@
+# APEX Template System
+
+## Overview
+
+This directory contains template files used to initialize APEX workflow outputs when save mode (`-s`) is enabled. This template system significantly reduces token usage by moving repetitive content out of step files.
+
+## Template Files
+
+| Template | Purpose | Created When |
+|----------|---------|--------------|
+| `00-context.md` | Workflow configuration and progress tracking | Always (if save_mode) |
+| `01-analyze.md` | Analysis findings | Always (if save_mode) |
+| `02-plan.md` | Implementation plan | Always (if save_mode) |
+| `03-execute.md` | Implementation log | Always (if save_mode) |
+| `04-validate.md` | Validation results | Always (if save_mode) |
+| `05-examine.md` | Adversarial review findings | Only if examine_mode enabled |
+| `06-resolve.md` | Finding resolution log | Only if examine_mode enabled |
+| `07-tests.md` | Test analysis and creation | Only if test_mode enabled |
+| `08-run-tests.md` | Test runner log | Only if test_mode enabled |
+| `09-finish.md` | PR creation log | Only if pr_mode enabled |
+| `step-complete.md` | Completion marker template | Referenced in steps |
+
+## Template Variables
+
+Templates use `{{variable}}` syntax for placeholders:
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `{{task_id}}` | Kebab-case task identifier | `01-add-auth-middleware` |
+| `{{task_description}}` | Plain text task description | `add authentication middleware` |
+| `{{timestamp}}` | ISO 8601 timestamp | `2026-01-12T10:30:00Z` |
+| `{{auto_mode}}` | Auto mode flag | `true` or `false` |
+| `{{examine_mode}}` | Examine mode flag | `true` or `false` |
+| `{{save_mode}}` | Save mode flag | `true` or `false` |
+| `{{test_mode}}` | Test mode flag | `true` or `false` |
+| `{{economy_mode}}` | Economy mode flag | `true` or `false` |
+| `{{branch_mode}}` | Branch mode flag | `true` or `false` |
+| `{{pr_mode}}` | PR mode flag | `true` or `false` |
+| `{{interactive_mode}}` | Interactive mode flag | `true` or `false` |
+| `{{branch_name}}` | Git branch name | `feature/add-auth` |
+| `{{original_input}}` | Raw user input | `/apex -a -s add auth` |
+| `{{examine_status}}` | Progress status for examine steps | `⏸ Pending` or `⏭ Skip` |
+| `{{test_status}}` | Progress status for test steps | `⏸ Pending` or `⏭ Skip` |
+| `{{pr_status}}` | Progress status for PR step | `⏸ Pending` or `⏭ Skip` |
+
+## Setup Script
+
+### `setup-templates.sh`
+
+Initializes all template files in the output directory with variables replaced.
+
+**Usage:**
+```bash
+bash scripts/setup-templates.sh \
+  "task_id" \
+  "task_description" \
+  "auto_mode" \
+  "examine_mode" \
+  "save_mode" \
+  "test_mode" \
+  "economy_mode" \
+  "branch_mode" \
+  "pr_mode" \
+  "interactive_mode" \
+  "branch_name" \
+  "original_input"
+```
+
+**Output:**
+```
+.claude/output/apex/01-add-auth-middleware/
+├── 00-context.md      # Always created
+├── 01-analyze.md      # Always created
+├── 02-plan.md         # Always created
+├── 03-execute.md      # Always created
+├── 04-validate.md     # Always created
+├── 05-examine.md      # Only if examine_mode
+├── 06-resolve.md      # Only if examine_mode
+├── 07-tests.md        # Only if test_mode
+├── 08-run-tests.md    # Only if test_mode
+└── 09-finish.md       # Only if pr_mode
+```
+
+## Progress Update Script
+
+### `update-progress.sh`
+
+Updates the progress table in `00-context.md` without manual markdown editing.
+
+**Usage:**
+```bash
+bash scripts/update-progress.sh <task_id> <step_number> <step_name> <status>
+```
+
+**Examples:**
+```bash
+# Mark step 01 as in progress
+bash scripts/update-progress.sh "01-add-auth" "01" "analyze" "in_progress"
+
+# Mark step 01 as complete
+bash scripts/update-progress.sh "01-add-auth" "01" "analyze" "complete"
+
+# Mark step 02 as in progress
+bash scripts/update-progress.sh "01-add-auth" "02" "plan" "in_progress"
+```
+
+**Status Values:**
+- `in_progress` → `⏳ In Progress`
+- `complete` → `✓ Complete`
+
+## Token Savings
+
+### Before Optimization
+
+Each step file contained full template content inline:
+
+```markdown
+### 1. Initialize Save Output (if save_mode)
+
+**If `{save_mode}` = true:**
+
+Create `{output_dir}/01-analyze.md`:
+```markdown
+# Step 01: Analyze
+
+**Task:** {task_description}
+**Started:** {ISO timestamp}
+
+---
+
+## Context Discovery
+```
+
+Update `00-context.md` progress:
+```markdown
+| 01-analyze | ⏳ In Progress | {timestamp} |
+```
+```
+
+**Token cost per step:** ~200 tokens × 9 steps = ~1,800 tokens
+
+### After Optimization
+
+Step files now reference templates and scripts:
+
+```markdown
+### 1. Initialize Save Output (if save_mode)
+
+**If `{save_mode}` = true:**
+
+The file `{output_dir}/01-analyze.md` has already been created by the setup script.
+
+Update progress:
+```bash
+bash {skill_dir}/scripts/update-progress.sh "{task_id}" "01" "analyze" "in_progress"
+```
+
+Append your findings to `01-analyze.md` as you work.
+```
+
+**Token cost per step:** ~50 tokens × 9 steps = ~450 tokens
+
+**Total savings:** ~1,350 tokens per workflow execution (75% reduction)
+
+## How It Works
+
+1. **Initialization (step-00-init.md):**
+   - Runs `setup-templates.sh` once at workflow start
+   - Creates all template files with variables replaced
+   - Output directory is ready with pre-initialized files
+
+2. **Each Step:**
+   - Runs `update-progress.sh` to mark step as "in_progress"
+   - Appends findings/logs to the pre-created step file
+   - Runs `update-progress.sh` again to mark step as "complete"
+
+3. **Benefits:**
+   - AI doesn't need to hold template content in context
+   - Consistent formatting across all workflows
+   - Easy to update templates without editing step files
+   - Scripts handle the tedious markdown updates
+
+## Updating Templates
+
+To modify template content:
+
+1. Edit the template file in `templates/`
+2. Changes apply to all future workflows automatically
+3. No need to update step files
+
+## Maintenance
+
+- Templates are stateless (no workflow-specific logic)
+- Scripts are idempotent (safe to run multiple times)
+- Variables use `{{var}}` syntax to avoid conflicts with markdown

package/agents-config/skills/apex/templates/step-complete.md

@@ -0,0 +1,7 @@
+---
+
+## Step Complete
+
+**Status:** ✓ Complete
+**Next:** {{next_step}}
+**Timestamp:** {{timestamp}}

package/agents-config/skills/appstore-connect/SKILL.md

@@ -1,19 +1,14 @@
 ---
 name: appstore-connect
-description: Interact with App Store Connect via the asc CLI - apps, builds, TestFlight, beta testers, reviews, sales/analytics, metadata, IAP, signing, submissions. Also builds an Expo/React Native iOS app and ships it to TestFlight via "appstore-connect testflight". Use for "check my app", "App Store Connect", "TestFlight status", "ship to TestFlight", "app review", "my app sales", or "asc".
-argument-hint: "[testflight [--expo] [setup]] | <natural-language ASC request>"
+description: Interact with App Store Connect via the asc CLI - apps, builds, TestFlight, beta testers, reviews, sales/analytics, metadata, IAP, signing, submissions. Use for "check my app", "App Store Connect", "TestFlight status", "app review", "my app sales", or "asc".
 ---
 
 # App Store Connect (asc)
 
 Read, manage, and ship any of the user's App Store apps through the **`asc`** CLI (App Store Connect CLI by Rork). `asc` covers nearly the entire ASC surface; reach for the raw API only for the rare gap.
 
-<testflight_mode>
-**If invoked as `appstore-connect testflight` (or "build and ship to TestFlight"):** this is a full build-and-upload workflow, not a single `asc` call. Read [references/testflight.md](references/testflight.md) and follow it end to end — it takes an Expo / React Native iOS app from local dev to an installable TestFlight build (ASC API-key signing to avoid Apple ID 2FA, `eas build --local` by default, `--expo` for a cloud build, then `asc publish testflight`). Pass `--expo` for a cloud build, or `testflight setup` to stop after credentials are ready. Everything below is the general `asc` surface for everyday read/manage tasks.
-</testflight_mode>
-
 <auth>
-`asc` is usually already authenticated on this machine (a default keychain profile). Verify before doing real work:
+`asc` is already authenticated on this machine (a default keychain profile). Verify before doing real work:
 
 ```bash
 asc auth status            # shows stored credential profiles + which is default
@@ -22,7 +17,7 @@ asc doctor                 # diagnose auth/config issues
 ```
 
 - Multiple accounts/teams: `asc --profile <name> <command>` selects a profile.
-- **Not authenticated / no working credential / a NEW account with no stored key:** read [references/setup.md](references/setup.md) and follow it — a battle-tested workflow to locate the `.p8`, key id, and issuer id, then `asc auth login`. Never print or commit `.p8` keys, key ids, or issuer ids.
+- A NEW account with no stored key: run the `find-asc-credentials` skill (locates the `.p8`, key id, and issuer id, then `asc auth login`). Never print or commit `.p8` keys, key ids, or issuer ids.
 </auth>
 
 <how_to_drive>
@@ -45,7 +40,6 @@ asc docs list              # embedded guides; `asc docs <topic>` to read one
 | List/inspect apps, app id | `asc apps`, `asc status --app <id>` |
 | Builds (processing, ids) | `asc builds` |
 | TestFlight: beta groups, testers, distribute a build | `asc testflight` |
-| **Build an iOS app + ship to TestFlight (end to end)** | `appstore-connect testflight` → [references/testflight.md](references/testflight.md) |
 | Versions / release state | `asc versions`, `asc release`, `asc status` |
 | Metadata, localizations, keywords | `asc metadata`, `asc localizations` |
 | Screenshots / previews | `asc screenshots`, `asc video-previews` |

package/agents-config/skills/environments-manager/SKILL.md

@@ -7,11 +7,13 @@ allow_implicit_invocation: true
 
 # Environments Manager
 
-Set up per-worktree environments so a fresh worktree is instantly ready to run: env files copied, dependencies installed, isolated database created, and common commands one click away. Supports Claude Code, Cursor, and Codex - the **shared scripts are the same on every IDE**; only the config file that points at them differs.
+Set up per-worktree environments so a fresh worktree is ready to run: env files copied, dependencies installed, optional data services isolated or seeded, generated code refreshed, and common commands exposed through the selected IDE. Supports Claude Code, Cursor, and Codex. The shared scripts are the same on every IDE; only the config file that points at them differs.
+
+Keep this skill database-agnostic. The main flow decides what needs to happen; database-specific implementation details live in references and should be loaded only when that backend is relevant.
 
 ## Interactive Flow
 
-This skill is interactive. Ask the user the two questions below before writing anything - the right setup depends on the project. Use whichever interactive question mechanism the host harness provides. Do not assume answers.
+This skill is interactive. Ask the user the questions below before writing anything. Use whichever interactive question mechanism the host harness provides. Do not assume answers.
 
 ### Step 1: What should happen in a fresh worktree?
 
@@ -19,24 +21,37 @@ Ask the user what the setup script should do, as a multi-select. The first optio
 
 | Option | What it adds to `scripts/worktree-up.sh` |
 | :--- | :--- |
-| Copy ignored env files from the source checkout | `cp` of `.env`, `.env.local`, `.env.development.local` (default - almost always wanted) |
-| Install dependencies | `pnpm install` / `bun install` / `npm install` based on lockfile |
-| Create an isolated database for this worktree | Build a unique DB name from the worktree dir, rewrite `DATABASE_URL` in `.env`, run `createdb` + import |
-| Run codegen (Prisma, Drizzle, generated types) | `pnpm prisma:generate` / `bun run db:generate` / etc. |
+| Copy ignored env files from the source checkout | Copy `.env`, `.env.local`, `.env.development.local` when the source has them and the worktree does not. For Claude Code, prefer `.worktreeinclude` when possible. |
+| Install dependencies | `pnpm install`, `bun install`, `yarn install`, or `npm install` based on lockfile. |
+| Isolate or seed a data backend | Load the backend reference when it exists. Otherwise use researcher agents to discover the project's backend, docs, and current best setup pattern before writing scripts. |
+| Run codegen | Project-specific codegen such as Prisma, Drizzle, Convex, generated types, or SDK generation. |
+
+If the user has project-specific steps such as seed data, S3/R2 sync, local services, webhook tunnels, fixture generation, or env cloning, ask one follow-up free-form question to capture them.
+
+### Step 2: Which data backend, if any?
+
+Ask which backend needs worktree isolation or seeding. Use the answer to decide which reference to load:
+
+| Backend | Action |
+| :--- | :--- |
+| None | Keep setup to env copy, install, codegen, and dev scripts. |
+| PostgreSQL | Load `references/postgresql.md`. |
+| Convex | Load `references/convex.md`. |
+| Other SQL or non-SQL backend | Use researcher agents to inspect the repo, official docs, and current CLI behavior. Then write a narrow project-specific approach instead of adapting PostgreSQL or Convex by analogy. |
 
-If the user has project-specific steps (seed data, S3 sync, etc.), ask a follow-up free-form question to capture them.
+For unknown backends, do not guess commands, reset behavior, file formats, import/export semantics, or production-safety flags. Ask researcher agents to find the official docs and at least one in-repo example or closely matching project pattern. Summarize the discovered approach before editing scripts.
 
-### Step 2: Which IDEs should be wired up?
+### Step 3: Which IDEs should be wired up?
 
-Ask a multi-select with options: Claude Code, Cursor, Codex. The user can pick any combination - the shared `scripts/` directory only gets generated once.
+Ask a multi-select with options: Claude Code, Cursor, Codex. The user can pick any combination. Generate the shared `scripts/` directory once.
 
-### Step 3: Apply each selected IDE
+### Step 4: Apply each selected IDE
 
-For each selected IDE, read the matching reference file and apply only its linking config. Do not duplicate the script logic - the IDE config just points at `scripts/worktree-up.sh`, `scripts/worktree-down.sh`, and `scripts/dev.sh`.
+For each selected IDE, read the matching reference file and apply only its linking config. Do not duplicate script logic in IDE config; the IDE config points at `scripts/worktree-up.sh`, `scripts/worktree-down.sh`, and `scripts/dev.sh`.
 
-- Claude Code → load `references/claude.md`
-- Cursor → load `references/cursor.md`
-- Codex → load `references/codex.md`
+- Claude Code -> load `references/claude.md`
+- Cursor -> load `references/cursor.md`
+- Codex -> load `references/codex.md`
 
 ## Shared Shape
 
@@ -50,9 +65,9 @@ scripts/
 └── (project-specific helpers, all *.sh)
 ```
 
-Plus one or more IDE config files (see references). The IDE config is thin; all logic lives in `scripts/`.
+Plus one or more IDE config files. The IDE config is thin; all logic lives in `scripts/`.
 
-**Naming convention**: every generated script MUST end in `.sh`. No bare `worktree-up`, no `dev`. IDE configs reference scripts by full filename (`scripts/worktree-up.sh`, not `scripts/worktree-up`). This is enforced in every reference file and example.
+Naming convention: every generated script MUST end in `.sh`. No bare `worktree-up`, no `dev`. IDE configs reference scripts by full filename (`scripts/worktree-up.sh`, not `scripts/worktree-up`). This is enforced in every reference file and example.
 
 ## Environment Variable Cascade
 
@@ -64,29 +79,29 @@ SOURCE_PATH="${CODEX_SOURCE_TREE_PATH:-${ROOT_WORKTREE_PATH:-}}"
 ```
 
 | Platform | Worktree path | Source checkout path | Setup trigger |
-| :------- | :----------------------- | :------------------------ | :--- |
-| Codex    | `$CODEX_WORKTREE_PATH`   | `$CODEX_SOURCE_TREE_PATH` | `[setup] script` in TOML, runs once per worktree |
-| Cursor   | `pwd` inside worktree    | `$ROOT_WORKTREE_PATH`     | `setup-worktree-unix` in JSON, runs once per worktree |
-| Claude   | `pwd` inside worktree (the hook wrapper cd's in) | `$CLAUDE_PROJECT_DIR` (source repo, exposed inside the hook); the wrapper re-exports it as `ROOT_WORKTREE_PATH` | `WorktreeCreate` hook, runs once per worktree |
+| :--- | :--- | :--- | :--- |
+| Codex | `$CODEX_WORKTREE_PATH` | `$CODEX_SOURCE_TREE_PATH` | `[setup] script` in TOML, runs once per worktree. |
+| Cursor | `pwd` inside worktree | `$ROOT_WORKTREE_PATH` | `setup-worktree-unix` in JSON, runs once per worktree. |
+| Claude | `pwd` inside worktree after wrapper `cd` | `$CLAUDE_PROJECT_DIR` from the hook, re-exported as `ROOT_WORKTREE_PATH` by the wrapper | `WorktreeCreate` hook, runs once per worktree. |
 
-**Important about Claude Code**: do NOT use `SessionStart` for setup - it fires every session. Use the `WorktreeCreate` hook, which fires once when `claude --worktree` creates the worktree. The Claude wrapper script (`scripts/claude-worktree-create.sh`) is responsible for calling `git worktree add` itself, then handing off to `scripts/worktree-up.sh` inside the new worktree with `ROOT_WORKTREE_PATH` set. See [references/claude.md](references/claude.md).
+Important about Claude Code: do not use `SessionStart` for setup; it fires every session. Use the `WorktreeCreate` hook, which fires once when `claude --worktree` creates the worktree. The Claude wrapper script (`scripts/claude-worktree-create.sh`) is responsible for calling `git worktree add` itself, then handing off to `scripts/worktree-up.sh` inside the new worktree with `ROOT_WORKTREE_PATH` set. See `references/claude.md`.
 
-If no env var yields a source checkout, fall back to a project-specific absolute path (e.g. `$HOME/Developer/saas/<repo>`). Ask the user during Step 1 if you cannot infer it.
+If no env var yields a source checkout, fall back to a project-specific absolute path only when you can infer it confidently. Otherwise ask the user during Step 1.
 
 ## `scripts/worktree-up.sh`
 
-Setup must be **idempotent** - reruns are safe. Built from the user's Step 1 selections. Required behavior in order:
+Setup must be idempotent: reruns are safe. Build the script from the user's Step 1 selections and any backend reference loaded in Step 2. Required behavior in order:
 
 1. `set -euo pipefail`.
 2. Resolve `WORKTREE_PATH` and `SOURCE_PATH`.
 3. `cd "$WORKTREE_PATH"`.
-4. If "Copy env files" selected: copy `.env`, `.env.local`, `.env.development.local` only when the source has them and the worktree does not.
-5. If "Install dependencies" selected: detect from lockfile and run the matching install.
-6. If "Isolated database" selected: build a DB name from `basename "$WORKTREE_PATH" | tr '/' '-'`, rewrite only `DATABASE_URL` (and any related vars) in the copied `.env`, create the DB if missing. Provide a reset escape hatch: `<PROJECT>_RESET_DB=1` drops and recreates.
-7. If "Codegen" selected: run the project's codegen command.
+4. If env copying was selected, copy `.env`, `.env.local`, `.env.development.local` only when the source has them and the worktree does not.
+5. If dependency install was selected, detect the lockfile and run the matching install.
+6. If backend isolation/seeding was selected, apply the backend reference or the researched project-specific approach.
+7. If codegen was selected, run the project's codegen command.
 8. Append any free-form project-specific steps from Step 1.
 
-Reference template (adjust based on selections):
+Base template, before backend-specific additions:
 
 ```bash
 #!/usr/bin/env bash
@@ -107,46 +122,28 @@ for f in .env .env.local .env.development.local; do
   fi
 done
 
-# Install deps
+# Install deps.
 if   [[ -f pnpm-lock.yaml ]]; then pnpm install
 elif [[ -f bun.lock || -f bun.lockb ]]; then bun install
 elif [[ -f yarn.lock ]]; then yarn install
 elif [[ -f package-lock.json ]]; then npm install
 fi
 
-# Project-specific DB isolation and codegen go here.
+# Backend isolation/seeding and codegen go here.
 ```
 
 ## `scripts/worktree-down.sh`
 
-Cleanup runs before the IDE destroys the worktree.
+Cleanup runs before the IDE destroys the worktree. Keep cleanup scoped to resources that the setup script created or selected explicitly.
 
 1. `set -euo pipefail`.
-2. `cd "$WORKTREE_PATH"`.
-3. Read DB names from the worktree `.env`. **Never guess from branch names.**
-4. `dropdb --if-exists` per DB found, against a maintenance database.
-5. Remove copied env files.
-6. If env files or PostgreSQL tools are missing, print one short message and exit 0.
-
-```bash
-#!/usr/bin/env bash
-set -euo pipefail
-
-WORKTREE_PATH="${CODEX_WORKTREE_PATH:-${CURSOR_WORKTREE_PATH:-$(pwd)}}"
-cd "$WORKTREE_PATH"
-
-if [[ ! -f .env ]]; then
-  echo "no .env in worktree, nothing to clean"
-  exit 0
-fi
-
-db_name=$(grep -E '^DATABASE_URL=' .env | sed -E 's|.*/([^/?]+).*|\1|' | head -n1 || true)
-if [[ -n "${db_name:-}" ]] && command -v dropdb >/dev/null 2>&1; then
-  dropdb --if-exists -d postgres "$db_name" || true
-fi
+2. Resolve `WORKTREE_PATH`.
+3. `cd "$WORKTREE_PATH"`.
+4. Run backend-specific cleanup only when the loaded backend reference requires it.
+5. Remove copied local env files only if that is appropriate for the project.
+6. If required tools or env files are missing, print one short message and exit 0.
 
-rm -f .env .env.local .env.development.local
-```
+Never guess resource names from branch names. Read names from the worktree's env/config files or from deterministic setup metadata created by `worktree-up.sh`.
 
 ## `scripts/dev.sh`
 
@@ -170,30 +167,32 @@ exec pnpm dev -p "$port"  # adjust for the project package manager
 
 ## Standard Actions
 
-Every project should expose these four actions through the IDE's own mechanism (see references). Wire them per IDE.
+Every project should expose these four actions through the IDE's own mechanism:
 
-| Action     | Command (typical)                |
-| :--------- | :------------------------------- |
-| Dev        | `scripts/dev.sh`                    |
-| Typecheck  | `pnpm ts` / `bun run typecheck`  |
-| Unit tests | `pnpm test:ci` / `bun test`      |
-| Lint       | `pnpm lint:ci` / `bun run lint`  |
+| Action | Command (typical) |
+| :--- | :--- |
+| Dev | `scripts/dev.sh` |
+| Typecheck | `pnpm ts` / `bun run typecheck` |
+| Unit tests | `pnpm test:ci` / `bun test` |
+| Lint | `pnpm lint:ci` / `bun run lint` |
 
 Add `E2E` as an action only if the suite is cheap enough to run interactively.
 
 ## Universal Guardrails
 
 - Never commit secrets. Copying ignored env files into a local worktree is fine; logging them is not.
-- Never drop a database whose name was guessed from a branch. Read it from the worktree `.env`.
 - Never put fragile multi-line shell programs inside an IDE config file. Keep all logic in `scripts/`; the IDE config just calls those scripts.
 - Never hardcode a dev port. Pick a free one starting from `${DEV_PORT_START:-3910}`.
-- Setup must be idempotent. Provide a reset escape hatch via env var (`<PROJECT>_RESET_DB=1`).
-- Print DB names and redacted hosts only.
+- Setup must be idempotent. Provide a reset escape hatch for stateful resources via env var (`<PROJECT>_RESET_<RESOURCE>=1`).
+- Print resource names and redacted hosts only.
 - The scripts and IDE config must live on the source checkout / main branch, not only the current worktree, or future worktrees will have nothing to copy.
-- **Never import data from a production source.** Any setup step that exports a database/deployment and replays it into the new worktree MUST reject any source ref containing `prod`/`production` and require an explicit override env var (`<PROJECT>_ALLOW_PROD_SOURCE=1`). Even a single mistaken `--replace-all` against the wrong source can nuke a teammate's dev environment or, worse, leak prod data into a feature branch. Default the source to `dev` and validate before each export.
+- Never destroy or import from production data by default. Any setup step that exports from a shared source and replays into a worktree must reject production-looking refs unless the user explicitly approved an override env var.
+- Hook wrappers must survive a missing `/dev/tty`, a wrong default Node version, and CLI prompts. See `references/claude.md` -> "Hook Robustness" for the concrete fixes.
+
+Use this production-source guard in backend references or project-specific helpers:
 
 ```bash
-assert_dev_source() {
+assert_non_prod_ref() {
   case "$1" in
     prod|prod:*|prod/*|production|production:*|production/*)
       echo "refusing prod source: $1" >&2; exit 1 ;;
@@ -203,8 +202,6 @@ assert_dev_source() {
 }
 ```
 
-- **Hook wrappers must survive a missing `/dev/tty`, a wrong default Node version, and CLI prompts.** See `references/claude.md` → "Hook Robustness" for the five concrete fixes.
-
 ## Verification
 
 After generating files:
@@ -214,7 +211,7 @@ bash -n scripts/worktree-up.sh scripts/worktree-down.sh scripts/dev.sh
 git status --short
 ```
 
-If Python 3.11+ is available, validate any generated TOML:
+If Python 3.11+ is available, validate generated TOML:
 
 ```bash
 python3 - <<'PY'
@@ -231,41 +228,36 @@ python3 -c "import json; json.load(open('.cursor/worktrees.json'))"
 python3 -c "import json; json.load(open('.claude/settings.json'))"
 ```
 
-## IDE-Specific Linking
-
-After the shared scripts are written, for each IDE selected in Step 2, load the matching reference file and apply only its linking config:
+## References
 
-- **Claude Code** → [references/claude.md](references/claude.md) - `.claude/settings.json` worktree hooks + optional project action skills.
-- **Cursor** → [references/cursor.md](references/cursor.md) - `.cursor/worktrees.json` setup keys.
-- **Codex** → [references/codex.md](references/codex.md) - `.codex/environments/environment.toml` setup, cleanup, and actions.
+Load only the references relevant to the selected backend and IDE:
 
-If multiple IDEs were selected, generate `scripts/` once and then apply each reference in turn.
+- `references/postgresql.md` - PostgreSQL isolation, reset, and cleanup.
+- `references/convex.md` - Convex local/cloud deployments, allowlisted seeding, env cloning, and cleanup.
+- `references/claude.md` - Claude Code WorktreeCreate/WorktreeRemove wiring.
+- `references/cursor.md` - Cursor worktree setup wiring.
+- `references/codex.md` - Codex local environment TOML.
 
 ## Examples
 
-Working copies of every file this skill generates live under [examples/](examples/). Use them as the source-of-truth shape when writing into a real project. Adapt the project section (package manager, DB name prefix, codegen step) for the target repo.
+Working examples live under `examples/`. Read the relevant example before writing files into a real project, but do not copy verbatim. The user's selections, backend reference, and project conventions determine which sections survive.
 
 ```text
 examples/
 ├── scripts/
-│   ├── worktree-up.sh             # pnpm + Postgres + Prisma reference
-│   ├── worktree-down.sh           # pnpm + Postgres reference
-│   ├── dev.sh                     # free-port dev server reference
-│   ├── claude-worktree-create.sh  # Claude WorktreeCreate hook wrapper
-│   └── claude-worktree-remove.sh  # Claude WorktreeRemove hook wrapper
+│   ├── worktree-up.sh
+│   ├── worktree-down.sh
+│   ├── dev.sh
+│   ├── convex-selective-seed.sh
+│   ├── claude-worktree-create.sh
+│   └── claude-worktree-remove.sh
 ├── claude/
-│   ├── .worktreeinclude           # native env-file copy list
-│   ├── settings.json              # WorktreeCreate + WorktreeRemove hooks
-├── skills/                        # optional project action skills
-│   ├── dev/SKILL.md
-│   ├── typecheck/SKILL.md
-│   ├── test/SKILL.md
-│   └── lint/SKILL.md
+│   ├── .worktreeinclude
+│   ├── settings.json
+│   └── commands/
 ├── cursor/
-│   └── worktrees.json             # setup-worktree-unix -> scripts/worktree-up.sh
+│   └── worktrees.json
 └── codex/
     └── environments/
-        └── environment.toml       # setup, cleanup, four actions
+        └── environment.toml
 ```
-
-Read the relevant example before writing the file into the target project. Do not copy verbatim - the user's Step 1 selections determine which sections of `worktree-up.sh` survive.

package/agents-config/skills/environments-manager/examples/{skills/dev/SKILL.md → claude/commands/dev.md}

@@ -1,6 +1,5 @@
 ---
-name: dev
-description: Start the dev server on a free port for this project.
+description: Start the dev server on a free port
 ---
 
 Run `scripts/dev.sh` from the project root. Stream output until the dev server is listening, then return the URL.

package/agents-config/skills/environments-manager/examples/{skills/lint/SKILL.md → claude/commands/lint.md}

@@ -1,6 +1,5 @@
 ---
-name: lint
-description: Run the linter for this project and report violations.
+description: Run the linter
 ---
 
 Run the project's lint command (`pnpm lint:ci`, `bun run lint`, or equivalent). Report any violations.

package/agents-config/skills/environments-manager/examples/{skills/test/SKILL.md → claude/commands/test.md}

@@ -1,6 +1,5 @@
 ---
-name: test
-description: Run unit tests for this project and summarize failures.
+description: Run unit tests
 ---
 
 Run the project's unit test command (`pnpm test:ci`, `bun test`, or equivalent). Report failures with file:line references.

package/agents-config/skills/environments-manager/examples/{skills/typecheck/SKILL.md → claude/commands/typecheck.md}

@@ -1,6 +1,5 @@
 ---
-name: typecheck
-description: Typecheck this project and report errors with file references.
+description: Typecheck the project
 ---
 
 Run the project's typecheck command (`pnpm ts`, `bun run typecheck`, or equivalent based on the lockfile). Report any errors with file:line references.

package/agents-config/skills/environments-manager/examples/scripts/worktree-down.sh

@@ -1,22 +1,15 @@
 #!/usr/bin/env bash
-# Example: pnpm + Postgres project cleanup. Generated by environments-manager.
+# Example: backend-neutral worktree cleanup.
+# Generated by environments-manager. Add backend-specific cleanup from references.
 
 set -euo pipefail
 
 WORKTREE_PATH="${CODEX_WORKTREE_PATH:-${CURSOR_WORKTREE_PATH:-$(pwd)}}"
 cd "$WORKTREE_PATH"
 
-if [[ ! -f .env ]]; then
-  echo "no .env in worktree, nothing to clean"
-  exit 0
-fi
-
-db_name=$(grep -E '^DATABASE_URL=' .env | sed -E 's|.*/([^/?]+).*|\1|' | head -n1 || true)
-
-if [[ -n "${db_name:-}" ]] && command -v dropdb >/dev/null 2>&1; then
-  dropdb --if-exists -d postgres "$db_name" || true
-  echo "dropped $db_name"
-fi
+# Backend-specific cleanup goes here.
+# Never guess resource names from branch names. Read them from env/config files
+# or deterministic setup metadata created by worktree-up.sh.
 
 rm -f .env .env.local .env.development.local
 echo "removed local env files"