overlord-cli 3.25.0 → 4.0.0

package/README.md

@@ -37,6 +37,7 @@ ovld protocol discover-project
 ovld protocol attach --ticket-id <ticket-id>
 ovld protocol update --session-key <session-key> --ticket-id <ticket-id> --summary "Working on it" --phase execute
 ovld setup codex
+ovld setup claude
 ovld setup cursor
 ovld setup gemini
 ovld setup all
@@ -59,7 +60,7 @@ ovld doctor
 - `protocol` - run ticket lifecycle commands such as `discover-project`, `attach`, `connect`, `load-context`, `spawn`, `update`, `record-change-rationales`, `ask`, `read-context`, `write-context`, `deliver`, and artifact upload/download helpers
 - `connect`, `restart`, `context` - launch or resume an agent session or print ticket context
 - `run`, `resume` - legacy aliases for `connect` and `restart`
-- `setup` - install the Overlord connector or plugin bundle for a supported agent
+- `setup` - prepare the Overlord plugin or connector for a supported agent; `ovld setup claude` performs the one-time v3.25.0 to v4 Claude plugin migration
 - `update` - install the latest CLI release from npm
 - `doctor` - verify installed agent connectors and check whether a newer CLI version is available
 

package/bin/_cli/launcher.mjs

@@ -9,10 +9,25 @@ import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { buildAuthHeaders, resolveAuth } from './credentials.mjs';
 import { runAttachCommand } from './attach.mjs';
 
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE_CLAUDE_PLUGIN_DIR = path.resolve(__dirname, '..', '..', 'plugins', 'claude');
+const REPO_CLAUDE_PLUGIN_DIR = path.resolve(__dirname, '..', '..', '..', '..', 'plugins', 'claude');
+
+function claudeSourcePluginDir() {
+  if (fs.existsSync(PACKAGE_CLAUDE_PLUGIN_DIR)) return PACKAGE_CLAUDE_PLUGIN_DIR;
+  if (fs.existsSync(REPO_CLAUDE_PLUGIN_DIR)) return REPO_CLAUDE_PLUGIN_DIR;
+  return null;
+}
+
 function getInstructionMode(agent) {
+  if (agent === 'claude') {
+    return claudeSourcePluginDir() ? 'bundle' : 'legacy';
+  }
+
   if (agent === 'codex') {
     const pluginManifest = path.join(
       os.homedir(),
@@ -108,20 +123,24 @@ async function runAgent(agent, mode = 'run') {
 
   try {
     if (agent === 'claude') {
+      const pluginDir = claudeSourcePluginDir();
       if (mode === 'resume') {
         const claudeSessionId = process.env.CLAUDE_SESSION_ID?.trim();
         const args = claudeSessionId
           ? ['--resume', claudeSessionId, context]
           : ['--continue', context];
+        if (pluginDir) args.unshift('--plugin-dir', pluginDir);
         execFileSync('claude', args, { stdio: 'inherit', env: childEnv });
       } else {
+        const args = [
+          '--append-system-prompt',
+          context,
+          'Begin working on this ticket. Start by calling the attach endpoint, then proceed with the objective described in your system prompt.'
+        ];
+        if (pluginDir) args.unshift('--plugin-dir', pluginDir);
         execFileSync(
           'claude',
-          [
-            '--append-system-prompt',
-            context,
-            'Begin working on this ticket. Start by calling the attach endpoint, then proceed with the objective described in your system prompt.'
-          ],
+          args,
           { stdio: 'inherit', env: childEnv }
         );
       }

package/bin/_cli/postinstall.mjs

@@ -27,15 +27,16 @@ const bold = s => `\x1b[1m${s}\x1b[0m`;
 console.log(`
 ${green('✓')} Overlord CLI installed successfully!
 
-${bold('Next step:')} Configure agent connectors
+${bold('Next step:')} Prepare agent plugins and connectors
 
   ${cyan('ovld setup')}
 
 This will guide you through:
-  • Selecting which agent connectors to install (Claude, Cursor, etc.)
+  • Selecting which agent plugins/connectors to prepare (Claude, Cursor, etc.)
+  • Migrating Claude from the v3.25 connector files to the v4 plugin
   • Configuring agent permissions for Overlord protocol access
 
-You can also run ${cyan('ovld setup <agent>')} to install a specific agent connector,
+You can also run ${cyan('ovld setup <agent>')} to prepare a specific agent,
 or ${cyan('ovld doctor')} to check your installation status.
 
 Run ${cyan('ovld help')} to see all available commands.

package/bin/_cli/setup.mjs

@@ -22,6 +22,8 @@ const MANIFEST_FILE = path.join(MANIFEST_DIR, 'bundle-manifest.json');
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PACKAGE_PLUGIN_DIR = path.resolve(__dirname, '..', '..', 'plugins', 'overlord');
 const REPO_PLUGIN_DIR = path.resolve(__dirname, '..', '..', '..', '..', 'plugins', 'overlord');
+const PACKAGE_CLAUDE_PLUGIN_DIR = path.resolve(__dirname, '..', '..', 'plugins', 'claude');
+const REPO_CLAUDE_PLUGIN_DIR = path.resolve(__dirname, '..', '..', '..', '..', 'plugins', 'claude');
 const CODEX_TARGET_PLUGIN_DIR = path.join(os.homedir(), '.codex', 'plugins', 'overlord');
 const CODEX_TARGET_PLUGIN_MANIFEST = path.join(
   CODEX_TARGET_PLUGIN_DIR,
@@ -459,11 +461,22 @@ function installSlashCommands(agent) {
   };
 }
 
+function uninstallSlashCommands(agent) {
+  const removedFiles = [];
+  const files = slashCommandFiles(agent);
+  for (const file of files) {
+    if (!fs.existsSync(file.path)) continue;
+    const existing = readTextFile(file.path);
+    if (existing.trim() !== file.content.trim()) continue;
+    fs.rmSync(file.path, { force: true });
+    removedFiles.push(file.path);
+  }
+  return { removedFiles };
+}
+
 function currentContentHashForAgent(agent) {
   if (agent === 'claude') {
-    return contentHash(
-      [CLAUDE_SKILL_CONTENT, PERMISSION_HOOK_SCRIPT, ...slashCommandFiles('claude').map(file => file.content)].join('\n')
-    );
+    return claudeContentHash();
   }
   if (agent === 'cursor') {
     return contentHash(
@@ -487,6 +500,14 @@ function codexSourcePluginDir() {
   );
 }
 
+function claudeSourcePluginDir() {
+  if (fs.existsSync(PACKAGE_CLAUDE_PLUGIN_DIR)) return PACKAGE_CLAUDE_PLUGIN_DIR;
+  if (fs.existsSync(REPO_CLAUDE_PLUGIN_DIR)) return REPO_CLAUDE_PLUGIN_DIR;
+  throw new Error(
+    `Claude plugin bundle not found. Checked ${PACKAGE_CLAUDE_PLUGIN_DIR} and ${REPO_CLAUDE_PLUGIN_DIR}.`
+  );
+}
+
 function listFilesRecursive(dir) {
   if (!fs.existsSync(dir)) return [];
   return fs.readdirSync(dir, { withFileTypes: true }).flatMap(entry => {
@@ -496,8 +517,7 @@ function listFilesRecursive(dir) {
   });
 }
 
-function codexContentHash() {
-  const sourceDir = codexSourcePluginDir();
+function contentHashForDirectory(sourceDir) {
   const hash = crypto.createHash('sha256');
 
   for (const filePath of listFilesRecursive(sourceDir).sort()) {
@@ -510,6 +530,14 @@ function codexContentHash() {
   return hash.digest('hex').slice(0, 16);
 }
 
+function codexContentHash() {
+  return contentHashForDirectory(codexSourcePluginDir());
+}
+
+function claudeContentHash() {
+  return contentHashForDirectory(claudeSourcePluginDir());
+}
+
 function mergeCodexRules(existingContent) {
   const managedBlock = [
     CODEX_RULES_START,
@@ -621,6 +649,62 @@ function removeLegacyCodexBundle() {
   writeManifest(manifest);
 }
 
+function removeLegacyClaudeBundle() {
+  const paths = claudePaths();
+  const removed = [];
+
+  if (fs.existsSync(paths.skillDir)) {
+    fs.rmSync(paths.skillDir, { recursive: true, force: true });
+    removed.push(paths.skillDir);
+  }
+
+  if (fs.existsSync(paths.hookScript)) {
+    fs.rmSync(paths.hookScript, { force: true });
+    removed.push(paths.hookScript);
+  }
+
+  const slashResult = uninstallSlashCommands('claude');
+  removed.push(...slashResult.removedFiles);
+
+  if (fs.existsSync(paths.settingsFile)) {
+    const settings = readJsonFile(paths.settingsFile);
+    let changed = false;
+
+    if (settings.__overlord_managed) {
+      delete settings.__overlord_managed;
+      changed = true;
+    }
+
+    const hooks = settings.hooks && typeof settings.hooks === 'object' ? settings.hooks : {};
+    if (Array.isArray(hooks.PermissionRequest)) {
+      const nextPermissionHooks = hooks.PermissionRequest.filter(hook => {
+        if (hook && typeof hook === 'object' && Array.isArray(hook.hooks)) {
+          return !hook.hooks.some(
+            inner =>
+              typeof inner?.command === 'string' &&
+              inner.command.includes('overlord-permission-hook')
+          );
+        }
+        return true;
+      });
+      if (nextPermissionHooks.length !== hooks.PermissionRequest.length) {
+        changed = true;
+        if (nextPermissionHooks.length > 0) hooks.PermissionRequest = nextPermissionHooks;
+        else delete hooks.PermissionRequest;
+      }
+    }
+
+    if (changed) {
+      if (Object.keys(hooks).length > 0) settings.hooks = hooks;
+      else delete settings.hooks;
+      writeJsonFile(paths.settingsFile, settings);
+      removed.push(paths.settingsFile);
+    }
+  }
+
+  return removed;
+}
+
 // ---------------------------------------------------------------------------
 // Install
 // ---------------------------------------------------------------------------
@@ -660,82 +744,30 @@ function geminiPaths() {
 }
 
 function installClaude() {
-  const paths = claudePaths();
-  const backups = [];
-
-  // 1. Install skill file
-  writeTextFile(paths.skillFile, CLAUDE_SKILL_CONTENT);
-  console.log(`  ✓ Installed skill: ${paths.skillFile}`);
-
-  // 2. Install permission hook
-  writeTextFile(paths.hookScript, PERMISSION_HOOK_SCRIPT, 0o755);
-  console.log(`  ✓ Installed hook: ${paths.hookScript}`);
-
-  // 3. Merge hook into settings.json
-  const backup = backupFile(paths.settingsFile);
-  if (backup) {
-    backups.push(backup);
-    console.log(`  ✓ Backed up: ${paths.settingsFile} → ${path.basename(backup)}`);
+  const sourceDir = claudeSourcePluginDir();
+  const sourceManifest = path.join(sourceDir, '.claude-plugin', 'plugin.json');
+  const sourceVersion = pluginVersion(sourceManifest) ?? '0.0.0';
+  const removed = removeLegacyClaudeBundle();
+
+  console.log(`  ✓ Found Claude plugin source: ${sourceDir}`);
+  if (removed.length > 0) {
+    console.log('  ✓ Migrated v3.25 Claude connector files:');
+    for (const filePath of removed) console.log(`      ${filePath}`);
+  } else {
+    console.log('  ✓ No v3.25 Claude connector files needed migration.');
   }
+  console.log('  ✓ `ovld connect claude` now loads this plugin with `claude --plugin-dir`.');
 
-  const existingSettings = readJsonFile(paths.settingsFile);
-  const overlordHook = {
-    matcher: '.*',
-    hooks: [{ type: 'command', command: paths.hookScript }]
-  };
-
-  const existingHooks = existingSettings.hooks ?? {};
-  const existingPermHooks = Array.isArray(existingHooks.PermissionRequest)
-    ? existingHooks.PermissionRequest
-    : [];
-  const existingPermissions =
-    existingSettings.permissions && typeof existingSettings.permissions === 'object'
-      ? existingSettings.permissions
-      : {};
-  const mergedAllow = Array.from(
-    new Set([
-      ...asStringArray(existingPermissions.allow),
-      'Bash(ovld protocol:*)',
-      'Bash(curl -sS -X POST:*)'
-    ])
-  );
-
-  // Remove existing Overlord hooks
-  const filteredPermHooks = existingPermHooks.filter(hook => {
-    if (hook && typeof hook === 'object' && hook.hooks) {
-      return !hook.hooks.some(
-        inner =>
-          typeof inner.command === 'string' && inner.command.includes('overlord-permission-hook')
-      );
-    }
-    return true;
-  });
-
-  const merged = deepClone(existingSettings);
-  merged.hooks = { ...existingHooks, PermissionRequest: [...filteredPermHooks, overlordHook] };
-  merged.permissions = { ...existingPermissions, allow: mergedAllow };
-  merged.__overlord_managed = {
-    version: BUNDLE_VERSION,
-    paths: ['hooks.PermissionRequest', 'permissions.allow'],
-    updatedAt: new Date().toISOString()
-  };
-  writeJsonFile(paths.settingsFile, merged);
-  console.log(`  ✓ Merged hook into: ${paths.settingsFile}`);
-
-  const slashResult = installSlashCommands('claude');
-  backups.push(...slashResult.backups);
-
-  // 4. Update manifest
   const manifest = readManifest();
   manifest.claude = {
-    version: BUNDLE_VERSION,
+    version: sourceVersion,
     contentHash: currentContentHashForAgent('claude'),
     installedAt: new Date().toISOString(),
-    files: [paths.skillFile, paths.hookScript, paths.settingsFile, ...slashResult.managedFiles]
+    files: listFilesRecursive(sourceDir)
   };
   writeManifest(manifest);
 
-  return { ok: true, backups };
+  return { ok: true, backups: [] };
 }
 
 function installOpenCode() {
@@ -923,7 +955,9 @@ function doctorAgent(agent) {
   }
 
   const currentVersion =
-    agent === 'codex'
+    agent === 'claude'
+      ? pluginVersion(path.join(claudeSourcePluginDir(), '.claude-plugin', 'plugin.json'))
+      : agent === 'codex'
       ? pluginVersion(path.join(codexSourcePluginDir(), '.codex-plugin', 'plugin.json'))
       : BUNDLE_VERSION;
   const currentHash = currentContentHashForAgent(agent);
@@ -1346,12 +1380,12 @@ export async function runSetupCommand(args) {
   if (agent === '--help' || agent === '-h' || agent === 'help') {
     console.log(`Usage:
   ovld setup           Interactive setup (select agents and configure permissions)
-  ovld setup claude    Install Overlord bundle for Claude Code
+  ovld setup claude    Prepare the Overlord Claude plugin and migrate v3.25 connector files
   ovld setup codex     Install Overlord Codex plugin bundle
   ovld setup cursor    Install Overlord rules, slash commands, and permissions for Cursor
   ovld setup gemini    Install Overlord slash commands and policy rules for Gemini CLI
   ovld setup opencode  Install Overlord connector for OpenCode
-  ovld setup all       Install for all supported agents
+  ovld setup all       Prepare all supported agents
   ovld doctor          Validate installed connectors and check for CLI updates`);
     return;
   }
@@ -1373,7 +1407,7 @@ export async function runSetupCommand(args) {
     });
 
     const selectedLabels = await runCheckboxPrompt({
-      message: 'Select agent connectors to install (Space to toggle, Enter to confirm):',
+      message: 'Select agent plugins/connectors to prepare (Space to toggle, Enter to confirm):',
       choices: agentLabels,
       defaults: []
     });
@@ -1387,7 +1421,7 @@ export async function runSetupCommand(args) {
     const selectedAgents = selectedLabels.map(label => label.split('-')[0].trim());
 
     // Step 2: Install selected agents
-    console.log(`\nInstalling Overlord agent bundles for: ${selectedAgents.join(', ')}...\n`);
+    console.log(`\nPreparing Overlord agent plugins/connectors for: ${selectedAgents.join(', ')}...\n`);
 
     const installedAgents = [];
     for (const a of selectedAgents) {
@@ -1416,7 +1450,7 @@ export async function runSetupCommand(args) {
     );
 
     if (agentsThatNeedPermissions.length > 0) {
-      console.log('Agent connectors installed successfully!\n');
+      console.log('Agent plugins/connectors prepared successfully!\n');
 
       const shouldInstallPermissions = await askYesNo(
         'Would you like to configure agent permissions for Overlord protocol access?',
@@ -1439,7 +1473,7 @@ export async function runSetupCommand(args) {
   }
 
   if (agent === 'all') {
-    console.log('Installing Overlord agent bundle for all supported agents...\n');
+    console.log('Preparing Overlord agent plugins/connectors for all supported agents...\n');
     const installedAgents = [];
 
     for (const a of supportedAgents) {
@@ -1485,7 +1519,7 @@ export async function runSetupCommand(args) {
     process.exit(1);
   }
 
-  console.log(`Installing Overlord agent bundle for ${agent}...\n`);
+  console.log(`Preparing Overlord agent plugin/connector for ${agent}...\n`);
   try {
     if (agent === 'claude') installClaude();
     else if (agent === 'codex') installCodex();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "overlord-cli",
-  "version": "3.25.0",
+  "version": "4.0.0",
   "description": "Overlord CLI — launch AI agents on tickets from anywhere",
   "type": "module",
   "bin": {

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,41 @@
+# 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-workflow/SKILL.md` — durable attach → update → ask → deliver workflow.
+- `commands/{connect,load,spawn}.md` — slash commands for session routing and ticket creation.
+- `hooks/hooks.json` + `scripts/permission-hook.sh` — PermissionRequest notifier that posts to `/api/protocol/permission-request` on the Overlord platform.
+- `userConfig` for `overlord_url` (non-sensitive) and `agent_token` (sensitive → OS keychain) so the hook and CLI know where to talk.
+
+## 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
+```
+
+The plugin prompts for `overlord_url` and `agent_token` at install time. The token is persisted to the OS keychain; the URL is stored in `~/.claude/settings.json` under `pluginConfigs["overlord"].options`.
+
+## Namespaced components
+
+Inside Claude Code the components are surfaced with the plugin prefix:
+
+- skill → `overlord:overlord-ticket-workflow`
+- commands → `/overlord:connect`, `/overlord:load`, `/overlord:spawn`
+
+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,18 @@
+---
+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.

package/plugins/claude/commands/load.md

@@ -0,0 +1,18 @@
+---
+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.

package/plugins/claude/commands/spawn.md

@@ -0,0 +1,16 @@
+---
+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`.
+Otherwise, treat `$ARGUMENTS` as the objective text and run:
+`ovld protocol spawn --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`.

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 / AGENT_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_AGENT_TOKEN:-$AGENT_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-workflow/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: overlord-ticket-workflow
+description: Overlord local workflow protocol — attach, update, deliver lifecycle for ticket-driven work from Claude Code.
+---
+
+# Overlord Local Workflow
+
+If you receive a prompt with a specified ticket ID, adhere to the following. If the prompt does not have a ticket ID, the user may choose to add one later, but otherwise, proceed without it.
+
+## Lifecycle
+
+1. **Attach first** — If there is a TICKET_ID, always call attach before doing any work:
+   ```bash
+   ovld protocol attach --ticket-id $TICKET_ID
+   ```
+   Store `session.sessionKey` from the response — it is required for all subsequent calls.
+
+2. **Update during work** — Post at least one progress update before delivering:
+   ```bash
+   ovld protocol update --session-key <sessionKey> --ticket-id $TICKET_ID --summary "What you did and why." --phase execute
+   ```
+   Phases: `draft`, `execute`, `review`, `deliver`, `complete`, `blocked`, `cancelled`.
+   Use `execute` while working.
+
+   Pass `--event-type <type>` to publish a specific activity event (default: `update`):
+   - `update` — standard progress update (default)
+   - `user_follow_up` — a message or question from the human user (EXCLUDING THE INITIAL TICKET)
+   - `alert` — surface a warning or non-blocking alert
+
+3. **Ask when blocked** — Stop working after calling:
+   ```bash
+   ovld protocol ask --session-key <sessionKey> --ticket-id $TICKET_ID --question "Specific question for the PM."
+   ```
+
+4. **Deliver last** — Always deliver when done:
+   ```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 JSON, prefer `--payload-file -` and stream the full payload 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. Do not leave delivery JSON checked into the worktree.
+
+## 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. Prefer 1–5 concise rationales per ticket, each tied to a specific file and diff hunk.
+
+## Project Discovery & Ticket Spawning
+
+When creating tickets from within a repository, `spawn` automatically resolves the
+correct project by matching your current working directory against each project's
+configured "Local working directory". No `--project-id` flag is needed:
+
+```bash
+ovld protocol spawn --objective "Implement feature X" --priority medium
+```
+
+To discover which project maps to the current directory:
+
+```bash
+ovld protocol discover-project
+```
+
+You can override with `--project-id` or `--working-directory` if needed.
+
+## Context & 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 artifact-upload-file --session-key <sessionKey> --ticket-id $TICKET_ID --file ./spec.pdf --content-type application/pdf
+ovld protocol artifact-download-url --session-key <sessionKey> --ticket-id $TICKET_ID --artifact-id <artifact-id>
+```
+
+## Rules
+
+- Always attach first; always deliver when done.
+- Always communicate with Overlord using the ovld protocol cli commands.
+- Post any substantial updates about your decisions or progress.
+- If blocked on human-only work, call `ask` and request a follow-up human ticket.
+- The `summary` in deliver is what the PM reads first — write it as a narrative, not a command list.
+- Use `write-context` for facts a future agent session should know.
+- **If the user sends you a message during your session, immediately publish a `user_follow_up` activity event with the user's message recorded verbatim in the summary before doing anything else. This DOES NOT apply to the initial ticket.**
+- **Do not add or commit changes (git commit) unless the user explicitly asks you to commit.**
+- **Delivery is the concluding step.** After delivering, stop working. Do not continue unless the user follows up or the ticket is reopened.