# Agentera > 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. - Skill: `jgabor/agentera` (Agent Skill, multi-file: 88 files) - Install (CLI): `npx skillmds@latest add jgabor/agentera` - Raw SKILL.md: https://api.skillmd.com/api/skills/jgabor/agentera/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: jgabor (https://skillmd.com/u/jgabor) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/jgabor/agentera --- # 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`, resolve the app home in one separate command, then run prime: ```bash RESOLVED_AGENTERA_HOME="$(uvx --from git+https://github.com/jgabor/agentera agentera app-home)" uv run "$RESOLVED_AGENTERA_HOME/app/scripts/agentera" prime ``` In a local Agentera checkout, the resolver may use `uv run scripts/agentera app-home` instead of `uvx`. 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 `/app/scripts/agentera` before the assignment takes effect. Resolve `RESOLVED_AGENTERA_HOME` with the app-home precedence `AGENTERA_HOME` when set, otherwise the platform data home from `agentera app-home`. Do not substitute the Linux-only `${XDG_DATA_HOME:-$HOME/.local/share}/agentera` fallback on macOS or Windows. 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. 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 `$AGENTERA_HOME/app/scripts/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 uvx --from git+https://github.com/jgabor/agentera agentera upgrade --dry-run ``` 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 `. After approval, apply the same safe repair path: ```bash uvx --from git+https://github.com/jgabor/agentera agentera upgrade --yes ``` 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 uvx --from git+https://github.com/jgabor/agentera agentera upgrade --install-root "$RESOLVED_AGENTERA_HOME" --dry-run ``` 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 uvx --from git+https://github.com/jgabor/agentera agentera upgrade --install-root "$RESOLVED_AGENTERA_HOME" --yes ``` After apply, retry: ```bash uv run "$RESOLVED_AGENTERA_HOME/app/scripts/agentera" prime ``` If `AGENTERA_HOME` names the old default `$HOME/.agents/agentera`, no explicit `--install-root` was supplied, and `$AGENTERA_HOME/app/scripts/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 uvx 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 --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 · normal · annoying` in the order prime emits them. Omit `attention` only when the source has no attention items. Always include the mandatory `⌂ hej · ` marker below the dashboard code fence, and ask for confirmation before invoking the suggested downstream capability. For `/agentera ` or `/agentera `, 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 --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 ` 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 ` 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 `uvx --from git+https://github.com/jgabor/agentera agentera upgrade --project "$PWD" --dry-run` or the local-checkout equivalent `uv run scripts/agentera upgrade --project "$PWD" --dry-run` 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 ` — 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 `, 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 - 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 --- ## 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 uv run scripts/agentera validate capability ``` Self-validate the contract: ```bash uv run scripts/agentera validate capability-contract --format json ```