overlord-cli 0.2605101225.0

package/bin/_cli/ticket.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+
+import { buildAuthHeaders, resolveAuth } from './credentials.mjs';
+
+export async function ticketContext(ticketId) {
+  if (!ticketId) {
+    // Fall back to TICKET_ID env var
+    ticketId = process.env.TICKET_ID;
+  }
+
+  if (!ticketId) {
+    console.error('Error: ticket ID is required.\n');
+    console.error('Usage: ovld ticket context <ticketId>');
+    console.error('       TICKET_ID=<id> ovld ticket context');
+    process.exit(1);
+  }
+
+  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveAuth();
+
+  const url = `${platformUrl}/api/protocol/context/${ticketId}`;
+  const res = await fetch(url, {
+    headers: buildAuthHeaders(bearerToken, localSecret, organizationId)
+  });
+
+  if (!res.ok) {
+    throw new Error(`Failed to fetch ticket context (${res.status}): ${await res.text()}`);
+  }
+
+  const text = await res.text();
+  process.stdout.write(text);
+}
+
+export async function runTicketCommand(subcommand, args) {
+  if (!subcommand || subcommand === 'help' || subcommand === '--help') {
+    console.log(`ovld ticket <subcommand>
+
+Subcommands:
+  context <ticketId>   Print ticket context (objective, acceptance criteria, tools)
+
+Examples:
+  ovld ticket context abc-123
+  TICKET_ID=abc-123 ovld ticket context
+`);
+    return;
+  }
+
+  if (subcommand === 'context') {
+    await ticketContext(args[0]);
+    return;
+  }
+
+  console.error(`Unknown ticket subcommand: ${subcommand}\n`);
+  console.log('Run: ovld ticket help');
+  process.exit(1);
+}

package/bin/_cli/tickets.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+
+import { buildAuthHeaders, resolveAuth } from './credentials.mjs';
+import { runCreateCommand } from './new-ticket.mjs';
+
+/**
+ * Parse simple CLI flags: --key value or --key=value
+ * @param {string[]} args
+ * @param {string[]} knownFlags
+ * @returns {Record<string, string | boolean>}
+ */
+function parseFlags(args, knownFlags) {
+  const result = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg.startsWith('--')) {
+      const eqIdx = arg.indexOf('=');
+      if (eqIdx !== -1) {
+        const key = arg.slice(2, eqIdx);
+        result[key] = arg.slice(eqIdx + 1);
+      } else {
+        const key = arg.slice(2);
+        // If the next arg is not a flag, treat it as the value
+        if (i + 1 < args.length && !args[i + 1].startsWith('--')) {
+          result[key] = args[i + 1];
+          i++;
+        } else {
+          result[key] = true;
+        }
+      }
+    }
+  }
+  return result;
+}
+
+async function apiPost(url, token, localSecret, organizationId, body) {
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: {
+      ...buildAuthHeaders(token, localSecret, organizationId),
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify(body)
+  });
+
+  const data = await res.json().catch(() => ({}));
+
+  if (!res.ok) {
+    throw new Error(`API error (${res.status}): ${data.error ?? JSON.stringify(data)}`);
+  }
+
+  return data;
+}
+
+export async function ticketsCreate(args) {
+  await runCreateCommand(args);
+}
+
+export async function ticketsList(args) {
+  const flags = parseFlags(args, ['status', 'include-completed']);
+
+  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveAuth();
+
+  const body = {
+    includeCompleted: flags['include-completed'] !== false,
+    ...(flags.status ? { statuses: [String(flags.status)] } : {})
+  };
+
+  const data = await apiPost(
+    `${platformUrl}/api/protocol/search-tickets`,
+    bearerToken,
+    localSecret,
+    organizationId,
+    body
+  );
+
+  if (!data.tickets?.length) {
+    console.log('No tickets found.');
+    return;
+  }
+
+  for (const t of data.tickets) {
+    const ref = t.id?.slice(-8).toUpperCase() ?? '?';
+    const title = t.title || t.objective?.slice(0, 60) || '(no title)';
+    console.log(`  [${ref}] [${t.status ?? '?'}] ${title}`);
+    console.log(`         ${t.id}`);
+  }
+
+  console.log(`\n${data.count ?? data.tickets.length} ticket(s)`);
+}
+
+export async function runTicketsCommand(subcommand, args) {
+  if (!subcommand || subcommand === 'help' || subcommand === '--help') {
+    console.log(`ovld tickets <subcommand>
+
+Subcommands:
+  create   Create a new ticket
+  list     List tickets
+
+Examples:
+  ovld tickets create "Implement login page"
+  ovld tickets list
+  ovld tickets list --status draft
+`);
+    return;
+  }
+
+  if (subcommand === 'create') {
+    await ticketsCreate(args);
+    return;
+  }
+
+  if (subcommand === 'list') {
+    await ticketsList(args);
+    return;
+  }
+
+  console.error(`Unknown tickets subcommand: ${subcommand}\n`);
+  console.log('Run: ovld tickets help');
+  process.exit(1);
+}

package/bin/_cli/version.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+
+import { getCurrentCliVersion } from './cli-update.mjs';
+
+export function runVersionCommand() {
+  console.log(`Overlord CLI ${getCurrentCliVersion()}`);
+}

package/bin/ovld.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+
+/**
+ * Canonical CLI entrypoint. Used by both the npm package and the Electron app.
+ * All CLI source files live in _cli/ alongside this file.
+ */
+
+import { runCli } from './_cli/index.mjs';
+
+runCli({ primaryCommand: 'ovld' }).catch((error) => {
+  console.error(error instanceof Error ? error.message : error);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "overlord-cli",
+  "version": "0.2605101225.0",
+  "description": "Overlord CLI — launch AI agents on tickets from anywhere",
+  "homepage": "https://www.ovld.ai/docs/",
+  "type": "module",
+  "bin": {
+    "overlord": "bin/ovld.mjs",
+    "ovld": "bin/ovld.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "bin/",
+    "plugins/"
+  ],
+  "scripts": {
+    "postinstall": "node bin/_cli/postinstall.mjs || true"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "overlord",
+    "ai",
+    "agents",
+    "cli"
+  ],
+  "license": "Proprietary",
+  "repository": {
+    "private": true,
+    "type": "git",
+    "url": "git+https://github.com/cooperativ-labs/overlord/packages/overlord-cli.git"
+  }
+}

package/plugins/claude/.claude-plugin/plugin.json

@@ -0,0 +1,34 @@
+{
+  "name": "overlord",
+  "version": "0.1.0",
+  "description": "Overlord ticket protocol workflow for Claude Code — attach/update/ask/deliver, slash commands, and a PermissionRequest notifier.",
+  "author": {
+    "name": "Cooperativ",
+    "url": "https://github.com/cooperativ"
+  },
+  "homepage": "https://www.ovld.ai",
+  "repository": "https://github.com/cooperativ/overlord",
+  "license": "UNLICENSED",
+  "keywords": [
+    "overlord",
+    "tickets",
+    "agents",
+    "workflow",
+    "protocol",
+    "claude-code"
+  ],
+  "userConfig": {
+    "overlord_url": {
+      "type": "string",
+      "title": "Overlord URL",
+      "description": "Overlord platform URL (e.g. https://www.ovld.ai or http://localhost:3000).",
+      "sensitive": false
+    },
+    "agent_token": {
+      "type": "string",
+      "title": "Agent token",
+      "description": "Overlord agent token. Pull from Overlord Settings → Agents & MCP or from ~/.ovld/credentials.json.",
+      "sensitive": true
+    }
+  }
+}

package/plugins/claude/README.md

@@ -0,0 +1,42 @@
+# Overlord — Claude Code plugin
+
+Claude Code plugin that exposes the Overlord local ticket workflow to any Claude Code surface (CLI, VS Code extension, Claude Code desktop app).
+
+## What ships
+
+- `skills/overlord-ticket/SKILL.md` — durable attach → update → ask → deliver workflow.
+- `commands/{connect,load,create,prompt}.md` — slash commands for session routing and ticket creation.
+- `hooks/hooks.json` + `scripts/permission-hook.sh` — PermissionRequest notifier that calls `ovld protocol permission-request`.
+- If `ovld` reports `OVERLORD_URL` is unreachable, the workflow tells agents to request permission escalation or network access before retrying.
+- `userConfig` for `overlord_url`. Current installs should authenticate with `ovld auth repair` first when a shared session already exists, then `ovld auth login` or Overlord Desktop; env vars remain optional overrides for remote shells, CI, and explicit OAuth token injection.
+
+## Requirements
+
+- Overlord CLI (`ovld`) on `PATH`. See the Overlord docs / Settings → Agents & MCP.
+- `TICKET_ID` is exported automatically when a Claude session is launched from Overlord; outside that launch, set it manually before calling the permission hook.
+
+## Install (local dev)
+
+```bash
+claude --plugin-dir /absolute/path/to/overlord/plugins/claude
+```
+
+## Install (marketplace)
+
+Once published:
+
+```bash
+claude plugin marketplace add cooperativ/overlord-marketplace
+claude plugin install overlord@cooperativ
+```
+
+Older plugin versions prompted for `overlord_url` and a legacy token at install time. The current hook goes through `ovld protocol`, so the CLI resolves auth from env vars or the shared `~/.ovld` credentials written by CLI/Desktop login.
+
+## Namespaced components
+
+Inside Claude Code the components are surfaced with the plugin prefix:
+
+- skill → `overlord:overlord-ticket`
+- commands → `/overlord:connect`, `/overlord:load`, `/overlord:create`, `/overlord:prompt`
+
+Prompts generated by Overlord (see `lib/overlord/ticket-prompt.ts`) already reference these names in `bundle` instruction mode.

package/plugins/claude/commands/connect.md

@@ -0,0 +1,19 @@
+---
+description: Connect this session to another Overlord ticket by ticket ID
+argument-hint: <ticket_id>
+disable-model-invocation: true
+---
+
+Connect this session to another Overlord ticket.
+
+Treat `$ARGUMENTS` as the target ticket ID.
+If no ticket ID was provided, ask the user for one and stop.
+
+Run:
+`ovld protocol connect --ticket-id <ticketId>`
+
+Rules:
+- Use `connect`, not `attach`.
+- Do not load extra ticket context unless the user explicitly asks for it.
+- After the command succeeds, report the returned `SESSION_KEY` and confirm that future updates should use that ticket.
+- If `ovld` reports `OVERLORD_URL` is unreachable, stop and request permission escalation or network access before retrying.

package/plugins/claude/commands/create.md

@@ -0,0 +1,17 @@
+---
+description: Create a draft Overlord ticket from the current conversation
+argument-hint: <objective or raw flags>
+disable-model-invocation: true
+---
+
+Create a draft Overlord ticket from the user's request.
+
+Use `$ARGUMENTS` as the input.
+If it already contains flags such as `--title`, `--priority`, `--project-id`, or `--execution-target`, pass those flags through after `ovld protocol create --agent claude-code`.
+Otherwise, treat `$ARGUMENTS` as the objective text and run:
+`ovld protocol create --agent claude-code --objective "<objective>"`
+
+If no objective was provided, ask the user for one and stop.
+
+After the command succeeds, report the new `TICKET_ID`.
+- If `ovld` reports `OVERLORD_URL` is unreachable, stop and request permission escalation or network access before retrying.

package/plugins/claude/commands/load.md

@@ -0,0 +1,19 @@
+---
+description: Load Overlord ticket context without creating a new session
+argument-hint: <ticket_id>
+disable-model-invocation: true
+---
+
+Load Overlord ticket context without attaching to the ticket.
+
+Treat `$ARGUMENTS` as the target ticket ID.
+If no ticket ID was provided, ask the user for one and stop.
+
+Run:
+`ovld protocol load-context --ticket-id <ticketId>`
+
+Rules:
+- Use `load-context`, not `attach`.
+- Do not create or switch sessions.
+- Summarize the returned ticket details, history, artifacts, and shared context for the user.
+- If `ovld` reports `OVERLORD_URL` is unreachable, stop and request permission escalation or network access before retrying.

package/plugins/claude/commands/spawn.md

@@ -0,0 +1,17 @@
+---
+description: Create a new Overlord ticket from the current conversation
+argument-hint: <objective or raw flags>
+disable-model-invocation: true
+---
+
+Create a new Overlord ticket from the user's request.
+
+Use `$ARGUMENTS` as the input.
+If it already contains flags such as `--title`, `--priority`, `--project-id`, or `--execution-target`, pass those flags through after `ovld protocol spawn --agent claude-code`.
+Otherwise, treat `$ARGUMENTS` as the objective text and run:
+`ovld protocol spawn --agent claude-code --objective "<objective>"`
+
+If no objective was provided, ask the user for one and stop.
+
+After the command succeeds, report the new `TICKET_ID` and `SESSION_KEY`.
+- If `ovld` reports `OVERLORD_URL` is unreachable, stop and request permission escalation or network access before retrying.

package/plugins/claude/hooks/hooks.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PermissionRequest": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/permission-hook.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/claude/scripts/permission-hook.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+# Overlord PermissionRequest notification hook (plugin-managed).
+#
+# Prefers plugin userConfig values (CLAUDE_PLUGIN_OPTION_*) when set, and falls
+# back to the raw OVERLORD_URL / OVERLORD_ACCESS_TOKEN env vars Overlord-launched
+# shells already export. Silently no-ops if we can't authenticate — the hook must
+# never block the user or leak errors into the Claude session.
+BODY=$(cat -)
+OVERLORD_BASE_URL="${CLAUDE_PLUGIN_OPTION_OVERLORD_URL:-$OVERLORD_URL}"
+OVERLORD_TOKEN="${CLAUDE_PLUGIN_OPTION_OVERLORD_ACCESS_TOKEN:-$OVERLORD_ACCESS_TOKEN}"
+if [ -n "$OVERLORD_BASE_URL" ] && [ -n "$OVERLORD_TOKEN" ] && [ -n "$TICKET_ID" ]; then
+  curl -sf -m 5 \
+    -X POST "$OVERLORD_BASE_URL/api/protocol/permission-request?ticketId=$TICKET_ID" \
+    -H "Authorization: Bearer $OVERLORD_TOKEN" \
+    -H "X-Overlord-Local-Secret: $OVERLORD_LOCAL_SECRET" \
+    -H "Content-Type: application/json" \
+    -d "$BODY" \
+    >/dev/null 2>&1 &
+  disown
+fi
+exit 0

package/plugins/claude/skills/overlord-ticket/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: overlord-ticket
+description: Overlord local workflow protocol for Claude Code, covering both Overlord-launched tickets and chat-invoked Overlord work.
+---
+
+# Overlord Ticket
+
+Use this skill whenever Claude Code needs to work with Overlord, whether the session was launched by Overlord Desktop/CLI or the user asks from chat to engage with Overlord.
+
+## Mode 1: Launched From Overlord Desktop Or CLI
+
+Use this mode when the prompt already contains a ticket ID or explicitly says the session was launched by Overlord.
+
+1. Attach first with `ovld protocol attach --ticket-id <ticket_id>`.
+2. Keep the returned `session.sessionKey` for all follow-up calls.
+3. Treat the Overlord ticket prompt as authoritative for the objective, constraints, and delivery target.
+4. Post updates while working with `ovld protocol update --phase execute`.
+5. If the user sends a follow-up message after the initial ticket, publish it immediately with `--event-type user_follow_up`.
+6. If blocked, call `ovld protocol ask` and stop.
+7. Deliver last with `ovld protocol deliver`, including `changeRationales` for each meaningful behavioral file change.
+
+### Mode 1 Reference
+
+Attach:
+
+```bash
+ovld protocol attach --ticket-id $TICKET_ID
+```
+
+Update:
+
+```bash
+ovld protocol update --session-key <sessionKey> --ticket-id $TICKET_ID --summary "What you did and why." --phase execute
+```
+
+Supported `--phase` values:
+- `draft`
+- `execute`
+- `review`
+- `deliver`
+- `complete`
+- `blocked`
+- `cancelled`
+
+These are hardcoded CLI-supported values for the `--phase` flag. They are not user-defined phase types.
+
+Event types:
+- `update` for standard progress updates
+- `user_follow_up` for human follow-up messages after the initial ticket
+- `alert` for warnings or non-blocking issues
+
+Ask when blocked:
+
+```bash
+ovld protocol ask --session-key <sessionKey> --ticket-id $TICKET_ID --question "Specific question for the PM."
+```
+
+Deliver:
+
+```bash
+ovld protocol deliver --session-key <sessionKey> \
+  --ticket-id $TICKET_ID \
+  --summary "Narrative: what you did, next steps." \
+  --artifacts-json '[{"type":"next_steps","label":"Next steps","content":"..."}]' \
+  --change-rationales-json '[{"label":"Short reviewer title","file_path":"path/to/file.ts","summary":"What changed.","why":"Why it changed.","impact":"Behavioral impact.","hunks":[{"header":"@@ -10,6 +10,14 @@"}]}]'
+```
+
+For larger delivery payloads, prefer `--payload-file -` and stream the full JSON on stdin so no scratch file needs to be created or removed. If you use `--payload-file`, `--artifacts-file`, or `--change-rationales-file` with a real path, treat that file as ephemeral scratch data outside the repository and remove it after delivery.
+
+## Mode 2: Asked From Chat To Use Overlord
+
+Use this mode when the conversation starts normally and the user asks Claude to create, inspect, connect to, or otherwise use Overlord.
+
+1. If the user wants to create tickets (and does not ask to start execution), run `ovld protocol create --agent claude-code --objective "..."`.
+   - When `--session-key` and `--ticket-id` are provided, it creates a follow-up draft.
+   - When session flags are omitted, it resolves the project by matching current working directory (or `--working-directory`) to the caller's configured Overlord `project_user.local_working_directory`, then creates a standalone draft.
+2. Default to `create` for new tickets. Only use `/overlord:spawn` or `ovld protocol spawn --agent claude-code --objective "..."` when the user explicitly asks to create and execute immediately.
+   `spawn` creates the ticket in `execute` status and attaches immediately.
+3. If the user already has a ticket ID and only wants to inspect it, use `/overlord:load` or run `ovld protocol load-context --ticket-id <ticket_id>`.
+4. If the user wants to route the current session onto an existing ticket by ID, use `/overlord:connect` or run `ovld protocol connect --ticket-id <ticket_id>`.
+5. If the user wants to find a ticket but does not know the ID, use `ovld attach` for interactive ticket search and agent launch, or ask the user for the ticket ID if staying strictly inside chat is the better fit.
+6. If you need other lifecycle commands or flags, run `ovld protocol help` and use the real subcommand list instead of guessing.
+7. Once you attach to a ticket, switch back to Mode 1 and follow the full ticket lifecycle.
+
+## Change Rationales
+
+Always include `changeRationales` when delivering. Optionally include them on updates during long-running work.
+
+Before delivering, make sure every meaningful git-tracked file change is represented in `changeRationales`; do not send `file_changes` as an artifact.
+
+These are structured protocol payloads that Overlord stores as first-class rows in the `file_changes` table. Prefer inline JSON or the dedicated command below. For larger full delivery payloads, prefer `--payload-file -` so summary, artifacts, and change rationales stay in one JSON document without creating a temporary file. Ordinary deliver artifacts should use `next_steps`, `test_results`, `migration`, `note`, `url`, or `decision`.
+
+```bash
+ovld protocol record-change-rationales --session-key <sessionKey> --ticket-id $TICKET_ID \
+  --summary "Recorded rationale details for the latest code changes." --phase execute \
+  --change-rationales-json '[{"label":"Add backoff","file_path":"lib/api.ts","summary":"Added retry.","why":"Transient failures.","impact":"Retries 3x.","hunks":[{"header":"@@ -22,4 +22,18 @@"}]}]'
+```
+
+```bash
+ovld protocol update --session-key <sessionKey> --ticket-id $TICKET_ID \
+  --summary "Added retry logic." --phase execute \
+  --change-rationales-json '[{"label":"Add backoff","file_path":"lib/api.ts","summary":"Added retry.","why":"Transient failures.","impact":"Retries 3x.","hunks":[{"header":"@@ -22,4 +22,18 @@"}]}]'
+```
+
+Record only meaningful behavioral changes. Skip formatting-only noise.
+
+## Project Discovery And Ticket Creation
+
+When creating tickets from within a repository:
+- Prefer `create` by default for draft ticket creation.
+- Use `spawn` only when the user explicitly asks to start execution immediately.
+- Both commands can resolve the project from the current working directory; use `--working-directory` to override.
+
+```bash
+ovld protocol create --agent claude-code --objective "Capture follow-up work from this repository"
+```
+
+```bash
+ovld protocol spawn --agent claude-code --objective "Implement feature X" --priority medium
+```
+
+To inspect project resolution explicitly:
+
+```bash
+ovld protocol discover-project
+```
+
+You can override with `--project-id` or `--working-directory` if needed.
+
+### Choosing `--execution-target`
+
+Pass `--execution-target agent` or `--execution-target human` (default: `human`) when creating tickets.
+
+- **`agent`** — any task an AI agent can complete in a computer environment: coding, internet research, document editing, data analysis, automated testing, etc.
+- **`human`** — any task requiring human presence or judgment: setting credentials or tokens in a third-party UI (e.g. Vercel, AWS), sending physical mail, making a product or business decision, physical-world actions.
+
+When in doubt, ask yourself: *can this be done entirely inside a terminal or browser by an AI without human intervention?* If yes → `agent`. If it requires a human to log in, decide, or act in the real world → `human`.
+
+## Context And Artifacts
+
+```bash
+ovld protocol read-context --session-key <sessionKey> --ticket-id $TICKET_ID
+ovld protocol write-context --session-key <sessionKey> --ticket-id $TICKET_ID --key "key" --value '"json-value"'
+ovld protocol attachment-list --session-key <sessionKey> --ticket-id $TICKET_ID
+ovld protocol attachment-upload-file --session-key <sessionKey> --ticket-id $TICKET_ID --objective-id <objective-id> --file ./spec.pdf --content-type application/pdf
+ovld protocol attachment-download-url --session-key <sessionKey> --ticket-id $TICKET_ID --attachment-id <attachment-id>
+```
+
+The `attach` and `load-context` responses already include `attachments` and `objectives` arrays — use those for `<attachment-id>` and `<objective-id>` values. Run `attachment-list` mid-session if new files have been uploaded since attach.
+
+## Rules
+
+- Always attach first and always deliver last once you are on a ticket.
+- Use `ovld protocol` commands and the plugin's slash commands instead of ad hoc scripts.
+- Do not invent protocol subcommands. Use `ovld protocol help` when unsure.
+- The `summary` in deliver is what the PM reads first, so write it as a narrative, not a command list.
+- Use `write-context` for facts a future agent session should know.
+- If `ovld` reports `OVERLORD_URL` is unreachable, request permission escalation or network access before retrying.
+- If a protocol or MCP call fails with auth/session errors, run `ovld auth repair` yourself before asking the user to log in again or proceed without Overlord updates.
+- If you must run `ovld auth login`, always include `--organization-id <id>` — use the organization ID from the ticket prompt context to select the organization non-interactively and avoid a blocking TTY prompt.
+- Do not add or commit changes unless the user explicitly asks you to commit.
+- Delivery is the concluding step. After delivering, stop unless the user follows up or the ticket is reopened.
+
+<!-- version: 0.2.6 -->

package/plugins/cursor/.cursor-plugin/plugin.json

@@ -0,0 +1,14 @@
+{
+  "name": "overlord",
+  "version": "0.1.0",
+  "description": "Local Overlord workflow plugin for Cursor terminal agents.",
+  "author": {
+    "name": "Cooperativ",
+    "url": "https://github.com/cooperativ"
+  },
+  "homepage": "https://github.com/cooperativ/overlord",
+  "repository": "https://github.com/cooperativ/overlord",
+  "license": "UNLICENSED",
+  "skills": "./skills/",
+  "mcpServers": "./mcp.json"
+}

package/plugins/cursor/commands/connect.md

@@ -0,0 +1,3 @@
+Run `ovld protocol connect --ticket-id <ticketId>` using the text after `/connect`.
+
+If `ovld` reports `OVERLORD_URL` is unreachable, stop and request permission escalation or network access before retrying.

package/plugins/cursor/commands/create.md

@@ -0,0 +1,11 @@
+Create a draft Overlord ticket.
+
+Use the text after `/create` as the objective unless raw flags are present.
+
+Run:
+`ovld protocol create --agent cursor --objective "<objective>"`
+
+If raw flags are present, pass them through after:
+`ovld protocol create --agent cursor`
+
+If `ovld` reports `OVERLORD_URL` is unreachable, stop and request permission escalation or network access before retrying.

package/plugins/cursor/commands/load.md

@@ -0,0 +1,3 @@
+Run `ovld protocol load-context --ticket-id <ticketId>` using the text after `/load`.
+
+If `ovld` reports `OVERLORD_URL` is unreachable, stop and request permission escalation or network access before retrying.

package/plugins/cursor/commands/spawn.md

@@ -0,0 +1,3 @@
+Run `ovld protocol spawn --agent cursor --objective "<objective>"` using text after `/spawn` unless raw flags were provided.
+
+If `ovld` reports `OVERLORD_URL` is unreachable, stop and request permission escalation or network access before retrying.

package/plugins/cursor/mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "overlord": {
+      "command": "node",
+      "args": ["./scripts/overlord-mcp.mjs"]
+    }
+  }
+}

package/plugins/cursor/rules/overlord-local.mdc

@@ -0,0 +1,10 @@
+---
+description: Overlord local workflow protocol for Cursor.
+alwaysApply: true
+---
+
+# Overlord Local Workflow
+
+- If the session was launched by Overlord Desktop or CLI, attach first with `ovld protocol attach --ticket-id $TICKET_ID`, update during work, ask when blocked, and deliver last.
+- If the user asks from chat to use Overlord, use `/spawn` for new tickets, `/load` for read-only context by ticket ID, `/connect` to route the session onto an existing ticket, and `search_tickets` to find tickets by keyword or status.
+- If you need other protocol commands or flags, run `ovld protocol help` instead of guessing.