agentera 0.0.0 → 3.0.0-dev.0

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

@@ -0,0 +1,113 @@
+VALIDATION:
+  1:
+    id: V1
+    rule: read_only_codebase
+    description: >-
+      Inspektera MUST NOT modify any source code files. It is a read-only
+      assessment capability. Other capabilities fix what inspektera finds.
+    severity: critical
+    checks:
+      - "No source code files are modified during audit"
+  2:
+    id: V2
+    rule: confidence_threshold
+    description: >-
+      Findings below 50 confidence (protocol: below CS3 range) MUST be
+      discarded. Findings in the 50-69 range (CS3) MUST be marked as "info"
+      (SF3) regardless of apparent severity. This prevents speculative
+      findings from being presented as definitive problems.
+    severity: critical
+    checks:
+      - "No finding has confidence below 50"
+      - "Findings with confidence 50-69 are severity info (SF3)"
+  3:
+    id: V3
+    rule: decisions_respected
+    description: >-
+      Findings that contradict deliberate decisions documented in DECISIONS.md
+      MUST be discarded or downgraded to info (SF3). A deliberate decision is
+      not a finding; it is an implementation of that decision.
+    severity: critical
+    checks:
+      - "No finding contradicts a known deliberate decision"
+  4:
+    id: V4
+    rule: no_duplicate_findings
+    description: >-
+      Issues already tracked in TODO.md MUST NOT be reported as new findings.
+      Known issues may be referenced for trajectory comparison but not
+      re-filed at their original severity.
+    severity: warning
+    checks:
+      - "No finding duplicates an existing TODO.md entry"
+  5:
+    id: V5
+    rule: user_confirmation_for_filing
+    description: >-
+      Findings MUST NOT be filed to TODO.md without explicit user confirmation.
+      Present the findings and ask; the user decides what to track.
+    severity: critical
+    checks:
+      - "TODO.md is only modified after user confirmation"
+  6:
+    id: V6
+    rule: exit_marker_required
+    description: >-
+      Every inspektera invocation MUST emit an exit marker. The marker uses
+      the canonical glyph ⛶ (SG3) in the format ⛶ inspektera · <status>
+      where status is one of EX1-EX4.
+    severity: critical
+    checks:
+      - "Exit marker present after audit"
+      - "Exit marker uses glyph ⛶ (SG3)"
+      - "Exit marker status is one of complete, flagged, stuck, waiting"
+  7:
+    id: V7
+    rule: evidence_context_first
+    description: >-
+      Inspektera evaluation startup MUST begin with `agentera prime --context
+      inspektera --format json` and use complete CLI `evidence_context` before
+      raw plan, progress, docs, health, TODO, or decisions artifacts.
+    severity: critical
+    checks:
+      - "Evidence context is requested through prime --context before raw artifacts"
+      - "Complete evidence_context is used for evaluation target, criteria, evidence, caveats, and residual risks"
+  8:
+    id: V8
+    rule: evidence_context_fallback_before_raw
+    description: >-
+      When evidence_context is absent, incomplete, or caveated for needed state,
+      Inspektera MUST run listed existing CLI fallback commands before any last-resort
+      raw artifact read.
+    severity: critical
+    checks:
+      - "evidence_context.fallback_commands are attempted before raw artifact reads"
+      - "capability_context.state.fallback_commands is used when evidence_context is unavailable"
+      - "Raw artifact reads are last-resort diagnostics, not normal evaluation startup"
+  9:
+    id: V9
+    rule: evidence_context_caveats_preserved
+    description: >-
+      Inspektera reports MUST preserve evidence_context caveats for stale app/profile
+      state, compacted decisions, protected-state boundaries, unavailable version or
+      publication evidence, manual-check states, and residual risks instead of hiding,
+      flattening, or reconstructing them.
+    severity: critical
+    checks:
+      - "state_family_caveats are preserved in evaluation results"
+      - "residual_risks.attributed_items are preserved with category, status, message, and provenance"
+      - "Compacted decision, protected-state, version, publication, remote, app, and profile caveats are not reconstructed or hidden"
+  10:
+    id: V10
+    rule: satisfaction_authority_boundary
+    description: >-
+      When Inspektera touches decision satisfaction, it may report 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/inspirera/instructions.md

@@ -0,0 +1,280 @@
+# INSPIRERA
+
+**Insight Navigation: Source Pattern Identification and Resonance. Evaluate, Reframe, Assimilate**
+
+Analyze an external resource and map its ideas to a target project. Output a structured markdown analysis the user can navigate and act on.
+
+Skill introduction: `─── ⬚ inspirera · analysis ───`
+
+---
+
+## Visual identity
+
+Glyph: **⬚** (protocol ref: SG10). Used in the mandatory exit marker.
+
+---
+
+## State artifacts
+
+No dedicated state file. Writes to other capabilities' artifacts.
+
+| Artifact | Purpose | Path |
+|----------|---------|------|
+| TODO.md | File actionable findings for realisera (severity per protocol SF1-SF3) | `TODO.md` (per DOCS.md mapping) |
+| VISION.md | Refine direction when inspiration shifts thinking | `VISION.md` (per DOCS.md mapping) |
+| PROFILE.md | Decision profile for persona-grounded applicability judgments | `$PROFILERA_PROFILE_DIR/PROFILE.md` (global, not project-scoped) |
+
+### 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 (TODO.md, VISION.md, etc.). 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 writes (TODO.md, VISION.md).
+
+PROFILE.md is global, not project-scoped. Its path is determined by profilera: `$PROFILERA_PROFILE_DIR/PROFILE.md` (default: `$XDG_DATA_HOME/agentera/PROFILE.md`). Check the profilera-determined path directly rather than falling back to the project root.
+
+### Contract values
+
+Contract values are inlined where referenced. Visual tokens from protocol: confidence tokens VT9-VT11 (━/─/┄), list item VT15 (▸), inline separator VT16 (·), section divider VT14. Skill glyph SG10 for exit markers. Exit signals EX1-EX4 for status reporting. Severity finding levels SF1-SF3 for TODO.md entries.
+
+`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.
+
+---
+
+Step markers: display `── step N/5: verb` before each step.
+Steps: identify, read, explore, map, deliver.
+
+---
+
+## Step 1: Identify source and target
+
+From the user's message, extract:
+
+- **Source**: the external URL (GitHub repo, article, docs, HN thread, etc.)
+- **Target**: the user's project, which could be any of:
+  - A **GitHub repo URL** → explore via the optional GitHub MCP integration
+  - A **local path** or project name → explore via filesystem tools
+  - The **current working directory** → if the user says "my project" / "what I'm building" without a URL, and they're clearly working in a project, treat cwd as the target
+  - **Absent** → if truly no target is implied, skip Steps 3–4 and do source-only analysis
+
+---
+
+## Step 2: Read the source
+
+This should feel like a colleague diving into something interesting, genuinely curious, reading deeply, forming opinions as you go. Not a report generator collecting data points.
+
+### GitHub repos
+
+Use the optional GitHub MCP integration to explore deeply:
+
+1. List root directory structure
+2. Read README
+3. Read key source directories until you understand: core abstractions, design patterns,
+   notable primitives, dependencies, clever approaches worth borrowing
+
+Go deep and don't stop at the README. If the optional GitHub MCP integration
+returns errors, fall back to public pages or note the limitation.
+
+### Articles, blog posts, docs pages
+
+Fetch full content. Extract core thesis, named concepts/patterns, code samples, and referenced tools. If paywalled, try reader-mode variant; if that fails, note the limitation.
+
+### Hacker News threads
+
+Read both the linked article and top comments. HN comments often contain the most useful distillation. Treat as signal.
+
+### Known libraries
+
+For well-known libraries, also check context7 for up-to-date docs beyond the README.
+
+Before proceeding to target analysis: in your response, list the 3-5 most transferable concepts from the source. These survive if the source file reads are cleared.
+
+---
+
+## Step 3: Read the target project
+
+Choose the exploration strategy based on the target type identified in Step 1.
+
+### Local projects (current directory or local path)
+
+Common case. Use filesystem tools (faster, includes uncommitted work):
+
+1. `Glob` to map the directory structure (e.g. `**/*.{ts,go,py,rs}`)
+2. Read README.md if one exists
+3. Check dependency manifests (`package.json`, `go.mod`, `Cargo.toml`, `pyproject.toml`, etc.)
+4. `Grep` for patterns, imports, or abstractions relevant to the source's concepts
+5. Read key source files to understand architecture and current patterns
+
+### Remote GitHub repos
+
+Use the optional GitHub MCP integration:
+
+1. List the root directory structure
+2. Read the README
+3. Read dependency manifests and key source files
+
+### Build understanding of
+
+Language, stack, dependencies, architecture, patterns, and problems being solved.
+
+### Check for existing usage
+
+Does the target already use the source (or a fork/alternative)?
+
+- **Already using**: "Getting the most out of it?" Focus on underused features and better patterns.
+- **Using alternative**: "Worth switching?" Compare approaches and migration cost.
+- **Not using**: "Should you adopt?" This is the default framing.
+
+---
+
+## Step 4: Map concepts across
+
+With both codebases understood, reason about applicability:
+
+- What is the source doing that the target should be?
+- Abstractions that simplify current complexity?
+- Patterns the target implements manually or poorly?
+- Primitives worth borrowing or adapting?
+- Source doing something the target does, but better?
+- Fundamentally incompatible? Say so clearly.
+- Adoption cost: one-file change or multi-sprint refactor?
+
+---
+
+## Step 5: Deliver the analysis
+
+The sharp colleague, here to share what you dug up, not file a report. Open with your take before the structured sections: what excited you, what surprised you, what the user should care about most. "Here's what I found and what matters for us." The structured analysis follows, but the human read comes first.
+
+Write a **structured markdown analysis**:
+
+### Output format
+
+````markdown
+# [Source Name] → [Target Name]: Cross-Pollination Analysis
+
+## TL;DR
+One or two sentences. Is this worth pursuing? What's the strongest single takeaway?
+
+## Source Overview
+Brief summary of what the source does and its core design philosophy.
+
+## Key Concepts
+
+### [Concept Name]
+What it is, why it's interesting, and concretely where/how it applies to the target.
+
+### [Concept Name]
+...repeat for each significant concept (typically 2–5)
+
+Reason through concept applicability in your response text. The Applicability Matrix below
+should contain only conclusions, not reasoning chains.
+Output constraint: ≤15 words per matrix cell.
+
+## Applicability Matrix
+
+| Concept | Relevance | Effort | Where in [Target] | Already Partially Done? |
+|---------|-----------|--------|-------------------|------------------------|
+| ...     | High/Med/Low | Low/Med/High | specific module or file | Yes/No |
+
+## What Doesn't Apply
+Honest assessment of concepts/patterns that look interesting but don't fit, and why.
+Being clear about what *not* to adopt is as valuable as the recommendations.
+
+## Recommended Next Steps
+▸ [action] · [specific file or module]
+▸ [action] · [specific file or module]
+Ordered by value/effort ratio.
+````
+
+**Tone**: direct, technically fluent. Skip empty sections. Lead with highest signal.
+
+Offer to go deeper: prototype a change, explore a concept with code, compare alternatives.
+
+### No target given
+
+Surface transferable concepts in general terms. Skip Applicability Matrix. Ask if the user wants to map to a specific project.
+
+---
+
+## Safety rails
+
+<critical>
+- NEVER modify code in the target project. Inspirera analyzes; other capabilities implement.
+- NEVER write to TODO.md or VISION.md without explicit user confirmation. Present findings and get approval before filing.
+- NEVER present shallow analysis as deep insight. If you haven't read the source thoroughly, say so.
+- NEVER recommend adoption without assessing fit. Every recommendation must consider the target project's constraints, stack, and principles.
+- NEVER fabricate source content. Quote actual code and text from the source.
+</critical>
+
+---
+
+## Exit signals
+
+Report one of these statuses at workflow completion (protocol refs: EX1-EX4).
+
+Format: emit `⬚ inspirera · <status>` on its own line, followed by a one-sentence summary. For `flagged` (EX2), `stuck` (EX3), and `waiting` (EX4), add a ▸ (VT15) bullet below the summary identifying what needs attention. The exit marker uses inspirera's canonical glyph ⬚ (SG10, U+2B1A).
+
+- **complete** (EX1): Source was read deeply, target project was explored (if provided), concept mapping was completed, and a structured analysis with applicability matrix and recommended next steps was delivered.
+- **flagged** (EX2): Analysis completed but with limitations worth surfacing: the source was paywalled or truncated, the target project was inaccessible, or key concepts could not be fully assessed for fit (e.g., incompatible language or paradigm).
+- **stuck** (EX3): Cannot proceed because the source URL is inaccessible and no fallback content is available, or the target project specified does not exist and cannot be located.
+- **waiting** (EX4): The source link was not provided or is malformed, or the target project is genuinely ambiguous and neither the current directory nor context resolves it.
+
+---
+
+## Cross-capability integration
+
+Inspirera is part of a twelve-capability suite. Its analysis feeds naturally into the other capabilities.
+
+### Feeding into realisera
+
+Add actionable findings to the project's TODO.md, classifying each by severity per protocol SF1-SF3. Or refine VISION.md's direction if the inspiration shifts thinking. The next realisera cycle picks up the changes automatically.
+
+### Feeding into optimera
+
+When the source contains optimization techniques (performance patterns, algorithm improvements, caching strategies), optimera's Hypothesize step can draw on the analysis for its next experiment.
+
+### Informed by profilera
+
+If a decision profile exists at `$PROFILERA_PROFILE_DIR/PROFILE.md`, read it directly and use effective confidence to weight applicability judgments. If PROFILE.md is missing, proceed without persona grounding.
+
+### Feeding into visionera
+
+When the analysis shifts thinking about the project's direction (a new paradigm, a competitor's approach, or a user need not yet captured), the findings can inform vision refinement. Suggest ⛥ visionera to revisit VISION.md with the new context.
+
+### Feeding into planera
+
+When the analysis recommends adopting patterns or libraries, planera can incorporate those recommendations into a plan's design section and task decomposition.
+
+### Feeding into resonera
+
+When the analysis surfaces recommendations that require deliberation (competing approaches, unclear adoption cost, or tradeoffs the user needs to resolve), suggest ❈ resonera to think it through before acting. Resonera can evaluate which recommendations are actually worth adopting and capture the reasoning in DECISIONS.md.
+
+---
+
+## Getting started
+
+### Analyze a GitHub repo
+
+```
+/agentera research https://github.com/org/repo
+```
+
+Reads the repo, maps its patterns to your current project.
+
+### Analyze an article or docs page
+
+```
+/agentera research https://example.com/blog/interesting-approach
+```
+
+Extracts transferable concepts and assesses applicability.
+
+### Feed findings into the development loop
+
+After analysis, file actionable findings to TODO.md for ⧉ realisera to pick up, or refine VISION.md if the research shifts your project's direction.
+
+---
+
+## Notes on depth vs. speed
+
+- Read more files, not fewer. Shallow reads produce shallow analysis.
+- Large repos: focus on modules most relevant to the concept, not everything.
+- Explore source and target concurrently where possible.
+- Always use the optional GitHub MCP integration for GitHub URLs.

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

@@ -0,0 +1,24 @@
+ARTIFACTS:
+  1:
+    id: A1
+    artifact_id: todo
+    local_role: produces
+    description: >-
+      Open problems by severity. Inspirera writes actionable findings here
+      (with user confirmation), classifying each by severity per protocol
+      SF1-SF3. Realisera picks up changes automatically in its next cycle.
+  2:
+    id: A2
+    artifact_id: vision
+    local_role: produces
+    description: >-
+      Inspirera may refine project direction with user confirmation when the
+      analysis shifts thinking about the project's direction.
+  3:
+    id: A3
+    artifact_id: profile
+    local_role: consumes
+    description: >-
+      Inspirera reads this via the effective profile script to weight
+      applicability judgments. If missing, inspirera proceeds without persona
+      grounding.

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

@@ -0,0 +1,33 @@
+EXIT_CONDITIONS:
+  1:
+    id: E1
+    condition: complete
+    description: >-
+      Source was read deeply, target project was explored (if provided),
+      concept mapping was completed, and a structured analysis with
+      applicability matrix and recommended next steps was delivered.
+    exit_signal: complete
+  2:
+    id: E2
+    condition: flagged
+    description: >-
+      Analysis completed but with limitations worth surfacing: the source
+      was paywalled or truncated, the target project was inaccessible, or
+      key concepts could not be fully assessed for fit.
+    exit_signal: flagged
+  3:
+    id: E3
+    condition: stuck
+    description: >-
+      Cannot proceed because the source URL is inaccessible and no fallback
+      content is available, or the target project specified does not exist
+      and cannot be located.
+    exit_signal: stuck
+  4:
+    id: E4
+    condition: waiting
+    description: >-
+      The source link was not provided or is malformed, or the target
+      project is genuinely ambiguous and neither the current directory
+      nor context resolves it.
+    exit_signal: waiting

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

@@ -0,0 +1,34 @@
+TRIGGERS:
+  1:
+    id: T1
+    description: >-
+      Direct invocation by name or slash command. Matches when the user
+      explicitly requests inspirera.
+    priority: high
+    patterns:
+      - "inspirera"
+      - "/inspirera"
+  2:
+    id: T2
+    description: >-
+      Applicability assessment requests. Matches when the user provides
+      an external URL and asks how it applies to their project or whether
+      they should adopt it.
+    priority: medium
+    patterns:
+      - "could I use this in"
+      - "how does this apply to my project"
+      - "is this relevant to"
+      - "what can I take from this"
+      - "should I adopt"
+  3:
+    id: T3
+    description: >-
+      External resource review requests. Matches when the user wants
+      analysis of a library, repo, or approach for ideas and patterns.
+    priority: medium
+    patterns:
+      - "what do you think of this library"
+      - "review this repo for ideas"
+      - "anything worth stealing from"
+      - "how does this compare to what I'm doing"

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

@@ -0,0 +1,58 @@
+VALIDATION:
+  1:
+    id: V1
+    rule: read_only_target
+    description: >-
+      Inspirera MUST NOT modify code in the target project. It analyzes
+      and maps concepts; other capabilities (realisera, optimera)
+      implement changes. The only writes are to TODO.md and VISION.md,
+      and only with explicit user confirmation.
+    severity: critical
+    checks:
+      - "No code modifications in target project"
+      - "TODO.md and VISION.md writes require user confirmation"
+  2:
+    id: V2
+    rule: source_depth
+    description: >-
+      The analysis MUST reflect deep reading of the source. Shallow
+      reads produce shallow analysis. If the source was not read
+      thoroughly (e.g., paywalled, truncated), the limitation must
+      be explicitly stated.
+    severity: critical
+    checks:
+      - "Analysis reflects actual source content"
+      - "Limitations are stated when source access is partial"
+  3:
+    id: V3
+    rule: fit_assessment
+    description: >-
+      Every recommendation MUST consider the target project's constraints,
+      stack, and principles. Recommendations without fit assessment are
+      not acceptable. Fundamentally incompatible patterns must be called
+      out explicitly.
+    severity: critical
+    checks:
+      - "Each recommendation considers target constraints"
+      - "Incompatible patterns are explicitly noted"
+  4:
+    id: V4
+    rule: no_fabrication
+    description: >-
+      Source content MUST be quoted from actual code and text. Fabricated
+      quotes or invented patterns are never acceptable.
+    severity: critical
+    checks:
+      - "All source quotes trace to actual content"
+      - "No invented patterns or concepts"
+  5:
+    id: V5
+    rule: matrix_constraint
+    description: >-
+      The Applicability Matrix cells MUST be ≤15 words each. The matrix
+      contains conclusions only, not reasoning chains. Reasoning belongs
+      in the response text before the matrix.
+    severity: warning
+    checks:
+      - "Matrix cells ≤ 15 words"
+      - "Reasoning in response text, not matrix cells"