@damphuquy/agent-init 1.2.5 → 1.4.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 (16) hide show
  1. package/README.md +30 -84
  2. package/README.vi.md +30 -84
  3. package/dist/config.d.ts.map +1 -1
  4. package/dist/config.js +4 -0
  5. package/dist/config.js.map +1 -1
  6. package/package.json +1 -1
  7. package/templates/.agents/guardrails.md +38 -1
  8. package/templates/AGENTS.md +2 -0
  9. package/templates/process/.editorconfig +15 -0
  10. package/templates/process/README.md +10 -2
  11. package/templates/process/_seeds/_GUIDE.md +37 -8
  12. package/templates/process/_seeds/cancellation-template.md.seed +79 -0
  13. package/templates/process/_seeds/results-template.tsv.seed +5 -0
  14. package/templates/process/_seeds/review-template.md.seed +2 -1
  15. package/templates/process/context/all-context.md +6 -0
  16. package/templates/process/context/tests/all-tests.md +56 -0
package/README.md CHANGED
@@ -8,114 +8,60 @@
8
8
 
9
9
  ---
10
10
 
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).
11
+ A structured scaffolding framework for AI Coding Agents following the **RIPER-5 Framework** — cleanly separated into three layers: `AGENTS.md` (project configuration), `.agents/` (agent behavioral controls), and `process/` (task execution and verification workflow).
12
12
 
13
13
  ```bash
14
- # Bootstrap immediately into your project
15
- npx @damphuquy/agent-init ./my-project
14
+ # Bootstrap immediately into your project (takes 30 seconds)
15
+ npx @damphuquy/agent-init .
16
16
  ```
17
17
 
18
18
  ---
19
19
 
20
- ### 3-Layer Architecture
20
+ ## 🚀 Documentation
21
21
 
22
- ```
23
- AGENTS.md ← Entry point: project-specific toolchain + RIPER-5 phase definitions
24
- .agents/ ← Agent control layer: mode declaration, guardrails, conventions
25
- process/ ← Engineering workflow: task artifacts, seed blueprints, context
26
- ```
22
+ Designed for minimal overhead, practical focus, and zero fluff:
27
23
 
28
- Each layer has single-responsibility ownership with **Zero Duplication**.
29
- Full architectural details → [`docs/en/01-overview.md`](docs/en/01-overview.md)
24
+ ### 1. For Daily Development (Start Here)
25
+ * 📘 **[01 · Hands-on Walkthrough from A–Z](docs/en/01-getting-started.md)**: **The only guide you need to get started**. Step-by-step instructions with **a complete end-to-end example** (adding a user change-password endpoint), prompt templates, and quality gate sign-offs.
26
+ * ⚡ **[02 · Daily Cheat Sheet](docs/en/02-cheat-sheet.md)**: Copy-paste prompt templates for each phase, quality gates summary (Gates G0–G3), and file ownership matrix (Human vs Agent).
30
27
 
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.
28
+ ### 2. In-Depth Reference (For Tech Leads & Maintainers)
29
+ * 🏛️ **[3-Layer Architecture & Context Router](docs/en/reference/architecture.md)**: Deep dive into the 3-layer decoupled architecture and Minimum Sufficient Context principles (No Full-Repo Scan).
30
+ * 🚢 **[DevOps & Release Automation](docs/en/reference/devops-release.md)**: CI/CD release lifecycle, automated Semantic Versioning, and NPM package publishing.
32
31
 
33
32
  ---
34
33
 
35
- ### RIPER-5 End-to-End Workflow
34
+ ## ⚡ 5-Step Daily Collaboration Workflow
36
35
 
37
36
  ```
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)
37
+ ┌────────────────────────────────────────────────────────────────────────────────┐
38
+ │ YOUR 5-STEP DAILY WORKFLOW WITH AGENTS │
39
+ ├────────────────────────────────────────────────────────────────────────────────┤
40
+ │ 1. YOU: Create task folder & describe spec in task.md (1 min) │
41
+ │ 2. PROMPT AGENT: "Read task.md, start RESEARCH" ──► Agent inspects codebase │
42
+ │ 3. YOU: Pick architectural option & sign Gate G1 in decision.md (30 secs) │
43
+ │ 4. YOU: Verify allowed files list & sign Gate G2 in plan.md (30 secs) │
44
+ │ 5. AGENT CODES & TESTS ──► YOU: Review git diff, sign Gate G3, commit & push! │
45
+ └────────────────────────────────────────────────────────────────────────────────┘
57
46
  ```
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
-
62
- ### Documentation
63
-
64
- | Document | Description |
65
- |---|---|
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) | File ownership, create/edit/approve matrix, Quality Gates (G0–G3), maintenance |
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 |
75
47
 
76
48
  ---
77
49
 
78
- ### Quick-start (5 minutes)
50
+ ## 📦 NPX CLI Commands
79
51
 
80
52
  ```bash
81
- # 1. Bootstrap template into your target project
82
- npx @damphuquy/agent-init ./my-project
53
+ # Bootstrap in current directory
54
+ npx @damphuquy/agent-init .
83
55
 
84
- # 2. Configure project toolchain in AGENTS.md (2 mins)
85
- # Find <validation_commands> and enter your test/lint commands
56
+ # Bootstrap into a subfolder/monorepo package
57
+ npx @damphuquy/agent-init ./services/billing
86
58
 
87
- # 3. Instantiate your first active task
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. Prompt your AI Agent to begin
92
- # "Read AGENTS.md and task.md, start RESEARCH phase."
59
+ # Force overwrite existing scaffold files
60
+ npx @damphuquy/agent-init . --force
93
61
  ```
94
62
 
95
63
  ---
96
64
 
97
- ### NPX CLI Options
98
-
99
- ```bash
100
- npx @damphuquy/agent-init . # Bootstrap in current directory
101
- npx @damphuquy/agent-init ./services/billing # Bootstrap into a monorepo subsystem
102
- npx @damphuquy/agent-init ./my-project --force # Overwrite existing files
103
- ```
104
-
105
- ---
65
+ ## 📄 License
106
66
 
107
- ### CI/CD & Automated NPM Release
108
-
109
- This repository includes a continuous integration and release pipeline configured at [`.github/workflows/release.yml`](.github/workflows/release.yml):
110
-
111
- 1. **Automated Semantic Versioning:** On pushes to `main`, commit messages determine the version bump:
112
- - `BREAKING CHANGE:`, `!:`, `major:` $\rightarrow$ **Major** bump (`2.0.0`)
113
- - `feat:` $\rightarrow$ **Minor** bump (`1.1.0`)
114
- - `fix:`, `chore:`, `docs:`, etc. $\rightarrow$ **Patch** bump (`1.0.4`)
115
- *(Manual version increments in `package.json` are automatically respected)*.
116
- 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.
117
- 3. **NPM Publishing:** Automatically packages and publishes to npm registry using `NPM_TOKEN` (Classic Token with **Automation** type).
118
- 4. **Local Sync:** To sync newly generated tags and commits locally:
119
- ```bash
120
- git pull --tags origin main
121
- ```
67
+ Licensed under the [MIT License](LICENSE).
package/README.vi.md CHANGED
@@ -8,114 +8,60 @@
8
8
 
9
9
  ---
10
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).
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` (cấu hình dự án), `.agents/` (quy chuẩn hành vi của Agent), và `process/` (quy trình thực thi task và kiểm thử).
12
12
 
13
13
  ```bash
14
- # Khởi tạo ngay vào project của bạn
15
- npx @damphuquy/agent-init ./my-project
14
+ # Khởi tạo ngay vào project của bạn (chỉ mất 30 giây)
15
+ npx @damphuquy/agent-init .
16
16
  ```
17
17
 
18
18
  ---
19
19
 
20
- ### Kiến trúc 3-layer
20
+ ## 🚀 Tài liệu Hướng dẫn
21
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
- ```
22
+ Tài liệu được thiết kế tối giản, tập trung vào thực hành, không lý thuyết rườm rà:
27
23
 
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)
24
+ ### 1. Dành cho công việc hằng ngày (Bắt đầu tại đây)
25
+ * 📘 **[01 · Hướng dẫn Thực chiến từ A–Z (Hands-on Walkthrough)](docs/vi/01-getting-started.md)**: **Tài liệu duy nhất bạn cần đọc để bắt đầu**. Hướng dẫn từng bước với **ví dụ cụ thể xuyên suốt** (thêm chức năng đổi mật khẩu), chi tiết ai làm gì, gõ lệnh gì, prompt mẫu và cách ký duyệt qua các cổng.
26
+ * ⚡ **[02 · Sổ tay Tra cứu Nhanh (Cheat Sheet)](docs/vi/02-cheat-sheet.md)**: Bảng copy-paste prompt mẫu cho từng giai đoạn, bảng 4 cổng kiểm soát (Gates G0–G3), và ma trận quyền hạn file (Human vs Agent).
30
27
 
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.
28
+ ### 2. Tài liệu Chuyên sâu & Tham khảo (Dành cho Lead / Maintainer)
29
+ * 🏛️ **[Kiến trúc 3 Tầng & Cơ chế Context Router](docs/vi/reference/architecture.md)**: Giải thích sâu về thiết kế tách rời 3 layer và cơ chế nạp ngữ cảnh tối thiểu (No Full-Repo Scan).
30
+ * 🚢 **[Cẩm nang DevOps & Tự động hóa Phát hành](docs/vi/reference/devops-release.md)**: Quy trình CI/CD tự động tính Semantic Versioning và publish package lên NPM.
32
31
 
33
32
  ---
34
33
 
35
- ### Sơ đồ Tổng quát Quy trình RIPER-5 (Workflows)
34
+ ## ⚡ Quy trình Phối hợp 5 Bước trong 1 Phút
36
35
 
37
36
  ```
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)
37
+ ┌────────────────────────────────────────────────────────────────────────────────┐
38
+ │ QUY TRÌNH 5 BƯỚC HẰNG NGÀY CỦA BẠN │
39
+ ├────────────────────────────────────────────────────────────────────────────────┤
40
+ │ 1. BẠN: Tạo thư mục task & viết yêu cầu vào task.md (1 phút) │
41
+ │ 2. PROMPT AGENT: "Đọc task.md, bắt đầu RESEARCH" ──► Agent tự khảo sát code │
42
+ │ 3. BẠN: Chọn phương án kiến trúc & ký Gate G1 trong decision.md (30 giây) │
43
+ │ 4. BẠN: Xem danh sách file được sửa & ký Gate G2 trong plan.md (30 giây) │
44
+ │ 5. AGENT CODE & TEST ──► BẠN: Kiểm tra git diff, ký Gate G3, commit & push! │
45
+ └────────────────────────────────────────────────────────────────────────────────┘
57
46
  ```
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) | Quyền sở hữu file, ma trận tạo/sửa/duyệt, 4 Cổng kiểm soát (G0–G3), bảo trì framework |
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
47
 
76
48
  ---
77
49
 
78
- ### Quick-start (5 phút)
50
+ ## 📦 Các Lệnh NPX CLI Tiện ích
79
51
 
80
52
  ```bash
81
- # 1. Bootstrap template vào project của bạn
82
- npx @damphuquy/agent-init ./my-project
53
+ # Khởi tạo tại thư mục hiện tại
54
+ npx @damphuquy/agent-init .
83
55
 
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
56
+ # Khởi tạo vào một thư mục con trong monorepo
57
+ npx @damphuquy/agent-init ./services/billing
86
58
 
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."
59
+ # Ghi đè file nếu đã tồn tại
60
+ npx @damphuquy/agent-init . --force
93
61
  ```
94
62
 
95
63
  ---
96
64
 
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
- ---
65
+ ## 📄 Giấy phép
106
66
 
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
- ```
67
+ Phát hành dưới giấy phép [MIT](LICENSE).
package/dist/config.d.ts.map CHANGED
@@ -1 +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,EAyD3C,CAAC;AAEF,wBAAgB,cAAc,IAAI,MAAM,CASvC;AAED,wBAAgB,cAAc,CAAC,cAAc,GAAE,MAAyB,GAAG,WAAW,CAgBrF"}
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,EA6D3C,CAAC;AAEF,wBAAgB,cAAc,IAAI,MAAM,CASvC;AAED,wBAAgB,cAAc,CAAC,cAAc,GAAE,MAAyB,GAAG,WAAW,CAgBrF"}
package/dist/config.js CHANGED
@@ -22,6 +22,7 @@ export const FILE_GROUPS = [
22
22
  title: 'Operational Workspace Control & Seeds (_seeds/)',
23
23
  files: [
24
24
  { path: 'process/README.md', desc: 'Operational Workspace Control Center' },
25
+ { path: 'process/.editorconfig', desc: 'Consistent editor and format rules for process artifacts' },
25
26
  { path: 'process/_seeds/_GUIDE.md', desc: 'Seed archetypes usage & lifecycle guide' },
26
27
  { path: 'process/_seeds/task-template.md.seed', desc: 'Task master contract & RIPER-5 execution plan' },
27
28
  { path: 'process/_seeds/context-group.md.seed', desc: 'Research phase artifact blueprint' },
@@ -30,6 +31,8 @@ export const FILE_GROUPS = [
30
31
  { path: 'process/_seeds/state-template.md.seed', desc: 'Execute loop persistent memory' },
31
32
  { path: 'process/_seeds/review-template.md.seed', desc: 'Review phase artifact & Gate 3' },
32
33
  { path: 'process/_seeds/handoff-template.md.seed', desc: 'Final projection (intentionally short)' },
34
+ { path: 'process/_seeds/cancellation-template.md.seed', desc: 'Knowledge-preserving task cancellation record' },
35
+ { path: 'process/_seeds/results-template.tsv.seed', desc: 'Benchmark & quantitative metrics evaluation registry' },
33
36
  { path: 'process/_seeds/program-template.md.seed', desc: 'Multi-phase umbrella epic blueprint' },
34
37
  ],
35
38
  },
@@ -38,6 +41,7 @@ export const FILE_GROUPS = [
38
41
  files: [
39
42
  { path: 'process/context/all-context.md', desc: 'Root context & knowledge routing registry' },
40
43
  { path: 'process/context/planning/all-planning.md', desc: 'INVEST criteria & vertical slicing standards' },
44
+ { path: 'process/context/tests/all-tests.md', desc: 'Test pyramid, isolation policies, and harness strategy' },
41
45
  ],
42
46
  },
43
47
  {
package/dist/config.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@damphuquy/agent-init",
3
- "version": "1.2.5",
3
+ "version": "1.4.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/.agents/guardrails.md CHANGED
@@ -57,7 +57,8 @@
57
57
  2. All validation commands (as defined in `AGENTS.md`) execute with
58
58
  zero errors and zero warnings.
59
59
  3. Gate 3 in `review.md` is checked and review decision is PASS.
60
- 4. The final `git diff` contains zero extraneous or unreviewed modifications.
60
+ 4. The final `git diff` contains zero extraneous or unreviewed modifications,
61
+ and all transient debug code/scratch artifacts are completely removed.
61
62
  5. Task folder is moved to `completed/` and `handoff.md` is produced.
62
63
  </completion_gate>
63
64
 
@@ -73,4 +74,40 @@
73
74
  coordination is requested and approved.
74
75
  </invariants>
75
76
 
77
+ ---
78
+
79
+ ## 5. Command Safety & Destructive Action Blacklist
80
+
81
+ <command_safety>
82
+ The agent must NEVER execute destructive, irreversible, or credential-leaking commands:
83
+
84
+ - **Git Operations:** Never execute `git push --force`, `git push -f`, `git reset --hard`,
85
+ or `git clean -fdx` unless explicitly authorized by the human engineer in the current session.
86
+ - **Filesystem Deletion:** Never execute unconstrained recursive deletion (e.g. `rm -rf /`,
87
+ `rm -rf ~`, `rm -rf .`) or delete files outside the immediate active task scope.
88
+ - **Database DDL/DML:** Never execute destructive data operations without explicit prior approval
89
+ (`DROP DATABASE`, `DROP TABLE`, `TRUNCATE`, or `DELETE` queries lacking a specific `WHERE` clause).
90
+ - **Secrets & Credentials:** Never read, print, log, or export contents of `.env*`, `*.pem`,
91
+ `*.key`, SSH keys, or cloud credential stores into task artifacts or conversation output.
92
+ - **Environment Containment:** Execute commands exclusively through the designated harness
93
+ `<validation_commands>` or standard package managers. Never download or execute arbitrary
94
+ remote binary scripts (`curl ... | bash`).
95
+ </command_safety>
96
+
97
+ ---
98
+
99
+ ## 6. Session Housekeeping & Teardown Protocol
100
+
101
+ <housekeeping_protocol>
102
+ Before requesting Gate 3 sign-off or marking a task COMPLETE, the agent must perform full teardown:
103
+
104
+ 1. **Transient Debug Removal:** Remove all temporary debugging lines (`console.log`, `print()`,
105
+ `debugger`, `dump()`, `pprint()`, or commented-out experiment blocks) introduced during execution.
106
+ 2. **Scratch Cleanup:** Delete temporary mock files, scratch test scripts, and transient SQLite/data
107
+ dumps created during the execution loop.
108
+ 3. **Diff Sanitization:** Run `git status` and `git diff` to ensure that only the intentional, scoped
109
+ files agreed upon in `plan.md` have been modified.
110
+ 4. **State Finalization:** Ensure `state.md` is cleanly synchronized and generate `handoff.md`.
111
+ </housekeeping_protocol>
112
+
76
113
  </agent_guardrails>
package/templates/AGENTS.md CHANGED
@@ -126,6 +126,8 @@
126
126
  <rule id="isolation">Keep edits within this subsystem unless explicit cross-system coordination is requested.</rule>
127
127
  <rule id="subagents">Subagent delegation must adhere to [`process/development-protocols/orchestration.md`](process/development-protocols/orchestration.md).</rule>
128
128
  <rule id="no_stale_context">Re-read relevant files after the repository changes. Do not rely on stale conversation context.</rule>
129
+ <rule id="command_safety">Never run destructive commands (force push, hard reset, unconstrained rm -rf, DDL drops, secret inspection). See .agents/guardrails.md.</rule>
130
+ <rule id="housekeeping">Remove all debug logs, scratch artifacts, and verify git diff cleanliness before Gate G3.</rule>
129
131
  </workspace_rules>
130
132
 
131
133
  </agent_guidelines>
package/templates/process/.editorconfig ADDED
@@ -0,0 +1,15 @@
1
+ root = true
2
+
3
+ [*]
4
+ charset = utf-8
5
+ end_of_line = lf
6
+ indent_style = space
7
+ indent_size = 2
8
+ insert_final_newline = true
9
+ trim_trailing_whitespace = true
10
+
11
+ [*.tsv]
12
+ indent_style = tab
13
+
14
+ [*.md]
15
+ trim_trailing_whitespace = false
package/templates/process/README.md CHANGED
@@ -13,6 +13,7 @@
13
13
  ```text
14
14
  process/
15
15
  ├── README.md # Operational guide (this file)
16
+ ├── .editorconfig # Unified format settings for markdown, tsv, json
16
17
  ├── _seeds/ # Read-only archetype blueprints
17
18
  │ ├── _GUIDE.md # Full catalog, artifact chain, and instantiation commands
18
19
  │ ├── task-template.md.seed # Master contract & RIPER state record
@@ -22,10 +23,13 @@ process/
22
23
  │ ├── state-template.md.seed # Execute loop persistent memory
23
24
  │ ├── review-template.md.seed # Review phase artifact (Gate 3)
24
25
  │ ├── handoff-template.md.seed # Final projection (short)
26
+ │ ├── cancellation-template.md.seed # Knowledge-preserving cancellation record
27
+ │ ├── results-template.tsv.seed # Benchmark & quantitative metrics tracker
25
28
  │ └── program-template.md.seed # Multi-phase program blueprint
26
29
  ├── context/ # Durable knowledge base & context routers
27
30
  │ ├── all-context.md # Root context router
28
- │ └── planning/all-planning.md # Planning calibration & vertical slicing rules
31
+ │ ├── planning/all-planning.md # Planning calibration & vertical slicing rules
32
+ │ └── tests/all-tests.md # Testing pyramid, harness policy & mock conventions
29
33
  ├── development-protocols/ # System rules & execution harness
30
34
  │ ├── all-development-protocols.md
31
35
  │ ├── orchestration.md # Subagent delegation rules
@@ -39,7 +43,9 @@ process/
39
43
  │ │ ├── plan.md # Plan phase output
40
44
  │ │ ├── state.md # Execute loop memory
41
45
  │ │ ├── review.md # Review phase output
42
- │ │ └── handoff.md # Final projection
46
+ │ │ ├── handoff.md # Final projection
47
+ │ │ ├── results.tsv # (Optional) Benchmark & metric iteration tracking
48
+ │ │ └── cancelled.md # (If aborted) Cancellation findings & rollback status
43
49
  │ ├── completed/ # Archived task workspaces
44
50
  │ └── backlog/ # Backlog notes: {note_slug}_NOTE_{dd-mm-yy}.md
45
51
  └── general-plans/ # Cross-cutting & standalone tasks
@@ -101,6 +107,8 @@ handoff.md ← (Complete) Short final projection
101
107
  | Execute | source code + tests + `state.md` |
102
108
  | Review | `review.md` |
103
109
  | Handoff | `handoff.md` |
110
+ | Cancellation | `cancelled.md` (knowledge preservation upon abort) |
111
+ | Benchmark / Metrics | `results.tsv` (performance and eval metrics) |
104
112
  | Gate 1 | `decision.md` approval |
105
113
  | Gate 2 | `plan.md` approval |
106
114
  | Gate 3 | `review.md` approval |
package/templates/process/_seeds/_GUIDE.md CHANGED
@@ -69,6 +69,16 @@
69
69
  blast radius registries, and phase gate rules.
70
70
  </seed>
71
71
 
72
+ <seed type="cancellation" path="cancellation-template.md.seed">
73
+ Task cancellation record. Preserves investigation findings, decision rationale,
74
+ reusable prototypes/tests, and rollback verification when an in-flight task is cancelled.
75
+ </seed>
76
+
77
+ <seed type="results" path="results-template.tsv.seed">
78
+ Benchmark and quantitative metrics evaluation registry.
79
+ Use for tracking latency, throughput, memory, or eval scores across iterations and vertical slices.
80
+ </seed>
81
+
72
82
  </catalog>
73
83
 
74
84
  ---
@@ -107,15 +117,28 @@ handoff.md ← Final projection (short)
107
117
 
108
118
  ## 3. Recommended Task Workspace Layout
109
119
 
120
+ ### Standard Single-Project Layout
110
121
  ```text
111
122
  process/features/active/CHG-017-your-feature/
112
- ├── task.md ← instantiated from task-template.md.seed
113
- ├── research.md ← instantiated from context-group.md.seed
114
- ├── decision.md ← instantiated from decision-template.md.seed
115
- ├── plan.md ← instantiated from plan-template.md.seed
116
- ├── state.md ← instantiated from state-template.md.seed
117
- ├── review.md ← instantiated from review-template.md.seed
118
- └── handoff.md ← instantiated from handoff-template.md.seed
123
+ ├── task.md ← instantiated from task-template.md.seed (Master Spec & AC)
124
+ ├── research.md ← instantiated from context-group.md.seed (Research Output)
125
+ ├── decision.md ← instantiated from decision-template.md.seed (Gate 1 Options)
126
+ ├── plan.md ← instantiated from plan-template.md.seed (Gate 2 Execution Contract)
127
+ ├── state.md ← instantiated from state-template.md.seed (Execute Memory)
128
+ ├── review.md ← instantiated from review-template.md.seed (Gate 3 Audit)
129
+ ├── handoff.md ← instantiated from handoff-template.md.seed (Final Projection)
130
+ ├── results.tsv ← (Optional) instantiated from results-template.tsv.seed (Metrics/Benchmarks)
131
+ └── cancelled.md ← (If cancelled) instantiated from cancellation-template.md.seed
132
+ ```
133
+
134
+ ### Monorepo / Multi-Domain Layout (Optional)
135
+ When working in monorepos with independent domains (e.g. `mobile-app`, `billing-service`), partition features by domain:
136
+ ```text
137
+ process/features/{domain-slug}/
138
+ ├── active/
139
+ │ └── CHG-XXX-your-feature/
140
+ ├── backlog/
141
+ └── completed/
119
142
  ```
120
143
 
121
144
  Not all artifacts are required at start. Create them progressively as the task advances through RIPER phases.
@@ -128,7 +151,7 @@ Not all artifacts are required at start. Create them progressively as the task a
128
151
  # Create a new task workspace
129
152
  mkdir -p process/features/active/CHG-XXX-your-feature
130
153
 
131
- # Instantiate seeds into the workspace
154
+ # Instantiate primary seeds into the workspace
132
155
  cp process/_seeds/task-template.md.seed process/features/active/CHG-XXX-your-feature/task.md
133
156
  cp process/_seeds/context-group.md.seed process/features/active/CHG-XXX-your-feature/research.md
134
157
  cp process/_seeds/decision-template.md.seed process/features/active/CHG-XXX-your-feature/decision.md
@@ -136,6 +159,12 @@ cp process/_seeds/plan-template.md.seed process/features/active/CHG-XXX-your-
136
159
  cp process/_seeds/state-template.md.seed process/features/active/CHG-XXX-your-feature/state.md
137
160
  cp process/_seeds/review-template.md.seed process/features/active/CHG-XXX-your-feature/review.md
138
161
  cp process/_seeds/handoff-template.md.seed process/features/active/CHG-XXX-your-feature/handoff.md
162
+
163
+ # (Optional) Tracking performance or evaluation metrics:
164
+ cp process/_seeds/results-template.tsv.seed process/features/active/CHG-XXX-your-feature/results.tsv
165
+
166
+ # (When cancelling an in-flight task):
167
+ cp process/_seeds/cancellation-template.md.seed process/features/active/CHG-XXX-your-feature/cancelled.md
139
168
  ```
140
169
 
141
170
  </seeds_guide>
package/templates/process/_seeds/cancellation-template.md.seed ADDED
@@ -0,0 +1,79 @@
1
+ # Cancellation Record: [TASK-ID] [Task Title]
2
+
3
+ <cancellation_record task_id="[TASK-ID]" version="1.0" framework="RIPER-5">
4
+
5
+ <!--
6
+ TASK CANCELLATION GUIDELINES:
7
+ - Purpose: Preserve investigation knowledge, technical discoveries, and decision rationale when a task is aborted.
8
+ - Never delete a task workspace outright if research or partial planning has occurred.
9
+ - Instantiate this file as `cancelled.md` inside the task workspace.
10
+ - Complete the reversal checklist, then move the task directory to `completed/` (or `cancelled/`).
11
+ -->
12
+
13
+ <status>
14
+ <phase_at_cancellation>[RESEARCH | INNOVATE | PLAN | EXECUTE | REVIEW]</phase_at_cancellation>
15
+ <cancelled_date>[YYYY-MM-DD or DD-MM-YY]</cancelled_date>
16
+ <cancelled_by>[@engineer_or_product_lead]</cancelled_by>
17
+ <reversal_status>[CLEAN | ROLLBACK_APPLIED | DIRTY_NEEDS_MANUAL_CLEANUP]</reversal_status>
18
+ </status>
19
+
20
+ ---
21
+
22
+ ## 1. Rationale for Cancellation
23
+
24
+ <cancellation_rationale>
25
+ <primary_reason>
26
+ <!-- [e.g. Pivot in product strategy / Architectural blocker / Excessive blast radius / Superseded by CHG-YYY] -->
27
+ [Concise summary of why this task was terminated prematurely.]
28
+ </primary_reason>
29
+
30
+ <decision_context>
31
+ [Detailed context, trade-offs evaluated, and key stakeholder guidance that led to cancellation.]
32
+ </decision_context>
33
+ </cancellation_rationale>
34
+
35
+ ---
36
+
37
+ ## 2. Technical Findings & Preserved Knowledge
38
+
39
+ <preserved_knowledge>
40
+ <codebase_discoveries>
41
+ <!-- What did we learn about the system, data models, or hidden dependencies during this task? -->
42
+ - [Discovery 1 — Component behavior, undocumented API limits, or legacy constraints]
43
+ - [Discovery 2 — Existing tests or subsystem boundaries uncovered]
44
+ </codebase_discoveries>
45
+
46
+ <invalidated_hypotheses>
47
+ <!-- What assumptions proved false during investigation? -->
48
+ - [Hypothesis that turned out incorrect or infeasible]
49
+ </invalidated_hypotheses>
50
+
51
+ <reusable_assets>
52
+ <!-- Are there test cases, draft schemas, benchmarks, or prototypes that future tasks can reuse? -->
53
+ - [Reusable asset 1: test cases or data models in draft branch / commit]
54
+ </reusable_assets>
55
+ </preserved_knowledge>
56
+
57
+ ---
58
+
59
+ ## 3. Working Tree Reversal & Cleanup Checklist
60
+
61
+ <cleanup_checklist>
62
+ - [ ] Uncommitted changes rolled back or stashed cleanly (`git status` clean)
63
+ - [ ] Temporary debug logs, scratch scripts, or test dumps deleted
64
+ - [ ] No phantom migrations or schema artifacts left in local database
65
+ - [ ] Task folder archived to `completed/` (or `cancelled/`)
66
+ </cleanup_checklist>
67
+
68
+ ---
69
+
70
+ ## 4. Superseding Task or Follow-Up
71
+
72
+ <follow_up>
73
+ <superseded_by>[Link to new task folder or CHG-YYY, or NONE]</superseded_by>
74
+ <recommended_next_action>
75
+ [Specific recommendations if this problem is revisited in the future.]
76
+ </recommended_next_action>
77
+ </follow_up>
78
+
79
+ </cancellation_record>
package/templates/process/_seeds/results-template.tsv.seed ADDED
@@ -0,0 +1,5 @@
1
+ # Benchmark & Metric Evaluation Registry (RIPER-5 Framework)
2
+ # Instantiate as results.tsv in task workspace when tracking performance, latency, memory, or eval metrics.
3
+ iteration timestamp slice_id metric_name baseline observed unit diff_pct status notes
4
+ 0 2026-01-01T00:00:00Z baseline p99_latency_ms 100.0 100.0 ms 0.0% BASELINE Initial baseline measurement
5
+ 1 2026-01-01T01:00:00Z slice-01 p99_latency_ms 100.0 75.0 ms -25.0% PASS Optimization slice 1 applied
package/templates/process/_seeds/review-template.md.seed CHANGED
@@ -135,7 +135,8 @@
135
135
  ## Gate 3 — Review Passed
136
136
 
137
137
  <gate id="G3">
138
- - [ ] Full diff reviewed.
138
+ - [ ] Full diff reviewed (zero extraneous changes).
139
+ - [ ] Housekeeping complete: all transient debug logs, print statements, and scratch files removed.
139
140
  - [ ] All required evidence exists and is attached.
140
141
  - [ ] All findings triaged (Confirmed Defects resolved or risk-accepted).
141
142
  - [ ] Residual risk explicitly accepted.
package/templates/process/context/all-context.md CHANGED
@@ -29,6 +29,12 @@
29
29
  <scope>Scaffolding seeds for tasks, research, decisions, plans, state, reviews, handoffs, and programs. Full artifact chain and instantiation commands.</scope>
30
30
  </group>
31
31
 
32
+ <group id="tests">
33
+ <title>Testing Standards & Harness Strategy</title>
34
+ <path>[`tests/all-tests.md`](tests/all-tests.md)</path>
35
+ <scope>Test pyramid, unit/integration isolation policies, mock conventions, and test fixtures</scope>
36
+ </group>
37
+
32
38
  <group id="protocols">
33
39
  <title>Development Protocols Index</title>
34
40
  <path>[`../development-protocols/all-development-protocols.md`](../development-protocols/all-development-protocols.md)</path>
package/templates/process/context/tests/all-tests.md ADDED
@@ -0,0 +1,56 @@
1
+ # Testing Standards & Harness Strategy Context
2
+
3
+ <testing_context version="1.0">
4
+
5
+ <overview>
6
+ Guidelines for test pyramid calibration, isolation policies, mock conventions, and automated verification harness across the system.
7
+ </overview>
8
+
9
+ ## 1. Test Pyramid & Classification
10
+ <test_pyramid>
11
+ <layer name="Unit Tests" path="tests/unit/">
12
+ - Scope: Pure business logic, domain models, utility functions, edge case branching.
13
+ - Execution speed: Fast (< 50ms per test), zero network/disk/external I/O.
14
+ - Mock policy: Mock all I/O boundaries, external clients, and port interfaces.
15
+ </layer>
16
+
17
+ <layer name="Integration Tests" path="tests/integration/">
18
+ - Scope: Database persistence, external API client adapters, framework wiring.
19
+ - Isolation: Ephemeral test containers (e.g. Testcontainers) or dedicated isolated test database per suite.
20
+ - Teardown: Must guarantee zero state leakage across test runs.
21
+ </layer>
22
+
23
+ <layer name="End-to-End Tests" path="tests/e2e/">
24
+ - Scope: Critical user journeys, full HTTP/gRPC API lifecycle, regression smoke tests.
25
+ - Verification: Validates end-to-end contract integrity across subsystems.
26
+ </layer>
27
+ </test_pyramid>
28
+
29
+ ## 2. Test Harness Policies
30
+ <test_policies>
31
+ <policy name="Determinism">
32
+ Zero flaky tests. Tests must not depend on real wall-clock time (use frozen clocks or fake timers) or randomized execution order.
33
+ </policy>
34
+
35
+ <policy name="Clean State">
36
+ Every test must seed its own data or fixtures. Tests must never assume pre-existing database rows.
37
+ </policy>
38
+
39
+ <policy name="Assertion Precision">
40
+ Avoid vague assertions (e.g. `expect(res).toBeTruthy()`). Always assert exact expected structures, status codes, and error types.
41
+ </policy>
42
+
43
+ <policy name="Fast Feedback">
44
+ Unit tests must execute in under 30 seconds for the entire suite. Slow integration suites must be cleanly partitioned.
45
+ </policy>
46
+ </test_policies>
47
+
48
+ ## 3. Verification Commands Mapping
49
+ <verification_commands>
50
+ <!-- Keep aligned with AGENTS.md <validation_commands> -->
51
+ <command type="unit">Run fast unit test suite</command>
52
+ <command type="integration">Run integration/e2e tests</command>
53
+ <command type="coverage">Run test coverage check</command>
54
+ </verification_commands>
55
+
56
+ </testing_context>