loreli 0.0.0 → 1.0.0

package/packages/marker/src/index.js

@@ -0,0 +1,184 @@
+/**
+ * Loreli marker system — machine-readable HTML comment metadata for GitHub content.
+ *
+ * Marker format: `<!-- loreli:TYPE key="value" key="value" -->`
+ *
+ * Decouples workflow-state detection from human-visible text so themed
+ * messages can change freely without breaking parsing logic.
+ *
+ * @module loreli/marker
+ */
+
+const PREFIX = 'loreli';
+
+/**
+ * HTML-entity-encode a marker value so `"`, `&`, `<`, and `>` are safe
+ * inside the `key="value"` format within an HTML comment.
+ *
+ * @param {string} value - Raw value string.
+ * @returns {string} Encoded value (no literal `"`, `&`, `<`, or `>`).
+ */
+function encode(value) {
+  return value
+    .replaceAll('&', '&amp;')
+    .replaceAll('"', '&quot;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;');
+}
+
+/**
+ * Decode HTML entities produced by {@link encode} back to raw characters.
+ *
+ * @param {string} value - Encoded value string.
+ * @returns {string} Original value with entities resolved.
+ */
+function decode(value) {
+  return value
+    .replaceAll('&quot;', '"')
+    .replaceAll('&lt;', '<')
+    .replaceAll('&gt;', '>')
+    .replaceAll('&amp;', '&');
+}
+
+/**
+ * Matches a loreli marker with a specific type.
+ * Capture group 1: the key-value payload (may be empty).
+ *
+ * @param {string} type - Marker type to target.
+ * @returns {RegExp}
+ */
+function regex(type) {
+  return new RegExp(`<!-- ${PREFIX}:${type}((?:\\s+\\w+="[^"]*")*) -->`);
+}
+
+/**
+ * Parses `key="value"` pairs from the raw payload string captured by {@link regex}.
+ * Values are HTML-entity-decoded so callers receive the original strings.
+ *
+ * @param {string} raw - Space-separated key="value" string.
+ * @returns {Object<string, string>}
+ */
+function pairs(raw) {
+  const data = {};
+  const re = /(\w+)="([^"]*)"/g;
+  let m;
+  while ((m = re.exec(raw)) !== null) data[m[1]] = decode(m[2]);
+  return data;
+}
+
+/**
+ * Produces a loreli marker string. Values are HTML-entity-encoded so
+ * special characters (`"`, `&`, `<`, `>`) do not break the marker format
+ * or prematurely close the HTML comment.
+ *
+ * @param {string} type - Marker type (e.g. 'claim', 'signature', 'agent').
+ * @param {Object<string, string>} [data] - Key-value pairs to embed.
+ * @returns {string} An HTML comment marker.
+ * @throws {Error} If type is falsy or empty.
+ */
+export function mark(type, data) {
+  if (!type) throw new Error('type is required');
+
+  const entries = Object.entries(data ?? {});
+  const payload = entries.length
+    ? ' ' + entries.map(function pair([k, v]) { return `${k}="${encode(v)}"`; }).join(' ')
+    : '';
+
+  return `<!-- ${PREFIX}:${type}${payload} -->`;
+}
+
+/**
+ * Checks whether a body contains a marker of the given type.
+ *
+ * @param {string | null | undefined} body - GitHub comment/PR/discussion body.
+ * @param {string} type - Marker type to look for.
+ * @returns {boolean}
+ */
+export function has(body, type) {
+  if (!body) return false;
+  return regex(type).test(body);
+}
+
+/**
+ * Extracts the key-value data from the first marker of the given type.
+ *
+ * @param {string | null | undefined} body - GitHub comment/PR/discussion body.
+ * @param {string} type - Marker type to extract.
+ * @returns {Object<string, string> | null} Parsed data, or null if not found.
+ */
+export function parse(body, type) {
+  if (!body) return null;
+  const m = body.match(regex(type));
+  if (!m) return null;
+  return pairs(m[1]);
+}
+
+/**
+ * Removes the first marker of the given type and everything after it,
+ * trimming trailing whitespace from the remaining content.
+ *
+ * @param {string | null | undefined} body - GitHub comment/PR/discussion body.
+ * @param {string} type - Marker type to strip from.
+ * @returns {string | null | undefined} Body with marker and trailing content removed.
+ */
+export function strip(body, type) {
+  if (body == null || body === '') return body;
+  const idx = body.search(regex(type));
+  if (idx === -1) return body;
+  return body.slice(0, idx).trimEnd();
+}
+
+/**
+ * Removes the last marker of the given type and everything after it,
+ * trimming trailing whitespace from the remaining content.
+ *
+ * Use when multiple markers exist and only the trailing one should be
+ * removed (e.g. duplicate signatures at end of body).
+ *
+ * @param {string | null | undefined} body - GitHub comment/PR/discussion body.
+ * @param {string} type - Marker type to strip from.
+ * @returns {string | null | undefined} Body with last marker and trailing content removed.
+ */
+export function stripLast(body, type) {
+  if (body == null || body === '') return body;
+  const re = new RegExp(regex(type).source, 'g');
+  let lastIdx = -1;
+  let m;
+  while ((m = re.exec(body)) !== null) lastIdx = m.index;
+  if (lastIdx === -1) return body;
+  return body.slice(0, lastIdx).trimEnd();
+}
+
+/**
+ * Removes content between paired markers of the given type.
+ *
+ * Finds the opening `<!-- loreli:TYPE ... -->` and the closing
+ * `<!-- loreli:TYPE-end -->`, removes both markers and everything
+ * between them, and collapses extra blank lines at the join point.
+ *
+ * Unlike {@link strip}, which removes a marker and everything after it,
+ * `excise` removes only the delimited section and preserves content on
+ * both sides. Designed for trace blocks and other self-contained sections
+ * embedded within larger bodies.
+ *
+ * @param {string | null | undefined} body - GitHub comment/PR/discussion body.
+ * @param {string} type - Marker type to excise (matches TYPE and TYPE-end).
+ * @returns {string | null | undefined} Body with the marker-delimited section removed.
+ */
+export function excise(body, type) {
+  if (body == null || body === '') return body;
+  const startIdx = body.search(regex(type));
+  if (startIdx === -1) return body;
+
+  const endMarker = new RegExp(`<!-- ${PREFIX}:${type}-end -->`);
+  const after = body.slice(startIdx);
+  const endMatch = endMarker.exec(after);
+  if (!endMatch) return body;
+
+  const endIdx = startIdx + endMatch.index + endMatch[0].length;
+  const before = body.slice(0, startIdx);
+  const rest = body.slice(endIdx);
+
+  // Collapse extra blank lines at the join point
+  return (before.replace(/\n+$/, '') + rest.replace(/^\n+/, '\n')).trim();
+}

package/packages/mcp/README.md

@@ -0,0 +1,279 @@
+# loreli/mcp
+
+MCP server for agentic team orchestration via GitHub. Exposes orchestration tools, manages agent lifecycle, and provides a CLI entry point.
+
+## Quick Start
+
+Run this command to start the MCP server over stdio when you want to connect a client directly; the process should stay running and wait for MCP messages.
+
+```bash
+loreli mcp
+```
+
+Before using the CLI tool commands below, configure an MCP server entry named `loreli` in your client or global config (for example `~/.cursor/mcp.json`, `~/.claude/.mcp.json`, or `~/.codex/config.toml`). This matters because the CLI resolves tool invocations through that server entry, and without it the commands will fail. When configured correctly, you should see the tool list printed and each command should execute successfully.
+
+```bash
+loreli tools list
+loreli tools start --repo owner/repo
+loreli tools team_status
+loreli tools agents --action check
+```
+
+All MCP tools are automatically available as CLI commands through `@mcp-layer/cli` once the `loreli` MCP server entry is configured. Run `loreli --help` for the full list.
+
+## API Reference
+
+### `Loreli` Class
+
+The main server class following the uprising start pattern.
+
+```js
+import { Loreli } from 'loreli/mcp';
+
+const loreli = new Loreli();
+await loreli.start();  // connects stdio transport
+```
+
+#### `loreli.loadInstructions()` -> string
+
+Loads the `instructions.md` file that is returned to MCP clients via the protocol's `instructions` field. This gives connected agents context about how Loreli works, its workflow, and review expectations.
+
+#### `loreli.tools(tools)`
+
+Register tool definitions. Each tool is `{ title, description, schema, exec }`.
+
+#### `loreli.prompts(prompts)` / `loreli.resources(resources)`
+
+Register prompt and resource definitions.
+
+#### `loreli.start(transport?)` -> McpServer
+
+Start the server. Defaults to stdio transport.
+
+## MCP Tools
+
+All tools are visible at all times. No progressive disclosure — every tool is available from the first connection.
+
+### Start & Environment
+
+| Tool | Description |
+|------|-------------|
+| `start` | Initialize orchestration for a target GitHub repo. Validates access, discovers/scaffolds templates, creates project board. Idempotent — safe to re-run. |
+| `environment` | Report detected environment: tmux, backends, providers, review strategy. |
+
+### Team Management
+
+| Tool | Description |
+|------|-------------|
+| `add_agent` | Add an agent. Params: `provider` (`openai`, `anthropic`, `cursor-openai`, `cursor-anthropic`), `role` (`planner`, `action`, `reviewer`), `model`, `theme`. |
+| `agents` | Query agent team state. Actions: `list` (show all agents with state, identity, role, and terminal output; optional `lines` param, default 40), `check` (liveness check for one or all agents). |
+| `start_planning` | Activate planner agents to analyze the repo and create draft work items. Accepts an `objective` to guide the planner. |
+| `start_work` | Begin action/review cycle. Action agents claim issues, do work, create PRs. Review agents are auto-assigned via yin/yang pairing. |
+| `team_status` | Dashboard: issues, PRs, agent states with terminal snapshots (last 20 lines), review loops, PRs awaiting human review, and GitHub API rate limits. |
+| `escalate` | Signal a concern or feature idea to the planner queue. Creates a draft on the project board. |
+
+### Human In The Loop (HITL)
+
+| Tool | Description |
+|------|-------------|
+| `hitl` | Hand off a PR to human reviewers (Human In The Loop). Requests review, assigns users, posts summary comment tagging reviewers. Kills agents to conserve resources. |
+| `watch` | Check an HITL PR for new human feedback. Filters out agent comments. Returns comments posted after the HITL timestamp. |
+
+### Agent Lifecycle
+
+| Tool | Description |
+|------|-------------|
+| `stop` | Stop an agent by name. Actions: `shutdown` (graceful, agent finishes current work then exits; escalates to kill after timeout), `kill` (immediate forced termination of tmux pane). |
+
+## Start Repair
+
+Start is an idempotent repair operation. Every invocation discovers which required files exist and scaffolds any that are missing. Safe to re-run.
+
+```mermaid
+flowchart TD
+  Discover["discover templates via hub.read"] --> Check{"Missing files?"}
+  Check -->|yes| Scaffold["scaffold via hub.write"]
+  Check -->|no| Load
+  Scaffold --> Load["config.load via hub"]
+  Load --> Merge["config.merge(args)"]
+  Merge --> Session["storage.init(session, config)"]
+  Session --> Report["Report: found + scaffolded"]
+```
+
+### Required Files
+
+| File | Scaffold Source | Discover Key |
+|------|----------------|--------------|
+| `.github/pull_request_template.md` | `scaffolding/pull-request.md` | `pr` |
+| `.github/ISSUE_TEMPLATE/` | `scaffolding/ISSUE_TEMPLATE/` | `issue` |
+| `loreli.yml` | `scaffolding/loreli.yml` | `config` |
+
+## Scaffolding Templates
+
+Default templates for empty repos, read from `scaffolding/`:
+
+- `pull-request.md` — PR template with Summary, Changes, Testing, Issue Reference, Sign-off
+- `ISSUE_TEMPLATE/loreli.yml` — Structured issue form mirroring the planner output format: Objective, Acceptance Criteria, Testing Strategy, Scope Boundaries, Dependencies, Estimated Complexity. Auto-applies the `loreli` label so issues enter the dispatch pipeline immediately.
+- `ISSUE_TEMPLATE/config.yml` — Issue template configuration (blank issues disabled to ensure all issues use the structured template and receive the `loreli` label)
+- `loreli.yml` — Default config with all keys documented via inline comments
+
+Issue templates use the [new YAML-based issue form workflow](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository) instead of the deprecated single-file Markdown format. The template guides authors toward writing agent-actionable prompts with mandatory acceptance criteria and testing strategy, matching the same structure the planner produces.
+
+## Orchestrator
+
+The `Orchestrator` class manages the full lifecycle:
+
+1. **Plan** — Planner creates drafts on project board, reviewer challenges
+2. **Promote** — Approved drafts become real issues
+3. **Action** — Agents claim issues, create PRs
+4. **Review** — Cross-provider adversarial review
+5. **HITL** (optional) — Hand off to human reviewers, kill agents
+6. **Merge** — Dual sign-off triggers merge (auto), or human merges (HITL)
+
+### Orchestrator Lifecycle
+
+```mermaid
+stateDiagram-v2
+    [*] --> Init: start
+    Init --> Planning: start_planning(objective)
+    Planning --> Promoting: drafts approved
+    Promoting --> Working: start_work
+    Working --> Reviewing: PR opened
+    Reviewing --> Working: feedback
+    Reviewing --> Gating: dual sign-off
+    Gating --> Merged: auto-merge
+    Gating --> AwaitingHuman: HITL
+    AwaitingHuman --> Merged: human merges
+    AwaitingHuman --> Rework: human comments
+    Rework --> Reviewing: fresh agent
+    Merged --> [*]
+```
+
+### Stall Detection (Escalation Tiers)
+
+The orchestrator monitors agents for inactivity with three escalation tiers:
+
+| Tier | Trigger | Action |
+|------|---------|--------|
+| **Nudge** | 1x `timeouts.stall` | Send a message to the agent asking for status |
+| **Warning** | 2x `timeouts.stall` | Post a visible GitHub comment on the agent's claimed issue |
+| **Reassign** | 3x `timeouts.stall` | Kill the agent, release all claimed issues, emit event |
+
+When an agent is killed via stall detection (tier 3), its claimed issues are released so `start_work` can re-assign them to a fresh agent.
+
+### Issue Reassignment
+
+When an agent is killed (`stop` action: `kill`) or shut down (`stop` action: `shutdown`), any GitHub issues claimed by that agent are automatically released. This prevents dead agents from blocking work:
+
+1. Scan open issues for the agent's claim comments
+2. Post a release comment on each claimed issue
+3. Remove agent-specific labels
+4. Issue becomes available for re-claim by `start_work`
+
+### Structured Shutdown Protocol
+
+Agent shutdown follows a 3-phase protocol:
+
+1. **Request** — Send a structured shutdown message with a unique `requestId` and optional reason
+2. **Poll** — Wait for the agent to acknowledge (exits or transitions to dormant)
+3. **Cleanup** — Force stop, release claimed issues, remove from registry
+
+The `requestId` prevents confusion between concurrent shutdown requests. If the agent doesn't acknowledge within the timeout, it is force-stopped.
+
+### Plan Review
+
+When `start_planning` dispatches to planner agents, a reviewer agent (if available) is automatically assigned to adversarially review the resulting drafts. This leverages the yin/yang pairing to get cross-provider plan review before drafts are promoted to issues.
+
+### Human In The Loop (HITL)
+
+```mermaid
+sequenceDiagram
+    participant Action as ActionAgent
+    participant Reviewer as ReviewAgent
+    participant GH as GitHub PR
+    participant Orch as Orchestrator
+    participant Human as Human Reviewer
+
+    Action->>GH: Opens PR
+    Reviewer->>GH: Reviews PR
+    Action->>GH: Addresses feedback
+    Reviewer->>GH: Approves
+    Action->>GH: Signs off
+    Orch->>Orch: config.get merge.hitl
+    alt hitl = false
+        Orch->>GH: Merge PR
+    else hitl = true
+        Orch->>GH: Request review + assign reviewers
+        Orch->>GH: Post summary comment @tagging reviewers
+        Orch->>Orch: Kill both agents
+        Note over GH: awaiting_hitl
+        Human->>GH: Merge OR comment
+        alt human merges
+            Note over GH: Done
+        else human comments
+            Orch->>Orch: Spawn fresh agent
+            Action->>GH: Address feedback + push
+            Orch->>GH: Re-request + re-assign
+            Orch->>Orch: Kill agent
+        end
+    end
+```
+
+HITL is activated when `loreli.yml` has a non-empty `reviewers` list or `merge.hitl` is set to `true`.
+
+## CLI
+
+The CLI is powered by `@mcp-layer/cli`, which automatically exposes all MCP tools as CLI commands.
+
+```bash
+# Start the MCP server (required when used as MCP server)
+loreli mcp
+
+# All tools are available as subcommands
+loreli tools list
+loreli tools start --repo owner/repo
+loreli tools add_agent --provider anthropic --role action
+loreli tools team_status
+loreli tools agents --action check --name optimus-0
+
+# Default (no args) shows help
+loreli
+```
+
+## Input Validation
+
+All tool handlers validate inputs before any side effects using `check.*` from `loreli/config`:
+
+| Validator | Rule |
+|-----------|------|
+| `check.repo(str)` | Must match `owner/name` format |
+| `check.name(str)` | Alphanumeric + hyphens/underscores, max 64 chars |
+| `check.role(str)` | Must be `planner`, `action`, or `reviewer` |
+| `check.theme(str)` | Must be one of the supported themes (`transformers`, `pokemon`, `marvel`, `digimon`, `starwars`, `lotr`, `dragonball`, `avatar`, `zelda`) |
+| `check.provider(str)` | Must be `openai`, `anthropic`, `cursor-openai`, or `cursor-anthropic` |
+| `check.positive(n, label)` | Must be a finite positive number |
+
+Invalid inputs throw immediately with descriptive error messages before any GitHub API calls or state mutations.
+
+## Dynamic Tool Descriptions
+
+After start discovers available backends, the `add_agent` tool description is dynamically updated to list available backends, model aliases, and providers. MCP clients receive a `tools/list_changed` notification so they can refresh the tool list.
+
+## Client Detection
+
+The server identifies the connected MCP client via the standard `initialize` handshake. The `clientInfo` field (name, version) from the handshake is used to build a lightweight `Identity` for stamping tool-originated content. This replaces the previous sampling-based probe which was fragile and optional.
+
+## Error Handling
+
+| Scenario | Behavior |
+|----------|----------|
+| Spawn fails | All steps rolled back in reverse order, identity released, error propagated |
+| Agent stalls | Tier 1: nudge, Tier 2: GitHub comment, Tier 3: kill and reassign |
+| Shutdown timeout | Force stop after timeout, issues released |
+| Agent killed | Issues reassigned, identity released, labels cleaned |
+| Invalid tool input | Descriptive error thrown before any side effects |
+| No backends found | Clear error with installation guidance |
+| Hub unavailable | Tool returns error with guidance |
+| No planner agents | `start_planning` returns error |
+| No unclaimed issues | `start_work` returns "no unclaimed issues" message |
+| tmux missing | `loreli mcp` exits with install instructions |

package/packages/mcp/instructions.md

@@ -0,0 +1,121 @@
+You are connected to **Loreli**, an agentic team orchestration server that coordinates AI agents using GitHub as the collaboration layer.
+
+<overview>
+
+Loreli manages teams of AI agents that work on GitHub repositories. Issues are tasks, pull requests are deliverables, discussions are plans, comments are communication, and reviews are quality gates.
+
+### Workflow
+
+1. **Start**: Point Loreli at a target GitHub repository. It validates access, discovers existing files, and scaffolds any missing ones (PR template, issue template, `loreli.yml`). This is idempotent — safe to re-run.
+2. **Plan**: Planner agents create plan discussions in the Loreli category using the `plan` tool. A polar-opposite reviewer challenges the plan using the `plan` tool (action: `verdict`).
+3. **Action**: Action agents claim approved issues (first-comment-wins), create branches, implement work, and open PRs using the `pr` tool.
+4. **Review**: Cross-provider reviewers assess PRs adversarially using the `pr` tool (action: `review`). Feedback is addressed in iteration loops.
+5. **Human In The Loop (HITL)** (optional): If `loreli.yml` has `reviewers` configured, PRs are handed off to human reviewers after agent approval. Agents are shut down while awaiting human decision.
+6. **Merge**: Dual sign-off triggers merge (auto), or human merges manually (HITL). Agents go dormant or claim new work.
+
+### Configuration
+
+Each target repository can have a `loreli.yml` in its root to configure orchestration behavior — theme, merge method, human reviewers, timeouts, and more. If the file doesn't exist, start scaffolds a default one. Start params override `loreli.yml` values.
+
+### Agent Identity
+
+Agents are assigned themed identities (Transformers, Pokemon, Marvel, Digimon) with yin/yang provider pairing. OpenAI agents get one faction, Anthropic agents get the opposing faction. This creates adversarial quality checks.
+
+### Backends
+
+Loreli supports multiple backends: Claude (interactive, Anthropic), Cursor Agent (interactive, multi-provider), Codex (interactive, OpenAI). The `environment` tool shows which backends are available. When adding agents, use `provider: "anthropic"` for Claude, `provider: "openai"` for Codex, or `provider: "multi"` for Cursor Agent (which can run models from any provider).
+
+</overview>
+
+<protocols>
+
+### Claim Protocol
+
+Issues are claimed via first-comment-wins. When an agent wants to work on an issue, it posts a claim comment using the `comment` tool. The first claim comment's author is the assigned agent.
+
+### Review Expectations
+
+- Address all review feedback before requesting re-review.
+- Both the action agent and review agent must sign off for merge.
+- Escalate scope concerns using the `plan` tool (action: `escalate`).
+
+### Human In The Loop (HITL)
+
+When configured, after both agents sign off:
+
+1. Loreli requests review from the configured human reviewers.
+2. Agents are shut down to conserve resources.
+3. If the human merges, the workflow is complete.
+4. If the human posts comments, Loreli spawns a fresh agent to address the feedback and re-requests review.
+
+### Communication
+
+All communication happens through GitHub: issue comments, PR comments, discussion comments, and reviews. There are no private channels — everything is visible and auditable.
+
+</protocols>
+
+<tool_contract>
+
+## Agent Tool Contract
+
+When you are a spawned agent (planner, action, or reviewer), use the Loreli MCP tools for all GitHub operations. Your identity, repository, and current work item are resolved automatically from your session.
+
+### Available Agent Tools
+
+| Tool | Actions | Used By |
+|------|---------|---------|
+| **plan** | `create`, `revise`, `verdict`, `escalate` | Planner creates/revises; Reviewer renders verdict; Any role escalates |
+| **pr** | `create`, `review` | Action creates PRs; Reviewer submits reviews |
+| **comment** | (none) | Any role posts comments on their current work item |
+| **context** | `blame`, `history`, `search`, `patterns` | Any role looks up code context, decision history, and feedback patterns |
+
+### Context Resolution
+
+Your session automatically provides:
+- **Repository**: The target repo you are assigned to.
+- **Identity**: Your themed identity with stamp and labels.
+- **Role**: Your role (planner, action, reviewer).
+- **Task**: Your current work item (discussion number, issue number, or PR number).
+
+You do not need to provide these values — the tools resolve them from your session.
+
+### Role Enforcement
+
+Tools enforce role boundaries server-side:
+
+| Action | Allowed Role | Blocked Roles |
+|--------|-------------|---------------|
+| `plan/create`, `plan/revise` | planner | action, reviewer |
+| `plan/verdict` | reviewer | planner, action |
+| `pr/create` | action | planner, reviewer |
+| `pr/review` | reviewer | planner, action |
+| `plan/escalate`, `comment` | any | — |
+| `context/*` | any | — |
+
+An action agent cannot approve its own PR. A planner cannot approve its own plan. The antagonist (opposing-provider reviewer) is always mandatory and auto-enlisted when missing.
+
+### Context Tool
+
+The `context` tool resolves code context — tracing lines to the PRs, issues, and discussions that shaped them. Use it to understand why code exists before changing it.
+
+| Action | What it does |
+|--------|-------------|
+| `blame` | Trace a file+line to the commit, author, and associated PRs |
+| `history` | View the commit history for a file with linked PR references |
+| `search` | Search issues and PRs by keyword to find past decisions |
+| `patterns` | View recurring review feedback patterns across PRs and plan discussions |
+
+Also available via CLI: `loreli tools context --action blame --file <path> --line <N>`
+
+</tool_contract>
+
+<rules>
+
+1. **Never bypass the tools**: All GitHub interactions must go through Loreli MCP tools. Direct `gh` CLI, REST, or GraphQL calls bypass stamping and label enforcement.
+2. **Never manage labels manually**: Labels are applied automatically by the tools. Do not add, remove, or modify `loreli:*` labels yourself.
+3. **Stay within scope**: If you discover work outside your current assignment, use the `plan` tool (action: `escalate`) to flag it.
+4. **Respect your role**: Only use actions permitted for your role. Attempting unauthorized actions wastes tokens and time.
+5. **Honor repository policy files**: If `AGENTS.md` exists in the repository root, treat it as authoritative repository policy input.
+6. **Follow role prompt quality gates**: Testing and style-quality requirements are enforced in role-specific prompts and review flows; do not bypass them.
+
+</rules>

package/packages/mcp/scaffolding/.agents/skills/loreli-context/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: loreli-context
+description: Use when modifying unfamiliar code, investigating patterns, or reviewing PRs — resolves code to its full decision chain via git blame, PR history, issue tracking, and discussion threads
+---
+
+# Loreli Context
+
+## Overview
+
+Loreli maintains a complete decision chain for every line of code: commits link to PRs, PRs link to issues, and issues link to planning discussions. This skill teaches you how to query that chain.
+
+**Core principle:** Understand why code exists before changing it.
+
+## When to Use
+
+- Before modifying code you did not write
+- When encountering a pattern or convention you do not understand
+- When reviewing PRs with unclear rationale
+- Before making architectural decisions (check what has been tried before)
+- When debugging to understand historical context of a module
+
+## CLI Commands
+
+All commands are run in the terminal via the loreli CLI:
+
+### Blame — "Why was this line written?"
+
+```bash
+loreli tools context --action blame --file <path> --line <N>
+```
+
+Traces a specific line to the commit that created it, the PR that landed it, the issue it addressed, and the discussion where it was planned. Includes agent traces if available.
+
+### History — "What decisions shaped this file?"
+
+```bash
+loreli tools context --action history --file <path> --limit <N>
+```
+
+Returns recent commits touching a file with their associated PRs. Default limit is 10. Use this to understand the evolution of a module before making changes.
+
+### Search — "What do we know about X?"
+
+```bash
+loreli tools context --action search --query "<keywords>"
+```
+
+Searches across issues, PRs, and discussions for matching content. Use this to find prior discussions about a concept, pattern, or decision.
+
+### Patterns — "What recurring review themes exist?"
+
+```bash
+loreli tools context --action patterns --category <category>
+```
+
+Shows recurring feedback patterns across PR reviews and plan discussion verdicts. Categories: naming, architecture, testing, documentation, performance, security. Each pattern lists its source refs as `PR #N` or `Discussion #N` so you can trace feedback origin. Check this before submitting PRs to avoid known issues.
+
+## Documentation Requirements
+
+When working on code, maintain these documentation standards:
+
+### Architectural Changes
+
+If you add new packages, modules, or change data flow:
+
+- Create or update architecture diagrams in `docs/`
+- Explain the decision and alternatives considered
+- Link back to the discussion/issue where the change was planned
+
+### Error Handling
+
+If you add new error handling:
+
+- Document each error with resolution steps
+- Steps must be followable by anyone regardless of skill level
+- Include the error message, cause, and fix
+
+### API Documentation
+
+If you add exported functions, endpoints, or tool definitions:
+
+- Document parameters, return shapes, and error behavior
+- Update the package README
+
+## Lore Maintenance
+
+- When decisions change, update the relevant docs
+- Link docs to the discussion/issue where the decision was made
+- Use `loreli tools context --action search` to find existing docs before creating new ones

package/packages/mcp/scaffolding/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,2 @@
+blank_issues_enabled: false
+contact_links: []