agentplane 0.3.1 → 0.3.3

package/dist/cli/command-guide.js

@@ -1,183 +1,98 @@
 import { COMMAND_SNIPPETS } from "./command-snippets.js";
-const CHEAT_SHEET_ROWS = [
-    {
-        operation: "PLANNER: list/show tasks",
-        command: "`agentplane task list` / `agentplane task show <task-id>`",
-    },
-    {
-        operation: "PLANNER: set/approve/reject plan",
-        command: '`agentplane task plan set <task-id> --text "..." --updated-by <id>` / `agentplane task plan approve <task-id> --by <id> --note "OK"`',
-    },
-    {
-        operation: "PLANNER: create task (auto ID)",
-        command: '`agentplane task new --title "..." --description "..." --priority med --owner CODER --tag <tag> [--depends-on <task-id|json>]`',
-    },
-    {
-        operation: "PLANNER: add/update task",
-        command: "`agentplane task add <task-id> ...` / `agentplane task update <task-id> ...`",
-    },
-    {
-        operation: "PLANNER: backfill/repair scaffold",
-        command: "`agentplane task scaffold <task-id>` (backfill/import/manual repair only)",
-    },
-    {
-        operation: "PLANNER: derive implementation from spike",
-        command: '`agentplane task derive <spike-id> --title "..." --description "..." --priority med --owner CODER --tag code`',
-    },
-    {
-        operation: "Config: show/set",
-        command: "`agentplane config show` / `agentplane config set <key> <value>`",
-    },
-    {
-        operation: "CODER/TESTER/DOCS: start checkout (branch_pr)",
-        command: "`agentplane work start <task-id> --agent <ROLE> --slug <slug> --worktree`",
-    },
-    {
-        operation: "CODER/TESTER: start task deterministically",
-        command: '`agentplane task start-ready <task-id> --author <ROLE> --body "Start: ..."` (run after successful `task plan approve`; do not run in parallel)',
-    },
-    {
-        operation: "CODER/TESTER/DOCS: update PR artifacts",
-        command: "`agentplane pr update <task-id>`",
-    },
-    {
-        operation: "CODER/TESTER/DOCS/REVIEWER: add handoff note",
-        command: '`agentplane pr note <task-id> --author <ROLE> --body "..."`',
-    },
-    {
-        operation: "CODER/TESTER: verify task",
-        command: '`agentplane verify <task-id> --ok|--rework --by <id> --note "..."` (record-only; appends to README)',
-    },
-    {
-        operation: "CODER/TESTER: print Verify Steps",
-        command: "`agentplane task verify-show <task-id>`",
-    },
-    {
-        operation: "REVIEWER: check PR artifacts",
-        command: "`agentplane pr check <task-id>`",
-    },
-    {
-        operation: "INTEGRATOR: integrate task",
-        command: "`agentplane integrate <task-id> --branch task/<task-id>/<slug> --merge-strategy squash --run-verify`",
-    },
-    {
-        operation: "INTEGRATOR: finish task(s)",
-        command: '`agentplane finish <task-id> [<task-id> ...] --commit <git-rev> --author INTEGRATOR --body "Verified: ..." [--result "<one line>"] [--close-commit] [--close-unstage-others]`',
-    },
-    {
-        operation: "INTEGRATOR: commit closure",
-        command: "Preferred: `agentplane finish <task-id> --close-commit` (single command). Legacy/manual: `agentplane commit <task-id> --close [--check-only] [--unstage-others]` / duplicate no-op close: `agentplane task close-duplicate <task-id> --of <canonical-task-id> --author <ROLE>`",
-    },
-];
+import { AGENT_BOOTSTRAP_DOC_PATH, BOOTSTRAP_PREFLIGHT_COMMANDS, BOOTSTRAP_TASK_PREP_COMMANDS, } from "./bootstrap-guide.js";
+const CLI_REFERENCE_DOC_PATH = "docs/user/cli-reference.generated.mdx";
+function renderQuickstartCommandBlock(commands) {
+    return ["```bash", ...commands, "```"];
+}
 const ROLE_GUIDES = [
     {
         role: "ORCHESTRATOR",
         lines: [
-            "- Plan intake: `agentplane task list` / `agentplane task show <task-id>`",
-            "- After plan approval: ask PLANNER to create executable tasks directly from the approved task graph.",
-            "- If task graph has exactly one work item, create exactly one executable task.",
-            "- Two-stage verification: `## Verify Steps` is the ex-ante contract; `agentplane verify ...` appends an ex-post entry into `## Verification`.",
+            `- Shared bootstrap path: \`${COMMAND_SNIPPETS.core.quickstart}\` -> \`${AGENT_BOOTSTRAP_DOC_PATH}\`.`,
+            "- Owns preflight, plan summaries, approvals, and scope checkpoints.",
+            "- Does not create non-executable tasks or bypass lifecycle guardrails.",
         ],
     },
     {
         role: "PLANNER",
         lines: [
-            '- TODO scan: `agentplane task list` / `agentplane task search "..."` / `agentplane task next`',
-            '- Create tasks: `agentplane task new --title "..." --description "..." --priority med --owner <ROLE> --depends-on "[]" --tag <tag>` (tags are required; use `task add` only for imported IDs)',
-            '- Update tasks: `agentplane task update <task-id> --title "..." --description "..." --priority med --owner <ROLE> --depends-on <task-id>`',
-            "- `task new` auto-seeds README sections; use `task scaffold` only for backfill/import/manual repair.",
-            '- Plan lifecycle: `agentplane task plan set <task-id> --text "..." --updated-by <ROLE>` -> `agentplane task plan approve <task-id> --by <id>`',
-            "- Verify Steps discipline: if a task primary tag is verify-required (default: code/data/ops), fill `## Verify Steps` before plan approval.",
-            "- Doc quality gate: `task plan approve` and `finish` fail when required agent-filled sections (`Summary/Scope/Plan/Risks/Rollback Plan`, per config) are empty/TODO placeholders.",
-            '- Task docs (when planning needs it): `agentplane task doc set <task-id> --section Summary --text "..."`; if `--text`/`--file` contains multiple known headings, the command applies it as one batched full-doc update.',
+            `- Shared bootstrap path: \`${COMMAND_SNIPPETS.core.quickstart}\` -> \`${AGENT_BOOTSTRAP_DOC_PATH}\`.`,
+            '- Create executable tasks with `agentplane task new --title "..." --description "..." --priority med --owner <ROLE> --tag <tag>`.',
+            '- Fill docs with `agentplane task doc set <task-id> --section <name> --text "..."` and set plan text with `agentplane task plan set <task-id> --text "..." --updated-by <ROLE>`.',
+            "- Approve plan only after required sections and Verify Steps are ready.",
         ],
     },
     {
         role: "CODER",
         lines: [
-            "- direct mode: single-stream in the current checkout; `agentplane work start <task-id> --agent <ROLE> --slug <slug>` records the active task and keeps the current branch (no task branches). Use `task doc set` / `task plan set` for normal docs updates; batched doc updates are allowed before approval.",
-            "- branch_pr: `agentplane work start <task-id> --agent <ROLE> --slug <slug> --worktree`",
-            '- Start status (deterministic): `agentplane task start-ready <task-id> --author <ROLE> --body "Start: ..."` (after `task plan approve`, sequential only).',
-            '- Other status updates: `agentplane block <task-id> --author <ROLE> --body "Blocked: ..."`',
-            "- Verify Steps: `agentplane task verify-show <task-id>` (use as the verification contract before recording results).",
-            '- Verify: `agentplane verify <task-id> --ok|--rework --by <ROLE> --note "..."`',
-            '- PR artifacts (branch_pr): `agentplane pr open <task-id> --branch task/<task-id>/<slug> --author <ROLE>` / `agentplane pr update <task-id>` / `agentplane pr note <task-id> --author <ROLE> --body "..."`',
-            '- Commit: `agentplane guard commit <task-id> -m "<emoji> <suffix> <scope>: <summary>"` / `agentplane commit <task-id> -m "<emoji> <suffix> <scope>: <summary>" --allow <path-prefix>` / preferred close path: `agentplane finish <task-id> --close-commit [--close-unstage-others]`',
+            `- Shared bootstrap path: \`${COMMAND_SNIPPETS.core.quickstart}\` -> \`${AGENT_BOOTSTRAP_DOC_PATH}\`.`,
+            "- direct: stay in the current checkout; branch_pr: start a task branch/worktree first.",
+            `- Start deterministically with \`${COMMAND_SNIPPETS.core.startTask}\` after plan approval.`,
+            '- Treat `agentplane task verify-show <task-id>` as the verification contract, then record `agentplane verify <task-id> --ok|--rework --by <ROLE> --note "..."`.',
+            `- Preferred direct close path: \`${COMMAND_SNIPPETS.core.finishTask}\` with \`--result "..." \`; add \`--no-close-commit\` only for explicit manual close handling.`,
+            "- For manual close or allowlist detail, use `agentplane help finish` and `agentplane help commit` on demand.",
         ],
     },
     {
         role: "TESTER",
         lines: [
-            "- direct mode: single-stream in the current checkout; `agentplane work start <task-id> --agent <ROLE> --slug <slug>` records the active task and keeps the current branch (no task branches). Use `task doc set` / `task plan set` for normal docs updates; batched doc updates are allowed before approval.",
-            "- branch_pr: `agentplane work start <task-id> --agent <ROLE> --slug <slug> --worktree`",
-            '- Start status (deterministic): `agentplane task start-ready <task-id> --author <ROLE> --body "Start: ..."` (after `task plan approve`, sequential only).',
-            '- Other status updates: `agentplane block <task-id> --author <ROLE> --body "Blocked: ..."`',
-            "- Verify Steps: `agentplane task verify-show <task-id>` (treat as the verification contract).",
-            '- Verify: `agentplane verify <task-id> --ok|--rework --by <ROLE> --note "..."`',
-            '- PR artifacts (branch_pr): `agentplane pr open <task-id> --branch task/<task-id>/<slug> --author <ROLE>` / `agentplane pr update <task-id>` / `agentplane pr note <task-id> --author <ROLE> --body "..."`',
-            '- Commit: `agentplane guard commit <task-id> -m "<emoji> <suffix> <scope>: <summary>"` / `agentplane commit <task-id> -m "<emoji> <suffix> <scope>: <summary>" --allow <path-prefix>` / preferred close path: `agentplane finish <task-id> --close-commit [--close-unstage-others]`',
+            `- Shared bootstrap path: \`${COMMAND_SNIPPETS.core.quickstart}\` -> \`${AGENT_BOOTSTRAP_DOC_PATH}\`.`,
+            "- Start only after plan approval and explicit Verify Steps exist.",
+            '- Use `agentplane task verify-show <task-id>` before running checks, then record `agentplane verify <task-id> --ok|--rework --by <ROLE> --note "..."`.',
+            `- In direct mode, close with \`${COMMAND_SNIPPETS.core.finishTask}\` plus \`--result "..." \` when you own final verification.`,
+            "- For mixed-state recovery or runtime ambiguity, use `agentplane doctor` and `agentplane runtime explain` instead of relying on the short quickstart screen.",
         ],
     },
     {
         role: "DOCS",
         lines: [
-            '- Task docs: `agentplane task doc set <task-id> --section Summary --text "..."` (repeat per section, or send one multi-heading full-doc payload via `--text`/`--file`)',
-            '- PR notes: `agentplane pr note <task-id> --author DOCS --body "..."`',
-            '- Commit: `agentplane guard commit <task-id> -m "<emoji> <suffix> <scope>: <summary>"` / `agentplane commit <task-id> -m "<emoji> <suffix> <scope>: <summary>" --allow <path-prefix>` / preferred close path: `agentplane finish <task-id> --close-commit [--close-unstage-others]`',
+            `- Shared bootstrap path: \`${COMMAND_SNIPPETS.core.quickstart}\` -> \`${AGENT_BOOTSTRAP_DOC_PATH}\`.`,
+            '- Keep task docs and user docs aligned with runtime behavior via `agentplane task doc set <task-id> --section <name> --text "..."`.',
+            "- For implementation tasks, verify generated/help surfaces after changing CLI-facing text.",
+            `- Treat \`${CLI_REFERENCE_DOC_PATH}\` as the deep reference surface; keep first-screen help intentionally shorter.`,
         ],
     },
     {
         role: "REVIEWER",
         lines: [
-            "- Review artifacts: `agentplane pr check <task-id>` / `agentplane task show <task-id>`",
-            '- Handoff notes: `agentplane pr note <task-id> --author REVIEWER --body "..."`',
+            `- Shared bootstrap path: \`${COMMAND_SNIPPETS.core.quickstart}\` -> \`${AGENT_BOOTSTRAP_DOC_PATH}\`.`,
+            "- Review artifacts with `agentplane task show <task-id>` and `agentplane pr check <task-id>` when relevant.",
+            "- Focus on regressions, lifecycle drift, and missing verification evidence.",
         ],
     },
     {
         role: "INTEGRATOR",
         lines: [
-            '- branch_pr: `agentplane pr check <task-id>` -> `agentplane integrate <task-id> --branch task/<task-id>/<slug> --merge-strategy squash --run-verify` -> `agentplane finish <task-id> --commit <git-rev> --author INTEGRATOR --body "Verified: ..." --close-commit`',
-            '- direct: task owner uses `agentplane finish <task-id> --commit <git-rev> --author <OWNER> --body "Verified: ..." --close-commit` after the implementation commit',
-            "- Optional cleanup: `agentplane cleanup merged --yes`",
+            `- Shared bootstrap path: \`${COMMAND_SNIPPETS.core.quickstart}\` -> \`${AGENT_BOOTSTRAP_DOC_PATH}\`.`,
+            '- branch_pr: `agentplane pr check <task-id>` -> `agentplane integrate <task-id> --branch task/<task-id>/<slug> --merge-strategy squash --run-verify` -> `agentplane finish <task-id> --commit <git-rev> --author INTEGRATOR --body "Verified: ..." --result "..." --close-commit`.',
+            `- direct: the task owner normally closes with \`${COMMAND_SNIPPETS.core.finishTask}\` plus \`--result "..." \`.`,
+            "- For branch-level flags and branch/base diagnostics, use `agentplane help work start`, `agentplane help integrate`, and `agentplane help branch base`.",
         ],
     },
     {
         role: "CREATOR",
         lines: [
-            '- Task bookkeeping: `agentplane task update <task-id> ...` / `agentplane task start-ready <task-id> --author CREATOR --body "Start: ..."`',
-            '- Commits: `agentplane guard commit <task-id> -m "<emoji> <suffix> <scope>: <summary>"` / `agentplane commit <task-id> -m "<emoji> <suffix> <scope>: <summary>" --allow <path-prefix>`',
+            `- Shared bootstrap path: \`${COMMAND_SNIPPETS.core.quickstart}\` -> \`${AGENT_BOOTSTRAP_DOC_PATH}\`.`,
+            `- Use \`${COMMAND_SNIPPETS.core.startTask}\` only when the new-agent creation task is approved and ready.`,
+            "- Keep commits scoped to the created agent artifacts and task docs.",
         ],
     },
     {
         role: "REDMINE",
         lines: [
-            `- Sync before/after updates: \`${COMMAND_SNIPPETS.sync.pullRedmineExplicit}\` / \`${COMMAND_SNIPPETS.sync.pushRedmineExplicitWithYes}\``,
-            "- Then use normal task/doc commands (`agentplane task list` / `agentplane task show` / `agentplane task update` / `agentplane task doc set`) as needed.",
+            `- Shared bootstrap path: \`${COMMAND_SNIPPETS.core.quickstart}\` -> \`${AGENT_BOOTSTRAP_DOC_PATH}\`.`,
+            `- Sync explicitly with \`${COMMAND_SNIPPETS.sync.pullRedmineExplicit}\` / \`${COMMAND_SNIPPETS.sync.pushRedmineExplicitWithYes}\`.`,
+            "- After sync, follow the same task/bootstrap lifecycle as local backends.",
         ],
     },
     {
         role: "UPDATER",
         lines: [
-            '- Read-only audit: `agentplane task list` / `agentplane task show` / `agentplane task search "..."` / `agentplane task next` (no write commands).',
+            `- Shared bootstrap path: \`${COMMAND_SNIPPETS.core.quickstart}\` -> \`${AGENT_BOOTSTRAP_DOC_PATH}\`.`,
+            "- Read-only role: inspect state, do not mutate task or workflow artifacts.",
         ],
     },
 ];
-function renderCheatSheet(rows) {
-    const lines = ["Operation | Command", "--- | ---"];
-    for (const row of rows) {
-        lines.push(`${row.operation} | ${row.command}`);
-    }
-    return lines;
-}
-function renderRoleSection() {
-    const lines = [];
-    for (const guide of ROLE_GUIDES) {
-        lines.push(`### ${guide.role}`, ...guide.lines, "");
-    }
-    if (lines.at(-1) === "")
-        lines.pop();
-    return lines;
-}
 export function listRoles() {
     return ROLE_GUIDES.map((guide) => guide.role);
 }
@@ -195,92 +110,36 @@ export function renderQuickstart() {
     return [
         "# agentplane quickstart",
         "",
-        "The policy gateway file (AGENTS.md or CLAUDE.md) is the source of truth for workflow/process policy; quickstart and role output are the source of truth for CLI syntax and artifacts.",
+        "The policy gateway file (AGENTS.md or CLAUDE.md) is the source of truth for workflow/process policy.",
+        "Keep this first screen short: use it for startup only, then go deeper with `agentplane role <ROLE>` or `agentplane help <command>`.",
         "Do not edit `.agentplane/tasks.json` by hand.",
+        "If the repository is not initialized yet, stop and run `agentplane init` first.",
         "",
-        "- See your policy gateway file (AGENTS.md or CLAUDE.md) for canonical workflow policy and approval gates.",
-        "",
-        "## Project setup",
-        "",
-        "- `agentplane init` (bootstrap `.agentplane/`)",
-        "- `agentplane config show` / `agentplane config set <key> <value>`",
-        "- `agentplane mode get` / `agentplane mode set <direct|branch_pr>`",
-        "- `agentplane ide sync` (regenerate IDE entrypoints)",
-        "",
-        "## Daily task workflow",
-        "",
-        `- \`${COMMAND_SNIPPETS.core.taskList}\` / \`${COMMAND_SNIPPETS.core.taskShow}\``,
-        `- \`${COMMAND_SNIPPETS.core.taskNew}\``,
-        `- \`${COMMAND_SNIPPETS.core.startTask}\``,
-        `- \`${COMMAND_SNIPPETS.core.verifyTask}\``,
-        `- \`${COMMAND_SNIPPETS.core.finishTask}\``,
-        "",
-        "## Harness engeneering loop",
-        "",
-        "- Constrain: policy + workflow contract first.",
-        "- Execute: small explicit transitions.",
-        "- Observe: structured artifacts and diagnostics.",
-        "- Recover: deterministic fallback before manual repair.",
-        "",
-        "## Branch workflow (branch_pr)",
-        "",
-        "- `agentplane work start <task-id> --agent <ROLE> --slug <slug> --worktree`",
-        "- `agentplane pr open <task-id>` / `agentplane pr update <task-id>` / `agentplane pr check <task-id>`",
-        "- `agentplane integrate <task-id> --branch task/<task-id>/<slug> --run-verify`",
-        "",
-        "## Workflow operations (core)",
-        "- `agentplane workflow debug`",
-        "- `agentplane workflow sync`",
-        "- `agentplane workflow land`",
-        "",
-        "## Recipes and scenarios (extensions)",
-        "",
-        "- `agentplane recipes list`",
-        "- `agentplane recipes list --tag <tag>`",
-        "- `agentplane recipes explain <id>`",
-        "- `agentplane scenario list`",
-        "- `agentplane scenario run <recipe:scenario>`",
-        "",
-        "## More guidance",
-        "",
-        `- \`${COMMAND_SNIPPETS.core.quickstart}\` and \`${COMMAND_SNIPPETS.core.role}\` show command guidance.`,
-        "",
-        "## Agent cheat sheet",
-        "",
-        ...renderCheatSheet(CHEAT_SHEET_ROWS),
-        "",
-        "## Config management",
-        "",
-        "- Show the current config: `agentplane config show`",
-        "- Set a value by dotted key: `agentplane config set workflow_mode branch_pr`",
-        '- Set JSON values (lists/objects): `agentplane config set tasks.verify.require_steps_for_primary \'["code","data","ops"]\'`',
+        `Canonical bootstrap doc: \`${AGENT_BOOTSTRAP_DOC_PATH}\`.`,
         "",
-        "## Role/phase command guide (when to use what)",
+        "## First screen",
         "",
-        "Use `agentplane role <ROLE>` to print a single block from this section.",
+        "Run preflight:",
         "",
-        ...renderRoleSection(),
+        ...renderQuickstartCommandBlock(BOOTSTRAP_PREFLIGHT_COMMANDS),
         "",
-        "## Global flags",
+        "Default direct route:",
         "",
-        "- `--root <path>`: treat <path> as project root",
-        "- `--output <text|json>`: force global CLI output mode (`json` is agent-oriented envelope mode)",
-        "- `--json-errors`: emit JSON-formatted errors",
-        "- `--help` / `-h`: show help",
-        "- `--version`: show version",
-        "- `--no-update-check`: skip checking npm for a newer CLI version",
+        `- Task setup: \`${BOOTSTRAP_TASK_PREP_COMMANDS[0]}\` -> \`${BOOTSTRAP_TASK_PREP_COMMANDS[1]}\` -> \`${BOOTSTRAP_TASK_PREP_COMMANDS[2]}\`.`,
+        `- Execution: \`${COMMAND_SNIPPETS.core.startTask}\` -> \`agentplane task verify-show <task-id>\` -> \`${COMMAND_SNIPPETS.core.verifyTask}\` -> \`${COMMAND_SNIPPETS.core.finishTask}\` with \`--result "..." \`.`,
+        "- In `direct`, `finish` creates the deterministic close commit by default.",
         "",
-        "Notes:",
-        "- `AGENTPLANE_OUTPUT=json` enables global JSON output mode for agent runtimes.",
-        "- `.env` at the repo root is loaded automatically (without overwriting existing environment variables).",
+        "## Go deeper",
         "",
-        "## Commit message format",
+        `- \`${COMMAND_SNIPPETS.core.role}\` for role-specific deltas and mode-specific ownership rules.`,
+        "- `agentplane help <command>` for flags, examples, and exceptional/manual flows.",
+        `- \`${AGENT_BOOTSTRAP_DOC_PATH}\` for the full startup path instead of repeating it on the first screen.`,
+        `- \`${CLI_REFERENCE_DOC_PATH}\` for the generated full command reference.`,
         "",
-        "Use: `<emoji> <suffix> <scope>: <summary>`.",
+        "## Non-default",
         "",
-        "Notes:",
-        "- `suffix` is the task ID segment after the last dash.",
-        "- When using comment-driven flags, the subject is auto-built as `<emoji> <suffix> <primary>: <status>` and only for major transitions (TODO->DOING, DOING->BLOCKED, BLOCKED->DOING, DOING->DONE).",
-        "- Comment-driven commit bodies are structured: `Task`, `Primary`, `Status`, `Comment`.",
+        "- `branch_pr`: use `agentplane help work start`, `agentplane help pr`, and `agentplane help integrate`.",
+        "- Recovery/mixed state: use `agentplane doctor`, `agentplane upgrade`, and `agentplane runtime explain`.",
+        "- Manual close or allowlist details belong in command-specific help, not on this first screen.",
     ].join("\n");
 }

package/dist/cli/command-snippets.d.ts

@@ -2,10 +2,10 @@ export declare const COMMAND_SNIPPETS: {
     readonly core: {
         readonly taskList: "agentplane task list";
         readonly taskShow: "agentplane task show <task-id>";
-        readonly taskNew: "agentplane task new --title \"...\" --description \"...\" --priority med --owner CODER --tag <tag>";
+        readonly taskNew: "agentplane task new --title \"...\" --description \"...\" --priority med --owner <ROLE> --tag <tag>";
         readonly startTask: "agentplane task start-ready <task-id> --author <ROLE> --body \"Start: ...\"";
         readonly verifyTask: "agentplane verify <task-id> --ok|--rework --by <ROLE> --note \"...\"";
-        readonly finishTask: "agentplane finish <task-id> --author <ROLE> --body \"Verified: ...\" --commit <git-rev> --close-commit";
+        readonly finishTask: "agentplane finish <task-id> --author <ROLE> --body \"Verified: ...\" --commit <git-rev>";
         readonly quickstart: "agentplane quickstart";
         readonly role: "agentplane role <ROLE>";
     };

package/dist/cli/command-snippets.js

@@ -2,10 +2,10 @@ export const COMMAND_SNIPPETS = {
     core: {
         taskList: "agentplane task list",
         taskShow: "agentplane task show <task-id>",
-        taskNew: 'agentplane task new --title "..." --description "..." --priority med --owner CODER --tag <tag>',
+        taskNew: 'agentplane task new --title "..." --description "..." --priority med --owner <ROLE> --tag <tag>',
         startTask: 'agentplane task start-ready <task-id> --author <ROLE> --body "Start: ..."',
         verifyTask: 'agentplane verify <task-id> --ok|--rework --by <ROLE> --note "..."',
-        finishTask: 'agentplane finish <task-id> --author <ROLE> --body "Verified: ..." --commit <git-rev> --close-commit',
+        finishTask: 'agentplane finish <task-id> --author <ROLE> --body "Verified: ..." --commit <git-rev>',
         quickstart: "agentplane quickstart",
         role: "agentplane role <ROLE>",
     },

package/dist/cli/run-cli/catalog.d.ts

@@ -0,0 +1,7 @@
+import { COMMANDS } from "./command-catalog.js";
+export type CatalogMatch = {
+    entry: (typeof COMMANDS)[number];
+    consumed: number;
+};
+export declare function matchCommandCatalog(tokens: readonly string[]): CatalogMatch | null;
+//# sourceMappingURL=catalog.d.ts.map

package/dist/cli/run-cli/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../../src/cli/run-cli/catalog.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAEhD,MAAM,MAAM,YAAY,GAAG;IAAE,KAAK,EAAE,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAElF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,YAAY,GAAG,IAAI,CAkBlF"}

package/dist/cli/run-cli/catalog.js

@@ -0,0 +1,22 @@
+import { COMMANDS } from "./command-catalog.js";
+export function matchCommandCatalog(tokens) {
+    let best = null;
+    for (const entry of COMMANDS) {
+        const id = entry.spec.id;
+        if (tokens.length < id.length)
+            continue;
+        let ok = true;
+        for (const [i, seg] of id.entries()) {
+            if (tokens[i] !== seg) {
+                ok = false;
+                break;
+            }
+        }
+        if (!ok)
+            continue;
+        if (!best || id.length > best.consumed) {
+            best = { entry, consumed: id.length };
+        }
+    }
+    return best;
+}

package/dist/cli/run-cli/command-catalog.d.ts

@@ -15,5 +15,5 @@ export type CommandEntry = {
     needsConfig: boolean;
     needsTaskContext: boolean;
 };
-export declare const COMMANDS: readonly [CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry];
+export declare const COMMANDS: readonly [CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry];
 //# sourceMappingURL=command-catalog.d.ts.map

package/dist/cli/run-cli/command-catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-catalog.d.ts","sourceRoot":"","sources":["../../../src/cli/run-cli/command-catalog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAkHvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AAC5E,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEzE,MAAM,MAAM,OAAO,GAAG;IACpB,MAAM,EAAE,CAAC,sBAAsB,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IACpE,kBAAkB,EAAE,CAAC,sBAAsB,EAAE,MAAM,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;IACjF,eAAe,EAAE,CAAC,sBAAsB,EAAE,MAAM,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;IAC3E,kBAAkB,EAAE,MAAM,SAAS,QAAQ,EAAE,CAAC;CAC/C,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC;IAC3B,IAAI,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC;IAC1D,YAAY,EAAE,OAAO,CAAC;IACtB,WAAW,EAAE,OAAO,CAAC;IACrB,gBAAgB,EAAE,OAAO,CAAC;CAC3B,CAAC;AAgBF,eAAO,MAAM,QAAQ,m4CA+hBuB,CAAC"}
+{"version":3,"file":"command-catalog.d.ts","sourceRoot":"","sources":["../../../src/cli/run-cli/command-catalog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAmHvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AAC5E,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEzE,MAAM,MAAM,OAAO,GAAG;IACpB,MAAM,EAAE,CAAC,sBAAsB,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IACpE,kBAAkB,EAAE,CAAC,sBAAsB,EAAE,MAAM,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;IACjF,eAAe,EAAE,CAAC,sBAAsB,EAAE,MAAM,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;IAC3E,kBAAkB,EAAE,MAAM,SAAS,QAAQ,EAAE,CAAC;CAC/C,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC;IAC3B,IAAI,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC;IAC1D,YAAY,EAAE,OAAO,CAAC;IACtB,WAAW,EAAE,OAAO,CAAC;IACrB,gBAAgB,EAAE,OAAO,CAAC;CAC3B,CAAC;AAgBF,eAAO,MAAM,QAAQ,+5CA6iBuB,CAAC"}

package/dist/cli/run-cli/command-catalog.js

@@ -67,6 +67,7 @@ import { workflowBuildSpec } from "../../commands/workflow-build.command.js";
 import { workflowRestoreSpec } from "../../commands/workflow-restore.command.js";
 import { workflowDebugSpec, workflowLandSpec, workflowSyncSpec, } from "../../commands/workflow-playbook.command.js";
 import { docsCliSpec } from "../../commands/docs/cli.command.js";
+import { runtimeExplainSpec, runtimeSpec } from "../../commands/runtime.command.js";
 import { hooksSpec } from "../../commands/hooks/hooks.command.js";
 import { hooksInstallSpec } from "../../commands/hooks/install.command.js";
 import { hooksUninstallSpec } from "../../commands/hooks/uninstall.command.js";
@@ -124,6 +125,16 @@ export const COMMANDS = [
         needsConfig: false,
         needsTaskContext: false,
     }),
+    entry(runtimeSpec, () => import("../../commands/runtime.command.js").then((m) => m.runRuntime), {
+        needsProject: false,
+        needsConfig: false,
+        needsTaskContext: false,
+    }),
+    entry(runtimeExplainSpec, () => import("../../commands/runtime.command.js").then((m) => m.runRuntimeExplain), {
+        needsProject: false,
+        needsConfig: false,
+        needsTaskContext: false,
+    }),
     entry(roleSpec, () => import("./commands/core.js").then((m) => m.runRole), {
         needsProject: false,
         needsConfig: false,

package/dist/cli/run-cli/commands/core.js

@@ -15,7 +15,7 @@ import { wrapCommand } from "./wrap-command.js";
 export const quickstartSpec = {
     id: ["quickstart"],
     group: "Core",
-    summary: "Print CLI quickstart and command cheat sheet.",
+    summary: "Print the canonical agent bootstrap path and startup guidance.",
     options: [
         {
             kind: "boolean",

package/dist/cli/run-cli/commands/init/write-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"write-config.d.ts","sourceRoot":"","sources":["../../../../../src/cli/run-cli/commands/init/write-config.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,cAAc,GAAG,UAAU,GAAG,YAAY,CAAC;IACpD,gBAAgB,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC5C,WAAW,EAAE;QACX,SAAS,EAAE,MAAM,CAAC;QAClB,cAAc,EAAE,MAAM,CAAC;QACvB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,yCAAyC,EAAE,MAAM,EAAE,CAAC;CACrD,CAAC;AAEF,wBAAsB,oBAAoB,CACxC,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,OAAO,GAAG,SAAS,GAC3B,OAAO,CAAC,IAAI,CAAC,CAOf;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,QAAQ,GAAG,WAAW,CAAC;IACjC,oBAAoB,EAAE,MAAM,CAAC;IAC7B,mBAAmB,EAAE,OAAO,CAAC;IAC7B,sBAAsB,EAAE,OAAO,CAAC;IAChC,qBAAqB,EAAE,OAAO,CAAC;IAC/B,SAAS,EAAE,mBAAmB,CAAC;CAChC,GAAG,OAAO,CAAC,IAAI,CAAC,CAyBhB;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,OAAO,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7B,WAAW,EAAE,MAAM,CAAC;CACrB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBhB"}
+{"version":3,"file":"write-config.d.ts","sourceRoot":"","sources":["../../../../../src/cli/run-cli/commands/init/write-config.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,cAAc,GAAG,UAAU,GAAG,YAAY,CAAC;IACpD,gBAAgB,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC5C,WAAW,EAAE;QACX,SAAS,EAAE,MAAM,CAAC;QAClB,cAAc,EAAE,MAAM,CAAC;QACvB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,yCAAyC,EAAE,MAAM,EAAE,CAAC;CACrD,CAAC;AAEF,wBAAsB,oBAAoB,CACxC,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,OAAO,GAAG,SAAS,GAC3B,OAAO,CAAC,IAAI,CAAC,CAOf;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,QAAQ,GAAG,WAAW,CAAC;IACjC,oBAAoB,EAAE,MAAM,CAAC;IAC7B,mBAAmB,EAAE,OAAO,CAAC;IAC7B,sBAAsB,EAAE,OAAO,CAAC;IAChC,qBAAqB,EAAE,OAAO,CAAC;IAC/B,SAAS,EAAE,mBAAmB,CAAC;CAChC,GAAG,OAAO,CAAC,IAAI,CAAC,CA0BhB;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,OAAO,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7B,WAAW,EAAE,MAAM,CAAC;CACrB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBhB"}

package/dist/cli/run-cli/commands/init/write-config.js

@@ -2,6 +2,7 @@ import { mkdir } from "node:fs/promises";
 import path from "node:path";
 import { defaultConfig, saveConfig, setByDottedKey } from "@agentplaneorg/core";
 import { writeJsonStableIfChanged } from "../../../../shared/write-if-changed.js";
+import { getVersion } from "../../../../meta/version.js";
 export async function ensureAgentplaneDirs(agentplaneDir, backend) {
     await mkdir(agentplaneDir, { recursive: true });
     await mkdir(path.join(agentplaneDir, "tasks"), { recursive: true });
@@ -21,6 +22,7 @@ export async function writeInitConfig(opts) {
     setByDottedKey(rawConfig, "agents.approvals.require_plan", String(opts.requirePlanApproval));
     setByDottedKey(rawConfig, "agents.approvals.require_network", String(opts.requireNetworkApproval));
     setByDottedKey(rawConfig, "agents.approvals.require_verify", String(opts.requireVerifyApproval));
+    setByDottedKey(rawConfig, "framework.cli.expected_version", getVersion());
     setByDottedKey(rawConfig, "execution", JSON.stringify(opts.execution));
     await saveConfig(opts.agentplaneDir, rawConfig);
 }

package/dist/cli/run-cli/commands/init.js

@@ -220,8 +220,8 @@ export const initSpec = {
             why: "Non-interactive setup with flexible defaults.",
         },
         {
-            cmd: "agentplane init --workflow direct --backend local --hooks true --require-plan-approval true --require-network-approval true --require-verify-approval true --yes",
-            why: "Non-interactive setup with explicit policy flags.",
+            cmd: "agentplane init --workflow direct --backend local --hooks true --require-network-approval true --yes",
+            why: "Non-interactive setup with profile defaults plus an explicit network-approval override.",
         },
         {
             cmd: "agentplane init --force --yes",
@@ -318,14 +318,11 @@ async function cmdInit(opts) {
     const isInteractive = process.stdin.isTTY && !flags.yes;
     if (!process.stdin.isTTY &&
         !flags.yes &&
-        (!flags.workflow ||
-            flags.requirePlanApproval === undefined ||
-            flags.requireNetworkApproval === undefined ||
-            flags.requireVerifyApproval === undefined)) {
+        (!flags.workflow || flags.requireNetworkApproval === undefined)) {
         throw usageError({
             spec: initSpec,
             command: "init",
-            message: "Non-interactive init requires --yes or explicit values for: --workflow, --require-plan-approval, --require-network-approval, --require-verify-approval.",
+            message: "Non-interactive init requires --yes or explicit values for: --workflow, --require-network-approval.",
         });
     }
     if (isInteractive) {
@@ -406,16 +403,10 @@ async function cmdInit(opts) {
             if (flags.strictUnsafeConfirm === undefined) {
                 strictUnsafeConfirm = await askYesNo("Require strict explicit confirmation for extra unsafe actions?", strictUnsafeConfirm);
             }
-            process.stdout.write(renderInitSection("Approvals", "Control whether plan/network/verification actions require explicit approval by default."));
-            if (flags.requirePlanApproval === undefined) {
-                requirePlanApproval = await askYesNo("Require plan approval before work starts?", requirePlanApproval);
-            }
+            process.stdout.write(renderInitSection("Network Approval", "Control whether network actions require explicit approval by default. Plan and verification approvals follow the selected setup profile unless you override them with explicit flags."));
             if (flags.requireNetworkApproval === undefined) {
                 requireNetworkApproval = await askYesNo("Require explicit approval for network actions?", requireNetworkApproval);
             }
-            if (flags.requireVerifyApproval === undefined) {
-                requireVerifyApproval = await askYesNo("Require explicit approval before recording verification?", requireVerifyApproval);
-            }
             process.stdout.write(renderInitSection("Recipes", "Optional: install recipe packs now (comma-separated IDs) or choose none."));
             if (!flags.recipes) {
                 process.stdout.write(`${renderBundledRecipesHint()}\n`);

package/dist/cli/run-cli/error-guidance.d.ts

@@ -0,0 +1,9 @@
+import type { CliError } from "../../shared/errors.js";
+export type NextAction = {
+    command: string;
+    reason: string;
+    reasonCode?: string;
+};
+export declare function writeError(err: CliError, jsonErrors: boolean): void;
+export declare function resolveAgentplaneHome(): string;
+//# sourceMappingURL=error-guidance.d.ts.map

package/dist/cli/run-cli/error-guidance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-guidance.d.ts","sourceRoot":"","sources":["../../../src/cli/run-cli/error-guidance.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAGvD,MAAM,MAAM,UAAU,GAAG;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AASF,wBAAgB,UAAU,CAAC,GAAG,EAAE,QAAQ,EAAE,UAAU,EAAE,OAAO,GAAG,IAAI,CA4CnE;AAID,wBAAgB,qBAAqB,IAAI,MAAM,CAI9C"}