ai-developer-skill-os 7.5.0 → 8.1.4

package/.agents/CHANGELOG.md

@@ -14,7 +14,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed (The "Anti-Slop & Zero-Trust" Architecture Upgrade)
 - **Zero-Trust Logic**: Core logic skills (`qk-context-loader`, `qk-orchestrator`, `qk-feature-delivery`) now mandate a Topological Context Graph prior to any code generation.
-- **Strict Design Contract**: Frontend skills (`qk-ui-system-builder`, `qk-design-to-code`, `qk-ui-audit`) now explicitly reject generic styling (slop) and enforce strict token matching against a mandated `DESIGN.md`.
+- **Strict Design Contract**: Frontend skills (`qk-ui-system-builder`, `qk-ui-builder`, `qk-ui-audit`) now explicitly reject generic styling (slop) and enforce strict token matching against a mandated `DESIGN.md`.
 - **Repair Loop Enforcement**: `qk-bug-resolution` updated to strictly prohibit jumping to fixes without explicitly establishing an `Observe -> Hypothesis -> Evidence` chain.
 - **Contract-First APIs**: `qk-api-lifecycle` now requires explicit OpenAPI/Swagger definitions prior to endpoint implementation.
 - **Upgraded Testing Framework**: Fixed regex and validation logic in `behavior-conformance.test.js` to rigorously support YAML array strings and precise V7 markdown constraints. All 22 skills bumped to `v7.0.0`.
@@ -67,3 +67,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added detailed user documentation in `docs/HUONG_DAN_SU_DUNG.md` and `docs/CHI_TIET_SKILLS.md`.
 - Translated all skill frontmatter descriptions to Vietnamese for better UX in agent terminals.
 - Included generic English and Vietnamese usage examples in `_template/examples/`.
+

package/.agents/README.md

@@ -1,6 +1,6 @@
-# 🚀 AI Developer Skill OS (ai-developer-skill-os) v7.0.0
+# 🚀 AI Developer Skill OS (ai-developer-skill-os) v7.5.0
 
-> **V7.0.0 "Anti-Slop & Zero-Trust Architecture"**
+> **V7.5.0 "Anti-Slop & Zero-Trust Architecture"**
 
 Hệ sinh thái AI Developer Skill OS đã được tái cấu trúc hoàn toàn. Thay vì cung cấp các "công cụ rời rạc" (Toolbox), phiên bản V7 được thiết kế như một **Hệ điều hành khép kín, hoạt động theo kỷ luật của một Kiến trúc sư Hệ thống (50 năm kinh nghiệm)**.
 
@@ -21,31 +21,71 @@ Bảo vệ mã nguồn khỏi thói quen "sửa vội" của AI. Lỗi bắt bu
 
 ---
 
-## 🧩 Danh sách 23 Master Skills
+## 🧩 Danh sách 22 Master Skills
 
 Các kỹ năng được quản lý cực kỳ chặt chẽ với bài kiểm tra tự động (Vitest) để đảm bảo tính nhất quán của luật lệ:
-- **Orchestration:** `qk-orchestrator`, `qk-context-loader`, `qk-policy-engine`, `qk-access-policy`
-- **Engineering / Dev:** `qk-feature-delivery`, `qk-api-lifecycle`, `qk-fe-api-integration`, `qk-data-lifecycle`, `qk-design-to-code`, `qk-ui-system-builder`
+- **Orchestration:** `qk-orchestrator`, `qk-context-loader`, `qk-access-policy`
+- **Engineering / Dev:** `qk-feature-delivery`, `qk-api-lifecycle`, `qk-fe-api-integration`, `qk-data-lifecycle`, `qk-ui-builder`, `qk-ui-system-builder`
 - **Validation & Standards:** `qk-validation-gate`, `qk-engineering-standard`, `qk-ui-audit`, `qk-project-health`, `qk-bug-resolution`
 - **Ops & AI:** `qk-system-evolution`, `qk-production-release`, `qk-ai-builder`, `qk-project-bootstrap`
-- **Docs & Utils:** `qk-docs`, `qk-project-memory`, `qk-help`
+- **Docs & Utils:** `qk-docs`, `qk-project-memory`, `qk-help`, `qk-db-optimizer`
 
 ---
 
 ## 💻 Cách Cài Đặt (Installation)
 
-Sử dụng npm:
+### Cách 1: NPM Global (Khuyên dùng cho nhiều máy)
 ```bash
 npm i -g ai-developer-skill-os
 ```
-Hoặc khởi tạo thông qua `npx`:
+
+### Cách 2: NXP (Không cần cài global)
+```bash
+npx ai-developer-skill-os init --ide=antigravity --scope=2
+```
+
+### Cách 3: NPM Scripts (Trong dự án)
 ```bash
-npx ai-developer-skill-os init
+# Antigravity Global — 1 lần cài, mọi dự án dùng chung
+npm run install:antigravity
+
+# Antigravity Local — cài riêng cho dự án này
+npm run install:antigravity:local
+
+# Các IDE khác
+npm run install:cursor        # Global Cursor
+npm run install:windsurf      # Global Windsurf
+npm run install:claude        # Global Claude Code
+npm run install:kilo          # Global Kilo Code
+npm run install:multi         # Multi-IDE
+```
+
+## 📦 Tham số cho `init`
+
+| Tham số | Giá trị | Mô tả |
+|---------|---------|-------|
+| `--ide` | `antigravity`, `cursor`, `windsurf`, `claude`, `kilo`, `multi-ide` | IDE/AI Assistant |
+| `--scope` | `1` = Local, `2` = Global | Phạm vi cài đặt |
+
+### Ví dụ thực tế
+
+```bash
+# Cài Antigravity Global (toàn máy)
+npx ai-developer-skill-os init --ide=antigravity --scope=2
+
+# Cài Antigravity Local (chỉ dự án này)
+npx ai-developer-skill-os init --ide=antigravity --scope=1
+
+# Cài Cursor Local
+npx ai-developer-skill-os init --ide=cursor --scope=1
+
+# Cài Multi-IDE (tạo CLAUDE.md + .qk-ai-skill-os)
+npx ai-developer-skill-os init --ide=multi-ide --scope=2
 ```
 
 ## 🧪 Testing
 
-Hệ thống được bảo vệ bằng bộ Test Suite (Vitest) để tự động kiểm toán tính hợp lệ của toàn bộ 23 file Kỹ năng trước khi xuất bản:
+Hệ thống được bảo vệ bằng bộ Test Suite (Vitest) để tự động kiểm toán tính hợp lệ của toàn bộ 22 file Kỹ năng trước khi xuất bản:
 
 ```bash
 npm test
@@ -57,3 +97,4 @@ npm test
 ```bash
 ./qk-help
 ```
+

package/.agents/docs/ARCHITECTURE.md

@@ -0,0 +1,156 @@
+# AI Developer Skill OS — V8 Architecture
+
+## Source of Truth
+
+> [!IMPORTANT]
+> The **only** editable skill metadata source is: `.agents/skills/**/SKILL.md`
+>
+> All other manifests are **generated artifacts** — manual modification is prohibited.
+
+| File | Editable? | Generated from |
+|---|---|---|
+| `.agents/skills/*/SKILL.md` | ✅ YES | — (source) |
+| `.agents/registry/skills-index.yml` | ❌ NO | `tooling/generate-registry.js` |
+| `skills.json` | ❌ NO | `tooling/generate-registry.js` |
+
+Regenerate after any SKILL.md change:
+```bash
+node tooling/generate-registry.js
+```
+
+---
+
+## Request Flow
+
+```
+User / Calling Agent
+        │
+        ▼
+   AGENTS.md               ← Entry point. Read this first.
+        │
+        ▼
+ registry/skills-index.yml ← Find candidate skills by task keywords
+        │
+        ▼
+  skills/qk-*/SKILL.md     ← Confirm intent, preconditions, complexity
+        │
+        ├── rules: [global, coding, safety]   ← Load relevant rules
+        │
+        ├── workflow: bug-resolution          ← Load execution pipeline
+        │
+        └── verification: strategy           ← Know how to verify
+                │
+                ▼
+        Execute workflow steps
+                │
+                ▼
+        Exit with: SUCCESS | BLOCKED | FAILED | PARTIAL
+                │
+                ▼
+        learnings/ ← (human) Document lessons learned
+```
+
+---
+
+## Domain Map
+
+| Domain | Path | Question Answered | Owner |
+|---|---|---|---|
+| Rules | `.agents/rules/` | How should agent behave? | Architect |
+| Workflows | `.agents/workflows/` | What sequence to follow? | Architect |
+| Skills | `.agents/skills/` | What can agent do? | Skill author |
+| Examples | `.agents/examples/` | What does good output look like? | Human |
+| Learnings | `.agents/learnings/` | What lessons are validated? | Human |
+| Registry | `.agents/registry/` | Which skill for this task? | Generated |
+
+---
+
+## Skill Anatomy (V8)
+
+```
+SKILL.md
+├── frontmatter (YAML)
+│   ├── Identity: name, version, description
+│   ├── Classification: type, intent, triggers, complexity
+│   ├── References: workflow, rules, tools, related_skills
+│   ├── Verification: required, strategy
+│   └── Runtime: execution_mode, token_budget, exit_codes
+│
+└── body (Markdown)
+    ├── Preconditions
+    ├── Scope (✅ does / ❌ does not)
+    └── Output Format
+```
+
+The skill body contains **what** and **when**. The referenced **workflow** contains **how**.
+
+---
+
+## Retrieval Path (AI-Native)
+
+When given a task, the agent MUST:
+
+```
+1. Read registry/skills-index.yml
+   → triggers matching → candidate_skills[]
+
+2. Read candidate SKILL.md(s)
+   → confirm intent + preconditions met?
+   → if BLOCKED: ask user for missing info
+
+3. Load workflow YAML
+   → understand step inputs/outputs
+
+4. Load referenced rules (global.md always, coding.md if edit_files)
+
+5. Execute step by step
+   → each step: check inputs → execute → verify outputs
+
+6. Exit with code + report
+```
+
+**Do NOT:**
+- Load all 22 skills at once
+- Read entire files without targeted grep first
+- Proceed without verifying preconditions
+
+---
+
+## Knowledge Lifecycle
+
+```
+Observation (agent)
+      ↓
+Draft Learning (auto-created on FAILED exit)
+      ↓
+Human Review
+      ↓
+Validated Learning (human promotes with evidence)
+      ↓
+Referenced in Skill / Workflow
+      ↓
+Deprecated (when superseded by newer evidence)
+```
+
+---
+
+## Versioning Summary
+
+See [VERSIONING.md](./VERSIONING.md) for full policy.
+
+| Change Type | Version Bump |
+|---|---|
+| Breaking schema change | Major (8.x.x → 9.0.0) |
+| New skill / workflow | Minor (8.0.x → 8.1.0) |
+| Fix typo / improve description | Patch (8.0.0 → 8.0.1) |
+
+---
+
+## File Conventions
+
+| Pattern | Purpose |
+|---|---|
+| `_schema.yml` | Schema definition (not a skill/workflow) |
+| `README.md` in empty dirs | Placeholder + instructions |
+| `ADR-NNN-*.md` | Architecture Decision Record |
+| `[validated]` in git message | Promotes draft learning to validated |

package/.agents/docs/CHI_TIET_SKILLS.md

@@ -40,7 +40,7 @@ Dưới đây là danh sách chi tiết và giải thích cụ thể cho toàn b
 - **Mô tả:** Quản lý Design Token, tạo ra các Component có thể tái sử dụng (Button, Table, Form) đảm bảo tính nhất quán toàn dự án.
 - **Khi nào dùng:** Xây dựng thư viện giao diện, tránh viết CSS lộn xộn.
 
-### 8. `qk-design-to-code` (Chuyển Đổi Thiết Kế)
+### 8. `qk-ui-builder` (Chuyển Đổi Thiết Kế)
 - **Mô tả:** Đọc hiểu hình ảnh/Figma để tự động chuyển thành mã nguồn giao diện (React, Tailwind, v.v.).
 - **Khi nào dùng:** Bóc tách UI từ bản thiết kế.
 
@@ -123,3 +123,4 @@ Dưới đây là danh sách chi tiết và giải thích cụ thể cho toàn b
 ### 22. `qk-help` (Tra Cứu Nhanh)
 - **Mô tả:** Cuốn từ điển sống. Cung cấp thông tin và hướng dẫn chi tiết (Pro-tips) về cách sử dụng toàn bộ hệ thống.
 - **Khi nào dùng:** Bất kỳ khi nào người dùng cần hỗ trợ sử dụng hệ điều hành.
+

package/.agents/docs/MIGRATION-CLEANUP-V8.1.3.md

@@ -0,0 +1,36 @@
+# V8.1.3 Repository Cleanup Record
+
+## Objective
+
+Remove V7 legacy artifacts and establish
+V8 Control Plane as single source of truth.
+
+## Removed
+
+- `/skills`
+- `/skills.json`
+- `/.agents/skills.json`
+
+## Archived
+
+- `tests/agent-evaluation` legacy markdown cases
+
+## New Authority
+
+Skill metadata:
+
+`.agents/skills/*/SKILL.md`
+
+Registry:
+
+`.agents/registry/`
+
+Generated:
+
+- `skills-index.yml`
+- `capability-graph.yml`
+
+## Verification
+
+- `npm run test:agent`
+- `npm run test:graph`

package/.agents/docs/MIGRATION-STATUS.md

@@ -0,0 +1,35 @@
+# V8 Migration Status
+
+| Skill | Version | Status | Workflow |
+|---|---|---|---|
+| qk-orchestrator | 8.0.0 | stable | internal |
+| qk-bug-resolution | 8.0.0 | stable | bug-resolution |
+| qk-context-loader | 8.0.0 | stable | internal |
+| qk-feature-delivery | 8.0.0 | stable | feature-delivery |
+| qk-validation-gate | 8.0.0 | stable | code-review |
+| qk-engineering-standard | 8.0.0 | stable | code-review |
+| qk-project-memory | 8.0.0 | stable | documentation |
+| qk-project-health | 8.0.0 | stable | code-review |
+| qk-system-evolution | 8.0.0 | stable | refactor |
+| qk-docs | 8.0.0 | stable | documentation |
+| qk-api-lifecycle | 8.0.0 | stable | feature-delivery |
+| qk-fe-api-integration | 8.0.0 | stable | feature-delivery |
+| qk-data-lifecycle | 8.0.0 | stable | feature-delivery |
+| qk-ui-builder | 8.0.0 | stable | feature-delivery |
+| qk-ui-system-builder | 8.0.0 | stable | feature-delivery |
+| qk-ui-audit | 8.0.0 | stable | code-review |
+| qk-db-optimizer | 8.0.0 | stable | refactor |
+| qk-access-policy | 8.0.0 | stable | feature-delivery |
+| qk-production-release | 8.0.0 | stable | internal |
+| qk-project-bootstrap | 8.0.0 | stable | feature-delivery |
+| qk-ai-builder | 8.0.0 | stable | feature-delivery |
+| qk-help | 8.0.0 | deprecated | internal |
+| qk-frontend-architecture | 8.1.0 | experimental | feature-delivery |
+| qk-design-system-engineering | 8.1.0 | experimental | feature-delivery |
+| qk-web-quality-gate | 8.1.0 | experimental | feature-delivery |
+| qk-test-engineering | 8.1.0 | experimental | feature-delivery |
+| qk-security-audit | 8.1.0 | experimental | security-audit |
+| qk-product-specification | 8.1.0 | experimental | spec-driven-development |
+
+Progress:
+22/22 stable, 6 experimental, 1 deprecated

package/.agents/docs/MIGRATION-V8.md

@@ -0,0 +1,10 @@
+# V8 Migration Protocol
+
+Every migrated skill MUST meet the following criteria before being marked as `status: stable`:
+
+- [ ] **Preserve original capability**: Do not alter the core instructions and behavior of the skill unless fixing bugs.
+- [ ] **Add V8 frontmatter**: Update the frontmatter strictly according to `_template/SKILL.md`.
+- [ ] **Map workflow**: Ensure `workflow` references an existing V8 workflow (e.g. `feature-delivery`, `bug-resolution`, `code-review`).
+- [ ] **Define verification**: Include the `verification` block with a valid `strategy`.
+- [ ] **Define selection**: Include the `selection` block with `priority` and appropriate `confidence_threshold`.
+- [ ] **Generate registry successfully**: Must pass schema validation in `node tooling/validate-skills.js` and `node tooling/generate-registry.js` without warnings.

package/.agents/docs/ROADMAP-V8.2.md

@@ -0,0 +1,78 @@
+# V8.2 Roadmap: Adaptive Agent OS
+
+## Triết lý cốt lõi (Core Philosophy)
+**Self Improving = Self Optimizing, NOT Self Modifying.**
+Hệ thống chuyển mình từ "Governed Capability Graph" sang "Decision Intelligence Layer" với khả năng "học từ vận hành" thông qua:
+```
+Observe -> Analyze -> Recommend -> Human Approval -> Controlled Evolution
+```
+
+---
+
+## 4 Ranh giới Anti-Pattern (Boundaries)
+Để tránh lặp lại sự phình to không kiểm soát, V8.2 thiết lập 4 rào cản tuyệt đối:
+
+### Boundary 1 — Skill Inflation
+- Giữ nguyên giới hạn 30 capabilities.
+- KHÔNG tạo các skill như `qk-react-performance`, `qk-nextjs-specialist`. Những kỹ năng này thuộc **Knowledge Layer** (kiến thức tham khảo), không phải **Decision Capability Layer**.
+
+### Boundary 2 — Frontend Fragmentation
+- Giữ vững cấu trúc: `qk-frontend-architecture` -> `delegates_to` -> `qk-ui-builder`.
+- KHÔNG chia nhỏ frontend thành: `component`, `hooks`, `css`, `state`. Điều này sẽ phá vỡ boundary ra quyết định.
+
+### Boundary 3 — Graph Complexity
+- Chỉ giữ 5 loại relations cốt lõi (phục vụ Decision): `depends_on`, `conflicts_with`, `delegates_to`, `implemented_by`, `feeds`.
+- KHÔNG thêm các quan hệ Semantic mờ nhạt (như `related_to`, `similar_to`) biến graph thành Knowledge Map.
+
+### Boundary 4 — Agent Authority
+- **Agent được phép**: observe, measure, recommend, simulate.
+- **Agent KHÔNG được phép**: modify stable skill, change schema, promote itself, rewrite governance.
+
+---
+
+## Lộ trình 4 Phase (V8.2 Execution Phases)
+
+### Phase 1 — Decision Memory (Ưu tiên số 1)
+Thu thập dữ liệu làm nền tảng cho Adaptive Routing.
+- Cấu trúc `decision_record`: Lưu trữ `input`, `candidates`, `selected`, `rejected`, `reason`, `confidence`, `human_feedback`.
+- Ghi nhớ "Vì sao chọn Skill này? Vì sao loại Skill kia?" để Agent có thể phân tích pattern.
+
+### Phase 2 — Skill Analytics
+Đánh giá sức khỏe của từng Capability thông qua công thức đa chiều:
+```yaml
+skill_health:
+  quality_score
+  usage_score
+  conflict_score
+  freshness_score
+  overall_score
+```
+*Lưu ý: Không chỉ đánh giá dựa trên tần suất sử dụng (usage), vì có những skill quan trọng nhưng ít gọi (như security).*
+
+### Phase 3 — Adaptive Routing
+Chuyển đổi từ đánh giá tĩnh sang động (với trọng số).
+- `dynamic score = intent_match + boundary_fit + historical_success + human_feedback`
+- **Ràng buộc tối thượng**: `Decision Boundary > Ranking Score`. Dù Score cao đến đâu, nếu vi phạm Boundary vẫn phải bị loại (Reject).
+
+### Phase 4 — Human Feedback Loop
+Thu thập phản hồi từ người dùng (Human correction).
+- **Khóa an toàn**: Human Feedback chỉ đóng vai trò là `routing signal` (tín hiệu định tuyến), không được phép trực tiếp thay đổi/đột biến (mutation) logic của Skill.
+
+---
+
+## Tầm nhìn V8.3+: Enterprise Multi-Agent (Deferred Domains)
+Các lĩnh vực dưới đây được khóa lại và không phát triển trong V8.2:
+1. **Product Management (`qk-product-strategy`)**: Ưu tiên, roadmap, market, user.
+2. **Backend Architecture (`qk-backend-architecture`)**: Phân định service boundary, architecture style, scalability.
+3. **Cloud Architecture (`qk-cloud-architecture`)**: AWS/GCP/Azure, networking, cost.
+4. **AI Engineering (`qk-ai-engineering`)**: Quản trị AI system, LLM architecture, RAG, prompt evaluation.
+
+---
+
+## Non-Goals
+V8.2 will NOT:
+- create autonomous skill generation
+- modify stable capabilities automatically
+- replace human architecture review
+- optimize only for usage frequency
+- increase skill count without new decision boundary

package/.agents/docs/V8-CERTIFICATION.md

@@ -0,0 +1,27 @@
+# V8 Certification
+
+V8 preserves validated V7 knowledge while introducing structured retrieval, workflow reuse, verification contracts, and lifecycle management.
+
+Skills:
+22/22 stable
+
+Registry:
+generated
+
+Schema:
+validated
+
+Legacy:
+0
+
+Retrieval tests:
+PASS
+
+Workflow tests:
+PASS
+
+Ambiguity:
+PASS
+
+Migration:
+completed

package/.agents/docs/VERSIONING.md

@@ -0,0 +1,95 @@
+# Versioning Policy — AI Developer Skill OS V8
+
+## Semantic Versioning: `MAJOR.MINOR.PATCH`
+
+Current: `8.0.0`
+
+### Bản đồ Kiến trúc các Phiên bản
+
+| Version | Identity                  | Architecture                               |
+| ------- | ------------------------- | ------------------------------------------ |
+| V7      | Prompt Collection         | Static instructions                        |
+| V8.0    | Skill System              | Structured capabilities                    |
+| V8.1.x  | Governed Capability Graph | Decision boundaries + lifecycle governance |
+| V8.2    | Adaptive Agent OS         | Analytics + feedback + adaptive routing    |
+
+---
+
+## When to bump each segment
+
+### MAJOR (8.x.x → 9.0.0)
+Breaking changes that require skill/workflow authors to update their files.
+
+```
+✅ Examples:
+- Removing or renaming a required frontmatter field
+- Changing the schema of workflow steps (removing inputs/outputs)
+- Changing exit_codes semantics
+- Architecture restructure that changes file paths
+```
+
+**Gate:** Requires ADR + announcement. All existing skills must be migrated.
+
+---
+
+### MINOR (8.0.x → 8.1.0)
+Backward-compatible additions.
+
+```
+✅ Examples:
+- Adding a new skill
+- Adding a new workflow
+- Adding a new optional frontmatter field
+- Adding a new rule to rules/
+- Adding a new example or validated learning
+```
+
+**Gate:** No migration required. Existing skills remain valid.
+
+---
+
+### PATCH (8.0.0 → 8.0.1)
+Backward-compatible fixes and improvements.
+
+```
+✅ Examples:
+- Fixing a typo in SKILL.md body
+- Improving description or explanation
+- Adding an example to an existing skill
+- Updating triggers list with additional keywords
+- Fixing a broken link in docs
+```
+
+**Gate:** No review required. Direct commit.
+
+---
+
+## Who can bump versions?
+
+| Type | Who | Process |
+|---|---|---|
+| MAJOR | Architect (human) | ADR + PR + migration plan |
+| MINOR | Skill author | PR with description |
+| PATCH | Anyone | Direct commit OK |
+
+---
+
+## Registry versioning
+
+`registry/skills-index.yml` is a **generated file**. Its version tracks the knowledge system version, not the registry format.
+
+It is regenerated whenever any SKILL.md is modified. **Never manually edit it.**
+
+---
+
+## Learning lifecycle versioning
+
+Learnings do not follow semver. They follow a lifecycle:
+
+```
+draft/ → validated/ → deprecated/
+```
+
+- `draft/`: Created automatically or by human. Not yet reviewed.
+- `validated/`: Requires human commit with `[validated]` in message + evidence field filled.
+- `deprecated/`: Superseded by newer evidence. Keep for historical reference.

package/.agents/docs/decisions/ADR-001-v8-migration.md

@@ -0,0 +1,58 @@
+# ADR-001: V8 Architecture Migration Strategy
+
+**Date:** 2026-07  
+**Status:** Accepted  
+**Deciders:** Quang Khánh
+
+---
+
+## Context
+
+V7 (7.5.1) had 22 skills, each a monolithic SKILL.md containing:
+- Routing logic
+- Execution workflow
+- Verification steps
+- Rules and policies
+
+This made skills hard to reuse, workflows inconsistent across skills, and AI agents often confused about which skill to choose.
+
+---
+
+## Decision
+
+Migrate to V8 **Agent Knowledge System** using **Structured Monolith** approach:
+
+1. **Keep skills** — don't split SKILL.md into multiple files
+2. **Add schema** — new frontmatter fields (intent, triggers, workflow ref, verification)
+3. **Extract workflows** — move execution pipelines to shared `workflows/*.yml`
+4. **Extract rules** — move global policies to `rules/*.md`
+5. **Add registry** — generated `registry/skills-index.yml` for AI retrieval
+
+---
+
+## Rationale
+
+**Why not split SKILL.md into separate files?**  
+- Migration cost too high (22 skills × 4 extractions = 88 operations)
+- Risk of losing embedded knowledge in the split
+- Structured Monolith achieves the same retrieval benefit via references
+
+**Why pilot 5 skills first?**  
+- Schema may need adjustment based on real agent behavior
+- Safer to validate on 5 before committing to 22
+
+**Why keep git history instead of `archive/` folder?**  
+- V7.5.1 tagged at git → complete history available
+- Archive folder in repo creates noise for AI agents
+- Clean break is cleaner than carrying historical artifacts
+
+---
+
+## Consequences
+
+- ✅ Workflows are now reusable (shared across skills)
+- ✅ AI retrieval is faster (registry index)
+- ✅ Rules are explicit and non-duplicated
+- ✅ Verification is mandatory and standardized
+- ⚠️ New schema requires migration of all 22 skills (3 weeks)
+- ⚠️ `skills.json` is now generated, not authoritative

package/.agents/docs/decisions/ADR-002-workflow-separation.md

@@ -0,0 +1,50 @@
+# ADR-002: Workflow Separation from Skills
+
+**Date:** 2026-07  
+**Status:** Accepted
+
+---
+
+## Context
+
+In V7, each SKILL.md contained its own workflow embedded in the body. This meant:
+- Workflow for bug-fixing existed in `qk-bug-resolution/SKILL.md`
+- Similar steps were duplicated across multiple skills
+- No way to reuse or compose workflows
+
+---
+
+## Decision
+
+Extract workflows into dedicated `workflows/*.yml` files. Skills reference workflows by name:
+
+```yaml
+# In SKILL.md frontmatter:
+workflow: bug-resolution  # → workflows/bug-resolution.yml
+```
+
+Each workflow step MUST define `inputs` and `outputs` (not just `actions`) so agents understand what a step achieves, not just how to do it.
+
+---
+
+## Rationale
+
+**Why YAML instead of Markdown?**  
+- Machine-readable: easier for agents to parse step inputs/outputs
+- Structured: enforces schema compliance
+- If found to be too rigid, can switch to Markdown+frontmatter without breaking skill references
+
+**Why inputs/outputs per step?**  
+- Agents need to know WHAT each step achieves, not just HOW
+- Enables future: step skipping based on already-available outputs
+- Better debugging: "step X failed because output Y was not produced"
+
+---
+
+## Consequences
+
+- ✅ Workflows are reusable across skills
+- ✅ Each step has clear contract (inputs → outputs)
+- ✅ Easier to add new skills that reuse existing workflows
+- ⚠️ YAML can be verbose — acceptable tradeoff for clarity
+- ⚠️ If workflow changes, all referencing skills remain valid (they only reference by name)