agentera 0.0.0 → 3.0.0-dev.1

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,428 @@
+# DOKUMENTERA
+
+**Documentation Origin: Knowledge Unified, Methodology Enforced, Notation Traced. Encode, Record, Archive**
+
+Owns the docs-first workflow: document intended behavior before tests and code. Writes intent docs before code exists, generates docs for existing code, maintains docs as projects evolve, verifies docs against implementation.
+
+Two modes: **create** and **update**. Context-detected: no feature yet = intent-first; code exists = explore and generate.
+
+---
+
+## Visual identity
+
+Glyph: **▤** (protocol ref: SG8). Used in the mandatory exit marker.
+
+---
+
+## State artifacts
+
+One index file; writes individual doc files across the project.
+
+| Artifact | Purpose | Bootstrap |
+|----------|---------|-----------|
+| `DOCS.md` | Canonical documentation contract, stored as `.agentera/docs.yaml` unless mapped otherwise. Conventions, artifact mapping, and documentation index. | Created on first dokumentera run. |
+
+Use `agentera describe --format json` and its `artifact_schemas` entry for `docs` to locate the active installed schema; use `artifact_locations` or `agentera query --list-artifacts --format json` for mapped artifact paths and raw-access boundaries. Do not search Agentera directories manually. The repository's existing `.agentera/docs.yaml` shape provides the local structure when editing that artifact. Individual documentation files are written to their mapped locations.
+
+### Artifact path resolution
+
+Before reading or writing any artifact, prefer the CLI artifact-location contract from `agentera describe --format json` or `agentera query --list-artifacts --format json`. It resolves `.agentera/docs.yaml` mappings, default paths, existence, normal read commands, and raw-access boundaries without a separate raw docs read. Raw `.agentera/docs.yaml` access is reserved for writing or validating the docs artifact itself, corruption diagnostics, or unavailable/incomplete CLI discovery. This applies to all artifact references in this capability, including cross-capability reads (VISION.md, .agentera/progress.yaml, .agentera/decisions.yaml, .agentera/health.yaml).
+
+### Contract values
+
+Contract values are inlined where referenced. Visual tokens from protocol: severity arrows VT5-VT8, trend arrows VT12-VT13, progress bar VT18, inline separator VT16 (·), list item VT15 (▸), section divider VT14, flow/target VT17 (→). Skill glyph SG8 for the exit marker. Exit signals EX1-EX4 for the exit marker. Confidence scale CS1-CS5 for decision profile consumption.
+
+`references/contract.md` (at the v2 skill location `skills/agentera/references/contract.md`) remains available as a full-spec reference for ambiguous cases or cross-checking.
+
+---
+
+## docs.yaml shape
+
+```yaml
+last_audit: YYYY-MM-DD
+conventions:
+  doc_root: .
+  style: technical, concise
+  auto_gen: []
+  version_files: []
+  semver_policy:
+    feat: minor
+    fix: patch
+    docs/chore/test: no bump
+mapping:
+  - artifact: VISION.md
+    path: .agentera/vision.yaml
+    producers: [visionera, realisera]
+index:
+  - document: README
+    path: README.md
+    last_updated: YYYY-MM-DD
+    status: current
+```
+
+---
+
+## Step 0: Detect context
+
+Before artifact-backed work, use supported Agentera CLI state first. For final
+documentation or metadata synchronization, follow the closeout context startup
+contract below before reading TODO, docs, changelog, or progress artifacts directly.
+
+Determine what kind of documentation work is needed:
+
+1. Read DOCS.md (if exists) for current state
+2. Parse user request: specific target or broad "write/update docs"?
+3. Check codebase: does the feature exist in code?
+
+| Context | Approach |
+|---------|----------|
+| Feature doesn't exist yet, user wants to document intent | **Intent-first** (conversational) |
+| Code exists, docs don't | **Explore and generate** (autonomous) |
+| Docs exist, may be stale | **Update and verify** (audit-driven) |
+| Broad "audit the docs" / "are docs up to date" | **Full audit** |
+| No DOCS.md exists | **First-run survey** (convention detection) |
+
+---
+
+## Closeout context startup
+
+Closeout synchronization uses the existing state seam:
+
+```bash
+agentera prime --context dokumentera --format json
+```
+
+When the response includes `closeout_context.source_contract.complete_for_closeout_context: true`, use `closeout_context` as the normal source for:
+
+- artifact mappings
+- version policy
+- TODO blockers
+- changelog and release boundary state
+- progress evidence
+- benchmark evidence or unavailable caveat
+- fallback commands
+- state caveats
+- raw-read policy
+- completeness and non-empty evidence flags
+
+Do not raw-read `TODO.md`, `.agentera/docs.yaml`, `CHANGELOG.md`, or `.agentera/progress.yaml` merely to reconstruct those fields when the closeout context is complete. Raw artifacts are write targets or last-resort diagnostics, not normal closeout inputs.
+
+When closeout context is incomplete or caveated:
+
+1. Preserve every returned caveat, including stale app/profile state, compacted state, missing benchmark evidence, absent local tag/metadata, and no-publication/no-remote state.
+2. Run the listed `closeout_context.fallback_commands` before any raw artifact read. Expected existing fallbacks are `agentera todo --format json`, `agentera docs --format json`, `agentera progress --format json`, `agentera query changelog --format json`, `agentera query --list-artifacts --format json`, and `agentera decisions --format json` when listed.
+3. If fallback CLI state is still incomplete, raw reads may be used only as last-resort diagnostics or as explicit write targets after artifact path resolution.
+4. Never hide or reconstruct caveats while preparing docs, changelog, TODO, or progress closeout. Carry them into the final synchronization note.
+
+Closeout context does not approve publication, remote push, installed app refresh, profile refresh, vision edits, or objective-state edits. Treat those fields as recorded evidence or caveats only.
+
+### Decision satisfaction authority
+
+When documentation or closeout work touches decision satisfaction, agents may
+mark provisional satisfaction with evidence only. Dokumentera must not mark or
+imply user-confirmed final satisfaction; only the user confirms final
+satisfaction. If decisions are compacted, missing satisfaction state, open,
+provisional, or review-needed, preserve the caveat and review pressure in docs
+or closeout notes instead of reconstructing hidden outcomes or claiming
+automation proved intent.
+
+---
+
+## First-run survey (convention detection)
+
+When DOCS.md doesn't exist, run a survey first. Observe the project and propose a three-layer convention map for user approval.
+
+Step markers: display `── step N/5: verb` before each step.
+Steps: explore, propose, handle, audit, write.
+
+### Step 1: Explore structure
+
+Detect documentation conventions:
+
+1. **Doc root**: check docs/, doc/, documentation/, wiki/, or root. Default to root.
+2. **Existing docs**: README, CLAUDE.md, AGENTS.md, CONTRIBUTING.md, API docs, guides
+3. **Auto-generated docs**: TypeDoc, Storybook, OpenAPI/Swagger, GoDoc, Rustdoc, Javadoc. Record each with output path.
+4. **Style**: infer tone, structure patterns, formatting conventions from existing docs
+5. **Skill artifacts**: check `.agentera/docs.yaml` mappings, root human artifacts, and `.agentera/*.yaml` agent artifacts
+6. **Version files**: package.json, Cargo.toml, pyproject.toml, plugin.json, etc. Note files and current values. None found = omit versioning from DOCS.md.
+
+### Step 2: Propose conventions
+
+Draft three-layer `.agentera/docs.yaml` from the artifact schema and observed repository conventions:
+
+1. **Conventions**: doc_root, style, auto_gen from observations. If version files found, populate `version_files` and ask about semver policy. No version files = omit block.
+2. **Artifact mapping**: paths consistent with project's doc organization
+3. **Index**: all discovered docs (auto-generated = `generated`, existing = `current`)
+
+Present for user approval.
+
+### Step 3: Handle existing artifacts
+
+If artifacts exist at root but mapping places them elsewhere:
+
+1. List artifacts that would move
+2. Offer to relocate via `git mv`
+3. If declined, update mapping to match actual locations
+
+### Step 4: Pre-write self-audit
+
+Pre-write self-audit: run `agentera lint --artifact <ARTIFACT> --text "<DRAFT>"` (or `--file <PATH>`; schema names such as `decisions` auto-resolve the artifact file when no input is given) on the draft entry to check verbosity overruns (per-artifact budget), abstraction creep (>=1 concrete anchor), and filler accumulation (banned patterns).
+Max 3 revision attempts. Flag with [post-audit-flagged] if still failing.
+
+Narration voice (riff, don't script):
+
+- "Tightening this up..." · "Cutting the filler first..." · "One more pass..."
+
+### Step 5: Write DOCS.md
+
+Write the approved convention map to `.agentera/docs.yaml`. After writing, proceed to the originally requested mode, or stop if the survey was the entire request.
+
+Artifact writing follows contract Section 24 (Artifact Writing Conventions): banned verbosity patterns, 25-word sentence cap, preferred vocabulary, and lead-with-conclusion structure.
+
+---
+
+## Intent-first mode (docs before code)
+
+Docs-first workflow: document what a feature SHOULD do before building. Docs become the spec.
+
+Step markers: display `── step N/5: verb` before each step.
+Steps: understand, write, audit, update, suggest.
+
+### Step 1: Understand the intent
+
+Brief conversation (2-4 questions): what, who reads it, what format, what detail level.
+
+Read VISION.md for direction/audience and decision profile per protocol confidence scale (CS1-CS5) conventions for doc style preferences if they exist.
+
+### Step 2: Write the documentation
+
+Write docs in the appropriate location: project-level (README, CLAUDE.md) to standard paths, feature docs to the project's docs directory, inline docs to source files.
+
+**Principles**: follow DOCS.md style conventions, infer details from existing docs. Write as intended steady state (evergreen, non-temporal). Primary audience first. Concrete examples. DRY across doc files.
+
+When presenting drafts, introduce what you wrote and why: what choices you made, what you left out on purpose, what you'd want feedback on. Don't just dump the doc.
+
+Present draft for approval before writing.
+
+### Step 3: Pre-write self-audit
+
+Pre-write self-audit: run `agentera lint --artifact <ARTIFACT> --text "<DRAFT>"` (or `--file <PATH>`; schema names such as `decisions` auto-resolve the artifact file when no input is given) on the draft entry to check verbosity overruns (per-artifact budget), abstraction creep (>=1 concrete anchor), and filler accumulation (banned patterns).
+Max 3 revision attempts. Flag with [post-audit-flagged] if still failing.
+
+Narration voice (riff, don't script):
+
+- "Tightening this up..." · "Cutting the filler first..." · "One more pass..."
+
+### Step 4: Update DOCS.md
+
+Add or update the relevant entry in DOCS.md:
+
+- Document name and path
+- Date written
+- Status: `current`
+
+Output constraint: ≤15 words per index entry description.
+
+Artifact writing follows contract Section 24 (Artifact Writing Conventions): banned verbosity patterns, 25-word sentence cap, preferred vocabulary, and lead-with-conclusion structure.
+
+### Step 5: Suggest next steps
+
+- Feature docs: suggest ≡ planera to plan implementation
+- Standalone docs: suggest update mode later for verification
+
+---
+
+## Explore-and-generate mode (docs for existing code)
+
+Code exists, docs don't. Read codebase and generate.
+
+Step markers: display `── step N/5: verb` before each step.
+Steps: explore, gaps, generate, audit, update.
+
+### Step 1: Explore
+
+1. Map directory structure, read dependency manifests
+2. Read existing docs to see what's already documented
+3. Read key source files: architecture, public APIs, patterns
+4. Read VISION.md, PROGRESS.md, DECISIONS.md, decision profile if they exist; use `agentera decisions --format json` for normal decision context and carry returned `missing_fields`, `compacted`, `caveats`, and `satisfaction.review_needed` pressure into documentation scope instead of raw-reading missing historical decision context.
+5. `git log --oneline -20` for context
+
+**Exit-early stop condition**: If DOCS.md exists with coverage at 100% and no files have changed since the last dokumentera audit (`git log --since` the last audit date in DOCS.md shows no changes), report exit signal `complete` (EX1): documentation current, and stop.
+
+### Step 2: Identify gaps
+
+Compare what exists against what should be documented: README.md accuracy, CLAUDE.md/AGENTS.md presence, API docs, CLI docs with usage, configuration docs, architectural decision docs.
+
+### Step 3: Generate
+
+Write docs for gaps, prioritized: (1) README, (2) CLAUDE.md, (3) API/CLI docs, (4) architecture docs. Follow DOCS.md style conventions.
+
+When presenting drafts, introduce what you wrote and why: what you learned from the code, what design choices the doc reflects, what you're less sure about. Don't just dump the doc.
+
+Present drafts for approval.
+
+### Step 4: Pre-write self-audit
+
+Pre-write self-audit: run `agentera lint --artifact <ARTIFACT> --text "<DRAFT>"` (or `--file <PATH>`; schema names such as `decisions` auto-resolve the artifact file when no input is given) on the draft entry to check verbosity overruns (per-artifact budget), abstraction creep (>=1 concrete anchor), and filler accumulation (banned patterns).
+Max 3 revision attempts. Flag with [post-audit-flagged] if still failing.
+
+Narration voice (riff, don't script):
+
+- "Tightening this up..." · "Cutting the filler first..." · "One more pass..."
+
+### Step 5: Update DOCS.md
+
+Create or update DOCS.md with all items. Edit specific YAML entries when updating status/dates. If DOCS.md doesn't exist, run first-run survey first.
+
+Artifact writing follows contract Section 24 (Artifact Writing Conventions): banned verbosity patterns, 25-word sentence cap, preferred vocabulary, and lead-with-conclusion structure.
+
+---
+
+## Update-and-verify mode (audit-driven)
+
+Docs exist but may be out of sync with implementation.
+
+Step markers: display `── step N/6: verb` before each step.
+Steps: discover, verify, prose-enforce, report, audit, update.
+
+### Step 1: Discover
+
+Identify all doc files: root (README, CLAUDE.md, etc.), directories (docs/, .github/), config comments. Read DOCS.md for current index. Track auto-generated docs as `generated`. Skip node_modules/, .git/, vendor/.
+
+### Step 2: Verify
+
+Check each doc file on four dimensions:
+
+- **Gaps**: documented features/APIs/behaviors that don't exist in code
+- **Staleness**: changed signatures, removed features, outdated setup instructions
+- **Redundancies**: duplicated content across doc files
+- **Misalignments**: docs contradict actual code behavior
+
+For each finding: quote the doc section, reference code location (file:line), explain the discrepancy.
+
+### Step 3: Doc-prose enforcement
+
+Check all docs indexed in DOCS.md against the 3 self-audit rules:
+
+1. **Read DOCS.md index**: if DOCS.md is absent, run first-run survey to bootstrap it, then continue. Extract tracked docs from the `index` list. Skip entries with `generated` or `missing` status.
+2. **For each doc**, read the file and check against the 3 rules:
+   - **Verbosity overrun**: entry word counts exceeding token budgets for the artifact's scope. Flag entries that exceed budget without compaction.
+   - **Abstraction creep**: sections lacking ≥1 concrete anchor (file path, line number, commit hash, metric value, identifier, direct quote). Flag entries that narrate concepts without evidence.
+   - **Filler accumulation**: scan for banned verbosity patterns: meta-commentary about writing, hedging qualifiers, redundant transitions, self-referential process narration, filler introductions, summary preambles, excessive justification. Flag entries containing banned patterns.
+3. **Surface `[post-audit-flagged]` entries**: scan each doc for the `[post-audit-flagged]` marker. Report any flagged entries as warning-level findings.
+4. **Report findings** at standard severity levels:
+   - **critical** (SF1): doc section contradicts code, or instructions that would cause user errors
+   - **warning** (SF2): verbosity above budgets, abstraction creep, accumulated filler patterns, pre-existing `[post-audit-flagged]` markers
+   - **info** (SF3): minor style issues, single banned pattern in an otherwise clean entry
+
+### Step 4: Report and fix
+
+By severity: ⇶ critical (VT5, causes user errors), ⇉ warning (VT6, causes confusion), ⇢ info (VT8, cosmetic). For each finding, offer to: fix the doc, file to TODO.md (code is wrong per the docs-first workflow), or skip.
+
+### Step 5: Pre-write self-audit
+
+Pre-write self-audit: run `agentera lint --artifact <ARTIFACT> --text "<DRAFT>"` (or `--file <PATH>`; schema names such as `decisions` auto-resolve the artifact file when no input is given) on the draft entry to check verbosity overruns (per-artifact budget), abstraction creep (>=1 concrete anchor), and filler accumulation (banned patterns).
+Max 3 revision attempts. Flag with [post-audit-flagged] if still failing.
+
+Narration voice (riff, don't script):
+
+- "Tightening this up..." · "Cutting the filler first..." · "One more pass..."
+
+### Step 6: Update DOCS.md
+
+Update the index with:
+
+- ▸ Audit date
+- ▸ Status changes (■ current / ▣ stale / □ missing)
+- ▸ Coverage numbers
+- ▸ Audit log entry
+
+---
+
+## Safety rails
+
+<critical>
+- NEVER modify documentation without explicit user approval. Present drafts and get confirmation.
+- NEVER update docs to match broken code. Per the docs-first workflow, if code diverges from docs, the code is wrong. Document the divergence as an issue in TODO.md.
+- NEVER write temporal documentation (changelogs, "we recently added..."). Write as the intended steady state, evergreen and non-temporal.
+- NEVER duplicate information across doc files. Keep it DRY: reference, don't repeat.
+- NEVER write generic filler documentation. Every sentence should be specific to this project. If there's nothing useful to say about a section, omit it.
+- NEVER skip the verification step in update mode. Every doc claim must be checked against code.
+- NEVER auto-generate documentation without reading the code it describes. Understanding precedes documentation.
+</critical>
+
+---
+
+## Exit signals
+
+Report one of these statuses at workflow completion (protocol refs: EX1-EX4).
+
+Format: `▤ dokumentera · <status>` followed by a summary sentence.
+For flagged, stuck, and waiting: add `▸` (VT15) bullet details below the summary.
+
+- **complete** (EX1): Documentation was written, updated, or audited successfully; DOCS.md is current, and all drafted content received user approval before writing.
+- **flagged** (EX2): Documentation tasks completed but gaps remain (e.g., some doc files could not be verified against code, coverage is partial, or the audit found issues that were logged but not yet fixed).
+- **stuck** (EX3): Cannot proceed because a user approval step was declined, a required artifact (VISION.md, source code) is missing or inaccessible, or a contradicting doc-vs-code situation requires a decision the capability should not make autonomously.
+- **waiting** (EX4): The documentation intent is unclear: the target audience, format, or scope of what to document was not specified and cannot be inferred from the codebase or DOCS.md.
+
+---
+
+## Cross-capability integration
+
+Dokumentera is part of a twelve-capability suite. It is the documentation layer and owns the docs-first workflow.
+
+### Dokumentera feeds planera (docs-first workflow)
+
+In the strict docs-first workflow, dokumentera writes intent docs first, then planera breaks them into implementation tasks. The docs become the spec that planera's acceptance criteria verify against. When the plan includes documentation tasks, dokumentera handles them.
+
+### Dokumentera feeds realisera
+
+When dokumentera writes intent-first docs for a feature that doesn't exist yet, realisera implements code to match those docs. The docs are the target state; if code diverges from docs, the code is wrong per the docs-first workflow.
+
+### Dokumentera is informed by inspektera
+
+HEALTH.md findings may include documentation gaps. Inspektera's architecture alignment dimension can surface undocumented modules or APIs.
+
+### Dokumentera is informed by visionera
+
+VISION.md sets the project's direction and audience. Dokumentera reads it to understand who the documentation is for and what tone to use.
+
+### Dokumentera is informed by profilera
+
+The decision profile calibrates documentation style: the user's preferences for detail level, tone, format, and which docs they consider essential.
+
+### Dokumentera reads visualisera output
+
+DESIGN.md provides visual identity context that dokumentera respects when generating user-facing documentation, ensuring docs match the project's declared aesthetic and voice.
+
+### Dokumentera feeds profilera
+
+Documentation decisions (what to document, how, at what depth) are signal for profilera's extraction scripts.
+
+---
+
+## Getting started
+
+### Docs-first workflow: document before building
+
+1. ▤ dokumentera: write intent docs for the feature (what it should do, how it should work)
+2. ≡ planera: plan the implementation with acceptance criteria derived from the docs
+3. ⧉ realisera: build to match the docs
+4. ▤ dokumentera: update mode to verify docs still match implementation
+
+### Document existing code
+
+1. ▤ dokumentera: explore-and-generate mode reads the codebase and writes docs for what exists
+2. Review generated docs for accuracy and completeness
+
+### Audit and maintain
+
+1. ▤ dokumentera: update-and-verify mode checks all docs against code
+2. Fix findings or file code issues to TODO.md
+
+### Project bootstrap
+
+1. ⛥ visionera: create VISION.md (strategic direction)
+2. ▤ dokumentera: create README.md, CLAUDE.md, AGENTS.md (project documentation)
+3. ≡ planera: plan first features
+4. ⧉ realisera: start building

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

@@ -0,0 +1,73 @@
+ARTIFACTS:
+  1:
+    id: A1
+    artifact_id: docs
+    local_role: produces_and_consumes
+    description: >-
+      Documentation contract with conventions, artifact mapping, and
+      documentation index. Dokumentera writes and reads doc root, style
+      conventions, auto-generated doc tracking, project-local artifact mappings,
+      and a status index (current/stale/missing) for tracked docs. During
+      closeout, Dokumentera consumes docs state through CLI `closeout_context`
+      before raw artifact fallback.
+  2:
+    id: A2
+    artifact_id: vision
+    local_role: consumes
+    description: >-
+      Dokumentera reads this to understand who the documentation is for
+      and what tone to use.
+  3:
+    id: A3
+    artifact_id: progress
+    local_role: consumes
+    description: >-
+      Dokumentera reads this during explore-and-generate mode to understand
+      recent project context. During closeout, latest progress evidence and
+      verification pointers are consumed through CLI `closeout_context` before
+      raw artifact fallback.
+  4:
+    id: A4
+    artifact_id: decisions
+    local_role: consumes
+    description: >-
+      Dokumentera reads this during explore-and-generate mode for project
+      context and decision awareness.
+  5:
+    id: A5
+    artifact_id: health
+    local_role: consumes
+    description: >-
+      Dokumentera reads this to discover documentation gaps surfaced
+      during health audits.
+  6:
+    id: A6
+    artifact_id: todo
+    local_role: produces_and_consumes
+    description: >-
+      Dokumentera writes to this when code diverges from docs (per DTC,
+      the code is wrong). Also reads for context during documentation work;
+      closeout blocker state is consumed through CLI `closeout_context` before
+      raw artifact fallback.
+  7:
+    id: A7
+    artifact_id: design
+    local_role: consumes
+    description: >-
+      Dokumentera reads this to respect the declared aesthetic and voice
+      when generating user-facing documentation.
+  8:
+    id: A8
+    artifact_id: profile
+    local_role: consumes
+    description: >-
+      Dokumentera reads this to calibrate documentation style preferences:
+      detail level, tone, format.
+  9:
+    id: A9
+    artifact_id: changelog
+    local_role: consumes
+    description: >-
+      Dokumentera reads this during closeout synchronization through CLI
+      `closeout_context` to preserve the changelog boundary and avoid inventing
+      release, tag, publication, or remote state.

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

@@ -0,0 +1,35 @@
+EXIT_CONDITIONS:
+  1:
+    id: E1
+    condition: complete
+    description: >-
+      Documentation was written, updated, or audited successfully.
+      DOCS.md is current, and all drafted content received user
+      approval before writing.
+    exit_signal: complete
+  2:
+    id: E2
+    condition: flagged
+    description: >-
+      Documentation tasks completed but gaps remain. Possible causes:
+      some doc files could not be verified against code, coverage is
+      partial, or the audit found issues that were logged but not yet
+      fixed.
+    exit_signal: flagged
+  3:
+    id: E3
+    condition: stuck
+    description: >-
+      Cannot proceed because a user approval step was declined, a
+      required artifact (VISION.md, source code) is missing or
+      inaccessible, or a contradicting doc-vs-code situation requires
+      a decision the capability should not make autonomously.
+    exit_signal: stuck
+  4:
+    id: E4
+    condition: waiting
+    description: >-
+      The documentation intent is unclear: the target audience, format,
+      or scope of what to document was not specified and cannot be
+      inferred from the codebase or DOCS.md.
+    exit_signal: waiting

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

@@ -0,0 +1,35 @@
+TRIGGERS:
+  1:
+    id: T1
+    description: >-
+      Direct invocation by name or slash command. Matches when the user
+      explicitly requests dokumentera.
+    priority: high
+    patterns:
+      - "dokumentera"
+      - "/dokumentera"
+  2:
+    id: T2
+    description: >-
+      Documentation creation requests. Matches when the user wants to
+      write or create documentation, including DTC-first workflows.
+    priority: medium
+    patterns:
+      - "write docs"
+      - "document this"
+      - "create README"
+      - "write CLAUDE.md"
+      - "write AGENTS.md"
+      - "docs first"
+      - "document before building"
+  3:
+    id: T3
+    description: >-
+      Documentation maintenance and audit requests. Matches when the user
+      wants to update, check, or verify existing documentation.
+    priority: medium
+    patterns:
+      - "update the docs"
+      - "audit docs"
+      - "check documentation"
+      - "docs out of sync"