ai-developer-skill-os 9.1.1 → 9.3.0

package/.agents/skills/qk-project-bootstrap/SKILL.md

@@ -1,520 +1,372 @@
 ---
 # ── Identity ───────────────────────────────────────────────
 name: qk-project-bootstrap
-version: 9.1.0
+version: 9.2.0
 status: stable
-description: "Khởi tạo dự án mới theo chuẩn V8.2 Blueprint Plugin Generator (project.yaml, 4-folder AI RAG hoặc Coding) với cấu trúc kiên cường."
+description: "Khởi tạo dự án mới HOẶC setup DEV_PROFILE.md cho dự án đang chạy — auto-detect stack từ manifest files, không hỏi lại những gì đã có thể đọc được. Dùng skill này khi user nhắc đến: khởi tạo dự án, project setup, scaffold, bootstrap, new app, setup dev profile, detect stack, cấu hình skin — kể cả khi chỉ nói 'bắt đầu dự án mới'."
 platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
 
-# ── V9: Classification ─────────────────────────────────────
+# ── Classification ─────────────────────────────────────────
 type: capability
 
 intent:
   - project-initialization
-  - setup
+  - dev-profile-setup
+  - stack-detection
+  - scaffolding
 
 complexity:
   level: high
   criteria:
     files_affected: "10+"
-    has_behavior_change: true
-    has_external_dependency: true
+    has_behavior_change: false
+    has_external_dependency: false
     has_breaking_change: false
 
 triggers:
-  - "khởi tạo project"
-  - "tạo dự án mới"
+  - "khởi tạo dự án"
+  - "project setup"
+  - "scaffold"
   - "bootstrap"
-  - "setup project"
-  - "init repo"
+  - "new app"
+  - "setup dev profile"
+  - "detect stack"
+  - "cấu hình skin"
 
-# ── V8: References ─────────────────────────────────────────
+# ── References ─────────────────────────────────────────────
 workflow: feature-delivery
 
 rules:
   - global
   - safety
-  - filesystem-boundary
 
 tools:
   - filesystem
   - terminal
 
 related_skills:
-  - qk-engineering-standard
+  - qk-context-loader   # Load sau khi DEV_PROFILE.md đã được tạo
 
 knowledge_scope:
   owns:
     - project-structure
-    - initial-setup
+    - dev-profile-setup
+    - stack-detection
   references:
     - architecture
     - security
-    - anti-patterns
 
-# ── V8: Verification ───────────────────────────────────────
+# ── Verification ───────────────────────────────────────────
 verification:
   required: true
-  strategy: bootstrap-validation
-
-selection:
-  priority: medium
-  confidence_threshold: 0.85
+  strategy: bootstrap
 
 examples: []
 learnings: []
 
-# ── V7 Runtime ─────────────────────────────────────────────
+# ── Runtime ────────────────────────────────────────────────
 execution_mode: deterministic
-cost: high
-latency: slow
+cost: low
+latency: fast
 risk: low
-side_effects: edit_files
-produces: [code, schema, plan]
-consumes: [user-description]
+side_effects: create_files
+produces: [dev-profile, scaffold]
+consumes: [manifest-files, user-description]
 
 token_budget:
-  max_files_read: 1
-  max_lines_per_read: 50
+  max_files_read: 10
+  max_lines_per_read: 80
   max_shell_commands: 2
   stop_early: true
 
 exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
 ---
 
-# qk-project-bootstrap — Project Foundation Builder
+# qk-project-bootstrap — Project Setup & Stack Detection
 
 > **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
 
 ---
 
-## Memory Workflow
-
-### 0. Self-Init Protocol (Khởi Tạo Bộ Nhớ Local & Gitignore)
-- Trước khi tra cứu hoặc lưu trữ tri thức, BẮT BUỘC kiểm tra sự tồn tại của thư mục `.ai-local/` tại gốc dự án:
-  - **Tự động tạo mới:** Nếu `.ai-local/` chưa tồn tại, AI phải tự động tạo cấu trúc thư mục `.ai-local/knowledge/` (và file `index.yaml` nếu cần thiết) cùng `.ai-local/candidates/`. Tuyệt đối không ngưng chạy hay hỏi ý kiến người dùng về thao tác khởi tạo tiêu chuẩn này.
-  - **Bảo mật Gitignore:** BẮT BUỘC kiểm tra file `.gitignore` của dự án, nếu chưa có dòng `.ai-local/` thì phải tự động thêm vào để tuyệt đối bảo mật tri thức cá nhân và tránh lộ lọt lên Git.
-
----
-
-### Pre-flight Retrieve (Trước khi thực thi)
-- Trước các task có tính lặp lại, debug, refactor, kiến trúc hoặc rủi ro cao:
-  bắt buộc tra cứu:
-  - `.ai-local/knowledge/index.yaml` (Private Local Knowledge)
-
-- Ưu tiên sử dụng các Knowledge đang có trạng thái `Active` thuộc:
-  - Architecture
-  - Hard Bug
-  - Convention
-  - Pattern
-  - Tech Debt Pattern
-  - 👉 *Domain Focus:* Architecture / Convention (vd: mô hình 4-folder RAG/Agent, blueprint quy chuẩn V9).
-
-- Memory chỉ đóng vai trò **Navigator (bản đồ chỉ đường)**.
-  Không được xem Memory là Source of Truth.
-  Luôn xác minh lại bằng source code, configuration và trạng thái hiện tại của dự án trước khi áp dụng.
-
----
-
-### Learning Flow (AI tự học có kiểm soát)
-- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
-  - Hard Bug có khả năng tái diễn.
-  - Pattern làm việc lặp lại trong dự án.
-  - Convention hoặc quy tắc kiến trúc mới.
-  - Quyết định Architecture quan trọng.
-  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
-  - 👉 *Domain Harvest:* Cấu trúc thư mục hoặc template scaffold mẫu mới của dự án.
-
-- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
-- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
-- AI không được tự động Promote Candidate Memory thành Project Knowledge.
-
----
-
-### Post-flight Harvest (Đề xuất → Phê duyệt)
-Sau khi hoàn thành task:
-- AI đánh giá các Candidate Memory đã tạo.
-- Nếu phát hiện tri thức có giá trị tái sử dụng:
-  - Đề xuất người dùng xem xét.
-  - Gửi yêu cầu phê duyệt thông qua:
-    - `/learn`
-    - `qk-project-memory`
-- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
-
-```
-.ai-local/candidates/  ──(Approve)──>  .ai-local/knowledge/index.yaml
-```
-
-- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
-  - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
-
----
-
-### Ignore (Không đưa vào Memory)
-Không lưu:
-- Trace log của một session đơn lẻ.
-- Temporary debugging data.
-- Output của một lần chạy test/scan.
-- Report health tạm thời của một đợt kiểm tra.
-- Lỗi nhỏ chỉ xảy ra một lần.
-- Thông tin không có khả năng tái sử dụng.
-- 👉 *Domain Ignore:* File cấu hình local rác (đã đưa vào gitignore).
+## Preconditions
 
----
+Trước khi khởi tạo dự án hoặc setup DEV_PROFILE.md, AI BẮT BUỘC kiểm tra:
 
-### Golden Rule
-> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
-> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
+- [ ] Xác định thư mục root của dự án.
+- [ ] Kiểm tra xem thư mục có file manifest nào tồn tại không (`package.json`, `requirements.txt`, `go.mod`, `Cargo.toml`, v.v.) để chọn Mode A (dự án mới) hay Mode B (dự án hiện có).
+- [ ] Kiểm tra xem `.agents/DEV_PROFILE.md` đã tồn tại chưa. Nếu đã có và user không yêu cầu ghi đè:
+  → **EXIT: PARTIAL**
+  → Đề xuất cập nhật hoặc giữ nguyên thay vì overwrite toàn bộ.
 
 ---
 
+## Hai chế độ hoạt động
 
+**Mode A — New Project:** Tạo project mới từ đầu theo Blueprint template
+**Mode B — Existing Project:** Scan project đang có, detect stack, tạo/cập nhật `DEV_PROFILE.md`
 
-### 0. Self-Init Protocol (Khởi Tạo Bộ Nhớ Local & Gitignore)
-- Trước khi tra cứu hoặc lưu trữ tri thức, BẮT BUỘC kiểm tra sự tồn tại của thư mục `.ai-local/` tại gốc dự án:
-  - **Tự động tạo mới:** Nếu `.ai-local/` chưa tồn tại, AI phải tự động tạo cấu trúc thư mục `.ai-local/knowledge/` (và file `index.yaml` nếu cần thiết) cùng `.ai-local/candidates/`. Tuyệt đối không ngưng chạy hay hỏi ý kiến người dùng về thao tác khởi tạo tiêu chuẩn này.
-  - **Bảo mật Gitignore:** BẮT BUỘC kiểm tra file `.gitignore` của dự án, nếu chưa có dòng `.ai-local/` thì phải tự động thêm vào để tuyệt đối bảo mật tri thức cá nhân và tránh lộ lọt lên Git.
+AI tự xác định mode dựa vào context:
+- Có `package.json` / `requirements.txt` / `go.mod` tồn tại → **Mode B**
+- Không có gì → **Mode A**
+- User nói rõ → follow user
 
 ---
 
-### Pre-flight Retrieve (Trước khi thực thi)
-- Trước các task có tính lặp lại, debug, refactor, kiến trúc hoặc rủi ro cao:
-  bắt buộc tra cứu:
-  - `.ai-local/knowledge/index.yaml` (Private Local Knowledge)
+## Scope
 
-- Ưu tiên sử dụng các Knowledge đang có trạng thái `Active` thuộc:
-  - Architecture
-  - Hard Bug
-  - Convention
-  - Pattern
-  - Tech Debt Pattern
-  - 👉 *Domain Focus:* Architecture / Convention (vd: mô hình 4-folder RAG/Agent, blueprint quy chuẩn V9).
+✅ Skill này làm:
+- Auto-detect tech stack từ manifest files
+- Tạo / cập nhật `.agents/DEV_PROFILE.md` với stack được detect
+- Tạo cấu trúc project theo Blueprint template đúng loại
+- Setup `.gitignore`, `.env.example`, `README.md` ban đầu
+- Gợi ý skills phù hợp với stack được detect
 
-- Memory chỉ đóng vai trò **Navigator (bản đồ chỉ đường)**.
-  Không được xem Memory là Source of Truth.
-  Luôn xác minh lại bằng source code, configuration và trạng thái hiện tại của dự án trước khi áp dụng.
+❌ Skill này KHÔNG làm:
+- Viết business logic hay feature code
+- Setup CI/CD pipeline (→ `qk-devops-platform`)
+- Deploy hay publish (→ `qk-production-release`)
+- Viết test (→ `qk-test-engineering`)
 
 ---
 
-### Learning Flow (AI tự học có kiểm soát)
-- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
-  - Hard Bug có khả năng tái diễn.
-  - Pattern làm việc lặp lại trong dự án.
-  - Convention hoặc quy tắc kiến trúc mới.
-  - Quyết định Architecture quan trọng.
-  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
-  - 👉 *Domain Harvest:* Cấu trúc thư mục hoặc template scaffold mẫu mới của dự án.
+## Execution Steps — Mode B: Detect Stack cho dự án đang có
 
-- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
-- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
-- AI không được tự động Promote Candidate Memory thành Project Knowledge.
+> Đây là mode quan trọng nhất — dùng khi muốn setup skin cho project hiện tại.
 
----
-
-### Post-flight Harvest (Đề xuất → Phê duyệt)
-Sau khi hoàn thành task:
-- AI đánh giá các Candidate Memory đã tạo.
-- Nếu phát hiện tri thức có giá trị tái sử dụng:
-  - Đề xuất người dùng xem xét.
-  - Gửi yêu cầu phê duyệt thông qua:
-    - `/learn`
-    - `qk-project-memory`
-- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
-
-```
-.ai-local/candidates/  ──(Approve)──>  .ai-local/knowledge/index.yaml
+### Step 1 — Scan Manifest Files
 ```
+Actions (chạy song song, đọc lần lượt từng file nếu tồn tại):
 
-- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
-  - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
+JavaScript / TypeScript:
+  - package.json          → dependencies, devDependencies, scripts
+  - tsconfig.json         → strict mode, paths, target
+  - .nvmrc / .node-version → Node version
 
----
+Python:
+  - requirements.txt / requirements/*.txt
+  - pyproject.toml (poetry/pdm sections)
+  - setup.py / setup.cfg
+  - Pipfile
 
-### Ignore (Không đưa vào Memory)
-Không lưu:
-- Trace log của một session đơn lẻ.
-- Temporary debugging data.
-- Output của một lần chạy test/scan.
-- Report health tạm thời của một đợt kiểm tra.
-- Lỗi nhỏ chỉ xảy ra một lần.
-- Thông tin không có khả năng tái sử dụng.
-- 👉 *Domain Ignore:* File cấu hình local rác (đã đưa vào gitignore).
+Go:
+  - go.mod                → module name, Go version, dependencies
 
----
+Rust:
+  - Cargo.toml
 
-### Golden Rule
-> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
-> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
+Java / Kotlin:
+  - pom.xml / build.gradle / build.gradle.kts
 
----
+Data / AI:
+  - dbt_project.yml       → dbt version, profile
+  - airflow.cfg / dag folder structure
+  - mlflow.yml / kedro.yml
+  - .env.example          → DB_URL, OPENAI_API_KEY hints
 
-## Preconditions
-- [ ] Framework/language preference is stated (or ask before proceeding)
-- [ ] Project purpose is clear (web app, API, CLI, library)
+Infrastructure:
+  - docker-compose.yml    → services (db type, cache, queue)
+  - Dockerfile            → base image → language + version
+  - .github/workflows/    → CI tools
+  - terraform/ / pulumi/  → infra provider
 
+Output: raw_detected = { language, frameworks[], databases[], tools[] }
 ```
-On missing precondition:
-  EXIT: BLOCKED
-  Message: "Vui lòng cho biết: framework (React/Next.js/NestJS/Express...) và mục đích dự án."
-```
-
----
-
-## Scope & V8.2 Blueprint Generator
-- ✅ **One-Click Blueprint Selection:** Choose from Blueprint Plugins (`coding`, `rag`, `workflow`, `enterprise`).
-- ✅ **Generate `project.yaml`:** Copy appropriate manifest from `.agents/blueprints/<type>/project.yaml.tpl` to workspace root.
-- ✅ **Initialize Project Scaffolding:** Create standard directory structure (including the **4-Folder RAG Architecture** for AI projects).
-- ✅ **Initialize Project Knowledge V1:** Setup Local Private Memory architecture (`.ai-local/` directory with automatic `.gitignore` entry included by default) containing concise `AGENTS.md` (<100 lines) and `knowledge/index.yaml` (4 core types: Architecture, Convention, Pattern, Hard Bug).
-- ✅ **Configure Tooling:** Linter, Prettier, TypeScript strict mode, or Python environment depending on stack.
-- ✅ **Generate `DESIGN.md`:** Mandatory brand & token contract for any UI project.
-
-## Non-Goals
-- ❌ Skip `project.yaml` workspace manifest initialization
-- ❌ Skip Project Knowledge V1 (`AGENTS.md` & `index.yaml` memory setup in `.ai-local/`)
-- ❌ Skip DESIGN.md for UI projects
-- ❌ Hardcode outdated dependency versions or absolute machine disk paths
-- ❌ Skip README or documentation
 
----
-
-## V8.2 Blueprint Plugins & Directory Structures
-
-### 1. RAG & AI Agents (The 4-Folder Architecture Blueprint)
-*Activated when building AI agents, RAG engines, or domain automation.*
-```text
-project.yaml              # ⭐ V8.2 Workspace Manifest (Profiles & Capabilities)
-.ai-local/                # ⭐ V1 Private Project Memory (Self-Init & Gitignored by default)
-├── AGENTS.md             # Project roadmap & quick actions (<100 lines)
-└── knowledge/
-      └── index.yaml      # Architecture, Convention, Pattern & Hard Bug repository
-prompts/                  # Prompt instructions managed as code
-├── system/
-├── tasks/
-└── tools/
-data/                     # Strict data discipline
-├── raw/                  # IMMUTABLE original files (PDFs, Excel, Revit/CAD)
-└── processed/            # Cleaned, standardized chunks for AI ingestion
-agents/                   # Agent configurations and domain micro-skills
-├── skills/
-└── tools/
-evals/                    # Quantitative validation evidence
-├── tests/
-├── traces/               # Audit execution traces
-└── scorecards/           # scorecard.yaml eval rubrics
+### Step 2 — Classify Stack
 ```
-
-### 2. Standard Coding Workspaces (Next.js / React / Node)
-*Activated when developing software applications or UI components.*
-```text
-project.yaml              # ⭐ V8.2 Workspace Manifest
-.ai-local/                # ⭐ V1 Private Project Memory (Self-Init & Gitignored by default)
-├── AGENTS.md             # Project roadmap & quick actions (<100 lines)
-└── knowledge/
-      └── index.yaml      # Architecture, Convention, Pattern & Hard Bug repository
-src/
-├── app/                  # Pages or App Router
-├── components/           # Shared UI components & Design system primitives
-├── hooks/
-├── lib/
-├── services/             # API integration & State stores
-├── types/
-└── styles/
-DESIGN.md                 # Brand & Design Contract
+Inputs:  raw_detected
+Actions:
+  Determine role từ stack combination:
+  
+  fe:          React/Vue/Angular + NO backend framework trong cùng repo
+  be:          Express/FastAPI/NestJS/Django + NO React/Vue trong cùng repo
+  fullstack:   Frontend framework + Backend framework TRONG CÙNG REPO
+               (Next.js = fullstack mặc định; Nuxt = fullstack mặc định)
+  data:        dbt / Airflow / Spark / Dagster / Prefect / Pandas heavy
+  ai-engineer: LangChain / LlamaIndex / OpenAI SDK + vector DB
+  devops:      Terraform / Pulumi / GitHub Actions heavy, ít application code
+  
+  Nếu ambiguous → default: fullstack, ghi chú để user confirm
+
+  Map dependencies → specific stack fields:
+  
+  frontend:  next → "Next.js", nuxt → "Nuxt 3", react (no next) → "React",
+             vue → "Vue 3", angular → "Angular", svelte → "SvelteKit"
+  backend:   express → "Express", fastapi → "FastAPI", nestjs → "NestJS",
+             django → "Django", laravel → "Laravel", gin → "Gin (Go)"
+  database:  pg/postgres → "PostgreSQL", mysql → "MySQL",
+             mongodb → "MongoDB", sqlite → "SQLite",
+             supabase → "Supabase", prisma → also check schema.prisma
+  orm:       prisma → "Prisma", typeorm → "TypeORM", drizzle → "Drizzle",
+             sqlalchemy → "SQLAlchemy", sequelize → "Sequelize"
+  css:       tailwind → "Tailwind CSS", sass/scss → "SCSS",
+             styled-components → "Styled Components", @emotion → "Emotion"
+  state:     zustand → "Zustand", redux → "Redux Toolkit",
+             jotai → "Jotai", pinia → "Pinia", @tanstack/query → "React Query"
+  auth:      next-auth/auth.js → "NextAuth", clerk → "Clerk",
+             passport → "Passport.js", supabase/auth → "Supabase Auth"
+  test:      jest → "Jest", vitest → "Vitest", pytest → "Pytest",
+             playwright → "Playwright", cypress → "Cypress"
+  language:  typescript in deps → "TypeScript", python → "Python",
+             go.mod exists → "Go"
+
+Output: classified_stack = fully mapped stack object
 ```
 
-### 3. Automation Workflows (n8n & Data ETL)
-```text
-project.yaml              # ⭐ V8.2 Workspace Manifest
-.ai-local/                # ⭐ V1 Private Project Memory (Self-Init & Gitignored by default)
-workflows/                # Automation graphs & JSON blueprints
-connectors/               # API & Database integrations
-pipelines/                # Transformation scripts
-evals/                    # Traceability logs
+### Step 3 — Tạo / Cập nhật DEV_PROFILE.md
 ```
-
----
-
-## Required Files Checklist
-```
-[ ] project.yaml — V8.2 Machine-readable Workspace Manifest
-[ ] .ai-local/AGENTS.md — V1 Project Architecture Navigator (<100 lines)
-[ ] .ai-local/knowledge/index.yaml — V1 Actionable Knowledge Base (Self-Init on demand)
-[ ] package.json / pyproject.toml — dependencies and scripts
-[ ] tsconfig.json — strict mode enabled (if TypeScript)
-[ ] .eslintrc / .prettierrc — project standard linting and formatting
-[ ] .gitignore — standard entries (MUST include .ai-local/ to protect personal project memory)
-[ ] README.md — project description + setup instructions
-[ ] DESIGN.md — (UI projects) brand contract with color/font/spacing tokens
-[ ] evals/scorecard.yaml — (AI/RAG/Workflow projects) eval standard
-[ ] .agents/rules/anti-patterns.md — Bắt buộc phải có (chuẩn V8.3 R-C-09)
-[ ] .agents/rules/security.md — Bắt buộc phải có (chuẩn V8.3 R-SEC-04)
+Inputs:  classified_stack, detected role
+Actions:
+  - Đọc DEV_PROFILE.md hiện tại nếu tồn tại (không overwrite những gì user đã điền)
+  - Điền các field detect được, giữ nguyên field user đã điền tay
+  - Để trống những field không detect được (không đoán mò)
+  - Thêm comment "# auto-detected" sau mỗi giá trị được detect
+  - Nếu có conflict giữa detected và existing → giữ existing, ghi chú
+
+Output: .agents/DEV_PROFILE.md được điền đầy đủ phần detect được
 ```
------
-
-## DESIGN.md Minimum Template
-```markdown
-# Design System
-
-## Colors (HSL)
---color-primary: hsl(220, 80%, 55%);
---color-surface: hsl(220, 15%, 12%);
---color-text: hsl(220, 10%, 90%);
 
-## Spacing Scale (4px base)
---space-1: 4px; --space-2: 8px; --space-3: 16px;
---space-4: 24px; --space-5: 32px; --space-6: 48px;
-
-## Typography
---font-sans: 'Inter', system-ui, sans-serif;
---font-size-base: 1rem;
---font-size-lg: 1.25rem;
-
-## Border Radius
---radius-sm: 4px; --radius-md: 8px; --radius-lg: 16px;
-
-## Animation
---transition-fast: 150ms ease;
---transition-base: 250ms ease;
+### Step 4 — Report & Suggest Next Steps
+```
+Actions:
+  - Hiển thị detected stack summary cho user confirm
+  - List những field còn trống cần user điền tay
+  - Suggest 3 skills phù hợp nhất để bắt đầu với stack này
+  - Suggest conventions dựa trên stack (ví dụ: Next.js → feature-based folder)
 ```
 
 ---
 
-## Workflow
+## Execution Steps — Mode A: New Project
 
-### Phase 1 — Blueprint Selection
-**Steps:**
-1. Assess Preconditions to determine framework/purpose.
-2. Select appropriate blueprint (coding, rag, workflow, enterprise).
+### Blueprint Types
 
-**Decision:**
+**Type 1: Standard Web App** (fe / be / fullstack)
 ```
-IF framework/purpose is clear
-  → Confidence: HIGH → go to Phase 2
-ELSE
-  → EXIT: BLOCKED — ask user
+Cấu trúc:
+  src/
+  ├── features/          # Feature-based modules
+  ├── components/        # Shared UI components  
+  ├── lib/               # Utilities, helpers
+  ├── hooks/             # Custom React hooks (nếu React)
+  ├── types/             # TypeScript interfaces
+  ├── api/               # API layer / service functions
+  └── config/            # App configuration
+
+Files sinh ra:
+  .gitignore, .env.example, README.md,
+  DESIGN.md (placeholder), .agents/DEV_PROFILE.md (pre-filled)
 ```
 
-### Phase 2 — Scaffold Generation
-**Steps:**
-1. Generate `project.yaml` manifest.
-2. Create directory tree structure based on blueprint.
-3. Configure tooling and generate `DESIGN.md` if UI project.
-
-**Decision:**
+**Type 2: RAG / AI Agent** (ai-engineer)
 ```
-IF directories and files are generated
-  → Confidence: HIGH → go to Phase 3
-ELSE
-  → EXIT: FAILED
+Cấu trúc (4-folder chuẩn):
+  prompts/               # System prompts, few-shot examples
+  data/
+  ├── raw/               # Source data — KHÔNG bao giờ edit
+  ├── processed/         # Cleaned, chunked
+  └── embeddings/        # Vector representations
+  agents/                # Agent definitions, tool configs
+  evals/
+  ├── traces/            # Execution logs
+  ├── datasets/          # Golden Q&A sets
+  └── scorecards/        # Metric definitions
+
+Files sinh ra:
+  .gitignore (data/raw/, .env), .env.example,
+  README.md, .agents/DEV_PROFILE.md (ai-engineer role pre-filled)
 ```
 
-### Phase 3 — Verification
-**Steps:**
-1. Check Required Files Checklist against what was actually created.
-2. Ensure no mandatory files are missing.
-
-**Decision:**
+**Type 3: Data Pipeline** (data)
 ```
-IF all required files exist
-  → EXIT: SUCCESS
-ELSE
-  → EXIT: PARTIAL
+Cấu trúc:
+  dags/ / pipelines/     # DAG definitions
+  models/
+  ├── staging/           # Raw → cleaned
+  ├── intermediate/      # Business transforms
+  └── mart/              # Final analytics tables
+  tests/                 # Data quality tests
+  docs/                  # Data lineage docs
+  seeds/                 # Static reference data
+
+Files sinh ra:
+  .gitignore, .env.example, README.md,
+  dbt_project.yml (nếu dbt), .agents/DEV_PROFILE.md (data role)
 ```
 
----
-
-## Evidence Format
-
+**Type 4: DevOps / Platform** (devops)
 ```
-[SEVERITY] path/to/expected-file
-Issue:      [MISSING_MANIFEST | MISSING_DESIGN_MD | WRONG_STRUCTURE]
-Confidence: HIGH
-Fix:        [specific file to create]
+Cấu trúc:
+  .github/workflows/     # CI/CD pipelines
+  terraform/ / pulumi/   # IaC modules
+  scripts/               # Automation scripts
+  docs/
+  ├── runbooks/          # Incident response
+  └── architecture/      # System diagrams
+
+Files sinh ra:
+  .gitignore, .env.example, README.md,
+  .agents/DEV_PROFILE.md (devops role)
 ```
 
 ---
 
-## Priority Order
-
-| Priority | Task | Skip Threshold |
-|----------|------|----------------|
-| P1 | project.yaml manifest created | Never |
-| P2 | Core scaffolding per blueprint type | Never |
-| P3 | Tooling config | Budget < 40% |
-| P4 | DESIGN.md for UI projects | Never for UI |
-| P5 | README | Budget < 60% |
+## Prompt Template
 
----
-## Exit Codes
-| Code | Meaning | When |
-|------|---------|------|
-| SUCCESS | All required files created, structure matches framework standard | Full bootstrap complete |
-| PARTIAL | Structure created but DESIGN.md incomplete (UI project) | Follow-up needed |
-| BLOCKED | Framework/purpose not specified | Ask user |
-| FAILED | Cannot initialize (permission error, invalid framework) | Report error |
-
----
-
-## Confidence Model
-| Level | Condition | Action |
-|-------|-----------|--------|
-| HIGH | Framework explicitly stated, directory structure clear | Build directly |
-| MEDIUM | Framework inferred from context (found React imports) | Note assumption, proceed |
-| LOW | Cannot determine framework or project type | EXIT: BLOCKED |
+```
+Mode:    [new / existing / profile-only]
+Role:    [fe / be / fullstack / data / ai-engineer / devops — hoặc "auto-detect"]
+Name:    [Tên project]
+Mô tả:  [1-2 câu app làm gì]
+Stack:   [Nếu biết rồi — hoặc để trống để AI detect]
+```
 
 ---
 
-## Severity
-| Level | Definition | Example |
-|-------|-----------|----------|
-| CRITICAL | Security misconfiguration in bootstrap | .env with real secrets committed |
-| HIGH | Missing mandatory file blocks all future work | No DESIGN.md for UI project |
-| MEDIUM | Incomplete setup reduces developer experience | Missing ESLint config |
-| LOW | Cosmetic or optional file missing | Missing .editorconfig |
+### Ví dụ theo từng tình huống:
 
----
-
-## Retry Policy
+**Tình huống 1 — Dự án đang có, muốn setup DEV_PROFILE nhanh**
 ```
-File creation fails
-  └─ Check: permission issue vs path error
-       ├─ Path error → correct path and retry
-       └─ Permission error → EXIT: FAILED, report exact path
-            └─ Do NOT retry more than 1 time per file
+Mode:    existing
+Role:    auto-detect
+Name:    (đọc từ project)
 ```
+→ AI scan `package.json`, detect `Next.js + Prisma + Tailwind + TypeScript`,
+  điền DEV_PROFILE.md với `role: fullstack`, toàn bộ stack fields,
+  gợi ý: "Tiếp theo dùng `qk-feature-delivery` để build feature đầu tiên".
 
----
-
-## Escalation Rules
+**Tình huống 2 — Dự án mới Fullstack**
 ```
-BLOCKED: Framework or project type not specified
-Missing:
-  - Framework name (React, Next.js, NestJS, Express, etc.)
-  - Project purpose (web app, API, CLI, library)
-Questions:
-  1. Framework nào bạn muốn dùng?
-  2. Dự án này là web app, API server, hay CLI tool?
-Recommended Assumptions (if proceeding):
-  - Default: Next.js 14 (App Router) + TypeScript + ESLint
+Mode:    new
+Role:    fullstack
+Name:    ecommerce-platform
+Mô tả:  Nền tảng thương mại điện tử B2C — quản lý sản phẩm, đơn hàng, thanh toán
+Stack:  Next.js 14 + Prisma + PostgreSQL + Tailwind + TypeScript
 ```
+→ AI tạo: folder structure theo Standard Web App blueprint,
+  `.env.example` với `DATABASE_URL`, `NEXTAUTH_SECRET`, `STRIPE_SECRET_KEY`,
+  `README.md` với setup instructions, `DEV_PROFILE.md` pre-filled.
 
----
-
-## Handoff Contract
-### Consumes
-```json
-{
-  "from": "user",
-  "required_fields": ["framework", "project_purpose"],
-  "optional_fields": ["project_name", "existing_dir"]
-}
+**Tình huống 3 — Setup RAG pipeline**
 ```
-### Produces
-```json
-{
-  "to": "qk-feature-delivery or qk-ui-builder",
-  "output_fields": ["project_structure", "design_md_path", "tooling_config", "exit_code"]
-}
+Mode:    new
+Role:    ai-engineer
+Name:    internal-kb-assistant
+Mô tả:  Q&A bot trả lời từ tài liệu nội bộ công ty (PDF, Confluence)
+Stack:  OpenAI GPT-4o + pgvector + LangChain + FastAPI
 ```
+→ AI tạo: 4-folder AI structure, `prompts/system.txt` placeholder,
+  `evals/scorecards/rag_metrics.yml` template (faithfulness, relevance, groundedness),
+  `DEV_PROFILE.md` với `role: ai-engineer`, full `data_stack` filled.
 
----
+**Tình huống 4 — Data pipeline mới**
+```
+Mode:    new
+Role:    data
+Name:    sales-analytics
+Mô tả:  Pipeline load sales data từ Salesforce → BigQuery, build mart cho dashboard
+Stack:  dbt + Airflow + BigQuery + Python
+```
+→ AI tạo: dbt project structure (staging/intermediate/mart),
+  `dbt_project.yml`, Airflow DAG folder, `DEV_PROFILE.md` với `role: data`,
+  full `data_stack` (pipeline: "dbt + Airflow", warehouse: "BigQuery").