agentplane 0.3.3 → 0.3.4

package/dist/cli/bootstrap-guide.js

@@ -1,5 +1,6 @@
 import { COMMAND_SNIPPETS } from "./command-snippets.js";
 export const AGENT_BOOTSTRAP_DOC_PATH = "docs/user/agent-bootstrap.generated.mdx";
+export const AGENT_BOOTSTRAP_RUNTIME_SURFACE = "agentplane quickstart";
 export const BOOTSTRAP_PREFLIGHT_COMMANDS = [
     "agentplane config show",
     "agentplane quickstart",
@@ -58,7 +59,7 @@ export const BOOTSTRAP_SECTIONS = [
     },
 ];
 export function renderBootstrapReferenceLine() {
-    return `Canonical bootstrap doc: \`${AGENT_BOOTSTRAP_DOC_PATH}\`.`;
+    return `Canonical installed startup surface: \`${AGENT_BOOTSTRAP_RUNTIME_SURFACE}\`.`;
 }
 export function renderBootstrapSectionLines(sections) {
     const lines = [];
@@ -91,7 +92,7 @@ export function renderBootstrapDoc() {
         "",
         "This page is generated from `packages/agentplane/src/cli/bootstrap-guide.ts`.",
         "",
-        "Use it as the single startup path for agents. `AGENTS.md`, `agentplane quickstart`, and `agentplane role <ROLE>` should point here instead of restating lifecycle prose.",
+        "This is the docs-site rendering of the CLI bootstrap model. Installed repositories should rely on `agentplane quickstart` and `agentplane role <ROLE>` instead of requiring this file to exist locally.",
         "",
         "## Copy-paste start block",
         "",

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

@@ -1,4 +1,17 @@
+export type RoleProfileGuide = {
+    filename?: string;
+    id?: string;
+    role?: string;
+    description?: string;
+    inputs?: readonly string[];
+    outputs?: readonly string[];
+    permissions?: readonly string[];
+    workflow?: readonly string[];
+};
 export declare function listRoles(): string[];
-export declare function renderRole(roleRaw: string): string | null;
+export declare function getRoleSupplementLines(roleRaw: string): string[] | null;
+export declare function renderRole(roleRaw: string, opts?: {
+    profile?: RoleProfileGuide | null;
+}): string | null;
 export declare function renderQuickstart(): string;
 //# sourceMappingURL=command-guide.d.ts.map

package/dist/cli/command-guide.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-guide.d.ts","sourceRoot":"","sources":["../../src/cli/command-guide.ts"],"names":[],"mappings":"AA4GA,wBAAgB,SAAS,IAAI,MAAM,EAAE,CAEpC;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOzD;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CAoCzC"}
+{"version":3,"file":"command-guide.d.ts","sourceRoot":"","sources":["../../src/cli/command-guide.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9B,CAAC;AAkGF,wBAAgB,SAAS,IAAI,MAAM,EAAE,CAEpC;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAMvE;AAMD,wBAAgB,UAAU,CACxB,OAAO,EAAE,MAAM,EACf,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAA;CAAO,GAC/C,MAAM,GAAG,IAAI,CA6Bf;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CAoCzC"}

package/dist/cli/command-guide.js

@@ -1,6 +1,6 @@
 import { COMMAND_SNIPPETS } from "./command-snippets.js";
-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";
+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, "```"];
 }
@@ -8,7 +8,7 @@ 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.",
         ],
@@ -16,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.",
@@ -25,7 +25,7 @@ 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 "..."`.',
@@ -36,7 +36,7 @@ const ROLE_GUIDES = [
     {
         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.`,
@@ -46,16 +46,16 @@ const ROLE_GUIDES = [
     {
         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.",
-            `- Treat \`${CLI_REFERENCE_DOC_PATH}\` as the deep reference surface; keep first-screen help intentionally shorter.`,
+            "- 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.",
         ],
@@ -63,7 +63,7 @@ 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`.",
@@ -72,7 +72,7 @@ const ROLE_GUIDES = [
     {
         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.",
         ],
@@ -80,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.",
         ],
@@ -88,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.",
         ],
     },
@@ -96,15 +96,46 @@ 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;
+    const normalized = trimmed.toUpperCase();
+    const supplementLines = getRoleSupplementLines(normalized);
+    const profile = opts.profile ?? null;
+    if (!supplementLines && !profile)
         return null;
-    return [`### ${guide.role}`, ...guide.lines].join("\n").trimEnd();
+    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 [
@@ -115,7 +146,7 @@ export function renderQuickstart() {
         "Do not edit `.agentplane/tasks.json` by hand.",
         "If the repository is not initialized yet, stop and run `agentplane init` first.",
         "",
-        `Canonical bootstrap doc: \`${AGENT_BOOTSTRAP_DOC_PATH}\`.`,
+        `Canonical installed startup surface: \`${COMMAND_SNIPPETS.core.quickstart}\`.`,
         "",
         "## First screen",
         "",
@@ -133,8 +164,8 @@ export function renderQuickstart() {
         "",
         `- \`${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.`,
+        "- 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.",
         "",
         "## Non-default",
         "",

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-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/commands/upgrade.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"upgrade.d.ts","sourceRoot":"","sources":["../../src/commands/upgrade.ts"],"names":[],"mappings":"AA2CA,MAAM,MAAM,YAAY,GAAG;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC;IACvB,MAAM,EAAE,OAAO,CAAC;IAChB,YAAY,EAAE,OAAO,CAAC;IACtB,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,GAAG,EAAE,OAAO,CAAC;CACd,CAAC;AAuMF,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,YAAY,CAAC;CACrB,GAAG,OAAO,CAAC,MAAM,CAAC,CA4gBlB;AAED,OAAO,EACL,kCAAkC,EAClC,qBAAqB,EACrB,iCAAiC,GAClC,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"upgrade.d.ts","sourceRoot":"","sources":["../../src/commands/upgrade.ts"],"names":[],"mappings":"AA4CA,MAAM,MAAM,YAAY,GAAG;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC;IACvB,MAAM,EAAE,OAAO,CAAC;IAChB,YAAY,EAAE,OAAO,CAAC;IACtB,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,GAAG,EAAE,OAAO,CAAC;CACd,CAAC;AAuMF,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,YAAY,CAAC;CACrB,GAAG,OAAO,CAAC,MAAM,CAAC,CAsiBlB;AAED,OAAO,EACL,kCAAkC,EAClC,qBAAqB,EACrB,iCAAiC,GAClC,MAAM,qBAAqB,CAAC"}

package/dist/commands/upgrade.js

@@ -10,6 +10,7 @@ import { extractArchive } from "../cli/archive.js";
 import { exitCodeForError } from "../cli/exit-codes.js";
 import { warnMessage } from "../cli/output.js";
 import { CliError } from "../shared/errors.js";
+import { ensureWorkflowArtifacts } from "../shared/workflow-artifacts.js";
 import { ensureNetworkApproved } from "./shared/network-approval.js";
 import { getVersion } from "../meta/version.js";
 import { applyManagedFiles, cleanupAutoUpgradeArtifacts, createUpgradeCommit, ensureCleanTrackedTreeForUpgrade, persistUpgradeState, } from "./upgrade/apply.js";
@@ -638,8 +639,25 @@ export async function cmdUpgradeParsed(opts) {
             updates: updates.length,
             skipped: skipped.length,
         });
+        const orchestratorProfilePath = path.join(resolved.agentplaneDir, "agents", "ORCHESTRATOR.json");
+        const workflowArtifacts = (await fileExists(orchestratorProfilePath))
+            ? await ensureWorkflowArtifacts({
+                gitRoot: resolved.gitRoot,
+                workflowMode: loaded.config.workflow_mode,
+                approvals: {
+                    requirePlanApproval: loaded.config.agents?.approvals?.require_plan ?? true,
+                    requireVerifyApproval: loaded.config.agents?.approvals?.require_verify ?? true,
+                    requireNetworkApproval: loaded.config.agents?.approvals?.require_network ?? true,
+                },
+            })
+            : { installPaths: [], commitPaths: [], changedPaths: [] };
         const commitPaths = [
-            ...new Set([...additions, ...updates, ...(shouldMutateConfig ? [CONFIG_REL_PATH] : [])]),
+            ...new Set([
+                ...additions,
+                ...updates,
+                ...workflowArtifacts.commitPaths,
+                ...(shouldMutateConfig ? [CONFIG_REL_PATH] : []),
+            ]),
         ];
         const commit = await createUpgradeCommit({
             gitRoot: resolved.gitRoot,
@@ -653,6 +671,9 @@ export async function cmdUpgradeParsed(opts) {
         });
         await cleanupAutoUpgradeArtifacts({ upgradeStateDir, createdBackups });
         process.stdout.write(`Upgrade applied: ${additions.length} add, ${updates.length} update, ${skipped.length} unchanged\n`);
+        if (workflowArtifacts.changedPaths.length > 0) {
+            process.stdout.write(`Workflow artifacts refreshed: ${workflowArtifacts.commitPaths.join(", ")}\n`);
+        }
         if (commit) {
             process.stdout.write(`Upgrade commit: ${commit.hash.slice(0, 12)} ${commit.subject}\n`);
         }

package/dist/commands/workflow-build.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workflow-build.command.d.ts","sourceRoot":"","sources":["../../src/commands/workflow-build.command.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAWvE,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,mBAAmB,CAgC9D,CAAC;AAWF,eAAO,MAAM,gBAAgB,EAAE,cAAc,CAAC,mBAAmB,CA2EhE,CAAC"}
+{"version":3,"file":"workflow-build.command.d.ts","sourceRoot":"","sources":["../../src/commands/workflow-build.command.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAYvE,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,mBAAmB,CAgC9D,CAAC;AAWF,eAAO,MAAM,gBAAgB,EAAE,cAAc,CAAC,mBAAmB,CAoEhE,CAAC"}

package/dist/commands/workflow-build.command.js

@@ -2,6 +2,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { loadConfig, resolveProject } from "@agentplaneorg/core";
 import { successMessage, warnMessage } from "../cli/output.js";
+import { buildWorkflowRuntimeContext } from "../shared/workflow-artifacts.js";
 import { DEFAULT_WORKFLOW_TEMPLATE, buildWorkflowFromTemplates, diagnosticsSummary, publishWorkflowCandidate, resolveWorkflowPaths, validateWorkflowText, } from "../workflow-runtime/index.js";
 export const workflowBuildSpec = {
     id: ["workflow", "build"],
@@ -50,22 +51,15 @@ export const runWorkflowBuild = async (ctx, flags) => {
     const configLoaded = await loadConfig(resolved.agentplaneDir);
     const workflowPaths = resolveWorkflowPaths(resolved.gitRoot);
     const configApprovals = configLoaded.config.agents?.approvals;
-    const runtimeContext = {
-        workflow: {
-            mode: configLoaded.config.workflow_mode,
-            version: 1,
-            approvals: {
-                require_plan: configApprovals?.require_plan ?? true,
-                require_verify: configApprovals?.require_verify ?? true,
-                require_network: configApprovals?.require_network ?? true,
-            },
+    const runtimeContext = buildWorkflowRuntimeContext({
+        gitRoot: resolved.gitRoot,
+        workflowMode: configLoaded.config.workflow_mode,
+        approvals: {
+            requirePlanApproval: configApprovals?.require_plan ?? true,
+            requireVerifyApproval: configApprovals?.require_verify ?? true,
+            requireNetworkApproval: configApprovals?.require_network ?? true,
         },
-        runtime: {
-            repo_name: path.basename(resolved.gitRoot),
-            repo_root: resolved.gitRoot,
-            timestamp: new Date().toISOString(),
-        },
-    };
+    });
     const overrideTemplate = await maybeReadOverride(workflowPaths);
     const built = buildWorkflowFromTemplates({
         baseTemplate: DEFAULT_WORKFLOW_TEMPLATE,

package/dist/shared/workflow-artifacts.d.ts

@@ -0,0 +1,37 @@
+export type WorkflowArtifactApprovals = {
+    requirePlanApproval: boolean;
+    requireVerifyApproval: boolean;
+    requireNetworkApproval: boolean;
+};
+export declare function buildWorkflowRuntimeContext(opts: {
+    gitRoot: string;
+    workflowMode: "direct" | "branch_pr";
+    approvals: WorkflowArtifactApprovals;
+    timestamp?: string;
+}): {
+    workflow: {
+        mode: "direct" | "branch_pr";
+        version: number;
+        approvals: {
+            require_plan: boolean;
+            require_verify: boolean;
+            require_network: boolean;
+        };
+    };
+    runtime: {
+        repo_name: string;
+        repo_root: string;
+        timestamp: string;
+    };
+};
+export declare function ensureWorkflowArtifacts(opts: {
+    gitRoot: string;
+    workflowMode: "direct" | "branch_pr";
+    approvals: WorkflowArtifactApprovals;
+    projectOverrideTemplate?: string;
+}): Promise<{
+    installPaths: string[];
+    commitPaths: string[];
+    changedPaths: string[];
+}>;
+//# sourceMappingURL=workflow-artifacts.d.ts.map

package/dist/shared/workflow-artifacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-artifacts.d.ts","sourceRoot":"","sources":["../../src/shared/workflow-artifacts.ts"],"names":[],"mappings":"AAYA,MAAM,MAAM,yBAAyB,GAAG;IACtC,mBAAmB,EAAE,OAAO,CAAC;IAC7B,qBAAqB,EAAE,OAAO,CAAC;IAC/B,sBAAsB,EAAE,OAAO,CAAC;CACjC,CAAC;AAEF,wBAAgB,2BAA2B,CAAC,IAAI,EAAE;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,QAAQ,GAAG,WAAW,CAAC;IACrC,SAAS,EAAE,yBAAyB,CAAC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;;;;;;;;;;;;;;;EAiBA;AAUD,wBAAsB,uBAAuB,CAAC,IAAI,EAAE;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,QAAQ,GAAG,WAAW,CAAC;IACrC,SAAS,EAAE,yBAAyB,CAAC;IACrC,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC,GAAG,OAAO,CAAC;IAAE,YAAY,EAAE,MAAM,EAAE,CAAC;IAAC,WAAW,EAAE,MAAM,EAAE,CAAC;IAAC,YAAY,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAwErF"}