agentera 3.0.0-dev.3 → 3.0.0-dev.31

package/bundle/skills/agentera/schemas/artifacts/health.yaml

@@ -1,12 +1,14 @@
 # Health Artifact Schema
 #
-# Audit log maintained by inspektera. Each audit entry records assessed
-# dimensions, findings (critical/warning/info counts), overall trajectory,
-# per-dimension grades (A-F), per-dimension findings with confidence, and
-# trend analysis against the prior audit.
+# Audit normally owns health records. Orchestrate may append only the limited
+# artifact_freshness record for terminal-plan closure after Audit passes. Each
+# audit entry records assessed dimensions, findings (critical/warning/info
+# counts), overall trajectory, per-dimension grades (A-F), per-dimension
+# findings with confidence, and trend analysis against the prior audit.
 #
-# Structural pattern: UPPER_CASE groups with numbered entries and stable IDs,
-# following capability_schema_contract.yaml and protocol.yaml conventions.
+# The active authority is one health_audit entity per writer-owned file. The
+# numbered projection model below is retained only as an exact legacy migration
+# input schema; it is not an ordinary read or write contract after cutover.
 #
 # ── Field-by-field mapping: v1 HEALTH.md → v2 health.yaml ──
 #
@@ -14,6 +16,7 @@
 # ─────────────────────────────────────────────────────────────────────
 # ## Audit N · date                     AUDIT.number           HA1
 # (date from heading)                   AUDIT.date             HA2
+# (CLI append time)                     AUDIT.appended_at      HA7
 # **Dimensions assessed**: <list>       AUDIT.dimensions       HA3
 # **Findings**: N crit, N warn, N info  AUDIT.findings_summary HA4
 # **Overall trajectory**: <text>        AUDIT.trajectory       HA5
@@ -49,14 +52,27 @@ meta:
   name: health
   version: "1.0.0"
   description: >-
-    Audit log maintained by inspektera. Consumed by capabilities that need
-    codebase health context.
+    Audit normally owns health records. Orchestrate may append only the
+    limited artifact_freshness record for terminal-plan closure after Audit
+    passes. Consumed by capabilities that need codebase health context.
   artifact_type: agent_facing
   path: ".agentera/health.yaml"
-  producer: inspektera
-  consumers: [dokumentera, hej, inspektera, orkestrera, planera, realisera, visionera]
+  authority: legacy_migration_input_only
+  producer: [audit, orchestrate]
+  consumers: [document, status, audit, orchestrate, plan, build, vision]
   format: yaml
 
+ENTITY_AUTHORITY:
+  identity_fields: [id, artifact]
+  artifact: health
+  boundary: health_audit
+  retrieval:
+    list: agentera state health list --format json
+    get: agentera state health get --id ID --format json
+  mutation: agentera state health explain --verb append --format json
+  direct_file_edits: forbidden
+  legacy_schema_below: migration_input_only
+
 GROUP_PREFIXES:
   BUDGET: HB
   COMPACTION: HX
@@ -87,10 +103,10 @@ BUDGET:
 COMPACTION:
   1:
     id: HX1
-    rule: uniform_10_40_50
+    rule: lossless_projection
     description: >-
-      Growing artifacts follow a uniform 10/40/50 rule: 10 full-detail
-      entries, 40 one-line archive entries, drop beyond 50 total.
+      The 10/40/50 values are current projection defaults, not deletion limits.
+      Numbered archive records remain complete and unlimited.
   2:
     id: HX2
     full_detail:
@@ -109,21 +125,27 @@ COMPACTION:
     description: >-
       Audits 11 through 50 are collapsed to one-line format under the
       archive section. One-line summaries preserve audit number, date,
-      overall grade, and trajectory.
+      overall grade, and trajectory. Entries beyond the summary default are
+      represented by omission metadata while their numbered archive records
+      remain available.
   4:
     id: HX4
-    dropped:
-      threshold: 50
-      action: "Removed entirely"
+    omission:
+      fields: [omitted, omitted_count, omission_reason, retrieval]
+      reason: projection_capacity_or_byte_budget
     description: >-
-      Audits older than 50 are dropped entirely.
+      Omitted projection detail is never silently deleted or truncated. The
+      numbered archive is the complete historical source and retrieval points
+      use the direct state get contract.
   5:
     id: HX5
-    trigger: "When inspektera writes a new audit"
+    trigger: "When audit writes a new audit"
     description: >-
       Compaction runs when the producing skill writes a new entry.
-      If >10 full-detail entries exist, collapse the oldest to one-line.
-      If >40 one-line entries exist, drop the oldest.
+      If >10 full-detail entries exist and their numbered archives verify,
+      collapse the oldest to one-line. If >40 summary entries exist, omit the
+      oldest from this bounded projection with metadata; never delete its
+      numbered archive record. Unverified entries remain full for recovery.
   6:
     id: HX6
     archive_section:
@@ -219,6 +241,21 @@ AUDIT:
     validation:
       - "Every assessed dimension has a grade"
       - "Grades are single characters A through F"
+  7:
+    id: HA7
+    field: appended_at
+    type: string
+    format: "YYYY-MM-DDTHH:mm:ss.sssZ"
+    required: false
+    cli_owned: true
+    description: >-
+      Canonical UTC timestamp assigned by the health append writer. Full records
+      with this field sort newest-first by append time, then stable ID. Legacy
+      records without it retain date-then-ID ordering; migration never fabricates
+      append chronology.
+    validation:
+      - "When present, must be canonical UTC ISO-8601 with millisecond precision"
+      - "Must be omitted from caller input and assigned by the CLI writer"
 
 DIMENSION:
   1:

package/bundle/skills/agentera/schemas/artifacts/objective.yaml

@@ -1,7 +1,7 @@
 # Objective Artifact Schema
 #
-# Optimization objective maintained by optimera. Each objective lives in its
-# own subdirectory under .agentera/optimera/<name>/ and captures the metric,
+# Optimization objective maintained by optimize. Each objective lives in its
+# own subdirectory under .agentera/optimize/<name>/ and captures the metric,
 # target, baseline, constraints, measurement method, gates, and scope.
 #
 # Structural pattern: UPPER_CASE groups with numbered entries and stable IDs,
@@ -47,12 +47,12 @@ meta:
   name: objective
   version: "1.0.0"
   description: >-
-    Optimization objective. Produced by optimera and resonera. Each objective
-    lives in its own subdirectory under .agentera/optimera/<name>/.
+    Optimization objective. Produced by optimize and discuss. Each objective
+    lives in its own subdirectory under .agentera/optimize/<name>/.
   artifact_type: agent_facing
-  path: ".agentera/optimera/<name>/objective.yaml"
-  producer: [optimera, resonera]
-  consumers: [hej, optimera, resonera]
+  path: ".agentera/optimize/<name>/objective.yaml"
+  producer: [optimize, discuss]
+  consumers: [status, optimize, discuss]
   format: yaml
 
 GROUP_PREFIXES:
@@ -78,6 +78,19 @@ BUDGET:
       bounded by the measurement description's inherent complexity.
 
 HEADER:
+  0:
+    id: OB_HDR0
+    field: id
+    type: string
+    required: true
+    description: >-
+      Stable objective identity in objective:<lowercase RFC 9562 UUID> form.
+      It is assigned when a new objective is published and remains unchanged
+      when the title or containing directory is renamed. Legacy objectives
+      without this field remain read-compatible through a derived identity and
+      an explicit compatibility caveat; reads never rewrite legacy bytes.
+    validation:
+      - "Matches objective:<lowercase-rfc9562-uuid>"
   1:
     id: OB_HDR1
     field: title
@@ -360,10 +373,11 @@ VALIDATION_RULES:
     rule: required_fields
     severity: error
     description: >-
-      The objective must have: title, status, description, why,
+      A newly published objective must have: stable id, title, status, description, why,
       measurement, metric (description, direction, unit), baseline,
       and scope (included, excluded).
     checks:
+      - "id is present and matches objective:<lowercase-rfc9562-uuid>"
       - "title is present and non-empty"
       - "status is present and is 'open' or 'closed'"
       - "description is present and non-empty"

package/bundle/skills/agentera/schemas/artifacts/plan.yaml

@@ -1,11 +1,12 @@
 # Plan Artifact Schema
 #
-# Active work plan maintained by planera. Each plan captures what will be built,
+# Current work plan maintained by plan. Each plan captures what will be built,
 # why, constraints, scope boundaries, design approach, tasks with dependencies
 # and acceptance criteria, overall acceptance, and surprises.
 #
-# Structural pattern: UPPER_CASE groups with numbered entries and stable IDs,
-# following capability_schema_contract.yaml and protocol.yaml conventions.
+# The active authority uses one plan or plan_task entity per writer-owned file.
+# The aggregate model and ordinal fields below are retained only as an exact
+# legacy migration input schema; they are not ordinary post-cutover contracts.
 #
 # ── Field-by-field mapping: v1 PLAN.md → v2 plan.yaml ──
 #
@@ -13,7 +14,7 @@
 # ─────────────────────────────────────────────────────────────────────
 # <!-- Level: light/full -->            HEADER.level           PL1
 # <!-- Created: date -->                HEADER.created         PL2
-# <!-- Status: active/completed -->     HEADER.status          PL3
+# <!-- Status: active/completed -->     HEADER.status          PL3 (normalized)
 # <!-- Reviewed: date -->               HEADER.reviewed        PL4
 # <!-- Critic issues: N found... -->    HEADER.critic_issues   PL5
 # <!-- Revised: description -->         HEADER.revised         PL6
@@ -32,6 +33,8 @@
 # **Acceptance**: <criteria list>       TASK.acceptance        PL19
 # ## Overall Acceptance                 PLAN.overall_acceptance PL20
 # ## Surprises                          PLAN.surprises         PL21
+# ## Unknowns                           UNKNOWN.entry          PU1
+# ## Rejected Review Findings           REJECTED.entry         PR1
 #
 # Protocol references:
 #   status visual tokens: VT1-VT4 (protocol.yaml VISUAL_TOKENS)
@@ -41,20 +44,37 @@ meta:
   name: plan
   version: "1.0.0"
   description: >-
-    Active work plan. Produced by planera and updated by plan executors.
+    Active work plan. Produced by plan and updated by plan executors.
     Consumed by capabilities that inspect or execute plan state.
   artifact_type: agent_facing
   path: ".agentera/plan.yaml"
-  producer: [orkestrera, planera, realisera]
-  consumers: [hej, inspektera, orkestrera, planera, realisera]
+  authority: legacy_migration_input_only
+  producer: [orchestrate, plan, build]
+  consumers: [status, audit, orchestrate, plan, build]
   format: yaml
 
+ENTITY_AUTHORITY:
+  identity_fields: [id, artifact]
+  artifact: plan
+  boundaries: [plan, plan_task]
+  relationship: plan_task.record.plan is a bare plan ID
+  retrieval:
+    list: agentera state plan list --format json
+    get: agentera state plan get --id ID --format json
+    tasks_list: agentera state plan tasks list [PLAN_ID] --format json
+    task_get: agentera state plan tasks get --id ID --format json
+  mutation: agentera state plan explain --format json
+  direct_file_edits: forbidden
+  legacy_schema_below: migration_input_only
+
 GROUP_PREFIXES:
   BUDGET: PB
   HEADER: PH
   PLAN: PL
   SCOPE: PS
   TASK: PT
+  UNKNOWN: PU
+  REJECTED: PR
   VALIDATION: PV
 
 BUDGET:
@@ -99,10 +119,11 @@ HEADER:
     type: string
     required: true
     description: >-
-      Plan lifecycle status. Active plans are being executed; complete
-      plans are candidates for archival.
+      Canonical plan lifecycle. Open plans are active candidates, complete
+       plans satisfy every task through completion or valid supersession, and
+       archived plans are historical or abandoned.
     validation:
-      - "Must be one of: active, complete"
+      - "Must be one of: open, complete, archived"
   4:
     id: PH4
     field: reviewed
@@ -134,10 +155,21 @@ HEADER:
     type: string
     required: true
     description: >-
-      Short plan title. Used in archive naming and plan listing.
+      Short plan title. Used in archive naming and active/archived plan listing.
       Format: 'Plan: <descriptive name>'.
     validation:
       - "Non-empty string"
+  8:
+    id: PH8
+    field: id
+    type: string
+    required: false
+    description: >-
+      Stable plan identity assigned by the typed writer at first publication and
+      retained unchanged when the plan moves from active to archived history.
+      Legacy plans without this field derive a read-only identity.
+    validation:
+      - "Must match plan:<lowercase RFC 9562 UUID> when present"
 
 PLAN:
   1:
@@ -191,7 +223,7 @@ PLAN:
     required: false
     description: >-
       Runtime surprises discovered during plan execution. Populated
-      by realisera when reality diverges from plan. Default: empty.
+      by build when reality diverges from plan. Default: empty.
   7:
     id: PL22
     field: previous_plan_archived
@@ -201,6 +233,62 @@ PLAN:
       Path to the previous active plan archived when this plan was created.
       Preserves plan lineage without changing lifecycle status.
 
+UNKNOWN:
+  1:
+    id: PU1
+    field: entry
+    type: map
+    required: true
+    description: >-
+      A planning-time question that can change whether downstream work remains
+      necessary as written. Full plans require at least one entry.
+    min_count: 1
+  2:
+    id: PU2
+    field: question
+    parent: UNKNOWN.entry
+    type: string
+    required: true
+    description: "The unresolved planning-time question."
+  3:
+    id: PU3
+    field: affects_task
+    parent: UNKNOWN.entry
+    type: integer
+    required: true
+    description: "The task number whose scope depends on the answer."
+  4:
+    id: PU4
+    field: resolve_by
+    parent: UNKNOWN.entry
+    type: string
+    required: true
+    description: "How the affected task will resolve the question."
+
+REJECTED:
+  1:
+    id: PR1
+    field: entry
+    type: map
+    required: true
+    description: >-
+      A dismissed adversarial-review finding preserved with its rationale.
+    min_count: 1
+  2:
+    id: PR2
+    field: issue
+    parent: REJECTED.entry
+    type: string
+    required: true
+    description: "The critic finding that was dismissed."
+  3:
+    id: PR3
+    field: rationale
+    parent: REJECTED.entry
+    type: string
+    required: true
+    description: "Why the finding was dismissed rather than addressed."
+
 SCOPE:
   1:
     id: PS11
@@ -268,7 +356,7 @@ TASK:
       Task execution status. Uses visual tokens from protocol.yaml
       VISUAL_TOKENS (VT1-VT4) for display.
     validation:
-      - "Must be one of: complete, in_progress, pending, blocked"
+      - "Must be one of: complete, in_progress, pending, blocked, superseded"
   5:
     id: PT19
     field: acceptance
@@ -278,11 +366,37 @@ TASK:
       Acceptance criteria for this task. Each entry is a GIVEN/WHEN/THEN
       statement that must hold for the task to be considered complete.
       Required for full-level plans.
+  6:
+    id: PT20
+    field: evaluation
+    type: mapping
+    required: false
+    description: >-
+      CLI-owned evaluator state written only by `agentera state plan
+      record-evaluation`. It records attempt and failure counts, the latest
+       verdict, retained failure evidence, and stable attempt provenance.
+  7:
+    id: PT21
+    field: superseded_by
+    type: list[string]
+    required: false
+    description: >-
+      CLI-owned completed replacement task IDs from the same plan. Required only
+      when status is superseded; IDs must be distinct and the replacements remain
+      complete.
+  8:
+    id: PT22
+    field: superseded_reason
+    type: string
+    required: false
+    description: >-
+      CLI-owned required explanation, at most 500 characters, for a superseded
+      task. Present only with superseded_by when status is superseded.
 
 VALIDATION:
   1:
     id: PV1
-    rule: unique_task_numbers
+    rule: unique_entity_ids
     severity: error
     description: >-
       Task numbers must be unique within a plan and sequential.
@@ -300,7 +414,7 @@ VALIDATION:
     checks:
       - "level is present and is 'light' or 'full'"
       - "created is present and matches YYYY-MM-DD"
-      - "status is present and is 'active' or 'completed'"
+      - "status is present and is 'open', 'complete', or 'archived'"
       - "title is present and non-empty"
       - "what is present and non-empty"
       - "why is present and non-empty"
@@ -340,3 +454,201 @@ VALIDATION:
     checks:
       - "Per-task word count <= 100"
       - "Total file word count <= 2500"
+
+LIFECYCLE_CONTRACT:
+  authority: this schema
+  canonical:
+    identity:
+      field: header.id
+      format: 'plan:<lowercase-rfc9562-uuid>'
+      assignment: The typed create writer assigns identity at first publication.
+      transition: Active and archived positions retain the identical identity.
+      legacy: Missing identity is derived deterministically at read time without rewriting bytes.
+      collision: Different documents with one identity are ambiguous and never selected by path or time.
+    persisted_status:
+      field: header.status
+      values:
+        - open
+        - complete
+        - archived
+      meaning:
+        open: Work is active and unfinished.
+        complete: Every task is complete or validly superseded.
+        archived: Historical or abandoned source; tasks may be incomplete or empty.
+    position:
+      active: A unique open entity plan supplies the default active selection.
+      archived: Archived lifecycle marks historical or abandoned entity plans; legacy archives occupy the sibling archive directory.
+      persisted: true
+    execution:
+      eligible: Only a plan at the current-plan path can supply executable work.
+      archived: An archived plan is historical and non-executable regardless of status.
+    forced_archive:
+      unfinished_status: archived
+      effect: Move the plan to immutable history without claiming completion or changing tasks.
+  compatibility:
+    legacy_read_window:
+      scope: >-
+        Read normalization and typed-writer canonicalization of plan-level
+        active to open and completed to complete for artifacts produced by
+        pre-canonical Agentera versions at the docs-mapped current-plan path
+        or its sibling archive directory.
+      writers: Ordinary create and status writers emit open or complete; only archive lifecycle and migration emit archived.
+      removal_condition: >-
+        Remove normalization only after the deterministic migration covers
+        current plans, archives, fixtures, and bundled upgrade inputs, and
+        regression tests prove no supported producer can emit a legacy value.
+      test_boundary:
+        - current plan with active normalizes to open and reports legacy input
+        - archived plan with active normalizes to open and remains non-executable
+        - completed normalizes to complete only at the plan-level compatibility seam
+        - canonical writers reject active and completed after migration support lands
+        - typed writes canonicalize a legacy current plan before publication
+    external_consumers:
+      evidence: >-
+        No shipped SDK, adapter, or package reads header.status directly;
+        supported consumers use the CLI plan discovery and state contracts.
+      commitment: No compatibility window is provided for direct YAML consumers.
+  inventory:
+    method: >-
+      Classification is pattern-based and enforced by a bounded repository
+      scan. Every file under scan.roots containing a discovery marker must
+      match at least one family pattern unless an explicit exclusion applies.
+    scan:
+      roots:
+        - .
+      symlinks: Excluded because their targets may leave the repository boundary.
+      excluded_directory_names:
+        names:
+          - .git
+          - node_modules
+          - .pnpm-store
+          - .venv
+          - .pytest_cache
+          - .ruff_cache
+          - .cache
+          - .snapshots
+          - __pycache__
+          - dist
+          - build
+          - coverage
+          - bundle
+          - .astro
+          - .svelte-kit
+          - .wrangler
+        reason: >-
+          Directory-name pruning prevents traversal of VCS metadata, vendor
+          dependencies, environments, caches, snapshots, bytecode, and generated
+          build or publication outputs at any repository depth.
+      markers:
+        - planDocumentParts
+        - discoverPlanArtifacts
+        - resolvePlanTaskEvidence
+        - header.status
+        - previous_plan_archived
+        - plan_archive
+        - state plan
+        - .agentera/plan.yaml
+        - plan.yaml
+        - state.plan.
+        - artifact: plan
+        - artifact: plan
+        - active plan
+        - archived plan
+        - plan lifecycle
+      exclusions:
+        - patterns: [.git, .git/**]
+          reason: Git object and worktree metadata is not a repository contract surface.
+        - patterns: [node_modules, node_modules/**, "**/node_modules", "**/node_modules/**"]
+          reason: Installed third-party dependencies are vendor content.
+        - patterns: [.pnpm-store, .pnpm-store/**, .venv, .venv/**]
+          reason: Package and Python environments are external dependency caches.
+        - patterns: [.pytest_cache, .pytest_cache/**, .ruff_cache, .ruff_cache/**]
+          reason: Tool caches are generated and carry no product contract.
+        - patterns: ["**/.cache", "**/.cache/**", .snapshots, .snapshots/**]
+          reason: Caches and filesystem snapshots are generated or external state.
+        - patterns: ["**/dist", "**/dist/**", "**/build", "**/build/**", "**/coverage", "**/coverage/**"]
+          reason: Compiled, bundled, and coverage outputs are generated from classified sources.
+        - patterns: [packages/cli/bundle, packages/cli/bundle/**, "**/.astro", "**/.astro/**", "**/.svelte-kit", "**/.svelte-kit/**"]
+          reason: Runtime bundles and framework outputs are generated publication artifacts.
+        - patterns: [.wrangler, .wrangler/**, "**/.wrangler", "**/.wrangler/**", "*.tgz", "**/*.tgz"]
+          reason: Deployment outputs and package tarballs are generated publication artifacts.
+        - patterns: [.env, .env.*, "**/.env", "**/.env.*", "*.pem", "**/*.pem", "*.key", "**/*.key"]
+          reason: Local secret files are neither read nor classified by repository contract tests.
+        - patterns:
+            - references/adapters/runtime-lifecycle-*.yaml
+            - packages/cli/src/runtime/lifecycle*.ts
+            - packages/cli/src/upgrade/lifecycle*.ts
+            - packages/cli/test/runtime/lifecycle*.test.ts
+            - packages/cli/test/upgrade/lifecycle*.test.ts
+            - packages/cli/test/cli/lifecycle*.test.ts
+            - packages/cli/test/validate/lifecycle*.test.ts
+          reason: These surfaces govern runtime installation lifecycle, not plan artifact lifecycle.
+    readers:
+      - src/**
+      - hooks/**
+      - .opencode/plugins/**/*.js
+      - packages/cli/src/cli/plan*.ts
+      - packages/cli/src/cli/orientation.ts
+      - packages/cli/src/cli/appContext.ts
+      - packages/cli/src/cli/commands/state/plan*.ts
+      - packages/cli/src/state/plan*.ts
+      - packages/cli/src/state/durability.ts
+      - packages/cli/src/cli/commands/prime/*.ts
+      - packages/cli/src/cli/capabilityContext/*.ts
+      - packages/cli/src/cli/contracts/orientationState.ts
+      - packages/cli/src/cli/startupCompletenessContract.ts
+      - packages/cli/src/hooks/sessionStart.ts
+      - packages/cli/src/eval/evalSkills.ts
+    writers:
+      - packages/cli/src/state/write/*.ts
+      - packages/cli/src/state/entityStorage.ts
+      - packages/cli/src/cli/commands/state/write.ts
+    migrators:
+      - packages/cli/src/upgrade/migrateArtifacts*.ts
+      - packages/cli/src/upgrade/upgradeOrchestrator.ts
+      - packages/cli/src/upgrade/doctor.ts
+      - packages/cli/src/cli/commands/prime/v1Migration.ts
+      - packages/cli/src/state/entityMigration*.ts
+      - packages/cli/src/state/canonicalMigrationRecord.ts
+    schemas:
+      - skills/agentera/schemas/artifacts/*.yaml
+      - skills/agentera/capabilities/*/schemas/*.yaml
+      - skills/agentera/capability_schema_contract.yaml
+    adapters:
+      - references/**/*.yaml
+      - packages/cli/src/registries/*.ts
+      - packages/cli/src/state/retrievalAuthority.ts
+      - packages/cli/src/state/projectionPolicy.ts
+      - packages/cli/src/state/startupAnalysis/*.ts
+      - packages/cli/src/cli/commands/schema.ts
+      - packages/cli/src/cli/commands/validate.ts
+      - packages/cli/src/cli/help.ts
+      - packages/cli/src/cli/prime-blob.ts
+      - packages/cli/src/hooks/validateArtifact/*.ts
+      - packages/cli/src/validate/selfAudit.ts
+      - packages/cli/src/hooks/compaction/*.ts
+      - packages/cli/src/cli/dispatch/*.ts
+      - .agentera/docs.yaml
+      - scripts/**
+    fixtures:
+      - packages/cli/test/**/*.ts
+      - packages/cli/test/**/*.md
+      - packages/cli/test/fixtures/**
+      - packages/cli/test/fixtures/**/.agentera/*
+      - packages/cli/test/upgrade/fixtures/**
+      - packages/cli/test/upgrade/fixtures/**/.agentera/*
+      - packages/cli/test/cli/fixtures/**
+      - tests/**
+      - fixtures/**
+      - .agentera/**
+    documented_external_commitments:
+      - packages/cli/src/capabilities/*/instructions.ts
+      - packages/cli/README.md
+      - skills/agentera/SKILL.md
+      - skills/agentera/references/*
+      - references/**/*.md
+      - docs/**
+      - "*.md"
+      - AGENTS.md
+      - README.md
+      - UPGRADE.md