vp-evolve
- Repo stars 13
- Author updated Live
- Author repo viepilot
- Domain
- Other
- Compatible agents
-
- Claude Code
- Cursor
- Cline
- Codex
- Windsurf
- Gemini CLI
- +20
- Trust score
- 92 / 100 · audit passed
- Author / version / license
- @0-CODE · v0.3.0 · no license declared
- Token usage
- Heavy
- 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-evolve
description: Upgrade, add features, or start a new milestone Output this banner as the first thing on every i…
category: other
runtime: Node.js
---
# vp-evolve output preview
## PART A: Task fit
- Use case: Upgrade, add features, or start a new milestone Output this banner as the first thing on every invocation — before questions, work, or any other output: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ VIEPILOT ► VP-EVOLVE v0.3.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 “Upgrade, add features, or start a new milestone Output this banner as the first thing on every invocation — before questions, work, or any other output: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ VIEPILOT ► VP-EVOLVE v0.3.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-evolve`, `/multitask`, `/vp-auto`, `/vp-brainstorm`, `/absolute`; 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-evolve
description: Upgrade, add features, or start a new milestone Output this banner as the first thing on every i…
category: other
source: 0-CODE/viepilot
---
# vp-evolve
## When to use
- Upgrade, add features, or start a new milestone Output this banner as the first thing on every invocation — before que…
- 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-evolve" {
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-EVOLVE v0.3.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 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)
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.
- This skill is planning only: ROADMAP, phase dir, SPEC/tasks, TRACKER, version/CHANGELOG notes when the workflow specifies — does not implement default shipping code (
lib/,tests/,bin/, large edits toworkflows//skills/beyond plan artifacts). - Next step:
/vp-auto. Seeworkflows/evolve.md. - Exception: User explicit bypass — state clearly in chat.
Modes:
- Add Feature - Add a feature to the current milestone
- New Milestone - Start a new milestone
- Refactor - Improve existing code
Routing intelligence:
- For requests leaning toward idea exploration (especially landing pages), prioritize routing through enhanced
/vp-brainstormbefore the crystallize phase. - Supports brainstorm routing with in-session research so the user can decide within a single session.
Updates:
.viepilot/ROADMAP.md.viepilot/TRACKER.md.viepilot/ARCHITECTURE.md(if there are changes)CHANGELOG.md
Task path convention (BUG-009):
When generating task files, ALL paths in ## Paths blocks MUST be
repo-relative (relative to the repository root where package.json lives).
CORRECT: workflows/foo.md skills/vp-bar/SKILL.md lib/foo.cjs
INCORRECT: ~/.claude/viepilot/workflows/foo.md /absolute/path
Absolute paths inside code block content (bash examples, runtime descriptions)
are fine — only the ## Paths header block must use repo-relative paths.
See guard in workflows/evolve.md → "TASK PATH RULE (BUG-009)".
Step 1: Detect Current State
cat .viepilot/TRACKER.md
- Check milestone progress
- Check if current milestone complete
Step 2: Ask User Intent
How would you like to evolve the project?
1. Add Feature - Add new feature to current milestone
2. New Milestone - Start a new milestone (archive current)
3. Refactor - Improve existing code without new features
Step 3A: Add Feature Mode
flow:
1. Ask feature description
2. Mini brainstorm:
- What does it do?
- Which services affected?
- Dependencies on existing code?
3. If landing-page or research-heavy:
- route: /vp-brainstorm --new --landing --research
- return here after brainstorm summary
4. Check architecture compatibility
5. Generate new phase in ROADMAP.md
6. Create phase directory with SPEC.md
7. Update TRACKER.md
output:
- New phase added to ROADMAP.md
- Phase directory created
- Ready for /vp-auto
Step 3B: New Milestone Mode
flow:
1. Archive current milestone:
- Move ROADMAP.md → milestones/v{X}/
- Create MILESTONE-SUMMARY.md
- Tag git: v{X}.0.0
2. Start brainstorm for new scope:
- Default: /vp-brainstorm --new
- If landing-page oriented: /vp-brainstorm --new --landing --research
3. After brainstorm, route to /vp-crystallize
4. Carry over:
- PROJECT-META.md (unchanged)
- SYSTEM-RULES.md (unchanged)
- Learnings and patterns
output:
- Previous milestone archived
- New ROADMAP.md created
- Version bumped (MAJOR or MINOR)
Step 3C: Refactor Mode
flow:
1. Analyze code for improvement areas:
- Code duplication
- Performance issues
- Architecture violations
- Technical debt
2. Create refactor tasks
3. Ensure backward compatibility
4. Generate refactor phase
5. Update ARCHITECTURE.md if structure changes
output:
- Refactor phase added
- Backward compatibility documented
- Ready for /vp-auto
Step 4: Update Version
Based on changes:
- Add Feature → MINOR bump
- New Milestone → MAJOR or MINOR bump
- Refactor → PATCH bump (no behavior change)
Update in:
- TRACKER.md
- pom.xml / package.json
- CHANGELOG.md [Unreleased] section
Step 5: Confirm & Suggest Next
Display summary banner:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
VIEPILOT ► EVOLVE COMPLETE ✓
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Mode: {mode}
Changes: {list}
Version: {old} → {new}
New Phases: Phase {N}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Claude Code (terminal) — REQUIRED: After banner, call 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"
On selection:
- "Execute now → /vp-auto": invoke
/vp-auto --from {new_phase}skill - "Create another request → /vp-request": invoke
/vp-requestskill - "Done for now": print "Phase {N} ready. Run /vp-auto when ready." and exit
Text fallback (Cursor/Codex/Copilot/Antigravity):
Next actions:
/vp-auto --from {N} Execute Phase {N}
/vp-request Create another request
Adapter Compatibility
AskUserQuestion Tool (ENH-048 + ENH-055)
| Adapter | Interactive Prompts | Notes |
|---|---|---|
| Claude Code (terminal) | ✅ AskUserQuestion tool — REQUIRED |
Must call AUQ; plain-text only if tool errors or is unavailable |
| Cursor (Agent/Skills) | ❌ Text fallback | AskQuestion not available in Agent Mode |
| Codex CLI | ❌ Text fallback | Native tool N/A |
| 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.
Prompts using AskUserQuestion in this skill:
- Evolve mode selection (Step 2 — Add Feature / New Milestone / Refactor)
- Complexity selection (Step 3A — S/M/L/XL)
- Brainstorm routing decision (Step 3A — Yes / No)
- Workflow continuation (Step 5 — Execute /vp-auto / Create request / Done)
Decide Fit First
Design Intent
How To Use It
Boundaries And Review