vp-brainstorm
- Repo stars 13
- Author updated Live
- Author repo viepilot
- Domain
- Engineering
- Compatible agents
-
- Claude Code
- Cursor
- Cline
- Codex
- Windsurf
- Gemini CLI
- +20
- Trust score
- 92 / 100 · audit passed
- Author / version / license
- @0-CODE · v1.1.0 · no license declared
- Token usage
- Moderate
- Setup complexity
- Guided setup
- External API key
- Not required
- Operating systems
- macOS · Linux · Windows
- Runtime requirements
- Node.js
- Permissions
-
- Read-only
- Write / modify
- Shell exec
- Network behavior
- Local-only
- Install commands
- 26 variants
Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.
Heads up: 未限定 allowed-tools,默认拥有全部工具权限。
---
name: vp-brainstorm
description: Brainstorm session to collect ideas and decisions for the project Output this banner as the firs…
category: engineering
runtime: Node.js
---
# vp-brainstorm output preview
## PART A: Task fit
- Use case: Brainstorm session to collect ideas and decisions for the project Output this banner as the first thing on every invocation — before questions, work, or any other output: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ VIEPILOT ► VP-BRAINSTORM v1.1.0 (fw 2.19.0) runs entirely locally; runs on Node.js. Works with Claude Code, Cursor, Cline and 23 more..
- Inputs: target material, constraints, expected output, and acceptance criteria.
- Evidence boundary: follow “Invocation Banner / Version Update Check (ENH-072) / Persona Context Injection (ENH-073)” and do not present inference as author intent.
## PART B: Execution result
- **01** The card summarizes the use case; runtime output centers on “Brainstorm session to collect ideas and decisions for the project Output this banner as the first thing on every invocation — before questions, work, or any other output: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ VIEPILOT ► VP-BRAINSTORM v1.1.0 (fw 2.19.0) runs entirely locally; runs on Node.js. Works with Claude Code, Cursor, Cline and 23 more.”.
- **02** When the source has headings, the agent prioritizes “Invocation Banner / Version Update Check (ENH-072) / Persona Context Injection (ENH-073)” so the result follows the author’s structure.
- **03** Typical output includes task judgment, concrete steps, required commands or file edits, validation, and follow-up options.
- **04** Risk context follows the fingerprint: read files, write/modify files, run shell commands; mostly runs locally; usually needs no extra API key.
## Running Rules
- read files, write/modify files, run shell commands; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding scope.
- Return the result, validation criteria, and next iteration options. The source mentions slash commands such as `/vp-brainstorm`, `/vp-crystallize`, `/command`, `/multitask`, `/vp-auto`; use them first when your agent supports command triggers.
Name target files or source material, expected output, forbidden changes, and whether network or shell access is allowed. Permission fingerprint: read files, write/modify files, run shell commands.
Start with a small task and check whether the result follows “Invocation Banner / Version Update Check (ENH-072) / Persona Context Injection (ENH-073)”. Inspect diffs, logs, previews, or tests before expanding scope.
Confirm the final output includes a concrete result, evidence, and next action. If it stays generic, tighten inputs, boundaries, and acceptance criteria.
---
name: vp-brainstorm
description: Brainstorm session to collect ideas and decisions for the project Output this banner as the firs…
category: engineering
source: 0-CODE/viepilot
---
# vp-brainstorm
## When to use
- Brainstorm session to collect ideas and decisions for the project Output this banner as the first thing on every invoc…
- Use it when the task has clear inputs, repeatable steps, and validation criteria.
## What to provide
- Target material, scope, expected result, and forbidden changes.
- Whether network, commands, file writes, or external services are allowed.
## Execution rules
- Organize steps around “Invocation Banner / Version Update Check (ENH-072) / Persona Context Injection (ENH-073)” and keep inference separate from source facts.
- read files, write/modify files, run shell commands; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding the task.
## Output requirements
- Return the deliverable, key evidence, validation method, and next action.
- Mark missing information as unknown; do not invent commands, platforms, or dependencies. The author source anchors workflow facts; repository files anchor sources and commands; Fluxly only adds fit, limitations, and quality judgment.
skill "vp-brainstorm" {
input -> user goal + target files + boundaries + acceptance criteria
context -> Invocation Banner / Version Update Check (ENH-072) / Persona Context Injection (ENH-073)
rules -> SKILL.md triggers / order / output contract
runtime -> Node.js | read files, write/modify files, run shell commands | mostly runs locally
guardrails -> usually needs no extra API key + small-sample validation + diff/log review
output -> copyable result + checklist + next iteration
} Output this banner as the first thing on every invocation — before questions, work, or any other output:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
VIEPILOT ► VP-BRAINSTORM v1.1.0 (fw 2.19.0)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
After displaying the greeting banner, run:
node "$HOME/.claude/viepilot/bin/vp-tools.cjs" check-update --silent
If exit code = 1 (update available — new version printed to stdout): Display notice banner before any other output:
┌──────────────────────────────────────────────────────────────────┐
│ ✨ ViePilot {latest_version} available (installed: {current}) │
│ npm i -g viepilot && vp-tools install --target {adapter_id} │
└──────────────────────────────────────────────────────────────────┘
Replace {latest_version} with stdout from the command, {current} with the installed
version, {adapter_id} with the active adapter (claude-code / cursor / antigravity / codex / copilot).
If exit code = 0 or command unavailable: silent, continue.
Suppression rules:
--no-update-checkflag on skill invocation → skip this step entirelyconfig.json→update.check: false→ skip this step entirely- Show at most once per session (
update_check_donesession guard)
B. User Prompting
Prompt user conversationally with numbered list options.
C. Tool Usage
Use Claude Code tools: Bash (shell), Read (file), Edit + Write (file write/patch),
Grep (search), Glob (file patterns), LS, WebSearch, WebFetch,
Agent (spawn subagent — multi-level nesting supported)
Interactive: AskUserQuestion (deferred — preload via ToolSearch before first call)
D. Session Actions — Proactive AUQ Triggers (BUG-026)
No slash sub-commands. All session actions are triggered proactively by the AI via
AskUserQuestion at the right moment — no user typing required.
| Action | Trigger condition | AUQ prompt |
|---|---|---|
| Save + crystallize handoff | User signals done: "save", "done", "xong", "lưu", "finished", "ready", "crystallize", or equivalent intent | "Save session and prepare for /vp-crystallize?" |
| UX walkthrough | In UI session AND user mentions "research", "test", "UX", "walkthrough" — OR ≥1 UI signals accumulated | "Run UX walkthrough (3-phase simulate + research + update HTML)?" |
| Architecture review | User asks "review decisions", "check arch", "summarize choices", or equivalent intent | "Generate architecture review summary table?" |
| Sync UI → Arch | After arch update when UI workspace also active | "Sync architecture changes to UI Direction workspace?" |
Why: In Claude Code terminal, any /command is intercepted by the shell as a skill invocation. Using proactive AUQ triggers works identically on ALL adapters — no adapter-specific typing rules needed.
C. Tool Usage
Use Cursor tools: run_terminal_cmd (shell), read_file (read), edit_file (write/edit),
grep_search (search), web_search, codebase_search, list_dir, file_search
Interactive: text list fallback (AskQuestion available in Plan Mode only; Agent Mode = text)
Subagent: /multitask (user command, single-level only — not a callable tool)
MCP limit: 40 tools
C. Tool Usage
Use Antigravity tools: shell (cmd), file_read, file_write, MCP plugins
Interactive: text fallback (TUI-based; no formal AskUserQuestion)
Skill path: .agents/skills/<skill>/SKILL.md (project) or ~/.gemini/antigravity/skills/ (global)
Note: Gemini CLI deprecated June 18, 2026 — use Antigravity CLI.
C. Tool Usage
Use Codex tools: container.exec (sandboxed shell), apply_patch (file write), web_search
Interactive: text fallback (TUI Tab/Enter injection)
Config: ~/.codex/config.toml
C. Tool Usage
Use Copilot tools: runCommands (shell), read/readfile (read), edit/editFiles (write),
code_search, find_references
Interactive: askQuestions (main agent only — NOT available in subagents; VS Code issue #293745)
Skill path: .github/agents/<name>.agent.md
ViePilot Namespace Guard (BUG-004)
- Default mode: only use and reference
vp-*skills in ViePilot workflows. - External skills (
non vp-*) are out of framework scope unless user explicitly opts in. - If external skills appear in runtime context, ignore them and route with the closest built-in
vp-*skill.
- Scoped to session artifacts (
docs/brainstorm/*,.viepilot/ui-direction/*). Does not implement on behalf of/vp-autoforlib/,tests/, or frameworkworkflows//skills/changes — after brainstorm use/vp-crystallize//vp-evolve→/vp-autodepending on the stage. Explicit override — state it in chat.
Supports:
- Create a new session
- Continue a previous session
- Review a past session
- Landing page layout discovery (follow-up questions to finalize layout)
- In-session research (research during the brainstorm session on demand)
- UI Direction mode: create/update HTML prototype + notes under
.viepilot/ui-direction/{session-id}/— supports multi-page (pages/{slug}.html+ hubindex.html) and the## Pages inventoryhook innotes.mdwhenpages/exists (FEAT-007) - Phase assignment (ENH-030): in every session, features/capabilities are assigned directly to Phase 1, Phase 2, Phase 3... — no MVP/Post-MVP/Future tiers. Session file stores assignments in the
## Phasessection. - Project meta intake (FEAT-009): after scope locked, before
Completed//end, if.viepilot/META.md(viepilot_profile_id) is missing — run sequential Q&A with proposals; read/write~/.viepilot/profile-map.md; create~/.viepilot/profiles/<slug>.md+ binding perdocs/dev/global-profiles.md. If a profile is already bound — skip intake by default (ask if change needed). - UX walkthrough (FEAT-010 + ENH-019 + ENH-020): in
--uimode, proactively offered via AUQ when user mentions "research", "test UX", "walkthrough" — or when ≥1 UI signals accumulated. Runs 3 phases: simulates end-user (with content stress pass + stress recipes by archetype → Stress findings) → UX designer + web research → updateindex.html/pages/*.html/style.cssand write## UX walkthrough loginnotes.md(sync hub + Pages inventory for multi-page). - Background UI extraction (ENH-026 + ENH-060): automatically detects UI signal keywords in every brainstorm session (no
--uiflag required). Auto-suggests itself (ENH-060): if the initial message contains ≥1 UI keyword, shows a proactive 🎨 banner immediately — mirrors Architect Design Mode's 🏗️ proactive activation. Accumulation starts at ≥1 signal (was ≥3); surfaces for confirmation when topic ends, user signals done, or ≥2 unique signals accumulated (was ≥5) — does not interrupt the main conversation. - Idea → Architecture breakdown loop (ENH-061): structured 8-step flow from free idea collection → scope lock → Feature → Coverage mapping (maps each Phase 1 feature to an architect page + UI screen, outputs
## Coveragematrix innotes.md) → Architect Design →arch_to_ui_syncreverse sync (surfaces UI implications of architectural decisions; proactively offered via AUQ after arch updates) → UI Direction → completeness gate (CHECK 4: warns if any Phase 1 feature has no coverage in either mode, non-blocking). SeeRecommended Breakdown Orderingsection inworkflows/brainstorm.md. - Unified workspace mode selection (BUG-018): after scope lock, before any design workspace is created, an AUQ prompt offers: Both / Architect only / UI Direction only / Neither. Architect auto-activate heuristic is deferred until after this selection; suppressed if user selects "Neither" or "UI Direction only".
- Admin & Governance coverage (ENH-063): Topic 6 in brainstorm template; proactive 🔐 heuristic fires on admin/governance keywords; admin coverage gate before /save for multi-user/SaaS/compliance projects;
admin.htmladded to Architect workspace when applicable;notes.md ## adminYAML exported via crystallize. - Content Management coverage (ENH-065): Topic 7 in brainstorm template; proactive 🗂️ heuristic fires on content-type/media/SEO keywords; content coverage gate before /save for projects with content layer;
content.htmladded to Architect workspace;notes.md ## contentYAML exported via crystallize. - Admin Entity Management coverage (ENH-068): Topic 7 in brainstorm template; proactive 🗄️ heuristic fires on CRUD/entity/admin panel keywords; entity management coverage gate before /save for projects with DB entities (cross-references ERD);
entity-mgmt.htmladded to Architect workspace;notes.md ## entity_mgmtYAML exported via crystallize. - User Data Management coverage (ENH-066): Topic 9 in brainstorm template; proactive 👤 heuristic fires on user-account/privacy/auth keywords; user data coverage gate before /save for B2C/SaaS/GDPR projects;
user-data.htmladded to Architect workspace;notes.md ## user_dataYAML exported via crystallize. - Architect Design Mode (FEAT-011):
/vp-brainstorm --architector auto-activate when ≥3 components/services detected; generate HTML workspace (architecture, data-flow, decisions, tech-stack, tech-notes, feature-map) with Mermaid diagrams; incremental update per decision; architecture review offered via AUQ when user asks to review decisions; machine-readablenotes.mdYAML schema. - ERD page (ENH-027): Architect workspace includes
erd.html— MermaiderDiagram, entity list table, relationship summary; triggered by DB/entity/table/relationship keywords; notes.md## erdYAML section exported to ARCHITECTURE.md## Database Schemavia crystallize Step 1D. - User Use Cases page (ENH-028): Architect workspace includes
user-use-cases.html— actor/use-case diagram (Mermaid flowchart), use case table; triggered by user/role/actor/story keywords; notes.md## use_casesYAML section exported to PROJECT-CONTEXT.md## User Stories & Use Casesvia crystallize Step 1D. - C4Context/Sequence/Deployment/APIs pages (ENH-029, 12-page workspace): Architect workspace expanded to 12 pages —
sequence-diagram.html(per-scenario sequenceDiagram),deployment.html(infra graph + environments + CI/CD pipeline),apis.html(endpoint tables with HTTP method badges); page boundary rules table; trigger keywords for sequence/deploy/API; notes.md## apisYAML section; deployment+APIs exported to ARCHITECTURE.md via crystallize Step 1D (sequence excluded — scenario docs are not architecture artifacts). - Embedded Domain Mode (ENH-071): Activated when ≥2 embedded trigger keywords detected (MCU families: STM32/ESP32/nRF52/AVR/RISC-V/RP2040; concepts: firmware/bare-metal/GPIO/interrupt/HAL/bootloader/RTOS) OR
--domain embeddedflag. Adds 6 Architect workspace pages for embedded hardware artifacts, injects domain-specific topic probes, suppresses web-UI false-positives for hardware display keywords, and offers a firmware phase ordering template. crystallize exports 8 YAML sections to ARCHITECTURE.md hardware sections.
Creates/Updates:
docs/brainstorm/session-{YYYY-MM-DD}.md
After: Ready for /vp-crystallize
Language configuration (ENH-032):
- Step 0 reads
~/.viepilot/config.json→BRAINSTORM_LANG=language.document(default:en). BRAINSTORM_LANGis used for brainstorm file storage and generated content.- User session language takes precedence over config if different.
- Configure via:
vp-tools config set language.document vi
Workflow version stamps (ENH-067):
- Session files record
workflow_version(current ViePilot semver) at create/save time. upgrade_supplement_versionstamped after gap-detection supplement completes (idempotency guard).
Upgrade gap detection (ENH-067):
- On
--continue, compares sessionworkflow_versionvs. current Topics Template to detect missing topics. - Proactive 🔄 upgrade banner (AUQ) lists missing topics; user can discuss inline, defer to /save, or skip.
- Inline supplement appended as
## Upgrade supplement (vX → vY)section;upgrade_supplement_versionstamped for idempotency. - After supplement: suggests
/vp-crystallize --upgradeto patch project artifacts.
Reference URL Input (ENH-092)
When user provides a URL during brainstorm (competitor app, documentation, reference product):
- research-agent is dispatched with
op: browse_urlusingvercel-labs/agent-browser - Extracted insights added as
## Reference Researchsection in session output - Covers: features, UX patterns, pricing model, tech stack clues
- Available as context for crystallize step
- Falls back to WebFetch if agent-browser not installed (static HTML only — warns if page is JS-rendered)
Examples:
/vp-brainstorm I want to build a task manager. Reference: https://linear.app
/vp-brainstorm --new Compare these two tools: https://notion.so https://coda.io
Multiple URLs: dispatches compare_products op → side-by-side comparison table.
Embedded Domain Mode (ENH-071)
Activation: Automatically when ≥2 embedded keywords detected, or via --domain embedded flag. One-time 🔌 Embedded Domain Mode activated banner shown.
Topic probes injected when embedded_domain: true:
- MCU/Toolchain (Gap 2): MCU family, toolchain (GCC-ARM/Keil/IAR), build system (CMake/PlatformIO/West), debug interface (SWD/JTAG), flasher, SDK/HAL
- RTOS/Scheduling (Gap 3): bare-metal vs RTOS choice, task list, ISR table, resource protection strategy
- Power Budget (Gap 7): supply type, sleep modes, current targets, battery life (triggered by battery/power/sleep keywords)
- Safety/Compliance (Gap 10): IEC 61508/ISO 26262/DO-178C, watchdog, fault handlers (triggered by safety/SIL/ASIL keywords)
- Firmware Phase Template (Gap 9): Board Bring-Up → Drivers → RTOS → Middleware → Application → Integration Test → OTA
6 new Architect workspace pages (in .viepilot/architect/{session-id}/):
| Page | Trigger | Content |
|---|---|---|
hw-topology.html |
Always in embedded domain | MCU block diagram (Mermaid graph TD) + component/bus/power-rail tables |
pin-map.html |
GPIO/pin/pinout keywords | Pin assignment table (Pin# / GPIO / Function / Peripheral / Direction / Pull / Voltage) |
memory-layout.html |
Flash/RAM/linker/bootloader/OTA keywords | Flash + RAM regions tables + linker constraint notes |
protocol-matrix.html |
CAN/I2C/SPI/BLE/LoRa/MQTT/Modbus keywords | Bus protocol + wireless connectivity tables (distinct from apis.html HTTP REST) |
rtos-scheduler.html |
RTOS/FreeRTOS/task/ISR/scheduler keywords | Task priority table + ISR table + state diagram (≤5 tasks) |
power-budget.html |
Battery/sleep/power/µA/mAh keywords | Power modes table + battery life estimate |
Pages linked in index.html under an Embedded nav section.
UI Direction false-positive suppression (Gap 6):
LCD/OLED/TFT/display/screenin hardware context → routed tohw-topologyperipherals, NOT UI Direction buffer- Hardware context confirmed by: GPIO / SPI / I2C / driver / framebuffer / ILI9341 / SSD1306 / LVGL / u8g2 keywords
🎨 UI Direction Mode?banner suppressed when all display signals have hardware context
notes.md YAML sections written: ## hw_topology, ## pin_map, ## memory_layout, ## protocols, ## rtos_config, ## embedded_toolchain, ## power_budget, ## safety_config
crystallize Step 1D item 13 exports:
## Hardware Architecture(fromhw_topology)## Hardware Interface(frompin_map)## Memory Map(frommemory_layout)## Communication Protocols(fromprotocols) — distinct from## APIs## RTOS & Task Model(fromrtos_config)## Toolchain & Build System(fromembedded_toolchain)## Power Budget(frompower_budget)## Safety & Reliability(fromsafety_config)## Embedded Domain: true+ MCU family written toPROJECT-CONTEXT.md- UI Coverage Gate skipped; Hardware Coverage Check (driver-task completeness, non-blocking) applied instead
Key steps:
- Detect existing sessions
- Ask user intent (new/continue/review)
- Load context if continuing
- Run interactive Q&A with topic-based structure
- If topic is a landing page: ask follow-up layout questions + reference
21st.devto suggest sections/components - If topic needs UI/UX: create/update UI Direction artifacts under
.viepilot/ui-direction/{session-id}/— legacy:index.html+style.css+notes.md; multi-page: addpages/*.html,index.htmlas hub, and after each page change update## Pages inventoryinnotes.md(seedocs/user/features/ui-direction.md) 6b. When user types/research-uior/research uiduring a UI session: followworkflows/brainstorm.mdexactly (FEAT-010) — do not merge into the short regular research step - If user requests research or needs to clarify a decision: research inline in the session and return to the topic
- When a topic adds/modifies a capability: update
## Phasesin the session perworkflows/brainstorm.md - Before completing the session: step 5 — Project meta intake (FEAT-009) in
workflows/brainstorm.mdwhen binding is missing; sequential Q&A + profile-map disambiguation + write global profile +.viepilot/META.md - Save session with structured format (including
## Project meta intake (FEAT-009), research notes + UI direction references +## Phases) - Suggest next action:
/vp-crystallize
Stakeholder Generation (ENH-098):
At session end (scope locked), automatically infers project stakeholders from the domain and
creates .claude/agents/{project-slug}-{role}.md agent files. These are consumed by
/vp-crystallize Step 1G for parallel context review. Skip with --no-stakeholders.
Adapter Compatibility
AskUserQuestion Tool (ENH-048)
This skill uses adapter-aware interactive prompts. Behavior depends on your adapter:
| Adapter | Interactive Prompts | Notes |
|---|---|---|
| Claude Code (terminal) | ✅ AskUserQuestion tool — REQUIRED |
Must call AUQ; plain-text only if tool errors or is unavailable |
| Claude Code (VS Code ext) | ⚠️ Partial | Terminal yes; VS Code UI pending anthropics/claude-code#12609 |
| Cursor (Plan Mode) | ⚠️ Partial | AskQuestion in Plan Mode only — not in Agent/Skills Mode |
| Cursor (Agent/Skills) | ❌ Text fallback | AskQuestion not available in Agent Mode |
| Codex CLI | ❌ Text fallback | Native tool N/A; community MCP available |
| Antigravity (native agent) | ❌ Text fallback | Artifact model, no raw tool calls |
| GitHub Copilot | ✅ /skill-name in Chat |
Via .agent.md custom agent; AUQ not available — text fallback |
Claude Code (terminal) — AUQ preload required (ENH-059):
Before the first interactive prompt, call ToolSearch with query: "select:AskUserQuestion" to load the deferred tool schema. Only after ToolSearch succeeds can AskUserQuestion be invoked. If ToolSearch returns an error, fall back to plain-text numbered list for that session.
When AskUserQuestion is not available on other adapters, the skill automatically falls back to
plain-text numbered list prompts — no configuration required.
Prompts using AskUserQuestion in this skill:
- Session intent (continue / review / new — Step 2)
- Landing page layout selection (Step 4 — Layout A/B/C/D)
- Mid-session structured choices (≥2 discrete named options — BUG-022): topic direction, section priority, angle selection, and any numbered decision with enumerable options
- Session-transition/next-steps prompt (session-flow choices: save/crystallize, update UI artifacts, continue discussing — BUG-023)
Skill Registry Integration (FEAT-020)
When UI Direction Mode is active, vp-brainstorm automatically:
- Loads
~/.viepilot/skill-registry.json(written byvp-tools scan-skills) - Matches installed skills by
capabilitiesto current UI signals - Silently applies matched skill
best_practicesto HTML generation - Records matched skills in
notes.md ## skills_used
No prompt is shown — integration is transparent. Skills with relevant
capabilities (e.g., ui-generation, component-design, responsive-layout)
are detected automatically.
Skill decisions are locked at crystallize time (see /vp-crystallize).
/vp-auto executes with those locked decisions — no re-asking.
Install skills via vp-tools install-skill <source>.
See: docs/user/features/skill-registry.md
Decide Fit First
Design Intent
How To Use It
Boundaries And Review