agentplane 0.3.2 → 0.3.4

package/dist/cli/command-guide.js

@@ -1,23 +1,14 @@
 import { COMMAND_SNIPPETS } from "./command-snippets.js";
-import { AGENT_BOOTSTRAP_DOC_PATH, BOOTSTRAP_SECTIONS, renderBootstrapReferenceLine, } from "./bootstrap-guide.js";
-function renderBootstrapOverview() {
-    const lines = [];
-    for (const section of BOOTSTRAP_SECTIONS) {
-        lines.push(`## ${section.heading}`, "", section.summary, "");
-        for (const command of section.commands) {
-            lines.push(`- \`${command}\``);
-        }
-        lines.push("");
-    }
-    if (lines.at(-1) === "")
-        lines.pop();
-    return lines;
+import { BOOTSTRAP_PREFLIGHT_COMMANDS, BOOTSTRAP_TASK_PREP_COMMANDS } from "./bootstrap-guide.js";
+const SHARED_STARTUP_NOTE = `- Shared startup path: \`${COMMAND_SNIPPETS.core.quickstart}\` is the canonical installed bootstrap; use \`${COMMAND_SNIPPETS.core.role}\` only for role-specific deltas.`;
+function renderQuickstartCommandBlock(commands) {
+    return ["```bash", ...commands, "```"];
 }
 const ROLE_GUIDES = [
     {
         role: "ORCHESTRATOR",
         lines: [
-            `- Shared bootstrap path: \`${COMMAND_SNIPPETS.core.quickstart}\` -> \`${AGENT_BOOTSTRAP_DOC_PATH}\`.`,
+            SHARED_STARTUP_NOTE,
             "- Owns preflight, plan summaries, approvals, and scope checkpoints.",
             "- Does not create non-executable tasks or bypass lifecycle guardrails.",
         ],
@@ -25,7 +16,7 @@ const ROLE_GUIDES = [
     {
         role: "PLANNER",
         lines: [
-            `- Shared bootstrap path: \`${COMMAND_SNIPPETS.core.quickstart}\` -> \`${AGENT_BOOTSTRAP_DOC_PATH}\`.`,
+            SHARED_STARTUP_NOTE,
             '- 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.",
@@ -34,34 +25,37 @@ const ROLE_GUIDES = [
     {
         role: "CODER",
         lines: [
-            `- Shared bootstrap path: \`${COMMAND_SNIPPETS.core.quickstart}\` -> \`${AGENT_BOOTSTRAP_DOC_PATH}\`.`,
+            SHARED_STARTUP_NOTE,
             "- 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: [
-            `- Shared bootstrap path: \`${COMMAND_SNIPPETS.core.quickstart}\` -> \`${AGENT_BOOTSTRAP_DOC_PATH}\`.`,
+            SHARED_STARTUP_NOTE,
             "- 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: [
-            `- Shared bootstrap path: \`${COMMAND_SNIPPETS.core.quickstart}\` -> \`${AGENT_BOOTSTRAP_DOC_PATH}\`.`,
+            SHARED_STARTUP_NOTE,
             '- 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.",
+            "- The docs site may expand CLI behavior, but installed runtime guidance must stay self-contained and must not depend on repo-only docs paths.",
         ],
     },
     {
         role: "REVIEWER",
         lines: [
-            `- Shared bootstrap path: \`${COMMAND_SNIPPETS.core.quickstart}\` -> \`${AGENT_BOOTSTRAP_DOC_PATH}\`.`,
+            SHARED_STARTUP_NOTE,
             "- 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.",
         ],
@@ -69,15 +63,16 @@ const ROLE_GUIDES = [
     {
         role: "INTEGRATOR",
         lines: [
-            `- Shared bootstrap path: \`${COMMAND_SNIPPETS.core.quickstart}\` -> \`${AGENT_BOOTSTRAP_DOC_PATH}\`.`,
+            SHARED_STARTUP_NOTE,
             '- 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: [
-            `- Shared bootstrap path: \`${COMMAND_SNIPPETS.core.quickstart}\` -> \`${AGENT_BOOTSTRAP_DOC_PATH}\`.`,
+            SHARED_STARTUP_NOTE,
             `- 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.",
         ],
@@ -85,7 +80,7 @@ const ROLE_GUIDES = [
     {
         role: "REDMINE",
         lines: [
-            `- Shared bootstrap path: \`${COMMAND_SNIPPETS.core.quickstart}\` -> \`${AGENT_BOOTSTRAP_DOC_PATH}\`.`,
+            SHARED_STARTUP_NOTE,
             `- Sync explicitly with \`${COMMAND_SNIPPETS.sync.pullRedmineExplicit}\` / \`${COMMAND_SNIPPETS.sync.pushRedmineExplicitWithYes}\`.`,
             "- After sync, follow the same task/bootstrap lifecycle as local backends.",
         ],
@@ -93,7 +88,7 @@ const ROLE_GUIDES = [
     {
         role: "UPDATER",
         lines: [
-            `- Shared bootstrap path: \`${COMMAND_SNIPPETS.core.quickstart}\` -> \`${AGENT_BOOTSTRAP_DOC_PATH}\`.`,
+            SHARED_STARTUP_NOTE,
             "- Read-only role: inspect state, do not mutate task or workflow artifacts.",
         ],
     },
@@ -101,52 +96,81 @@ const ROLE_GUIDES = [
 export function listRoles() {
     return ROLE_GUIDES.map((guide) => guide.role);
 }
-export function renderRole(roleRaw) {
+export function getRoleSupplementLines(roleRaw) {
     const trimmed = roleRaw.trim();
     if (!trimmed)
         return null;
     const normalized = trimmed.toUpperCase();
     const guide = ROLE_GUIDES.find((entry) => entry.role.toUpperCase() === normalized);
-    if (!guide)
+    return guide ? guide.lines : null;
+}
+function renderRoleList(title, items) {
+    return items && items.length > 0 ? ["", `${title}:`, ...items.map((item) => `- ${item}`)] : [];
+}
+export function renderRole(roleRaw, opts = {}) {
+    const trimmed = roleRaw.trim();
+    if (!trimmed)
         return null;
-    return [`### ${guide.role}`, ...guide.lines].join("\n").trimEnd();
+    const normalized = trimmed.toUpperCase();
+    const supplementLines = getRoleSupplementLines(normalized);
+    const profile = opts.profile ?? null;
+    if (!supplementLines && !profile)
+        return null;
+    const heading = (typeof profile?.id === "string" && profile.id.trim()) || normalized;
+    const role = typeof profile?.role === "string" ? profile.role.trim() : "";
+    const description = typeof profile?.description === "string" ? profile.description.trim() : "";
+    const lines = [
+        `### ${heading}`,
+        ...(role ? [`Role: ${role}`] : []),
+        ...(description ? [`Description: ${description}`] : []),
+        ...renderRoleList("Inputs", profile?.inputs),
+        ...renderRoleList("Outputs", profile?.outputs),
+        ...renderRoleList("Permissions", profile?.permissions),
+        ...renderRoleList("Workflow", profile?.workflow),
+        ...(supplementLines ? ["", "CLI/runtime notes:", ...supplementLines] : []),
+        ...(profile?.filename
+            ? [
+                "",
+                `Source: .agentplane/agents/${profile.filename} (role-specific content); policy gateway files still have higher priority.`,
+            ]
+            : []),
+    ];
+    return lines.join("\n").trimEnd();
 }
 export function renderQuickstart() {
     return [
         "# agentplane quickstart",
         "",
-        "The policy gateway file (AGENTS.md or CLAUDE.md) is the source of truth for workflow/process policy. CLI syntax lives in quickstart and `agentplane role <ROLE>`.",
+        "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.",
         "",
-        renderBootstrapReferenceLine(),
-        "",
-        ...renderBootstrapOverview(),
+        `Canonical installed startup surface: \`${COMMAND_SNIPPETS.core.quickstart}\`.`,
         "",
-        "## Role-specific deltas",
+        "## First screen",
         "",
-        `- Use \`${COMMAND_SNIPPETS.core.role}\` for role-specific constraints after you understand the shared bootstrap path.`,
-        "- Role output should add deltas, not replace the canonical bootstrap flow.",
+        "Run preflight:",
         "",
-        "## Branch workflow extras",
+        ...renderQuickstartCommandBlock(BOOTSTRAP_PREFLIGHT_COMMANDS),
         "",
-        "- `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`",
+        "Default direct route:",
         "",
-        "## More guidance",
+        `- 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.",
         "",
-        "- `agentplane help <command>` for command-level flags and examples.",
-        `- \`${COMMAND_SNIPPETS.core.role}\` for role-specific deltas.`,
-        `- \`${AGENT_BOOTSTRAP_DOC_PATH}\` for the canonical startup path in repository docs.`,
+        "## 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.",
+        "- Keep installed runtime guidance self-contained; do not depend on repo-only docs files.",
+        "- If you need the docs site, treat it as a public reference surface rather than a required local file.",
         "",
-        "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/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.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../../../src/cli/run-cli/commands/core.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAOtE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAIrD,KAAK,gBAAgB,GAAG;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAE1C,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,gBAAgB,CAcxD,CAAC;AA6BF,eAAO,MAAM,aAAa,EAAE,cAAc,CAAC,gBAAgB,CAE1D,CAAC;AAEF,KAAK,aAAa,GAAG,OAAO,GAAG,MAAM,CAAC;AACtC,KAAK,eAAe,GAAG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,aAAa,CAAA;CAAE,CAAC;AAkP9D,eAAO,MAAM,aAAa,EAAE,WAAW,CAAC,eAAe,CAuCtD,CAAC;AAiDF,eAAO,MAAM,YAAY,EAAE,cAAc,CAAC,eAAe,CAExD,CAAC;AAEF,KAAK,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAElD,eAAO,MAAM,QAAQ,EAAE,WAAW,CAAC,UAAU,CAe5C,CAAC;AAoOF,eAAO,MAAM,OAAO,EAAE,cAAc,CAAC,UAAU,CAE9C,CAAC;AAEF,KAAK,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAE1C,eAAO,MAAM,UAAU,EAAE,WAAW,CAAC,YAAY,CAMhD,CAAC;AAEF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAAC,YAAY,CAAC,CA0FhF"}
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../../../src/cli/run-cli/commands/core.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAatE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAIrD,KAAK,gBAAgB,GAAG;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAE1C,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,gBAAgB,CAcxD,CAAC;AA6BF,eAAO,MAAM,aAAa,EAAE,cAAc,CAAC,gBAAgB,CAE1D,CAAC;AAEF,KAAK,aAAa,GAAG,OAAO,GAAG,MAAM,CAAC;AACtC,KAAK,eAAe,GAAG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,aAAa,CAAA;CAAE,CAAC;AAkP9D,eAAO,MAAM,aAAa,EAAE,WAAW,CAAC,eAAe,CAuCtD,CAAC;AAiDF,eAAO,MAAM,YAAY,EAAE,cAAc,CAAC,eAAe,CAExD,CAAC;AAEF,KAAK,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAElD,eAAO,MAAM,QAAQ,EAAE,WAAW,CAAC,UAAU,CAe5C,CAAC;AA4OF,eAAO,MAAM,OAAO,EAAE,cAAc,CAAC,UAAU,CAE9C,CAAC;AAEF,KAAK,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAE1C,eAAO,MAAM,UAAU,EAAE,WAAW,CAAC,YAAY,CAMhD,CAAC;AAEF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAAC,YAAY,CAAC,CA0FhF"}

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

@@ -8,7 +8,7 @@ import { fileExists } from "../../fs-utils.js";
 import { CliError } from "../../../shared/errors.js";
 import { dedupeStrings } from "../../../shared/strings.js";
 import { usageError } from "../../spec/errors.js";
-import { listRoles, renderQuickstart, renderRole } from "../../command-guide.js";
+import { getRoleSupplementLines, listRoles, renderQuickstart, renderRole, } from "../../command-guide.js";
 import { isWorkflowEnforcementDisabled, validateWorkflowAtPath, workflowEnforcementEnvHint, } from "../../../workflow-runtime/index.js";
 import { toStringList } from "../../spec/parse-utils.js";
 import { wrapCommand } from "./wrap-command.js";
@@ -420,7 +420,7 @@ async function readAgentProfile(opts) {
     const raw = parseAgentProfileJson(filePath, await readFile(filePath, "utf8"));
     return { agentplaneDir: listing.agentplaneDir, filename, profile: raw };
 }
-function renderAgentProfileBlock(opts) {
+function toRoleProfileGuide(opts) {
     const id = (typeof opts.profile.id === "string" ? opts.profile.id : "").trim() || opts.roleId;
     const role = (typeof opts.profile.role === "string" ? opts.profile.role : "").trim();
     const description = (typeof opts.profile.description === "string" ? opts.profile.description : "").trim();
@@ -428,18 +428,16 @@ function renderAgentProfileBlock(opts) {
     const outputs = toStringList(opts.profile.outputs);
     const permissions = toStringList(opts.profile.permissions);
     const workflow = toStringList(opts.profile.workflow);
-    const lines = [
-        `### ${id}`,
-        ...(role ? [`Role: ${role}`] : []),
-        ...(description ? [`Description: ${description}`] : []),
-        ...(inputs.length > 0 ? ["", "Inputs:", ...inputs.map((s) => `- ${s}`)] : []),
-        ...(outputs.length > 0 ? ["", "Outputs:", ...outputs.map((s) => `- ${s}`)] : []),
-        ...(permissions.length > 0 ? ["", "Permissions:", ...permissions.map((s) => `- ${s}`)] : []),
-        ...(workflow.length > 0 ? ["", "Workflow:", ...workflow.map((s) => `- ${s}`)] : []),
-        "",
-        `Source: .agentplane/agents/${opts.filename} (lower priority; see policy gateway file AGENTS.md or CLAUDE.md)`,
-    ];
-    return lines.join("\n").trimEnd();
+    return {
+        filename: opts.filename,
+        id,
+        role,
+        description,
+        inputs,
+        outputs,
+        permissions,
+        workflow,
+    };
 }
 async function cmdRole(opts) {
     return wrapCommand({ command: "role", rootOverride: opts.rootOverride }, async () => {
@@ -452,12 +450,19 @@ async function cmdRole(opts) {
             });
         }
         const normalizedRole = normalizeRoleId(roleRaw);
-        const guide = renderRole(normalizedRole);
         const agentProfile = await readAgentProfile({
             cwd: opts.cwd,
             rootOverride: opts.rootOverride,
             roleId: normalizedRole,
         });
+        const normalizedProfile = agentProfile
+            ? toRoleProfileGuide({
+                filename: agentProfile.filename,
+                roleId: normalizedRole,
+                profile: agentProfile.profile,
+            })
+            : null;
+        const guide = renderRole(normalizedRole, { profile: normalizedProfile });
         if (!guide && !agentProfile) {
             const builtin = listRoles();
             const agentIds = await listAgentProfileIds({
@@ -477,11 +482,15 @@ async function cmdRole(opts) {
             if (opts.json) {
                 const payload = {
                     role: normalizedRole,
-                    builtin_guide: guide
+                    guide: guide
                         .split("\n")
                         .map((line) => line.trim())
                         .filter((line) => line.length > 0),
                 };
+                const supplementLines = getRoleSupplementLines(normalizedRole);
+                if (supplementLines) {
+                    payload.builtin_guide = supplementLines;
+                }
                 if (agentProfile) {
                     payload.agent_profile = {
                         filename: agentProfile.filename,
@@ -492,14 +501,6 @@ async function cmdRole(opts) {
                 return 0;
             }
             process.stdout.write(`${guide}\n`);
-            if (agentProfile) {
-                const block = renderAgentProfileBlock({
-                    filename: agentProfile.filename,
-                    roleId: normalizedRole,
-                    profile: agentProfile.profile,
-                });
-                process.stdout.write(`\n## Agent profile\n\n${block}\n`);
-            }
             return 0;
         }
         if (!agentProfile) {
@@ -510,14 +511,21 @@ async function cmdRole(opts) {
                 message: `Unknown role: ${roleRaw}.`,
             });
         }
-        const block = renderAgentProfileBlock({
-            filename: agentProfile.filename,
-            roleId: normalizedRole,
-            profile: agentProfile.profile,
-        });
+        const block = renderRole(normalizedRole, { profile: normalizedProfile });
+        if (!block) {
+            throw usageError({
+                spec: roleSpec,
+                command: "role",
+                message: `Unknown role: ${roleRaw}.`,
+            });
+        }
         if (opts.json) {
             process.stdout.write(`${JSON.stringify({
                 role: normalizedRole,
+                guide: block
+                    .split("\n")
+                    .map((line) => line.trim())
+                    .filter((line) => line.length > 0),
                 agent_profile: {
                     filename: agentProfile.filename,
                     profile: agentProfile.profile,

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/write-workflow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"write-workflow.d.ts","sourceRoot":"","sources":["../../../../../src/cli/run-cli/commands/init/write-workflow.ts"],"names":[],"mappings":"AASA,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,QAAQ,GAAG,WAAW,CAAC;IACrC,SAAS,EAAE;QACT,mBAAmB,EAAE,OAAO,CAAC;QAC7B,qBAAqB,EAAE,OAAO,CAAC;QAC/B,sBAAsB,EAAE,OAAO,CAAC;KACjC,CAAC;CACH,GAAG,OAAO,CAAC;IAAE,YAAY,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CA2DtC"}
+{"version":3,"file":"write-workflow.d.ts","sourceRoot":"","sources":["../../../../../src/cli/run-cli/commands/init/write-workflow.ts"],"names":[],"mappings":"AAEA,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,QAAQ,GAAG,WAAW,CAAC;IACrC,SAAS,EAAE;QACT,mBAAmB,EAAE,OAAO,CAAC;QAC7B,qBAAqB,EAAE,OAAO,CAAC;QAC/B,sBAAsB,EAAE,OAAO,CAAC;KACjC,CAAC;CACH,GAAG,OAAO,CAAC;IAAE,YAAY,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAOtC"}

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

@@ -1,58 +1,9 @@
-import { CliError } from "../../../../shared/errors.js";
-import { DEFAULT_WORKFLOW_TEMPLATE, buildWorkflowFromTemplates, diagnosticsSummary, publishWorkflowCandidate, resolveWorkflowPaths, } from "../../../../workflow-runtime/index.js";
+import { ensureWorkflowArtifacts } from "../../../../shared/workflow-artifacts.js";
 export async function ensureInitWorkflow(opts) {
-    const built = buildWorkflowFromTemplates({
-        baseTemplate: DEFAULT_WORKFLOW_TEMPLATE,
-        runtimeContext: {
-            workflow: {
-                mode: opts.workflowMode,
-                version: 1,
-                approvals: {
-                    require_plan: opts.approvals.requirePlanApproval,
-                    require_verify: opts.approvals.requireVerifyApproval,
-                    require_network: opts.approvals.requireNetworkApproval,
-                },
-            },
-            runtime: {
-                repo_name: opts.gitRoot.split(/[/\\\\]/).findLast((segment) => segment.length > 0) ?? "repo",
-                repo_root: opts.gitRoot,
-                timestamp: new Date().toISOString(),
-            },
-        },
+    const ensured = await ensureWorkflowArtifacts({
+        gitRoot: opts.gitRoot,
+        workflowMode: opts.workflowMode,
+        approvals: opts.approvals,
     });
-    if (built.diagnostics.some((d) => d.severity === "ERROR")) {
-        throw new CliError({
-            exitCode: 3,
-            code: "E_VALIDATION",
-            message: `Failed to generate WORKFLOW.md: ${diagnosticsSummary(built.diagnostics)}`,
-            context: {
-                diagnostics: built.diagnostics.map((d) => ({
-                    severity: d.severity,
-                    code: d.code,
-                    path: d.path,
-                    message: d.message,
-                })),
-            },
-        });
-    }
-    const published = await publishWorkflowCandidate(opts.gitRoot, built.text);
-    if (!published.ok) {
-        throw new CliError({
-            exitCode: 3,
-            code: "E_VALIDATION",
-            message: `Failed to publish WORKFLOW.md: ${diagnosticsSummary(published.diagnostics)}`,
-            context: {
-                diagnostics: published.diagnostics.map((d) => ({
-                    severity: d.severity,
-                    code: d.code,
-                    path: d.path,
-                    message: d.message,
-                })),
-            },
-        });
-    }
-    const workflowPaths = resolveWorkflowPaths(opts.gitRoot);
-    return {
-        installPaths: [workflowPaths.workflowPath, workflowPaths.lastKnownGoodPath],
-    };
+    return { installPaths: ensured.installPaths };
 }

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"}