ai-fob 1.2.0 → 1.3.0

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
@@ -113,7 +113,7 @@ Used during resume detection to verify step outputs are genuine and complete (no
 You (the main agent) handle this step directly.
 
 1. **Validate inputs**: Parse ARGUMENTS_RAW into HL_PLAN_PATH (first arg) and PHASE_NUMBER (second arg). If either is missing, error with: `Usage: /build-phase-V2 [path to HL plan] [phase number]`. Verify HL_PLAN_PATH exists and is a `.md` file. Read its YAML frontmatter and verify PHASE_NUMBER is an integer within the range of the `phases:` count. If out of range, error with: `Phase {N} is out of range. This plan has {count} phases (1-{count}).`
-2. **Derive variables**: Extract SPEC_DIR (parent directory of HL_PLAN_PATH), SPEC_DIR_BASENAME (basename of SPEC_DIR), TASK_NAME (from frontmatter `task:` field), PHASE_NAME (from `### Phase {N}: {Name}` header in the plan body), PHASE_NAME_KEBAB (kebab-case of PHASE_NAME), PHASE_DIR (`{SPEC_DIR}/phase{N}_{PHASE_NAME_KEBAB}/`).
+2. **Derive variables**: Extract SPEC_DIR (parent directory of HL_PLAN_PATH), SPEC_DIR_BASENAME (basename of SPEC_DIR), TASK_NAME (from frontmatter `task:` field), PHASE_NAME (from `### Phase {N}: {Name}` header in the plan body), PHASE_NAME_KEBAB (kebab-case of PHASE_NAME), PHASE_DIR (`{SPEC_DIR}/phase{N}_{PHASE_NAME_KEBAB}/`), REFERENCE_DOCUMENTS (from frontmatter `reference-documents:` field -- a list of file paths, or empty list if the field is absent).
 
 3. **Resume detection**: Determine if this phase was previously started and can be resumed.
 
@@ -230,6 +230,7 @@ You (the main agent) handle this step directly.
    Success Criteria: {count} defined
    Prior Phase Reports: {count read} | N/A (Phase 1)
    Skills Detected: {list or "None"}
+   Reference Documents: {count from REFERENCE_DOCUMENTS, or "None"}
    Resume Status: {Fresh run | Resuming from Step {RESUME_FROM} - {step name}}
    Pre-phase SHA: {PRE_PHASE_SHA | N/A (git unavailable)}
    ```
@@ -273,6 +274,12 @@ Run MARK_STEP_START(1).
    ## Detailed Specifications
    {Section 8 from HL plan, if present. If not present, omit this entire section.}
 
+   ## Reference Documents
+   {If REFERENCE_DOCUMENTS is non-empty, list each path. If empty, omit this entire section.}
+   The following documents were provided by the user as detailed reference material for this task. Read each document IN FULL using the Read tool before proceeding with your task. These contain detailed specifications, schemas, and implementation context that the plan must follow.
+   {For each path in REFERENCE_DOCUMENTS:}
+   - {path}
+
    ## Prior Phase Context
    {PRIOR_PHASE_CONTEXT if N > 1, otherwise "N/A -- this is Phase 1"}
    {If N > 1: "IMPORTANT: Explore the actual codebase state, not the HL plan's assumptions. Prior phases may have deviated from the plan."}
@@ -369,6 +376,12 @@ After research is complete, spawn the architect agent to create the implementati
    {Section 8 from HL plan, if present. If not present, omit this entire section.}
    {If present: "IMPORTANT: These are user-provided specifications. The implementation plan MUST conform to these specifications exactly. Do not simplify, generalize, or omit any detail from these specifications."}
 
+   ## Reference Documents
+   {If REFERENCE_DOCUMENTS is non-empty, list each path. If empty, omit this entire section.}
+   The following documents were provided by the user as detailed reference material for this task. Read each document IN FULL using the Read tool before proceeding with your task. These contain detailed specifications, schemas, and implementation context that the implementation plan MUST conform to.
+   {For each path in REFERENCE_DOCUMENTS:}
+   - {path}
+
    ## Prior Phase Context
    {PRIOR_PHASE_CONTEXT if N > 1, otherwise "N/A -- this is Phase 1"}
    {If N > 1: "IMPORTANT: Base your plan on the ACTUAL state described in prior phase reports, not the HL plan's original assumptions. Prior phases may have deviated from the plan."}
@@ -569,6 +582,11 @@ Read the plan at: {PHASE_DIR}/plan_V1.md
 ### Detailed Specifications
 {Section 8 from HL plan, if present. If not present: "None provided."}
 
+### Reference Documents
+{If REFERENCE_DOCUMENTS is non-empty, list each path. If empty: "None provided."}
+{For each path in REFERENCE_DOCUMENTS:}
+- {path}
+
 ### Prior Phase Context
 {PRIOR_PHASE_CONTEXT if N > 1, otherwise "N/A -- this is Phase 1"}
 
@@ -646,6 +664,12 @@ Success Criteria:
 {Section 8 from HL plan, if present. If not present, omit this entire section.}
 {If present: "IMPORTANT: These are user-provided specifications. The implementation plan MUST conform to these specifications exactly. Do not simplify, generalize, or omit any detail from these specifications."}
 
+## Reference Documents
+{If REFERENCE_DOCUMENTS is non-empty, list each path. If empty, omit this entire section.}
+The following documents were provided by the user as detailed reference material for this task. Read each document IN FULL using the Read tool before proceeding with your task. These contain detailed specifications, schemas, and implementation context that the implementation plan MUST conform to.
+{For each path in REFERENCE_DOCUMENTS:}
+- {path}
+
 ## Prior Phase Context
 {PRIOR_PHASE_CONTEXT if N > 1, otherwise "N/A -- this is Phase 1"}
 {If N > 1: "IMPORTANT: Base your plan on the ACTUAL state described in prior phase reports, not the HL plan's original assumptions. Prior phases may have deviated from the plan."}

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)
@@ -31,9 +31,14 @@ If the file exists AND its frontmatter contains `type: feature-document`:
   - Set FEATURE_DOC_CONTENT = the full content of the file
   - Extract from frontmatter: FEATURE_NAME (from `feature` field), SOURCE_REPO (from `source-repo` field), ANALYSIS_DEPTH (from `analysis-depth` field), DOC_DATE (from `date` field)
   - Set TASK_DESCRIPTION = "Reimplement: {FEATURE_NAME}" (derived from the document)
+  - Set REFERENCE_DOCUMENTS = [FEATURE_DOC_PATH]
 
 If the file does NOT exist, OR the file exists but its frontmatter does NOT contain `type: feature-document`:
   - Set IS_RE_ENGINEERING = false
+  - If the file DOES exist (but is not a feature document):
+    - Set REFERENCE_DOCUMENTS = [TASK_DESCRIPTION] (store the file path)
+  - If the file does NOT exist:
+    - Set REFERENCE_DOCUMENTS = [] (empty list)
   - Leave TASK_DESCRIPTION as-is (the user's original input)
   - Proceed with the existing workflow unchanged
 
@@ -104,6 +109,7 @@ The user provided a feature document from a reverse-engineering analysis. Use it
    - Should the scope be narrower or broader than the original feature?
    - Are there integration points in this codebase that affect the approach?
    - Are there detailed specifications (database schemas, API requirements, business rules, data structures) that the plan must incorporate? Capture any provided specifications verbatim.
+   - **Reference document collection**: Throughout this conversation, if the user mentions or provides paths to additional documents (brainstorm docs, design docs, specification docs, or any other reference files), attempt to read each path using the Read tool. If the file exists, append its path to REFERENCE_DOCUMENTS. Confirm to the user: "Added {path} to reference documents." At the end of Phase 1, present the full REFERENCE_DOCUMENTS list to the user for confirmation.
 
 8. Summarize the complete understanding (task description, category, user stories, anti-stories, phase breakdown with success criteria, and detailed specifications if any) and get explicit user confirmation.
 
@@ -120,6 +126,7 @@ The user provided a feature document from a reverse-engineering analysis. Use it
    - What success looks like
    - Any constraints (timeline, tech stack, performance)
    - **Detailed specifications**: If the user provides detailed technical requirements (database schemas, API specifications, business rules, data structures, validation rules, or other concrete specifications), capture them verbatim. These are REQUIREMENTS, not implementation details -- they must be preserved through the entire planning process and appear in the final plan.
+   - **Reference document collection**: Throughout this conversation, if the user mentions or provides paths to additional documents (brainstorm docs, design docs, specification docs, or any other reference files), attempt to read each path using the Read tool. If the file exists, append its path to REFERENCE_DOCUMENTS. Confirm to the user: "Added {path} to reference documents." At the end of Phase 1, present the full REFERENCE_DOCUMENTS list to the user for confirmation.
 5. Collaboratively define **user stories** at the feature level -- the positive outcomes users should experience.
    - Format: "As a [role], I can [action], so that [benefit]"
    - Each story should describe a concrete, testable outcome from the user's perspective
@@ -337,12 +344,18 @@ Once the plan passes validation, save it using FOB-state-context patterns:
      date: {current date}
      plan-type: phased
      phases: {count}
+     reference-documents:
+       - {path1}
+       - {path2}
      ---
      ```
-     If IS_RE_ENGINEERING is true, add this field to the frontmatter (after `phases`):
+     The `reference-documents` field lists all paths from REFERENCE_DOCUMENTS. If REFERENCE_DOCUMENTS is empty, omit the `reference-documents` field entirely.
+
+     If IS_RE_ENGINEERING is true, ALSO add this field to the frontmatter (after `reference-documents`):
      ```
      source-feature-doc: {FEATURE_DOC_PATH}
      ```
+     This preserves backward compatibility. The feature doc path appears in BOTH `reference-documents` and `source-feature-doc`.
    - Followed by the eight-section plan content
    - If IS_RE_ENGINEERING is true, add a note at the end of the "Task Overview" section (section 1 of the plan):
      "This plan is based on a reverse-engineered feature document: `{FEATURE_DOC_PATH}` (source repo: {SOURCE_REPO}, analysis depth: {ANALYSIS_DEPTH})."

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
 ---