ai-developer-skill-os 10.1.0 → 10.2.0

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"]

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

@@ -1,188 +1,143 @@
-# Skill Schema — V8
-
+# Skill Schema — V10.2
 # 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:
+schema_version: 10.2.0
+
+# ── Identity ────────────────────────────────────────────
+name:
+  type: string
+  pattern: "^qk-[a-z-]+$"
+  example: "qk-bug-resolution"
+
+version:
+  type: semver
+  example: "10.2.0"
+
+status:
+  type: enum
+  values: [stable, experimental, deprecated]
+
+description:
+  type: string
+  maxLength: 200
+  example: "Chẩn đoán nguyên nhân gốc rễ và khắc phục lỗi mã nguồn."
+
+platforms:
+  type: array
+  items: [antigravity, claude, opencode]
+  description: "Which IDEs this skill supports"
+  example: [antigravity, claude, opencode]
+
+runtime_version:
+  type: integer
+  default: 1
+
+type:
+  type: enum
+  values: [capability, utility, orchestrator]
+  example: "capability"
+
+# ── Classification ──────────────────────────────────────
+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"]
+
+selection:
+  type: object
+  required_fields: [priority]
+  optional_fields: [confidence_threshold, fallback_skill]
+  priority:
     type: enum
-    values: [draft, experimental, stable, legacy, deprecated]
-
-  description:
+    values: [high, medium, low]
+  confidence_threshold:
+    type: number
+    default: 0.75
+    range:
+      min: 0.0
+      max: 1.0
+  fallback_skill:
     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: true
+
+# ── References ──────────────────────────────────────────
+workflow:
+  type: string
+  description: "References workflows/<name>.yml"
+  example: "bug-resolution"
+
+rules:
+  type: array
+  example: [global]
+
+tools:
+  type: array
+  example: [filesystem]
+
+# ── Runtime ─────────────────────────────────────────────
+execution_mode:
+  type: enum
+  values: [deterministic]
+
+token_budget:
+  type: object
+  required_fields: [max_files_read, max_lines_per_read, max_shell_commands, stop_early]
+
+# ── V10 Required Sections ───────────────────────────────
+exit_codes:
+  type: object
+  required_fields: [SUCCESS, PARTIAL, BLOCKED, FAILED]
+  description: "Each exit code with meaning and when"
+
+confidence_model:
+  type: object
+  levels: [HIGH, MEDIUM, LOW]
+  description: "Confidence levels for evidence-based routing"
+
+compliance:
+  type: object
+  required_fields: [schema_version, runtime_version, platforms]
+  description: "Compliance check block at end of SKILL.md"
+
+# ── 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"
-
+  knowledge_scope:
+    type: object
+    fields: [owns, references]
   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:
+  verification:
     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
-
+    required_fields: [required, strategy]
+    strategies: [bug-fix, refactor, feature, documentation, review]

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

@@ -1,33 +1,58 @@
-# Workflow Schema Reference
+# Workflow Schema — V10.2
 # See workflows/_schema.yml for the full machine-readable schema.
 # This file is for human reference.
 
-schema_version: 8.0.0
+schema_version: 10.2.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}"
+# ── Required top-level fields ──────────────────────
+required:
+  - name          # string: workflow identifier (kebab-case)
+  - version       # semver: 10.x.x
+  - description   # string: what this pipeline does
+  - owner
+  - steps
 
-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"
+# ── Owner ──────────────────────────────────────────
+owner:
+  type: engineering
+  maintained_by: qk-team
 
-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)"
+# ── Steps ──────────────────────────────────────────
+steps:
+  - id: string          # Unique step identifier
+    name: string        # Display name
+    purpose: string     # What this step achieves
+    required: boolean   # Whether step is mandatory
+    outputs:            # Array of output names
+      - string
+    actions:            # Array of action descriptions
+      - string
+    human_checkpoint:   # Optional human approval
+      condition: string
+      message: string
+    exit_on_fail:       # What to do on failure
+      - PARTIAL
+      - BLOCKED
+      - FAILED
 
-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]
+# ── Escalation ─────────────────────────────────────
+escalation:
+  max_retries: integer
+  on_failure: string
+
+# ── Example ────────────────────────────────────────
+example: |
+  name: bug-resolution
+  version: 10.2.0
+  description: "Pipeline chuẩn để diagnose và fix bugs."
+  owner:
+    type: engineering
+    maintained_by: qk-team
+  steps:
+    - id: understand
+      name: "Hiểu yêu cầu"
+      purpose: "Nhận diện mục tiêu cốt lõi"
+      required: true
+  escalation:
+    max_retries: 2
+    on_failure: "Report error and ask user"

package/.agents/docs/skill-classification.md

@@ -5,7 +5,7 @@ Skills are classified into behavioral groups that define their **Primary Objecti
 *Note: Actual verification depth is NOT determined by the skill itself, but must strictly follow the **Risk-based Verification Policy** defined in `AGENTS.md`.*
 
 ## 1. Static Analysis Skills
-*e.g., Code Review, Project Health, Architecture, Documentation*
+*e.g., qk-code-review, qk-product-spec, qk-orchestrator*
 - **Primary Goal:** Audit, analyze, or document without altering system behavior.
 - **Preferred Behavior:** Prefer static analysis (`read_file`, `grep_search`). Do not execute code or run test suites unless explicitly requested to validate the audit.