git:20260830.f1da03f to git:20260831.c10e62e

- **Output language:** All output mirrors the language of the invoking prompt. Vietnamese prompt → Vietnamese output; English prompt → English output. Canonical tokens (`PENDING HUMAN REVIEW`, `APPROVED`, `CONFIGURATION GAP`), file paths, and CLI commands are language-invariant.

-

- Dùng để áp dụng SDD + ADD vào repository có source code sẵn hoặc tạo Reverse Spec cho module legacy.

- - `--stack=<tech-stack>`: Tùy chọn; stack đã biết, ví dụ `NestJS + PostgreSQL + Prisma`.

- - `--reverse-feature=<feature-slug>`: Tùy chọn; feature cần Reverse Spec.

- - `--path=<module-path>`: Tùy chọn; path module nguồn, ví dụ `src/modules/auth`.

- - `--team-size=solo|team`: Tùy chọn; chế độ làm việc. `solo` = 1 developer vừa là Human Director vừa là Agent; `team` = multi-agent (mặc định). Xem [Solo vs Team Mode](#solo-vs-team-mode).

-

- ## Các bước

-

- 1. Kiểm tra root, manifest, lockfile, runtime/bootstrap config, DB/migration config, CI, test config và source layout.

- 2. Tạo/cập nhật `.sdd/architecture-profile.md`; mỗi runtime, framework, DB, ORM, validation, test/build/lint command phải có evidence, confidence, conflict và `PENDING HUMAN REVIEW`.

- 3. Resolve binding theo thứ tự: profile approved → repository evidence rõ ràng → `--stack` explicit → core-only baseline. Mâu thuẫn thì dừng; không ghi đè profile approved.

- 4. **Generate governance files theo stack thực tế** (xem nguyên tắc Generate vs Copy bên dưới): `CLAUDE.md`, `AGENTS.md` phải giới hạn path/tool phù hợp repository; `CONSTITUTION.md` chỉ thay đổi qua RFC process.

- 5. Khởi tạo `.sdd/`, architecture protocol và toàn bộ slash command hiện hành.

-

- ## Generate vs Copy — Nguyên tắc quan trọng

-

- Với brownfield adoption, các governance file **phải phản chiếu repository thực** — persona, path, command và anti-pattern học được từ codebase hiện có — không phải copy verbatim từ template. Điều này đặc biệt quan trọng vì:

- - Project đã có convention riêng (naming, error handling, test patterns) → AGENTS.md phải capture những điều này

- - Build/lint/test command đã xác định từ CI → CONSTITUTION.md ENG-03 có thể điền exact command ngay

- - Lesson learned có thể seed từ PR history, commit message, incident log

-

- ### AGENTS.md — Generate từ repository evidence

-

- Survey repository trước khi generate:

-

- 1. **Identity & Persona**: Detect ngôn ngữ chính, framework, test runner. Generate persona phù hợp (Go developer ≠ TypeScript developer — philosophy, style guide, idioms khác nhau).

- 2. **Scope & Boundaries**: Dùng path thực của repository. Nếu project dùng `app/`, `lib/`, `pkg/` thay vì `src/` — reflect đúng thực tế.

- 3. **Tool Permissions**: Điền exact command từ CI/Makefile/package.json scripts đã verified. Ví dụ: nếu CI chạy `make test`, ghi `make test`, không ghi `npm test`.

- 4. **Security Rules**: Giữ Zero Secret Policy. Thêm constraint đặc thù nếu phát hiện (ví dụ: project có `.env.vault` → ghi rõ không được commit `.env.vault`).

- 5. **Communication Style**: Mirroring language rule + format báo cáo.

- 6. **Error Handling**: Quy trình khi test fail, Spec mơ hồ, conflict.

- 7. **Escalation Protocol**: Khi nào dừng và báo Human Director.

- 8. **Changelog**: Seed với version 1.0.0 + timestamp adoption.

-

- ### CLAUDE.md — Generate từ codebase thực

-

- Không dùng placeholder. Điền từ repository evidence:

-

- 1. **TL;DR**: Viết mô tả ngắn dựa trên README, package.json description, module chính.

- 2. **Architecture**: Detect pattern thực (thư mục `domain/`, `usecase/` → Clean Architecture; `modules/` → Modular Monolith; ...). Ghi file structure thực.

- 3. **Lesson Learned**: Seed từ PR/commit history nếu có pattern nổi bật (ví dụ: nhiều commit fix N+1, deadlock, auth bug). Format `[YYYY-MM] Vấn đề — Fix đã áp dụng`.

- 4. **Current Sprint Focus**: Để trống hoặc điền nếu `--reverse-feature` được cung cấp.

-

- ### .agentignore — Generate theo stack thực

-

- Scan build artifact, cache directory và generated file trong repository; thêm vào pattern chuẩn theo ngôn ngữ. Ví dụ: nếu repository có `coverage/` directory → thêm. Nếu có Prisma → thêm `prisma/migrations/*.js` (generated). Không copy `.agentignore` của template.

- ### .gitignore — Bổ sung, không ghi đè

- Nếu repository đã có `.gitignore`, chỉ thêm pattern liên quan SDD (`.sdd/updates/`) mà chưa có. Không xóa hoặc thay thế. Nếu chưa có `.gitignore`, generate theo stack phát hiện.

- ### CONSTITUTION.md — Tùy chỉnh nhẹ, không ghi đè sau RFC

- Nếu repository chưa có `CONSTITUTION.md`:

- - Generate với 3-layer structure chuẩn

- - Điền exact verification command (ENG-03) từ CI evidence nếu có

- Nếu repository đã có `CONSTITUTION.md` (từ lần adopt trước hoặc manual):

- - Không ghi đè Layer 1/2 đã approved

- - Chỉ bổ sung thiếu với recommendation `PENDING HUMAN REVIEW`

- - Layer 1/2 thay đổi cần RFC theo `/sdd-rfc`

- Khi có `--reverse-feature` và `--path`:

-

- - Đọc source/test trong module.

- - Tạo `CONTEXT.md`, `SPEC.md`, `PLAN.md`, `TASKS.md` quan sát behavior hiện tại.

- - `SPEC.md` dùng EARS, bắt đầu `DRAFT`; `PLAN.md`/`TASKS.md` không tự thành `COMPLETED`.

- - Chỉ thêm `@ears` vào source sau scope approval và khi binding liên quan đã approved.

- - Reverse Spec mô tả behavior quan sát được, không chứng minh business behavior đúng.

-

- ## Solo vs Team Mode

-

- ### Solo mode (`--team-size=solo`)

- Dùng khi developer duy nhất vừa là Human Director vừa là sole agent. Governance file được generate tối giản:

- - `AGENTS.md`: 1 role `@developer` — full-stack scope, toàn bộ tool permission.

- - `.sdd/shared_context.md`: Sole Developer context, bỏ multi-agent ownership table.

- - `.sdd/mcp-config.yaml`: 1 entry `@developer`.

- - `docs/multi-agent-orchestration-guide.md`: Vẫn tạo, thêm section Solo Workflow.

- ### Team mode (`--team-size=team`, mặc định)

- Multi-agent orchestration với Lead Agent và sub-agents. Xem `docs/multi-agent-orchestration-guide.md`.

- ---

- ## AI Recommendation và Human Final Review

- Sau adoption hoặc Reverse Spec, tạo recommendation theo `.claude/skills/_shared/ai-review-protocol.md` gồm kiến trúc phát hiện, governance assumption, migration risk, độ tin cậy Reverse Spec và alternative. Lưu tại `.sdd/reviews/adopt-<slug>.md` với `PENDING HUMAN REVIEW`. Human Director/Tech Lead approve scope trước downstream work; Agent không self-approve hoặc coi legacy behavior là business-approved.