overlord-cli 4.14.0 → 4.16.0

package/bin/_cli/protocol.mjs

@@ -69,7 +69,7 @@ function resolveProtocolMetadata(flags = {}, base = {}) {
   const metadata = { ...base };
 
   if (flags['metadata-json']) {
-    const parsed = JSON.parse(String(flags['metadata-json']));
+    const parsed = parseJsonFlag('--metadata-json', flags['metadata-json']);
     if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
       throw new Error('--metadata-json must be a JSON object');
     }
@@ -215,6 +215,15 @@ function requireFlag(flags, name, envAlias) {
   return String(value);
 }
 
+function parseJsonFlag(flagName, rawValue) {
+  try {
+    return JSON.parse(String(rawValue));
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    throw new Error(`${flagName} must be valid JSON: ${detail}`);
+  }
+}
+
 function readTextFile(filePath, label) {
   try {
     return fs.readFileSync(filePath, 'utf8');
@@ -286,11 +295,7 @@ async function resolveChangeRationales(flags) {
     );
   }
   if (flags['change-rationales-json']) {
-    try {
-      return JSON.parse(String(flags['change-rationales-json']));
-    } catch {
-      throw new Error('--change-rationales-json must be valid JSON');
-    }
+    return parseJsonFlag('--change-rationales-json', flags['change-rationales-json']);
   }
   return [];
 }
@@ -534,7 +539,7 @@ async function protocolUpdate(args) {
       : {}),
     ...(flags.phase ? { phase: String(flags.phase) } : {}),
     ...(flags['event-type'] ? { eventType: String(flags['event-type']) } : {}),
-    ...(flags['payload-json'] ? { payload: JSON.parse(String(flags['payload-json'])) } : {}),
+    ...(flags['payload-json'] ? { payload: parseJsonFlag('--payload-json', flags['payload-json']) } : {}),
     ...(changeRationales.length > 0 ? { changeRationales } : {})
   };
 
@@ -613,7 +618,7 @@ async function protocolAsk(args) {
     ticketId,
     question,
     ...(flags.phase ? { phase: String(flags.phase) } : {}),
-    ...(flags['payload-json'] ? { payload: JSON.parse(String(flags['payload-json'])) } : {})
+    ...(flags['payload-json'] ? { payload: parseJsonFlag('--payload-json', flags['payload-json']) } : {})
   };
 
   const data = await apiPost(platformUrl, agentToken, localSecret, '/api/protocol/ask', body, timeoutMs);
@@ -750,11 +755,7 @@ async function protocolDeliver(args) {
   if (flags['artifacts-file']) {
     artifacts = await readJsonFileOrStdin(String(flags['artifacts-file']), '--artifacts-file');
   } else if (flags['artifacts-json']) {
-    try {
-      artifacts = JSON.parse(String(flags['artifacts-json']));
-    } catch {
-      throw new Error('--artifacts-json must be valid JSON');
-    }
+    artifacts = parseJsonFlag('--artifacts-json', flags['artifacts-json']);
   }
 
   if (deliverPayload && (flags['change-rationales-file'] || flags['change-rationales-json'])) {
@@ -805,7 +806,7 @@ async function protocolArtifactPrepareUpload(args) {
     ...(flags['artifact-type'] ? { artifactType: String(flags['artifact-type']) } : {}),
     ...(flags['content-type'] ? { contentType: String(flags['content-type']) } : {}),
     ...(flags['file-size'] ? { fileSize: parseInt(String(flags['file-size']), 10) } : {}),
-    ...(flags['metadata-json'] ? { metadata: JSON.parse(String(flags['metadata-json'])) } : {})
+    ...(flags['metadata-json'] ? { metadata: parseJsonFlag('--metadata-json', flags['metadata-json']) } : {})
   };
 
   const data = await apiPost(
@@ -838,7 +839,7 @@ async function protocolArtifactFinalizeUpload(args) {
     ...(flags['artifact-type'] ? { artifactType: String(flags['artifact-type']) } : {}),
     ...(flags['content-type'] ? { contentType: String(flags['content-type']) } : {}),
     ...(flags['file-size'] ? { fileSize: parseInt(String(flags['file-size']), 10) } : {}),
-    ...(flags['metadata-json'] ? { metadata: JSON.parse(String(flags['metadata-json'])) } : {})
+    ...(flags['metadata-json'] ? { metadata: parseJsonFlag('--metadata-json', flags['metadata-json']) } : {})
   };
 
   const data = await apiPost(
@@ -915,7 +916,7 @@ async function protocolArtifactUploadFile(args) {
       artifactType: String(flags['artifact-type'] ?? 'document'),
       contentType,
       fileSize: fileStats.size,
-      ...(flags['metadata-json'] ? { metadata: JSON.parse(String(flags['metadata-json'])) } : {})
+      ...(flags['metadata-json'] ? { metadata: parseJsonFlag('--metadata-json', flags['metadata-json']) } : {})
     },
     timeoutMs
   );
@@ -941,7 +942,7 @@ async function protocolArtifactUploadFile(args) {
       artifactType: String(flags['artifact-type'] ?? 'document'),
       contentType,
       fileSize: fileStats.size,
-      ...(flags['metadata-json'] ? { metadata: JSON.parse(String(flags['metadata-json'])) } : {})
+      ...(flags['metadata-json'] ? { metadata: parseJsonFlag('--metadata-json', flags['metadata-json']) } : {})
     },
     timeoutMs
   );
@@ -1044,8 +1045,9 @@ async function protocolSpawn(args) {
   const agentIdentifier = resolveProtocolAgentIdentifier(flags);
   const modelIdentifier = resolveProtocolModelIdentifier(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.
+  // When --project-id is not provided, auto-send cwd as workingDirectory so
+  // the server can resolve the project from the caller's project_user
+  // local_working_directory setting.
   const workingDirectory = flags['working-directory'] ?? (!flags['project-id'] ? process.cwd() : undefined);
 
   const body = {
@@ -1147,7 +1149,7 @@ async function protocolCreateTicket(args) {
   const projectId = discovered?.project?.id;
   if (!projectId) {
     throw new Error(
-      'Could not resolve project from working directory. Set project local working directory in Overlord or pass --working-directory.'
+      "Could not resolve project from working directory. Set your local working directory for this project in Overlord or pass --working-directory."
     );
   }
 
@@ -1215,8 +1217,8 @@ or attach to an existing ticket with \`ovld protocol attach --ticket-id <id>\`.
 
 Project discovery:
   When spawning or creating tickets, the CLI automatically resolves the correct
-  project by matching your current working directory against each project's
-  configured "Local working directory" (set in Project Settings in the Overlord UI).
+  project by matching your current working directory against your configured
+  "Local working directory" for that project (stored per user in Overlord).
   You can also discover the project explicitly:
 
     ovld protocol discover-project
@@ -1267,13 +1269,13 @@ auth-status:
 discover-project:
   Purpose:
     Resolve the Overlord project that corresponds to the current (or given) working directory.
-    Uses each project's "Local working directory" setting for matching.
+    Uses the caller's configured "Local working directory" for matching.
   Optional:
     --working-directory <path>  Directory to match (default: current working directory)
   Returns:
     Project JSON with id, name, organizationId. Prints PROJECT_ID=<id> on stderr.
   Notes:
-    Set the local working directory for a project in the Overlord UI under Project Settings.
+    Set your local working directory for a project in the Overlord UI under Project Settings.
     When no match is found, returns a 404 with a hint.
 
 attach:
@@ -1406,7 +1408,7 @@ spawn:
   Purpose:
     Create a follow-up ticket and attach to it in one call.
     When --project-id is omitted, automatically resolves the project from the
-    current working directory (matching against each project's local_working_directory).
+    current working directory (matching against the caller's project_user.local_working_directory).
   Required:
     --objective <text>
   Optional:
@@ -1437,7 +1439,7 @@ create:
   Optional:
     --session-key <key>
     --ticket-id <id>
-    --working-directory <path>  Resolve project by local working directory (default: cwd)
+    --working-directory <path>  Resolve project by your configured local working directory (default: cwd)
     --title <text>
     --priority <level>        low | medium | high | urgent
     --acceptance-criteria <text>

package/package.json

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

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

@@ -73,7 +73,7 @@ Use this mode when the conversation starts normally and the user asks Claude to
 
 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 Overlord `local_working_directory`, then creates a standalone 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>`.