loreli 0.0.0 → 2.0.0

package/packages/mcp/README.md

@@ -0,0 +1,323 @@
+# 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
+# or rely on repo fallback from loreli.yml / LORELI_REPO
+loreli tools start
+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. Accepts `--repo`, or falls back to configured `repo` from `loreli.yml` / `LORELI_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. Uses explicit `repo` argument when provided, otherwise falls back to configured `repo`. |
+| `start_work` | Begin action/review cycle. Action agents claim issues, do work, create PRs. Review agents are auto-assigned via yin/yang pairing. Uses explicit `repo` argument when provided, otherwise falls back to configured `repo`. |
+| `team_status` | Dashboard: issues, PRs, agent states with terminal snapshots (last 20 lines), review loops, PRs awaiting human review, and GitHub API rate limits. Uses explicit `repo` argument when provided, otherwise falls back to configured `repo`. |
+
+### Agent Tools (Agent-Only)
+
+| Tool | Description |
+|------|-------------|
+| `plan` | Plan lifecycle management. Actions: `create` (new discussion), `revise` (update after feedback), `verdict` (approve/reject as reviewer), `escalate` (flag process or architecture concerns). |
+| `pr` | Pull request lifecycle. Actions: `create` (open PR from branch), `review` (submit adversarial review). |
+| `comment` | Post a comment on the agent's current work item. Set `claim: true` to claim an issue, `abandon: true` to abandon. |
+| `read` | Read any issue, PR, or discussion by number. |
+| `refactor` | Flag a bug, code smell, or tech debt discovered during implementation. Action agents only. Creates a deduplicated Loreli discussion labeled `loreli:refactor` that enters the standard review/promote pipeline. |
+| `context` | Resolve code context. Actions: `blame`, `history`, `search`, `patterns`. |
+| `environment` | Report detected environment: tmux, backends, providers, review strategy. |
+
+#### `refactor` Tool
+
+Enables [opportunistic refactoring](https://martinfowler.com/bliki/OpportunisticRefactoring.html) — action agents report improvements they discover without leaving their assigned scope.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `kind` | `string` | yes | Category: `bug`, `refactor`, `smell`, or `debt` |
+| `title` | `string` | yes | Concise improvement title |
+| `description` | `string` | yes | Problem statement with stable identifiers (function names, class names, error messages) |
+| `files` | `string[]` | no | Affected file paths, optionally with line range hints |
+| `impact` | `string` | no | `low`, `medium` (default), or `high` |
+
+**File path format:**
+
+File entries accept plain paths or paths with GitHub-style line range hints:
+
+- `src/hub.js` — plain path
+- `packages/hub/src/github.js#R40-R50` — path with line range hint (lines 40–50)
+
+Line ranges are advisory hints; they may drift between commits. Always include stable identifiers (function names, error patterns) in the `description`.
+
+**Dedup behavior:**
+
+Before creating a discussion, the tool searches existing issues and `loreli:refactor`-labeled discussions by normalized title. If a match is found, it returns an "Already tracked" reference instead of creating a duplicate. Dedup is best-effort — parallel reports can race.
+
+**Pipeline integration:**
+
+Created discussions enter the existing planner review/revise/promote pipeline. When promoted to issues, the `loreli:refactor` label is carried to the new issue for tracking.
+
+### 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. Uses explicit `repo` argument when provided, otherwise falls back to configured `repo`. |
+| `watch` | Check an HITL PR for new human feedback. Filters out agent comments. Returns comments posted after the HITL timestamp. Uses explicit `repo` argument when provided, otherwise falls back to configured `repo`. |
+
+### 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,126 @@
+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 |
+| **read** | (none) | Any role reads issues, PRs, or discussions by number |
+| **refactor** | (none) | Action flags bugs, smells, debt for planning |
+| **context** | `blame`, `history`, `search`, `patterns` | Any role looks up code context, decision history, and feedback patterns |
+| **environment** | (none) | Any role checks available backends |
+
+### 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 |
+| `refactor` | action | planner, reviewer |
+| `plan/escalate`, `comment` | any | — |
+| `context/*`, `read`, `environment` | 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.
+7. **Flag improvements opportunistically**: When you encounter bugs, code smells, or tech debt during your work, use the `refactor` tool immediately. Do not fix out-of-scope issues yourself — flag them and continue your task. The dedup gate prevents duplicate reports. Use `plan` (action: `escalate`) for process or architecture concerns, not code-level findings.
+
+</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: []

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

@@ -0,0 +1,83 @@
+name: Loreli Work Item
+description: Structured work item for Loreli agent orchestration. Issues created with this template are automatically labeled for agent dispatch.
+title: "[Loreli]: "
+labels: ["loreli"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        This template produces issues that Loreli agents can act on directly.
+        Write each section as if briefing an engineer who has never seen this
+        codebase — specific, testable, and unambiguous.
+
+  - type: textarea
+    id: objective
+    attributes:
+      label: Objective
+      description: What needs to be done, in one sentence. Be precise — this becomes the agent's mission.
+      placeholder: "Add exponential backoff retry logic to the GitHub API client for transient failures."
+    validations:
+      required: true
+
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Acceptance Criteria
+      description: >
+        Specific, testable conditions that define "done". Each criterion must be
+        independently verifiable by someone who did not write the code. Aim for
+        3+ criteria — vague items like "works correctly" will be rejected.
+      placeholder: |
+        - [ ] Retries on 429 and 5xx status codes, up to 3 attempts.
+        - [ ] Uses exponential backoff: 1s, 2s, 4s base delays with jitter.
+        - [ ] Non-retryable errors (4xx except 429) propagate immediately.
+        - [ ] Retry attempts are logged with attempt number and delay.
+    validations:
+      required: true
+
+  - type: textarea
+    id: testing
+    attributes:
+      label: Testing Strategy
+      description: >
+        Concrete test scenarios to write before implementation (TDD). Name
+        specific inputs, expected behaviors, and edge cases. Agents write
+        tests first — this section tells them what to test.
+      placeholder: |
+        - Test that 429 responses trigger retry with correct backoff timing.
+        - Test that 500/502/503 trigger retry.
+        - Test that 400/401/404 propagate immediately without retry.
+        - Test that max retries is respected and final error surfaces.
+        - Test jitter produces non-deterministic delays within expected bounds.
+    validations:
+      required: true
+
+  - type: textarea
+    id: scope
+    attributes:
+      label: Scope Boundaries
+      description: What is explicitly NOT included in this work. Helps agents avoid scope creep.
+      placeholder: "Does NOT include circuit breaker patterns, request queuing, or rate limit header parsing."
+    validations:
+      required: false
+
+  - type: textarea
+    id: dependencies
+    attributes:
+      label: Dependencies
+      description: Other issues, PRs, or external work this depends on. Link them if possible.
+      placeholder: "Depends on #42 (API client refactor)."
+    validations:
+      required: false
+
+  - type: dropdown
+    id: complexity
+    attributes:
+      label: Estimated Complexity
+      description: Rough sizing to help the orchestrator allocate the right agent tier.
+      options:
+        - Low
+        - Medium
+        - High
+    validations:
+      required: true