@edupia-tutor/spec-driven-docs 0.14.6 → 0.14.8

package/core/skills/setup-ai-first/SKILL.md

@@ -4,213 +4,8 @@ description: Cài đặt framework Spec-Driven Development trong bất kỳ back
 
 # /setup-ai-first — Initialize Spec-Driven Docs in a Project
 
-Dẫn người dùng qua một setup một-lần tạo mọi thư mục cần thiết, cài CLAUDE.md, và verify môi trường.
+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.
 
-## Precondition Check
-
-Trước tiên, hỏi: "Bạn đang ở project nào? Cho tôi đường dẫn root của project."
-
-Kiểm tra đã setup chưa:
-- Nếu `.claude/commands/` tồn tại với file `.md` → báo "Đã setup. Chạy `/validate-traces` để kiểm tra trạng thái."
-- Nếu `specs/` tồn tại → đề nghị re-initialize hoặc skip
-
-## Step 1 — Tạo cấu trúc thư mục
-
-Tạo các thư mục sau (skip nếu đã tồn tại):
-
-```
-{project-root}/
-├── specs/
-│   ├── product-definition/   # Output of /define-product
-│   └── domain-knowledge/     # Business dictionary + core entities
-├── .trace/                   # Traceability state (.trace/{domain}/{prd-slug}/{UC-ID}.tsv)
-└── .agent/
-    └── review/               # Output of /refine-prd ({prd-slug}-findings.yaml)
-```
-
-**Bố cục feature-package** — artifact theo từng feature KHÔNG được tạo trước ở đây; mỗi lệnh
-tự tạo folder của nó on demand dưới `specs/{domain}/{prd-slug}/`:
-
-```
-specs/{domain}/{prd-slug}/
-├── {TICKET-ID}-{prd-slug}.md # /generate-prd  (vd SEG01-segment-scoring-service.md)
-├── bdd/                      # /generate-bdd (file .feature)
-├── tech-docs/                # /generate-tech-docs
-└── design-spec/              # /generate-design-spec (chỉ FE/App)
-```
-
-Report mỗi thư mục được tạo hoặc đã tồn tại.
-
-## Step 2 — Copy Slash Commands
-
-Nói với người dùng:
-
-> "Framework này đã cài slash commands vào Claude tự động qua skill system.
-> Nếu bạn muốn dùng commands trực tiếp trong Claude Code project (`.claude/commands/`), chạy lệnh sau:"
-
-```bash
-# Copy all commands from plugin to project
-mkdir -p {project-root}/.claude/commands
-cp {plugin-dir}/commands/*.md {project-root}/.claude/commands/
-```
-
-Lưu ý: Bản copy `.claude/commands/` là tuỳ chọn. Skill trong framework này hoạt động không cần chúng.
-
-## Step 3 — Tạo CLAUDE.md
-
-Kiểm tra `{project-root}/CLAUDE.md` tồn tại chưa:
-- Nếu có: hỏi "CLAUDE.md đã tồn tại. Merge template vào hay bỏ qua?"
-- Nếu không: tạo từ template trong `templates/architecture.template.md`
-
-Sau khi tạo, hướng dẫn:
-> "Mở CLAUDE.md và điền vào các placeholder `{{...}}` với thông tin dự án của bạn.
-> Đặc biệt quan trọng: §1 (project overview) và §3 (coding standards)."
-
-## Step 4 — Tạo project-context.yaml
-
-Tạo `{project-root}/.agent/project-context.yaml`:
-
-```yaml
-# Project context for AI-First workflow
-# Fill in all fields before starting
-
-project:
-  name: "{{PROJECT_NAME}}"
-  description: "{{ONE_LINE_DESCRIPTION}}"
-
-tech_stack:
-  language: "{{LANGUAGE}}"           # e.g. Java 21, Python 3.12, Node.js 20
-  framework: "{{FRAMEWORK}}"         # e.g. Spring Boot 3.x, FastAPI, NestJS
-  build_tool: "{{BUILD_TOOL}}"       # e.g. Gradle, Maven, npm
-  test_framework: "{{TEST_FW}}"      # e.g. JUnit 5, pytest, Jest
-  orm: "{{ORM}}"                     # e.g. Hibernate/JPA, SQLAlchemy, Prisma
-  database: "{{DATABASE}}"           # e.g. PostgreSQL, MySQL, MongoDB
-
-conventions:
-  build_command: "{{BUILD_COMMAND}}"   # e.g. ./gradlew build -x test
-  test_command: "{{TEST_COMMAND}}"     # e.g. ./gradlew test
-  service_run: "{{RUN_COMMAND}}"       # e.g. ./gradlew bootRun
-  ticket_prefix: "{{TICKET_PREFIX}}"  # e.g. PROJ, FEAT, PD
-
-domains: []  # List your business domains, e.g. [rental, payment, user]
-```
-
-## Step 5 — Verify Setup
-
-Chạy check nhanh:
-- [ ] Thư mục `specs/` tồn tại
-- [ ] Thư mục `.trace/` tồn tại
-- [ ] `.agent/project-context.yaml` tồn tại
-- [ ] `CLAUDE.md` tồn tại
-
-Report:
-```
-/setup-ai-first Complete ✅
-
-Directories created: {N}
-Files created:
-  ✅ CLAUDE.md (needs customization)
-  ✅ .agent/project-context.yaml (needs customization)
-```
-
-# Report Footer — Định dạng output chuẩn cho mọi lệnh
-
-Mọi report của lệnh phải kết thúc bằng section footer chuẩn này.
-
-## Status Badge
-
-Chọn một theo kết quả:
-- `✅ Complete` — mọi bước thành công, không có vấn đề
-- `❌ Failed` — lệnh không hoàn thành được do lỗi chặn
-- `⚠️ Warnings` — hoàn thành nhưng có vấn đề không chặn, nên review lại
-
-## Output Artifacts
-
-Liệt kê mọi file được tạo hoặc sửa bởi lệnh này:
-```
-Output Artifacts:
-  {created|updated} {file-path} ({mô tả ngắn})
-  {created|updated} {file-path} ({mô tả ngắn})
-```
-
-Nếu không ghi file nào (vd: lệnh review hoặc phân tích) → ghi `Output Artifacts: none (read-only)`.
-
-## Pipeline Position
-
-In một sơ đồ pipeline một dòng, đánh dấu phase của lệnh HIỆN TẠI bằng `◀ bạn ở đây`,
-để người dùng luôn thấy lệnh này nằm ở đâu trong luồng end-to-end:
-
-```
-Discovery → PRD → [Design Spec] → BDD → Tech Design → Code → Dev Self-Check → QC → Trace Audit
-```
-
-Tìm lệnh hiện tại trong bảng phase dưới đây và đánh dấu **phase của nó** trong sơ đồ trên:
-
-| Phase | Commands |
-|-------|----------|
-| Discovery | `/define-product` |
-| PRD | `/generate-prd` · `/refine-prd` · `/review-context` (PRD) |
-| Design Spec | `/generate-design-spec` |
-| BDD | `/generate-bdd` · `/review-context` (BDD) |
-| Tech Design | `/generate-tech-docs` · `/map-testids` · `/review-tech-docs` |
-| Code | `/generate-code` · `/review-code` |
-| Dev Self-Check | `/dev-gen-test` · `/dev-run-test` · `/dev-smoke-test` |
-| QC | `/qc-analyze` · `/qc-plan` · `/qc-design-test` · `/qc-review` · `/qc-run-test` · `/qc-report` |
-| Trace Audit | `/validate-traces` |
-
-Với **lệnh review**, thêm vòng review 3 bước và đánh dấu bước hiện tại, vd:
-`Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume`.
-
-**Lệnh xuyên suốt** (`/sync`, `/update-framework`, `/fix-bug`, `/debug`, `/learn`,
-`/report-bug`, `/propose-scenario`, `/generate-spec-manifest`) nằm ngoài pipeline tuyến tính —
-**bỏ hẳn dòng Pipeline** cho các lệnh này (đừng cố nhét chúng vào sơ đồ).
-
-## Gợi ý lệnh tiếp theo
-
-Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
-
-| Lệnh hiện tại           | Gợi ý lệnh tiếp theo                          |
-|-------------------------|-----------------------------------------------|
-| /setup-ai-first         | `/define-product` để bắt đầu feature đầu tiên |
-| /define-product         | `/generate-prd {product-definition-file}`     |
-| /generate-prd           | `/refine-prd {prd-file}` rồi `/review-context {prd-file}` |
-| /refine-prd             | Mở Review Board → cập nhật PRD → `/review-context {prd-file}` |
-| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (rồi BDD sau khi sign-off); BE: `/generate-bdd {prd-file}` trực tiếp; sửa PRD nếu NEEDS_FIX |
-| /generate-design-spec   | Designer review → xác nhận link Figma → PO + Designer sign-off → `/generate-bdd {prd-file}` |
-| /generate-bdd           | `/review-context {feature-file}` để kiểm tra độ phủ |
-| /review-context (BDD)   | `/generate-tech-docs {UC-ID}` nếu APPROVED; sinh lại nếu NEEDS_FIX |
-| /qc-analyze             | `/qc-plan {UC-ID}` (xử lý các gap blocker 🔴 trước) |
-| /qc-plan                | `/qc-design-test {UC-ID}`                     |
-| /qc-design-test         | `/qc-review {UC-ID}` (review test-case)       |
-| /qc-review (test-case)  | `/qc-run-test {UC-ID}` nếu APPROVED; sửa TC nếu NEEDS_FIX |
-| /qc-run-test            | `/qc-report {UC-ID}` rồi `/qc-review {UC-ID}` (review script) |
-| /qc-review (script)     | `/qc-report {UC-ID}` rồi tạo PR nếu APPROVED |
-| /qc-report              | `/validate-traces {UC-ID}` để làm mới Living Docs (qc_status) |
-| /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
-| /review-tech-docs       | `/generate-code {feature-file}` nếu APPROVED; sửa doc nếu NEEDS_FIX |
-| /generate-code          | Lần gen đầu → `/review-code {UC-ID}`; gen lại → `/dev-gen-test {UC-ID}` |
-| /dev-gen-test         | `/dev-run-test {UC-ID}`                          |
-| /dev-run-test (passing)    | `/review-code {UC-ID}`                        |
-| /dev-run-test (failing)    | `/fix-bug {ticket-id}` hoặc `/debug {error}`    |
-| /review-code            | `/dev-smoke-test {UC-ID}` hoặc tạo PR            |
-| /dev-smoke-test             | Tạo PR và link tới ticket                  |
-| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/dev-gen-test {UC-ID}`; tất cả OK → tạo PR |
-| /fix-bug                | Tạo PR và link tới ticket                  |
-| /debug                  | `/fix-bug {ticket-id}` nếu cần sửa          |
-| /report-bug             | Gửi cho dev (`/fix-bug {BUG-ID}`); nếu thiếu coverage → `/propose-scenario {UC-ID}` |
-| /propose-scenario       | Báo PO/Dev review proposal trong `feedback/bdd-proposals/` |
-| /learn                  | Tiếp tục làm việc — lesson áp dụng ở lệnh kế tiếp |
-| /sync                   | `/validate-traces` để xem độ phủ đầy đủ; xử lý mọi `📥 tester feedback` được nêu |
-| /update-framework       | Review `git diff .agent/`, commit; `/sync` để đồng bộ nội dung dự án |
-
-Định dạng footer như sau:
-```
----
-Status   : {badge}
-{khối Output Artifacts}
-Pipeline : Discovery → PRD → [BDD ◀ bạn ở đây] → Tech Design → Code → Dev Self-Check → QC → Trace Audit
-           (lệnh review) Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume
-Next     : {lệnh gợi ý kèm ví dụ tham số}
-```
-*(Bỏ dòng `Pipeline` cho các lệnh xuyên suốt liệt kê ở trên.)*
+→ **Đọc và tuân theo `commands/setup-ai-first.md`** với cùng `$ARGUMENTS`.
 
+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.