viepilot 1.0.0

package/dev-install.sh

@@ -0,0 +1,109 @@
+#!/bin/bash
+
+# ViePilot Development Installation Script
+# Creates symlinks to development version for instant updates
+
+set -e
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+# Get script directory (project root)
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CURSOR_SKILLS_DIR="$HOME/.cursor/skills"
+VIEPILOT_DIR="$HOME/.cursor/viepilot"
+AUTO_YES="${VIEPILOT_AUTO_YES:-0}"
+INSTALL_PROFILE="${VIEPILOT_INSTALL_PROFILE:-cursor-agent}"
+
+echo -e "${BLUE}"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo " VIEPILOT DEV INSTALLER"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo -e "${NC}"
+
+echo -e "${YELLOW}Development mode installation${NC}"
+echo "  Source: $SCRIPT_DIR"
+echo "  Target: $CURSOR_SKILLS_DIR, $VIEPILOT_DIR"
+echo "  Profile: $INSTALL_PROFILE"
+echo ""
+
+# Confirm
+if [ "$AUTO_YES" != "1" ]; then
+    read -p "This will replace existing installation with symlinks. Continue? (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}Removing old installations...${NC}"
+
+# Remove old skill installations
+for skill in "$CURSOR_SKILLS_DIR"/vp-*/; do
+    if [ -d "$skill" ] || [ -L "$skill" ]; then
+        rm -rf "$skill"
+        echo "  Removed: $(basename "$skill")"
+    fi
+done
+
+# Remove old viepilot installation
+if [ -d "$VIEPILOT_DIR" ] || [ -L "$VIEPILOT_DIR" ]; then
+    rm -rf "$VIEPILOT_DIR"
+    echo "  Removed: viepilot/"
+fi
+
+echo ""
+echo -e "${BLUE}Creating skill symlinks...${NC}"
+
+# Create skill symlinks
+mkdir -p "$CURSOR_SKILLS_DIR"
+for skill in "$SCRIPT_DIR"/skills/vp-*/; do
+    skill_name=$(basename "$skill")
+    ln -s "$skill" "$CURSOR_SKILLS_DIR/$skill_name"
+    echo -e "  ${GREEN}✓${NC} $skill_name"
+done
+
+echo ""
+echo -e "${BLUE}Creating viepilot symlinks...${NC}"
+
+# Create viepilot directory and symlinks
+mkdir -p "$VIEPILOT_DIR"
+ln -s "$SCRIPT_DIR/workflows" "$VIEPILOT_DIR/workflows"
+ln -s "$SCRIPT_DIR/templates" "$VIEPILOT_DIR/templates"
+ln -s "$SCRIPT_DIR/bin" "$VIEPILOT_DIR/bin"
+ln -s "$SCRIPT_DIR/lib" "$VIEPILOT_DIR/lib"
+ln -s "$SCRIPT_DIR/ui-components" "$VIEPILOT_DIR/ui-components"
+
+echo -e "  ${GREEN}✓${NC} workflows"
+echo -e "  ${GREEN}✓${NC} templates"
+echo -e "  ${GREEN}✓${NC} bin"
+echo -e "  ${GREEN}✓${NC} lib"
+echo -e "  ${GREEN}✓${NC} ui-components"
+
+# Count installed
+SKILL_COUNT=$(ls -d "$CURSOR_SKILLS_DIR"/vp-*/ 2>/dev/null | wc -l | tr -d ' ')
+WORKFLOW_COUNT=$(ls "$SCRIPT_DIR"/workflows/*.md 2>/dev/null | wc -l | tr -d ' ')
+
+echo ""
+echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo -e "${GREEN} DEV INSTALLATION COMPLETE ✓${NC}"
+echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo ""
+echo "Installed (via symlinks):"
+echo "  - Skills: $SKILL_COUNT"
+echo "  - Workflows: $WORKFLOW_COUNT"
+echo ""
+echo -e "${YELLOW}Development mode enabled!${NC}"
+echo "Any changes to $SCRIPT_DIR will be reflected immediately."
+echo ""
+echo "To switch back to stable installation:"
+echo "  ./install.sh"
+echo ""

package/docs/README.md

@@ -0,0 +1,125 @@
+# ViePilot Documentation
+
+> Autonomous Vibe Coding Framework — phát triển phần mềm với AI có hệ thống và kiểm soát.
+
+## Quick Links
+
+| | |
+|--|--|
+| 🚀 [Quick Start](user/quick-start.md) | Bắt đầu trong 5 phút |
+| 🔧 [CLI Reference](dev/cli-reference.md) | `vp-tools` commands |
+| 🏗️ [Architecture](dev/architecture.md) | System design |
+| 🔌 [API / interfaces](api/README.md) | No HTTP API — CLI & file contracts |
+| ❓ [FAQ](user/faq.md) | Common questions |
+| 🐛 [Troubleshooting](troubleshooting.md) | Common issues |
+
+---
+
+## Documentation Index
+
+### User Guide
+
+| Document | Description |
+|----------|-------------|
+| [Quick Start](user/quick-start.md) | Install, brainstorm, crystallize, auto — 5 min guide |
+| [FAQ](user/faq.md) | Frequently asked questions |
+
+#### Features
+
+| Feature | Document |
+|---------|----------|
+| Autonomous Mode | [autonomous-mode.md](user/features/autonomous-mode.md) (flags, `--fast`, lượt chat) |
+| UI Direction Mode | [ui-direction.md](user/features/ui-direction.md) |
+| Checkpoint Recovery | [checkpoint-recovery.md](user/features/checkpoint-recovery.md) |
+| Debug Mode | [debug-mode.md](user/features/debug-mode.md) |
+
+---
+
+### API & machine interface
+
+| Document | Description |
+|----------|-------------|
+| [API index](api/README.md) | ViePilot has no REST stack; links to CLI/file model |
+| [REST / CLI model](api/rest-api.md) | Framework integration surface |
+| [GraphQL](api/graphql-schema.md) | N/A for this repo |
+| [Kafka](api/kafka-events.md) | N/A for this repo |
+| [WebSocket](api/websocket-api.md) | N/A for this repo |
+
+---
+
+### Developer Guide
+
+| Document | Description |
+|----------|-------------|
+| [Getting Started](getting-started.md) | Installation and first steps |
+| [Getting Started (dev entry)](dev/getting-started.md) | Short link into dev guide |
+| [CLI Reference](dev/cli-reference.md) | All 13 `vp-tools` commands with examples |
+| [Architecture](dev/architecture.md) | System layers, data flow, design decisions |
+| [UI Components Library](dev/ui-components-library.md) | Curation taxonomy, storage contract, reuse flow |
+| [Contributing](dev/contributing.md) | How to add skills, workflows, CLI commands |
+| [Testing](dev/testing.md) | Test structure, running tests, writing new tests |
+| [Deployment](dev/deployment.md) | Distribution, versioning, CI/CD |
+
+---
+
+### Skills Reference
+
+| Document | Description |
+|----------|-------------|
+| [Skills Reference](skills-reference.md) | All 13 skills with flags and examples |
+| [Advanced Usage](advanced-usage.md) | Power user features and patterns |
+
+---
+
+### Examples
+
+| Example | Stack | Description |
+|---------|-------|-------------|
+| [web-app](../examples/web-app/) | Next.js, SQLite | Todo web application |
+| [api-service](../examples/api-service/) | Express, PostgreSQL, JWT | REST API with auth |
+| [cli-tool](../examples/cli-tool/) | Node.js (no deps) | CLI application |
+
+---
+
+### Video Tutorials
+
+| Video | Duration | Description |
+|-------|----------|-------------|
+| [01 — Installation](videos/01-installation.md) | 5 min | Install ViePilot and first run |
+| [02 — First Project](videos/02-first-project.md) | 8 min | Build a REST API end-to-end |
+| [03 — Autonomous Mode](videos/03-autonomous-mode.md) | 7 min | Control points, rollback, debug |
+
+---
+
+### Reference
+
+| Document | Description |
+|----------|-------------|
+| [Troubleshooting](troubleshooting.md) | 15+ common issues with solutions |
+| [CHANGELOG](../CHANGELOG.md) | Version history |
+| [CONTRIBUTING](../CONTRIBUTING.md) | Contribution guidelines |
+
+---
+
+## Skills Quick Reference
+
+| Skill | Trigger | Purpose |
+|-------|---------|---------|
+| `/vp-brainstorm` | "brainstorm", "ý tưởng" | Gather requirements |
+| `/vp-crystallize` | "crystallize", "tạo artifacts" | Generate project structure |
+| `/vp-auto` | "auto", "vibe", "chạy tự động" | Autonomous execution |
+| `/vp-pause` | "pause", "dừng" | Save state and pause |
+| `/vp-resume` | "resume", "tiếp tục" | Restore and continue |
+| `/vp-status` | "status", "tiến độ" | Progress dashboard |
+| `/vp-request` | "request", "feature", "bug" | Add feature/bug |
+| `/vp-ui-components` | "ui components", "21st.dev" | Curate and reuse UI component library |
+| `/vp-evolve` | "evolve", "milestone mới" | New milestone |
+| `/vp-docs` | "docs", "documentation" | Generate docs |
+| `/vp-task` | "task", "manual" | Manual task control |
+| `/vp-debug` | "debug", "investigate" | Debug issues |
+| `/vp-rollback` | "rollback", "revert" | Checkpoint recovery |
+| `/vp-audit` | "audit", "kiểm tra" | Documentation sync |
+
+---
+
+*Last updated: 2026-03-31 — ViePilot framework v0.10.0 (see `.viepilot/TRACKER.md`); guided NPX installer flow added.*

package/docs/advanced-usage.md

@@ -0,0 +1,366 @@
+# ViePilot Advanced Usage Guide
+
+Power user features and patterns for experienced ViePilot users.
+
+---
+
+## 1. Autonomous Mode Flags
+
+### `--from N` — Start from a specific phase
+
+Skip completed phases and jump directly to phase N:
+
+```
+/vp-auto --from 3
+```
+
+Useful when you've manually completed earlier phases or fixed a blocker.
+
+---
+
+### `--phase N` — Run only one phase
+
+Useful for re-running a specific phase after changes:
+
+```
+/vp-auto --phase 2
+```
+
+Warning: Dependencies must be satisfied (phases before N must be complete).
+
+---
+
+### `--fast` — Skip optional verifications
+
+Skips manual review prompts and optional checks. Use for rapid iteration:
+
+```
+/vp-auto --fast
+```
+
+Not recommended for final releases — quality gates are important.
+
+---
+
+### `--dry-run` — Preview without executing
+
+See exactly what would happen without writing any files:
+
+```
+/vp-auto --dry-run
+```
+
+Output shows: phases to run, tasks in each, verification steps.
+
+---
+
+## 2. Mid-Project Changes
+
+### Adding a feature (`/vp-request --feature`)
+
+Add a new feature requirement without disrupting the current phase:
+
+```
+/vp-request --feature Add export to PDF functionality
+```
+
+ViePilot will:
+1. Create a new phase (e.g., Phase 3.5) inserted between current phases
+2. Add it to ROADMAP.md
+3. On next `/vp-auto`, include it in the execution queue
+
+---
+
+### Reporting a bug (`/vp-request --bug`)
+
+```
+/vp-request --bug Login form submits but user is not authenticated
+```
+
+ViePilot creates a bug phase with investigation and fix tasks.
+
+---
+
+### Evolving to a new milestone (`/vp-evolve`)
+
+When M1 is complete and you want to start M2:
+
+```
+/vp-evolve Add real-time collaboration features
+```
+
+ViePilot:
+1. Archives the current milestone
+2. Runs `/vp-brainstorm` for the new feature set
+3. Creates M2 phases in ROADMAP.md
+4. Updates TRACKER.md
+
+---
+
+## 3. Checkpoint Management
+
+### Listing all checkpoints
+
+```bash
+vp-tools checkpoints
+```
+
+Output:
+```
+ViePilot Checkpoints
+
+  TAG                         COMMIT    DATE
+  ─────────────────────────────────────────────────────
+  ✅ vp-p3-complete           a1b2c3d   2026-03-30 14:00
+  ✔️  vp-p3-t4-done            b2c3d4e   2026-03-30 13:45
+  ✔️  vp-p3-t3-done            c3d4e5f   2026-03-30 13:20
+  📌 vp-p3-t3                  d4e5f6g   2026-03-30 12:00
+  ...
+
+  Total: 14 checkpoints
+```
+
+---
+
+### Rolling back to a checkpoint
+
+```
+/vp-rollback
+```
+
+Interactive selection:
+```
+Select checkpoint to restore:
+1. vp-p3-t4-done  (Phase 3 Task 4 complete)
+2. vp-p3-t3-done  (Phase 3 Task 3 complete)
+3. vp-p3-complete (Phase 3 complete)
+```
+
+Rollback uses `git revert` — safe, non-destructive, preserves history.
+
+---
+
+### Saving state manually
+
+Before a risky operation:
+
+```bash
+vp-tools save-state
+```
+
+This updates `HANDOFF.json` with:
+- Current git HEAD
+- Branch name
+- Node.js version
+- Precise timestamp
+
+---
+
+## 4. Debugging Workflows
+
+### Starting a debug session
+
+```
+/vp-debug investigate: API returns 500 after adding auth middleware
+```
+
+ViePilot creates a structured debug session:
+
+```
+.viepilot/debug/
+└── DEBUG-001.md
+    ├── Problem Statement
+    ├── Hypotheses (tracked)
+    ├── Attempts (with results)
+    └── Resolution (when found)
+```
+
+---
+
+### Continuing a debug session
+
+```
+/vp-debug continue
+```
+
+Loads the last open debug session and continues from where you left off — even across context resets.
+
+---
+
+### Closing a debug session
+
+```
+/vp-debug close: Fixed by removing duplicate middleware in app.js
+```
+
+Marks the session resolved and logs the fix in CHANGELOG.md.
+
+---
+
+## 5. State Management CLI
+
+### Progress overview
+
+```bash
+vp-tools progress
+```
+
+Returns JSON with phase completion percentages — useful for scripts.
+
+---
+
+### Version management
+
+```bash
+# Get current version
+vp-tools version get
+
+# Bump for new features (Phase complete)
+vp-tools version bump minor
+
+# Bump for bug fixes only
+vp-tools version bump patch
+
+# Major breaking change
+vp-tools version bump major
+```
+
+---
+
+### Checking for conflicts
+
+Before running `/vp-auto` on a dirty working directory:
+
+```bash
+vp-tools conflicts
+```
+
+Shows: modified, untracked, deleted, staged files. Resolve before continuing.
+
+---
+
+### Cleaning generated state
+
+Safe reset of HANDOFF.json (not code files):
+
+```bash
+# Preview what would be removed
+vp-tools clean --dry-run
+
+# With confirmation prompt
+vp-tools clean
+
+# Force (no confirmation)
+vp-tools clean --force
+```
+
+---
+
+## 6. Custom Skill Creation
+
+Create your own ViePilot skill:
+
+```
+skills/vp-mycustom/SKILL.md
+```
+
+Required structure:
+
+```markdown
+---
+name: vp-mycustom
+description: "What my skill does"
+version: 0.1.0
+---
+
+<cursor_skill_adapter>
+## A. Skill Invocation
+- Triggered by: /vp-mycustom
+
+## B. Tool Usage
+Use Cursor tools: Shell, Read, Write
+</cursor_skill_adapter>
+
+<objective>
+What this skill accomplishes.
+</objective>
+
+<execution_context>
+@$HOME/.cursor/viepilot/workflows/mycustom.md
+</execution_context>
+
+<success_criteria>
+- [ ] Task completed correctly
+</success_criteria>
+```
+
+Then create `workflows/mycustom.md` with the implementation steps.
+
+---
+
+## 7. CI/CD Integration
+
+### Running ViePilot state checks in CI
+
+```yaml
+# .github/workflows/viepilot-check.yml
+- name: Check project state
+  run: |
+    node bin/vp-tools.cjs init
+    node bin/vp-tools.cjs conflicts
+```
+
+---
+
+### Version gate on PRs
+
+Block merges if version wasn't bumped:
+
+```yaml
+- name: Version check
+  run: |
+    VERSION=$(node bin/vp-tools.cjs version get --raw 2>/dev/null || echo "0.0.0")
+    # Set EXPECTED to `.viepilot/TRACKER.md` "Current Version" when pinning a release
+    EXPECTED="0.8.2"
+    if [ "$VERSION" != "$EXPECTED" ]; then
+      echo "Version mismatch: got $VERSION, expected $EXPECTED"
+      exit 1
+    fi
+```
+
+---
+
+## 8. Multi-Project Usage
+
+Use ViePilot across multiple projects simultaneously:
+
+```bash
+# Project A
+cd ~/project-a
+/vp-status   # shows project A state
+
+# Project B (completely independent state)
+cd ~/project-b
+/vp-status   # shows project B state
+```
+
+Each project has its own `.viepilot/` directory — fully isolated.
+
+---
+
+## Context Loading Strategy
+
+For long sessions or large codebases, follow AI-GUIDE.md's minimal context strategy:
+
+```
+Minimal (quick tasks):
+  AI-GUIDE.md + TRACKER.md + specific file
+
+Standard (coding tasks):
+  Above + ROADMAP.md + SYSTEM-RULES.md
+
+Full (architecture decisions):
+  Above + ARCHITECTURE.md + PROJECT-CONTEXT.md
+```
+
+Never load the entire codebase — be selective.

package/docs/api/README.md

@@ -0,0 +1,12 @@
+# API documentation (ViePilot framework)
+
+ViePilot repository is a **skill + workflow framework**, not an HTTP/GraphQL/Kafka service. There is **no network API surface** in this repo.
+
+| Document | Purpose |
+|----------|---------|
+| [REST / machine interface](rest-api.md) | How automation interacts with the project (CLI, files, skills) |
+| [GraphQL](graphql-schema.md) | Not applicable |
+| [Kafka](kafka-events.md) | Not applicable |
+| [WebSocket](websocket-api.md) | Not applicable |
+
+For command-line behavior, see [CLI Reference](../dev/cli-reference.md).

package/docs/api/graphql-schema.md

@@ -0,0 +1,5 @@
+# GraphQL schema — ViePilot framework
+
+**Not applicable.** The ViePilot framework repo does not expose a GraphQL API.
+
+Use this file in **consumer projects** that generate schema docs from code or `.viepilot/schemas/`.

package/docs/api/kafka-events.md

@@ -0,0 +1,5 @@
+# Kafka events — ViePilot framework
+
+**Not applicable.** The ViePilot framework repo does not define Kafka topics or producers/consumers.
+
+For event-driven systems built with ViePilot, document topics here after you add `.viepilot/schemas/kafka-topics.yaml` (or equivalent).

package/docs/api/rest-api.md

@@ -0,0 +1,19 @@
+# REST API — ViePilot framework
+
+## Summary
+
+This repository **does not ship a REST HTTP API**. Integration is **file-based** and **CLI-assisted**:
+
+- **Skills** (`skills/vp-*/SKILL.md`) define how an AI assistant runs workflows.
+- **Workflows** (`workflows/*.md`) encode step-by-step processes.
+- **CLI** (`bin/vp-tools.cjs`) manages version, state, checkpoints, and helpers.
+
+## Primary interfaces
+
+| Interface | Location | Description |
+|-----------|----------|-------------|
+| CLI | [CLI Reference](../dev/cli-reference.md) | 13 commands (`init`, `version`, `progress`, …) |
+| State | `.viepilot/HANDOFF.json`, `.viepilot/TRACKER.md` | Resume and progress |
+| Contracts | Templates under `templates/` | Generated project docs |
+
+If you are documenting an **application built with ViePilot**, add OpenAPI or schema files under that app (e.g. `.viepilot/schemas/`) and extend this folder with real endpoints.

package/docs/api/websocket-api.md

@@ -0,0 +1,5 @@
+# WebSocket API — ViePilot framework
+
+**Not applicable.** The ViePilot framework repo does not implement WebSocket servers.
+
+Real-time stacks using ViePilot should document connection URLs, auth, and event payloads in this file for their own services.