@longph2102/v-flow 1.5.0

package/cli/lib/yaml-parser.js

@@ -0,0 +1,203 @@
+/**
+ * YAML Parser — Shared .flow-state.yaml parsing for V-Flow CLI
+ *
+ * Replaces fragile regex-based parsing with proper YAML library.
+ * Used by: status.js, doctor.js, feature.js
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+
+// Use js-yaml if available, otherwise fallback to regex-based parsing
+let yaml;
+try {
+  yaml = require('js-yaml');
+} catch {
+  yaml = null;
+}
+
+/**
+ * Parse .flow-state.yaml content into a structured object.
+ *
+ * @param {string} content - Raw YAML content
+ * @returns {object} Parsed flow state
+ */
+function parseFlowState(content) {
+  // Use js-yaml if available
+  if (yaml) {
+    try {
+      const raw = yaml.load(content);
+      return normalizeFlowState(raw || {});
+    } catch {
+      // Fallback to regex if YAML parsing fails
+      return parseFlowStateRegex(content);
+    }
+  }
+  return parseFlowStateRegex(content);
+}
+
+/**
+ * Normalize raw YAML object into the expected flow state shape.
+ * Ensures consistent field names and defaults.
+ */
+function normalizeFlowState(raw) {
+  return {
+    featureName: raw.feature_name || null,
+    featureId: raw.feature_id || null,
+    currentPhase: raw.current_phase || null,
+    phaseStatus: raw.phase_status || null,
+    projectType: raw.project_type || null,
+    createdAt: raw.created_at || null,
+    lastUpdated: raw.last_updated || null,
+    specVersion: raw.spec_version_latest || null,
+    blocked: raw.blocked === true,
+    blockedReason: raw.blocked_reason || null,
+    awaitingCheckpoint: raw.awaiting_checkpoint || null,
+
+    // Governance — risk tier + structured approvals (actor/timestamp/decision)
+    riskTier: raw.risk_tier || null,
+    approvals: Array.isArray(raw.approvals) ? raw.approvals : [],
+
+    // Artifacts
+    artifacts: normalizeArtifacts(raw.artifacts || {}),
+
+    // Routing
+    routeDecision: raw.routing?.after_master_check?.route_decision || null,
+
+    // Concerns
+    concernsCount: Array.isArray(raw.active_concerns) ? raw.active_concerns.length : 0,
+
+    // Phase history
+    phaseHistory: raw.phase_history || [],
+  };
+}
+
+/**
+ * Normalize artifacts section from YAML
+ */
+function normalizeArtifacts(artifacts) {
+  const result = {};
+  const defaults = {
+    exists: false,
+    version: null,
+    status: null,
+    verdict: null,
+    total: 0,
+    completed: 0,
+    human_approved: false,
+    synced_to_spec: null,
+    concerns_count: 0,
+  };
+
+  const artifactNames = ['spec', 'plan', 'tasks', 'test_cases', 'validation_report', 'code_review'];
+  for (const name of artifactNames) {
+    const src = artifacts[name] || {};
+    result[name] = {
+      exists: src.exists === true,
+      version: src.version || defaults.version,
+      status: src.status || defaults.status,
+      verdict: src.verdict || defaults.verdict,
+      total: typeof src.total === 'number' ? src.total : defaults.total,
+      completed: typeof src.completed === 'number' ? src.completed : defaults.completed,
+      human_approved: src.human_approved === true,
+      synced_to_spec: src.synced_to_spec || defaults.synced_to_spec,
+      concerns_count: typeof src.concerns_count === 'number' ? src.concerns_count : defaults.concerns_count,
+    };
+  }
+
+  return result;
+}
+
+/**
+ * Fallback regex-based parser (for environments without js-yaml).
+ * Preserves backward compatibility with the original status.js logic.
+ */
+function parseFlowStateRegex(content) {
+  const state = {};
+
+  const getField = (key) => {
+    const match = content.match(new RegExp(`^${key}:\\s*"?([^"\\n]*)"?`, 'm'));
+    return match ? match[1].trim() : null;
+  };
+
+  state.featureName = getField('feature_name');
+  state.featureId = getField('feature_id');
+  state.currentPhase = getField('current_phase');
+  state.phaseStatus = getField('phase_status');
+  state.projectType = getField('project_type');
+  state.createdAt = getField('created_at');
+  state.lastUpdated = getField('last_updated');
+  state.specVersion = getField('spec_version_latest');
+  state.blocked = getField('blocked') === 'true';
+  state.blockedReason = getField('blocked_reason');
+  state.awaitingCheckpoint = getField('awaiting_checkpoint');
+  state.riskTier = getField('risk_tier');
+  state.approvals = []; // structured list — only the js-yaml path parses it fully
+
+  // Parse artifact statuses
+  state.artifacts = {};
+  const artifactNames = ['spec', 'plan', 'tasks', 'test_cases', 'validation_report', 'code_review'];
+  for (const name of artifactNames) {
+    const existsMatch = content.match(new RegExp(`${name}:[\\s\\S]*?exists:\\s*(true|false)`, 'm'));
+    state.artifacts[name] = {
+      exists: existsMatch ? existsMatch[1] === 'true' : false,
+    };
+
+    if (name === 'spec') {
+      const versionMatch = content.match(/spec:[\s\S]*?version:\s*"?([^"\n]*)"?/m);
+      const statusMatch = content.match(/spec:[\s\S]*?status:\s*"?([^"\n]*)"?/m);
+      state.artifacts.spec.version = versionMatch ? versionMatch[1] : null;
+      state.artifacts.spec.status = statusMatch ? statusMatch[1] : null;
+    }
+
+    if (name === 'validation_report') {
+      const verdictMatch = content.match(/validation_report:[\s\S]*?verdict:\s*"?([^"\n]*)"?/m);
+      state.artifacts.validation_report.verdict = verdictMatch ? verdictMatch[1] : null;
+    }
+
+    if (name === 'tasks') {
+      const totalMatch = content.match(/tasks:[\s\S]*?total:\s*(\d+)/m);
+      const completedMatch = content.match(/tasks:[\s\S]*?completed:\s*(\d+)/m);
+      state.artifacts.tasks.total = totalMatch ? parseInt(totalMatch[1]) : 0;
+      state.artifacts.tasks.completed = completedMatch ? parseInt(completedMatch[1]) : 0;
+    }
+  }
+
+  // Parse routing
+  const routeDecision = content.match(/route_decision:\s*"?([^"\n]*)"?/m);
+  state.routeDecision = routeDecision ? routeDecision[1] : null;
+
+  // Parse concerns count
+  const concernsCount = content.match(/concerns_count:\s*(\d+)/m);
+  state.concernsCount = concernsCount ? parseInt(concernsCount[1]) : 0;
+
+  state.phaseHistory = [];
+
+  return state;
+}
+
+/**
+ * Read and parse .flow-state.yaml from a feature directory.
+ *
+ * @param {string} featureDir - Absolute path to feature directory
+ * @returns {object|null} Parsed flow state, or null if file doesn't exist
+ */
+async function readFlowState(featureDir) {
+  const flowStatePath = path.join(featureDir, '.flow-state.yaml');
+  if (!fs.existsSync(flowStatePath)) return null;
+
+  try {
+    const content = await fs.readFile(flowStatePath, 'utf8');
+    return parseFlowState(content);
+  } catch {
+    return null;
+  }
+}
+
+module.exports = {
+  parseFlowState,
+  normalizeFlowState,
+  normalizeArtifacts,
+  parseFlowStateRegex,
+  readFlowState,
+};

package/commands/v.ba-critic.md

@@ -0,0 +1,101 @@
+---
+description: "BA Critic Agent — Adversarial spec review 1 round (dùng sau /v.specify --dual)"
+phase: "S.1"
+agent: "ba-critic-agent"
+---
+
+# /v.ba-critic
+
+> Orchestration wrapper cho **BA Critic Agent**. Đọc `agents/ba-critic-agent.md` để thực hiện core logic.
+
+## Điều kiện sử dụng
+
+- Đã chạy `/v.specify --dual` → `spec.md` và `spec-review-log.md` đã tồn tại
+- Hoặc: BA Agent vừa cập nhật spec sau ITERATE và bạn muốn chạy round tiếp theo
+
+## Execution
+1. Đọc agent definition: `agents/ba-critic-agent.md`
+2. Thực hiện toàn bộ quy trình trong agent definition
+3. Ghi kết quả theo Output Template bên dưới
+
+---
+
+## 🔀 Routing Rules — Sau BA Critic
+
+```
+Verdict = CONVERGED (0 Critical + 0 Major)
+  → [Optional S.1.5] /v.prototype  ← nếu spec có ambiguity sau review
+  → Route: /v.plan + /v.test (SONG SONG)
+  → Spec đã hội tụ, sẵn sàng chuyển sang Build phase
+
+Verdict = ITERATE (≥ 1 Critical hoặc Major)
+  → Route: BA Agent sửa spec → /v.ba-critic (round tiếp)
+  → BA Agent đọc issues và bump spec version
+
+Verdict = ESCALATE (Round ≥ 4)
+  → Route: Human review
+  → Cần meeting với stakeholder
+```
+
+## Output Template — spec-review-log.md
+
+Append Round N vào `spec-review-log.md`:
+
+```markdown
+## Round [N] — [YYYY-MM-DD]
+
+**Spec Version đầu round**: v[X.Y]
+**Reviewer**: BA Critic Agent (fresh context)
+
+### Issues Found
+
+| ID | Mức | Mô tả ngắn | Requirement liên quan |
+|----|-----|------------|----------------------|
+| R[N]-C001 | 🔴 Critical | ... | REQ-xxx |
+
+### Thống kê Round [N]
+
+| Mức | Số lượng |
+|-----|---------|
+| 🔴 Critical | N |
+| 🟠 Major | N |
+| 🟡 Minor | N |
+
+### Verdict Round [N]
+> [CONVERGED / ITERATE / ESCALATE]
+```
+
+Cập nhật **Convergence Summary** ở cuối file.
+
+---
+
+## Input
+- `.v-flow/features/NNN-feature/spec.md`
+- `.v-flow/constitution.md`
+- `.v-flow/context.md` *(nếu legacy)*
+- `.v-flow/features/NNN-feature/spec-review-log.md` *(header only)*
+
+## Output
+- `.v-flow/features/NNN-feature/spec-review-log.md` *(append Round N)*
+
+## Ví dụ
+
+```
+/v.ba-critic
+```
+
+*(Không cần argument — tự động đọc feature folder hiện tại)*
+
+---
+
+## Cập nhật State & Session
+
+**Append vào `_session.md`**:
+```markdown
+### [S.1] BA Critic Round [N] — [YYYY-MM-DD]
+- **Agent**: BA Critic Agent
+- **Spec Version**: v[X.Y]
+- **Verdict**: [CONVERGED | ITERATE | ESCALATE]
+- **Issues**: [N] Critical, [N] Major, [N] Minor
+- **Routing**: → [next step]
+```

package/commands/v.ba-to-ptyc.md

@@ -0,0 +1,71 @@
+---
+description: "BA to PTYC Agent — Sinh tài liệu Phân tích Yêu cầu (PTYC.docx) chuẩn ISO từ spec.md (Doc Export — S.1.6, optional)"
+phase: "S.1.6"
+agent: "ba-to-ptyc-agent"
+optional: true
+dependency: "Python docxtpl (pip install docxtpl); mermaid-cli optional cho sơ đồ"
+---
+
+# /v.ba-to-ptyc
+
+> Orchestration wrapper cho **BA to PTYC Agent**. Đọc `agents/ba-to-ptyc-agent.md` để thực hiện core logic.
+> Tương ứng **bước 7a** trong BA Skill Pipeline: `spec.md` → `PTYC.docx`.
+
+> ⚠️ **OPTIONAL — Doc Export**. Chỉ sinh tài liệu bàn giao, không thay đổi spec/plan/code.
+> Cơ chế **Route B**: đổ dữ liệu vào template `.docx` có sẵn → **giữ nguyên 100% format ISO Viettel**.
+
+---
+
+## Prerequisites
+
+> ⚠️ Tooling nằm **trong `.v-flow/` của project** (do `v-flow init/sync` copy vào): `.v-flow/scripts/ptyc/` + `.v-flow/templates/ptyc/`. Chạy mọi lệnh từ **gốc project** (nơi có thư mục `.v-flow/`) — **KHÔNG** dùng đường dẫn kiểu `<project>/scripts/...` ở thư mục gốc (không tồn tại), cũng không cần repo framework ngoài.
+> Nếu `.v-flow/scripts/ptyc/` chưa có → chạy `v-flow sync --apply` (hoặc `v-flow init`) để copy vào. `<F>` = `.v-flow/features/{NNN}`.
+
+```
+1. <F>/spec.md                              ← nên đã Approved
+2. <F>/ptyc.meta.yaml                       ← nếu chưa có: copy .v-flow/templates/ptyc/ptyc.meta.example.yaml và điền
+3. venv trong .v-flow (1 lần) — macOS python externally-managed:
+     python3 -m venv .v-flow/.venv && .v-flow/.venv/bin/pip install docxtpl
+```
+
+> Thiếu `docxtpl` → `render_ptyc.py` in hướng dẫn cài venv và **dừng (không ra file)**.
+> Thiếu `mermaid-cli` → sơ đồ dùng placeholder (không fail).
+> Template tự resolve `.v-flow/templates/ptyc/PTYC.template.docx` — không cần `--template`.
+
+---
+
+## Execution
+
+1. Đọc agent definition: `agents/ba-to-ptyc-agent.md`
+2. Chạy từ **gốc project** (nơi có `.v-flow/`). `<F>` = `.v-flow/features/{NNN}`.
+3. Đọc `<F>/spec.md` + `<F>/ptyc.meta.yaml` (+ `<F>/plan.md` nếu có)
+4. Map → `<F>/ptyc/ptyc-data.json` (đúng `.v-flow/scripts/ptyc/ptyc-data.schema.json`)
+5. (Tùy chọn) `node .v-flow/scripts/ptyc/render_mermaid.mjs <F>/ptyc/img`
+6. Render — **`--out` là thư mục** → file tự đặt tên `{doc_code}.docx` (doc_code tự sinh từ `pyc_ref.no`, KHÔNG hardcode):
+   `.v-flow/.venv/bin/python .v-flow/scripts/ptyc/render_ptyc.py --data <F>/ptyc/ptyc-data.json --out <F>/ptyc/ --img-dir <F>/ptyc/img`
+7. **Xác nhận file `.docx` tồn tại** + đúng số PYC → báo đường dẫn + danh sách `[TBD]`
+
+## Options
+
+### `--feature <NNN>`
+Chỉ định feature. Mặc định: feature đang active trong `.flow-state.yaml`.
+
+### `--meta <path>`
+Đường dẫn `ptyc.meta.yaml` khác (mặc định: trong thư mục feature).
+
+### `--no-images`
+Bỏ qua bước mermaid → tất cả sơ đồ dùng placeholder (nhanh, không cần mmdc).
+
+---
+
+## Output
+
+```
+.v-flow/features/{NNN}/ptyc/
+├── ptyc.meta.yaml          ← metadata (BA điền)
+├── ptyc-data.json          ← dữ liệu AI map từ spec (trung gian, review được)
+├── img/                    ← *.mmd + *.png (nếu render được)
+└── PTYC_{doc_code}.docx    ← ✅ tài liệu bàn giao
+```
+
+> 📎 Sinh lại template (khi file mẫu đổi): `.v-flow/.venv/bin/python .v-flow/scripts/ptyc/build_template.py <file-mẫu.docx> .v-flow/templates/ptyc/PTYC.template.docx`

package/commands/v.bugfix.md

@@ -0,0 +1,86 @@
+---
+description: "Bugfix Flow — S.1(3-behavior) → B.0(opt) → B.1(3-tier TDD) → R.1. Dành cho bug cần investigate."
+phase: "S.1 → B.0 → B.1 → R.1"
+agents: ["bugfix-analyst-agent", "plan-agent", "implement-agent", "review-agent"]
+---
+
+# /v.bugfix
+
+Chạy **Bugfix Flow** — pipeline chuẩn hóa để chẩn đoán và sửa lỗi (Surgical Bugfix), áp dụng 3-behavior model và 3-tier TDD.
+
+> ⚠️ **Điều kiện sử dụng**: Chỉ dùng khi:
+> - Bug cần investigate, ảnh hưởng nhiều file (≥ 5 files), hoặc cần regression testing
+> - Có risk regression nếu sửa sai
+> - Bug đã reproduced hoặc có log/evidence rõ ràng
+
+> ❌ **Không dùng cho**:
+> - Bug trivial < 5 files, nguyên nhân rõ ràng → dùng `/v.quickfix`
+> - Production incident P1/P2 → dùng `/v.hotfix`
+> - Mở rộng feature mới → dùng full pipeline `/v.specify`
+
+---
+
+## Phase 1: Bugfix Analysis [S.1]
+
+Bạn là **Bugfix Analyst Agent** — chuyên gia chẩn đoán bug.
+
+### Quy trình:
+1. Đọc và tuân thủ tuyệt đối kỹ năng tại `skills/specify/bugfix-analyst/SKILL.md`
+2. Phân tích root cause từ input
+3. Khởi tạo `.flow-state.yaml` nếu chưa có (Phase S.1, type bugfix)
+4. Xây dựng 3-Behavior Model:
+   - BUG-B (Defect): Cái gì ĐANG SAI
+   - BUG-E (Expected): Cái gì PHẢI ĐÚNG
+   - BUG-U (Unchanged): Cái gì KHÔNG ĐƯỢC ĐỔI (≥ 2 items)
+5. Thiết kế 3-Tier Test Plan (T1: Red, T2: Green, T3: Protect)
+6. Output ra `bugfix.md` dựa theo `.v-flow/templates/bugfix-spec-template.md`
+7. Cập nhật vào `_session.md`
+
+### Routing sau Phase 1
+- Human approve `bugfix.md` → /v.plan (nếu cần design) hoặc /v.implement (nếu fix đơn giản)
+- Root cause confidence = low → DỪNG, yêu cầu user thêm log/debug session
+
+---
+
+## Phase 2: Fix Design [B.0a] (Optional)
+
+Bạn là **Plan Agent** — thiết kế fix an toàn.
+
+### Quy trình:
+1. Đọc `bugfix.md`
+2. Lên plan sửa đổi chi tiết, đảm bảo cover hết BUG-E và không break BUG-U.
+3. Không đụng No-Go Zones trong `context.md`
+4. Lên rollback plan
+5. Output ra `plan.md`
+
+---
+
+## Phase 3: Implement Fix [B.1]
+
+Bạn là **Implement Agent** — code theo TDD 3-Tier.
+
+### Quy trình:
+1. Thực hiện TDD theo 3 Tier:
+   - 🔴 **RED**: Viết T1 tests (reproduce bug) → Run → confirm FAIL
+   - 🟢 **GREEN**: Implement fix → Run T1 PASS → Run T2 PASS
+   - 🛡️ **PROTECT**: Run T3 PASS (regression check) → Full suite PASS
+2. Fix không được đụng tới files nằm ngoài scope trừ khi cần thiết (và update report)
+3. Cập nhật kết quả vào `_session.md`
+
+---
+
+## Phase 4: Review + Bugfix Report [R.1]
+
+Bạn là **Review Agent** — adversarial review và tạo báo cáo.
+
+### Quy trình:
+1. Đọc kỹ `bugfix.md` và changes
+2. Xác nhận 3-Tier Test Plan đã được implement đầy đủ (T1, T2, T3 pass)
+3. Xác nhận root cause thực sự đã được giải quyết
+4. Tạo `bugfix-report.md` theo `.v-flow/templates/bugfix-report-template.md` (Trả lời 6 câu hỏi: Bug là gì? Root cause? Giải pháp? Sửa ntn? File nào sửa? File nào ảnh hưởng?)
+5. Đưa ra Verdict.
+
+### Verdict:
+- APPROVED → Có bugfix-report.md → Deploy
+- CHANGES_REQUIRED → Bắt buộc sửa lại
+- ESCALATE → Chuyển sang full pipeline

package/commands/v.check.md

@@ -0,0 +1,131 @@
+---
+description: "Master Check Agent — Cross-validate Spec ↔ Plan ↔ Tests trước khi implement"
+phase: "R.0"
+agent: "master-check-agent"
+routing_rules:
+  PASS: "implement"
+  PASS_WITH_CONCERNS: "implement"
+  FAIL_spec_gap: "re_specify"
+  FAIL_plan_gap: "re_plan"
+  FAIL_test_gap: "re_test"
+  FAIL_nogo_violation: "re_plan"
+  FAIL_constitution: "fix_artifact"
+---
+
+# /v.check
+
+> Orchestration wrapper cho **Master Check Agent**. Đọc `agents/master-check-agent.md` để thực hiện core logic.
+
+> ⚠️ KHÔNG có code nào được viết cho đến khi Master Check = **PASS** hoặc **PASS WITH CONCERNS**
+
+## Điều kiện tiên quyết
+- `spec.md` — kiểm tra Status block (Section 7): tất cả artifacts phải ✅
+- `plan.md` + `tasks.md` phải tồn tại
+- `test-cases.md` phải tồn tại
+- `constitution.md` phải tồn tại
+- `context.md` (nếu legacy project)
+
+## Execution
+1. Đọc agent definition: `agents/master-check-agent.md`
+2. Thực hiện toàn bộ quy trình trong agent definition
+3. Tạo `validation-report.md` theo output template
+
+---
+
+## 🔀 Routing Rules — Sau Master Check
+
+> Điền `fail_reason` vào `validation-report.md` và `.flow-state.yaml` để agent/user biết đi đâu tiếp theo.
+
+```
+Verdict = PASS
+  → Route: /v.implement
+  → Không có vấn đề, sẵn sàng code
+
+Verdict = PASS_WITH_CONCERNS
+  → Route: /v.implement
+  → ⚠️ Implement Agent PHẢI đọc và xử lý từng concern trong list
+  → ⚠️ /v.review PHẢI verify concerns đã resolved
+
+Verdict = FAIL + fail_reason = "spec_gap"
+  → Route: /v.specify (sửa/bổ sung spec)
+  → Sau spec: bump version → /v.sync → /v.check
+
+Verdict = FAIL + fail_reason = "plan_gap"
+  → Route: /v.plan (re-design plan)
+  → Sau plan: /v.sync → /v.check
+
+Verdict = FAIL + fail_reason = "test_gap"
+  → Route: /v.test (bổ sung test cases)
+  → Sau test: /v.check
+
+Verdict = FAIL + fail_reason = "nogo_violation"
+  → Route: /v.plan (redesign tránh No-Go Zones)
+
+Verdict = FAIL + fail_reason = "constitution_violation"
+  → Route: Fix artifact vi phạm → /v.check
+```
+
+## Output — validation-report.md
+
+```markdown
+# Validation Report — [Feature Name]
+
+**Ngày check**: YYYY-MM-DD
+**Spec Version**: vX.Y
+**Verdict**: ✅ PASS / ⚠️ PASS WITH CONCERNS / ❌ FAIL
+
+## Tóm tắt Coverage
+
+| Metric | Kết quả |
+|--------|---------|
+| Tổng requirements | N |
+| REQ có task | N/N ✅ |
+| REQ có test case | N/N ✅ |
+| Orphan tasks | 0 ✅ |
+| Orphan tests | 0 ✅ |
+
+## Issues
+(Critical / Major / Concerns / Minor)
+
+## Kết luận
+> ✅ PASS — Sẵn sàng implement
+> ⚠️ PASS WITH CONCERNS — Xem danh sách Concerns ở trên
+> ❌ FAIL — Fix [N] Critical/Major issues trước khi implement
+```
+
+## Cập nhật State & Session
+
+**Cập nhật `.flow-state.yaml`**:
+```yaml
+artifacts:
+  validation_report:
+    exists: true
+    verdict: "PASS"
+    spec_version_checked: "v1.0"
+    concerns_count: 0
+    issues_critical: 0
+    issues_major: 0
+routing:
+  after_master_check:
+    last_verdict: "PASS"
+    last_fail_reason: null
+    route_decision: "implement"
+current_phase: "R.0"
+phase_status: "done"
+```
+
+**Append vào `_session.md`**:
+```markdown
+### [R.0] Master Check — [YYYY-MM-DD]
+- **Verdict**: [PASS | PASS_WITH_CONCERNS | FAIL]
+- **Issues**: [N] critical, [N] major, [N] concerns
+- **Routing**: [route_decision] — [lý do]
+```
+
+---
+
+## Ví dụ
+
+```
+/v.check Feature 001-user-login
+```

package/commands/v.constitute.md

@@ -0,0 +1,87 @@
+---
+description: "Constitute Agent — AI phân tích dự án và tự động draft constitution.md v2"
+phase: "S.0a"
+agent: "constitute-agent"
+---
+
+# /v.constitute
+
+> Orchestration wrapper cho **Constitute Agent**. Đọc `agents/constitute-agent.md` để thực hiện core logic.
+
+> ⚠️ **Khác với `/v.constitution`**: Lệnh cũ hỏi user từng bước (interactive). Lệnh này **tự scan codebase và draft**, user chỉ cần review sau.
+
+## Điều kiện tiên quyết
+- `.v-flow/` phải tồn tại (đã chạy `v-flow init`)
+- `.v-flow/constitution.md` nên tồn tại (v1 template từ init)
+- Ưu tiên đọc `.v-flow/context.md` nếu đã có
+
+## Execution
+1. Đọc agent definition: `agents/constitute-agent.md`
+2. Thực hiện toàn bộ quy trình trong agent definition
+3. Ghi đè `constitution.md` với v2 (AI-drafted)
+
+## Options
+
+### (không có argument) — Scan codebase tự động
+AI scan codebase, infer patterns, draft constitution.
+
+### --from-context — Ưu tiên đọc context.md
+```
+/v.constitute --from-context
+```
+Ưu tiên đọc `context.md` thay vì scan lại codebase từ đầu.
+
+### [text kèm] — Kèm mô tả ngắn
+```
+/v.constitute Dự án Flutter mobile app, team 5 người
+```
+Kèm context bổ sung giúp AI draft chính xác hơn.
+
+---
+
+## 🔀 Routing Rules — Sau Constitute
+
+```
+Constitution v2 được tạo
+  → Tech Lead review:
+    1. Xác nhận / chỉnh sửa [⚠️ AI-inferred]
+    2. Điền [Cần quyết định] (đặc biệt AI models, privacy)
+    3. Xóa header warning → constitution có hiệu lực
+  → Sau approve: S.0b (agent-config.md) hoặc S.1 (/v.specify)
+
+Dự án legacy chưa có module cards
+  → /v.understand --module (generate Module Cards)
+```
+
+## Cập nhật State & Session
+
+**Cập nhật `.flow-state.yaml`**:
+```yaml
+current_phase: "S.0a"
+phase_status: "awaiting_human"
+```
+
+**Append vào `_session.md`**:
+```markdown
+### [S.0a] Constitution — [YYYY-MM-DD]
+- **Agent**: Constitute Agent
+- **Output**: `constitution.md` v2 (AI-drafted)
+- **Sections inferred**: [N]/7
+- **Sections needing human**: [N] `[Cần quyết định]`
+- **Routing**: → Await Tech Lead review
+```
+
+---
+
+## Output
+- `.v-flow/constitution.md` **(v2 — AI-drafted, cần Tech Lead review & approve)**
+
+---
+
+## Ví dụ
+
+```
+/v.constitute
+/v.constitute Dự án Flutter mobile app, team 5 người
+/v.constitute --from-context
+```