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

package/bundle/skills/agentera/capabilities/{visionera → vision}/schemas/artifacts.yaml

@@ -1,57 +1,57 @@
 ARTIFACTS:
   1:
     id: A1
-    artifact_id: vision
+    artifact: vision
     local_role: produces_and_consumes
     description: >-
-      Visionera writes and refines project direction, principles, personas,
+      Vision writes and refines project direction, principles, personas,
       aspirations, and identity.
   2:
     id: A2
-    artifact_id: decisions
+    artifact: decisions
     local_role: consumes
     description: >-
-      Visionera reads this to detect shifted thinking during refine mode
+      Vision reads this to detect shifted thinking during refine mode
       and to surface unresolved tensions with the vision.
   3:
     id: A3
-    artifact_id: progress
+    artifact: progress
     local_role: consumes
     description: >-
-      Visionera reads this during refine mode to understand what has been
+      Vision reads this during refine mode to understand what has been
       built since the vision was last updated.
   4:
     id: A4
-    artifact_id: health
+    artifact: health
     local_role: consumes
     description: >-
-      Visionera reads this to understand structural realities that
+      Vision reads this to understand structural realities that
       constrain or inform the vision.
   5:
     id: A5
-    artifact_id: todo
+    artifact: todo
     local_role: consumes
     description: >-
-      Visionera reads this during refine mode to detect recurring problems
+      Vision reads this during refine mode to detect recurring problems
       that suggest the vision needs adjustment.
   6:
     id: A6
-    artifact_id: design
+    artifact: design
     local_role: consumes
     description: >-
-      Visionera reads this during codebase exploration to ensure the
+      Vision reads this during codebase exploration to ensure the
       Identity section in project direction coheres with the visual system.
   7:
     id: A7
-    artifact_id: docs
+    artifact: docs
     local_role: consumes
     description: >-
-      Visionera reads this first to resolve project-local artifact mappings
+      Vision reads this first to resolve project-local artifact mappings
       before accessing other artifacts.
   8:
     id: A8
-    artifact_id: profile
+    artifact: profile
     local_role: consumes
     description: >-
-      Visionera reads this to calibrate the vision conversation: high-confidence
+      Vision reads this to calibrate the vision conversation: high-confidence
       entries become proposed principles.

package/bundle/skills/agentera/capabilities/{visionera → vision}/schemas/exit.yaml

@@ -3,9 +3,9 @@ EXIT_CONDITIONS:
     id: E1
     condition: complete
     description: >-
-      VISION.md was written (Create/Replace mode) or updated (Refine mode)
-      with explicit user approval. The vision is ambitious, concrete, and
-      structured to sustain autonomous development.
+      The vision artifact was written (Create/Replace mode) or updated
+      (Refine mode) with explicit user approval. The vision is ambitious,
+      concrete, and structured to sustain autonomous development.
     exit_signal: complete
   2:
     id: E2
@@ -14,14 +14,15 @@ EXIT_CONDITIONS:
       The vision was produced but with weaknesses worth surfacing: the user
       settled for a less ambitious or less specific vision than pushed for,
       key sections (personas, principles, direction) are thin due to limited
-      conversation depth, or the vision has unresolved tensions with existing
-      DECISIONS.md entries.
+      conversation depth, or the vision has unresolved tensions with
+      existing decision entries.
     exit_signal: flagged
   3:
     id: E3
     condition: stuck
     description: >-
-      Cannot write VISION.md because the user declined to approve the draft
+      Cannot write the vision artifact because the user declined to approve
+      the draft
       and no actionable revision direction was given, or codebase exploration
       failed in a way that would make the vision unreliable.
     exit_signal: stuck

package/bundle/skills/agentera/capabilities/vision/schemas/triggers.yaml

@@ -0,0 +1,23 @@
+TRIGGERS:
+  1:
+    id: T1
+    description: Requests to define or refine the project's vision and direction.
+    priority: high
+  2:
+    id: T2
+    description: Define a new north star, product direction, or desired future.
+    priority: high
+  3:
+    id: T3
+    description: Refine, rethink, or update an existing vision or north star.
+    priority: high
+    disambiguates_against:
+      - capability: build
+        hint: "vision refines existing project direction; build implements code"
+  4:
+    id: T4
+    description: Establish a new project's identity or decide what it should become.
+    priority: high
+    disambiguates_against:
+      - capability: plan
+        hint: "vision defines what a project should become; plan structures the work"

package/bundle/skills/agentera/capabilities/{visionera → vision}/schemas/validation.yaml

@@ -3,8 +3,8 @@ VALIDATION:
     id: V1
     rule: user_approval_required
     description: >-
-      VISION.md MUST NOT be written or modified without explicit user
-      approval. Present drafts and get confirmation before writing.
+      The vision artifact MUST NOT be written or modified without explicit
+      user approval. Present drafts and get confirmation before writing.
       This applies to both Create and Refine modes.
     severity: critical
     checks:
@@ -14,12 +14,12 @@ VALIDATION:
     id: V2
     rule: no_realisera_modification
     description: >-
-      VISION.md MUST NOT be modified during a realisera execution cycle.
-      Vision changes happen only in dedicated visionera sessions. This
-      prevents vision drift during autonomous development.
+      The vision artifact MUST NOT be modified during a build execution
+      cycle. Vision changes happen only in dedicated vision sessions.
+      This prevents vision drift during autonomous development.
     severity: critical
     checks:
-      - "VISION.md not written during realisera cycle"
+      - "Vision artifact not written during build cycle"
   3:
     id: V3
     rule: inspirational_tone
@@ -29,13 +29,13 @@ VALIDATION:
       should inspire and guide, not specify.
     severity: warning
     checks:
-      - "VISION.md is aspirational, not prescriptive"
+      - "The vision artifact is aspirational, not prescriptive"
   4:
     id: V4
     rule: codebase_exploration_required
     description: >-
       When code exists, the codebase exploration step (Step 1) MUST NOT
-      be skipped. Arriving informed distinguishes visionera from a
+      be skipped. Arriving informed distinguishes vision from a
       blank-slate interview.
     severity: critical
     checks:
@@ -46,26 +46,24 @@ VALIDATION:
     description: >-
       The vision MUST be concrete enough to guide autonomous development.
       "Make a great tool" is not a vision. It must include specific
-      direction, principles, and enough detail for planera to derive tasks.
+      direction, principles, and enough detail for plan to derive tasks.
     severity: critical
     checks:
       - "Vision contains specific direction"
       - "Vision contains actionable principles"
-  6:
-    id: V6
-    rule: principle_brevity
-    description: >-
-      Each principle in VISION.md MUST be ≤20 words. Principles are
-      decision guides, not essays. Brevity forces clarity.
-    severity: warning
-    checks:
-      - "Each principle ≤ 20 words"
+  # V6 (principle_brevity) retired per Decision 81: linter does not enforce word
+  # count on principle descriptions; the live vision artifact violates the limit
+  # intentionally (principles carry rationale, not just labels). The
+  # MUST-state-tradeoff / SHOULD-name-prevention / MUST-NOT-name-implementations
+  # rules in capability instructions and the lint abstraction/filler checks
+  # cover principle quality holistically. ID gap (V6 → V7) preserved to avoid
+  # breaking external references to V7.
   7:
     id: V7
     rule: exit_marker_required
     description: >-
-      Every visionera invocation MUST emit an exit marker using the
-      canonical glyph ⛥ (SG6) in the format ⛥ visionera · <status>
+      Every vision invocation MUST emit an exit marker using the
+      canonical glyph ⛥ (SG6) in the format ⛥ vision · <status>
       where status is one of EX1-EX4.
     severity: critical
     checks:

package/bundle/skills/agentera/capability_schema_contract.yaml

@@ -7,15 +7,18 @@
 #   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/)
+#   4. Directory structure requirements (instruction module, schemas/)
 #   5. Machine-readable validation rules consumed by future contract loaders
+#   6. Optional trigger-entry intent documentation (TRIGGER_ENRICHMENT)
 
 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.
+    A capability directory must contain schemas/ and the runtime must
+    resolve the capability's behavioral instructions from the
+    packages/cli/src/capabilities/<name>/instructions.ts module.
     The union of all YAML files in schemas/ must contain all required groups.
   capability_type: contract
   self_referential: true
@@ -45,9 +48,10 @@ ENTRY_SCHEMA:
       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.
+        Advisory relevance-precedence hint a host reads alongside the entry
+        description only after deterministic routing returns semantic_required.
         Required for all TRIGGERS entries.
+        Valid values: high, medium, low.
     deprecated:
       type: boolean
       required: false
@@ -68,11 +72,15 @@ GROUP_PREFIXES:
   EXIT_CONDITIONS: E
 
 DIRECTORY_REQUIREMENTS:
-  instruction_file:
-    path: instructions.md
+  instruction_module:
+    path: packages/cli/src/capabilities/<name>/instructions.ts
     type: file
     required: true
-    description: Behavioral instructions the agent reads.
+    description: >-
+      TypeScript module that exports the capability's behavioral instructions
+      as a default-exported string constant. The runtime loads it via the
+      compiled .js path and surfaces the prose through
+      `agentera prime --context <name> --format json`.
   schemas_directory:
     path: schemas
     type: directory
@@ -128,7 +136,112 @@ FIELD_RULES:
         - high
         - medium
         - low
-      description: Priority of this trigger entry for routing confidence.
+      description: >-
+        Relevance-precedence hint a host reads when ordering capability intent
+        after deterministic abstention. See
+        references/cli/routing-model.md for routing semantics.
+
+TRIGGER_ENRICHMENT:
+  description: >-
+    Optional trigger-entry fields. Every field is OPTIONAL: a triggers.yaml
+    entry that omits all enriched fields remains valid. A host consumes
+    disambiguates_against as semantic-phase intent documentation only after
+    deterministic abstention. patterns,
+    confidence_threshold, borderline_band, and patterns_regex are legacy
+    compatibility fields: they remain shape-validated only and never enter the
+    active semantic trigger model.
+  spec: references/cli/trigger-schema-enrichment.md
+  fields:
+    patterns:
+      type: list_of_strings
+      required: false
+      description: >-
+        Legacy matcher strings retained only so existing trigger files load and
+        validate. They are never matched or returned by the active model.
+    confidence_threshold:
+      type: integer
+      required: false
+      min: 0
+      max: 100
+      description: >-
+        Legacy integer 0-100. Not consumed by the LLM host; retained so
+        triggers.yaml files carrying the field still validate. A non-integer
+        or value outside 0..100 fails V7 validation with the valid range
+        and the offending entry ID.
+    borderline_band:
+      type: integer
+      required: false
+      min: 0
+      max: 100
+      description: >-
+        Legacy integer 0-100. Not consumed by the LLM host; retained so
+        triggers.yaml files carrying the field still validate. A non-integer
+        or value outside 0..100 fails V7 validation.
+    patterns_regex:
+      type: list_of_strings
+      required: false
+      each_must_be_valid_regex: true
+      description: >-
+        Legacy list of regex strings. Not consumed by the LLM host; retained
+        so triggers.yaml files carrying the field still validate. The loader
+        syntax-validates each entry but never returns a RegExp or matches it.
+    disambiguates_against:
+      type: list_of_mappings
+      required: false
+      description: >-
+        Declares which other capabilities this trigger's intent could be
+        confused with, with a hint the LLM host consults when a request could
+        match more than one capability (spec §1.2). Advisory: the LLM host
+        resolves ambiguity natively and MAY surface the hint when asking the
+        user to confirm or clarify. Each entry MUST be a mapping with
+        `capability` and `hint`.
+      entries:
+        capability:
+          type: string
+          required: true
+          enum_source: ROUTE_ALIASES.primary_aliases.capability
+          description: >-
+            Canonical capability ID. Must be one of the twelve English
+            canonical IDs enumerated by ROUTE_ALIASES.primary_aliases
+            (status, vision, discuss, research, plan, build, optimize, audit,
+            document, profile, design, orchestrate). A non-canonical value
+            fails V7 validation with the offending entry ID.
+        hint:
+          type: string
+          required: true
+          non_empty: true
+          description: >-
+            Non-empty string distinguishing this trigger's intent from the
+            named capability on near-equal requests. A missing or empty hint
+            fails V7 validation.
+
+PROSE_CONVENTIONS:
+  description: >-
+    Authoring rules for capability behavioral instructions. These
+    conventions govern the prose in
+    packages/cli/src/capabilities/<name>/instructions.ts.
+  modal_vocabulary:
+    authority: RFC 2119
+    keywords:
+      - MUST
+      - MUST NOT
+      - SHOULD
+      - SHOULD NOT
+      - MAY
+    rule: >-
+      Capitalized keywords carry protocol force. Lowercase modal verbs
+      (should, must, may) remain ordinary English with no protocol force.
+      Use capitalized keywords when stating hard requirements, strong
+      recommendations, or optional behavior. Use lowercase modals in
+      natural prose that does not bind the agent.
+    rationale: >-
+      Weak models read capability instructions literally as user commands.
+      Deliberate modal vocabulary disambiguates intent: a capitalized MUST
+      signals a hard constraint, while lowercase "should" in descriptive
+      prose does not bind. This is the disambiguator, not the offender.
+    example: >-
+      Steps SHOULD be ordered by value/effort ratio. Each matrix cell
+      MUST be ≤15 words. A concept MAY reference external sources.
 
 PRIMITIVE_REFERENCE_FIELDS:
   description: >-
@@ -159,41 +272,68 @@ PRIMITIVE_REFERENCE_FIELDS:
 
 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.
+    Primary `/agentera <alias>` slash-route aliases for each capability.
+    English capability names are canonical protocol identity; the route alias
+    word is the canonical ID itself. Swedish -era names are legacy v2-stable
+    references, preserved for the v2 stable distribution and historical
+    artifacts (see legacy_aliases). 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.
+    the plan capability, while `agentera state plan` remains the
+    state-oriented CLI command for reading plan state. Do not add capability or
+    alias commands to the CLI.
   primary_aliases:
     - alias: status
-      capability: hej
+      capability: status
     - alias: vision
-      capability: visionera
+      capability: vision
     - alias: discuss
-      capability: resonera
+      capability: discuss
     - alias: research
-      capability: inspirera
+      capability: research
     - alias: plan
-      capability: planera
+      capability: plan
     - alias: build
-      capability: realisera
+      capability: build
     - alias: optimize
-      capability: optimera
+      capability: optimize
     - alias: audit
-      capability: inspektera
+      capability: audit
     - alias: document
-      capability: dokumentera
+      capability: document
     - alias: profile
-      capability: profilera
+      capability: profile
     - alias: design
-      capability: visualisera
+      capability: design
     - alias: orchestrate
-      capability: orkestrera
+      capability: orchestrate
+  legacy_aliases:
+    - legacy: hej
+      canonical: status
+    - legacy: visionera
+      canonical: vision
+    - legacy: resonera
+      canonical: discuss
+    - legacy: inspirera
+      canonical: research
+    - legacy: planera
+      canonical: plan
+    - legacy: realisera
+      canonical: build
+    - legacy: optimera
+      canonical: optimize
+    - legacy: inspektera
+      canonical: audit
+    - legacy: dokumentera
+      canonical: document
+    - legacy: profilera
+      canonical: profile
+    - legacy: visualisera
+      canonical: design
+    - legacy: orkestrera
+      canonical: orchestrate
 
 # ---------------------------------------------------------------------------
 # The four required groups follow. The contract IS a valid capability schema,
@@ -246,9 +386,9 @@ ARTIFACTS:
     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.
+      A valid capability directory. Must contain schemas/. The behavioral
+      instructions module lives at
+      packages/cli/src/capabilities/<name>/instructions.ts.
     produces: false
     consumes: true
   2:
@@ -263,11 +403,13 @@ ARTIFACTS:
     consumes: true
   3:
     id: A3
-    name: instruction_file
-    path: "capabilities/<name>/instructions.md"
+    name: instruction_module
+    path: "packages/cli/src/capabilities/<name>/instructions.ts"
     description: >-
-      Behavioral instructions the agent reads. Markdown format. Contains the
-      capability's workflow, personality, interaction rules, and examples.
+      Behavioral instructions the agent reads. TypeScript module that exports
+      a default-exported string constant. The runtime loads it via the
+      compiled .js path and serves the prose through
+      `agentera prime --context <name> --format json`.
     produces: false
     consumes: true
   4:
@@ -285,10 +427,12 @@ VALIDATION:
     id: V1
     rule: directory_structure
     description: >-
-      Capability directory must contain instructions.md and schemas/ directory.
+      Capability directory must contain schemas/ and the instruction module
+      packages/cli/src/capabilities/<name>/instructions.ts must exist as a
+      TypeScript source file (the runtime resolves the compiled .js path).
     severity: error
     checks:
-      - "instructions.md is a file"
+      - "instruction_module is a file"
       - "schemas/ is a directory"
       - "schemas/ contains at least one .yaml file"
   2:
@@ -346,6 +490,25 @@ VALIDATION:
       - "Contract file contains all required groups"
       - "Contract file entries follow entry schema structure"
       - "Contract file passes deprecation consistency check"
+  7:
+    id: V7
+    rule: trigger_enrichment_fields
+    description: >-
+      Trigger entries MAY carry the optional intent-documentation fields
+      defined in TRIGGER_ENRICHMENT. Enrichment is opt-in per entry;
+      triggers omitting every enriched field remain valid. patterns,
+      confidence_threshold, borderline_band, and patterns_regex are legacy
+      compatibility fields only; disambiguates_against is consumed by the
+      LLM host at runtime. Validating an entry with enriched fields fails
+      when the rules below are violated.
+    severity: error
+    checks:
+      - "patterns, when present, is a list of strings"
+      - "confidence_threshold, when present, is an integer in 0..100"
+      - "borderline_band, when present, is an integer in 0..100"
+      - "patterns_regex entries are strings that compile as regular expressions"
+      - "disambiguates_against entries are mappings with a non-empty hint"
+      - "disambiguates_against.capability is one of the twelve canonical capability IDs"
 
 EXIT_CONDITIONS:
   1:
@@ -359,8 +522,8 @@ EXIT_CONDITIONS:
     id: E2
     condition: invalid_structure
     description: >-
-      Directory structure validation failed. Missing instructions.md, schemas/
-      directory, or YAML files.
+      Directory structure validation failed. Missing instruction module,
+      schemas/ directory, or YAML files.
     exit_code: 1
   3:
     id: E3