ai-fob 1.2.1 → 1.3.1

package/assets/agents/build-validator-agent.md

@@ -26,6 +26,10 @@ You are a rigorous build validator. Your job is to run validation checks provide
 
 Run every validation check. Report exactly what you observe. If a check fails, describe the failure precisely -- what was expected vs. what actually happened. Do not attempt to fix the code or suggest fixes. Your report goes back to the orchestrator who will route failures to a builder agent for correction.
 
+## Browser Tool Constraint
+
+NEVER use the macOS `open` command to open URLs in a browser. ALWAYS use `agent-browser open <url>` for all browser-based checks. The `open` command launches Safari, which cannot be automated, snapshotted, or device-emulated. All browser interactions MUST go through `agent-browser` (Chromium via Playwright).
+
 ## Checks
 
 The calling prompt provides a numbered list of checks to run. Execute every check listed -- no more, no fewer. For each check:

package/assets/agents/meta-validator-agent.md

@@ -4,7 +4,7 @@ description: >
   CC Asset Validator. Validates CC asset plans, design specs, and built
   assets using CC-specific conventions and testing patterns. Operates in
   plan-validation or build-validation mode as directed by the calling prompt.
-tools: Read, Write, Grep, Glob, Bash, WebFetch, WebSearch, Skill, Task
+tools: Read, Write, Grep, Glob, Bash, WebFetch, WebSearch, Skill, Agent
 model: opus
 color: red
 skills:

package/assets/commands/build-cc-assets-phases.md

@@ -3,7 +3,7 @@ description: Build one phase of a CC assets plan — executes a single phase thr
 argument-hint: [path to cc-assets-plan] [phase number]
 model: opus
 disable-model-invocation: false
-allowed-tools: Skill, Task, Read, Glob, Grep, Write, Bash
+allowed-tools: Skill, Agent, Read, Glob, Grep, Write, Bash
 ---
 
 # Build CC Assets Phase
@@ -706,6 +706,7 @@ Assemble structural AND functional checks based on ASSET_TYPE, then delegate to
 5. **Referenced files exist** — Find all markdown links in SKILL.md (pattern: `[text](path)`). For each link pointing to a relative file path, verify the file exists relative to the skill directory. PASS if all referenced files found. FAIL if any missing.
 6. **Directory structure** — List the skill directory contents. PASS if only recognized items: SKILL.md, reference/, templates/, scripts/, workflows/. FAIL if unexpected files or directories.
 7. **Description quality** — The `description` field is a complete sentence explaining what the skill provides. PASS if it reads as a complete description with context for when to use it. FAIL if it is a fragment or lacks guidance.
+8. **No command name collision** — Verify that no file named `{ASSET_NAME}.md` exists in `.claude/commands/`. If a skill and command share the same name, the skill takes precedence and the command becomes uninvocable. Use Glob to check `.claude/commands/{ASSET_NAME}.md`. PASS if no such file exists. FAIL if a matching command file is found.
 
 **Structural checks when ASSET_TYPE == "agent":**
 
@@ -727,6 +728,7 @@ Assemble structural AND functional checks based on ASSET_TYPE, then delegate to
 6. **Has workflow steps** — The body contains numbered or headed workflow steps (patterns like `### Step` or `## Step` or numbered lists within a Workflow section). PASS if workflow structure found. FAIL if body lacks clear workflow organization.
 7. **Skill invocations valid** — If `Skill` appears in `allowed-tools`, search the body for skill invocation references. Verify each referenced skill exists at `.claude/skills/{name}/SKILL.md`. PASS if all found or `Skill` not in allowed-tools. FAIL if referenced skill not found.
 8. **Argument handling consistent** — If `argument-hint:` is set in frontmatter, verify `$ARGUMENTS` appears in the body. PASS if consistent (both present or both absent). FAIL if argument-hint is set but $ARGUMENTS not used.
+9. **No skill name collision** — Verify that no skill directory named `{ASSET_NAME}` exists in `.claude/skills/`. If a skill and command share the same name, the skill takes precedence and the command becomes uninvocable. Use Glob to check `.claude/skills/{ASSET_NAME}/SKILL.md`. PASS if no such skill exists. FAIL if a matching skill directory is found.
 
 **Modification add-on (when ASSET_ACTION == "modify", append to whichever type-specific list):**
 
@@ -737,9 +739,9 @@ Store the total structural check count as `STRUCTURAL_CHECK_COUNT`.
 
 **Functional checks when ASSET_TYPE == "skill"** (append after structural checks):
 
-8. **Skill loads via Skill tool** — Invoke the skill `{ASSET_NAME}` using the Skill tool. PASS if the skill loads without error. FAIL if an error occurs.
-9. **Reference files accessible** — After loading the skill, use Glob to list files in the skill's `reference/` and `templates/` directories. Read each file. PASS if all files listed in SKILL.md are readable. FAIL if any file fails to read.
-10. **Knowledge verification** — After loading the skill, derive a knowledge question from the test scenario: {TEST_SCENARIO}. The question should require specific knowledge from the skill's content (not general knowledge). Evaluate whether the skill's content addresses the test scenario's success criteria. PASS if the skill content supports the expected knowledge. FAIL if it does not.
+9. **Skill loads via Skill tool** — Invoke the skill `{ASSET_NAME}` using the Skill tool. PASS if the skill loads without error. FAIL if an error occurs.
+10. **Reference files accessible** — After loading the skill, use Glob to list files in the skill's `reference/` and `templates/` directories. Read each file. PASS if all files listed in SKILL.md are readable. FAIL if any file fails to read.
+11. **Knowledge verification** — After loading the skill, derive a knowledge question from the test scenario: {TEST_SCENARIO}. The question should require specific knowledge from the skill's content (not general knowledge). Evaluate whether the skill's content addresses the test scenario's success criteria. PASS if the skill content supports the expected knowledge. FAIL if it does not.
 
 **Functional checks when ASSET_TYPE == "agent"** (append after structural checks):
 
@@ -748,7 +750,7 @@ Store the total structural check count as `STRUCTURAL_CHECK_COUNT`.
 
 **Functional checks when ASSET_TYPE == "command"** (append after structural checks):
 
-9. **Manual test instructions written** — Write manual test instructions to `{PHASE_DIR}/manual_test_instructions.md` using this format:
+10. **Manual test instructions written** — Write manual test instructions to `{PHASE_DIR}/manual_test_instructions.md` using this format:
 
 ```
 # Manual Test: /{ASSET_NAME}
@@ -1098,4 +1100,4 @@ Run /{ASSET_NAME} with test scenario inputs.
 Instructions: {PHASE_DIR}/manual_test_instructions.md}
 
 Next Phase: {If PHASE_NUMBER < total phases: "Phase {PHASE_NUMBER + 1}: {next phase name} — run /build-cc-assets-phases {PLAN_PATH} {PHASE_NUMBER + 1}" | "All phases complete."}
-```
+```

package/assets/commands/build-phase-V2.md

@@ -3,7 +3,7 @@ description: Build one phase of a phased high-level plan (Research + Implementat
 argument-hint: [path to HL plan] [phase number]
 model: opus
 disable-model-invocation: true
-allowed-tools: Skill, Task, Read, Glob, Grep, Write, Bash
+allowed-tools: Skill, Agent, Read, Glob, Grep, Write, Bash
 ---
 
 # Build Phase V2
@@ -927,6 +927,12 @@ Store the total check count as `BUILD_CHECK_COUNT`. Store the count of HL criter
 
 Determine if browser checks exist: scan the assembled check list for any check that mentions "browser", "agent-browser", "navigate", "page", "UI", or "localhost". Store as `HAS_BROWSER_CHECKS` (true/false).
 
+If `HAS_BROWSER_CHECKS` is true: Read the Mobile Test Devices section from the testing-and-validation skill. Extract the Primary Device and Secondary Device values. Store as `MOBILE_PRIMARY_DEVICE` and `MOBILE_SECONDARY_DEVICE`. Determine `HAS_MOBILE_CHECKS`:
+- If `MOBILE_PRIMARY_DEVICE` is "NONE": set `HAS_MOBILE_CHECKS = false`.
+- Otherwise: set `HAS_MOBILE_CHECKS = true`.
+
+If `HAS_BROWSER_CHECKS` is false: set `HAS_MOBILE_CHECKS = false`.
+
 #### 5b. Start Dev Server (if needed)
 
 If `HAS_BROWSER_CHECKS` is true:
@@ -997,6 +1003,27 @@ Read the build report(s) for context on what was built:
  If Username is "REPLACE_WITH_TEST_USERNAME":
   "Test credentials have NOT been configured in the testing-and-validation skill. The placeholder values have not been replaced. Browser checks that require authentication MUST be marked as BLOCKED with reason: 'Test credentials not configured in testing-and-validation skill -- user must replace placeholder values.'"}
 
+## Mobile Device Testing
+{Read the Mobile Test Devices section from the testing-and-validation skill. Extract the Primary Device and Secondary Device values.
+
+ If HAS_MOBILE_CHECKS is true (Primary Device is NOT "NONE"):
+  "Mobile viewport testing is configured for this project. After completing each browser check at the default desktop viewport, you MUST repeat the visual/layout portions of that check at the mobile viewport.
+
+  Mobile testing procedure (use the agent-browser skill):
+  1. Complete the browser check at the default desktop viewport first
+  2. Set the mobile device: `agent-browser set device \"{MOBILE_PRIMARY_DEVICE}\"`
+  3. Reload the page: `agent-browser reload`
+  4. Take a snapshot to verify layout at mobile viewport: `agent-browser snapshot -i`
+  5. Take a screenshot for visual evidence: `agent-browser screenshot`
+  6. Verify the page renders correctly at the mobile viewport -- no overlapping elements, no horizontal scrolling, no truncated content, no inaccessible interactive elements
+  7. Reset to desktop viewport when done: `agent-browser set viewport 1920 1080`{If MOBILE_SECONDARY_DEVICE is not "NONE":
+  8. Repeat steps 2-7 with the secondary device: `agent-browser set device \"{MOBILE_SECONDARY_DEVICE}\"`}
+
+  For each browser check, report desktop and mobile results separately. If a check passes at desktop but fails at mobile, the overall check result is FAIL. Include the device name in the findings (e.g., 'FAIL at iPhone 12 Pro: navigation menu overlaps content')."
+
+ If HAS_MOBILE_CHECKS is false:
+  "Mobile viewport testing is not configured (Primary Device is NONE in the testing-and-validation skill). All browser checks run at the default desktop viewport only."}
+
 ## Validation Checks ({BUILD_CHECK_COUNT} -- run ALL of these)
 
 {The assembled numbered check list from step 5a -- paste the full list verbatim, including the [HL] prefixed checks at the end}

package/assets/commands/create-highlevel-plan-phases.md

@@ -3,7 +3,7 @@ description: Create a high-level plan with phased implementation breakdown and p
 argument-hint: [task description or feature document path]
 model: opus
 disable-model-invocation: true
-allowed-tools: Skill, Task, TeamCreate, SendMessage, TaskCreate, TaskUpdate, TaskList, TaskGet
+allowed-tools: Skill, Agent, TeamCreate, SendMessage, TaskCreate, TaskUpdate, TaskList, TaskGet
 ---
 
 # Create High-Level Plan (Phased)
@@ -93,7 +93,8 @@ The user provided a feature document from a reverse-engineering analysis. Use it
    - **Name**: short descriptive name
    - **Goal**: 1-2 sentences on what this phase achieves and why it comes at this position
    - **Dependencies**: which prior phase(s) must complete first (or "None" for the first)
-   - **Success criteria**: concrete, verifiable statements (can be user stories, anti-stories, API checks, state checks, UI checks, build checks)
+   - **Success criteria**: concrete, verifiable statements (can be user stories, anti-stories, API checks, state checks, UI checks, build checks, mobile viewport checks)
+   - For phases with UI work, ask: "Does this need to work on mobile viewports?" If yes, include mobile-specific success criteria (e.g., "Navigation menu is usable on iPhone 12 Pro viewport")
    Target 3-5 phases. Present the suggested phases to the user:
    ```
    Based on the feature document, I suggest this phase breakdown:
@@ -155,7 +156,9 @@ The user provided a feature document from a reverse-engineering analysis. Use it
        - State/infrastructure checks: "Database tables exist and are accessible"
        - UI checks: "Login form renders with email and password fields"
        - Build/tooling checks: "`bun dev` starts without errors"
+       - Mobile viewport checks: "Navigation is usable at iPhone 12 Pro viewport"
    - For phases with user-facing behavior, success criteria MUST include both user stories (what users CAN do) and anti-stories (what users CANNOT do)
+   - For phases with UI work, ask the user: "Does this need to work on mobile viewports?" If yes, include mobile-specific success criteria. Mobile viewport testing is configured in the testing-and-validation skill.
    - Each criterion must be testable -- a future validator should be able to determine PASS/FAIL
    - The last phase should typically be "Integration & Polish"
 8. Do NOT proceed to Phase 2 until you and the user explicitly agree on the task description, user stories, anti-stories, phase breakdown, and detailed specifications (if any were provided).

package/assets/commands/handoff.md

@@ -2,7 +2,7 @@
 description: Hand off plan implementation to a sub-agent
 model: opus
 disable-model-invocation: true
-allowed-tools: Task, Read, Glob
+allowed-tools: Agent, Read, Glob
 ---
 
 # Handoff

package/assets/commands/plan-cc-assets-phases.md

@@ -3,7 +3,7 @@ description: Plan a phased system of CC assets (skills, agents, commands)
 argument-hint: [description of the system to plan]
 model: opus
 disable-model-invocation: true
-allowed-tools: Skill, Task, TeamCreate, SendMessage, TaskCreate, TaskUpdate, TaskList, TaskGet
+allowed-tools: Skill, Agent, TeamCreate, SendMessage, TaskCreate, TaskUpdate, TaskList, TaskGet
 ---
 
 # Plan CC Assets (Phased)
@@ -205,6 +205,7 @@ You (the main agent) handle this step directly. Using the understanding from Ste
 - **The command controls behavior via prompts.** When a workflow needs an agent to do three different things (e.g., scan broadly, then trace deeply, then synthesize), that's three Task tool calls to the same agent with different prompts — not three separate agent definitions.
 - **Challenge every "New Agent".** For each proposed new agent, ask: "Could an existing agent do this if given the right prompt?" If yes, it's a Reuse, not a New Agent.
 - **Skills earn their place.** Only propose a new skill if there is genuine domain knowledge that needs to be encoded and reused across multiple agents or commands. A one-off workflow does not need its own skill.
+- **No cross-type name collisions.** A new skill MUST NOT share its directory name with any existing or planned command filename (minus `.md`), and vice versa. If a skill and command share the same name, the skill takes precedence and the command becomes uninvocable. For every proposed asset, check: `ls .claude/skills/` and `ls .claude/commands/` and verify no collision exists among planned assets either.
 
 With the minimalism principle in mind:
 
@@ -430,7 +431,7 @@ Read the plan file at: {SAVE_PATH}
 ### Confirmed Asset Inventory
 {The asset inventory as confirmed by the user in Step 3}
 
-## Validation Checks (8 — run ALL of these)
+## Validation Checks (9 — run ALL of these)
 
 1. **Existing asset references** — Does every referenced existing asset actually exist on disk? For each asset the plan says to "reuse" or "modify", verify the file exists: skills in `.claude/skills/{name}/SKILL.md`, agents in `.claude/agents/{name}.md`, commands in `.claude/commands/{name}.md`. Use Glob to check. Flag any reference to an asset that does not exist.
 
@@ -448,6 +449,8 @@ Read the plan file at: {SAVE_PATH}
 
 8. **Minimalism compliance** — Does the asset inventory follow the minimalism principle? Check for: (a) agents with the same tools and skills that should be consolidated into one agent spawned with different prompts, (b) skills that encode knowledge used by only one agent for one task, (c) new assets that could be replaced by reusing existing ones. Cross-reference with the existing asset landscape from the context. Flag any violation of minimalism.
 
+9. **No cross-type name collisions** — Does any proposed skill share its directory name with a proposed or existing command filename (minus `.md`), or vice versa? For each skill in the asset inventory, check if a command with the same name exists in `.claude/commands/` or is planned in the inventory. For each command, check if a skill with the same name exists in `.claude/skills/` or is planned. If a skill and command share the same name, the skill takes precedence and the command becomes uninvocable. Flag any collision.
+
 ## Output
 Present the validation report directly in your response using your standard validation report format (Overall PASS/FAIL, checks table, issues found, verified claims).
 ```
@@ -466,13 +469,13 @@ After the validator completes, read the validation report:
 - **With agent teams**: Read the Validator's report from the shared task list.
 - **With Task tool fallback**: Use the captured output from the Task delegation.
 
-**If validation PASSES (all 8 checks):**
+**If validation PASSES (all 9 checks):**
 - Note the validation result for the final report
 - Proceed to Step 6
 
 **If validation FAILS:**
 
-1. Present the validation failures to the user briefly: "{N}/8 checks passed. The following issues were found: {summary of FAIL items}. Sending back to the architect for corrections."
+1. Present the validation failures to the user briefly: "{N}/9 checks passed. The following issues were found: {summary of FAIL items}. Sending back to the architect for corrections."
 
 2. Send corrections to the architect:
 
@@ -524,7 +527,7 @@ Apply corrections and write the updated plan back to the same path using the Wri
 
 Read the plan from SAVE_PATH and present it to the user in full. Include the validation status:
 
-"The following CC assets plan has been produced and validated ({checks_passed}/8 checks passed{', with known issues noted' if any checks failed after max cycles}). Plan file: {SAVE_PATH}"
+"The following CC assets plan has been produced and validated ({checks_passed}/9 checks passed{', with known issues noted' if any checks failed after max cycles}). Plan file: {SAVE_PATH}"
 
 Then present the complete plan content (read from disk).
 
@@ -613,7 +616,7 @@ Asset Summary:
   Reuse (existing): {count}
   Total: {count}
 
-Validation: {PASSED | PASSED with warnings} ({checks_passed}/8 checks verified)
+Validation: {PASSED | PASSED with warnings} ({checks_passed}/9 checks verified)
 Architect Iterations: {count}
 
 Delegation Mode: {Agent Teams | Task Tool (fallback)}
@@ -622,7 +625,7 @@ Team Members Used:
 - Explorer: completed
 - Docs Researcher: completed
 - Architect: completed ({N} iterations)
-- Validator: {PASSED | FAILED} ({checks_passed}/8 checks verified)
+- Validator: {PASSED | FAILED} ({checks_passed}/9 checks verified)
 
 Next Step:
   Run /build-cc-assets-phases {SAVE_PATH} 1
@@ -688,4 +691,4 @@ How all assets work together once all phases are complete. Trace the end-to-end
 
 ## 6. Key Considerations
 Risks, open questions, dependencies on external factors.
-```
+```

package/assets/commands/plan-project.md

@@ -2,7 +2,7 @@
 description: Interactive project planning — gathers requirements, researches tech docs, produces specs/project.md
 argument-hint: [project idea or name]
 model: opus
-allowed-tools: Skill, Task, TeamCreate, SendMessage, TaskCreate, TaskUpdate, TaskList, TaskGet, AskUserQuestion, Read, Write, Bash, Glob, Grep
+allowed-tools: Skill, Agent, TeamCreate, SendMessage, TaskCreate, TaskUpdate, TaskList, TaskGet, AskUserQuestion, Read, Write, Bash, Glob, Grep
 disable-model-invocation: true
 ---
 

package/assets/commands/repair-workflow.md

@@ -3,7 +3,7 @@ description: Diagnose and fix broken CC assets -- traces problems through the pr
 argument-hint: [description of the problem or path to affected asset]
 model: opus
 disable-model-invocation: true
-allowed-tools: Agent, Skill, Task, Read, Write, Edit, Glob, Grep, Bash, MultiEdit
+allowed-tools: Agent, Skill, Read, Write, Edit, Glob, Grep, Bash, MultiEdit
 ---
 
 # Repair Workflow
@@ -119,8 +119,8 @@ You are checking whether current CC documentation affects a broken CC asset.
 ## Your Research Tasks
 
 1. Check current Claude Code skills documentation at https://code.claude.com/docs/en/skills
-2. Check current Claude Code sub-agents documentation at https://docs.anthropic.com/en/docs/claude-code/sub-agents
-3. Check current Claude Code settings documentation at https://docs.anthropic.com/en/docs/claude-code/settings
+2. Check current Claude Code sub-agents documentation at https://code.claude.com/docs/en/sub-agents
+3. Check current Claude Code settings documentation at https://code.claude.com/docs/en/settings
 4. If the affected asset uses agent teams, check teams documentation at https://code.claude.com/docs/en/agent-teams
 
 ## Output Format

package/assets/commands/reverse-engineer-from-code.md

@@ -3,7 +3,7 @@ description: Reverse-engineer a feature from a locally cloned repo into a tech-a
 argument-hint: [repo-path]
 model: opus
 disable-model-invocation: true
-allowed-tools: Skill, Task, TeamCreate, SendMessage, TaskCreate, TaskUpdate, TaskList, TaskGet, Read, Glob, Grep, Write, Bash
+allowed-tools: Skill, Agent, TeamCreate, SendMessage, TaskCreate, TaskUpdate, TaskList, TaskGet, Read, Glob, Grep, Write, Bash
 ---
 
 # Reverse-Engineer From Code

package/assets/commands/{audit-cc-assets.md → run-audit-cc-assets.md}

@@ -581,5 +581,5 @@ Output:
 
 Next Steps:
   - Review MISSING findings in the audit report for manual design decisions
-  - Run /audit-cc-assets again after the next CC update to check for new changes
+  - Run /run-audit-cc-assets again after the next CC update to check for new changes
 ```

package/assets/commands/setup-convex-dev-deployment.md

@@ -0,0 +1,288 @@
+---
+description: Provision an isolated Convex dev deployment seeded with data from the current dev deployment
+allowed-tools: Agent, Skill, Bash, Read, Glob, Grep, AskUserQuestion
+model: opus
+disable-model-invocation: true
+---
+
+# Setup Convex Dev Deployment
+
+Provision a new, isolated Convex development deployment for feature work. Exports data from the current dev deployment, guides you through creating a new Convex project, imports the data snapshot, copies environment variables, and provides auth webhook instructions. The output (deployment name + URL) can feed into `/feature-dev-worktree` to create a git worktree pointed at the new deployment.
+
+**Required Skill**: Before starting Phase 1, invoke the `convex-best-practices` skill using the Skill tool to load deployment management knowledge. This provides the CLI commands, deployment model, and auth reconnection patterns used throughout the workflow.
+
+## Variables
+
+FEATURE_NAME: $ARGUMENTS
+
+## Workflow
+
+### Phase 1: Detect Project Setup (Explorer Agent)
+
+You (the main agent) handle argument parsing and skill invocation. Then delegate detection to the explorer-agent.
+
+1. **Parse arguments.** Extract FEATURE_NAME from `$ARGUMENTS`.
+   - If FEATURE_NAME is empty (no arguments provided), use AskUserQuestion to ask: "What is the name of the feature you are creating this deployment for? (e.g., auth-refactor, payments-v2, onboarding-flow)"
+   - Store the FEATURE_NAME for use in Phase 3 naming suggestions.
+
+2. **Invoke the skill.** The `convex-best-practices` skill should already be loaded from the Required Skill invocation above. Confirm it is available in context. The deployment management knowledge from `reference/deployment-management.md` provides the CLI commands and patterns for all subsequent phases.
+
+3. **Delegate to explorer-agent.** Use the Agent tool to delegate to `explorer-agent` (set `subagent_type` to `explorer-agent`). Include this FULL prompt:
+
+```
+You are scanning this project to identify its Convex setup. This information is needed to provision an isolated dev deployment.
+
+## Your Detection Tasks
+
+Report the following with exact values:
+
+1. **Convex directory**: Where is the `convex/` directory? (relative path from project root)
+2. **Monorepo**: Is this a monorepo? If so, what type? (Turborepo, Bun workspaces, npm workspaces, pnpm workspaces, or "not a monorepo")
+3. **Package manager**: What package manager is used? (bun, npm, pnpm, yarn) -- check for lock files: bun.lock/bun.lockb, package-lock.json, pnpm-lock.yaml, yarn.lock
+4. **Env file location**: Where is `.env.local`? (may be at project root or in a specific app directory in a monorepo)
+5. **CONVEX_DEPLOYMENT**: What is the current `CONVEX_DEPLOYMENT` value from `.env.local`?
+6. **Deployment URL variable**: What is the deployment URL variable name and value? (e.g., `NEXT_PUBLIC_CONVEX_URL`, `VITE_CONVEX_URL`, `EXPO_PUBLIC_CONVEX_URL`)
+7. **Auth provider**: What auth provider is used? Search for: `@clerk/nextjs` or `@clerk/react` (Clerk), `next-auth` (NextAuth), `@auth0/nextjs-auth0` (Auth0), `convex/auth` imports (Convex Auth), or none
+8. **Clerk webhook**: If Clerk: is there a `clerk-users-webhook` HTTP action in the convex directory? Search for files containing "clerk-users-webhook" or httpAction handlers related to Clerk
+9. **Team name**: What is the Convex team name? Parse the `CONVEX_DEPLOYMENT` value -- the format is typically `<team>:<project>:<deployment>` or check `convex.json` for team info
+10. **Other env files**: Are there any other `.env` files? (`.env`, `.env.development`, `.env.production`, etc.)
+
+## Output Format
+
+Report your findings as a structured list:
+
+- **Convex Directory**: {path}
+- **Monorepo**: {type or "No"}
+- **Package Manager**: {name}
+- **Env File Location**: {path to .env.local}
+- **CONVEX_DEPLOYMENT**: {value}
+- **Deployment URL Variable**: {NAME}={value}
+- **Auth Provider**: {name or "None"}
+- **Clerk Webhook Action**: {Yes/No -- file path if yes}
+- **Team Name**: {name}
+- **Other Env Files**: {list or "None"}
+
+Do NOT suggest improvements or changes. Only report what exists.
+```
+
+4. **Validate findings.** After the explorer returns:
+   - If no `convex/` directory was found: STOP and tell the user: "No Convex setup detected in this project. This command requires an existing Convex project with a `convex/` directory and `.env.local` file."
+   - If `.env.local` was not found or `CONVEX_DEPLOYMENT` is empty: STOP and tell the user: "No `.env.local` file found with a `CONVEX_DEPLOYMENT` value. This command requires an existing Convex dev deployment. Run `npx convex dev` first to set up your initial deployment."
+   - Store all explorer findings for use in subsequent phases. In particular, store:
+     - `ORIGINAL_DEPLOYMENT_NAME` = the `CONVEX_DEPLOYMENT` value (this is CRITICAL -- it will be needed in Phase 6 after `.env.local` is overwritten)
+     - `ORIGINAL_DEPLOYMENT_URL` = the deployment URL value
+     - `ENV_FILE_PATH` = the path to `.env.local`
+     - `WORKING_DIR` = the directory containing `.env.local` (this is where Convex CLI commands should run)
+     - `AUTH_PROVIDER` = the auth provider name
+     - `HAS_CLERK_WEBHOOK` = whether a clerk-users-webhook action exists
+     - `TEAM_NAME` = the Convex team name
+
+### Phase 2: Export Snapshot
+
+Using the explorer's findings, export a data snapshot from the current dev deployment.
+
+1. **Create temp directory.** Run via Bash:
+   ```
+   TIMESTAMP=$(date +%Y%m%d_%H%M%S)
+   mkdir -p /tmp/convex-snapshot-${TIMESTAMP}
+   echo "/tmp/convex-snapshot-${TIMESTAMP}"
+   ```
+   Store the temp directory path as `SNAPSHOT_DIR`.
+
+2. **Export data.** Run via Bash (from the WORKING_DIR):
+   ```
+   cd {WORKING_DIR} && npx convex export --path {SNAPSHOT_DIR}/snapshot.zip
+   ```
+
+   Note: Do NOT use `--include-file-storage` unless the user specifically asks for it. Storage files (profile pictures, uploads, etc.) can be large and are often acceptable losses for a feature deployment.
+
+3. **Verify export.** Run via Bash:
+   ```
+   ls -lh {SNAPSHOT_DIR}/snapshot.zip
+   ```
+   - If the export failed (non-zero exit code or file does not exist): STOP and report the error to the user. Include the full error output.
+   - If successful: report the snapshot file size to the user.
+
+4. **Report to user:**
+   > Snapshot exported successfully.
+   > - File: `{SNAPSHOT_DIR}/snapshot.zip`
+   > - Size: {file size}
+   >
+   > Proceeding to create a new Convex project.
+
+### Phase 3: Create New Project (User Manual Step)
+
+**CONFIRMATION GATE**: Do NOT proceed to Phase 4 until the user confirms the new project has been created.
+
+1. **Derive project name suggestion.** Parse the current project name from `ORIGINAL_DEPLOYMENT_NAME` or from the closest `package.json` name field. Suggest a name following the convention: `{project-name}-feature-{FEATURE_NAME}`.
+
+2. **Present instructions via AskUserQuestion:**
+
+   > **ACTION REQUIRED: Create a new Convex project**
+   >
+   > Please create a new project in the Convex dashboard:
+   >
+   > 1. Open: https://dashboard.convex.dev
+   > 2. Click "Create Project"
+   > 3. Suggested name: `{project-name}-feature-{FEATURE_NAME}`
+   > 4. Select your team: `{TEAM_NAME}`
+   > 5. Once created, come back here
+   >
+   > What is the name of the new project you created?
+
+3. **Store the response** as `NEW_PROJECT_NAME`.
+
+### Phase 4: Configure New Deployment (User Manual Step)
+
+**CONFIRMATION GATE**: Do NOT proceed to Phase 5 until the user confirms the deployment is configured.
+
+1. **Present instructions via AskUserQuestion:**
+
+   > **ACTION REQUIRED: Connect to the new deployment**
+   >
+   > Run this command in a **separate terminal** (not in Claude Code):
+   > ```
+   > npx convex dev --configure=existing --team {TEAM_NAME} --project {NEW_PROJECT_NAME}
+   > ```
+   >
+   > This will update your `.env.local` with the new deployment's `CONVEX_DEPLOYMENT` and URL.
+   >
+   > **IMPORTANT**: After running this command, leave that terminal running -- it deploys your schema and functions to the new deployment. Come back here and confirm when the deployment is ready.
+   >
+   > Have you run the command and is the deployment ready?
+
+2. **Capture new deployment values.** After the user confirms, read the `.env.local` file at `ENV_FILE_PATH` to capture:
+   - `NEW_DEPLOYMENT_NAME` = the new `CONVEX_DEPLOYMENT` value
+   - `NEW_DEPLOYMENT_URL` = the new deployment URL value
+
+3. **Verify the switch.** Confirm that `NEW_DEPLOYMENT_NAME` is different from `ORIGINAL_DEPLOYMENT_NAME`. If they are the same, warn the user: "It looks like `.env.local` still points to the original deployment. Please check that you ran `npx convex dev --configure=existing` successfully."
+
+### Phase 5: Import Snapshot
+
+Import the previously exported data into the new deployment.
+
+1. **Import data.** Run via Bash (from the WORKING_DIR):
+   ```
+   cd {WORKING_DIR} && npx convex import {SNAPSHOT_DIR}/snapshot.zip
+   ```
+
+2. **Handle import result:**
+   - If successful: report "Data imported successfully" and proceed to Phase 6.
+   - If failed with "table already contains data" or similar: retry with the `--replace` flag:
+     ```
+     cd {WORKING_DIR} && npx convex import --replace {SNAPSHOT_DIR}/snapshot.zip
+     ```
+   - If the retry also fails: report the full error to the user and use AskUserQuestion to ask how to proceed:
+     > Import failed. Error: {error details}
+     >
+     > Options:
+     > A) Retry with different flags
+     > B) Skip import -- I'll handle data manually
+     > C) Abort -- I'll fix the issue and try again later
+
+3. **Report to user:**
+   > Data imported to the new deployment.
+   > - Source: `{ORIGINAL_DEPLOYMENT_NAME}`
+   > - Target: `{NEW_DEPLOYMENT_NAME}`
+
+### Phase 6: Copy Environment Variables
+
+Copy environment variables from the source deployment to the new deployment.
+
+1. **List source env vars.** Since `.env.local` now points to the new deployment, use `--deployment-name` to target the original. Run via Bash:
+   ```
+   cd {WORKING_DIR} && npx convex env list --deployment-name {ORIGINAL_DEPLOYMENT_NAME}
+   ```
+
+   Note: This is why we stored `ORIGINAL_DEPLOYMENT_NAME` in Phase 1 -- `.env.local` was overwritten in Phase 4.
+
+2. **Parse the output.** Extract NAME=VALUE pairs from the env list output. If the output is empty (no environment variables), skip to Phase 7 with a note: "No environment variables found on the source deployment. Skipping env var copy."
+
+3. **Present to user via AskUserQuestion:**
+
+   > **Environment Variables from source deployment (`{ORIGINAL_DEPLOYMENT_NAME}`):**
+   >
+   > {list each variable with name visible and value partially masked, e.g., CLERK_SECRET_KEY=sk_test_***...***abc}
+   >
+   > Which variables should be copied to the new deployment?
+   > A) All of them (Recommended)
+   > B) Let me select which ones to exclude
+   > C) Skip -- I'll set them manually
+
+4. **Handle response:**
+   - If A: copy all variables
+   - If B: use AskUserQuestion to ask which variables to exclude, then copy the rest
+   - If C: skip to Phase 7
+
+5. **Copy approved variables.** For each approved variable, run via Bash:
+   ```
+   cd {WORKING_DIR} && npx convex env set {NAME} '{VALUE}'
+   ```
+
+   Run these sequentially, not in parallel. Report progress as each variable is set.
+
+6. **Track results.** Store the count of copied vs. skipped variables and the names of any skipped variables for the final report.
+
+### Phase 7: Cleanup and Report
+
+1. **Clean up temp snapshot.** Run via Bash:
+   ```
+   rm -rf {SNAPSHOT_DIR}
+   ```
+
+2. **Determine auth instructions.** Based on the explorer findings:
+   - If AUTH_PROVIDER is "Clerk" AND HAS_CLERK_WEBHOOK is true, present Clerk webhook instructions (see below).
+   - If AUTH_PROVIDER is "Clerk" but no webhook action was found, present a generic note: "Your project uses Clerk. Verify that your auth configuration works with the new deployment. If you have webhook-based user sync, you may need to add a new webhook endpoint."
+   - If AUTH_PROVIDER is something other than "Clerk" and not "None", present: "Your project uses {AUTH_PROVIDER}. If your auth setup includes webhooks or deployment-specific configuration, you may need to update it for the new deployment."
+   - If AUTH_PROVIDER is "None", skip auth instructions.
+
+3. **Clerk webhook instructions** (if applicable):
+
+   > **ACTION REQUIRED: Configure Clerk Webhook**
+   >
+   > Your project uses Clerk with a webhook for user sync. You need to add a new webhook endpoint in the Clerk dashboard:
+   >
+   > 1. Open the Clerk dashboard: https://dashboard.clerk.com
+   > 2. Go to **Webhooks**
+   > 3. Click **Add Endpoint**
+   > 4. URL: `https://{NEW_DEPLOYMENT_NAME}.convex.site/clerk-users-webhook`
+   > 5. Subscribe to the same events as your existing webhook (typically: `user.created`, `user.updated`, `user.deleted`)
+   >
+   > Without this, user creation/updates in Clerk will not sync to your new deployment's database.
+
+   Note: The `{NEW_DEPLOYMENT_NAME}` is used as the deployment slug in the `.convex.site` URL. If the deployment name format includes a team prefix (e.g., `team:project:deployment`), extract just the deployment slug portion. The correct slug is typically visible in the Convex dashboard URL.
+
+4. **Present the final report.**
+
+## Report
+
+Present the final report in this exact format:
+
+```
+DEPLOYMENT SETUP COMPLETE
+
+Source Deployment: {ORIGINAL_DEPLOYMENT_NAME}
+New Deployment: {NEW_DEPLOYMENT_NAME}
+New URL: {NEW_DEPLOYMENT_URL}
+Feature: {FEATURE_NAME}
+
+Data:
+  Snapshot exported: {file size}
+  Tables imported: successfully
+  Storage files: Not transferred (expected)
+
+Environment Variables:
+  Copied: {count} of {total}
+  Skipped: {list of skipped var names, or "None"}
+
+Auth:
+  Provider: {AUTH_PROVIDER}
+  Webhook setup: {Required -- see instructions above | Not applicable}
+
+Next Steps:
+  1. {If Clerk webhook needed: "Configure the Clerk webhook (see instructions above)"}
+  2. Verify the new deployment works: open https://dashboard.convex.dev and check your data
+  3. Your .env.local now points to the new deployment -- all local dev uses the new deployment
+  4. To switch back to the original: npx convex dev --configure=existing --team {TEAM_NAME} --project {original project name}
+  5. Future: run /feature-dev-worktree to create a git worktree using this deployment
+```

package/assets/commands/setup-project.md

@@ -1,6 +1,6 @@
 ---
 description: Scaffold a new project from specs/project.md — creates codebase, installs packages, initializes state files
-allowed-tools: Task, Skill, TeamCreate, SendMessage, TaskCreate, TaskUpdate, TaskList, TaskGet, Read, Glob, Grep, AskUserQuestion
+allowed-tools: Agent, Skill, TeamCreate, SendMessage, TaskCreate, TaskUpdate, TaskList, TaskGet, Read, Glob, Grep, AskUserQuestion
 model: opus
 disable-model-invocation: true
 ---

package/assets/skills/audit-cc-assets/SKILL.md

@@ -212,7 +212,7 @@ For the structured report template that aggregates findings, see [templates/audi
 
 ## For Agents Consuming This Skill
 
-This section guides the meta-auditor-agent and the `/audit-cc-assets` command in applying this methodology. The meta-auditor-agent has this skill pre-loaded via its `skills:` frontmatter field. The command also invokes this skill via the Skill tool for its own context.
+This section guides the meta-auditor-agent and the `/run-audit-cc-assets` command in applying this methodology. The meta-auditor-agent has this skill pre-loaded via its `skills:` frontmatter field. The command also invokes this skill via the Skill tool for its own context.
 
 ### Agent Roles
 
@@ -233,7 +233,7 @@ This section guides the meta-auditor-agent and the `/audit-cc-assets` command in
 
 ### What This Skill Does NOT Cover
 
-- This skill does NOT contain workflow steps for the audit process (those belong in the `/audit-cc-assets` command, Phase 3).
+- This skill does NOT contain workflow steps for the audit process (those belong in the `/run-audit-cc-assets` command, Phase 3).
 - This skill does NOT prescribe which tools to use or how to interact with the user (those are command and agent concerns).
 - This skill does NOT encode domain-specific technology knowledge (e.g., React, Convex, TypeScript).
 - This skill does NOT duplicate CC asset creation knowledge (that belongs in the `claude-code-primitives` skill).

package/assets/skills/audit-cc-assets/templates/audit-report.md

@@ -1,6 +1,6 @@
 # Audit Report Template
 
-This template defines the structured output format for CC asset audit findings. The meta-auditor-agent uses this template to produce its report. The `/audit-cc-assets` command presents this report to the user and uses it to drive the fix approval workflow.
+This template defines the structured output format for CC asset audit findings. The meta-auditor-agent uses this template to produce its report. The `/run-audit-cc-assets` command presents this report to the user and uses it to drive the fix approval workflow.
 
 ## Template
 

package/assets/skills/audit-cc-assets/templates/audit-state-schema.md

@@ -52,6 +52,6 @@ The file `.claude/audit-state.json` tracks audit history for the project. It is
 
 - The `auditHistory` array is append-only. New entries are added at the end after each audit completes. Do not remove or modify previous entries.
 - The `lastAuditSummary` object is always overwritten with the most recent audit's data. It provides a quick snapshot without needing to parse the full history array.
-- The `/audit-cc-assets` command reads this file at the start of each audit to determine whether to run a full or incremental audit. If `lastAuditedCCVersion` is more than 5 versions behind the current CC version, a full audit is recommended.
+- The `/run-audit-cc-assets` command reads this file at the start of each audit to determine whether to run a full or incremental audit. If `lastAuditedCCVersion` is more than 5 versions behind the current CC version, a full audit is recommended.
 - If the file does not exist, the command creates it after the first audit completes. The first audit is always a full audit.
 - The file should be committed to version control so that all team members share the same audit baseline.