ai-developer-skill-os 7.5.1 → 8.1.4

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