@damphuquy/agent-init 1.0.3 → 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 (3) hide show
  1. package/README.md +143 -29
  2. package/package.json +1 -1
  3. package/templates/process/context/all-context.md +17 -0
package/README.md CHANGED
@@ -1,66 +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).
16
+
17
+ ```bash
18
+ # Bootstrap immediately into your project
19
+ npx @damphuquy/agent-init ./my-project
20
+ ```
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
+
49
+ ---
50
+
51
+ ### Quick-start (5 minutes)
4
52
 
5
53
  ```bash
6
- # Bootstrap ngay vào project của bạn
54
+ # 1. Bootstrap template into your target project
7
55
  npx @damphuquy/agent-init ./my-project
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."
8
66
  ```
9
67
 
10
68
  ---
11
69
 
12
- ## Kiến trúc 3-layer
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
76
+ ```
77
+
78
+ ---
79
+
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
+ ```
95
+
96
+ ---
97
+
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
13
109
 
14
110
  ```
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
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
18
114
  ```
19
115
 
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)
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.
22
120
 
23
121
  ---
24
122
 
25
- ## Tài liệu hướng dẫn
123
+ ### Tài liệu hướng dẫn
26
124
 
27
125
  | Tài liệu | Nội dung |
28
126
  |---|---|
29
- | [01 · Overview & Architecture](docs/01-overview.md) | Mental model, 3-layer design, quick-start |
30
- | [02 · Layer: `.agents/`](docs/02-layer-agents.md) | File-by-file: behavior, guardrails, conventions |
31
- | [03 · Layer: `process/`](docs/03-layer-process.md) | File-by-file: seeds, context, protocols, artifact chain |
32
- | [04 · Layer: `AGENTS.md`](docs/04-layer-agentsmd.md) | Entry point anatomy, customization |
33
- | [05 · Workflow: Tạo task mới](docs/05-workflow-new-task.md) | Tutorial từng bước RIPER-5 |
34
- | [06 · Human vs Agent](docs/06-human-vs-agent.md) | Phân rõ ai làm gì ở từng bước |
35
- | [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ố |
36
134
 
37
135
  ---
38
136
 
39
- ## Quick-start (5 phút)
137
+ ### Quick-start (5 phút)
40
138
 
41
139
  ```bash
42
- # 1. Bootstrap template vào project
140
+ # 1. Bootstrap template vào project của bạn
43
141
  npx @damphuquy/agent-init ./my-project
44
142
 
45
143
  # 2. Mở AGENTS.md, cấu hình toolchain (2 phút)
46
- # 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
47
145
 
48
- # 3. Tạo task đầu tiên
146
+ # 3. Khởi tạo task đầu tiên
49
147
  cp my-project/process/_seeds/task-template.md.seed \
50
148
  my-project/process/general-plans/active/CHG-001-init/task.md
51
149
 
52
- # 4. Yêu cầu agent bắt đầu
53
- # "Đọ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."
54
152
  ```
55
153
 
56
- Hướng dẫn chi tiết → [`docs/07-deployment.md`](docs/07-deployment.md)
57
-
58
154
  ---
59
155
 
60
- ## NPX Options
156
+ ### Tùy chọn lệnh NPX CLI
61
157
 
62
158
  ```bash
63
- npx @damphuquy/agent-init . # Bootstrap tại thư mục hiện tại
64
- npx @damphuquy/agent-init ./services/billing # Bootstrap vào subsystem cụ thể
65
- 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
66
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.0.3",
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",
package/templates/process/context/all-context.md CHANGED
@@ -7,6 +7,15 @@
7
7
  </description>
8
8
 
9
9
  ## Context Directory Index
10
+
11
+ <!--
12
+ CONTEXT ROUTING GUIDELINES:
13
+ - Central index for all project domain knowledge, architecture, and invariants.
14
+ - When adding a new context file or directory (e.g. context/auth/, context/database/),
15
+ ALWAYS register a new <group> entry below.
16
+ - Specify clear `scope` so agents know exactly when to load this context group without
17
+ unnecessary full-directory scanning.
18
+ -->
10
19
  <context_groups>
11
20
  <group id="planning">
12
21
  <title>Planning Standards & Calibration</title>
@@ -25,6 +34,14 @@
25
34
  <path>[`../development-protocols/all-development-protocols.md`](../development-protocols/all-development-protocols.md)</path>
26
35
  <scope>Engineering harness, subagent orchestration, and code standards</scope>
27
36
  </group>
37
+
38
+ <!-- Example: Register custom domain context below
39
+ <group id="domain-billing">
40
+ <title>Billing & Invoicing Architecture</title>
41
+ <path>[`billing/billing-context.md`](billing/billing-context.md)</path>
42
+ <scope>Payment gateway integrations, invoice calculation invariants, tax handling</scope>
43
+ </group>
44
+ -->
28
45
  </context_groups>
29
46
 
30
47
  </context_router>