vp-auto

name	vp-auto
description	Autonomous execution loop with control points and recovery
version	0.2.2

## 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)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

## Version Update Check (ENH-072)

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-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:

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>

## 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).

## 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

## 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.

## 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

## 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 <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>

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

<execution_context> @$HOME/{envToolDir}/workflows/autonomous.md </execution_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)”.

Execute workflow from `@$HOME/{envToolDir}/workflows/autonomous.md`

1. Initialize

# 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

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

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.

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