@damphuquy/agent-init 1.1.0 → 1.2.0

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 (2) hide show
  1. package/README.md +142 -30
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,68 +1,180 @@
1
- # agent-instructions
1
+ # agent-instructions (@damphuquy/agent-init)
2
2
 
3
- 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).
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*
5
+
6
+ <p align="center">
7
+ <a href="#english">English</a> • <a href="#tiếng-việt">Tiếng Việt</a>
8
+ </p>
9
+
10
+ ---
11
+
12
+ <a id="english"></a>
13
+ ## English
14
+
15
+ 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).
4
16
 
5
17
  ```bash
6
- # Bootstrap ngay vào project của bạn
18
+ # Bootstrap immediately into your project
7
19
  npx @damphuquy/agent-init ./my-project
8
20
  ```
9
21
 
22
+ ### 3-Layer Architecture
23
+
24
+ ```
25
+ AGENTS.md ← Entry point: project-specific toolchain + RIPER-5 phase definitions
26
+ .agents/ ← Agent control layer: mode declaration, guardrails, conventions
27
+ process/ ← Engineering workflow: task artifacts, seed blueprints, context
28
+ ```
29
+
30
+ Each layer has single-responsibility ownership with **Zero Duplication**.
31
+ Full architectural details → [`docs/01-overview.md`](docs/01-overview.md)
32
+
33
+ > 💡 **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
+
35
+ ---
36
+
37
+ ### Documentation
38
+
39
+ | Document | Description |
40
+ |---|---|
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
+
10
49
  ---
11
50
 
12
- ## Kiến trúc 3-layer
51
+ ### Quick-start (5 minutes)
52
+
53
+ ```bash
54
+ # 1. Bootstrap template into your target project
55
+ npx @damphuquy/agent-init ./my-project
13
56
 
57
+ # 2. Configure project toolchain in AGENTS.md (2 mins)
58
+ # Find <validation_commands> and enter your test/lint commands
59
+
60
+ # 3. Instantiate your first active task
61
+ cp my-project/process/_seeds/task-template.md.seed \
62
+ my-project/process/general-plans/active/CHG-001-init/task.md
63
+
64
+ # 4. Prompt your AI Agent to begin
65
+ # "Read AGENTS.md and task.md, start RESEARCH phase."
14
66
  ```
15
- AGENTS.md ← Entry point: project config + RIPER-5 phase definitions
16
- .agents/ ← Agent control layer: behavior, guardrails, conventions
17
- process/ ← Engineering workflow: task artifacts, seeds, context
67
+
68
+ ---
69
+
70
+ ### NPX CLI Options
71
+
72
+ ```bash
73
+ npx @damphuquy/agent-init . # Bootstrap in current directory
74
+ npx @damphuquy/agent-init ./services/billing # Bootstrap into a monorepo subsystem
75
+ npx @damphuquy/agent-init ./my-project --force # Overwrite existing files
18
76
  ```
19
77
 
20
- Mỗi layer có trách nhiệm độc lập và không duplicate nhau.
21
- Chi tiết → [`docs/01-overview.md`](docs/01-overview.md)
78
+ ---
22
79
 
23
- > 💡 **Lưu ý về Context Router:** Mọi kiến thức domain lâu dài (kiến trúc, DB schema, quy tắc nghiệp vụ) lưu trong `process/context/` đều cần được khai báo đị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, không quét bừa toàn bộ repository.
80
+ ### CI/CD & Automated NPM Release
81
+
82
+ This repository includes a continuous integration and release pipeline configured at [`.github/workflows/release.yml`](.github/workflows/release.yml):
83
+
84
+ 1. **Automated Semantic Versioning:** On pushes to `main`, commit messages determine the version bump:
85
+ - `BREAKING CHANGE:`, `!:`, `major:` $\rightarrow$ **Major** bump (`2.0.0`)
86
+ - `feat:` $\rightarrow$ **Minor** bump (`1.1.0`)
87
+ - `fix:`, `chore:`, `docs:`, etc. $\rightarrow$ **Patch** bump (`1.0.4`)
88
+ *(Manual version increments in `package.json` are automatically respected)*.
89
+ 2. **Git Tagging & GitHub Release:** Automatically creates and pushes the tag (e.g. `v1.1.0`), commits `package.json` with `[skip ci]`, and publishes GitHub Release notes.
90
+ 3. **NPM Publishing:** Automatically packages and publishes to npm registry using `NPM_TOKEN` (Classic Token with **Automation** type).
91
+ 4. **Local Sync:** To sync newly generated tags and commits locally:
92
+ ```bash
93
+ git pull --tags origin main
94
+ ```
24
95
 
25
96
  ---
26
97
 
27
- ## Tài liệu hướng dẫn
98
+ <a id="tiếng-việt"></a>
99
+ ## Tiếng Việt
100
+
101
+ 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).
102
+
103
+ ```bash
104
+ # Khởi tạo ngay vào project của bạn
105
+ npx @damphuquy/agent-init ./my-project
106
+ ```
107
+
108
+ ### Kiến trúc 3-layer
109
+
110
+ ```
111
+ AGENTS.md ← Entry point: cấu hình project + định nghĩa các phase RIPER-5
112
+ .agents/ ← Agent control layer: hành vi, guardrails, quy chuẩn code
113
+ process/ ← Engineering workflow: task artifacts, seed blueprints, context
114
+ ```
115
+
116
+ Mỗi layer chịu trách nhiệm độc lập theo nguyên tắc **Zero Duplication**.
117
+ Chi tiết kiến trúc → [`docs/01-overview.md`](docs/01-overview.md)
118
+
119
+ > 💡 **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.
120
+
121
+ ---
122
+
123
+ ### Tài liệu hướng dẫn
28
124
 
29
125
  | Tài liệu | Nội dung |
30
126
  |---|---|
31
- | [01 · Overview & Architecture](docs/01-overview.md) | Mental model, 3-layer design, quick-start |
32
- | [02 · Layer: `.agents/`](docs/02-layer-agents.md) | File-by-file: behavior, guardrails, conventions |
33
- | [03 · Layer: `process/`](docs/03-layer-process.md) | File-by-file: seeds, context, protocols, artifact chain |
34
- | [04 · Layer: `AGENTS.md`](docs/04-layer-agentsmd.md) | Entry point anatomy, customization |
35
- | [05 · Workflow: Tạo task mới](docs/05-workflow-new-task.md) | Tutorial từng bước RIPER-5 |
36
- | [06 · Human vs Agent](docs/06-human-vs-agent.md) | Phân rõ ai làm gì ở từng bước |
37
- | [07 · Deployment](docs/07-deployment.md) | Bootstrap, cài đặt, cấu hình lần đầu |
127
+ | [01 · Overview & Architecture](docs/01-overview.md) | Mental model, thiết kế 3 layer, luồng thông tin |
128
+ | [02 · Layer: `.agents/`](docs/02-layer-agents.md) | Chi tiết: behavior, guardrails, conventions |
129
+ | [03 · Layer: `process/`](docs/03-layer-process.md) | Chi tiết: seeds, context router, chuỗi artifact |
130
+ | [04 · Layer: `AGENTS.md`](docs/04-layer-agentsmd.md) | Cấu trúc entry point & cách tùy biến theo project |
131
+ | [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 |
132
+ | [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) |
133
+ | [07 · Deployment](docs/07-deployment.md) | Các cách bootstrap, cấu hình monorepo, xử lý sự cố |
38
134
 
39
135
  ---
40
136
 
41
- ## Quick-start (5 phút)
137
+ ### Quick-start (5 phút)
42
138
 
43
139
  ```bash
44
- # 1. Bootstrap template vào project
140
+ # 1. Bootstrap template vào project của bạn
45
141
  npx @damphuquy/agent-init ./my-project
46
142
 
47
143
  # 2. Mở AGENTS.md, cấu hình toolchain (2 phút)
48
- # Tìm dòng <validation_commands> và điền lệnh test/lint của project
144
+ # Tìm thẻ <validation_commands> và điền lệnh test/lint của dự án
49
145
 
50
- # 3. Tạo task đầu tiên
146
+ # 3. Khởi tạo task đầu tiên
51
147
  cp my-project/process/_seeds/task-template.md.seed \
52
148
  my-project/process/general-plans/active/CHG-001-init/task.md
53
149
 
54
- # 4. Yêu cầu agent bắt đầu
55
- # "Đọc AGENTS.md và task.md, bắt đầu phase RESEARCH"
150
+ # 4. Yêu cầu AI Agent bắt đầu
151
+ # "Đọc AGENTS.md và task.md, bắt đầu phase RESEARCH."
56
152
  ```
57
153
 
58
- Hướng dẫn chi tiết → [`docs/07-deployment.md`](docs/07-deployment.md)
59
-
60
154
  ---
61
155
 
62
- ## NPX Options
156
+ ### Tùy chọn lệnh NPX CLI
63
157
 
64
158
  ```bash
65
- npx @damphuquy/agent-init . # Bootstrap tại thư mục hiện tại
66
- npx @damphuquy/agent-init ./services/billing # Bootstrap vào subsystem cụ thể
67
- npx @damphuquy/agent-init ./my-project --force # Ghi đè file đã tồn tại
159
+ npx @damphuquy/agent-init . # Khởi tạo tại thư mục hiện tại
160
+ npx @damphuquy/agent-init ./services/billing # Khởi tạo vào subsystem trong monorepo
161
+ npx @damphuquy/agent-init ./my-project --force # Ghi đè file nếu đã tồn tại
68
162
  ```
163
+
164
+ ---
165
+
166
+ ### Quy trình CI/CD & Tự động Publish lên NPM
167
+
168
+ Repository được thiết lập pipeline tự động hóa tại [`.github/workflows/release.yml`](.github/workflows/release.yml):
169
+
170
+ 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:
171
+ - `BREAKING CHANGE:`, `!:`, `major:` $\rightarrow$ Tăng **Major** (`2.0.0`)
172
+ - `feat:` $\rightarrow$ Tăng **Minor** (`1.1.0`)
173
+ - `fix:`, `chore:`, `docs:`, ... $\rightarrow$ Tăng **Patch** (`1.0.4`)
174
+ *(Nếu bạn chủ động sửa version trong `package.json`, CI sẽ tự nhận diện version đó)*.
175
+ 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.
176
+ 3. **Tự động Publish NPM:** Build và đẩy package lên npm registry bằng `NPM_TOKEN` (loại Classic **Automation** token).
177
+ 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:
178
+ ```bash
179
+ git pull --tags origin main
180
+ ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@damphuquy/agent-init",
3
- "version": "1.1.0",
3
+ "version": "1.2.0",
4
4
  "description": "Scaffolding CLI to bootstrap RIPER-5 Coding Agents & Operational Workspace",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",