@damphuquy/agent-init 3.2.0 → 3.3.0

package/package.json

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

package/templates/en/AGENTS.md

@@ -132,6 +132,7 @@
     <constraint>One slice at a time. Run verifier after each slice. Inspect diff after each slice.</constraint>
     <constraint>No unrelated refactoring. No changes to forbidden files.</constraint>
     <constraint>Update `state.md` after every slice.</constraint>
+    <constraint>Cost observability & benchmarking follow strict Trigger Governance: default is OFF (zero-overhead); consolidate section 14 in `state.md` (single-shot) only when `--profile` / `[profile]` is present, and initialize `results.tsv` only when `--bench` / `[benchmark]` is present.</constraint>
     <output>Source code + tests + updated `state.md` with verification evidence. When all slices pass, advance directly to REVIEW.</output>
   </phase>
 

package/templates/en/instruction-version.json

@@ -1,13 +1,13 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "name": "@damphuquy/agent-init",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "framework": "RIPER-5",
-  "frameworkVersion": "3.2.0",
+  "frameworkVersion": "3.3.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-13T00:00:00.000Z",
+  "updatedAt": "2026-09-14T00:00:00.000Z",
   "manifest": {
     "core": [
       "AGENTS.md",

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

@@ -98,6 +98,7 @@
 
   <seed type="results" path="results-template.tsv.seed">
     Benchmark and quantitative metrics evaluation registry.
+    Trigger-based activation (--bench, [benchmark], or <observability_mode>BENCHMARK</observability_mode>).
     Use for tracking latency, throughput, memory, or eval scores across iterations and vertical slices.
   </seed>
 

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

@@ -150,7 +150,8 @@
 
 ## 14. Cost & Resource Observability
 
-<cost_observability>
+<!-- Triggered via flags (--profile, [profile], or <observability_mode>PROFILE|BENCHMARK</observability_mode>). Defaults to status="OFF" for lean execution; updated once at EXECUTE completion before REVIEW. -->
+<cost_observability status="OFF">
   <total_tool_calls>0</total_tool_calls>
   <estimated_tokens_consumed></estimated_tokens_consumed>
   <total_retries_used>0</total_retries_used>  <!-- maximum 3 per unique symptom -->

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

@@ -10,6 +10,7 @@
   <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) -->
+  <observability_mode>OFF</observability_mode>  <!-- OFF (default: lean, zero-overhead) | PROFILE (single-shot cost tally at review) | BENCHMARK (with results.tsv) -->
   <current_phase>PLAN</current_phase>  <!-- PLAN | EXECUTE | REVIEW -->
   <owner>@engineer</owner>
 </task_control>

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

@@ -12,6 +12,7 @@
   <risk>MEDIUM</risk>  <!-- LOW | MEDIUM | HIGH -->
   <estimated_story_points>2</estimated_story_points>  <!-- 1 SP ≈ 2-4 focused engineering hours -->
   <working_mode>PAIR</working_mode>  <!-- PAIR (default: halts at each gate for review) | DELEGATED (fast-track: continuous autonomous run) | MANUAL | DIAGNOSE-ONLY -->
+  <observability_mode>OFF</observability_mode>  <!-- OFF (default: lean, zero-overhead) | PROFILE (single-shot cost tally at review) | BENCHMARK (with results.tsv) -->
   <current_phase>RESEARCH</current_phase>  <!-- RESEARCH | INNOVATE | PLAN | EXECUTE | REVIEW -->
   <owner>@engineer</owner>
   <decision_owner>@engineer</decision_owner>

package/templates/en/process/development-protocols/observability-and-evals.md

@@ -9,7 +9,37 @@
 
 ---
 
-## 1. Cost & Token Observability Governance
+## 1. Trigger-Based Observability & Evals Governance
+
+<trigger_governance>
+  To prevent token bloat and eliminate wasted tool calls, the system implements a strict trigger-based activation model:
+
+  ### 1. Default Mode — Lean & Zero-Overhead:
+  - **Default is OFF (Zero-Overhead):** For standard routine engineering tasks (CRUD, UI tweaks, bugfixes, docs), the agent MUST NOT consume tool calls or context window measuring tokens, counting intermediate tool calls, or generating benchmark tables. The `<cost_observability>` block in `state.md` remains in its default template values.
+
+  ### 2. Explicit Trigger Mechanisms:
+  The agent activates tracking if and only if one of the following triggers is present:
+  - **Prompt Flags:**
+    - `--profile` or `[profile]`: Activates execution cost and resource monitoring for the task.
+    - `--bench` or `[benchmark]`: Activates the quantitative benchmarking lifecycle and creates `results.tsv`.
+    - `--eval` or `[eval]`: Activates deterministic governance evaluation fixtures (`process/evals/`).
+  - **Task Spec Control Field (`task.md` / `task-lite.md`):**
+    - `<observability_mode>PROFILE</observability_mode>`: Activates cost and resource profiling.
+    - `<observability_mode>BENCHMARK</observability_mode>`: Activates dual-run A/B benchmarking (baseline vs candidate).
+
+  ### 3. End-of-Task Single-Shot Finalization:
+  - When `--profile` is triggered, the agent **MUST NOT** perform repetitive updates to `state.md` after each slice.
+  - The agent consolidates metrics (total tool calls, retry count, wall-clock duration) and updates section 14 `<cost_observability>` in `state.md` **exactly once at the end of the EXECUTE phase**, immediately prior to generating `review.md`.
+
+  ### 4. Adaptive Fallback Trigger (Risk-Based):
+  The agent automatically activates cost tracking and `<failure_memory>` recording without explicit flags if:
+  - A vertical slice fails verification more than once (`retries >= 2`).
+  - The task consumes more than 30 tool calls without slice completion.
+</trigger_governance>
+
+---
+
+## 2. Cost & Token Observability Governance
 
 <token_cost_governance>
   Every agent session operates under finite token budgets and computational resource limits.
@@ -28,7 +58,7 @@
 
 ---
 
-## 2. Git-Atomic Commits & Sandboxing Policy
+## 3. Git-Atomic Commits & Sandboxing Policy
 
 <atomic_commits_and_sandboxing>
   ### Git-Atomic Commit Convention:
@@ -52,7 +82,7 @@
 
 ---
 
-## 3. Benchmark & Quantitative Evaluation (Evals Framework)
+## 4. Benchmark & Quantitative Evaluation (Evals Framework)
 
 <evals_framework>
   For performance optimization, architectural refactoring, or algorithmic upgrades:
@@ -65,7 +95,7 @@
 
 ---
 
-## 4. Deterministic Governance Evals & Evidence Hygiene
+## 5. Deterministic Governance Evals & Evidence Hygiene
 
 <governance_evals>
   Use `process/evals/eval-case.json` as an offline, deterministic fixture. A case records input as data, expected policy verdict, expected side effects, and evidence references; it must never cause a command or MCP call to execute.

package/templates/vi/AGENTS.md

@@ -132,6 +132,7 @@
     <constraint>Thực hiện từng lát cắt một. Chạy verifier sau mỗi slice. Kiểm tra diff sau mỗi slice.</constraint>
     <constraint>Không refactor lan man. Không sửa các file bị cấm.</constraint>
     <constraint>Cập nhật `state.md` ngay sau mỗi slice hoàn thành.</constraint>
+    <constraint>Giám sát chi phí & benchmark tuân thủ cơ chế Trigger: mặc định OFF (zero-overhead); chỉ tổng kết mục 14 state.md (single-shot) khi có cờ `--profile` / `[profile]`, và chỉ khởi tạo `results.tsv` khi có cờ `--bench` / `[benchmark]`.</constraint>
     <output>Mã nguồn + kiểm thử + cập nhật `state.md` kèm bằng chứng kiểm chứng. Khi hoàn tất toàn bộ lát cắt, tự động chuyển ngay sang REVIEW.</output>
   </phase>
 

package/templates/vi/instruction-version.json

@@ -1,13 +1,13 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "name": "@damphuquy/agent-init",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "framework": "RIPER-5",
-  "frameworkVersion": "3.2.0",
+  "frameworkVersion": "3.3.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-13T00:00:00.000Z",
+  "updatedAt": "2026-09-14T00:00:00.000Z",
   "manifest": {
     "core": [
       "AGENTS.md",

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

@@ -98,6 +98,7 @@
 
   <seed type="results" path="results-template.tsv.seed">
     Bảng đăng ký đánh giá số liệu benchmark và định lượng.
+    Kích hoạt theo trigger (--bench, [benchmark], hoặc <observability_mode>BENCHMARK</observability_mode>).
     Dùng để theo dõi latency, throughput, bộ nhớ hoặc điểm đánh giá qua các vòng lặp và lát cắt dọc.
   </seed>
 

package/templates/vi/process/_seeds/state-template.md.seed

@@ -140,7 +140,8 @@
 
 ## 14. Quan Sát Chi Phí & Tài Nguyên (Cost & Resource Observability)
 
-<cost_observability>
+<!-- Kích hoạt khi có trigger (--profile, [profile], hoặc <observability_mode>PROFILE|BENCHMARK</observability_mode>). Mặc định status="OFF" để tiết kiệm token; tổng kết đúng 1 lần trước khi sang REVIEW. -->
+<cost_observability status="OFF">
   <total_tool_calls>0</total_tool_calls>
   <estimated_tokens_consumed></estimated_tokens_consumed>
   <total_retries_used>0</total_retries_used>  <!-- tối đa 3 cho mỗi lỗi -->

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

@@ -10,6 +10,7 @@
   <status>ACTIVE</status>  <!-- ACTIVE | REVIEW | COMPLETED | CANCELLED -->
   <priority>P2</priority>  <!-- P0=khẩn | P1=cao | P2=bình thường | P3=thấp -->
   <working_mode>PAIR</working_mode>  <!-- PAIR (duyệt tại cổng) | DELEGATED (chạy tự trị liên tục) -->
+  <observability_mode>OFF</observability_mode>  <!-- OFF (mặc định: tinh gọn, không tốn token giám sát) | PROFILE (tổng kết chi phí khi review) | BENCHMARK (kèm results.tsv) -->
   <current_phase>PLAN</current_phase>  <!-- PLAN | EXECUTE | REVIEW -->
   <owner>@engineer</owner>
 </task_control>

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

@@ -12,6 +12,7 @@
   <risk>MEDIUM</risk>  <!-- LOW | MEDIUM | HIGH -->
   <estimated_story_points>2</estimated_story_points>  <!-- 1 SP ≈ 2-4 giờ làm việc kỹ thuật tập trung -->
   <working_mode>PAIR</working_mode>  <!-- PAIR (mặc định: dừng chờ duyệt từng gate) | DELEGATED (fast-track: tự động chạy liên tục qua các phase) | MANUAL | DIAGNOSE-ONLY -->
+  <observability_mode>OFF</observability_mode>  <!-- OFF (mặc định: tiết kiệm token) | PROFILE (đo chi phí cuối task) | BENCHMARK (kèm results.tsv) -->
   <current_phase>RESEARCH</current_phase>  <!-- RESEARCH | INNOVATE | PLAN | EXECUTE | REVIEW -->
   <owner>@engineer</owner>
   <decision_owner>@engineer</decision_owner>

package/templates/vi/process/development-protocols/observability-and-evals.md

@@ -9,7 +9,37 @@
 
 ---
 
-## 1. Quan Sát Chi Phí Token & Ngân Sách Thực Thi (Cost & Token Observability)
+## 1. Cơ Chế Kích Hoạt Có Điều Kiện (Trigger-Based Observability & Evals)
+
+<trigger_governance>
+  Để đảm bảo tối ưu chi phí token và không lãng phí lượt gọi công cụ (tool calls), hệ thống áp dụng cơ chế kích hoạt theo trigger:
+
+  ### 1. Trạng Thái Mặc Định — Tinh Gọn (Default LEAN Mode):
+  - **Mặc định là OFF (Zero-Overhead):** Đối với hầu hết các task phát triển thông thường (CRUD, sửa lỗi nhỏ, thêm UI, chỉnh sửa tài liệu), Agent KHÔNG cần đo đạc chi phí token, không tự đếm tool calls giữa chừng và không tạo bảng benchmark. Khối `<cost_observability>` trong `state.md` được giữ nguyên giá trị mặc định.
+
+  ### 2. Các Trigger Kích Hoạt Tường Minh (Explicit Triggers):
+  Agent chỉ kích hoạt theo dõi khi phát hiện một trong các trigger sau:
+  - **Cờ Prompt:**
+    - `--profile` hoặc `[profile]`: Kích hoạt theo dõi chi phí và hiệu suất thực thi task.
+    - `--bench` hoặc `[benchmark]`: Kích hoạt vòng đời Benchmark định lượng và tạo bảng `results.tsv`.
+    - `--eval` hoặc `[eval]`: Kích hoạt bộ kiểm thử đánh giá bảo mật / ranh giới tin cậy (`process/evals/`).
+  - **Thẻ Điều Khiển Trong Task Spec (`task.md` / `task-lite.md`):**
+    - `<observability_mode>PROFILE</observability_mode>`: Kích hoạt theo dõi chi phí.
+    - `<observability_mode>BENCHMARK</observability_mode>`: Kích hoạt đo lường hiệu năng kép (A/B baseline vs candidate).
+
+  ### 3. Quy Tắc Tổng Kết Cuối Task (Single-Shot Finalization):
+  - Khi có trigger `--profile`, Agent **TUYỆT ĐỐI KHÔNG** cập nhật liên tục sau mỗi lát cắt nhỏ làm phình to context window.
+  - Agent chỉ thực hiện tổng kết số liệu (đếm tool calls, số retry, thời gian hoàn thành) và ghi vào mục 14 `<cost_observability>` trong `state.md` **đúng 1 lần duy nhất khi kết thúc phase EXECUTE**, ngay trước khi tạo `review.md`.
+
+  ### 4. Trigger Tự Động Theo Ngưỡng Rủi Ro (Adaptive Fallback Trigger):
+  Agent tự động kích hoạt ghi nhận chi phí và bộ nhớ lỗi `<failure_memory>` mà không cần cờ báo trước nếu:
+  - Một lát cắt thất bại kiểm chứng từ lần thứ 2 trở lên (`retries >= 2`).
+  - Task vượt quá 30 tool calls mà chưa hoàn tất lát cắt.
+</trigger_governance>
+
+---
+
+## 2. Quan Sát Chi Phí Token & Ngân Sách Thực Thi (Cost & Token Observability)
 
 <token_cost_governance>
   Mọi phiên làm việc của Agent đều chịu sự chi phối của ngân sách token và tài nguyên tính toán.
@@ -28,7 +58,7 @@
 
 ---
 
-## 2. Chuẩn Hóa Git-Atomic Commits & Môi Trường Cách Ly (Sandboxing)
+## 3. Chuẩn Hóa Git-Atomic Commits & Môi Trường Cách Ly (Sandboxing)
 
 <atomic_commits_and_sandboxing>
   ### Quy Ước Commit Nguyên Tử (Git-Atomic Commit Convention):
@@ -52,7 +82,7 @@
 
 ---
 
-## 3. Khung Đánh Giá Benchmark & Đo Lường Định Lượng (Evals Framework)
+## 4. Khung Đánh Giá Benchmark & Đo Lường Định Lượng (Evals Framework)
 
 <evals_framework>
   Đối với các task tối ưu hóa hiệu năng, refactor kiến trúc hoặc nâng cấp thuật toán:
@@ -65,7 +95,7 @@
 
 ---
 
-## 4. Evals Governance Xác Định & Vệ Sinh Bằng Chứng
+## 5. Evals Governance Xác Định & Vệ Sinh Bằng Chứng
 
 <governance_evals>
   Dùng `process/evals/eval-case.json` làm fixture offline, có tính xác định. Mỗi case ghi input như dữ liệu, policy verdict, side effect và evidence reference kỳ vọng; nó không bao giờ được khiến lệnh hay MCP call thực thi.