agentera 0.0.0 → 3.0.0-dev.0

package/bundle/references/adapters/package-manifest-interface-model.yaml

@@ -0,0 +1,337 @@
+interface: PackageManifest
+status: implemented
+implemented_by: references/adapters/package-registry.yaml
+intent: >
+  Define the package and release-surface access Interface before introducing an
+  executable registry Module. This model records ownership boundaries and the
+  validation contract for future PackageManifest records. The executable registry
+  at references/adapters/package-registry.yaml and its loader scripts/package_registry.py
+  now implement this interface; this model remains the authoritative design contract.
+record:
+  required_groups:
+    - identity
+    - version_authority
+    - version_surfaces
+    - runtime_package_manifests
+    - bundle_surfaces
+    - package_commands
+    - docs_targets
+    - release_policy
+  groups:
+    identity:
+      type: object
+      owns:
+        - package id
+        - suite name
+        - skill path
+        - capability count expectation
+      required_fields:
+        id: string
+        name: string
+        skill_path: repo_relative_path
+        expected_capabilities: integer
+    version_authority:
+      type: object
+      owns:
+        - suite version access selector
+        - persisted authority declaration
+        - authority transition rule
+      required_fields:
+        persisted_authority: repo_relative_path
+        selector: string
+        access_interface: string
+        future_authority_change_requires: string
+    version_surfaces:
+      type: object
+      owns:
+        - version-bearing repository surfaces
+        - version extraction selectors
+        - non-version surface exclusions
+      required_fields:
+        surfaces: list[object]
+        excluded_runtime_manifests: list[repo_relative_path]
+    runtime_package_manifests:
+      type: object
+      owns:
+        - runtime package manifest paths
+        - runtime package shape expectations
+        - shared package path expectations
+      required_fields:
+        manifests: list[object]
+        shared_paths_policy: string
+    bundle_surfaces:
+      type: object
+      owns:
+        - bundled directories
+        - bundled files
+        - bundle skip rules
+        - bundle mismatch standardization target
+      required_fields:
+        directories: list[repo_relative_path]
+        files: list[repo_relative_path]
+        skip_parts: list[string]
+        skip_suffixes: list[string]
+    package_commands:
+      type: object
+      owns:
+        - package-manager command specifications
+        - package command action names
+        - package command runtime scope
+        - package write-gate preservation
+      required_fields:
+        commands: list[object]
+        safety: object
+    docs_targets:
+      type: object
+      owns:
+        - docs version targets
+        - docs index targets for package surfaces
+        - non-version docs exclusions
+      required_fields:
+        version_files_source: string
+        version_files: list[repo_relative_path]
+        index_targets: list[repo_relative_path]
+        excluded_version_files: list[repo_relative_path]
+    release_policy:
+      type: object
+      owns:
+        - semver policy projection
+        - changelog decision guidance
+        - release publication exclusion
+      required_fields:
+        semver_policy_source: string
+        version_bump_required_for_interface_only_change: boolean
+        release_publication_in_scope: boolean
+ownership:
+  registry_json_version_authority:
+    owner: registry.json
+    persisted_authority: true
+    path: registry.json
+    selector: skills[0].version
+    access_interface: PackageManifest
+    rule: >
+      registry.json remains the persisted suite-version authority. PackageManifest
+      becomes the typed access Interface for consumers after migration, unless an
+      explicit future ADR changes persisted authority.
+    future_authority_change_requires: explicit ADR
+  install_root_delegated:
+    owner: scripts/install_root.py
+    forbidden_in_package_manifest:
+      - AGENTERA_HOME precedence
+      - default app home
+      - managed classification
+      - stale classification
+      - unmanaged classification
+      - app-home diagnostics
+  runtime_adapter_delegated:
+    owner: scripts/runtime_adapter_registry.py
+    forbidden_in_package_manifest:
+      - runtime discovery
+      - lifecycle events
+      - artifact validation hooks
+      - config target paths
+      - runtime diagnostics
+      - documentation claims
+command_safety:
+  argv_only: true
+  approved_executables:
+    - npx
+  approved_actions:
+    - remove-legacy-skills
+    - install-agentera-skill
+  approved_runtimes:
+    - all
+    - claude
+    - opencode
+  approved_runtime_agents:
+    - claude-code
+    - opencode
+  approved_package_tool:
+    executable: npx
+    command_namespace: skills
+    actions:
+      - remove
+      - add
+  cleanup_actions:
+    - remove-legacy-skills
+  runtime_install_actions:
+    - install-agentera-skill
+  gates:
+    update_packages_required_to_plan: true
+    yes_required_to_execute: true
+    preserve_existing_write_gates: true
+sample_manifest:
+  identity:
+    id: agentera
+    name: agentera
+    skill_path: skills/agentera
+    expected_capabilities: 12
+  version_authority:
+    persisted_authority: registry.json
+    selector: skills[0].version
+    access_interface: PackageManifest
+    future_authority_change_requires: explicit ADR
+  version_surfaces:
+    surfaces:
+      - id: registry
+        path: registry.json
+        selector: skills[0].version
+      - id: python-project
+        path: pyproject.toml
+        selector: project.version
+      - id: copilot-root
+        path: plugin.json
+        selector: version
+      - id: copilot-repository
+        path: .github/plugin/plugin.json
+        selector: version
+      - id: codex-plugin
+        path: .codex-plugin/plugin.json
+        selector: version
+      - id: claude-marketplace-metadata
+        path: .claude-plugin/marketplace.json
+        selector: metadata.version
+      - id: claude-marketplace-plugins
+        path: .claude-plugin/marketplace.json
+        selector: plugins[*].version
+      - id: opencode-plugin-marker
+        path: .opencode/plugins/agentera.js
+        selector: AGENTERA_VERSION
+    excluded_runtime_manifests:
+      - .opencode/package.json
+  runtime_package_manifests:
+    manifests:
+      - runtime: copilot
+        path: plugin.json
+        version_bearing: true
+        package_shape: suite-bundle
+      - runtime: copilot
+        path: .github/plugin/plugin.json
+        version_bearing: true
+        package_shape: suite-bundle
+      - runtime: codex
+        path: .codex-plugin/plugin.json
+        version_bearing: true
+        package_shape: suite-bundle
+      - runtime: claude
+        path: .claude-plugin/marketplace.json
+        version_bearing: true
+        package_shape: suite-bundle
+      - runtime: opencode
+        path: .opencode/package.json
+        version_bearing: false
+        package_shape: suite-bundle
+    shared_paths_policy: validate minimum shared paths separately from full bundle includes
+  bundle_surfaces:
+    directories:
+      - skills
+      - scripts
+      - hooks
+      - references
+      - agents
+      - .agents/plugins
+      - .codex-plugin
+      - .claude-plugin
+      - .github/hooks
+      - .github/plugin
+      - .opencode/commands
+      - .opencode/plugins
+    files:
+      - README.md
+      - UPGRADE.md
+      - CHANGELOG.md
+      - DESIGN.md
+      - LICENSE
+      - pyproject.toml
+      - uv.lock
+      - registry.json
+      - plugin.json
+      - .opencode/package.json
+    skip_parts:
+      - __pycache__
+      - .pytest_cache
+      - node_modules
+    skip_suffixes:
+      - .pyc
+      - .pyo
+  package_commands:
+    commands:
+      - runtime: all
+        action: remove-legacy-skills
+        phase: cleanup
+        argv:
+          - npx
+          - skills
+          - remove
+          - hej
+          - visionera
+          - resonera
+          - inspirera
+          - planera
+          - realisera
+          - inspektera
+          - optimera
+          - orkestrera
+          - visualisera
+          - dokumentera
+          - profilera
+          - -g
+          - -y
+        skipped_without_update_packages_message: legacy skill removal skipped; pass --update-packages to run
+      - runtime: claude
+        action: install-agentera-skill
+        phase: runtime-install
+        argv:
+          - npx
+          - skills
+          - add
+          - jgabor/agentera
+          - -g
+          - -a
+          - claude-code
+          - --skill
+          - agentera
+          - -y
+        skipped_without_update_packages_message: external package update skipped; pass --update-packages to run
+      - runtime: opencode
+        action: install-agentera-skill
+        phase: runtime-install
+        argv:
+          - npx
+          - skills
+          - add
+          - jgabor/agentera
+          - -g
+          - -a
+          - opencode
+          - --skill
+          - agentera
+          - -y
+        skipped_without_update_packages_message: external package update skipped; pass --update-packages to run
+    safety:
+      argv_only: true
+      update_packages_required_to_plan: true
+      yes_required_to_execute: true
+      preserve_existing_write_gates: true
+      cleanup_phase: cleanup
+      runtime_install_phase: runtime-install
+  docs_targets:
+    version_files_source: .agentera/docs.yaml conventions.version_files
+    version_files:
+      - pyproject.toml
+      - uv.lock
+      - plugin.json
+      - .github/plugin/plugin.json
+      - .codex-plugin/plugin.json
+      - .claude-plugin/marketplace.json
+      - .opencode/plugins/agentera.js
+      - registry.json
+    index_targets:
+      - references/adapters/package-surface-characterization.md
+      - references/adapters/package-manifest-interface-model.yaml
+    excluded_version_files:
+      - .opencode/package.json
+  release_policy:
+    semver_policy_source: .agentera/docs.yaml conventions.semver_policy
+    version_bump_required_for_interface_only_change: false
+    release_publication_in_scope: false

package/bundle/references/adapters/package-registry.yaml

@@ -0,0 +1,247 @@
+schema_version: agentera.packageRegistry.v1
+package_order:
+  - agentera
+records:
+  - identity:
+      id: agentera
+      name: agentera
+      skill_path: skills/agentera
+      expected_capabilities: 12
+    version_authority:
+      persisted_authority: registry.json
+      selector: skills[0].version
+      access_interface: PackageManifest
+      future_authority_change_requires: explicit ADR
+    version_surfaces:
+      surfaces:
+        - id: registry
+          path: registry.json
+          selector: skills[0].version
+        - id: python-project
+          path: pyproject.toml
+          selector: project.version
+        - id: copilot-root
+          path: plugin.json
+          selector: version
+        - id: copilot-repository
+          path: .github/plugin/plugin.json
+          selector: version
+        - id: codex-plugin
+          path: .codex-plugin/plugin.json
+          selector: version
+        - id: claude-marketplace-metadata
+          path: .claude-plugin/marketplace.json
+          selector: metadata.version
+        - id: claude-marketplace-plugins
+          path: .claude-plugin/marketplace.json
+          selector: plugins[*].version
+        - id: opencode-plugin-marker
+          path: .opencode/plugins/agentera.js
+          selector: AGENTERA_VERSION
+      excluded_runtime_manifests:
+        - .opencode/package.json
+    runtime_package_manifests:
+      manifests:
+        - id: copilot-root-manifest
+          runtime: copilot
+          path: plugin.json
+          version_bearing: true
+          package_shape: suite-bundle
+        - id: copilot-repository-manifest
+          runtime: copilot
+          path: .github/plugin/plugin.json
+          version_bearing: true
+          package_shape: suite-bundle
+        - id: codex-plugin-manifest
+          runtime: codex
+          path: .codex-plugin/plugin.json
+          version_bearing: true
+          package_shape: suite-bundle
+        - id: cursor-plugin-manifest
+          runtime: cursor
+          path: .cursor-plugin/plugin.json
+          version_bearing: true
+          package_shape: suite-bundle
+        - id: claude-marketplace-manifest
+          runtime: claude
+          path: .claude-plugin/marketplace.json
+          version_bearing: true
+          package_shape: suite-bundle
+        - id: opencode-package-manifest
+          runtime: opencode
+          path: .opencode/package.json
+          version_bearing: false
+          package_shape: npm-loadable-plugin
+      shared_paths:
+        - id: skills
+          path: skills
+          kind: dir
+        - id: scripts
+          path: scripts
+          kind: dir
+        - id: hooks
+          path: hooks
+          kind: dir
+        - id: registry
+          path: registry.json
+          kind: file
+        - id: copilot-root-manifest
+          path: plugin.json
+          kind: file
+        - id: readme
+          path: README.md
+          kind: file
+        - id: upgrade-guide
+          path: UPGRADE.md
+          kind: file
+      shared_paths_policy: validate minimum shared paths separately from full bundle includes
+    bundle_surfaces:
+      directories:
+        - id: skills
+          path: skills
+        - id: scripts
+          path: scripts
+        - id: hooks
+          path: hooks
+        - id: references
+          path: references
+        - id: agents
+          path: agents
+        - id: agents-plugins
+          path: .agents/plugins
+        - id: codex-plugin
+          path: .codex-plugin
+        - id: cursor-plugin
+          path: .cursor-plugin
+        - id: cursor-agents
+          path: .cursor/agents
+        - id: claude-plugin
+          path: .claude-plugin
+        - id: github-hooks
+          path: .github/hooks
+        - id: github-plugin
+          path: .github/plugin
+        - id: opencode-commands
+          path: .opencode/commands
+        - id: opencode-agents
+          path: .opencode/agents
+        - id: opencode-plugins
+          path: .opencode/plugins
+      files:
+        - id: readme
+          path: README.md
+        - id: upgrade-guide
+          path: UPGRADE.md
+        - id: changelog
+          path: CHANGELOG.md
+        - id: design
+          path: DESIGN.md
+        - id: license
+          path: LICENSE
+        - id: python-project
+          path: pyproject.toml
+        - id: python-lock
+          path: uv.lock
+        - id: registry
+          path: registry.json
+        - id: copilot-root-manifest
+          path: plugin.json
+        - id: opencode-package-manifest
+          path: .opencode/package.json
+        - id: cursor-hooks
+          path: .cursor/hooks.json
+      skip_parts:
+        - __pycache__
+        - .pytest_cache
+        - node_modules
+      skip_suffixes:
+        - .pyc
+        - .pyo
+    package_commands:
+      commands:
+        - id: remove-legacy-skills
+          runtime: all
+          action: remove-legacy-skills
+          phase: cleanup
+          argv:
+            - npx
+            - skills
+            - remove
+            - hej
+            - visionera
+            - resonera
+            - inspirera
+            - planera
+            - realisera
+            - inspektera
+            - optimera
+            - orkestrera
+            - visualisera
+            - dokumentera
+            - profilera
+            - -g
+            - -y
+          skipped_without_update_packages_message: legacy skill removal skipped; pass --update-packages to run
+        - id: install-agentera-skill-claude
+          runtime: claude
+          action: install-agentera-skill
+          phase: runtime-install
+          argv:
+            - npx
+            - skills
+            - add
+            - jgabor/agentera
+            - -g
+            - -a
+            - claude-code
+            - --skill
+            - agentera
+            - -y
+          skipped_without_update_packages_message: external package update skipped; pass --update-packages to run
+        - id: install-agentera-skill-opencode
+          runtime: opencode
+          action: install-agentera-skill
+          phase: runtime-install
+          argv:
+            - npx
+            - skills
+            - add
+            - jgabor/agentera
+            - -g
+            - -a
+            - opencode
+            - --skill
+            - agentera
+            - -y
+          skipped_without_update_packages_message: external package update skipped; pass --update-packages to run
+      safety:
+        argv_only: true
+        update_packages_required_to_plan: true
+        yes_required_to_execute: true
+        preserve_existing_write_gates: true
+        cleanup_phase: cleanup
+        runtime_install_phase: runtime-install
+    docs_targets:
+      version_files_source: .agentera/docs.yaml conventions.version_files
+      version_files:
+        - pyproject.toml
+        - uv.lock
+        - plugin.json
+        - .github/plugin/plugin.json
+        - .codex-plugin/plugin.json
+        - .cursor-plugin/plugin.json
+        - .claude-plugin/marketplace.json
+        - .opencode/plugins/agentera.js
+        - skills/agentera/SKILL.md
+        - skills/hej/SKILL.md
+        - registry.json
+      index_targets:
+        - references/adapters/package-surface-characterization.md
+        - references/adapters/package-manifest-interface-model.yaml
+        - references/adapters/package-registry.yaml
+      excluded_version_files:
+        - .opencode/package.json
+    release_policy:
+      semver_policy_source: .agentera/docs.yaml conventions.semver_policy
+      version_bump_required_for_interface_only_change: false
+      release_publication_in_scope: false

package/bundle/references/adapters/package-surface-characterization.md

@@ -0,0 +1,48 @@
+# Package Surface Characterization
+
+Characterized on 2026-05-06 before the PackageManifest registry migration. This file records current behavior only; it is not the registry design.
+
+The executable PackageManifest registry at `references/adapters/package-registry.yaml` and its loader `scripts/package_registry.py` now own the single source of truth for version surfaces, runtime package manifests, bundle surfaces, package commands, and docs targets. Validators, upgrade, and tests consume registry facts instead of duplicating constants.
+
+## Version-Bearing Surfaces
+
+`registry.json` is the persisted suite-version authority. The current suite version is `2.2.0` at `skills[0].version`.
+
+The current version-bearing surfaces are:
+
+| Surface | Kind | Current behavior |
+| --- | --- | --- |
+| `registry.json` | version-bearing surface | `skills[0].version` is the suite authority. |
+| `pyproject.toml` | version-bearing surface | `[project].version` matches the registry suite version. |
+| `plugin.json` | version-bearing surface and runtime package manifest | root Copilot manifest `version` matches the suite version. |
+| `.github/plugin/plugin.json` | version-bearing surface and runtime package manifest | repository Copilot manifest `version` matches the suite version. |
+| `.codex-plugin/plugin.json` | version-bearing surface and runtime package manifest | Codex manifest `version` matches the suite version. |
+| `.claude-plugin/marketplace.json` | version-bearing surface and runtime package manifest | `metadata.version` and every plugin entry version, including the legacy `hej` bridge, match the suite version. |
+| `.opencode/plugins/agentera.js` | version-bearing surface | `AGENTERA_VERSION` matches the registry suite version and drives the OpenCode command marker file `.agentera-version`. |
+
+`.opencode/package.json` is intentionally not version-bearing. Its current behavior is runtime package manifest behavior only: it keeps `type: "module"`, `main`/`exports` pointing at `./plugins/agentera.js`, `dependencies["@opencode-ai/plugin"] == "1.14.33"`, and an `agentera` npm-loadable plugin metadata block, but it has no top-level `name` or `version` field.
+
+## Package-Manager Command Surface
+
+Upgrade package planning currently emits package-manager commands only for Claude Code and OpenCode runtime selections.
+
+| Runtime | Action | Command argv | Skipped message | Dry-run behavior | Apply behavior with mocked command |
+| --- | --- | --- | --- | --- | --- |
+| `all` | `remove-legacy-skills` | `npx skills remove hej visionera resonera inspirera planera realisera inspektera optimera orkestrera visualisera dokumentera profilera -g -y` | `legacy skill removal skipped; pass --update-packages to run` | `--update-packages` without `--yes` leaves status `pending` and does not execute. | status becomes `applied`, message `package update completed`, and command result tails are recorded. |
+| `claude` | `install-agentera-skill` | `npx skills add jgabor/agentera -g -a claude-code --skill agentera -y` | `external package update skipped; pass --update-packages to run` | `--update-packages` without `--yes` leaves status `pending` and does not execute. | status becomes `applied`, message `package update completed`, and command result tails are recorded. |
+| `opencode` | `install-agentera-skill` | `npx skills add jgabor/agentera -g -a opencode --skill agentera -y` | `external package update skipped; pass --update-packages to run` | `--update-packages` without `--yes` leaves status `pending` and does not execute. | status becomes `applied`, message `package update completed`, and command result tails are recorded. |
+
+Write gating is preserved: `--update-packages` changes package items from `skipped` to `pending`, but package-manager commands execute only during apply mode behind `--yes`. Focused tests mock `subprocess.run`; no live package-manager call is part of this characterization.
+
+## Bundle And Docs Drift Inventory
+
+| Drift point | Surface class | Decision | Current behavior to preserve before migration |
+| --- | --- | --- | --- |
+| `pyproject.toml` force-includes and `scripts/agentera_upgrade.py` bundle lists duplicate the same shipped bundle directories and files. | bundle metadata surface | `standardize` | Keep both lists aligned now; later PackageManifest should own the list once. |
+| Lifecycle validation requires only the minimal shared runtime package paths (`skills`, `scripts`, `hooks`, `registry.json`, `plugin.json`, `pyproject.toml`, `README.md`) while pyproject and upgrade copy the larger distributable bundle. | runtime package manifest | `standardize` | Keep the validator as a minimum package-shape check now; later PackageManifest should separate minimal runtime metadata from full bundle includes. |
+| Runtime manifest `agentera.sharedPaths` includes `UPGRADE.md`, but `SUITE_BUNDLE_REQUIRED_PATHS` does not require it. | runtime package manifest | `standardize` | Keep current validator leniency now; later PackageManifest should make required shared paths explicit in one place. |
+| `.agentera/docs.yaml` `version_files` includes version-bearing surfaces and excludes `.opencode/package.json`. | version-bearing surface | `preserve` | Keep `.opencode/package.json` out of version checks because it is a runtime package manifest, not a suite version surface. |
+| `.opencode/package.json` is force-included and bundled, but it is not in docs `version_files`. | runtime package manifest | `preserve` | Keep packaging it without treating it as version-bearing. |
+| Upgrade package commands are represented as argv lists for Claude Code and OpenCode only; Codex and Copilot have runtime manifests but no package-manager command entries. | package-manager command surface | `preserve` | Keep command planning limited to currently managed package runtimes. |
+| `.claude-plugin/marketplace.json` carries a `hej` legacy bridge version alongside `agentera`. | version-bearing surface | `defer` | Keep the legacy bridge version aligned until a separate legacy-bridge removal or marketplace simplification task exists. |
+| Live package-manager behavior is not characterized by this task. | package-manager command surface | `defer` | Keep tests mocked; do not introduce live `npx skills` execution. |