agentera 0.0.0 → 3.0.0-dev.1

package/bundle/skills/agentera/capabilities/dokumentera/schemas/validation.yaml

@@ -0,0 +1,139 @@
+VALIDATION:
+  1:
+    id: V1
+    rule: user_approval_required
+    description: >-
+      Documentation MUST NOT be written or modified without explicit user
+      approval. Present drafts and get confirmation before writing.
+      This applies to all modes: intent-first, explore-and-generate,
+      update-and-verify, and first-run survey.
+    severity: critical
+    checks:
+      - "Draft presented to user before write"
+      - "Explicit approval received"
+  2:
+    id: V2
+    rule: dtc_code_wrong
+    description: >-
+      Per DTC principle, if code diverges from documentation, the code
+      is wrong. Documentation MUST NOT be updated to match broken code.
+      The divergence MUST be documented as an issue in TODO.md instead.
+    severity: critical
+    checks:
+      - "Docs not updated to match broken code"
+      - "Divergences filed to TODO.md"
+  3:
+    id: V3
+    rule: evergreen_prose
+    description: >-
+      Documentation MUST be written as the intended steady state:
+      evergreen and non-temporal. No changelogs, no "we recently added",
+      no temporal language. Write as if the feature has always existed.
+    severity: warning
+    checks:
+      - "No temporal language in documentation"
+  4:
+    id: V4
+    rule: dry_across_docs
+    description: >-
+      Information MUST NOT be duplicated across doc files. Keep it DRY:
+      reference, don't repeat. Each fact lives in one authoritative
+      location and other docs link to it.
+    severity: warning
+    checks:
+      - "No duplicated content across doc files"
+  5:
+    id: V5
+    rule: verification_required
+    description: >-
+      In update-and-verify mode, every doc claim MUST be checked against
+      code. The verification step MUST NOT be skipped.
+    severity: critical
+    checks:
+      - "All doc claims verified against code in update mode"
+  6:
+    id: V6
+    rule: read_before_generate
+    description: >-
+      Documentation MUST NOT be auto-generated without reading the code
+      it describes. Understanding precedes documentation.
+    severity: critical
+    checks:
+      - "Source code read before generating documentation"
+  7:
+    id: V7
+    rule: index_entry_brevity
+    description: >-
+      Each DOCS.md index entry description MUST be ≤15 words.
+      Index entries are summaries, not documentation.
+    severity: warning
+    checks:
+      - "Each index entry description ≤ 15 words"
+  8:
+    id: V8
+    rule: exit_marker_required
+    description: >-
+      Every dokumentera invocation MUST emit an exit marker using the
+      canonical glyph ▤ (SG8) in the format ▤ dokumentera · <status>
+      where status is one of EX1-EX4.
+    severity: critical
+    checks:
+      - "Exit marker present"
+      - "Exit marker uses glyph ▤ (SG8)"
+      - "Exit marker status is one of complete, flagged, stuck, waiting"
+  9:
+    id: V9
+    rule: closeout_context_first
+    description: >-
+      During final synchronization, Dokumentera MUST use `agentera prime
+      --context dokumentera --format json` and its `closeout_context`
+      before reading TODO, docs, changelog, or progress artifacts directly.
+      Complete closeout context is the normal source for mappings, version
+      policy, blockers, boundaries, progress evidence, benchmark evidence,
+      caveats, fallback commands, raw-read policy, and completeness.
+    severity: critical
+    checks:
+      - "Closeout starts from hej capability context"
+      - "Complete closeout_context is used before raw artifact reads"
+      - "Completeness and non-empty evidence flags are preserved"
+  10:
+    id: V10
+    rule: closeout_fallback_before_raw
+    description: >-
+      If closeout context is incomplete or caveated, Dokumentera MUST run the
+      listed existing CLI fallback commands before any last-resort raw artifact
+      read. No unsupported capability-name command or new closeout command may
+      be introduced.
+    severity: critical
+    checks:
+      - "Listed CLI fallback commands run before raw artifact reads"
+      - "Raw reads are last-resort diagnostics or write targets only"
+      - "No unsupported capability-name command is introduced"
+  11:
+    id: V11
+    rule: closeout_caveat_preservation
+    description: >-
+      Dokumentera MUST preserve closeout caveats about stale app/profile state,
+      compacted or missing state, missing benchmark evidence, absent local
+      metadata or tags, and unrecorded publication or remote state. Caveats must
+      not be hidden, reconstructed, or converted into approval to refresh apps,
+      profiles, vision, objective state, publication, push, or tags.
+    severity: critical
+    checks:
+      - "State caveats are carried into closeout notes"
+      - "Missing benchmark evidence remains caveated"
+      - "Publication, remote, tag, app refresh, and profile refresh are not invented"
+  12:
+    id: V12
+    rule: satisfaction_authority_boundary
+    description: >-
+      When Dokumentera touches decision satisfaction, it may record provisional
+      satisfaction with evidence but MUST NOT user-confirm satisfaction. Missing,
+      compacted, open, provisional, or review-needed satisfaction state remains a
+      caveat and review pressure; automation must not reconstruct hidden outcomes
+      or claim it proved user intent.
+    severity: critical
+    checks:
+      - "Provisional satisfaction requires evidence"
+      - "Only the user confirms final satisfaction"
+      - "Missing or compacted satisfaction caveats are preserved"

package/bundle/skills/agentera/capabilities/hej/instructions.md

@@ -0,0 +1,331 @@
+# HEJ
+
+**Holistic Entry Junction. Orient, Route, Activate**
+
+Single entry point to the agentera suite. Detects fresh vs returning, delivers a situational briefing, routes to the right capability. Same on first install and 100th session. A bare user message exactly `hej` uses this same briefing path, not generic greeting behavior.
+
+Each invocation = one orientation. Uses the CLI composite briefing first,
+writes nothing.
+
+---
+
+## State artifacts
+
+Glyph: **⌂** (SG1). Hej reads suite state through `agentera hej` and writes
+nothing. It may fall back to direct reads only when the composite command fails
+or explicitly asks for fallback.
+
+### CLI-first access
+
+For returning projects, run one composite command before any individual state
+access:
+
+```bash
+npx -y agentera prime
+```
+
+Use that output to render the dashboard and select the concrete next action. Do
+not relay raw CLI lines as the user-facing briefing. Source labels such as
+`mode:`, `profile:`, `v1_migration:`, `health:`, `issues:`, `plan:`,
+`objective:`, `attention:`, `next_action:`, `source_contract:`, and the
+compatibility `bundle:` installed-app status object are parsing aids, not
+dashboard lines. Do not run `agentera plan`, `agentera progress`, `agentera
+health`, `agentera todo`, `agentera decisions`, or `agentera objective` as part
+of normal hej briefing assembly. Do not read raw
+`.agentera/*.yaml` files for normal hej orientation. If a normal dashboard field
+is missing from `agentera hej`, fix or extend the composite CLI contract instead
+of adding routine fallback reads. Use top-level fallback commands only when
+`agentera hej` fails or explicitly reports fallback-only recovery.
+
+Resolve `RESOLVED_AGENTERA_HOME` with the app-home precedence `AGENTERA_HOME`
+when set, otherwise the platform data home, then run
+the installed command once. Do not preflight app health with `glob`, `grep`,
+`read`, `ls`, `python`, `doctor`, `--help`,
+`registry.json`, or `.agentera-bundle.json`.
+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.
+
+Recovery copy must be plain-language and recommendation-first. Never ask users
+to choose between technical install concepts, internal directory states,
+command-mode flags, or package-layout terms. Say what happened, what changed,
+what the safe fix does, and what it will not touch. The safe fix must say it will
+not edit project files, shell startup files, or unknown directories. Good recovery labels are `Use the safe fix
+(Recommended)`, `Choose a different directory`, and `Stop`.
+
+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`. Say: `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
+```
+
+That 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>`. Then 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 exits
+successfully, inspect the CLI-provided `bundle.status` installed-app status
+object. Only `up_to_date` passes the installed Agentera app gate for normal briefing.
+The object also carries `appHome`, `managedAppRoot`, `userDataRoot`,
+`expectedVersionSource`, `bundle.dryRunCommand`, `bundle.applyCommand`, and
+approval text. If the installed command cannot execute, is out of date, missing
+`hej`, fails before argparse, or reports manual-review-needed/repair-needed status, tell
+the user `Agentera found an old or broken local copy of itself.` Then preview the
+repair with the CLI-provided command when present:
+
+```bash
+npx -y agentera@latest doctor
+```
+
+Do not run the matching apply command until the user explicitly approves the
+same Agentera repair and directory.
+After apply, retry `npx -y agentera prime`; do not treat local checkout
+fallback as installed-app success. 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, show the normal
+Agentera directory preview above instead of first asking the user to unset
+`AGENTERA_HOME`; do not claim to prove where the environment value came from. If
+`AGENTERA_HOME` points at any other missing path, file, or directory with unknown
+files, 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 doctor reports a leftover 1.x managed marker block in
+shell startup files, say plainly that Agentera will not edit those files.
+Cleanup is user-owned manual cleanup, not a repair write.
+
+Use `agentera query <artifact-name> --format json|yaml` only for advanced or
+custom artifact inspection when no top-level command serves the needed state.
+
+### Artifact path resolution
+
+Only if `agentera hej` fails and fallback raw artifact access is explicitly
+needed, check `.agentera/docs.yaml` for path mappings before reading artifacts.
+Without a mapping, use the default layout:
+
+- Human-facing artifacts at the project root (Markdown): `TODO.md`, `CHANGELOG.md`, `DESIGN.md`
+- Agent-facing artifacts in `.agentera/` (YAML): `progress.yaml`, `decisions.yaml`, `health.yaml`, `plan.yaml`, `docs.yaml`, `vision.yaml`, and per-objective `objective.yaml` / `experiments.yaml`
+
+Canonical names are identifiers, not literal paths. PROFILE.md is global:
+`$PROFILERA_PROFILE_DIR/PROFILE.md`, default `$XDG_DATA_HOME/agentera/PROFILE.md`.
+
+### Contract values
+
+Use protocol tokens by ID where needed: severity arrows VT5-VT8, trend arrows
+VT12-VT13, progress bar VT18, separator VT16, list item VT15, section divider
+VT14, flow arrow VT17, skill glyphs SG1-SG12, exits EX1-EX4, issues SI1-SI4.
+
+---
+
+## Step 0: Detect mode
+
+Run the resolved installed `agentera hej` and use its `mode` field. If the
+installed-app status check reports out-of-date or blocked, show the CLI-provided
+refresh preview before normal mode handling.
+
+- **No artifacts found** → Step 1a (first time on this project)
+- **Artifacts found** → Step 1b (returning to known project)
+
+Narration voice: warm, brief, unscripted.
+
+---
+
+## Step 0.5: CLI-owned checks
+
+Do not run separate v1 artifact or PROFILE.md checks during normal hej
+orientation. `agentera hej` owns those checks and emits the mode, profile status,
+`v1_migration.detected`, `v1_migration.affected_files`,
+`v1_migration.dry_run_command`, `v1_migration.apply_command`, attention items,
+and next action. Render those fields; do not spend additional tool calls on
+`.agentera/*.md`, `.agentera/*.yaml`, `VISION.md`, or global profile-path
+discovery. Treat `v1_migration.dry_run_command` as the CLI-supplied preview and
+tell the user it changes nothing. Ask before any upgrade apply command, and only run
+`v1_migration.apply_command` after confirmation.
+The artifacts phase migrates supported v1 Markdown files to YAML with backups
+after preview and confirmation.
+
+If `v1_migration.detected` is false, emit no upgrade notice. Profile status is
+also CLI-owned: render `profile: loaded` without warning, and render
+`profile.suggested_action` or a missing-profile attention item only when
+`agentera hej` supplies one.
+
+If `npx skills update` refreshed only the visible skill and `/agentera` next
+finds missing or out-of-date app files, explain in plain language that Agentera
+also needs to repair its local app copy; the visible skill update alone is not
+enough. Package-manager repair commands remain opt-in through
+`--update-packages`.
+
+---
+
+## Step 1a: Welcome
+
+First impression: the colleague meets a new project.
+
+1. **Use composite state**: Build the welcome from `agentera hej` output only.
+   Do not scan README files, git history, languages, framework files, or project
+   size during bare orientation.
+
+2. **Share what's available**: lead with the suggested capability from
+   `next_action`. Do not enumerate the full suite unless asked.
+
+3. **Route**: ask what they'd like to do with a free-form prompt. Do not use a
+   native question menu on the initial welcome unless the user explicitly asked
+   for bounded choices. Invoke a capability only after the user confirms it.
+
+---
+
+## Step 1b: Briefing
+
+Show where things stand.
+
+1. **Use composite state**: Build the briefing from `agentera hej` output.
+   - Use its mode, profile, health, issue counts, plan progress, objective,
+     attention, and next_action fields.
+   - Do not issue individual artifact queries during normal returning-project
+     orientation.
+   - Do not open raw `.agentera/*.yaml` files unless the composite command fails
+     or names a fallback need.
+   - If exceptional fallback is required, prefer top-level commands such as
+     `agentera plan`, `agentera progress`, `agentera health`, `agentera todo`,
+     `agentera decisions`, `agentera objective`, and `agentera experiments`.
+     Missing normal dashboard fields should be repaired in `agentera hej`
+     instead of weakening the one-command path.
+   - Keep `agentera query` for advanced/custom inspection only.
+
+2. **Brief them**: concise status, only what exists. No empty sections.
+   Show the agentera logo.
+
+   ```
+   ┌─┐┌─┐┌─┐┌┐┌┌┬┐┌─┐┬─┐┌─┐
+   ├─┤│ ┬├┤ │││ │ ├┤ ├┬┘├─┤
+   ┴ ┴└─┘└─┘┘└┘ ┴ └─┘┴└─┴ ┴
+
+   ─── status ─────────────────────────────
+
+     ⛶ health    [⮉|⮋] [grade] ([worst dimension: grade])
+     ⇶ issues    N critical · M degraded · J annoying
+     ≡ plan      [██████▓░░░] N/M tasks
+     ⎘ optim     [metric] [current] → [target]
+     ♾ profile   [loaded | not found]
+
+     [1-2 sentence narrative read: what shipped, what's moving, what needs eyes.
+     Interpretation, not metrics. Closes the status section before attention.]
+
+   ─── attention ──────────────────────────
+
+     ⇶ [critical items, triple arrow for critical]
+     ⇉ [degraded items, double arrow for degraded]
+     → [normal items, single arrow for normal]
+     ⇢ [annoying items, dashed arrow for annoying]
+
+   ─── next ───────────────────────────────
+
+     suggested → [glyph] [capability] ([reason])
+   ```
+
+   Output constraint: ≤120 words total briefing, ≤15 words per routing suggestion.
+
+   **Exit marker**: after the closing code fence of the dashboard, emit `⌂ hej · <status>` on its own line, followed by a one-sentence summary of what you delivered. For `waiting`, `flagged`, or `stuck`, add a `▸` bullet below the summary identifying what the user needs to decide or act on next. The exit marker is mandatory on every invocation regardless of mode (fresh welcome or returning briefing).
+
+   **Formatting rules**:
+   - Each status line uses the skill glyph that owns that data
+   - Severity arrows (VT5-VT8) mark attention items by urgency
+   - Trend arrows (VT12/VT13) show health trajectory
+   - Progress bars (VT18) show plan completion visually
+   - The inline separator (VT16) joins counts on a single line
+   - Lead with status metrics, then the narrative read inside the status section
+   - The narrative read is colleague interpretation; metric lines above it are evidence
+   - The issues summary line lists critical, degraded, and annoying counts only;
+     normal-priority items belong in attention with → (SI3), not on the summary line
+   - Omit any line whose source artifact is missing
+   - Omit any section that would be empty (e.g., no attention items = no attention section)
+
+3. **Attention items**: priority order with severity arrows (SI1-SI4):
+   - ⇶ (SI1) Critical issues, degrading health dimensions
+   - ⇉ (SI2) Blocked/overdue plan tasks, stale artifacts (plan-relative per contract staleness detection; fall back to PROGRESS.md recency heuristic when no plan context exists), overdue health audits (hybrid time/cycle staleness via `AGENTERA_INSPEKTERA_MAX_AGE_DAYS` default 30 and `AGENTERA_INSPEKTERA_MAX_CYCLES` default 10; stale when either axis exceeds its threshold), loop stop-condition triggers
+   - → (SI3) Standard work: features, improvements, routine tasks
+   - ⇢ (SI4) Unresolved exploratory decisions
+
+   Nothing? Say so. A clean bill of health is useful.
+
+4. **Select the concrete next action before selecting the skill**.
+   - The routing suggestion MUST name the artifact item it would act on.
+   - Valid objects: `PLAN Task N: <title>`, `TODO: <item>`, `DECISION N follow-up`, `OBJECTIVE: <metric>`, or `VISION refresh`.
+   - A skill name without a concrete object is not a valid suggestion.
+
+    Priority order. SG codes are internal protocol references; never render them
+    in user-facing handoff labels:
+   - Active PLAN with pending tasks → suggest ⎈ orkestrera for the first unblocked pending task.
+   - Critical or degrading health → suggest ⛶ inspektera or ⧉ realisera for the named finding.
+   - Stale health audit (CLI `health.stale=true`) with no higher-priority work → suggest ⛶ inspektera for `HEALTH: Audit N stale`.
+   - Active non-closed OBJECTIVE with stalled or missing metric evidence → suggest ⎘ optimera for that metric.
+   - TODO.md open items → select the highest-severity open item, then route by shape: narrow one-cycle TODOs suggest ⧉ realisera; contract-shaped, multi-surface, dependency-heavy, migration, schema, metadata, validation, or acceptance-risky TODOs suggest ≡ planera first. Prefer items that unlock product evidence or future plans.
+   - Pending DECISIONS.md follow-up → suggest ❈ resonera for the named unresolved decision.
+   - Vision exists but no plan, objective, decision follow-up, or TODO work is active → suggest ≡ planera.
+   - No vision, no executable follow-ups, and no active plan → suggest ⛥ visionera to choose a direction.
+
+   Do not let `healthy + plan complete → ⛥` override active TODO, OBJECTIVE, DECISIONS, or a newer active PLAN. A completed plan means "look for the next executable follow-up," not automatically "refresh vision."
+
+5. **Route**: present one concrete suggestion and let the user choose. No coercion.
+   - Do not list generic skill options unless the user asks for the full menu.
+   - The waiting bullet should ask whether to run the named action, not ask the user to pick from skills.
+   - On the initial Agentera/hej brief, use a free-form continuation prompt rather than a native question menu unless the user asked for bounded choices or the suggested next step is a state-changing Proceed/Cancel handoff.
+   - Mid-conversation, use the native question tool only for at least two meaningful non-terminal next actions or a consequential Proceed/Cancel decision; `Done` and free-form/custom answer affordances do not count as alternatives.
+   - State-changing handoffs are consequential Proceed/Cancel decisions even when there is only one suggested action. 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.
+   - For one non-mutating suggested action, clear free-form acceptance such as `yes`, `start`, `do it`, or `run <capability>` confirms that suggestion. Ambiguous replies get one clarifying question.
+
+---
+
+## Step 2: Route
+
+Narration voice: "Kicking off [skill]..." or similarly brief.
+
+Invoke the capability. Hej's work is done.
+
+Unclear mapping? Ask **one** clarifying question. No compound questions.
+
+---
+
+## Safety rails
+
+<critical>
+- NEVER execute implementation work. Hej orients and routes; it does not build, audit, plan, or decide.
+- NEVER dump full artifact contents verbatim. Summarize concisely; the user can read the files themselves.
+- NEVER skip the briefing in returning mode. The user needs context before choosing a direction.
+- NEVER assume what the user wants without asking. Present the suggestion, then wait for confirmation.
+- NEVER modify any state artifact. Hej is strictly read-only.
+- NEVER route to a capability without the user's consent. Suggest, don't force.
+</critical>
+
+---
+
+## Exit signals
+
+Report one of these statuses at workflow completion (protocol refs: EX1-EX4).
+
+Format: emit `⌂ hej · <status>` on its own line below the dashboard's closing code fence, followed by a one-sentence summary of what was delivered. For `flagged` (EX2), `stuck` (EX3), and `waiting` (EX4), add a `▸` (VT15) bullet below the summary identifying what the user needs to decide or act on next. The exit marker is mandatory and uses hej's canonical glyph `⌂` (SG1, U+2302).
+
+- **complete** (EX1): Briefing delivered (or welcome shown) and user successfully routed to a capability.
+- **flagged** (EX2): Briefing delivered but critical attention items were found: critical issues, degrading health, loop stop-condition triggers. Each concern is listed explicitly.
+- **stuck** (EX3): Cannot orient: the working directory is not a code project, no readable files exist, or permissions prevent scanning.
+- **waiting** (EX4): Briefing or welcome delivered, suggestion made, awaiting user input on which direction to take.
+
+---
+
+## Cross-capability integration
+
+Hej is the suite entry point. It reads other capabilities' artifacts, produces
+no artifact, and outputs only a briefing plus routing suggestion.

package/bundle/skills/agentera/capabilities/hej/schemas/artifacts.yaml

@@ -0,0 +1,69 @@
+ARTIFACTS:
+  1:
+    id: A1
+    artifact_id: vision
+    local_role: consumes
+    description: >-
+      Hej reads this for the briefing's project context.
+  2:
+    id: A2
+    artifact_id: decisions
+    local_role: consumes
+    description: >-
+      Hej reads this to identify unresolved decisions requiring follow-up.
+  3:
+    id: A3
+    artifact_id: plan
+    local_role: consumes
+    description: >-
+      Hej reads this to identify the next executable task and plan progress.
+  4:
+    id: A4
+    artifact_id: progress
+    local_role: consumes
+    description: >-
+      Hej reads this for the briefing's "what shipped" context.
+  5:
+    id: A5
+    artifact_id: todo
+    local_role: consumes
+    description: >-
+      Hej reads this to identify high-severity open items for routing.
+  6:
+    id: A6
+    artifact_id: health
+    local_role: consumes
+    description: >-
+      Hej reads this for the health status line and attention items.
+  7:
+    id: A7
+    artifact_id: objective
+    local_role: consumes
+    description: >-
+      Hej reads this to check for active optimization objectives.
+  8:
+    id: A8
+    artifact_id: experiments
+    local_role: consumes
+    description: >-
+      Hej reads this alongside the active optimization target to determine
+      optimization status.
+  9:
+    id: A9
+    artifact_id: docs
+    local_role: consumes
+    description: >-
+      Hej reads this first to resolve project-local artifact mappings before
+      reading other artifacts.
+  10:
+    id: A10
+    artifact_id: design
+    local_role: consumes
+    description: >-
+      Hej reads this for the briefing's design status.
+  11:
+    id: A11
+    artifact_id: profile
+    local_role: consumes
+    description: >-
+      Hej reads this to report profile status (loaded/not found) in the briefing.

package/bundle/skills/agentera/capabilities/hej/schemas/exit.yaml

@@ -0,0 +1,32 @@
+EXIT_CONDITIONS:
+  1:
+    id: E1
+    condition: complete
+    description: >-
+      Briefing delivered (or welcome shown in fresh mode) and user
+      successfully routed to a capability. Normal successful exit.
+    exit_signal: complete
+  2:
+    id: E2
+    condition: flagged
+    description: >-
+      Briefing delivered but critical attention items were found: critical
+      issues, degrading health dimensions, or loop guard triggers. Each
+      concern is listed explicitly in the attention section.
+    exit_signal: flagged
+  3:
+    id: E3
+    condition: stuck
+    description: >-
+      Cannot orient. The working directory is not a code project, no
+      readable files exist, or permissions prevent scanning. The exit
+      marker explains what is blocking orientation.
+    exit_signal: stuck
+  4:
+    id: E4
+    condition: waiting
+    description: >-
+      Briefing or welcome delivered, concrete suggestion made, but awaiting
+      user input on which direction to take. The waiting bullet identifies
+      the specific decision or action the user needs to make.
+    exit_signal: waiting

package/bundle/skills/agentera/capabilities/hej/schemas/triggers.yaml

@@ -0,0 +1,58 @@
+TRIGGERS:
+  1:
+    id: T1
+    description: >-
+      Direct invocation by name or slash command. Matches when the user
+      explicitly requests hej.
+    priority: high
+    patterns:
+      - "hej"
+      - "/hej"
+  2:
+    id: T2
+    description: >-
+      Greetings and session-start signals. Matches casual greetings or
+      explicit session start requests.
+    priority: medium
+    patterns:
+      - "hello"
+      - "hi"
+      - "start"
+      - "begin"
+      - "getting started"
+      - "onboard me"
+  3:
+    id: T3
+    description: >-
+      Status and orientation requests. Matches when the user wants to know
+      the current state of the project or get a briefing.
+    priority: medium
+    patterns:
+      - "status"
+      - "dashboard"
+      - "pulse"
+      - "brief"
+      - "brief me"
+      - "update me"
+      - "what needs attention"
+  4:
+    id: T4
+    description: >-
+      Returning-to-project signals. Matches when the user resumes work
+      on a known project and wants to pick up where they left off.
+    priority: medium
+    patterns:
+      - "where were we"
+      - "catch me up"
+      - "what should I work on"
+      - "what's next"
+  5:
+    id: T5
+    description: >-
+      Fallback. Hej is the default capability when no other capability's
+      trigger patterns match. This entry documents the fallback behavior
+      defined in the routing layer routing logic.
+    patterns:
+      - "*"
+    fallback: true
+    priority: low

package/bundle/skills/agentera/capabilities/hej/schemas/validation.yaml

@@ -0,0 +1,55 @@
+VALIDATION:
+  1:
+    id: V1
+    rule: read_only
+    description: >-
+      Hej MUST NOT produce or modify any artifacts. It is strictly read-only.
+      All artifacts consumed by hej are produced by other capabilities.
+      This rule verifies that no artifact entry has produces: true.
+    severity: critical
+    checks:
+      - "No artifact entry has produces: true"
+  2:
+    id: V2
+    rule: briefing_completeness
+    description: >-
+      In returning mode, the briefing MUST include a status section (if any
+      artifacts exist), an attention section (if any issues exist), and a
+      concrete next-action suggestion with a named artifact item.
+      A skill name alone is not a valid suggestion.
+    severity: critical
+    checks:
+      - "Briefing contains at least one status line when artifacts exist"
+      - "Routing suggestion names a concrete artifact item"
+  3:
+    id: V3
+    rule: exit_marker_required
+    description: >-
+      Every hej invocation MUST emit an exit marker after the briefing or
+      welcome. The marker uses the canonical glyph ⌂ (SG1) in the format
+      ⌂ hej · <status> where status is one of EX1-EX4.
+    severity: critical
+    checks:
+      - "Exit marker present after closing code fence"
+      - "Exit marker uses glyph ⌂ (SG1)"
+      - "Exit marker status is one of complete, flagged, stuck, waiting"
+  4:
+    id: V4
+    rule: word_budget
+    description: >-
+      The briefing MUST be ≤120 words total. Each routing suggestion MUST be
+      ≤15 words. These constraints keep the briefing scannable and avoid
+      information overload.
+    severity: warning
+    checks:
+      - "Briefing word count ≤ 120"
+      - "Each routing suggestion ≤ 15 words"
+  5:
+    id: V5
+    rule: single_clarifying_question
+    description: >-
+      If the routing target is unclear, hej MUST ask exactly one clarifying
+      question. Compound questions are not allowed.
+    severity: critical
+    checks:
+      - "At most one clarifying question when routing is unclear"