viepilot 1.0.0

package/docs/user/quick-start.md

@@ -0,0 +1,157 @@
+# Quick Start Guide
+
+Bắt đầu với ViePilot trong 5 phút.
+
+## What is ViePilot?
+
+ViePilot là framework giúp bạn phát triển phần mềm với AI một cách **có hệ thống và kiểm soát**. Thay vì chat với AI và copy-paste code, ViePilot tổ chức toàn bộ dự án thành phases, tasks, và checkpoints — với AI thực thi từng bước một.
+
+```
+Bạn: Mô tả ý tưởng
+  ↓
+ViePilot: Tạo roadmap, phases, tasks
+  ↓
+AI: Tự động code từng task
+  ↓
+Bạn: Review, approve, hoặc rollback
+```
+
+---
+
+## Step 1: Install
+
+```bash
+git clone https://github.com/0-CODE/viepilot
+cd viepilot
+npx @0/viepilot install
+```
+
+Chọn profile cài đặt trong wizard:
+- `claude-code`
+- `cursor-agent`
+- `cursor-ide`
+
+Non-interactive:
+```bash
+npx @0/viepilot install --target cursor-agent --yes
+```
+
+Verify:
+```bash
+viepilot --list-targets
+vp-tools help
+# Hiển thị targets + ViePilot CLI Tools
+```
+
+---
+
+## Step 2: Create a New Project
+
+```bash
+mkdir my-project && cd my-project
+git init
+```
+
+Mở thư mục trong **Cursor IDE**.
+
+---
+
+## Step 3: Brainstorm
+
+Trong Cursor Chat:
+
+```
+/vp-brainstorm Build a REST API for managing tasks
+```
+
+ViePilot sẽ hỏi bạn về:
+- Tech stack (Node.js? Python? Java?)
+- Features cần thiết
+- Constraints (deadline, team size, etc.)
+
+Trả lời tự nhiên — không cần format đặc biệt.
+
+Nếu dự án thiên về UI/UX:
+
+```text
+/vp-brainstorm --ui
+```
+
+Workflow sẽ duy trì direction artifacts tại `.viepilot/ui-direction/{session-id}/`.
+
+---
+
+## Step 4: Crystallize
+
+```
+/vp-crystallize
+```
+
+ViePilot tạo `.viepilot/` directory với:
+- `ROADMAP.md` — Phases và tasks
+- `TRACKER.md` — Progress tracking
+- `ARCHITECTURE.md` — System design
+- `SYSTEM-RULES.md` — Coding standards
+
+---
+
+## Step 5: Run Autonomous Mode
+
+```
+/vp-auto
+```
+
+ViePilot sẽ:
+1. Đọc phase đầu tiên (hoặc phase tiếp theo) từ ROADMAP.md / TRACKER
+2. Tạo git checkpoint tag
+3. Implement từng task
+4. Verify acceptance criteria
+5. Commit và cập nhật state; lặp task kế hoặc phase kế
+
+**Can thiệp của bạn:** Tại **control points** (lỗi, conflict, bước manual trong task, menu retry/skip). **Không arg** trên `/vp-auto` không có nghĩa bị “khóa” dừng sau mỗi task trong spec — nhưng trong chat một lượt AI thường xử lý một task; muốn chạy tiếp, gọi lại `/vp-auto` hoặc nhắc tiếp. Dùng `/vp-auto --fast` nếu muốn **bỏ qua verify tùy chọn** (ít dừng hơn). Chi tiết: [Autonomous mode](features/autonomous-mode.md).
+
+---
+
+## Step 6: Check Progress
+
+```
+/vp-status
+```
+
+Hiển thị:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ VIEPILOT ► STATUS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ Phase 1: Setup         [██████████] 100% ✅
+ Phase 2: Core API      [████░░░░░░]  40% 🔄
+ Phase 3: Tests         [░░░░░░░░░░]   0% ⏳
+
+ Overall:               [████░░░░░░]  47%
+```
+
+---
+
+## Common Commands
+
+| Command | When to Use |
+|---------|-------------|
+| `/vp-brainstorm` | Bắt đầu project mới hoặc feature mới |
+| `/vp-crystallize` | Sau brainstorm, tạo artifacts |
+| `/vp-auto` | Chạy autonomous execution |
+| `/vp-status` | Xem progress dashboard |
+| `/vp-pause` | Dừng và lưu state |
+| `/vp-resume` | Tiếp tục từ lần dừng |
+| `/vp-request --feature` | Thêm feature mới |
+| `/vp-rollback` | Quay lại checkpoint trước |
+| `/vp-debug` | Debug issue có hệ thống |
+
+---
+
+## Next Steps
+
+- [Skills Reference](../skills-reference.md) — Chi tiết tất cả commands
+- [Advanced Usage](../advanced-usage.md) — Power user features
+- [Troubleshooting](../troubleshooting.md) — Common issues
+- [Examples](../../examples/) — 3 example projects

package/docs/videos/01-installation.md

@@ -0,0 +1,113 @@
+# Video Script: ViePilot Installation
+
+**Target duration**: 5 minutes  
+**Audience**: Developers new to ViePilot  
+**Tool**: Terminal + Cursor IDE
+
+---
+
+## 0:00 — Introduction
+
+> "Welcome to ViePilot — the autonomous vibe coding framework. In this video,
+> we'll get ViePilot installed and running your first project in under 5 minutes."
+
+Show: ViePilot README on GitHub
+
+---
+
+## 0:30 — Prerequisites
+
+> "You'll need: Git, Node.js 18+, and Cursor IDE with Claude enabled."
+
+```bash
+node --version   # v18+
+git --version    # any recent version
+```
+
+---
+
+## 1:00 — Installation
+
+> "Clone the repository and run the install script."
+
+```bash
+git clone https://github.com/0-CODE/viepilot
+cd viepilot
+./install.sh
+```
+
+> "The installer copies skills to `~/.cursor/skills/` and workflows to
+> `~/.cursor/viepilot/`. You'll see confirmation for each file."
+
+Show: installer output with ✔ checkmarks
+
+---
+
+## 1:45 — Verify Installation
+
+> "Let's verify everything is set up correctly."
+
+```bash
+vp-tools help
+```
+
+Show: help output listing all 13 commands
+
+> "And check that skills are accessible in Cursor:"
+
+Show: Cursor → open a project → type `/vp-` to see skill completions
+
+---
+
+## 2:30 — Create Your First Project
+
+> "Navigate to your project directory and initialize ViePilot."
+
+```bash
+cd ~/my-project
+/vp-brainstorm
+```
+
+Show: Cursor Chat with /vp-brainstorm producing a brainstorm template
+
+---
+
+## 3:30 — Run Crystallize
+
+> "Now crystallize the brainstorm into executable artifacts."
+
+```bash
+/vp-crystallize
+```
+
+Show: Cursor generating `.viepilot/` directory structure with TRACKER.md, ROADMAP.md
+
+---
+
+## 4:15 — Start Autonomous Mode
+
+> "With your project structure ready, kick off autonomous execution:"
+
+```bash
+/vp-auto
+```
+
+Show: vp-auto banner displaying project name, phase, progress bar
+
+---
+
+## 4:45 — Summary
+
+> "In just 5 minutes you've installed ViePilot and initialized your first project.
+> Next video: Creating your first feature with `/vp-brainstorm` in depth."
+
+Show: `/vp-status` dashboard with progress bars
+
+---
+
+## Recording Notes
+
+- Record at 1920×1080
+- Use large terminal font (18pt+)
+- Pause 2 seconds after each command before showing output
+- Add captions for accessibility

package/docs/videos/02-first-project.md

@@ -0,0 +1,132 @@
+# Video Script: Your First ViePilot Project
+
+**Target duration**: 8 minutes  
+**Audience**: Developers who completed installation  
+**Tool**: Cursor IDE with a blank Node.js project
+
+---
+
+## 0:00 — What We're Building
+
+> "We're building a simple REST API with ViePilot guiding us through every step —
+> from brainstorm to deployed code."
+
+Show: final project structure in file tree
+
+---
+
+## 0:30 — Start Brainstorm
+
+> "Open your project in Cursor and start a brainstorm session."
+
+```
+/vp-brainstorm Build a REST API for managing todo items
+```
+
+Show: ViePilot asking clarifying questions about tech stack, features, constraints
+
+---
+
+## 1:30 — Answer Questions
+
+> "ViePilot gathers requirements through conversation. Answer naturally."
+
+Demo conversation:
+- Tech stack: Node.js + Express + SQLite
+- Features: CRUD todos, tags, due dates
+- Constraints: No auth needed for MVP
+
+---
+
+## 2:30 — Crystallize
+
+> "Now convert the brainstorm into your project plan."
+
+```
+/vp-crystallize
+```
+
+Show: `.viepilot/` directory being created with:
+- `ROADMAP.md` (phases)
+- `TRACKER.md` (current state)
+- `HANDOFF.json` (machine state)
+
+---
+
+## 3:30 — Review the Roadmap
+
+> "Let's see what ViePilot planned for us."
+
+```bash
+cat .viepilot/ROADMAP.md
+```
+
+Show: 3 phases — Project Setup, Core API, Testing
+
+---
+
+## 4:00 — Start Autonomous Execution
+
+> "One command to start building:"
+
+```
+/vp-auto
+```
+
+Show: progress banner, then watch Phase 1 tasks execute:
+- Creating project structure
+- Installing dependencies
+- Setting up Express
+
+---
+
+## 5:30 — Check Progress
+
+> "At any point, check where you are:"
+
+```
+/vp-status
+```
+
+Show: visual dashboard with progress bars and current task
+
+---
+
+## 6:00 — Phase Complete
+
+> "When Phase 1 completes, ViePilot creates a checkpoint tag and moves on."
+
+Show: git log with `vp-p1-complete` tag
+
+---
+
+## 6:30 — Pause and Resume
+
+> "Need to step away? Pause cleanly:"
+
+```
+/vp-pause
+```
+
+> "When you're back:"
+
+```
+/vp-resume
+```
+
+Show: context restored with same phase and task
+
+---
+
+## 7:30 — Summary
+
+> "That's the core ViePilot flow: brainstorm → crystallize → auto.
+> Next: Advanced features with `/vp-debug` and `/vp-rollback`."
+
+---
+
+## Recording Notes
+
+- Use a fresh project directory
+- Pre-configure with working Node.js and git initialized
+- Keep Cursor Chat visible throughout

package/docs/videos/03-autonomous-mode.md

@@ -0,0 +1,147 @@
+# Video Script: Mastering Autonomous Mode
+
+**Target duration**: 7 minutes  
+**Audience**: Developers comfortable with ViePilot basics  
+**Tool**: Cursor IDE with an existing ViePilot project
+
+---
+
+## 0:00 — Overview
+
+> "Autonomous mode is ViePilot's superpower. In this video, we cover advanced
+> techniques: control points, recovery, parallel tasks, and quality gates."
+
+---
+
+## 0:30 — Control Points
+
+> "vp-auto pauses automatically when it needs your input."
+
+Show: a blocker scenario — conflicting files detected
+
+```
+⚠ Phase 2 (Database): Issue Encountered
+Conflicting migration files detected.
+
+Options:
+1. Fix and retry
+2. Skip task
+3. Rollback task
+4. Stop autonomous mode
+```
+
+> "Enter '1' to auto-fix, '2' to skip, '3' to rollback, '4' to stop."
+
+---
+
+## 1:30 — Rollback
+
+> "Made a mistake? Roll back to any checkpoint."
+
+```
+/vp-rollback
+```
+
+Show: list of available checkpoints (git tags)
+
+```
+1. vp-p2-t3      (Phase 2 Task 3 start)
+2. vp-p2-t2-done (Phase 2 Task 2 complete)
+3. vp-p2-t1-done (Phase 2 Task 1 complete)
+```
+
+> "Select a checkpoint to restore."
+
+---
+
+## 2:30 — Debug Mode
+
+> "When something goes wrong and you need to track down why:"
+
+```
+/vp-debug investigate: API tests failing after database migration
+```
+
+Show: vp-debug creating a debug session, tracking hypothesis attempts
+
+---
+
+## 3:30 — Running Specific Phases
+
+> "Skip ahead or repeat a specific phase:"
+
+```
+/vp-auto --phase 3
+```
+
+> "Or start from a specific phase:"
+
+```
+/vp-auto --from 2
+```
+
+---
+
+## 4:00 — Fast Mode
+
+> "Skip optional verifications for speed (not recommended for production):"
+
+```
+/vp-auto --fast
+```
+
+---
+
+## 4:30 — Dry Run
+
+> "Preview what would happen without executing:"
+
+```
+/vp-auto --dry-run
+```
+
+Show: plan displayed without any file changes
+
+---
+
+## 5:00 — Quality Gates
+
+> "vp-auto enforces quality at every step. Here's what it checks:"
+
+```
+quality_gate:
+  ✅ acceptance_criteria_met
+  ✅ automated_tests_pass
+  ✅ no_lint_errors
+```
+
+> "If any gate fails, you get a control point — not a silent failure."
+
+---
+
+## 5:30 — Monitoring with vp-status
+
+> "Keep a second terminal open with status:"
+
+```
+/vp-status
+```
+
+Show: updating dashboard as phases complete
+
+---
+
+## 6:30 — Summary
+
+> "Key takeaways: control points keep you in charge, rollback makes mistakes safe,
+> and quality gates ensure every commit is clean. ViePilot's autonomy has guardrails."
+
+Show: final project with all phases complete, `vp-p4-complete` tag in git log
+
+---
+
+## Recording Notes
+
+- Use a project with a deliberate error in phase 2 to demonstrate control points
+- Show the git log with checkpoint tags prominently
+- Keep terminal font large for readability

package/install.sh

@@ -0,0 +1,144 @@
+#!/bin/bash
+
+# ViePilot Installation Script
+# Installs ViePilot skills and tools to Cursor/Claude environment
+
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Get script directory
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Default installation paths
+CURSOR_SKILLS_DIR="$HOME/.cursor/skills"
+VIEPILOT_DIR="$HOME/.cursor/viepilot"
+AUTO_YES="${VIEPILOT_AUTO_YES:-0}"
+INSTALL_PROFILE="${VIEPILOT_INSTALL_PROFILE:-cursor-ide}"
+ADD_PATH_CHOICE="${VIEPILOT_ADD_PATH:-0}"
+
+echo -e "${BLUE}"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo " VIEPILOT INSTALLER"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo -e "${NC}"
+
+# Check if running from viepilot directory
+if [ ! -f "$SCRIPT_DIR/README.md" ] || [ ! -d "$SCRIPT_DIR/skills" ]; then
+    echo -e "${RED}Error: Please run this script from the viepilot directory${NC}"
+    exit 1
+fi
+
+echo -e "${YELLOW}Installation paths:${NC}"
+echo "  Skills: $CURSOR_SKILLS_DIR"
+echo "  ViePilot: $VIEPILOT_DIR"
+echo "  Profile: $INSTALL_PROFILE"
+echo ""
+
+# Confirm installation
+if [ "$AUTO_YES" != "1" ]; then
+    read -p "Continue with installation? (y/n) " -n 1 -r
+    echo
+    if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+        echo "Installation cancelled."
+        exit 0
+    fi
+else
+    echo "Auto-yes enabled via VIEPILOT_AUTO_YES=1"
+fi
+
+echo ""
+echo -e "${BLUE}Installing...${NC}"
+
+# Create directories
+echo "  Creating directories..."
+mkdir -p "$CURSOR_SKILLS_DIR"
+mkdir -p "$VIEPILOT_DIR/workflows"
+mkdir -p "$VIEPILOT_DIR/templates/project"
+mkdir -p "$VIEPILOT_DIR/templates/phase"
+mkdir -p "$VIEPILOT_DIR/bin"
+mkdir -p "$VIEPILOT_DIR/lib"
+mkdir -p "$VIEPILOT_DIR/ui-components"
+
+# Install skills
+echo "  Installing skills..."
+for skill_dir in "$SCRIPT_DIR/skills"/*; do
+    if [ -d "$skill_dir" ]; then
+        skill_name=$(basename "$skill_dir")
+        cp -r "$skill_dir" "$CURSOR_SKILLS_DIR/"
+        echo "    ✓ $skill_name"
+    fi
+done
+
+# Install workflows
+echo "  Installing workflows..."
+cp -r "$SCRIPT_DIR/workflows"/* "$VIEPILOT_DIR/workflows/"
+echo "    ✓ workflows"
+
+# Install templates
+echo "  Installing templates..."
+cp -r "$SCRIPT_DIR/templates/project"/* "$VIEPILOT_DIR/templates/project/"
+cp -r "$SCRIPT_DIR/templates/phase"/* "$VIEPILOT_DIR/templates/phase/"
+echo "    ✓ templates"
+
+# Install stock UI components
+echo "  Installing stock UI components..."
+if [ -d "$SCRIPT_DIR/ui-components" ]; then
+    cp -r "$SCRIPT_DIR/ui-components"/* "$VIEPILOT_DIR/ui-components/"
+    echo "    ✓ ui-components"
+fi
+
+# Install CLI tools
+echo "  Installing CLI tools..."
+cp "$SCRIPT_DIR/bin/vp-tools.cjs" "$VIEPILOT_DIR/bin/"
+cp "$SCRIPT_DIR/bin/viepilot.cjs" "$VIEPILOT_DIR/bin/"
+cp "$SCRIPT_DIR/lib/cli-shared.cjs" "$VIEPILOT_DIR/lib/"
+chmod +x "$VIEPILOT_DIR/bin/vp-tools.cjs"
+chmod +x "$VIEPILOT_DIR/bin/viepilot.cjs"
+echo "    ✓ vp-tools.cjs + viepilot.cjs + lib/cli-shared.cjs"
+
+# Create symlink in PATH (optional)
+echo ""
+if [ "$AUTO_YES" != "1" ]; then
+    read -p "Add vp-tools + viepilot to PATH? (creates symlink in /usr/local/bin) (y/n) " -n 1 -r
+    echo
+else
+    REPLY=$([ "$ADD_PATH_CHOICE" = "1" ] && echo "y" || echo "n")
+fi
+if [[ $REPLY =~ ^[Yy]$ ]]; then
+    if [ -w "/usr/local/bin" ]; then
+        ln -sf "$VIEPILOT_DIR/bin/vp-tools.cjs" "/usr/local/bin/vp-tools"
+        ln -sf "$VIEPILOT_DIR/bin/viepilot.cjs" "/usr/local/bin/viepilot"
+        echo "    ✓ vp-tools + viepilot added to PATH"
+    else
+        echo -e "${YELLOW}    Note: Need sudo to create symlink${NC}"
+        sudo ln -sf "$VIEPILOT_DIR/bin/vp-tools.cjs" "/usr/local/bin/vp-tools"
+        sudo ln -sf "$VIEPILOT_DIR/bin/viepilot.cjs" "/usr/local/bin/viepilot"
+        echo "    ✓ vp-tools + viepilot added to PATH"
+    fi
+fi
+
+echo ""
+echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo -e "${GREEN} INSTALLATION COMPLETE ✓${NC}"
+echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo ""
+echo "Installed:"
+echo "  - Skills: $CURSOR_SKILLS_DIR/vp-*"
+echo "  - Workflows: $VIEPILOT_DIR/workflows/"
+echo "  - Templates: $VIEPILOT_DIR/templates/"
+echo "  - CLI: $VIEPILOT_DIR/bin/vp-tools.cjs"
+echo ""
+echo "Quick Start:"
+echo "  1. Open your project in Cursor"
+echo "  2. Run: /vp-brainstorm"
+echo "  3. After brainstorm: /vp-crystallize"
+echo "  4. Start coding: /vp-auto"
+echo ""
+echo "Documentation: $SCRIPT_DIR/docs/getting-started.md"
+echo ""