agentera 3.0.0-dev.2 → 3.0.0-dev.21

package/bundle/skills/agentera/SKILL.md

@@ -1,404 +1,113 @@
 ---
 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"
+  One agent, one CLI, many capabilities. Per-capability instructions live in
+  `packages/cli/src/capabilities/<name>/instructions.ts` and the runtime serves
+  it through `agentera prime --context <name> --format json`. Use this skill
+  for /agentera and Agentera capability requests; bare `/agentera` runs the
+  agentera prime orientation dashboard path instead of a generic greeting.
+version: "3.0.0"
 spec_sections: [1, 2, 3, 4, 5, 6, 11, 13, 18, 19, 20, 22, 23]
+capabilities:
+  - status
+  - vision
+  - discuss
+  - research
+  - plan
+  - build
+  - optimize
+  - audit
+  - document
+  - profile
+  - design
+  - orchestrate
 ---
 
 # agentera
 
-One install, one entry point, one query interface to all project state. Twelve capabilities live inside one Agentera skill.
+One agent, one CLI, many capabilities. The CLI is the routing brain — it owns
+project memory, capability instructions, routing judgment, and the worker-spec contract.
+The host agent learns one contract: the CLI.
 
 ---
 
-## Shared Protocol
+## Bootstrap
 
-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:
+Run `agentera prime` for orientation. The JSON it returns is the complete
+contract — app status, state slices, attention items, next action, and the
+source contract that declares what's complete and what requires fallback.
 
 ```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:
+For capability-specific startup context:
 
 ```bash
-npx -y agentera@latest doctor
+npx -y agentera prime --context <capability> --format json
 ```
 
-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:
+This returns the capability's instructions, declared read/write needs, artifact
+inventory, included/missing state, and fallback commands. Use it before
+reading the instructions module directly.
+
+For static routing guidance (agentera vs native tools):
 
 ```bash
-npx -y agentera@latest prime
+npx -y agentera prime --guidance
 ```
 
-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:
+## Routing
 
-```bash
-npx -y agentera@latest doctor
-```
+The CLI routes. The host agent follows.
 
-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:
+| Request shape | Route |
+|---|---|
+| Bare `/agentera` | 1. Run `agentera prime --format json` for state data. 2. Run the `fetch_command` from `source_contract.capability_context` to get rendering instructions. 3. Follow `capability_context.instructions` for dashboard template, field rules, and exit marker. 4. Render the dashboard from the state data per the instructions. 5. Follow `next_action` to suggest the next capability. |
+| `/agentera <capability-name>` | Run `agentera prime --context <capability> --format json`. Follow the capability's instructions and contract. |
+| `/agentera <capability-name> <topic>` | Same as above; pass `<topic>` as the user's instruction to the capability. |
+| Natural language | Run `agentera prime --format json`. Run the `fetch_command` from `source_contract.capability_context` for rendering instructions. Use `next_action.capability` to suggest the matching capability. If no high-confidence match, present a disambiguation prompt. |
 
-```bash
-npx -y agentera@latest prime
-```
+Capability names are the routing identity: `status`, `vision`, `discuss`,
+`research`, `plan`, `build`, `optimize`, `audit`, `document`, `profile`,
+`design`, `orchestrate`. Plain-language triggers (`help me decide`, `what's
+next`, `plan this`) match against each capability's `schemas/triggers.yaml`,
+not hardcoded here.
 
-After apply, retry:
+The full five-layer routing model (Decision 42) — Layer 1 bare `/agentera`,
+Layer 2 capability/alias direct route, Layer 3 high-confidence natural-language
+match, Layer 4 borderline disambiguation, Layer 5 no-match fallback to status —
+is defined in [`references/cli/routing-model.md`](../../references/cli/routing-model.md).
+Layers 1, 2, and 5 are implemented; Layers 3 and 4 are being built by the Trigger
+Schema Enrichment and Layer 3-4 Routing plan.
 
-```bash
-npx -y agentera prime
-```
+Handoff verbs:
 
-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.
+- `route`: user directly invoked a capability. Consent to invoke; no extra confirmation.
+- `suggest`: recommend a downstream capability and wait for confirmation.
+- `dispatch`: invoke another capability autonomously only when the current capability owns that orchestration flow.
+- `chain`: dispatch multiple capabilities only inside an orchestrated flow.
 
-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 ───────────────────────────────
-```
+Capability handoffs use glyph plus canonical name (e.g. `⧉ build`, `≡ plan`).
 
-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.
+---
+
+## Dashboard rendering
+
+The prime dashboard rendering contract — template, field-by-field rules, output
+budget, attention-item ordering, exit marker — is owned by the status capability
+instructions. Bare `agentera prime --format json` returns a pointer at
+`source_contract.capability_context` with a `fetch_command` to retrieve them;
+run it, then follow `capability_context.instructions` for layout,
+inclusion/exclusion rules, and the mandatory `⌂ status · <status>` exit marker.
+Ask for confirmation before invoking a state-changing downstream capability.
+
+The first response in a fresh interaction delivers 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.
 
 ---
 
@@ -408,63 +117,82 @@ The trigger-to-capability map for Layers 3-4 is derived from each capability's `
 - 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
+- For supported mutations, use the state writer; it resolves `.agentera/docs.yaml` path overrides and validates the published bytes
+- For direct access to other agent-facing artifacts, respect `.agentera/docs.yaml` path overrides
 </critical>
 
 ---
 
-## Exit signals
+## Capabilities
 
-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.
+| | Capability | Primary route | Purpose |
+|---|---|---|---|
+| ⌂ | status | `/agentera status` | Orientation and routing |
+| ⛥ | vision | `/agentera vision` | Define project direction |
+| ❈ | discuss | `/agentera discuss` | Structured deliberation |
+| ⬚ | research | `/agentera research` | External pattern analysis |
+| ≡ | plan | `/agentera plan` | Planning with acceptance criteria |
+| ⧉ | build | `/agentera build` | Autonomous development |
+| ⎘ | optimize | `/agentera optimize` | Metric-driven optimization |
+| ⛶ | audit | `/agentera audit` | Codebase health audit |
+| ▤ | document | `/agentera document` | Documentation |
+| ♾ | profile | `/agentera profile` | Decision profiling |
+| ◰ | design | `/agentera design` | Visual identity system |
+| ⎈ | orchestrate | `/agentera orchestrate` | Multi-cycle orchestration |
 
 ---
 
-## Cross-skill integration
+## Artifact writes
 
-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.
+The CLI state writer is the canonical mutation path for `progress`, `decisions`,
+`plan`, and `health`. Do not hand-edit those artifacts during normal capability
+execution. The writer assigns numbers, validates schema fields, honors docs-mapped
+paths, serializes concurrent writes, compacts where required, and supports
+filesystem-safe previews.
 
-### Artifact path resolution
+Discover the live contract before constructing a write:
 
-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:
+```bash
+agentera state decisions explain --format json
+agentera state decisions explain --verb update --format json
+```
 
-- 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`
+The same pattern applies to every writable artifact:
 
----
+```bash
+agentera state <progress|decisions|plan|health> explain --verb <verb> --format json
+```
 
-## Directory Structure
+Common mutations:
 
-```
-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)
-```
+- `agentera state progress append ... --format json`
+- `agentera state decisions append ... --format json`
+- `agentera state decisions update --number N ... --format json`
+- `agentera state plan create --input plan.yaml --format json`
+- `agentera state plan append|update|set-status|set-plan-status ... --format json`
+- `agentera state plan archive --format json`
+- `agentera state health append --input audit.yaml --format json`
 
-Validate any capability against the contract through the canonical CLI:
+Add `--dry-run` to preview any mutation without publishing it. Artifacts not
+listed above are outside the typed writer contract and remain governed by their
+owning capability's instructions and safety rails. `agentera schema --format
+json` exposes the machine-readable writer operation matrix under
+`state_writer` and on each writable `artifact_schemas[*].write_interface`.
 
-```bash
-npx -y agentera check validate capability <name-or-path>
-```
+---
 
-Self-validate the contract:
+## Artifact path resolution
 
-```bash
-npx -y agentera check validate capability-contract --format json
-```
+The state writer resolves path mappings itself. Before directly reading or
+writing an artifact outside the writer contract, 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`
+
+Do not silently bypass the CLI and read raw `.agentera/*.yaml` files first. If
+CLI state declares complete coverage, do not perform defensive raw artifact
+reads. Use raw artifact reads only as a last-resort fallback after CLI
+fallback commands fail or declare incomplete state.

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

@@ -0,0 +1,6 @@
+# agentera_managed: true
+name = "audit"
+description = "Codebase health audit."
+developer_instructions = """
+You are the Agentera audit 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. Run `agentera prime --context audit --format json` to fetch the authoritative instructions as a JSON capsule (the `prose` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+"""

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

@@ -0,0 +1,6 @@
+# agentera_managed: true
+name = "build"
+description = "Autonomous development execution."
+developer_instructions = """
+You are the Agentera build 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. Run `agentera prime --context build --format json` to fetch the authoritative instructions as a JSON capsule (the `prose` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+"""

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

@@ -0,0 +1,6 @@
+# agentera_managed: true
+name = "design"
+description = "Visual identity and design systems."
+developer_instructions = """
+You are the Agentera design 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. Run `agentera prime --context design --format json` to fetch the authoritative instructions as a JSON capsule (the `prose` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+"""

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

@@ -0,0 +1,6 @@
+# agentera_managed: true
+name = "discuss"
+description = "Structured deliberation and decision support."
+developer_instructions = """
+You are the Agentera discuss 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. Run `agentera prime --context discuss --format json` to fetch the authoritative instructions as a JSON capsule (the `prose` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+"""