agentera 0.0.0 → 3.0.0-dev.1

package/bundle/references/v1-section-mapping.md

@@ -0,0 +1,47 @@
+# v1-to-v2 Section Mapping
+
+Maps every behavioral section in the 12 v1 SKILL.md files to the v2 capability schema groups.
+No unmappable content.
+
+## Mapping Table
+
+| v1 Section | v2 Target | Rationale |
+|---|---|---|
+| Frontmatter: `name`, `description` | `instructions.md` (header) + `TRIGGERS` group | Name is prose identity. Description is prose metadata. Trigger patterns extracted to TRIGGERS entries. |
+| Frontmatter: `spec_sections` | Dropped | SPEC.md dissolves into per-capability schemas (ROADMAP: "Spec dissolves into schemas"). No central spec to reference. |
+| `## State artifacts` (artifact list) | `ARTIFACTS` group | Each consumed/produced artifact becomes an ARTIFACTS entry with stable ID. |
+| `### Artifact path resolution` | `ARTIFACTS` group (path metadata) | Path resolution rules become path field metadata on artifact entries. |
+| `### Contract` (inlined values) | `VALIDATION` group + `protocol.yaml` | Inlined contract values (severity arrows, trend arrows, glyphs, token budgets) become shared protocol primitives referenced by VALIDATION entries. |
+| `references/contract.md` | `protocol.yaml` | Centralized contract reference replaced by shared protocol schema. |
+| `## Step N: ...` (workflow steps) | `instructions.md` | Behavioral instructions the agent reads. Steps remain prose. |
+| `## Brainstorm: ...` (sub-workflows) | `instructions.md` | Interactive sub-workflows are behavioral instructions. |
+| `## Personality` / `## Interaction rules` | `instructions.md` | Personality and interaction rules are agent-facing behavioral guidance. |
+| `## Safety rails` | `VALIDATION` group | Each safety rail becomes a VALIDATION entry with rule, severity, and checks. |
+| `## Exit signals` | `EXIT_CONDITIONS` group | Each exit signal becomes an EXIT_CONDITIONS entry with condition, description, and exit_code. |
+| `## Cross-skill integration` | `ARTIFACTS` group (cross-capability refs) + `instructions.md` | Cross-skill dependencies become ARTIFACTS entries with cross-capability ID references. Integration guidance stays in prose. |
+| `## Getting started` | `instructions.md` | First-run guidance is behavioral instruction. |
+| `references/templates/` | `instructions.md` (embedded or referenced) | Templates are part of the capability's behavioral instructions. |
+| `scripts/` (Python helpers) | Kept at repo level or capability-local | Scripts are tooling, not behavioral. Location unchanged for v2. |
+
+## Per-Skill Coverage
+
+Every section found in each v1 SKILL.md is covered by the mapping above. Verification:
+
+| Skill | Sections | All Mapped? |
+|---|---|---|
+| dokumentera | State artifacts, Contract, Conventions, Artifact Mapping, Index, Steps 0, First-run, Intent-first, Explore-and-generate, Update-and-verify, Safety rails, Exit signals, Cross-skill, Getting started | Yes |
+| hej | State artifacts, Contract, Steps 0-2 (Detect, Welcome, Briefing, Route), Safety rails, Exit signals, Cross-skill, Getting started | Yes |
+| inspektera | State artifacts, Contract, Audit template, Steps 1-7, Dimensions, Evidence, Confidence, Findings, Safety rails, Exit signals, Cross-skill, Getting started | Yes |
+| inspirera | Steps 1-5, Source overview, Concepts, Applicability, Next steps, Exit signals, State artifacts, Cross-skill, Safety rails, Getting started, Notes on depth | Yes |
+| optimera | State artifacts, Objective template, Experiment template, Closure template, Brainstorm, Cycle, Hypothesis, Constraints, Safety rails, Blocked handling, Exit signals, Cross-skill, Getting started | Yes |
+| orkestrera | State artifacts, Personality, Conductor protocol, Task template, Acceptance template, Context, Verification, Output format, Lean conductor, Safety rails, Exit signals, Cross-skill, Getting started | Yes |
+| planera | State artifacts, Contract, Steps 0-6, Plan template (quick + full), Acceptance criteria, Handoff, How realisera reads PLAN, Safety rails, Exit signals, Cross-skill, Getting started | Yes |
+| profilera | State artifacts, Steps 0, Full mode, Profile template, Validate mode, Safety rails, Exit signals, Cross-skill, Getting started, Notes on depth | Yes |
+| realisera | State artifacts, Contract, VISION template, PROGRESS template, TODO template, CHANGELOG template, Brainstorm, Cycle, Task, Constraints, Safety rails, Blocked handling, Exit signals, Cross-skill | Yes |
+| resonera | State artifacts, Decision template, Personality, Interaction rules, Starting a session, Running state, Good questions, Done handling, Safety rails, Exit signals, Cross-skill, Getting started | Yes |
+| visionera | State artifacts, Contract, VISION template, Steps 0, Create mode, Refine mode, Safety rails, Exit signals, Cross-skill, Getting started | Yes |
+| visualisera | State artifacts, Contract, Design template, Steps 0, Create, Refine, Audit modes, Safety rails, Exit signals, Cross-skill, Getting started | Yes |
+
+## Unmappable Content
+
+None. Every section in every v1 SKILL.md maps to one of: `instructions.md`, `TRIGGERS`, `ARTIFACTS`, `VALIDATION`, `EXIT_CONDITIONS`, or `protocol.yaml` (shared primitives extracted from Contract sections).

package/bundle/registry.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "version": "1",
+  "skills": [
+    {
+      "name": "agentera",
+      "version": "2.7.6",
+      "description": "Compound agent orchestration suite — 12 capabilities in one bundled skill; exact bare hej uses the Agentera dashboard path",
+      "path": "skills/agentera",
+      "capabilities": [
+        "hej",
+        "realisera",
+        "resonera",
+        "planera",
+        "inspektera",
+        "optimera",
+        "orkestrera",
+        "visionera",
+        "visualisera",
+        "dokumentera",
+        "profilera",
+        "inspirera"
+      ],
+      "tags": [
+        "orchestration",
+        "autonomous",
+        "planning",
+        "optimization",
+        "audit",
+        "documentation",
+        "vision",
+        "research",
+        "deliberation",
+        "design"
+      ],
+      "added": "2026-05-04"
+    }
+  ]
+}

package/bundle/skills/agentera/.claude-plugin/plugin.json

@@ -0,0 +1,27 @@
+{
+  "name": "agentera",
+  "version": "2.0.3",
+  "description": "The open protocol for turning AI agents into engineering teams. One bundled skill with twelve capabilities. Use for /agentera and for a complete user message exactly `hej`; bare `hej` runs the Agentera dashboard path.",
+  "author": {
+    "name": "jgabor"
+  },
+  "agentera": {
+    "packageShape": "bundled-skill",
+    "capabilities": [
+      "hej",
+      "visionera",
+      "resonera",
+      "inspirera",
+      "planera",
+      "realisera",
+      "optimera",
+      "inspektera",
+      "dokumentera",
+      "profilera",
+      "visualisera",
+      "orkestrera"
+    ],
+    "schemas": "schemas",
+    "protocol": "protocol.yaml"
+  }
+}

package/bundle/skills/agentera/SKILL.md

@@ -0,0 +1,470 @@
+---
+name: agentera
+description: >
+  The open protocol for turning AI agents into engineering teams.
+  One Agentera skill with twelve capabilities, each defined by human-readable
+  prose and machine-readable schemas. The agent reads this file to route
+  incoming requests to the right capability. Use this skill for /agentera,
+  Agentera capability requests, and a complete user message exactly `hej`;
+  bare `hej` runs the agentera prime orientation dashboard path instead of a generic greeting.
+version: "2.7.6"
+spec_sections: [1, 2, 3, 4, 5, 6, 11, 13, 18, 19, 20, 22, 23]
+---
+
+# agentera
+
+One install, one entry point, one query interface to all project state. Twelve capabilities live inside one Agentera skill.
+
+---
+
+## Shared Protocol
+
+All capabilities reference shared primitives defined in `protocol.yaml`:
+
+- **Confidence scale**: 0-100, five tiers with explicit boundaries
+- **Severity levels**: finding vocabulary and issue vocabulary
+- **Visual tokens**: status, severity, confidence, and trend glyphs
+- **Phase model**: five phases with valid transitions
+
+Capabilities import these by name. The schema contract ensures consistent usage.
+
+---
+
+## Capabilities
+
+| | Capability | Primary route | Purpose |
+|---|---|---|---|
+| ⌂ | hej | `/agentera status` | Orientation and routing |
+| ⛥ | visionera | `/agentera vision` | Define project direction |
+| ❈ | resonera | `/agentera discuss` | Structured deliberation |
+| ⬚ | inspirera | `/agentera research` | External pattern analysis |
+| ≡ | planera | `/agentera plan` | Planning with acceptance criteria |
+| ⧉ | realisera | `/agentera build` | Autonomous development |
+| ⎘ | optimera | `/agentera optimize` | Metric-driven optimization |
+| ⛶ | inspektera | `/agentera audit` | Codebase health audit |
+| ▤ | dokumentera | `/agentera document` | Documentation |
+| ♾ | profilera | `/agentera profile` | Decision profiling |
+| ◰ | visualisera | `/agentera design` | Visual identity system |
+| ⎈ | orkestrera | `/agentera orchestrate` | Multi-cycle orchestration |
+
+---
+
+## Routing Logic
+
+When a request arrives, route to the matching capability using the five-layer routing model from Decision 42.
+
+### Prerequisite: Single-call installed CLI gate
+
+This gate is mandatory, but the gate and the orientation dashboard source are the same
+installed CLI invocation. For bare `/agentera` or bare `hej`, the first normal
+state-access tool call is:
+
+```bash
+npx -y agentera prime
+```
+
+Resolve `RESOLVED_AGENTERA_HOME` with the app-home precedence `AGENTERA_HOME`
+when set, otherwise the platform data home. Do not run `glob`, `grep`, `read`,
+`ls`, `python`, `doctor`, `--help`, `registry.json`,
+or `.agentera-bundle.json` preflight checks before this call. The CLI owns app
+validation, v1 detection, profile detection, artifact condensation, and the
+`source_contract` that tells the caller how to render the dashboard.
+Never combine the app-home assignment with the same shell command that expands
+the managed app script path; shell expansion can otherwise turn an unset
+`AGENTERA_HOME` into `npx -y agentera` before the assignment takes effect.
+
+If the command exits successfully, inspect the CLI-provided `bundle.status`
+installed-app status object. If its value is `fresh`, treat the installed app gate as passed
+for that briefing and render from the output. The object includes
+`expectedVersion`, `expectedVersionSource`, `appHome`, `managedAppRoot`,
+`userDataRoot`, repair commands, and approval text.
+
+### User-facing repair wording
+
+Recovery and troubleshooting prompts must be plain enough for a non-technical
+user. Never ask the user to choose between technical install concepts, internal
+directory states, command-mode flags, or package-layout terms. Keep those as
+internal facts.
+User-facing copy must answer four questions in this order:
+
+1. What happened: `Agentera found an old or broken local copy of itself.`
+2. What the preview did: `Nothing was changed.`
+3. What the recommended fix will do: `Install a fresh Agentera app copy in the normal Agentera directory.`
+4. What it will not do: `It will not edit your project files, shell startup files, or unknown directories.`
+
+Use recommendation-first choices only when a choice is unavoidable. Put the safe
+default first and name it as the recommendation. Good labels: `Use the safe fix
+(Recommended)`, `Choose a different directory`, `Stop`. Bad labels: `Use platform
+home`, `Force old directory`, or labels that expose internal flags and app-file
+packaging terms.
+Only mention commands and paths after the plain explanation, as technical detail.
+
+If the command cannot execute because `AGENTERA_HOME` names the old default
+`$HOME/.agents/agentera` and `npx -y agentera` is missing,
+do not require a successful failed CLI invocation and do not first ask the user to
+unset `AGENTERA_HOME`. Tell the user: `Agentera found an old or broken local copy
+of itself. The safe fix is to install a fresh copy in the normal Agentera directory.`
+Then show this preview command and say it changes nothing:
+
+```bash
+npx -y agentera@latest doctor
+```
+
+This preview writes nothing. Because no explicit `--install-root` is supplied,
+upgrade can choose the normal platform app directory and preview repair for app
+files, managed runtime surfaces, and cleanup of the old directory. Ask for
+explicit approval before writes, using plain wording such as
+`Approve the safe Agentera repair at <directory>`. After approval, apply the same
+safe repair path:
+
+```bash
+npx -y agentera@latest prime
+```
+
+After apply, retry the installed command from the platform app home reported by
+the upgrade output, not from the old default directory. If the command executes but
+fails before argparse, reports `invalid choice` for `prime`, or reports a status of
+`outdated`, `manual_review_needed`, missing-command, or repair-needed:
+
+- Say `Agentera found an old or broken local copy of itself.`
+- Say whether the preview changed anything; preview commands change nothing.
+- State the safe recommendation in plain language before paths or commands.
+- Show the clone-free preview command from `bundle.dryRunCommand` when present:
+
+```bash
+npx -y agentera@latest doctor
+```
+
+Ask for explicit approval before writes. A normal affirmative response is
+acceptable only when it clearly authorizes the same Agentera repair and directory.
+If approved, apply:
+
+```bash
+npx -y agentera@latest prime
+```
+
+After apply, retry:
+
+```bash
+npx -y agentera prime
+```
+
+If `AGENTERA_HOME` names the old default `$HOME/.agents/agentera`, no explicit
+`--install-root` was supplied, and `npx -y agentera` is
+missing or out of date, treat this as safe to preview with the normal Agentera
+directory above. Do not first ask the user to unset `AGENTERA_HOME`; do not claim to
+prove where the environment value came from. If `AGENTERA_HOME` names any other
+missing path, file, or directory with unknown files and the single command cannot
+run, do not overwrite it silently or fall back to a local checkout. Say:
+`Agentera was told to use a directory it cannot safely use. Choose a different
+Agentera directory, or approve --force only after checking that directory is safe to
+replace.`
+
+If a leftover 1.x managed marker block (`# agentera: AGENTERA_HOME (managed)`) is
+reported in shell startup diagnostics, say plainly that Agentera will not edit
+those files. Cleanup is user-owned manual cleanup, not a repair write. Upgrade
+does not scan shell startup files.
+
+Only after the installed CLI succeeds, proceed to Step -1 and the routing layers
+below. Do not fall through to a local checkout as a workaround; the npx commands
+above are portable and require no local checkout.
+
+### Step -1: Top-level CLI-first state access
+
+The `agentera` CLI is the authoritative interface to project state. Use
+top-level state commands for routine access. `agentera query` is reserved for
+advanced/custom artifact inspection when no normal command serves the needed
+state.
+
+Before any artifact-backed briefing, route decision, or capability state read,
+run the top-level command that owns the needed state. The app health gate
+above must have already confirmed the installed CLI is usable.
+
+Routine commands are: `prime`, `state plan`, `state progress`, `state health`,
+`state todo`, `state decisions`, `state docs`, `state objective`, and
+`state experiments`. Top-level aliases for legacy commands remain during migration with stderr deprecation; see [audience-namespace-cli-migration.yaml](references/cli/audience-namespace-cli-migration.yaml) for the full list. Discovery and custom
+inspection remain available through `agentera schema --format json`
+(with legacy `describe` alias),
+`state query --list-artifacts`, and `state query <artifact-name> --format json|yaml`.
+Structured discovery includes an artifact-location contract with mapped paths,
+normal read commands, and raw-access boundaries; use that contract before
+reading `.agentera/docs.yaml` or probing `.agentera/` for path discovery.
+
+Do not silently bypass the CLI and read raw `.agentera/*.yaml` files first. If
+CLI state declares complete startup coverage, do not perform defensive raw
+artifact reads for normal startup. If CLI state is unavailable or incomplete,
+try the CLI-provided fallback commands first; use raw artifact reads only as a
+last-resort fallback after those paths fail or still declare incomplete state.
+When `agentera state plan --format json` returns
+`source_contract.complete_for_plan_artifact=true`, treat its `summary`,
+`entries`, and `source_contract` as complete for normal `PLAN.md` startup and
+evaluation context; do not read `.agentera/plan.yaml` merely to re-check task
+dependencies, acceptance criteria, evidence, overall acceptance, surprises,
+prior-plan archive references, or plan metadata. This no-raw-read rule is for
+normal read-only startup/evaluation. Raw mapped plan artifact access remains valid
+for writes, archives, validation, corruption diagnostics, or unavailable or
+incomplete CLI state after CLI fallbacks.
+
+When artifact paths are the only missing fact, prefer the CLI discovery contract:
+`agentera schema --format json` exposes `artifact_locations`, and
+`agentera state query --list-artifacts --format json` exposes the same compact records
+with a `names` compatibility list. Plain `state query --list-artifacts` remains the
+human names list. These discovery surfaces do not replace routine state commands
+for normal artifact content reads.
+
+For bare `/agentera` or a bare user message exactly `hej`, run `agentera prime`
+first and render the README-style hej dashboard from that single composite
+result. The CLI output is source data, not the user-facing dashboard; do not
+relay raw `agentera prime` lines as the final briefing. Do not run individual `state plan`, `state progress`, `state health`,
+`state todo`, or `state decisions` commands unless `agentera prime` fails or explicitly asks
+for fallback. The final response must
+transform source labels such as `mode:`, `profile:`, `health:`, `issues:`,
+`plan:`, `objective:`, `attention:`, `next_action:`, `app_home:`,
+`v1_migration:`, and `source_contract:` into the dashboard below; never paste
+those labels as the briefing.
+
+Bare `/agentera` returning-project output must include these visible markers:
+
+```text
+┌─┐┌─┐┌─┐┌┐┌┌┬┐┌─┐┬─┐┌─┐
+├─┤│ ┬├┤ │││ │ ├┤ ├┬┘├─┤
+┴ ┴└─┘└─┘┘└┘ ┴ └─┘┴└─┴ ┴
+
+─── status ─────────────────────────────
+  [metric lines: health, issues, plan, objective, profile as available]
+  [1-2 sentence narrative read closing the status section]
+─── attention ──────────────────────────
+─── next ───────────────────────────────
+```
+
+Use the README-style layout from hej Step 1b: metrics first, narrative read
+inside `status`, then attention and next. The issues summary line uses
+`critical · degraded · annoying` only. Omit `attention` only when the source has no attention items. Always include the
+mandatory `⌂ hej · <status>` marker below the dashboard code fence, and ask for
+confirmation before invoking the suggested downstream capability. For
+`/agentera <capability-name>` or `/agentera <alias>`, do not assume the route
+word is a CLI command. The CLI command surface is state-oriented, not
+capability-oriented:
+use the supported routine state command or commands that own the capability's
+needed artifacts, as declared by that capability's artifact schema. For example,
+`resonera` reads decisions through `agentera state decisions`, not through the
+unsupported capability-name command `agentera resonera`. Never run unsupported
+capability-name commands such as `agentera resonera`, `agentera planera`, or
+`agentera realisera` as a bootstrap step. Shared words stay split by interface:
+`/agentera plan` routes to planera, while `agentera state plan` reads plan state from
+the CLI. When capability-specific startup context is needed, request it through
+`agentera prime --context <capability> --format json`. Use returned
+`capability_context.state.included` directly, and for
+`capability_context.state.missing`, run the listed
+`capability_context.state.fallback_commands` before raw file access. Historical
+v2 paths `hej --capability-context` and `--context-profile` are removed in 3.0.
+For normal ≡ planera execution, use
+`capability_context.context.planning_context.startup_contract` from
+`agentera prime --context planera --format json`
+before reading `skills/agentera/capabilities/planera/instructions.md`. Read Planera prose only when
+editing Planera, resolving contradiction or ambiguity, validating detailed
+behavior not covered by the compact contract, or investigating benchmark/read-trigger
+evidence. This preserves Planera prose as detailed authority and does not add
+`agentera planera`; `/agentera plan` remains routing while `agentera state plan`
+remains plan state (top-level `agentera plan` is a migration alias).
+For normal DECISIONS.md context, use `agentera state decisions --format json` and its
+source_contract. When `complete_for_normal_deliberation_context=true`, preserve
+returned `missing_fields`, `compacted`, `caveats`, and `satisfaction.review_needed`
+instead of raw-reading `.agentera/decisions.yaml` to reconstruct missing history.
+Raw decision artifact access is reserved for Resonera-owned writes/repairs,
+artifact corruption diagnostics, or CLI defect investigation.
+Reading a capability's `instructions.md` file is not itself a capability invocation;
+invocation means routing to the capability, following its prose, and using the
+CLI state layer first for artifact-backed state.
+
+Capability handoffs use glyph plus canonical capability name, for example
+`⧉ realisera` or `≡ planera`. Reserve `/agentera <alias>` wording for explicit
+slash-route documentation and do not use standalone slash-capability names such
+as `/realisera` or `/planera` as handoff labels. SG priority codes such as `SG2`
+are internal protocol references; do not render them in user-facing handoff
+labels.
+
+Handoff verbs are normative:
+
+- `route`: the user directly invoked a capability by canonical name, primary
+  alias, or slash route. This is consent to invoke that capability; do not ask
+  for extra handoff confirmation.
+- `suggest`: recommend a downstream capability and wait for user confirmation.
+- `handoff prompt`: ask whether to run the suggested capability. Use the native
+  question tool for multi-choice prompts and for a single state-changing
+  Proceed/Cancel handoff. State-changing means the proposed next step may write
+  artifacts, edit code, run optimization or orchestration cycles, apply
+  migrations, refresh app/runtime state, or otherwise mutate project/runtime
+  state. Use the behavior rule first, with common examples such as ⧉ realisera,
+  ≡ planera when creating or updating plans, ▤ dokumentera when writing docs,
+  ⎘ optimera when running or applying optimization cycles, and ⎈ orkestrera
+  when dispatching cycles. A single non-mutating suggestion may use a free-form
+  prompt; clear replies such as `yes`, `start`, `do it`, or `run <capability>`
+  confirm the named suggestion. Ambiguous replies get one clarifying question.
+- `dispatch`: invoke another capability autonomously only when the current
+  capability explicitly owns that orchestration flow.
+- `chain`: dispatch multiple capabilities autonomously only inside an explicitly
+  orchestrated flow; otherwise suggest the next capability and wait.
+
+The first Agentera/hej response in a fresh interaction should deliver the brief
+and a free-form continuation prompt, not a native question menu, unless the user
+explicitly asks for bounded choices or the suggested next step is a
+state-changing Proceed/Cancel handoff. Mid-conversation, use the runtime's
+native question tool only when there are at least two meaningful non-terminal
+next actions or a consequential Proceed/Cancel decision; state-changing
+capability handoffs are consequential Proceed/Cancel decisions even when there
+is only one suggested action. Do not count `Done` or free-form/custom answer
+affordances as alternatives. Current host examples are Claude Code
+`AskUserQuestion`, Copilot `ask_user`, Codex `request_user_input`, and OpenCode
+`question`. Put the recommended choice first with `(Recommended)` in its label
+and include `Done`. Selecting a downstream capability option is confirmation to
+invoke that capability; selecting `Done` stops without routing. This generic
+question-tool gating applies to hej and capability handoff prompts. Once a
+capability is invoked, that capability's own interaction rules control whether
+the runtime-native question tool is required.
+
+### Step 0: V1 migration handling
+
+Do not perform separate v1 Markdown/YAML discovery before a normal prime briefing.
+The top-level CLI owns v1 detection. For bare `/agentera` or bare `hej`, render
+any `v1 artifacts detected` attention item and affected-file list from
+`agentera prime`; do not spend extra tool calls on `.agentera/*.md`,
+`.agentera/*.yaml`, or `VISION.md` globs.
+
+If the CLI reports v1 state, use the `v1_migration.dry_run_command` preview it
+supplies. A no-write preview is mandatory before any apply command. Tell the
+user the preview changes nothing, then ask before applying. Only after
+confirmation, run `v1_migration.apply_command`.
+Never infer consent from the presence of v1 artifacts.
+The preview command shape is
+`npx -y agentera@latest doctor`
+or, from a local checkout, `node packages/cli/dist/bin/agentera.js doctor`
+when supplied by the CLI.
+Do not replace the CLI-owned preview with manual artifact inspection,
+hand-written migration steps, or raw YAML reads. Only the apply step requires confirmation.
+
+The upgrade command is idempotent. It installs or updates Agentera app files
+when invoked through `uvx`, migrates v1 artifacts, wires runtime config to that
+app home, and removes fixable outdated v1 runtime artifacts.
+The artifacts phase migrates supported v1 Markdown files to YAML with backups
+after preview and confirmation. Package refreshes that run `npx skills remove`
+for v1 skill entries and `npx skills add` for `/agentera` remain explicit opt-in
+via `--update-packages`. `npx skills update` by itself updates only the visible
+skill; if `/agentera` then finds missing or out-of-date app files, run the
+plain-language repair preview above so upgrade updates the app and cleans up
+the old default directory when it is recoverable.
+
+### Layer 1: Bare `/agentera` or bare `hej` — delegate to prime
+
+If the request is `/agentera` with no additional text, or the complete user
+message is exactly `hej`, delegate immediately to hej. Hej performs state-aware
+routing through the `agentera prime` composite result, which condenses project
+artifacts and suggests the most useful next capability. This is deterministic
+and never wrong. Bare `hej` must not be handled as a generic greeting.
+
+### Layer 2: capability name or `/agentera <primary-alias>` — direct route
+
+If the request text exactly matches a capability name (case-insensitive, e.g.,
+"resonera", "planera", "hej"), route directly to that capability without
+evaluating natural-language trigger patterns. Canonical Swedish names remain the
+protocol identity and bypass natural-language matching.
+
+If the request begins with a canonical capability name followed by more text, or
+uses `/agentera <capability-name> <topic>`, route directly to that capability and
+pass the remaining text as the user's topic or instruction. For example,
+`resonera decide whether to keep this API` invokes ❈ resonera; it must not
+receive a generic analysis response and must not try the unsupported CLI command
+`agentera resonera`.
+
+If the request text exactly matches one primary alias from
+`capability_schema_contract.yaml` `ROUTE_ALIASES.primary_aliases`, route directly
+to that alias's capability without evaluating natural-language trigger patterns.
+Each capability has exactly one primary alias. Secondary user wording stays in
+capability trigger schemas below this layer. Examples: `deliberate`,
+`brainstorm`, and `rubber duck` remain resonera trigger wording; `brief` and
+`what's next` remain hej trigger wording. These are not primary aliases.
+
+### Layer 3: Natural language with high-confidence match
+
+If the request is natural language (e.g., "help me think through this"), evaluate capability trigger schemas and route when the schema-owned semantics produce a high-confidence match.
+
+### Layer 4: Borderline match — disambiguation
+
+If the schema-owned routing semantics produce competing borderline matches, present a disambiguation prompt instead of silently choosing. List the matching capabilities with brief descriptions and ask the user to confirm or clarify.
+
+### Layer 5: No match — fallback to hej
+
+If no capability matches with sufficient confidence, route to hej for orientation. Hej handles greetings, status requests, and ambiguous inputs.
+
+### Trigger Pattern Discovery
+
+The trigger-to-capability map for Layers 3-4 is derived from each capability's `schemas/triggers.yaml`, not hardcoded here. Pattern matching, priority, thresholds, fallback, and disambiguation metadata belong to those trigger schemas and the capability schema contract. This keeps the routing layer focused on request-to-capability routing; capability directories and schemas remain the detailed Interface sources.
+
+---
+
+## Safety rails
+
+<critical>
+- NEVER push to remote repos without explicit user instruction
+- NEVER modify `.agentera/vision.yaml` or objective state during execution cycles (only the user or the owning capability may change these)
+- NEVER commit secrets or credentials to any artifact or file
+- Respect artifact path resolution: check `.agentera/docs.yaml` for path overrides before accessing any agent-facing artifact
+</critical>
+
+---
+
+## Exit signals
+
+All capabilities use the exit vocabulary defined by `protocol.yaml` `EXIT_SIGNALS`. Capability `schemas/exit.yaml` files reference that protocol authority; the routing layer does not maintain a separate exit-signal table.
+
+---
+
+## Cross-skill integration
+
+The twelve-skill suite is collapsed into one Agentera skill. Each capability's schemas define cross-capability artifact references using stable IDs. Cross-capability routing is handled through capability trigger schemas described in the Routing Logic section. Capabilities read from and write to the same artifact store (`.agentera/` for agent-facing, project root for human-facing), so inter-capability data flows through shared artifacts, not direct invocation.
+
+### Artifact path resolution
+
+Before reading or writing any artifact, check if `.agentera/docs.yaml` exists. If it has an Artifact Mapping section, use the path specified for each canonical filename. If `.agentera/docs.yaml` doesn't exist or has no mapping for a given artifact, use the default layout:
+
+- Human-facing artifacts at the project root: `TODO.md`, `CHANGELOG.md`, `DESIGN.md`
+- Agent-facing artifacts in `.agentera/` as YAML: `progress.yaml`, `decisions.yaml`, `health.yaml`, `plan.yaml`, `docs.yaml`, `vision.yaml`, `objective.yaml`, `experiments.yaml`
+
+---
+
+## Directory Structure
+
+```
+skills/agentera/
+  SKILL.md                          # This file
+  protocol.yaml                     # Shared primitives
+  capability_schema_contract.yaml   # Self-referential schema contract
+  capabilities/
+    hej/
+      instructions.md
+      schemas/
+        triggers.yaml
+        artifacts.yaml
+        validation.yaml
+        exit.yaml
+    resonera/
+      instructions.md
+      schemas/
+        triggers.yaml
+        artifacts.yaml
+        validation.yaml
+        exit.yaml
+    ... (12 capabilities total)
+```
+
+Validate any capability against the contract through the canonical CLI:
+
+```bash
+npx -y agentera check validate capability <name-or-path>
+```
+
+Self-validate the contract:
+
+```bash
+npx -y agentera check validate capability-contract --format json
+```

package/bundle/skills/agentera/agents/dokumentera.toml

@@ -0,0 +1,6 @@
+# agentera_managed: true
+name = "dokumentera"
+description = "Documentation updates and synchronization."
+developer_instructions = """
+You are the Agentera dokumentera capability subagent. You have file write and file edit tools available to create or update files, but shell execution is disabled — do not attempt to run command line tools or scripts. Read the authoritative instructions at ${AGENTERA_HOME}/app/skills/agentera/capabilities/dokumentera/instructions.md when available. For local checkout development, use skills/agentera/capabilities/dokumentera/instructions.md under the active Agentera source root. Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+"""

package/bundle/skills/agentera/agents/hej.toml

@@ -0,0 +1,6 @@
+# agentera_managed: true
+name = "hej"
+description = "Agentera orientation and routing dashboard."
+developer_instructions = """
+You are the Agentera hej capability subagent. You are a read-only agent — do not write files or execute shell commands. Read the authoritative instructions at ${AGENTERA_HOME}/app/skills/agentera/capabilities/hej/instructions.md when available. For local checkout development, use skills/agentera/capabilities/hej/instructions.md under the active Agentera source root. Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+"""

package/bundle/skills/agentera/agents/inspektera.toml

@@ -0,0 +1,6 @@
+# agentera_managed: true
+name = "inspektera"
+description = "Codebase health audit."
+developer_instructions = """
+You are the Agentera inspektera capability subagent. You have file write and file edit tools available to create or update files, but shell execution is disabled — do not attempt to run command line tools or scripts. Read the authoritative instructions at ${AGENTERA_HOME}/app/skills/agentera/capabilities/inspektera/instructions.md when available. For local checkout development, use skills/agentera/capabilities/inspektera/instructions.md under the active Agentera source root. Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+"""

package/bundle/skills/agentera/agents/inspirera.toml

@@ -0,0 +1,6 @@
+# agentera_managed: true
+name = "inspirera"
+description = "External pattern research and synthesis."
+developer_instructions = """
+You are the Agentera inspirera capability subagent. You are a read-only agent — do not write files or execute shell commands. Read the authoritative instructions at ${AGENTERA_HOME}/app/skills/agentera/capabilities/inspirera/instructions.md when available. For local checkout development, use skills/agentera/capabilities/inspirera/instructions.md under the active Agentera source root. Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+"""

package/bundle/skills/agentera/agents/optimera.toml

@@ -0,0 +1,6 @@
+# agentera_managed: true
+name = "optimera"
+description = "Metric-driven optimization cycles."
+developer_instructions = """
+You are the Agentera optimera capability subagent. You have full file write, file edit, and shell execution tools available — use them to implement code changes, run tests, and commit results. Read the authoritative instructions at ${AGENTERA_HOME}/app/skills/agentera/capabilities/optimera/instructions.md when available. For local checkout development, use skills/agentera/capabilities/optimera/instructions.md under the active Agentera source root. Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+"""

package/bundle/skills/agentera/agents/orkestrera.toml

@@ -0,0 +1,6 @@
+# agentera_managed: true
+name = "orkestrera"
+description = "Multi-cycle orchestration over active plans."
+developer_instructions = """
+You are the Agentera orkestrera capability subagent. You have full file write, file edit, and shell execution tools available — use them to implement code changes, run tests, and commit results. Read the authoritative instructions at ${AGENTERA_HOME}/app/skills/agentera/capabilities/orkestrera/instructions.md when available. For local checkout development, use skills/agentera/capabilities/orkestrera/instructions.md under the active Agentera source root. Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+"""

package/bundle/skills/agentera/agents/planera.toml

@@ -0,0 +1,6 @@
+# agentera_managed: true
+name = "planera"
+description = "Planning with acceptance criteria."
+developer_instructions = """
+You are the Agentera planera capability subagent. You have file write and file edit tools available to create or update files, but shell execution is disabled — do not attempt to run command line tools or scripts. Read the authoritative instructions at ${AGENTERA_HOME}/app/skills/agentera/capabilities/planera/instructions.md when available. For local checkout development, use skills/agentera/capabilities/planera/instructions.md under the active Agentera source root. Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+"""

package/bundle/skills/agentera/agents/profilera.toml

@@ -0,0 +1,6 @@
+# agentera_managed: true
+name = "profilera"
+description = "Decision profiling and preference memory."
+developer_instructions = """
+You are the Agentera profilera capability subagent. You have full file write, file edit, and shell execution tools available — use them to implement code changes, run tests, and commit results. Read the authoritative instructions at ${AGENTERA_HOME}/app/skills/agentera/capabilities/profilera/instructions.md when available. For local checkout development, use skills/agentera/capabilities/profilera/instructions.md under the active Agentera source root. Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+"""