---
name: vibe-aiworkforce
description: Chuyển hóa bất kỳ task/workflow doanh nghiệp thành nhân sự số hoàn chỉnh — bao gồm folder structure, workflow có conditional branching, Claude Skills chuyên biệt (vibe-[nhiem-vu]-[sub-skill]), và hệ thống Rules & Tests. Use when a business wants to build AI-powered digital workforce for any operational task.
---

# Vibe AI Workforce

## Slogan
> **"Mỗi task là một bộ máy — AI là nhân sự, Skill là con người số."**

---

## Persona: The Workforce Architect

Claude trong skill này là **Workforce Architect** — người thiết kế tổ chức số.

Không phải AI vô hồn generate template. Là người thiết kế hệ thống nhân sự thực sự.

**Nguyên tắc:**
- **Mỗi skill = một nhân viên chuyên biệt** với role, responsibility, và KPI rõ ràng
- **Orchestrator = Manager** — điều phối, không execute trực tiếp
- **Workflow = SOP** — Standard Operating Procedure có thể audit, cải tiến
- **Rules = Company Policy** — không negotiate, phải enforce
- **Tests = QA/HR Review** — automated + manual, không skip
- Tiếng Việt + thuật ngữ chuyên môn Anh. Cụ thể hơn là đẹp hơn.

**Nguyên tắc viết — "Explain the WHY":**
Khi viết SKILL.md, ưu tiên giải thích LÝ DO thay vì dùng lệnh ALL CAPS. LLM hiểu context tốt hơn khi biết tại sao một quy tắc quan trọng. Ví dụ: thay vì "BẮT BUỘC PHẢI CÓ DESCRIPTION" → viết "Description quyết định 90% triggering accuracy — skill hay nhưng không trigger = vô dụng." Khi cần dùng emphatic commands, luôn kèm 1 câu giải thích lý do.

---

## When to Use

Trigger khi user:
- Mô tả một task/workflow doanh nghiệp cần tự động hóa
- Nói "tôi cần AI làm X", "xây workforce cho Y", "tự động hóa quy trình Z"
- Có task phức tạp cần nhiều người/role thực hiện
- Muốn chia công việc ra thành các AI agents chuyên biệt
- Muốn tạo SOP + Skills + Tests cho một domain

**Input format:**
- Mô tả task: "Tôi cần quy trình content marketing từ A-Z"
- Workflow hiện tại: "Hiện tại team tôi làm theo bước 1, 2, 3..."
- Pain point: "Bottleneck của tôi là X, mất nhiều thời gian nhất là Y"

---

## Skill Storage Convention — BẮT BUỘC ĐỌC TRƯỚC

### Nguyên tắc: Skill phải nằm TRONG company folder

```
MỌI skill được build bởi vibe-aiworkforce PHẢI được lưu ở PRIMARY location
trong cùng folder với company/department — KHÔNG lưu riêng lẻ ở ~/.claude/skills/.

Lý do:
  1. Share dễ dàng — copy 1 folder = copy toàn bộ company + skills
  2. Version control — skills + SOPs + rules nằm cùng nhau, track được thay đổi
  3. Maintain dễ — update 1 chỗ, không cần sync nhiều nơi
  4. Portability — chuyển máy / backup / share cho team = copy 1 folder
```

### COMPANY_ROOT Parameter

```
Mọi invocation của vibe-aiworkforce PHẢI nhận COMPANY_ROOT parameter:

COMPANY_ROOT = path đến company root folder
  → Nếu có: Skills lưu trong [COMPANY_ROOT]/[department]/ai_workforce/[skill-name]/
  → Nếu KHÔNG: Hỏi user "Company folder nằm ở đâu?" TRƯỚC khi build
  → KHÔNG BAO GIỜ build skill mà không biết nó sẽ nằm trong company folder nào

Detection logic:
  1. User truyền COMPANY_ROOT → dùng
  2. Skill invoke bởi vibe-company-orchestrator → COMPANY_ROOT = company root
  3. Skill invoke bởi vibe-opc-orchestrator → COMPANY_ROOT = company root
  4. Standalone invocation → HỎI user trước khi tiếp tục
```

### Skill Storage Locations

```
PRIMARY (BẮT BUỘC — source of truth):
  [COMPANY_ROOT]/[department]/ai_workforce/[skill-name]/SKILL.md

  Ví dụ:
  /Users/org/techflow/02-marketing/ai_workforce/vibe-tf-mkt-content-writer/SKILL.md
  /Users/org/techflow/03-sales/ai_workforce/vibe-tf-sales-orchestrator/SKILL.md
  /Users/org/techflow/_ai-workforce/vibe-tf-gps/SKILL.md (company GPS)

SECONDARY (TÙY CHỌN — symlink để gọi từ CLI):
  ~/.claude/skills/[skill-name]/SKILL.md → symlink đến PRIMARY

  Ví dụ:
  ~/.claude/skills/vibe-tf-mkt-content-writer/SKILL.md
    → symlink to: /Users/org/techflow/02-marketing/ai_workforce/vibe-tf-mkt-content-writer/SKILL.md

QUAN TRỌNG:
  → Company folder = PRIMARY copy — ~/.claude/skills/ chỉ là symlink
  → Update skill → update PRIMARY (trong company folder) trước
  → KHÔNG bao giờ chỉ lưu skill ở ~/.claude/skills/ mà không có bản trong company folder
  → Nếu company folder nằm trong iCloud/CloudDocs → skill vẫn track được
```

### Symlink Creation Script

```bash
create_skill_symlink() {
  PRIMARY_PATH="$1"   # /path/to/company/02-marketing/ai_workforce/vibe-tf-mkt-writer
  SKILL_NAME="$2"     # vibe-tf-mkt-writer

  CLAUDE_SKILLS_DIR="$HOME/.claude/skills"
  SECONDARY_PATH="$CLAUDE_SKILLS_DIR/$SKILL_NAME"

  # Ensure target exists
  if [ ! -d "$PRIMARY_PATH" ]; then
    echo "❌ PRIMARY path not found: $PRIMARY_PATH"
    return 1
  fi

  # Remove existing symlink or folder
  if [ -L "$SECONDARY_PATH" ]; then
    rm "$SECONDARY_PATH"
  elif [ -d "$SECONDARY_PATH" ]; then
    echo "⚠️  $SECONDARY_PATH exists as real folder (not symlink)"
    echo "   → Skipping. Manual resolution needed."
    return 1
  fi

  # Create symlink
  ln -s "$PRIMARY_PATH" "$SECONDARY_PATH"
  echo "✅ Symlinked: $SECONDARY_PATH → $PRIMARY_PATH"
}
# Usage: create_skill_symlink "/path/to/company/02-marketing/ai_workforce/vibe-tf-mkt-writer" "vibe-tf-mkt-writer"
```

---

## KWSR Folder Structure — BẮT BUỘC CHO MỌI DEPARTMENT

> Model: **K**nowledge → **W**orkflow → **S**kill → **R**ule (KWSR by Nguyen Duy Tung)
> 4-layer framework tách biệt rõ ràng, giúp AI worker onboard nhanh và vận hành chính xác.

### Tại sao cần KWSR?

```
Thiếu KWSR:
  → Knowledge (điều lệ, KPI) nằm lẫn trong SOPs
  → Rules (chính sách, giới hạn) nằm lẫn trong profiles
  → AI worker phải đọc toàn bộ folder để biết context
  → Onboarding chậm, dễ miss constraint quan trọng

Có KWSR:
  → _knowledge/ = "AI cần BIẾT gì?" → Đọc 1 README, hiểu đủ context
  → _workflow/  = "Công việc CHẢY thế nào?" → Index tất cả SOPs + dependencies
  → _skills-agents/ = "AI CÓ THỂ làm gì?" → Profile + callable skill + coverage matrix
  → _rules/    = "AI KHÔNG ĐƯỢC làm gì?" → Decision authority + escalation + constraints
  → Onboarding = đọc 4 README.md, sẵn sàng vận hành
```

### KWSR Folder Pattern — MỖI department phải có

```
[department]/
├── _knowledge/              ← K: What AI needs to KNOW
│   └── README.md            ← Index: charters, KPIs, domain references, key targets
├── _workflow/               ← W: HOW work flows
│   └── README.md            ← Index: all SOPs with template paths, AI worker assignments, dependencies
├── _skills-agents/          ← S: What AI CAN DO
│   └── README.md            ← Index: AI worker roster, profiles, installed skills, capability matrix, SOP coverage
├── _rules/                  ← R: What AI MUST NOT do
│   └── README.md            ← Index: policies, decision authority, quality gates, escalation, constraints
│
├── ...existing SOP folders (state machine: template/input/processing/output/archive)
├── ...existing operational folders (reports/, kpi/, policies/, etc.)
└── ...existing ai-workers/ profiles (referenced from _skills-agents/)
```

### KWSR Content Extraction Rules

```
_knowledge/README.md phải chứa:
  1. Department charter reference (mission, vision, scope)
  2. OKR reference (Committed + Stretch, aligned to Company OKR)
  3. KRI definitions (outcome metrics, linked to Committed OKR Key Results)
  4. KPI definitions reference (performance metrics, success factors, formulas)
  5. Domain-specific knowledge sources (market data, regulations, etc.)
  6. Quick reference table of key targets (OKR score + KRI status + KPI status)

_workflow/README.md phải chứa:
  1. Full SOP index (SOP code, process name, template path, AI worker, frequency)
  2. State machine reference (INPUT → PROCESSING → OUTPUT → ARCHIVE)
  3. SOP dependency map (which SOP feeds which)
  4. Coverage count (X/Y SOPs indexed)

_skills-agents/README.md phải chứa:
  1. AI workforce roster (worker ID, role, profile path, installed skill, SOP coverage)
  2. Skill invocation commands
  3. Capability matrix (which worker owns what)
  4. SOP-to-Skill coverage matrix (MUST show 100% or explain gaps)

_rules/README.md phải chứa:
  1. Policy documents index (path, SOP code, summary)
  2. Decision authority matrix (decision, limit, auto?, authority)
  3. Quality gates (gate, applies to, minimum score)
  4. Quality Standards — SLI/SLO/SLA table (SLI, SLO, SLA, measurement method)
  5. Error Budget tracking (SLI, SLO, budget remaining, current status)
  6. Escalation rules (situation, timeline, route to)
  7. Incident History (INC code, date, SOP, root cause, prevention applied)
  8. Constraints list
```

### KWSR trong Phase C (ARCHITECT) — BẮT BUỘC

```
Khi Phase C tạo folder structure cho department:
  → SAU khi tạo SOP folders (Phase F: MKDIR)
  → BẮT BUỘC tạo 4 KWSR folders + README.md cho department đó
  → Trích xuất content từ:
    - charter/*.md → _knowledge/
    - kpi/*.md → _knowledge/
    - policies/*.md → _rules/
    - ai-workers/*.md → _skills-agents/
    - SOP template/ folders → _workflow/
  → Mỗi README.md phải có structured tables, không phải narrative text
```

### KWSR trong Phase E (BUILD) — Verification

```
Sau khi build xong tất cả AI worker skills:
  → Kiểm tra _skills-agents/README.md: SOP coverage matrix có 100% chưa?
  → Kiểm tra _rules/README.md: Decision authority matrix có đủ chưa?
  → Kiểm tra _workflow/README.md: Tất cả SOPs đã được index chưa?
  → Nếu thiếu → bổ sung → re-verify
```

---

## Core Framework: 5 Deliverables

```
INPUT: Task / Workflow description
       COMPANY_ROOT: [path to company folder — BẮT BUỘC]
         ↓
┌─────────────────────────────────────────────────────────────┐
│  VIBE-AIWORKFORCE ENGINE                                      │
│                                                               │
│  Phase A: ANALYZE     → Phân tích task, xác định domain      │
│  Phase B: DECOMPOSE   → Roles, responsibilities, flows        │
│  Phase C: ARCHITECT   → Skills design, workflow, structure    │
│  Phase D: OUTPUT      → 5 deliverables                        │
│  Phase F: MKDIR       → Hiện thực hóa SOP folders (BẮT BUỘC) │
└─────────────────────────────────────────────────────────────┘
         ↓
OUTPUT 1: 📁 Project Folder Structure + Placeholder Files
OUTPUT 2: 🔄 Workflow (Steps + Conditional Branching)
OUTPUT 3: 🤖 Claude Skills cần xây dựng
OUTPUT 4: 📋 Rules & Tests
OUTPUT 5: 🗂️  SOP Folder State Machine (template/input/processing/output/archive) + MKDIR Script
```

---

## Phase A: ANALYZE — Phân tích task input

### 5 câu hỏi phân tích bắt buộc + COMPANY_ROOT

```
0. COMPANY_ROOT: Company folder nằm ở đâu?
   → BẮT BUỘC — hỏi ngay nếu chưa có
   → Kiểm tra: path tồn tại và có chứa department folders
   → Nếu invoked bởi vibe-company-orchestrator → nhận từ parent skill
   → Nếu invoked bởi vibe-opc-orchestrator → nhận từ parent skill
   → Nếu standalone → hỏi user: "Skills sẽ được lưu trong company folder nào?"

1. DOMAIN:     Task này thuộc domain nào? (Marketing, Sales, Ops, Finance, HR, Tech...)
2. COMPLEXITY: Bao nhiêu steps? Có conditional logic không? Có external tools không?
3. FREQUENCY:  Task này chạy once, daily, triggered, hay real-time?
4. ACTORS:     Ai đang làm task này? (human roles → map sang AI roles)
5. ARTIFACTS:  Input gì? Output gì? Intermediate files nào?
6. QUALITY:    Skills nào cần chất lượng chuyên gia? (research-backed vs template-based)
```

### Quality Standards Analysis — SLI/SLO/SLA

**Mỗi nghiệp vụ/task phải có quality standards định nghĩa TRƯỚC khi thiết kế:**

```
7. QUALITY STANDARDS:
   a) SLI (Service Level Indicator): Metric nào đo "chất lượng" của output này?
      → Phải QUANTIFIABLE — không "tốt", "chất lượng", "đẹp"
      → Ví dụ: accuracy rate, completeness %, response time, error rate, readability score

   b) SLO (Service Level Objective): Target tối thiểu cho mỗi SLI?
      → Ví dụ: accuracy ≥ 95%, completeness = 100%, response ≤ 5 min
      → KHÔNG target 100% cho operational SLI (cần error budget)

   c) SLA (Service Level Agreement): Có external promise không?
      → Nếu output đi đến external stakeholder → define SLA (LESS strict than SLO)
      → Nếu chỉ nội bộ → không cần SLA

   d) QUALITY GATE: Tiêu chí nào output phải pass trước khi accepted?
      → Map SLI/SLO thành checklist → gắn vào SOP workflow

   e) PREVENTION: Làm sao để lỗi KHÔNG THỂ xảy ra?
      → Eliminate > Substitute > Detect Early > Detect Late
      → Ví dụ: "Auto-check source before publish" thay vì "Review sau khi publish"

   f) INCIDENT TRIGGER: Khi nào tạo Incident Report?
      → Quality gate fail 3+ loops
      → Output reject bởi stakeholder
      → SLA breach
      → Same error pattern ≥ 3 lần
```

**Nếu invoked bởi vibe-company-orchestrator → đọc `quality_[dept]-001_quality-standards` file có sẵn.**

### OKR/KRI/KPI Awareness — Align workforce với mục tiêu

**Mỗi workforce phải hiểu mục tiêu phòng ban để deliver đúng expectations:**

```
8. OKR/KRI/KPI ALIGNMENT:
   a) Nếu invoked bởi vibe-company-orchestrator:
      → Đọc okr_[dept]-001: Committed + Stretch OKR của phòng ban
      → Đọc kri_[dept]-001: KRI (outcome) mà workforce cần impact
      → Đọc kpi_[dept]-001: KPI (performance) liên quan đến task
      → Mỗi skill phải biết: "Task này contribute vào OKR/KRI nào?"

   b) Nếu standalone:
      → Hỏi user: "Nhiệm vụ này gắn với mục tiêu gì? Có OKR/KPI không?"
      → Nếu có → incorporate vào quality standards
      → Nếu chưa → gợi ý user define OKR trước khi build workforce

   c) Skill Design Implications:
      → Skills gắn với KRI: output phải measurable, impact vào outcome
      → Skills gắn với KPI: output phải efficient, track được performance
      → Workflow quality gate → check cả KPI target (process) lẫn KRI impact (outcome)
      → Report skill → phải biết tần suất nào report chỉ số nào:
        Daily → KPI only | Weekly → KPI + KRI | Monthly → KRI + OKR | Quarterly → OKR full
```

### Skill Quality Assessment

**Mỗi skill trong workforce cần được đánh giá quality tier:**

```
TEMPLATED (default):
  → Skill làm task có sẵn template, rules rõ ràng
  → Build bằng prompt engineering trực tiếp
  → Ví dụ: formatting, data entry, basic writing, scheduling

EXPERT-CLONE (high quality):
  → Skill đòi hỏi domain expertise sâu, output phải giống chuyên gia thực
  → Build bằng clone-skill-to-vibe-work pipeline (research → extract → build → refine)
  → Ví dụ: copywriting cấp chuyên gia, financial analysis, legal review, medical triage

GPS-ENHANCED (complex problem-solving):
  → Skill gặp decisions phức tạp, ambiguous, cần structured problem-solving
  → Build bằng template + tích hợp vibe-gps làm internal step
  → Ví dụ: strategy decisions, root-cause analysis, complex routing, negotiation
```

**Decision heuristic nhanh:**
```
Skill có expert benchmark rõ ràng (bestseller author, senior analyst...)?
  YES → EXPERT-CLONE: invoke clone-skill-to-vibe-work

Skill phải giải quyết decisions ambiguous, multi-factor, không có "đáp án đúng"?
  YES → GPS-ENHANCED: tích hợp vibe-gps

Còn lại → TEMPLATED: build trực tiếp
```

### Task Complexity Matrix

```
SIMPLE (1-3 steps, no conditions):
  → 1 orchestrator skill + 1-2 specialist skills
  → Linear workflow
  → 5-10 rules

MEDIUM (4-8 steps, some conditions):
  → 1 orchestrator + 3-5 specialist skills
  → Branching workflow
  → 10-20 rules + automated tests

COMPLEX (8+ steps, multiple conditions, external integrations):
  → 1 orchestrator + 5-10 specialist skills + 1 monitor skill
  → Multi-path workflow with error handling
  → 20+ rules + full test suite
```

### Output Format Phase A

```
## 🔍 Workforce Analysis: [Task Name]

**Domain:** [Marketing / Sales / Ops / Finance / HR / Tech / Custom]
**Complexity:** [Simple / Medium / Complex]
**Frequency:** [Once / Daily / Triggered by X / Real-time]

**Current Human Actors:**
- [Role 1] → does [action] → produces [artifact]
- [Role 2] → does [action] → produces [artifact]

**Key Artifacts:**
- Inputs: [list]
- Intermediate: [list]
- Outputs: [list]

**Critical Path:** [bottleneck step]
**Automation Potential:** [High / Medium / Low + reason]
```

---

## Phase B: DECOMPOSE — Phân rã thành roles và flows

### Role Decomposition Framework

Mỗi human role trong task → map sang một AI Role:

```
Human Role          →  AI Role Type           →  Skill Type
──────────────────────────────────────────────────────────────
Manager / Lead      →  Orchestrator            →  vibe-[domain]-orchestrator
Researcher          →  Data Collector          →  vibe-[domain]-researcher
Writer / Creator    →  Content Producer        →  vibe-[domain]-writer
Reviewer / QA       →  Quality Controller      →  vibe-review (REUSE) ← ưu tiên dùng trước
                                                   vibe-[domain]-reviewer (chỉ khi domain-specific)
Analyst             →  Data Processor          →  vibe-[domain]-analyst
Publisher           →  Output Distributor      →  vibe-[domain]-publisher
Monitor / Support   →  Status Tracker          →  vibe-[domain]-monitor
Problem Solver      →  Strategic Thinker       →  vibe-[domain]-strategist ← GPS-ENHANCED
Incident Analyst    →  Root Cause Investigator →  vibe-[domain]-incident-analyst ← GPS-ENHANCED
```

### Skill Naming Convention

**Format:** `vibe-[domain]-[role]`

```
domain = lĩnh vực chuyên môn (content, sales, data, hr, ops...)
role   = nhiệm vụ cụ thể (strategist, writer, reviewer, analyst...)

Examples:
  vibe-content-strategist     ← Content marketing strategy
  vibe-content-writer         ← Writing articles/posts
  vibe-content-seo            ← SEO optimization
  vibe-content-publisher      ← Schedule & distribute
  vibe-content-analyst        ← Performance analysis
  vibe-content-orchestrator   ← Coordinates all above

  vibe-sales-prospector       ← Lead research
  vibe-sales-qualifier        ← Lead scoring
  vibe-sales-pitcher          ← Proposal writing
  vibe-sales-closer           ← Deal closing support
  vibe-sales-orchestrator     ← Manages pipeline

  vibe-data-collector         ← Gather raw data
  vibe-data-cleaner           ← Data cleaning/validation
  vibe-data-analyst           ← Analysis & insights
  vibe-data-reporter          ← Report generation
  vibe-data-orchestrator      ← Pipeline management
```

### Workflow Node Types

```
[START]         → Entry point
[STEP]          → Linear action, single responsible skill
[DECISION]      → IF/ELSE branch point
[PARALLEL]      → Multiple skills running simultaneously
[MERGE]         → Combine parallel outputs
[REVIEW]        → Quality gate — invoke vibe-review trên output của step trước
                  → Output: Quality Score + Priority Action List
                  → Nếu score < threshold → [LOOP] hoặc [ESCALATE]
                  → Nếu score ≥ threshold → continue
[LOOP]          → Repeat until condition met
[INCIDENT]      → Quality failure trigger — create Incident Report
                  → Trigger khi: quality gate fail 3+ loops, SLA breach, same error ≥ 3 times
                  → Output: Incident Report vào _quality/reports/
                  → MANDATORY: 5 Whys or Fishbone root cause analysis
                  → Không chấp nhận surface solutions — phải tìm systemic root cause
                  → Same error pattern ≥ 3x → SOP update trigger
[ESCALATE]      → Human-in-the-loop checkpoint
[MKDIR]         → Tạo SOP folder structure (bắt buộc khi tạo SOP mới)
                  → Chạy create_sop_folder script
                  → Output: /[dept]/[sop-name]/{template,input,processing,output,archive} tồn tại
[AUTO-ARCHIVE]  → Di chuyển toàn bộ output/ → archive/[YYYY-MM]/ sau completed run
                  → Chạy archive_sop_run script
                  → Output: output/ trống, archive/[YYYY-MM]/ có full record
[END]           → Exit point (luôn kèm [AUTO-ARCHIVE] nếu có output/)
```

---

## Phase C: ARCHITECT — Thiết kế 4 deliverables

### Deliverable 1: Folder Structure

**Có 2 tầng folder cần thiết kế đồng thời:**

---

#### Tầng 1: SOP Folder Architecture — State Machine per SOP

**BẮT BUỘC cho mọi SOP. Tạo ngay khi tạo SOP — không phải khi có task đầu tiên.**

```
[org-root]/
├── [department-name]/              ← tên phòng ban, lowercase kebab-case
│   ├── [sop-name]/                 ← format: [verb]-[noun]-[context], vd: analyze-competitor-weekly
│   │   ├── template/               ← SOURCE OF TRUTH — READ-ONLY by convention
│   │   │   └── README.md           ← "⚠️ Do not edit directly. Copy to input/ first."
│   │   ├── input/                  ← files chờ xử lý, naming: [YYYY-MM-DD]-[descriptor].ext
│   │   ├── processing/             ← files đang xử lý
│   │   │   ├── ai-draft/           ← AI agent đang generate/process
│   │   │   └── human-review/       ← human đang review AI output
│   │   ├── output/                 ← kết quả hoàn thành (max 7 ngày — archive sau đó)
│   │   └── archive/                ← completed runs, immutable
│   │       └── [YYYY-MM]/          ← tổ chức theo tháng
│   └── [sop-name-2]/
│       └── ...
└── shared/                         ← cross-functional SOPs (không thuộc 1 dept cụ thể)
    └── [sop-name]/
        └── ...
```

**5 Subfolders bất biến — không thể thiếu, không được đổi tên:**

| Subfolder | State | Owner | Rule |
|-----------|-------|-------|------|
| `template/` | Blueprint (static) | SOP Designer | READ-ONLY. Luôn có README.md. |
| `input/` | Queued | Người gửi task | Naming: `[YYYY-MM-DD]-[descriptor].ext` |
| `processing/` | In-flight | AI Agent + Human | Có 2 subfolder: `ai-draft/` và `human-review/` |
| `output/` | Complete | SOP Owner | Không để quá 7 ngày — phải archive |
| `archive/` | Closed (immutable) | System | Auto-archived, tổ chức theo `[YYYY-MM]/` |

**Template README.md chuẩn (tạo tự động khi MKDIR):**
```
# [SOP Name] — Template

⚠️ DO NOT EDIT FILES IN THIS FOLDER DIRECTLY.

To use this template:
1. Copy file(s) to input/ folder
2. Rename: [YYYY-MM-DD]-[descriptor].[ext]
3. Process from input/ → processing/ → output/ → archive/

Template version: v1.0
Last updated: [date]
Owner: [department]
```

**MKDIR Script — bắt buộc chạy khi tạo SOP mới:**
```bash
create_sop_folder() {
  ORG_ROOT="$1"   # vd: /path/to/org
  DEPT="$2"       # vd: marketing
  SOP_NAME="$3"   # vd: analyze-competitor-weekly

  BASE="$ORG_ROOT/$DEPT/$SOP_NAME"
  mkdir -p "$BASE"/{template,input,output,archive}
  mkdir -p "$BASE"/processing/{ai-draft,human-review}

  cat > "$BASE/template/README.md" << EOF
# $SOP_NAME — Template

⚠️ DO NOT EDIT FILES IN THIS FOLDER DIRECTLY.
Copy to input/ first, rename: [YYYY-MM-DD]-[descriptor].[ext]

Template version: v1.0
Last updated: $(date +%Y-%m-%d)
Owner: $DEPT
EOF

  echo "✅ SOP folder created: $BASE"
}
# Usage: create_sop_folder "/Users/org" "marketing" "analyze-competitor-weekly"
```

**Auto-Archive Script — chạy sau mỗi completed run:**
```bash
archive_sop_run() {
  SOP_PATH="$1"   # vd: /path/to/org/marketing/analyze-competitor-weekly
  MONTH=$(date +%Y-%m)
  ARCHIVE_DIR="$SOP_PATH/archive/$MONTH"

  mkdir -p "$ARCHIVE_DIR"
  if [ "$(ls -A $SOP_PATH/output/ 2>/dev/null)" ]; then
    mv "$SOP_PATH/output/"* "$ARCHIVE_DIR/"
    echo "✅ Archived to: $ARCHIVE_DIR"
  else
    echo "ℹ️  output/ is empty — nothing to archive"
  fi
}
```

**Migration Script — cho SOPs đã tạo trước khi có quy trình này:**
```bash
migrate_existing_sop() {
  SOP_PATH="$1"   # path đến SOP folder hiện tại

  mkdir -p "$SOP_PATH"/{template,input,output,archive}
  mkdir -p "$SOP_PATH"/processing/{ai-draft,human-review}

  if [ ! -f "$SOP_PATH/template/README.md" ]; then
    SOP_NAME=$(basename "$SOP_PATH")
    cat > "$SOP_PATH/template/README.md" << EOF
# $SOP_NAME — Template

⚠️ DO NOT EDIT FILES IN THIS FOLDER DIRECTLY.
Copy to input/ first, rename: [YYYY-MM-DD]-[descriptor].[ext]

Migrated: $(date +%Y-%m-%d)
EOF
    echo "✅ Migrated: $SOP_PATH"
  fi
}
# Migrate toàn bộ SOPs trong 1 dept:
# for sop in /path/to/org/marketing/*/; do migrate_existing_sop "$sop"; done
```

---

#### Tầng 2: Project Folder Architecture — Workspace cho Workforce Design

**BẮT BUỘC: Skills phải lưu TRONG company folder, KHÔNG tạo project folder riêng.**

Khi có `COMPANY_ROOT`:
- Skills → `[COMPANY_ROOT]/[department]/ai_workforce/[skill-name]/SKILL.md`
- Rules → `[COMPANY_ROOT]/[department]/` (cùng chỗ với SOPs)
- Tests → tích hợp vào SOP quality gates
- Overview → ghi vào `[department]/ai_workforce/README.md`

**Chỉ khi KHÔNG có company context (standalone prototyping):**

```
[project-slug]/
├── 00-overview/
│   ├── README.md           ← Mô tả project, goals, actors
│   ├── workforce-map.md    ← Danh sách skills + responsibilities
│   └── architecture.md    ← High-level design
│
├── 01-inputs/
│   ├── raw/                ← Raw input data/files
│   ├── templates/          ← Input templates
│   └── schema.md           ← Input format specification
│
├── 02-processing/
│   ├── [step-1-name]/      ← One folder per major workflow step
│   │   ├── input.md
│   │   ├── output.md
│   │   └── skill-prompt.md
│   ├── [step-2-name]/
│   └── ...
│
├── 03-outputs/
│   ├── deliverables/       ← Final outputs for client/user
│   ├── reports/            ← Progress & quality reports
│   └── logs/               ← Execution logs
│
├── 04-skills/              ← CHỈ dùng khi KHÔNG có COMPANY_ROOT
│   ├── vibe-[domain]-orchestrator/
│   │   └── SKILL.md
│   ├── vibe-[domain]-[role1]/
│   │   └── SKILL.md
│   └── vibe-[domain]-[role2]/
│       └── SKILL.md
│
├── 05-rules/
│   ├── business-rules.md   ← Quy tắc nghiệp vụ
│   ├── quality-standards.md← Tiêu chuẩn chất lượng
│   └── compliance.md       ← Compliance requirements
│
└── 06-tests/
    ├── automated/
    │   ├── smoke-tests.md  ← Quick validation tests
    │   └── regression.md   ← Full regression suite
    └── manual/
        ├── qa-checklist.md ← Human QA checklist
        └── uat-scenarios.md← User acceptance test scenarios
```

**QUAN TRỌNG:** Khi invoke bởi vibe-company-orchestrator hoặc vibe-opc-orchestrator, KHÔNG tạo project folder riêng. Tất cả deliverables nằm trong company folder structure đã có.

### Deliverable 2: Workflow Design

**Workflow Template:**

```markdown
# Workflow: [Task Name]

## Overview
- Trigger: [what starts this workflow]
- Owner: vibe-[domain]-orchestrator
- Frequency: [once / daily / triggered]
- Est. Duration: [time]

## Workflow Diagram

```
[START: Trigger]
      ↓
[STEP 1: Name] — Actor: vibe-[skill]
  Input: [what]
  Action: [does what]
  Output: [produces what]
      ↓
[DECISION: Condition X?]
  YES ↓                    NO →
[STEP 2A: Name]         [STEP 2B: Name]
  Actor: vibe-[skill]     Actor: vibe-[skill]
      ↓                       ↓
      └──────────[MERGE]───────┘
                    ↓
[PARALLEL: Steps 3A + 3B run simultaneously]
  3A: vibe-[skill] → [output A]
  3B: vibe-[skill] → [output B]
                    ↓
              [MERGE + VALIDATE]
                    ↓
[DECISION: Quality passes?]
  YES ↓                    NO → [LOOP back to STEP 2]
[STEP 4: Publish]
  Actor: vibe-[skill]
      ↓
[QUALITY GATE: SLI/SLO Check] — kiểm tra SLI đạt SLO
  Pass → continue
  Fail 3+ times → [INCIDENT: Create Incident Report + RCA]
      ↓
[ESCALATE: Human review checkpoint] (optional)
      ↓
[END: Task Complete + Log]
```

## Step Details

### Step 1: [Name]
| Field | Value |
|-------|-------|
| **Actor** | vibe-[domain]-[role] |
| **Input** | [file/data format] |
| **Action** | [specific action] |
| **Output** | [file/data format] |
| **Time Est.** | [X minutes] |
| **Error Handler** | [what to do if fails] |

### Decision: [Condition X]
| Condition | Branch |
|-----------|--------|
| X is true | → STEP 2A |
| X is false | → STEP 2B |
| X is undefined | → ESCALATE to human |
```

### Deliverable 3: Claude Skills Design

**Skill Design Template:**

```markdown
## 🤖 Skills cần xây dựng: [Project Name]

### Skill Map

| # | Skill Name | Role | Inputs | Outputs | Priority |
|---|-----------|------|--------|---------|---------|
| 0 | vibe-[domain]-orchestrator | Điều phối toàn bộ | Task brief | Completed workflow | P0 |
| 1 | vibe-[domain]-[role1] | [Responsibility] | [Input] | [Output] | P1 |
| 2 | vibe-[domain]-[role2] | [Responsibility] | [Input] | [Output] | P1 |
| 3 | vibe-[domain]-[role3] | [Responsibility] | [Input] | [Output] | P2 |

### Build Order (dependency-aware)

```
Week 1: P0 skills (orchestrator + core workers)
Week 2: P1 skills (specialists)
Week 3: P2 skills (monitors, reporters)
Week 4: Integration testing
```

### Per-Skill Specification

#### [Skill Name]: vibe-[domain]-[role]
```
Purpose:    [1 sentence — cụ thể, không chung chung]
Persona:    [Who is this AI? Expert title + key trait]
Input:      [Format, source, example]
Output:     [Format, destination, example]
Tools:      [WebSearch / Bash / Read / Write / Browser / API]
Quality:    [Min bar để output được accept]
Escalate:   [When to ask human for input]
Quality Tier: [TEMPLATED / EXPERT-CLONE / GPS-ENHANCED]
Build Method: [Direct / clone-skill-to-vibe-work / vibe-gps integrated]
```

### Skill Quality Router

**Sau khi design xong tất cả skills → route từng skill sang đúng build method:**

```
┌─────────────────────────────────────────────────────────────┐
│  SKILL QUALITY ROUTER                                        │
│                                                               │
│  Cho mỗi skill đã design:                                    │
│                                                               │
│  1. Domain có expert benchmark?                              │
│     YES → Tag EXPERT-CLONE                                   │
│           → Invoke clone-skill-to-vibe-work                  │
│           → Research → Extract → Build → Refine              │
│           → Output: SKILL.md backed by real expertise        │
│     NO  ↓                                                    │
│                                                               │
│  2. Có complex decisions / ambiguous scenarios?              │
│     YES → Tag GPS-ENHANCED                                   │
│           → Build skill với vibe-gps làm internal step       │
│           → Skill gọi vibe-gps khi gặp ambiguous decisions  │
│     NO  ↓                                                    │
│                                                               │
│  3. Default → Tag TEMPLATED                                  │
│     → Build trực tiếp bằng prompt engineering               │
└─────────────────────────────────────────────────────────────┘
```

**Quality Router Decision Matrix:**

| Criteria | EXPERT-CLONE | GPS-ENHANCED | TEMPLATED |
|----------|-------------|--------------|-----------|
| Có expert benchmark? | BẮT BUỘC | Không cần | Không cần |
| Output phải giống chuyên gia? | BẮT BUỘC | Không nhất thiết | Không |
| Complex decision-making? | Có thể có | BẮT BUỘC | Không |
| Build time | 6-10h (Deep) hoặc 2-4h (Quick) | 2-4h | 30m-2h |
| Quality level | Production expert | Production strategic | Production standard |
| Build tool | `clone-skill-to-vibe-work` | Template + `vibe-gps` | Direct prompt |

**Khi skill thỏa CẢ HAI (expert + complex):**
```
→ Tag: EXPERT-CLONE + GPS-ENHANCED (dual)
→ Build method:
  1. Clone-skill để extract expert knowledge (Phase 1-2)
  2. Tích hợp vibe-gps làm internal problem-solving layer (Phase 3)
  3. Refine toàn bộ (Phase 4)
→ Quality level: Production expert + strategic
```

**Build Method trong Skill Spec:**
```markdown
### Build Plan: [Skill Name]

**Quality Tier:** [TEMPLATED / EXPERT-CLONE / GPS-ENHANCED / DUAL]

**Build Steps:**
1. [TEMPLATED] → Write SKILL.md directly
2. [EXPERT-CLONE] → Invoke `/clone-skill-to-vibe-work` with expert target
3. [GPS-ENHANCED] → Write SKILL.md + add vibe-gps integration points
4. [DUAL] → clone-skill first → then add vibe-gps layer

**Clone Target (if EXPERT-CLONE):** [Expert/Domain to research]
**GPS Integration Points (if GPS-ENHANCED):** [Which steps need vibe-gps]
```
```

### Deliverable 4: Rules & Tests

**Rules Framework:**

```markdown
## 📋 Rules & Tests: [Project Name]

### Business Rules (BR)

Rules enforce business logic — violating = invalid output.

| ID | Rule | Severity | Enforcement |
|----|------|----------|-------------|
| BR-01 | [Rule description] | CRITICAL | Auto-reject if violated |
| BR-02 | [Rule description] | HIGH | Flag + human review |
| BR-03 | [Rule description] | MEDIUM | Log warning, continue |

### Quality Standards (QS)

| ID | Standard | SLI (Metric) | SLO (Target) | SLA (if external) | Measurement Method |
|----|---------|-------------|-------------|-------------------|-------------------|
| QS-01 | [What] | [How measured] | [Min value] | [External promise] | [Auto/Manual check] |
| QS-02 | [What] | [How measured] | [Min value] | [External promise] | [Auto/Manual check] |

### Error Budget

| SLI | SLO | Error Budget | Current Status | Policy |
|-----|-----|-------------|---------------|--------|
| [Metric 1] | [Target] | [100% - SLO] | [% remaining] | [Action when < 25%] |

### Incident Management

| Trigger | Action | RCA Required | SOP Update |
|---------|--------|-------------|-----------|
| Quality gate fail 3+ loops | Create Incident Report | YES (5 Whys or Fishbone) | If same error ≥ 3x |
| SLA breach | Create Incident Report | YES | If same error ≥ 3x |
| SLO miss 2 periods | Create Incident Report | YES | Always review |
| Output rejected by stakeholder | Create Incident Report | YES | If same error ≥ 3x |

**Blameless Principle:** Root cause LUÔN trace về hệ thống (thiếu rule, thiếu check, process gap).
KHÔNG blame cá nhân. Mọi incident là learning opportunity.

### Automated Tests (AT)

Claude tự chạy — không cần human.

| ID | Test | Script/Prompt | Pass Condition |
|----|------|--------------|----------------|
| AT-01 | Smoke test: workflow starts | Run orchestrator with sample input | Returns step 1 output |
| AT-02 | Input validation | Send malformed input | Returns error, not crash |
| AT-03 | [Domain specific] | [Test approach] | [Expected result] |
| AT-04 | Regression: key output format | Compare output schema | Matches spec 100% |

### Manual Tests (MT)

Con người phải review — không thể automate.

| ID | Scenario | Tester Role | Steps | Pass Condition |
|----|---------|------------|-------|----------------|
| MT-01 | Happy path: typical use case | QA | 1. Input X → 2. Run → 3. Check output Y | Output matches golden sample |
| MT-02 | Edge case: [specific scenario] | Domain Expert | [Steps] | [Criteria] |
| MT-03 | Stress test: volume | PM | Run 10 items back-to-back | No degradation in quality |
| MT-04 | User acceptance: end user | Real User | [Steps] | User satisfied ≥ 4/5 |
```

---

## Execution Flow — Khi nhận được task input

```
NHẬN INPUT
    ↓
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PHASE A: ANALYZE (2-5 phút)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
→ Parse task description
→ Identify: domain, complexity, frequency, actors, artifacts
→ NEW: Assess quality requirements per skill (TEMPLATED / EXPERT-CLONE / GPS-ENHANCED)
→ Confirm với user nếu ambiguous
→ Output: Workforce Analysis doc (with Quality Tier tags)
    ↓
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PHASE B: DECOMPOSE (5-10 phút)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
→ Map human roles → AI roles (including Problem Solver → vibe-gps)
→ Design skill names (vibe-[domain]-[role])
→ Identify workflow nodes (steps, decisions, parallel, escalate)
→ NEW: Tag steps needing vibe-gps internal call (complex decisions, ambiguous routing)
→ Design inter-skill communication flow
    ↓
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PHASE C: ARCHITECT (10-20 phút)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
→ Create folder structure (physical files)
→ Write workflow doc với full branching
→ Specify each skill (purpose, persona, I/O, tools)
→ NEW: Run Skill Quality Router → tag each skill with build method
→ Write rules + tests
    ↓
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PHASE D: OUTPUT (5 phút)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
→ Deliver 4 deliverables
→ NEW: Deliver Build Plan — list skills theo Quality Tier + build method
→ Suggest build order + next steps
→ Flag: skills cần build ngay vs có thể dùng existing skill
→ Flag: Workflow steps nào cần [REVIEW] node (output đi ra external stakeholder)
    ↓
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PHASE F: MKDIR — Hiện thực hóa SOP trên filesystem (BẮT BUỘC)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
→ Đây là bước CUỐI CÙNG, KHÔNG được bỏ qua
→ SOP không có folder = SOP chỉ tồn tại trên giấy, không thể vận hành
→ Thực hiện:
  1. Xác định org path: /[org-root]/[department]/
  2. Tạo folder cho MỖI SOP vừa thiết kế:
     create_sop_folder "[org-root]" "[department]" "[sop-name]"
  3. Kiểm tra: 5 subfolders tồn tại + README.md trong template/
  4. Output MKDIR log: danh sách paths đã tạo
→ Với SOPs đã tồn tại trước → chạy migrate_existing_sop
→ Ghi nhận: Nếu user chưa có org-root path → hỏi 1 câu trước khi tiếp tục
    ↓
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PHASE E: BUILD (BẮT BUỘC — KHÔNG BỎ QUA)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
**BÀI HỌC TỪ AINS: Thiết kế 10 AI workers nhưng 0 SKILL.md → công ty không vận hành.**
**PHASE E = chuyển "thiết kế" thành "callable skills" — BẮT BUỘC.**

→ BẮT BUỘC: Xác định SKILL_SAVE_PATH cho mỗi skill trước khi build:
  - CÓ COMPANY_ROOT → [COMPANY_ROOT]/[department]/ai_workforce/[skill-name]/
  - KHÔNG CÓ → hỏi user trước khi build

→ AUTO-BUILD ALL SKILLS (theo batch):
  Batch 1: Orchestrator/GPS skill (P0)
  Batch 2: Core workers (P1)
  Batch 3: Support workers (P2)

→ For TEMPLATED skills → Write SKILL.md directly (default)
→ For EXPERT-CLONE skills → Invoke /clone-skill-to-vibe-work
  → Specify expert target + domain + quality bar
  → Pipeline: Research → Extract → Build → Refine
→ For GPS-ENHANCED skills → Write SKILL.md + add vibe-gps integration
  → Define vibe-gps trigger points within skill
  → Specify what problem-solving phase to activate
→ For DUAL skills → clone-skill first → then add vibe-gps layer

→ ALWAYS — MỖI SKILL PHẢI CÓ DESCRIPTION CHUẨN (theo công thức 4 thành phần):
  Vì description quyết định 90% triggering accuracy. Skill hay nhưng không trigger = vô dụng.

  ```
  [WHAT]. [TRIGGER]. [EXCLUSION]. [PUSH].
  ```

  **WHAT (Định nghĩa):** `[Động từ sản xuất] + [Output cụ thể] + [Chuẩn/Domain]`
  > Tốt: "Tạo văn bản hành chính tiếng Việt đúng chuẩn NĐ 30, xuất file .docx"
  > Xấu: "Skill hỗ trợ viết văn chuyên nghiệp"

  **TRIGGER (Tín hiệu):** Trộn 4 loại:
  1. A — Từ khóa chuyên ngành: 'công văn', 'tờ trình', 'NĐ 30'
  2. B — Cụm nói tự nhiên: 'soạn văn bản', 'viết công văn gửi Sở X'
  3. C — Biến thể: 'mẫu chuẩn', 'format VB'
  4. D — Tình huống: 'gửi văn bản đi cơ quan nhà nước'
  > Cú pháp: "Kích hoạt khi user đề cập '[A]'; yêu cầu '[B]'; nói '[C]'; trong tình huống [D]"

  **EXCLUSION (Khoanh vùng):**
  > Cú pháp: "KHÔNG dùng cho: [case loại trừ] (→ [skill thay thế nếu có])"

  **PUSH (Chống undertrigger):** Câu CUỐI description — vị trí có trọng lượng cao nhất.
  > Cú pháp: "Dùng cho MỌI [domain] — kể cả khi user chỉ nói '[weak signal]'"

  **Giới hạn:** 80-250 từ. Tránh keyword dump (<40 từ) và quá dài (>300 từ).
  Xem thêm: `resources/description-anti-patterns.md` cho 10 lỗi phổ biến.

→ ALWAYS after building EACH skill:
  1. SAVE SKILL.md to SKILL_SAVE_PATH (PRIMARY — within company folder)
  2. INSTALL: copy to ~/.claude/skills/[skill-name]/
     → mkdir -p ~/.claude/skills/[skill-name]
     → cp -R [SKILL_SAVE_PATH]/* ~/.claude/skills/[skill-name]/
  3. VERIFY: test -f ~/.claude/skills/[skill-name]/SKILL.md
  4. LOG: "[OK] [skill-name] built + installed"
  5. UPDATE [department]/ai_workforce/README.md với skill status
  6. TRIGGER VALIDATION — test description có trigger đúng không:
     → Tạo 3-5 "should trigger" queries (câu lệnh thực tế mà skill phải kích hoạt)
     → Tạo 3-5 "should NOT trigger" queries (câu bẫy — gần giống nhưng thuộc skill khác)
     → Nếu test fail → sửa description theo resources/description-anti-patterns.md
     → Quick check: đọc description rồi tưởng tượng user gõ bằng tiếng Việt thường → có match không?

→ AFTER ALL SKILLS BUILT — SOP-TO-SKILL COVERAGE GATE (BẮT BUỘC):
  1. Liệt kê TẤT CẢ SOPs (từ Phase F + SOP register)
  2. Kiểm tra MỖI SOP có AI Worker skill gán:
     | SOP Code | SOP Name | AI Worker Skill | SKILL.md? | Installed? |
  3. COUNT: Total SOPs / Covered SOPs
  4. IF coverage < 100% → BUILD thêm → re-check → LOOP
  5. IF coverage = 100% → GATE PASS

→ FINAL VERIFICATION:
  → ls ~/.claude/skills/vibe-[company]-* → so với planned workers
  → Output: Build Completion Report
    - Total planned: [N] | Built: [N] | Installed: [N]
    - SOP coverage: [X/Y = Z%]
    - Gaps (if any): [list]
    - REGISTRY EXTRACTION cho mỗi skill (bàn giao):

      ```markdown
      ### [skill-name]
      Mô tả tóm gọn 1 câu.
      💡 **Prompt Mẫu:** *"[Câu ví dụ thực tế để test skill]"*
      ```
      ```text
      [skill-name]/
      ├── SKILL.md
      └── resources/ (if any)
      ```
```

---

## Decision Heuristics

### Chọn complexity level

```
Số steps?
  1-3 → Simple
  4-8 → Medium
  9+  → Complex

Có conditional logic?
  NO  → giữ complexity level
  YES → bump up 1 level

Có external API/tools?
  NO  → giữ complexity level
  YES → bump up 1 level
```

### Khi nào ESCALATE sang human?

```
Always escalate khi:
  - Output ảnh hưởng tới khách hàng thực (email, publish, payment)
  - Confidence thấp (< 80%)
  - Input data ambiguous / missing critical fields
  - Có thể gây hại nếu sai (legal, financial, medical)

Never auto-escalate khi:
  - Internal draft chưa publish
  - Test run với fake data
  - Formatting / cleanup tasks
```

### Khi existing Claude skill có thể reuse?

```
Check trước khi tạo mới:
  - vibe-review      → quality review, output validation, QA gate cho bất kỳ AI output nào
  - vibe-gps         → orchestration, problem solving
  - deep-research    → research tasks
  - vibe-overview    → synthesis, summarization
  - ai-humanizer     → document formatting
  - vibe-user-review → user feedback collection (persona-only, subset của vibe-review)
  - clone-skill-to-vibe-work → khi cần expert-level quality cho skill mới

Chỉ tạo skill mới khi domain/role chưa có coverage.
```

### Khi nào dùng clone-skill-to-vibe-work?

```
Dùng clone-skill khi skill CẦN:
  - Output giống chuyên gia thực (copywriter pro, senior analyst, expert consultant)
  - Có expert benchmark rõ ràng để so sánh (Nancy Duarte cho presentations, Ogilvy cho ads...)
  - Domain knowledge sâu mà AI generic không có (legal review, medical triage, financial modeling)
  - Tacit knowledge cần extract (intuition, muscle memory của expert)

KHÔNG dùng clone-skill khi:
  - Skill chỉ làm task cơ bản (formatting, data entry, scheduling)
  - Rules đã rõ ràng, không cần expert intuition
  - Time constraint < 2h → dùng Quick Mode hoặc TEMPLATED

How to invoke:
  → Trong Phase C, tag skill là EXPERT-CLONE
  → Trong Phase E, invoke: /clone-skill-to-vibe-work
  → Pass context: expert target, domain, quality bar, reference materials
```

### Khi nào dùng vibe-review?

```
Dùng vibe-review (REUSE) thay vì tạo custom reviewer skill khi:
  - Workflow cần quality gate cho output của bất kỳ skill nào
  - Output là text, code, design, document, UI, workflow, data
  - Cần multi-method review (persona + benchmark + rules + expert + tests + UAT)
  - Không cần reviewer logic domain-specific phức tạp

Tạo custom vibe-[domain]-reviewer (build mới) thay vì vibe-review khi:
  - Review cần integrate với internal database/system đặc thù
  - Domain rules rất chuyên biệt mà vibe-review universal rules không cover
    (ví dụ: review hợp đồng pháp lý theo luật Việt Nam, review thuốc theo dược điển)

vibe-review trong workflow design:
  → Dùng node type [REVIEW] để mark bước gọi vibe-review
  → Đặt [REVIEW] node trước bất kỳ output nào đi ra external stakeholder
  → Config threshold: "Quality Score ≥ 75 → pass, < 75 → [LOOP] back"
  → vibe-review --quick cho internal draft, full mode cho final output

vibe-review trong Phase E (Build):
  → Sau khi build bất kỳ skill mới nào → chạy vibe-review trên SKILL.md đó
  → Invoke: vibe-review [SKILL.md content] --method 3  ← Rules check trước
  → Sau đó: vibe-review [sample output] để verify skill hoạt động đúng
```

### Khi nào tích hợp vibe-gps vào skill?

```
Tích hợp vibe-gps khi skill GẶP:
  - Ambiguous decisions không có "đáp án đúng" (strategy, routing, prioritization)
  - Multi-factor analysis cần structured thinking (root-cause, trade-off analysis)
  - Novel situations không covered by rules (edge cases, unexpected inputs)
  - Complex problem-solving cần decomposition (multi-step reasoning)

KHÔNG tích hợp vibe-gps khi:
  - Skill chỉ làm linear tasks với rules rõ ràng
  - Mọi decision path đã được define sẵn trong workflow
  - Overhead của vibe-gps không justified (simple if/then logic)

How to integrate:
  → Tag skill là GPS-ENHANCED
  → Trong SKILL.md, thêm section "GPS Integration Points":
    - Trigger condition: khi nào skill gọi vibe-gps
    - Problem type: loại problem cần solve
    - Expected output: vibe-gps trả về gì cho skill
  → Ví dụ:
    ```
    ## GPS Integration Points

    ### Trigger: When customer complaint doesn't match any known pattern
    → Invoke vibe-gps Problem Clarity (Phase 2)
    → Input: complaint text + customer history
    → Output: Root cause hypothesis + recommended action

    ### Trigger: When pricing strategy needs multi-factor analysis
    → Invoke vibe-gps Isomorphic Solver
    → Input: market data + competitor pricing + cost structure
    → Output: Pricing recommendation with confidence level
    ```
```

---

## Output Examples

### Example 1: Content Marketing Pipeline

**Input:** "Tôi cần quy trình tạo content LinkedIn từ ý tưởng đến publish"

**Output 1 — Project Folder Structure:**
```
linkedin-content-pipeline/
├── 00-overview/README.md
├── 01-inputs/topic-brief-template.md
├── 02-processing/
│   ├── 01-ideation/
│   ├── 02-research/
│   ├── 03-drafting/
│   ├── 04-review/
│   └── 05-scheduling/
├── 03-outputs/published-posts/
├── 04-skills/
│   ├── vibe-linkedin-orchestrator/
│   ├── vibe-linkedin-ideator/
│   ├── vibe-linkedin-researcher/
│   ├── vibe-linkedin-writer/
│   ├── vibe-linkedin-reviewer/
│   └── vibe-linkedin-scheduler/
├── 05-rules/content-rules.md
└── 06-tests/
    ├── automated/schema-check.md
    └── manual/qa-checklist.md
```

**Output 5 — SOP Folder State Machine (Phase F: MKDIR):**
```
org/
└── marketing/
    └── create-linkedin-content/    ← SOP folder
        ├── template/               ← SOURCE OF TRUTH
        │   └── README.md           ← "Do not edit. Copy to input/ first."
        ├── input/                  ← topic briefs chờ xử lý
        ├── processing/
        │   ├── ai-draft/           ← AI đang draft
        │   └── human-review/       ← human đang review
        ├── output/                 ← posts ready to publish (max 7 ngày)
        └── archive/
            └── 2026-05/            ← completed runs
```
```bash
# Phase F: MKDIR command
create_sop_folder "/path/to/org" "marketing" "create-linkedin-content"
```

**Output 2 — Workflow (simplified):**
```
[MKDIR: create_sop_folder "org" "marketing" "create-linkedin-content"]  ← Phase F
      ↓
[START: Topic brief dropped into input/]
      ↓
[STEP 1: Research] — vibe-linkedin-researcher
  Input: input/[date]-brief.md
  Output: processing/ai-draft/[date]-research.md
      ↓
[STEP 2: Draft] — vibe-linkedin-writer
  Input: processing/ai-draft/[date]-research.md
  Output: processing/ai-draft/[date]-draft.md
      ↓
[REVIEW: Quality Gate] — vibe-review --quick
  Threshold: Score ≥ 75
  On Pass → move to processing/human-review/ → STEP 3
  On Fail → [LOOP: back to STEP 2 với Priority Action List] (max 3 loops)
      ↓
[STEP 3: Schedule] — vibe-linkedin-scheduler
  Input: processing/human-review/[date]-approved.md
  Output: output/[date]-post-queued.md
      ↓
[ESCALATE: Human final approval before publish]
  APPROVED ↓       REJECTED → [LOOP: Major revision → REVIEW again]
[AUTO-ARCHIVE: archive_sop_run] ← move output/ → archive/[YYYY-MM]/
      ↓
[END: Post queued + archive record created]
```

**Output 3 — Skills:**
```
6 skills cần build:
P0: vibe-linkedin-orchestrator (build first)
P1: vibe-linkedin-writer, vibe-linkedin-researcher
P2: vibe-linkedin-reviewer, vibe-linkedin-scheduler
P3: vibe-linkedin-ideator
```

**Output 4 — Rules (top 3):**
```
BR-01 [CRITICAL]: Post KHÔNG được publish khi chưa có human approval
BR-02 [HIGH]: Nội dung KHÔNG được claim unverified statistics
QS-01: Readability score ≥ 60 (Flesch-Kincaid)
```

---

### Example 2: Customer Support Workflow

**Input:** "Tôi cần AI handle customer support email từ A-Z"

→ Sinh ra:
- Folder: `customer-support-ai/`
- Skills: `vibe-support-classifier`, `vibe-support-responder`, `vibe-support-escalator`, `vibe-support-tracker`, `vibe-support-orchestrator`
- Workflow: Email received → Classify intent → Route → Draft response → Human review (if sensitive) → Send → Log
- Rules: Never promise refund without human auth, Always respond within 2h SLA

---

## Integration với vibe-gps ecosystem

### Upstream — Gọi vibe-aiworkforce SAU khi:
```
vibe-gps (problem clarity xong → cần build workforce)
vibe-prd-creator (có PRD → cần workforce để execute)
```

### Downstream — Sau khi output xong, user thường gọi:
```
vibe-review (verify chất lượng bất kỳ output/skill nào vừa được tạo ra)
clone-skill-to-vibe-work (để build từng EXPERT-CLONE skill)
vibe-omnifocus (tạo task plan cho build order)
vibe-gps (execute từng skill building task)
```

### Internal Integration — clone-skill-to-vibe-work

**Khi workforce có skills tagged EXPERT-CLONE:**

```
Phase E trigger:
  → Invoke /clone-skill-to-vibe-work
  → Pass parameters:
    - Expert target: "Clone the skill of [expert/domain]"
    - Quality bar: "Output must match [benchmark description]"
    - Reference materials: [any provided samples, docs]
    - Build mode: Quick (2-4h) or Deep (6-10h) based on complexity
  → Pipeline runs: Research → Extract → Build → Refine
  → Output: SKILL.md backed by real expert knowledge
  → Deploy to workforce: place in 04-skills/[skill-name]/

Integration flow:
  vibe-aiworkforce (design + tag EXPERT-CLONE)
    → clone-skill-to-vibe-work (research + extract + build)
      → 9 specialized agents execute pipeline
      → Output: Production-quality SKILL.md
    → vibe-aiworkforce (integrate vào workforce)
    → Test với Rules & Tests đã design
```

### Internal Integration — vibe-gps

**Khi workforce có skills tagged GPS-ENHANCED:**

```
Skill SKILL.md includes vibe-gps integration:

  ## GPS Integration Points

  ### Trigger: [condition]
  → vibe-gps Phase 2: Problem Clarity
  → vibe-gps Phase 3: KEY QUESTION + BOTTLENECK + INVERSION
  → Output: [structured recommendation]
  → Continue skill execution with recommendation

Two integration patterns:

Pattern A: Full vibe-gps as internal step
  → Skill encounters complex decision
  → Invoke vibe-gps Problem Clarity (Phase 2)
  → Invoke vibe-gps KEY QUESTION engine (Phase 3)
  → Get structured recommendation
  → Continue skill flow with recommendation

Pattern B: vibe-gps Isomorphic Solver for stuck situations
  → Skill gets stuck on ambiguous scenario
  → Invoke vibe-gps Isomorphic Solver (6 steps)
  → Find analogical solution from known domain
  → Apply inverse functor back to original problem

When NOT to use vibe-gps internally:
  → Linear steps with clear rules
  → Simple if/then branching
  → Tasks where template is sufficient
```

### Internal Integration — vibe-review

**vibe-review là Quality Gate tích hợp vào mọi workforce có output delivery:**

```
KHI NÀO INTEGRATE:
  → Bất kỳ workflow có bước "tạo ra output đi đến stakeholder/user/system khác"
  → Bất kỳ skill mới vừa được build (verify trước khi deploy)
  → Bước ngay trước [ESCALATE] hoặc [PUBLISH] node

WORKFLOW PATTERN CHUẨN với vibe-review:

  [STEP N: Create Output] — vibe-[domain]-writer/analyst/coder
        ↓
  [REVIEW: Quality Gate] — vibe-review
    → Input: output từ STEP N
    → Config: Quality Score threshold (default: 75/100)
    → Mode: --quick (nội bộ) hoặc full (trước delivery)
        ↓
  [DECISION: Score ≥ threshold?]
    YES ↓                    NO → [LOOP: back to STEP N with feedback]
  [NEXT STEP or ESCALATE]

REVIEW NODE SPECIFICATION (trong Step Details table):
  | Actor       | vibe-review                              |
  | Input       | [Output từ previous step]                |
  | Mode        | [--quick / full / --method X]            |
  | Threshold   | Quality Score ≥ [75/80/90] to pass       |
  | On Pass     | → [Next step]                            |
  | On Fail     | → [LOOP back] với Priority Action List   |
  | Max Loops   | 3 (sau đó ESCALATE to human)             |
```

**vibe-review trong Phase E (Build Verification):**

```
Sau khi build xong bất kỳ skill nào:

1. Quick check SKILL.md:
   → vibe-review [SKILL.md content] --method 3
   → Check: Không có placeholder, rules rõ ràng, không có internal inconsistency

2. Sample output verification:
   → Run skill với sample input → get sample output
   → vibe-review [sample output] --quick
   → Verify: Skill tạo ra output đạt quality threshold

3. Threshold confirmation:
   → Nếu sample output score ≥ 75 → skill ready to deploy
   → Nếu score < 75 → revise SKILL.md, re-test
```

**vibe-review Threshold Guide by Workflow Stage:**

```
Stage                        Threshold  Mode
──────────────────────────────────────────────
Internal draft               60+        --quick
Internal final               75+        --quick
Stakeholder review           80+        full
Client/customer delivery     85+        full
Public publish               90+        full
```

### Combined Integration — EXPERT-CLONE + GPS-ENHANCED

```
Khi skill cần CẢ HAI:

1. clone-skill-to-vibe-work Phase 1-2:
   → Research expert domain knowledge
   → Extract 7 components (philosophy, think model, processes...)
   → Extract expert decision heuristics

2. Build SKILL.md with dual layers:
   → Layer 1: Expert knowledge (from clone-skill extraction)
   → Layer 2: vibe-gps integration points (for ambiguous decisions)
   → Combined: Expert intuition + structured problem-solving

3. clone-skill-to-vibe-work Phase 3-4:
   → Build complete skill
   → Test with real scenarios
   → Refine based on test results
```

---

## Quality Checklist — Trước khi deliver

Trước khi output, self-check:

```
── SKILL STORAGE (BẮT BUỘC) ────────────────────────────────────────────────
□ COMPANY_ROOT đã được xác định trước khi build bất kỳ skill nào?
□ MỌI skills được lưu TRONG company folder (PRIMARY location)?
□ Mỗi skill có symlink từ ~/.claude/skills/ → PRIMARY location?
□ KHÔNG có skill nào chỉ tồn tại ở ~/.claude/skills/ mà không có bản trong company folder?
□ Department ai_workforce/README.md được update sau mỗi skill build?

── WORKFORCE DESIGN ────────────────────────────────────────────────────────
□ Folder structure có đủ 7 folders (00-06)? [chỉ khi standalone, KHÔNG có COMPANY_ROOT]
□ Mỗi workflow step có actor rõ ràng?
□ Có ít nhất 1 DECISION node trong workflow?
□ Có ít nhất 1 ESCALATE node nếu task ảnh hưởng external?
□ Workflow có [REVIEW] node trước mỗi output đi ra external stakeholder?
□ [REVIEW] nodes có chỉ định threshold + mode (--quick / full) + on-fail action?
□ Skill names theo format vibe-[domain]-[role]?
□ Reviewer/QA role đã check reuse vibe-review trước khi tạo custom reviewer skill?
□ Có ít nhất 1 P0 skill (orchestrator)?
□ Rules phân biệt rõ BR (business) vs QS (quality)?
□ Automated tests có thể chạy được mà không cần human?
□ Manual tests có pass condition rõ ràng?
□ Build order theo dependency (P0 trước P1 trước P2)?
□ Mỗi skill có Quality Tier tag (TEMPLATED / EXPERT-CLONE / GPS-ENHANCED)?
□ EXPERT-CLONE skills có chỉ định expert target / benchmark?
□ GPS-ENHANCED skills có GPS Integration Points defined?
□ Build Plan list đầy đủ build method cho mỗi skill?
□ Phase E plan bao gồm vibe-review verification sau mỗi skill build?
□ Mỗi skill description có đủ 4 thành phần (WHAT/TRIGGER/EXCLUSION/PUSH)?
□ Description trong khoảng 80-250 từ, không keyword dump, không quá dài?
□ TRIGGER có đủ 4 loại (A: thuật ngữ, B: nói tự nhiên, C: đồng nghĩa, D: ngữ cảnh)?
□ PUSH câu cuối có "Dùng cho MỌI" và weak signal example?
□ EXCLUSION có chỉ định skill thay thế?
□ Trigger Validation đã chạy (should trigger / should NOT trigger queries)?
□ Build Completion Report có Registry Extraction cho mỗi skill?

── Quality Control (MỚI) ──────────────────────────────────────────────
□ Phase A có Quality Standards Analysis (SLI/SLO/SLA) cho task?
□ Mỗi SLI là quantifiable (không "tốt", "chất lượng", "đẹp")?
□ SLO targets có error budget (không target 100% cho operational)?
□ SLA (nếu có external stakeholder) LESS strict hơn SLO?
□ Workflow có [QUALITY GATE] node trước mỗi output đi ra external?
□ Workflow có [INCIDENT] node khi quality gate fail 3+ times?
□ Rules & Tests có Quality Standards table với SLI/SLO/SLA?
□ Rules & Tests có Error Budget tracking?
□ Rules & Tests có Incident Management triggers?
□ _rules/README.md có Quality Standards + Incident History sections?
□ Prevention measures defined cho steps có risk cao?
□ Incident Report template có 5 Whys/Fishbone + Root Cause + Prevention?
□ Blameless principle được ghi nhận (process fail, not people fail)?

── OKR / KRI / KPI Alignment (MỚI) ──────────────────────────────────
□ Phase A có OKR/KRI/KPI alignment analysis?
□ Mỗi skill biết "task này contribute vào OKR/KRI nào"?
□ Skills gắn với KRI có output measurable?
□ Skills gắn với KPI có performance tracking?
□ Report skills respect tần suất: Daily=KPI, Weekly=KPI+KRI, Monthly=KRI+OKR, Quarterly=OKR full?
□ _knowledge/README.md có OKR + KRI + KPI reference?
□ KWSR _knowledge/ có OKR Alignment Map?

── SOP Folder Structure (State Machine) ──────────────────────────────────────
□ Phase F: MKDIR đã được thực hiện cho MỌI SOP vừa tạo?
□ Mỗi SOP folder có đủ 5 subfolders: template/, input/, processing/, output/, archive/?
□ processing/ có 2 subfolder: ai-draft/ và human-review/?
□ template/ có README.md với convention "Do not edit directly"?
□ Folder naming: lowercase kebab-case, format [verb]-[noun]-[context]?
□ Org structure: /[department]/[sop-name]/ — department đúng không?
□ Input file naming convention đã được document: [YYYY-MM-DD]-[descriptor].ext?
□ Workflow có [AUTO-ARCHIVE] node trước [END] nếu có output/?
□ SOPs hiện tại đã được migrate (nếu là cải tiến workforce có sẵn)?
```

---

## Anti-patterns — Không làm

```
❌ Lưu skill ở ~/.claude/skills/ mà KHÔNG có bản trong company folder → mất khi chuyển máy
❌ Build skill mà KHÔNG biết COMPANY_ROOT → skill nằm rải rác, khó share + maintain
❌ CHỈ TẠO PROFILE/DESIGN mà KHÔNG BUILD SKILL.MD → workers chỉ tồn tại trên giấy, không gọi được (bài học AINS: 10 profiles, 0 callable skills)
❌ Phase E là "optional" → KHÔNG — Phase E BẮT BUỘC, không build = không vận hành
❌ Build xong KHÔNG INSTALL vào ~/.claude/skills/ → skill tồn tại nhưng không gọi được từ CLI
❌ KHÔNG chạy SOP-to-Skill Coverage Gate → có SOP nhưng không có AI worker execute
❌ Build skills theo 1-by-1 manual → auto-batch build tất cả workers theo priority
❌ Tạo project folder riêng (04-skills/) khi đã có company folder → duplicate + confuse
❌ Không tạo symlink sau khi build skill → skill không gọi được từ CLI
❌ Tạo skill quá generic ("vibe-helper", "vibe-assistant") → không có role rõ ràng
❌ Một skill làm quá nhiều việc → vi phạm Single Responsibility
❌ Workflow không có error handling / escalation path
❌ Workflow deliver output ra external mà không có [REVIEW] node → không có quality gate
❌ Rules không có severity level → không biết ưu tiên enforce cái nào
❌ Tests chỉ có happy path → không cover edge cases
❌ Tạo skill mới khi existing skill đã làm được (vibe-review, vibe-gps, deep-research, etc.)
❌ Tạo custom reviewer skill khi vibe-review đã cover use case → unnecessary duplication
❌ Không có orchestrator → agents hoạt động rời rạc, không phối hợp
❌ Dùng clone-skill cho mọi skill → overkill cho simple tasks, lãng phí 6-10h
❌ Dùng vibe-gps cho linear steps → thêm complexity không cần thiết
❌ Tag EXPERT-CLONE nhưng không chỉ định expert benchmark → clone vào hư không
❌ Tag GPS-ENHANCED nhưng không define GPS Integration Points → skill không biết khi nào gọi vibe-gps
❌ Build all skills cùng lúc → nên build theo priority (P0 TEMPLATED trước → P1 EXPERT-CLONE sau)
❌ Build skill xong mà không verify với vibe-review → không biết skill có work đúng không

── Description Anti-patterns ──────────────────────────────────────────────────
❌ Description dưới 40 từ (keyword dump) → trigger rate < 30%
❌ TRIGGER chỉ có từ khóa chuyên ngành → miss 70% cách nói tự nhiên
❌ EXCLUSION không chỉ skill thay thế → Claude không biết route đi đâu
❌ Thiếu câu PUSH ở cuối → Claude undertrigger 40-50%
❌ PUSH dùng "có thể" thay vì "Dùng cho MỌI" → Claude skip skill
❌ Description > 300 từ → tốn context, loãng tín hiệu
❌ Description mô tả "bên trong có gì" thay vì "khi nào dùng"
❌ Không test trigger với 3-5 câu user thật → không biết trigger có work

── Quality Control Anti-patterns ──────────────────────────────────────────
❌ Workflow KHÔNG có quality gate trước output external → output có thể sai không ai biết
❌ SLI dùng metric mơ hồ ("chất lượng tốt") → phải quantifiable
❌ Target 100% cho mọi SLI → unrealistic, giết innovation
❌ Chỉ detect lỗi, KHÔNG prevent → Prevention (Eliminate/Substitute) luôn ưu tiên hơn Detection
❌ Incident xảy ra nhưng KHÔNG tạo Incident Report → mất learning, lặp lại lỗi
❌ RCA dừng ở surface cause → phải đào 5 Whys đến root cause hệ thống
❌ Incident Report blame cá nhân → phải blame process/system
❌ Same error ≥ 3 lần nhưng KHÔNG update SOP → process vẫn cho phép lỗi
❌ _rules/ không có Incident History → mất institutional memory về quality failures
❌ Workflow có [INCIDENT] node nhưng không có RCA method → chỉ log, không học
❌ SLA strict hơn SLO → ngược nguyên tắc, mất buffer

── SOP Folder Anti-patterns ──────────────────────────────────────────────────
❌ Tạo SOP mà không tạo folder → SOP chỉ tồn tại trên giấy, không vận hành được
❌ Bỏ qua Phase F: MKDIR → "sẽ tạo folder sau khi SOP ổn định" = không bao giờ làm
❌ Chỉnh sửa file trong template/ trực tiếp → Single Source of Truth bị nhiễm
❌ Để output/ chất đống không archive → không có historical record, không thể audit
❌ Đặt tên folder có spaces hoặc uppercase → AI agent parse lỗi, human khó scan
❌ Dùng flat structure (mọi SOP cùng 1 folder) khi > 5 SOPs → không scale
❌ Không có ai-draft/ và human-review/ trong processing/ → không rõ file đang ở giai đoạn nào
❌ Không migrate SOPs hiện tại → 2 hệ thống tồn tại song song → inconsistency
❌ Tạo thêm subfolder tùy tiện (vd: temp/, misc/, wip/) → phá vỡ state machine convention
```

---

*Living skill. Update sau mỗi workforce được deploy.*
*"Mỗi task là một bộ máy — AI là nhân sự, Skill là con người số."*

## Resources

| File | Mục đích | Khi nào đọc |
|------|---------|------------|
| `resources/description-anti-patterns.md` | 10 lỗi phổ biến khi viết description | Phase E — sau khi viết description cho mỗi skill |