viepilot 1.0.0

package/docs/dev/contributing.md

@@ -0,0 +1,195 @@
+# Contributing to ViePilot
+
+Hướng dẫn đóng góp cho ViePilot framework.
+
+## Development Workflow
+
+1. Fork repository trên GitHub
+2. Clone fork của bạn:
+   ```bash
+   git clone https://github.com/0-CODE/viepilot
+   cd viepilot
+   ```
+3. Cài đặt development mode:
+   ```bash
+   ./dev-install.sh
+   ```
+4. Tạo branch cho feature/fix:
+   ```bash
+   git checkout -b feat/my-new-skill
+   # hoặc
+   git checkout -b fix/cli-validation-bug
+   ```
+5. Implement changes
+6. Chạy tests:
+   ```bash
+   npm test
+   ```
+7. Commit theo Conventional Commits
+8. Submit Pull Request
+
+---
+
+## Branching Strategy
+
+| Branch | Purpose |
+|--------|---------|
+| `main` | Stable releases |
+| `develop` | Integration branch |
+| `feat/{name}` | New features |
+| `fix/{name}` | Bug fixes |
+| `docs/{name}` | Documentation |
+
+---
+
+## Commit Message Format
+
+ViePilot dùng **Conventional Commits**:
+
+```
+{type}({scope}): {description}
+
+[optional body]
+
+[optional footer]
+```
+
+### Types
+
+| Type | When to Use |
+|------|-------------|
+| `feat` | New skill, workflow, command, template |
+| `fix` | Bug fix |
+| `docs` | Documentation only |
+| `style` | Formatting, no code change |
+| `refactor` | Code change, no new feature/fix |
+| `test` | Adding or updating tests |
+| `chore` | Maintenance (CI, deps, etc.) |
+
+### Scopes
+
+| Scope | For |
+|-------|-----|
+| `skill` | `skills/` changes |
+| `workflow` | `workflows/` changes |
+| `template` | `templates/` changes |
+| `cli` | `bin/` changes |
+| `docs` | `docs/` changes |
+| `test` | `tests/` changes |
+| `ci` | `.github/` changes |
+
+### Examples
+
+```bash
+feat(skill): add vp-notify for Slack notifications
+fix(workflow): correct state tracking in autonomous mode
+docs(readme): update installation instructions
+test(cli): add unit tests for version command
+chore(ci): add Node 22 to test matrix
+```
+
+---
+
+## Adding a New Skill
+
+1. Bắt đầu từ template:
+   ```bash
+   cp -r templates/skill-template skills/vp-myskill
+   ```
+
+2. Edit `skills/vp-myskill/SKILL.md`:
+   ```yaml
+   ---
+   name: vp-myskill
+   description: "Short description"
+   version: 0.1.0
+   ---
+   ```
+
+3. Tạo workflow tương ứng:
+   ```bash
+   cp templates/workflow-template.md workflows/myskill.md
+   ```
+
+4. Cập nhật `ARCHITECTURE.md` với skill mới
+
+5. Chạy audit để verify:
+   ```
+   /vp-audit
+   ```
+
+6. Viết tests trong `tests/unit/ai-provider-compat.test.js` sẽ tự động pick up skill mới
+
+---
+
+## Adding a CLI Command
+
+1. Mở `bin/vp-tools.cjs`
+
+2. Thêm command vào `commands` object:
+   ```javascript
+   mycommand: (args) => {
+     const projectCheck = validators.requireProjectRoot();
+     validateArgs([projectCheck]);
+     // implementation
+     console.log(formatSuccess('Done'));
+     console.log(JSON.stringify({ result: 'value' }));
+   },
+   ```
+
+3. Thêm help entry vào `commandHelp` object trong `commands.help`
+
+4. Viết unit tests trong `tests/unit/validators.test.js`
+
+5. Cập nhật `ARCHITECTURE.md` CLI count
+
+---
+
+## Code Standards
+
+### File Structure Rules
+
+- Skills: YAML frontmatter + XML-like tags (xem [architecture.md](architecture.md))
+- Workflows: `<purpose>`, `<process>`, `<step name="...">`, `<success_criteria>`
+- Templates: `{{PLACEHOLDER}}` format (ALL_CAPS)
+- CLI: CommonJS, no external dependencies
+
+### Comment Standards
+
+```javascript
+// ✅ DO: Explain WHY
+// Prevents race condition when multiple workers claim same job
+async function claimJob(jobId) { ... }
+
+// ❌ DON'T: State the obvious
+const count = 0; // Initialize count to zero
+```
+
+### Quality Gates
+
+Trước khi commit:
+- [ ] No syntax errors (`node --check bin/vp-tools.cjs`)
+- [ ] Tests pass (`npm test`)
+- [ ] Follows file structure rules
+- [ ] ARCHITECTURE.md updated nếu thêm skill/workflow/command
+
+---
+
+## Pull Request Process
+
+1. Ensure tests pass: `npm test`
+2. Update `CHANGELOG.md` nếu có feature/fix mới
+3. Bump version nếu cần: `vp-tools version bump minor`
+4. Submit PR với description rõ ràng
+5. CI sẽ chạy tự động (Node 18/20/22 matrix)
+6. Một reviewer sẽ review trong 48h
+
+---
+
+## Testing Requirements
+
+- Unit tests cho mọi CLI command mới
+- AI compatibility tests tự động chạy cho skills mới
+- Coverage phải ≥ 80%
+
+Xem [testing.md](testing.md) để biết chi tiết.

package/docs/dev/deployment.md

@@ -0,0 +1,204 @@
+# Deployment Guide
+
+ViePilot là một local framework — không có server để deploy. "Deployment" ở đây nghĩa là **distribution**: đưa ViePilot đến máy của users.
+
+## Distribution Methods
+
+### Method 1: npm distribution (recommended for users)
+
+```bash
+npx @0/viepilot install
+```
+
+Direct target mode:
+
+```bash
+npx @0/viepilot install --target cursor-agent --yes
+```
+
+### Method 2: Git Clone + Install Script (maintainers/dev)
+
+```bash
+git clone https://github.com/0-CODE/viepilot
+cd viepilot
+./install.sh
+```
+
+`install.sh` copies:
+- `skills/vp-*/` → `~/.cursor/skills/`
+- `workflows/` → `~/.cursor/viepilot/workflows/`
+- `templates/` → `~/.cursor/viepilot/templates/`
+- `bin/vp-tools.cjs` → `~/.local/bin/vp-tools`
+
+### Method 3: Development Mode
+
+Dùng khi đang develop ViePilot itself — symlinks thay vì copy:
+
+```bash
+./dev-install.sh
+```
+
+Changes to `skills/`, `workflows/`, `bin/` phản ánh ngay lập tức mà không cần reinstall.
+
+---
+
+## Environments
+
+| Environment | Purpose | Notes |
+|-------------|---------|-------|
+| Local dev | Developing ViePilot | Use `dev-install.sh` |
+| User machine | Using ViePilot | Use `install.sh` |
+| CI | Running tests | `npm ci && npm test` |
+
+---
+
+## Versioning
+
+ViePilot dùng SemVer, tracked trong `TRACKER.md`:
+
+```bash
+# Check current version
+vp-tools version get
+
+# Bump for new features
+vp-tools version bump minor
+
+# Bump for bug fixes
+vp-tools version bump patch
+```
+
+Release tags (use current framework version from `vp-tools version get`):
+```bash
+git tag v0.8.2
+git push origin v0.8.2
+```
+
+---
+
+## npm Publish Workflow
+
+### Preflight Checklist
+
+```bash
+npm run release:checklist
+npm run verify:release
+```
+
+This verifies:
+- CLI syntax (`vp-tools.cjs`, `viepilot.cjs`)
+- test suite pass
+- publish tarball preview (`npm pack --dry-run`)
+
+### Manual Publish
+
+```bash
+npm publish --access public
+```
+
+Required:
+- npm account with publish permission for package `viepilot`
+- `NPM_TOKEN` configured (for CI publish)
+
+### CI Publish (GitHub Actions)
+
+Workflow file: `.github/workflows/release-npm.yml`
+
+Triggers:
+- release published
+- manual workflow dispatch
+
+Secret required:
+- `NPM_TOKEN` (repository secret)
+
+### Post-publish Smoke Verification
+
+```bash
+npm run smoke:published
+# or explicitly:
+npx viepilot --help
+npx @0/viepilot install --help
+```
+
+Optional version pin:
+
+```bash
+NPM_VERSION=1.0.0 npm run smoke:published
+```
+
+### Rollback / Mitigation
+
+If a bad release is published:
+
+```bash
+# Deprecate bad version
+npm deprecate viepilot@<bad_version> "Deprecated due to release issue; use latest stable version"
+
+# Publish hotfix version after fix
+npm version patch
+npm publish --access public
+```
+
+For dist-tag mitigation:
+
+```bash
+npm dist-tag add viepilot@<stable_version> latest
+```
+
+---
+
+## Updating ViePilot
+
+Users cập nhật bằng cách pull và reinstall:
+
+```bash
+cd /path/to/viepilot
+git pull
+./install.sh
+```
+
+---
+
+## CI/CD Pipeline
+
+GitHub Actions tại `.github/workflows/ci.yml`:
+
+```
+Push/PR → test (Node 18/20/22) → coverage → lint
+```
+
+**Jobs**:
+1. **test**: Runs unit + integration tests on 3 Node versions
+2. **coverage**: Generates lcov report, enforces >80% threshold
+3. **lint**: Syntax check for CLI and test files
+
+**Artifacts**: Coverage report (7-day retention)
+
+---
+
+## Makefile Targets
+
+```bash
+make help       # Show available targets
+make test       # Run test suite
+make install    # Install to ~/.cursor/
+make dev        # Development mode install
+make clean      # Remove installed files
+```
+
+---
+
+## Monitoring
+
+ViePilot không có runtime monitoring. "Health" được kiểm tra bằng:
+
+```bash
+# Check installation
+vp-tools help
+
+# Check project state
+vp-tools init
+vp-tools progress
+
+# Check documentation sync
+/vp-audit
+```

package/docs/dev/getting-started.md

@@ -0,0 +1,16 @@
+# Getting Started (Developer)
+
+The canonical **install + first-run** guide lives here:
+
+➜ **[Getting Started](../getting-started.md)**
+
+That guide covers clone, `./install.sh`, `/vp-brainstorm`, `/vp-crystallize`, and `/vp-auto`.
+
+**Repository:** [https://github.com/0-CODE/viepilot](https://github.com/0-CODE/viepilot)
+
+Once you are set up, continue with:
+
+- [Architecture](architecture.md)
+- [CLI Reference](cli-reference.md)
+- [Contributing](contributing.md)
+- [Testing](testing.md)

package/docs/dev/testing.md

@@ -0,0 +1,171 @@
+# Testing Guide
+
+ViePilot có 3 loại tests, tổng cộng **194 tests**.
+
+## Test Structure
+
+```
+tests/
+├── unit/
+│   ├── validators.test.js          # 30 tests — CLI command behavior
+│   └── ai-provider-compat.test.js  # 142 tests — Skill/workflow structure
+└── integration/
+    └── workflow.test.js            # 22 tests — End-to-end workflows
+```
+
+## Running Tests
+
+```bash
+# All tests
+npm test
+
+# With coverage report
+npm run test:coverage
+
+# Watch mode (re-runs on file change)
+npm run test:watch
+
+# Specific suite
+npx jest tests/unit/validators.test.js
+npx jest tests/integration/workflow.test.js
+
+# Verbose output
+npx jest --verbose
+```
+
+## Test Suites
+
+### Unit Tests — `tests/unit/validators.test.js`
+
+Tests CLI commands via subprocess spawning (black-box approach).
+
+**Covers**:
+- `current-timestamp` — all formats, `--raw` flag, invalid format rejection
+- `task-status` — all valid statuses, invalid input rejection
+- `commit` — message validation, `--files` flag
+- `version` — get, bump (patch/minor/major), invalid type rejection
+- `help` — general and command-specific help
+- `init` — project root detection, failure outside project
+- `progress` — phase data structure
+- `clean --dry-run` — non-destructive behavior
+- Unknown command — Levenshtein suggestion
+
+**Helper**: `extractJson(stdout)` — strips ANSI codes, finds last JSON block
+
+### AI Provider Compatibility — `tests/unit/ai-provider-compat.test.js`
+
+Validates skill and workflow files conform to structure required by AI providers.
+
+**Covers**:
+- All 13 skill files have required XML-like sections
+- `<cursor_skill_adapter>` with Skill Invocation + Tool Usage
+- `<execution_context>` or inline `<process>` (both valid)
+- Referenced workflows exist on disk
+- `<success_criteria>` has at least one checkbox
+- All 11 workflow files have `<purpose>`, `<process>`, named `<step>`, `<success_criteria>`
+- Steps are properly closed (open count == close count)
+- UTF-8 validity, no binary content
+- Naming conventions (vp-{name}, kebab-case)
+- Portable paths (no hardcoded `/Users/` in execution_context)
+- Template `{{PLACEHOLDER}}` format
+
+### Integration Tests — `tests/integration/workflow.test.js`
+
+End-to-end tests using isolated temp project directories.
+
+**Covers**:
+- Project initialization workflow
+- Task lifecycle: `not_started → in_progress → done`
+- Version management sequence
+- Commit command structure
+- Timestamp consistency across formats
+- `save-state` persistence (HANDOFF.json updated)
+- `clean --dry-run` safety
+- Error handling and graceful failures
+
+**Setup**: Each test suite creates a fresh temp dir with minimal `.viepilot/` structure.
+
+## Writing New Tests
+
+### Unit Test Pattern
+
+```javascript
+const { spawnSync } = require('child_process');
+const CLI = path.join(__dirname, '../../bin/vp-tools.cjs');
+
+function run(args, cwd = PROJECT_ROOT) {
+  return spawnSync('node', [CLI, ...args], {
+    cwd,
+    encoding: 'utf8',
+    env: { ...process.env, NO_COLOR: '1' },
+  });
+}
+
+test('my command returns expected output', () => {
+  const { stdout, code } = run(['my-command', 'arg']);
+  expect(code).toBe(0);
+  const data = extractJson(stdout);
+  expect(data.field).toBe('expected');
+});
+```
+
+### Integration Test Pattern
+
+```javascript
+function createTempProject() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'vp-test-'));
+  // Create minimal .viepilot/ structure
+  fs.mkdirSync(path.join(dir, '.viepilot'), { recursive: true });
+  // Write TRACKER.md, ROADMAP.md, HANDOFF.json
+  return dir;
+}
+
+describe('My workflow', () => {
+  let projectDir;
+  beforeAll(() => { projectDir = createTempProject(); });
+  afterAll(() => { fs.rmSync(projectDir, { recursive: true }); });
+
+  test('workflow step works', () => {
+    const { stdout, code } = run(['command'], projectDir);
+    expect(code).toBe(0);
+  });
+});
+```
+
+### AI Compatibility Test Pattern
+
+New skills are automatically picked up by `getSkillFiles()` — no test changes needed. The existing test suite validates all `skills/vp-*/SKILL.md` files.
+
+## Coverage
+
+```bash
+npm run test:coverage
+```
+
+Coverage is collected from `bin/vp-tools.cjs`.
+
+**Threshold**: ≥ 80% line coverage (enforced in CI).
+
+**Report formats**: text (console) + lcov (HTML, uploaded as CI artifact).
+
+## CI Integration
+
+Tests run automatically on every push and PR via GitHub Actions:
+
+```yaml
+# .github/workflows/ci.yml
+jobs:
+  test:
+    strategy:
+      matrix:
+        node-version: [18, 20, 22]
+    steps:
+      - run: npx jest tests/unit/ --no-coverage
+      - run: npx jest tests/integration/ --no-coverage
+
+  coverage:
+    steps:
+      - run: npx jest --coverage
+```
+
+Coverage artifact is available for 7 days after each run.

package/docs/dev/ui-components-library.md

@@ -0,0 +1,36 @@
+# UI Components Library
+
+Workflow curation UI components để tái sử dụng xuyên dự án.
+
+## Stores
+- Global: `~/.viepilot/ui-components/`
+- Local project: `.viepilot/ui-components/`
+
+## Skill
+Sử dụng `/vp-ui-components` để:
+- ingest component references (21st.dev prompt/link/snippet)
+- phân loại taxonomy
+- lưu artifacts chuẩn hóa
+- cập nhật index cho tìm kiếm lại
+
+## Artifact contract
+
+```text
+{store}/{category}/{component-id}/
+  README.md
+  SOURCE.md
+  component.html
+  component.css
+  metadata.json
+```
+
+## metadata.json tối thiểu
+- `id`
+- `category`
+- `source`
+- `tags`
+- `stack_notes`
+- `status` (`raw`, `adapted`, `approved`)
+
+## Stock components
+ViePilot cài sẵn stock set trong `ui-components/` để dùng làm nguyên liệu thô ban đầu.