agentplane 0.1.0 → 0.1.2

package/dist/run-cli.js

@@ -4,7 +4,7 @@ import { chmod, cp, mkdir, mkdtemp, readdir, readFile, realpath, rename, rm, wri
 import os from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
-import { defaultConfig, extractTaskSuffix, findGitRoot, getBaseBranch, getStagedFiles, getUnstagedFiles, lintTasksFile, loadConfig, renderTaskReadme, resolveProject, saveConfig, setByDottedKey, setPinnedBaseBranch, taskReadmePath, validateCommitSubject, validateTaskDocMetadata, } from "@agentplane/core";
+import { defaultConfig, extractTaskSuffix, findGitRoot, getBaseBranch, getStagedFiles, getUnstagedFiles, lintTasksFile, loadConfig, renderTaskReadme, resolveProject, saveConfig, setByDottedKey, setPinnedBaseBranch, taskReadmePath, validateCommitSubject, validateTaskDocMetadata, } from "@agentplaneorg/core";
 import { renderHelp } from "./help.js";
 import { listRoles, renderQuickstart, renderRole } from "./command-guide.js";
 import { formatCommentBodyForCommit } from "./comment-format.js";
@@ -52,7 +52,11 @@ function parseGlobalArgs(argv) {
         if (arg === "--root") {
             const next = argv[i + 1];
             if (!next)
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: "Missing value for --root" });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: "Missing value after --root (expected repository path)",
+                });
             root = next;
             i++;
             continue;
@@ -80,24 +84,82 @@ function writeError(err, jsonErrors) {
     }
 }
 function renderErrorHint(err) {
+    const command = typeof err.context?.command === "string" ? err.context.command : undefined;
+    const usage = command ? `agentplane ${command} --help` : "agentplane --help";
     switch (err.code) {
         case "E_USAGE": {
-            return "Run `agentplane --help` for usage.";
+            return `See \`${usage}\` for usage.`;
         }
         case "E_GIT": {
-            return "Run inside a git repository or pass --root <path>.";
+            if (command?.startsWith("branch")) {
+                return "Check git repo/branch; run `git branch` or pass --root <path>.";
+            }
+            if (command === "guard commit" || command === "commit") {
+                return "Check git status/index; stage changes and retry.";
+            }
+            return "Check git repo context; pass --root <path> if needed.";
         }
         case "E_NETWORK": {
-            return "Check network connectivity and credentials.";
+            return "Check network access and credentials.";
         }
         case "E_BACKEND": {
-            return "Check backend configuration in .agentplane/backends.";
+            if (command?.includes("sync")) {
+                return "Check backend config under .agentplane/backends and retry.";
+            }
+            return "Check backend config under .agentplane/backends.";
         }
         default: {
             return undefined;
         }
     }
 }
+function missingValueMessage(flag) {
+    return `Missing value for ${flag} (expected value after flag)`;
+}
+function invalidValueMessage(label, value, expected) {
+    return `Invalid ${label}: ${value} (expected ${expected})`;
+}
+function invalidValueForFlag(flag, value, expected) {
+    return invalidValueMessage(`value for ${flag}`, value, expected);
+}
+function unknownEntityMessage(entity, value) {
+    return `Unknown ${entity}: ${value}`;
+}
+function emptyStateMessage(resource, hint) {
+    return `No ${resource} found.${hint ? ` ${hint}` : ""}`;
+}
+function requiredFieldMessage(field, source) {
+    return `Missing required field: ${field}${source ? ` (${source})` : ""}`;
+}
+function invalidFieldMessage(field, expected, source) {
+    return `Invalid field ${field}: expected ${expected}${source ? ` (${source})` : ""}`;
+}
+function invalidPathMessage(field, reason, source) {
+    return `Invalid ${field}: ${reason}${source ? ` (${source})` : ""}`;
+}
+function missingFileMessage(filename, rootHint) {
+    return `Missing ${filename}${rootHint ? ` at ${rootHint}` : ""}`;
+}
+function successMessage(action, target, details) {
+    const base = target ? `${action} ${target}` : action;
+    const suffix = details ? ` (${details})` : "";
+    return `✅ ${base}${suffix}`;
+}
+function infoMessage(message) {
+    return `ℹ️ ${message}`;
+}
+function warnMessage(message) {
+    return `⚠️ ${message}`;
+}
+function usageMessage(usage, example) {
+    return example ? `${usage}\nExample: ${example}` : usage;
+}
+function backendNotSupportedMessage(feature) {
+    return `Backend does not support ${feature}`;
+}
+function workflowModeMessage(actual, expected) {
+    return `Invalid workflow_mode: ${actual ?? "unknown"} (expected ${expected})`;
+}
 function mapCoreError(err, context) {
     const message = err instanceof Error ? err.message : String(err);
     if (message.startsWith("Not a git repository")) {
@@ -254,30 +316,78 @@ const RECIPES_SCENARIOS_DIR_NAME = "scenarios";
 const RECIPES_SCENARIOS_INDEX_NAME = "scenarios.json";
 const RECIPES_REMOTE_INDEX_NAME = "recipes-index.json";
 const RECIPE_USAGE = "Usage: agentplane recipes <list|info|explain|install|remove|list-remote|cache> [args]";
+const RECIPE_USAGE_EXAMPLE = "agentplane recipes list";
 const RECIPE_INFO_USAGE = "Usage: agentplane recipes info <id>";
+const RECIPE_INFO_USAGE_EXAMPLE = "agentplane recipes info viewer";
 const RECIPE_EXPLAIN_USAGE = "Usage: agentplane recipes explain <id>";
+const RECIPE_EXPLAIN_USAGE_EXAMPLE = "agentplane recipes explain viewer";
 const RECIPE_INSTALL_USAGE = "Usage: agentplane recipes install --name <id> [--index <path|url>] [--refresh] | --path <path> | --url <url>";
+const RECIPE_INSTALL_USAGE_EXAMPLE = "agentplane recipes install --name viewer";
 const RECIPE_REMOVE_USAGE = "Usage: agentplane recipes remove <id>";
+const RECIPE_REMOVE_USAGE_EXAMPLE = "agentplane recipes remove viewer";
 const RECIPE_CACHE_USAGE = "Usage: agentplane recipes cache <prune> [args]";
+const RECIPE_CACHE_USAGE_EXAMPLE = "agentplane recipes cache prune --dry-run";
 const RECIPE_CACHE_PRUNE_USAGE = "Usage: agentplane recipes cache prune [--dry-run] [--all]";
+const RECIPE_CACHE_PRUNE_USAGE_EXAMPLE = "agentplane recipes cache prune --dry-run";
 const RECIPE_LIST_REMOTE_USAGE = "Usage: agentplane recipes list-remote [--refresh] [--index <path|url>]";
+const RECIPE_LIST_REMOTE_USAGE_EXAMPLE = "agentplane recipes list-remote --refresh";
 const DEFAULT_RECIPES_INDEX_URL = "https://raw.githubusercontent.com/basilisk-labs/agentplane-recipes/main/index.json";
 const RECIPE_CONFLICT_MODES = ["fail", "rename", "overwrite"];
 const AGENTPLANE_HOME_ENV = "AGENTPLANE_HOME";
 const GLOBAL_RECIPES_DIR_NAME = "recipes";
 const PROJECT_RECIPES_CACHE_DIR_NAME = "recipes-cache";
 const SCENARIO_USAGE = "Usage: agentplane scenario <list|info|run> [args]";
+const SCENARIO_USAGE_EXAMPLE = "agentplane scenario list";
 const SCENARIO_INFO_USAGE = "Usage: agentplane scenario info <recipe:scenario>";
+const SCENARIO_INFO_USAGE_EXAMPLE = "agentplane scenario info viewer:demo";
 const SCENARIO_RUN_USAGE = "Usage: agentplane scenario run <recipe:scenario>";
+const SCENARIO_RUN_USAGE_EXAMPLE = "agentplane scenario run viewer:demo";
 const BACKEND_SYNC_USAGE = "Usage: agentplane backend sync <id> --direction <push|pull> [--conflict <diff|prefer-local|prefer-remote|fail>] [--yes] [--quiet]";
+const BACKEND_SYNC_USAGE_EXAMPLE = "agentplane backend sync local --direction pull";
 const SYNC_USAGE = "Usage: agentplane sync [<id>] [--direction <push|pull>] [--conflict <diff|prefer-local|prefer-remote|fail>] [--yes] [--quiet]";
+const SYNC_USAGE_EXAMPLE = "agentplane sync --direction push --yes";
 const READY_USAGE = "Usage: agentplane ready <task-id>";
+const READY_USAGE_EXAMPLE = "agentplane ready 202602030608-F1Q8AB";
 const ROLE_USAGE = "Usage: agentplane role <role>";
+const ROLE_USAGE_EXAMPLE = "agentplane role ORCHESTRATOR";
 const AGENTS_USAGE = "Usage: agentplane agents";
+const AGENTS_USAGE_EXAMPLE = "agentplane agents";
 const BRANCH_BASE_USAGE = "Usage: agentplane branch base get|set <name>";
+const BRANCH_BASE_USAGE_EXAMPLE = "agentplane branch base set main";
 const BRANCH_STATUS_USAGE = "Usage: agentplane branch status [--branch <name>] [--base <name>]";
+const BRANCH_STATUS_USAGE_EXAMPLE = "agentplane branch status --base main";
 const BRANCH_REMOVE_USAGE = "Usage: agentplane branch remove [--branch <name>] [--worktree <path>] [--force] [--quiet]";
+const BRANCH_REMOVE_USAGE_EXAMPLE = "agentplane branch remove --branch task/20260203-F1Q8AB --worktree .agentplane/worktrees/task";
 const UPGRADE_USAGE = "Usage: agentplane upgrade [--tag <tag>] [--dry-run] [--no-backup] [--source <repo-url>] [--bundle <path|url>] [--checksum <path|url>]";
+const UPGRADE_USAGE_EXAMPLE = "agentplane upgrade --tag v0.1.2 --dry-run";
+const INIT_USAGE = "Usage: agentplane init --ide <...> --workflow <...> --hooks <...> --require-plan-approval <...> --require-network-approval <...> [--recipes <...>] [--yes] [--force|--backup]";
+const INIT_USAGE_EXAMPLE = "agentplane init --ide codex --workflow direct --hooks false --require-plan-approval true --require-network-approval true --yes";
+const CONFIG_SET_USAGE = "Usage: agentplane config set <key> <value>";
+const CONFIG_SET_USAGE_EXAMPLE = "agentplane config set workflow_mode branch_pr";
+const MODE_SET_USAGE = "Usage: agentplane mode set <direct|branch_pr>";
+const MODE_SET_USAGE_EXAMPLE = "agentplane mode set direct";
+const QUICKSTART_USAGE = "Usage: agentplane quickstart";
+const QUICKSTART_USAGE_EXAMPLE = "agentplane quickstart";
+const TASK_UPDATE_USAGE = "Usage: agentplane task update <task-id> [flags]";
+const TASK_UPDATE_USAGE_EXAMPLE = 'agentplane task update 202602030608-F1Q8AB --title "..." --owner CODER';
+const TASK_SCAFFOLD_USAGE = "Usage: agentplane task scaffold <task-id> [--title <text>] [--overwrite] [--force]";
+const TASK_SCAFFOLD_USAGE_EXAMPLE = "agentplane task scaffold 202602030608-F1Q8AB";
+const TASK_SHOW_USAGE = "Usage: agentplane task show <task-id>";
+const TASK_SHOW_USAGE_EXAMPLE = "agentplane task show 202602030608-F1Q8AB";
+const TASK_SEARCH_USAGE = "Usage: agentplane task search <query> [flags]";
+const TASK_SEARCH_USAGE_EXAMPLE = 'agentplane task search "cli"';
+const TASK_COMMENT_USAGE = "Usage: agentplane task comment <task-id>";
+const TASK_COMMENT_USAGE_EXAMPLE = 'agentplane task comment 202602030608-F1Q8AB --author CODER --body "..."';
+const TASK_SET_STATUS_USAGE = "Usage: agentplane task set-status <task-id> <status> [flags]";
+const TASK_SET_STATUS_USAGE_EXAMPLE = "agentplane task set-status 202602030608-F1Q8AB DONE";
+const PR_GROUP_USAGE = "Usage: agentplane pr open|update|check|note <task-id>";
+const PR_GROUP_USAGE_EXAMPLE = "agentplane pr open 202602030608-F1Q8AB --author CODER";
+const GUARD_USAGE = "Usage: agentplane guard <subcommand>";
+const GUARD_USAGE_EXAMPLE = 'agentplane guard commit 202602030608-F1Q8AB -m "✨ F1Q8AB update" --allow packages/agentplane';
+const HOOKS_RUN_USAGE = "Usage: agentplane hooks run <hook>";
+const HOOKS_RUN_USAGE_EXAMPLE = "agentplane hooks run pre-commit";
+const HOOKS_INSTALL_USAGE = "Usage: agentplane hooks install|uninstall";
+const HOOKS_INSTALL_USAGE_EXAMPLE = "agentplane hooks install";
 const DEFAULT_UPGRADE_ASSET = "agentplane-upgrade.tar.gz";
 const DEFAULT_UPGRADE_CHECKSUM_ASSET = `${DEFAULT_UPGRADE_ASSET}.sha256`;
 function parseBooleanFlag(value, flag) {
@@ -289,7 +399,7 @@ function parseBooleanFlag(value, flag) {
     throw new CliError({
         exitCode: 2,
         code: "E_USAGE",
-        message: `Invalid value for ${flag}: ${value}`,
+        message: invalidValueForFlag(flag, value, "true|false"),
     });
 }
 function parseInitFlags(args) {
@@ -315,7 +425,7 @@ function parseInitFlags(args) {
         }
         const next = args[i + 1];
         if (!next) {
-            throw new CliError({ exitCode: 2, code: "E_USAGE", message: `Missing value for ${arg}` });
+            throw new CliError({ exitCode: 2, code: "E_USAGE", message: missingValueMessage(arg) });
         }
         switch (arg) {
             case "--ide": {
@@ -324,7 +434,7 @@ function parseInitFlags(args) {
                     throw new CliError({
                         exitCode: 2,
                         code: "E_USAGE",
-                        message: "Usage: --ide <codex|cursor|windsurf>",
+                        message: invalidValueForFlag("--ide", next, "codex|cursor|windsurf"),
                     });
                 }
                 out.ide = normalized;
@@ -335,7 +445,7 @@ function parseInitFlags(args) {
                     throw new CliError({
                         exitCode: 2,
                         code: "E_USAGE",
-                        message: "Usage: --workflow <direct|branch_pr>",
+                        message: invalidValueForFlag("--workflow", next, "direct|branch_pr"),
                     });
                 }
                 out.workflow = next;
@@ -386,7 +496,11 @@ function parseUpgradeFlags(args) {
         if (!arg)
             continue;
         if (!arg.startsWith("--")) {
-            throw new CliError({ exitCode: 2, code: "E_USAGE", message: UPGRADE_USAGE });
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: usageMessage(UPGRADE_USAGE, UPGRADE_USAGE_EXAMPLE),
+            });
         }
         if (arg === "--dry-run") {
             out.dryRun = true;
@@ -398,7 +512,7 @@ function parseUpgradeFlags(args) {
         }
         const next = args[i + 1];
         if (!next) {
-            throw new CliError({ exitCode: 2, code: "E_USAGE", message: `Missing value for ${arg}` });
+            throw new CliError({ exitCode: 2, code: "E_USAGE", message: missingValueMessage(arg) });
         }
         switch (arg) {
             case "--source": {
@@ -426,13 +540,21 @@ function parseUpgradeFlags(args) {
                 break;
             }
             default: {
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: UPGRADE_USAGE });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: usageMessage(UPGRADE_USAGE, UPGRADE_USAGE_EXAMPLE),
+                });
             }
         }
         i++;
     }
     if ((out.bundle && !out.checksum) || (!out.bundle && out.checksum)) {
-        throw new CliError({ exitCode: 2, code: "E_USAGE", message: UPGRADE_USAGE });
+        throw new CliError({
+            exitCode: 2,
+            code: "E_USAGE",
+            message: usageMessage(UPGRADE_USAGE, UPGRADE_USAGE_EXAMPLE),
+        });
     }
     return out;
 }
@@ -443,7 +565,11 @@ function parseRecipeListRemoteFlags(args) {
         if (!arg)
             continue;
         if (!arg.startsWith("--")) {
-            throw new CliError({ exitCode: 2, code: "E_USAGE", message: RECIPE_LIST_REMOTE_USAGE });
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: usageMessage(RECIPE_LIST_REMOTE_USAGE, RECIPE_LIST_REMOTE_USAGE_EXAMPLE),
+            });
         }
         if (arg === "--refresh") {
             out.refresh = true;
@@ -451,7 +577,7 @@ function parseRecipeListRemoteFlags(args) {
         }
         const next = args[i + 1];
         if (!next) {
-            throw new CliError({ exitCode: 2, code: "E_USAGE", message: `Missing value for ${arg}` });
+            throw new CliError({ exitCode: 2, code: "E_USAGE", message: missingValueMessage(arg) });
         }
         switch (arg) {
             case "--index": {
@@ -459,7 +585,11 @@ function parseRecipeListRemoteFlags(args) {
                 break;
             }
             default: {
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: RECIPE_LIST_REMOTE_USAGE });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: usageMessage(RECIPE_LIST_REMOTE_USAGE, RECIPE_LIST_REMOTE_USAGE_EXAMPLE),
+                });
             }
         }
         i++;
@@ -469,36 +599,36 @@ function parseRecipeListRemoteFlags(args) {
 function normalizeRecipeId(value) {
     const trimmed = value.trim();
     if (!trimmed)
-        throw new Error("manifest.id must be non-empty");
+        throw new Error(requiredFieldMessage("manifest.id"));
     if (trimmed.includes("/") || trimmed.includes("\\")) {
-        throw new Error("manifest.id must not contain path separators");
+        throw new Error(invalidPathMessage("manifest.id", "must not contain path separators"));
     }
     if (trimmed === "." || trimmed === "..") {
-        throw new Error("manifest.id must not be '.' or '..'");
+        throw new Error(invalidPathMessage("manifest.id", "must not be '.' or '..'"));
     }
     return trimmed;
 }
 function normalizeAgentId(value) {
     const trimmed = value.trim();
     if (!trimmed)
-        throw new Error("agent.id must be non-empty");
+        throw new Error(requiredFieldMessage("agent.id"));
     if (trimmed.includes("/") || trimmed.includes("\\")) {
-        throw new Error("agent.id must not contain path separators");
+        throw new Error(invalidPathMessage("agent.id", "must not contain path separators"));
     }
     if (trimmed === "." || trimmed === "..") {
-        throw new Error("agent.id must not be '.' or '..'");
+        throw new Error(invalidPathMessage("agent.id", "must not be '.' or '..'"));
     }
     return trimmed;
 }
 function normalizeScenarioId(value) {
     const trimmed = value.trim();
     if (!trimmed)
-        throw new Error("scenario.id must be non-empty");
+        throw new Error(requiredFieldMessage("scenario.id"));
     if (trimmed.includes("/") || trimmed.includes("\\")) {
-        throw new Error("scenario.id must not contain path separators");
+        throw new Error(invalidPathMessage("scenario.id", "must not contain path separators"));
     }
     if (trimmed === "." || trimmed === "..") {
-        throw new Error("scenario.id must not be '.' or '..'");
+        throw new Error(invalidPathMessage("scenario.id", "must not be '.' or '..'"));
     }
     return trimmed;
 }
@@ -506,33 +636,33 @@ function normalizeRecipeTags(value) {
     if (value === undefined)
         return [];
     if (!Array.isArray(value))
-        throw new Error("manifest.tags must be an array of strings");
+        throw new Error(invalidFieldMessage("manifest.tags", "string[]"));
     const tags = value.map((tag) => {
         if (typeof tag !== "string")
-            throw new Error("manifest.tags must be an array of strings");
+            throw new Error(invalidFieldMessage("manifest.tags", "string[]"));
         return tag.trim();
     });
     return dedupeStrings(tags);
 }
 function validateRecipeManifest(raw) {
     if (!isRecord(raw))
-        throw new Error("manifest must be an object");
+        throw new Error(invalidFieldMessage("manifest", "object"));
     if (raw.schema_version !== "1")
-        throw new Error("manifest.schema_version must be '1'");
+        throw new Error(invalidFieldMessage("manifest.schema_version", '"1"'));
     if (typeof raw.id !== "string")
-        throw new Error("manifest.id must be string");
+        throw new Error(invalidFieldMessage("manifest.id", "string"));
     if (typeof raw.version !== "string")
-        throw new Error("manifest.version must be string");
+        throw new Error(invalidFieldMessage("manifest.version", "string"));
     if (typeof raw.name !== "string")
-        throw new Error("manifest.name must be string");
+        throw new Error(invalidFieldMessage("manifest.name", "string"));
     if (typeof raw.summary !== "string")
-        throw new Error("manifest.summary must be string");
+        throw new Error(invalidFieldMessage("manifest.summary", "string"));
     if (typeof raw.description !== "string")
-        throw new Error("manifest.description must be string");
+        throw new Error(invalidFieldMessage("manifest.description", "string"));
     const id = normalizeRecipeId(raw.id);
     const version = raw.version.trim();
     if (!version)
-        throw new Error("manifest.version must be non-empty");
+        throw new Error(requiredFieldMessage("manifest.version"));
     const tags = normalizeRecipeTags(raw.tags);
     return {
         schema_version: "1",
@@ -551,11 +681,11 @@ function validateRecipeManifest(raw) {
 }
 function validateInstalledRecipesFile(raw) {
     if (!isRecord(raw))
-        throw new Error("recipes.json must be an object");
+        throw new Error(invalidFieldMessage("recipes.json", "object"));
     if (raw.schema_version !== 1)
-        throw new Error("recipes.json schema_version must be 1");
+        throw new Error(invalidFieldMessage("recipes.json.schema_version", "1"));
     if (!Array.isArray(raw.recipes))
-        throw new Error("recipes.json recipes must be array");
+        throw new Error(invalidFieldMessage("recipes.json.recipes", "array"));
     const updatedAt = typeof raw.updated_at === "string" ? raw.updated_at : "";
     const recipes = raw.recipes
         .filter((entry) => isRecord(entry))
@@ -566,10 +696,10 @@ function validateInstalledRecipesFile(raw) {
         const source = typeof entry.source === "string" ? entry.source.trim() : "";
         const installedAt = typeof entry.installed_at === "string" ? entry.installed_at.trim() : "";
         if (!id || !version || !source || !installedAt) {
-            throw new Error("recipes.json entries must include id, version, source, installed_at");
+            throw new Error(invalidFieldMessage("recipes.json.recipes[]", "id, version, source, installed_at"));
         }
         if (id !== manifest.id || version !== manifest.version) {
-            throw new Error("recipes.json entry id/version must match manifest");
+            throw new Error(invalidFieldMessage("recipes.json.recipes[]", "id/version match manifest"));
         }
         const tags = normalizeRecipeTags(entry.tags ?? manifest.tags ?? []);
         return { id, version, source, installed_at: installedAt, tags, manifest };
@@ -582,11 +712,11 @@ function sortInstalledRecipes(file) {
 }
 function validateRecipesIndex(raw) {
     if (!isRecord(raw))
-        throw new Error("recipes index must be an object");
+        throw new Error(invalidFieldMessage("recipes index", "object"));
     if (raw.schema_version !== 1)
-        throw new Error("recipes index schema_version must be 1");
+        throw new Error(invalidFieldMessage("recipes index.schema_version", "1"));
     if (!Array.isArray(raw.recipes))
-        throw new Error("recipes index recipes must be array");
+        throw new Error(invalidFieldMessage("recipes index.recipes", "array"));
     const recipes = raw.recipes
         .filter((entry) => isRecord(entry))
         .map((entry) => {
@@ -595,7 +725,7 @@ function validateRecipesIndex(raw) {
         const description = typeof entry.description === "string" ? entry.description : undefined;
         const versionsRaw = Array.isArray(entry.versions) ? entry.versions : [];
         if (!id || !summary || versionsRaw.length === 0) {
-            throw new Error("recipes index entries must include id, summary, and versions");
+            throw new Error(invalidFieldMessage("recipes index.recipes[]", "id, summary, versions"));
         }
         const versions = versionsRaw
             .filter((version) => isRecord(version))
@@ -604,7 +734,7 @@ function validateRecipesIndex(raw) {
             const url = typeof version.url === "string" ? version.url : "";
             const sha256 = typeof version.sha256 === "string" ? version.sha256 : "";
             if (!versionId || !url || !sha256) {
-                throw new Error("recipes index versions must include version, url, sha256");
+                throw new Error(invalidFieldMessage("recipes index.recipes[].versions[]", "version, url, sha256"));
             }
             return {
                 version: versionId,
@@ -624,21 +754,21 @@ function validateRecipesIndex(raw) {
 }
 function validateScenarioDefinition(raw, sourcePath) {
     if (!isRecord(raw))
-        throw new Error(`scenario must be an object (${sourcePath})`);
+        throw new Error(invalidFieldMessage("scenario", "object", sourcePath));
     if (raw.schema_version !== undefined && raw.schema_version !== "1") {
-        throw new Error(`scenario.schema_version must be "1" (${sourcePath})`);
+        throw new Error(invalidFieldMessage("scenario.schema_version", '"1"', sourcePath));
     }
     const rawId = typeof raw.id === "string" ? raw.id : "";
     const id = normalizeScenarioId(rawId);
     const goal = typeof raw.goal === "string" ? raw.goal.trim() : "";
     if (!goal)
-        throw new Error(`scenario.goal must be non-empty (${sourcePath})`);
+        throw new Error(requiredFieldMessage("scenario.goal", sourcePath));
     if (!("inputs" in raw))
-        throw new Error(`scenario.inputs is required (${sourcePath})`);
+        throw new Error(requiredFieldMessage("scenario.inputs", sourcePath));
     if (!("outputs" in raw))
-        throw new Error(`scenario.outputs is required (${sourcePath})`);
+        throw new Error(requiredFieldMessage("scenario.outputs", sourcePath));
     if (!Array.isArray(raw.steps)) {
-        throw new Error(`scenario.steps must be an array (${sourcePath})`);
+        throw new Error(invalidFieldMessage("scenario.steps", "array", sourcePath));
     }
     return {
         schema_version: "1",
@@ -658,11 +788,11 @@ async function readScenarioDefinition(filePath) {
 async function readScenarioIndex(filePath) {
     const raw = JSON.parse(await readFile(filePath, "utf8"));
     if (!isRecord(raw))
-        throw new Error("scenarios index must be an object");
+        throw new Error(invalidFieldMessage("scenarios index", "object"));
     if (raw.schema_version !== 1)
-        throw new Error("scenarios index schema_version must be 1");
+        throw new Error(invalidFieldMessage("scenarios index.schema_version", "1"));
     if (!Array.isArray(raw.scenarios))
-        throw new Error("scenarios index scenarios must be array");
+        throw new Error(invalidFieldMessage("scenarios index.scenarios", "array"));
     const scenarios = raw.scenarios
         .filter((entry) => isRecord(entry))
         .map((entry) => ({
@@ -728,24 +858,24 @@ async function collectRecipeScenarioDetails(recipeDir, manifest) {
 }
 function normalizeScenarioToolStep(raw, sourcePath) {
     if (!isRecord(raw)) {
-        throw new Error(`scenario step must be an object (${sourcePath})`);
+        throw new Error(invalidFieldMessage("scenario step", "object", sourcePath));
     }
     const tool = typeof raw.tool === "string" ? raw.tool.trim() : "";
     if (!tool) {
-        throw new Error(`scenario step is missing tool id (${sourcePath})`);
+        throw new Error(requiredFieldMessage("scenario step.tool", sourcePath));
     }
     const args = Array.isArray(raw.args) ? raw.args.filter((arg) => typeof arg === "string") : [];
     if (Array.isArray(raw.args) && args.length !== raw.args.length) {
-        throw new Error(`scenario step args must be strings (${sourcePath})`);
+        throw new Error(invalidFieldMessage("scenario step.args", "string[]", sourcePath));
     }
     const env = {};
     if (raw.env !== undefined) {
         if (!isRecord(raw.env)) {
-            throw new Error(`scenario step env must be an object (${sourcePath})`);
+            throw new Error(invalidFieldMessage("scenario step.env", "object", sourcePath));
         }
         for (const [key, value] of Object.entries(raw.env)) {
             if (typeof value !== "string") {
-                throw new Error(`scenario step env values must be strings (${sourcePath})`);
+                throw new Error(invalidFieldMessage("scenario step.env", "string map", sourcePath));
             }
             env[key] = value;
         }
@@ -783,11 +913,11 @@ async function resolveRecipeRoot(extractedDir) {
     const entries = await readdir(extractedDir, { withFileTypes: true });
     const dirs = entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
     if (dirs.length !== 1) {
-        throw new Error("manifest.json not found at archive root");
+        throw new Error(missingFileMessage("manifest.json", "archive root"));
     }
     const candidate = path.join(extractedDir, dirs[0]);
     if (!(await fileExists(path.join(candidate, "manifest.json")))) {
-        throw new Error("manifest.json not found at archive root");
+        throw new Error(missingFileMessage("manifest.json", "archive root"));
     }
     return candidate;
 }
@@ -823,7 +953,11 @@ function resolveProjectRecipesCacheDir(resolved) {
 async function extractArchive(archivePath, destDir) {
     const archiveType = detectArchiveType(archivePath);
     if (!archiveType) {
-        throw new CliError({ exitCode: 2, code: "E_USAGE", message: RECIPE_INSTALL_USAGE });
+        throw new CliError({
+            exitCode: 2,
+            code: "E_USAGE",
+            message: usageMessage(RECIPE_INSTALL_USAGE, RECIPE_INSTALL_USAGE_EXAMPLE),
+        });
     }
     if (archiveType === "tar") {
         await execFileAsync("tar", ["-xzf", archivePath, "-C", destDir]);
@@ -879,7 +1013,11 @@ function parseRecipeInstallArgs(args) {
         if (arg === "--name") {
             const next = args[i + 1];
             if (!next)
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: RECIPE_INSTALL_USAGE });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: usageMessage(RECIPE_INSTALL_USAGE, RECIPE_INSTALL_USAGE_EXAMPLE),
+                });
             name = next;
             i++;
             continue;
@@ -887,7 +1025,11 @@ function parseRecipeInstallArgs(args) {
         if (arg === "--path") {
             const next = args[i + 1];
             if (!next)
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: RECIPE_INSTALL_USAGE });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: usageMessage(RECIPE_INSTALL_USAGE, RECIPE_INSTALL_USAGE_EXAMPLE),
+                });
             localPath = next;
             i++;
             continue;
@@ -895,7 +1037,11 @@ function parseRecipeInstallArgs(args) {
         if (arg === "--url") {
             const next = args[i + 1];
             if (!next)
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: RECIPE_INSTALL_USAGE });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: usageMessage(RECIPE_INSTALL_USAGE, RECIPE_INSTALL_USAGE_EXAMPLE),
+                });
             url = next;
             i++;
             continue;
@@ -903,7 +1049,11 @@ function parseRecipeInstallArgs(args) {
         if (arg === "--index") {
             const next = args[i + 1];
             if (!next)
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: RECIPE_INSTALL_USAGE });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: usageMessage(RECIPE_INSTALL_USAGE, RECIPE_INSTALL_USAGE_EXAMPLE),
+                });
             index = next;
             i++;
             continue;
@@ -915,28 +1065,52 @@ function parseRecipeInstallArgs(args) {
         if (arg === "--on-conflict") {
             const next = args[i + 1];
             if (!next)
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: RECIPE_INSTALL_USAGE });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: usageMessage(RECIPE_INSTALL_USAGE, RECIPE_INSTALL_USAGE_EXAMPLE),
+                });
             if (!RECIPE_CONFLICT_MODES.includes(next)) {
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: RECIPE_INSTALL_USAGE });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: usageMessage(RECIPE_INSTALL_USAGE, RECIPE_INSTALL_USAGE_EXAMPLE),
+                });
             }
             onConflict = next;
             i++;
             continue;
         }
         if (arg.startsWith("--")) {
-            throw new CliError({ exitCode: 2, code: "E_USAGE", message: RECIPE_INSTALL_USAGE });
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: usageMessage(RECIPE_INSTALL_USAGE, RECIPE_INSTALL_USAGE_EXAMPLE),
+            });
         }
         positional.push(arg);
     }
     const explicitFlags = [name, localPath, url].filter(Boolean).length;
     if (explicitFlags > 1) {
-        throw new CliError({ exitCode: 2, code: "E_USAGE", message: RECIPE_INSTALL_USAGE });
+        throw new CliError({
+            exitCode: 2,
+            code: "E_USAGE",
+            message: usageMessage(RECIPE_INSTALL_USAGE, RECIPE_INSTALL_USAGE_EXAMPLE),
+        });
     }
     if (positional.length > 1) {
-        throw new CliError({ exitCode: 2, code: "E_USAGE", message: RECIPE_INSTALL_USAGE });
+        throw new CliError({
+            exitCode: 2,
+            code: "E_USAGE",
+            message: usageMessage(RECIPE_INSTALL_USAGE, RECIPE_INSTALL_USAGE_EXAMPLE),
+        });
     }
     if (positional.length > 0 && explicitFlags > 0) {
-        throw new CliError({ exitCode: 2, code: "E_USAGE", message: RECIPE_INSTALL_USAGE });
+        throw new CliError({
+            exitCode: 2,
+            code: "E_USAGE",
+            message: usageMessage(RECIPE_INSTALL_USAGE, RECIPE_INSTALL_USAGE_EXAMPLE),
+        });
     }
     if (name)
         return { source: { type: "name", value: name }, index, refresh, onConflict };
@@ -947,7 +1121,11 @@ function parseRecipeInstallArgs(args) {
     if (positional.length === 1) {
         return { source: { type: "auto", value: positional[0] }, index, refresh, onConflict };
     }
-    throw new CliError({ exitCode: 2, code: "E_USAGE", message: RECIPE_INSTALL_USAGE });
+    throw new CliError({
+        exitCode: 2,
+        code: "E_USAGE",
+        message: usageMessage(RECIPE_INSTALL_USAGE, RECIPE_INSTALL_USAGE_EXAMPLE),
+    });
 }
 function parseRecipeListArgs(args) {
     const flags = { full: false };
@@ -962,18 +1140,34 @@ function parseRecipeListArgs(args) {
         if (arg === "--tag") {
             const next = args[i + 1];
             if (!next)
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: RECIPE_USAGE });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: usageMessage(RECIPE_USAGE, RECIPE_USAGE_EXAMPLE),
+                });
             flags.tag = next.trim();
             i++;
             continue;
         }
         if (arg.startsWith("--")) {
-            throw new CliError({ exitCode: 2, code: "E_USAGE", message: RECIPE_USAGE });
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: usageMessage(RECIPE_USAGE, RECIPE_USAGE_EXAMPLE),
+            });
         }
-        throw new CliError({ exitCode: 2, code: "E_USAGE", message: RECIPE_USAGE });
+        throw new CliError({
+            exitCode: 2,
+            code: "E_USAGE",
+            message: usageMessage(RECIPE_USAGE, RECIPE_USAGE_EXAMPLE),
+        });
     }
     if (flags.tag !== undefined && !flags.tag) {
-        throw new CliError({ exitCode: 2, code: "E_USAGE", message: RECIPE_USAGE });
+        throw new CliError({
+            exitCode: 2,
+            code: "E_USAGE",
+            message: usageMessage(RECIPE_USAGE, RECIPE_USAGE_EXAMPLE),
+        });
     }
     return flags;
 }
@@ -990,7 +1184,11 @@ function parseRecipeCachePruneArgs(args) {
             flags.all = true;
             continue;
         }
-        throw new CliError({ exitCode: 2, code: "E_USAGE", message: RECIPE_CACHE_PRUNE_USAGE });
+        throw new CliError({
+            exitCode: 2,
+            code: "E_USAGE",
+            message: usageMessage(RECIPE_CACHE_PRUNE_USAGE, RECIPE_CACHE_PRUNE_USAGE_EXAMPLE),
+        });
     }
     return flags;
 }
@@ -1006,7 +1204,11 @@ function parseBackendSyncArgs(args) {
             continue;
         if (!arg.startsWith("--")) {
             if (backendId) {
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: BACKEND_SYNC_USAGE });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: usageMessage(BACKEND_SYNC_USAGE, BACKEND_SYNC_USAGE_EXAMPLE),
+                });
             }
             backendId = arg;
             continue;
@@ -1014,7 +1216,11 @@ function parseBackendSyncArgs(args) {
         if (arg === "--direction") {
             const next = args[i + 1];
             if (!next || (next !== "push" && next !== "pull")) {
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: BACKEND_SYNC_USAGE });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: usageMessage(BACKEND_SYNC_USAGE, BACKEND_SYNC_USAGE_EXAMPLE),
+                });
             }
             direction = next;
             i++;
@@ -1023,7 +1229,11 @@ function parseBackendSyncArgs(args) {
         if (arg === "--conflict") {
             const next = args[i + 1];
             if (!next || !["diff", "prefer-local", "prefer-remote", "fail"].includes(next)) {
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: BACKEND_SYNC_USAGE });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: usageMessage(BACKEND_SYNC_USAGE, BACKEND_SYNC_USAGE_EXAMPLE),
+                });
             }
             conflict = next;
             i++;
@@ -1037,10 +1247,18 @@ function parseBackendSyncArgs(args) {
             quiet = true;
             continue;
         }
-        throw new CliError({ exitCode: 2, code: "E_USAGE", message: BACKEND_SYNC_USAGE });
+        throw new CliError({
+            exitCode: 2,
+            code: "E_USAGE",
+            message: usageMessage(BACKEND_SYNC_USAGE, BACKEND_SYNC_USAGE_EXAMPLE),
+        });
     }
     if (!backendId || !direction) {
-        throw new CliError({ exitCode: 2, code: "E_USAGE", message: BACKEND_SYNC_USAGE });
+        throw new CliError({
+            exitCode: 2,
+            code: "E_USAGE",
+            message: usageMessage(BACKEND_SYNC_USAGE, BACKEND_SYNC_USAGE_EXAMPLE),
+        });
     }
     return { backendId, direction, conflict, confirm, quiet };
 }
@@ -1056,7 +1274,11 @@ function parseSyncArgs(args) {
             continue;
         if (!arg.startsWith("--")) {
             if (backendId) {
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: SYNC_USAGE });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: usageMessage(SYNC_USAGE, SYNC_USAGE_EXAMPLE),
+                });
             }
             backendId = arg;
             continue;
@@ -1064,7 +1286,11 @@ function parseSyncArgs(args) {
         if (arg === "--direction") {
             const next = args[i + 1];
             if (!next || (next !== "push" && next !== "pull")) {
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: SYNC_USAGE });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: usageMessage(SYNC_USAGE, SYNC_USAGE_EXAMPLE),
+                });
             }
             direction = next;
             i++;
@@ -1073,7 +1299,11 @@ function parseSyncArgs(args) {
         if (arg === "--conflict") {
             const next = args[i + 1];
             if (!next || !["diff", "prefer-local", "prefer-remote", "fail"].includes(next)) {
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: SYNC_USAGE });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: usageMessage(SYNC_USAGE, SYNC_USAGE_EXAMPLE),
+                });
             }
             conflict = next;
             i++;
@@ -1087,7 +1317,11 @@ function parseSyncArgs(args) {
             quiet = true;
             continue;
         }
-        throw new CliError({ exitCode: 2, code: "E_USAGE", message: SYNC_USAGE });
+        throw new CliError({
+            exitCode: 2,
+            code: "E_USAGE",
+            message: usageMessage(SYNC_USAGE, SYNC_USAGE_EXAMPLE),
+        });
     }
     return { backendId, direction, conflict, confirm, quiet };
 }
@@ -1106,11 +1340,11 @@ async function applyRecipeAgents(opts) {
         const agentId = normalizeAgentId(rawId);
         const sourcePath = path.join(opts.recipeDir, rawFile);
         if (!(await fileExists(sourcePath))) {
-            throw new Error(`Recipe agent file not found: ${rawFile}`);
+            throw new Error(missingFileMessage("recipe agent file", rawFile));
         }
         const rawAgent = JSON.parse(await readFile(sourcePath, "utf8"));
         if (!isRecord(rawAgent)) {
-            throw new Error(`Recipe agent file must be a JSON object: ${rawFile}`);
+            throw new Error(invalidFieldMessage("recipe agent file", "JSON object", rawFile));
         }
         const baseId = `${opts.manifest.id}__${agentId}`;
         let targetId = baseId;
@@ -1191,19 +1425,19 @@ async function loadRecipesRemoteIndex(opts) {
 function parseGitHubRepo(source) {
     const trimmed = source.trim();
     if (!trimmed)
-        throw new Error("config.framework.source must be non-empty");
+        throw new Error(requiredFieldMessage("config.framework.source"));
     if (!trimmed.includes("github.com")) {
-        throw new Error("upgrade supports GitHub sources only");
+        throw new Error(invalidFieldMessage("config.framework.source", "GitHub URL"));
     }
     try {
         const url = new URL(trimmed);
         const parts = url.pathname.replaceAll(".git", "").split("/").filter(Boolean);
         if (parts.length < 2)
-            throw new Error("Invalid GitHub repo URL");
+            throw new Error(invalidValueMessage("GitHub repo URL", trimmed, "owner/repo"));
         return { owner: parts[0], repo: parts[1] };
     }
     catch {
-        throw new Error("Invalid GitHub repo URL");
+        throw new Error(invalidValueMessage("GitHub repo URL", trimmed, "owner/repo"));
     }
 }
 async function resolveUpgradeRoot(extractedDir) {
@@ -1260,7 +1494,7 @@ async function cmdInit(opts) {
         throw new CliError({
             exitCode: 2,
             code: "E_USAGE",
-            message: "Usage: agentplane init --ide <...> --workflow <...> --hooks <...> --require-plan-approval <...> --require-network-approval <...> [--recipes <...>] [--yes] [--force|--backup]",
+            message: usageMessage(INIT_USAGE, INIT_USAGE_EXAMPLE),
         });
     }
     if (process.stdin.isTTY && !flags.yes) {
@@ -1413,10 +1647,10 @@ async function cmdInit(opts) {
         }
         if (recipes.length > 0) {
             if (listBundledRecipes().length === 0) {
-                process.stdout.write("Bundled recipes catalog is empty; skipping install.\n");
+                process.stdout.write(`${infoMessage("bundled recipes are empty; nothing to install")}\n`);
             }
             else {
-                process.stdout.write("Recipes install is not implemented yet; skipping.\n");
+                process.stdout.write(`${infoMessage("bundled recipe install is not implemented; skipping")}\n`);
             }
         }
         await ensureInitCommit({
@@ -1636,13 +1870,21 @@ function cmdRole(opts) {
     try {
         const roleRaw = opts.role.trim();
         if (!roleRaw) {
-            throw new CliError({ exitCode: 2, code: "E_USAGE", message: ROLE_USAGE });
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: usageMessage(ROLE_USAGE, ROLE_USAGE_EXAMPLE),
+            });
         }
         const guide = renderRole(roleRaw);
         if (!guide) {
             const roles = listRoles();
             const available = roles.length > 0 ? `\nAvailable roles: ${roles.join(", ")}` : "";
-            throw new CliError({ exitCode: 2, code: "E_USAGE", message: `${ROLE_USAGE}${available}` });
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: usageMessage(`${ROLE_USAGE}${available}`, ROLE_USAGE_EXAMPLE),
+            });
         }
         process.stdout.write(`${guide}\n`);
         return 0;
@@ -1675,7 +1917,7 @@ async function cmdAgents(opts) {
             throw new CliError({
                 exitCode: 2,
                 code: "E_USAGE",
-                message: `Missing directory: ${agentsDir}`,
+                message: `Agents directory not found: ${agentsDir} (run \`agentplane init\`)`,
             });
         }
         const entriesRaw = await readdir(agentsDir);
@@ -1684,7 +1926,7 @@ async function cmdAgents(opts) {
             throw new CliError({
                 exitCode: 2,
                 code: "E_USAGE",
-                message: `No agents found under ${agentsDir}`,
+                message: `No agent definitions found under ${agentsDir} (expected *.json)`,
             });
         }
         const rows = [];
@@ -1739,10 +1981,10 @@ async function cmdRecipeList(opts) {
         }
         if (recipes.length === 0) {
             if (flags.tag) {
-                process.stdout.write(`No recipes matched tag: ${flags.tag}\n`);
+                process.stdout.write(`${emptyStateMessage(`installed recipes for tag ${flags.tag}`)}\n`);
                 return 0;
             }
-            process.stdout.write("No recipes installed.\n");
+            process.stdout.write(`${emptyStateMessage("installed recipes", "Use `agentplane recipes list-remote` or `agentplane recipes install <id>`.")}\n`);
             return 0;
         }
         if (flags.full) {
@@ -1755,7 +1997,7 @@ async function cmdRecipeList(opts) {
             return 0;
         }
         for (const entry of recipes) {
-            process.stdout.write(`${entry.id}@${entry.version} - ${entry.manifest.summary || "No summary provided."}\n`);
+            process.stdout.write(`${entry.id}@${entry.version} - ${entry.manifest.summary || "No summary"}\n`);
         }
         return 0;
     }
@@ -1818,7 +2060,7 @@ async function cmdScenarioList(opts) {
             }
         }
         if (entries.length === 0) {
-            process.stdout.write("No scenarios installed.\n");
+            process.stdout.write(`${emptyStateMessage("scenarios", "Install a recipe to add scenarios.")}\n`);
             return 0;
         }
         const sorted = entries.toSorted((a, b) => {
@@ -1828,7 +2070,7 @@ async function cmdScenarioList(opts) {
             return a.scenarioId.localeCompare(b.scenarioId);
         });
         for (const entry of sorted) {
-            process.stdout.write(`${entry.recipeId}:${entry.scenarioId} - ${entry.summary ?? "No summary provided."}\n`);
+            process.stdout.write(`${entry.recipeId}:${entry.scenarioId} - ${entry.summary ?? "No summary"}\n`);
         }
         return 0;
     }
@@ -1842,7 +2084,11 @@ async function cmdScenarioInfo(opts) {
     try {
         const [recipeId, scenarioId] = opts.id.split(":");
         if (!recipeId || !scenarioId) {
-            throw new CliError({ exitCode: 2, code: "E_USAGE", message: SCENARIO_INFO_USAGE });
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: usageMessage(SCENARIO_INFO_USAGE, SCENARIO_INFO_USAGE_EXAMPLE),
+            });
         }
         const installed = await readInstalledRecipesFile(resolveInstalledRecipesPath());
         const entry = installed.recipes.find((recipe) => recipe.id === recipeId);
@@ -1944,7 +2190,11 @@ async function cmdScenarioRun(opts) {
         });
         const [recipeId, scenarioId] = opts.id.split(":");
         if (!recipeId || !scenarioId) {
-            throw new CliError({ exitCode: 2, code: "E_USAGE", message: SCENARIO_RUN_USAGE });
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: usageMessage(SCENARIO_RUN_USAGE, SCENARIO_RUN_USAGE_EXAMPLE),
+            });
         }
         const installed = await readInstalledRecipesFile(resolveInstalledRecipesPath());
         const entry = installed.recipes.find((recipe) => recipe.id === recipeId);
@@ -2416,7 +2666,7 @@ async function cmdRecipeRemove(opts) {
             updated_at: installed.updated_at,
             recipes: updated,
         });
-        process.stdout.write(`Removed recipe ${entry.id}@${entry.version}\n`);
+        process.stdout.write(`${successMessage("removed recipe", `${entry.id}@${entry.version}`)}\n`);
         return 0;
     }
     catch (err) {
@@ -2452,20 +2702,20 @@ async function cmdRecipeCachePrune(opts) {
     try {
         const cacheDir = resolveGlobalRecipesDir();
         if (!(await fileExists(cacheDir))) {
-            process.stdout.write("No recipes directory found.\n");
+            process.stdout.write(`${infoMessage(`recipe cache directory not found: ${cacheDir}`)}\n`);
             return 0;
         }
         const cacheEntries = await listRecipeCacheEntries(cacheDir);
         if (cacheEntries.length === 0) {
-            process.stdout.write("No cached recipes found.\n");
+            process.stdout.write(`${infoMessage("recipe cache is empty")}\n`);
             return 0;
         }
         if (flags.all) {
             if (flags.dryRun) {
                 for (const entry of cacheEntries) {
-                    process.stdout.write(`Would remove ${entry.id}@${entry.version}\n`);
+                    process.stdout.write(`${infoMessage(`dry-run: would remove ${entry.id}@${entry.version}`)}\n`);
                 }
-                process.stdout.write(`Would remove ${cacheEntries.length} cached recipes.\n`);
+                process.stdout.write(`${infoMessage(`dry-run: would remove ${cacheEntries.length} cached recipes`)}\n`);
                 return 0;
             }
             await rm(cacheDir, { recursive: true, force: true });
@@ -2474,21 +2724,21 @@ async function cmdRecipeCachePrune(opts) {
                 updated_at: "",
                 recipes: [],
             });
-            process.stdout.write(`Removed ${cacheEntries.length} cached recipes.\n`);
+            process.stdout.write(`${successMessage("removed cached recipes", undefined, `count=${cacheEntries.length}`)}\n`);
             return 0;
         }
         const installed = await readInstalledRecipesFile(resolveInstalledRecipesPath());
         const keep = new Set(installed.recipes.map((entry) => `${entry.id}@${entry.version}`));
         const prune = cacheEntries.filter((entry) => !keep.has(`${entry.id}@${entry.version}`));
         if (prune.length === 0) {
-            process.stdout.write("No cached recipes to prune.\n");
+            process.stdout.write(`${infoMessage("recipe cache already clean (no uninstalled entries)")}\n`);
             return 0;
         }
         if (flags.dryRun) {
             for (const entry of prune) {
-                process.stdout.write(`Would remove ${entry.id}@${entry.version}\n`);
+                process.stdout.write(`${infoMessage(`dry-run: would remove ${entry.id}@${entry.version}`)}\n`);
             }
-            process.stdout.write(`Would remove ${prune.length} cached recipes.\n`);
+            process.stdout.write(`${infoMessage(`dry-run: would remove ${prune.length} cached recipes`)}\n`);
             return 0;
         }
         const recipeDirs = new Set();
@@ -2502,7 +2752,7 @@ async function cmdRecipeCachePrune(opts) {
                 await rm(recipeDir, { recursive: true, force: true });
             }
         }
-        process.stdout.write(`Removed ${prune.length} cached recipes.\n`);
+        process.stdout.write(`${successMessage("removed cached recipes", undefined, `count=${prune.length}`)}\n`);
         return 0;
     }
     catch (err) {
@@ -2529,7 +2779,7 @@ async function cmdBackendSync(opts) {
             throw new CliError({
                 exitCode: 2,
                 code: "E_USAGE",
-                message: "Configured backend does not support sync()",
+                message: backendNotSupportedMessage("sync()"),
             });
         }
         await backend.sync({
@@ -2564,7 +2814,7 @@ async function cmdSync(opts) {
             throw new CliError({
                 exitCode: 2,
                 code: "E_USAGE",
-                message: "Configured backend does not support sync()",
+                message: backendNotSupportedMessage("sync()"),
             });
         }
         await backend.sync({
@@ -2581,6 +2831,12 @@ async function cmdSync(opts) {
         throw mapBackendError(err, { command: "sync", root: opts.rootOverride ?? null });
     }
 }
+const TASK_NEW_USAGE = "Usage: agentplane task new --title <text> --description <text> --priority <low|normal|med|high> --owner <id> --tag <tag> [--tag <tag>...]";
+const TASK_NEW_USAGE_EXAMPLE = 'agentplane task new --title "Refactor CLI" --description "Improve CLI output" --priority med --owner CODER --tag cli';
+const TASK_ADD_USAGE = "Usage: agentplane task add <task-id> [<task-id> ...] --title <text> --description <text> --priority <low|normal|med|high> --owner <id> --tag <tag> [--tag <tag>...]";
+const TASK_ADD_USAGE_EXAMPLE = 'agentplane task add 202602030608-F1Q8AB --title "..." --description "..." --priority med --owner CODER --tag cli';
+const TASK_SCRUB_USAGE = "Usage: agentplane task scrub --find <text> --replace <text> [flags]";
+const TASK_SCRUB_USAGE_EXAMPLE = 'agentplane task scrub --find "agentctl" --replace "agentplane" --dry-run';
 function parseTaskNewFlags(args) {
     const out = { tags: [], dependsOn: [], verify: [] };
     for (let i = 0; i < args.length; i++) {
@@ -2596,7 +2852,7 @@ function parseTaskNewFlags(args) {
         }
         const next = args[i + 1];
         if (!next) {
-            throw new CliError({ exitCode: 2, code: "E_USAGE", message: `Missing value for ${arg}` });
+            throw new CliError({ exitCode: 2, code: "E_USAGE", message: missingValueMessage(arg) });
         }
         switch (arg) {
             case "--title": {
@@ -2642,7 +2898,7 @@ async function cmdTaskNew(opts) {
         throw new CliError({
             exitCode: 2,
             code: "E_USAGE",
-            message: "Usage: agentplane task new --title <text> --description <text> --priority <low|normal|med|high> --owner <id> --tag <tag> [--tag <tag>...]",
+            message: usageMessage(TASK_NEW_USAGE, TASK_NEW_USAGE_EXAMPLE),
         });
     }
     try {
@@ -2655,7 +2911,7 @@ async function cmdTaskNew(opts) {
             throw new CliError({
                 exitCode: 3,
                 code: "E_VALIDATION",
-                message: "Configured backend does not support generateTaskId()",
+                message: backendNotSupportedMessage("generateTaskId()"),
             });
         }
         const taskId = await backend.generateTaskId({ length: suffixLength, attempts: 1000 });
@@ -2680,7 +2936,7 @@ async function cmdTaskNew(opts) {
             throw new CliError({
                 exitCode: 2,
                 code: "E_USAGE",
-                message: "verify commands are required for tasks with code/backend/frontend tags",
+                message: "Missing verify commands for tasks with code/backend/frontend tags (use --verify)",
             });
         }
         await backend.writeTask(task);
@@ -2713,10 +2969,14 @@ function parseTaskAddFlags(args) {
         }
         const next = args[i + 1];
         if (arg === "--replace-tags" || arg === "--replace-depends-on" || arg === "--replace-verify") {
-            throw new CliError({ exitCode: 2, code: "E_USAGE", message: "Usage: agentplane task add" });
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: usageMessage(TASK_ADD_USAGE, TASK_ADD_USAGE_EXAMPLE),
+            });
         }
         if (!next) {
-            throw new CliError({ exitCode: 2, code: "E_USAGE", message: `Missing value for ${arg}` });
+            throw new CliError({ exitCode: 2, code: "E_USAGE", message: missingValueMessage(arg) });
         }
         switch (arg) {
             case "--title": {
@@ -2778,7 +3038,7 @@ async function cmdTaskAdd(opts) {
         throw new CliError({
             exitCode: 2,
             code: "E_USAGE",
-            message: "Usage: agentplane task add <task-id> [<task-id> ...] --title <text> --description <text> --priority <low|normal|med|high> --owner <id> --tag <tag> [--tag <tag>...]",
+            message: usageMessage(TASK_ADD_USAGE, TASK_ADD_USAGE_EXAMPLE),
         });
     }
     try {
@@ -2849,7 +3109,7 @@ function parseTaskUpdateFlags(args) {
         throw new CliError({
             exitCode: 2,
             code: "E_USAGE",
-            message: "Usage: agentplane task update <task-id> [flags]",
+            message: usageMessage(TASK_UPDATE_USAGE, TASK_UPDATE_USAGE_EXAMPLE),
         });
     }
     const out = {
@@ -2881,12 +3141,12 @@ function parseTaskUpdateFlags(args) {
             throw new CliError({
                 exitCode: 2,
                 code: "E_USAGE",
-                message: "Usage: agentplane task update <task-id> [flags]",
+                message: usageMessage(TASK_UPDATE_USAGE, TASK_UPDATE_USAGE_EXAMPLE),
             });
         }
         const next = rest[i + 1];
         if (!next) {
-            throw new CliError({ exitCode: 2, code: "E_USAGE", message: `Missing value for ${arg}` });
+            throw new CliError({ exitCode: 2, code: "E_USAGE", message: missingValueMessage(arg) });
         }
         switch (arg) {
             case "--title": {
@@ -2941,7 +3201,7 @@ async function cmdTaskUpdate(opts) {
             throw new CliError({
                 exitCode: 2,
                 code: "E_USAGE",
-                message: `Unknown task id: ${flags.taskId}`,
+                message: unknownEntityMessage("task id", flags.taskId),
             });
         }
         const next = { ...task };
@@ -2973,7 +3233,7 @@ async function cmdTaskUpdate(opts) {
             });
         }
         await backend.writeTask(next);
-        process.stdout.write(`✅ updated ${flags.taskId}\n`);
+        process.stdout.write(`${successMessage("updated", flags.taskId)}\n`);
         return 0;
     }
     catch (err) {
@@ -3000,11 +3260,15 @@ function parseTaskScrubFlags(args) {
             continue;
         }
         if (!arg.startsWith("--")) {
-            throw new CliError({ exitCode: 2, code: "E_USAGE", message: "Usage: agentplane task scrub" });
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: usageMessage(TASK_SCRUB_USAGE, TASK_SCRUB_USAGE_EXAMPLE),
+            });
         }
         const next = args[i + 1];
         if (!next)
-            throw new CliError({ exitCode: 2, code: "E_USAGE", message: `Missing value for ${arg}` });
+            throw new CliError({ exitCode: 2, code: "E_USAGE", message: missingValueMessage(arg) });
         if (arg === "--find") {
             out.find = next;
         }
@@ -3039,7 +3303,7 @@ async function cmdTaskScrub(opts) {
         throw new CliError({
             exitCode: 2,
             code: "E_USAGE",
-            message: "Usage: agentplane task scrub --find",
+            message: usageMessage(TASK_SCRUB_USAGE, TASK_SCRUB_USAGE_EXAMPLE),
         });
     }
     try {
@@ -3066,7 +3330,7 @@ async function cmdTaskScrub(opts) {
         }
         if (flags.dryRun) {
             if (!flags.quiet) {
-                process.stdout.write(`Would update ${changedIds.size} task(s).\n`);
+                process.stdout.write(`${infoMessage(`dry-run: would update ${changedIds.size} task(s)`)}` + "\n");
                 for (const id of [...changedIds].toSorted()) {
                     process.stdout.write(`${id}\n`);
                 }
@@ -3082,7 +3346,7 @@ async function cmdTaskScrub(opts) {
             }
         }
         if (!flags.quiet) {
-            process.stdout.write(`Updated ${changedIds.size} task(s).\n`);
+            process.stdout.write(`${successMessage("updated tasks", undefined, `count=${changedIds.size}`)}` + "\n");
         }
         return 0;
     }
@@ -3103,7 +3367,11 @@ function parseTaskListFilters(args, opts) {
         if (arg === "--status") {
             const next = args[i + 1];
             if (!next)
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: "Missing value for --status" });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: missingValueMessage("--status"),
+                });
             out.status.push(next);
             i++;
             continue;
@@ -3111,7 +3379,11 @@ function parseTaskListFilters(args, opts) {
         if (arg === "--owner") {
             const next = args[i + 1];
             if (!next)
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: "Missing value for --owner" });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: missingValueMessage("--owner"),
+                });
             out.owner.push(next);
             i++;
             continue;
@@ -3119,7 +3391,7 @@ function parseTaskListFilters(args, opts) {
         if (arg === "--tag") {
             const next = args[i + 1];
             if (!next)
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: "Missing value for --tag" });
+                throw new CliError({ exitCode: 2, code: "E_USAGE", message: missingValueMessage("--tag") });
             out.tag.push(next);
             i++;
             continue;
@@ -3127,10 +3399,18 @@ function parseTaskListFilters(args, opts) {
         if (opts?.allowLimit && arg === "--limit") {
             const next = args[i + 1];
             if (!next)
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: "Missing value for --limit" });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: missingValueMessage("--limit"),
+                });
             const parsed = Number.parseInt(next, 10);
             if (!Number.isFinite(parsed)) {
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: "Invalid --limit value" });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: invalidValueForFlag("--limit", next, "integer"),
+                });
             }
             out.limit = parsed;
             i++;
@@ -3254,10 +3534,10 @@ async function cmdReady(opts) {
             }
         }
         else {
-            warnings.push(`Unknown task id: ${opts.taskId}`);
+            warnings.push(unknownEntityMessage("task id", opts.taskId));
         }
         for (const warning of warnings) {
-            process.stdout.write(`⚠️ ${warning}\n`);
+            process.stdout.write(`${warnMessage(warning)}\n`);
         }
         if (task) {
             const status = String(task.status || "TODO").toUpperCase();
@@ -3271,14 +3551,14 @@ async function cmdReady(opts) {
             const missing = dep?.missing ?? [];
             const incomplete = dep?.incomplete ?? [];
             if (missing.length > 0) {
-                process.stdout.write(`Missing deps: ${missing.join(", ")}\n`);
+                process.stdout.write(`${warnMessage(`missing deps: ${missing.join(", ")}`)}\n`);
             }
             if (incomplete.length > 0) {
-                process.stdout.write(`Incomplete deps: ${incomplete.join(", ")}\n`);
+                process.stdout.write(`${warnMessage(`incomplete deps: ${incomplete.join(", ")}`)}\n`);
             }
         }
         const ready = warnings.length === 0;
-        process.stdout.write(`${ready ? "✅ ready" : "⛔ not ready"}\n`);
+        process.stdout.write(`${ready ? successMessage("ready") : warnMessage("not ready")}` + "\n");
         return ready ? 0 : 2;
     }
     catch (err) {
@@ -3311,7 +3591,11 @@ function taskTextBlob(task) {
 async function cmdTaskSearch(opts) {
     const query = opts.query.trim();
     if (!query) {
-        throw new CliError({ exitCode: 2, code: "E_USAGE", message: "Query must be non-empty" });
+        throw new CliError({
+            exitCode: 2,
+            code: "E_USAGE",
+            message: "Missing query (expected non-empty text)",
+        });
     }
     let regex = false;
     const restArgs = [...opts.args];
@@ -3351,7 +3635,11 @@ async function cmdTaskSearch(opts) {
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : "Invalid regex";
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: `Invalid regex: ${message}` });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: invalidValueMessage("regex", message, "valid pattern"),
+                });
             }
             matches = filtered.filter((task) => pattern.test(taskTextBlob(task)));
         }
@@ -3380,7 +3668,7 @@ function parseTaskScaffoldFlags(args) {
         throw new CliError({
             exitCode: 2,
             code: "E_USAGE",
-            message: "Usage: agentplane task scaffold <task-id> [--title <text>] [--overwrite] [--force]",
+            message: usageMessage(TASK_SCAFFOLD_USAGE, TASK_SCAFFOLD_USAGE_EXAMPLE),
         });
     }
     const out = { taskId, overwrite: false, force: false, quiet: false };
@@ -3403,7 +3691,11 @@ function parseTaskScaffoldFlags(args) {
         if (arg === "--title") {
             const next = rest[i + 1];
             if (!next)
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: "Missing value for --title" });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: missingValueMessage("--title"),
+                });
             out.title = next;
             i++;
             continue;
@@ -3428,7 +3720,7 @@ async function cmdTaskScaffold(opts) {
             throw new CliError({
                 exitCode: 2,
                 code: "E_USAGE",
-                message: `Unknown task id: ${flags.taskId}`,
+                message: unknownEntityMessage("task id", flags.taskId),
             });
         }
         const readmePath = taskReadmePath(path.join(resolved.gitRoot, config.paths.workflow_dir), flags.taskId);
@@ -3474,7 +3766,7 @@ async function cmdTaskScaffold(opts) {
         await mkdir(path.dirname(readmePath), { recursive: true });
         await writeFile(readmePath, text.endsWith("\n") ? text : `${text}\n`, "utf8");
         if (!flags.quiet) {
-            process.stdout.write(`✅ wrote ${path.relative(resolved.gitRoot, readmePath)}\n`);
+            process.stdout.write(`${successMessage("wrote", path.relative(resolved.gitRoot, readmePath))}\n`);
         }
         return 0;
     }
@@ -3494,7 +3786,7 @@ function parseTaskNormalizeFlags(args) {
         else if (arg === "--force")
             out.force = true;
         else if (arg.startsWith("--"))
-            throw new CliError({ exitCode: 2, code: "E_USAGE", message: "Unknown flag" });
+            throw new CliError({ exitCode: 2, code: "E_USAGE", message: `Unknown flag: ${arg}` });
     }
     return out;
 }
@@ -3517,7 +3809,7 @@ async function cmdTaskNormalize(opts) {
                 await backend.writeTask(task);
         }
         if (!flags.quiet) {
-            process.stdout.write(`✅ normalized ${tasks.length} task(s)\n`);
+            process.stdout.write(`${successMessage("normalized tasks", undefined, `count=${tasks.length}`)}\n`);
         }
         return 0;
     }
@@ -3542,13 +3834,17 @@ function parseTaskMigrateFlags(args) {
         if (arg === "--source") {
             const next = args[i + 1];
             if (!next)
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: "Missing value for --source" });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: missingValueMessage("--source"),
+                });
             out.source = next;
             i++;
             continue;
         }
         if (arg.startsWith("--")) {
-            throw new CliError({ exitCode: 2, code: "E_USAGE", message: "Unknown flag" });
+            throw new CliError({ exitCode: 2, code: "E_USAGE", message: `Unknown flag: ${arg}` });
         }
     }
     return out;
@@ -3576,7 +3872,7 @@ async function cmdTaskMigrate(opts) {
                 await backend.writeTask(task);
         }
         if (!flags.quiet) {
-            process.stdout.write(`✅ migrated ${tasks.length} task(s) into backend\n`);
+            process.stdout.write(`${successMessage("migrated tasks into backend", undefined, `count=${tasks.length}`)}\n`);
         }
         return 0;
     }
@@ -3602,7 +3898,7 @@ async function cmdTaskComment(opts) {
             doc_updated_by: "agentplane",
         };
         await backend.writeTask(next);
-        process.stdout.write(`✅ commented ${opts.taskId}\n`);
+        process.stdout.write(`${successMessage("commented", opts.taskId)}\n`);
         return 0;
     }
     catch (err) {
@@ -3673,10 +3969,10 @@ async function cmdTaskSetStatus(opts) {
             if (dep && (dep.missing.length > 0 || dep.incomplete.length > 0)) {
                 if (!opts.quiet) {
                     if (dep.missing.length > 0) {
-                        process.stderr.write(`⚠️ missing deps: ${dep.missing.join(", ")}\n`);
+                        process.stderr.write(`${warnMessage(`missing deps: ${dep.missing.join(", ")}`)}\n`);
                     }
                     if (dep.incomplete.length > 0) {
-                        process.stderr.write(`⚠️ incomplete deps: ${dep.incomplete.join(", ")}\n`);
+                        process.stderr.write(`${warnMessage(`incomplete deps: ${dep.incomplete.join(", ")}`)}\n`);
                     }
                 }
                 throw new CliError({
@@ -3737,7 +4033,7 @@ async function cmdTaskSetStatus(opts) {
             });
         }
         if (!opts.quiet) {
-            process.stdout.write(`✅ status ${opts.taskId} -> ${nextStatus}\n`);
+            process.stdout.write(`${successMessage("status", opts.taskId, `next=${nextStatus}`)}\n`);
         }
         return 0;
     }
@@ -3792,7 +4088,7 @@ async function cmdTaskExport(opts) {
             throw new CliError({
                 exitCode: 3,
                 code: "E_VALIDATION",
-                message: "Configured backend does not support exportTasksJson()",
+                message: backendNotSupportedMessage("exportTasksJson()"),
             });
         }
         await backend.exportTasksJson(outPath);
@@ -3823,19 +4119,33 @@ async function cmdTaskLint(opts) {
     }
 }
 const IDE_SYNC_USAGE = "Usage: agentplane ide sync";
+const IDE_SYNC_USAGE_EXAMPLE = "agentplane ide sync";
 const GUARD_COMMIT_USAGE = "Usage: agentplane guard commit <task-id> -m <message> --allow <path> [--allow <path>...] [--auto-allow] [--allow-tasks] [--require-clean] [--quiet]";
+const GUARD_COMMIT_USAGE_EXAMPLE = 'agentplane guard commit 202602030608-F1Q8AB -m "✨ F1Q8AB update" --allow packages/agentplane';
 const COMMIT_USAGE = "Usage: agentplane commit <task-id> -m <message>";
+const COMMIT_USAGE_EXAMPLE = 'agentplane commit 202602030608-F1Q8AB -m "✨ F1Q8AB update"';
 const START_USAGE = "Usage: agentplane start <task-id> --author <id> --body <text> [flags]";
+const START_USAGE_EXAMPLE = 'agentplane start 202602030608-F1Q8AB --author CODER --body "Start: ..."';
 const BLOCK_USAGE = "Usage: agentplane block <task-id> --author <id> --body <text> [flags]";
+const BLOCK_USAGE_EXAMPLE = 'agentplane block 202602030608-F1Q8AB --author CODER --body "Blocked: ..."';
 const FINISH_USAGE = "Usage: agentplane finish <task-id> [<task-id>...] --author <id> --body <text> [flags]";
+const FINISH_USAGE_EXAMPLE = 'agentplane finish 202602030608-F1Q8AB --author INTEGRATOR --body "Verified: ..."';
 const VERIFY_USAGE = "Usage: agentplane verify <task-id> [--cwd <path>] [--log <path>] [--skip-if-unchanged] [--quiet] [--require]";
+const VERIFY_USAGE_EXAMPLE = "agentplane verify 202602030608-F1Q8AB";
 const WORK_START_USAGE = "Usage: agentplane work start <task-id> --agent <id> --slug <slug> --worktree";
+const WORK_START_USAGE_EXAMPLE = "agentplane work start 202602030608-F1Q8AB --agent CODER --slug cli --worktree";
 const PR_OPEN_USAGE = "Usage: agentplane pr open <task-id> --author <id> [--branch <name>]";
+const PR_OPEN_USAGE_EXAMPLE = "agentplane pr open 202602030608-F1Q8AB --author CODER";
 const PR_UPDATE_USAGE = "Usage: agentplane pr update <task-id>";
+const PR_UPDATE_USAGE_EXAMPLE = "agentplane pr update 202602030608-F1Q8AB";
 const PR_CHECK_USAGE = "Usage: agentplane pr check <task-id>";
+const PR_CHECK_USAGE_EXAMPLE = "agentplane pr check 202602030608-F1Q8AB";
 const PR_NOTE_USAGE = "Usage: agentplane pr note <task-id> --author <id> --body <text>";
+const PR_NOTE_USAGE_EXAMPLE = 'agentplane pr note 202602030608-F1Q8AB --author REVIEWER --body "..."';
 const INTEGRATE_USAGE = "Usage: agentplane integrate <task-id> [--branch <name>] [--base <name>] [--merge-strategy squash|merge|rebase] [--run-verify] [--dry-run] [--quiet]";
+const INTEGRATE_USAGE_EXAMPLE = "agentplane integrate 202602030608-F1Q8AB --run-verify";
 const CLEANUP_MERGED_USAGE = "Usage: agentplane cleanup merged [--base <name>] [--yes] [--archive] [--quiet]";
+const CLEANUP_MERGED_USAGE_EXAMPLE = "agentplane cleanup merged --yes";
 function pathIsUnder(candidate, prefix) {
     if (prefix === "." || prefix === "")
         return true;
@@ -3856,7 +4166,7 @@ function normalizeTaskStatus(value) {
         throw new CliError({
             exitCode: 2,
             code: "E_USAGE",
-            message: `Invalid status: ${value} (allowed: ${[...ALLOWED_TASK_STATUSES].join(", ")})`,
+            message: invalidValueMessage("status", value, `one of ${[...ALLOWED_TASK_STATUSES].join(", ")}`),
         });
     }
     return normalized;
@@ -4010,7 +4320,7 @@ function deriveCommitMessageFromComment(opts) {
         throw new CliError({
             exitCode: 2,
             code: "E_USAGE",
-            message: `Invalid task id: ${opts.taskId}`,
+            message: invalidValueMessage("task id", opts.taskId, "valid task id"),
         });
     }
     return `${prefix} ${suffix} ${summary}`;
@@ -4020,7 +4330,7 @@ function enforceStatusCommitPolicy(opts) {
         return;
     if (opts.policy === "warn") {
         if (!opts.quiet && !opts.confirmed) {
-            process.stderr.write(`⚠️ ${opts.action}: status/comment-driven commit requested; policy=warn (pass --confirm-status-commit to acknowledge)\n`);
+            process.stderr.write(`${warnMessage(`${opts.action}: status/comment-driven commit requested; policy=warn (pass --confirm-status-commit to acknowledge)`)}\n`);
         }
         return;
     }
@@ -4355,7 +4665,11 @@ function shimScriptText() {
 function validateWorkSlug(slug) {
     const trimmed = slug.trim();
     if (!trimmed) {
-        throw new CliError({ exitCode: 2, code: "E_USAGE", message: WORK_START_USAGE });
+        throw new CliError({
+            exitCode: 2,
+            code: "E_USAGE",
+            message: usageMessage(WORK_START_USAGE, WORK_START_USAGE_EXAMPLE),
+        });
     }
     if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(trimmed)) {
         throw new CliError({
@@ -4368,7 +4682,11 @@ function validateWorkSlug(slug) {
 function validateWorkAgent(agent) {
     const trimmed = agent.trim();
     if (!trimmed) {
-        throw new CliError({ exitCode: 2, code: "E_USAGE", message: WORK_START_USAGE });
+        throw new CliError({
+            exitCode: 2,
+            code: "E_USAGE",
+            message: usageMessage(WORK_START_USAGE, WORK_START_USAGE_EXAMPLE),
+        });
     }
     if (!/^[A-Z0-9_]+$/.test(trimmed)) {
         throw new CliError({
@@ -4553,7 +4871,7 @@ async function cmdGuardClean(opts) {
             });
         }
         if (!opts.quiet) {
-            process.stdout.write("✅ index clean (no staged files)\n");
+            process.stdout.write(`${successMessage("index clean", undefined, "no staged files")}\n`);
         }
         return 0;
     }
@@ -4567,7 +4885,11 @@ async function cmdGuardSuggestAllow(opts) {
     try {
         const staged = await getStagedFiles({ cwd: opts.cwd, rootOverride: opts.rootOverride ?? null });
         if (staged.length === 0) {
-            throw new CliError({ exitCode: 2, code: "E_USAGE", message: "No staged files" });
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: "No staged files (git index empty)",
+            });
         }
         const prefixes = suggestAllowPrefixes(staged);
         if (opts.format === "args") {
@@ -4600,7 +4922,11 @@ async function guardCommitCheck(opts) {
     }
     const staged = await getStagedFiles({ cwd: opts.cwd, rootOverride: opts.rootOverride ?? null });
     if (staged.length === 0) {
-        throw new CliError({ exitCode: 5, code: "E_GIT", message: "No staged files" });
+        throw new CliError({
+            exitCode: 5,
+            code: "E_GIT",
+            message: "No staged files (git index empty)",
+        });
     }
     if (opts.allow.length === 0) {
         throw new CliError({
@@ -4685,7 +5011,11 @@ async function stageAllowlist(opts) {
     });
     const changed = await gitStatusChangedPaths({ cwd: opts.cwd, rootOverride: opts.rootOverride });
     if (changed.length === 0) {
-        throw new CliError({ exitCode: 2, code: "E_USAGE", message: "No changes to stage" });
+        throw new CliError({
+            exitCode: 2,
+            code: "E_USAGE",
+            message: "No changes to stage (working tree clean)",
+        });
     }
     const allow = opts.allow.map((prefix) => normalizeAllowPrefix(prefix.trim().replace(/^\.?\//, "")));
     const denied = new Set();
@@ -4704,7 +5034,7 @@ async function stageAllowlist(opts) {
         throw new CliError({
             exitCode: 2,
             code: "E_USAGE",
-            message: "No changes matched the allowed prefixes (use --commit-auto-allow or broaden --commit-allow)",
+            message: "No changes matched allowed prefixes (use --commit-auto-allow or update --commit-allow)",
         });
     }
     await execFileAsync("git", ["add", "--", ...unique], { cwd: resolved.gitRoot });
@@ -4763,7 +5093,7 @@ async function commitFromComment(opts) {
     const trimmed = stdout.trim();
     const [hash, subject] = trimmed.split(":", 2);
     if (!opts.quiet) {
-        process.stdout.write(`✅ committed ${hash?.slice(0, 12) ?? ""} ${subject ?? ""} (staged: ${staged.join(", ")})\n`);
+        process.stdout.write(`${successMessage("committed", `${hash?.slice(0, 12) ?? ""} ${subject ?? ""}`.trim(), `staged=${staged.join(", ")}`)}\n`);
     }
     return { hash: hash ?? "", message: subject ?? "", staged };
 }
@@ -4790,7 +5120,11 @@ async function cmdCommit(opts) {
             });
             const prefixes = suggestAllowPrefixes(staged);
             if (prefixes.length === 0) {
-                throw new CliError({ exitCode: 5, code: "E_GIT", message: "No staged files" });
+                throw new CliError({
+                    exitCode: 5,
+                    code: "E_GIT",
+                    message: "No staged files (git index empty)",
+                });
             }
             allow = prefixes;
         }
@@ -4821,7 +5155,7 @@ async function cmdCommit(opts) {
             });
             const trimmed = stdout.trim();
             const [hash, subject] = trimmed.split(":", 2);
-            process.stdout.write(`✅ committed ${hash?.slice(0, 12) ?? ""} ${subject ?? ""}\n`);
+            process.stdout.write(`${successMessage("committed", `${hash?.slice(0, 12) ?? ""} ${subject ?? ""}`.trim())}\n`);
         }
         return 0;
     }
@@ -4868,10 +5202,10 @@ async function cmdStart(opts) {
             if (dep && (dep.missing.length > 0 || dep.incomplete.length > 0)) {
                 if (!opts.quiet) {
                     if (dep.missing.length > 0) {
-                        process.stderr.write(`⚠️ missing deps: ${dep.missing.join(", ")}\n`);
+                        process.stderr.write(`${warnMessage(`missing deps: ${dep.missing.join(", ")}`)}\n`);
                     }
                     if (dep.incomplete.length > 0) {
-                        process.stderr.write(`⚠️ incomplete deps: ${dep.incomplete.join(", ")}\n`);
+                        process.stderr.write(`${warnMessage(`incomplete deps: ${dep.incomplete.join(", ")}`)}\n`);
                     }
                 }
                 throw new CliError({
@@ -4920,7 +5254,7 @@ async function cmdStart(opts) {
         }
         if (!opts.quiet) {
             const suffix = commitInfo ? ` (commit=${commitInfo.hash.slice(0, 12)})` : "";
-            process.stdout.write(`✅ started ${opts.taskId}${suffix}\n`);
+            process.stdout.write(`${successMessage("started", `${opts.taskId}${suffix}`)}\n`);
         }
         return 0;
     }
@@ -4996,7 +5330,7 @@ async function cmdBlock(opts) {
         }
         if (!opts.quiet) {
             const suffix = commitInfo ? ` (commit=${commitInfo.hash.slice(0, 12)})` : "";
-            process.stdout.write(`✅ blocked ${opts.taskId}${suffix}\n`);
+            process.stdout.write(`${successMessage("blocked", `${opts.taskId}${suffix}`)}\n`);
         }
         return 0;
     }
@@ -5086,7 +5420,7 @@ async function cmdFinish(opts) {
             throw new CliError({
                 exitCode: 3,
                 code: "E_VALIDATION",
-                message: "Configured backend does not support exportTasksJson()",
+                message: backendNotSupportedMessage("exportTasksJson()"),
             });
         }
         const outPath = path.join(resolved.gitRoot, config.paths.tasks_path);
@@ -5135,7 +5469,7 @@ async function cmdFinish(opts) {
             });
         }
         if (!opts.quiet) {
-            process.stdout.write("✅ finished\n");
+            process.stdout.write(`${successMessage("finished")}\n`);
         }
         return 0;
     }
@@ -5175,7 +5509,7 @@ async function cmdVerify(opts) {
                 });
             }
             if (!opts.quiet) {
-                process.stdout.write(`ℹ️ ${task.id}: no verify commands configured\n`);
+                process.stdout.write(`${infoMessage(`${task.id}: no verify commands configured`)}\n`);
             }
             return 0;
         }
@@ -5223,7 +5557,7 @@ async function cmdVerify(opts) {
             });
             if (changed.length > 0) {
                 if (!opts.quiet) {
-                    process.stdout.write(`⚠️ ${task.id}: working tree is dirty; ignoring --skip-if-unchanged\n`);
+                    process.stdout.write(`${warnMessage(`${task.id}: working tree is dirty; ignoring --skip-if-unchanged`)}\n`);
                 }
             }
             else {
@@ -5238,7 +5572,7 @@ async function cmdVerify(opts) {
                         await appendVerifyLog(logPath, header, "");
                     }
                     if (!opts.quiet) {
-                        process.stdout.write(`ℹ️ ${task.id}: verify skipped (unchanged sha ${currentSha.slice(0, 12)})\n`);
+                        process.stdout.write(`${infoMessage(`${task.id}: verify skipped (unchanged sha ${currentSha.slice(0, 12)})`)}\n`);
                     }
                     if (meta) {
                         const nextMeta = {
@@ -5279,7 +5613,7 @@ async function cmdVerify(opts) {
             }
         }
         if (!opts.quiet) {
-            process.stdout.write(`✅ verify passed for ${task.id}\n`);
+            process.stdout.write(`${successMessage("verify passed", task.id)}\n`);
         }
         if (meta) {
             const nextMeta = {
@@ -5313,11 +5647,15 @@ async function cmdWorkStart(opts) {
             throw new CliError({
                 exitCode: 2,
                 code: "E_USAGE",
-                message: "work start is only supported when workflow_mode=branch_pr",
+                message: workflowModeMessage(loaded.config.workflow_mode, "branch_pr"),
             });
         }
         if (!opts.worktree) {
-            throw new CliError({ exitCode: 2, code: "E_USAGE", message: WORK_START_USAGE });
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: usageMessage(WORK_START_USAGE, WORK_START_USAGE_EXAMPLE),
+            });
         }
         await loadBackendTask({
             cwd: opts.cwd,
@@ -5360,7 +5698,7 @@ async function cmdWorkStart(opts) {
             ? ["worktree", "add", worktreePath, branchName]
             : ["worktree", "add", "-b", branchName, worktreePath, baseBranch];
         await execFileAsync("git", worktreeArgs, { cwd: resolved.gitRoot, env: gitEnv() });
-        process.stdout.write(`✅ work start ${branchName} (worktree=${path.relative(resolved.gitRoot, worktreePath)})\n`);
+        process.stdout.write(`${successMessage("work start", branchName, `worktree=${path.relative(resolved.gitRoot, worktreePath)}`)}\n`);
         return 0;
     }
     catch (err) {
@@ -5391,7 +5729,11 @@ async function cmdPrOpen(opts) {
     try {
         const author = opts.author.trim();
         if (!author)
-            throw new CliError({ exitCode: 2, code: "E_USAGE", message: PR_OPEN_USAGE });
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: usageMessage(PR_OPEN_USAGE, PR_OPEN_USAGE_EXAMPLE),
+            });
         const { task } = await loadBackendTask({
             cwd: opts.cwd,
             rootOverride: opts.rootOverride,
@@ -5402,12 +5744,16 @@ async function cmdPrOpen(opts) {
             throw new CliError({
                 exitCode: 2,
                 code: "E_USAGE",
-                message: "pr commands require workflow_mode=branch_pr",
+                message: workflowModeMessage(config.workflow_mode, "branch_pr"),
             });
         }
         const branch = (opts.branch ?? (await gitCurrentBranch(resolved.gitRoot))).trim();
         if (!branch)
-            throw new CliError({ exitCode: 2, code: "E_USAGE", message: PR_OPEN_USAGE });
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: usageMessage(PR_OPEN_USAGE, PR_OPEN_USAGE_EXAMPLE),
+            });
         await mkdir(prDir, { recursive: true });
         const now = nowIso();
         let meta = null;
@@ -5435,7 +5781,7 @@ async function cmdPrOpen(opts) {
             const review = renderPrReviewTemplate({ author, createdAt, branch });
             await writeFile(reviewPath, review, "utf8");
         }
-        process.stdout.write(`✅ pr open ${path.relative(resolved.gitRoot, prDir)}\n`);
+        process.stdout.write(`${successMessage("pr open", path.relative(resolved.gitRoot, prDir))}\n`);
         return 0;
     }
     catch (err) {
@@ -5456,14 +5802,19 @@ async function cmdPrUpdate(opts) {
             throw new CliError({
                 exitCode: 2,
                 code: "E_USAGE",
-                message: "pr commands require workflow_mode=branch_pr",
+                message: workflowModeMessage(config.workflow_mode, "branch_pr"),
             });
         }
         if (!(await fileExists(metaPath)) || !(await fileExists(reviewPath))) {
+            const missing = [];
+            if (!(await fileExists(metaPath)))
+                missing.push(path.relative(resolved.gitRoot, metaPath));
+            if (!(await fileExists(reviewPath)))
+                missing.push(path.relative(resolved.gitRoot, reviewPath));
             throw new CliError({
                 exitCode: 3,
                 code: "E_VALIDATION",
-                message: "PR artifacts missing: run `agentplane pr open` first",
+                message: `PR artifacts missing: ${missing.join(", ")} (run \`agentplane pr open\`)`,
             });
         }
         const baseBranch = await getBaseBranch({
@@ -5501,7 +5852,7 @@ async function cmdPrUpdate(opts) {
             last_verified_at: meta.last_verified_at ?? null,
         };
         await writeFile(metaPath, `${JSON.stringify(nextMeta, null, 2)}\n`, "utf8");
-        process.stdout.write(`✅ pr update ${path.relative(resolved.gitRoot, prDir)}\n`);
+        process.stdout.write(`${successMessage("pr update", path.relative(resolved.gitRoot, prDir))}\n`);
         return 0;
     }
     catch (err) {
@@ -5522,20 +5873,25 @@ async function cmdPrCheck(opts) {
             throw new CliError({
                 exitCode: 2,
                 code: "E_USAGE",
-                message: "pr commands require workflow_mode=branch_pr",
+                message: workflowModeMessage(config.workflow_mode, "branch_pr"),
             });
         }
         const errors = [];
+        const relPrDir = path.relative(resolved.gitRoot, prDir);
+        const relMetaPath = path.relative(resolved.gitRoot, metaPath);
+        const relDiffstatPath = path.relative(resolved.gitRoot, diffstatPath);
+        const relVerifyLogPath = path.relative(resolved.gitRoot, verifyLogPath);
+        const relReviewPath = path.relative(resolved.gitRoot, reviewPath);
         if (!(await fileExists(prDir)))
-            errors.push("Missing PR directory");
+            errors.push(`Missing PR directory: ${relPrDir}`);
         if (!(await fileExists(metaPath)))
-            errors.push("Missing pr/meta.json");
+            errors.push(`Missing ${relMetaPath}`);
         if (!(await fileExists(diffstatPath)))
-            errors.push("Missing pr/diffstat.txt");
+            errors.push(`Missing ${relDiffstatPath}`);
         if (!(await fileExists(verifyLogPath)))
-            errors.push("Missing pr/verify.log");
+            errors.push(`Missing ${relVerifyLogPath}`);
         if (!(await fileExists(reviewPath)))
-            errors.push("Missing pr/review.md");
+            errors.push(`Missing ${relReviewPath}`);
         let meta = null;
         if (await fileExists(metaPath)) {
             try {
@@ -5571,7 +5927,7 @@ async function cmdPrCheck(opts) {
         if (errors.length > 0) {
             throw new CliError({ exitCode: 3, code: "E_VALIDATION", message: errors.join("\n") });
         }
-        process.stdout.write(`✅ pr check ${path.relative(resolved.gitRoot, prDir)}\n`);
+        process.stdout.write(`${successMessage("pr check", path.relative(resolved.gitRoot, prDir))}\n`);
         return 0;
     }
     catch (err) {
@@ -5585,27 +5941,32 @@ async function cmdPrNote(opts) {
         const author = opts.author.trim();
         const body = opts.body.trim();
         if (!author || !body) {
-            throw new CliError({ exitCode: 2, code: "E_USAGE", message: PR_NOTE_USAGE });
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: usageMessage(PR_NOTE_USAGE, PR_NOTE_USAGE_EXAMPLE),
+            });
         }
-        const { config, reviewPath } = await resolvePrPaths(opts);
+        const { config, reviewPath, resolved } = await resolvePrPaths(opts);
         if (config.workflow_mode !== "branch_pr") {
             throw new CliError({
                 exitCode: 2,
                 code: "E_USAGE",
-                message: "pr commands require workflow_mode=branch_pr",
+                message: workflowModeMessage(config.workflow_mode, "branch_pr"),
             });
         }
         if (!(await fileExists(reviewPath))) {
+            const relReviewPath = path.relative(resolved.gitRoot, reviewPath);
             throw new CliError({
                 exitCode: 3,
                 code: "E_VALIDATION",
-                message: "Missing pr/review.md (run `agentplane pr open`)",
+                message: `Missing ${relReviewPath} (run \`agentplane pr open\`)`,
             });
         }
         const review = await readFile(reviewPath, "utf8");
         const updated = appendHandoffNote(review, `${author}: ${body}`);
         await writeFile(reviewPath, updated, "utf8");
-        process.stdout.write("✅ pr note\n");
+        process.stdout.write(`${successMessage("pr note", opts.taskId)}\n`);
         return 0;
     }
     catch (err) {
@@ -5658,7 +6019,7 @@ async function cmdIntegrate(opts) {
             throw new CliError({
                 exitCode: 2,
                 code: "E_USAGE",
-                message: "integrate is only supported when workflow_mode=branch_pr",
+                message: workflowModeMessage(loaded.config.workflow_mode, "branch_pr"),
             });
         }
         await ensureGitClean({ cwd: opts.cwd, rootOverride: opts.rootOverride });
@@ -5684,13 +6045,17 @@ async function cmdIntegrate(opts) {
                 branch = (meta.branch ?? "").trim();
         }
         if (!branch) {
-            throw new CliError({ exitCode: 2, code: "E_USAGE", message: INTEGRATE_USAGE });
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: usageMessage(INTEGRATE_USAGE, INTEGRATE_USAGE_EXAMPLE),
+            });
         }
         if (!(await gitBranchExists(resolved.gitRoot, branch))) {
             throw new CliError({
                 exitCode: 2,
                 code: "E_USAGE",
-                message: `Unknown branch: ${branch}`,
+                message: unknownEntityMessage("branch", branch),
             });
         }
         const metaSource = meta ??
@@ -5700,6 +6065,9 @@ async function cmdIntegrate(opts) {
             ? baseCandidate.trim()
             : baseBranch;
         const errors = [];
+        const relDiffstat = path.relative(resolved.gitRoot, path.join(prDir, "diffstat.txt"));
+        const relVerifyLog = path.relative(resolved.gitRoot, path.join(prDir, "verify.log"));
+        const relReview = path.relative(resolved.gitRoot, path.join(prDir, "review.md"));
         const diffstatText = await readPrArtifact({
             resolved,
             prDir,
@@ -5707,7 +6075,7 @@ async function cmdIntegrate(opts) {
             branch,
         });
         if (diffstatText === null)
-            errors.push("Missing pr/diffstat.txt");
+            errors.push(`Missing ${relDiffstat}`);
         const verifyLogText = await readPrArtifact({
             resolved,
             prDir,
@@ -5715,7 +6083,7 @@ async function cmdIntegrate(opts) {
             branch,
         });
         if (verifyLogText === null)
-            errors.push("Missing pr/verify.log");
+            errors.push(`Missing ${relVerifyLog}`);
         const reviewText = await readPrArtifact({
             resolved,
             prDir,
@@ -5723,7 +6091,7 @@ async function cmdIntegrate(opts) {
             branch,
         });
         if (reviewText === null)
-            errors.push("Missing pr/review.md");
+            errors.push(`Missing ${relReview}`);
         if (reviewText)
             validateReviewContents(reviewText, errors);
         if (errors.length > 0) {
@@ -5761,7 +6129,7 @@ async function cmdIntegrate(opts) {
         let shouldRunVerify = opts.runVerify || (verifyCommands.length > 0 && alreadyVerifiedSha === null);
         if (opts.dryRun) {
             if (!opts.quiet) {
-                process.stdout.write(`✅ integrate dry-run ${task.id} (base=${base} branch=${branch} verify=${shouldRunVerify ? "yes" : "no"})\n`);
+                process.stdout.write(`${successMessage("integrate dry-run", task.id, `base=${base} branch=${branch} verify=${shouldRunVerify ? "yes" : "no"}`)}\n`);
             }
             return 0;
         }
@@ -5838,7 +6206,7 @@ async function cmdIntegrate(opts) {
                 });
             }
             if (!opts.quiet) {
-                process.stdout.write(`✅ verify passed for ${task.id}\n`);
+                process.stdout.write(`${successMessage("verify passed", task.id)}\n`);
             }
         }
         const baseShaBeforeMerge = await gitRevParse(resolved.gitRoot, [base]);
@@ -5984,7 +6352,7 @@ async function cmdIntegrate(opts) {
                     });
                 }
                 if (!opts.quiet) {
-                    process.stdout.write(`✅ verify passed for ${task.id}\n`);
+                    process.stdout.write(`${successMessage("verify passed", task.id)}\n`);
                 }
             }
             try {
@@ -6007,7 +6375,7 @@ async function cmdIntegrate(opts) {
             throw new CliError({
                 exitCode: 3,
                 code: "E_VALIDATION",
-                message: `Missing PR artifact dir after merge: ${prDir}`,
+                message: `Missing PR artifact dir after merge: ${path.relative(resolved.gitRoot, prDir)}`,
             });
         }
         if (verifyEntries.length > 0) {
@@ -6072,7 +6440,7 @@ async function cmdIntegrate(opts) {
             quiet: opts.quiet,
         });
         if (!opts.quiet) {
-            process.stdout.write(`✅ integrate ${task.id} (merge=${mergeHash.slice(0, 12)})\n`);
+            process.stdout.write(`${successMessage("integrate", task.id, `merge=${mergeHash.slice(0, 12)}`)}\n`);
         }
         return 0;
     }
@@ -6106,19 +6474,23 @@ async function cmdCleanupMerged(opts) {
             throw new CliError({
                 exitCode: 2,
                 code: "E_USAGE",
-                message: "cleanup merged is only supported when workflow_mode=branch_pr",
+                message: workflowModeMessage(loaded.config.workflow_mode, "branch_pr"),
             });
         }
         await ensureGitClean({ cwd: opts.cwd, rootOverride: opts.rootOverride });
         const baseBranch = (opts.base ?? (await getBaseBranch({ cwd: opts.cwd, rootOverride: opts.rootOverride ?? null }))).trim();
         if (!baseBranch) {
-            throw new CliError({ exitCode: 2, code: "E_USAGE", message: CLEANUP_MERGED_USAGE });
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: usageMessage(CLEANUP_MERGED_USAGE, CLEANUP_MERGED_USAGE_EXAMPLE),
+            });
         }
         if (!(await gitBranchExists(resolved.gitRoot, baseBranch))) {
             throw new CliError({
                 exitCode: 5,
                 code: "E_GIT",
-                message: `Unknown base branch: ${baseBranch}`,
+                message: unknownEntityMessage("base branch", baseBranch),
             });
         }
         const currentBranch = await gitCurrentBranch(resolved.gitRoot);
@@ -6209,7 +6581,7 @@ async function cmdCleanupMerged(opts) {
             });
         }
         if (!opts.quiet) {
-            process.stdout.write(`✅ cleanup merged deleted=${candidates.length}\n`);
+            process.stdout.write(`${successMessage("cleanup merged", undefined, `deleted=${candidates.length}`)}\n`);
         }
         return 0;
     }
@@ -6274,7 +6646,9 @@ async function cmdHooksUninstall(opts) {
             removed++;
         }
         if (!opts.quiet) {
-            process.stdout.write(removed > 0 ? "OK\n" : "No agentplane hooks found\n");
+            process.stdout.write(removed > 0
+                ? `${successMessage("removed hooks", undefined, `count=${removed}`)}\n`
+                : `${infoMessage("no agentplane hooks found")}\n`);
         }
         return 0;
     }
@@ -6292,7 +6666,7 @@ async function cmdHooksRun(opts) {
                 throw new CliError({
                     exitCode: 2,
                     code: "E_USAGE",
-                    message: "Missing commit message file",
+                    message: "Missing commit message file path",
                 });
             }
             const raw = await readFile(messagePath, "utf8");
@@ -6409,10 +6783,14 @@ async function cmdBranchBaseGet(opts) {
 async function cmdBranchBaseSet(opts) {
     const trimmed = opts.value.trim();
     if (trimmed.length === 0) {
-        throw new CliError({ exitCode: 2, code: "E_USAGE", message: BRANCH_BASE_USAGE });
-    }
-    try {
-        const value = await setPinnedBaseBranch({
+        throw new CliError({
+            exitCode: 2,
+            code: "E_USAGE",
+            message: usageMessage(BRANCH_BASE_USAGE, BRANCH_BASE_USAGE_EXAMPLE),
+        });
+    }
+    try {
+        const value = await setPinnedBaseBranch({
             cwd: opts.cwd,
             rootOverride: opts.rootOverride ?? null,
             value: trimmed,
@@ -6434,20 +6812,24 @@ async function cmdBranchStatus(opts) {
         const branch = (opts.branch ?? (await gitCurrentBranch(resolved.gitRoot))).trim();
         const base = (opts.base ?? (await getBaseBranch({ cwd: opts.cwd, rootOverride: opts.rootOverride ?? null }))).trim();
         if (!branch || !base) {
-            throw new CliError({ exitCode: 2, code: "E_USAGE", message: BRANCH_STATUS_USAGE });
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: usageMessage(BRANCH_STATUS_USAGE, BRANCH_STATUS_USAGE_EXAMPLE),
+            });
         }
         if (!(await gitBranchExists(resolved.gitRoot, branch))) {
             throw new CliError({
                 exitCode: 2,
                 code: "E_USAGE",
-                message: `Unknown branch: ${branch}`,
+                message: unknownEntityMessage("branch", branch),
             });
         }
         if (!(await gitBranchExists(resolved.gitRoot, base))) {
             throw new CliError({
                 exitCode: 2,
                 code: "E_USAGE",
-                message: `Unknown base branch: ${base}`,
+                message: unknownEntityMessage("base branch", base),
             });
         }
         const taskId = parseTaskIdFromBranch(loaded.config.branch.task_prefix, branch);
@@ -6469,7 +6851,11 @@ async function cmdBranchRemove(opts) {
     const branch = (opts.branch ?? "").trim();
     const worktree = (opts.worktree ?? "").trim();
     if (!branch && !worktree) {
-        throw new CliError({ exitCode: 2, code: "E_USAGE", message: BRANCH_REMOVE_USAGE });
+        throw new CliError({
+            exitCode: 2,
+            code: "E_USAGE",
+            message: usageMessage(BRANCH_REMOVE_USAGE, BRANCH_REMOVE_USAGE_EXAMPLE),
+        });
     }
     try {
         const resolved = await resolveProject({
@@ -6491,7 +6877,7 @@ async function cmdBranchRemove(opts) {
             }
             await execFileAsync("git", ["worktree", "remove", ...(opts.force ? ["--force"] : []), worktreePath], { cwd: resolved.gitRoot, env: gitEnv() });
             if (!opts.quiet) {
-                process.stdout.write(`✅ removed worktree ${worktreePath}\n`);
+                process.stdout.write(`${successMessage("removed worktree", worktreePath)}\n`);
             }
         }
         if (branch) {
@@ -6499,7 +6885,7 @@ async function cmdBranchRemove(opts) {
                 throw new CliError({
                     exitCode: 2,
                     code: "E_USAGE",
-                    message: `Unknown branch: ${branch}`,
+                    message: unknownEntityMessage("branch", branch),
                 });
             }
             await execFileAsync("git", ["branch", opts.force ? "-D" : "-d", branch], {
@@ -6507,7 +6893,7 @@ async function cmdBranchRemove(opts) {
                 env: gitEnv(),
             });
             if (!opts.quiet) {
-                process.stdout.write(`✅ removed branch ${branch}\n`);
+                process.stdout.write(`${successMessage("removed branch", branch)}\n`);
             }
         }
         return 0;
@@ -6630,7 +7016,9 @@ async function loadBackendTask(opts) {
     return { backend, backendId, resolved, config, task };
 }
 const TASK_DOC_SET_USAGE = "Usage: agentplane task doc set <task-id> --section <name> (--text <text> | --file <path>)";
+const TASK_DOC_SET_USAGE_EXAMPLE = 'agentplane task doc set 202602030608-F1Q8AB --section Summary --text "..."';
 const TASK_DOC_SHOW_USAGE = "Usage: agentplane task doc show <task-id> [--section <name>] [--quiet]";
+const TASK_DOC_SHOW_USAGE_EXAMPLE = "agentplane task doc show 202602030608-F1Q8AB --section Summary";
 function parseTaskDocShowFlags(args) {
     const out = { quiet: false };
     for (let i = 0; i < args.length; i++) {
@@ -6644,7 +7032,7 @@ function parseTaskDocShowFlags(args) {
         if (arg === "--section") {
             const next = args[i + 1];
             if (!next) {
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: `Missing value for ${arg}` });
+                throw new CliError({ exitCode: 2, code: "E_USAGE", message: missingValueMessage(arg) });
             }
             out.section = next;
             i++;
@@ -6665,7 +7053,7 @@ function parseTaskDocSetFlags(args) {
         }
         const next = args[i + 1];
         if (!next) {
-            throw new CliError({ exitCode: 2, code: "E_USAGE", message: `Missing value for ${arg}` });
+            throw new CliError({ exitCode: 2, code: "E_USAGE", message: missingValueMessage(arg) });
         }
         switch (arg) {
             case "--section": {
@@ -6695,12 +7083,20 @@ function parseTaskDocSetFlags(args) {
 async function cmdTaskDocSet(opts) {
     const flags = parseTaskDocSetFlags(opts.args);
     if (!flags.section) {
-        throw new CliError({ exitCode: 2, code: "E_USAGE", message: TASK_DOC_SET_USAGE });
+        throw new CliError({
+            exitCode: 2,
+            code: "E_USAGE",
+            message: usageMessage(TASK_DOC_SET_USAGE, TASK_DOC_SET_USAGE_EXAMPLE),
+        });
     }
     const hasText = flags.text !== undefined;
     const hasFile = flags.file !== undefined;
     if (hasText === hasFile) {
-        throw new CliError({ exitCode: 2, code: "E_USAGE", message: TASK_DOC_SET_USAGE });
+        throw new CliError({
+            exitCode: 2,
+            code: "E_USAGE",
+            message: usageMessage(TASK_DOC_SET_USAGE, TASK_DOC_SET_USAGE_EXAMPLE),
+        });
     }
     const updatedBy = (flags.updatedBy ?? "agentplane").trim();
     if (updatedBy.length === 0) {
@@ -6724,7 +7120,7 @@ async function cmdTaskDocSet(opts) {
             throw new CliError({
                 exitCode: 2,
                 code: "E_USAGE",
-                message: "Configured backend does not support task docs",
+                message: backendNotSupportedMessage("task docs"),
             });
         }
         const allowed = config.tasks.doc.sections;
@@ -6732,13 +7128,44 @@ async function cmdTaskDocSet(opts) {
             throw new CliError({
                 exitCode: 2,
                 code: "E_USAGE",
-                message: `Unknown doc section: ${flags.section}`,
+                message: unknownEntityMessage("doc section", flags.section),
             });
         }
+        const normalizedAllowed = new Set(allowed.map((section) => normalizeDocSectionName(section)));
+        const targetKey = normalizeDocSectionName(flags.section);
+        const headingKeys = new Set();
+        for (const line of text.replaceAll("\r\n", "\n").split("\n")) {
+            const match = /^##\s+(.*)$/.exec(line.trim());
+            if (!match)
+                continue;
+            const key = normalizeDocSectionName(match[1] ?? "");
+            if (key && normalizedAllowed.has(key))
+                headingKeys.add(key);
+        }
         const existing = await backend.getTaskDoc(opts.taskId);
         const baseDoc = ensureDocSections(existing ?? "", config.tasks.doc.required_sections);
-        const nextDoc = setMarkdownSection(baseDoc, flags.section, text);
-        await backend.setTaskDoc(opts.taskId, nextDoc, updatedBy);
+        if (headingKeys.size > 0 && (headingKeys.size > 1 || !headingKeys.has(targetKey))) {
+            const fullDoc = ensureDocSections(text, config.tasks.doc.required_sections);
+            await backend.setTaskDoc(opts.taskId, fullDoc, updatedBy);
+        }
+        else {
+            let nextText = text;
+            if (headingKeys.size > 0 && headingKeys.has(targetKey)) {
+                const lines = nextText.replaceAll("\r\n", "\n").split("\n");
+                let firstContent = 0;
+                while (firstContent < lines.length && lines[firstContent]?.trim() === "")
+                    firstContent++;
+                const headingRe = new RegExp(String.raw `^##\s+${escapeRegExp(flags.section)}\s*$`);
+                if (headingRe.test(lines[firstContent]?.trim() ?? "")) {
+                    lines.splice(firstContent, 1);
+                    if (lines[firstContent]?.trim() === "")
+                        lines.splice(firstContent, 1);
+                    nextText = lines.join("\n");
+                }
+            }
+            const nextDoc = setMarkdownSection(baseDoc, flags.section, nextText);
+            await backend.setTaskDoc(opts.taskId, nextDoc, updatedBy);
+        }
         const tasksDir = path.join(resolved.gitRoot, config.paths.workflow_dir);
         process.stdout.write(`${path.join(tasksDir, opts.taskId, "README.md")}\n`);
         return 0;
@@ -6760,7 +7187,7 @@ async function cmdTaskDocShow(opts) {
             throw new CliError({
                 exitCode: 2,
                 code: "E_USAGE",
-                message: "Configured backend does not support task docs",
+                message: backendNotSupportedMessage("task docs"),
             });
         }
         const doc = (await backend.getTaskDoc(opts.taskId)) ?? "";
@@ -6774,7 +7201,7 @@ async function cmdTaskDocShow(opts) {
                 return 0;
             }
             if (!flags.quiet) {
-                process.stdout.write(`ℹ️ no content for section: ${flags.section}\n`);
+                process.stdout.write(`${infoMessage(`section has no content: ${flags.section}`)}\n`);
             }
             return 0;
         }
@@ -6783,7 +7210,7 @@ async function cmdTaskDocShow(opts) {
             return 0;
         }
         if (!flags.quiet) {
-            process.stdout.write("ℹ️ no task doc metadata\n");
+            process.stdout.write(`${infoMessage("task doc metadata missing")}\n`);
         }
         return 0;
     }
@@ -6814,7 +7241,7 @@ export async function runCli(argv) {
                 throw new CliError({
                     exitCode: 2,
                     code: "E_USAGE",
-                    message: "Usage: agentplane init [--ide <...>] [--workflow <...>] [--hooks <...>] [--require-plan-approval <...>] [--require-network-approval <...>] [--recipes <...>] [--yes] [--force|--backup]",
+                    message: usageMessage(INIT_USAGE, INIT_USAGE_EXAMPLE),
                 });
             }
             return await cmdInit({ cwd: process.cwd(), rootOverride: globals.root, args: initArgs });
@@ -6822,7 +7249,11 @@ export async function runCli(argv) {
         if (namespace === "upgrade") {
             const upgradeArgs = command ? [command, ...args] : [];
             if (command && !command.startsWith("--")) {
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: UPGRADE_USAGE });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: usageMessage(UPGRADE_USAGE, UPGRADE_USAGE_EXAMPLE),
+                });
             }
             return await cmdUpgrade({
                 cwd: process.cwd(),
@@ -6839,7 +7270,7 @@ export async function runCli(argv) {
                 throw new CliError({
                     exitCode: 2,
                     code: "E_USAGE",
-                    message: "Usage: agentplane config set <key> <value>",
+                    message: usageMessage(CONFIG_SET_USAGE, CONFIG_SET_USAGE_EXAMPLE),
                 });
             }
             return await cmdConfigSet({ cwd: process.cwd(), rootOverride: globals.root, key, value });
@@ -6853,7 +7284,7 @@ export async function runCli(argv) {
                 throw new CliError({
                     exitCode: 2,
                     code: "E_USAGE",
-                    message: "Usage: agentplane mode set <direct|branch_pr>",
+                    message: usageMessage(MODE_SET_USAGE, MODE_SET_USAGE_EXAMPLE),
                 });
             }
             return await cmdModeSet({ cwd: process.cwd(), rootOverride: globals.root, mode });
@@ -6863,32 +7294,48 @@ export async function runCli(argv) {
                 throw new CliError({
                     exitCode: 2,
                     code: "E_USAGE",
-                    message: "Usage: agentplane quickstart",
+                    message: usageMessage(QUICKSTART_USAGE, QUICKSTART_USAGE_EXAMPLE),
                 });
             }
             return cmdQuickstart({ cwd: process.cwd(), rootOverride: globals.root });
         }
         if (namespace === "role") {
             if (!command || command.startsWith("--") || args.length > 0) {
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: ROLE_USAGE });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: usageMessage(ROLE_USAGE, ROLE_USAGE_EXAMPLE),
+                });
             }
             return cmdRole({ cwd: process.cwd(), rootOverride: globals.root, role: command });
         }
         if (namespace === "agents") {
             if (command) {
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: AGENTS_USAGE });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: usageMessage(AGENTS_USAGE, AGENTS_USAGE_EXAMPLE),
+                });
             }
             return await cmdAgents({ cwd: process.cwd(), rootOverride: globals.root });
         }
         if (namespace === "ready") {
             if (!command || command.startsWith("--") || args.length > 0) {
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: READY_USAGE });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: usageMessage(READY_USAGE, READY_USAGE_EXAMPLE),
+                });
             }
             return await cmdReady({ cwd: process.cwd(), rootOverride: globals.root, taskId: command });
         }
         if (namespace === "ide") {
             if (command !== "sync" || args.length > 0) {
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: IDE_SYNC_USAGE });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: usageMessage(IDE_SYNC_USAGE, IDE_SYNC_USAGE_EXAMPLE),
+                });
             }
             return await cmdIdeSync({ cwd: process.cwd(), rootOverride: globals.root });
         }
@@ -6910,7 +7357,7 @@ export async function runCli(argv) {
                 throw new CliError({
                     exitCode: 2,
                     code: "E_USAGE",
-                    message: "Usage: agentplane task show <task-id>",
+                    message: usageMessage(TASK_SHOW_USAGE, TASK_SHOW_USAGE_EXAMPLE),
                 });
             }
             return await cmdTaskShow({ cwd: process.cwd(), rootOverride: globals.root, taskId });
@@ -6927,7 +7374,7 @@ export async function runCli(argv) {
                 throw new CliError({
                     exitCode: 2,
                     code: "E_USAGE",
-                    message: "Usage: agentplane task search <query> [flags]",
+                    message: usageMessage(TASK_SEARCH_USAGE, TASK_SEARCH_USAGE_EXAMPLE),
                 });
             }
             return await cmdTaskSearch({
@@ -6956,7 +7403,11 @@ export async function runCli(argv) {
             const [subcommand, taskId, ...restArgs] = args;
             if (subcommand === "show") {
                 if (!taskId) {
-                    throw new CliError({ exitCode: 2, code: "E_USAGE", message: TASK_DOC_SHOW_USAGE });
+                    throw new CliError({
+                        exitCode: 2,
+                        code: "E_USAGE",
+                        message: usageMessage(TASK_DOC_SHOW_USAGE, TASK_DOC_SHOW_USAGE_EXAMPLE),
+                    });
                 }
                 return await cmdTaskDocShow({
                     cwd: process.cwd(),
@@ -6967,7 +7418,11 @@ export async function runCli(argv) {
             }
             if (subcommand === "set") {
                 if (!taskId) {
-                    throw new CliError({ exitCode: 2, code: "E_USAGE", message: TASK_DOC_SET_USAGE });
+                    throw new CliError({
+                        exitCode: 2,
+                        code: "E_USAGE",
+                        message: usageMessage(TASK_DOC_SET_USAGE, TASK_DOC_SET_USAGE_EXAMPLE),
+                    });
                 }
                 return await cmdTaskDocSet({
                     cwd: process.cwd(),
@@ -6976,7 +7431,11 @@ export async function runCli(argv) {
                     args: restArgs,
                 });
             }
-            throw new CliError({ exitCode: 2, code: "E_USAGE", message: TASK_DOC_SET_USAGE });
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: usageMessage(TASK_DOC_SET_USAGE, TASK_DOC_SET_USAGE_EXAMPLE),
+            });
         }
         if (namespace === "task" && command === "comment") {
             const [taskId, ...restArgs] = args;
@@ -6984,7 +7443,7 @@ export async function runCli(argv) {
                 throw new CliError({
                     exitCode: 2,
                     code: "E_USAGE",
-                    message: "Usage: agentplane task comment <task-id>",
+                    message: usageMessage(TASK_COMMENT_USAGE, TASK_COMMENT_USAGE_EXAMPLE),
                 });
             }
             let author = "";
@@ -6999,7 +7458,7 @@ export async function runCli(argv) {
                         throw new CliError({
                             exitCode: 2,
                             code: "E_USAGE",
-                            message: "Missing value for --author",
+                            message: missingValueMessage("--author"),
                         });
                     }
                     author = next;
@@ -7012,7 +7471,7 @@ export async function runCli(argv) {
                         throw new CliError({
                             exitCode: 2,
                             code: "E_USAGE",
-                            message: "Missing value for --body",
+                            message: missingValueMessage("--body"),
                         });
                     }
                     body = next;
@@ -7023,7 +7482,7 @@ export async function runCli(argv) {
                     throw new CliError({
                         exitCode: 2,
                         code: "E_USAGE",
-                        message: "Usage: agentplane task comment <task-id>",
+                        message: usageMessage(TASK_COMMENT_USAGE, TASK_COMMENT_USAGE_EXAMPLE),
                     });
                 }
             }
@@ -7031,7 +7490,7 @@ export async function runCli(argv) {
                 throw new CliError({
                     exitCode: 2,
                     code: "E_USAGE",
-                    message: "Usage: agentplane task comment <task-id>",
+                    message: usageMessage(TASK_COMMENT_USAGE, TASK_COMMENT_USAGE_EXAMPLE),
                 });
             }
             return await cmdTaskComment({
@@ -7048,7 +7507,7 @@ export async function runCli(argv) {
                 throw new CliError({
                     exitCode: 2,
                     code: "E_USAGE",
-                    message: "Usage: agentplane task set-status <task-id> <status> [flags]",
+                    message: usageMessage(TASK_SET_STATUS_USAGE, TASK_SET_STATUS_USAGE_EXAMPLE),
                 });
             }
             let author;
@@ -7073,7 +7532,7 @@ export async function runCli(argv) {
                         throw new CliError({
                             exitCode: 2,
                             code: "E_USAGE",
-                            message: "Missing value for --author",
+                            message: missingValueMessage("--author"),
                         });
                     author = next;
                     i++;
@@ -7085,7 +7544,7 @@ export async function runCli(argv) {
                         throw new CliError({
                             exitCode: 2,
                             code: "E_USAGE",
-                            message: "Missing value for --body",
+                            message: missingValueMessage("--body"),
                         });
                     body = next;
                     i++;
@@ -7097,7 +7556,7 @@ export async function runCli(argv) {
                         throw new CliError({
                             exitCode: 2,
                             code: "E_USAGE",
-                            message: "Missing value for --commit",
+                            message: missingValueMessage("--commit"),
                         });
                     commit = next;
                     i++;
@@ -7117,7 +7576,7 @@ export async function runCli(argv) {
                         throw new CliError({
                             exitCode: 2,
                             code: "E_USAGE",
-                            message: "Missing value for --commit-emoji",
+                            message: missingValueMessage("--commit-emoji"),
                         });
                     commitEmoji = next;
                     i++;
@@ -7129,7 +7588,7 @@ export async function runCli(argv) {
                         throw new CliError({
                             exitCode: 2,
                             code: "E_USAGE",
-                            message: "Missing value for --commit-allow",
+                            message: missingValueMessage("--commit-allow"),
                         });
                     commitAllow.push(next);
                     i++;
@@ -7159,7 +7618,7 @@ export async function runCli(argv) {
                     throw new CliError({
                         exitCode: 2,
                         code: "E_USAGE",
-                        message: "Usage: agentplane task set-status <task-id> <status> [flags]",
+                        message: usageMessage(TASK_SET_STATUS_USAGE, TASK_SET_STATUS_USAGE_EXAMPLE),
                     });
                 }
             }
@@ -7190,7 +7649,11 @@ export async function runCli(argv) {
                 }
                 if (subcommand === "set") {
                     if (!value) {
-                        throw new CliError({ exitCode: 2, code: "E_USAGE", message: BRANCH_BASE_USAGE });
+                        throw new CliError({
+                            exitCode: 2,
+                            code: "E_USAGE",
+                            message: usageMessage(BRANCH_BASE_USAGE, BRANCH_BASE_USAGE_EXAMPLE),
+                        });
                     }
                     return await cmdBranchBaseSet({
                         cwd: process.cwd(),
@@ -7198,7 +7661,11 @@ export async function runCli(argv) {
                         value,
                     });
                 }
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: BRANCH_BASE_USAGE });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: usageMessage(BRANCH_BASE_USAGE, BRANCH_BASE_USAGE_EXAMPLE),
+                });
             }
             if (command === "status") {
                 let branch;
@@ -7213,7 +7680,7 @@ export async function runCli(argv) {
                             throw new CliError({
                                 exitCode: 2,
                                 code: "E_USAGE",
-                                message: BRANCH_STATUS_USAGE,
+                                message: usageMessage(BRANCH_STATUS_USAGE, BRANCH_STATUS_USAGE_EXAMPLE),
                             });
                         branch = next;
                         i++;
@@ -7225,7 +7692,7 @@ export async function runCli(argv) {
                             throw new CliError({
                                 exitCode: 2,
                                 code: "E_USAGE",
-                                message: BRANCH_STATUS_USAGE,
+                                message: usageMessage(BRANCH_STATUS_USAGE, BRANCH_STATUS_USAGE_EXAMPLE),
                             });
                         base = next;
                         i++;
@@ -7235,7 +7702,7 @@ export async function runCli(argv) {
                         throw new CliError({
                             exitCode: 2,
                             code: "E_USAGE",
-                            message: BRANCH_STATUS_USAGE,
+                            message: usageMessage(BRANCH_STATUS_USAGE, BRANCH_STATUS_USAGE_EXAMPLE),
                         });
                     }
                 }
@@ -7261,7 +7728,7 @@ export async function runCli(argv) {
                             throw new CliError({
                                 exitCode: 2,
                                 code: "E_USAGE",
-                                message: BRANCH_REMOVE_USAGE,
+                                message: usageMessage(BRANCH_REMOVE_USAGE, BRANCH_REMOVE_USAGE_EXAMPLE),
                             });
                         branch = next;
                         i++;
@@ -7273,7 +7740,7 @@ export async function runCli(argv) {
                             throw new CliError({
                                 exitCode: 2,
                                 code: "E_USAGE",
-                                message: BRANCH_REMOVE_USAGE,
+                                message: usageMessage(BRANCH_REMOVE_USAGE, BRANCH_REMOVE_USAGE_EXAMPLE),
                             });
                         worktree = next;
                         i++;
@@ -7291,7 +7758,7 @@ export async function runCli(argv) {
                         throw new CliError({
                             exitCode: 2,
                             code: "E_USAGE",
-                            message: BRANCH_REMOVE_USAGE,
+                            message: usageMessage(BRANCH_REMOVE_USAGE, BRANCH_REMOVE_USAGE_EXAMPLE),
                         });
                     }
                 }
@@ -7304,12 +7771,20 @@ export async function runCli(argv) {
                     quiet,
                 });
             }
-            throw new CliError({ exitCode: 2, code: "E_USAGE", message: BRANCH_BASE_USAGE });
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: usageMessage(BRANCH_BASE_USAGE, BRANCH_BASE_USAGE_EXAMPLE),
+            });
         }
         if (namespace === "work" && command === "start") {
             const [taskId, ...restArgs] = args;
             if (!taskId) {
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: WORK_START_USAGE });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: usageMessage(WORK_START_USAGE, WORK_START_USAGE_EXAMPLE),
+                });
             }
             let agent = "";
             let slug = "";
@@ -7321,7 +7796,11 @@ export async function runCli(argv) {
                 if (arg === "--agent") {
                     const next = restArgs[i + 1];
                     if (!next)
-                        throw new CliError({ exitCode: 2, code: "E_USAGE", message: WORK_START_USAGE });
+                        throw new CliError({
+                            exitCode: 2,
+                            code: "E_USAGE",
+                            message: usageMessage(WORK_START_USAGE, WORK_START_USAGE_EXAMPLE),
+                        });
                     agent = next;
                     i++;
                     continue;
@@ -7329,7 +7808,11 @@ export async function runCli(argv) {
                 if (arg === "--slug") {
                     const next = restArgs[i + 1];
                     if (!next)
-                        throw new CliError({ exitCode: 2, code: "E_USAGE", message: WORK_START_USAGE });
+                        throw new CliError({
+                            exitCode: 2,
+                            code: "E_USAGE",
+                            message: usageMessage(WORK_START_USAGE, WORK_START_USAGE_EXAMPLE),
+                        });
                     slug = next;
                     i++;
                     continue;
@@ -7338,10 +7821,18 @@ export async function runCli(argv) {
                     worktree = true;
                     continue;
                 }
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: WORK_START_USAGE });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: usageMessage(WORK_START_USAGE, WORK_START_USAGE_EXAMPLE),
+                });
             }
             if (!agent || !slug || !worktree) {
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: WORK_START_USAGE });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: usageMessage(WORK_START_USAGE, WORK_START_USAGE_EXAMPLE),
+                });
             }
             return await cmdWorkStart({
                 cwd: process.cwd(),
@@ -7355,7 +7846,11 @@ export async function runCli(argv) {
         if (namespace === "pr") {
             const [taskId, ...restArgs] = args;
             if (!taskId) {
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: PR_OPEN_USAGE });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: usageMessage(PR_OPEN_USAGE, PR_OPEN_USAGE_EXAMPLE),
+                });
             }
             if (command === "open") {
                 let author = "";
@@ -7367,7 +7862,11 @@ export async function runCli(argv) {
                     if (arg === "--author") {
                         const next = restArgs[i + 1];
                         if (!next)
-                            throw new CliError({ exitCode: 2, code: "E_USAGE", message: PR_OPEN_USAGE });
+                            throw new CliError({
+                                exitCode: 2,
+                                code: "E_USAGE",
+                                message: usageMessage(PR_OPEN_USAGE, PR_OPEN_USAGE_EXAMPLE),
+                            });
                         author = next;
                         i++;
                         continue;
@@ -7375,15 +7874,27 @@ export async function runCli(argv) {
                     if (arg === "--branch") {
                         const next = restArgs[i + 1];
                         if (!next)
-                            throw new CliError({ exitCode: 2, code: "E_USAGE", message: PR_OPEN_USAGE });
+                            throw new CliError({
+                                exitCode: 2,
+                                code: "E_USAGE",
+                                message: usageMessage(PR_OPEN_USAGE, PR_OPEN_USAGE_EXAMPLE),
+                            });
                         branch = next;
                         i++;
                         continue;
                     }
-                    throw new CliError({ exitCode: 2, code: "E_USAGE", message: PR_OPEN_USAGE });
+                    throw new CliError({
+                        exitCode: 2,
+                        code: "E_USAGE",
+                        message: usageMessage(PR_OPEN_USAGE, PR_OPEN_USAGE_EXAMPLE),
+                    });
                 }
                 if (!author) {
-                    throw new CliError({ exitCode: 2, code: "E_USAGE", message: PR_OPEN_USAGE });
+                    throw new CliError({
+                        exitCode: 2,
+                        code: "E_USAGE",
+                        message: usageMessage(PR_OPEN_USAGE, PR_OPEN_USAGE_EXAMPLE),
+                    });
                 }
                 return await cmdPrOpen({
                     cwd: process.cwd(),
@@ -7395,7 +7906,11 @@ export async function runCli(argv) {
             }
             if (command === "update") {
                 if (restArgs.length > 0) {
-                    throw new CliError({ exitCode: 2, code: "E_USAGE", message: PR_UPDATE_USAGE });
+                    throw new CliError({
+                        exitCode: 2,
+                        code: "E_USAGE",
+                        message: usageMessage(PR_UPDATE_USAGE, PR_UPDATE_USAGE_EXAMPLE),
+                    });
                 }
                 return await cmdPrUpdate({
                     cwd: process.cwd(),
@@ -7405,7 +7920,11 @@ export async function runCli(argv) {
             }
             if (command === "check") {
                 if (restArgs.length > 0) {
-                    throw new CliError({ exitCode: 2, code: "E_USAGE", message: PR_CHECK_USAGE });
+                    throw new CliError({
+                        exitCode: 2,
+                        code: "E_USAGE",
+                        message: usageMessage(PR_CHECK_USAGE, PR_CHECK_USAGE_EXAMPLE),
+                    });
                 }
                 return await cmdPrCheck({
                     cwd: process.cwd(),
@@ -7423,7 +7942,11 @@ export async function runCli(argv) {
                     if (arg === "--author") {
                         const next = restArgs[i + 1];
                         if (!next)
-                            throw new CliError({ exitCode: 2, code: "E_USAGE", message: PR_NOTE_USAGE });
+                            throw new CliError({
+                                exitCode: 2,
+                                code: "E_USAGE",
+                                message: usageMessage(PR_NOTE_USAGE, PR_NOTE_USAGE_EXAMPLE),
+                            });
                         author = next;
                         i++;
                         continue;
@@ -7431,15 +7954,27 @@ export async function runCli(argv) {
                     if (arg === "--body") {
                         const next = restArgs[i + 1];
                         if (!next)
-                            throw new CliError({ exitCode: 2, code: "E_USAGE", message: PR_NOTE_USAGE });
+                            throw new CliError({
+                                exitCode: 2,
+                                code: "E_USAGE",
+                                message: usageMessage(PR_NOTE_USAGE, PR_NOTE_USAGE_EXAMPLE),
+                            });
                         body = next;
                         i++;
                         continue;
                     }
-                    throw new CliError({ exitCode: 2, code: "E_USAGE", message: PR_NOTE_USAGE });
+                    throw new CliError({
+                        exitCode: 2,
+                        code: "E_USAGE",
+                        message: usageMessage(PR_NOTE_USAGE, PR_NOTE_USAGE_EXAMPLE),
+                    });
                 }
                 if (!author || !body) {
-                    throw new CliError({ exitCode: 2, code: "E_USAGE", message: PR_NOTE_USAGE });
+                    throw new CliError({
+                        exitCode: 2,
+                        code: "E_USAGE",
+                        message: usageMessage(PR_NOTE_USAGE, PR_NOTE_USAGE_EXAMPLE),
+                    });
                 }
                 return await cmdPrNote({
                     cwd: process.cwd(),
@@ -7452,7 +7987,7 @@ export async function runCli(argv) {
             throw new CliError({
                 exitCode: 2,
                 code: "E_USAGE",
-                message: "Usage: agentplane pr open|update|check|note <task-id>",
+                message: usageMessage(PR_GROUP_USAGE, PR_GROUP_USAGE_EXAMPLE),
             });
         }
         if (namespace === "guard") {
@@ -7468,7 +8003,11 @@ export async function runCli(argv) {
                 if (formatFlagIndex !== -1) {
                     const next = restArgs[formatFlagIndex + 1];
                     if (next !== "lines" && next !== "args") {
-                        throw new CliError({ exitCode: 2, code: "E_USAGE", message: "Invalid --format" });
+                        throw new CliError({
+                            exitCode: 2,
+                            code: "E_USAGE",
+                            message: invalidValueForFlag("--format", String(next), "lines|args"),
+                        });
                     }
                     format = next;
                 }
@@ -7481,7 +8020,11 @@ export async function runCli(argv) {
             if (subcommand === "commit") {
                 const taskId = restArgs[0];
                 if (!taskId) {
-                    throw new CliError({ exitCode: 2, code: "E_USAGE", message: GUARD_COMMIT_USAGE });
+                    throw new CliError({
+                        exitCode: 2,
+                        code: "E_USAGE",
+                        message: usageMessage(GUARD_COMMIT_USAGE, GUARD_COMMIT_USAGE_EXAMPLE),
+                    });
                 }
                 const allow = [];
                 let message = "";
@@ -7497,7 +8040,11 @@ export async function runCli(argv) {
                     if (arg === "--allow") {
                         const next = restArgs[i + 1];
                         if (!next)
-                            throw new CliError({ exitCode: 2, code: "E_USAGE", message: GUARD_COMMIT_USAGE });
+                            throw new CliError({
+                                exitCode: 2,
+                                code: "E_USAGE",
+                                message: usageMessage(GUARD_COMMIT_USAGE, GUARD_COMMIT_USAGE_EXAMPLE),
+                            });
                         allow.push(next);
                         i++;
                         continue;
@@ -7505,7 +8052,11 @@ export async function runCli(argv) {
                     if (arg === "-m" || arg === "--message") {
                         const next = restArgs[i + 1];
                         if (!next)
-                            throw new CliError({ exitCode: 2, code: "E_USAGE", message: GUARD_COMMIT_USAGE });
+                            throw new CliError({
+                                exitCode: 2,
+                                code: "E_USAGE",
+                                message: usageMessage(GUARD_COMMIT_USAGE, GUARD_COMMIT_USAGE_EXAMPLE),
+                            });
                         message = next;
                         i++;
                         continue;
@@ -7531,11 +8082,19 @@ export async function runCli(argv) {
                         continue;
                     }
                     if (arg.startsWith("--")) {
-                        throw new CliError({ exitCode: 2, code: "E_USAGE", message: GUARD_COMMIT_USAGE });
+                        throw new CliError({
+                            exitCode: 2,
+                            code: "E_USAGE",
+                            message: usageMessage(GUARD_COMMIT_USAGE, GUARD_COMMIT_USAGE_EXAMPLE),
+                        });
                     }
                 }
                 if (!message) {
-                    throw new CliError({ exitCode: 2, code: "E_USAGE", message: GUARD_COMMIT_USAGE });
+                    throw new CliError({
+                        exitCode: 2,
+                        code: "E_USAGE",
+                        message: usageMessage(GUARD_COMMIT_USAGE, GUARD_COMMIT_USAGE_EXAMPLE),
+                    });
                 }
                 if (autoAllow && allow.length === 0) {
                     const staged = await getStagedFiles({
@@ -7544,12 +8103,16 @@ export async function runCli(argv) {
                     });
                     const prefixes = suggestAllowPrefixes(staged);
                     if (prefixes.length === 0) {
-                        throw new CliError({ exitCode: 5, code: "E_GIT", message: "No staged files" });
+                        throw new CliError({
+                            exitCode: 5,
+                            code: "E_GIT",
+                            message: "No staged files (git index empty)",
+                        });
                     }
                     allow.push(...prefixes);
                 }
                 if (allowDirty) {
-                    // Deprecated no-op for parity with agentctl.
+                    // Deprecated no-op retained for compatibility.
                 }
                 return await cmdGuardCommit({
                     cwd: process.cwd(),
@@ -7565,13 +8128,17 @@ export async function runCli(argv) {
             throw new CliError({
                 exitCode: 2,
                 code: "E_USAGE",
-                message: "Usage: agentplane guard <subcommand>",
+                message: usageMessage(GUARD_USAGE, GUARD_USAGE_EXAMPLE),
             });
         }
         if (namespace === "commit") {
             const taskId = command;
             if (!taskId) {
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: COMMIT_USAGE });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: usageMessage(COMMIT_USAGE, COMMIT_USAGE_EXAMPLE),
+                });
             }
             const allow = [];
             let message = "";
@@ -7587,7 +8154,11 @@ export async function runCli(argv) {
                 if (arg === "--allow") {
                     const next = args[i + 1];
                     if (!next)
-                        throw new CliError({ exitCode: 2, code: "E_USAGE", message: COMMIT_USAGE });
+                        throw new CliError({
+                            exitCode: 2,
+                            code: "E_USAGE",
+                            message: usageMessage(COMMIT_USAGE, COMMIT_USAGE_EXAMPLE),
+                        });
                     allow.push(next);
                     i++;
                     continue;
@@ -7595,7 +8166,11 @@ export async function runCli(argv) {
                 if (arg === "-m" || arg === "--message") {
                     const next = args[i + 1];
                     if (!next)
-                        throw new CliError({ exitCode: 2, code: "E_USAGE", message: COMMIT_USAGE });
+                        throw new CliError({
+                            exitCode: 2,
+                            code: "E_USAGE",
+                            message: usageMessage(COMMIT_USAGE, COMMIT_USAGE_EXAMPLE),
+                        });
                     message = next;
                     i++;
                     continue;
@@ -7621,11 +8196,19 @@ export async function runCli(argv) {
                     continue;
                 }
                 if (arg.startsWith("--")) {
-                    throw new CliError({ exitCode: 2, code: "E_USAGE", message: COMMIT_USAGE });
+                    throw new CliError({
+                        exitCode: 2,
+                        code: "E_USAGE",
+                        message: usageMessage(COMMIT_USAGE, COMMIT_USAGE_EXAMPLE),
+                    });
                 }
             }
             if (!message) {
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: COMMIT_USAGE });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: usageMessage(COMMIT_USAGE, COMMIT_USAGE_EXAMPLE),
+                });
             }
             return await cmdCommit({
                 cwd: process.cwd(),
@@ -7650,7 +8233,11 @@ export async function runCli(argv) {
                 taskId = process.env.AGENT_PLANE_TASK_ID ?? "";
             }
             if (!taskId) {
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: START_USAGE });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: usageMessage(START_USAGE, START_USAGE_EXAMPLE),
+                });
             }
             let author = "";
             let body = "";
@@ -7670,7 +8257,11 @@ export async function runCli(argv) {
                 if (arg === "--author") {
                     const next = startArgs[i + 1];
                     if (!next)
-                        throw new CliError({ exitCode: 2, code: "E_USAGE", message: START_USAGE });
+                        throw new CliError({
+                            exitCode: 2,
+                            code: "E_USAGE",
+                            message: usageMessage(START_USAGE, START_USAGE_EXAMPLE),
+                        });
                     author = next;
                     i++;
                     continue;
@@ -7678,7 +8269,11 @@ export async function runCli(argv) {
                 if (arg === "--body") {
                     const next = startArgs[i + 1];
                     if (!next)
-                        throw new CliError({ exitCode: 2, code: "E_USAGE", message: START_USAGE });
+                        throw new CliError({
+                            exitCode: 2,
+                            code: "E_USAGE",
+                            message: usageMessage(START_USAGE, START_USAGE_EXAMPLE),
+                        });
                     body = next;
                     i++;
                     continue;
@@ -7690,7 +8285,11 @@ export async function runCli(argv) {
                 if (arg === "--commit-emoji") {
                     const next = startArgs[i + 1];
                     if (!next)
-                        throw new CliError({ exitCode: 2, code: "E_USAGE", message: START_USAGE });
+                        throw new CliError({
+                            exitCode: 2,
+                            code: "E_USAGE",
+                            message: usageMessage(START_USAGE, START_USAGE_EXAMPLE),
+                        });
                     commitEmoji = next;
                     i++;
                     continue;
@@ -7698,7 +8297,11 @@ export async function runCli(argv) {
                 if (arg === "--commit-allow") {
                     const next = startArgs[i + 1];
                     if (!next)
-                        throw new CliError({ exitCode: 2, code: "E_USAGE", message: START_USAGE });
+                        throw new CliError({
+                            exitCode: 2,
+                            code: "E_USAGE",
+                            message: usageMessage(START_USAGE, START_USAGE_EXAMPLE),
+                        });
                     commitAllow.push(next);
                     i++;
                     continue;
@@ -7728,11 +8331,19 @@ export async function runCli(argv) {
                     continue;
                 }
                 if (arg.startsWith("--")) {
-                    throw new CliError({ exitCode: 2, code: "E_USAGE", message: START_USAGE });
+                    throw new CliError({
+                        exitCode: 2,
+                        code: "E_USAGE",
+                        message: usageMessage(START_USAGE, START_USAGE_EXAMPLE),
+                    });
                 }
             }
             if (!author || !body) {
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: START_USAGE });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: usageMessage(START_USAGE, START_USAGE_EXAMPLE),
+                });
             }
             return await cmdStart({
                 cwd: process.cwd(),
@@ -7761,7 +8372,11 @@ export async function runCli(argv) {
                 taskId = process.env.AGENT_PLANE_TASK_ID ?? "";
             }
             if (!taskId) {
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: BLOCK_USAGE });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: usageMessage(BLOCK_USAGE, BLOCK_USAGE_EXAMPLE),
+                });
             }
             let author = "";
             let body = "";
@@ -7781,7 +8396,11 @@ export async function runCli(argv) {
                 if (arg === "--author") {
                     const next = blockArgs[i + 1];
                     if (!next)
-                        throw new CliError({ exitCode: 2, code: "E_USAGE", message: BLOCK_USAGE });
+                        throw new CliError({
+                            exitCode: 2,
+                            code: "E_USAGE",
+                            message: usageMessage(BLOCK_USAGE, BLOCK_USAGE_EXAMPLE),
+                        });
                     author = next;
                     i++;
                     continue;
@@ -7789,7 +8408,11 @@ export async function runCli(argv) {
                 if (arg === "--body") {
                     const next = blockArgs[i + 1];
                     if (!next)
-                        throw new CliError({ exitCode: 2, code: "E_USAGE", message: BLOCK_USAGE });
+                        throw new CliError({
+                            exitCode: 2,
+                            code: "E_USAGE",
+                            message: usageMessage(BLOCK_USAGE, BLOCK_USAGE_EXAMPLE),
+                        });
                     body = next;
                     i++;
                     continue;
@@ -7801,7 +8424,11 @@ export async function runCli(argv) {
                 if (arg === "--commit-emoji") {
                     const next = blockArgs[i + 1];
                     if (!next)
-                        throw new CliError({ exitCode: 2, code: "E_USAGE", message: BLOCK_USAGE });
+                        throw new CliError({
+                            exitCode: 2,
+                            code: "E_USAGE",
+                            message: usageMessage(BLOCK_USAGE, BLOCK_USAGE_EXAMPLE),
+                        });
                     commitEmoji = next;
                     i++;
                     continue;
@@ -7809,7 +8436,11 @@ export async function runCli(argv) {
                 if (arg === "--commit-allow") {
                     const next = blockArgs[i + 1];
                     if (!next)
-                        throw new CliError({ exitCode: 2, code: "E_USAGE", message: BLOCK_USAGE });
+                        throw new CliError({
+                            exitCode: 2,
+                            code: "E_USAGE",
+                            message: usageMessage(BLOCK_USAGE, BLOCK_USAGE_EXAMPLE),
+                        });
                     commitAllow.push(next);
                     i++;
                     continue;
@@ -7839,11 +8470,19 @@ export async function runCli(argv) {
                     continue;
                 }
                 if (arg.startsWith("--")) {
-                    throw new CliError({ exitCode: 2, code: "E_USAGE", message: BLOCK_USAGE });
+                    throw new CliError({
+                        exitCode: 2,
+                        code: "E_USAGE",
+                        message: usageMessage(BLOCK_USAGE, BLOCK_USAGE_EXAMPLE),
+                    });
                 }
             }
             if (!author || !body) {
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: BLOCK_USAGE });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: usageMessage(BLOCK_USAGE, BLOCK_USAGE_EXAMPLE),
+                });
             }
             return await cmdBlock({
                 cwd: process.cwd(),
@@ -7886,7 +8525,11 @@ export async function runCli(argv) {
                     taskIds.push(envTaskId);
             }
             if (taskIds.length === 0) {
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: FINISH_USAGE });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: usageMessage(FINISH_USAGE, FINISH_USAGE_EXAMPLE),
+                });
             }
             let author = "";
             let body = "";
@@ -7914,7 +8557,11 @@ export async function runCli(argv) {
                 if (arg === "--author") {
                     const next = flagArgs[i + 1];
                     if (!next)
-                        throw new CliError({ exitCode: 2, code: "E_USAGE", message: FINISH_USAGE });
+                        throw new CliError({
+                            exitCode: 2,
+                            code: "E_USAGE",
+                            message: usageMessage(FINISH_USAGE, FINISH_USAGE_EXAMPLE),
+                        });
                     author = next;
                     i++;
                     continue;
@@ -7922,7 +8569,11 @@ export async function runCli(argv) {
                 if (arg === "--body") {
                     const next = flagArgs[i + 1];
                     if (!next)
-                        throw new CliError({ exitCode: 2, code: "E_USAGE", message: FINISH_USAGE });
+                        throw new CliError({
+                            exitCode: 2,
+                            code: "E_USAGE",
+                            message: usageMessage(FINISH_USAGE, FINISH_USAGE_EXAMPLE),
+                        });
                     body = next;
                     i++;
                     continue;
@@ -7930,7 +8581,11 @@ export async function runCli(argv) {
                 if (arg === "--commit") {
                     const next = flagArgs[i + 1];
                     if (!next)
-                        throw new CliError({ exitCode: 2, code: "E_USAGE", message: FINISH_USAGE });
+                        throw new CliError({
+                            exitCode: 2,
+                            code: "E_USAGE",
+                            message: usageMessage(FINISH_USAGE, FINISH_USAGE_EXAMPLE),
+                        });
                     commit = next;
                     i++;
                     continue;
@@ -7958,7 +8613,11 @@ export async function runCli(argv) {
                 if (arg === "--commit-emoji") {
                     const next = flagArgs[i + 1];
                     if (!next)
-                        throw new CliError({ exitCode: 2, code: "E_USAGE", message: FINISH_USAGE });
+                        throw new CliError({
+                            exitCode: 2,
+                            code: "E_USAGE",
+                            message: usageMessage(FINISH_USAGE, FINISH_USAGE_EXAMPLE),
+                        });
                     commitEmoji = next;
                     i++;
                     continue;
@@ -7966,7 +8625,11 @@ export async function runCli(argv) {
                 if (arg === "--commit-allow") {
                     const next = flagArgs[i + 1];
                     if (!next)
-                        throw new CliError({ exitCode: 2, code: "E_USAGE", message: FINISH_USAGE });
+                        throw new CliError({
+                            exitCode: 2,
+                            code: "E_USAGE",
+                            message: usageMessage(FINISH_USAGE, FINISH_USAGE_EXAMPLE),
+                        });
                     commitAllow.push(next);
                     i++;
                     continue;
@@ -7990,7 +8653,11 @@ export async function runCli(argv) {
                 if (arg === "--status-commit-emoji") {
                     const next = flagArgs[i + 1];
                     if (!next)
-                        throw new CliError({ exitCode: 2, code: "E_USAGE", message: FINISH_USAGE });
+                        throw new CliError({
+                            exitCode: 2,
+                            code: "E_USAGE",
+                            message: usageMessage(FINISH_USAGE, FINISH_USAGE_EXAMPLE),
+                        });
                     statusCommitEmoji = next;
                     i++;
                     continue;
@@ -7998,7 +8665,11 @@ export async function runCli(argv) {
                 if (arg === "--status-commit-allow") {
                     const next = flagArgs[i + 1];
                     if (!next)
-                        throw new CliError({ exitCode: 2, code: "E_USAGE", message: FINISH_USAGE });
+                        throw new CliError({
+                            exitCode: 2,
+                            code: "E_USAGE",
+                            message: usageMessage(FINISH_USAGE, FINISH_USAGE_EXAMPLE),
+                        });
                     statusCommitAllow.push(next);
                     i++;
                     continue;
@@ -8016,11 +8687,19 @@ export async function runCli(argv) {
                     continue;
                 }
                 if (arg.startsWith("--")) {
-                    throw new CliError({ exitCode: 2, code: "E_USAGE", message: FINISH_USAGE });
+                    throw new CliError({
+                        exitCode: 2,
+                        code: "E_USAGE",
+                        message: usageMessage(FINISH_USAGE, FINISH_USAGE_EXAMPLE),
+                    });
                 }
             }
             if (!author || !body) {
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: FINISH_USAGE });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: usageMessage(FINISH_USAGE, FINISH_USAGE_EXAMPLE),
+                });
             }
             return await cmdFinish({
                 cwd: process.cwd(),
@@ -8057,7 +8736,11 @@ export async function runCli(argv) {
                 taskId = process.env.AGENT_PLANE_TASK_ID ?? "";
             }
             if (!taskId) {
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: VERIFY_USAGE });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: usageMessage(VERIFY_USAGE, VERIFY_USAGE_EXAMPLE),
+                });
             }
             let cwdOverride;
             let logPath;
@@ -8071,7 +8754,11 @@ export async function runCli(argv) {
                 if (arg === "--cwd") {
                     const next = verifyArgs[i + 1];
                     if (!next)
-                        throw new CliError({ exitCode: 2, code: "E_USAGE", message: VERIFY_USAGE });
+                        throw new CliError({
+                            exitCode: 2,
+                            code: "E_USAGE",
+                            message: usageMessage(VERIFY_USAGE, VERIFY_USAGE_EXAMPLE),
+                        });
                     cwdOverride = next;
                     i++;
                     continue;
@@ -8079,7 +8766,11 @@ export async function runCli(argv) {
                 if (arg === "--log") {
                     const next = verifyArgs[i + 1];
                     if (!next)
-                        throw new CliError({ exitCode: 2, code: "E_USAGE", message: VERIFY_USAGE });
+                        throw new CliError({
+                            exitCode: 2,
+                            code: "E_USAGE",
+                            message: usageMessage(VERIFY_USAGE, VERIFY_USAGE_EXAMPLE),
+                        });
                     logPath = next;
                     i++;
                     continue;
@@ -8097,7 +8788,11 @@ export async function runCli(argv) {
                     continue;
                 }
                 if (arg.startsWith("--")) {
-                    throw new CliError({ exitCode: 2, code: "E_USAGE", message: VERIFY_USAGE });
+                    throw new CliError({
+                        exitCode: 2,
+                        code: "E_USAGE",
+                        message: usageMessage(VERIFY_USAGE, VERIFY_USAGE_EXAMPLE),
+                    });
                 }
             }
             return await cmdVerify({
@@ -8114,7 +8809,11 @@ export async function runCli(argv) {
         if (namespace === "integrate") {
             const taskId = command;
             if (!taskId) {
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: INTEGRATE_USAGE });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: usageMessage(INTEGRATE_USAGE, INTEGRATE_USAGE_EXAMPLE),
+                });
             }
             let branch;
             let base;
@@ -8129,7 +8828,11 @@ export async function runCli(argv) {
                 if (arg === "--branch") {
                     const next = args[i + 1];
                     if (!next)
-                        throw new CliError({ exitCode: 2, code: "E_USAGE", message: INTEGRATE_USAGE });
+                        throw new CliError({
+                            exitCode: 2,
+                            code: "E_USAGE",
+                            message: usageMessage(INTEGRATE_USAGE, INTEGRATE_USAGE_EXAMPLE),
+                        });
                     branch = next;
                     i++;
                     continue;
@@ -8137,7 +8840,11 @@ export async function runCli(argv) {
                 if (arg === "--base") {
                     const next = args[i + 1];
                     if (!next)
-                        throw new CliError({ exitCode: 2, code: "E_USAGE", message: INTEGRATE_USAGE });
+                        throw new CliError({
+                            exitCode: 2,
+                            code: "E_USAGE",
+                            message: usageMessage(INTEGRATE_USAGE, INTEGRATE_USAGE_EXAMPLE),
+                        });
                     base = next;
                     i++;
                     continue;
@@ -8145,7 +8852,11 @@ export async function runCli(argv) {
                 if (arg === "--merge-strategy") {
                     const next = args[i + 1];
                     if (next !== "squash" && next !== "merge" && next !== "rebase") {
-                        throw new CliError({ exitCode: 2, code: "E_USAGE", message: INTEGRATE_USAGE });
+                        throw new CliError({
+                            exitCode: 2,
+                            code: "E_USAGE",
+                            message: usageMessage(INTEGRATE_USAGE, INTEGRATE_USAGE_EXAMPLE),
+                        });
                     }
                     mergeStrategy = next;
                     i++;
@@ -8164,9 +8875,17 @@ export async function runCli(argv) {
                     continue;
                 }
                 if (arg.startsWith("--")) {
-                    throw new CliError({ exitCode: 2, code: "E_USAGE", message: INTEGRATE_USAGE });
+                    throw new CliError({
+                        exitCode: 2,
+                        code: "E_USAGE",
+                        message: usageMessage(INTEGRATE_USAGE, INTEGRATE_USAGE_EXAMPLE),
+                    });
                 }
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: INTEGRATE_USAGE });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: usageMessage(INTEGRATE_USAGE, INTEGRATE_USAGE_EXAMPLE),
+                });
             }
             return await cmdIntegrate({
                 cwd: process.cwd(),
@@ -8183,7 +8902,11 @@ export async function runCli(argv) {
         if (namespace === "cleanup") {
             const subcommand = command;
             if (subcommand !== "merged") {
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: CLEANUP_MERGED_USAGE });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: usageMessage(CLEANUP_MERGED_USAGE, CLEANUP_MERGED_USAGE_EXAMPLE),
+                });
             }
             let base;
             let yes = false;
@@ -8196,7 +8919,11 @@ export async function runCli(argv) {
                 if (arg === "--base") {
                     const next = args[i + 1];
                     if (!next)
-                        throw new CliError({ exitCode: 2, code: "E_USAGE", message: CLEANUP_MERGED_USAGE });
+                        throw new CliError({
+                            exitCode: 2,
+                            code: "E_USAGE",
+                            message: usageMessage(CLEANUP_MERGED_USAGE, CLEANUP_MERGED_USAGE_EXAMPLE),
+                        });
                     base = next;
                     i++;
                     continue;
@@ -8214,9 +8941,17 @@ export async function runCli(argv) {
                     continue;
                 }
                 if (arg.startsWith("--")) {
-                    throw new CliError({ exitCode: 2, code: "E_USAGE", message: CLEANUP_MERGED_USAGE });
+                    throw new CliError({
+                        exitCode: 2,
+                        code: "E_USAGE",
+                        message: usageMessage(CLEANUP_MERGED_USAGE, CLEANUP_MERGED_USAGE_EXAMPLE),
+                    });
                 }
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: CLEANUP_MERGED_USAGE });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: usageMessage(CLEANUP_MERGED_USAGE, CLEANUP_MERGED_USAGE_EXAMPLE),
+                });
             }
             return await cmdCleanupMerged({
                 cwd: process.cwd(),
@@ -8230,17 +8965,29 @@ export async function runCli(argv) {
         if (namespace === "scenario") {
             const subcommand = command;
             if (!subcommand) {
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: SCENARIO_USAGE });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: usageMessage(SCENARIO_USAGE, SCENARIO_USAGE_EXAMPLE),
+                });
             }
             if (subcommand === "list") {
                 if (args.length > 0) {
-                    throw new CliError({ exitCode: 2, code: "E_USAGE", message: SCENARIO_USAGE });
+                    throw new CliError({
+                        exitCode: 2,
+                        code: "E_USAGE",
+                        message: usageMessage(SCENARIO_USAGE, SCENARIO_USAGE_EXAMPLE),
+                    });
                 }
                 return await cmdScenarioList({ cwd: process.cwd(), rootOverride: globals.root });
             }
             if (subcommand === "info") {
                 if (args.length !== 1) {
-                    throw new CliError({ exitCode: 2, code: "E_USAGE", message: SCENARIO_INFO_USAGE });
+                    throw new CliError({
+                        exitCode: 2,
+                        code: "E_USAGE",
+                        message: usageMessage(SCENARIO_INFO_USAGE, SCENARIO_INFO_USAGE_EXAMPLE),
+                    });
                 }
                 return await cmdScenarioInfo({
                     cwd: process.cwd(),
@@ -8250,7 +8997,11 @@ export async function runCli(argv) {
             }
             if (subcommand === "run") {
                 if (args.length !== 1) {
-                    throw new CliError({ exitCode: 2, code: "E_USAGE", message: SCENARIO_RUN_USAGE });
+                    throw new CliError({
+                        exitCode: 2,
+                        code: "E_USAGE",
+                        message: usageMessage(SCENARIO_RUN_USAGE, SCENARIO_RUN_USAGE_EXAMPLE),
+                    });
                 }
                 return await cmdScenarioRun({
                     cwd: process.cwd(),
@@ -8258,12 +9009,20 @@ export async function runCli(argv) {
                     id: args[0],
                 });
             }
-            throw new CliError({ exitCode: 2, code: "E_USAGE", message: SCENARIO_USAGE });
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: usageMessage(SCENARIO_USAGE, SCENARIO_USAGE_EXAMPLE),
+            });
         }
         if (namespace === "recipe" || namespace === "recipes") {
             const subcommand = command;
             if (!subcommand) {
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: RECIPE_USAGE });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: usageMessage(RECIPE_USAGE, RECIPE_USAGE_EXAMPLE),
+                });
             }
             if (subcommand === "list") {
                 return await cmdRecipeList({
@@ -8281,7 +9040,11 @@ export async function runCli(argv) {
             }
             if (subcommand === "info") {
                 if (args.length !== 1) {
-                    throw new CliError({ exitCode: 2, code: "E_USAGE", message: RECIPE_INFO_USAGE });
+                    throw new CliError({
+                        exitCode: 2,
+                        code: "E_USAGE",
+                        message: usageMessage(RECIPE_INFO_USAGE, RECIPE_INFO_USAGE_EXAMPLE),
+                    });
                 }
                 return await cmdRecipeInfo({
                     cwd: process.cwd(),
@@ -8291,7 +9054,11 @@ export async function runCli(argv) {
             }
             if (subcommand === "explain") {
                 if (args.length !== 1) {
-                    throw new CliError({ exitCode: 2, code: "E_USAGE", message: RECIPE_EXPLAIN_USAGE });
+                    throw new CliError({
+                        exitCode: 2,
+                        code: "E_USAGE",
+                        message: usageMessage(RECIPE_EXPLAIN_USAGE, RECIPE_EXPLAIN_USAGE_EXAMPLE),
+                    });
                 }
                 return await cmdRecipeExplain({
                     cwd: process.cwd(),
@@ -8312,7 +9079,11 @@ export async function runCli(argv) {
             }
             if (subcommand === "remove") {
                 if (args.length !== 1) {
-                    throw new CliError({ exitCode: 2, code: "E_USAGE", message: RECIPE_REMOVE_USAGE });
+                    throw new CliError({
+                        exitCode: 2,
+                        code: "E_USAGE",
+                        message: usageMessage(RECIPE_REMOVE_USAGE, RECIPE_REMOVE_USAGE_EXAMPLE),
+                    });
                 }
                 return await cmdRecipeRemove({
                     cwd: process.cwd(),
@@ -8324,7 +9095,11 @@ export async function runCli(argv) {
                 const cacheSub = args[0];
                 const cacheArgs = args.slice(1);
                 if (!cacheSub) {
-                    throw new CliError({ exitCode: 2, code: "E_USAGE", message: RECIPE_CACHE_USAGE });
+                    throw new CliError({
+                        exitCode: 2,
+                        code: "E_USAGE",
+                        message: usageMessage(RECIPE_CACHE_USAGE, RECIPE_CACHE_USAGE_EXAMPLE),
+                    });
                 }
                 if (cacheSub === "prune") {
                     return await cmdRecipeCachePrune({
@@ -8333,14 +9108,26 @@ export async function runCli(argv) {
                         args: cacheArgs,
                     });
                 }
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: RECIPE_CACHE_USAGE });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: usageMessage(RECIPE_CACHE_USAGE, RECIPE_CACHE_USAGE_EXAMPLE),
+                });
             }
-            throw new CliError({ exitCode: 2, code: "E_USAGE", message: RECIPE_USAGE });
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: usageMessage(RECIPE_USAGE, RECIPE_USAGE_EXAMPLE),
+            });
         }
         if (namespace === "backend") {
             const subcommand = command;
             if (subcommand !== "sync") {
-                throw new CliError({ exitCode: 2, code: "E_USAGE", message: BACKEND_SYNC_USAGE });
+                throw new CliError({
+                    exitCode: 2,
+                    code: "E_USAGE",
+                    message: usageMessage(BACKEND_SYNC_USAGE, BACKEND_SYNC_USAGE_EXAMPLE),
+                });
             }
             return await cmdBackendSync({
                 cwd: process.cwd(),
@@ -8377,7 +9164,7 @@ export async function runCli(argv) {
                     throw new CliError({
                         exitCode: 2,
                         code: "E_USAGE",
-                        message: "Usage: agentplane hooks run <hook>",
+                        message: usageMessage(HOOKS_RUN_USAGE, HOOKS_RUN_USAGE_EXAMPLE),
                     });
                 }
                 return await cmdHooksRun({
@@ -8390,7 +9177,7 @@ export async function runCli(argv) {
             throw new CliError({
                 exitCode: 2,
                 code: "E_USAGE",
-                message: "Usage: agentplane hooks install|uninstall",
+                message: usageMessage(HOOKS_INSTALL_USAGE, HOOKS_INSTALL_USAGE_EXAMPLE),
             });
         }
         throw new CliError({