agentera 0.0.0 → 3.0.0-dev.0

package/bundle/references/cli/bundle-skill-vocabulary.yaml

@@ -0,0 +1,278 @@
+schema_version: agentera.bundle_skill_vocabulary.v1
+status: active_authority
+purpose: >-
+  Classify surviving `bundle` and `SKILL.md` terminology so docs, package
+  metadata, runtime descriptors, tests, historical records, and compatibility
+  identifiers share one bounded vocabulary source without forcing mechanical
+  renames of shipped surfaces.
+sources:
+  prose:
+    - references/cli/vocabulary.md#bundle-and-skillmd-vocabulary
+scope:
+  includes:
+    - Current user-facing and diagnostic prose that names Agentera app files.
+    - Package and distribution metadata that names the suite package shape.
+    - Runtime hook packaging prose and metadata for plugin-shipped hooks.
+    - Historical references to the removed `bundle-status` command.
+    - Current and legacy references to `skills/agentera/SKILL.md` and v1 skill entry files.
+  excludes:
+    - Routing and execution vocabulary collapse work.
+    - Capability instruction-file rename work.
+    - "`first_invocation_read` metadata or startup-read behavior."
+    - Objective state, decision satisfaction state, package publication, and installed app refreshes.
+compatibility_boundary: >-
+  Compatibility identifiers, package metadata names, fixture names, historical
+  records, and path-like references may keep `bundle` or `SKILL.md` when the
+  spelling is the contract. New conceptual prose should use the canonical
+  concept terms below.
+canonical_concept_order:
+  - agentera_app_files
+  - suite_package
+  - plugin_shipped_hooks
+  - removed_bundle_status_command
+  - agentera_routing_entry
+  - skill_entry_file
+  - v1_skill_entry_file
+  - legacy_hej_bridge
+canonical_concepts:
+  agentera_app_files:
+    definition: >-
+      Managed Agentera application files installed under the app files directory,
+      separate from user data in the Agentera directory.
+    allowed_terms:
+      - Agentera app files
+      - app files
+      - app files directory
+      - installed app
+      - managed app files
+    forbidden_ambiguous_shortcuts:
+      - bundle
+      - installed bundle
+      - bundle freshness
+      - bundle refresh
+      - durable bundle
+  suite_package:
+    definition: >-
+      The packaged distribution shape that ships the Agentera skill, CLI,
+      scripts, hooks, references, runtime descriptors, and package metadata as
+      one suite artifact.
+    allowed_terms:
+      - suite package
+      - Agentera package
+      - packaged suite
+      - suite-bundle
+    forbidden_ambiguous_shortcuts:
+      - bundle
+      - single-bundle model
+      - bundled suite
+  plugin_shipped_hooks:
+    definition: >-
+      Hooks that are shipped by runtime plugin package surfaces such as Codex,
+      OpenCode, Claude, or GitHub plugin metadata.
+    allowed_terms:
+      - plugin-shipped hooks
+      - plugin-bundled hooks
+      - bundled hook metadata
+      - copied user hooks
+    forbidden_ambiguous_shortcuts:
+      - bundle hooks
+      - bundled hooks
+      - hook bundle
+  removed_bundle_status_command:
+    definition: >-
+      The removed legacy `agentera bundle-status` command name, preserved only
+      for historical release notes, migration evidence, and tests that prove it
+      remains unavailable.
+    allowed_terms:
+      - "removed `bundle-status` command"
+      - "legacy `agentera bundle-status` command"
+      - "historical `bundle-status` reference"
+    forbidden_ambiguous_shortcuts:
+      - bundle status
+      - bundle-status path
+      - bundle status command
+  agentera_routing_entry:
+    definition: >-
+      The v2 `skills/agentera/SKILL.md` routing entry that describes the Agentera
+      skill entry point, capability routing model, CLI-first state access, and
+      safety rails.
+    allowed_terms:
+      - Agentera routing entry point
+      - Agentera router
+      - routing layer
+      - "`skills/agentera/SKILL.md` routing entry"
+    forbidden_ambiguous_shortcuts:
+      - Agentera skill dispatcher
+      - SKILL.md
+      - master dispatcher
+      - skill dispatcher
+  skill_entry_file:
+    definition: >-
+      A concrete runtime skill entry file named `SKILL.md`, usually referenced
+      as a path or validation target rather than as a conceptual noun.
+    allowed_terms:
+      - skill entry file
+      - "`SKILL.md` file"
+      - "`skills/agentera/SKILL.md`"
+      - "`skills/*/SKILL.md`"
+    forbidden_ambiguous_shortcuts:
+      - SKILL.md
+      - skill file
+      - skill entry
+  v1_skill_entry_file:
+    definition: >-
+      A historical standalone v1 skill entry file or path retained in migration
+      notes, tests, stale-path checks, and compatibility fixtures.
+    allowed_terms:
+      - v1 skill entry file
+      - v1 standalone skill entry file
+      - "historical v1 `SKILL.md` file"
+      - v1 skill path
+    forbidden_ambiguous_shortcuts:
+      - SKILL.md
+      - v1 SKILL.md
+      - old skill file
+  legacy_hej_bridge:
+    definition: >-
+      The temporary v1 `/hej` bridge or exact bare `hej` compatibility path that
+      guides users toward `/agentera` and the v2 upgrade path.
+    allowed_terms:
+      - legacy hej bridge
+      - "legacy `/hej` bridge"
+      - v1 hej bridge
+      - "bare `hej` compatibility path"
+    forbidden_ambiguous_shortcuts:
+      - hej skill
+      - legacy skill
+      - old hej
+classification_order:
+  - canonical_concept
+  - compatibility_identifier
+  - path_like_reference
+  - package_metadata
+  - historical_record
+  - fixture_only
+  - generic_plain_language
+  - ambiguous_current_prose
+classification_rules:
+  canonical_concept:
+    meaning: Usage matches one of the canonical concepts and uses an allowed term.
+    action: Keep and prefer in new current prose.
+  compatibility_identifier:
+    meaning: The spelling is a shipped field, command flag, file name, code identifier, or parseable label.
+    action: Preserve until an explicit migration exists.
+  path_like_reference:
+    meaning: The occurrence is a literal file path, glob, manifest path, fixture path, or code path.
+    action: Preserve the concrete path spelling.
+  package_metadata:
+    meaning: The occurrence is a concrete package metadata value or installed package layout name.
+    action: Preserve unless package metadata migration is explicitly in scope.
+  historical_record:
+    meaning: The occurrence is in changelog, progress, decision, archived plan, migration history, or release evidence.
+    action: Do not rewrite solely for vocabulary cleanup; qualify when current prose interprets it.
+  fixture_only:
+    meaning: The occurrence is test fixture input, expected compatibility output, or stale-path regression data.
+    action: Preserve when the test proves compatibility or rejection behavior.
+  generic_plain_language:
+    meaning: The occurrence is ordinary English unrelated to Agentera app files, package shape, hooks, commands, or skill entries.
+    action: Allowed, but prefer object-specific terms when risk is high.
+  ambiguous_current_prose:
+    meaning: The occurrence uses bare `bundle` or bare `SKILL.md` as a conceptual noun in current user-facing prose.
+    action: Replace or qualify with the relevant canonical concept term.
+focused_scan:
+  allowed_classifications:
+    - canonical
+    - compatibility-preserved
+    - historical
+    - fixture-only
+    - generic
+  paths:
+    - AGENTS.md
+    - README.md
+    - references/cli/vocabulary.md
+    - references/adapters/opencode.md
+    - (retired maintainer measurement tool)
+    - skills/agentera/SKILL.md
+    - skills/agentera/capabilities/hej/schemas/triggers.yaml
+    - skills/agentera/capabilities/resonera/instructions.md
+    - tests/test_cross_capability.py
+    - tests/test_resonera_capability.py
+    - tests/test_runtime_adapters.py
+  allowed_occurrences:
+    - path: ^AGENTS\.md$
+      text: skills/agentera/SKILL\.md|Agentera routing entry point
+      classification: canonical
+      reason: AGENTS guidance names the concrete Agentera routing entry point.
+    - path: ^README\.md$
+      text: skills/agentera/SKILL\.md|Agentera routing entry point
+      classification: canonical
+      reason: README names the canonical routing entry point and concrete linked path.
+    - path: ^references/cli/vocabulary\.md$
+      text: references/cli/bundle-skill-vocabulary\.yaml|Bundle and SKILL\.md vocabulary
+      classification: canonical
+      reason: Vocabulary docs delegate this exact concept family to this authority.
+    - path: ^references/cli/vocabulary\.md$
+      text: Agentera app files need repair|bundle freshness|bundle refresh|required repair Agentera app files|install status check failed
+      classification: historical
+      reason: Decision 44 replacement tables preserve deprecated bundle wording as historical examples.
+    - path: ^references/cli/vocabulary\.md$
+      text: skills/agentera/SKILL\.md|SKILL\.md`
+      classification: canonical
+      reason: Vocabulary docs use concrete skill entry file paths and source-index references.
+    - path: ^references/cli/vocabulary\.md$
+      text: --only bundle|\.agentera-bundle\.json|bundle\.status|activeBundleRoot|bundle-status
+      classification: compatibility-preserved
+      reason: Vocabulary docs preserve shipped compatibility identifiers and removed command references.
+    - path: ^references/adapters/opencode\.md$
+      text: bundled Agentera dashboard path|bundled `agentera` skill|bundled Agentera
+      classification: generic
+      reason: OpenCode adapter prose uses bundled in the ordinary package-shipping sense, not as Agentera app-file terminology.
+    - path: ^references/adapters/opencode\.md$
+      text: SKILL\.md files|<name>/SKILL\.md|skills/\*/SKILL\.md|skills/agentera/SKILL\.md
+      classification: compatibility-preserved
+      reason: OpenCode adapter prose documents concrete runtime skill entry file paths.
+    - path: ^scripts/measure_token_payload\.py$
+      text: 'v1 baseline: all 12 v1 SKILL\.md files|skill_root / "SKILL\.md"'
+      classification: historical
+      reason: Token payload measurement preserves the historical v1 SKILL.md baseline and concrete path construction.
+    - path: ^skills/agentera/SKILL\.md$
+      text: \.agentera-bundle\.json|bundle\.status|bundle\.dryRunCommand
+      classification: compatibility-preserved
+      reason: The routing entry documents CLI-provided compatibility fields and marker files that still exist.
+    - path: ^skills/agentera/SKILL\.md$
+      text: SKILL\.md\s+# This file
+      classification: canonical
+      reason: The directory listing names the actual Agentera routing entry file.
+    - path: ^tests/test_cross_capability\.py$
+      text: SKILL_MD_PATH|test_master_bundle_health_gate|bundle\.status|bundle\.dryRunCommand
+      classification: fixture-only
+      reason: Cross-capability tests assert compatibility wording and historical test names.
+    - path: ^tests/test_runtime_adapters\.py$
+      text: .
+      classification: fixture-only
+      reason: Runtime adapter tests use fixture paths, expected diagnostics, package metadata, and compatibility test class names.
+compatibility_identifiers:
+  bundle:
+    - .agentera-bundle.json
+    - bundle.status
+    - activeBundleRoot
+    - "--only bundle"
+    - bundle.dryRunCommand
+  skill_entry_file:
+    - skills/agentera/SKILL.md
+    - skills/*/SKILL.md
+    - SKILL.md
+package_metadata_values:
+  - suite-bundle
+  - agentera/bundle
+  - bundle-only enhancements
+historical_terms:
+  - agentera bundle-status
+  - bundle-status
+  - single-bundle model
+  - Agentera skill dispatcher
+docs_delegation:
+  document: references/cli/vocabulary.md
+  required_anchor: Bundle and SKILL.md vocabulary
+  authority_path: references/cli/bundle-skill-vocabulary.yaml
+  must_not_duplicate_large_table: true

package/bundle/references/cli/capability-instruction-contract.yaml

@@ -0,0 +1,123 @@
+schema_version: agentera.capability_instruction_contract.v1
+status: active_authority
+decision: 57
+purpose: >-
+  Define the Decision 57 capability instruction-file contract: the canonical
+  `instructions.md` file name, implemented CLI/schema first-invocation read
+  discoverability, compact-startup exception boundaries, and runtime behavior
+  that remains intentionally unsupported.
+sources:
+  decision: .agentera/decisions.yaml#decision-57
+  prose:
+    - references/cli/vocabulary.md#capability-instruction-contract
+    - README.md#development
+scope:
+  includes:
+    - Documentation authority for the implemented capability instruction-file name.
+    - CLI/schema discoverability for first capability invocation startup-read metadata.
+    - Compact-startup exception semantics and boundaries.
+    - Current canonical references to existing `instructions.md` files.
+    - Explicit separation from runtime behavior work.
+  excludes:
+    - Implementing first-invocation read behavior.
+    - Marking Decision 57 satisfied or editing protected vision/objective/profile/installed-app state.
+current_state:
+  canonical_instruction_file:
+    path: skills/agentera/capabilities/<name>/instructions.md
+    status: current_canonical_implemented
+    definition: >-
+      The human-readable instruction file for each capability.
+  legacy_instruction_file:
+    path: skills/agentera/capabilities/<name>/prose.md
+    status: historical_or_compatibility_evidence_only
+    definition: >-
+      The former capability instruction filename. It may survive only in archived
+      history, compatibility fixtures, benchmark evidence, or explicit migration
+      documentation; real capability directories do not use it as canonical.
+  validator_requirement:
+    current_required_path: instructions.md
+    future_required_path: instructions.md
+    status: current_requirement_enforced
+  cli_metadata:
+    field: first_invocation_read
+    status: emitted_in_prime_capability_context
+    current_behavior: >-
+      `agentera prime --context <name> --format json` emits
+      `capability_context` metadata including `first_invocation_read` for
+      supported capabilities. Historical `hej --capability-context` is removed in 3.0.
+first_invocation_read:
+  field_status: cli_schema_discoverability_implemented
+  definition: >-
+    Capability metadata declaring what instruction content an agent must read on
+    the first invocation of that capability in a session.
+  allowed_values:
+    full:
+      meaning: >-
+        The first capability invocation must read `instructions.md` in full before
+        executing capability-specific work.
+      obligation: full_instruction_file_read_required
+    compact_startup:
+      meaning: >-
+        A declared compact startup contract may satisfy initial orientation without
+        reading the full instruction file first.
+      obligation: compact_contract_must_name_covered_guidance_and_escalation_rules
+    skip:
+      meaning: >-
+        No first-invocation instruction read is required for the declared scope.
+      obligation: requires_explicit_contract_justification
+      caution: >-
+        Reserved for narrow future surfaces; not a default and not implemented by
+        this authority.
+  default_rule: full
+  full_read_obligation: >-
+    On initial capability invocation, read `instructions.md` in full unless that
+    capability declares a compact-startup exception with explicit coverage and
+    escalation boundaries.
+compact_startup_exception:
+  status: implemented_for_planera_compact_startup_discoverability
+  allowed_when:
+    - A machine-readable startup contract is available through supported state access.
+    - The compact contract states which instruction topics it covers.
+    - The compact contract states when the agent must escalate to a full instruction-file read.
+    - The compact contract preserves unsupported-command and raw-artifact-read boundaries.
+  not_allowed_when:
+    - The agent is editing the capability's own instructions or schemas.
+    - The compact contract is missing, incomplete, stale, or contradictory.
+    - The requested work touches behavior not covered by the compact contract.
+    - Safety rails, validation, exit semantics, or cross-capability boundaries are ambiguous.
+implementation_state:
+  instructions_md_files: renamed
+  validators_require_instructions_md: true
+  first_invocation_read_cli_metadata: true
+  first_invocation_read_schema_metadata: true
+  runtime_first_invocation_behavior: false
+  descriptors_rewritten_to_instructions_md: true
+  package_metadata_rewritten_to_instructions_md: true
+compatibility_preservation:
+  preserve_legacy_references_only_when_classified:
+    - skills/agentera/capabilities/*/instructions.md paths
+    - skills/agentera/capability_schema_contract.yaml directory requirements
+    - runtime descriptors and generated agent guidance that point to `instructions.md`
+    - archived v1/v2 migration records and progress evidence
+    - compatibility fixtures and tests that intentionally preserve old behavior evidence
+    - README, AGENTS, and vocabulary references that explicitly describe the current canonical state
+  resolved_implementation_todos:
+    metadata_feature: >-
+      Added `first_invocation_read` metadata and surfaced required instruction
+      reads through capability context output.
+    validation_regression: >-
+      Prove capability directories require `instructions.md`, reject new `prose.md`
+      conventions, emit required-read context, and preserve compact-startup exceptions.
+surface_inventory:
+  decision_57: current_canonical_contract_source
+  todo_sequence: separates_docs_rename_metadata_and_validation_work
+  docs_vocabulary: delegates_to_this_authority
+  readme: concise_user_facing_current_and_future_authoring_seam
+  capability_schema_contract: current_canonical_validator_reference
+  runtime_descriptors: current_canonical_instructions_md_pointers
+  capability_instruction_files: current_canonical_instruction_files
+docs_delegation:
+  document: references/cli/vocabulary.md
+  required_anchor: Capability instruction contract
+  authority_path: references/cli/capability-instruction-contract.yaml
+  must_not_duplicate_large_table: true

package/bundle/references/cli/capability-tool-classification.yaml

@@ -0,0 +1,53 @@
+# Capability tool classification authority
+# Defines which tools each capability subagent needs to fulfill its purpose.
+# Consumed by: descriptor validation, regression tests, runtime adapter docs.
+# Source of truth for per-capability tool requirements across all runtimes.
+
+classification:
+  mutation_capable:
+    description: Needs file write, edit, and/or shell execution to fulfill purpose
+    capabilities:
+      realisera:
+        permission: {write: allow, bash: allow}
+        rationale: Autonomous dev execution — writes code, runs tests/builds, commits
+      optimera:
+        permission: {write: allow, bash: allow}
+        rationale: Metric-driven optimization — runs experiments, writes harnesses
+      orkestrera:
+        permission: {write: allow, bash: allow}
+        rationale: Multi-cycle orchestration — dispatches workers, updates plan/progress
+      dokumentera:
+        permission: {write: allow, bash: deny}
+        rationale: Documentation generation — creates/updates doc files
+      planera:
+        permission: {write: allow, bash: deny}
+        rationale: Plan management — writes plan.yaml, archives completed plans
+
+  contextual_write:
+    description: Writes owned Agentera state artifacts
+    capabilities:
+      visionera:
+        permission: {write: allow, bash: deny}
+        rationale: Writes vision.yaml, archives old visions
+      resonera:
+        permission: {write: allow, bash: deny}
+        rationale: Writes decisions.yaml, may update TODO.md
+      visualisera:
+        permission: {write: allow, bash: deny}
+        rationale: Writes DESIGN.md, archives old designs
+      profilera:
+        permission: {write: allow, bash: allow}
+        rationale: Runs extraction scripts, writes PROFILE.md
+      inspektera:
+        permission: {write: allow, bash: deny}
+        rationale: Writes health.yaml audit reports
+
+  read_only:
+    description: Only reads files, searches, analyzes
+    capabilities:
+      hej:
+        permission: {write: deny, bash: deny}
+        rationale: Strictly read-only orientation dashboard
+      inspirera:
+        permission: {write: deny, bash: deny}
+        rationale: Analysis-only creative exploration