overlord-cli 4.0.0 → 4.1.0

package/bin/_cli/new-ticket.mjs

@@ -6,7 +6,14 @@ import { stdin as input, stdout as output } from 'node:process';
 import { buildAuthHeaders, resolveAuth } from './credentials.mjs';
 import { runLauncherCommand } from './launcher.mjs';
 
-const PROMPT_AGENTS = ['claude', 'codex', 'cursor', 'gemini', 'opencode'];
+const PROMPT_AGENT_IDENTIFIERS = {
+  claude: 'claude-code',
+  codex: 'codex',
+  cursor: 'cursor',
+  gemini: 'gemini',
+  opencode: 'opencode'
+};
+const PROMPT_AGENTS = Object.keys(PROMPT_AGENT_IDENTIFIERS);
 
 function parseFlags(args) {
   const flags = {};
@@ -40,10 +47,10 @@ function parseFlags(args) {
 
 function buildUsage(commandName) {
   if (commandName === 'prompt') {
-    return 'Usage: ovld prompt "<objective>" [--title "..."] [--acceptance-criteria "..."] [--available-tools "..."] [--execution-target agent|human] [--priority low|medium|high|urgent] [--project-id <id>] [--agent <agent>]';
+    return 'Usage: ovld prompt "<objective>" [--title "..."] [--acceptance-criteria "..."] [--available-tools "..."] [--execution-target agent|human] [--priority low|medium|high|urgent] [--project-id <id>] [--agent <agent>] [--delegate <agent>]';
   }
 
-  return 'Usage: ovld create "<objective>" [--title "..."] [--acceptance-criteria "..."] [--available-tools "..."] [--execution-target agent|human] [--priority low|medium|high|urgent] [--project-id <id>]';
+  return 'Usage: ovld create "<objective>" [--title "..."] [--acceptance-criteria "..."] [--available-tools "..."] [--execution-target agent|human] [--priority low|medium|high|urgent] [--project-id <id>] [--delegate <agent>]';
 }
 
 function ensureObjective(commandName, objective) {
@@ -151,7 +158,9 @@ async function createTicket(platformUrl, agentToken, localSecret, body) {
 
   const data = await res.json().catch(() => ({}));
   if (!res.ok) {
-    throw new Error(`Failed to create ticket (${res.status}): ${data.error ?? JSON.stringify(data)}`);
+    throw new Error(
+      `Failed to create ticket (${res.status}): ${data.error ?? JSON.stringify(data)}`
+    );
   }
 
   return data.ticket;
@@ -179,6 +188,20 @@ function resolveAgent(agent) {
   return normalizedAgent;
 }
 
+export function resolvePromptAgentIdentifier(agent) {
+  return PROMPT_AGENT_IDENTIFIERS[agent] ?? agent;
+}
+
+export function resolveTicketCreationDelegate(flags = {}, selectedAgent = null) {
+  const explicitDelegate = typeof flags.delegate === 'string' ? flags.delegate.trim() : '';
+  if (explicitDelegate) return explicitDelegate;
+
+  if (selectedAgent) return resolvePromptAgentIdentifier(selectedAgent);
+
+  const envAgent = process.env.AGENT_IDENTIFIER?.trim();
+  return envAgent || null;
+}
+
 async function runTicketCreationFlow(args, { commandName, launchAgent }) {
   const { flags, positionals } = parseFlags(args);
   const objective = String(flags.objective ?? positionals.join(' ')).trim();
@@ -200,6 +223,18 @@ async function runTicketCreationFlow(args, { commandName, launchAgent }) {
       renderItem: project => projectLabel(project)
     }));
 
+  const selectedAgent = launchAgent
+    ? (resolveAgent(typeof flags.agent === 'string' ? flags.agent : '') ??
+      (await promptForSelection({
+        items: PROMPT_AGENTS,
+        label: 'Agents',
+        prompt: 'Select an agent by number:',
+        renderItem: agent => agent
+      })))
+    : null;
+
+  const ticketDelegate = resolveTicketCreationDelegate(flags, selectedAgent);
+
   const ticket = await createTicket(platformUrl, agentToken, localSecret, {
     objective,
     title: String(flags.title ?? ''),
@@ -207,7 +242,8 @@ async function runTicketCreationFlow(args, { commandName, launchAgent }) {
     availableTools: String(flags['available-tools'] ?? ''),
     executionTarget: String(flags['execution-target'] ?? 'agent'),
     priority: String(flags.priority ?? 'medium'),
-    projectId: selectedProject.id
+    projectId: selectedProject.id,
+    ...(ticketDelegate ? { delegate: ticketDelegate } : {})
   });
 
   if (!launchAgent) {
@@ -215,15 +251,6 @@ async function runTicketCreationFlow(args, { commandName, launchAgent }) {
     return;
   }
 
-  const selectedAgent =
-    resolveAgent(typeof flags.agent === 'string' ? flags.agent : '') ??
-    (await promptForSelection({
-      items: PROMPT_AGENTS,
-      label: 'Agents',
-      prompt: 'Select an agent by number:',
-      renderItem: agent => agent
-    }));
-
   process.env.TICKET_ID = ticket.id;
   await runLauncherCommand('run', [selectedAgent, '--ticket-id', ticket.id]);
 }

package/bin/_cli/protocol.mjs

@@ -35,6 +35,22 @@ function parseFlags(args) {
   return result;
 }
 
+export function resolveProtocolAgentIdentifier(flags = {}) {
+  const explicitAgent = typeof flags.agent === 'string' ? flags.agent.trim() : '';
+  if (explicitAgent) return explicitAgent;
+
+  const envAgent = process.env.AGENT_IDENTIFIER?.trim();
+  return envAgent || 'claude-code';
+}
+
+export function resolveProtocolTicketDelegate(flags = {}, agentIdentifier = '') {
+  const explicitDelegate = typeof flags.delegate === 'string' ? flags.delegate.trim() : '';
+  if (explicitDelegate) return explicitDelegate;
+
+  const resolvedAgent = String(agentIdentifier).trim();
+  return resolvedAgent || null;
+}
+
 /**
  * Default request timeout in milliseconds. Overridable via --timeout flag or
  * OVERLORD_TIMEOUT env var. A bounded timeout prevents indefinite spinner hangs
@@ -427,7 +443,7 @@ async function protocolAttach(args) {
 
   const body = {
     ticketId,
-    agentIdentifier: String(flags.agent ?? process.env.AGENT_IDENTIFIER ?? 'claude-code'),
+    agentIdentifier: resolveProtocolAgentIdentifier(flags),
     connectionMethod: String(flags.method ?? 'cli'),
     ...(externalSessionId !== undefined ? { externalSessionId } : {}),
     metadata: {
@@ -915,7 +931,7 @@ async function protocolConnect(args) {
 
   const body = {
     ticketId,
-    agentIdentifier: String(flags.agent ?? process.env.AGENT_IDENTIFIER ?? 'claude-code'),
+    agentIdentifier: resolveProtocolAgentIdentifier(flags),
     connectionMethod: String(flags.method ?? 'cli'),
     metadata: {}
   };
@@ -969,6 +985,7 @@ async function protocolSpawn(args) {
   const objective = requireFlag(flags, 'objective', undefined);
   const { platformUrl, agentToken, localSecret } = resolveAuth();
   const timeoutMs = resolveTimeout(flags);
+  const agentIdentifier = resolveProtocolAgentIdentifier(flags);
 
   // When --project-id is not provided, auto-send cwd as workingDirectory
   // so the server can resolve the project from the local_working_directory setting.
@@ -976,7 +993,7 @@ async function protocolSpawn(args) {
 
   const body = {
     objective,
-    agentIdentifier: String(flags.agent ?? process.env.AGENT_IDENTIFIER ?? 'claude-code'),
+    agentIdentifier,
     connectionMethod: String(flags.method ?? 'cli'),
     metadata: {},
     ...(flags.title ? { title: String(flags.title) } : {}),
@@ -986,7 +1003,7 @@ async function protocolSpawn(args) {
     ...(flags['acceptance-criteria'] ? { acceptanceCriteria: String(flags['acceptance-criteria']) } : {}),
     ...(flags['available-tools'] ? { availableTools: String(flags['available-tools']) } : {}),
     ...(flags['execution-target'] ? { executionTarget: String(flags['execution-target']) } : {}),
-    ...(flags.delegate ? { delegate: String(flags.delegate) } : {}),
+    delegate: resolveProtocolTicketDelegate(flags, agentIdentifier),
     ...(flags['parent-session-key'] ? { parentSessionKey: String(flags['parent-session-key']) } : {}),
     ...(flags['parent-ticket-id'] ? { parentTicketId: String(flags['parent-ticket-id'] ?? process.env.TICKET_ID ?? '') } : {})
   };
@@ -1260,12 +1277,12 @@ artifact-upload-file:
 Examples:
   ovld protocol discover-project
   ovld protocol discover-project --working-directory /path/to/repo
-  ovld protocol spawn --objective "Implement feature X"   # auto-resolves project from cwd
+  ovld protocol spawn --agent codex --objective "Implement feature X"   # auto-resolves project from cwd
   ovld protocol attach --ticket-id abc-123
   ovld protocol attach --ticket-id abc-123 --external-session-id null
   ovld protocol connect --ticket-id abc-123
   ovld protocol load-context --ticket-id abc-123
-  ovld protocol spawn --objective "Implement user auth" --priority high
+  ovld protocol spawn --agent codex --objective "Implement user auth" --priority high
   ovld protocol update --session-key <key> --ticket-id <id> --summary "Did X" --phase execute
   ovld protocol update --session-key <key> --ticket-id <id> --summary-file ./update.txt --event-type user_follow_up
   ovld protocol record-change-rationales --session-key <key> --ticket-id <id> --change-rationales-json '[{"label":"...","file_path":"...","summary":"...","why":"...","impact":"...","hunks":[{"header":"@@ ... @@"}]}]'

package/bin/_cli/setup.mjs

@@ -367,7 +367,7 @@ argument-hint: <objective or raw flags>
 disable-model-invocation: true
 ---
 
-Run \`ovld protocol spawn\` with \`$ARGUMENTS\`. If no flags are present, treat the arguments as the objective and call \`ovld protocol spawn --objective "<objective>"\`.`
+Run \`ovld protocol spawn --agent claude-code\` with \`$ARGUMENTS\`. If no flags are present, treat the arguments as the objective and call \`ovld protocol spawn --agent claude-code --objective "<objective>"\`.`
       }
     ];
   }
@@ -388,7 +388,7 @@ Run \`ovld protocol spawn\` with \`$ARGUMENTS\`. If no flags are present, treat
       {
         path: path.join(base, 'spawn.md'),
         content:
-          'Create a new Overlord ticket.\n\nRun `ovld protocol spawn --objective "<objective>"` using the text after `/spawn` unless raw flags were provided.\n'
+          'Create a new Overlord ticket.\n\nRun `ovld protocol spawn --agent cursor --objective "<objective>"` using the text after `/spawn` unless raw flags were provided. If raw flags were provided, pass them after `ovld protocol spawn --agent cursor`.\n'
       }
     ];
   }
@@ -409,7 +409,7 @@ Run \`ovld protocol spawn\` with \`$ARGUMENTS\`. If no flags are present, treat
       {
         path: path.join(base, 'spawn.toml'),
         content:
-          'description = "Create a new Overlord ticket from the current conversation."\nprompt = """\nRun `ovld protocol spawn --objective "<objective>"` using `{{args}}` as the objective unless raw flags were provided.\n"""\n'
+          'description = "Create a new Overlord ticket from the current conversation."\nprompt = """\nRun `ovld protocol spawn --agent gemini --objective "<objective>"` using `{{args}}` as the objective unless raw flags were provided. If raw flags were provided, pass them after `ovld protocol spawn --agent gemini`.\n"""\n'
       }
     ];
   }
@@ -441,7 +441,7 @@ description: Create a new Overlord ticket from the current conversation
 agent: build
 ---
 
-Run \`ovld protocol spawn\` with \`$ARGUMENTS\`. If no flags are present, treat the arguments as the objective and call \`ovld protocol spawn --objective "<objective>"\`.`
+Run \`ovld protocol spawn --agent opencode\` with \`$ARGUMENTS\`. If no flags are present, treat the arguments as the objective and call \`ovld protocol spawn --agent opencode --objective "<objective>"\`.`
     }
   ];
 }

package/package.json

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

package/plugins/claude/commands/spawn.md

@@ -7,9 +7,9 @@ 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`.
+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 --objective "<objective>"`
+`ovld protocol spawn --agent claude-code --objective "<objective>"`
 
 If no objective was provided, ask the user for one and stop.
 

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

@@ -71,7 +71,7 @@ correct project by matching your current working directory against each project'
 configured "Local working directory". No `--project-id` flag is needed:
 
 ```bash
-ovld protocol spawn --objective "Implement feature X" --priority medium
+ovld protocol spawn --agent claude-code --objective "Implement feature X" --priority medium
 ```
 
 To discover which project maps to the current directory: