agentera 0.0.0 → 3.0.0-dev.1

package/bundle/skills/agentera/capability_schema_contract.yaml

@@ -0,0 +1,385 @@
+# Capability Schema Contract
+#
+# Self-referential: this file IS a valid capability schema.
+# Validating it against its own rules passes.
+#
+# The contract defines:
+#   1. Required groups every capability schema must contain
+#   2. Entry structure within each group (numbered, stable IDs)
+#   3. Deprecation protocol (deprecated + replaced_by)
+#   4. Directory structure requirements (instructions.md, schemas/)
+#   5. Machine-readable validation rules consumed by future contract loaders
+
+meta:
+  name: capability_schema_contract
+  version: "1.0.0"
+  description: >-
+    Defines what a valid capability schema looks like.
+    A capability directory must contain instructions.md and a schemas/ directory.
+    The union of all YAML files in schemas/ must contain all required groups.
+  capability_type: contract
+  self_referential: true
+
+REQUIRED_GROUPS:
+  - TRIGGERS
+  - ARTIFACTS
+  - VALIDATION
+  - EXIT_CONDITIONS
+
+ENTRY_SCHEMA:
+  description: >-
+    Every entry within a group follows this structure.
+    Entries are numbered map keys (1, 2, 3, ...).
+    Each entry MUST have a stable `id` field.
+    Entries MAY carry `deprecated: true` and `replaced_by: <id>`.
+  fields:
+    id:
+      type: string
+      required: true
+      description: "Stable identifier that survives renames. Format: <GROUP_PREFIX><N> (e.g. T1, A3, V2, E1)."
+    description:
+      type: string
+      required: true
+      description: Human-readable explanation of this entry.
+    priority:
+      type: string
+      required: false
+      description: >-
+        Priority of this trigger entry for routing confidence. Used in the
+        five-layer routing model (Decision 42). Valid values: high, medium, low.
+        Required for all TRIGGERS entries.
+    deprecated:
+      type: boolean
+      required: false
+      default: false
+      description: Mark this entry as deprecated. Deprecated entries must not be removed.
+    replaced_by:
+      type: string
+      required: false
+      description: >-
+        ID of the entry that replaces this deprecated entry.
+        Required when deprecated is true. Must reference a valid entry ID
+        within the same group.
+
+GROUP_PREFIXES:
+  TRIGGERS: T
+  ARTIFACTS: A
+  VALIDATION: V
+  EXIT_CONDITIONS: E
+
+DIRECTORY_REQUIREMENTS:
+  instruction_file:
+    path: instructions.md
+    type: file
+    required: true
+    description: Behavioral instructions the agent reads.
+  schemas_directory:
+    path: schemas
+    type: directory
+    required: true
+    description: Directory containing YAML schema files.
+  schema_files:
+    directory: schemas
+    glob: "*.yaml"
+    minimum_count: 1
+    description: Capability schema files whose union must satisfy REQUIRED_GROUPS.
+  optional_files: []
+
+ENTRY_REQUIREMENTS:
+  description: >-
+    Structured entry rules for each required capability schema group. These
+    rules mirror current validator behavior and keep enforcement contract-owned.
+  default_required_fields:
+    - id
+    - description
+  groups:
+    TRIGGERS:
+      required_fields:
+        - id
+        - description
+        - priority
+    ARTIFACTS:
+      required_fields:
+        - id
+        - description
+    VALIDATION:
+      required_fields:
+        - id
+        - description
+    EXIT_CONDITIONS:
+      required_fields:
+        - id
+        - description
+  deprecation:
+    marker_field: deprecated
+    marker_value: true
+    replacement_field: replaced_by
+    replacement_required_when_deprecated: true
+    replacement_scope: same_group
+    replacement_target_field: id
+    unresolved_replacement_severity: warning
+    preserve_deprecated_entries: true
+
+FIELD_RULES:
+  TRIGGERS:
+    priority:
+      required: true
+      allowed_values:
+        - high
+        - medium
+        - low
+      description: Priority of this trigger entry for routing confidence.
+
+PRIMITIVE_REFERENCE_FIELDS:
+  description: >-
+    Capability schema fields that reference protocol primitive groups. This
+    contract owns the field-to-group mapping; protocol.yaml owns the primitive
+    group definitions and allowed values.
+  protocol_values_authority: protocol.yaml
+  fields:
+    severity:
+      protocol_groups:
+        - SEVERITY_FINDING
+        - SEVERITY_ISSUE
+    finding_severity:
+      protocol_groups:
+        - SEVERITY_FINDING
+    issue_severity:
+      protocol_groups:
+        - SEVERITY_ISSUE
+    decision_label:
+      protocol_groups:
+        - DECISION_LABELS
+    exit_signal:
+      protocol_groups:
+        - EXIT_SIGNALS
+    phase:
+      protocol_groups:
+        - PHASES
+
+ROUTE_ALIASES:
+  description: >-
+    Primary plain slash-route aliases from Decision 43. These aliases are exact
+    `/agentera <alias>` routes for users; the Swedish -era capability directory
+    names remain canonical protocol identity. Alias routes are not CLI commands.
+  route_prefix: /agentera
+  canonical_name_precedence: true
+  cli_boundary: >-
+    Slash routes and state commands are distinct: `/agentera plan` routes to
+    planera, while `agentera plan` remains the state-oriented CLI command for
+    reading plan state. Do not add non-hej capability or alias commands to the
+    CLI.
+  primary_aliases:
+    - alias: status
+      capability: hej
+    - alias: vision
+      capability: visionera
+    - alias: discuss
+      capability: resonera
+    - alias: research
+      capability: inspirera
+    - alias: plan
+      capability: planera
+    - alias: build
+      capability: realisera
+    - alias: optimize
+      capability: optimera
+    - alias: audit
+      capability: inspektera
+    - alias: document
+      capability: dokumentera
+    - alias: profile
+      capability: profilera
+    - alias: design
+      capability: visualisera
+    - alias: orchestrate
+      capability: orkestrera
+
+# ---------------------------------------------------------------------------
+# The four required groups follow. The contract IS a valid capability schema,
+# so these groups demonstrate the structure they define.
+# ---------------------------------------------------------------------------
+
+TRIGGERS:
+  1:
+    id: T1
+    description: >-
+      Validate a capability directory. Invoked when checking if a capability
+      conforms to this contract (directory structure, required groups, entry
+      structure, deprecation consistency).
+    priority: high
+    patterns:
+      - "validate a capability"
+      - "check capability schema"
+      - "validate schema contract"
+  2:
+    id: T2
+    description: >-
+      Parse a capability schema YAML file. Invoked when reading a single schema
+      file to verify it contains properly structured entries within its groups.
+    priority: medium
+    patterns:
+      - "parse capability schema"
+      - "read schema file"
+  3:
+    id: T3
+    description: >-
+      Schema evolution check. Invoked when verifying that deprecated entries
+      have valid replaced_by references and no orphaned deprecation chains.
+    priority: medium
+    patterns:
+      - "check deprecation"
+      - "schema evolution"
+  4:
+    id: T4
+    description: >-
+      Self-validation. The contract file validates against its own rules.
+      Ensures the meta-schema is a correct instance of itself.
+    priority: medium
+    patterns:
+      - "self-validate contract"
+      - "validate schema contract against itself"
+
+ARTIFACTS:
+  1:
+    id: A1
+    name: capability_directory
+    path: "capabilities/<name>/"
+    description: >-
+      A valid capability directory. Must contain instructions.md and schemas/.
+      The schemas/ directory holds YAML files whose union covers all required
+      groups.
+    produces: false
+    consumes: true
+  2:
+    id: A2
+    name: schema_file
+    path: "capabilities/<name>/schemas/<filename>.yaml"
+    description: >-
+      A YAML file within a capability's schemas/ directory. Contains one or
+      more groups (TRIGGERS, ARTIFACTS, VALIDATION, EXIT_CONDITIONS). Multiple
+      files are allowed; the validator checks their union for completeness.
+    produces: false
+    consumes: true
+  3:
+    id: A3
+    name: instruction_file
+    path: "capabilities/<name>/instructions.md"
+    description: >-
+      Behavioral instructions the agent reads. Markdown format. Contains the
+      capability's workflow, personality, interaction rules, and examples.
+    produces: false
+    consumes: true
+  4:
+    id: A4
+    name: validation_report
+    path: "stdout"
+    description: >-
+      Output of the validation script. Reports pass/fail per check, with
+      details on any violations found.
+    produces: true
+    consumes: false
+
+VALIDATION:
+  1:
+    id: V1
+    rule: directory_structure
+    description: >-
+      Capability directory must contain instructions.md and schemas/ directory.
+    severity: error
+    checks:
+      - "instructions.md is a file"
+      - "schemas/ is a directory"
+      - "schemas/ contains at least one .yaml file"
+  2:
+    id: V2
+    rule: required_groups_present
+    description: >-
+      The union of all YAML files in schemas/ must contain all four required
+      groups: TRIGGERS, ARTIFACTS, VALIDATION, EXIT_CONDITIONS.
+    severity: error
+    checks:
+      - "TRIGGERS group exists in at least one schema file"
+      - "ARTIFACTS group exists in at least one schema file"
+      - "VALIDATION group exists in at least one schema file"
+      - "EXIT_CONDITIONS group exists in at least one schema file"
+  3:
+    id: V3
+    rule: numbered_entries
+    description: >-
+      Each group must contain numbered entries (1, 2, 3, ...) as map keys.
+      Non-numeric keys within groups are not allowed.
+    severity: error
+    checks:
+      - "Group keys are positive integers"
+  4:
+    id: V4
+    rule: stable_ids
+    description: >-
+      Every entry must have a stable `id` field. The id should follow the
+      GROUP_PREFIX pattern (T for TRIGGERS, A for ARTIFACTS, V for VALIDATION,
+      E for EXIT_CONDITIONS) followed by a number.
+    severity: error
+    checks:
+      - "Each entry has an 'id' field"
+      - "Each entry has a 'description' field"
+  5:
+    id: V5
+    rule: deprecation_consistency
+    description: >-
+      Entries marked deprecated: true must have a replaced_by field. The
+      replaced_by value must reference a valid entry ID within the same group.
+      Deprecated entries must not be removed; they stay for referential
+      integrity.
+    severity: warning
+    checks:
+      - "deprecated entries have replaced_by field"
+      - "replaced_by references a valid entry ID"
+  6:
+    id: V6
+    rule: self_referential
+    description: >-
+      The capability schema contract file must pass its own validation rules.
+      This ensures the meta-schema is internally consistent.
+    severity: error
+    checks:
+      - "Contract file contains all required groups"
+      - "Contract file entries follow entry schema structure"
+      - "Contract file passes deprecation consistency check"
+
+EXIT_CONDITIONS:
+  1:
+    id: E1
+    condition: valid
+    description: >-
+      All validation checks pass. The capability directory conforms to the
+      schema contract.
+    exit_code: 0
+  2:
+    id: E2
+    condition: invalid_structure
+    description: >-
+      Directory structure validation failed. Missing instructions.md, schemas/
+      directory, or YAML files.
+    exit_code: 1
+  3:
+    id: E3
+    condition: missing_groups
+    description: >-
+      One or more required groups are absent from the union of schema files.
+    exit_code: 1
+  4:
+    id: E4
+    condition: invalid_entries
+    description: >-
+      Entries within groups violate the entry schema (missing id, unnumbered
+      keys, missing description).
+    exit_code: 1
+  5:
+    id: E5
+    condition: deprecation_warnings
+    description: >-
+      Deprecated entries have inconsistent replaced_by references. Treated as
+      warnings, not errors. Validation still passes (exit 0) but reports are
+      emitted to stderr.
+    exit_code: 0