ai-developer-skill-os 8.2.1 → 8.3.1

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

@@ -1,10 +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.
+# 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/V8-CERTIFICATION.md

@@ -1,27 +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
+# 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/decisions/ADR-001-v8-migration.md

@@ -1,58 +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
+# 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

@@ -1,50 +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)
+# 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

@@ -1,54 +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)
+# 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

@@ -1,27 +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).
+# 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).

package/.agents/registry/capability-graph.yml

@@ -1,7 +1,7 @@
 # registry/capability-graph.yml
-# GENERATED FILE — DO NOT EDIT MANUALLY
+# GENERATED FILE - DO NOT EDIT MANUALLY.
 version: 8.1.3
-generated_at: '2026-07-23T06:25:44.563Z'
+generated_at: '2026-07-29T07:30:08.002Z'
 nodes:
   qk-access-policy:
     type: capability
@@ -24,6 +24,7 @@ nodes:
       - infrastructure_monitoring
       - log_aggregation
       - uptime_monitoring
+      - pass_fail_enforcement
     conflicts: []
     workflow: skill-evolution
   qk-ai-builder:
@@ -47,6 +48,13 @@ nodes:
     does_not_own: []
     conflicts: []
     workflow: bug-resolution
+  qk-code-review:
+    type: utility
+    maturity: stable
+    owns: []
+    does_not_own: []
+    conflicts: []
+    workflow: code-review
   qk-context-loader:
     type: utility
     maturity: stable
@@ -142,7 +150,7 @@ nodes:
     owns: []
     does_not_own: []
     conflicts: []
-    workflow: internal
+    workflow: documentation
   qk-orchestrator:
     type: orchestrator
     maturity: stable
@@ -165,10 +173,15 @@ nodes:
   qk-production-release:
     type: capability
     maturity: stable
-    owns: []
-    does_not_own: []
-    conflicts: []
-    workflow: internal
+    owns:
+      - release-gate-checklist
+      - deployment-readiness-verdict
+    does_not_own:
+      - ci-cd-pipeline-design
+      - infrastructure-provisioning
+    conflicts:
+      - qk-devops-platform
+    workflow: production-release
   qk-project-bootstrap:
     type: capability
     maturity: stable
@@ -190,6 +203,13 @@ nodes:
     does_not_own: []
     conflicts: []
     workflow: documentation
+  qk-refactor:
+    type: capability
+    maturity: stable
+    owns: []
+    does_not_own: []
+    conflicts: []
+    workflow: refactor
   qk-security-audit:
     type: capability
     maturity: experimental
@@ -230,19 +250,17 @@ nodes:
     does_not_own: []
     conflicts: []
     workflow: code-review
-  qk-ui-builder:
-    type: capability
-    maturity: stable
-    owns: []
-    does_not_own: []
-    conflicts: []
-    workflow: feature-delivery
   qk-ui-system-builder:
     type: capability
     maturity: stable
-    owns: []
-    does_not_own: []
-    conflicts: []
+    owns:
+      - tokens
+      - ui-system
+    does_not_own:
+      - page implementation
+      - visual direction
+    conflicts:
+      - qk-design-system-engineering
     workflow: feature-delivery
   qk-validation-gate:
     type: utility
@@ -273,6 +291,9 @@ edges:
   - from: qk-agent-observability
     to: skill-evolution
     relation: depends_on
+  - from: qk-agent-observability
+    to: qk-validation-gate
+    relation: feeds
   - from: qk-ai-builder
     to: feature-delivery
     relation: depends_on
@@ -294,6 +315,18 @@ edges:
   - from: qk-bug-resolution
     to: qk-validation-gate
     relation: feeds
+  - from: qk-code-review
+    to: code-review
+    relation: depends_on
+  - from: qk-code-review
+    to: qk-validation-gate
+    relation: feeds
+  - from: qk-code-review
+    to: qk-engineering-standard
+    relation: feeds
+  - from: qk-code-review
+    to: qk-project-health
+    relation: feeds
   - from: qk-context-loader
     to: research
     relation: depends_on
@@ -394,7 +427,7 @@ edges:
     to: qk-web-quality-gate
     relation: feeds
   - from: qk-help
-    to: internal
+    to: documentation
     relation: depends_on
   - from: qk-help
     to: qk-orchestrator
@@ -418,8 +451,11 @@ edges:
     to: qk-feature-delivery
     relation: feeds
   - from: qk-production-release
-    to: internal
+    to: production-release
     relation: depends_on
+  - from: qk-production-release
+    to: qk-devops-platform
+    relation: conflicts_with
   - from: qk-production-release
     to: qk-validation-gate
     relation: feeds
@@ -441,6 +477,15 @@ edges:
   - from: qk-project-memory
     to: qk-engineering-standard
     relation: feeds
+  - from: qk-refactor
+    to: refactor
+    relation: depends_on
+  - from: qk-refactor
+    to: qk-engineering-standard
+    relation: feeds
+  - from: qk-refactor
+    to: qk-project-health
+    relation: feeds
   - from: qk-security-audit
     to: security-audit
     relation: depends_on
@@ -474,15 +519,12 @@ edges:
   - from: qk-ui-audit
     to: qk-ui-builder
     relation: feeds
-  - from: qk-ui-builder
-    to: feature-delivery
-    relation: depends_on
-  - from: qk-ui-builder
-    to: qk-ui-system-builder
-    relation: feeds
   - from: qk-ui-system-builder
     to: feature-delivery
     relation: depends_on
+  - from: qk-ui-system-builder
+    to: qk-design-system-engineering
+    relation: conflicts_with
   - from: qk-ui-system-builder
     to: qk-ui-builder
     relation: feeds