Heavy AI Workflow for production-grade software projects.
Languages: English · Tiếng Việt
VGFlow là một config-driven AI development pipeline mạnh mẽ — được thiết kế chuyên cho các dự án software lớn, đa thành phần, chất lượng production. Pipeline hỗ trợ đầy đủ các loại hình:
- Web applications (React / Next / Vue / Svelte frontend + Node / Python / Go / Rust backend)
- Web servers / Backend APIs (REST / GraphQL / gRPC, microservices, RTB engines, ad exchanges)
- CLI tools (CLI utilities, dev tools, DevOps automation)
- Mobile apps (React Native, Flutter, native iOS / Android, hybrid)
Zero hardcoded stack — mọi giá trị đều derive từ vg.config.md. Portable 100% qua mọi project, mọi ngôn ngữ, mọi deployment model (VPS / Docker / Kubernetes / serverless).
Version: 3.0.0 · License: MIT
v3.0.0 (2026-05-11) — MAJOR / BREAKING. Global install at ~/.vgflow/ (single-version, npm-distributable). Project state under .vg/ (config, ROADMAP, FOUNDATION, deploy state — all relocated from root + .claude/). Resolver dual-mode (find_repo_root() + find_vg_home()) lets old code coexist with new layout. Hook installer accepts --mode global|project. New /vg:install skill handles first-run / re-install / switch / repair. vg-migrate-v3.sh migrates existing v2.x projects in one atomic command (auto-merges per-phase deploy state into project-level .vg/deploy/STATE.json). /vg:update is now marker-aware — global mode refreshes ~/.vgflow/ via git pull or npm. Anti-rationalization tables + engineering principles + lifecycle taxonomy + skill discovery flowchart shipped (inspired by addyosmani/agent-skills audit). See CHANGELOG for migration steps.
VGFlow là một pipeline chuyên sâu, nhiều tầng orchestration, token-intensive. Không phải "hỏi AI sửa 1 file" — mỗi phase đi qua 7 steps, spawn multiple AI agents, chạy CrossAI consensus, validate qua weighted gates, commit theo atomic group. Token cost ở từng giai đoạn đáng kể:
/vg:scope~$0.15-0.30/phase (Opus adversarial challenger + dimension expander)/vg:build~$0.50-2.00/phase (Sonnet execution waves, contract-aware)/vg:deploy~$0.05/run (mostly bash + ssh, tiny AI surface) [optional, multi-env]/vg:review~$0.30-0.80/phase (Opus navigator + Haiku scanners + CrossAI)/vg:test~$0.20-0.50/phase (goal verification + codegen regression)/vg:roam~$0.10-0.40/phase (lens-driven exploratory pass —selfmode cheapest,spawnadds CLI cost) [optional, post-test]
VGFlow shine nhất khi:
- Phase có 10-50+ tasks, spans multiple apps trong monorepo
- Critical domain constraints (billing, auth, auction, compliance, payout)
- Cần audit trail cho production deploy hoặc regulatory review
- Team có nhiều developers cần decision traceability (D-XX namespace)
- Performance SLA nghiêm ngặt (RTB ≤50ms, API p95 ≤200ms...)
VGFlow KHÔNG phù hợp khi:
- Chỉ cần sửa 1-2 files hoặc hotfix cấp tốc → dùng
/vg:amendhoặc direct edit - Prototype cuối tuần, one-off script → overhead không xứng
- Solo developer làm side project nhỏ → simpler workflow đủ
Opus / Sonnet / Haiku tier routing theo task complexity. Opus cho reasoning-heavy gates (scope adversarial, plan architect, block resolver L2). Sonnet cho execution waves + code review. Haiku cho exhaustive scan, rationalization guard, pattern probing. Right model, right price, right quality.
Post-test janitor catches silent state mismatches /vg:review + /vg:test miss. 20+ adversarial lenses: table-interaction (filter/sort/paginate URL state sync), form-lifecycle (Create→Read→Update→Delete round-trip với UI/network/DB coherence), business-coherence (UI claim ↔ network truth ↔ DB read-after-write), modal-state (focus trap, ESC, multi-modal stacking), IDOR/BOLA, mass-assignment, BFLA, race conditions, SSRF, JWT alg confusion, file-upload polyglot, path traversal — full STRIDE+OWASP coverage as separate lens prompts. Commander analyzes raw observe-*.jsonl logs (R1-R8 deterministic rules), generates ROAM-BUGS.md + proposed .spec.ts files for the test suite. Per-brief skip on resume — partial runs don't waste prior work.
Roam runs the same brief 3 different ways depending on environment:
self— current Claude Code session IS the executor, drives Playwright MCP directly. No subprocess, no CLI auth, no Chromium permission issues. Login works because the model is authed to MCP servers. Cheapest + most reliable for web platforms.spawn— VG subprocesscodex exec --full-autoorgemini --yoloper brief, parallel-bounded 5-slot. For when you want a different model voicing the run, or need parallelism across model dirs (Council mode).manual— VG generatesPASTE-PROMPT.md+ INSTRUCTION-*.md per surface; user pastes into any CLI of choice (Claude Code window, Codex desktop, Cursor, web ChatGPT). Drop JSONL back, VG aggregates.
Platform detection (web / mobile-native / desktop / api-only) reads CONTEXT.md keywords + checks tool availability (Playwright MCP, Maestro, adb, codex, gemini binaries) — only offers modes the platform supports. Mobile-native phase without Maestro+adb? Skill hard-blocks and suggests /vg:setup-mobile.
Optional standalone step between build and review/test/roam. Multi-select envs (sandbox/staging/prod), sequential per-env loop, per-env log files. Prod gate: separate AskUserQuestion 3-option danger gate (PROCEED / NON-PROD-ONLY / ABORT) interactively, OR --prod-confirm-token=DEPLOY-PROD-{phase} for non-interactive runs (token must match exactly — typo aborts). Captures previous_sha before overwrite for future /vg:rollback. Health check retries 6× 5s before marking failed. DEPLOY-STATE.json drives downstream env recommendation: review/test/roam env gate auto-suggests "sandbox (Recommended — deployed 2min ago, sha abc1234)" via enrich-env-question.py (suggestion-only — user always confirms).
Blueprint + Scope reviews không phê duyệt bằng 1 AI. Pipeline spawn song song Claude Code + OpenAI Codex CLI + Gemini CLI → synthesize consensus → PASS / BLOCK / escalate disagreement. Independent eyes catch blind spots mà single-AI thường miss.
/vg:build parse task dependency graph → graph-coloring waves → parallel execute. File conflicts auto-force sequential. Contract injection copies Zod / Pydantic / TypeScript schemas verbatim vào task prompts — zero typo drift từ API contract. Silent agent failures caught via commit-count verification.
Not "tests green" — mà goal-coverage-matrix: critical goals 100%, important 80%, nice-to-have 50%. Goals mapped to code via surface taxonomy (UI / API / Data / Integration / Time-driven), mỗi surface có dedicated runner. Mixed-phase project (some UI + some backend) vẫn cover hết.
Mỗi answer trong /vg:scope đi qua 8-lens Opus challenger: contradiction · hidden assumption · edge case · foundation conflict · security threat · performance budget · failure mode · integration chain. Cuối mỗi round, dimension-expander (Opus) đặt câu hỏi "what haven't we discussed yet?" — proactive gap finding, không chờ bug xuất hiện.
Auto-detect feature / feature-legacy / infra / hotfix / bugfix / migration / docs từ SPECS.md → gate policy + test mode + required artifacts tự động phù hợp. Infra phase không cần TEST-GOALS. Migration phase phải có ROLLBACK.md. Feature-legacy (no SPECS) vẫn review được. Không một-size-fits-all.
Bị block giữa phase? Không phải hard stop. Pipeline escalates:
- L1 Inline — auto-fix candidate retries (cheap, local)
- L2 Architect — Haiku subagent propose solution (zero-context adjudication)
- L3 User Choice — AskUserQuestion với concrete options
- L4 Stuck — genuine blocker, escalate with full context
AI tự nghĩ option trước khi đòi user quyết định.
/vg:review không script tĩnh — organic exploration: click sidebar, click mỗi button, quan sát kết quả, catch console errors + network 4xx/5xx + i18n key resolution. Mobile-aware (v1.9.4): single-device projects (iOS sim / Android emu) auto-sequential spawn, web projects parallel 5-slot. CLI/library projects skip UI scan entirely.
/vg:update pulls latest release from GitHub, 3-way merge against user customizations, parks conflicts cho /vg:reapply-patches. Không clobber custom edits. Breaking changes (major version) yêu cầu --accept-breaking explicit.
Mỗi phase có manifest hash-validates all artifacts (SPECS / PLAN / CONTEXT / TEST-GOALS / SUMMARY / RUNTIME-MAP...). Corruption detected early via /vg:integrity. Commits atomic per task với namespace enforcement P{phase}.D-XX.
Append-only JSONL events (gate hits, overrides, fix routing, phase timing). Query qua /vg:telemetry + /vg:gate-stats. Mỗi --allow-* / --skip-* được log với event-based resolution — không accumulate hidden technical debt.
Khi gate skip được đề xuất, spawn Haiku subagent zero-context adjudicates: real blocker vs rationalization? Anti-corner-cutting ở critical gates (compliance, security, performance).
UI changes pixel-diff vs baseline screenshot. Threats từ STRIDE + OWASP taxonomy cumulated qua milestone, cross-phase correlation. Security audit chạy end-of-milestone — không bỏ sót.
8-dimension foundation (platform / runtime / data / auth / hosting / distribution / scale / compliance) lock tại /vg:project. Mỗi phase scope check drift — nếu phase đột ngột assume cross-tenancy mà foundation nói single-tenant → flag immediately.
Codebase auto-rebuild knowledge graph sau mỗi build wave — fresh sibling/caller context cho next wave. God nodes + communities injected vào scope/plan prompts. Code understanding scale với codebase size.
VGFlow không chỉ là happy-path workflow. Từ v2.19.0–v2.32.1, mỗi bug từ production dogfood được trace đến root cause và fix ngay trong cùng pipeline. Dưới đây là những cơ chế bảo vệ được xây từ thực tế:
Problem: Mở 2 Claude Code windows — /vg:scope phase 1 + /vg:build phase 2 — cái nào chạy sau nhận ⛔ Active run exists. Single-tenant current-run.json block toàn project.
Fix: Per-session state files .vg/active-runs/{session_id}.json. Same session → block-or-stale-clear như trước. Khác session → WARN nhẹ về shared git index, không block. run-status aggregate shows this_session + other_sessions_active[]. Hai developer có thể làm song song 2 phase khác nhau cùng project, không cần phối hợp manual.
Problem: VGFlow dùng general-purpose agents; AI thỉnh thoảng spawn gsd-executor (wrong rule-set, wrong commit conventions). Prose rule "don't spawn gsd-executor" — AI đọc nhưng Claude Code's agent picker có thể override.
Fix: PreToolUse hook với matcher: "Agent" intercept spawn BEFORE nó fire. Trả về permissionDecision: "deny" với reason → Claude nhận reason ở next turn và re-spawn correctly. Hard enforcement tại OS level — không phải rule AI có thể rationalize qua. Allow-list cho gsd-debugger (VGFlow legitimate dùng ở build step 12). Smoke-tested 6 scenarios kể cả GSD coexistence.
Problem: Chicken-and-egg — vg_update.py bị stale/broken (silent merge bug #30 parked fix dưới dạng .conflict). Update fail. Bản thân updater cần được update nhưng updater không chạy được.
Fix: /vg:update load merge helper từ freshly downloaded tarball, không phải installed copy. Stale installed helper không thể block replacement của chính nó nữa. install.sh --refresh force-overwrite mọi VG-managed file với backup trước. Fresh installs seed .claude/vgflow-ancestor/v{version}/ baseline để future 3-way merges có real ancestor (loại bỏ "ancestor missing → force-upstream → silent overwrite" cliff). Pre-flight integrity scan classify clean/new/force_upstream_at_risk trước khi ghi đè.
Problem: Parallel executor agents (Wave N) git add files TRƯỚC khi acquire commit-queue mutex. Agent đầu tiên acquire mutex absorb file của agent khác → cross-attribution corruption — task A's code committed dưới tên task B.
Fix: vg_commit_with_files <task_id> <max_wait> <msg_file> <file>... — stage + commit nằm TRONG mutex, không thể tách ra. Index luôn sạch khi acquire. Diagnostic WARN nếu index có pre-staged file tại acquire time (dấu hiệu crashed task trước để lại). Executor rules cập nhật explicit rule: ⛔ DO NOT run git add BEFORE acquire.
Problem: Test suites cover happy path + alternate flows. Không có adversarial spec format → AI phải "đoán" threat ở step cuối pipeline khi code đã viết xong.
Fix: adversarial_scope field trong TEST-GOAL-enriched-template — declared tại /vg:blueprint Round 4, không thêm sau:
adversarial_scope:
threats: [auth_bypass, injection, race, duplicate_submit]
per_threat:
auth_bypass:
paths: ["other-tenant-id", "expired-session"]
assertions: ["status: 403", "no PII leak in error body"]Codegen tự sinh <goal>.adversarial.<threat>.spec.ts per threat. Validator verify-adversarial-coverage.py enforce: mutation goals không được có empty threats. Override --skip-adversarial=<reason> log vào OVERRIDE-DEBT.md severity=critical. Threat model → code → test là một luồng liên tục, không phải afterthought.
Problem: git log --grep=PATTERN scans cả commit body. Phase 2 regex \(2[-.0-9]*-[0-9]+\): match date string (2026-04-22): trong body của commit cũ → subject_format_violation false positive, block /vg:build run-complete deterministically.
Fix: Drop --grep filter, raw git log --pretty=format:%H%x00%s%x00%b%x01 + Python-side re.match anchored tại start của subject chỉ. Body không bao giờ scan nữa. Date strings trong commit bodies không thể trigger phantom violations.
Problem: Tất cả design assets land vào project-level .vg/design-normalized/ bất kể phase nào generate. Sau 10+ phases, directory là mớ hỗn độn — không biết asset nào thuộc phase nào, không thể prune safely.
Fix: 2-tier layout:
- Tier 1 — phase-scoped:
.vg/phases/{N}/design/— default write target per phase - Tier 2 — project-shared:
.vg/design-system/— brand assets, design tokens dùng cross-phase
design-path-resolver.sh abstraction layer — consumers source helper thay vì hardcode path. /vg:accept visual baseline resolve qua 3-tier fallback (phase → shared → legacy). Migration script phân tích PLAN.md citations để auto-classify và move existing assets với backup.
Problem: Skill bodies say "MANDATORY FIRST ACTION — invoke AskUserQuestion" but text-only "must ask" instructions are not enforced. Dogfood incident on /vg:roam invocation: AI silently skipped both 0aa resume prompt and 0a env+model+mode batch, then proceeded to backfill ROAM-CONFIG.json + relocate observe-* files + spawn S01 — all without user input. Prose rules don't bind AI execution under auto mode.
Fix: Three-layer enforcement that binds at runtime, not at "AI cẩn thận":
runtime_contract.must_emit_telemetrywithrequired_unless_flag: --non-interactiveforroam.resume_mode_chosen+roam.config_confirmedevents. Harness-level gate — Stop hook blocks run if events missing..tmp/{step}-confirmed.markerfiles written ONLY by code paths that follow AskUserQuestion answer. Step 1 entry asserts markers exist + are < 30 min old + env/model/mode env vars non-empty. Bash-level gate — fails fast with explicit "HARD GATE BREACH" message and emitsroam.gate_breachtelemetry.- Legacy state detection expanded from "ROAM-CONFIG.json exists" to also include RAW-LOG.jsonl / SURFACES.md / ROAM-BUGS.md / INSTRUCTION-.md / observe-.jsonl. Pre-v2.42.6 partial runs no longer silently bypass the resume prompt.
Lesson: Soft instructions describing "must ask the user" are routinely ignored when AI sees a quicker path. The fix is enforcement at telemetry + filesystem layer — same pattern as pre-stage commit-queue mutex (v2.28.0) and runtime_contract.must_touch_markers (v2.2). If the harness can't verify it happened, assume it didn't.
Problem: When /vg:roam detects prior state, v2.42.6-9 silently loaded saved env/model/mode from ROAM-CONFIG.json and skipped the 0a 3-question batch. User wanted to switch env mid-stream (local → sandbox) but resume locked them in to the prior choice. Workaround was --force wipe — destructive and discards prior briefs.
Fix: Step 0a now ALWAYS fires its 3-question batch regardless of resume mode. Prior config loads as ROAM_PRIOR_ENV/MODEL/MODE env vars used as "Recommended — prior run" pre-fill in each option. User must confirm even if they keep the same value. Mid-stream env switches become a 3-click operation, not a wipe.
Lesson: "Resume" should mean "skip work that was done", not "lock you out of decisions you made before". Conflating the two creates a footgun. The right primitive is pre-fill, not silent-load.
Problem: bug-reporter.sh embed ${context} vào Python triple-quoted heredoc. Context chứa quote / newline / $ → SyntaxError; 2>/dev/null swallow error → GitHub issues với empty body.
Fix: Pass tất cả data qua env vars (BR_SIG, BR_CTX, BR_DATA) + single-quoted Python source. os.environ.get() — fully byte-safe, không quan tâm chars. Sentinel fallback nếu JSON encode fail. GitHub issue body không bao giờ rỗng nữa.
Hầu hết AI coding tools dừng lại ở generation. VGFlow là enforcement substrate:
| Layer | Cơ chế |
|---|---|
| Gate enforcement | Claude Code hooks (Stop / PreToolUse / UserPromptSubmit) — không phải prose rules |
| Conflict detection | Commit-queue mutex với pre-stage guard — không phải "AI cẩn thận" |
| Session isolation | Per-session state files — không phải single global lock |
| Update integrity | Tarball self-bootstrap + ancestor baseline — không phải hope updater works |
| Threat coverage | Declarative adversarial spec + codegen + validator — không phải test-after-code |
| Telemetry | Append-only JSONL + SQLite events — không phải logs bị lost |
| Decision traceability | D-XX namespace per decision, CONTEXT.md linked to PLAN.md tasks |
| Bug feedback loop | Auto-report → dogfood → root cause → same-pipeline fix |
Mỗi cơ chế này không phải viết ra trên giấy — là kết quả của một bug được trace từ production dogfood đến root cause, và fix deployed trong vài giờ.
/vg:project → /vg:roadmap → /vg:map → /vg:prioritize
(7-round (ROADMAP.md, (optional — (which phase
discussion → phase list, graphify to work next)
PROJECT.md + soft drift codebase)
FOUNDATION.md + warning)
vg.config.md
ATOMIC)
v1.6.0 entry point change: /vg:project is the single entry point. It captures your free-form description, derives FOUNDATION (8 dimensions: platform/runtime/data/auth/hosting/distribution/scale/compliance), then auto-generates vg.config.md. Config is downstream of foundation, not upstream.
/vg:init is preserved as a backward-compat soft alias → /vg:project --init-only.
/vg:specs → /vg:scope → /vg:blueprint → /vg:build → [/vg:deploy] → /vg:review → /vg:test → [/vg:roam] → /vg:accept
(goal, (discussion (PLAN.md + (wave-based (optional — (scan + fix (goal verify (optional — (human UAT
scope, → CONTEXT.md API-CONTRACTS + parallel multi-env loop → + codegen lens-driven → UAT.md)
constraints) with D-XX) TEST-GOALS) execute) deploy) RUNTIME-MAP) regression) CRUD pass)
Required core (7 steps): specs → scope → blueprint → build → review → test → accept
Optional bridges (v2.43+): /vg:deploy between build and review when phase ships to a remote env; /vg:roam between test and accept for ship-critical phases that warrant adversarial coverage.
Full pipeline shortcut: /vg:phase {X} runs all 7 required steps with resume support; deploy + roam invoked separately as needed.
Advance step-by-step: /vg:next auto-detects current position and invokes the next command (skips deploy/roam unless flagged).
- Python 3.10+ (
tuple[bool, str]type hints and other 3.10 syntax) - Node 14+ (npm CLI dispatcher)
- Git + GitHub CLI (
gh) for/vg:update - Claude Code and/or OpenAI Codex CLI installed and authenticated
- Optional:
pnpm+graphifyfor full feature set
Installs harness at ~/.vgflow/ once. Hooks at ~/.claude/settings.json apply to every project automatically. Project state stays in per-project .vg/.
# Recommended — npm public package
npm install -g vgflow
cd /path/to/your-project
vg install --global# Or — one-line installer
curl -fsSL https://raw.githubusercontent.com/vietdev99/vgflow/main/install.sh | bash
cd /path/to/your-project
vg install --globalvg install --global writes ${cwd}/.vg/.install-target=global so subsequent VG commands resolve VG_HOME=~/.vgflow/ automatically. Uninstall via vg uninstall --global.
For users who prefer per-project copies of the harness:
cd /path/to/your-project
curl -fsSL https://raw.githubusercontent.com/vietdev99/vgflow/main/install.sh -o /tmp/vgflow-install.sh
bash /tmp/vgflow-install.sh .
vg install --project # or omit; install.sh handles thisProject-local mode keeps .claude/{commands,skills,scripts} per project. Hooks at ${project}/.claude/settings.json. Marker .vg/.install-target=project.
# Inspect plan first
bash ~/.vgflow/scripts/migrate/vg-migrate-v3.sh --target=global --dry-run
# Apply (interactive confirm)
bash ~/.vgflow/scripts/migrate/vg-migrate-v3.sh --target=global
# Apply + auto-commit
bash ~/.vgflow/scripts/migrate/vg-migrate-v3.sh --target=global --yes --commitWhat it does:
- Pre-flight (refuse if dirty working tree)
- Backup
.claude/{commands,skills,scripts}+settings.json→.vg/.backup-<ts>/ - Move root docs →
.vg/:ROADMAP.md,FOUNDATION.md,vg.config.md→.vg/config.md,OVERRIDE-DEBT.md - Auto-merge legacy per-phase
DEPLOY-STATE.json→.vg/deploy/STATE.json(NEW v3.0.0 — preserves deploy history) - Apply target via
vg-cli-dispatcher.sh install --<target> - Append
.vg/whitelist to.gitignore vg doctorsmoke + stage all changes
Refuses to run on a dirty working tree. Backs everything up first — recovery is cp -r .vg/.backup-<ts>/* . + git checkout.
cd /path/to/your-project
pip install -r .claude/scripts/requirements.txt # pyyaml + pytest (only 2 third-party deps)Most of VG is stdlib-only (hashlib, secrets, sqlite3, json, pathlib). Only the registry loader (pyyaml) and regression suite (pytest) need installation.
Required before first /vg:build with any --allow-* flag. The allow-flag gate uses HMAC-signed tokens; you need a signing key and a CI nonce directory:
# One-time: create signing key at ~/.vg/.approver-key (mode 0600 on POSIX)
python .claude/scripts/vg-auth.py init
# Verify
python .claude/scripts/vg-auth.py verify --token dummy --flag X # expected INVALID (key exists)Environment variables (optional — override defaults):
| Variable | Purpose | Default |
|---|---|---|
VG_APPROVER_KEY_DIR |
Signing key location (override for CI / testing) | ~/.vg/ |
VG_APPROVER_NONCE_DIR |
Nonce challenge storage (v2.5.2.3+) | ~/.vg/.approver-nonces/ |
VG_AUTH_CI_MODE |
Set to 1 in CI to enable nonce-bound fallback |
unset |
VG_AUTH_OPERATOR_ACK |
Nonce value pasted from vg-auth issue-nonce |
unset |
VG_ALLOW_FLAGS_STRICT_MODE |
Force strict env-approver mode (default true v2.5.2.2+) | default strict |
VG_ALLOW_FLAGS_LEGACY_RAW |
Opt-in to legacy raw-string env (v2.5.1 compat) | unset |
CI flow (never let CI self-mint tokens):
# On TTY operator machine:
python .claude/scripts/vg-auth.py issue-nonce --ttl-minutes 60 # prints plaintext nonce
# → deliver nonce OOB (Vault/SOPS secret, email, 2FA paste) to CI
# On CI runner:
export VG_AUTH_CI_MODE=1
export VG_AUTH_OPERATOR_ACK="<nonce-pasted-from-OOB>"
python .claude/scripts/vg-auth.py approve --flag allow-security-baseline --ttl-days 1
# → prints signed token; use as VG_HUMAN_OPERATOR in /vg:* callspython .claude/scripts/vg-hooks-selftest.py # verifies Stop + PostToolUse + UserPromptSubmit hooks fireIf hooks fail with can't open file 'D:\\AI' or similar truncated-path errors, the path contains spaces and the hook command wasn't quoted. Fix:
python .claude/scripts/vg-hooks-install.py # auto-repairs unquoted ${CLAUDE_PROJECT_DIR}Then restart Claude Code — hooks are cached at session start; repaired settings take effect next session only.
/vg:update --check # peek at latest version without applying
/vg:update # apply latest release
/vg:update --accept-breaking # required for major version bumps
/vg:reapply-patches # resolve conflicts from /vg:update
Update flow: query GitHub API → download tarball + SHA256 verify → 3-way merge (preserves your local edits) → park conflicts in .claude/vgflow-patches/.
If an older install reports the latest version but core files are still stale, force-refresh VG managed files from the current release:
cd /path/to/your-project
curl -fsSL https://raw.githubusercontent.com/vietdev99/vgflow/main/install.sh -o /tmp/vgflow-install.sh
bash /tmp/vgflow-install.sh --refresh .--refresh backs up existing VG managed files under .vgflow-refresh-backup/ before overwriting commands, skills, scripts, schemas, templates, and Codex mirrors.
Existing projects with .vg/design-normalized/ can migrate assets to phase-scoped + shared layout:
# Dry-run (default) — shows classification without moving anything:
python3 .claude/scripts/migrate-design-paths.py --repo . --verbose
# Apply — moves files with backup to .vg/.design-migration-backup/{ts}/:
python3 .claude/scripts/migrate-design-paths.py --repo . --apply --verbose
# Or combine with install --refresh:
bash /tmp/vgflow-install.sh --refresh --migrate-design .The script scans PLAN.md <design-ref slug="..."> citations to classify each slug: single-phase → phases/{N}/design/, multi-phase → .vg/design-system/, uncited → .vg/design-system/orphans/ for triage.
| Command | Purpose |
|---|---|
/vg:project |
ENTRY POINT — 7-round discussion → PROJECT.md + FOUNDATION.md + vg.config.md (atomic) |
/vg:project --view |
Pretty-print current artifacts (read-only) |
/vg:project --update |
MERGE-preserving update of existing artifacts |
/vg:project --milestone |
Append new milestone (foundation untouched) |
/vg:project --rewrite |
Destructive reset with backup → .archive/{ts}/ |
/vg:project --migrate |
Extract FOUNDATION.md from legacy v1 PROJECT.md + codebase scan |
/vg:project --init-only |
Re-derive vg.config.md from existing FOUNDATION.md |
/vg:init |
[DEPRECATED] Soft alias → /vg:project --init-only |
/vg:roadmap |
Derive phases from PROJECT + FOUNDATION → ROADMAP.md (soft drift warning) |
/vg:map |
Rebuild graphify knowledge graph → codebase-map.md |
/vg:prioritize |
Rank phases by impact + readiness |
| Step | Command | Output |
|---|---|---|
| 1 | /vg:specs {X} |
SPECS.md (goal, scope, constraints, success criteria) |
| 2 | /vg:scope {X} |
CONTEXT.md (enriched with decisions D-XX) + DISCUSSION-LOG.md (step 1b: per-phase preferred_env_for env preset) |
| 3 | /vg:blueprint {X} |
PLAN.md + API-CONTRACTS.md + TEST-GOALS.md + CrossAI review |
| 4 | /vg:build {X} |
Code + SUMMARY.md (wave-based parallel execution) |
| 4.5 | /vg:deploy {X} (optional, v2.43+) |
DEPLOY-STATE.json with deployed.{env} block per env (sha + timestamp + health + previous_sha for rollback). Multi-select envs, prod typed-token gate. |
| 5 | /vg:review {X} |
RUNTIME-MAP.json (browser discovery + fix loop). Env gate reads DEPLOY-STATE → "Recommended sandbox 2min ago, sha abc1234". |
| 6 | /vg:test {X} |
SANDBOX-TEST.md (goal verification + codegen regression) |
| 6.5 | /vg:roam {X} (optional, v2.43+) |
ROAM-BUGS.md + RUN-SUMMARY.json + proposed-specs/ (lens-driven CRUD-lifecycle pass). Always asks env/model/mode (v2.43.1 hard gate). |
| 7 | /vg:accept {X} |
UAT.md (human acceptance) |
| Command | Purpose |
|---|---|
/vg:phase {X} |
Run full 7-step phase pipeline with resume support |
/vg:next |
Auto-detect + advance to next step |
/vg:progress |
Status across all phases + update check |
/vg:amend {X} |
Mid-phase change — update CONTEXT.md, cascade impact |
/vg:add-phase |
Insert a new phase into ROADMAP.md |
/vg:remove-phase |
Archive + delete a phase |
/vg:regression |
Re-run all tests from accepted phases |
/vg:migrate {X} |
Convert legacy GSD artifacts to VG format (also backfills infra registers) |
| Command | Purpose |
|---|---|
/vg:milestone-summary {M} |
Aggregate report — phase status, goal coverage, security posture, override debt, companion artifact links |
/vg:complete-milestone {M} |
Close milestone — verify all phases accepted → security audit → summary → archive phase dirs → advance STATE.md → atomic commit |
/vg:complete-milestone {M} --check |
Dry-run gate check (no mutations) |
/vg:security-audit-milestone |
Cross-phase security correlation + Strix scan advisory (v2.32.0) |
/vg:project --milestone |
Append next milestone scope to PROJECT.md (after /vg:complete-milestone) |
| Command | Purpose |
|---|---|
/vg:update |
Pull latest release from GitHub |
/vg:reapply-patches |
Resolve conflicts from /vg:update |
/vg:sync |
Dev-side source↔mirror sync (maintainer only) |
/vg:telemetry |
Summarize workflow telemetry |
Enable AI's auto-learning loop:
/vg:meta-memory enable # full loop: reflect + inject as advice
/vg:meta-memory reflect-only # reflector only (drafts, no inject)
/vg:meta-memory statusThis sets meta_memory_mode: inject-as-advice in .claude/vg.config.md. The harness then:
- Reflects after
/vg:deploy /vg:test /vg:accept /vg:roam /vg:amend - Persists promoted rules into
.vg/bootstrap/rules/ - Injects them as advisory rules into build / accept / deploy preflight
Stop hook reminds you to run /vg:learn --consolidate --apply when 24h + 5 sessions accumulate. Does NOT auto-mutate — you stay in control.
Default remains disabled — no behavior change unless you explicitly opt in.
When a wave is mid-execution and the session crashes / hits limit / compacts, VGFlow restores the full tasklist projection on resume. The Stop hook captures latest TodoWrite state to .vg/runs/{run_id}/.todowrite-snapshot.json after every update; SessionStart hook re-projects on resume so in_progress items + completed status are preserved. No more "1 next task only" after resume.
in_progress items surface to the top of each group, completed sink to the bottom. Group headers auto-reflect active state — groups with any in_progress step show as in_progress, fully-completed groups show completed.
The SessionStart-injected primer now includes an Intent → Command map. When you type "build phase 7.14 bằng VG đi" or "lập plan cho phase 8", the AI recognizes the intent and invokes the matching /vg:* slash command. Supports both English and Vietnamese trigger phrases.
vgflow/
├── VERSION ← SemVer (e.g. "1.1.0")
├── CHANGELOG.md ← curated per release
├── commands/vg/ ← Claude Code slash commands
├── skills/ ← api-contract, vg-* skills
├── codex-skills/ ← Codex CLI parity
├── gemini-skills/ ← Gemini CLI parity
├── scripts/ ← Python helpers (vg_update, graphify, visual-diff, …)
├── templates/vg/ ← commit-msg hook template
├── vg.config.template.md ← schema seed for new projects
├── migrations/ ← vN_to_vN+1.md breaking-change guides
├── install.sh ← fresh install entrypoint
└── sync.sh ← dev-side source↔mirror (maintainer)
- Tags: SemVer —
v1.2.3 - Tarballs: attached to each GitHub Release (auto-built via
.github/workflows/release.yml) - Changelog:
CHANGELOG.md+ rendered in each Release body - Breaking changes:
migrations/vN_to_vN+1.mdshown before update proceeds
Maintained by @vietdev99. Not accepting external PRs at this stage — bug reports welcome as issues.
MIT — see LICENSE