@allthingsclaude/blueprints 0.4.6 → 0.4.8

package/README.md

@@ -140,7 +140,7 @@ Control which models power your agents:
 | `/email` | Create on-brand HTML email templates (newsletters, announcements, transactional) |
 | `/pitch` | Create an on-brand HTML presentation deck with speaker notes |
 | `/og` | Auto-generate Open Graph images for all pages in your project |
-| `/imagine` | Generate images using Nano Banana 2 (Gemini/fal.ai) |
+| `/imagine` | Generate images using Nano Banana 2 (Gemini/fal.ai) or GPT Image 2 (fal.ai), or both side-by-side |
 | `/storyboard` | Extract UI interaction specs from video mockups |
 | `/showcase` | Design an award-winning landing page with animations and micro-interactions |
 | `/diagram` | Generate Mermaid diagrams from your codebase |
@@ -442,7 +442,7 @@ Agents are specialized workers launched by commands. Each agent is assigned a mo
 | `finalize` | `/finalize` | Session wrap-up and commits |
 | `handoff` | `/handoff` | Context documentation |
 | `i18n` | `/i18n` | Internationalization auditing and setup |
-| `imagine` | `/imagine` | Image generation via Nano Banana 2 |
+| `imagine` | `/imagine` | Image generation via Nano Banana 2 or GPT Image 2 |
 | `implement` | `/implement` | Autonomous plan execution |
 | `migrate` | `/migrate` | Dependency upgrades and migrations |
 | `og` | `/og` | Open Graph image generation for all pages |

package/content/agents/imagine.md

@@ -1,6 +1,6 @@
 ---
 name: imagine
-description: Generate images via Nano Banana 2 API
+description: Generate images via Nano Banana 2 or GPT Image 2
 tools: Bash
 model: {{MODEL}}
 author: "@markoradak"
@@ -16,8 +16,10 @@ You generate images by running a single Bash command. Nothing else.
 - Do NOT search the web or use the Write tool
 - If the command fails, report the error and stop immediately
 - ONLY use these exact API endpoints:
-  - fal generate: `https://fal.run/fal-ai/nano-banana-2`
-  - fal edit: `https://fal.run/fal-ai/nano-banana-2/edit`
+  - fal nano generate: `https://fal.run/fal-ai/nano-banana-2`
+  - fal nano edit: `https://fal.run/fal-ai/nano-banana-2/edit`
+  - fal gpt generate: `https://fal.run/openai/gpt-image-2`
+  - fal gpt edit: `https://fal.run/openai/gpt-image-2/edit`
   - gemini: `https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent`
 
 ## CRITICAL: Shell escaping
@@ -30,6 +32,7 @@ You generate images by running a single Bash command. Nothing else.
 
 Extract from the prompt you received:
 - `prompt` — the enhanced image prompt
+- `model` — `nano-banana-2`, `gpt-image-2`, or `both`
 - `api` — "gemini" or "fal"
 - `mode` — "generate" or "edit"
 - `name` — snake_case name for the output file
@@ -37,9 +40,38 @@ Extract from the prompt you received:
 - `resolution` — "1K", "2K", or "4K"
 - `reference_images` — file paths (only if mode is "edit")
 
-Output file: `generated/imagine_{name}.png`
+## Template selection
 
-## fal + generate
+| model            | mode     | use template                |
+|------------------|----------|-----------------------------|
+| nano-banana-2    | generate | `gemini + generate` if api=gemini, else `fal nano + generate` |
+| nano-banana-2    | edit     | `gemini + edit` if api=gemini, else `fal nano + edit`         |
+| gpt-image-2      | generate | `fal gpt + generate`        |
+| gpt-image-2      | edit     | `fal gpt + edit`            |
+| both             | generate | `both + generate` (parallel fal nano + fal gpt) |
+| both             | edit     | `both + edit` (parallel fal nano + fal gpt)     |
+
+## Output file(s)
+
+- `model=nano-banana-2` or `gpt-image-2` → `generated/imagine_{name}.png`
+- `model=both` → `generated/imagine_{name}_nano.png` AND `generated/imagine_{name}_gpt.png`
+
+## aspect_ratio → image_size preset (gpt-image-2 only)
+
+gpt-image-2 doesn't take `aspect_ratio`/`resolution`. Map to fal preset name:
+
+| aspect_ratio | image_size preset  |
+|--------------|--------------------|
+| `1:1`        | `square_hd`        |
+| `16:9`       | `landscape_16_9`   |
+| `9:16`       | `portrait_16_9`    |
+| `4:3`        | `landscape_4_3`    |
+| `3:4`        | `portrait_4_3`     |
+| anything else| `landscape_4_3`    |
+
+Always pass `quality: "high"` for gpt-image-2.
+
+## fal nano + generate
 
 Copy this template exactly, substituting PROMPT, NAME, ASPECT, RESOLUTION:
 
@@ -51,7 +83,7 @@ PROMPTEOF
 node -e 'var fs=require("fs");fs.writeFileSync("/tmp/imagine_payload.json",JSON.stringify({prompt:fs.readFileSync("/tmp/imagine_prompt.txt","utf-8").trim(),aspect_ratio:"ASPECT",resolution:"RESOLUTION"}))' && curl -s "https://fal.run/fal-ai/nano-banana-2" -H "Authorization: Key $FAL_KEY" -H "Content-Type: application/json" -d @/tmp/imagine_payload.json -o /tmp/imagine_resp.json && IMG=$(node -p 'JSON.parse(require("fs").readFileSync("/tmp/imagine_resp.json","utf-8")).images[0].url') && curl -s "$IMG" -o generated/imagine_NAME.png && rm -f /tmp/imagine_resp.json /tmp/imagine_payload.json /tmp/imagine_prompt.txt
 ```
 
-## fal + edit
+## fal nano + edit
 
 Copy this template exactly, substituting PROMPT, NAME, ASPECT, RESOLUTION, PATH1/PATH2:
 
@@ -87,8 +119,62 @@ PROMPTEOF
 node -e 'var fs=require("fs"),prompt=fs.readFileSync("/tmp/imagine_prompt.txt","utf-8").trim(),imgs=["PATH1","PATH2"],parts=imgs.map(function(p){return {inline_data:{mime_type:"image/"+p.split(".").pop(),data:fs.readFileSync(p).toString("base64")}}});parts.push({text:prompt});fs.writeFileSync("/tmp/imagine_payload.json",JSON.stringify({contents:[{parts:parts}],generationConfig:{responseModalities:["IMAGE"],imageConfig:{aspectRatio:"ASPECT",imageSize:"RESOLUTION"}}}))' && curl -s "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent" -H "Content-Type: application/json" -H "x-goog-api-key: $GEMINI_API_KEY" -d @/tmp/imagine_payload.json -o /tmp/imagine_resp.json && node -e 'var fs=require("fs"),r=JSON.parse(fs.readFileSync("/tmp/imagine_resp.json","utf-8")),c=r.candidates,p=c&&c[0]&&c[0].content&&c[0].content.parts,i=p&&p.find(function(x){return x.inlineData||x.inline_data});if(!i){var e=r.error;console.error(e&&e.message||"No image");process.exit(1)}var d=i.inlineData||i.inline_data;fs.writeFileSync("generated/imagine_NAME.png",Buffer.from(d.data,"base64"))' && rm -f /tmp/imagine_resp.json /tmp/imagine_payload.json /tmp/imagine_prompt.txt
 ```
 
+## fal gpt + generate
+
+Copy this template exactly, substituting PROMPT, NAME, IMAGE_SIZE (mapped from aspect_ratio per the table above):
+
+```
+mkdir -p generated
+cat << 'PROMPTEOF' > /tmp/imagine_prompt.txt
+PROMPT
+PROMPTEOF
+node -e 'var fs=require("fs");fs.writeFileSync("/tmp/imagine_payload.json",JSON.stringify({prompt:fs.readFileSync("/tmp/imagine_prompt.txt","utf-8").trim(),image_size:"IMAGE_SIZE",quality:"high"}))' && curl -s "https://fal.run/openai/gpt-image-2" -H "Authorization: Key $FAL_KEY" -H "Content-Type: application/json" -d @/tmp/imagine_payload.json -o /tmp/imagine_resp.json && IMG=$(node -p 'JSON.parse(require("fs").readFileSync("/tmp/imagine_resp.json","utf-8")).images[0].url') && curl -s "$IMG" -o generated/imagine_NAME.png && rm -f /tmp/imagine_resp.json /tmp/imagine_payload.json /tmp/imagine_prompt.txt
+```
+
+## fal gpt + edit
+
+Copy this template exactly, substituting PROMPT, NAME, IMAGE_SIZE, PATH1/PATH2:
+
+```
+mkdir -p generated
+cat << 'PROMPTEOF' > /tmp/imagine_prompt.txt
+PROMPT
+PROMPTEOF
+node -e 'var fs=require("fs"),prompt=fs.readFileSync("/tmp/imagine_prompt.txt","utf-8").trim(),imgs=["PATH1","PATH2"],urls=imgs.map(function(p){return "data:image/"+p.split(".").pop()+";base64,"+fs.readFileSync(p).toString("base64")});fs.writeFileSync("/tmp/imagine_payload.json",JSON.stringify({prompt:prompt,image_urls:urls,image_size:"IMAGE_SIZE",quality:"high"}))' && curl -s "https://fal.run/openai/gpt-image-2/edit" -H "Authorization: Key $FAL_KEY" -H "Content-Type: application/json" -d @/tmp/imagine_payload.json -o /tmp/imagine_resp.json && IMG=$(node -p 'JSON.parse(require("fs").readFileSync("/tmp/imagine_resp.json","utf-8")).images[0].url') && curl -s "$IMG" -o generated/imagine_NAME.png && rm -f /tmp/imagine_resp.json /tmp/imagine_payload.json /tmp/imagine_prompt.txt
+```
+
+## both + generate
+
+Runs fal nano-banana-2 and fal gpt-image-2 in parallel within a single Bash call. Substitute PROMPT, NAME, ASPECT, RESOLUTION, IMAGE_SIZE:
+
+```
+mkdir -p generated
+cat << 'PROMPTEOF' > /tmp/imagine_prompt.txt
+PROMPT
+PROMPTEOF
+node -e 'var fs=require("fs"),p=fs.readFileSync("/tmp/imagine_prompt.txt","utf-8").trim();fs.writeFileSync("/tmp/imagine_nano_payload.json",JSON.stringify({prompt:p,aspect_ratio:"ASPECT",resolution:"RESOLUTION"}));fs.writeFileSync("/tmp/imagine_gpt_payload.json",JSON.stringify({prompt:p,image_size:"IMAGE_SIZE",quality:"high"}))' && (curl -s "https://fal.run/fal-ai/nano-banana-2" -H "Authorization: Key $FAL_KEY" -H "Content-Type: application/json" -d @/tmp/imagine_nano_payload.json -o /tmp/imagine_nano_resp.json & curl -s "https://fal.run/openai/gpt-image-2" -H "Authorization: Key $FAL_KEY" -H "Content-Type: application/json" -d @/tmp/imagine_gpt_payload.json -o /tmp/imagine_gpt_resp.json & wait) && NANO=$(node -p 'JSON.parse(require("fs").readFileSync("/tmp/imagine_nano_resp.json","utf-8")).images[0].url') && GPT=$(node -p 'JSON.parse(require("fs").readFileSync("/tmp/imagine_gpt_resp.json","utf-8")).images[0].url') && (curl -s "$NANO" -o generated/imagine_NAME_nano.png & curl -s "$GPT" -o generated/imagine_NAME_gpt.png & wait) && rm -f /tmp/imagine_nano_resp.json /tmp/imagine_gpt_resp.json /tmp/imagine_nano_payload.json /tmp/imagine_gpt_payload.json /tmp/imagine_prompt.txt
+```
+
+## both + edit
+
+Runs fal nano-banana-2/edit and fal gpt-image-2/edit in parallel. Substitute PROMPT, NAME, ASPECT, RESOLUTION, IMAGE_SIZE, PATH1/PATH2:
+
+```
+mkdir -p generated
+cat << 'PROMPTEOF' > /tmp/imagine_prompt.txt
+PROMPT
+PROMPTEOF
+node -e 'var fs=require("fs"),prompt=fs.readFileSync("/tmp/imagine_prompt.txt","utf-8").trim(),imgs=["PATH1","PATH2"],urls=imgs.map(function(p){return "data:image/"+p.split(".").pop()+";base64,"+fs.readFileSync(p).toString("base64")});fs.writeFileSync("/tmp/imagine_nano_payload.json",JSON.stringify({prompt:prompt,aspect_ratio:"ASPECT",resolution:"RESOLUTION",image_urls:urls}));fs.writeFileSync("/tmp/imagine_gpt_payload.json",JSON.stringify({prompt:prompt,image_urls:urls,image_size:"IMAGE_SIZE",quality:"high"}))' && (curl -s "https://fal.run/fal-ai/nano-banana-2/edit" -H "Authorization: Key $FAL_KEY" -H "Content-Type: application/json" -d @/tmp/imagine_nano_payload.json -o /tmp/imagine_nano_resp.json & curl -s "https://fal.run/openai/gpt-image-2/edit" -H "Authorization: Key $FAL_KEY" -H "Content-Type: application/json" -d @/tmp/imagine_gpt_payload.json -o /tmp/imagine_gpt_resp.json & wait) && NANO=$(node -p 'JSON.parse(require("fs").readFileSync("/tmp/imagine_nano_resp.json","utf-8")).images[0].url') && GPT=$(node -p 'JSON.parse(require("fs").readFileSync("/tmp/imagine_gpt_resp.json","utf-8")).images[0].url') && (curl -s "$NANO" -o generated/imagine_NAME_nano.png & curl -s "$GPT" -o generated/imagine_NAME_gpt.png & wait) && rm -f /tmp/imagine_nano_resp.json /tmp/imagine_gpt_resp.json /tmp/imagine_nano_payload.json /tmp/imagine_gpt_payload.json /tmp/imagine_prompt.txt
+```
+
 ## After the command completes
 
-Report the output path: `generated/imagine_{name}.png`
+Report the output path(s):
+- single model → `generated/imagine_{name}.png`
+- both → `generated/imagine_{name}_nano.png` and `generated/imagine_{name}_gpt.png`
 
 If the command failed, report the error. Do NOT retry.
+
+### Known caveat
+
+`gpt-image-2/edit` accepts `image_urls` per its schema, but the official examples only show HTTPS URLs. Data URIs may or may not be accepted — if you see an error like "invalid url" or "unable to fetch image" coming from the gpt-image-2 edit endpoint, surface it verbatim and stop. Do not attempt to upload reference images to a host as a workaround.

package/content/commands/autopilot.md

@@ -12,10 +12,15 @@ Full autonomous development loop. I'll take it from idea to committed code on a
 
 **Working Directory**: !`pwd`
 
-**Branch**: !`git branch --show-current 2>/dev/null || echo "Not a git repository"`
+**Is Git Repo**: !`git rev-parse --is-inside-work-tree 2>/dev/null || echo "no"`
+
+**Branch**: !`git branch --show-current 2>/dev/null || echo "(not a repo — will scan children)"`
 
 **Git Status**:
-!`git status --short 2>/dev/null || echo "Not a git repository"`
+!`git status --short 2>/dev/null || echo "(not a repo)"`
+
+**Child Git Repos** (for multi-repo mode):
+!`find . -mindepth 2 -maxdepth 2 -name .git -type d 2>/dev/null`
 
 **Active Plan**:
 !`cat {{STATE_FILE}} 2>/dev/null || echo "No active plan"`
@@ -24,7 +29,7 @@ Full autonomous development loop. I'll take it from idea to committed code on a
 !`ls -1 {{PLANS_DIR}}/PLAN_*.md 2>/dev/null || echo "No plans found"`
 
 **Project Detection**:
-!`ls package.json tsconfig.json Cargo.toml go.mod pyproject.toml requirements.txt 2>/dev/null || echo "No recognized project files"`
+!`ls package.json tsconfig.json Cargo.toml go.mod pyproject.toml requirements.txt 2>/dev/null || echo "(no root-level project files — multi-repo likely)"`
 
 ---
 
@@ -40,12 +45,13 @@ You are now in **AUTOPILOT MODE** — a full development loop that orchestrates
 
 ### Step 0: Parse Arguments
 
-Parse `$ARGUMENTS` for:
+Parse `$ARGUMENTS` for (in order):
 - **`--full`** flag: If present, run the entire loop without stopping for confirmation — commit automatically, skip approval prompts, maximize autonomy. Remove this flag from the remaining arguments before further processing.
-- **Plan name**: If the first remaining word matches an existing plan in `{{PLANS_DIR}}/PLAN_{NN}_{NAME}.md`, treat it as a plan name to execute.
+- **`--repos a,b,c`** flag: If present, overrides auto-detection for multi-repo mode. Value is a comma-separated list of child directory names that should be treated as "affected" regardless of what the plan references. Remove this flag and its value from the remaining arguments. Store as `REPOS_OVERRIDE`.
+- **Plan name**: If the first remaining word matches an existing plan in `{{PLANS_DIR}}/PLAN_{NN}_{NAME}.md` (case-insensitive, matched by the `{NAME}` portion), treat it as a plan name to execute.
 - **Feature description**: Otherwise, treat remaining arguments as a feature description for brainstorming.
 
-Store the `--full` preference — you'll check it at every commit checkpoint and decision point.
+Store the `--full` and `REPOS_OVERRIDE` preferences — you'll check them at commit checkpoints and in Step 3a respectively.
 
 ---
 
@@ -55,7 +61,14 @@ Follow this decision tree **in order**:
 
 #### 1a. Check for Active Plan in STATE.md
 
-Read `{{STATE_FILE}}`. If it contains an active plan (status is `In Progress` or `Paused`):
+Look for `{{STATE_FILE}}` in this search order (first match wins):
+1. `./{{STATE_FILE}}` — cwd
+2. `../{{STATE_FILE}}` — parent directory (useful when user accidentally ran from inside a child repo in a multi-repo setup)
+
+If found in the parent, emit a notice: "Found {{TASKS_DIR}}/ in parent directory — treating parent as the working root. Suggest running `/autopilot` from `{parent_abspath}` in the future."
+
+Then, if STATE.md contains an active plan (status is `In Progress` or `Paused`):
+- If the resolved STATE.md is at `../`, **change working directory to the parent** before continuing. All subsequent steps (discovery, branching, commits) must operate relative to the parent.
 - Load the plan file referenced in STATE.md
 - Check which phase we're on and what tasks remain
 - **If there are uncompleted tasks** → skip to **Step 3** (branch) then **Step 4** (execute)
@@ -134,26 +147,112 @@ Use the Task tool to launch the plan agent (`subagent_type="plan"`) with the fea
 
 Wait for the plan agent to complete, then load and display a brief summary of the plan.
 
-**COMMIT CHECKPOINT**: After plan is created, commit it:
-- Stage the plan file and STATE.md
-- Use the Task tool to launch the commit agent (`subagent_type="commit"`) with context: "docs: add implementation plan for {NAME}"
+**COMMIT CHECKPOINT (conditional)**: After plan is created, commit it **only if cwd is a git repo**:
+- Check: `git rev-parse --is-inside-work-tree 2>/dev/null`
+- If cwd IS a git repo (single-repo or meta-repo case):
+  - Stage the plan file and STATE.md
+  - Use the Task tool to launch the commit agent (`subagent_type="commit"`) with context: "docs: add implementation plan for {NAME}"
+- If cwd is NOT a git repo (parent-with-child-repos case):
+  - **Skip the commit** — the plan and STATE.md stay as uncommitted coordination artifacts at the parent level.
+  - Report: "Plan created at parent level (not a git repo) — left uncommitted as coordination artifact. To version it, init a meta-repo at the parent or commit in any workflow you choose."
 
 ---
 
-### Step 3: Create Feature Branch
+### Step 3: Detect Repositories & Create Feature Branch(es)
+
+Before starting implementation, detect the repository topology and create feature branches.
+
+#### 3a. Discover Repos & Determine Mode
+
+Always perform both discoveries below before deciding mode. Mode is chosen based on **what the plan references**, not purely on whether cwd is a git repo. This correctly handles three distinct layouts: plain single-repo, parent-is-not-a-repo-but-children-are, and parent-is-a-meta-repo-with-child-repos.
+
+**Discovery 1 — is cwd itself a git repo?**
+```bash
+git rev-parse --is-inside-work-tree 2>/dev/null
+```
+Store as `CWD_IS_REPO` (true/false).
+
+**Discovery 2 — are there child git repos?**
+```bash
+find . -mindepth 2 -maxdepth 2 -name .git -type d 2>/dev/null
+```
+Store the list as `CHILD_REPOS`. (Avoid `for` / `while` loops in inline shell — some harnesses reject control-flow statements.)
+
+**Discovery 3 — which repos does the plan reference?**
+If there's an active plan file (`{{PLANS_DIR}}/PLAN_{NN}_{NAME}.md`), for each entry in `CHILD_REPOS`, grep the plan for its directory name:
+```bash
+grep -c "{child_repo_name}" {{PLANS_DIR}}/PLAN_{NN}_{NAME}.md
+```
+Any child with **> 0 mentions** goes into `AFFECTED_CHILDREN`.
+
+**Mode decision** (evaluate in this order, first match wins):
+
+| Condition | Mode | `AFFECTED_REPOS` | Notes |
+|---|---|---|---|
+| User passed `--repos a,b,...` | multi | `{a, b, ...}` | Explicit override wins over all auto-detection |
+| `AFFECTED_CHILDREN` is non-empty | multi | `AFFECTED_CHILDREN` | Applies even if cwd is itself a git repo (meta-repo case). The parent repo, if any, is NOT branched — it stays where it is. |
+| `CWD_IS_REPO` is true | single | `[.]` | No child repos mentioned in plan → plain single-repo |
+| Otherwise | fail | — | "No git repo found here, and no child directories with `.git/` are referenced by the plan. Either cd into a repo, initialize one, or verify the plan references the correct repo directories." |
+
+**Ambiguity warning**: If `CHILD_REPOS` is non-empty but `AFFECTED_CHILDREN` is empty AND `CWD_IS_REPO` is true (falling through to single-repo mode), this might indicate a plan authoring mistake. Emit a warning before proceeding:
+
+> "Detected child git repos {list} but the plan does not reference any of them by directory name. Proceeding with single-repo mode (branching in cwd). If you intended multi-repo, either (a) update the plan's file paths to include the repo prefix (e.g., `{child_name}/src/...`), or (b) re-run with `--repos {child_name}` to force multi-repo mode."
+
+Prompt the user to confirm before continuing (in `--full` mode, auto-continue with the warning still logged).
+
+**Important — meta-repo case**: If cwd is a git repo AND there are affected children, we enter **multi-repo mode**. Branches are created only in the affected children. The parent (meta) repo is left alone — no branch, no commits, no state mutations. STATE.md changes at the parent level remain uncommitted coordination artifacts. If the user later wants to version those in the meta-repo, they can commit them manually via `/commit`.
+
+Report the decision:
+- Single-repo: "Branching in this repo."
+- Multi-repo: "Plan touches {N} child repo(s): {list}. Will branch in each. Parent repo (if any) left untouched."
+
+#### 3b. Pre-flight: Check for Dirty Working State
+
+Before branching, guard against clobbering uncommitted work in any target repo.
+
+For each repo in `AFFECTED_REPOS`:
+1. `cd {repo}` (skip for single-repo mode where this is cwd)
+2. Run: `git status --short`
+3. If non-empty → mark this repo as "dirty" and collect the output.
+4. `cd -`
+
+If any repo is dirty:
+- Report to the user: list each dirty repo and its `git status --short` output.
+- Ask: "Uncommitted changes found in {N} repo(s). How should I proceed?
+  - **stash** — I'll stash the changes in each dirty repo before branching (`git stash push -u -m 'autopilot pre-branch'`). You can restore with `git stash pop` later.
+  - **abort** — stop autopilot so you can handle the changes manually.
+  - **continue** — proceed anyway; the uncommitted changes will carry onto the new branch (only safe if you want them there)."
+- In `--full` mode, default to **abort** (never silently discard or carry unintended work).
+- Wait for user decision before proceeding.
+
+If all repos are clean (or user chose stash/continue), proceed to 3c.
+
+#### 3c. Create Branches
 
-Before starting implementation, create a feature branch:
+Determine the branch name:
+- Convert plan name to lowercase kebab-case
+- Prefix with `feat/` (e.g., plan "USER_AUTH" → branch `feat/user-auth`)
 
-1. Determine the branch name from the plan name:
-   - Convert plan name to lowercase kebab-case
-   - Prefix with `feat/` (e.g., plan "USER_AUTH" → branch `feat/user-auth`)
-2. Check if the branch already exists:
-   - If yes and we're resuming → switch to it: `git checkout feat/{name}`
-   - If yes and NOT resuming → switch to it (it may have prior work)
-   - If no → create it: `git checkout -b feat/{name}`
-3. Confirm the branch: `git branch --show-current`
+**Single-repo mode**: run branching in cwd.
+**Multi-repo mode**: run branching in each affected repo.
 
-Report: "Working on branch: `feat/{name}`"
+For each target repo, in order:
+1. `cd {repo}` (or stay at cwd for single-repo)
+2. Check current branch: `git branch --show-current`
+3. Check if `feat/{name}` exists:
+   - Exists + we're resuming → switch to it: `git checkout feat/{name}`
+   - Exists + not resuming → switch to it (prior work)
+   - Does not exist → create it: `git checkout -b feat/{name}`
+4. Confirm the branch.
+5. `cd -` (return to parent)
+
+**STATE UPDATE**: Add a `**Repos**:` line to STATE.md header listing the affected repos and the branch name:
+```markdown
+**Repos**: cli-shopnosis-shopper-app, cli-shopnosis-shopper-server
+**Branch**: feat/{name}
+```
+
+Report: "Working on branch `feat/{name}` in {N} repo(s): {list}"
 
 ---
 
@@ -181,10 +280,10 @@ Count the `- [ ]` uncompleted tasks in the current phase.
 Use the Task tool to launch the showcase agent (`subagent_type="showcase"`) with the plan context and any reference files from `{{TASKS_DIR}}/references/`.
 
 **For `/implement` mode:**
-Use the Task tool to launch the implement agent (`subagent_type="implement"`) with the plan name and instruction to work on the current phase only (e.g., "Execute Phase 1 only, then stop").
+Use the Task tool to launch the implement agent (`subagent_type="implement"`) with the plan name and instruction to work on the current phase only (e.g., "Execute Phase 1 only, then stop"). **Multi-repo mode**: include in the prompt the list of affected repos and their paths so the agent writes files into the correct sub-directories (file paths in the plan should already be prefixed with the repo name).
 
 **For `/parallelize` mode:**
-Use the Task tool to launch the parallelize orchestrator (`subagent_type="parallelize"`) with the plan name and instruction to work on the current phase only.
+Use the Task tool to launch the parallelize orchestrator (`subagent_type="parallelize"`) with the plan name and instruction to work on the current phase only. **Multi-repo mode**: include the list of affected repos in the prompt.
 
 Wait for the agent to complete. Review its summary.
 
@@ -194,11 +293,24 @@ Present the blockers to the user and ask how to proceed. Do NOT continue until b
 #### 4c. Commit the Phase
 
 **COMMIT CHECKPOINT**: After each phase completes:
+
+**Single-repo mode**:
 - Use the Task tool to launch the commit agent (`subagent_type="commit"`) with context describing what was accomplished in this phase
 - The commit agent will determine the appropriate prefix (`feat:`, `fix:`, `refactor:`, `chore:`, etc.) based on the nature of the changes
 - The commit message should reference the plan and phase (e.g., "feat: implement user authentication (PLAN_AUTH Phase 1)")
 
-**STATE UPDATE**: Read and update `{{STATE_FILE}}`:
+**Multi-repo mode**:
+- Before the commit loop, capture the parent directory: `PARENT_DIR=$(pwd)`.
+- For each repo in `AFFECTED_REPOS`:
+  1. `cd "$PARENT_DIR/{repo}"` (use the absolute path — never rely on `cd -` chains)
+  2. Check `git status --short` — if empty, skip this repo for this phase (no changes here).
+  3. If there are changes, launch the commit agent (`subagent_type="commit"`) with context including (a) what was accomplished in this phase, and (b) which repo this is. The commit runs inside the repo's working directory.
+- After the loop, **unconditionally** return: `cd "$PARENT_DIR"`.
+- Confirm cwd is the parent before the STATE.md update below (run `pwd` to verify).
+- A single phase may produce commits in multiple repos; that's expected.
+- Record the resulting commit hashes per repo for the final report.
+
+**STATE UPDATE** (always from the parent dir — STATE.md lives at `$PARENT_DIR/{{STATE_FILE}}`): Read and update `{{STATE_FILE}}`:
 - Increment `**Phase**` to the next phase number
 - Keep `**Status**` as `🚧 In Progress`
 - Update `**Updated**` timestamp
@@ -216,7 +328,9 @@ After committing and updating STATE.md, check if there are more phases remaining
 
 ### Step 5: Validate & Fix
 
-After all phases are implemented and committed, run validation. Each step uses a subagent:
+After all phases are implemented and committed, run validation. Each step uses a subagent.
+
+**Multi-repo mode**: every validation step below runs **once per affected repo**, with `cd {repo}` before launching the agent. Aggregate results per repo into the final report. A failure in one repo does not short-circuit the others — validate all, then report aggregated findings and decide together.
 
 #### 5a. Audit
 
@@ -293,7 +407,9 @@ Review security report:
 - Update `**Updated**` timestamp
 - Update all task statuses in the task tables under `## Plans` to reflect final state
 
-After everything is done (or stopped), provide a final summary:
+After everything is done (or stopped), provide a final summary.
+
+**Single-repo mode**:
 
 ```markdown
 **Autopilot Complete**
@@ -305,7 +421,6 @@ After everything is done (or stopped), provide a final summary:
 **Commits Made**:
 - `{hash}` {commit message 1}
 - `{hash}` {commit message 2}
-- `{hash}` {commit message 3}
 
 **What Was Done**:
 - [Phase 1 summary]
@@ -322,6 +437,45 @@ After everything is done (or stopped), provide a final summary:
 - Or continue working: `/autopilot` (will resume from STATE.md)
 ```
 
+**Multi-repo mode**:
+
+```markdown
+**Autopilot Complete (multi-repo)**
+
+**Plan**: {NAME}
+**Branch**: `feat/{name}` (same across all affected repos)
+**Status**: {Complete / Partially Complete}
+
+**Per-repo results**:
+
+### {repo-name-1}
+- Branch: `feat/{name}`
+- Commits:
+  - `{hash}` {commit message}
+  - `{hash}` {commit message}
+- Next: `cd {repo-name-1} && gh pr create`
+
+### {repo-name-2}
+- Branch: `feat/{name}`
+- Commits:
+  - `{hash}` {commit message}
+- Next: `cd {repo-name-2} && gh pr create`
+
+**What Was Done**:
+- [Phase 1 summary]
+- [Phase 2 summary]
+
+**Validation Results**:
+- Audit: {result per repo}
+- Tests: {result per repo}
+- Security: {result per repo}
+
+**Next Steps**:
+- Review changes in each repo individually.
+- Open one PR per repo (they can reference each other's branch name).
+- Or resume: `/autopilot` will pick up from STATE.md.
+```
+
 ---
 
 ## Commit Checkpoint Rules
@@ -352,6 +506,19 @@ Autopilot commits **early and often** using the commit agent (`subagent_type="co
 - BUT always stop for: blockers and validation failures that can't be auto-fixed
 - Never force-push, delete branches, or make destructive changes without asking
 
+### Multi-Repo Mode
+- **Trigger**: multi-repo mode activates whenever the plan references child directories that are git repos — regardless of whether the parent (cwd) is itself a git repo. The parent is never branched in this mode.
+- Three scenarios it handles:
+  1. Parent is NOT a git repo + children are → multi-repo.
+  2. Parent IS a git repo (meta-repo) + children are + plan mentions them → multi-repo, meta-repo untouched.
+  3. Parent IS a git repo + no children mentioned in plan → single-repo (plain case).
+- The same branch name (`feat/{name}`) is created in every "affected" child repo.
+- Commits run per-repo: `cd {repo}`, check `git status`, launch commit agent, `cd -`.
+- Validation (audit / test / security / a11y) runs per-repo. Failures in one repo don't short-circuit others — validate all, report together.
+- STATE.md lives at the parent level and is NOT committed by autopilot; it's a coordination artifact. If the parent is itself a meta-repo and the user wants to version STATE.md/plan updates, they can do so manually via `/commit` in the parent — autopilot does not touch the parent.
+- The plan document should prefix file paths with the repo directory name (e.g., `cli-shopnosis-shopper-server/src/models/...`) so the implement/parallelize agents write into the right sub-directory, and so the grep-for-mentions step correctly detects affected repos.
+- If the user passes `--repos repoA,repoB`, override auto-detection with that explicit list.
+
 ### Compose Existing Agents
 - Use the existing subagent types: `bootstrap`, `plan`, `implement`, `parallelize`, `showcase`, `audit`, `test`, `secure`, `a11y`, `commit`, `update`
 - Do NOT try to do their jobs inline — delegate to specialists

package/content/commands/imagine.md

@@ -14,13 +14,23 @@ $ARGUMENTS
 
 ## Instructions
 
-1. If no API key is available, stop and tell the user to set `GEMINI_API_KEY` or `FAL_KEY`.
+1. **API key check.** If no API key is available, stop and tell the user to set `GEMINI_API_KEY` or `FAL_KEY`.
 
-2. Determine `api`: "gemini" if GEMINI_API_KEY is available, "fal" otherwise.
+2. **Determine `model`** — one of `nano-banana-2`, `gpt-image-2`, or `both`. Resolve in this order; first match wins:
+   1. **Explicit flag** in `$ARGUMENTS`: `--model=nano-banana-2`, `--model=gpt-image-2`, or `--model=both`. Strip the flag from the prompt.
+   2. **Prefix**: `nano:`, `gpt:`, or `both:` at the start. Strip it.
+   3. **Natural language mention**: phrases like "with gpt-image-2", "use gpt image", "using gpt", "with nano banana", "using nano", "with both models", "compare both", "render with both". Map to the right model and remove the directive cleanly from the prompt.
+   4. **Auto-heuristic** — only if none of the above matched. Bias conservatively toward `nano-banana-2` since gpt-image-2 is materially more expensive on fal:
+      - **Strong text-rendering signals** → `gpt-image-2`. Only triggers when the user clearly wants legible text rendered: quoted strings the prompt asks to render (`"..."`, `'...'` paired with verbs like "that says", "with the words", "reading", "labeled"), or explicit "render this text", "billboard that reads", "sign that says", "headline:", "caption:", "infographic with text". Soft typography hints alone ("logo", "poster", "book cover", "magazine cover") do **not** trigger gpt — those go to nano.
+      - **Otherwise** → `nano-banana-2` (default — covers people, scenes, products, soft typography, and ambiguous cases).
 
-3. Check if the user included any image file paths. If yes, mode is "edit". If no, mode is "generate".
+3. **Determine `api`** based on `model`:
+   - `gpt-image-2` or `both` → `fal` (requires `FAL_KEY`; if missing, stop and tell the user).
+   - `nano-banana-2` → `gemini` if `GEMINI_API_KEY` is available, else `fal`.
 
-4. Determine `aspect_ratio` and `resolution`:
+4. **Mode**: if the user included any image file paths, `mode` is `edit`. Otherwise `generate`.
+
+5. **Determine `aspect_ratio` and `resolution`** (used by nano-banana-2; mapped to `image_size` preset by the agent for gpt-image-2):
    - If the user explicitly requests a size or ratio (e.g., "16:9", "square", "4K"), use that.
    - If the user describes where the image will be used, infer the best fit:
      - Hero banner / website header → `16:9`, `2K`
@@ -34,17 +44,21 @@ $ARGUMENTS
    - Valid aspect ratios: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`
    - Valid resolutions: `1K`, `2K`, `4K`
 
-5. Enhance the user's description into a detailed prompt (~100 words max). Add lighting, composition, camera angle, style, mood — stay faithful to the original request.
+6. Enhance the user's description into a detailed prompt (~100 words max). Add lighting, composition, camera angle, style, mood — stay faithful to the original request. Do NOT strip out text the user wants rendered in the image (quoted strings, headlines, etc.) — preserve it verbatim.
 
-6. Derive a short snake_case name (e.g., `mountain_cabin`).
+7. Derive a short snake_case name (e.g., `mountain_cabin`).
 
-7. Launch the imagine agent via Task tool with `subagent_type="imagine"` passing:
+8. Launch the imagine agent via Task tool with `subagent_type="imagine"` passing:
    - `prompt`: the enhanced prompt text
-   - `api`: "gemini" or "fal"
-   - `mode`: "generate" or "edit"
+   - `model`: `nano-banana-2`, `gpt-image-2`, or `both`
+   - `api`: `gemini` or `fal`
+   - `mode`: `generate` or `edit`
    - `name`: the snake_case name
-   - `aspect_ratio`: e.g., "16:9"
-   - `resolution`: e.g., "2K"
+   - `aspect_ratio`: e.g., `16:9`
+   - `resolution`: e.g., `2K`
    - `reference_images`: list of absolute file paths (if edit mode)
 
-8. After the agent returns, use the Read tool to display `generated/imagine_{name}.png` inline. Show the path.
+9. After the agent returns, display the output(s) inline with the Read tool:
+   - `model=nano-banana-2` or `gpt-image-2` → `generated/imagine_{name}.png`
+   - `model=both` → `generated/imagine_{name}_nano.png` AND `generated/imagine_{name}_gpt.png`
+   Show the path(s).

package/content/commands/pitch.md

@@ -43,58 +43,73 @@ Parse the brief for: presentation type, audience, slide count, key points, and s
 
 ### If the brief is empty or vague:
 
-Conduct a focused discovery questionnaire. Ask questions **one at a time**, adapting based on previous answers. Don't dump all questions at once — this should feel like a conversation.
+Conduct a focused discovery using the **AskUserQuestion tool** for interactive selection. The user should be able to click/select options rather than typing numbers. Adapt follow-up questions based on previous answers.
 
 #### First, determine the repo context:
 
 Check the "Existing Brand Brief", "Project Identity", "Package Description", and "Product Features & Stats" sections above. If meaningful product information was detected (README with clear positioning, product features, stats, metrics, or an existing `design/brand-brief.md`), this is a **brand-rich repo** — the codebase contains enough to derive brand identity, product messaging, and content automatically.
 
-#### Always ask (every context):
-
-**Q1: What's the presentation for?**
-- Product launch
-- Investor pitch
-- Conference talk
-- Team update
-- Sales demo
-- Workshop
-- Custom (describe)
-
-**Q2: Who's the audience?**
-- Investors
-- Developers
-- Customers
-- Team / internal
-- Executives
-- Conference attendees
-- Custom (describe)
-
-**Q3: How many slides?** (default: 10-12)
-
-**Q4: Key points to cover?**
-- List specific topics, features, stats, or talking points
-- Or say "derive from codebase" to auto-extract from README, features, and product info
-
-#### Only ask in bare repos (no brand or product info detected):
-
-If no README positioning, brand brief, features, or product info was found, the agent has nothing to derive from — so you need to ask:
-
-**Q5: What's the brand/style direction?**
-- Minimal / editorial (whitespace, typography-driven)
-- Bold / high-contrast (oversized type, strong colors)
-- Dark / premium (dark backgrounds, glow effects, sleek)
-- Technical / developer (terminal aesthetics, monospace)
-- Corporate / clean (structured, professional)
-- Playful / colorful (gradients, rounded shapes, vibrant)
-
-**Q6: What content should the deck cover?**
-(Free text — outline the narrative arc, key arguments, data points, or story beats)
-
-#### In brand-rich repos, skip Q5-Q6:
+#### Round 1 — Core questions (single AskUserQuestion call, 3 questions):
+
+**Q1** (header: "Presentation type", multiSelect: false):
+Question: "What's the presentation for?"
+Options:
+- label: "Product launch" / description: "Announce a new product, feature, or version"
+- label: "Investor pitch" / description: "Fundraising deck — vision, traction, the ask"
+- label: "Conference talk" / description: "Keynote or session for an audience of peers"
+- label: "Sales demo" / description: "Walk a prospect through product value and pricing"
+
+**Q2** (header: "Audience", multiSelect: false):
+Question: "Who's the audience?"
+Options:
+- label: "Investors" / description: "VCs, angels, or strategic capital partners"
+- label: "Developers" / description: "Technical practitioners and engineering teams"
+- label: "Customers / prospects" / description: "Buyers, end users, or decision-makers"
+- label: "Team / internal" / description: "Colleagues, executives, or cross-functional peers"
+
+**Q3** (header: "Slide count", multiSelect: false):
+Question: "How many slides should the deck have?"
+Options:
+- label: "6-8 slides" / description: "Tight lightning-talk pacing"
+- label: "10-12 slides (Recommended)" / description: "Standard pitch / launch length"
+- label: "15-18 slides" / description: "Deeper narrative with room for demo and proof"
+- label: "20+ slides" / description: "Long-form workshop or detailed walkthrough"
+
+#### Round 2 — Content direction (single AskUserQuestion call, 1 question):
+
+**Q4** (header: "Key points", multiSelect: false):
+Question: "What should the deck cover?"
+Options:
+- label: "Derive from codebase" / description: "Auto-extract from README, features, and product info"
+- label: "Narrative arc" / description: "Problem → solution → proof → CTA"
+- label: "Feature-led" / description: "Core capabilities with demos and use cases"
+- label: "Metrics-led" / description: "Traction, growth, and data-driven highlights"
+
+#### Round 3 — Brand & style (only for bare repos, single AskUserQuestion call):
+
+Only ask these if **no brand files, README positioning, or product info were detected**. In brand-rich repos, skip to confirmation.
+
+**Q1** (header: "Style", multiSelect: false):
+Question: "What visual style fits your brand?"
+Options:
+- label: "Minimal / editorial" / description: "Whitespace, typography-driven, structural grids"
+- label: "Bold / dark premium" / description: "High-contrast, oversized type, dark backgrounds, glow"
+- label: "Technical / developer" / description: "Terminal mockups, monospace, code aesthetics"
+- label: "Corporate / clean" / description: "Structured, professional, restrained palette"
+
+**Q2** (header: "Tone", multiSelect: false):
+Question: "What's the tone of voice for the deck?"
+Options:
+- label: "Confident / bold" / description: "Declarative, punchy, no hedging"
+- label: "Warm / conversational" / description: "Approachable, human, inviting"
+- label: "Authoritative / precise" / description: "Data-driven, measured, expert"
+- label: "Playful / energetic" / description: "Witty, spirited, brand-forward"
+
+#### In brand-rich repos, skip Round 3:
 
 The agent will automatically analyze the codebase for brand identity, product features, stats, and messaging. Visual style and content direction will be derived from the existing design system and product information. The user can still override any of these when confirming the brief.
 
-After gathering answers, **summarize the complete brief and ask for confirmation** before launching the agent. Include what will be auto-derived from the codebase so the user can correct anything.
+After gathering all answers, **summarize the complete brief and ask for confirmation** before launching the agent. Include what will be auto-derived from the codebase so the user can correct anything.
 
 ### Launching the Agent
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allthingsclaude/blueprints",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "description": "Claude Code commands and agents for enhanced AI-assisted development workflows",
   "type": "module",
   "main": "dist/index.js",