@damphuquy/agent-init 1.0.2 → 1.0.3

package/README.md

@@ -1,134 +1,66 @@
-# @damphuquy/agent-init
+# agent-instructions
 
-Bộ công cụ khởi tạo khung System Prompt / Agent Manual (`AGENTS.md`) và Operational Workspace (`process/`) theo chuẩn **RIPER-5 Framework** cho mọi repository hoặc subsystem.
-
-CLI sở hữu giao diện trực quan với phong cách **Tokyo Night Theme**, hỗ trợ hiển thị trạng thái chi tiết, thống kê quá trình cài đặt và hướng dẫn các bước tiếp theo.
-
----
-
-## 1. Khởi tạo nhanh với NPX (Khuyên dùng)
-
-Không cần cài đặt toàn cục hay clone repository, bạn có thể khởi tạo trực tiếp bất kỳ lúc nào:
+Template hệ thống điều phối AI Coding Agent theo chuẩn **RIPER-5 Framework** — bao gồm ba layer rõ ràng: `AGENTS.md` (entry point), `.agents/` (agent control), và `process/` (engineering workflow).
 
 ```bash
-# Khởi tạo tại thư mục hiện tại
-npx @damphuquy/agent-init .
-
-# Khởi tạo vào thư mục / subsystem chỉ định
+# Bootstrap ngay vào project của bạn
 npx @damphuquy/agent-init ./my-project
-npx @damphuquy/agent-init ./services/billing
 ```
 
 ---
 
-## 2. Khởi tạo cục bộ (Local Execution)
+## Kiến trúc 3-layer
 
-Khi làm việc trực tiếp trong repository mã nguồn:
+```
+AGENTS.md          ← Entry point: project config + RIPER-5 phase definitions
+.agents/           ← Agent control layer: behavior, guardrails, conventions
+process/           ← Engineering workflow: task artifacts, seeds, context
+```
 
-```bash
-# Build mã nguồn TypeScript
-npm run build
+Mỗi layer có trách nhiệm độc lập và không duplicate nhau.
+Chi tiết → [`docs/01-overview.md`](docs/01-overview.md)
 
-# Chạy trực tiếp qua CLI
-npm start -- [target_directory] [options]
+---
 
-# Hoặc qua npx/node
-node dist/cli.js [target_directory] [options]
-node bin/bootstrap.js [target_directory] [options]
-```
+## Tài liệu hướng dẫn
 
----
+| Tài liệu | Nội dung |
+|---|---|
+| [01 · Overview & Architecture](docs/01-overview.md) | Mental model, 3-layer design, quick-start |
+| [02 · Layer: `.agents/`](docs/02-layer-agents.md) | File-by-file: behavior, guardrails, conventions |
+| [03 · Layer: `process/`](docs/03-layer-process.md) | File-by-file: seeds, context, protocols, artifact chain |
+| [04 · Layer: `AGENTS.md`](docs/04-layer-agentsmd.md) | Entry point anatomy, customization |
+| [05 · Workflow: Tạo task mới](docs/05-workflow-new-task.md) | Tutorial từng bước RIPER-5 |
+| [06 · Human vs Agent](docs/06-human-vs-agent.md) | Phân rõ ai làm gì ở từng bước |
+| [07 · Deployment](docs/07-deployment.md) | Bootstrap, cài đặt, cấu hình lần đầu |
 
-## 3. Tùy chọn tham số (Options)
+---
 
-- `-f, --force`: Ghi đè các file đã tồn tại trước đó.
-- `-h, --help`: Hiển thị bảng trợ giúp và các ví dụ sử dụng.
-- `-v, --version`: Hiển thị phiên bản hiện tại.
+## Quick-start (5 phút)
 
-Ví dụ:
 ```bash
-npx @damphuquy/agent-init ./my-project --force
-```
-
----
+# 1. Bootstrap template vào project
+npx @damphuquy/agent-init ./my-project
 
-## 4. Cấu trúc mã nguồn Scaffolder (TypeScript)
-
-```text
-.
-├── src/                           # Mã nguồn TypeScript (đầy đủ Type definitions)
-│   ├── types.ts                   # Interfaces, Types cho Palette, Theme, FileGroups, Options, Stats
-│   ├── theme.ts                   # Tokyo Night Color Engine & ANSI formatters
-│   ├── config.ts                  # File classification catalog & package info
-│   ├── ui.ts                      # Box renderer, Banner & Help documentation UI
-│   ├── scaffolder.ts              # Core Scaffolding Engine
-│   ├── cli.ts                     # CLI argument parser & runner entrypoint
-│   └── index.ts                   # Public library exports
-├── templates/                     # Toàn bộ template gốc (chỉnh sửa trực tiếp tại đây)
-│   ├── AGENTS.md                  # Master Agent Manual (4 Pillars & RIPER-5 Loop)
-│   ├── .agents/name_rule.md       # Quy tắc đặt tên và interface
-│   └── process/
-│       ├── README.md              # Trung tâm điều hành task process
-│       ├── _seeds/                # Các seed templates (task, program, context)
-│       │   ├── _GUIDE.md
-│       │   ├── task-template.md.seed
-│       │   ├── program-template.md.seed
-│       │   └── context-group.md.seed
-│       ├── context/               # Context routers & Planning standards
-│       ├── development-protocols/ # Giao thức lập trình & điều phối
-│       ├── features/              # Thư mục active/backlog/completed cho features
-│       └── general-plans/         # Thư mục active/backlog/completed cho general plans
-├── dist/                          # Compiled JavaScript & Type Declaration files (.d.ts)
-├── bin/
-│   └── bootstrap.js               # CLI runner forwarder
-├── tsconfig.json                  # TypeScript Compiler Configuration (Strict mode)
-└── package.json
-```
+# 2. Mở AGENTS.md, cấu hình toolchain (2 phút)
+#    Tìm dòng <validation_commands> và điền lệnh test/lint của project
 
----
+# 3. Tạo task đầu tiên
+cp my-project/process/_seeds/task-template.md.seed \
+   my-project/process/general-plans/active/CHG-001-init/task.md
 
-## 5. Cấu trúc thư mục được sinh ra trên dự án đích
-
-```text
-<target_dir>/
-├── AGENTS.md                      # Master Agent Guidelines (4 Pillars + RIPER-5 Framework)
-├── .agents/
-│   └── name_rule.md               # Quy tắc đặt tên và interface
-└── process/
-    ├── README.md                  # Trung tâm điều hành task process
-    ├── _seeds/                    # Blueprints / Templates gốc (Read-only)
-    │   ├── _GUIDE.md              # Hướng dẫn sử dụng seeds
-    │   ├── task-template.md.seed  # Template cho task đơn lẻ (SPEC, PLAN, AC)
-    │   ├── program-template.md.seed # Blueprint cho chương trình đa pha
-    │   └── context-group.md.seed  # Seed cho router ngữ cảnh domain
-    ├── context/
-    │   ├── all-context.md         # Root context router
-    │   └── planning/all-planning.md # Tiêu chuẩn INVEST, capacity planning
-    ├── development-protocols/
-    │   ├── all-development-protocols.md # Protocols index
-    │   ├── orchestration.md       # Quy tắc subagent delegation
-    │   └── implementation-standards.md # Chuẩn typing, domain purity, testing
-    ├── features/                  # Quản lý task theo feature/domain
-    │   ├── active/                # Task đang thực thi ({task_slug}_{date}/)
-    │   ├── backlog/               # Task chờ xử lý ({note_slug}_NOTE_{date}.md)
-    │   └── completed/             # Task đã hoàn thành
-    └── general-plans/             # Quản lý task cross-cutting / độc lập
-        ├── active/
-        ├── backlog/
-        └── completed/
+# 4. Yêu cầu agent bắt đầu
+# "Đọc AGENTS.md và task.md, bắt đầu phase RESEARCH"
 ```
 
----
-
-## 6. Các bước sau khi khởi tạo
+Hướng dẫn chi tiết → [`docs/07-deployment.md`](docs/07-deployment.md)
 
-1. **Cập nhật lệnh kiểm thử trong `AGENTS.md`**:
-   Mở file `<target_dir>/AGENTS.md` và tùy chỉnh các lệnh kiểm thử tại phần `<validation_commands>` phù hợp với stack công nghệ của dự án (ví dụ: `npm test`, `pytest`, `cargo test`, `go test ./...`).
+---
 
-2. **Tạo task đầu tiên từ template**:
-   ```bash
-   cp process/_seeds/task-template.md.seed process/general-plans/active/01-init_PLAN.md
-   ```
+## NPX Options
 
-3. **Kích hoạt AI Coding Agent**:
-   Yêu cầu Agent đọc file `AGENTS.md` để nắm quy trình và bắt đầu thực hiện kế hoạch trong `process/general-plans/active/01-init_PLAN.md`.
+```bash
+npx @damphuquy/agent-init .                    # Bootstrap tại thư mục hiện tại
+npx @damphuquy/agent-init ./services/billing   # Bootstrap vào subsystem cụ thể
+npx @damphuquy/agent-init ./my-project --force # Ghi đè file đã tồn tại
+```

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEpD,eAAO,MAAM,WAAW,EAAE,SAAS,SAAS,EA4C3C,CAAC;AAEF,wBAAgB,cAAc,IAAI,MAAM,CASvC;AAED,wBAAgB,cAAc,CAAC,cAAc,GAAE,MAAyB,GAAG,WAAW,CAgBrF"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEpD,eAAO,MAAM,WAAW,EAAE,SAAS,SAAS,EAyD3C,CAAC;AAEF,wBAAgB,cAAc,IAAI,MAAM,CASvC;AAED,wBAAgB,cAAc,CAAC,cAAc,GAAE,MAAyB,GAAG,WAAW,CAgBrF"}

package/dist/config.js

@@ -4,10 +4,18 @@ import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 export const FILE_GROUPS = [
     {
-        title: 'Core Agent Manual & Interface Directives',
+        title: 'Core Agent Manual & Entry Point',
         files: [
             { path: 'AGENTS.md', desc: 'Master Agent Manual (4 Pillars & RIPER-5 Loop)' },
-            { path: '.agents/name_rule.md', desc: 'Agent naming conventions & interface contracts' },
+        ],
+    },
+    {
+        title: 'Agent Control Layer (.agents/)',
+        files: [
+            { path: '.agents/README.md', desc: 'Agent control layer index & boundary declaration' },
+            { path: '.agents/behavior.md', desc: 'Mode declaration, session startup, context navigation' },
+            { path: '.agents/guardrails.md', desc: 'Retry budget, escalation triggers, completion gate' },
+            { path: '.agents/conventions/naming.md', desc: 'Universal naming rules & structural hygiene' },
         ],
     },
     {
@@ -15,9 +23,14 @@ export const FILE_GROUPS = [
         files: [
             { path: 'process/README.md', desc: 'Operational Workspace Control Center' },
             { path: 'process/_seeds/_GUIDE.md', desc: 'Seed archetypes usage & lifecycle guide' },
-            { path: 'process/_seeds/task-template.md.seed', desc: 'Task Spec & Plan blueprint (INVEST & AC)' },
+            { path: 'process/_seeds/task-template.md.seed', desc: 'Task master contract & RIPER-5 execution plan' },
+            { path: 'process/_seeds/context-group.md.seed', desc: 'Research phase artifact blueprint' },
+            { path: 'process/_seeds/decision-template.md.seed', desc: 'Innovate phase artifact & Gate 1 memory' },
+            { path: 'process/_seeds/plan-template.md.seed', desc: 'Plan phase artifact & execution contract (Gate 2)' },
+            { path: 'process/_seeds/state-template.md.seed', desc: 'Execute loop persistent memory' },
+            { path: 'process/_seeds/review-template.md.seed', desc: 'Review phase artifact & Gate 3' },
+            { path: 'process/_seeds/handoff-template.md.seed', desc: 'Final projection (intentionally short)' },
             { path: 'process/_seeds/program-template.md.seed', desc: 'Multi-phase umbrella epic blueprint' },
-            { path: 'process/_seeds/context-group.md.seed', desc: 'Domain knowledge & context router blueprint' },
         ],
     },
     {

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/package.json

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

package/templates/.agents/README.md

@@ -0,0 +1,29 @@
+# Agent Control Layer (`.agents/`)
+
+<agent_control_layer version="1.0">
+
+<purpose>
+  Universal, project-agnostic agent control rules. These files define HOW the
+  agent thinks and behaves — not what it builds or how tasks are tracked.
+
+  Copy this directory verbatim into any repository. No project-specific edits required.
+</purpose>
+
+<boundary>
+  `.agents/` owns: mode declaration, session startup protocol, retry budgets,
+  escalation triggers, completion gate, and code/naming conventions.
+
+  `.agents/` NEVER owns: task workflow (→ `process/`), artifact chain
+  (→ `process/_seeds/`), toolchain commands (→ `AGENTS.md`), or project context
+  (→ `process/context/`).
+</boundary>
+
+## File Catalog
+
+| File | Purpose |
+|------|---------|
+| [`behavior.md`](behavior.md) | Mode declaration, session startup, persistent state reload |
+| [`guardrails.md`](guardrails.md) | Retry budget, escalation triggers, stop conditions, completion gate |
+| [`conventions/naming.md`](conventions/naming.md) | Universal naming and code hygiene rules |
+
+</agent_control_layer>

package/templates/.agents/behavior.md

@@ -0,0 +1,72 @@
+# Agent Behavior Protocol
+
+<behavior_protocol version="1.0">
+
+<description>
+  Universal rules governing HOW the agent declares its operating mode,
+  reloads state at session start, and navigates context. Project-agnostic.
+</description>
+
+---
+
+## 1. Mode Declaration
+
+Every response that advances a task MUST open with a mode declaration on the
+first line. The declared mode must match the current phase recorded in `task.md`.
+
+```
+[MODE: RESEARCH]   — read-only, no source changes
+[MODE: INNOVATE]   — generating options, no source changes
+[MODE: PLAN]       — writing plan artifacts, no source changes
+[MODE: EXECUTE]    — making scoped source changes
+[MODE: REVIEW]     — reviewing, no code fixes
+```
+
+Omit the mode declaration only for pure conversational exchanges that do not
+advance a task (e.g., answering a factual question, clarifying scope).
+
+---
+
+## 2. Session Startup Protocol
+
+Before continuing any in-progress task, reload persistent state in this order:
+
+<startup_sequence>
+  1. Read `task.md` — confirm current phase and open gates.
+  2. Read `research.md` if Research phase is complete.
+  3. Read `decision.md` if Innovate phase is complete — confirm approved decisions.
+  4. Read `plan.md` — confirm current slice index and scope contract.
+  5. Read `state.md` — confirm completed slices, failure memory, retry budget, next action.
+  6. Re-read any source files that changed since last context load.
+</startup_sequence>
+
+**Do NOT rely on conversation memory alone.** Always verify against the
+file-based artifacts listed above.
+
+---
+
+## 3. Context Navigation Rules
+
+<context_rules>
+  <rule id="minimum_context">
+    Gather minimum sufficient context only. Never scan the full repository or
+    perform drive-by refactoring outside the active task scope.
+  </rule>
+
+  <rule id="information_priority">
+    Load context in this priority order:
+    1. Task spec and acceptance criteria (`task.md`)
+    2. Research and decision artifacts (`research.md`, `decision.md`)
+    3. Relevant test suites
+    4. Domain models and port interfaces
+    5. Configuration and dependency injection setup
+    6. Concrete infrastructure implementations
+  </rule>
+
+  <rule id="no_stale_context">
+    Re-read relevant files after any repository change. Never act on stale
+    in-memory snapshots.
+  </rule>
+</context_rules>
+
+</behavior_protocol>

package/templates/.agents/conventions/naming.md

@@ -0,0 +1,55 @@
+# Naming & Code Conventions
+
+<naming_conventions version="1.0">
+
+<description>
+  Universal code hygiene rules that apply across languages and projects.
+  Project-specific linting/formatting rules live in `AGENTS.md` and
+  `process/development-protocols/implementation-standards.md`.
+</description>
+
+---
+
+## 1. Naming Rules
+
+<naming_rules>
+  <rule id="no_leading_underscore">
+    Never use a leading underscore `_` for function or method names to imply
+    "private". Write flat, clean, public functions with self-explanatory names.
+    Exception: language-mandated dunder/magic methods (e.g., Python `__init__`).
+  </rule>
+
+  <rule id="self_explanatory">
+    Names must reveal intent without requiring a comment to explain them.
+    Prefer `calculate_retry_delay()` over `calc()` or `do_thing()`.
+  </rule>
+
+  <rule id="no_abbreviations">
+    Avoid opaque abbreviations. Write `connection_timeout` not `conn_to`,
+    `maximum_retry_count` not `max_rtry_cnt`.
+    Exception: universally understood acronyms (e.g., `url`, `id`, `api`).
+  </rule>
+</naming_rules>
+
+---
+
+## 2. Structural Hygiene
+
+<structural_rules>
+  <rule id="single_responsibility">
+    Each function or class has one clearly stated responsibility.
+    Split when a unit does more than one thing.
+  </rule>
+
+  <rule id="no_magic_values">
+    Extract all numeric/string literals into named constants or configuration.
+  </rule>
+
+  <rule id="no_suppression">
+    Never silence linter or type checker errors with inline suppression comments
+    (`# type: ignore`, `# noqa`, `eslint-disable`, `@SuppressWarnings`, etc.)
+    unless the suppression itself is explicitly reviewed and annotated with a reason.
+  </rule>
+</structural_rules>
+
+</naming_conventions>

package/templates/.agents/guardrails.md

@@ -0,0 +1,76 @@
+# Agent Guardrails
+
+<agent_guardrails version="1.0">
+
+<description>
+  Universal safety boundaries for agent execution: retry budget, escalation
+  triggers, stop conditions, and completion gate. Project-agnostic — applies
+  regardless of language, framework, or toolchain.
+</description>
+
+---
+
+## 1. Retry Budget
+
+<retry_budget max_attempts="3">
+  Maximum 3 consecutive attempts per distinct failure symptom.
+
+  Rules:
+  - Never suppress errors with flags (e.g. `# type: ignore`, `eslint-disable`,
+    `@SuppressWarnings`) to artificially pass a gate.
+  - Record every failure in `state.md > <failure_memory>` with:
+    - failure signature (unique symptom description)
+    - hypothesis tested
+    - experiment run
+    - result observed
+  - If retry budget is exhausted: HALT, log into `<open_decisions>` in `task.md`,
+    and request human guidance.
+</retry_budget>
+
+---
+
+## 2. Escalation & Stop Conditions
+
+<escalation_triggers>
+  Halt immediately and request human guidance if ANY of the following occur:
+
+  1. Retry budget exhausted on a recurring failure.
+  2. Required change touches a public API, database schema, or security policy
+     not declared in the approved plan.
+  3. Required change touches a file outside the scope defined in `plan.md`.
+  4. A business or policy decision is needed that is not in `<approved_decisions>`.
+  5. Scope expansion is needed beyond `<out_of_scope>` in `task.md`.
+
+  Exception: Do NOT halt if the change was explicitly authorized by the user
+  in the prompt/spec, or if it is a mandatory accompanying test or import update.
+</escalation_triggers>
+
+---
+
+## 3. Completion Gate
+
+<completion_gate>
+  A task is COMPLETE only when ALL of the following are true simultaneously:
+
+  1. All Acceptance Criteria in `task.md` are verified (`- [x]`) with
+     evidence recorded in `review.md`.
+  2. All validation commands (as defined in `AGENTS.md`) execute with
+     zero errors and zero warnings.
+  3. Gate 3 in `review.md` is checked and review decision is PASS.
+  4. The final `git diff` contains zero extraneous or unreviewed modifications.
+  5. Task folder is moved to `completed/` and `handoff.md` is produced.
+</completion_gate>
+
+---
+
+## 4. Invariant Preservation
+
+<invariants>
+  - Never overwrite or delete human-authored spec content in `task.md`.
+  - Only toggle `- [x]` after the corresponding verifier actually passes —
+    never preemptively.
+  - Keep edits within the declared subsystem unless explicit cross-system
+    coordination is requested and approved.
+</invariants>
+
+</agent_guardrails>