viepilot 2.15.0 → 2.23.0

package/workflows/autonomous.md

@@ -13,9 +13,34 @@ Pauses at control points for user decisions.
 
 - **`/vp-auto`** + this workflow is the **default lane** for **implementing** work that already has a **phase/task plan** (and doc-first **BUG-001**). **`/vp-request`** and **`/vp-evolve`** do **not** replace this step unless the user explicitly overrides — see **Implementation routing guard** in `workflows/request.md` and `workflows/evolve.md`.
 
+## Agent Delegation (ENH-057)
+
+This workflow delegates heavy/repetitive operations to sub-agents defined in `agents/`.
+Each agent is invoked via the pattern below rather than implemented inline.
+
+| Agent | When invoked | Operation |
+|-------|-------------|-----------|
+| tracker-agent | Task start, task complete, phase complete | TRACKER.md status updates |
+| changelog-agent | Post-phase last task (version bump) | CHANGELOG + package.json bump |
+| test-generator-agent | Last task of each phase (contract tests) | Test file generation + run |
+| doc-sync-agent | Bulk edits: ≥5 identical file types in Paths block | Multi-file .md updates |
+
+**Invoke-agent pattern** (Claude Code adapter):
+```
+Agent({
+  subagent_type: "general-purpose",
+  description: "{agent-name}: {operation}",
+  prompt: "Load agents/{agent-name}.md for full spec. Execute: {operation} with inputs: {inputs}"
+})
+```
+**Non-Claude Code adapters**: execute the equivalent operation inline in the same session.
+
+See `agents/` directory for full agent specifications.
 
 <process>
 
+> **AUQ preload — Claude Code adapter (ENH-059):** At session start, before any interactive prompt, call `ToolSearch` with `query: "select:AskUserQuestion"` to load the deferred schema. Required on Claude Code (terminal). Skip only if `ToolSearch` returns an error → use text fallback for that session.
+
 <step name="initialize">
 ## 1. Initialize
 
@@ -36,6 +61,26 @@ cat .viepilot/ROADMAP.md
 Read `~/.viepilot/config.json` → `COMMUNICATION_LANG` (default: `en`).
 Use `COMMUNICATION_LANG` for all banners, control-point messages, and user-facing output in this session.
 
+### Tag Prefix Resolution (ENH-050)
+Resolve the enriched git tag prefix once at session start. All task/phase tags use `${TAG_PREFIX}`.
+
+```bash
+PROJECT_PREFIX=$(node bin/vp-tools.cjs info --prefix 2>/dev/null \
+  || grep -i "^prefix:" .viepilot/PROJECT-META.md 2>/dev/null | awk '{print $2}' \
+  || basename "$(pwd)")
+BRANCH_SAFE=$(git rev-parse --abbrev-ref HEAD 2>/dev/null \
+  | sed 's/[^a-zA-Z0-9._-]/-/g' || echo "main")
+VERSION=$(node -e "try{console.log(require('./package.json').version)}catch(e){console.log('0.0.0')}" 2>/dev/null \
+  || grep '"version"' package.json 2>/dev/null | head -1 | sed 's/.*"\([0-9.]*\)".*/\1/' || echo "0.0.0")
+TAG_PREFIX="${PROJECT_PREFIX}-${BRANCH_SAFE}-${VERSION}"
+# Example: viepilot-main-2.17.0
+# Tags: ${TAG_PREFIX}-vp-p{phase}-t{task}
+#        ${TAG_PREFIX}-vp-p{phase}-t{task}-done
+#        ${TAG_PREFIX}-vp-p{phase}-complete
+```
+
+> Note: dots in version are valid in git tag names. Branch `/` → `-` via sed.
+
 Display startup banner:
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -195,7 +240,7 @@ Canonical order for every task: **Validate contract → Doc-first gate → Stack
 
 If any check fails:
 - Mark task `blocked` in `PHASE-STATE.md` and list what is missing under **Notes**
-- **Do not** create `{projectPrefix}-vp-p{phase}-t{task}`
+- **Do not** create `{TAG_PREFIX}-vp-p{phase}-t{task}` (where `TAG_PREFIX=${PROJECT_PREFIX}-${BRANCH_SAFE}-${VERSION}`)
 - **Do not** proceed to **Execute Task**
 
 #### Stack Preflight (token-efficient lookup)
@@ -213,9 +258,34 @@ If stack cache is missing:
 
 Only after **Validate Task Contract**, **Pre-execution documentation gate**, and **Stack Preflight** (or explicit waiver logged in the task file with reason):
 
-Create git tag: `{projectPrefix}-vp-p{phase}-t{task}`  
+Create git tag: `{TAG_PREFIX}-vp-p{phase}-t{task}` (enriched format: `${PROJECT_PREFIX}-${BRANCH_SAFE}-${VERSION}-vp-p{phase}-t{task}`)
+```bash
+git tag "${TAG_PREFIX}-vp-p${PHASE}-t${TASK}"
+```
 Ensure `PHASE-STATE.md` already shows current task `in_progress` (set during the gate if not already).
 
+#### Bulk-Edit Task Detection — doc-sync-agent (ENH-057)
+
+**Before executing**, scan the `## Paths` block of the task:
+
+```
+IF (Paths block contains ≥5 files of the same type, e.g., skills/*/SKILL.md)
+  OR (task description matches: "update all N files", "add row to all skills", "sync across N files")
+→ Invoke doc-sync-agent instead of N sequential edits:
+
+   Agent({ subagent_type: "general-purpose",
+     description: "doc-sync-agent: {change_mode} across {file_pattern}",
+     prompt: "Load agents/doc-sync-agent.md. Pattern: {glob}. Mode: {change_mode}. Anchor: {anchor}. Content: {content}."
+   })
+   Non-Claude Code: apply changes sequentially inline.
+
+   Example: Task 84.3 "Update all 17 SKILL.md — add Copilot adapter row"
+   → Pattern: skills/*/SKILL.md | Mode: insert-row | Anchor: "| Codex CLI |" | Content: "| GitHub Copilot | ✅ ..."
+   → 1 agent call replaces 17 sequential Edit calls.
+```
+
+If Paths block has < 5 files: proceed with sequential edits as normal.
+
 #### Execute Task
 1. Read task objective and acceptance criteria
 2. Read SYSTEM-RULES.md for coding standards
@@ -289,7 +359,7 @@ If any check fails:
 #### Handle Result
 
 **PASS:**
-- Create git tag: `{projectPrefix}-vp-p{phase}-t{task}-done`
+- Create git tag: `{TAG_PREFIX}-vp-p{phase}-t{task}-done` (e.g. `git tag "${TAG_PREFIX}-vp-p${PHASE}-t${TASK}-done"`)
 - Update PHASE-STATE.md immediately: task → done, append files changed by this task to Files Changed table (individual files, no glob patterns)
 - Update TRACKER.md immediately
 - Update HANDOFF.json immediately
@@ -312,12 +382,21 @@ After each PASS task and PASS sub-task (state-first, then continue):
 ```yaml
 update:
   - PHASE-STATE.md: task status, timestamp
-  - TRACKER.md: current state, progress
+  - TRACKER.md: current state, progress   ← via tracker-agent (ENH-057)
   - HANDOFF.json: latest position
   - ROADMAP.md: sync when phase status/progress changed
-  - CHANGELOG.md: if feature/fix completed
+  - CHANGELOG.md: if feature/fix completed  ← via changelog-agent at end of phase (ENH-057)
 ```
 
+**Tracker updates — invoke tracker-agent:**
+```
+Agent({ subagent_type: "general-purpose",
+  description: "tracker-agent: update task {phase}.{task} → {status}",
+  prompt: "Load agents/tracker-agent.md. Operation: update-task-status. Phase: {phase}. Task: {task}. Status: {status}."
+})
+```
+Non-Claude Code: update TRACKER.md inline as before.
+
 Rule:
 - Never defer state updates to end-of-phase only.
 - If interrupted, HANDOFF.json must still point to exact in-progress task/sub-task.
@@ -355,10 +434,22 @@ When all tasks in phase are done/skipped:
    | smarttrack-*/pom.xml (8 files) | 1.1 |   ← WRONG: glob pattern
    | smarttrack-*/src/** (7 files)  | 1.1 |   ← WRONG: summarized
    ```
-4. Create git tag: `{projectPrefix}-vp-p{phase}-complete`
-5. Check version bump needed:
-   - Features added → MINOR
-   - Fixes only → PATCH
+4. Create git tag: `{TAG_PREFIX}-vp-p{phase}-complete` (e.g. `git tag "${TAG_PREFIX}-vp-p${PHASE}-complete"`)
+5. Check version bump needed — apply `.viepilot/SYSTEM-RULES.md → Version Bump Rules`:
+   - Features added → MINOR; Fixes only → PATCH; Mixed → MINOR; Breaking → MAJOR
+
+   **Version bump — invoke changelog-agent (ENH-057, ENH-053 fix):**
+   ```
+   Agent({ subagent_type: "general-purpose",
+     description: "changelog-agent: bump to {version} + CHANGELOG [{version}]",
+     prompt: "Load agents/changelog-agent.md. Version: {version}. Date: {today}. Entries: {phase_summary_bullets}. Files: package.json + CHANGELOG.md."
+   })
+   ```
+   Non-Claude Code: update CHANGELOG.md + package.json inline as before.
+
+   > changelog-agent is the **single authority** for version bumps. Both autonomous.md and
+   > evolve.md invoke it — never do inline version bumps (resolves ENH-053).
+
 6. Update TRACKER.md
 7. Push all changes:
    ```bash
@@ -406,6 +497,46 @@ fi
 ```
 </step>
 
+<step name="post_phase_audit">
+## 5c. Post-Phase Documentation Audit (Tier 1 + 2 only)
+
+After the phase-complete git tag is created, run a fast silent audit:
+
+```bash
+AUDIT_ISSUES=0
+
+# Tier 1: ROADMAP.md phase marked ✅?
+PHASE_IN_ROADMAP=$(grep -c "Phase ${PHASE_NUM}.*✅" .viepilot/ROADMAP.md 2>/dev/null || echo "0")
+[ "$PHASE_IN_ROADMAP" -eq 0 ] && AUDIT_ISSUES=$((AUDIT_ISSUES+1)) && \
+  echo "⚠️  Tier 1: Phase ${PHASE_NUM} not marked ✅ in ROADMAP.md"
+
+# Tier 1: HANDOFF.json current phase matches?
+HANDOFF_PHASE=$(node -e "try{const h=require('./.viepilot/HANDOFF.json');console.log(h.phase||'')}catch(e){}" 2>/dev/null)
+[ "$HANDOFF_PHASE" != "$PHASE_NUM" ] && AUDIT_ISSUES=$((AUDIT_ISSUES+1)) && \
+  echo "⚠️  Tier 1: HANDOFF.json phase=$HANDOFF_PHASE, expected $PHASE_NUM"
+
+# Tier 2: README.md version badge matches package.json?
+PKG_VERSION=$(node -p "require('./package.json').version" 2>/dev/null)
+README_VERSION=$(grep -o 'version-[0-9]*\.[0-9]*\.[0-9]*' README.md 2>/dev/null | head -1 | sed 's/version-//')
+[ "$PKG_VERSION" != "$README_VERSION" ] && AUDIT_ISSUES=$((AUDIT_ISSUES+1)) && \
+  echo "⚠️  Tier 2: README.md badge=$README_VERSION, package.json=$PKG_VERSION"
+```
+
+If `AUDIT_ISSUES > 0`:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ POST-PHASE AUDIT: {AUDIT_ISSUES} issue(s) found
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+{list issues}
+
+Fix now before starting next phase? (y/n)
+→ y: run /vp-audit --fix  then continue
+→ n: continue (issues noted, non-blocking)
+```
+
+If `AUDIT_ISSUES == 0`: silent — no output.
+</step>
+
 <step name="iterate">
 ## 6. Iterate
 

package/workflows/brainstorm.md

@@ -7,9 +7,10 @@ Allows research inline within the same brainstorm session when needed.
 
 | Feature | Claude Code (terminal) | Cursor (Agent/Skills) | Codex CLI | Antigravity (native) |
 |---------|----------------------|-----------------------|-----------|----------------------|
-| Interactive prompts | ✅ `AskUserQuestion` tool | ❌ text fallback | ❌ text fallback | ❌ text fallback |
+| Interactive prompts | ✅ `AskUserQuestion` tool — **REQUIRED** | ❌ text fallback | ❌ text fallback | ❌ text fallback |
 
-When `AskUserQuestion` is not available, each prompt block falls back to the plain-text numbered list shown below it — no configuration needed.
+**Claude Code (terminal):** Always call `AskUserQuestion` first. Only fall back to the plain-text menu below if the tool returns an error or is unavailable.
+**Cursor / Codex CLI / Antigravity / other adapters:** `AskUserQuestion` not available — use text menus below.
 
 ## ViePilot Skill Scope Policy (BUG-004)
 
@@ -47,12 +48,12 @@ Parse results to get list of existing sessions.
 **If previous sessions exist:**
 
 > **Adapter-aware prompt:**
-> - **Claude Code (terminal):** use `AskUserQuestion` tool — spec:
+> **Claude Code (terminal) — REQUIRED:** Call `AskUserQuestion` tool. Only fall back to text menu if the tool errors or is unavailable. AUQ spec:
 >   - question: "Previous brainstorm sessions found. What would you like to do?"
 >   - header: "Session"
 >   - options: [{ label: "Continue recent session", description: "Resume the most recent session from where it stopped" }, { label: "Review specific session", description: "Choose a particular session to review or continue" }, { label: "New brainstorm session", description: "Start fresh — previous sessions are preserved" }]
 >   - multiSelect: false
-> - **Cursor / Codex / Antigravity / other:** use text menu below
+> **Cursor / Codex / Antigravity / other:** use text menu below
 
 ```
 I found previous brainstorm sessions:
@@ -137,12 +138,12 @@ If the user is brainstorming a landing page / homepage / marketing page:
 2. Present a layout menu for the user to choose from:
 
 > **Adapter-aware prompt:**
-> - **Claude Code (terminal):** use `AskUserQuestion` tool — spec:
+> **Claude Code (terminal) — REQUIRED:** Call `AskUserQuestion` tool. Only fall back to text menu if the tool errors or is unavailable. AUQ spec:
 >   - question: "Which landing page layout fits your goals and audience?"
 >   - header: "Layout"
 >   - options: [{ label: "Layout A — Hero centric", description: "Hero + trust logos + features + CTA — best for brand awareness and conversions" }, { label: "Layout B — Problem/Solution", description: "Problem/Solution + social proof + pricing + FAQ — best for SaaS sign-ups" }, { label: "Layout C — Product storytelling", description: "Screenshots + testimonials + final CTA — best for product demos" }, { label: "Layout D — SaaS conversion", description: "Integrations + comparison + onboarding steps — best for tool adoption" }]
 >   - multiSelect: false
-> - **Cursor / Codex / Antigravity / other:** use list below
+> **Cursor / Codex / Antigravity / other:** use list below
 
    - Layout A: Hero centric + trust logos + features + CTA
    - Layout B: Problem/Solution + social proof + pricing + FAQ
@@ -593,6 +594,40 @@ After intake is **completed** or a **valid skip** (META already has profile) →
 <step name="save_session">
 ## 6. Save Session
 
+### Pre-Save Phase Assignment Validation (ENH-052)
+
+Before writing the session file, validate phase assignment completeness:
+
+**Scope-locked session** — `## Phases` section exists with real content OR user confirmed scope finalized (ref: Step 5.1 condition 1):
+
+```
+CHECK 1: Does session draft contain a non-empty ## Phases section?
+CHECK 2: Does Phase 1 have at least one feature/capability assigned?
+CHECK 3: Are there any features listed outside a phase (unassigned)?
+```
+
+**Gate condition:**
+- If scope is locked AND (CHECK 1 fails OR CHECK 2 fails):
+  → **Block save.** Show:
+  ```
+  ⚠️  Phase assignment incomplete — cannot save as Completed.
+
+  Features were discussed but no phase assignments exist.
+  Before saving:
+    1. Assign all features to phases (## Phases section)
+    2. Ensure Phase 1 has at least one feature
+
+  Return to the conversation to assign phases, then /save again.
+  ```
+- If scope is **not** locked (exploratory session — no feature assignments):
+  → **Allow save** with `Status: In Progress` and add advisory note to session file:
+  ```markdown
+  > ⚠️ Exploratory session — no phase assignments yet.
+  > Run /vp-brainstorm to continue and assign features to phases before /vp-crystallize.
+  ```
+- If brownfield stub session (`IS_BROWNFIELD=true`): **skip this gate** — brownfield stubs intentionally have no phases.
+- If all checks pass → proceed to file write below.
+
 Create/update file: `docs/brainstorm/session-{YYYY-MM-DD}.md`
 
 ```markdown

package/workflows/crystallize.md

@@ -6,9 +6,10 @@ Convert brainstorm sessions into structured artifacts for autonomous AI executio
 
 | Feature | Claude Code (terminal) | Cursor (Agent/Skills) | Codex CLI | Antigravity (native) |
 |---------|----------------------|-----------------------|-----------|----------------------|
-| Interactive prompts | ✅ `AskUserQuestion` tool | ❌ text fallback | ❌ text fallback | ❌ text fallback |
+| Interactive prompts | ✅ `AskUserQuestion` tool — **REQUIRED** | ❌ text fallback | ❌ text fallback | ❌ text fallback |
 
-When `AskUserQuestion` is not available, each prompt block falls back to the plain-text numbered list shown below it — no configuration needed.
+**Claude Code (terminal):** Always call `AskUserQuestion` first. Only fall back to the plain-text menu below if the tool returns an error or is unavailable.
+**Cursor / Codex CLI / Antigravity / other adapters:** `AskUserQuestion` not available — use text menus below.
 
 ## ViePilot Skill Scope Policy (BUG-004)
 
@@ -102,12 +103,12 @@ Ask the user for project information:
 ### License & Year
 
 > **Adapter-aware prompt (question 13):**
-> - **Claude Code (terminal):** use `AskUserQuestion` tool — spec:
+> **Claude Code (terminal) — REQUIRED:** Call `AskUserQuestion` tool. Only fall back to text menu if the tool errors or is unavailable. AUQ spec:
 >   - question: "Which license for this project?"
 >   - header: "License"
 >   - options: [{ label: "MIT", description: "Permissive — most common open-source choice" }, { label: "Apache-2.0", description: "Permissive with patent grant — preferred for enterprise OSS" }, { label: "GPL-3.0", description: "Copyleft — derivative works must stay open-source" }, { label: "Proprietary", description: "All rights reserved — no public redistribution" }]
 >   - multiSelect: false
-> - **Cursor / Codex / Antigravity / other:** use text list below
+> **Cursor / Codex / Antigravity / other:** use text list below
 
 ```
 13. License?
@@ -134,12 +135,12 @@ Store all metadata for template generation.
 - Warn: "`.viepilot/` already exists. Re-running brownfield mode will overwrite artifacts."
 
 > **Adapter-aware prompt:**
-> - **Claude Code (terminal):** use `AskUserQuestion` tool — spec:
+> **Claude Code (terminal) — REQUIRED:** Call `AskUserQuestion` tool. Only fall back to text menu if the tool errors or is unavailable. AUQ spec:
 >   - question: "`.viepilot/` already exists. Re-running brownfield mode will overwrite artifacts. Continue?"
 >   - header: "Overwrite?"
 >   - options: [{ label: "Yes, continue", description: "Overwrite existing .viepilot/ artifacts with new scan results" }, { label: "No, abort", description: "Stop here — keep existing artifacts unchanged" }]
 >   - multiSelect: false
-> - **Cursor / Codex / Antigravity / other:** use text prompt below
+> **Cursor / Codex / Antigravity / other:** use text prompt below
 >
 > Ask: "Continue? (y/n)" — abort if n.
 
@@ -227,12 +228,12 @@ If `polyrepo_hints` is empty → skip this section entirely (no empty array in c
 **Interactive prompt** (fire when `polyrepo_hints` non-empty):
 
 > **Adapter-aware prompt:**
-> - **Claude Code (terminal):** use `AskUserQuestion` tool — spec:
+> **Claude Code (terminal) — REQUIRED:** Call `AskUserQuestion` tool. Only fall back to text menu if the tool errors or is unavailable. AUQ spec:
 >   - question: "Polyrepo signals detected — this repo may be part of a multi-repo system. Would you like to provide related repo URLs?"
 >   - header: "Polyrepo?"
 >   - options: [{ label: "Yes, I'll list them", description: "Provide sibling repo URLs — improves system-level context accuracy" }, { label: "Skip for now", description: "Continue without related repos — affected fields will be marked ASSUMED" }]
 >   - multiSelect: false
-> - **Cursor / Codex / Antigravity / other:** use text prompt below
+> **Cursor / Codex / Antigravity / other:** use text prompt below
 
 ```
 ⚠️ Polyrepo signals detected:
@@ -786,6 +787,31 @@ When generating TRACKER.md in Step 9 (brownfield mode only), append:
 
 </step>
 
+<step name="brownfield_execution_path">
+## Brownfield Execution Path
+
+When `IS_BROWNFIELD=true`, the following table governs which steps execute:
+
+| Step | Name | Brownfield behavior | Rationale |
+|------|------|---------------------|-----------|
+| 0 | Collect metadata | **RUN** | Always needed |
+| 0-B | Brownfield scanner | **RUN** | Core brownfield step |
+| 0-C | Generate brainstorm stub | **RUN** | Creates `session-brownfield-import.md` |
+| 1 | Analyze brainstorm | **RUN (stub only)** | Reads brownfield stub; skips greenfield-only checks |
+| 1A | UI direction gate | **CONDITIONAL** — run if `.viepilot/ui-direction/` already exists in the project |
+| 1B | Stack research cache | **CONDITIONAL** — skip if brownfield scanner already populated stack cache |
+| 1C | Architect artifact consumption | **SKIP** — no architect HTML workspace in a brownfield import |
+| 1D | Architect auto-activate suggestion | **SKIP** — no scope brainstorm; architect mode not applicable |
+| 2+ | All subsequent steps | **RUN** — same as greenfield from Step 2 onward |
+
+> **Implementation note for AI agents:** When `IS_BROWNFIELD=true`, check each CONDITIONAL
+> step against the stated condition before executing. Do **not** skip Step 1 entirely —
+> read the brownfield stub to extract stack + gap data for Step 2 (AI-GUIDE.md generation).
+> For Step 1B: check `~/.viepilot/stacks/` for entries created during the Step 0-B scan;
+> if present and non-empty, skip the full research pass in 1B.
+
+</step>
+
 <step name="analyze_brainstorm">
 ## Step 1: Analyze Brainstorm
 
@@ -842,12 +868,12 @@ Check if `.viepilot/ui-direction/` exists and contains any session artifacts.
 If `ui_scope_detected = true` **AND** artifacts are missing → **STOP** and present:
 
 > **Adapter-aware prompt:**
-> - **Claude Code (terminal):** use `AskUserQuestion` tool — spec:
+> **Claude Code (terminal) — REQUIRED:** Call `AskUserQuestion` tool. Only fall back to text menu if the tool errors or is unavailable. AUQ spec:
 >   - question: "UI Direction artifacts missing. The brainstorm indicates UI scope but `.viepilot/ui-direction/` has no artifacts. How to proceed?"
 >   - header: "UI Direction"
 >   - options: [{ label: "Return to /vp-brainstorm --ui (Recommended)", description: "Create UI direction artifacts first for best results" }, { label: "Continue with assumptions", description: "Record assumptions in ARCHITECTURE.md and proceed without visual direction" }]
 >   - multiSelect: false
-> - **Cursor / Codex / Antigravity / other:** use text menu below
+> **Cursor / Codex / Antigravity / other:** use text menu below
 
 ```
 ⚠️ UI Direction artifacts missing
@@ -1016,12 +1042,12 @@ If `.viepilot/architect/` does **not** exist but brainstorm shows complex archit
 - Suggest (soft prompt — not a hard block):
 
 > **Adapter-aware prompt:**
-> - **Claude Code (terminal):** use `AskUserQuestion` tool — spec:
+> **Claude Code (terminal) — REQUIRED:** Call `AskUserQuestion` tool. Only fall back to text menu if the tool errors or is unavailable. AUQ spec:
 >   - question: "Complex architecture detected (≥5 services/components). Would you like to create architecture visualizations first with /vp-brainstorm --architect?"
 >   - header: "Architect?"
 >   - options: [{ label: "Yes, go to architect mode", description: "Create visual architecture diagrams before crystallizing (recommended for complex systems)" }, { label: "No, continue now", description: "Continue crystallize with text-only brainstorm — no visual diagrams" }]
 >   - multiSelect: false
-> - **Cursor / Codex / Antigravity / other:** use text menu below
+> **Cursor / Codex / Antigravity / other:** use text menu below
 
   ```
   💡 Would you like to return to /vp-brainstorm --architect to create visualizations first?

package/workflows/evolve.md

@@ -6,9 +6,10 @@ Upgrade or expand the project: add features, start a new milestone, or refactor.
 
 | Feature | Claude Code (terminal) | Cursor (Agent/Skills) | Codex CLI | Antigravity (native) |
 |---------|----------------------|-----------------------|-----------|----------------------|
-| Interactive prompts | ✅ `AskUserQuestion` tool | ❌ text fallback | ❌ text fallback | ❌ text fallback |
+| Interactive prompts | ✅ `AskUserQuestion` tool — **REQUIRED** | ❌ text fallback | ❌ text fallback | ❌ text fallback |
 
-When `AskUserQuestion` is not available, each prompt block falls back to the plain-text numbered list shown below it — no configuration needed.
+**Claude Code (terminal):** Always call `AskUserQuestion` first. Only fall back to the plain-text menu below if the tool returns an error or is unavailable.
+**Cursor / Codex CLI / Antigravity / other adapters:** `AskUserQuestion` not available — use text menus below.
 
 ## ViePilot Skill Scope Policy (BUG-004)
 
@@ -25,6 +26,8 @@ When `AskUserQuestion` is not available, each prompt block falls back to the pla
 
 <process>
 
+> **AUQ preload — Claude Code adapter (ENH-059):** At session start, before any interactive prompt, call `ToolSearch` with `query: "select:AskUserQuestion"` to load the deferred schema. Required on Claude Code (terminal). Skip only if `ToolSearch` returns an error → use text fallback for that session.
+
 <step name="detect_state">
 ## 1. Detect Current State
 
@@ -54,8 +57,9 @@ Determine:
 How would you like to evolve the project?
 ```
 
-> **Adapter-aware prompt:**
-> - **Claude Code (terminal):** use `AskUserQuestion` tool — spec:
+> **Claude Code (terminal) — REQUIRED:** Call `AskUserQuestion` tool. Only fall back to text menu if the tool errors or is unavailable.
+> **Cursor / Codex / Antigravity:** use text menu below.
+> AUQ spec:
 >   - question: "How would you like to evolve the project?"
 >   - header: "Evolve mode"
 >   - options: [{ label: "Add Feature", description: "Add a new capability to the current milestone" }, { label: "New Milestone", description: "Archive current milestone and start a new scope" }, { label: "Refactor", description: "Improve existing code without adding new features" }]
@@ -81,23 +85,25 @@ Describe the new feature:
 3. Which services/modules affected?
 4. Dependencies on existing code?
 
-> **Adapter-aware prompt (question 5 — complexity):**
-> - **Claude Code (terminal):** use `AskUserQuestion` tool — spec:
+> **Claude Code (terminal) — REQUIRED (question 5 — complexity):** Call `AskUserQuestion` tool. Only fall back to text menu if the tool errors or is unavailable.
+> **Cursor / Codex / Antigravity:** use text menu below.
+> AUQ spec:
 >   - question: "Estimated implementation complexity?"
 >   - header: "Complexity"
 >   - options: [{ label: "S — Small", description: "Few hours — isolated change, 1 file" }, { label: "M — Medium", description: "1–2 days — 1–2 files, some integration" }, { label: "L — Large", description: "3–5 days — multiple modules affected" }, { label: "XL — Extra Large", description: "1+ week — architectural change or major feature" }]
 >   - multiSelect: false
-> - **Cursor / Codex / Antigravity / other:** use text below
+> **Cursor / Codex / Antigravity / other:** use text below
 
 5. Estimated complexity? (S/M/L/XL)
 
-> **Adapter-aware prompt (question 6 — brainstorm routing):**
-> - **Claude Code (terminal):** use `AskUserQuestion` tool — spec:
+> **Claude Code (terminal) — REQUIRED (question 6 — brainstorm routing):** Call `AskUserQuestion` tool. Only fall back to text menu if the tool errors or is unavailable.
+> **Cursor / Codex / Antigravity:** use text menu below.
+> AUQ spec:
 >   - question: "Does this feature need a brainstorm session first?"
 >   - header: "Brainstorm?"
 >   - options: [{ label: "Yes — go to /vp-brainstorm", description: "Research-heavy, UX-driven, or landing page feature — brainstorm first" }, { label: "No — plan directly", description: "Scope is clear — proceed to phase/task planning now" }]
 >   - multiSelect: false
-> - **Cursor / Codex / Antigravity / other:** use text below
+> **Cursor / Codex / Antigravity / other:** use text below
 
 6. Need deep brainstorm? (landing page / UX / growth ideas / research-heavy)
 ```
@@ -288,13 +294,15 @@ Add to ROADMAP.md as phase {N+0.5} or insert between phases.
 <step name="update_version">
 ## 4. Update Version
 
-Based on changes:
+Apply the canonical bump rules from `.viepilot/SYSTEM-RULES.md → Version Bump Rules`.
+Precedence: MAJOR > MINOR > PATCH. Mixed phase → highest applicable bump wins.
 
-| Mode | Version Bump |
-|------|--------------|
-| Add Feature | MINOR (x.Y.z) |
-| New Milestone | MAJOR or MINOR |
-| Refactor | PATCH (x.y.Z) |
+Quick reference:
+- Add Feature → **MINOR**
+- Bug fix only → **PATCH**
+- Refactor (no behavior change) → **PATCH**
+- Mixed feature + fix → **MINOR**
+- Breaking change → **MAJOR**
 
 Update in:
 - TRACKER.md
@@ -305,6 +313,8 @@ Update in:
 <step name="confirm">
 ## 5. Confirm & Suggest Next
 
+Output the evolution summary banner:
+
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  VIEPILOT ► EVOLVE COMPLETE ✓
@@ -322,7 +332,32 @@ Update in:
  - Phase {N}: {name}
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- Next: /vp-auto --from {new_phase}
+```
+
+Then — **Claude Code adapter (terminal): use AskUserQuestion**:
+
+```
+question: "Phase {N} planned. What would you like to do next?"
+options:
+  - label: "Execute now → /vp-auto"
+    description: "Start implementing Phase {N} immediately (Recommended)"
+  - label: "Create another request → /vp-request"
+    description: "Log more requests before implementing"
+  - label: "Done for now"
+    description: "Exit — run /vp-auto later to start implementation"
+```
+
+**On selection:**
+- "Execute now → /vp-auto": invoke `/vp-auto --from {new_phase}` skill
+- "Create another request → /vp-request": invoke `/vp-request` skill
+- "Done for now": print brief confirmation and exit
+
+**Text fallback (Cursor, Codex, Copilot, Antigravity — AUQ not available):**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Next:
+ - /vp-auto --from {new_phase}    Execute Phase {N}
+ - /vp-request                    Create another request
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 </step>