@educa-corp/sdd-framework 0.2.3 → 0.2.5
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/commands/generate-architecture.md +706 -0
- package/commands/generate-architecture.tmpl +194 -0
- package/commands/generate-code.md +16 -2
- package/commands/generate-code.tmpl +16 -2
- package/commands/generate-tech-docs.md +19 -0
- package/commands/generate-tech-docs.tmpl +19 -0
- package/core/FRAMEWORK_VERSION +1 -1
- package/core/commands/generate-architecture.md +706 -0
- package/core/commands/generate-code.md +16 -2
- package/core/commands/generate-tech-docs.md +19 -0
- package/core/skills/setup-ai-first/SKILL.md +12 -4
- package/core/templates/architecture.template.md +392 -111
- package/docs/01-getting-started/installation.md +47 -112
- package/docs/01-getting-started/quickstart.md +58 -72
- package/docs/01-getting-started/what-is-sdd.md +75 -0
- package/docs/02-concepts/architecture.md +109 -0
- package/docs/02-concepts/glossary.md +87 -0
- package/docs/02-concepts/overview.md +93 -0
- package/docs/02-concepts/pipeline-steps/00-setup.md +102 -0
- package/docs/02-concepts/pipeline-steps/01-discovery.md +129 -0
- package/docs/02-concepts/pipeline-steps/02-specification.md +130 -0
- package/docs/02-concepts/pipeline-steps/03-design-spec.md +90 -0
- package/docs/02-concepts/pipeline-steps/04-bdd.md +120 -0
- package/docs/02-concepts/pipeline-steps/05-tech-docs.md +101 -0
- package/docs/02-concepts/pipeline-steps/06-code.md +119 -0
- package/docs/02-concepts/pipeline-steps/07-dev-selftest.md +92 -0
- package/docs/02-concepts/pipeline-steps/08-qc-automation.md +102 -0
- package/docs/02-concepts/pipeline-steps/09-validate-traces.md +104 -0
- package/docs/02-concepts/pipeline-steps/10-feedback-loop.md +105 -0
- package/docs/02-concepts/pipeline-steps/README.md +92 -0
- package/docs/02-concepts/roles-and-hitl.md +73 -0
- package/docs/02-concepts/traceability.md +94 -0
- package/docs/03-guides/architect.md +98 -0
- package/docs/03-guides/developer.md +76 -0
- package/docs/03-guides/product-owner.md +68 -0
- package/docs/03-guides/tester-qa.md +70 -0
- package/docs/04-reference/commands.md +105 -0
- package/docs/04-reference/configuration.md +94 -0
- package/docs/04-reference/model-selection.md +68 -0
- package/docs/04-reference/modules.md +74 -0
- package/docs/04-reference/trace-schema.md +93 -0
- package/docs/README.md +29 -40
- package/docs/explain/00-setup-ai-first.md +77 -0
- package/docs/explain/00b-generate-architecture.md +76 -0
- package/docs/explain/01-define-product.md +79 -0
- package/docs/explain/02-generate-prd.md +78 -0
- package/docs/explain/03-refine-prd.md +86 -0
- package/docs/explain/04-review-context.md +100 -0
- package/docs/explain/05-generate-design-spec.md +73 -0
- package/docs/explain/06-generate-bdd.md +77 -0
- package/docs/explain/07-generate-tech-docs.md +71 -0
- package/docs/explain/08-review-tech-docs.md +79 -0
- package/docs/explain/09-generate-code.md +78 -0
- package/docs/explain/10-review-code.md +70 -0
- package/docs/explain/11-map-testids.md +69 -0
- package/docs/explain/12-dev-gen-test.md +66 -0
- package/docs/explain/13-dev-run-test.md +69 -0
- package/docs/explain/14-dev-smoke-test.md +67 -0
- package/docs/explain/15-qc-analyze.md +68 -0
- package/docs/explain/16-qc-plan.md +61 -0
- package/docs/explain/17-qc-design-test.md +61 -0
- package/docs/explain/18-qc-review.md +59 -0
- package/docs/explain/19-qc-run-test.md +67 -0
- package/docs/explain/20-qc-report.md +61 -0
- package/docs/explain/21-validate-traces.md +68 -0
- package/docs/explain/22-generate-spec-manifest.md +60 -0
- package/docs/explain/23-fix-bug.md +69 -0
- package/docs/explain/24-debug.md +61 -0
- package/docs/explain/25-report-bug.md +65 -0
- package/docs/explain/26-propose-scenario.md +63 -0
- package/docs/explain/27-learn.md +65 -0
- package/docs/explain/28-sync.md +70 -0
- package/docs/explain/29-update-framework.md +65 -0
- package/docs/explain/README.md +134 -0
- package/package.json +1 -1
- package/skills/setup-ai-first/SKILL.md +12 -4
- package/skills/setup-ai-first/SKILL.tmpl +12 -4
- package/templates/architecture.template.md +392 -111
- package/docs/01-getting-started/README.md +0 -19
- package/docs/01-getting-started/core-concepts.md +0 -102
- package/docs/02-guides/README.md +0 -26
- package/docs/02-guides/bdd-input-checklist.md +0 -68
- package/docs/02-guides/developer/README.md +0 -49
- package/docs/02-guides/developer/bdd-and-trace.md +0 -126
- package/docs/02-guides/developer/commands.md +0 -76
- package/docs/02-guides/developer/pr-checklist.md +0 -16
- package/docs/02-guides/developer/scenarios.md +0 -460
- package/docs/02-guides/developer/workflow.md +0 -121
- package/docs/02-guides/prd-input-checklist.md +0 -94
- package/docs/02-guides/product-owner/README.md +0 -81
- package/docs/02-guides/product-owner/commands.md +0 -30
- package/docs/02-guides/product-owner/handoff-checklist.md +0 -42
- package/docs/02-guides/product-owner/prd-writing-rules.md +0 -45
- package/docs/02-guides/product-owner/scenarios.md +0 -438
- package/docs/02-guides/tech-docs-input-checklist.md +0 -109
- package/docs/02-guides/tester/README.md +0 -75
- package/docs/02-guides/tester/bug-reporting.md +0 -117
- package/docs/02-guides/tester/qc-automation.md +0 -165
- package/docs/02-guides/tester/reading-specs.md +0 -79
- package/docs/02-guides/tester/scenarios.md +0 -186
- package/docs/02-guides/tester/spec-manifest.md +0 -130
- package/docs/02-guides/tester/test-checklist.md +0 -31
- package/docs/02-guides/tester/workflow.md +0 -77
- package/docs/03-concepts/README.md +0 -20
- package/docs/03-concepts/architecture.md +0 -248
- package/docs/03-concepts/mechanisms-explained.md +0 -124
- package/docs/03-concepts/pipeline.md +0 -278
- package/docs/03-concepts/traceability.md +0 -152
- package/docs/04-operations/README.md +0 -33
- package/docs/04-operations/bug-flow.md +0 -364
- package/docs/04-operations/publishing.md +0 -154
- package/docs/04-operations/sync-and-update.md +0 -522
- package/docs/05-reference/README.md +0 -34
- package/docs/05-reference/command-cheatsheet.md +0 -147
- package/docs/05-reference/commands.md +0 -234
- package/docs/05-reference/model-selection.md +0 -74
- package/docs/05-reference/modules.md +0 -110
- package/docs/05-reference/trace-schema.md +0 -154
- package/docs/06-commands/README.md +0 -75
- package/docs/06-commands/explain-debug.md +0 -32
- package/docs/06-commands/explain-define-product.md +0 -43
- package/docs/06-commands/explain-dev-gen-test.md +0 -28
- package/docs/06-commands/explain-dev-run-test.md +0 -24
- package/docs/06-commands/explain-dev-smoke-test.md +0 -25
- package/docs/06-commands/explain-fix-bug.md +0 -28
- package/docs/06-commands/explain-generate-bdd.md +0 -45
- package/docs/06-commands/explain-generate-code.md +0 -53
- package/docs/06-commands/explain-generate-design-spec.md +0 -54
- package/docs/06-commands/explain-generate-prd.md +0 -45
- package/docs/06-commands/explain-generate-spec-manifest.md +0 -20
- package/docs/06-commands/explain-generate-tech-docs.md +0 -56
- package/docs/06-commands/explain-learn.md +0 -21
- package/docs/06-commands/explain-map-testids.md +0 -28
- package/docs/06-commands/explain-propose-scenario.md +0 -24
- package/docs/06-commands/explain-qc-analyze.md +0 -22
- package/docs/06-commands/explain-qc-design-test.md +0 -20
- package/docs/06-commands/explain-qc-plan.md +0 -21
- package/docs/06-commands/explain-qc-report.md +0 -23
- package/docs/06-commands/explain-qc-review.md +0 -24
- package/docs/06-commands/explain-qc-run-test.md +0 -27
- package/docs/06-commands/explain-refine-prd.md +0 -51
- package/docs/06-commands/explain-report-bug.md +0 -24
- package/docs/06-commands/explain-review-code.md +0 -45
- package/docs/06-commands/explain-review-context.md +0 -68
- package/docs/06-commands/explain-review-tech-docs.md +0 -45
- package/docs/06-commands/explain-setup-ai-first.md +0 -25
- package/docs/06-commands/explain-sync.md +0 -24
- package/docs/06-commands/explain-update-framework.md +0 -22
- package/docs/06-commands/explain-validate-traces.md +0 -25
- package/docs/t-sample.md +0 -826
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
[← /propose-scenario](26-propose-scenario.md) · [Explain Home](README.md) · [Next: /sync →](28-sync.md)
|
|
2
|
+
|
|
3
|
+
# 27 · `/learn` — Ghi một Project Lesson (Guardrail)
|
|
4
|
+
|
|
5
|
+
> **Một câu.** Biến một định hướng/lỗi lặp lại thành **guardrail** ghi vào `project-lessons.md` — nạp lại vào context mọi lệnh sau để không sai lại.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Vấn đề giải quyết
|
|
10
|
+
|
|
11
|
+
Định hướng lặp lại nằm trong đầu vài senior → AI sai lại. `/learn` biến nó thành **lesson dán tường** máy-đọc, được context-loader (Bước 6.7) nạp làm ràng buộc cứng ngang coding standards → hệ thống *nhớ* qua thời gian.
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## Vị trí & tiền đề
|
|
16
|
+
|
|
17
|
+
- **Vị trí:** xuyên suốt (cơ chế tự học). Cũng được gọi từ `/review-code`, `/fix-bug`, `/debug`.
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
## Input / Output
|
|
22
|
+
|
|
23
|
+
**Input:** mô tả lesson (Rule + ngữ cảnh) + `category` + `scope`.
|
|
24
|
+
|
|
25
|
+
**Output:** entry `L-NNN` trong `project-lessons.md`.
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
## Các bước xử lý (chi tiết)
|
|
30
|
+
|
|
31
|
+
1. **Step 1 · Parse Lesson** — tách Rule, category, scope từ input.
|
|
32
|
+
2. **Step 2 · Capture** (step `capture-lesson`):
|
|
33
|
+
- **L1** phân giải file lessons (theo `paths.lessons_file` / service override).
|
|
34
|
+
- **L2** dựng lesson (Rule + category + scope + ví dụ).
|
|
35
|
+
- **L3** khử trùng lặp (không ghi lesson đã có).
|
|
36
|
+
- **L4** ghi vào `project-lessons.md`.
|
|
37
|
+
- **L5** xác nhận.
|
|
38
|
+
|
|
39
|
+
---
|
|
40
|
+
|
|
41
|
+
## Checkpoint & Gate
|
|
42
|
+
|
|
43
|
+
- L5 xác nhận trước khi ghi.
|
|
44
|
+
|
|
45
|
+
---
|
|
46
|
+
|
|
47
|
+
## Cơ chế đặc biệt
|
|
48
|
+
|
|
49
|
+
- **Lesson là ràng buộc cứng** — context-loader Bước 6.7 nạp mọi lesson khớp `category`+`scope`; output vi phạm → AI sửa trước khi trình + ghi `L-NNN` đã áp.
|
|
50
|
+
- **Dùng chung `capture-lesson`** với `/review-code`, `/fix-bug`, `/debug` — lesson sinh tự nhiên từ chỗ phát hiện.
|
|
51
|
+
|
|
52
|
+
---
|
|
53
|
+
|
|
54
|
+
## 👓 Góc nhìn tối ưu
|
|
55
|
+
|
|
56
|
+
- **Bộ nhớ dự án cốt lõi** — nhưng phụ thuộc con người chủ động `/learn`. Lesson không ghi = không nhớ.
|
|
57
|
+
- **Dedup L3 phụ thuộc AI so khớp** — lesson gần giống có thể lọt thành trùng, phình file → tốn context mọi lệnh.
|
|
58
|
+
- **Scope/category filtering** quyết định lesson nào nạp — nếu gắn sai, guardrail không kích hoạt đúng lúc.
|
|
59
|
+
- **Không có cơ chế "retire" lesson lỗi thời** — file chỉ lớn dần. Đáng cân nhắc vòng đời lesson.
|
|
60
|
+
|
|
61
|
+
---
|
|
62
|
+
|
|
63
|
+
## Kết nối
|
|
64
|
+
|
|
65
|
+
**Trước:** [`/review-code`](10-review-code.md) / [`/fix-bug`](23-fix-bug.md) / phát hiện định hướng lặp · **Sau:** lesson áp dụng ở mọi lệnh kế tiếp.
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
[← /learn](27-learn.md) · [Explain Home](README.md) · [Next: /update-framework →](29-update-framework.md)
|
|
2
|
+
|
|
3
|
+
# 28 · `/sync` — Đồng bộ & làm mới umbrella
|
|
4
|
+
|
|
5
|
+
> **Một câu.** Lệnh vận hành hằng ngày cho umbrella: pull + init submodule + advance spec repo + **nổi feedback tester** + bootstrap config service + làm mới Living Docs & spec manifest. An toàn chạy lặp lại.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Vấn đề giải quyết
|
|
10
|
+
|
|
11
|
+
Umbrella nhiều submodule + một spec repo dùng chung dễ lệch nhau. `/sync` là "một lệnh lo mọi thứ": đồng bộ code/spec, nổi feedback, cập nhật dashboard — tự phát hiện cần làm gì.
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## Vị trí & tiền đề
|
|
16
|
+
|
|
17
|
+
- **Vị trí:** xuyên suốt (vận hành), chủ yếu **umbrella mode**.
|
|
18
|
+
- **Đặc biệt:** idempotent — chạy lặp an toàn.
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## Input / Output
|
|
23
|
+
|
|
24
|
+
**Input:** umbrella repo + submodule + `spec_source`.
|
|
25
|
+
|
|
26
|
+
**Output:** repo đồng bộ + service config bootstrap + Living Docs + spec-manifest làm mới + feedback nổi lên.
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## Các bước xử lý (chi tiết)
|
|
31
|
+
|
|
32
|
+
1. **Step 0 · Pre-flight Checks** — kiểm trạng thái submodule (entry `-` chưa clone).
|
|
33
|
+
2. **Step 1 · Umbrella Pull** — pull umbrella; sync `.gitmodules`; init **chỉ** submodule chưa clone (KHÔNG blanket `submodule update --recursive` để không detach submodule đang làm việc).
|
|
34
|
+
3. **Step 1b · Phân loại & Sync từng Submodule** — xử lý per-submodule (an toàn với cái đang active).
|
|
35
|
+
4. **Step 1c · Advance Spec Submodule** (nếu `spec_source`) — cập nhật spec repo dùng chung.
|
|
36
|
+
5. **Step 1d · Surface Feedback tester/QC** — nổi bug report / scenario proposal / PRD change request lên.
|
|
37
|
+
6. **Step 2 · Post-sync State Check.**
|
|
38
|
+
7. **Step 3 · Bootstrap Service Configs** — tự sinh `project-context.yaml` cho mỗi service (phát hiện module từ pom.xml/go.mod/package.json/pubspec.yaml).
|
|
39
|
+
8. **Step 4 · Check `.gitignore`.**
|
|
40
|
+
9. **Step 5 · Refresh Living Docs** (umbrella).
|
|
41
|
+
10. **Step 6 · Refresh Spec Manifest** (nếu `spec_source`).
|
|
42
|
+
|
|
43
|
+
---
|
|
44
|
+
|
|
45
|
+
## Checkpoint & Gate
|
|
46
|
+
|
|
47
|
+
- Không gate — idempotent, tự dò việc cần làm.
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## Cơ chế đặc biệt
|
|
52
|
+
|
|
53
|
+
- **Không blanket submodule update** — bảo vệ submodule đang chỉnh khỏi bị detach.
|
|
54
|
+
- **Bootstrap service config tự động** — phát hiện stack từ manifest file → giảm setup tay.
|
|
55
|
+
- **Nổi feedback** — khép vòng: feedback tester đi vào tầm nhìn PO/Dev.
|
|
56
|
+
|
|
57
|
+
---
|
|
58
|
+
|
|
59
|
+
## 👓 Góc nhìn tối ưu
|
|
60
|
+
|
|
61
|
+
- **Lệnh "lo mọi thứ"** — mạnh nhưng nhiều bước; khó chẩn khi một step lỗi. Đáng có chế độ verbose/dry-run.
|
|
62
|
+
- **Chỉ umbrella** — single-service không hưởng bootstrap/living-docs auto; các bước tương đương phải làm tay.
|
|
63
|
+
- **Chạy hằng ngày phụ thuộc kỷ luật** — feedback/Living Docs chỉ tươi nếu sync đều.
|
|
64
|
+
- **Phát hiện module từ manifest file** — stack lạ (không pom/go.mod/package.json/pubspec) không auto-detect được.
|
|
65
|
+
|
|
66
|
+
---
|
|
67
|
+
|
|
68
|
+
## Kết nối
|
|
69
|
+
|
|
70
|
+
**Trước:** bất kỳ (vận hành) · **Sau:** [`/validate-traces`](21-validate-traces.md); xử lý `📥 tester feedback` nổi lên → [`/fix-bug`](23-fix-bug.md)/[`/generate-bdd`](06-generate-bdd.md).
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
[← /sync](28-sync.md) · [Explain Home](README.md)
|
|
2
|
+
|
|
3
|
+
# 29 · `/update-framework` — Nâng cấp bản framework (npm)
|
|
4
|
+
|
|
5
|
+
> **Một câu.** Sync bản npm mới của framework — **ghi đè** file framework (`.agent/commands|steps|hooks|rules|templates|skills|modules`) nhưng **giữ nguyên** nội dung của bạn (`CLAUDE.md`, `project-context.yaml`, `domain-knowledge/`, `.trace/`).
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Vấn đề giải quyết
|
|
10
|
+
|
|
11
|
+
Framework tiến hoá qua npm. Command nâng cấp an toàn: cập nhật cơ chế mới mà **không đụng** cấu hình/tri thức dự án — tách rõ "code framework" vs "nội dung của bạn".
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## Vị trí & tiền đề
|
|
16
|
+
|
|
17
|
+
- **Vị trí:** xuyên suốt (vận hành).
|
|
18
|
+
- **Tiền đề:** Node.js; git sạch (pre-flight check).
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## Input / Output
|
|
23
|
+
|
|
24
|
+
**Input:** bản npm mới `@educa-corp/sdd-framework`.
|
|
25
|
+
|
|
26
|
+
**Output:** `.agent/*` cập nhật; `git diff .agent/` để review + commit.
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## Các bước xử lý (chi tiết)
|
|
31
|
+
|
|
32
|
+
1. **Step 0 · Phát hiện trạng thái hiện tại** — version đang dùng, mode.
|
|
33
|
+
2. **Step 1 · Kiểm tra version mới nhất** — `npm view … version`.
|
|
34
|
+
3. **Step 2 · Umbrella Awareness** (umbrella) — lưu ý nhiều submodule.
|
|
35
|
+
4. **Step 3 · Pre-flight Git Check** — đảm bảo working tree sạch trước khi ghi đè.
|
|
36
|
+
5. **Step 4 · Chạy nâng cấp** — ghi đè file framework; **KHÔNG** đụng `CLAUDE.md`, `project-context.yaml`, `domain-knowledge/`, `.trace/`.
|
|
37
|
+
6. **Step 5 · Review Changes** — `git diff .agent/` để người xem trước khi commit.
|
|
38
|
+
|
|
39
|
+
---
|
|
40
|
+
|
|
41
|
+
## Checkpoint & Gate
|
|
42
|
+
|
|
43
|
+
- Pre-flight git check (working tree sạch).
|
|
44
|
+
- Review diff trước commit.
|
|
45
|
+
|
|
46
|
+
---
|
|
47
|
+
|
|
48
|
+
## Cơ chế đặc biệt
|
|
49
|
+
|
|
50
|
+
- **Ranh giới ghi đè rõ** — framework file bị thay, nội dung dự án được giữ. Đây là điều khiến nâng cấp an toàn.
|
|
51
|
+
- **Review diff bắt buộc** — người xác nhận thay đổi framework trước khi commit.
|
|
52
|
+
|
|
53
|
+
---
|
|
54
|
+
|
|
55
|
+
## 👓 Góc nhìn tối ưu
|
|
56
|
+
|
|
57
|
+
- **Ranh giới "giữ vs ghi đè"** là sống còn — nếu người dùng lỡ sửa tay `.agent/commands/*.md` (thay vì `.tmpl`), thay đổi mất khi update. Quy ước này phụ thuộc kỷ luật + memory, không có hook chặn.
|
|
58
|
+
- **Pre-flight git sạch** ngăn mất chỉnh chưa commit — tốt, nhưng có thể chặn người quen làm việc với tree bẩn.
|
|
59
|
+
- **Sau update → `/sync`** để lan nội dung — chuỗi phụ thuộc người chạy tiếp.
|
|
60
|
+
|
|
61
|
+
---
|
|
62
|
+
|
|
63
|
+
## Kết nối
|
|
64
|
+
|
|
65
|
+
**Trước:** bất kỳ (vận hành) · **Sau:** review `git diff .agent/` + commit; [`/sync`](28-sync.md) để đồng bộ nội dung dự án.
|
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
# 🔬 Explain — Giải phẫu từng command (Command Deep-Dive)
|
|
2
|
+
|
|
3
|
+
> Tài liệu **đi sâu vào bên trong** từng command của pipeline, theo đúng thứ tự thực thi. Mục tiêu: làm **cơ sở review, phân tích và tối ưu** các bước trong pipeline.
|
|
4
|
+
>
|
|
5
|
+
> Khác với [Pipeline Steps](../02-concepts/pipeline-steps/) (tầng khái niệm, gom theo phase), thư mục này bám **logic thực tế trong command file** (`commands/*.md`) — từng bước command làm gì, giải quyết vấn đề gì, và **điểm nào đáng cân nhắc tối ưu**.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Cách đọc (How to read)
|
|
10
|
+
|
|
11
|
+
Mỗi trang command theo cùng một khuôn:
|
|
12
|
+
|
|
13
|
+
| Mục | Nội dung |
|
|
14
|
+
|-----|----------|
|
|
15
|
+
| **Một câu** | Command làm gì |
|
|
16
|
+
| **Vấn đề giải quyết** | Tại sao command này tồn tại |
|
|
17
|
+
| **Vị trí & tiền đề** | Chạy sau gì, cần gì mở khoá |
|
|
18
|
+
| **Input / Output** | Đầu vào & sản phẩm cụ thể |
|
|
19
|
+
| **Các bước xử lý** | ⭐ Đi từng bước bên trong, dễ hiểu |
|
|
20
|
+
| **Checkpoint & Gate** | Điểm dừng con người |
|
|
21
|
+
| **Cơ chế đặc biệt** | Phần logic riêng đáng chú ý |
|
|
22
|
+
| **👓 Góc nhìn tối ưu** | Điểm review/optimize: chi phí, rủi ro, phụ thuộc |
|
|
23
|
+
| **Kết nối** | Bước trước ← → bước sau |
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## ⭐ Bộ khung chung mọi command (Shared Skeleton)
|
|
28
|
+
|
|
29
|
+
**Đọc phần này trước.** Mọi command file được build từ `.tmpl` + `{{include:steps/*.md}}`, nên đều có **cùng một bộ khung** bao quanh logic riêng. Hiểu bộ khung một lần → các trang command chỉ cần nói phần **riêng**.
|
|
30
|
+
|
|
31
|
+
Cấu trúc một command file:
|
|
32
|
+
|
|
33
|
+
```
|
|
34
|
+
┌─ Gate (steps/gate) ──────────── chung, giống hệt mọi lệnh
|
|
35
|
+
├─ Context Loader (steps/context-loader) ── chung, 7 bước
|
|
36
|
+
├─ Business Language Guard (steps/business-language) ── chung, chỉ lệnh viết doc nghiệp vụ
|
|
37
|
+
├─ ★ LOGIC RIÊNG CỦA LỆNH ★ ──── phần mỗi trang explain tập trung
|
|
38
|
+
└─ Report Footer (steps/report-footer) ── chung
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
### 1 · Gate — Cổng vào chuẩn (5 bước con)
|
|
42
|
+
|
|
43
|
+
Chạy **trước** mọi logic riêng:
|
|
44
|
+
|
|
45
|
+
| Bước | Tên | Việc | Ý nghĩa tối ưu |
|
|
46
|
+
|------|-----|------|----------------|
|
|
47
|
+
| 0 | **Sub-agent mode** | Nếu `$ARGUMENTS` là JSON có `_agent_mode` → bỏ Gate 1/2/3, chạy đúng phạm vi orchestrator giao (target_file, uc_id, uc_section, dimension) | Cơ chế fan-out per-UC dùng chính lệnh này làm "worker" |
|
|
48
|
+
| 0-B | **Model check** | Khuyến nghị Opus. `Y`=tiếp · `S`=bỏ qua (⚠️ report) · khác=DỪNG | Checkpoint mềm; sub-agent bỏ qua (orchestrator đã check) |
|
|
49
|
+
| 1 | **Target file** | Phân giải file mục tiêu từ path / UC-ID / ticket bằng glob theo bố cục feature-package; nhiều kết quả → hỏi | Điểm hay tốn 1 vòng hỏi khi `$ARGUMENTS` rỗng |
|
|
50
|
+
| 2 | **Context loader** | Chạy 7 bước nạp context (mục 2 dưới) | Nơi quyết định "đúng-đủ-gọn" — trọng tâm tối ưu |
|
|
51
|
+
| 3 | **CHECKPOINT** | Trình target + scope → chờ `Y` | Read-only command bỏ qua |
|
|
52
|
+
|
|
53
|
+
### 2 · Context Loader — "Thủ thư" (7 bước)
|
|
54
|
+
|
|
55
|
+
Nạp context theo thứ tự chống Lost-in-the-Middle (đầu = "build gì", giữa = ràng buộc, cuối = "follow style này"):
|
|
56
|
+
|
|
57
|
+
| Bước | Nạp gì | Ghi chú |
|
|
58
|
+
|------|--------|---------|
|
|
59
|
+
| 1 | **project-context.yaml** | tech_stack, conventions, domains, paths; trích `domain`/`prd_slug` từ path target |
|
|
60
|
+
| 1.5 | **Service routing** (umbrella) | Khớp domain → service; dạng phẳng (2a) hay map-theo-platform (2b); override paths sang `spec_source` |
|
|
61
|
+
| 1.6 | **Service conventions** (umbrella) | Nạp `build_command`/`test_command` riêng của service; set `service_root` |
|
|
62
|
+
| 2 | **Module stack-profile** | `.agent/modules/{module}/stack-profile.yaml` — layer/test pattern |
|
|
63
|
+
| 3 | **CLAUDE.md phân tầng** | root (BASE) + service overlay (stack) — **overlay thắng**; §2 layer/package, §3 naming, §5 error |
|
|
64
|
+
| 4 | **data-protection** | Pattern file nhạy cảm — cấm truy cập cả phiên |
|
|
65
|
+
| 5 | **Business dictionary** | Canonical + **banned terms** (thực thi chủ động) + enum registry |
|
|
66
|
+
| 6 | **Core entities** | Entity catalog + field registry + relationship map |
|
|
67
|
+
| 6.5 | **platform_type** | Suy `backend`/`web-frontend`/`mobile` từ module |
|
|
68
|
+
| 6.7 | **Project lessons** | Guardrail từ `/learn` — ràng buộc cứng ngang coding standards |
|
|
69
|
+
| 7 | **Recap** | In khối `[CTX LOADED]` — đẩy sự thật quan trọng lên cuối bộ nhớ |
|
|
70
|
+
|
|
71
|
+
> 👓 **Đây là component quyết định 80% chất lượng.** Khi review tối ưu: chú ý `required` vs `optional`, filter theo domain, và budget context (~50% window).
|
|
72
|
+
|
|
73
|
+
### 3 · Business Language Guard (chỉ lệnh viết doc nghiệp vụ)
|
|
74
|
+
|
|
75
|
+
Chặn thuật ngữ kỹ thuật rò vào PRD/BDD/product-definition. 4 nhóm xử lý: (1) tương tác/UI → diễn đạt lại nghiệp vụ · (2) visual thuần → chuyển Design Spec · (3) backend/contract → bỏ về Tech Docs · (4) ẩn dụ dữ liệu → xét ngữ cảnh (không thay máy móc). Áp cho `/define-product`, `/generate-prd`, `/refine-prd`, `/review-context`, `/generate-bdd`.
|
|
76
|
+
|
|
77
|
+
### 4 · Report Footer (mọi lệnh)
|
|
78
|
+
|
|
79
|
+
Kết thúc bằng: **Status badge** (✅/❌/⚠️) · **Output Artifacts** (file tạo/sửa) · **Pipeline Position** (`◀ bạn ở đây`) · **Next command** (gợi ý lệnh kế + tham số).
|
|
80
|
+
|
|
81
|
+
---
|
|
82
|
+
|
|
83
|
+
## Danh sách command theo thứ tự pipeline (Pipeline Order)
|
|
84
|
+
|
|
85
|
+
### Phase Setup & Discovery
|
|
86
|
+
- [00 · `/setup-ai-first`](00-setup-ai-first.md)
|
|
87
|
+
- [00b · `/generate-architecture`](00b-generate-architecture.md)
|
|
88
|
+
- [01 · `/define-product`](01-define-product.md)
|
|
89
|
+
|
|
90
|
+
### Phase Specification (PRD)
|
|
91
|
+
- [02 · `/generate-prd`](02-generate-prd.md)
|
|
92
|
+
- [03 · `/refine-prd`](03-refine-prd.md)
|
|
93
|
+
- [04 · `/review-context`](04-review-context.md) *(dùng cho cả PRD & BDD)*
|
|
94
|
+
|
|
95
|
+
### Phase Design
|
|
96
|
+
- [05 · `/generate-design-spec`](05-generate-design-spec.md)
|
|
97
|
+
- [06 · `/generate-bdd`](06-generate-bdd.md)
|
|
98
|
+
- [07 · `/generate-tech-docs`](07-generate-tech-docs.md)
|
|
99
|
+
- [08 · `/review-tech-docs`](08-review-tech-docs.md)
|
|
100
|
+
|
|
101
|
+
### Phase Implementation
|
|
102
|
+
- [09 · `/generate-code`](09-generate-code.md)
|
|
103
|
+
- [10 · `/review-code`](10-review-code.md)
|
|
104
|
+
- [11 · `/map-testids`](11-map-testids.md)
|
|
105
|
+
|
|
106
|
+
### Phase Dev Self-Test
|
|
107
|
+
- [12 · `/dev-gen-test`](12-dev-gen-test.md)
|
|
108
|
+
- [13 · `/dev-run-test`](13-dev-run-test.md)
|
|
109
|
+
- [14 · `/dev-smoke-test`](14-dev-smoke-test.md)
|
|
110
|
+
|
|
111
|
+
### Phase QC Automation
|
|
112
|
+
- [15 · `/qc-analyze`](15-qc-analyze.md)
|
|
113
|
+
- [16 · `/qc-plan`](16-qc-plan.md)
|
|
114
|
+
- [17 · `/qc-design-test`](17-qc-design-test.md)
|
|
115
|
+
- [18 · `/qc-review`](18-qc-review.md)
|
|
116
|
+
- [19 · `/qc-run-test`](19-qc-run-test.md)
|
|
117
|
+
- [20 · `/qc-report`](20-qc-report.md)
|
|
118
|
+
|
|
119
|
+
### Phase Trace & Quality
|
|
120
|
+
- [21 · `/validate-traces`](21-validate-traces.md)
|
|
121
|
+
- [22 · `/generate-spec-manifest`](22-generate-spec-manifest.md)
|
|
122
|
+
|
|
123
|
+
### Lệnh xuyên suốt (Cross-cutting)
|
|
124
|
+
- [23 · `/fix-bug`](23-fix-bug.md)
|
|
125
|
+
- [24 · `/debug`](24-debug.md)
|
|
126
|
+
- [25 · `/report-bug`](25-report-bug.md)
|
|
127
|
+
- [26 · `/propose-scenario`](26-propose-scenario.md)
|
|
128
|
+
- [27 · `/learn`](27-learn.md)
|
|
129
|
+
- [28 · `/sync`](28-sync.md)
|
|
130
|
+
- [29 · `/update-framework`](29-update-framework.md)
|
|
131
|
+
|
|
132
|
+
---
|
|
133
|
+
|
|
134
|
+
*Nguồn: `commands/*.md` (build từ `.tmpl` + `steps/`). Khi command đổi, cập nhật trang tương ứng ở đây.*
|
package/package.json
CHANGED
|
@@ -1,11 +1,19 @@
|
|
|
1
1
|
---
|
|
2
|
-
description: Cài đặt framework Spec-Driven Development
|
|
2
|
+
description: Cài đặt framework Spec-Driven Development, và sinh/làm mới tài liệu kiến trúc (architecture.md SSOT). Trigger when: "/setup-ai-first", "/generate-architecture", "setup spec-driven workflow", "initialize ai-first framework", "cài đặt framework", "khởi tạo spec-driven", "set up this workflow", "how do I start using this framework", "sinh architecture", "tạo tài liệu kiến trúc", "generate architecture doc", "refresh architecture", "scan codebase architecture".
|
|
3
3
|
---
|
|
4
4
|
|
|
5
|
-
# /setup-ai-first —
|
|
5
|
+
# /setup-ai-first · /generate-architecture — Foundation Skills (SA / Tech Lead)
|
|
6
6
|
|
|
7
|
-
Skill này xử lý `/setup-ai-first`. Để **không lệch** (umbrella/services routing, cấu trúc), skill KHÔNG nhân bản — thực thi **y hệt** command.
|
|
7
|
+
Skill này xử lý `/setup-ai-first` và `/generate-architecture`. Để **không lệch** (umbrella/services routing, cấu trúc, trust-gate), skill KHÔNG nhân bản — mỗi lệnh thực thi **y hệt** command tương ứng.
|
|
8
|
+
|
|
9
|
+
## /setup-ai-first — Initialize SDD Framework in a Project
|
|
8
10
|
|
|
9
11
|
→ **Đọc và tuân theo `commands/setup-ai-first.md`** với cùng `$ARGUMENTS`.
|
|
10
12
|
|
|
11
|
-
Command lo: tạo cấu trúc thư mục + feature-package on demand · CLAUDE.md + `.agent/project-context.yaml` (gồm umbrella `services` routing) · nhắc PO đặt row `Domain` (bảng Metadata) khớp services config · verify môi trường.
|
|
13
|
+
Command lo: tạo cấu trúc thư mục + feature-package on demand · CLAUDE.md + `.agent/project-context.yaml` (gồm umbrella `services` routing) · seed `architecture.md` (Step 3.5) · nhắc PO đặt row `Domain` (bảng Metadata) khớp services config · verify môi trường.
|
|
14
|
+
|
|
15
|
+
## /generate-architecture — Sinh / làm mới Architecture Context (SSOT)
|
|
16
|
+
|
|
17
|
+
→ **Đọc và tuân theo `commands/generate-architecture.md`** với cùng `$ARGUMENTS`.
|
|
18
|
+
|
|
19
|
+
Command lo: phân giải target (single-service / per-service umbrella) · phát hiện greenfield vs brownfield · **scan codebase** (build-file/DI/middleware/config/CI) → draft từng section kèm bằng chứng · xoá section [OPTIONAL] không dùng · **trust-gate** `verified_by: AI-draft` · refresh có kiểm soát (không đè bản người đã verify) · bàn giao cho người verify.
|
|
@@ -1,11 +1,19 @@
|
|
|
1
1
|
---
|
|
2
|
-
description: Cài đặt framework Spec-Driven Development
|
|
2
|
+
description: Cài đặt framework Spec-Driven Development, và sinh/làm mới tài liệu kiến trúc (architecture.md SSOT). Trigger when: "/setup-ai-first", "/generate-architecture", "setup spec-driven workflow", "initialize ai-first framework", "cài đặt framework", "khởi tạo spec-driven", "set up this workflow", "how do I start using this framework", "sinh architecture", "tạo tài liệu kiến trúc", "generate architecture doc", "refresh architecture", "scan codebase architecture".
|
|
3
3
|
---
|
|
4
4
|
|
|
5
|
-
# /setup-ai-first —
|
|
5
|
+
# /setup-ai-first · /generate-architecture — Foundation Skills (SA / Tech Lead)
|
|
6
6
|
|
|
7
|
-
Skill này xử lý `/setup-ai-first`. Để **không lệch** (umbrella/services routing, cấu trúc), skill KHÔNG nhân bản — thực thi **y hệt** command.
|
|
7
|
+
Skill này xử lý `/setup-ai-first` và `/generate-architecture`. Để **không lệch** (umbrella/services routing, cấu trúc, trust-gate), skill KHÔNG nhân bản — mỗi lệnh thực thi **y hệt** command tương ứng.
|
|
8
|
+
|
|
9
|
+
## /setup-ai-first — Initialize SDD Framework in a Project
|
|
8
10
|
|
|
9
11
|
→ **Đọc và tuân theo `commands/setup-ai-first.md`** với cùng `$ARGUMENTS`.
|
|
10
12
|
|
|
11
|
-
Command lo: tạo cấu trúc thư mục + feature-package on demand · CLAUDE.md + `.agent/project-context.yaml` (gồm umbrella `services` routing) · nhắc PO đặt row `Domain` (bảng Metadata) khớp services config · verify môi trường.
|
|
13
|
+
Command lo: tạo cấu trúc thư mục + feature-package on demand · CLAUDE.md + `.agent/project-context.yaml` (gồm umbrella `services` routing) · seed `architecture.md` (Step 3.5) · nhắc PO đặt row `Domain` (bảng Metadata) khớp services config · verify môi trường.
|
|
14
|
+
|
|
15
|
+
## /generate-architecture — Sinh / làm mới Architecture Context (SSOT)
|
|
16
|
+
|
|
17
|
+
→ **Đọc và tuân theo `commands/generate-architecture.md`** với cùng `$ARGUMENTS`.
|
|
18
|
+
|
|
19
|
+
Command lo: phân giải target (single-service / per-service umbrella) · phát hiện greenfield vs brownfield · **scan codebase** (build-file/DI/middleware/config/CI) → draft từng section kèm bằng chứng · xoá section [OPTIONAL] không dùng · **trust-gate** `verified_by: AI-draft` · refresh có kiểm soát (không đè bản người đã verify) · bàn giao cho người verify.
|