ai-developer-skill-os 7.5.0 → 8.1.4

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

package/.agents/docs/schemas/learning.schema.yml

@@ -0,0 +1,69 @@
+# Learning Schema — V8
+# Defines the required structure for all learning files.
+
+schema_version: 8.0.0
+
+# ── Required fields for all learnings ──────────────────────
+required:
+  claim:
+    type: string
+    description: "A specific, falsifiable statement about agent/workflow behavior"
+    example: "Bug fixes using hypothesis-first approach have 40% lower regression rate"
+
+  context:
+    type: string
+    description: "When does this learning apply?"
+    example: "When diagnosing bugs with incomplete stack traces"
+
+  lifecycle:
+    type: enum
+    values: [draft, validated, deprecated]
+
+# ── Required only for validated learnings ──────────────────
+validated_required:
+  evidence:
+    type: array
+    description: "References to issues, experiments, or benchmarks that support this claim"
+    example: ["issue-102", "experiment-2026-07"]
+
+  validated_by:
+    type: enum
+    values: [human, benchmark]
+
+  validated_date:
+    type: date
+    example: "2026-07"
+
+# ── Optional fields ─────────────────────────────────────────
+optional:
+  counter_examples:
+    type: array
+    description: "Cases where this learning does NOT apply"
+
+  superseded_by:
+    type: string
+    description: "For deprecated: which learning replaced this one"
+
+  related_skills:
+    type: array
+    description: "Skills that should reference this learning"
+
+# ── Lifecycle transitions ────────────────────────────────────
+lifecycle_rules:
+  draft_to_validated:
+    - "Human review required"
+    - "Evidence field must be filled"
+    - "Git commit message must include [validated]"
+
+  validated_to_deprecated:
+    - "Superseded_by field must reference the newer learning"
+    - "Keep file in deprecated/ for 6 months then can archive"
+
+  agent_can:
+    - "Create draft learnings"
+    - "Read validated learnings"
+
+  agent_cannot:
+    - "Promote draft to validated"
+    - "Delete any learning"
+    - "Modify validated learnings"

package/.agents/docs/schemas/skill.schema.yml

@@ -0,0 +1,188 @@
+# Skill Schema — V8
+
+# This file defines the required and optional fields for all SKILL.md frontmatter.
+# Every skill MUST conform to this schema. Validator: tooling/validate-skills.js
+
+schema_version: 8.0.0
+
+# ── Required fields ────────────────────────────────────────
+required:
+  name:
+    type: string
+    pattern: "^qk-[a-z-]+$"
+    example: "qk-bug-resolution"
+
+  version:
+    type: semver
+    example: "8.0.0"
+
+  status:
+    type: enum
+    values: [draft, experimental, stable, legacy, deprecated]
+
+  description:
+    type: string
+    maxLength: 120
+    example: "Sửa lỗi bằng chu trình khép kín: Observe → Hypothesize → Evidence → Fix."
+
+  platforms:
+    type: array
+    items: [antigravity, claude-code, cursor, windsurf, kilo-code]
+
+  type:
+    type: enum
+    values: [capability, utility, orchestrator]
+    example: "capability"
+
+  intent:
+    type: array
+    minItems: 1
+    example: [bug-fixing, debugging]
+
+  complexity:
+    type: object
+    required_fields: [level]
+    optional_fields: [criteria]
+    levels: [low, medium, high, critical]
+
+  triggers:
+    type: array
+    minItems: 2
+    description: "Keywords that cause AI to select this skill"
+    example: ["fix bug", "lỗi", "crash"]
+
+  workflow:
+    type: string
+    description: "References workflows/<name>.yml"
+    example: "bug-resolution"
+
+  selection:
+    type: object
+    required_fields: [priority]
+    optional_fields: [confidence_threshold, fallback_skill]
+    priority:
+      type: enum
+      values: [high, medium, low]
+    confidence_threshold:
+      type: number
+      default: 0.75
+      range:
+        min: 0.0
+        max: 1.0
+    fallback_skill:
+      type: string
+      optional: true
+
+  verification:
+    type: object
+    required_fields: [required, strategy]
+    strategies: [bug-fix, refactor, feature, documentation, review, api-change, migration-safety, performance-regression, release-safety, bootstrap-validation, none]
+
+  execution_mode:
+    type: enum
+    values: [deterministic]
+
+  token_budget:
+    type: object
+    required_fields: [max_files_read, max_lines_per_read, max_shell_commands, stop_early]
+
+  exit_codes:
+    type: array
+    items: [SUCCESS, BLOCKED, FAILED, PARTIAL]
+
+# ── Optional fields ─────────────────────────────────────────
+optional:
+  rules:
+    type: array
+    description: "References rules/<name>.md"
+    example: [global, coding]
+
+  tools:
+    type: array
+    example: [filesystem, git, browser]
+
+  related_skills:
+    type: array
+    description: "Skills often used together"
+    example: [qk-engineering-standard]
+
+  examples:
+    type: array
+    description: "References examples/good/*.md"
+
+  learnings:
+    type: array
+    description: "References learnings/validated/*.md"
+
+  cost:
+    type: enum
+    values: [low, medium, high]
+
+  latency:
+    type: enum
+    values: [fast, medium, slow]
+
+  risk:
+    type: enum
+    values: [low, medium, high]
+
+  side_effects:
+    type: enum
+    values: [edit_files, run_commands, read_only, none]
+
+  produces:
+    type: array
+    items: [code, report, schema, plan, tokens]
+
+  consumes:
+    type: array
+
+  knowledge_scope:
+    type: object
+    description: "Defines what knowledge this skill knows vs. references"
+    fields:
+      domain:
+        type: array
+      concepts:
+        type: array
+      references:
+        type: array
+
+  decision_boundary:
+    type: object
+    description: "Defines what decisions this skill is authorized to make"
+    fields:
+      owns:
+        type: array
+      does_not_own:
+        type: array
+      conflicts_with:
+        type: array
+      delegates_to:
+        type: array
+        description: "Other skills this skill can delegate implementation to"
+
+  lifecycle:
+    type: object
+    description: "Lifecycle governance for promotion and demotion"
+    fields:
+      promotion_gate:
+        type: object
+        fields:
+          requirements:
+            type: object
+            fields:
+              tests:
+                type: object
+              usage:
+                type: object
+              conflicts:
+                type: object
+              evidence:
+                type: object
+                fields:
+                  required:
+                    type: array
+      demotion_gate:
+        type: object
+

package/.agents/docs/schemas/workflow.schema.yml

@@ -0,0 +1,33 @@
+# Workflow Schema Reference
+# See workflows/_schema.yml for the full machine-readable schema.
+# This file is for human reference.
+
+schema_version: 8.0.0
+
+top_level_required:
+  name:        "string, kebab-case"
+  version:     "semver 8.x.x"
+  description: "string, one sentence"
+  steps:       "array, minimum 2"
+  escalation:  "object: {max_retries, on_failure}"
+
+step_required:
+  id:       "string, snake_case, unique within workflow"
+  name:     "string, human-readable"
+  purpose:  "string — WHAT the step achieves"
+  inputs:   "array — what this step needs to start"
+  outputs:  "array — what this step produces when done"
+  required: "bool — true = cannot be skipped without skip_if condition"
+
+step_optional:
+  skip_if:        "string — condition under which step can be skipped"
+  exit_on_fail:   "BLOCKED | PARTIAL | FAILED"
+  min_confidence: "HIGH | MEDIUM"
+  actions:        "array — hints for HOW (not mandatory for agent)"
+
+verification_profiles:
+  bug-fix:      [regression_check, root_cause_fixed, lint_clean, test_if_available]
+  refactor:     [behavior_unchanged, test_pass, lint_clean, no_new_complexity]
+  feature:      [acceptance_criteria, test_coverage, integration_check, lint_clean]
+  documentation:[accuracy, completeness, no_broken_links]
+  review:       [findings_have_evidence, severity_justified, actionable_suggestions]

package/.agents/knowledge/design-intelligence/industries/ecommerce.md

@@ -0,0 +1,3 @@
+# E-commerce Design Intelligence
+
+Focus: Conversion-optimized, high visual hierarchy, vibrant.

package/.agents/knowledge/design-intelligence/industries/fintech.md

@@ -0,0 +1,3 @@
+# Fintech Design Intelligence
+
+Focus: Trustworthy, data-heavy, clean, secure.

package/.agents/knowledge/design-intelligence/industries/healthcare.md

@@ -0,0 +1,3 @@
+# Healthcare Design Intelligence
+
+Focus: Accessible, calming, reliable, clear hierarchy.

package/.agents/learnings/draft/README.md

@@ -0,0 +1,37 @@
+# Learning Draft — Placeholder
+
+This directory contains draft learnings created by AI agents or humans that have NOT yet been validated.
+
+## How to add a draft learning
+
+Create a new file: `YYYY-MM-[short-slug].md`
+
+```markdown
+---
+claim: "..."
+context: "When does this apply?"
+lifecycle: draft
+observed_by: agent | human
+observed_date: YYYY-MM
+related_skills: []
+---
+
+## Observation
+
+What was observed?
+
+## Why it matters
+
+Why is this worth noting?
+
+## Counter examples (if any)
+
+When does this NOT apply?
+```
+
+## How to promote to validated
+
+1. Fill the `evidence` field with links to issues/experiments
+2. Human reviews and agrees
+3. Move file to `validated/`
+4. Git commit with `[validated]` in message