Vibe DevKit

Bộ công cụ + rules + workflow biến ý tưởng thành code có GATE — ép AI behave như senior engineer: clarify trước, spec testable, architecture có trade-off, task nhỏ, prove bằng test.

Tương thích Cursor, Claude Code, Codex (qua AGENTS.md).

v0.2.3 — Hướng dẫn sử dụng · Thêm preset · Changelog

Pipeline

Idea → Clarify → Spec → Architecture → Tasks → Code → Review/Test
 G0      G1       G2        G3           G4      G5        G6

| Phase | Slash command | Artifact | Gate | |-------|---------------|----------|------| | 0 Idea | /vibe-idea | idea.md | G0 | | 1 Clarify | /vibe-clarify | clarify.md | G1 | | 2 Spec | /vibe-spec | spec.md | G2 | | 3 Architecture | /vibe-architecture | architecture.md | G3 | | 4 Tasks | /vibe-tasks | tasks.md | G4 | | 5 Code | /vibe-code | code + tasks.md ✓ | G5 | | 6 Review | /vibe-review | review.md | G6 |

Artifacts: docs/vibe/NNN-{slug}/ · Chi tiết gate: workflow/PIPELINE.md

Ngoài pipeline: /vibe-status (tiến độ) · /vibe-find-skill (tìm skill bổ sung — sau GATE 2, không thay phase)

Cài đặt

# npx (khuyến nghị)
npx @hamanhtuan/vibe-devkit install --preset nextjs .
npx @hamanhtuan/vibe-devkit validate --strict

# global CLI
npm install -g @hamanhtuan/vibe-devkit
vibe install --preset laravel-vue ~/projects/my-app

# clone + install.sh
git clone <repo> ~/vibe-devkit && cd ~/vibe-devkit
./install.sh --preset flutter-supabase /path/to/project

Yêu cầu: Node.js ≥ 18 · Python 3.10+ · Bash

Quick start (đội dev)

# 1. Tạo feature + set active
vibe new checkout --title "Checkout Flow"

# 2. Pipeline trong Cursor (theo thứ tự)
/vibe-clarify docs/vibe/001-checkout
/vibe-spec docs/vibe/001-checkout
/vibe-architecture docs/vibe/001-checkout
/vibe-tasks docs/vibe/001-checkout
/vibe-code docs/vibe/001-checkout
/vibe-review docs/vibe/001-checkout

# 3. Trước merge PR
vibe validate --strict

Gold standard: docs/vibe/000-example-user-login/ — artifact mẫu đủ 7 phase.

Hướng dẫn chi tiết: docs/GUIDE.md — workflow từng bước, troubleshooting, FAQ.

Nhiều feature song song:

vibe list-features          # (active) marker
vibe set-active 002-billing

CLI

vibe new <slug> [--title "Name"]   # tạo folder + set active_feature
vibe set-active <folder>           # đổi feature đang làm
vibe validate [slug] [--strict]    # kiểm gate (CI: exit 1 nếu fail)
vibe trace AC-001 [-f feature]     # trace AC → tasks → review
vibe list-features
vibe list-presets
vibe gate-check "implement now"    # dùng bởi Cursor hook

vibe.config.yaml

| Key | Mô tả | |-----|-------| | active_feature | Feature cho hooks + gate-check (vd. docs/vibe/001-checkout) | | gate_mode | strict (default) · normal · relaxed | | require_human_approval | Bắt status: approved trên spec/architecture | | commands.test / lint / typecheck | Lệnh phase Code & Review | | artifacts_dir | Mặc định docs/vibe |

Slash commands

| Command | Khi dùng | |---------|----------| | /vibe-idea … /vibe-review | 7 phase pipeline | | /vibe-status | Xem gate / blockers | | /vibe-find-skill | Tìm skill ecosystem — sau spec.md, không skip pipeline |

Skills

Core (mọi install)

| Skill | Nguồn | Vai trò | |-------|-------|---------| | vibe-* | DevKit | Pipeline phases | | frontend-design | anthropics | UI/design — architecture & code | | find-skills | vercel-labs | Discovery — qua /vibe-find-skill | | vibe-find-skill | DevKit | Wrapper: preset → .vibe → npx skills find |

Refresh vendored: npm run vendor:core-skills · Manifest: SOURCES.md

Preset — greenfield

| Preset | Stack | Skills chính | |--------|-------|--------------| | flutter-supabase | Flutter + Supabase | flutter-mvvm | | laravel | Laravel API | laravel-api | | laravel-vue | Laravel + Vue 3 + Tailwind + Docker | laravel-fullstack, vue-inertia + 3 external* | | nextjs | Next.js App Router | nextjs-app-router |

*laravel-vue external: SOURCES.md · npm run vendor:skills

Preset — brownfield

| Preset | Stack | |--------|-------| | vue-element-plus-admin | Vue 3 + Element Plus + Vite (template) | | shadcn-vue-admin | Vue 3 + shadcn-vue + Tailwind (template) | | fastapi | FastAPI + Python |

npx @hamanhtuan/vibe-devkit install --preset vue-element-plus-admin .

Thêm preset: docs/PRESETS.md

Project (team)

| Custom | Path | Sync | |--------|------|------| | Rules | .vibe/rules/90-*.mdc | install.sh --project-only | | Domain skills | .vibe/skills/*/SKILL.md | --project-only | | Constitution patch | .vibe/constitution.patch.md | --project-only | | Skill install log | .vibe/skills-installed.log | thủ công / agent |

3 lớp scale

Core (00-09)  →  Preset (10-19)  →  Project .vibe/ (90-99)

| Thao tác | Lệnh | |----------|------| | Cài / đổi preset | install.sh --preset <name> . | | Update core rules/skills | install.sh --update-core . | | Sync .vibe/ | install.sh --project-only . |

Registry preset: presets/registry.yaml

Gates & enforcement

Runtime (Cursor):

| Hook | Hành vi | |------|---------| | beforeSubmitPrompt | Chặn “implement ngay” nếu GATE 4 chưa pass (failClosed: true) | | afterFileEdit | Nhắc cập nhật tasks.md khi sửa code |

Dùng active_feature trong config — không chỉ folder mới nhất.

Override (có audit):

GATE OVERRIDE: P0 production down
QUICK: yes   # thay đổi nhỏ (< quick_change_loc_threshold LOC)

Ghi log: .vibe/override-log.md

Gate modes:

| Mode | Hành vi | |------|---------| | strict | Checklist + semantic validators — khuyến nghị production | | normal | Blocker chính; warning cho gate chưa xong | | relaxed | Code được nếu có tasks.md |

CI

Copy .github/workflows/vibe-validate.yml vào repo app:

- run: pip install -r requirements-dev.txt
- run: python3 scripts/vibe.py validate --strict
- run: pytest tests/ -q

PR checklist: .github/pull_request_template.md

Cấu trúc repo

vibe-devkit/
├── bin/vibe                      # CLI (npx / global)
├── scripts/
│   ├── vibe.py                   # validate, new, trace, gate-check
│   ├── vendor-core-skills.sh     # frontend-design, find-skills
│   └── vendor-external-skills.sh # laravel-vue preset skills
├── .cursor/                      # rules, commands, skills, hooks
├── .claude/commands/             # slash commands Claude
├── .vibe/                        # template custom project
├── presets/                      # flutter, laravel, nextjs, laravel-vue
├── docs/
│   ├── vibe/000-example-user-login/   # gold standard
│   ├── GUIDE.md
│   ├── ONBOARDING.md
│   └── MIGRATION.md
├── tests/                        # pytest
├── templates/                    # idea, spec, tasks, …
├── constitution/ workflow/
├── core-external-skills.lock.yaml
└── install.sh

Multi-tool

| Tool | Entry | |------|-------| | Cursor | .cursor/rules + /vibe-* + hooks | | Claude | CLAUDE.md + .claude/commands/ | | Codex | AGENTS.md |

Develop & maintain

npm test                         # validate example + pytest
npm run vendor:core-skills       # refresh core external skills
npm run vendor:skills            # refresh laravel-vue externals
npm run pack:check               # dry-run npm pack

Maintainers publish: npm run publish:npm (xem scripts/publish.sh)

Tài liệu

| File | Nội dung | |------|----------| | docs/GUIDE.md | Hướng dẫn sử dụng đầy đủ | | docs/PRESETS.md | Thêm preset stack / brownfield | | docs/ONBOARDING.md | Quick start 5 phút | | docs/MIGRATION.md | Upgrade 0.1 → 0.2 | | workflow/PIPELINE.md | Gate criteria chi tiết | | constitution/CONSTITUTION.md | Nguyên tắc bất biến | | AGENTS.md | Agent instructions |

License

MIT — upstream skills: xem LICENSE.txt trong từng skill folder (SOURCES.md).