ai-developer-skill-os 7.5.1 → 8.1.4

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/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)

package/.agents/docs/decisions/ADR-003-registry-generated.md

@@ -0,0 +1,54 @@
+# ADR-003: Registry as Generated Artifact
+
+**Date:** 2026-07  
+**Status:** Accepted
+
+---
+
+## Context
+
+V7 had `skills.json` as the primary manifest — manually maintained, often drifting from actual SKILL.md content. This created two sources of truth.
+
+V8 needs a retrieval index for AI agents to find the right skill without reading all 22 SKILL.md files.
+
+---
+
+## Decision
+
+`registry/skills-index.yml` is a **generated file**. It is produced by `tooling/generate-registry.js` by reading all `SKILL.md` frontmatter.
+
+`SKILL.md` is the single source of truth. The registry is a derivative.
+
+```
+SKILL.md (source of truth)
+    ↓
+tooling/generate-registry.js
+    ↓
+registry/skills-index.yml (DO NOT EDIT MANUALLY)
+```
+
+`skills.json` is kept as a compatibility manifest for platforms that expect it (e.g., Antigravity v7 convention). It is also generated, not manually maintained.
+
+---
+
+## Rationale
+
+**Why not edit the registry manually?**  
+- Two sources of truth always drift
+- Triggers, intent, complexity are already defined in SKILL.md
+- Generator can be run as a pre-commit hook or on demand
+
+**Why keep skills.json?**  
+- Antigravity and some platforms discover skills via `skills.json`
+- Backward compatibility for v7 skill consumers
+- It's generated, so no maintenance burden
+
+---
+
+## Consequences
+
+- ✅ Single source of truth: SKILL.md
+- ✅ No drift between skill and registry
+- ✅ Registry update is automatic when skills are updated
+- ⚠️ Requires running generator after any SKILL.md change
+- ⚠️ If generator is not run, registry may be stale (mitigated by pre-commit hook)

package/.agents/docs/decisions/ADR-008-skill-boundary-review.md

@@ -0,0 +1,27 @@
+# ADR 008: Skill Boundary Review (V8.1.3)
+
+## Tiêu đề
+Định hướng tương lai cho ranh giới của `qk-validation-gate` và `qk-ai-builder`.
+
+## Bối cảnh
+Trong quá trình hoàn thiện Agent Engineering OS (V8.1.3), quá trình kiểm toán phát hiện rằng một số skill ban đầu có phạm vi hoạt động (scope) quá rộng hoặc chưa phân vai rõ ràng, dễ dẫn đến conflict. Tuy nhiên, để không làm vỡ kiến trúc (scope creep) trong giai đoạn chốt Control Plane, chúng ta quyết định giữ nguyên nhưng ghi chú định hướng cho V8.2.
+
+## Quyết định
+
+### 1. Về `qk-validation-gate`
+- **Hiện trạng:** Đang đóng vai trò validation coordinator.
+- **Định hướng (V8.2):** Sẽ được định hình rõ thành `release decision orchestrator`.
+- **Ranh giới tương lai:** Không trực tiếp chạy test, không trực tiếp scan security, không audit quality. Nhiệm vụ của nó là tổng hợp kết quả từ `qk-test-engineering`, `qk-security-audit`, và `qk-web-quality-gate` để ra quyết định cuối cùng (gate decision).
+
+### 2. Về `qk-ai-builder`
+- **Hiện trạng:** Đang quá rộng (gồm cả frontend AI apps, general AI coding, prompt writing...).
+- **Định hướng (V8.2):** Đổi tên (rename semantic) thành `qk-agent-platform-engineering`.
+- **Ranh giới tương lai:**
+  - **Owns:** agent architecture, MCP integration, skill generation, agent runtime patterns.
+  - **Does not own:** frontend AI apps, general AI coding, prompt writing.
+
+## Trạng thái
+Đề xuất được chấp nhận (Deferred to V8.2).
+
+## Hệ quả
+Ngăn chặn các kỹ năng này bị phình to trong quá trình triển khai thực tế. Chuẩn bị sẵn sàng cấu trúc cho giai đoạn V8.2 (Self-Improving Agent).