@damphuquy/agent-init 1.2.1 → 1.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +41 -102
  2. package/README.vi.md +121 -0
  3. package/package.json +1 -1
  4. package/templates/process/README.md +26 -1
package/README.md CHANGED
@@ -1,17 +1,13 @@
1
1
  # agent-instructions (@damphuquy/agent-init)
2
2
 
3
- > **AI Coding Agent Scaffolding & Orchestration System (RIPER-5 Framework)**
4
- > *Hệ thống điều phối và khởi tạo AI Coding Agent theo chuẩn RIPER-5*
3
+ > **AI Coding Agent Scaffolding & Orchestration System (RIPER-5 Framework)**
5
4
 
6
5
  <p align="center">
7
- <a href="#english">English</a> • <a href="#tiếng-việt">Tiếng Việt</a>
6
+ <b>English</b> • <a href="README.vi.md">Tiếng Việt</a>
8
7
  </p>
9
8
 
10
9
  ---
11
10
 
12
- <a id="english"></a>
13
- ## English
14
-
15
11
  A structured scaffolding framework for AI Coding Agents following the **RIPER-5 Framework** — cleanly separated into three independent layers: `AGENTS.md` (entry point), `.agents/` (agent control), and `process/` (engineering workflow).
16
12
 
17
13
  ```bash
@@ -19,6 +15,8 @@ A structured scaffolding framework for AI Coding Agents following the **RIPER-5
19
15
  npx @damphuquy/agent-init ./my-project
20
16
  ```
21
17
 
18
+ ---
19
+
22
20
  ### 3-Layer Architecture
23
21
 
24
22
  ```
@@ -28,24 +26,52 @@ process/ ← Engineering workflow: task artifacts, seed blueprints, co
28
26
  ```
29
27
 
30
28
  Each layer has single-responsibility ownership with **Zero Duplication**.
31
- Full architectural details → [`docs/01-overview.md`](docs/01-overview.md)
29
+ Full architectural details → [`docs/en/01-overview.md`](docs/en/01-overview.md)
32
30
 
33
31
  > 💡 **Note on Context Router:** All long-term domain knowledge, database schemas, and architectural invariants stored in `process/context/` must be registered in [`process/context/all-context.md`](templates/process/context/all-context.md). Agents rely on this router to selectively load context, preventing token waste and unconstrained repository scans.
34
32
 
35
33
  ---
36
34
 
35
+ ### RIPER-5 End-to-End Workflow
36
+
37
+ ```
38
+ [Task Inception] ──► [0. Task Init: task.md] (Human defines spec & AC)
39
+ │
40
+ ▼
41
+ [1. RESEARCH] (Agent reads context ──► research.md ──► Gate G0)
42
+ │
43
+ ▼
44
+ [2. INNOVATE] (Agent creates 2-3 options in decision.md ──► Gate G1: Human Approval)
45
+ │
46
+ ▼
47
+ [3. PLAN] (Agent creates vertical slices in plan.md ──► Gate G2: Human Sign-off)
48
+ │
49
+ ▼
50
+ [4. EXECUTE] (Agent implements slice-by-slice ──► tests pass ──► state.md)
51
+ │
52
+ ▼
53
+ [5. REVIEW] (Agent audits behavior/security in review.md ──► Gate G3: Human Approval)
54
+ │
55
+ ▼
56
+ [COMPLETE] (Archive to completed/ ──► handoff.md)
57
+ ```
58
+ *(Interactive Mermaid diagram available in [`docs/en/01-overview.md`](docs/en/01-overview.md#riper-5-end-to-end-workflow-diagram))*.
59
+
60
+ ---
61
+
37
62
  ### Documentation
38
63
 
39
64
  | Document | Description |
40
65
  |---|---|
41
- | [01 · Overview & Architecture](docs/01-overview.md) | Mental model, 3-layer design, info flow |
42
- | [02 · Layer: `.agents/`](docs/02-layer-agents.md) | File-by-file: behavior, guardrails, conventions |
43
- | [03 · Layer: `process/`](docs/03-layer-process.md) | File-by-file: seeds, context router, artifact chain |
44
- | [04 · Layer: `AGENTS.md`](docs/04-layer-agentsmd.md) | Entry point anatomy & project customization |
45
- | [05 · Workflow: New Task](docs/05-workflow-new-task.md) | Step-by-step tutorial: idea → completed task |
46
- | [06 · Human vs Agent](docs/06-human-vs-agent.md) | Responsibility matrix & escalation triggers |
47
- | [07 · Deployment](docs/07-deployment.md) | Bootstrap options, monorepo setup, troubleshooting |
48
- | [Note · DevOps CI/CD & Release](docs/note/devops-release-automation.md) | Automated SemVer, 2FA npm tokens, Git tag sync |
66
+ | [01 · Overview & Architecture](docs/en/01-overview.md) | Mental model, 3-layer design, info flow, workflow diagram |
67
+ | [02 · Layer: `.agents/`](docs/en/02-layer-agents.md) | File-by-file: behavior, guardrails, conventions |
68
+ | [03 · Layer: `process/`](docs/en/03-layer-process.md) | File-by-file: seeds, context router, artifact chain |
69
+ | [04 · Layer: `AGENTS.md`](docs/en/04-layer-agentsmd.md) | Entry point anatomy & project customization |
70
+ | [05 · Workflow: New Task](docs/en/05-workflow-new-task.md) | Step-by-step tutorial: idea → completed task |
71
+ | [06 · Human vs Agent](docs/en/06-human-vs-agent.md) | Responsibility matrix & Quality Gates (G0–G3) deep dive |
72
+ | [07 · Deployment](docs/en/07-deployment.md) | Bootstrap options, monorepo setup, troubleshooting |
73
+ | [08 · Developer Playbook](docs/en/08-developer-workflow-playbook.md) | Practical scenarios, day-to-day operations, prompt cheat sheet |
74
+ | [Note · DevOps CI/CD & Release](docs/en/note/devops-release-automation.md) | Automated SemVer, 2FA npm tokens, Git tag sync |
49
75
 
50
76
  ---
51
77
 
@@ -93,90 +119,3 @@ This repository includes a continuous integration and release pipeline configure
93
119
  ```bash
94
120
  git pull --tags origin main
95
121
  ```
96
-
97
- ---
98
-
99
- <a id="tiếng-việt"></a>
100
- ## Tiếng Việt
101
-
102
- Hệ thống mẫu (scaffold) điều phối AI Coding Agent theo chuẩn **RIPER-5 Framework** — phân tách thành ba layer rõ ràng: `AGENTS.md` (entry point), `.agents/` (agent control), và `process/` (engineering workflow).
103
-
104
- ```bash
105
- # Khởi tạo ngay vào project của bạn
106
- npx @damphuquy/agent-init ./my-project
107
- ```
108
-
109
- ### Kiến trúc 3-layer
110
-
111
- ```
112
- AGENTS.md ← Entry point: cấu hình project + định nghĩa các phase RIPER-5
113
- .agents/ ← Agent control layer: hành vi, guardrails, quy chuẩn code
114
- process/ ← Engineering workflow: task artifacts, seed blueprints, context
115
- ```
116
-
117
- Mỗi layer chịu trách nhiệm độc lập theo nguyên tắc **Zero Duplication**.
118
- Chi tiết kiến trúc → [`docs/01-overview.md`](docs/01-overview.md)
119
-
120
- > 💡 **Lưu ý về Context Router:** Mọi tri thức domain lâu dài, database schema và quy tắc kiến trúc lưu trong `process/context/` đều cần được đăng ký định tuyến trong [`process/context/all-context.md`](templates/process/context/all-context.md). Agent sẽ dựa vào router này để nạp đúng ngữ cảnh khi cần, tránh scan bừa bãi toàn bộ repository.
121
-
122
- ---
123
-
124
- ### Tài liệu hướng dẫn
125
-
126
- | Tài liệu | Nội dung |
127
- |---|---|
128
- | [01 · Overview & Architecture](docs/01-overview.md) | Mental model, thiết kế 3 layer, luồng thông tin |
129
- | [02 · Layer: `.agents/`](docs/02-layer-agents.md) | Chi tiết: behavior, guardrails, conventions |
130
- | [03 · Layer: `process/`](docs/03-layer-process.md) | Chi tiết: seeds, context router, chuỗi artifact |
131
- | [04 · Layer: `AGENTS.md`](docs/04-layer-agentsmd.md) | Cấu trúc entry point & cách tùy biến theo project |
132
- | [05 · Workflow: Tạo task mới](docs/05-workflow-new-task.md) | Hướng dẫn từng bước: từ ý tưởng đến hoàn thành |
133
- | [06 · Human vs Agent](docs/06-human-vs-agent.md) | Ma trận trách nhiệm & các điểm kích hoạt dừng (HALT) |
134
- | [07 · Deployment](docs/07-deployment.md) | Các cách bootstrap, cấu hình monorepo, xử lý sự cố |
135
- | [Note · DevOps CI/CD & Release](docs/note/devops-release-automation.md) | Cẩm nang DevOps, xử lý token 2FA npm, đồng bộ Git tag |
136
-
137
- ---
138
-
139
- ### Quick-start (5 phút)
140
-
141
- ```bash
142
- # 1. Bootstrap template vào project của bạn
143
- npx @damphuquy/agent-init ./my-project
144
-
145
- # 2. Mở AGENTS.md, cấu hình toolchain (2 phút)
146
- # Tìm thẻ <validation_commands> và điền lệnh test/lint của dự án
147
-
148
- # 3. Khởi tạo task đầu tiên
149
- cp my-project/process/_seeds/task-template.md.seed \
150
- my-project/process/general-plans/active/CHG-001-init/task.md
151
-
152
- # 4. Yêu cầu AI Agent bắt đầu
153
- # "Đọc AGENTS.md và task.md, bắt đầu phase RESEARCH."
154
- ```
155
-
156
- ---
157
-
158
- ### Tùy chọn lệnh NPX CLI
159
-
160
- ```bash
161
- npx @damphuquy/agent-init . # Khởi tạo tại thư mục hiện tại
162
- npx @damphuquy/agent-init ./services/billing # Khởi tạo vào subsystem trong monorepo
163
- npx @damphuquy/agent-init ./my-project --force # Ghi đè file nếu đã tồn tại
164
- ```
165
-
166
- ---
167
-
168
- ### Quy trình CI/CD & Tự động Publish lên NPM
169
-
170
- Repository được thiết lập pipeline tự động hóa tại [`.github/workflows/release.yml`](.github/workflows/release.yml):
171
-
172
- 1. **Tự động tính toán Semantic Versioning:** Khi push code lên nhánh `main`, hệ thống tự phát hiện version dựa trên commit message:
173
- - `BREAKING CHANGE:`, `!:`, `major:` $\rightarrow$ Tăng **Major** (`2.0.0`)
174
- - `feat:` $\rightarrow$ Tăng **Minor** (`1.1.0`)
175
- - `fix:`, `chore:`, `docs:`, ... $\rightarrow$ Tăng **Patch** (`1.0.4`)
176
- *(Nếu bạn chủ động sửa version trong `package.json`, CI sẽ tự nhận diện version đó)*.
177
- 2. **Tự động gắn Git Tag & Tạo GitHub Release:** Tự tạo tag `vX.Y.Z`, commit cập nhật `package.json` kèm `[skip ci]` và sinh release notes trên GitHub.
178
- 3. **Tự động Publish NPM:** Build và đẩy package lên npm registry bằng `NPM_TOKEN` (loại Classic **Automation** token).
179
- 4. **Đồng bộ về máy Local:** Để kéo commit và Git tag mới nhất về máy sau khi CI hoàn tất:
180
- ```bash
181
- git pull --tags origin main
182
- ```
package/README.vi.md ADDED
@@ -0,0 +1,121 @@
1
+ # agent-instructions (@damphuquy/agent-init)
2
+
3
+ > **Hệ thống điều phối và khởi tạo AI Coding Agent theo chuẩn RIPER-5**
4
+
5
+ <p align="center">
6
+ <a href="README.md">English</a> • <b>Tiếng Việt</b>
7
+ </p>
8
+
9
+ ---
10
+
11
+ Hệ thống mẫu (scaffold) điều phối AI Coding Agent theo chuẩn **RIPER-5 Framework** — phân tách thành ba layer rõ ràng: `AGENTS.md` (entry point), `.agents/` (agent control), và `process/` (engineering workflow).
12
+
13
+ ```bash
14
+ # Khởi tạo ngay vào project của bạn
15
+ npx @damphuquy/agent-init ./my-project
16
+ ```
17
+
18
+ ---
19
+
20
+ ### Kiến trúc 3-layer
21
+
22
+ ```
23
+ AGENTS.md ← Entry point: cấu hình project + định nghĩa các phase RIPER-5
24
+ .agents/ ← Agent control layer: hành vi, guardrails, quy chuẩn code
25
+ process/ ← Engineering workflow: task artifacts, seed blueprints, context
26
+ ```
27
+
28
+ Mỗi layer chịu trách nhiệm độc lập theo nguyên tắc **Zero Duplication**.
29
+ Chi tiết kiến trúc → [`docs/vi/01-overview.md`](docs/vi/01-overview.md)
30
+
31
+ > 💡 **Lưu ý về Context Router:** Mọi tri thức domain lâu dài, database schema và quy tắc kiến trúc lưu trong `process/context/` đều cần được đăng ký định tuyến trong [`process/context/all-context.md`](templates/process/context/all-context.md). Agent sẽ dựa vào router này để nạp đúng ngữ cảnh khi cần, tránh scan bừa bãi toàn bộ repository.
32
+
33
+ ---
34
+
35
+ ### Sơ đồ Tổng quát Quy trình RIPER-5 (Workflows)
36
+
37
+ ```
38
+ [Khởi tạo Idea] ──► [0. Khởi tạo Task: task.md] (Human định nghĩa spec & AC)
39
+ │
40
+ ▼
41
+ [1. RESEARCH] (Agent nạp context ──► research.md ──► Gate G0)
42
+ │
43
+ ▼
44
+ [2. INNOVATE] (Agent tạo 2-3 options trong decision.md ──► Gate G1: Human duyệt)
45
+ │
46
+ ▼
47
+ [3. PLAN] (Agent chia vertical slices trong plan.md ──► Gate G2: Human duyệt)
48
+ │
49
+ ▼
50
+ [4. EXECUTE] (Agent code từng slice ──► test verifier ──► state.md)
51
+ │
52
+ ▼
53
+ [5. REVIEW] (Agent kiểm định đa chiều trong review.md ──► Gate G3: Human duyệt)
54
+ │
55
+ ▼
56
+ [COMPLETE] (Lưu trữ completed/ ──► handoff.md)
57
+ ```
58
+ *(Sơ đồ tương tác chi tiết Mermaid có tại [`docs/vi/01-overview.md`](docs/vi/01-overview.md#sơ-đồ-tổng-quát-quy-trình-riper-5-workflows))*.
59
+
60
+ ---
61
+
62
+ ### Tài liệu hướng dẫn
63
+
64
+ | Tài liệu | Nội dung |
65
+ |---|---|
66
+ | [01 · Overview & Architecture](docs/vi/01-overview.md) | Mental model, thiết kế 3 layer, luồng thông tin, sơ đồ workflow |
67
+ | [02 · Layer: `.agents/`](docs/vi/02-layer-agents.md) | Chi tiết: behavior, guardrails, conventions |
68
+ | [03 · Layer: `process/`](docs/vi/03-layer-process.md) | Chi tiết: seeds, context router, chuỗi artifact |
69
+ | [04 · Layer: `AGENTS.md`](docs/vi/04-layer-agentsmd.md) | Cấu trúc entry point & cách tùy biến theo project |
70
+ | [05 · Workflow: Tạo task mới](docs/vi/05-workflow-new-task.md) | Hướng dẫn từng bước: từ ý tưởng đến hoàn thành |
71
+ | [06 · Human vs Agent](docs/vi/06-human-vs-agent.md) | Ma trận trách nhiệm & chi tiết 4 Cổng kiểm soát (Gates G0–G3) |
72
+ | [07 · Deployment](docs/vi/07-deployment.md) | Các cách bootstrap, cấu hình monorepo, xử lý sự cố |
73
+ | [08 · Cẩm nang Kỹ thuật](docs/vi/08-developer-workflow-playbook.md) | Tình huống thực tế, thao tác hằng ngày, bảng prompt mẫu |
74
+ | [Note · DevOps CI/CD & Release](docs/vi/note/devops-release-automation.md) | Cẩm nang DevOps, xử lý token 2FA npm, đồng bộ Git tag |
75
+
76
+ ---
77
+
78
+ ### Quick-start (5 phút)
79
+
80
+ ```bash
81
+ # 1. Bootstrap template vào project của bạn
82
+ npx @damphuquy/agent-init ./my-project
83
+
84
+ # 2. Mở AGENTS.md, cấu hình toolchain (2 phút)
85
+ # Tìm thẻ <validation_commands> và điền lệnh test/lint của dự án
86
+
87
+ # 3. Khởi tạo task đầu tiên
88
+ cp my-project/process/_seeds/task-template.md.seed \
89
+ my-project/process/general-plans/active/CHG-001-init/task.md
90
+
91
+ # 4. Yêu cầu AI Agent bắt đầu
92
+ # "Đọc AGENTS.md và task.md, bắt đầu phase RESEARCH."
93
+ ```
94
+
95
+ ---
96
+
97
+ ### Tùy chọn lệnh NPX CLI
98
+
99
+ ```bash
100
+ npx @damphuquy/agent-init . # Khởi tạo tại thư mục hiện tại
101
+ npx @damphuquy/agent-init ./services/billing # Khởi tạo vào subsystem trong monorepo
102
+ npx @damphuquy/agent-init ./my-project --force # Ghi đè file nếu đã tồn tại
103
+ ```
104
+
105
+ ---
106
+
107
+ ### Quy trình CI/CD & Tự động Publish lên NPM
108
+
109
+ Repository được thiết lập pipeline tự động hóa tại [`.github/workflows/release.yml`](.github/workflows/release.yml):
110
+
111
+ 1. **Tự động tính toán Semantic Versioning:** Khi push code lên nhánh `main`, hệ thống tự phát hiện version dựa trên commit message:
112
+ - `BREAKING CHANGE:`, `!:`, `major:` $\rightarrow$ Tăng **Major** (`2.0.0`)
113
+ - `feat:` $\rightarrow$ Tăng **Minor** (`1.1.0`)
114
+ - `fix:`, `chore:`, `docs:`, ... $\rightarrow$ Tăng **Patch** (`1.0.4`)
115
+ *(Nếu bạn chủ động sửa version trong `package.json`, CI sẽ tự nhận diện version đó)*.
116
+ 2. **Tự động gắn Git Tag & Tạo GitHub Release:** Tự tạo tag `vX.Y.Z`, commit cập nhật `package.json` kèm `[skip ci]` và sinh release notes trên GitHub.
117
+ 3. **Tự động Publish NPM:** Build và đẩy package lên npm registry bằng `NPM_TOKEN` (loại Classic **Automation** token).
118
+ 4. **Đồng bộ về máy Local:** Để kéo commit và Git tag mới nhất về máy sau khi CI hoàn tất:
119
+ ```bash
120
+ git pull --tags origin main
121
+ ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@damphuquy/agent-init",
3
- "version": "1.2.1",
3
+ "version": "1.2.3",
4
4
  "description": "Scaffolding CLI to bootstrap RIPER-5 Coding Agents & Operational Workspace",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
package/templates/process/README.md CHANGED
@@ -50,10 +50,35 @@ process/
50
50
 
51
51
  ---
52
52
 
53
- ## 2. RIPER-5 Artifact Chain
53
+ ## 2. RIPER-5 Artifact Chain & Workflow
54
54
 
55
55
  Every task produces a sequential chain of artifacts. Create them progressively as the task advances:
56
56
 
57
+ ```mermaid
58
+ flowchart TD
59
+ subgraph Init["0. Initialization"]
60
+ Seed["task-template.md.seed"] -->|Instantiate| Task["task.md (Specification & AC)"]
61
+ end
62
+ subgraph R1["1. RESEARCH (Read-Only)"]
63
+ Task --> Res["research.md"] --> G0{"Gate G0 (Auto)"}
64
+ end
65
+ subgraph I2["2. INNOVATE (Read-Only)"]
66
+ G0 --> Dec["decision.md (2-3 Options)"] --> G1{"Gate G1 (Human Approval)"}
67
+ end
68
+ subgraph P3["3. PLAN (Plan-Only)"]
69
+ G1 --> Plan["plan.md (Vertical Slices)"] --> G2{"Gate G2 (Human Sign-off)"}
70
+ end
71
+ subgraph E4["4. EXECUTE (Scoped R/W)"]
72
+ G2 --> Code["Implement Slice"] --> Test["Run Verifiers"] --> State["state.md (Memory)"]
73
+ end
74
+ subgraph R5["5. REVIEW (Read-Only)"]
75
+ State --> Rev["review.md (Audit)"] --> G3{"Gate G3 (Human Approval)"}
76
+ end
77
+ subgraph Done["6. COMPLETE"]
78
+ G3 --> Arch["Move to completed/"] --> Handoff["handoff.md"]
79
+ end
80
+ ```
81
+
57
82
  ```text
58
83
  task.md ← (always) Master contract, RIPER phase/gate state, AC, decisions
59
84
  research.md ← (Research) Execution flow, evidence, boundaries