agentera 0.0.0 → 3.0.0-dev.1

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

@@ -0,0 +1,514 @@
+# INSPEKTERA
+
+**Integrity Navigation: Systematic Pattern Evaluation, Knowledge Tracing. Examine, Report, Advise.**
+
+Codebase health audit: multi-dimensional structural quality evaluation with evidence-based findings, confidence scores, and trajectory tracking. The retrospective counterpart to realisera's forward motion: is the codebase getting better or just bigger?
+
+Each invocation = one audit. Findings feed realisera's work selection via TODO.md. Skill introduction: `─── ⛶ inspektera · audit ───`
+
+---
+
+## Visual identity
+
+Glyph: **⛶** (protocol ref: SG3). Used in the mandatory exit marker.
+
+---
+
+## State artifacts
+
+One file in `.agentera/`, bootstrapped if absent.
+
+| File | Purpose | Bootstrap |
+|------|---------|-----------|
+| `HEALTH.md` | Canonical health artifact, stored as `.agentera/health.yaml` unless mapped otherwise. Findings, dimension grades, trajectory. | First audit entry in YAML form. |
+
+Use `agentera describe --format json` and its `artifact_schemas` entry for `health` to locate the active installed schema; do not search Agentera directories manually. Existing health artifacts provide repository-local examples of the shape.
+
+### Artifact path resolution
+
+Before reading or writing any artifact, check if `.agentera/docs.yaml` exists. If it has an Artifact Mapping section, use the path specified for each canonical filename. If `.agentera/docs.yaml` doesn't exist or has no mapping for a given artifact, use the default layout: TODO.md, CHANGELOG.md, and DESIGN.md at the project root; canonical VISION.md at `.agentera/vision.yaml`; other agent-facing artifacts at `.agentera/*.yaml`. This applies to all artifact references in this capability, including cross-capability reads (VISION.md, `.agentera/decisions.yaml`, TODO.md, `.agentera/progress.yaml`).
+
+### Contract
+
+Before starting, read `references/contract.md` (at v2 skill location `skills/agentera/references/contract.md`) for authoritative values: token budgets, severity levels, format contracts, and other shared conventions referenced in the steps below. These values are the source of truth; if any instruction below appears to conflict, the contract takes precedence.
+
+### health.yaml
+
+Open with your read on the codebase before the structured data: what's improving, what's sliding, what surprised you. 1-2 sentences of interpretation, then the grades and findings back it up. The colleague says what they think, then shows the evidence.
+
+```yaml
+audits:
+  - number: 1
+    date: YYYY-MM-DD
+    dimensions: [architecture_alignment, test_health]
+    findings_summary: "X critical, Y warnings, Z info"
+    overall: stable
+    dimension_grades:
+      - dimension: architecture_alignment
+        grade: B
+    findings:
+      - severity: degraded
+        title: Finding title
+        confidence: 80
+        location: file:line
+        evidence: What was observed.
+        impact: Why this matters.
+        suggested_action: Specific fix or investigation.
+    trends: What improved, degraded, or changed.
+    patterns_observed: De facto architecture patterns.
+```
+
+---
+
+Step markers: display `── step N/7: verb` before each step.
+Steps: orient, select, assess, distill, audit, report, connect.
+
+### Evidence context startup
+
+Before Step 1, start evaluation state gathering with:
+
+```bash
+agentera prime --context inspektera --format json
+```
+
+Use the returned `evidence_context` before raw plan, progress, docs, health, TODO, or decisions artifacts. If `evidence_context.source_contract.complete_for_evidence_context` is true, do not read raw PLAN, PROGRESS, DOCS, HEALTH, TODO, or DECISIONS artifacts merely to reconstruct evaluation target, plan criteria, progress verification, docs state, health state, TODO state, protected-state checks, version checks, residual risks, fallback commands, caveats, provenance, or non-empty evidence flags.
+
+If `evidence_context` is absent, incomplete, or caveated for a state family you need, run the listed `evidence_context.fallback_commands` first. If those are unavailable, use `capability_context.state.fallback_commands` from the same prime response. Raw artifact reads are last-resort diagnostics after listed CLI fallbacks, not normal evaluation startup behavior.
+
+Preserve caveats from `evidence_context.state_family_caveats`, `evidence_context.residual_risks.attributed_items`, `decision_context.caveats`, `protected_state_checks.caveats`, and `version_checks.caveats` when reporting evaluation results. Do not hide, flatten, or reconstruct stale app/profile state, compacted decisions, protected-state boundaries, unavailable version evidence, absent publication or remote evidence, manual-check states, or residual risks. These caveats calibrate confidence; they are not approval to refresh installed apps, refresh profile state, read or edit `.agentera/vision.yaml`, read or edit objective state, contact remotes or registries, or invent missing history.
+
+### Decision satisfaction authority
+
+When an audit touches decision satisfaction, agents may mark provisional
+satisfaction with evidence only. Inspektera must not mark, infer, or
+user-confirm 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 findings and residual
+risks instead of reconstructing hidden outcomes or claiming automation proved
+intent.
+
+## Step 1: Orient
+
+Use complete `evidence_context` first for the evaluated target, current plan criteria, latest progress verification, docs state, health state, TODO state, decision caveats, protected-state checks, version checks, and residual risks. Only run listed CLI fallbacks before raw artifact reads when the context is incomplete for the state needed.
+
+1. **Health state**: use `evidence_context.health_state` for prior audit findings, grades, current-state status, and caveats.
+2. **Protected-state boundary**: use `evidence_context.protected_state_checks` and preserve any not-checked-by-design caveats instead of reading protected state.
+3. **Decision context**: use `evidence_context.decision_context` for decision caveats. Findings contradicting deliberate decisions are not findings.
+4. **TODO state**: use `evidence_context.todo_state` for known problems. Don't re-report unless worsened.
+5. **Progress verification**: use `evidence_context.progress_verification` for recent-cycle verification and caveats.
+5b. **Change magnitude**: if CLI progress evidence exposes commit hashes from cycles since the last health audit timestamp, run `git log --stat` on those commits to estimate total change volume. If CLI progress evidence has no commit hashes, skip; default depth applies.
+5c. **Plan context** (for artifact current-state review): use `evidence_context.evaluation_target` and `evidence_context.plan_criteria` for the plan-relative baseline. If the evidence context reports no target, missing criteria, or missing current-state baseline, preserve that caveat; do not reconstruct it from raw plan state during normal startup.
+6. **Decision profile**: use profile/app caveats already attributed in `evidence_context.residual_risks`; stale or unavailable profile state calibrates confidence but is not approval to refresh profile state or read profile directly during startup.
+7. **Project discovery**: map directory structure, read dependency manifests, README, CLAUDE.md, AGENTS.md, identify language/stack/build commands, `git log --oneline -20`
+
+Before proceeding: in your response, list the key structural facts (module boundaries, dependency patterns, test coverage gaps) you observed. These survive context compaction.
+
+**Exit-early stop condition**: If `git diff` since the last `evidence_context.health_state` audit timestamp shows no file changes, report exit signal `complete: no changes since last audit` and stop.
+
+---
+
+## Step 2: Select dimensions
+
+Choose dimensions based on the codebase and user request. Not every dimension applies; a 200-line CLI doesn't need the same audit as a monorepo.
+
+### Available dimensions
+
+| Dimension | What it evaluates | When to include |
+|-----------|-------------------|-----------------|
+| **Architecture alignment** | Does the code match the stated architecture? Pattern mismatches, module boundary violations, layering breaks. | VISION.md or README describes architecture |
+| **Pattern consistency** | Are patterns used consistently? Naming, error handling, structure, abstractions. | Any codebase with 5+ modules or files |
+| **Coupling health** | Hidden dependencies, circular imports, god modules, inappropriate intimacy. | Any codebase with multiple modules |
+| **Complexity hotspots** | Functions too long, deeply nested, high fan-out, accumulated conditionals. | Any codebase |
+| **Test health** | Coverage gaps, test quality, test-to-code ratio, tests testing behavior vs implementation. | Project has tests |
+| **Dependency health** | Outdated deps, security advisories, unused deps, dep sprawl, pinning discipline. | Project has external dependencies |
+| **Version health** | Unreleased significant changes: `feat`/`fix` commits since the last version bump. | DOCS.md has a `versioning` convention block |
+| **Artifact freshness** | Are state artifacts current relative to plan activity or recent development? Protected health dimension label; current prose should call the work artifact current-state review. Detects artifacts that should have been updated but weren't. | Plan context available (PLAN.md with `Created` date) or PROGRESS.md has entries |
+| **Prose health** | Do artifact entries respect the writing rules? Checks verbosity overruns, abstraction creep, and filler accumulation across all project artifacts. | Project has 3+ artifact files |
+| **Security hygiene** | Hardcoded secrets, dangerous function calls, basic injection patterns. Lightweight regex-based scan, not a replacement for dedicated security tooling. | Any codebase |
+
+### Depth guidance
+
+When change magnitude was derived in Step 1, apply advisory depth scaling:
+
+- **Light changes** (roughly ≤5 files, ≤200 lines since last audit): prioritize dimensions most relevant to the changed areas. Skip dimensions with no intersection.
+- **Standard changes** (default): assess all applicable dimensions at normal depth.
+- **Heavy changes** (roughly ≥20 files or architectural-scope commits): assess all applicable dimensions and increase evidence collection depth. Read more files per dimension, trace more dependency paths, check more edge cases.
+
+These thresholds are guidelines, not hard rules. Use judgment: a 6-file change touching a critical security module warrants thorough depth, while a 25-file rename is light.
+
+**User specified dimensions**: audit only those.
+**Full audit or unspecified**: auto-select all applicable. Report selections before proceeding.
+
+---
+
+## Step 3: Assess
+
+Lead the assessment with your overall interpretation: what stands out, what's changed, where attention should go. Then the per-dimension breakdown provides the evidence.
+
+Launch parallel agents, one per dimension. Each receives the dimension definition, language-specific commands from `references/audit-commands.md` (at v2 skill location `skills/agentera/references/audit-commands.md`), relevant context files, the confidence scoring rubric, and instructions to return structured findings.
+
+**Before deep analysis**: run the quick checklist for a rapid pass/fail sweep. Dimensions passing all items can be audited at lower priority.
+
+```
+You are auditing the [dimension] health of [project].
+
+## What to evaluate
+[Dimension-specific instructions from below]
+
+## Evidence standard
+Every finding MUST include:
+- Specific file and line references
+- Quoted code showing the issue
+- Explanation of why it matters
+- Confidence score (0-100)
+
+## Presenting findings
+Introduce each finding conversationally before the structured evidence. The colleague
+says "hey, I noticed this" instead of just dumping a finding card. Lead with why it caught your eye and what it means, then back it up with the evidence block.
+
+## Confidence scoring (protocol: CS1-CS5)
+- 90-100 (CS1): Definitely a real issue. Verified by reading the code. Clear impact.
+- 70-89 (CS2): Very likely a real issue. Strong evidence, but some context might justify it.
+- 50-69 (CS3): Possibly an issue. The pattern is suspicious but could be intentional.
+- 30-49 (CS4): Uncertain. Might be an issue, might be a reasonable tradeoff.
+- 0-29 (CS5): Speculative. Flagging it but wouldn't be surprised if it's fine.
+
+## What is NOT a finding
+- Pre-existing patterns that are consistent and deliberate
+- Things a linter or type checker would catch (assume CI handles those)
+- Subjective style preferences not grounded in stated project principles
+- Known issues already tracked in TODO.md
+- Intentional decisions documented in DECISIONS.md
+```
+
+### Architecture alignment
+
+Compare codebase to stated architecture:
+
+- Read VISION.md (or README.md architecture section) for intended structure
+- Map actual module boundaries, dependency graph, data flow
+- Identify mismatches from stated architecture
+- Check layering and boundary cleanliness
+- Extract "Patterns Observed": de facto architecture independent of documentation
+
+No documented architecture? Extract and report de facto; note absence as a finding.
+
+### Pattern consistency
+
+Check consistency across the codebase:
+
+- Error handling (returns vs throws vs error types)
+- Naming (singular vs plural, prefixes, casing)
+- Module structure and layout similarity
+- Competing abstractions for the same concept
+- Duplicated logic that should be shared
+- Config handling (env vars vs files vs flags)
+
+Focus on inconsistencies between similar things, not whether the chosen pattern is "best."
+
+### Coupling health
+
+Evaluate coupling and dependency structure:
+
+- Map import graphs, identify circular dependencies
+- Find god modules (too many dependents or dependencies)
+- Check for inappropriate intimacy (reaching into internals)
+- Evaluate interface width: narrow boundaries or exposing everything?
+- Check hidden coupling via shared mutable state, global config, side effects
+
+Use language tools (`go list`, `madge`, import analysis). If unavailable, trace imports manually on highest-risk modules.
+
+### Complexity hotspots
+
+Find accumulating complexity:
+
+- Long functions (generally 50+ lines), deep nesting (3+ levels)
+- High fan-out, growing switch/match statements, many parameters (5+)
+- Files growing cycle over cycle (check git history)
+
+Prioritize high-change files: frequently modified + complex = high risk.
+
+### Test health
+
+Evaluate test suite quality and coverage:
+
+- Run coverage tools if available, otherwise estimate from file analysis
+- Identify critical paths with no coverage
+- Check: testing behavior or implementation? Excessive mocking? Brittle assertions?
+- Evaluate test naming: can you understand what failed from the name alone?
+- Check test-to-code ratio per major module
+- Check test proportionality against contract: default is one pass + one fail per testable unit. Flag under-testing and over-testing.
+
+Don't just report a number. Identify the *highest-risk* coverage gaps.
+
+### Dependency health
+
+Evaluate dependency management:
+
+- Outdated deps (package manager audit/outdated commands)
+- Known security vulnerabilities (npm audit, safety check, govulncheck)
+- Unused deps (installed but not imported)
+- Dep sprawl relative to project scope
+- Pinning discipline (pinned or floating?)
+- Vendored vs remote consistency
+
+### Version health
+
+Only run this dimension if DOCS.md exists and contains a `versioning` convention block. Skip entirely if the convention is absent.
+
+- Read DOCS.md `Conventions.versioning` to identify the version file(s) and bump trigger rules
+- Run `git log --oneline` to find `feat` and `fix` commits since the last modification date of the version file(s)
+- Count unbumped `feat`/`fix` commits and note the age of the oldest one
+- Severity: warning (SF2) if 1-4 unbumped commits or age ≤ 7 days; critical (SF1) if 5+ unbumped commits or age > 7 days
+- If no `feat`/`fix` commits have landed since the last bump, this dimension is healthy with no finding
+
+### Artifact current-state review
+
+Evaluates whether state artifacts are current relative to plan activity or recent development. The persisted health dimension label remains `Artifact freshness`; current prose should call the work artifact current-state review. Uses the staleness convention from contract.
+
+**With plan context** (PLAN.md has a created date and task execution history):
+
+- Read the plan's `Created` date from its HTML comment metadata
+- Identify which capabilities were dispatched during the plan by scanning task entries and PROGRESS.md cycle logs
+- For each dispatched capability, look up its expected artifacts in the contract staleness detection mapping
+- Check each expected artifact's last modification date: `git log -1 --format=%aI -- <path>`
+- An artifact is **stale** if its last modification predates the plan's creation date AND the capability that owns it was dispatched at least once during the plan
+- Severity: warning (SF2, confidence 70+). Plan-relative staleness carries causal evidence.
+- Artifacts that a capability reads but does not produce are not staleness candidates
+
+**Without plan context** (no PLAN.md, or PLAN.md has no created date):
+
+- Fall back to PROGRESS.md recency: an artifact is potentially stale if it was not modified since the most recent PROGRESS.md cycle entry date
+- If PROGRESS.md has no entries (fresh project), no staleness check applies
+- Severity: info (SF3, confidence 50-60). The fallback is advisory, not authoritative.
+
+**Handling**: stale artifact findings are reported like any other dimension finding but noted as context for the next plan cycle, not as blocking errors.
+
+### Prose health
+
+Evaluate artifact prose quality against the three Self-Audit Protocol rules. Use routine CLI state first for artifact-backed context, including `agentera decisions --format json` for DECISIONS.md. Preserve returned decision `missing_fields`, `compacted`, `caveats`, and `satisfaction.review_needed` pressure; raw decision artifact reads are for artifact-quality inspection, corruption diagnostics, or CLI defects, not normal post-CLI context recovery. Read all project artifacts (PROGRESS.md, DECISIONS.md, PLAN.md, HEALTH.md, TODO.md, CHANGELOG.md, VISION.md, DESIGN.md, DOCS.md) and check each entry when the prose-health audit explicitly requires raw artifact prose.
+
+**Rule 1: Verbosity overrun**: approximate word count per entry. Compare against per-entry budgets. Entries exceeding their budget by 50%+ are findings.
+
+**Rule 2: Abstraction creep**: scan each entry for ≥1 concrete anchor (file path with extension, line number, commit hash with 7+ hex chars, metric value with unit, identifier such as function/class/variable name, direct quote in quotes attributed to a source). Entries with zero concrete anchors are findings.
+
+**Rule 3: Filler accumulation**: scan each entry against banned verbosity patterns. Flag entries containing: meta-commentary about writing, hedging qualifiers, redundant transitions, self-referential process narration, filler introductions, summary preambles, excessive justification.
+
+### Security hygiene
+
+Lightweight regex-based scan for common security anti-patterns. This is a surface-level check, not a replacement for dedicated security analysis. Always recommend specialized tools for comprehensive coverage.
+
+**What to scan**:
+
+- **Hardcoded secrets**: API key patterns, password assignments, token strings in source, private keys in files
+- **Dangerous function calls**: `eval()` on variables or user input, `exec()` with string concatenation, subprocess/os.system with unsanitized input
+- **Basic injection patterns**: SQL string concatenation, unsanitized shell command construction
+
+**How to scan**: Use Grep with targeted patterns across the codebase. Focus on source files, not vendored dependencies, build artifacts, or lock files. Exclude `.git/`, `node_modules/`, `vendor/`, `__pycache__/`, and similar directories.
+
+**Severity assignment**:
+
+- Hardcoded secrets: warning (SF2, confidence 75-90)
+- Dangerous function calls: warning (SF2) or critical (SF1) depending on user input flow
+- Injection patterns: warning (SF2, confidence 60-80)
+
+**Scope limitation notice**: every security hygiene finding MUST include a footer recommending dedicated security tools for comprehensive analysis.
+
+---
+
+## Step 4: Distill
+
+After all agents complete:
+
+1. **Filter**: discard findings below 50 confidence. Mark 50-69 as "info" (SF3) regardless of apparent severity.
+2. **Deduplicate**: merge by preference: (1) fullest context, (2) most evidence-rich dimension, (3) most recent. Preserve complementary evidence from discarded findings.
+3. **Cross-reference** against DECISIONS.md and TODO.md using `agentera decisions --format json` for normal decision context:
+   - Matches known decision → discard or downgrade to info (SF3)
+   - Matches known issue → "already tracked", skip
+   - Genuinely new → include at full severity
+4. **Grade** each dimension:
+   - **A**: No critical/warning findings. **B**: No critical, some warnings.
+   - **C**: 1-2 critical or many warnings. **D**: Multiple critical.
+   - **F**: Pervasive critical findings.
+5. **Trajectory**: compare to prior HEALTH.md: improved (VT12), degraded (VT13), stable dimensions. Calculate overall trajectory.
+
+---
+
+## 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 table).
+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: Report
+
+Assess each dimension in your response. Write ONLY grade, trajectory marker, and finding summary per dimension to HEALTH.md. No reasoning in the artifact; the conversation preserves analysis, the artifact preserves conclusions.
+
+Output constraint per contract token budgets. Letter grade + ≤3 sentences justification per dimension.
+
+When updating existing HEALTH.md entries (e.g., updating patterns observed), edit the specific YAML entry rather than rewriting unrelated history. Append new audit entries.
+
+Write the audit results to `HEALTH.md` using its resolved YAML path (append new audit, keep prior audits for trajectory history) and present to the user.
+
+After writing a new audit entry to HEALTH.md, apply the schema COMPACTION rules before writing if thresholds are exceeded: keep 10 full audits, keep up to 40 one-line archive entries, and drop beyond 50 total.
+
+Artifact writing follows contract Artifact Writing Conventions: banned verbosity patterns, 25-word sentence cap, preferred vocabulary, and lead-with-conclusion structure.
+
+### Report structure
+
+```markdown
+## Audit N · YYYY-MM-DD
+
+**Dimensions assessed**: [list]
+**Findings**: X critical, Y warnings, Z info (N filtered by confidence)
+**Overall trajectory**: ⮉ improving | stable | ⮋ degrading vs Audit N-1
+**Grades**: Architecture [B] | Patterns [A] | Coupling [C] | Complexity [B] | Tests [D] | Deps [A] | Security [A]
+
+### [Dimension Name]: [Grade]
+
+#### ⇶ [Finding title], critical (confidence: N/100)
+#### ⇉ [Finding title], warning (confidence: N/100)
+#### ⇢ [Finding title], info (confidence: N/100)
+- **Location**: `file:line` (or module/package)
+- **Evidence**: [quoted code or structural observation]
+- **Impact**: [what breaks, degrades, or risks]
+- **Suggested action**: [specific fix, investigation, or refactor]
+
+[Repeat for each finding, ordered by severity then confidence]
+
+### Trends vs Audit N-1
+- **Improved**: [what got better and why]
+- **Degraded**: [what got worse and why]
+- **New findings**: [issues not present in prior audit]
+- **Resolved**: [prior findings no longer present]
+
+### Patterns Observed
+[De facto architecture patterns extracted, the "what IS" independent of what's stated.]
+- Module structure: [how code is organized]
+- Error handling: [predominant pattern]
+- Testing approach: [how tests are structured]
+- Dependency patterns: [how deps are managed]
+```
+
+---
+
+## Step 7: Connect
+
+Feed actionable findings into the suite:
+
+1. **TODO.md**: for each critical finding not already tracked, offer to add under the appropriate severity section.
+   Severity mapping (protocol: SM1-SM3): critical (SF1) → `## ⇶ Critical` (SI1), warning (SF2) → `## ⇉ Degraded` (SI2), info (SF3) → `## ⇢ Annoying` (SI4). Each entry is a checkbox line: `- [ ] [finding description]`. Get user confirmation before writing.
+   Output constraint per contract token budgets.
+2. **VISION.md**: if architecture has intentionally evolved past stated architecture, suggest updating via ❈ resonera.
+3. **Present findings** and ask if the user wants to: file to TODO.md, deliberate via ❈ resonera, deep-dive on a dimension, or investigate a specific finding.
+
+---
+
+## Safety rails
+
+<critical>
+
+- NEVER modify code. Inspektera audits; other capabilities fix.
+- NEVER file issues to TODO.md without explicit user confirmation.
+- NEVER present speculative findings (confidence < 50) as definitive problems.
+- NEVER ignore DECISIONS.md context. If a finding contradicts a deliberate decision,
+  it is not a finding but an implementation of that decision. Discard or downgrade.
+- NEVER report known issues already tracked in TODO.md as new findings.
+- NEVER flag subjective style preferences as findings unless they violate stated principles
+  in VISION.md, CLAUDE.md, or the decision profile.
+- NEVER run destructive commands or install packages. Read-only assessment.
+
+</critical>
+
+---
+
+## Exit signals
+
+Report one of these statuses at workflow completion (protocol refs: EX1-EX4).
+
+Format: `─── ⛶ inspektera · status ───` followed by a summary sentence.
+For flagged, stuck, and waiting: add `▸` bullet details below the summary.
+
+- **complete** (EX1): All selected audit dimensions were assessed, findings were synthesized, grades were assigned, HEALTH.md was updated, and the user was presented with actionable results.
+- **flagged** (EX2): The audit completed but with notable caveats: one or more dimensions had to be skipped due to missing tooling, confidence was too low to grade a dimension reliably, or critical findings were discovered that require urgent attention beyond the audit scope.
+- **stuck** (EX3): Cannot complete the audit because the project is inaccessible, required language tooling is unavailable and manual analysis is not feasible, or filing findings to TODO.md was declined by the user and the results cannot be safely surfaced any other way.
+- **waiting** (EX4): The audit target is ambiguous: no project was identified, the codebase is too incomplete to assess meaningfully, or the user's request specifies dimensions that cannot be evaluated without additional information.
+
+---
+
+## Cross-capability integration
+
+Inspektera is part of a twelve-capability suite. It is the feedback loop, the capability that tells realisera whether its work is making things better.
+
+### Inspektera feeds ⧉ realisera
+
+Critical and warning findings filed to TODO.md become candidates for realisera's work selection. The severity mapping ensures structural problems compete fairly with feature work. The "Patterns Observed" section helps realisera understand the codebase's de facto architecture when planning changes.
+
+### Inspektera feeds ❈ resonera
+
+When the audit reveals an architecture mismatch, suggest ❈ resonera before fixes begin.
+
+Use it when code has moved past stated architecture or competing patterns need a decision.
+
+### Inspektera feeds ≡ planera
+
+When the audit reveals multiple related structural issues, suggest ≡ planera to create a remediation plan. The plan's acceptance criteria give inspektera concrete targets to verify in the next audit.
+
+### Inspektera feeds ⎘ optimera
+
+When a dimension grade is poor and the improvement is measurable (test coverage, dependency count, complexity score), the finding can become an optimization objective. Suggest ⎘ optimera when the metric and direction are clear.
+
+### Inspektera reads ⧉ realisera output
+
+PROGRESS.md tells inspektera what was built recently. Recent changes are higher-priority audit targets because they're the most likely source of regressions or pattern breaks. Cycle count since last audit signals when a health check is overdue.
+
+### Inspektera reads ❈ resonera output
+
+DECISIONS.md explains why things are the way they are. Findings that contradict deliberate decisions are not findings. This prevents inspektera from flagging intentional tradeoffs as problems.
+
+### Inspektera reads ◰ visualisera output
+
+DESIGN.md provides visual identity constraints that inspektera can audit for consistency, checking whether the codebase respects the declared design tokens and patterns.
+
+### Inspektera is informed by ♾ profilera
+
+The decision profile calibrates what "healthy" means for this user. A user who values simplicity over flexibility will have different complexity thresholds than one who values extensibility. High-confidence quality preferences from the profile weight the grading.
+
+---
+
+## Getting started
+
+### First audit
+
+1. `/agentera audit`: runs a full audit across all applicable dimensions, bootstraps HEALTH.md
+2. Review findings, file critical ones to TODO.md
+3. `/agentera build`: next cycle picks up the filed issues and starts fixing
+
+### Periodic health checks
+
+Run ⛶ inspektera every 5-10 realisera cycles, or when:
+
+- A major feature was added
+- Significant refactoring occurred
+- The codebase "feels" harder to work in
+- Before a major architectural decision (to understand current state)
+
+Hej mirrors this cadence through hybrid audit staleness: `agentera hej` marks a health audit stale when days since the latest audit date reach `AGENTERA_INSPEKTERA_MAX_AGE_DAYS` (default 30) or progress cycles after that audit date reach `AGENTERA_INSPEKTERA_MAX_CYCLES` (default 10). Either axis exceeding its threshold is enough; when progress is absent, time-only evaluation still applies.
+
+### Targeted audits
+
+```
+/agentera audit architecture coupling
+```
+
+Specify dimensions to narrow the audit scope. Useful after specific kinds of changes.
+
+### After an audit
+
+- **Good grades (A/B)**: Celebrate. Keep building.
+- **Mixed grades (C)**: File the critical findings, deliberate on the warnings.
+- **Poor grades (D/F)**: Consider pausing feature work. Use ❈ resonera to deliberate on priorities, then ⧉ realisera to fix the structural problems before building more.

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

@@ -0,0 +1,76 @@
+ARTIFACTS:
+  1:
+    id: A1
+    artifact_id: health
+    local_role: produces_and_consumes
+    description: >-
+      Codebase health assessment with findings, dimension grades, and trajectory.
+      Inspektera writes audit entries with per-dimension grades, findings with
+      severity and confidence scores, trend comparisons, and de facto
+      architecture patterns. During evaluation startup, Inspektera consumes health
+      state through CLI `evidence_context` before raw health artifact fallback.
+  2:
+    id: A2
+    artifact_id: vision
+    local_role: consumes
+    description: >-
+      Inspektera treats vision state as protected during evidence-context startup;
+      missing or not-checked vision caveats from CLI `evidence_context` are preserved
+      instead of forcing a raw vision read.
+  3:
+    id: A3
+    artifact_id: decisions
+    local_role: consumes
+    description: >-
+      Inspektera consumes decision caveats through CLI `evidence_context` and the
+      listed `agentera decisions --format json` fallback before raw decisions artifact fallback.
+      Compacted decision caveats must be preserved rather than reconstructed.
+  4:
+    id: A4
+    artifact_id: todo
+    local_role: produces_and_consumes
+    description: >-
+      Inspektera reads this to avoid re-reporting known issues and writes to it
+      with user confirmation when filing
+      critical and warning findings. During evaluation startup, known TODO state is
+      consumed through CLI `evidence_context` before raw TODO artifact fallback.
+  5:
+    id: A5
+    artifact_id: progress
+    local_role: consumes
+    description: >-
+      Inspektera consumes latest progress verification and progress caveats through
+      CLI `evidence_context` before raw progress artifact fallback.
+  6:
+    id: A6
+    artifact_id: plan
+    local_role: consumes
+    description: >-
+      Inspektera consumes evaluation target and plan criteria through CLI
+      `evidence_context` before raw plan artifact fallback. The plan's Created date
+      still provides the artifact-current-state baseline when that state is needed.
+  7:
+    id: A7
+    artifact_id: design
+    local_role: consumes
+    description: >-
+      Inspektera treats design state as optional during evidence-context startup;
+      missing design caveats from CLI `evidence_context` are preserved before any raw
+      design artifact fallback.
+  8:
+    id: A8
+    artifact_id: docs
+    local_role: consumes
+    description: >-
+      Inspektera reads this first to resolve project-local artifact mappings
+      and checks the versioning convention for the version health dimension. During
+      evaluation startup, docs state and version-boundary caveats are consumed through
+      CLI `evidence_context` before raw docs artifact fallback.
+  9:
+    id: A9
+    artifact_id: profile
+    local_role: consumes
+    description: >-
+      Inspektera consumes profile status and stale-profile caveats through CLI
+      `evidence_context`; stale or missing profile state is preserved as a caveat and
+      is not approval to refresh profile state or read profile directly during startup.

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

@@ -0,0 +1,36 @@
+EXIT_CONDITIONS:
+  1:
+    id: E1
+    condition: complete
+    description: >-
+      All selected audit dimensions were assessed, findings were synthesized,
+      grades were assigned, HEALTH.md was updated, and the user was presented
+      with actionable results.
+    exit_signal: complete
+  2:
+    id: E2
+    condition: flagged
+    description: >-
+      The audit completed but with notable caveats: dimensions were skipped
+      due to missing tooling, confidence was too low to grade reliably, or
+      critical findings require urgent attention beyond audit scope.
+      Each concern is listed explicitly.
+    exit_signal: flagged
+  3:
+    id: E3
+    condition: stuck
+    description: >-
+      Cannot complete the audit because the project is inaccessible, required
+      language tooling is unavailable and manual analysis is not feasible, or
+      filing findings to TODO.md was declined by the user and results cannot
+      be safely surfaced any other way.
+    exit_signal: stuck
+  4:
+    id: E4
+    condition: waiting
+    description: >-
+      The audit target is ambiguous: no project was identified, the codebase
+      is too incomplete to assess meaningfully, or the user's request
+      specifies dimensions that cannot be evaluated without additional
+      information.
+    exit_signal: waiting

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

@@ -0,0 +1,38 @@
+TRIGGERS:
+  1:
+    id: T1
+    description: >-
+      Direct invocation by name or slash command. Matches when the user
+      explicitly requests inspektera.
+    priority: high
+    patterns:
+      - "inspektera"
+      - "/inspektera"
+  2:
+    id: T2
+    description: >-
+      Audit and codebase health requests. Matches when the user wants to
+      assess codebase health, architecture quality, or structural integrity.
+    priority: medium
+    patterns:
+      - "audit the codebase"
+      - "check code health"
+      - "architecture review"
+      - "find technical debt"
+      - "assess code quality"
+      - "how healthy is this codebase"
+      - "what needs fixing"
+      - "structural review"
+      - "pattern audit"
+      - "dependency check"
+      - "test coverage audit"
+  3:
+    id: T3
+    description: >-
+      Implicit trigger after extended realisera activity. Matches when
+      realisera has run 5+ cycles without a health check and the system
+      detects an overdue audit.
+    priority: medium
+    patterns:
+      - "health check overdue"
+      - "audit after realisera"