@damphuquy/agent-init 1.1.0 → 1.2.1
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.
- package/README.md +144 -30
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,68 +1,182 @@
|
|
|
1
|
-
# agent-instructions
|
|
1
|
+
# agent-instructions (@damphuquy/agent-init)
|
|
2
2
|
|
|
3
|
-
|
|
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
|
|
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
|
+
| [Note · DevOps CI/CD & Release](docs/note/devops-release-automation.md) | Automated SemVer, 2FA npm tokens, Git tag sync |
|
|
49
|
+
|
|
10
50
|
---
|
|
11
51
|
|
|
12
|
-
|
|
52
|
+
### Quick-start (5 minutes)
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
# 1. Bootstrap template into your target project
|
|
56
|
+
npx @damphuquy/agent-init ./my-project
|
|
13
57
|
|
|
58
|
+
# 2. Configure project toolchain in AGENTS.md (2 mins)
|
|
59
|
+
# Find <validation_commands> and enter your test/lint commands
|
|
60
|
+
|
|
61
|
+
# 3. Instantiate your first active task
|
|
62
|
+
cp my-project/process/_seeds/task-template.md.seed \
|
|
63
|
+
my-project/process/general-plans/active/CHG-001-init/task.md
|
|
64
|
+
|
|
65
|
+
# 4. Prompt your AI Agent to begin
|
|
66
|
+
# "Read AGENTS.md and task.md, start RESEARCH phase."
|
|
14
67
|
```
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
68
|
+
|
|
69
|
+
---
|
|
70
|
+
|
|
71
|
+
### NPX CLI Options
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
npx @damphuquy/agent-init . # Bootstrap in current directory
|
|
75
|
+
npx @damphuquy/agent-init ./services/billing # Bootstrap into a monorepo subsystem
|
|
76
|
+
npx @damphuquy/agent-init ./my-project --force # Overwrite existing files
|
|
18
77
|
```
|
|
19
78
|
|
|
20
|
-
|
|
21
|
-
Chi tiết → [`docs/01-overview.md`](docs/01-overview.md)
|
|
79
|
+
---
|
|
22
80
|
|
|
23
|
-
|
|
81
|
+
### CI/CD & Automated NPM Release
|
|
82
|
+
|
|
83
|
+
This repository includes a continuous integration and release pipeline configured at [`.github/workflows/release.yml`](.github/workflows/release.yml):
|
|
84
|
+
|
|
85
|
+
1. **Automated Semantic Versioning:** On pushes to `main`, commit messages determine the version bump:
|
|
86
|
+
- `BREAKING CHANGE:`, `!:`, `major:` $\rightarrow$ **Major** bump (`2.0.0`)
|
|
87
|
+
- `feat:` $\rightarrow$ **Minor** bump (`1.1.0`)
|
|
88
|
+
- `fix:`, `chore:`, `docs:`, etc. $\rightarrow$ **Patch** bump (`1.0.4`)
|
|
89
|
+
*(Manual version increments in `package.json` are automatically respected)*.
|
|
90
|
+
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.
|
|
91
|
+
3. **NPM Publishing:** Automatically packages and publishes to npm registry using `NPM_TOKEN` (Classic Token with **Automation** type).
|
|
92
|
+
4. **Local Sync:** To sync newly generated tags and commits locally:
|
|
93
|
+
```bash
|
|
94
|
+
git pull --tags origin main
|
|
95
|
+
```
|
|
24
96
|
|
|
25
97
|
---
|
|
26
98
|
|
|
27
|
-
|
|
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
|
|
28
125
|
|
|
29
126
|
| Tài liệu | Nội dung |
|
|
30
127
|
|---|---|
|
|
31
|
-
| [01 · Overview & Architecture](docs/01-overview.md) | Mental model, 3
|
|
32
|
-
| [02 · Layer: `.agents/`](docs/02-layer-agents.md) |
|
|
33
|
-
| [03 · Layer: `process/`](docs/03-layer-process.md) |
|
|
34
|
-
| [04 · Layer: `AGENTS.md`](docs/04-layer-agentsmd.md) |
|
|
35
|
-
| [05 · Workflow: Tạo task mới](docs/05-workflow-new-task.md) |
|
|
36
|
-
| [06 · Human vs Agent](docs/06-human-vs-agent.md) |
|
|
37
|
-
| [07 · Deployment](docs/07-deployment.md) |
|
|
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 |
|
|
38
136
|
|
|
39
137
|
---
|
|
40
138
|
|
|
41
|
-
|
|
139
|
+
### Quick-start (5 phút)
|
|
42
140
|
|
|
43
141
|
```bash
|
|
44
|
-
# 1. Bootstrap template vào project
|
|
142
|
+
# 1. Bootstrap template vào project của bạn
|
|
45
143
|
npx @damphuquy/agent-init ./my-project
|
|
46
144
|
|
|
47
145
|
# 2. Mở AGENTS.md, cấu hình toolchain (2 phút)
|
|
48
|
-
# Tìm
|
|
146
|
+
# Tìm thẻ <validation_commands> và điền lệnh test/lint của dự án
|
|
49
147
|
|
|
50
|
-
# 3.
|
|
148
|
+
# 3. Khởi tạo task đầu tiên
|
|
51
149
|
cp my-project/process/_seeds/task-template.md.seed \
|
|
52
150
|
my-project/process/general-plans/active/CHG-001-init/task.md
|
|
53
151
|
|
|
54
|
-
# 4. Yêu cầu
|
|
55
|
-
# "Đọc AGENTS.md và task.md, bắt đầu phase RESEARCH"
|
|
152
|
+
# 4. Yêu cầu AI Agent bắt đầu
|
|
153
|
+
# "Đọc AGENTS.md và task.md, bắt đầu phase RESEARCH."
|
|
56
154
|
```
|
|
57
155
|
|
|
58
|
-
Hướng dẫn chi tiết → [`docs/07-deployment.md`](docs/07-deployment.md)
|
|
59
|
-
|
|
60
156
|
---
|
|
61
157
|
|
|
62
|
-
|
|
158
|
+
### Tùy chọn lệnh NPX CLI
|
|
63
159
|
|
|
64
160
|
```bash
|
|
65
|
-
npx @damphuquy/agent-init . #
|
|
66
|
-
npx @damphuquy/agent-init ./services/billing #
|
|
67
|
-
npx @damphuquy/agent-init ./my-project --force # Ghi đè file đã tồn tại
|
|
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
|
|
68
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
|
+
```
|