vp auto
- Repo stars 13
- Author repo viepilot
- Domain
- Other
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 92 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @0-CODE · v0.2.2 · no license declared
- Token usage
- Heavy
- Setup complexity
- Guided setup
- External API key
- Not required
- Operating systems
- macOS · Linux · Windows
- Runtime requirements
- Node.js
- Detected file/system behavior
-
- Read-only
- Write / modify
- Shell exec
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
<greeting>
## Invocation Banner
Output this banner as the **first** thing on every invocation — before questions, work, or any other output:
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
VIEPILOT ► VP-AUTO v0.2.2 (fw 2.19.0)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```
</greeting>
<version_check>
## Version Update Check (ENH-072)
After displaying the greeting banner, run:
```bash
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-check` flag on skill invocation → skip this step entirely
- `config.json` → `update.check: false` → skip this step entirely
- Show at most once per session (`update_check_done` session guard)
</version_check>
<persona_context>
## Persona Context Injection (ENH-073)
At skill start, run:
```bash
node "$HOME/.claude/viepilot/bin/vp-tools.cjs" persona auto-switch
node "$HOME/.claude/viepilot/bin/vp-tools.cjs" persona context
```
Inject the output as `## User Persona` context before any task execution.
Silent if command unavailable or errors.
</persona_context>
<adapter id="claude-code">
## A. Skill Invocation
- Skill được gọi khi user mention `vp-auto`, `/vp-auto`, "auto", "vibe", "chạy tự động"
- Treat all user text after the skill mention as `{{VP_ARGS}}`
## B. User Prompting
Prompt user conversationally with numbered list options at control points.
## 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)
**Additional tools (ENH-099):**
- `Monitor` — run command in background, each output line fed back to Claude; use for
`npm test --watchAll=false`, dev server tail, CI polling mid-conversation
- `CronCreate` / `CronDelete` / `CronList` — in-session scheduled prompts (survive
`--resume`); use for periodic quality checks during long autonomous phases
- `EnterWorktree` / `ExitWorktree` — isolated git worktree per task; auto-cleanup on
exit if no changes; use for parallel task execution without branch conflicts
(not available to subagents)
- `LSP` — code intelligence: type errors after each edit, jump to definition, find
references; requires code intelligence plugin; replaces post-edit `tsc --noEmit`
- `PushNotification` — desktop + phone push on phase complete or control-point pause
(Anthropic infra only; not available on Bedrock/Vertex)
- `EnterPlanMode` / `ExitPlanMode` — plan gate before implementation: EnterPlanMode
switches to read-only planning; ExitPlanMode presents plan for approval before any
file edits are made
## D. Subagent Spawning
Use `Agent` tool for subagent dispatch. For parallel task execution: fan-out with multiple
`Agent` calls per cluster (see ADAPTER_CONTEXT.orchestration — claude-code supports parallel: true).
</adapter>
<adapter id="cursor-agent">
## A. Skill Invocation
Same trigger keywords as claude-code adapter.
## 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
</adapter>
<adapter id="antigravity">
## A. Skill Invocation
Same trigger keywords as claude-code adapter.
Skill discovery: LLM-driven (automatic, no slash command needed).
## 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.
</adapter>
<adapter id="codex">
## A. Skill Invocation
Same trigger keywords as claude-code adapter.
## 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`
</adapter>
<adapter id="copilot">
## A. Skill Invocation
Same trigger keywords as claude-code adapter.
Discovery: User-driven (`@agent-name` in GitHub Copilot Chat).
## 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`
</adapter>
<scope_policy>
## 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.
</scope_policy>
<implementation_routing_guard>
## Primary implementation lane (ENH-021)
- **`/vp-auto`** + `workflows/autonomous.md` is the **default lane** for **implementing** work that already has a **phase/task plan** (doc-first **BUG-001**, git persistence **BUG-003**). **`/vp-request`** and **`/vp-evolve`** do **not** replace this lane unless the user **explicitly** overrides.
</implementation_routing_guard>
<objective>
Autonomous execution of project phases. For each phase: analyze → plan → execute → verify → iterate.
Pauses at control points:
- Conflicts detected
- Quality gate failures
- User decision needed
- Blockers encountered
**Updates after each task:**
- `.viepilot/TRACKER.md`
- `.viepilot/phases/*/PHASE-STATE.md`
- `.viepilot/HANDOFF.json`
- `CHANGELOG.md` (if feature/fix)
- `.viepilot/ROADMAP.md` when task completion changes phase progress/status
**Git persistence gate before PASS (BUG-003):**
- Task/phase cannot be marked PASS if git is not durably persisted.
- Required checks:
- `git status --porcelain` must be empty
- upstream branch must exist (`git rev-parse ... @{u}`)
- no unpushed commits (`git rev-list --count @{u}..HEAD` equals `0`)
- Recommended single check: `node bin/vp-tools.cjs git-persistence --strict`
- On failure: route to control point (retry commit/push, rollback, or stop).
**Mandatory task decomposition before implementation:**
- Objective with concrete expected outcome
- Exact file paths to create/modify
- Per-file description (what + why)
- Best practices to apply (stack + coding conventions)
- Verification commands and expected output
If required task details are missing, do not implement until task contract is refined.
**Doc-first gate before implementation (BUG-001):**
- After contract validation and **before** any deliverable code/doc edits: the task `.md` MUST hold a real written plan (`Paths` + `File-Level Plan` or bullet **Implementation Notes**—no bare `{{PLACEHOLDER}}` rows).
- `PHASE-STATE.md` MUST show the task `in_progress` **before** the first implementation commit for that task.
- **Do not** create `{projectPrefix}-vp-p{phase}-t{task}` or edit shipping files until both are satisfied (read-only exploration and editing the task file to record the plan are allowed).
**Preflight before each task implementation:**
- Read `.viepilot/STACKS.md` (if exists)
- Read `~/.viepilot/stacks/{stack}/SUMMARY.md` for relevant stacks
- Expand to detailed cache files only when needed (token-efficient)
- If `.viepilot/audit-report.md` has Tier 3 stack guardrails, apply them before coding
**Updates after each phase complete:**
- `.viepilot/ROADMAP.md` — phase status row and Progress Summary table
**Updates after each phase (if new skills added):**
- `docs/skills-reference.md` — append sections for new skills
**Updates on milestone complete:**
- `README.md` — version badge, skills/workflows counts, Skills Reference table, Workflows table, Project Structure, Completion Status
- `README.md` metrics — run `npm run readme:sync` when script exists; if `cloc` missing, continue with logged guidance (non-blocking)
**After:** Project built, or paused for user intervention.
**Language configuration (ENH-032):**
- Initialize step reads `~/.viepilot/config.json` → `COMMUNICATION_LANG` (default: `en`).
- `COMMUNICATION_LANG` controls banners, control-point messages, and user-facing output.
- Configure via: `vp-tools config set language.communication vi`
</objective>
<execution_context>
@$HOME/{envToolDir}/workflows/autonomous.md
</execution_context>
<context>
Optional flags:
- `--from N` : Start from phase N
- `--phase N` : Run only phase N
- `--fast` : Skip optional verifications
- `--dry-run` : Plan only, no execution
No extra args: simply means the flags above are **off** — **not** a rule of “mandatory stop after each task”. In chat, one turn is typically ~one task; continue with the next turn or invoke `/vp-auto` again. Doc: `docs/user/features/autonomous-mode.md`.
**Task path validation (BUG-009):**
Before executing each task, validates all paths in the `## Paths` block.
If any path starts with `~/` or `/` (absolute):
- Execution stops for that task with a ⛔ error message
- User must fix the task file to use repo-relative paths before continuing
- This prevents accidentally editing `~/.claude/` (live install) instead of source
See preflight check in `workflows/autonomous.md` → “Preflight: Task Paths Validation (BUG-009)”.
</context>
<process>
Execute workflow from `@$HOME/{envToolDir}/workflows/autonomous.md`
### 1. Initialize
```bash
# Load context
Read AI-GUIDE.md → minimal context strategy
Read TRACKER.md → current state
Read ROADMAP.md → phases list
```
Display startup banner:
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
VIEPILOT ► AUTONOMOUS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Project: {project_name}
Phase: {current_phase}/{total_phases}
Progress: [████░░░░░░] {percent}%
```
### 2. Select Phase
- Find first incomplete phase
- Or resume in_progress phase
- Check dependencies met
### 3. Execute Phase Loop
For each task in phase:
#### 3a. Load Task Context
```yaml
Read:
- AI-GUIDE.md (always)
- TRACKER.md (always)
- PHASE-STATE.md (current phase)
- tasks/{task}.md (current task)
- context_required files (from task)
Stack preflight:
- Identify stacks used by task
- Load stack cache summary first
- Apply stack do/don't rules during implementation
```
#### Doc-first gate + checkpoint order
1. Validate task contract (`workflows/autonomous.md`).
2. Record plan in task file; set task `in_progress` in `PHASE-STATE.md`.
3. Stack preflight.
4. Create git tag `{projectPrefix}-vp-p{phase}-t{task}` **only after** steps 1–3 pass.
#### 3b. Execute Task
- Implement according to objective
- Follow acceptance criteria
- Split large tasks into sub-tasks (30-90 minutes)
- Record plan + files + best-practice checklist before each sub-task
- Write tests if required
- Atomic commits per sub-task
- Log notes in task file
#### 3c. Verify Task
```yaml
automated:
- Run defined commands
- Check expected outputs
manual:
- Present if defined
- Ask user if required
quality_gate:
- All acceptance criteria checked
- Automated tests pass
- No lint errors
```
#### 3d. Handle Result
- **PASS** → Mark task done, create tag `-done`, next task
- **PARTIAL** → Retry with fix
- **FAIL** → Control point (retry/skip/rollback/stop)
### 4. Update State
After each PASS task and PASS sub-task:
- Update PHASE-STATE.md
- Update TRACKER.md
- Update HANDOFF.json
- Update ROADMAP.md if progress/status changed
- Update CHANGELOG.md (if feature/fix)
Rule: state-first then continue. Do not batch updates only at end of phase.
### 5. Phase Complete
When all tasks done:
- Run phase verification
- Check phase quality gate
- Write SUMMARY.md
- Create git tag: `{projectPrefix}-vp-p{phase}-complete`
- Increment version if needed
### 6. Iterate
- More phases? → Loop to step 2
- All complete? → Suggest `/vp-docs`
### 7. Handle Blockers
At any control point, offer:
1. Fix and retry
2. Skip (with reason)
3. Rollback
4. Stop autonomous mode
Display progress summary on stop.
</process>
## Adapter Compatibility
### AskUserQuestion Tool (ENH-059)
Control-point prompts use `AskUserQuestion` on Claude Code (terminal).
| Adapter | Interactive Prompts | Notes |
|---------|---------------------|-------|
| Claude Code (terminal) | ✅ `AskUserQuestion` — **REQUIRED** at control points | Preload schema via ToolSearch first |
| Cursor / Codex / Copilot / Antigravity | ❌ Text fallback | Plain numbered list |
**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:**
- Control point decisions (retry / skip / rollback / stop — Step 7)
<success_criteria>
- [ ] Phases executed in dependency order
- [ ] Tasks tracked with git tags
- [ ] Quality gates enforced
- [ ] State updated after each task
- [ ] Checkpoints created for recovery
- [ ] CHANGELOG updated for features/fixes
- [ ] Clean stop with summary on pause/error
</success_criteria>
### Skill Context Execution (FEAT-020)
At session start, vp-auto reads `PROJECT-CONTEXT.md ## Skills` (locked by `/vp-crystallize`
Step 1E) and builds a `SKILL_CONTEXT_MAP`.
During each task:
- Required skills whose phases match the current task's phase are **silently** injected into the execution context
- Best practices from matched skills appear as a silent checklist before implementation
- Task output records `skills_applied: [id@version, ...]`
**No prompts are shown** — all skill decisions are locked at crystallize time.
`/vp-auto` is execution-only for skills.
Install skills: `vp-tools install-skill <source>`
Lock decisions: `/vp-crystallize` Step 1E
Docs: `docs/user/features/skill-registry.md`
Sections and files
Listed in source order.
sections -> Invocation Banner → Version Update Check (ENH-072) → Persona Context Injection (ENH-073) → A. Skill Invocation → B. User Prompting → C. Tool Usage
terms -> first · If exit code = 1 · If exit code = 0 or command unavailable · Suppression rules · Additional tools (ENH-099) · /vp-auto · default lane · implementing
files/cmd -> {latest_version} · {current} · {adapter_id} · --no-update-check · config.json · update.check: false · update_check_done · ## User Persona
body sha256 -> a4bf14c4751f
Invocation Banner
Output this banner as the first thing on every invocation — before questions, work, or any other output: </greeting> <version_check>
Version Update Check (ENH-072)
After displaying the greeting banner, run: If exit code = 1 (update available — new version printed to stdout): Display notice banner before any other output: 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).Persona Context Injection (ENH-073)
At skill start, run: Inject the output as
## User Personacontext before any task execution. Silent if command unavailable or errors. </persona_context> <adapter id="claude-code">B. User Prompting
Prompt user conversationally with numbered list options at control points.
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) Additional tools (ENH-099):