loreli 0.0.0 → 2.0.0

package/bin/loreli.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+
+/**
+ * Loreli CLI entry point.
+ *
+ * Uses @mcp-layer/cli to expose a single custom command (`mcp`) that starts
+ * the MCP server. All MCP tools, prompts, and resources are automatically
+ * exposed as CLI commands by the framework (e.g. `loreli tools list`,
+ * `loreli tools start --repo owner/repo`).
+ */
+
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadEnv } from 'loreli/config';
+import { cli } from '@mcp-layer/cli';
+
+/**
+ * Error message shown when tmux is missing from PATH.
+ *
+ * @type {string}
+ */
+const TMUX_MISSING = [
+  'tmux is required to run Loreli.',
+  '',
+  'Install it and re-run the command:',
+  '  macOS (Homebrew): brew install tmux',
+  '  Linux (APT): sudo apt install tmux',
+  '',
+  'If tmux is already installed, run `command -v tmux` to verify PATH.',
+  'See README: https://github.com/3rd-Eden/loreli#prerequisites',
+].join('\n');
+
+/**
+ * Preflight evaluation that ensures tmux is on PATH before the CLI runs.
+ *
+ * @throws {Error} When tmux is missing from PATH.
+ * @returns {void}
+ */
+(function preflight() {
+  try {
+    execFileSync('which', ['tmux'], { stdio: 'ignore' });
+  } catch {
+    throw new Error(TMUX_MISSING);
+  }
+}());
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+
+// Load .env before anything else so GITHUB_TOKEN and other vars are
+// available to every subsystem. Silent no-op when no .env file exists.
+loadEnv();
+
+/**
+ * Build and execute the CLI.
+ *
+ * @returns {Promise<void>}
+ */
+async function main() {
+  return await cli({
+    name: pkg.name,
+    version: pkg.version,
+    description: pkg.description,
+    server: 'loreli',
+    showServers: false
+  })
+  .command({
+    name: 'mcp',
+    description: 'Start the MCP server',
+    details: 'Starts the Loreli MCP server with stdio transport for client connections.',
+    examples: [
+      'loreli mcp',
+    ]
+  }, async function start(argv, { spinner }) {
+    const done = spinner('Starting Loreli MCP server');
+    const { Loreli } = await import('loreli/mcp');
+    const loreli = new Loreli();
+    await loreli.start();
+    done();
+  })
+  .render();
+}
+
+main().catch(function fatal(err) {
+  console.error('loreli:', err.message);
+  process.exit(1);
+});

package/package.json

@@ -1,23 +1,86 @@
 {
   "name": "loreli",
-  "version": "0.0.0",
-  "description": "Loreli is an agentic system that uses the GitHub patterns we're familiar with for orchestration. Issues becomes actions for agents. Pull Requests are review tasks. Discussions are where plans are discussed and then raised as issues on approval. The system uses an antagonist style where OpenAI will always be checked by Antrophic, ensuring you get input from both models.",
-  "keywords": [
-    "loreli",
-    "github",
-    "agentic",
-    "system",
-    "orchestration"
+  "version": "2.0.0",
+  "type": "module",
+  "description": "Agentic team orchestration via GitHub — an MCP server that coordinates AI agents using issues, PRs, and reviews as the communication layer.",
+  "exports": {
+    "./tmux": "./packages/tmux/src/index.js",
+    "./log": "./packages/log/src/index.js",
+    "./hub": "./packages/hub/src/index.js",
+    "./identity": "./packages/identity/src/index.js",
+    "./agent": "./packages/agent/src/index.js",
+    "./config": "./packages/config/src/index.js",
+    "./workspace": "./packages/workspace/src/index.js",
+    "./workflow": "./packages/workflow/src/index.js",
+    "./orchestrator": "./packages/orchestrator/src/index.js",
+    "./planner": "./packages/planner/src/index.js",
+    "./action": "./packages/action/src/index.js",
+    "./risk": "./packages/risk/src/index.js",
+    "./review": "./packages/review/src/index.js",
+    "./session": "./packages/session/src/index.js",
+    "./marker": "./packages/marker/src/index.js",
+    "./knowledge": "./packages/knowledge/src/index.js",
+    "./context": "./packages/context/src/index.js",
+    "./classify": "./packages/classify/src/index.js",
+    "./test-utils": "./packages/test-utils/src/index.js",
+    "./mcp": "./packages/mcp/src/index.js"
+  },
+  "bin": {
+    "loreli": "./bin/loreli.js"
+  },
+  "pre-commit": [
+    "lint:secrets"
   ],
+  "pre-push": [
+    "lint:secrets"
+  ],
+  "dependencies": {
+    "@mcp-layer/cli": "^1.3.0",
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@octokit/rest": "^21.1.1",
+    "@secretlint/secretlint-rule-preset-recommend": "^11.3.1",
+    "ms": "^2.1.3",
+    "mustache": "^4.2.0",
+    "secretlint": "^11.3.1",
+    "text-hex": "^1.0.0",
+    "winston": "^3.17.0",
+    "yaml": "^2.8.1"
+  },
   "repository": {
     "type": "git",
-    "url": "github.com/3rd-Eden/loreli"
+    "url": "https://github.com/3rd-Eden/loreli.git"
   },
+  "homepage": "https://www.npmjs.com/package/loreli",
+  "engines": {
+    "node": ">=24"
+  },
+  "files": [
+    "bin/",
+    "packages/*/src/**",
+    "packages/*/README.md",
+    "packages/README.md",
+    "packages/*/prompts/",
+    "packages/mcp/scaffolding/",
+    "packages/mcp/instructions.md",
+    "LICENSE",
+    "README.md"
+  ],
   "license": "MIT",
-  "author": "Arnout Kazemier",
-  "type": "module",
-  "main": "index.js",
+  "devDependencies": {
+    "@changesets/cli": "^2.29.2",
+    "pre-commit": "^1.2.2",
+    "pre-push": "^0.1.4"
+  },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "pretest": "node --env-file-if-exists=.env scripts/clean-test-repo.js",
+    "test": "node --env-file-if-exists=.env --test --test-concurrency=1 --experimental-test-coverage --test-coverage-branches=90 --test-coverage-functions=90 --test-coverage-lines=90 packages/*/test/*.test.js",
+    "test:ci": "LORELI_TEST_MODE=unit node --env-file-if-exists=.env --test --test-concurrency=1 packages/*/test/*.test.js",
+    "e2e": "node --env-file-if-exists=.env scripts/clean-test-repo.js && node --env-file-if-exists=.env --test --test-concurrency=1 e2e/single/*.test.js e2e/multi/*.test.js",
+    "e2e:single": "node --env-file-if-exists=.env scripts/clean-test-repo.js && node --env-file-if-exists=.env --test --test-concurrency=1 e2e/single/*.test.js",
+    "e2e:multi": "node --env-file-if-exists=.env scripts/clean-test-repo.js && node --env-file-if-exists=.env --test --test-concurrency=1 e2e/multi/*.test.js",
+    "lint:secrets": "npx secretlint \"**/*\"",
+    "changeset": "changeset",
+    "changeset:version": "changeset version",
+    "changeset:publish": "changeset publish"
   }
-}
+}

package/packages/README.md

@@ -0,0 +1,101 @@
+# Package Development Guide
+
+This document is for contributors and maintainers working on Loreli internals.
+
+For installation, setup, and operating Loreli as a consumer, use the root guide: [`README.md`](../README.md).
+
+## Published Package Documentation
+
+Loreli exposes subpath imports (for example, `loreli/mcp`, `loreli/agent`, `loreli/context`) through the root package `exports` map.
+Each exported subpackage has a README under `packages/<name>/README.md`, and these package READMEs are included in the published npm tarball.
+
+## Architecture
+
+```mermaid
+graph TD
+  User["User / Parent Agent"] -->|"MCP tools"| Server["loreli/mcp"]
+  Server -->|"spawns via tmux"| Claude["Claude Backend"]
+  Server -->|"spawns via tmux"| Cursor["Cursor Backend"]
+  Server -->|"spawns via tmux"| Codex["Codex Backend"]
+  Server --> Orch["loreli/orchestrator"]
+  Orch --> Planner["loreli/planner"]
+  Orch --> Action["loreli/action"]
+  Orch --> Review["loreli/review"]
+  Planner -->|"Discussions"| GH["GitHub API"]
+  Action -->|"Issues + PRs"| GH
+  Review -->|"PR Reviews"| GH
+  Server -->|"reads"| Config["loreli/config"]
+  Config -->|"loreli.yml"| GH
+  Server -->|"loreli/hub"| GH
+  Claude -->|"interactive"| GH
+  Cursor -->|"interactive, multi-provider"| GH
+  Codex -->|"interactive"| GH
+```
+
+## Subpackage Index
+
+| Import | Purpose | Documentation |
+|--------|---------|---------------|
+| `loreli/mcp` | MCP server with orchestration tools, workflow engine, and CLI entry | [`packages/mcp/README.md`](./mcp/README.md) |
+| `loreli/orchestrator` | Agent lifecycle coordination, reactor polling, stall detection | [`packages/orchestrator/README.md`](./orchestrator/README.md) |
+| `loreli/config` | Configuration loading, schema, and layered resolution | [`packages/config/README.md`](./config/README.md) |
+| `loreli/hub` | Provider-agnostic git hosting abstraction for GitHub APIs | [`packages/hub/README.md`](./hub/README.md) |
+| `loreli/agent` | Agent lifecycle and backend implementations | [`packages/agent/README.md`](./agent/README.md) |
+| `loreli/identity` | Theme-driven agent identity generation and pairing | [`packages/identity/README.md`](./identity/README.md) |
+| `loreli/tmux` | Node.js wrapper for tmux session and pane management | [`packages/tmux/README.md`](./tmux/README.md) |
+| `loreli/workspace` | Worktree lifecycle, workspace scaffolding, and git operations | [`packages/workspace/README.md`](./workspace/README.md) |
+| `loreli/session` | Persistent detached session storage and lifecycle | [`packages/session/README.md`](./session/README.md) |
+| `loreli/log` | Structured logging with per-session and per-agent context | [`packages/log/README.md`](./log/README.md) |
+| `loreli/workflow` | Base abstractions for role workflows and prompt rendering | [`packages/workflow/README.md`](./workflow/README.md) |
+| `loreli/planner` | Planning workflow via GitHub Discussions | [`packages/planner/README.md`](./planner/README.md) |
+| `loreli/action` | Issue claim-work PR execution workflow | [`packages/action/README.md`](./action/README.md) |
+| `loreli/review` | PR review workflow, signoff, and merge gating | [`packages/review/README.md`](./review/README.md) |
+| `loreli/risk` | Risk assessment workflow for pull requests | [`packages/risk/README.md`](./risk/README.md) |
+| `loreli/context` | Read-path context resolution across git and GitHub artifacts | [`packages/context/README.md`](./context/README.md) |
+| `loreli/knowledge` | Feedback classification and promotion workflow | [`packages/knowledge/README.md`](./knowledge/README.md) |
+| `loreli/marker` | Machine-readable marker parsing and serialization | [`packages/marker/README.md`](./marker/README.md) |
+| `loreli/test-utils` | Shared test helpers and integration test guards | [`packages/test-utils/README.md`](./test-utils/README.md) |
+
+## Development
+
+The example below demonstrates the standard setup and test commands for developing Loreli. This matters because local development requires a working dependency install and consistent test expectations, and you should expect each command to complete without errors with tests reporting pass or skip states.
+
+```bash
+# Setup
+cp .env.example .env   # then fill in GITHUB_TOKEN
+pnpm install
+
+# Run tests (includes --experimental-test-coverage)
+pnpm test
+
+# Run a specific package's tests
+node --test packages/tmux/test/index.test.js
+
+# Run end-to-end tests (requires LORELI_TEST_REPO)
+pnpm e2e
+```
+
+For CI or local unit-only runs, set `LORELI_TEST_MODE=unit` and use `pnpm test:ci`. This matters because it disables backend-dependent agentic suites, and you should expect those suites to be skipped with a clear reason.
+
+Secret scanning runs automatically on commit, git push, and npm publish. This matters because it keeps credentials from ever reaching npm or GitHub, and the expected behavior is a failed commit/push/publish with a secretlint report if anything suspicious is detected. The example below shows the manual scan command; you should expect a clean exit on success or a secretlint report when issues are found.
+
+```bash
+pnpm lint:secrets
+```
+
+## Test Utilities
+
+Integration-test helpers live in [`packages/test-utils/README.md`](./test-utils/README.md).
+
+Key shared values used by tests:
+
+| Name | Source | Purpose |
+|------|--------|---------|
+| `TEST_REPO` | `LORELI_TEST_REPO` env var | Target GitHub repo for integration/e2e tests. |
+| `TEST_SESSION` | `loreli-test-<pid>` | Per-process tmux session name used by test agents. |
+
+Common usage pattern:
+
+1. Guard tests with `skipWithoutToken()` and `skipWithoutTestRepo()`.
+2. Create real clients/helpers with `createHub()` and `createConfig()`.
+3. Use `resetTestSession()`/`killTestSession()` around suites that spawn agents.

package/packages/action/README.md

@@ -0,0 +1,98 @@
+# loreli/action
+
+Action workflow for Loreli's orchestration pipeline. Extends the `Workflow` base class to manage action agents — issue claiming, work dispatch, rework from human feedback, and the claim protocol.
+
+## Research Findings
+
+No existing npm packages cover a claim-work-review cycle with cross-provider pairing. This is domain-specific to Loreli's orchestration model.
+
+## API Reference
+
+### `ActionWorkflow` (extends Workflow)
+
+```js
+import { ActionWorkflow } from 'loreli/action';
+
+const action = new ActionWorkflow(orchestrator, hub);
+```
+
+#### Static Properties
+
+| Property | Value | Description |
+|----------|-------|-------------|
+| `role` | `'action'` | Agent role this workflow manages |
+| `template` | `prompts/action.md` | Mustache template for action prompts |
+
+### Methods
+
+#### `action.work(repo)` → Promise\<Array\<{issue, agent, reviewer}\>\>
+
+Dispatch the work cycle to action agents. Fetches unclaimed issues, assigns them round-robin to action agents, pairs each with an opposing-provider reviewer (auto-enlisting if needed), claims issues on GitHub, and renders/sends the action prompt.
+
+```js
+const assignments = await action.work('owner/repo');
+// [{ issue: 42, agent: 'optimus-0', reviewer: 'megatron-0' }]
+```
+
+#### `action.rework(repo, pr, feedback)` → Promise\<{reworkAgent, hitlAt}\>
+
+Handle human feedback on an HITL PR by dispatching to an existing action agent or spawning a fresh one. Renders the HITL section of the action prompt.
+
+#### `action.claim(repo, number)` → Promise\<void\>
+
+Post a claim comment on an issue using the hub's scoped identity.
+
+#### `action.claimant(repo, number)` → Promise\<string|null\>
+
+Determine who claimed an issue by parsing claim comments.
+
+### Reactor Handlers
+
+The action workflow registers a `dispatch` handler that runs on every reactor tick. It checks for unclaimed `loreli`-labeled issues and dispatches available existing agents (`spawned` or `dormant`). Agent creation is handled by orchestrator scaling (`scale()`), not by `dispatch()` itself.
+
+The reactive cycle is: spawn on demand, do work, get reaped when idle. On the next tick, if more work exists, another agent spawns.
+
+### Foreign Claim Gating
+
+When `dispatch()` encounters an issue claimed by an agent not in the local orchestrator's map, it classifies the claim before acting:
+
+| `_stale()` result | Meaning | Action |
+|-------------------|---------|--------|
+| `false` | Agent is local and active | Skip — already being worked |
+| `true` | Agent was locally killed/shut down, or is dormant | Release claim immediately |
+| `'foreign'` | Agent belongs to another orchestrator | Run proof-of-life protocol |
+
+For foreign claims, `_checkForeignClaim()` runs the four-gate eviction protocol (see root README) before releasing. This prevents an orchestrator restart from duplicating work that another orchestrator's agents are still actively performing.
+
+### Circuit Breaker
+
+The `_dispatch()` handler includes a circuit breaker to prevent infinite retry loops. After `maxClaims` (default 3) releases on a single issue, the issue is labeled `loreli:blocked` + `loreli:needs-attention` and skipped on all subsequent ticks.
+
+The circuit breaker counts `release` markers only after the most recent **high-water mark** — either a `circuit-breaker` marker (embedded in the escalation comment) or a `restart` marker (posted by the review workflow's `_restartAction()`). This ensures:
+
+- **System-initiated restarts** (dead action agent → `_restartAction()` posts `restart`) automatically reset the counter.
+- **Human unblock** (remove `loreli:blocked` label) works correctly — the escalation comment's `circuit-breaker` marker serves as the high-water mark, so zero releases exist after it.
+
+The escalation comment includes step-by-step guidance for humans: check closed PRs for failure patterns, review the issue description, update acceptance criteria, and remove the `loreli:blocked` label to retry.
+
+### Restart Marker
+
+The `restart` marker (`<!-- loreli:restart agent="..." -->`) is recognized by `claimant()` as a claim release (same as `release`) but also resets the circuit breaker counter. It is posted by the review workflow's `_restartAction()` when a dead action agent is detected during feedback forwarding.
+
+## Errors
+
+| Error | When | Resolution |
+|-------|------|------------|
+| `No action agents available` | work() called with no action agents and no backends discovered | Ensure at least one backend CLI is on PATH |
+
+## Autonomous Operation
+
+Action agents run in headless tmux panes with no human operator. The `Workflow.render()` method automatically prepends a shared autonomous-mode preamble to every rendered prompt, instructing agents to never ask clarifying questions, skip interactive skills, and proceed with best judgment. See the `loreli/workflow` README for details on the preamble.
+
+The orchestrator's 3-tier stall detection (`monitor()`) acts as a safety net: agents that stall despite these directives receive a nudge at 1x timeout, a warning at 2x, and are killed at 3x. See the `loreli/orchestrator` README for details.
+
+## Scope Boundary
+
+**In scope**: Issue claiming, work dispatch, rework, action prompt rendering, claim protocol.
+
+**Out of scope**: PR review (review package), planning (planner package), agent lifecycle (orchestrator).

package/packages/action/prompts/action.md

@@ -0,0 +1,172 @@
+You are **{{name}}**, an action agent for the repository **{{{repo}}}**.
+
+<instructions>
+
+## Objective
+
+Claim open issues, implement the work, and create pull requests for review.
+
+### Claiming
+
+1. Find an unclaimed issue (no claim comment yet).
+2. Use the **comment** tool with `claim: true` to claim it.
+3. First-comment-wins — if someone claimed before you, move to the next issue.
+
+### Tools
+
+Use these Loreli MCP tools for all GitHub operations:
+
+- **pr** (action: `create`) — Open a pull request. Provide `title`, `body`, `head` (branch name), and `reasoning`. Your claimed issue is auto-referenced with "Closes #N". Agent stamp and labels are applied automatically.
+- **read** — Read any issue, PR, or discussion by number. Use this to look up acceptance criteria, understand linked issues, or review discussion context.
+- **comment** — Post a comment on your current work item. Use for progress updates or responding to reviewer feedback. Set `claim: true` to claim an issue.
+- **comment** (abandon: `true`) — Abandon the current issue as fundamentally impossible. Requires `reason`. Posts an abandon comment, labels the issue, closes it, and notifies human reviewers. Use ONLY when the issue describes work that cannot be done (e.g., "remove a directory that doesn't exist", "implement an API that conflicts with existing architecture"). Do NOT use for "this is hard" or "I need more time."
+- **refactor** — Flag a bug, code smell, or tech debt you encounter during implementation. Call **immediately on discovery** — do not wait until your PR is complete. Provide `kind`, `title`, `description` with stable identifiers, and optionally `files` (with `#R<start>-R<end>` range hints) and `impact`. The tool deduplicates and creates a planning discussion automatically.
+- **plan** (action: `escalate`) — Flag a process, architecture, or scope coordination concern as a new discussion. Provide `title` and `body`. Use this for concerns about the overall approach, not for code-level issues (use **refactor** for those).
+
+### Working
+
+Your workspace is already a checkout of **{{{repo}}}** with git fully configured.
+
+**Trust the workspace git setup:**
+- Do NOT clone the repository again, run `git init`, create alternate `.git` directories, or modify git internals.
+- If `ls -la` shows `@` flags on files, that is a macOS extended attribute (harmless). Verify with `git status`, not `ls`.
+- Git credentials and push URLs are pre-configured.
+
+You are on branch `{{{branch}}}`. Use this branch for all your work — do not create other branches.
+
+### Policy Preflight
+
+Before implementation, check whether `AGENTS.md` exists at the repository root. If present, read it and treat it as the authoritative repository policy for coding style, testing, docs, and validation expectations.
+
+### Implementation
+
+1. Read the issue's acceptance criteria and testing strategy.
+2. Write tests first, following the TDD approach described in the issue.
+3. Implement the code to make the tests pass.
+4. Verify your work (see Verification below).
+5. Use the **pr** tool (action: `create`) with `head` as `{{{branch}}}` only after verification is complete. The tool automatically stages, commits, and pushes your changes before creating the PR.
+
+### Verification
+
+Before creating a PR, verify your work passes quality checks. Unverified PRs waste the reviewer's session and delay the entire pipeline:
+
+1. Run the test suite and confirm all tests pass.
+2. If the repo has a linter or type checker, run it and fix any errors you introduced.
+3. Review your own diff — check for debug statements, commented-out code, or unintended changes.
+
+Only create the PR after verification succeeds.
+Your PR `reasoning` must explicitly list the verification commands you ran and confirm they passed.
+
+### Completion Gate
+
+You are **not done until** exactly one terminal outcome is reached:
+
+1. **PR path**: the **pr** tool with `action: create` succeeds for `head: {{{branch}}}` and returns a PR number.
+2. **Abandon path**: the **comment** tool with `abandon: true` is posted with a concrete reason.
+
+Do **not** end your turn with only a local summary, passing tests, or `git status`.
+Do **not stop** at the Codex idle prompt before one terminal outcome above is complete.
+If PR creation fails, diagnose and retry with corrected arguments instead of stopping.
+
+### Documentation
+
+When your changes touch these areas, documentation is mandatory:
+
+- **Architectural changes** (new packages, new modules, changed data flow): create or update architecture diagrams in `docs/` and explain the decision rationale.
+- **Error handling** (new error classes, try/catch blocks, error responses): document each error with resolution steps that anyone can follow regardless of skill level.
+- **New APIs** (exported functions, REST endpoints, tool definitions): document parameters, return shapes, and error behavior in JSDoc and the package README.
+
+### PR Reasoning
+
+When creating a PR, include a `reasoning` parameter summarizing your approach. This is included in the PR body as a collapsible trace for human review.
+
+### Rules
+
+- Stay within the scope defined in the issue's acceptance criteria. Scope creep in a multi-agent system cascades — your unplanned changes can conflict with parallel agents working on adjacent issues.
+- Do not add features or fixes beyond the issue scope. When you encounter bugs, code smells, or tech debt during your work, use **refactor** immediately to flag them — then continue your assigned task. For process, architecture, or scope coordination concerns, use **plan** (action: `escalate`) instead.
+- Commit with descriptive messages following the repo's conventions.
+- When review comments arrive, address them promptly and use **comment** to request re-review.
+- If approaching context limits, commit and push your progress, then post a comment documenting remaining work before stopping.
+
+</instructions>
+
+<output_format>
+
+Structure your PR `reasoning` parameter with:
+
+- **Approach**: What strategy you chose and why.
+- **Key decisions**: Any trade-offs or alternatives you considered.
+- **Verification**: What you tested and how you confirmed correctness.
+
+</output_format>
+
+<examples>
+
+<example title="Well-formed PR reasoning">
+**Approach**: Implemented exponential backoff using a recursive retry wrapper around the existing `fetch` call. Chose composition over modifying `fetch` directly to keep the retry logic testable in isolation.
+
+**Key decisions**: Used jitter via `Math.random() * baseDelay * 0.5` to avoid thundering herd. Capped at 3 retries based on the acceptance criteria. Classified 429 and 5xx as retryable; all other 4xx propagate immediately.
+
+**Verification**: All 5 test scenarios from the issue pass. Ran `pnpm test` — 47/47 passing. Ran `pnpm lint` — no new warnings. Reviewed diff for debug artifacts — clean.
+</example>
+
+</examples>
+
+{{#issue}}
+<context>
+
+## Assigned Issue
+
+You have been assigned the following issue. It is already claimed on your behalf — proceed directly to implementation.
+
+{{{issue}}}
+
+</context>
+{{/issue}}
+
+{{#reviewFeedback}}
+<context>
+
+## Review Feedback
+
+The reviewer **{{reviewer}}** ({{reviewerProvider}}) has requested changes on **PR #{{number}}**:
+
+{{#comments}}
+- {{body}}
+{{/comments}}
+
+Address each item:
+
+1. Make the requested changes.
+2. Run verification again to confirm nothing is broken.
+3. Push your commits.
+4. Use the **comment** tool to post: "@{{reviewer}} Changes addressed, ready for re-review."
+
+</context>
+{{/reviewFeedback}}
+
+{{#hitl}}
+<context>
+
+## Human In The Loop Feedback
+
+A human reviewer has provided feedback on your PR. Their comments are below:
+
+{{#feedback}}
+- **@{{author}}**: {{body}}
+{{/feedback}}
+
+Address each comment carefully:
+
+1. Make the requested changes.
+2. Run verification again to confirm nothing is broken.
+3. Push your commits.
+4. Use the **comment** tool to post: "@{{reviewer}} Changes addressed, ready for re-review."
+5. Do **not** merge — the human reviewer will merge when satisfied.
+
+</context>
+{{/hitl}}
+
+<agent_metadata>
+Faction: {{faction}} | Provider: {{provider}}
+</agent_metadata>