@damphuquy/agent-init 2.2.0 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@damphuquy/agent-init",
-  "version": "2.2.0",
+  "version": "3.0.0",
   "description": "Scaffolding CLI to bootstrap RIPER-5 Coding Agents & Operational Workspace",
   "type": "module",
   "main": "./dist/index.js",

package/templates/en/.agents/behavior.md

@@ -74,9 +74,18 @@ In continuous autonomous execution (DELEGATED / Fast-Track), the agent opens wit
   | **`process/general-plans/active/{task-slug}/`** | `/task`<br>`/small-task`<br>`/bug`<br>`/quick-fix` | `small task`, `general changes`, `small changes`, `bug fix`, `quick fix` | Standalone tasks, quick bug fixes, general adjustments (< 5 files). Default mode: **PAIR**. |
   | **`process/general-plans/active/{task-slug}/`** | `/hotfix` | `hotfix`, `emergency fix`, `production bug` | Emergency production fix. Auto-activates **DELEGATED / Fast-Track** mode (auto-certifies G0–G2, pauses only at G3). |
   | *(Scope-derived)* | `/fast-track`<br>`/delegated`<br>`/auto` | `fast-track`, `autonomous`, `auto-advance`, `skip permissions` | Full autonomous execution. Sets `<working_mode>DELEGATED</working_mode>` and runs continuously through all phases. |
+  | *(Framework Maintenance)* | `/update`<br>`/upgrade` | `update instructions`, `upgrade framework`, `check updates` | Maintenance protocol: queries remote registry for a newer framework version. If a newer version exists, updates the instructions framework while preserving user configs (`preserveUserFiles`) and updates `instruction-version.json`. If already on the latest version, outputs `"nothing changed"`. |
 
   *Fallback Rule:* If no explicit keyword or slash command is found in the prompt, infer from scope (< 5 files or localized fix $\rightarrow$ `general-plans/`; new capability or multi-module impact $\rightarrow$ `features/`).
 
+  ### Framework Update Protocol (`/update`):
+  When the prompt begins with `/update` or `/upgrade` (or user asks to update instructions/framework):
+  1. **Inspect Local Version:** Read `instruction-version.json` at workspace root to inspect current `version`, `language`, and `updateStrategy`.
+  2. **Query Latest Version:** Query the registry (e.g. `npm view @damphuquy/agent-init version` or execute `npx @damphuquy/agent-init update`).
+  3. **Conditional Update:**
+     - **If newer version found:** Execute framework update (e.g. `npx @damphuquy/agent-init update` or `npx @damphuquy/agent-init@latest . --force`), preserving project-specific files defined in `preserveUserFiles` (`AGENTS.md#validation_commands`, active tasks). Update `instruction-version.json` timestamp and version. Report upgrade details.
+     - **If no newer version (already up to date):** Respond directly with `"nothing changed"` (e.g. `nothing changed: instruction framework is already at the latest version vX.Y.Z`) and make no file changes.
+
   ### Automated Scaffolding & Activation Steps:
   1. **Derive Slug:** Generate a concise, kebab-case `{task-slug}` from the prompt (e.g., `CHG-001-change-password`, `AUTH-002-rate-limiting`, or `{TICKET-ID}-{slug}`).
   2. **Create Directory:** Create `process/features/active/{task-slug}` or `process/general-plans/active/{task-slug}`.

package/templates/en/.agents/guardrails.md

@@ -111,4 +111,26 @@
   4. **State Finalization:** Ensure `state.md` is cleanly synchronized and generate `handoff.md`.
 </housekeeping_protocol>
 
+---
+
+## 7. Cross-Harness & Independent Review Principle
+
+<cross_harness_review>
+  Rule: **The implementer cannot be the sole reviewer.**
+  - To eliminate confirmation bias and algorithmic blind spots, the REVIEW phase should be conducted with fresh context, an independent reviewer subagent, or a distinct model harness when available.
+  - Reviewers evaluate code strictly against the `<scope_contract>`, security guidelines, and behavioral invariants without inheriting the implementer's speculative reasoning.
+</cross_harness_review>
+
+---
+
+## 8. Graduated Quality Gate Strictness
+
+<gate_strictness>
+  Quality gates operate under a 3-tier graduated enforcement model:
+
+  - **Hard-Mandatory (Blocking):** Zero tolerance. Must pass 100% without exception (e.g. typecheck, test suites, zero out-of-scope edits). Failure immediately blocks task completion.
+  - **Soft-Mandatory (Overridable with Justification):** Required by default. May only be overridden by the human engineer with a recorded rationale in `<override_reason>` (e.g. temporary performance baseline waiver).
+  - **Advisory (Informational):** Non-blocking recommendations, lint hints, or future technical debt observations logged into `review.md`.
+</gate_strictness>
+
 </agent_guardrails>

package/templates/en/AGENTS.md

@@ -10,6 +10,7 @@
 
   This file ONLY contains what is unique to this project: toolchain commands,
   architecture guardrail calibration, and path references.
+  Framework versioning and update procedures are managed via [`instruction-version.json`](instruction-version.json).
 </overview>
 
 ---
@@ -21,6 +22,7 @@
 
   | File | What it governs |
   |------|----------------|
+  | [`instruction-version.json`](instruction-version.json) | Framework version manifest, compatibility, and update strategy |
   | [`.agents/behavior.md`](.agents/behavior.md) | Mode declaration, session startup, context priority |
   | [`.agents/guardrails.md`](.agents/guardrails.md) | Retry budget, escalation triggers, completion gate |
   | [`.agents/conventions/naming.md`](.agents/conventions/naming.md) | Naming and structural hygiene |
@@ -35,23 +37,32 @@
 <foundations>
   <!-- Pillar 1: Task & Specification -->
   <pillar id="task_spec" title="Task & Specification">
-    <rule>Single Source of Truth: Active task file in [`process/features/active/{feature}/task.md`](process/features/) or [`process/general-plans/active/{task}/task.md`](process/general-plans/) (instantiated from [`process/_seeds/task-template.md.seed`](process/_seeds/task-template.md.seed)).</rule>
-    <rule>Prompt & Slash Command Initialization: Users can request and run tasks directly via prompt or pseudo-slash command prefixes. The Agent automatically routes the folder and instantiates `task.md` from [`process/_seeds/task-template.md.seed`](process/_seeds/task-template.md.seed):
-      - Commands `/feature`, `/big-task`, `/epic` or keywords `big task`, `feature`, `big changes`: routes to `process/features/active/{task-slug}/task.md` (PAIR mode).
-      - Commands `/task`, `/small-task`, `/bug` or keywords `small task`, `general changes`, `small changes`: routes to `process/general-plans/active/{task-slug}/task.md` (PAIR mode).
-      - Command `/hotfix`: routes to `process/general-plans/active/{task-slug}/task.md` and runs in DELEGATED mode.
+    <rule>Single Source of Truth: Active task file in [`process/features/active/{feature}/task.md`](process/features/) (Full Track) or [`process/general-plans/active/{task}/task-lite.md`](process/general-plans/) (Lite Track).</rule>
+    <rule>Dual-Track Routing:
+      - **Full Track (7 artifacts):** For complex features, epics, and cross-cutting refactoring. Initiated from [`process/_seeds/task-template.md.seed`](process/_seeds/task-template.md.seed) in `process/features/active/{task-slug}/`. Chain: `task.md → research.md → decision.md → plan.md → state.md → review.md → handoff.md`.
+      - **Lite Track (1 artifact):** For quick tasks, bugfixes, micro-features, and hotfixes. Initiated from [`process/_seeds/task-lite.md.seed`](process/_seeds/task-lite.md.seed) in `process/general-plans/active/{task-slug}/task-lite.md`. Consolidates spec, allowed files, slices, and verification gates into a single file to eliminate token overhead.</rule>
+    <rule>Prompt & Slash Command Initialization: Users can request and run tasks directly via prompt or pseudo-slash command prefixes:
+      - Commands `/feature`, `/big-task`, `/epic` or keywords `big task`, `feature`, `big changes`: routes to Full Track in `process/features/active/{task-slug}/task.md` (PAIR mode).
+      - Commands `/task`, `/small-task`, `/bug` or keywords `small task`, `bug`: routes to Lite Track in `process/general-plans/active/{task-slug}/task-lite.md` (PAIR mode).
+      - Command `/hotfix`: routes to Lite Track in `process/general-plans/active/{task-slug}/task-lite.md` and runs in DELEGATED mode.
       - Commands `/fast-track`, `/delegated`: executes autonomously through all phases.
-      The Agent creates the directory, hydrates `<goal>` and `<acceptance_criteria>` from the prompt, and initiates the RESEARCH phase immediately.</rule>
-    <rule>Define changes via Goal, Current Behavior, Expected Behavior, Invariants, and `<out_of_scope>`.</rule>
-    <rule>Acceptance Criteria (AC) must be unambiguous, verifiable markdown checkboxes (`- [ ]`).</rule>
-    <rule>Every task has a master contract (`task.md`) and a full artifact chain: `research.md → decision.md → plan.md → state.md → review.md → handoff.md`.</rule>
+      - Command `/sync`: runs `npx @damphuquy/agent-init sync` to mirror `AGENTS.md` to `.cursor/rules/`, `CLAUDE.md`, and `.windsurfrules`.
+      - Command `/verify-gate [G2|G3]`: verifies that no modified files in `git diff` violate `<allowed_files>`.
+      - Command /update: checks for a new framework version (via `instruction-version.json` and registry); updates instructions if a newer version exists, or outputs "nothing changed" if already on the latest version.</rule>
+    <rule>Define changes via Goal, Invariants, `<scope_contract>`, and Acceptance Criteria.</rule>
   </pillar>
 
-  <!-- Pillar 2: Context Navigation -->
-  <pillar id="context" title="Context Navigation">
+  <!-- Pillar 2: Context Navigation & Model Context Protocol (MCP) -->
+  <pillar id="context" title="Context Navigation & MCP">
     <rule>Gather minimum sufficient context. No full-repo scanning or drive-by refactoring.</rule>
     <rule>Follow information priority defined in [`.agents/behavior.md`](.agents/behavior.md).</rule>
     <rule>Project context routes via [`process/context/all-context.md`](process/context/all-context.md).</rule>
+    <mcp_tools>
+      When available, agents must prioritize native Model Context Protocol (MCP) tools:
+      - Database MCP: Inspect schemas and run read-only queries instead of hardcoded mock assumptions.
+      - Git MCP: Query log/diff cleanly without unconstrained shell parsing.
+      - Browser/DevTools MCP: Inspect live DOM/accessibility tree during UI review.
+    </mcp_tools>
   </pillar>
 
   <!-- Pillar 3: Engineering Harness & Guardrails -->
@@ -62,6 +73,12 @@
       # Node/TS: npm run test && npm run typecheck && npm run lint
       # Go:      go test ./... && go vet ./...
     </validation_commands>
+    <action_governance>
+      Agents operate under strict containment:
+      - Anti-Escape: Never modify files outside `<allowed_files>` or unapproved root configurations (`package.json`, workflow CI files) unless explicitly specified in `plan.md`.
+      - Safety Blacklist: Never execute destructive commands (`git push -f`, `git reset --hard`, recursive unconstrained deletes, `DROP TABLE`).
+      - Non-Implementer Review: Authors must never unilaterally certify their own work; review requires independent verification.
+    </action_governance>
     <architecture_guardrail>
       Clean Architecture & Dependency Injection provide structural guidance, NOT an
       instruction to blindly over-engineer simple utilities.

package/templates/en/instruction-version.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "name": "@damphuquy/agent-init",
+  "version": "3.0.0",
+  "framework": "RIPER-5",
+  "frameworkVersion": "3.0.0",
+  "language": "en",
+  "description": "Instruction and governance template manifest for AI coding agents and operational workspace.",
+  "installedAt": "2026-09-09T00:00:00.000Z",
+  "updatedAt": "2026-09-09T00:00:00.000Z",
+  "manifest": {
+    "core": [
+      "AGENTS.md",
+      "instruction-version.json"
+    ],
+    "controlLayer": [
+      ".agents/README.md",
+      ".agents/behavior.md",
+      ".agents/guardrails.md",
+      ".agents/conventions/naming.md"
+    ],
+    "seeds": [
+      "process/_seeds/_GUIDE.md",
+      "process/_seeds/task-template.md.seed",
+      "process/_seeds/task-lite.md.seed",
+      "process/_seeds/context-group.md.seed",
+      "process/_seeds/decision-template.md.seed",
+      "process/_seeds/plan-template.md.seed",
+      "process/_seeds/state-template.md.seed",
+      "process/_seeds/review-template.md.seed",
+      "process/_seeds/handoff-template.md.seed",
+      "process/_seeds/cancellation-template.md.seed",
+      "process/_seeds/pause-template.md.seed",
+      "process/_seeds/results-template.tsv.seed",
+      "process/_seeds/program-template.md.seed"
+    ],
+    "context": [
+      "process/context/all-context.md",
+      "process/context/planning/all-planning.md",
+      "process/context/tests/all-tests.md"
+    ],
+    "protocols": [
+      "process/development-protocols/all-development-protocols.md",
+      "process/development-protocols/orchestration.md",
+      "process/development-protocols/implementation-standards.md"
+    ]
+  },
+  "updateStrategy": {
+    "slashCommand": "/update",
+    "checkCommand": "npm view @damphuquy/agent-init version",
+    "updateCommand": "npx @damphuquy/agent-init update",
+    "forceUpdateCommand": "npx @damphuquy/agent-init@latest . --force",
+    "preserveUserFiles": [
+      "AGENTS.md#validation_commands",
+      "process/features/**",
+      "process/general-plans/**"
+    ],
+    "safeToOverwrite": [
+      ".agents/**",
+      "process/_seeds/**",
+      "process/context/**",
+      "process/development-protocols/**",
+      "instruction-version.json"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DamPhuQuy/agent-instructions"
+  }
+}

package/templates/en/process/_seeds/_GUIDE.md

@@ -23,9 +23,18 @@
 <catalog>
 
   <seed type="task" path="task-template.md.seed">
-    Master contract and state record for the full RIPER-5 lifecycle.
+    Master contract and state record for the full RIPER-5 lifecycle (Full Track: 7 artifacts).
     Contains: Task Control metadata (working_mode PAIR/DELEGATED), Spec, Context Boundaries, Verification Strategy,
     Decisions, RIPER-5 Execution Plan (with Gates G0–G3), and Guardrails.
+    Recommended for: Complex features, architectural refactors, and Epics in `process/features/`.
+  </seed>
+
+  <seed type="task-lite" path="task-lite.md.seed">
+    Consolidated single-file contract for RIPER-5 Lite Track (1 artifact).
+    Combines: Intent, Invariants, Scope Contract (<allowed_files>), Compact Vertical Slices,
+    and Consolidated Verification Gates (G1/G2/G3).
+    Recommended for: Small tasks, bugfixes, micro-features, and hotfixes in `process/general-plans/`.
+    Reduces token tax and context overhead by over 70%.
   </seed>
 
   <seed type="research" path="context-group.md.seed">

package/templates/en/process/_seeds/plan-template.md.seed

@@ -109,11 +109,11 @@
 <!-- Populated during and after Execute phase -->
 <verification_matrix>
 
-| AC / Risk | Test / Command | Expected Evidence | Actual Result |
-|---|---|---|---|
-| AC-1 | | | |
-| AC-2 | | | |
-| AC-3 | | | |
+| AC / Risk | Test / Command | Expected Evidence | Strictness (hard-mandatory / soft-mandatory / advisory) | Actual Result |
+|---|---|---|---|---|
+| AC-1 | | | hard-mandatory | |
+| AC-2 | | | hard-mandatory | |
+| AC-3 | | | advisory | |
 
 </verification_matrix>
 
@@ -124,6 +124,7 @@
 <gate id="G2">
   - [ ] Every slice has a defined verifier.
   - [ ] Scope contract (allowed / forbidden) approved.
+  - [ ] Enforcement strictness assigned per AC/verification item.
   - [ ] Stop conditions defined per slice.
   - [ ] Rollback point defined per slice.
   - [ ] Allowed commands listed.

package/templates/en/process/_seeds/review-template.md.seed

@@ -7,6 +7,7 @@
   <phase>REVIEW</phase>
   <mode>READ-ONLY</mode>
   <reviewer></reviewer>
+  <reviewer_harness></reviewer_harness>  <!-- e.g. human-pair / independent-subagent / cross-model-harness -->
   <last_updated></last_updated>
 </review_status>
 
@@ -136,6 +137,7 @@
 
 <gate id="G3">
   - [ ] Full diff reviewed (zero extraneous changes).
+  - [ ] Independent review verified (implementer was not sole reviewer).
   - [ ] Housekeeping complete: all transient debug logs, print statements, and scratch files removed.
   - [ ] All required evidence exists and is attached.
   - [ ] All findings triaged (Confirmed Defects resolved or risk-accepted).

package/templates/en/process/_seeds/task-lite.md.seed

@@ -0,0 +1,88 @@
+# Task Lite: [TASK-ID] [Task Title]
+
+<task_lite version="3.0" framework="RIPER-5-Lite">
+
+<!-- ════════════════════════════════════════════
+     SECTION 0 — TASK CONTROL
+     ════════════════════════════════════════════ -->
+<task_control>
+  <track>LITE</track>  <!-- LITE: Single-file artifact for fast iteration, bugfixes, micro-tasks -->
+  <status>ACTIVE</status>  <!-- ACTIVE | REVIEW | COMPLETED | CANCELLED -->
+  <priority>P2</priority>  <!-- P0=urgent | P1=high | P2=normal | P3=low -->
+  <working_mode>PAIR</working_mode>  <!-- PAIR (review at gates) | DELEGATED (autonomous run) -->
+  <current_phase>PLAN</current_phase>  <!-- PLAN | EXECUTE | REVIEW -->
+  <owner>@engineer</owner>
+</task_control>
+
+---
+
+## 1. Intent & Specification
+
+<specification>
+  <goal>
+    [Clear description of the fix, enhancement, or micro-feature]
+  </goal>
+
+  <invariants>
+    - [Key constraint that must NOT be broken during this task]
+  </invariants>
+
+  <acceptance_criteria>
+    - [ ] AC-1: [Specific verifiable outcome with expected behavior]
+    - [ ] AC-2: [Automated tests or lint checks passing]
+  </acceptance_criteria>
+
+  <!-- Definition-of-Ready (DoR): Do not begin coding if problem or allowed files are vague -->
+  <definition_of_ready>
+    - [ ] Intent and acceptance criteria are clear without assumptions.
+    - [ ] Allowed files in Section 2 are identified.
+  </definition_of_ready>
+</specification>
+
+---
+
+## 2. Scope Contract & File Whitelist
+
+<scope_contract>
+  <allowed_files>
+    <file>[exact/path/to/file1.ts]</file>
+    <file>[exact/path/to/file1.test.ts]</file>
+  </allowed_files>
+
+  <forbidden_files>
+    <file>[any/file/outside/the/scope]</file>
+  </forbidden_files>
+</scope_contract>
+
+---
+
+## 3. Execution Plan (Compact Slices)
+
+<execution_plan>
+  ### Slice 1: [Core Change Title]
+  - **Action:** [What code or test to write]
+  - **Verifier:** [e.g., npm test path/to/test.ts || pytest path/to/test.py]
+  - **Status:** [ ] PENDING / IN_PROGRESS / DONE
+
+  ### Slice 2 (Optional): [Secondary / Integration Change]
+  - **Action:** [What code or test to write]
+  - **Verifier:** [Command to run]
+  - **Status:** [ ] PENDING / IN_PROGRESS / DONE
+</execution_plan>
+
+---
+
+## 4. Consolidated Verification & Gates
+
+<verification_gates>
+  <!-- Gate G1/G2: Scope & Architecture check (pre-execution) -->
+  - [ ] **Gate G1/G2 (Plan Approved):** Allowed files confirmed, test verifiers defined.
+
+  <!-- Gate G3: Verification evidence (post-execution) -->
+  - [ ] **Gate G3 (Ready for Handoff):**
+    - [ ] Verifier commands executed cleanly (Zero errors).
+    - [ ] Git diff inspected — NO files touched outside `<allowed_files>`.
+    - [ ] No temporary debug logs or unintended changes.
+</verification_gates>
+
+</task_lite>

package/templates/en/process/_seeds/task-template.md.seed

@@ -53,6 +53,14 @@
     - [ ] AC-2: [Edge cases, validation rules, or error handling]
     - [ ] AC-3: [Automated tests added/updated and passing]
   </acceptance_criteria>
+
+  <!-- Definition-of-Ready (DoR) Gate — Frontload the thinking before dispatch -->
+  <definition_of_ready>
+    - [ ] Target outcome and acceptance criteria are verifiable without guessing.
+    - [ ] Invariants and <out_of_scope> boundaries are explicit.
+    - [ ] Open questions resolved or scheduled in decision.md (No speculative coding).
+    <!-- STOP: If any DoR item is unchecked, halt and ask clarifying questions first! -->
+  </definition_of_ready>
 </specification>
 
 ---

package/templates/en/process/development-protocols/orchestration.md

@@ -98,4 +98,23 @@
   </rule>
 </coordination_and_recovery>
 
+---
+
+## 6. Cross-Harness & Independent Review Protocol
+
+<cross_harness_review>
+  <rule id="implementer_cannot_review">
+    The subagent or harness that authored an implementation must NEVER act as the sole approver of that slice.
+    To prevent confirmation bias, delegate the verification of complex or security-sensitive slices to an independent review subagent, or require human gate sign-off.
+  </rule>
+
+  <rule id="adversarial_verification">
+    Review subagents must be tasked with finding edge-case regressions, compliance violations, and scope breaches against `<scope_contract>`, rather than merely validating the author's declared success.
+  </rule>
+
+  <rule id="fresh_context_mandate">
+    Independent review subagents should operate with clean context: they receive the task requirements, the git diff, and the test command, without the conversational baggage or speculative rationale of the implementation loop.
+  </rule>
+</cross_harness_review>
+
 </orchestration_protocol>

package/templates/vi/.agents/behavior.md

@@ -74,9 +74,18 @@ Trong chế độ chạy liên tục (DELEGATED / Fast-Track), Agent mở đầu
   | **`process/general-plans/active/{task-slug}/`** | `/task`<br>`/small-task`<br>`/bug`<br>`/quick-fix` | `small task`, `general changes`, `small changes`, `bug fix`, `quick fix` (hoặc: `task nhỏ`, `thay đổi chung`, `thay đổi nhỏ`, `sửa lỗi`) | Tác vụ độc lập, sửa bug nhanh, thay đổi nhỏ (< 5 files). Chế độ mặc định: **PAIR**. |
   | **`process/general-plans/active/{task-slug}/`** | `/hotfix` | `hotfix`, `khẩn cấp`, `emergency fix` | Sửa lỗi khẩn cấp production. Tự động kích hoạt chế độ **DELEGATED / Fast-Track** (vượt tự động G0–G2, dừng ở G3). |
   | *(Theo phạm vi)* | `/fast-track`<br>`/delegated`<br>`/auto` | `fast-track`, `autonomous`, `tự động chạy`, `skip permissions` | Chạy tự trị hoàn toàn. Tự động đặt `<working_mode>DELEGATED</working_mode>` và thực thi liên tục qua toàn bộ chu trình. |
+  | *(Bảo trì Framework)* | `/update`<br>`/upgrade` | `update instructions`, `cập nhật instruction`, `nâng cấp framework`, `kiểm tra bản mới` | Giao thức bảo trì: kiểm tra phiên bản framework mới nhất từ registry. Nếu phát hiện version mới hơn, cập nhật bộ quy chuẩn chỉ dẫn (bảo toàn tệp cấu hình dự án `preserveUserFiles`) và cập nhật `instruction-version.json`. Nếu đang ở bản mới nhất, thông báo `"nothing changed"`. |
 
   *Quy tắc suy luận dự phòng (Fallback):* Nếu prompt không chứa từ khóa hay slash command rõ ràng, Agent tự động ước lượng quy mô công việc (< 5 files hoặc sửa lỗi cục bộ $\rightarrow$ `general-plans/`; tính năng mới hoặc ảnh hưởng diện rộng $\rightarrow$ `features/`).
 
+  ### Giao Thức Cập Nhật Framework (`/update`):
+  Khi prompt bắt đầu bằng lệnh `/update` hoặc `/upgrade` (hoặc người dùng yêu cầu cập nhật instruction/framework):
+  1. **Đọc phiên bản hiện hành:** Đọc tệp `instruction-version.json` tại thư mục gốc của dự án để lấy `version`, `language`, và `updateStrategy`.
+  2. **Tra cứu phiên bản mới:** Kiểm tra phiên bản mới nhất trên registry (`npm view @damphuquy/agent-init version` hoặc chạy lệnh `npx @damphuquy/agent-init update`).
+  3. **Xử lý có điều kiện:**
+     - **Nếu có phiên bản mới hơn:** Chạy lệnh cập nhật (ví dụ: `npx @damphuquy/agent-init update` hoặc `npx @damphuquy/agent-init@latest . --force`), bảo toàn các tệp dự án theo danh mục `preserveUserFiles` trong `instruction-version.json` (như lệnh test trong `AGENTS.md`, các task đang làm). Cập nhật `version` và `updatedAt` trong `instruction-version.json`. Báo cáo tóm tắt nâng cấp từ bản cũ lên bản mới.
+     - **Nếu không có bản mới hơn (đang là mới nhất):** Phản hồi trực tiếp `"nothing changed"` (ví dụ: `nothing changed: quy chuẩn chỉ dẫn đang ở phiên bản mới nhất vX.Y.Z`) và tuyệt đối không sửa đổi file nào.
+
   ### Quy Trình Khởi Tạo & Kích Hoạt Tự Động:
   1. **Đặt tên slug:** Đặt `{task-slug}` ngắn gọn, chuẩn kebab-case dựa theo yêu cầu (ví dụ: `CHG-001-change-password`, `AUTH-002-rate-limiting`, hoặc `{TICKET-ID}-{slug}`).
   2. **Tạo thư mục:** Tạo thư mục `process/features/active/{task-slug}` hoặc `process/general-plans/active/{task-slug}`.

package/templates/vi/.agents/guardrails.md

@@ -111,4 +111,26 @@
   4. **Chốt Trạng Thái:** Đảm bảo `state.md` được đồng bộ sạch sẽ và tạo tệp `handoff.md`.
 </housekeeping_protocol>
 
+---
+
+## 7. Nguyên Tắc Đánh Giá Độc Lập & Đa Harness (Cross-Harness Review)
+
+<cross_harness_review>
+  Quy tắc: **Người thực hiện không thể là người đánh giá duy nhất (The implementer cannot be the sole reviewer).**
+  - Nhằm triệt tiêu thiên kiến xác nhận (confirmation bias) và điểm mù thuật toán, giai đoạn REVIEW nên được thực hiện với ngữ cảnh mới, subagent reviewer độc lập hoặc harness mô hình tách biệt khi có thể.
+  - Reviewer đánh giá mã nguồn nghiêm ngặt dựa trên `<scope_contract>`, hướng dẫn bảo mật và các bất biến hành vi mà không kế thừa các suy luận chủ quan của người thực hiện.
+</cross_harness_review>
+
+---
+
+## 8. Phân Cấp Độ Nghiêm Ngặt Của Quality Gate (Graduated Gate Strictness)
+
+<gate_strictness>
+  Quality gate vận hành theo mô hình phân cấp 3 tầng nghiêm ngặt:
+
+  - **Hard-Mandatory (Bắt Buộc Tuyệt Đối - Chặn):** Không có ngoại lệ. Phải vượt qua 100% (ví dụ: typecheck, test suite, không có chỉnh sửa ngoài phạm vi). Thất bại sẽ lập tức chặn hoàn thành task.
+  - **Soft-Mandatory (Bắt Buộc Mềm - Ghi Đè Khi Có Lý Do):** Mặc định bắt buộc. Chỉ có thể được ghi đè bởi kỹ sư con người kèm lý do hợp lý được ghi nhận trong `<override_reason>` (ví dụ: miễn giảm tạm thời baseline hiệu năng).
+  - **Advisory (Khuyến Nghị - Thông Tin):** Đóng góp khuyến nghị không chặn, gợi ý linter hoặc ghi nhận nợ kỹ thuật tương lai vào `review.md`.
+</gate_strictness>
+
 </agent_guardrails>

package/templates/vi/AGENTS.md

@@ -10,6 +10,7 @@
 
   Tệp này CHỈ chứa những gì đặc thù của dự án: lệnh kiểm thử/build,
   hiệu chỉnh ranh giới kiến trúc và tham chiếu đường dẫn.
+  Phiên bản framework và quy trình cập nhật chỉ dẫn được quản lý qua [`instruction-version.json`](instruction-version.json).
 </overview>
 
 ---
@@ -21,6 +22,7 @@
 
   | Tệp | Phạm vi quản lý |
   |-----|----------------|
+  | [`instruction-version.json`](instruction-version.json) | Định danh phiên bản framework, tính tương thích và chiến lược cập nhật |
   | [`.agents/behavior.md`](.agents/behavior.md) | Khai báo chế độ (Mode), khởi động session, thứ tự ưu tiên ngữ cảnh |
   | [`.agents/guardrails.md`](.agents/guardrails.md) | Ngân sách thử lại (Retry budget), điều kiện kích hoạt dừng khẩn cấp, cổng hoàn thành |
   | [`.agents/conventions/naming.md`](.agents/conventions/naming.md) | Quy chuẩn đặt tên và vệ sinh cấu trúc mã nguồn |
@@ -35,23 +37,32 @@
 <foundations>
   <!-- Trụ cột 1: Task & Specification -->
   <pillar id="task_spec" title="Task & Đặc tả (Specification)">
-    <rule>Nguồn sự thật duy nhất (Single Source of Truth): Tệp task đang thực thi trong [`process/features/active/{feature}/task.md`](process/features/) hoặc [`process/general-plans/active/{task}/task.md`](process/general-plans/) (khởi tạo từ [`process/_seeds/task-template.md.seed`](process/_seeds/task-template.md.seed)).</rule>
-    <rule>Khởi tạo qua Prompt & Lệnh Gạch Chéo (Prompt & Slash Command Initialization): Người dùng có thể yêu cầu tạo và chạy task trực tiếp bằng prompt hoặc tiền tố lệnh gạch chéo (Pseudo-Slash Commands). Agent tự động định tuyến thư mục và khởi tạo `task.md` từ [`process/_seeds/task-template.md.seed`](process/_seeds/task-template.md.seed):
-      - Cú pháp `/feature`, `/big-task`, `/epic` hoặc các từ khóa `big task`, `feature`, `big changes`: định tuyến vào `process/features/active/{task-slug}/task.md` (chế độ PAIR).
-      - Cú pháp `/task`, `/small-task`, `/bug` hoặc các từ khóa `small task`, `general changes`, `small changes`: định tuyến vào `process/general-plans/active/{task-slug}/task.md` (chế độ PAIR).
-      - Cú pháp `/hotfix`: định tuyến vào `process/general-plans/active/{task-slug}/task.md` và chạy chế độ DELEGATED.
+    <rule>Nguồn sự thật duy nhất (Single Source of Truth): Tệp task đang thực thi trong [`process/features/active/{feature}/task.md`](process/features/) (Full Track) hoặc [`process/general-plans/active/{task}/task-lite.md`](process/general-plans/) (Lite Track).</rule>
+    <rule>Cơ chế Định tuyến Đôi (Dual-Track Routing):
+      - **Full Track (7 artifacts):** Dành cho tính năng phức tạp, epic lớn, tái cấu trúc kiến trúc. Khởi tạo từ [`process/_seeds/task-template.md.seed`](process/_seeds/task-template.md.seed) tại `process/features/active/{task-slug}/`. Chuỗi: `task.md → research.md → decision.md → plan.md → state.md → review.md → handoff.md`.
+      - **Lite Track (1 artifact):** Dành cho tác vụ nhanh, sửa lỗi (bugfix), micro-tasks, và hotfix. Khởi tạo từ [`process/_seeds/task-lite.md.seed`](process/_seeds/task-lite.md.seed) tại `process/general-plans/active/{task-slug}/task-lite.md`. Gom toàn bộ spec, phạm vi file, kế hoạch cắt lát và cổng kiểm chứng vào duy nhất 1 file để triệt tiêu chi phí ngữ cảnh (token tax).</rule>
+    <rule>Khởi tạo qua Prompt & Lệnh Gạch Chéo (Prompt & Slash Command Initialization): Người dùng có thể yêu cầu tạo và chạy task trực tiếp:
+      - Cú pháp `/feature`, `/big-task`, `/epic` hoặc từ khóa `big task`, `feature`, `big changes`: định tuyến Full Track vào `process/features/active/{task-slug}/task.md` (chế độ PAIR).
+      - Cú pháp `/task`, `/small-task`, `/bug` hoặc từ khóa `small task`, `bug`: định tuyến Lite Track vào `process/general-plans/active/{task-slug}/task-lite.md` (chế độ PAIR).
+      - Cú pháp `/hotfix`: định tuyến Lite Track vào `process/general-plans/active/{task-slug}/task-lite.md` và chạy chế độ DELEGATED.
       - Cú pháp `/fast-track`, `/delegated`: chạy tự trị liên tục qua toàn bộ chu trình.
-      Agent tự tạo thư mục, điền mục tiêu & tiêu chí AC từ prompt vào `task.md` và bắt đầu ngay pha RESEARCH.</rule>
-    <rule>Định nghĩa thay đổi thông qua Mục tiêu (Goal), Hành vi hiện tại (Current Behavior), Hành vi kỳ vọng (Expected Behavior), Bất biến (Invariants) và Ngoài phạm vi (`<out_of_scope>`).</rule>
-    <rule>Tiêu chí nghiệm thu (Acceptance Criteria - AC) phải rõ ràng, kiểm chứng được dưới dạng checkbox markdown (`- [ ]`).</rule>
-    <rule>Mỗi task đều có bản hợp đồng master (`task.md`) và chuỗi artifact hoàn chỉnh: `research.md → decision.md → plan.md → state.md → review.md → handoff.md`.</rule>
+      - Cú pháp `/sync`: thực thi `npx @damphuquy/agent-init sync` để ánh xạ `AGENTS.md` sang `.cursor/rules/`, `CLAUDE.md`, và `.windsurfrules`.
+      - Cú pháp `/verify-gate [G2|G3]`: kiểm tra git diff, đảm bảo không có file nào bị sửa ngoài `<allowed_files>`.
+      - Cú pháp `/update`: kiểm tra và nâng cấp phiên bản quy chuẩn chỉ dẫn (qua `instruction-version.json`); nếu đã ở bản mới nhất thì xuất ra "nothing changed".</rule>
+    <rule>Định nghĩa thay đổi thông qua Mục tiêu (Goal), Bất biến (Invariants), Hợp đồng phạm vi (`<scope_contract>`), và Tiêu chí nghiệm thu (AC).</rule>
   </pillar>
 
-  <!-- Trụ cột 2: Context Navigation -->
-  <pillar id="context" title="Điều hướng & Nạp ngữ cảnh (Context Navigation)">
+  <!-- Trụ cột 2: Context Navigation & Model Context Protocol (MCP) -->
+  <pillar id="context" title="Điều hướng ngữ cảnh & MCP">
     <rule>Chỉ thu thập ngữ cảnh tối thiểu đủ dùng (Minimum Sufficient Context). Tuyệt đối không quét toàn bộ repo hay tự ý refactor ngoài phạm vi.</rule>
     <rule>Tuân thủ thứ tự ưu tiên thông tin được định nghĩa trong [`.agents/behavior.md`](.agents/behavior.md).</rule>
     <rule>Định tuyến ngữ cảnh dự án thông qua [`process/context/all-context.md`](process/context/all-context.md).</rule>
+    <mcp_tools>
+      Khi môi trường có sẵn Model Context Protocol (MCP), agent phải ưu tiên sử dụng MCP tools:
+      - Database MCP: Truy vấn schema và dữ liệu trực tiếp, không giả định schema mò mẫm.
+      - Git MCP: Đọc log/diff chính xác, tránh parsing lệnh shell tự do.
+      - Browser/DevTools MCP: Khảo sát live DOM / cây accessibility khi nghiệm thu giao diện.
+    </mcp_tools>
   </pillar>
 
   <!-- Trụ cột 3: Engineering Harness & Guardrails -->
@@ -62,6 +73,12 @@
       # Node/TS: npm run test && npm run typecheck && npm run lint
       # Go:      go test ./... && go vet ./...
     </validation_commands>
+    <action_governance>
+      Agent vận hành dưới cơ chế kiểm soát và ngăn chặn vi phạm nghiêm ngặt:
+      - Chống vượt ranh giới (Anti-Escape): Tuyệt đối không sửa đổi file ngoài danh sách `<allowed_files>` hoặc cấu hình gốc dự án chưa được duyệt (`package.json`, CI workflow) trừ khi được chỉ định rõ trong `plan.md`.
+      - Danh sách cấm an toàn (Safety Blacklist): Tuyệt đối không thực thi các lệnh phá hủy (`git push -f`, `git reset --hard`, xóa đệ quy không giới hạn, `DROP TABLE`).
+      - Nghiệm thu phi triển khai (Non-Implementer Review): Người trực tiếp viết code không được tự ý đơn phương nghiệm thu; việc nghiệm thu bắt buộc phải qua thẩm định độc lập.
+    </action_governance>
     <architecture_guardrail>
       Clean Architecture & Dependency Injection cung cấp định hướng cấu trúc, KHÔNG PHẢI
       chỉ thị để làm phức tạp hóa quá mức các hàm tiện ích đơn giản.

package/templates/vi/instruction-version.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "name": "@damphuquy/agent-init",
+  "version": "3.0.0",
+  "framework": "RIPER-5",
+  "frameworkVersion": "3.0.0",
+  "language": "vi",
+  "description": "Tệp định danh và kiểm soát phiên bản quy chuẩn chỉ dẫn (instructions) cho AI Coding Agents và Workspace.",
+  "installedAt": "2026-09-09T00:00:00.000Z",
+  "updatedAt": "2026-09-09T00:00:00.000Z",
+  "manifest": {
+    "core": [
+      "AGENTS.md",
+      "instruction-version.json"
+    ],
+    "controlLayer": [
+      ".agents/README.md",
+      ".agents/behavior.md",
+      ".agents/guardrails.md",
+      ".agents/conventions/naming.md"
+    ],
+    "seeds": [
+      "process/_seeds/_GUIDE.md",
+      "process/_seeds/task-template.md.seed",
+      "process/_seeds/task-lite.md.seed",
+      "process/_seeds/context-group.md.seed",
+      "process/_seeds/decision-template.md.seed",
+      "process/_seeds/plan-template.md.seed",
+      "process/_seeds/state-template.md.seed",
+      "process/_seeds/review-template.md.seed",
+      "process/_seeds/handoff-template.md.seed",
+      "process/_seeds/cancellation-template.md.seed",
+      "process/_seeds/pause-template.md.seed",
+      "process/_seeds/results-template.tsv.seed",
+      "process/_seeds/program-template.md.seed"
+    ],
+    "context": [
+      "process/context/all-context.md",
+      "process/context/planning/all-planning.md",
+      "process/context/tests/all-tests.md"
+    ],
+    "protocols": [
+      "process/development-protocols/all-development-protocols.md",
+      "process/development-protocols/orchestration.md",
+      "process/development-protocols/implementation-standards.md"
+    ]
+  },
+  "updateStrategy": {
+    "slashCommand": "/update",
+    "checkCommand": "npm view @damphuquy/agent-init version",
+    "updateCommand": "npx @damphuquy/agent-init update --lang vi",
+    "forceUpdateCommand": "npx @damphuquy/agent-init@latest . --lang vi --force",
+    "preserveUserFiles": [
+      "AGENTS.md#validation_commands",
+      "process/features/**",
+      "process/general-plans/**"
+    ],
+    "safeToOverwrite": [
+      ".agents/**",
+      "process/_seeds/**",
+      "process/context/**",
+      "process/development-protocols/**",
+      "instruction-version.json"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DamPhuQuy/agent-instructions"
+  }
+}

package/templates/vi/process/_seeds/_GUIDE.md

@@ -23,9 +23,18 @@
 <catalog>
 
   <seed type="task" path="task-template.md.seed">
-    Hợp đồng master và bản lưu vết trạng thái xuyên suốt toàn bộ vòng đời RIPER-5.
+    Hợp đồng master và bản lưu vết trạng thái xuyên suốt toàn bộ vòng đời RIPER-5 (Full Track: 7 artifacts).
     Bao gồm: Metadata kiểm soát task (working_mode PAIR/DELEGATED), Đặc tả (Spec), Ranh giới ngữ cảnh, Chiến lược kiểm chứng,
     Quyết định kỹ thuật, Kế hoạch thực thi RIPER-5 (kèm Gates G0–G3), và Ranh giới an toàn (Guardrails).
+    Khuyến nghị cho: Các tính năng phức tạp, tái cấu trúc kiến trúc, và Epic tại `process/features/`.
+  </seed>
+
+  <seed type="task-lite" path="task-lite.md.seed">
+    Hợp đồng tinh gọn gom vào duy nhất 1 artifact cho RIPER-5 Lite Track (1 artifact).
+    Bao gồm: Ý định, Ràng buộc bất biến, Hợp đồng phạm vi (<allowed_files>), Kế hoạch cắt lát tinh gọn,
+    và Cổng kiểm chứng nghiệm thu tổng hợp (G1/G2/G3).
+    Khuyến nghị cho: Tác vụ nhỏ, sửa lỗi (bugfix), tính năng nhỏ (micro-tasks), và hotfix tại `process/general-plans/`.
+    Giảm hơn 70% chi phí token và overhead khởi tạo.
   </seed>
 
   <seed type="research" path="context-group.md.seed">