ai-developer-skill-os 9.3.1 → 10.2.0

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.