| 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.11 |
| 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, resolve the app home in
one separate command, then run prime:
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:
- What happened:
Agentera found an old or broken local copy of itself.
- What the preview did:
Nothing was changed.
- What the recommended fix will do:
Install a fresh Agentera app copy in the normal Agentera directory.
- 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:
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 <directory>. After approval, apply the same
safe repair path:
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:
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:
uvx --from git+https://github.com/jgabor/agentera agentera upgrade --install-root "$RESOLVED_AGENTERA_HOME" --yes
After apply, retry:
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 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:
┌─┐┌─┐┌─┐┌┐┌┌┬┐┌─┐┬─┐┌─┐
├─┤│ ┬├┤ │││ │ ├┤ ├┬┘├─┤
┴ ┴└─┘└─┘┘└┘ ┴ └─┘┴└─┴ ┴
─── 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 · <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
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 <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
- 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:
uv run scripts/agentera validate capability <name-or-path>
Self-validate the contract:
uv run scripts/agentera validate capability-contract --format json
