@allthingsclaude/blueprints 0.4.5 → 0.4.7

package/content/commands/a11y.md

@@ -1,6 +1,6 @@
 ---
 description: Audit your frontend for accessibility issues
-argument-hint: [optional: file path, component name, or WCAG level like "AA" or "AAA"]
+argument-hint: optional: file path, component name, or WCAG level like "AA" or "AAA"
 author: "@markoradak"
 ---
 
@@ -15,13 +15,14 @@ I'll scan your frontend code for accessibility issues and provide actionable fix
 **Working Directory**: !`pwd`
 
 **Project**:
-!`cat package.json 2>/dev/null | head -10`
+!`head -10 package.json 2>/dev/null`
 
 **Frontend Files**:
-!`find src/ app/ pages/ components/ -name "*.tsx" -o -name "*.jsx" -o -name "*.vue" -o -name "*.svelte" -o -name "*.html" 2>/dev/null | head -25 || echo "No frontend files found in common locations"`
+!`find src/ app/ pages/ components/ -name "*.tsx" -o -name "*.jsx" -o -name "*.vue" -o -name "*.svelte" -o -name "*.html" 2>/dev/null || echo "No frontend files found in common locations"`
 
 **Existing A11y Setup**:
-!`ls .axerc* .pa11yci* .pa11yrc* a11y.config* 2>/dev/null; cat package.json 2>/dev/null | grep -i "a11y\|axe\|pa11y\|accessibility\|jest-axe\|@axe-core\|eslint-plugin-jsx-a11y" || echo "No a11y tooling detected"`
+!`ls .axerc* .pa11yci* .pa11yrc* a11y.config* 2>/dev/null || echo "No a11y config files"`
+!`grep -i "a11y\|axe\|pa11y\|accessibility\|jest-axe\|@axe-core\|eslint-plugin-jsx-a11y" package.json 2>/dev/null || echo "No a11y tooling detected"`
 
 ---
 

package/content/commands/audit.md

@@ -1,6 +1,6 @@
 ---
 description: Review code changes before committing
-argument-hint: [optional: specific files or focus area]
+argument-hint: optional: specific files or focus area
 author: "@markoradak"
 ---
 

package/content/commands/autopilot.md

@@ -1,6 +1,6 @@
 ---
 description: Full autonomous development loop - from idea to committed code
-argument-hint: [--full] [feature description or plan name]
+argument-hint: --full feature description or plan name
 author: "@markoradak"
 ---
 
@@ -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/brainstorm.md

@@ -1,6 +1,6 @@
 ---
 description: Enter brainstorming mode to explore ideas without implementation
-argument-hint: [topic or context]
+argument-hint: topic or context
 author: "@markoradak"
 ---
 
@@ -21,7 +21,7 @@ Before brainstorming, quickly assess the current project:
 !`ls package.json tsconfig.json Cargo.toml go.mod pyproject.toml requirements.txt composer.json Gemfile pom.xml build.gradle mix.exs 2>/dev/null || echo "No recognized project files"`
 
 **Source Files**:
-!`find . -maxdepth 3 -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" -o -name "*.py" -o -name "*.rs" -o -name "*.go" -o -name "*.java" -o -name "*.rb" -o -name "*.ex" -o -name "*.php" \) 2>/dev/null | head -10 | wc -l`
+!`find . -maxdepth 3 -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" -o -name "*.py" -o -name "*.rs" -o -name "*.go" -o -name "*.java" -o -name "*.rb" -o -name "*.ex" -o -name "*.php" \) 2>/dev/null`
 
 **Is this an empty/new project?** If there are fewer than 5 source files and no meaningful project configuration, this is likely a **new project**. In that case:
 - Mention to the user that this looks like a new project and brainstorming is a great starting point

package/content/commands/brand.md

@@ -1,6 +1,6 @@
 ---
 description: Create or document a comprehensive brand identity system
-argument-hint: [brand description] or leave empty for guided questionnaire
+argument-hint: brand description or leave empty for guided questionnaire
 author: "@markoradak"
 ---
 
@@ -13,29 +13,29 @@ I'll create or document a comprehensive brand identity system — colors, typogr
 **Working Directory**: !`pwd`
 
 **Existing Brand Assets**:
-!`ls tailwind.config.* src/app/globals.css src/styles/*.css styles/*.css public/images/*.svg public/*.svg 2>/dev/null | head -20 || echo "No brand files detected"`
+!`ls tailwind.config.* src/app/globals.css src/styles/*.css styles/*.css public/images/*.svg public/*.svg 2>/dev/null || echo "No brand files detected"`
 
 **Design Directory**:
-!`ls design/ 2>/dev/null && echo == existing brand docs == && ls design/brand-brief.md design/brand-guide.md design/tokens.css 2>/dev/null || echo "No existing design directory"`
+!`ls design/ 2>/dev/null || echo "No existing design directory"`
 
 **Previous Brand Brief**:
-!`cat design/brand-brief.md 2>/dev/null | head -40 || echo "No brand brief yet"`
+!`head -40 design/brand-brief.md 2>/dev/null || echo "No brand brief yet"`
 
 **CSS / Tailwind Config**:
-!`cat tailwind.config.* 2>/dev/null | head -40 || echo "No Tailwind config"`
+!`head -40 tailwind.config.* 2>/dev/null || echo "No Tailwind config"`
 
 **Font Imports**:
-!`grep -rE "googleapis.com/css|next/font|@import.*font|@font-face|fontFamily" tailwind.config.* src/app/layout.tsx src/app/globals.css src/styles/*.css 2>/dev/null | head -15 || echo "No font declarations found"`
+!`grep -rE "googleapis.com/css|next/font|@import.*font|@font-face|fontFamily" tailwind.config.* src/app/layout.tsx src/app/globals.css src/styles/*.css 2>/dev/null || echo "No font declarations found"`
 
 **Color Definitions**:
-!`grep -rE "#[0-9A-Fa-f]{3,8}\b|--color-|rgba?\(|hsl" src/app/globals.css tailwind.config.* styles/*.css src/styles/*.css 2>/dev/null | head -30 || echo "No color definitions found"`
+!`grep -rE "#[0-9A-Fa-f]{3,8}\b|--color-|rgba?\(|hsl" src/app/globals.css tailwind.config.* styles/*.css src/styles/*.css 2>/dev/null || echo "No color definitions found"`
 
 **Logo Files**:
-!`ls public/images/logo* public/logo* public/images/icon* public/*.svg src/assets/*.svg 2>/dev/null | head -10 || echo "No logo files found"`
+!`ls public/images/logo* public/logo* public/images/icon* public/*.svg src/assets/*.svg 2>/dev/null || echo "No logo files found"`
 
 **README / Package Info**:
-!`cat README.md 2>/dev/null | head -20 || echo "No README"`
-!`cat package.json 2>/dev/null | head -10 || echo "No package.json"`
+!`head -20 README.md 2>/dev/null || echo "No README"`
+!`head -10 package.json 2>/dev/null || echo "No package.json"`
 
 ---
 

package/content/commands/challenge.md

@@ -1,6 +1,6 @@
 ---
 description: Challenge Mode - Critical Thinking Assistant
-argument-hint: [optional: approach or decision to challenge]
+argument-hint: optional: approach or decision to challenge
 author: "@markoradak"
 ---
 

package/content/commands/changelog.md

@@ -1,6 +1,6 @@
 ---
 description: Generate a changelog from git history
-argument-hint: [optional: version tag, date range, or "unreleased"]
+argument-hint: optional: version tag, date range, or "unreleased"
 author: "@markoradak"
 ---
 
@@ -17,7 +17,7 @@ I'll analyze your git history and generate a well-structured changelog.
 **Branch**: !`git branch --show-current 2>/dev/null || echo "Not a git repository"`
 
 **Latest Tags**:
-!`git tag --sort=-version:refname 2>/dev/null | head -5 || echo "No tags found"`
+!`git tag --sort=-version:refname -n5 2>/dev/null || echo "No tags found"`
 
 **Recent Commits**:
 !`git log --oneline -10 2>/dev/null`

package/content/commands/cleanup.md

@@ -1,6 +1,6 @@
 ---
 description: Find and remove dead code, unused imports, and technical debt
-argument-hint: [optional: "imports" | "dead-code" | "types" | "todos" | focus area]
+argument-hint: optional: "imports" | "dead-code" | "types" | "todos" | focus area
 author: "@markoradak"
 ---
 
@@ -17,7 +17,7 @@ I'll scan your codebase for dead code, unused imports, and technical debt.
 **Branch**: !`git branch --show-current 2>/dev/null || echo "Not a git repository"`
 
 **Files to Analyze**:
-!`find . -maxdepth 5 -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" 2>/dev/null | grep -v node_modules | wc -l` source files
+!`find . -maxdepth 5 -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" -not -path "*/node_modules/*" 2>/dev/null` source files
 
 ---
 

package/content/commands/commit.md

@@ -1,6 +1,6 @@
 ---
 description: Create a well-crafted git commit from your current changes
-argument-hint: [optional: commit message hint or scope]
+argument-hint: optional: commit message hint or scope
 author: "@markoradak"
 ---
 

package/content/commands/copy.md

@@ -1,6 +1,6 @@
 ---
 description: Write on-brand marketing copy for social media, ads, emails, and landing pages
-argument-hint: [copy brief] or leave empty for guided questionnaire
+argument-hint: copy brief or leave empty for guided questionnaire
 author: "@markoradak"
 ---
 
@@ -13,22 +13,22 @@ I'll write on-brand marketing copy — social captions, ad copy, email subject l
 **Working Directory**: !`pwd`
 
 **Existing Brand Brief**:
-!`cat design/brand-brief.md 2>/dev/null | head -40 || echo "No brand brief yet"`
+!`head -40 design/brand-brief.md 2>/dev/null || echo "No brand brief yet"`
 
 **Project Identity**:
-!`cat README.md 2>/dev/null | head -30 || echo "No README found"`
+!`head -30 README.md 2>/dev/null || echo "No README found"`
 
 **Package Description**:
-!`cat package.json 2>/dev/null | head -10 || echo "No package.json found"`
+!`head -10 package.json 2>/dev/null || echo "No package.json found"`
 
 **Existing Copy & Messaging**:
-!`grep -rh 'content=\|<title>\|<meta name=.description' src/app/layout.tsx src/app/page.tsx index.html 2>/dev/null | head -10 || echo "No meta/title tags detected"`
+!`grep -rh 'content=\|<title>\|<meta name=.description' src/app/layout.tsx src/app/page.tsx index.html 2>/dev/null || echo "No meta/title tags detected"`
 
 **Landing Page Copy**:
-!`grep -rh "<h1\|<h2\|<p class.*hero\|<p class.*subtitle\|<p class.*tagline" src/app/page.tsx src/components/Hero.tsx src/components/Landing.tsx index.html 2>/dev/null | head -15 || echo "No landing page copy detected"`
+!`grep -rh "<h1\|<h2\|<p class.*hero\|<p class.*subtitle\|<p class.*tagline" src/app/page.tsx src/components/Hero.tsx src/components/Landing.tsx index.html 2>/dev/null || echo "No landing page copy detected"`
 
 **Design Directory**:
-!`ls design/ 2>/dev/null && echo == existing campaigns == && ls -d design/*/ 2>/dev/null || echo "No existing design directory"`
+!`ls design/ 2>/dev/null || echo "No existing design directory"`
 
 ---
 

package/content/commands/critique.md

@@ -1,6 +1,6 @@
 ---
 description: Critique Mode
-argument-hint: [optional: code, design, or approach to critique]
+argument-hint: optional: code, design, or approach to critique
 author: "@markoradak"
 ---
 

package/content/commands/debug.md

@@ -1,6 +1,6 @@
 ---
 description: Investigate and diagnose issues with systematic analysis
-argument-hint: [error message, file path, or behavior description]
+argument-hint: error message, file path, or behavior description
 author: "@markoradak"
 ---
 

package/content/commands/design.md

@@ -1,6 +1,6 @@
 ---
 description: Create on-brand design and marketing assets (social media, banners, ads)
-argument-hint: [design brief] or leave empty for guided questionnaire
+argument-hint: design brief or leave empty for guided questionnaire
 author: "@markoradak"
 ---
 
@@ -13,13 +13,13 @@ I'll create on-brand design and marketing assets — social media banners, ad cr
 **Working Directory**: !`pwd`
 
 **Existing Brand Assets**:
-!`ls tailwind.config.* src/app/globals.css src/styles/*.css public/images/*.svg 2>/dev/null | head -15 || echo "No brand files detected"`
+!`ls tailwind.config.* src/app/globals.css src/styles/*.css public/images/*.svg 2>/dev/null || echo "No brand files detected"`
 
 **Design Directory**:
-!`ls design/ 2>/dev/null && echo == existing campaigns == && ls -d design/*/ 2>/dev/null || echo "No existing design directory"`
+!`ls design/ 2>/dev/null || echo "No existing design directory"`
 
 **Previous Brand Brief**:
-!`cat design/brand-brief.md 2>/dev/null | head -30 || echo "No brand brief yet"`
+!`head -30 design/brand-brief.md 2>/dev/null || echo "No brand brief yet"`
 
 **Image Generation APIs** (agent will check GEMINI_API_KEY and FAL_KEY availability at runtime):
 

package/content/commands/diagram.md

@@ -1,6 +1,6 @@
 ---
 description: Generate Mermaid diagrams from your codebase
-argument-hint: [architecture | dependency | sequence | er | dataflow | component name or feature]
+argument-hint: architecture | dependency | sequence | er | dataflow | component name or feature
 author: "@markoradak"
 ---
 
@@ -15,13 +15,13 @@ I'll analyze your codebase and generate Mermaid diagrams that visualize architec
 **Working Directory**: !`pwd`
 
 **Project**:
-!`cat package.json 2>/dev/null | head -10 || cat Cargo.toml 2>/dev/null | head -10 || cat pyproject.toml 2>/dev/null | head -10 || cat go.mod 2>/dev/null | head -5`
+!`head -10 package.json 2>/dev/null`
 
 **Structure**:
-!`ls -la src/ 2>/dev/null | head -20 || ls -la lib/ 2>/dev/null | head -20 || ls -la app/ 2>/dev/null | head -20 || ls -la`
+!`ls -la src/ 2>/dev/null`
 
 **Existing Docs**:
-!`ls docs/ 2>/dev/null | head -10; ls *.md 2>/dev/null | head -5`
+!`ls docs/ 2>/dev/null`
 
 ---
 

package/content/commands/docs.md

@@ -1,6 +1,6 @@
 ---
 description: Generate or update project documentation
-argument-hint: [readme | api | architecture | file path or component to document]
+argument-hint: readme | api | architecture | file path or component to document
 author: "@markoradak"
 ---
 
@@ -15,10 +15,11 @@ I'll analyze your codebase and generate or update documentation.
 **Working Directory**: !`pwd`
 
 **Project**:
-!`ls README* 2>/dev/null; ls docs/ 2>/dev/null | head -10; echo ===; cat package.json 2>/dev/null | head -5`
+!`ls README* 2>/dev/null || echo "No README found"`
+!`ls docs/ 2>/dev/null || echo "No docs/ directory"`
 
 **Existing Docs**:
-!`find . -maxdepth 3 -name "*.md" -not -path "*/node_modules/*" -not -path "*/.git/*" 2>/dev/null | head -15`
+!`find . -maxdepth 3 -name "*.md" -not -path "*/node_modules/*" -not -path "*/.git/*" 2>/dev/null`
 
 ---
 

package/content/commands/dry.md

@@ -1,6 +1,6 @@
 ---
 description: Eliminate DRY violations without changing behavior
-argument-hint: [optional: file/folder path, "functions" | "components" | "hooks" | "types" | "constants"]
+argument-hint: optional: file/folder path, "functions" | "components" | "hooks" | "types" | "constants"
 author: "@markoradak"
 ---
 
@@ -20,7 +20,7 @@ I'll find and eliminate DRY violations across your codebase while guaranteeing i
 !`git status --short`
 
 **Files to Analyze**:
-!`find . -maxdepth 5 -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" 2>/dev/null | grep -v node_modules | wc -l` source files
+!`find . -maxdepth 5 -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" -not -path "*/node_modules/*" 2>/dev/null` source files
 
 ---
 

package/content/commands/email.md

@@ -1,6 +1,6 @@
 ---
 description: Create on-brand HTML email templates (newsletters, announcements, transactional)
-argument-hint: [email brief] or leave empty for guided questionnaire
+argument-hint: email brief or leave empty for guided questionnaire
 author: "@markoradak"
 ---
 
@@ -13,19 +13,19 @@ I'll create on-brand, email-client-compatible HTML templates — newsletters, pr
 **Working Directory**: !`pwd`
 
 **Existing Brand Assets**:
-!`ls tailwind.config.* src/app/globals.css src/styles/*.css public/images/*.svg 2>/dev/null | head -15 || echo "No brand files detected"`
+!`ls tailwind.config.* src/app/globals.css src/styles/*.css public/images/*.svg 2>/dev/null || echo "No brand files detected"`
 
 **Design Directory**:
-!`ls design/ 2>/dev/null && echo == existing campaigns == && ls -d design/*/ 2>/dev/null || echo "No existing design directory"`
+!`ls design/ 2>/dev/null || echo "No existing design directory"`
 
 **Previous Brand Brief**:
-!`cat design/brand-brief.md 2>/dev/null | head -30 || echo "No brand brief yet"`
+!`head -30 design/brand-brief.md 2>/dev/null || echo "No brand brief yet"`
 
 **Existing Email Templates**:
-!`find . -maxdepth 4 -name "*.html" -path "*email*" -o -name "*.html" -path "*newsletter*" -o -name "*.html" -path "*template*" -path "*mail*" 2>/dev/null | head -10 || echo "No existing email templates found"`
+!`find . -maxdepth 4 -name "*.html" -path "*email*" -o -name "*.html" -path "*newsletter*" -o -name "*.html" -path "*template*" -path "*mail*" 2>/dev/null || echo "No existing email templates found"`
 
 **Mail-Related Dependencies**:
-!`grep -E "nodemailer|sendgrid|mailgun|postmark|resend|ses|mailchimp|mjml|react-email" package.json 2>/dev/null | head -10 || echo "No mail dependencies detected"`
+!`grep -E "nodemailer|sendgrid|mailgun|postmark|resend|ses|mailchimp|mjml|react-email" package.json 2>/dev/null || echo "No mail dependencies detected"`
 
 ---
 

package/content/commands/explain.md

@@ -1,6 +1,6 @@
 ---
 description: Generate detailed explanations of code, architecture, or features
-argument-hint: [file path, component name, feature, or concept to explain]
+argument-hint: file path, component name, feature, or concept to explain
 author: "@markoradak"
 ---
 
@@ -13,7 +13,7 @@ I'll provide a detailed, educational explanation of the code, architecture, or f
 **Working Directory**: !`pwd`
 
 **Project Structure**:
-!`ls -la src/ 2>/dev/null | head -15`
+!`ls -la src/ 2>/dev/null`
 
 ---
 

package/content/commands/finalize.md

@@ -1,6 +1,6 @@
 ---
 description: Finalize work session - update plans, commit changes with proper message
-argument-hint: [optional: commit message prefix or focus area]
+argument-hint: optional: commit message prefix or focus area
 author: "@markoradak"
 ---
 

package/content/commands/handoff.md

@@ -1,6 +1,6 @@
 ---
 description: Generate comprehensive handoff documentation for context switching
-argument-hint: [optional: focus area or notes]
+argument-hint: optional: focus area or notes
 author: "@markoradak"
 ---
 

package/content/commands/history.md

@@ -27,13 +27,13 @@ Investigating the history of: **$ARGUMENTS**
 !`git log --follow --diff-filter=A --format="%h %an (%ar): %s" -- "$ARGUMENTS" 2>/dev/null || echo "Unable to determine creation"`
 
 **Contributors**:
-!`git log --follow --format="%an" -- "$ARGUMENTS" 2>/dev/null | sort | uniq -c | sort -rn || echo "N/A"`
+!`git log --follow --format="%an" -- "$ARGUMENTS" 2>/dev/null || echo "N/A"`
 
 **Recent Activity (last 30 days)**:
 !`git log --since="30 days ago" --follow --format="%h %s (%ar)" -- "$ARGUMENTS" 2>/dev/null || echo "No recent changes"`
 
 **Change Frequency**:
-!`git log --follow --oneline -- "$ARGUMENTS" 2>/dev/null | wc -l`
+!`git log --follow --oneline -- "$ARGUMENTS" 2>/dev/null`
 
 ---
 

package/content/commands/i18n.md

@@ -1,6 +1,6 @@
 ---
 description: Audit and set up internationalization for your project
-argument-hint: [optional: audit | setup | extract | add-locale <locale> | file path or component]
+argument-hint: optional: audit | setup | extract | add-locale <locale> | file path or component
 author: "@markoradak"
 ---
 
@@ -15,15 +15,15 @@ I'll audit your project's internationalization readiness, extract hardcoded stri
 **Working Directory**: !`pwd`
 
 **Project**:
-!`cat package.json 2>/dev/null | head -15`
+!`head -15 package.json 2>/dev/null`
 
 **Existing i18n Setup**:
-!`cat package.json 2>/dev/null | grep -i "i18n\|intl\|locale\|next-intl\|react-intl\|react-i18next\|i18next\|vue-i18n\|@formatjs\|lingui\|messageformat\|rosetta\|typesafe-i18n\|paraglide" || echo "No i18n dependencies detected"`
+!`grep -i "i18n\|intl\|locale\|next-intl\|react-intl\|react-i18next\|i18next\|vue-i18n\|@formatjs\|lingui\|messageformat\|rosetta\|typesafe-i18n\|paraglide" package.json 2>/dev/null || echo "No i18n dependencies detected"`
 !`ls -d **/locales/ **/translations/ **/i18n/ **/lang/ **/messages/ src/i18n* src/locales* public/locales* 2>/dev/null || echo "No i18n directories found"`
 !`ls i18n.config* i18next.config* next-i18next.config* lingui.config* 2>/dev/null || echo "No i18n config files found"`
 
 **Frontend Files**:
-!`find src/ app/ pages/ components/ -name "*.tsx" -o -name "*.jsx" -o -name "*.vue" -o -name "*.svelte" 2>/dev/null | wc -l`
+!`find src/ app/ pages/ components/ -name "*.tsx" -o -name "*.jsx" -o -name "*.vue" -o -name "*.svelte" 2>/dev/null`
 
 ---
 

package/content/commands/migrate.md

@@ -1,6 +1,6 @@
 ---
 description: Upgrade dependencies or migrate between framework versions
-argument-hint: [package@version, "all", or migration description]
+argument-hint: package@version, "all", or migration description
 author: "@markoradak"
 ---
 
@@ -20,10 +20,10 @@ I'll help you upgrade dependencies or migrate between framework versions safely.
 !`git status --short`
 
 **Current Dependencies**:
-!`cat package.json 2>/dev/null | head -40`
+!`head -40 package.json 2>/dev/null`
 
 **Lock File**:
-!`ls pnpm-lock.yaml yarn.lock bun.lockb package-lock.json 2>/dev/null | head -1 || echo "No lock file found"`
+!`ls pnpm-lock.yaml yarn.lock bun.lockb package-lock.json 2>/dev/null || echo "No lock file found"`
 
 ---
 

package/content/commands/og.md

@@ -1,6 +1,6 @@
 ---
 description: Auto-generate Open Graph images for all pages in your project
-argument-hint: [specific page or route] or leave empty for all pages
+argument-hint: specific page or route or leave empty for all pages
 author: "@markoradak"
 ---
 
@@ -16,25 +16,25 @@ I'll generate on-brand Open Graph images for your pages — each a self-containe
 !`ls next.config.* nuxt.config.* astro.config.* remix.config.* svelte.config.* vite.config.* angular.json 2>/dev/null || echo "No framework config detected"`
 
 **App Router Pages** (Next.js):
-!`find src/app -name "page.tsx" -o -name "page.jsx" -o -name "page.ts" -o -name "page.js" 2>/dev/null | head -20 || echo "No App Router pages"`
+!`find src/app -name "page.tsx" -o -name "page.jsx" -o -name "page.ts" -o -name "page.js" 2>/dev/null || echo "No App Router pages"`
 
 **Pages Router** (Next.js/Nuxt):
-!`ls src/pages/*.tsx src/pages/**/*.tsx pages/*.tsx pages/**/*.tsx src/pages/*.vue pages/*.vue 2>/dev/null | head -20 || echo "No Pages Router files"`
+!`ls src/pages/*.tsx src/pages/**/*.tsx pages/*.tsx pages/**/*.tsx src/pages/*.vue pages/*.vue 2>/dev/null || echo "No Pages Router files"`
 
 **Astro Pages**:
-!`find src/pages -name "*.astro" -o -name "*.md" -o -name "*.mdx" 2>/dev/null | head -20 || echo "No Astro pages"`
+!`find src/pages -name "*.astro" -o -name "*.md" -o -name "*.mdx" 2>/dev/null || echo "No Astro pages"`
 
 **Static HTML**:
-!`find . -maxdepth 3 -name "*.html" ! -path "./node_modules/*" ! -path "./design/*" ! -path "./public/og/*" ! -path "./.next/*" ! -path "./dist/*" 2>/dev/null | head -20 || echo "No static HTML files"`
+!`find . -maxdepth 3 -name "*.html" ! -path "./node_modules/*" ! -path "./design/*" ! -path "./public/og/*" ! -path "./.next/*" ! -path "./dist/*" 2>/dev/null || echo "No static HTML files"`
 
 **Existing OG Images**:
-!`ls public/og/ design/og-* 2>/dev/null | head -10 || echo "No existing OG images"`
+!`ls public/og/ design/og-* 2>/dev/null || echo "No existing OG images"`
 
 **Brand Assets**:
-!`cat design/brand-brief.md 2>/dev/null | head -30 || echo "No brand brief yet"`
+!`head -30 design/brand-brief.md 2>/dev/null || echo "No brand brief yet"`
 
 **Metadata / SEO**:
-!`grep -rn "openGraph\|og:image\|og:title\|og:description\|meta.*property.*og:" src/ pages/ app/ 2>/dev/null | head -15 || echo "No existing OG meta tags found"`
+!`grep -rn "openGraph\|og:image\|og:title\|og:description\|meta.*property.*og:" src/ pages/ app/ 2>/dev/null || echo "No existing OG meta tags found"`
 
 ---
 

package/content/commands/onboard.md

@@ -1,6 +1,6 @@
 ---
 description: Generate a developer onboarding guide for this project
-argument-hint: [optional: focus area like "backend", "frontend", "api", or "contributing"]
+argument-hint: optional: focus area like "backend", "frontend", "api", or "contributing"
 author: "@markoradak"
 ---
 
@@ -15,19 +15,20 @@ I'll analyze your project and generate a comprehensive onboarding guide for new
 **Working Directory**: !`pwd`
 
 **Project**:
-!`cat package.json 2>/dev/null | head -15 || cat Cargo.toml 2>/dev/null | head -15 || cat pyproject.toml 2>/dev/null | head -15 || cat go.mod 2>/dev/null | head -5`
+!`head -15 package.json 2>/dev/null`
 
 **Structure**:
 !`ls -la`
 
 **Git Info**:
-!`git log --oneline -5 2>/dev/null; echo ===; git branch -a 2>/dev/null | head -10`
+!`git log --oneline -5 2>/dev/null`
+!`git branch -a 2>/dev/null`
 
 **Existing Docs**:
-!`ls README* CONTRIBUTING* CLAUDE.md docs/ 2>/dev/null | head -10`
+!`ls README* CONTRIBUTING* CLAUDE.md docs/ 2>/dev/null`
 
 **Dev Scripts**:
-!`cat package.json 2>/dev/null | grep -A 20 '"scripts"' | head -25`
+!`grep -A 20 '"scripts"' package.json 2>/dev/null`
 
 ---
 

package/content/commands/pickup.md

@@ -1,6 +1,6 @@
 ---
 description: Load handoff document and continue from previous session
-argument-hint: [optional: specific task or focus area]
+argument-hint: optional: specific task or focus area
 author: "@markoradak"
 ---
 

package/content/commands/pitch.md

@@ -1,6 +1,6 @@
 ---
 description: Create an on-brand HTML presentation deck with speaker notes
-argument-hint: [pitch topic/audience] or leave empty for guided questionnaire
+argument-hint: pitch topic/audience or leave empty for guided questionnaire
 author: "@markoradak"
 ---
 
@@ -13,19 +13,19 @@ I'll create an on-brand, self-contained HTML presentation deck with keyboard nav
 **Working Directory**: !`pwd`
 
 **Existing Brand Brief**:
-!`cat design/brand-brief.md 2>/dev/null | head -40 || echo "No brand brief yet"`
+!`head -40 design/brand-brief.md 2>/dev/null || echo "No brand brief yet"`
 
 **Project Identity**:
-!`cat README.md 2>/dev/null | head -30 || echo "No README found"`
+!`head -30 README.md 2>/dev/null || echo "No README found"`
 
 **Package Description**:
-!`cat package.json 2>/dev/null | head -10 || echo "No package.json found"`
+!`head -10 package.json 2>/dev/null || echo "No package.json found"`
 
 **Product Features & Stats**:
-!`grep -rh "<h2\|<h3\|<strong\|features\|pricing\|stats\|metric" src/app/page.tsx src/components/*.tsx README.md 2>/dev/null | head -20 || echo "No product features detected"`
+!`grep -rh "<h2\|<h3\|<strong\|features\|pricing\|stats\|metric" src/app/page.tsx src/components/*.tsx README.md 2>/dev/null || echo "No product features detected"`
 
 **Design Directory**:
-!`ls design/ 2>/dev/null && echo == existing campaigns == && ls -d design/*/ 2>/dev/null || echo "No existing design directory"`
+!`ls design/ 2>/dev/null || echo "No existing design directory"`
 
 ---
 
@@ -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/content/commands/refactor.md

@@ -1,6 +1,6 @@
 ---
 description: Safely rename, extract, inline, or move code with validation
-argument-hint: [operation] [target] (e.g., "rename:old:new", "extract:ComponentName", "move:src:dest")
+argument-hint: operation target (e.g., "rename:old:new", "extract:ComponentName", "move:src:dest")
 author: "@markoradak"
 ---
 

package/content/commands/release.md

@@ -1,6 +1,6 @@
 ---
 description: Create a release — version bump, changelog, tag, and publish
-argument-hint: [optional: major | minor | patch | version number | --dry-run]
+argument-hint: optional: major | minor | patch | version number | --dry-run
 author: "@markoradak"
 ---
 
@@ -20,16 +20,16 @@ I'll orchestrate a complete release for your project — detecting existing rele
 !`git status --short`
 
 **Current Version**:
-!`cat package.json 2>/dev/null | grep '"version"' | head -1 || cat Cargo.toml 2>/dev/null | grep '^version' | head -1 || cat pyproject.toml 2>/dev/null | grep '^version' | head -1 || echo "Could not detect version"`
+!`grep '"version"' package.json 2>/dev/null || grep '^version' Cargo.toml 2>/dev/null || grep '^version' pyproject.toml 2>/dev/null || echo "Could not detect version"`
 
 **Latest Tags**:
-!`git tag --sort=-version:refname 2>/dev/null | head -5 || echo "No tags found"`
+!`git tag --sort=-version:refname -n5 2>/dev/null || echo "No tags found"`
 
 **Commits Since Last Tag**:
-!`git log --oneline 2>/dev/null | head -15`
+!`git log --oneline 2>/dev/null`
 
 **Release Scripts Detected**:
-!`cat package.json 2>/dev/null | grep -E '"(release|version|bump|publish|prepublish|postpublish|preversion|postversion|prepublishOnly)"' || echo "None in package.json"`
+!`grep -E '"(release|version|bump|publish|prepublish|postpublish|preversion|postversion|prepublishOnly)"' package.json 2>/dev/null || echo "None in package.json"`
 !`ls .release-it.* .changeset/ .versionrc* lerna.json .releaserc* release.config.* 2>/dev/null || echo "No release tool configs found"`
 !`ls scripts/release* scripts/publish* scripts/version* Makefile 2>/dev/null || echo "No release scripts found"`
 

package/content/commands/research.md

@@ -1,6 +1,6 @@
 ---
 description: Activate a specialized research agent (codebase/web/docs) to investigate specific topics
-argument-hint: [topic or question to research]
+argument-hint: topic or question to research
 author: "@markoradak"
 ---
 

package/content/commands/secure.md

@@ -1,6 +1,6 @@
 ---
 description: Run a focused security scan on your codebase
-argument-hint: [optional: file/folder path, or focus area like "deps", "auth", "api"]
+argument-hint: optional: file/folder path, or focus area like "deps", "auth", "api"
 author: "@markoradak"
 ---
 
@@ -20,7 +20,7 @@ I'll perform a focused security audit of your codebase, checking for vulnerabili
 !`git status --short`
 
 **Dependencies**:
-!`cat package.json 2>/dev/null | grep -c '"dependencies\|"devDependencies"' || echo "No package.json"`
+!`grep -c '"dependencies\|"devDependencies"' package.json 2>/dev/null || echo "No package.json"`
 
 ---
 

package/content/commands/showcase.md

@@ -1,6 +1,6 @@
 ---
 description: Design an award-winning landing page with animations and micro-interactions
-argument-hint: [product/project name or description]
+argument-hint: product/project name or description
 author: "@markoradak"
 ---
 
@@ -16,10 +16,10 @@ I'll design and build a high-end landing page with polished animations, micro-in
 !`ls package.json tsconfig.json next.config.* vite.config.* astro.config.* tailwind.config.* 2>/dev/null || echo "No recognized project files"`
 
 **Existing Pages**:
-!`find . -maxdepth 4 -type f \( -name "page.tsx" -o -name "page.jsx" -o -name "index.tsx" -o -name "index.jsx" -o -name "index.html" \) -not -path "*/node_modules/*" 2>/dev/null | head -10`
+!`find . -maxdepth 4 -type f \( -name "page.tsx" -o -name "page.jsx" -o -name "index.tsx" -o -name "index.jsx" -o -name "index.html" \) -not -path "*/node_modules/*" 2>/dev/null`
 
 **Reference Files** (images/videos provided):
-!`ls {{TASKS_DIR}}/references/ 2>/dev/null | head -10 || echo "No references found"`
+!`ls {{TASKS_DIR}}/references/ 2>/dev/null || echo "No references found"`
 
 ---
 

package/content/commands/standup.md

@@ -1,6 +1,6 @@
 ---
 description: Generate a standup summary from recent git activity
-argument-hint: [optional: timeframe like "3 days" or "this week"]
+argument-hint: optional: timeframe like "3 days" or "this week"
 author: "@markoradak"
 ---
 
@@ -17,7 +17,7 @@ Generating a standup summary from recent activity.
 **Author**: !`git config user.name 2>/dev/null || echo "Unknown"`
 
 **Commits (last 48 hours)**:
-!`git log --since="48 hours ago" --format="%h %an: %s (%ar)" 2>/dev/null | head -20 || echo "No recent commits"`
+!`git log --since="48 hours ago" --format="%h %an: %s (%ar)" 2>/dev/null || echo "No recent commits"`
 
 **Uncommitted Changes**:
 !`git diff --stat 2>/dev/null || echo "None"`

package/content/commands/test.md

@@ -1,6 +1,6 @@
 ---
 description: Run tests with intelligent analysis and fix suggestions
-argument-hint: [optional: file pattern, test name, or "generate" for new tests]
+argument-hint: optional: file pattern, test name, or "generate" for new tests
 author: "@markoradak"
 ---
 

package/content/commands/todo.md

@@ -1,6 +1,6 @@
 ---
 description: Scan codebase for TODO/FIXME/HACK markers and present an organized summary
-argument-hint: [optional: directory, file, or keyword to filter]
+argument-hint: optional: directory, file, or keyword to filter
 author: "@markoradak"
 ---
 
@@ -19,13 +19,13 @@ Scanning the codebase for code markers and annotations.
 ## Marker Scan
 
 **High Priority (FIXME, HACK, XXX)**:
-!`git grep -rn -E '\b(FIXME|HACK|XXX)\b' -- ':!node_modules' ':!.git' 2>/dev/null || grep -rn -E '\b(FIXME|HACK|XXX)\b' --include='*' --exclude-dir=node_modules --exclude-dir=.git . 2>/dev/null || echo "No high-priority markers found"`
+!`git grep -rn -E '\b(FIXME|HACK|XXX)\b' -- ':!node_modules' ':!.git' 2>/dev/null || echo "No high-priority markers found"`
 
 **Standard (TODO, TASK, TEMP, DEPRECATED)**:
-!`git grep -rn -E '\b(TODO|TASK|TEMP|DEPRECATED)\b' -- ':!node_modules' ':!.git' 2>/dev/null || grep -rn -E '\b(TODO|TASK|TEMP|DEPRECATED)\b' --include='*' --exclude-dir=node_modules --exclude-dir=.git . 2>/dev/null || echo "No standard markers found"`
+!`git grep -rn -E '\b(TODO|TASK|TEMP|DEPRECATED)\b' -- ':!node_modules' ':!.git' 2>/dev/null || echo "No standard markers found"`
 
 **Informational (NOTE, WARN)**:
-!`git grep -rn -E '\b(NOTE|WARN)\b' -- ':!node_modules' ':!.git' 2>/dev/null || grep -rn -E '\b(NOTE|WARN)\b' --include='*' --exclude-dir=node_modules --exclude-dir=.git . 2>/dev/null || echo "No informational markers found"`
+!`git grep -rn -E '\b(NOTE|WARN)\b' -- ':!node_modules' ':!.git' 2>/dev/null || echo "No informational markers found"`
 
 ## User Filter
 

package/content/commands/update.md

@@ -1,6 +1,6 @@
 ---
 description: Update CLAUDE.md and STATE.md to reflect current project state
-argument-hint: [optional: section to focus on]
+argument-hint: optional: section to focus on
 author: "@markoradak"
 ---
 
@@ -13,13 +13,13 @@ I'll scan the project and update CLAUDE.md and STATE.md to reflect the current s
 **Working Directory**: !`pwd`
 
 **Existing CLAUDE.md**:
-!`cat CLAUDE.md 2>/dev/null | head -5 || echo "No CLAUDE.md found"`
+!`head -5 CLAUDE.md 2>/dev/null || echo "No CLAUDE.md found"`
 
 **Project Detection**:
 !`ls package.json tsconfig.json Cargo.toml go.mod pyproject.toml requirements.txt composer.json Gemfile pom.xml build.gradle mix.exs 2>/dev/null || echo "No recognized project files"`
 
 **Source Files**:
-!`find . -maxdepth 3 -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" -o -name "*.py" -o -name "*.rs" -o -name "*.go" -o -name "*.java" -o -name "*.rb" -o -name "*.ex" -o -name "*.php" \) -not -path "*/node_modules/*" -not -path "*/.git/*" 2>/dev/null | wc -l`
+!`find . -maxdepth 3 -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" -o -name "*.py" -o -name "*.rs" -o -name "*.go" -o -name "*.java" -o -name "*.rb" -o -name "*.ex" -o -name "*.php" \) -not -path "*/node_modules/*" -not -path "*/.git/*" 2>/dev/null`
 
 ---
 

package/content/commands/verify.md

@@ -1,6 +1,6 @@
 ---
 description: Verification Mode
-argument-hint: [optional: approach or task to verify]
+argument-hint: optional: approach or task to verify
 author: "@markoradak"
 ---
 

package/package.json

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