@damphuquy/agent-init 1.4.1 → 1.4.3

package/package.json

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

package/templates/en/process/README.md

@@ -147,4 +147,27 @@ handoff.md       ← (Complete) Short final projection
   </phase>
 </operational_phases>
 
+---
+
+## 4. Template Architecture Philosophy: Understanding Why & How
+
+To prevent mechanical, cargo-cult usage of the framework, the template architecture is engineered around the following core technical principles:
+
+### 1. The Architectural "WHY" — Core Rationale
+* **Why the `.seed` extension in `_seeds/`?**
+  * Blueprint Immutability: The `.seed` suffix isolates master templates from standard AI discovery tools (`grep`, `find`), preventing agents from mistaking blueprints for active tasks and overwriting master templates.
+* **Why separate phase-specific artifacts instead of one large Markdown file?**
+  * Enforces Single Responsibility. Prevents oversized context windows (Anti-Context Saturation) that trigger hallucinations or rule neglect (Lost in the Middle). Ensures every Quality Gate (G1, G2, G3) maps to an auditable, physical file on disk.
+* **Why split `features/` vs `general-plans/`?**
+  * Blast Radius Separation: `features/` handles large, multi-phase epics (≥5 files or domain subsystems), whereas `general-plans/` houses rapid bugfixes and optimizations (<5 files). This keeps your workspace organized and prevents minor fixes from burying major architecture.
+* **Why use the 3-state pipeline (`active/`, `backlog/`, `completed/`)?**
+  * Filesystem State Machine: `active/` contains strictly one in-flight task at any time, maintaining zero context bleeding. `completed/` serves as a permanent historical archive for future tasks to reference via `<context_references>`.
+* **Why pseudo-XML tags (`<goal>`, `<allowed_files>`,...)?**
+  * Machine-Readable Contract: Enforces unambiguous semantic boundaries that LLMs parse reliably, strictly constraining AI write access.
+
+### 2. The Operational "HOW" — Execution Principles
+* **Copy-On-Demand:** Never bulk-copy all seeds into a task folder upfront. Start with `task.md`, then instantiate `research.md` $\rightarrow$ `decision.md` $\rightarrow$ `plan.md` $\rightarrow$ `state.md` $\rightarrow$ `review.md` $\rightarrow$ `handoff.md` sequentially as phases advance.
+* **Stateless Chat, Stateful Workspace:** Sessions can reset and chats can close. All operational progress and error memory (`<failure_memory>`) are recorded on disk (`state.md`), allowing any new session to resume with 100% fidelity.
+* **Selective Knowledge Crystallization:** Upon completion, summarize the task in `handoff.md`. Only promote reusable architectural standards or schema contracts into `process/context/` and `all-context.md`.
+
 </process_orchestration>

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

@@ -8,6 +8,13 @@
   Never edit seeds in-place — always copy first.
 </scope>
 
+<architectural_rationale>
+  ### Seeds Architectural Rationale: Understanding "Why" & "How"
+  * **Why the `.seed` extension? (Why):** The `.seed` suffix acts as an immutable boundary. It prevents automated AI discovery tools (`find`, `grep`) from confusing archetype templates with active `*.md` task files. This guarantees agents will never accidentally overwrite master blueprints during execution.
+  * **Why separate seeds per phase? (Why):** Each phase of RIPER-5 requires a distinct cognitive posture and permission boundary (Research vs Innovate vs Plan vs Execute vs Review). Splitting archetypes prevents context window bloat (Anti-Context Saturation), avoids hallucinations, and anchors each Quality Gate (G1–G3) to an auditable physical artifact.
+  * **Copy-On-Demand Protocol (How):** Never bulk-copy all seeds into a task directory. Start exclusively with `task.md`. Sequentially instantiate subsequent artifacts (`research.md` $\rightarrow$ `decision.md` $\rightarrow$ `plan.md` $\rightarrow$ `state.md` $\rightarrow$ `review.md` $\rightarrow$ `handoff.md`) only as the task progresses into each phase.
+</architectural_rationale>
+
 ---
 
 ## 1. Blueprint Catalog

package/templates/vi/process/README.md

@@ -147,4 +147,27 @@ handoff.md       ← (Complete) Tóm tắt bàn giao ngắn gọn
   </phase>
 </operational_phases>
 
+---
+
+## 4. Triết Lý Kiến Trúc Templates: Vì Sao Tổ Chức Như Vậy? (Why & How)
+
+Để tránh tình trạng chỉ sử dụng máy móc mà không hiểu nguyên lý, kiến trúc của hệ thống templates được xây dựng dựa trên các trụ cột kỹ thuật sau:
+
+### 1. Bản chất "WHY" — Lý Do Thiết Kế
+* **Tại sao có hậu tố `.seed` trong `_seeds/`?**
+  * Hậu tố `.seed` phân định ranh giới bất biến (Blueprint Immutability). Ngăn chặn các công cụ tìm kiếm của AI (như `grep`, `find`) nhận diện nhầm file mẫu thành file task đang chạy, bảo vệ phôi mẫu không bị AI vô tình ghi đè.
+* **Tại sao chia nhỏ theo từng Phase thay vì 1 file Markdown lớn?**
+  * Áp dụng nguyên lý Single Responsibility. Tránh hiện tượng phình to context window (Anti-Context Saturation) khiến AI bị ảo giác hoặc "quên" quy tắc (Lost in the middle). Đảm bảo mỗi Quality Gate (G1, G2, G3) được gắn với một bằng chứng vật lý độc lập.
+* **Tại sao phân chia `features/` vs `general-plans/`?**
+  * Phân tách theo bán kính ảnh hưởng (Blast Radius). `features/` dành cho task lớn (≥5 files hoặc theo domain), `general-plans/` dành cho tác vụ nhanh, sửa bug (<5 files). Ngăn chặn tình trạng hàng chục task vụn vặt làm loãng cấu trúc hệ thống.
+* **Tại sao có 3 trạng thái `active/`, `backlog/`, `completed/`?**
+  * Mô hình State Machine trên filesystem: `active/` tại một thời điểm chỉ chứa DUY NHẤT một task đang làm, giữ không gian làm việc của AI sạch sẽ tuyệt đối. `completed/` lưu trữ tri thức lịch sử để các task sau kế thừa qua `<context_references>`.
+* **Tại sao dùng thẻ XML (`<goal>`, `<allowed_files>`,...)?**
+  * Ranh giới cú pháp máy đọc được (Machine-Readable Contract), khóa chặt phạm vi sửa đổi của AI.
+
+### 2. Bản chất "HOW" — Nguyên Tắc Vận Hành
+* **Copy-On-Demand:** Tuyệt đối không copy hàng loạt tất cả seed vào task cùng lúc. Bắt đầu với `task.md`, sau đó sinh ra `research.md` $\rightarrow$ `decision.md` $\rightarrow$ `plan.md` $\rightarrow$ `state.md` $\rightarrow$ `review.md` $\rightarrow$ `handoff.md` theo tiến độ phase.
+* **Stateless Chat, Stateful Workspace:** Cửa sổ chat có thể tắt hoặc reset session. Toàn bộ tiến độ và bộ nhớ lỗi (`<failure_memory>`) được lưu bền vững trên ổ đĩa (`state.md`), session mới chỉ cần nạp lại file là tiếp tục công việc chính xác 100%.
+* **Selective Knowledge Crystallization:** Sau khi task hoàn thành và tạo `handoff.md`, chỉ những thay đổi kiến trúc/contract dùng chung mới được cập nhật vào `process/context/` và đăng ký trong `all-context.md`.
+
 </process_orchestration>

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

@@ -8,6 +8,13 @@
   Không bao giờ chỉnh sửa trực tiếp bên trong `_seeds/` — luôn luôn sao chép trước khi dùng.
 </scope>
 
+<architectural_rationale>
+  ### Triết Lý Thiết Kế Seeds: Bản Chất "Why" & "How"
+  * **Tại sao là đuôi `.seed`? (Why):** Đuôi `.seed` đóng vai trò ranh giới bất biến (Blueprint Immutability). Nó giúp phân biệt rõ ràng giữa "khuôn mẫu phôi" và "tài liệu markdown đang làm việc" (`*.md`). Khi AI quét repo bằng các công cụ tìm kiếm, hậu tố `.seed` bảo vệ các file này không bao giờ bị AI sửa đè vào làm hỏng template gốc của cả dự án.
+  * **Tại sao tách riêng từng seed theo phase? (Why):** Mỗi giai đoạn trong chu trình RIPER-5 đòi hỏi một kiểu tư duy và ranh giới quyền hạn khác biệt (Khảo sát vs Đề xuất vs Lập kế hoạch vs Thực thi vs Nghiệm thu). Việc tách rời giúp AI chỉ nạp đúng artifact cần thiết, chống phình to context window (Anti-Context Saturation) và gắn chặt với từng Cổng kiểm soát (Gates G1–G3).
+  * **Quy tắc Copy-On-Demand (How):** Tuyệt đối không copy hàng loạt tất cả seed vào thư mục task. Bắt đầu duy nhất với `task.md`. Khi task tiến vào phase nào, mới lần lượt khởi tạo artifact của phase đó (`research.md` $\rightarrow$ `decision.md` $\rightarrow$ `plan.md` $\rightarrow$ `state.md` $\rightarrow$ `review.md` $\rightarrow$ `handoff.md`).
+</architectural_rationale>
+
 ---
 
 ## 1. Danh Mục Blueprints Mẫu