viepilot 1.0.0

package/lib/cli-shared.cjs

@@ -0,0 +1,108 @@
+/**
+ * Shared CLI helpers: validation + project root resolution (unit-tested, coverage-targeted).
+ * Keeps bin/vp-tools.cjs thinner so Jest can enforce meaningful coverage thresholds.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const VIEPILOT_DIR = '.viepilot';
+
+function findProjectRoot() {
+  let dir = process.cwd();
+  while (dir !== path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, VIEPILOT_DIR))) {
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+  return null;
+}
+
+const validators = {
+  isPositiveInteger(value, name = 'value') {
+    const num = parseInt(value, 10);
+    if (isNaN(num) || num < 1) {
+      return { valid: false, error: `${name} must be a positive integer`, hint: `Got: "${value}"` };
+    }
+    return { valid: true, value: num };
+  },
+
+  isValidStatus(value) {
+    const validStatuses = ['not_started', 'in_progress', 'done', 'skipped', 'blocked'];
+    if (!validStatuses.includes(value)) {
+      return {
+        valid: false,
+        error: `Invalid status: "${value}"`,
+        hint: `Valid statuses: ${validStatuses.join(', ')}`,
+      };
+    }
+    return { valid: true, value };
+  },
+
+  isValidTimestampFormat(value) {
+    const validFormats = ['iso', 'date', 'full'];
+    if (!validFormats.includes(value)) {
+      return {
+        valid: false,
+        error: `Invalid timestamp format: "${value}"`,
+        hint: `Valid formats: ${validFormats.join(', ')}`,
+      };
+    }
+    return { valid: true, value };
+  },
+
+  isValidBumpType(value) {
+    const validTypes = ['major', 'minor', 'patch'];
+    if (!validTypes.includes(value)) {
+      return {
+        valid: false,
+        error: `Invalid bump type: "${value}"`,
+        hint: `Valid types: ${validTypes.join(', ')}`,
+      };
+    }
+    return { valid: true, value };
+  },
+
+  isNonEmptyString(value, name = 'value') {
+    if (!value || typeof value !== 'string' || value.trim() === '') {
+      return { valid: false, error: `${name} cannot be empty` };
+    }
+    return { valid: true, value: value.trim() };
+  },
+
+  requireProjectRoot() {
+    const root = findProjectRoot();
+    if (!root) {
+      return {
+        valid: false,
+        error: 'No ViePilot project found',
+        hint: 'Run this command from a directory containing .viepilot/',
+      };
+    }
+    return { valid: true, value: root };
+  },
+};
+
+function levenshteinDistance(a, b) {
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+  const matrix = [];
+  for (let i = 0; i <= b.length; i++) matrix[i] = [i];
+  for (let j = 0; j <= a.length; j++) matrix[0][j] = j;
+  for (let i = 1; i <= b.length; i++) {
+    for (let j = 1; j <= a.length; j++) {
+      matrix[i][j] = b.charAt(i - 1) === a.charAt(j - 1)
+        ? matrix[i - 1][j - 1]
+        : Math.min(matrix[i - 1][j - 1] + 1, matrix[i][j - 1] + 1, matrix[i - 1][j] + 1);
+    }
+  }
+  return matrix[b.length][a.length];
+}
+
+module.exports = {
+  VIEPILOT_DIR,
+  findProjectRoot,
+  validators,
+  levenshteinDistance,
+};

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "viepilot",
+  "version": "1.0.0",
+  "description": "**Autonomous Vibe Coding Framework / Bộ khung phát triển tự động có kiểm soát**",
+  "main": "index.js",
+  "bin": {
+    "viepilot": "bin/viepilot.cjs"
+  },
+  "directories": {
+    "doc": "docs",
+    "example": "examples"
+  },
+  "scripts": {
+    "test": "jest",
+    "test:coverage": "jest --coverage",
+    "test:watch": "jest --watch",
+    "lint:cli": "node --check bin/vp-tools.cjs && node --check bin/viepilot.cjs",
+    "verify:release": "npm run lint:cli && npm test && npm pack --dry-run",
+    "prepublishOnly": "npm run verify:release",
+    "smoke:published": "node scripts/smoke-published.cjs",
+    "release:checklist": "node scripts/release-checklist.cjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/0-CODE/viepilot.git"
+  },
+  "keywords": [
+    "cursor",
+    "claude",
+    "ai",
+    "autonomous",
+    "developer-tools",
+    "cli"
+  ],
+  "author": "",
+  "license": "MIT",
+  "type": "commonjs",
+  "files": [
+    "bin/",
+    "lib/",
+    "skills/",
+    "workflows/",
+    "templates/",
+    "ui-components/",
+    "install.sh",
+    "dev-install.sh",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "docs/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "bugs": {
+    "url": "https://github.com/0-CODE/viepilot/issues"
+  },
+  "homepage": "https://github.com/0-CODE/viepilot#readme",
+  "jest": {
+    "testEnvironment": "node",
+    "testMatch": [
+      "<rootDir>/tests/unit/**/*.test.js",
+      "<rootDir>/tests/integration/**/*.test.js"
+    ],
+    "testTimeout": 30000,
+    "collectCoverageFrom": [
+      "lib/cli-shared.cjs"
+    ],
+    "coverageThreshold": {
+      "global": {
+        "lines": 80
+      }
+    }
+  },
+  "devDependencies": {
+    "jest": "^30.3.0"
+  }
+}

package/skills/vp-audit/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: vp-audit
+description: "Audit state, docs drift, and stack best-practice compliance — works on any project"
+version: 0.3.0
+---
+
+<cursor_skill_adapter>
+## A. Skill Invocation
+- Skill được gọi khi user mention `vp-audit`, `/vp-audit`, "audit", "kiểm tra", "check docs"
+- Treat all user text after the skill mention as `{{VP_ARGS}}`
+
+## B. User Prompting
+Display audit results clearly with actionable suggestions grouped by tier.
+
+## C. Tool Usage
+Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`, `WebFetch`, `Subagent`
+</cursor_skill_adapter>
+
+<objective>
+Audit ViePilot project state và documentation để phát hiện drift.
+Hoạt động trên **bất kỳ project nào** đang dùng ViePilot (Java, Node, Python, v.v.).
+Auto-detect nếu đang chạy trong viepilot framework repo để thêm framework-specific checks.
+
+**Tier 1 — ViePilot State Consistency (mọi project):**
+- `.viepilot/TRACKER.md` current state vs `.viepilot/phases/*/PHASE-STATE.md`
+- `.viepilot/ROADMAP.md` phase status vs PHASE-STATE.md
+- `.viepilot/HANDOFF.json` vs TRACKER.md (resume-state consistency)
+- Git tags `vp-p{N}-complete` vs completed phases in PHASE-STATE.md
+
+**Tier 2 — Project Documentation Drift (mọi project):**
+- `README.md` version vs `package.json` / `pom.xml` / `pyproject.toml`
+- `CHANGELOG.md` vs recent git commits
+- Placeholder URLs trong `docs/` (`your-org`, `YOUR_USERNAME`, v.v.)
+- Features mới (từ phases gần đây) chưa có documentation
+
+**Tier 3 — Stack Best Practices + Code Quality (mọi project, theo stack detect được):**
+- Detect stacks liên quan từ context/project manifests
+- So khớp code patterns với stack-specific Do/Don't + anti-patterns
+- Severity findings: `critical` / `high` / `medium` / `low` kèm file/module mapping
+- Fallback research bằng `WebSearch` + `WebFetch` khi cache stack thiếu/yếu
+- Sinh output guardrails/checklist để `vp-auto` tái sử dụng trong preflight
+
+**Tier 4 — Framework Integrity (chỉ khi detect viepilot framework repo):**
+- Auto-detect: `skills/vp-*/SKILL.md` tồn tại → là viepilot framework repo
+- `ARCHITECTURE.md` counts vs `skills/`, `workflows/`, CLI thực tế
+- `README.md` viepilot-specific badges (version, skills-N, workflows-N)
+- `docs/skills-reference.md` sections vs `skills/` directory
+
+**Output:**
+- Báo cáo theo 4 tiers, mỗi tier có status riêng
+- Auto-fix option theo tier
+- Suggestions cho complex gaps
+- `vp-auto` compatible guardrails contract theo từng stack
+</objective>
+
+<execution_context>
+@$HOME/.cursor/viepilot/workflows/audit.md
+</execution_context>
+
+<context>
+Optional flags:
+- `--framework` : Force Tier 3 framework checks (even if not auto-detected)
+- `--project`   : Force project-only mode — skip Tier 3 framework checks
+- `--fix`       : Auto-fix all detected issues
+- `--report`    : Generate report file at `.viepilot/audit-report.md`
+- `--silent`    : Only output if issues found
+- `--tier1`     : Run Tier 1 (state consistency) only
+- `--tier2`     : Run Tier 2 (docs drift) only
+- `--tier3`     : Run Tier 3 (framework integrity) only
+</context>
+
+<process>
+Execute workflow from `@$HOME/.cursor/viepilot/workflows/audit.md`
+
+### Quick Summary
+
+**Step 0**: Detect project type (viepilot framework vs user project)
+
+**Step 1 — Tier 1**: ViePilot State Consistency
+```bash
+# TRACKER.md vs PHASE-STATE.md
+# ROADMAP.md vs PHASE-STATE.md
+# HANDOFF.json vs TRACKER.md
+# Git tags vs completed phases
+```
+
+**Step 2 — Tier 2**: Project Documentation Drift
+```bash
+# Detect version: package.json / pom.xml / pyproject.toml
+# README.md version mention
+# CHANGELOG.md vs recent commits
+# Placeholder URLs in docs/
+```
+
+**Step 3 — Tier 3**: Stack Best Practices + Code Quality
+```bash
+# detect stack(s), load cache summary first
+# if missing/weak cache -> run WebSearch/WebFetch fallback
+# emit severity findings + guardrails contract for vp-auto
+```
+
+**Step 4 — Tier 4**: Framework Integrity (conditional)
+
+**Step 5**: Generate full report
+
+**Step 6**: Auto-fix (if requested)
+</process>
+
+<auto_hook>
+## Integration with /vp-auto
+
+After each phase complete, /vp-auto should:
+1. Run quick audit (--silent mode, Tier 1 + Tier 2 only)
+2. If issues found → warn user
+3. Offer to fix before continuing
+
+```
+Phase 2 complete!
+
+⚠️ Audit found 2 issues:
+   Tier 1: ROADMAP.md phase 2 not marked ✅
+   Tier 2: README.md version not updated
+
+Fix now? (y/n)
+```
+</auto_hook>
+
+<success_criteria>
+- [ ] Runs on any project using ViePilot (Java, Node, Python, etc.) without errors
+- [ ] Tier 1 state consistency checks work for all projects
+- [ ] Tier 2 docs drift checks work for all project types (detects version from package.json/pom.xml/pyproject.toml)
+- [ ] Tier 3 stack checks run for detected stacks with severity output
+- [ ] Tier 3 supports research fallback when stack cache is missing/weak
+- [ ] Tier 4 only runs when `skills/vp-*/SKILL.md` detected OR `--framework` flag used
+- [ ] Results clearly labeled by tier
+- [ ] `--framework` flag forces Tier 4 checks
+- [ ] `--project` flag skips Tier 4 checks
+- [ ] Auto-fix applies correct fixes per tier
+- [ ] No mention of `skills/`, `workflows/`, `vp-tools.cjs` in Tier 1 or Tier 2 output for user projects
+</success_criteria>

package/skills/vp-auto/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: vp-auto
+description: "Autonomous execution loop với control points và recovery"
+version: 0.2.1
+---
+
+<cursor_skill_adapter>
+## 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 với numbered list options tại control points.
+
+## C. Tool Usage
+Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`, `WebFetch`, `Subagent`
+
+## D. Subagent Spawning
+Use `Task(subagent_type="generalPurpose", ...)` for parallel execution.
+</cursor_skill_adapter>
+
+<objective>
+Autonomous execution của project phases. Cho mỗi 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
+
+**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 `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
+
+**After:** Project built, or paused for user intervention.
+</objective>
+
+<execution_context>
+@$HOME/.cursor/viepilot/workflows/autonomous.md
+</execution_context>
+
+<context>
+Optional flags:
+- `--from N` : Start từ phase N
+- `--phase N` : Chỉ chạy phase N
+- `--fast` : Skip optional verifications
+- `--dry-run` : Plan only, no execution
+
+No extra args: chỉ nghĩa các cờ trên **tắt** — **không** phải rule “dừng bắt buộc sau mỗi task”. Trong chat, một turn thường ~một task; tiếp tục bằng lượt sau hoặc `/vp-auto` lại. Doc: `docs/user/features/autonomous-mode.md`.
+</context>
+
+<process>
+Execute workflow from `@$HOME/.cursor/viepilot/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 `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: `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>
+
+<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>

package/skills/vp-brainstorm/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: vp-brainstorm
+description: "Brainstorm session để thu thập ý tưởng, quyết định cho dự án"
+version: 0.3.0
+---
+
+<cursor_skill_adapter>
+## A. Skill Invocation
+- Skill được gọi khi user mention `vp-brainstorm`, `/vp-brainstorm`, hoặc yêu cầu "brainstorm"
+- Treat all user text after the skill mention as `{{VP_ARGS}}`
+
+## B. User Prompting
+Prompt user conversationally với numbered list options.
+
+## C. Tool Usage
+Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`, `WebFetch`, `Subagent`
+</cursor_skill_adapter>
+
+<objective>
+Thu thập ý tưởng, requirements, quyết định kiến trúc cho dự án thông qua interactive Q&A.
+
+Hỗ trợ:
+- Tạo session mới
+- Tiếp tục session cũ
+- Xem lại session trước đó
+- Landing page layout discovery (hỏi thêm để chốt bố cục)
+- In-session research (research ngay trong phiên brainstorm theo yêu cầu)
+- UI Direction mode: tạo/cập nhật HTML prototype + notes trong `.viepilot/ui-direction/{session-id}/`
+
+**Creates/Updates:**
+- `docs/brainstorm/session-{YYYY-MM-DD}.md`
+
+**After:** Ready for `/vp-crystallize`
+</objective>
+
+<execution_context>
+@$HOME/.cursor/viepilot/workflows/brainstorm.md
+</execution_context>
+
+<context>
+Optional flags:
+- `--new` : Force tạo session mới
+- `--continue` : Tiếp tục session gần nhất
+- `--list` : Liệt kê các sessions
+- `--landing` : Ưu tiên flow Landing Page layout discovery
+- `--research` : Bật proactive research suggestions trong phiên
+- `--ui` : Bật UI Direction mode (live HTML/CSS direction artifacts)
+</context>
+
+<process>
+Execute workflow from `@$HOME/.cursor/viepilot/workflows/brainstorm.md`
+
+Key steps:
+1. Detect existing sessions
+2. Ask user intent (new/continue/review)
+3. Load context if continuing
+4. Run interactive Q&A với topic-based structure
+5. Nếu topic là landing page: hỏi thêm bố cục + tham khảo `21st.dev` để đề xuất section/components
+6. Nếu topic cần UI/UX: tạo/cập nhật UI Direction artifacts (`index.html`, `style.css`, `notes.md`) trong `.viepilot/ui-direction/{session-id}/`
+7. Nếu user yêu cầu research hoặc cần làm rõ quyết định: research ngay trong session và quay lại topic
+8. Save session with structured format (bao gồm research notes + UI direction references khi có)
+9. Suggest next action: `/vp-crystallize`
+</process>
+
+<success_criteria>
+- [ ] Session file created/updated với đầy đủ sections
+- [ ] Decisions documented với rationale
+- [ ] Open questions listed
+- [ ] Action items captured
+- [ ] Landing page topics include explicit layout selection questions
+- [ ] 21st.dev references included when relevant
+- [ ] Research can be executed inside the same brainstorm session
+- [ ] UI Direction artifacts created/updated when UI mode is active
+- [ ] Next steps suggested
+</success_criteria>