ai-developer-skill-os 9.3.1 → 10.2.0

package/.agents/docs/SPEC.md

@@ -1,4 +1,4 @@
-# AI Developer Skill OS - Specification (v7.5)
+# AI Developer Skill OS - Specification (V10.2.0)
 
 This document defines the strict contract and schema for all `SKILL.md` files in the AI Developer Skill OS. Every active skill MUST comply with this specification. The frontmatter is frozen to ensure cross-platform compatibility and deterministic agent behavior.
 
@@ -8,28 +8,57 @@ Every `SKILL.md` must begin with this exact YAML structure. Do not add, remove,
 
 ```yaml
 ---
+# ── Identity ───────────────────────────────────────
 name: qk-[skill-name]
-category: [core|frontend|backend|fullstack|security|qa|maintenance|devops|utilities]
-version: X.Y.Z
-description: "[One sentence — what this skill does]"
-platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
-execution_mode: deterministic
+version: 10.2.0
+status: stable
+description: "[Một câu — skill này làm gì và dành cho ai]"
+platforms: [antigravity, claude, opencode]
+
+# ── Classification ─────────────────────────────────
+type: capability                    # capability | utility | orchestrator
+runtime_version: 1
+
+intent:
+  - [primary-intent]
+  - [secondary-intent]
+
+complexity:
+  level: medium                     # low | medium | high | critical
+
+triggers:
+  - "[trigger phrase 1]"
 
-# Orchestrator routing metadata
-cost: [low|medium|high]
-latency: [fast|medium|slow]
-risk: [low|medium|high]
-side_effects: [edit_files|run_commands|read_only|none]
-produces: [report|code|schema|plan|tokens]
-consumes: [context-graph|design-md|stack-trace|json-payload|none]
+selection:
+  priority: medium                  # high | medium | low
+  confidence_threshold: 0.75
 
+# ── References ─────────────────────────────────────
+workflow: [workflow-name]
+rules:
+  - global
+tools:
+  - filesystem
+
+# ── Runtime ────────────────────────────────────────
+execution_mode: deterministic
 token_budget:
   max_files_read: 3
   max_lines_per_read: 150
   max_shell_commands: 2
   stop_early: true
 
-exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
+# ── V10 Required ───────────────────────────────────
+exit_codes:
+  SUCCESS: "Task completed"
+  PARTIAL: "Task done with gaps"
+  BLOCKED: "Missing precondition"
+  FAILED: "Task failed"
+
+compliance:
+  schema_version: 10.2.0
+  runtime_version: 1
+  platforms: [antigravity, claude, opencode]
 ---
 ```
 
@@ -38,50 +67,98 @@ exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | `name` | string | YES | Skill identifier, must start with `qk-` |
-| `category` | enum | YES | Primary domain: `core`, `frontend`, `backend`, `fullstack`, `security`, `qa`, `maintenance`, `devops`, `utilities` |
-| `version` | semver | YES | Semantic version of this skill |
+| `version` | semver | YES | Must be `10.2.0` |
+| `status` | enum | YES | `stable`, `experimental`, or `deprecated` |
 | `description` | string | YES | One-sentence summary of the skill's purpose |
-| `platforms` | array | YES | Supported AI platforms. Valid values: `antigravity`, `claude-code`, `cursor`, `windsurf`, `kilo-code` |
-| `execution_mode` | string | YES | Must be `deterministic` for all v7.5 skills |
-| `cost` | enum | YES | Token/compute cost: `low`, `medium`, `high` |
-| `latency` | enum | YES | Expected execution speed: `fast`, `medium`, `slow` |
-| `risk` | enum | YES | Risk level of side effects: `low`, `medium`, `high` |
-| `side_effects` | enum | YES | What the skill modifies: `edit_files`, `run_commands`, `read_only`, `none` |
-| `produces` | array | YES | Output artifacts: `report`, `code`, `schema`, `plan`, `tokens` |
-| `consumes` | array | YES | Required inputs: `context-graph`, `design-md`, `stack-trace`, `json-payload`, `none` |
-| `token_budget.max_files_read` | int | YES | Maximum files to read before stopping |
-| `token_budget.max_lines_per_read` | int | YES | Maximum lines per file read operation |
-| `token_budget.max_shell_commands` | int | YES | Maximum shell commands allowed |
-| `token_budget.stop_early` | bool | YES | Whether to stop when confidence threshold is reached |
-| `exit_codes` | array | YES | Valid exit codes for this skill |
-
-## 2. Skill Body Structure (Markdown)
-
-The body of the `SKILL.md` file MUST contain the following sections in order:
-
-1. **Header:** Skill title and language rule
-2. **Preconditions:** Checklist of required inputs/state before execution
-3. **Scope:** What the skill explicitly does (✅) and does not do (❌)
-4. **Priority Order:** P1–P4 checks with skip thresholds for token budget management
-5. **Workflow:** Phased execution steps with explicit decision trees and exit conditions
-6. **Confidence Model:** HIGH/MEDIUM/LOW confidence levels with actions
-7. **Severity:** CRITICAL/HIGH/MEDIUM/LOW severity definitions with examples
-8. **Evidence Format:** Mandatory template for all findings
-9. **Retry Policy:** Retry logic with maximum attempt limits
-10. **Escalation Rules:** Structured BLOCKED response format
-11. **Handoff Contract:** JSON schema for `Consumes` and `Produces`
-12. **Output Format:** Mandatory output template
-13. **Exit Codes:** Table mapping codes to meanings
-
-## 3. Naming Conventions
-
-- Skill files: `skills/qk-[skill-name]/SKILL.md`
-- Registry entry: `qk-[skill-name]`
-- All code, identifiers, and file names: English only
-- Explanations and reports: Vietnamese (match user language)
-
-## 4. Compliance Enforcement
-
-- All skills MUST pass `npm run lint` (which validates frontmatter against this spec)
-- The `## Compliance` table at the bottom of each `SKILL.md` is deprecated and MUST be removed
-- CI pipeline enforces schema compliance automatically
+| `platforms` | array | YES | Supported IDEs. Valid values: `antigravity`, `claude`, `opencode` |
+| `type` | enum | YES | Primary domain: `capability`, `utility`, `orchestrator` |
+| `runtime_version` | integer | YES | Runtime version (currently `1`) |
+| `execution_mode` | string | YES | Must be `deterministic` for all V10 skills |
+| `intent` | array | YES | Primary and secondary intents |
+| `complexity.level` | enum | YES | `low`, `medium`, `high`, `critical` |
+| `triggers` | array | YES | Keywords that route AI to this skill |
+| `selection.priority` | enum | YES | `high`, `medium`, `low` |
+| `workflow` | string | YES | References `workflows/<name>.yml` |
+| `exit_codes` | object | YES | SUCCESS, PARTIAL, BLOCKED, FAILED with meanings |
+| `compliance` | object | YES | schema_version, runtime_version, platforms |
+
+---
+
+## 2. Required Body Sections (V10.2)
+
+Every `SKILL.md` body MUST contain sections in this order:
+
+```
+## 1. Nguyên Tắc Cốt Lõi & Luật Chống Over-Engineering
+## 2. Giới Hạn Kỹ Thuật & Cấm Kỵ Tuyệt Đối (Hard Boundaries)
+## 3. Quy Trình Thực Hiện Theo Bước (Sequential Procedure)
+## 4. Xử Lý Sự Cố Khi Thất Bại (Failure Path)     [if applicable]
+## 5. Thích Ứng Theo Role Kỹ Thuật (Role Adaptation) [if applicable]
+## 6. Mô Hình Độ Tin Cậy (Confidence Model)
+## 7. Bằng Chứng Định Dạng (Evidence Format)
+## 8. Thoái Ra Mã (Exit Codes)
+## 9. Chính Sách Retry (Retry Policy)               [if applicable]
+## 10. Platform-Specific Instructions
+## 11. Compliance
+```
+
+### V10 Key Requirements
+
+- **Confidence Model**: Every skill defines HIGH/MEDIUM/LOW confidence levels
+- **Exit Codes**: Every skill defines SUCCESS/PARTIAL/BLOCKED/FAILED
+- **Evidence Format**: Every skill has structured evidence format with severity + confidence
+- **Compliance**: Every skill ends with Compliance check table (schema_version 10.2.0)
+- **Platform-Specific**: Every skill has instructions for Antigravity, Claude, OpenCode
+
+---
+
+## 3. Supported Platforms
+
+| Platform | Config File | Context Window | Tool Format |
+|----------|-------------|----------------|-------------|
+| **Antigravity** (Google Gemini) | `.agents/AGENTS.md` | Large | Custom Cockpit |
+| **Claude** (Anthropic) | `.claude/CLAUDE.md` | ~200K tokens | Native (Read/Write/Edit/Bash) |
+| **OpenCode** (Open Source) | `.opencode/config.yaml` | ~128K tokens | Custom |
+
+---
+
+## 4. Registry Schema
+
+| File | Format | Generated by |
+|------|--------|--------------|
+| `.agents/registry/index.yaml` | YAML | `node tooling/build-registry.js` |
+| `.agents/registry/graph.json` | JSON | `node tooling/build-registry.js` |
+
+Each graph node includes: `path`, `version`, `platforms`, `tags`, `dependencies`, `dependents`, `is_orphan`.
+
+---
+
+## 5. Validation
+
+```bash
+# Validate all skill files
+node tooling/validate-skills.js    # 11/11 valid
+
+# Validate graph integrity
+node tooling/validate-graph.js     # Score 100/100
+
+# Rebuild registry
+node tooling/build-registry.js     # 11 active, 0 archived
+
+# Sync versions across repo
+node tooling/sync-versions.js      # All files to 10.2.0
+
+# Run full test suite
+npm run test:registry              # All tests pass
+```
+
+---
+
+## Changelog
+
+| Version | Change |
+|---------|--------|
+| V10.2.0 | 3 IDEs (Antigravity, Claude, OpenCode), platform-specific sections, platforms field |
+| V10.1.0 | 11 Super-Skills, API Discovery Engine, Prompt Compiler Control Plane |
+| V9.x | Legacy multi-skill system (29+ skills) |
+| V8.x | Structured skill system |

package/.agents/docs/VERSIONING.md

@@ -1,95 +1,63 @@
-# Versioning Policy — AI Developer Skill OS V8
+# Versioning Policy — AI Developer Skill OS V10
 
 ## Semantic Versioning: `MAJOR.MINOR.PATCH`
 
-Current: `8.0.0`
+Current: `10.2.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    |
+| V8.x    | Skill System              | Structured capabilities                    |
+| V9.x    | Governed Capability Graph | Decision boundaries + lifecycle governance |
+| V10.x   | 11 Super-Skills           | V10.2 — Confidence Model, Exit Codes, Evidence Format, Compliance |
 
 ---
 
 ## When to bump each segment
 
-### MAJOR (8.x.x → 9.0.0)
+### MAJOR (10.x.x → 11.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)
+### MINOR (10.2.0 → 10.3.0)
 Backward-compatible additions.
 
 ```
 ✅ Examples:
 - Adding a new skill
 - Adding a new workflow
-- Adding a new optional frontmatter field
+- Adding a new reference file
 - 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.
+### PATCH (10.2.0 → 10.2.1)
+Fixes that don't change behavior.
 
 ---
 
-## 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 |
+## V10.2 Migration Notes
 
----
-
-## Registry versioning
+All skill files, rule files, and workflow files MUST have version `10.2.0` in frontmatter.
 
-`registry/skills-index.yml` is a **generated file**. Its version tracks the knowledge system version, not the registry format.
+### New Required Sections in Every SKILL.md:
+- `## Mô Hình Độ Tin Cậy (Confidence Model)`
+- `## Thoái Ra Mã (Exit Codes)`
+- `## Bằng Chứng Định Dạng (Evidence Format)`
+- `## Compliance`
 
-It is regenerated whenever any SKILL.md is modified. **Never manually edit it.**
+### Registry Files:
+- `graph.json` and `index.yaml` — generated by `node tooling/build-registry.js`
+- Old files (`capability-graph.yml`, `skills-index.yml`) — REMOVED in V10
 
 ---
 
-## Learning lifecycle versioning
-
-Learnings do not follow semver. They follow a lifecycle:
+## Validation Commands
 
+```bash
+npm run test:registry   # Validate all skills + rebuild registry
+npm run test:graph      # Validate graph integrity
+npm run lint            # Validate individual skill structure
 ```
-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/adr/0005-v10-platform-consolidation.md

@@ -0,0 +1,50 @@
+# ADR-005: V10 Platform Consolidation
+
+**Date:** 2026-09-24
+**Status:** Accepted
+**Deciders:** AI Developer Skill OS Team
+
+## Context
+
+The V8-V9 architecture supported 29+ skills across multiple IDEs including Cursor, Windsurf, Kilo Code, and OpenAI Codex. This led to:
+
+- Two parallel skill systems (`/skills/` and `.agents/skills/`)
+- Registry inconsistency between `capability-graph.yml` (old) and `graph.json` (new)
+- Version fragmentation (8.0.0, 9.1.0, 9.2.0, 10.1.0, 11.1.0)
+- Missing validation sections (Exit Codes, Confidence Model, Evidence Format, Compliance)
+- No automated testing for skill structure
+
+## Decision
+
+Consolidate to **3 IDE platforms** with a clean architecture:
+
+| Platform | Config | Context Window |
+|----------|--------|----------------|
+| **Antigravity** | `.agents/AGENTS.md` | Large (Gemini) |
+| **Claude** | `.claude/CLAUDE.md` | ~200K tokens |
+| **OpenCode** | `.opencode/config.yaml` | ~128K tokens |
+
+### Structural Changes
+
+1. **Removed `/skills/` directory** — single system under `.agents/skills/`
+2. **Removed `capability-graph.yml` and `skills-index.yml`** — replaced by `graph.json` and `index.yaml`
+3. **Removed old worktrees** — `.kilo/worktrees/stealth-octagon`
+4. **Added `platforms` field** to all SKILL.md frontmatters
+5. **Added required sections** to all SKILL.md: Exit Codes, Confidence Model, Evidence Format, Compliance, Platform-Specific Instructions
+6. **Created `tooling/validate-skills.js`** — validates all skill structure
+7. **Created `tooling/validate-graph.js`** — validates graph integrity (Score 100/100)
+8. **Updated all versions** to `10.2.0` consistently
+
+### Consequences
+
+- Single source of truth: `.agents/skills/**/SKILL.md`
+- Automated validation: `npm run test:registry` (10/10 tests)
+- Graph integrity: `npm run test:graph` (100/100)
+- IDE-specific wrappers: `.claude/CLAUDE.md`, `.opencode/config.yaml`
+- 11 Super-Skills, 12 workflows, 9 rules, all at version 10.2.0
+
+### Future Considerations
+
+- Add platform-specific skill variants if context window differences require
+- Add `qk-help` skill if routing needs improvement
+- Consider adding ADR for each major version bump

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

@@ -1,69 +1,34 @@
-# Learning Schema — V8
+# Learning Schema — V10.2
 # Defines the required structure for all learning files.
 
-schema_version: 8.0.0
+schema_version: 10.2.0
 
-# ── Required fields for all learnings ──────────────────────
+# ── Required fields ────────────────────────────────
 required:
-  claim:
+  skill:
     type: string
-    description: "A specific, falsifiable statement about agent/workflow behavior"
-    example: "Bug fixes using hypothesis-first approach have 40% lower regression rate"
-
-  context:
+    pattern: "^qk-[a-z-]+$"
+    example: "qk-bug-resolution"
+  topic:
     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:
+    example: "triangulate-technique"
   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"
+    items: string
+    example: ["test-passed", "code-reviewed"]
+  validated_at:
+    type: string
+    format: date-time
 
-# ── Optional fields ─────────────────────────────────────────
+# ── Optional fields ────────────────────────────────
 optional:
-  counter_examples:
-    type: array
-    description: "Cases where this learning does NOT apply"
-
-  superseded_by:
+  confidence:
+    type: enum
+    values: [HIGH, MEDIUM, LOW]
+  source:
     type: string
-    description: "For deprecated: which learning replaced this one"
-
-  related_skills:
+    description: "Where this learning was validated"
+  applies_to:
     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"
+    items: string
+    example: ["qk-bug-resolution", "qk-code-cleaner"]