# =============================================================================
# PM-Skills Frontmatter Schema
# =============================================================================
#
# Version: 2.7.0
# Specification baseline: https://agentskills.io/specification
#
# Repo-native reference for SKILL.md files in pm-skills. This document reflects
# the rules currently enforced by scripts/lint-skills-frontmatter.sh/.ps1.
#
# =============================================================================

schema:
  overview: |
    Every skills/*/SKILL.md file uses agentskills-compatible frontmatter plus
    pm-skills repo rules for versioning, lifecycle grouping, and validation.

    Current repo model:
    - `name` and `description` remain the universal agentskills fields
    - `version`, `updated`, and `license` are required at the root
    - `phase` is required for domain skills
    - `classification` is used only when the skill is not phase-based
    - `metadata.version` is not allowed

  required:
    name:
      type: string
      pattern: "^[a-z0-9]+(-[a-z0-9]+)*$"
      description: |
        Unique skill identifier. Must match the parent directory name exactly.
        Use lowercase letters, numbers, and hyphens only.
      examples:
        valid:
          - deliver-prd
          - define-problem-statement
          - foundation-persona
        invalid:
          - Deliver-PRD
          - deliver_prd
          - prd

    description:
      type: string
      minLength: 1
      maxLength: 1024
      description: |
        Human and machine-readable summary for discovery and invocation.
        Use the pattern: [Action] [artifact/output]. Use when [trigger 1],
        [trigger 2], or [trigger 3].
      examples:
        - |
          Creates a comprehensive Product Requirements Document that aligns
          stakeholders on what to build, why, and how success will be measured.
          Use when specifying features, epics, or product initiatives for
          engineering handoff.

    version:
      type: string
      pattern: "^\\d+\\.\\d+\\.\\d+$"
      description: |
        Semantic version for the skill. Must appear exactly once at the root
        level and must be quoted.
      examples:
        - '"1.0.0"'
        - '"2.5.0"'

    updated:
      type: string
      pattern: "^\\d{4}-\\d{2}-\\d{2}$"
      description: |
        Last updated date in ISO format (YYYY-MM-DD).
      examples:
        - 2026-01-26
        - 2026-03-02

    license:
      type: string
      description: |
        SPDX license identifier. pm-skills uses Apache-2.0 for shipped skills.
      examples:
        - Apache-2.0

  conditional:
    classification:
      type: string
      enum:
        - domain
        - foundation
        - utility
      description: |
        Optional root field describing the skill family.

        Rules:
        - Omit for ordinary domain skills if you want default domain behavior
        - Use `foundation` for non-phase foundation skills
        - Use `utility` for non-phase helper skills

    phase:
      type: string
      enum:
        - discover
        - define
        - develop
        - deliver
        - measure
        - iterate
      description: |
        Root lifecycle phase for domain skills.

        Rules:
        - Required when `classification` is `domain`
        - Required when `classification` is omitted
        - Must be omitted when `classification` is `foundation` or `utility`

  metadata:
    description: |
      Optional repo metadata for categorization and discoverability. These
      fields may be omitted, but shipped skills typically include them.
    properties:
      category:
        type: string
        enum:
          - research
          - problem-framing
          - ideation
          - specification
          - validation
          - reflection
          - coordination
        description: |
          Framework-agnostic PM activity type.
      frameworks:
        type: array
        items:
          type: string
        description: |
          Supported methodologies such as triple-diamond, lean-startup,
          design-thinking, scrum, kanban, or safe.
      author:
        type: string
        description: |
          Skill creator or maintainer identifier.

  examples:
    domain_skill: |
      ---
      name: deliver-prd
      description: Creates a comprehensive Product Requirements Document that aligns stakeholders on what to build, why, and how success will be measured. Use when specifying features, epics, or product initiatives for engineering handoff.
      phase: deliver
      version: "2.0.0"
      updated: 2026-01-26
      license: Apache-2.0
      metadata:
        category: specification
        frameworks: [triple-diamond, lean-startup, design-thinking]
        author: product-on-purpose
      ---

    foundation_skill: |
      ---
      name: foundation-persona
      description: Generates an evidence-calibrated product or marketing persona using the canonical v2.5 output contract. Use when shaping artifact perspective, stress-testing decisions, or framing product and GTM strategy.
      classification: foundation
      version: "2.5.0"
      updated: 2026-03-02
      license: Apache-2.0
      metadata:
        category: research
        frameworks: [triple-diamond, lean-startup, design-thinking]
        author: product-on-purpose
      ---

    utility_skill: |
      ---
      name: utility-pm-skill-builder
      description: Guides contributors from a PM skill idea to a complete Skill Implementation Packet aligned with pm-skills conventions. Runs gap analysis, validates through a Why Gate, classifies by type and phase, generates draft files, and writes to a staging area for review before promotion.
      classification: utility
      version: "1.0.0"
      updated: 2026-03-22
      license: Apache-2.0
      metadata:
        category: coordination
        frameworks: [triple-diamond]
        author: product-on-purpose
      ---

  validation:
    rules:
      - id: required-name
        field: name
        rule: must be present and match the parent directory name
        severity: error

      - id: required-description
        field: description
        rule: must be present
        severity: error

      - id: required-version
        field: version
        rule: must exist exactly once at the root and match semantic versioning
        severity: error

      - id: required-updated
        field: updated
        rule: must exist at the root and use YYYY-MM-DD format
        severity: error

      - id: required-license
        field: license
        rule: must exist at the root
        severity: error

      - id: no-metadata-version
        field: metadata.version
        rule: must not exist
        severity: error

      - id: phase-required-for-domain
        field: phase
        rule: required when classification is domain or omitted
        severity: error

      - id: phase-omitted-for-foundation
        field: phase
        rule: must be omitted when classification is foundation or utility
        severity: error

  common_mistakes:
    - mistake: "Using metadata.version"
      incorrect: |
        metadata:
          version: "1.0.0"
      correct: |
        version: "1.0.0"
      explanation: "pm-skills allows only one quoted root version field."

    - mistake: "Foundation skill declares a phase"
      incorrect: |
        classification: foundation
        phase: define
      correct: |
        classification: foundation
      explanation: "Foundation and utility skills omit phase."

    - mistake: "Domain skill omits phase"
      incorrect: |
        name: deliver-launch-checklist
        version: "1.0.0"
      correct: |
        name: deliver-launch-checklist
        phase: deliver
        version: "1.0.0"
      explanation: "Domain skills require one of the six lifecycle phases."