aiblueprint-cli 1.4.88 → 1.4.90

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

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
-# Example: pnpm + Postgres project with all four setup steps enabled.
-# Generated by environments-manager. Adapt the project section for your repo.
+# Example: backend-neutral worktree setup.
+# Generated by environments-manager. Add backend-specific blocks from references.
 
 set -euo pipefail
 
@@ -24,26 +24,16 @@ elif [[ -f yarn.lock ]]; then yarn install
 elif [[ -f package-lock.json ]]; then npm install
 fi
 
-# 3. Worktree-isolated database
-worktree_slug=$(basename "$WORKTREE_PATH" | tr '/' '-' | tr '[:upper:]' '[:lower:]')
-db_name="myapp_${worktree_slug}"
-
-if [[ -f .env ]]; then
-  if grep -qE '^DATABASE_URL=' .env; then
-    if [[ "${MYAPP_RESET_DB:-0}" == "1" ]] && command -v dropdb >/dev/null 2>&1; then
-      dropdb --if-exists -d postgres "$db_name" || true
-    fi
-    if command -v createdb >/dev/null 2>&1; then
-      createdb -d postgres "$db_name" 2>/dev/null || true
-    fi
-    # Rewrite only the DB name in DATABASE_URL
-    sed -i.bak -E "s|(DATABASE_URL=postgres://[^/]+)/[^?\"']+|\1/${db_name}|" .env && rm -f .env.bak
-    echo "DB set to $db_name"
-  fi
-fi
+# 3. Backend isolation/seeding
+# Load a backend reference before adding database-specific behavior:
+# - references/postgresql.md
+# - references/convex.md
+# - researcher-agent findings for any other backend
 
-# 4. Codegen
-if [[ -f prisma/schema.prisma ]]; then
+# 4. Codegen (adapt to the project)
+if [[ -f convex/convex.config.ts || -f convex/schema.ts ]]; then
+  pnpm exec convex codegen
+elif [[ -f prisma/schema.prisma ]]; then
   pnpm prisma generate
 fi
 

package/agents-config/skills/environments-manager/references/claude.md

@@ -25,13 +25,12 @@ There is no separate `PostWorktreeCreate` hook (feature request #27744 is open).
 ```text
 .worktreeinclude                  # gitignore-syntax list of files to auto-copy
 .claude/
-└── settings.json                 # WorktreeCreate + WorktreeRemove hooks
-.agents/
-└── skills/                       # optional: per-action project skills
-    ├── dev/SKILL.md
-    ├── typecheck/SKILL.md
-    ├── test/SKILL.md
-    └── lint/SKILL.md
+├── settings.json                 # WorktreeCreate + WorktreeRemove hooks
+└── commands/                     # optional: per-action slash commands
+    ├── dev.md
+    ├── typecheck.md
+    ├── test.md
+    └── lint.md
 scripts/
 ├── claude-worktree-create.sh     # WorktreeCreate hook wrapper
 ├── claude-worktree-remove.sh     # WorktreeRemove hook wrapper
@@ -124,14 +123,11 @@ The `WorktreeCreate` hook **only fires for `claude --worktree` from the CLI**. T
 
 Also: **`.claude/settings.json` changes only take effect after restarting Claude.** A running session keeps the old hook config. Tell the user to restart before testing.
 
-## Project Action Skills (optional)
+## Custom Slash Commands as Actions (optional)
 
-To expose standard project actions consistently, write one skill per action
-under `.agents/skills/<name>/SKILL.md`. Each skill tells the agent to run the
-matching shared script or package-manager command.
+Claude Code does not have a top-bar action menu. To expose the standard actions, write one file per action under `.claude/commands/`. Each is a tiny prompt that tells Claude to run the matching shared script or package-manager command.
 
-See `examples/skills/` for the four standard ones (`dev`, `typecheck`, `test`,
-`lint`).
+See `examples/claude/commands/` for the four standard ones (`dev.md`, `typecheck.md`, `test.md`, `lint.md`).
 
 ## Guardrails
 

package/agents-config/skills/environments-manager/references/convex.md

@@ -0,0 +1,120 @@
+# Convex Worktree Backend
+
+Load this reference only when the target project uses Convex and the user selected backend isolation, seeding, env cloning, or Convex codegen.
+
+Convex worktree setup is project-specific. Prefer the target repo's existing scripts over generic snippets. If the repo is `thumbfa.st` or follows the same style, inspect `scripts/worktree-context.sh`, `scripts/worktree-setup.sh`, `scripts/worktree-cleanup.sh`, and `.codex/environments/environment.toml` before editing; they show a useful pattern for isolated Convex deployments, env sync, auth cookie isolation, codegen, and cleanup.
+
+## First Decision
+
+Ask or infer which Convex mode the project should use:
+
+| Mode | Use when | Setup shape |
+| :--- | :--- | :--- |
+| Local deployment | The worktree can run fully local Convex state. | Create/select local deployment, keep data local, run `convex dev --local --once` or the repo's equivalent. |
+| Cloud dev deployment | Each worktree needs an isolated Convex dev deployment. | Create/select `dev/<worktree-slug>`, clone safe env vars, push schema/functions, seed selected data. |
+| Existing deployment | The team wants to reuse the source checkout's selected deployment. | Copy env files and avoid destructive reset/import steps. |
+
+Do not assume one mode globally. Convex projects vary a lot.
+
+## Table Seeding Policy
+
+Fresh worktrees usually need enough data to log in, select an organization, exercise billing/credits, and test the product workflow. They do not need a full copy of analytics, logs, generated outputs, webhook history, background jobs, embeddings, message transcripts, file storage, or other heavy/derived tables.
+
+Before writing Convex seed code:
+
+1. Inspect `convex/schema.ts` and nearby feature code.
+2. Ask which tables are important enough to seed.
+3. If the user does not know, propose a small allowlist. Default to core identity, org, billing, settings, and product fixture tables.
+4. Read `examples/scripts/convex-selective-seed.sh` and adapt it to the repo.
+
+Use this policy when adding Convex data copy:
+
+- Require a small `CONVEX_IMPORT_TABLES` allowlist in the generated script or a project-specific helper.
+- Prefer committed seed fixtures or a project helper that exports only those tables to JSONL/JSON.
+- Import one table at a time with `npx convex import --table "$table" "$path"`.
+- Do not use a broad `npx convex export` / `npx convex import --replace-all` as the default setup path. It is a project-specific choice, not the generic safe default.
+- Do not include `_storage` unless the user explicitly says file storage is required for the workflow.
+- If relationships require stable document IDs across tables, document that targeted imports may regenerate IDs and prefer a purpose-built seed mutation/helper over partial backup editing.
+
+## Selective Seed Shape
+
+Adapt table names, deployment flags, and seed paths to the repo:
+
+```bash
+# Convex selected-table seed. Keep this list short and project-specific.
+CONVEX_IMPORT_DEPLOYMENT="${CONVEX_IMPORT_DEPLOYMENT:-dev}"
+CONVEX_IMPORT_DIR="${CONVEX_IMPORT_DIR:-$SOURCE_PATH/.worktree-seed/convex}"
+CONVEX_IMPORT_TABLES=(
+  users
+  organizations
+  organizationMembers
+  subscriptions
+  credits
+  settings
+)
+
+assert_non_prod_ref "$CONVEX_IMPORT_DEPLOYMENT"
+
+convex_import_flags=()
+case "$CONVEX_IMPORT_DEPLOYMENT" in
+  dev)
+    ;;
+  preview:*)
+    convex_import_flags=(--preview-name "${CONVEX_IMPORT_DEPLOYMENT#preview:}")
+    ;;
+  *)
+    echo "unknown Convex import target '$CONVEX_IMPORT_DEPLOYMENT'; use dev or preview:<name>" >&2
+    exit 1
+    ;;
+esac
+
+if [[ -d "$CONVEX_IMPORT_DIR" ]]; then
+  for table in "${CONVEX_IMPORT_TABLES[@]}"; do
+    seed_file="$CONVEX_IMPORT_DIR/$table.jsonl"
+    if [[ -f "$seed_file" ]]; then
+      npx convex import "${convex_import_flags[@]}" --replace --table "$table" "$seed_file"
+      echo "seeded Convex table: $table"
+    else
+      echo "skipped Convex table without seed file: $table"
+    fi
+  done
+else
+  echo "no Convex seed directory at $CONVEX_IMPORT_DIR, skipping selected-table seed"
+fi
+```
+
+## Cloud Dev Deployment Pattern
+
+When using isolated cloud dev deployments, generate or adapt helper functions instead of cramming everything into one giant script:
+
+- Resolve worktree path, source tree, workspace slug, and deployment ref in a small helper such as `scripts/worktree-context.sh`.
+- Use a deterministic dev deployment ref such as `dev/<worktree-slug>`, unless the user provides one.
+- Reject production-looking refs before exports, imports, env cloning, or cleanup.
+- Clone only safe env vars from the source dev deployment. If the project has a helper like `scripts/convex-sync-env.sh`, use it.
+- Set worktree-specific auth/cookie/session prefixes when the app uses Better Auth or similar auth middleware.
+- Push schema/functions with the repo's normal command, often `pnpm exec convex dev --once`.
+- Run `pnpm exec convex codegen` or the repo's codegen command after deployment selection.
+
+Thumbfa.st is a good local example of this shape: it resolves context in `scripts/worktree-context.sh`, creates/selects a Convex dev deployment in setup, syncs env, sets an auth cookie prefix, pushes Convex, generates code, and cleans local Convex state/env vars in cleanup. Borrow the structure, not every destructive command.
+
+## Cleanup
+
+Cleanup should only remove resources that the setup script created or selected explicitly.
+
+Typical cleanup:
+
+- Remove worktree-specific Convex env vars only for deterministic worktree deployment refs such as `dev/<slug>`.
+- Remove local `.convex` state only if the user did not request keeping it.
+- Remove copied env files after cleanup work is done.
+- Never remove or mutate production deployments.
+
+If the project creates cloud dev deployments and the Convex CLI supports deleting them in the current version, use researcher agents to verify the exact command and prompts before adding deletion. Otherwise leave deployment deletion manual and make cleanup idempotent.
+
+## Guardrails
+
+- Never import into or export from production by default.
+- Never copy every table just because the CLI supports full deployment backups.
+- Never log Convex deployment admin keys, auth secrets, webhooks, or API keys.
+- Keep setup non-interactive: set `CI=1` from wrappers where possible and use explicit CLI flags.
+- Keep reset explicit, for example `CONVEX_WORKTREE_RESET_DATA=1`.
+- Prefer project helpers over generic snippets when they already exist.

package/agents-config/skills/environments-manager/references/cursor.md

@@ -14,7 +14,7 @@ Three setup keys are supported (Cursor picks the first one that matches the host
 
 Cursor does **not** support a cleanup script. Cleanup is timer-based via global settings (`cursor.worktreeCleanupIntervalHours`, `cursor.worktreeMaxCount`). To get a real cleanup hook, expose `scripts/worktree-down.sh` as a project command the user runs manually before `/delete-worktree`.
 
-Cursor includes built-in worktree actions for creating, comparing, applying, and deleting worktrees.
+Built-in worktree slash commands the user already has: `/worktree`, `/best-of-n`, `/apply-worktree`, `/delete-worktree`.
 
 ## Environment Variables
 
@@ -72,7 +72,7 @@ Inline is fine for two-line setups. For anything more, use a script - the worktr
 
 - Do not put fragile multi-line setup inline. If it does not fit in two clean array entries, call the script.
 - Do not put `.cursor/worktrees.json` only in a worktree - it must be on the source checkout / main branch so future worktrees pick it up.
-- Do not rely on a cleanup hook - Cursor does not have one. Tell the user to run `scripts/worktree-down.sh` before deleting a worktree, or document it in the project README.
+- Do not rely on a cleanup hook - Cursor does not have one. Tell the user to run `scripts/worktree-down.sh` before `/delete-worktree`, or document it in the project README.
 - Do not use `$CURSOR_WORKTREE_PATH` - that variable is not documented and not guaranteed. Use `pwd` inside the worktree.
 
 ## Verification

package/agents-config/skills/environments-manager/references/postgresql.md

@@ -0,0 +1,89 @@
+# PostgreSQL Worktree Backend
+
+Load this reference only when the target project uses PostgreSQL and the user selected backend isolation or cleanup.
+
+## Goal
+
+Create a worktree-specific PostgreSQL database, rewrite only local env values to point at it, run the project's schema/codegen steps, and drop only that database during cleanup.
+
+Do not use this reference for other SQL engines by analogy. For MySQL, SQLite, Turso/libSQL, Neon branching, Supabase branching, PlanetScale, MongoDB, Redis, or any other backend, use researcher agents to inspect official docs and the repo's existing scripts before writing backend setup.
+
+## `scripts/worktree-up.sh` Additions
+
+Add this block after env copying and dependency install. Adapt the prefix, env vars, schema commands, and reset env var to the project.
+
+```bash
+# PostgreSQL worktree-isolated database.
+worktree_slug="$(basename "$WORKTREE_PATH" | tr '/' '-' | tr '[:upper:]' '[:lower:]')"
+db_name="<project>_${worktree_slug}"
+
+if [[ -f .env ]]; then
+  if grep -qE '^DATABASE_URL=' .env; then
+    # Replace PROJECT_RESET_DB with a project-specific env var, e.g. MYAPP_RESET_DB.
+    if [[ "${PROJECT_RESET_DB:-0}" == "1" ]] && command -v dropdb >/dev/null 2>&1; then
+      dropdb --if-exists -d postgres "$db_name" || true
+    fi
+
+    if command -v createdb >/dev/null 2>&1; then
+      createdb -d postgres "$db_name" 2>/dev/null || true
+    else
+      echo "createdb not found; skipped PostgreSQL database creation"
+    fi
+
+    # Rewrite only the DB name in DATABASE_URL.
+    sed -i.bak -E "s|(DATABASE_URL=postgres://[^/]+)/[^?\"']+|\1/${db_name}|" .env && rm -f .env.bak
+    echo "PostgreSQL DB set to $db_name"
+  fi
+fi
+```
+
+If the project uses `postgresql://`, multiple database env vars, SSL params, pooled URLs, direct URLs, or a hosted provider URL format, inspect existing env conventions and adjust carefully. Do not log secrets.
+
+## Schema and Seed
+
+Run only project-local schema steps after the URL rewrite. Examples:
+
+```bash
+if [[ -f prisma/schema.prisma ]]; then
+  pnpm prisma generate
+  pnpm prisma db push
+fi
+```
+
+```bash
+if [[ -f drizzle.config.ts ]]; then
+  pnpm drizzle-kit push
+fi
+```
+
+Use project seed commands only when the user selected seeding or the repo already treats them as required for local startup.
+
+## `scripts/worktree-down.sh` Additions
+
+Read the database name from the worktree env file. Never derive it from the branch or worktree path during cleanup.
+
+```bash
+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 PostgreSQL DB $db_name"
+else
+  echo "no PostgreSQL DB cleanup performed"
+fi
+```
+
+Remove copied env files only after cleanup has read the values it needs.
+
+## Guardrails
+
+- Never drop a database whose name was guessed from a branch.
+- Never print full `DATABASE_URL` values.
+- Keep reset explicit: `<PROJECT>_RESET_DB=1`.
+- Prefer idempotent schema commands for setup.
+- If database creation requires a hosted provider CLI or branching API, stop using this local PostgreSQL reference and research that provider directly.

package/agents-config/skills/oneshot/SKILL.md

@@ -1,56 +1,40 @@
 ---
 name: oneshot
-description: Ultra-fast feature implementation using Explore → Code → Test workflow. Use when implementing focused features, single tasks, or when speed over completeness is priority.
+description: Implement one focused code change quickly with minimal exploration and targeted validation. Use for small bug fixes, single feature edits, config updates, or explicit "$oneshot" requests.
 argument-hint: <feature-description>
 ---
 
 # OneShot
 
-Implement `$ARGUMENTS` at maximum speed. Ship fast, iterate later.
+Use this for one narrow implementation task. Optimize for the shortest reliable path to a working, verified change.
 
 ## Workflow
 
-### 1. EXPLORE (minimal)
+### 1. Scope
 
-Gather minimum viable context:
-- Use `Glob` to find 2-3 key files by pattern
-- Use `Grep` to search for specific patterns
-- Quick `WebSearch` only if library-specific API knowledge needed
-- NO exploration tours - find examples/edit targets and move on
+- Identify the exact target and likely files with `rg` / `rg --files`.
+- Read only the files needed to edit safely, usually 2-5 plus nearby examples.
+- Look up docs only when API, version, or current behavior may be stale.
 
-### 2. CODE (main phase)
+### 2. Implement
 
-Execute changes immediately:
-- Follow existing codebase patterns exactly
-- Clear variable/method names over comments
-- Stay STRICTLY in scope - change only what's needed
-- NO comments unless genuinely complex
-- NO refactoring beyond requirements
-- Run formatters if available (`npm run format`)
+- Edit as soon as the existing pattern is clear.
+- Keep the diff minimal and local to the request.
+- Do not refactor, rename, redesign, rewrite docs, or clean adjacent code unless required.
+- Prefer existing helpers, conventions, and package scripts.
 
-### 3. TEST (validate)
+### 3. Validate
 
-Check quality:
-- Run: `npm run lint && npm run typecheck` (or equivalent)
-- If fails: fix only what you broke, re-run
-- NO full test suite unless explicitly requested
+- Run the smallest meaningful checks: targeted tests, touched-package lint/typecheck, and formatter when expected.
+- If a check fails, fix only failures caused by this change and rerun.
+- Run broader checks only for shared/high-risk code or when the user asks.
 
-## Output
+## Stop Rules
 
-When complete, return:
+- Do not expand into adjacent improvements.
+- Ask only when a missing decision blocks safe implementation.
+- If blocked after two concrete attempts, report the blocker, evidence, and the next exact option.
 
-```
-## Done
+## Final Response
 
-**Task:** {what was implemented}
-**Files changed:** {list}
-**Validation:** ✓ lint ✓ typecheck
-```
-
-## Constraints
-
-- ONE task only - no tangential improvements
-- NO documentation files unless requested
-- NO refactoring outside immediate scope
-- NO "while I'm here" additions
-- If stuck >2 attempts: report blocker and stop
+Report changed files, validation commands/results, and any skipped checks with reason.

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

@@ -1,7 +1,7 @@
 ---
 name: rules-manager
-description: Create and maintain agent rules in AGENTS.md and .agents/rules/. Use for project rules, conventions, constraints, rule indexes, or requests to add or optimize agent rules.
-argument-hint: "[init | add <rule-name> | optimize | task description]"
+description: Create, edit, and maintain AGENTS.md and .agents/rules/ — tech stack, commands, universal rules, rule index, and rule files. Use to add, modify, restructure, or optimize project rules, conventions, and constraints.
+argument-hint: "[init | add <rule-name> | edit | optimize | task description]"
 ---
 
 <core_principle>
@@ -146,6 +146,17 @@ When the argument starts with `add`:
 
 **CRITICAL:** Step 5 is non-negotiable. A rule file without an index entry is invisible.
 
+## `/rules-manager edit` - Modify AGENTS.md directly
+
+When the user wants to change AGENTS.md itself rather than add a rule file — update the tech stack, commands, universal rules, project description, or restructure sections:
+
+1. **Read AGENTS.md** - Load current content.
+2. **Make the targeted edit in place** - Change only the relevant section; leave unrelated sections untouched.
+3. **Preserve the index** - If touching `## Rules`, keep every `.agents/rules/*.md` link intact.
+4. **Stay minimal** - Apply `<writing_rules>`: specific, prohibitions over guidance, no bloat.
+
+This is the default when the user references AGENTS.md content (not a rule file) — e.g. "add a command to AGENTS.md", "update the tech stack", "tighten the universal rules".
+
 ## `/rules-manager optimize` - Audit and clean up
 
 When the argument contains `optimize`:
@@ -177,11 +188,13 @@ When the argument is a free-form task (e.g., "add a rule about how we tag releas
 
 <rules_for_this_skill>
 
+- This skill manages ALL of AGENTS.md (tech stack, commands, universal rules, index, description) and `.agents/rules/` — not just creating new rule files. Editing existing AGENTS.md content is fully in scope.
 - ALWAYS update AGENTS.md `## Rules` index when creating a file in `.agents/rules/`
 - NEVER create a rule file without confirming with the user what it should contain
 - NEVER overwrite existing AGENTS.md or rule files without asking
 - Default to short rule files (20-60 lines). Split if larger.
 - When user asks "create a rule", default to creating a file in `.agents/rules/` (not inline in AGENTS.md), unless the rule is 1-2 lines and fits the universal section.
+- When the user references AGENTS.md content directly (a command, the stack, a universal rule), edit AGENTS.md in place via the `edit` workflow — don't spin up a new rule file.
   </rules_for_this_skill>
 
 <reference_guides>

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

@@ -44,6 +44,17 @@ Three loading levels:
 
 Keep references one level deep. Reference them by name in SKILL.md so the agent knows when to open them.
 
+### Online research routing
+
+When a skill or agent needs online research, name the exact research skill to use instead of relying on vague web-search language:
+
+- Use `/Users/melvynx/.agents/skills/find-docs/SKILL.md` for current technical documentation, API references, config options, SDKs, CLIs, cloud services, and code examples.
+- Use `/Users/melvynx/.agents/skills/exa-search/SKILL.md` for broader online research, recent information, source discovery, similar pages, URL extraction, or cited web answers.
+- Mention default harness tools for local code, file, git, shell, and browser inspection.
+- Keep built-in `WebSearch` and `WebFetch` as fallback tools unless the user explicitly asks for them.
+- For restricted agents, include `Skill` and `Bash` in the tool list when these skills need to run local CLIs.
+- Never put secrets, tokens, credentials, personal data, or proprietary code in external queries.
+
 ### Skill anatomy
 
 ```
@@ -94,8 +105,25 @@ For researched guidance and examples, see [references/description-recommandation
 
 ## Where each platform stores skills
 
+**Canonical personal skills:** `~/.agents/skills/` is the single source of truth (git repo `Melvynx/agents-config`). It is an official user-level root for both Cursor and Codex, so they read it directly. Write new personal skills only under `~/.agents/skills/<name>/`.
+
+Per the official Cursor docs ([cursor.com/docs/skills](https://cursor.com/docs/skills)), user-level roots are `~/.agents/skills/` and `~/.cursor/skills/`, plus compat dirs `~/.claude/skills/` and `~/.codex/skills/`. `~/.cursor/skills-cursor/` is NOT a documented path; do not use it.
+
+Because `~/.agents/skills/` is read directly, the only symlinks needed are the compat dirs for agents that do not read `~/.agents/skills/` themselves:
+
+```bash
+~/.claude/skills -> ~/.agents/skills   # Claude Code reads ~/.claude/skills
+~/.codex/skills  -> ~/.agents/skills   # Codex compat (optional; Codex also reads ~/.agents/skills)
+```
+
+Do NOT symlink `~/.cursor/skills` or `~/.cursor/skills-cursor` to `~/.agents/skills/`; that makes Cursor scan the same skills two or three times. To repair the compat symlinks if missing:
+
+```bash
+ln -s ~/.agents/skills ~/.claude/skills
+```
+
 See the per-platform reference files. Quick reminders:
 
-- **Claude Code**: `~/.claude/skills/` (personal) or `.claude/skills/` (project). Higher scope wins on name collision.
+- **Cursor**: reads `~/.agents/skills/` and `~/.cursor/skills/` (user-level), `.agents/skills/` and `.cursor/skills/` (project). Use `~/.agents/skills/` as the single root; skip the `~/.cursor/skills*` symlinks.
+- **Claude Code**: `~/.claude/skills/` (symlink → `~/.agents/skills/`) or `.claude/skills/` (project). Higher scope wins on name collision.
 - **Codex**: `.agents/skills/` walks up from CWD to repo root, then `~/.agents/skills/`, then `/etc/codex/skills`, then system bundled.
-- **Cursor**: `.cursor/rules/` (project, version-controlled) or `AGENTS.md` files in project subdirectories.

package/agents-config/skills/ultrathink/SKILL.md

@@ -25,7 +25,7 @@ Take a deep breath. We're not here to write code. We're here to make a dent in t
 
 ## Your Tools Are Instruments
 
-- Use bash tools, MCP servers, and reusable skills like a virtuoso
+- Use bash tools, MCP servers, and custom commands like a virtuoso
 - Git history tells the story—read it, learn from it, honor it
 - Multiple Claude instances aren't redundancy—they're collaboration between perspectives
 

package/agents-config/skills/use-fable/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: use-fable
+description: "Orchestrator mode for Fable: Fable thinks, plans, and reviews while Codex CLI and subagents execute all heavy work. Use when the user invokes /use-fable, says 'use fable', 'fable mode', 'orchestrator mode', or wants to save Fable tokens/rate limits."
+---
+
+# Use Fable
+
+Fable is the thinker, never the typist. Its tokens are scarce and expensive; Codex (GPT-5.5) is effectively free and highly steerable. In this mode, Fable's job is deciding **what** to do and judging **whether it was done well** — everything token-hungry runs elsewhere and reports back.
+
+Model rankings, Codex mechanics, and effort settings live in `~/.claude/rules/models.md` (already in context). This skill is the enforcement layer.
+
+## Core rule
+
+Fable does not execute. Fable may: read a few targeted files, search, inspect git state, think, plan, decompose, write specs and delegation prompts, review diffs and reports, judge outputs, and talk to the user.
+
+Fable must NOT directly do:
+
+- Implementation, refactors, migrations, test writing (any multi-file or >~15-line change)
+- Codebase-wide exploration or analysis (reading many files to "understand")
+- Computer use, browser automation, UI/UX verification
+- Log triage, data analysis, bulk mechanical edits
+- Running long build/test loops and reading their full output
+
+The only direct edits allowed: trivial single-file tweaks (a config value, a typo, a one-liner) where writing a delegation prompt would cost more than the edit itself.
+
+## Who executes what
+
+| Task | Executor |
+|------|----------|
+| Well-spec'd implementation, refactors, migrations, bulk edits | Codex: `codex exec "<prompt>"` |
+| Investigation, codebase analysis, log/data triage (no writes) | Codex: `codex exec -s read-only "<prompt>"` |
+| Computer use, UI/UX verification, browser checks | Codex (way better at it) or `verifier`/`dev-browser` subagent |
+| Codebase exploration to inform a plan | `Explore` or `explore-fast` subagent — Fable reads the summary, not the files |
+| User-facing taste work (UI, copy, API design) | Claude subagent with `model: "opus"` |
+| Plan/implementation review | Fable itself (its core job), optionally + Codex as second perspective |
+| Inside a Workflow | thin `sonnet`/`effort: low` wrapper agent that runs `codex exec` via Bash and returns output verbatim |
+
+Claude subagents always get `model: "opus"` unless the wrapper-for-Codex pattern applies. Never Haiku.
+
+## The loop
+
+1. **Think.** Understand the request. If context is missing, delegate the exploration (don't read the codebase yourself) and think on the summaries.
+2. **Spec.** Write a self-contained delegation prompt: exact files, goal, constraints, and what "done" looks like (tests pass, lint clean, behavior X). Codex can't see this conversation — spell everything out. See `/codex:gpt-5-4-prompting` for hard cases.
+3. **Delegate.** Fire independent tasks in parallel (multiple `codex exec` in background, or multiple subagents in one message). Stay available to steer.
+4. **Verify.** Delegate verification too — Codex read-only pass, test run, or `verifier` agent. Fable reads the report and the diff, not the whole tree.
+5. **Judge.** If the output misses the bar: refine the spec and re-delegate (Codex is steerable — better prompts beat manual fixes), or escalate to an opus subagent for taste-sensitive work. Do not "just fix it quickly" yourself — that's how the mode dies.
+
+## Delegation prompt checklist (for Codex)
+
+- Names exact files/paths and the repo root
+- States the goal in one sentence, then constraints (style, deletion safety: `trash` not `rm -rf`, no scope creep)
+- Defines done: commands to run, expected results
+- Asks for a report: changed files, what was done, tests run, risks
+- Non-git/untrusted dir → add `--skip-git-repo-check`
+
+## Anti-patterns
+
+- "It's faster if I just do it" — for anything beyond a trivial tweak, it isn't: it burns the budget the whole session depends on.
+- Reading 10 files to plan — delegate exploration, plan from the summary.
+- Fixing Codex's output by hand — refine the prompt and rerun instead.
+- Serializing independent delegations — parallelize.
+- Verifying UI by taking screenshots yourself — Codex does computer use and UI verification better and cheaper.
+
+If no delegation path works (Codex unavailable, Bash denied), say so explicitly and ask the user before falling back to direct execution — never silently drop out of the mode.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiblueprint-cli",
-  "version": "1.4.88",
+  "version": "1.4.90",
   "description": "AIBlueprint CLI for setting up AI coding configurations",
   "author": "AIBlueprint",
   "license": "MIT",