overlord-cli 0.2605201134.0 → 0.2605210944.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "overlord-cli",
-  "version": "0.2605201134.0",
+  "version": "0.2605210944.0",
   "description": "Overlord CLI — launch AI agents on tickets from anywhere",
   "homepage": "https://www.ovld.ai/docs/",
   "type": "module",
@@ -16,6 +16,7 @@
     "plugins/"
   ],
   "scripts": {
+    "prepack": "node ../../scripts/render-agent-plugins.mjs --check",
     "postinstall": "node bin/_cli/postinstall.mjs || true"
   },
   "engines": {

package/plugins/antigravity/scripts/overlord-mcp.mjs

@@ -927,20 +927,11 @@ function parseMessages(chunk) {
     if (headerEnd === -1) break;
 
     const headerText = buffer.subarray(0, headerEnd).toString('utf8');
-    const headers = Object.fromEntries(
-      headerText.split('\r\n').map(line => {
-        const separatorIndex = line.indexOf(':');
-        return [
-          line.slice(0, separatorIndex).trim().toLowerCase(),
-          line.slice(separatorIndex + 1).trim()
-        ];
-      })
-    );
-
-    const contentLength = Number(headers['content-length']);
-    if (!Number.isFinite(contentLength)) {
+    const lengthMatch = headerText.match(/Content-Length:\s*(\d+)/i);
+    if (!lengthMatch) {
       throw new Error('Missing Content-Length header');
     }
+    const contentLength = Number(lengthMatch[1]);
 
     const totalLength = headerEnd + 4 + contentLength;
     if (buffer.length < totalLength) break;
@@ -995,7 +986,7 @@ async function runProtocol(tool, args) {
         cwd: process.cwd(),
         env: {
           ...process.env,
-          AGENT_IDENTIFIER: process.env.AGENT_IDENTIFIER ?? 'antigravity-overlord-plugin'
+          AGENT_IDENTIFIER: process.env.AGENT_IDENTIFIER ?? 'antigravity'
         },
         maxBuffer: 20 * 1024 * 1024
       },

package/plugins/claude/README.md

@@ -4,17 +4,21 @@ Claude Code plugin that exposes the Overlord local ticket workflow to any Claude
 
 ## 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.
+- `hooks/hooks.json` + `scripts/permission-hook.sh` — PermissionRequest notifier that posts to `/api/protocol/permission-request` on the Overlord platform.
+- `userConfig` for `overlord_url`. Auth is expected to come from shared OAuth credentials or explicit `OVERLORD_ACCESS_TOKEN` + `OVERLORD_ORGANIZATION_ID` env vars.
+
+
 
 ## 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
@@ -23,14 +27,23 @@ 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.
+
+The plugin prompts for `overlord_url` at install time. Authentication should come from `ovld auth repair` first when a shared session already exists, then `ovld auth login`, Overlord Desktop, or explicit OAuth env vars in the launched shell.
+
+
+
+
 
 ## Namespaced components
 
@@ -40,3 +53,6 @@ Inside Claude Code the components are surfaced with the plugin prefix:
 - 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/add-objectives.md

@@ -12,3 +12,4 @@ Run:
 `ovld protocol add-objectives --ticket-id <ticket_id> --objectives-json '[{"objective":"Step one"},{"objective":"Step two"}]'`
 
 Index 0 is the first newly added objective to execute; later indexes queue after it.
+

package/plugins/claude/commands/connect.md

@@ -9,6 +9,7 @@ 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>`
 
@@ -16,4 +17,5 @@ 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

@@ -6,6 +6,7 @@ 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:
@@ -14,4 +15,5 @@ Otherwise, treat `$ARGUMENTS` as the objective text and run:
 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

@@ -6,9 +6,11 @@ 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>`
 
@@ -16,4 +18,5 @@ 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/prompt.md

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

package/plugins/claude/commands/record-work.md

@@ -25,4 +25,5 @@ Rules:
 - Do NOT use this for in-progress work. Use `/prompt` for that.
 - The CLI validates that every changed git-tracked file is represented in `changeRationales` unless `--skip-file-change-check` is passed.
 - If project resolution fails, re-run with `--project-id <id>` or `--personal`.
-- If `ovld` reports `OVERLORD_URL` is unreachable, stop and request permission escalation or network access before retrying.
+
+

package/plugins/claude/commands/spawn.md

@@ -1,17 +1,20 @@
 ---
-description: Create a new Overlord ticket from the current conversation
+description: (Deprecated — use /prompt instead) Create a new Overlord ticket
 argument-hint: <objective or raw flags>
 disable-model-invocation: true
 ---
 
+This command is deprecated. Use `/overlord:prompt` instead.
+
 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`.
+If it already contains flags such as `--title`, `--priority`, `--project-id`, or `--execution-target`, pass those flags through after `ovld protocol prompt --agent claude-code`.
 Otherwise, treat `$ARGUMENTS` as the objective text and run:
-`ovld protocol spawn --agent claude-code --objective "<objective>"`
+`ovld protocol prompt --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

@@ -24,3 +24,4 @@
     ]
   }
 }
+

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

@@ -19,251 +19,68 @@ Use this mode when the prompt already contains a ticket ID or explicitly says th
 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
+For full command syntax, flags, phase values, and event types see [reference/cli.md](reference/cli.md).
 
-Attach:
+## Objective Submission vs Execution
 
-```bash
-ovld protocol attach --ticket-id $TICKET_ID
-```
+Discussing or otherwise opening a ticket from within a chat should cause the draft objective to be marked **submitted** — this signals the ticket is in active discussion with an agent, but not yet being executed. Only an explicit order to execute (e.g. "execute this", "do this", "start working on it") should cause you to **attach** to the ticket and trigger execution.
 
-In a git workspace, `attach` automatically creates a local git checkpoint for each executing objective before work begins, stored under `refs/overlord/checkpoints/<objectiveId>`. Pass `--skip-checkpoint` only when intentionally bypassing local provenance.
+- **Discussing / opening a ticket** → `ovld protocol discuss-objective --ticket-id $TICKET_ID` (draft → submitted, no session).
+- **Creating a ticket** via `ovld protocol create` keeps the objective in `draft` state.
+- **Explicitly ordered to execute** → `ovld protocol attach --ticket-id $TICKET_ID` (draft/submitted → executing, session begins).
 
-Update:
-
-```bash
-ovld protocol update --session-key <sessionKey> --ticket-id $TICKET_ID --summary "What you did and why." --phase execute
-```
-
-When the summary contains backticks, quotes, or other special shell characters, pipe it via stdin to prevent shell interpretation:
-
-```bash
-ovld protocol update --session-key <sessionKey> --ticket-id $TICKET_ID --summary-file - --phase execute <<'EOF'
-What you did and why — including `backticks`, "quotes", and $variables are all safe here.
-EOF
-```
-
-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 when the automatic hook is unavailable
-- `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 @@"}]}]'
-```
-
-Use `--payload-json` when the full delivery object fits comfortably inline. 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 the summary contains special characters, use `--summary-file -` and pipe via a single-quoted heredoc (`<<'EOF'`) to prevent shell expansion. 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.
-
-Revert an objective:
-
-```bash
-ovld protocol revert --objective-id <objective-id>
-```
-
-`revert` restores the local working tree to the recorded objective checkpoint and saves a safety ref under `refs/overlord/safety/` first.
+Do not attach to a ticket just because it was mentioned or opened in conversation. Only attach when the user clearly asks you to execute the work.
 
 ## 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 --objectives-json '[{"objective":"..."}]'`.
+1. If the user wants to create tickets (and does not ask to start execution), use `/overlord:create` or run `ovld protocol create --agent claude-code --objectives-json '[{"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.
    - Pass multiple items in `--objectives-json` when creating ordered steps for the same feature or goal.
-2. Default to `create` for new draft tickets. Only use `/overlord:prompt` or `ovld protocol prompt --agent claude-code --objectives-json '[{"objective":"..."}]'` when the user explicitly asks to create and execute immediately. If the work is already complete in chat and just needs to be recorded, use `ovld protocol record-work` instead.`prompt` creates the ticket in `execute` status and attaches immediately.
+2. Default to `create` for new tickets. Only use `/overlord:prompt` or `ovld protocol prompt --agent claude-code --objectives-json '[{"objective":"..."}]'` when the user explicitly asks to create and execute immediately.
+   `prompt` 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>`.
+   When you open or discuss an existing ticket that has a draft objective, submit it with `ovld protocol discuss-objective --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 establish a persistent session with a ticket by ID, use `/overlord:attach` or run `ovld protocol attach --ticket-id <ticket_id>`.
-6. 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 run `ovld protocol search-tickets --query "..." --status next-up,execute` and ask the user to confirm.
-7. If you need other lifecycle commands or flags, run `ovld protocol help` and use the real subcommand list instead of guessing.
-8. Once you attach to a ticket, switch back to Mode 1 and follow the full ticket lifecycle.
+6. If the user wants to find a ticket but does not know the ID, run `ovld protocol search-tickets --query "..." --status next-up,execute` and ask the user to confirm. For interactive ticket search and agent launch, prefer `ovld attach`.
+7. If you need to understand project routing before prompting, use `ovld protocol discover-project`.
+8. If you need other lifecycle commands or flags, run `ovld protocol help` and use the real subcommand list instead of guessing.
+9. Once you attach to a ticket, switch back to Mode 1 and follow the full ticket lifecycle.
 
-## Recording Completed Work From Chat
-
-Use this when the user has had a working conversation with the agent (no Overlord ticket attached) and now wants to record the outcome as a ticket — both for review and to publish a feed post about it. This is **distinct from `create` and from `deliver`**:
-
-- `create` makes a draft ticket for *future* work; nothing happens yet.
-- `prompt` creates a ticket and starts an execution session.
-- `deliver` concludes an *attached* session; the ticket already exists.
-- `record-work` creates the ticket *and* completes the objective *and* triggers the feed-post generator in a single call, with no session left open.
-
-Do NOT use `record-work` for in-progress work. Use it only when the work is already done in the chat.
-
-```bash
-ovld protocol record-work \
-  --objectives-json '[{"objective":"User asked me to X; I did Y by..."}]' \
-  --summary  "Narrative for the feed post and reviewer." \
-  --change-rationales-file -
-```
-
-Or stream the full payload via stdin to avoid quote escaping:
-
-```bash
-ovld protocol record-work --payload-file - <<'EOF'
-{
-  "objectives": [{"objective": "..."}],
-  "summary": "...",
-  "artifacts": [{"type": "next_steps", "label": "...", "content": "..."}],
-  "changeRationales": [{"label": "...", "file_path": "...", "summary": "...", "why": "...", "impact": "...", "hunks": [{"header": "@@ ..."}]}]
-}
-EOF
-```
-
-Project resolution mirrors `prompt`/`create`: cwd is matched against the caller's `project_user.local_working_directory`. If no match:
-
-1. **Ask the user for a `--project-id`** if the work is project-related. Show them a brief description of what you're about to record so they can pick the right project.
-2. If the user confirms the work is not tied to any project, pass `--personal` to create a private ticket.
-
-Validation: in a git workspace, `record-work` checks that uncommitted changes are represented by `changeRationales` and rejects if they aren't (same check as `deliver`). Pass `--skip-file-change-check` only when intentionally bypassing.
-
-The hosted MCP tool name is `record_work` (snake_case). It accepts the same fields as the CLI but in camelCase JSON. Use `record_work` over the `create_ticket` + `attach` + `deliver` sequence whenever the work is already done.
+For ticket creation examples, project discovery, and `--objectives-json` format see [reference/cli.md](reference/cli.md).
 
 ## 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. Use `--payload-json` for compact full delivery payloads, or `--payload-file -` when the JSON is larger or quote-sensitive 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
+Before delivering, make sure every meaningful git-tracked file change is represented in `changeRationales`; do not send `file_changes` as an artifact. Record only meaningful behavioral changes. Skip formatting-only noise.
 
-When creating tickets from within a repository:
-
-- Prefer `create` by default for draft ticket creation.
-- Use `prompt` 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.
-- Create multiple tickets when each prompt represents a different feature or goal.
-- Add objectives to the same ticket when each prompt is a sequential step toward the same feature or goal; use `ovld protocol add-objectives --ticket-id <ticket_id> --objectives-json '[{"objective":"..."}]'`.
-- `create`, `prompt`, and `record-work` require `--objectives-json` or `--objectives-file` with an ordered array of `{ "objective": "...", "title": "...", "autoAdvance": true }` objects. A single objective is just an array with one item.
-
-```bash
-ovld protocol create --agent claude-code --objectives-json '[{"objective":"Capture follow-up work from this repository"}]'
-ovld protocol prompt --agent claude-code --objectives-json '[{"objective":"Implement feature X"}]' --priority medium
-```
-
-```bash
-ovld protocol add-objectives --ticket-id 1:899 --objectives-json '[{"objective":"Implement the API"},{"objective":"Add CLI docs"}]'
-```
-
-To inspect project resolution explicitly:
-
-```bash
-ovld protocol discover-project
-```
-
-You can override with `--project-id` or `--working-directory` if needed.
-
-### Resolving the project ID when you don't have one
-
-When you need a project ID for a protocol command and the ticket prompt did not supply one, resolve it in this order.
-
-**Locally (CLI inside a shell on the user's machine):**
-
-1. `--project-id` if explicitly provided.
-2. Otherwise, let the CLI match the current working directory (the default behavior of `create`, `prompt`, `discover-project`).
-3. If working-directory resolution returns nothing, read `overlord.json` from the cwd (or any ancestor you have access to) and pass its project id via `--project-id`.
-
-**Over MCP (web agents and hosted tools, where the server cannot see the agent's cwd):**
-
-1. `--project-id` / `projectId` if explicitly provided.
-2. Read `overlord.json` from the directory the user is accessing and pass its project id as `projectId`.
-3. As a last resort, try `workingDirectory` resolution.
-
-If `overlord.json` contains more than one project, show the user the project **names** from that file and ask which one to use before calling any protocol command — never silently pick one.
-
-### 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.
-
-Objective attachment uploads also expose two-step variants — `attachment-prepare-upload` and `attachment-finalize-upload` — for callers that need a signed URL directly. Prefer `attachment-upload-file` for one-shot uploads.
-
-"Artifacts" in `deliver` are the structured records an agent submits at delivery time (next_steps, test_results, migration, decision, note, url) — not user-uploaded files.
-
-## Large Artifacts
-
-For large artifacts such as planning documents, architecture decisions, research summaries, or design documents: **save the full content as a markdown file in the linked repository, then summarize it in the artifact returned to the ticket.**
-
-- Save to a meaningful path in the repository (e.g., `ai/feature-plans/my-feature.md` for feature plans, `docs/decisions/my-decision.md` for architecture decision records).
-- Commit the file as part of the ticket's work so it appears in `changeRationales`.
-- In the delivery, include a `note` or `decision` artifact with a concise summary and the repository file path — not the full document content.
-
-This keeps the ticket feed readable while preserving the full document in version control where it can be reviewed, diffed, and referenced later.
-
-## Defaults And Notes
-
-- API requires `agentIdentifier` and `connectionMethod` on attach/connect/prompt. The CLI defaults them to `claude-code`/`cli`; the MCP tool defaults to `mcp`. Override with `--agent` / `--method` when calling from a different runtime.
-- Hosted Overlord MCP (`/functions/v1/mcp`) uses the same canonical tool names as any local MCP shim that shells into `ovld protocol` (`attach`, `update`, `deliver`, `record_work`, …). Hosted calls use camelCase JSON keys (`ticketId`, `sessionKey`) matching `POST /api/protocol/*` bodies; the local shim uses snake_case keys mapped to CLI flags (`ticket_id`, `session_key`).
-- `permission-request` is invoked by the Claude Code permission hook installed by the bundle. Agents do not normally call it directly.
-- `record_change_rationales` (MCP) and `ovld protocol record-change-rationales` (CLI) both write to the same `file_changes` table. The dedicated CLI route is `POST /api/protocol/record-change-rationales`.
+For the `record-change-rationales` command and `--change-rationales-json` payload shape see [reference/cli.md](reference/cli.md).
 
 ## 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.
+- Include at least one progress update before delivering.
 - The `summary` in deliver is what the PM reads first, so write it as a narrative, not a command list.
-- When a summary or question contains backticks, `$vars`, or other shell-special characters, always use `--summary-file -` (or `--question-file -`) with a single-quoted heredoc (`<<'EOF'`). Never retry by stripping or escaping content — pipe stdin instead.
+- When a summary or question contains backticks, `$vars`, or other shell-special characters, always use `--summary-file -` (or `--question-file -`) with a single-quoted heredoc (`<<'EOF'`). Never retry by stripping or escaping content — pipe stdin instead. See [reference/shell-escaping.md](reference/shell-escaping.md).
 - Use `write-context` for facts a future agent session should know.
 - 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.4.12 -->
+## Reference
+
+- [reference/cli.md](reference/cli.md) — Full protocol command syntax, flags, phases, ticket creation, and project discovery
+- [reference/mcp.md](reference/mcp.md) — MCP tool naming, key casing, hosted vs local shim defaults
+- [reference/devices.md](reference/devices.md) — Device fingerprints, project resources, and `--execution-target`
+- [reference/context.md](reference/context.md) — Shared state, attachments, and large artifact policy
+- [reference/shell-escaping.md](reference/shell-escaping.md) — Heredoc stdin piping for special characters in summaries and payloads
+
+<!-- version: 0.5.3 -->
+

package/plugins/claude/skills/overlord-ticket/reference/cli.md

@@ -0,0 +1,127 @@
+# CLI Command Reference
+
+## Attach
+
+```bash
+ovld protocol attach --ticket-id $TICKET_ID
+```
+
+In a git workspace, `attach` automatically creates a local git checkpoint for each executing objective before work begins, stored under `refs/overlord/checkpoints/<objectiveId>`. Pass `--skip-checkpoint` only when intentionally bypassing local provenance.
+
+## 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` — only when the `UserPromptSubmit` hook is unavailable; the hook normally posts follow-ups to the activity feed
+- `alert` for warnings or non-blocking issues
+
+## Ask
+
+```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 @@"}]}]'
+```
+
+Use `--payload-json` when the full delivery object fits comfortably inline. 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.
+
+Ordinary deliver artifacts should use `next_steps`, `test_results`, `migration`, `note`, `url`, or `decision`.
+
+## Revert
+
+```bash
+ovld protocol revert --objective-id <objective-id>
+```
+
+`revert` restores the local working tree to the recorded objective checkpoint and saves a safety ref under `refs/overlord/safety/` first.
+
+## Record Change Rationales
+
+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. Use `--payload-json` for compact full delivery payloads, or `--payload-file -` when the JSON is larger or quote-sensitive so summary, artifacts, and change rationales stay in one JSON document without creating a temporary file.
+
+```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 @@"}]}]'
+```
+
+## Project Discovery And Ticket Creation
+
+When creating tickets from within a repository:
+
+- Prefer `create` by default for draft ticket creation.
+- Use `prompt` 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 or `--project-id` to be explicit.
+- Create multiple tickets when each prompt represents a different feature or goal.
+- Add objectives to the same ticket when each prompt is a sequential step toward the same feature or goal; use `ovld protocol add-objectives --ticket-id <ticket_id> --objectives-json '[{"objective":"..."}]'`.
+- `create`, `prompt`, and `record-work` require `--objectives-json` or `--objectives-file` with an ordered array of `{ "objective": "...", "title": "...", "autoAdvance": true }` objects. A single objective is just an array with one item.
+
+```bash
+ovld protocol create --agent claude-code --objectives-json '[{"objective":"Capture follow-up work from this repository"}]'
+```
+
+```bash
+ovld protocol prompt --agent claude-code --objectives-json '[{"objective":"Implement feature X"}]' --priority medium
+```
+
+```bash
+ovld protocol add-objectives --ticket-id 1:899 --objectives-json '[{"objective":"Implement the API"},{"objective":"Add CLI docs"}]'
+```
+
+To inspect project resolution explicitly:
+
+```bash
+ovld protocol discover-project
+```
+
+You can override with `--project-id` or `--working-directory` if needed.
+
+### Resolving the project ID when you don't have one
+
+When you need a project ID for a protocol command and the ticket prompt did not supply one, resolve it in this order.
+
+**Locally (CLI inside a shell on the user's machine):**
+
+1. `--project-id` if explicitly provided.
+2. Otherwise, let the CLI match the current working directory (the default behavior of `create`, `prompt`, `discover-project`).
+3. If working-directory resolution returns nothing, read `overlord.json` from the cwd (or any ancestor you have access to) and pass its project id via `--project-id`.
+
+**Over MCP (web agents and hosted tools, where the server cannot see the agent's cwd):**
+
+1. `--project-id` / `projectId` if explicitly provided.
+2. Read `overlord.json` from the directory the user is accessing and pass its project id as `projectId`.
+3. As a last resort, try `workingDirectory` resolution.
+
+If `overlord.json` contains more than one project, show the user the project **names** from that file and ask which one to use before calling any protocol command — never silently pick one.
+