agentplane 0.2.26 → 0.3.2

package/dist/cli/bootstrap-guide.js

@@ -0,0 +1,132 @@
+import { COMMAND_SNIPPETS } from "./command-snippets.js";
+export const AGENT_BOOTSTRAP_DOC_PATH = "docs/user/agent-bootstrap.generated.mdx";
+export const BOOTSTRAP_PREFLIGHT_COMMANDS = [
+    "agentplane config show",
+    "agentplane quickstart",
+    "agentplane task list",
+    "git status --short --untracked-files=no",
+    "git rev-parse --abbrev-ref HEAD",
+];
+export const BOOTSTRAP_TASK_PREP_COMMANDS = [
+    COMMAND_SNIPPETS.core.taskNew,
+    'agentplane task plan set <task-id> --text "..." --updated-by <ROLE>',
+    "agentplane task plan approve <task-id> --by ORCHESTRATOR",
+];
+export const BOOTSTRAP_TASK_LIFECYCLE_COMMANDS = [
+    ...BOOTSTRAP_TASK_PREP_COMMANDS,
+    COMMAND_SNIPPETS.core.startTask,
+    COMMAND_SNIPPETS.core.verifyTask,
+    'agentplane finish <task-id> --author <ROLE> --body "Verified: ..." --result "..." --commit <git-rev>',
+];
+export const BOOTSTRAP_VERIFY_AND_FINISH_COMMANDS = [
+    "agentplane task verify-show <task-id>",
+    COMMAND_SNIPPETS.core.verifyTask,
+    'agentplane finish <task-id> --author <ROLE> --body "Verified: ..." --result "..." --commit <git-rev>',
+];
+export const BOOTSTRAP_VERIFICATION_COMMANDS = [
+    "agentplane task verify-show <task-id>",
+    COMMAND_SNIPPETS.core.verifyTask,
+    "agentplane doctor",
+    "node .agentplane/policy/check-routing.mjs",
+];
+export const BOOTSTRAP_RECOVERY_COMMANDS = [
+    "agentplane doctor",
+    "agentplane upgrade --dry-run",
+    "agentplane upgrade",
+];
+export const BOOTSTRAP_SECTIONS = [
+    {
+        heading: "1. Preflight",
+        summary: "Establish workflow mode, current branch, current task state, and tracked working-tree state.",
+        commands: BOOTSTRAP_PREFLIGHT_COMMANDS,
+        notes: [
+            "Run this before any mutation.",
+            "If the project is not initialized, stop and use `agentplane init` first.",
+        ],
+    },
+    {
+        heading: "2. Prepare executable task scope",
+        summary: "Work only through executable task ids. Create the task, fill plan/docs, then approve the plan.",
+        commands: BOOTSTRAP_TASK_PREP_COMMANDS,
+        notes: [
+            "Use `task doc set` to fill required README sections before approval.",
+            "For dependent tasks, wait until upstream tasks are DONE before `task start-ready`.",
+        ],
+    },
+    {
+        heading: "3. Start work deterministically",
+        summary: "Move the task to DOING only after plan approval succeeds.",
+        commands: [COMMAND_SNIPPETS.core.startTask],
+        notes: ["`task plan approve` and `task start-ready` must run sequentially, never in parallel."],
+    },
+    {
+        heading: "4. Verify and finish",
+        summary: "Treat Verify Steps as the contract, then record verification and close with traceable metadata.",
+        commands: BOOTSTRAP_VERIFY_AND_FINISH_COMMANDS,
+        notes: [
+            "In `direct`, `finish` creates the deterministic close commit by default.",
+            "Use `--no-close-commit` only for explicit manual close handling.",
+        ],
+    },
+    {
+        heading: "5. Recover mixed or broken state",
+        summary: "Use diagnostics before manual repair, especially after framework upgrades or partial edits.",
+        commands: BOOTSTRAP_RECOVERY_COMMANDS,
+        notes: [
+            "Run `doctor` before touching managed policy files by hand.",
+            "`upgrade` applies the managed framework files from the installed CLI bundle.",
+        ],
+    },
+];
+export function renderBootstrapReferenceLine() {
+    return `Canonical bootstrap doc: \`${AGENT_BOOTSTRAP_DOC_PATH}\`.`;
+}
+export function renderBootstrapSectionLines(sections) {
+    const lines = [];
+    for (const section of sections) {
+        lines.push(`## ${section.heading}`, "", section.summary, "");
+        for (const command of section.commands) {
+            lines.push(`- \`${command}\``);
+        }
+        if (section.notes && section.notes.length > 0) {
+            lines.push("");
+            for (const note of section.notes) {
+                lines.push(`- ${note}`);
+            }
+        }
+        lines.push("");
+    }
+    if (lines.at(-1) === "")
+        lines.pop();
+    return lines;
+}
+function renderCommandBlock(commands) {
+    return ["```bash", ...commands, "```"];
+}
+export function renderBootstrapDoc() {
+    const lines = [
+        "---",
+        'title: "Agent bootstrap"',
+        'description: "The shortest canonical startup path for agent work in an Agent Plane repository."',
+        "---",
+        "",
+        "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.",
+        "",
+        "## Copy-paste start block",
+        "",
+        ...renderCommandBlock(BOOTSTRAP_PREFLIGHT_COMMANDS),
+        "",
+        "After preflight, continue with the smallest task flow that matches your mode and role.",
+        "",
+        ...renderBootstrapSectionLines(BOOTSTRAP_SECTIONS),
+        "",
+        "## Direct vs branch_pr",
+        "",
+        "- `direct`: work in the current checkout and finish the task yourself.",
+        "- `branch_pr`: start a task branch/worktree, maintain PR artifacts, and let INTEGRATOR close on base.",
+        "",
+    ];
+    return `${lines.join("\n")}\n`;
+}

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":"AAkMA,wBAAgB,SAAS,IAAI,MAAM,EAAE,CAEpC;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOzD;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CA2FzC"}
+{"version":3,"file":"command-guide.d.ts","sourceRoot":"","sources":["../../src/cli/command-guide.ts"],"names":[],"mappings":"AA+GA,wBAAgB,SAAS,IAAI,MAAM,EAAE,CAEpC;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOzD;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CAsCzC"}

package/dist/cli/command-guide.js

@@ -1,176 +1,103 @@
 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/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_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;
+}
 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.",
-            '- Task docs (when planning needs it): `agentplane task doc set <task-id> --section Summary --text "..."`',
+            `- 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.",
-            "- branch_pr: `agentplane work start <task-id> --agent <ROLE> --slug <slug> --worktree`",
-            '- Status updates: `agentplane start <task-id> --author <ROLE> --body "Start: ..."` / `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.`,
         ],
     },
     {
         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.",
-            "- branch_pr: `agentplane work start <task-id> --agent <ROLE> --slug <slug> --worktree`",
-            '- Status updates: `agentplane start <task-id> --author <ROLE> --body "Start: ..."` / `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.`,
         ],
     },
     {
         role: "DOCS",
         lines: [
-            '- Task docs: `agentplane task doc set <task-id> --section Summary --text "..."` (repeat per section or use `--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.",
         ],
     },
     {
         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 "..." \`.`,
         ],
     },
     {
         role: "CREATOR",
         lines: [
-            '- Task bookkeeping: `agentplane task update <task-id> ...` / `agentplane start <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);
 }
@@ -188,82 +115,30 @@ export function renderQuickstart() {
     return [
         "# agentplane quickstart",
         "",
-        "AGENTS.md is the source of truth for the 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. CLI syntax lives in quickstart and `agentplane role <ROLE>`.",
         "Do not edit `.agentplane/tasks.json` by hand.",
+        "If the repository is not initialized yet, stop and run `agentplane init` first.",
         "",
-        "- See AGENTS.md for the canonical workflow policy and approval gates.",
-        "",
-        "## Project setup",
+        renderBootstrapReferenceLine(),
         "",
-        "- `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)",
+        ...renderBootstrapOverview(),
         "",
-        "## Daily task workflow",
+        "## Role-specific deltas",
         "",
-        `- \`${COMMAND_SNIPPETS.core.taskList}\` / \`${COMMAND_SNIPPETS.core.taskShow}\``,
-        `- \`${COMMAND_SNIPPETS.core.taskNew}\``,
-        `- \`${COMMAND_SNIPPETS.core.startTask}\``,
-        `- \`${COMMAND_SNIPPETS.core.verifyTask}\``,
-        `- \`${COMMAND_SNIPPETS.core.finishTask}\``,
+        `- 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.",
         "",
-        "## 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)",
+        "## Branch workflow extras",
         "",
         "- `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"]\'`',
-        "",
-        "## Role/phase command guide (when to use what)",
-        "",
-        "Use `agentplane role <ROLE>` to print a single block from this section.",
-        "",
-        ...renderRoleSection(),
-        "",
-        "## Global flags",
-        "",
-        "- `--root <path>`: treat <path> as project root",
-        "- `--json-errors`: emit JSON-formatted errors",
-        "- `--help` / `-h`: show help",
-        "- `--version`: show version",
-        "- `--no-update-check`: skip checking npm for a newer CLI version",
-        "",
-        "Notes:",
-        "- `.env` at the repo root is loaded automatically (without overwriting existing environment variables).",
+        "- `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.`,
         "",
         "## Commit message format",
         "",

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 startTask: "agentplane start <task-id> --author <ROLE> --body \"Start: ...\"";
+        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>',
-        startTask: 'agentplane start <task-id> --author <ROLE> --body "Start: ..."',
+        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/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",
@@ -37,7 +37,7 @@ async function cmdQuickstart(opts) {
                 .filter((line) => line.length > 0);
             const payload = {
                 source_of_truth: {
-                    workflow_policy: "AGENTS.md",
+                    workflow_policy: "AGENTS.md|CLAUDE.md",
                     cli_syntax: "quickstart/role output",
                 },
                 lines,
@@ -437,7 +437,7 @@ function renderAgentProfileBlock(opts) {
         ...(permissions.length > 0 ? ["", "Permissions:", ...permissions.map((s) => `- ${s}`)] : []),
         ...(workflow.length > 0 ? ["", "Workflow:", ...workflow.map((s) => `- ${s}`)] : []),
         "",
-        `Source: .agentplane/agents/${opts.filename} (lower priority; see AGENTS.md)`,
+        `Source: .agentplane/agents/${opts.filename} (lower priority; see policy gateway file AGENTS.md or CLAUDE.md)`,
     ];
     return lines.join("\n").trimEnd();
 }

package/dist/cli/run-cli/commands/ide.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ide.d.ts","sourceRoot":"","sources":["../../../../src/cli/run-cli/commands/ide.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAGrD,KAAK,aAAa,GAAG;IAAE,GAAG,CAAC,EAAE,QAAQ,GAAG,UAAU,CAAA;CAAE,CAAC;AAErD,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,aAAa,CAkBlD,CAAC;AAEF,wBAAsB,UAAU,CAAC,IAAI,EAAE;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,EAAE,QAAQ,GAAG,UAAU,CAAC;IAC5B,IAAI,EAAE,OAAO,CAAC;CACf,GAAG,OAAO,CAAC,MAAM,CAAC,CAwClB;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAAC,aAAa,CAAC,CAElF"}
+{"version":3,"file":"ide.d.ts","sourceRoot":"","sources":["../../../../src/cli/run-cli/commands/ide.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAGrD,KAAK,aAAa,GAAG;IAAE,GAAG,CAAC,EAAE,QAAQ,GAAG,UAAU,CAAA;CAAE,CAAC;AAErD,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,aAAa,CAkBlD,CAAC;AAEF,wBAAsB,UAAU,CAAC,IAAI,EAAE;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,EAAE,QAAQ,GAAG,UAAU,CAAC;IAC5B,IAAI,EAAE,OAAO,CAAC;CACf,GAAG,OAAO,CAAC,MAAM,CAAC,CA4ClB;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAAC,aAAa,CAAC,CAElF"}

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

@@ -1,11 +1,12 @@
 import { mkdir, readFile } from "node:fs/promises";
 import path from "node:path";
 import { writeTextIfChanged } from "../../../shared/write-if-changed.js";
+import { resolvePolicyGatewayForRepo } from "../../../shared/policy-gateway.js";
 import { wrapCommand } from "./wrap-command.js";
 export const ideSyncSpec = {
     id: ["ide", "sync"],
     group: "IDE",
-    summary: "Generate IDE entrypoints from AGENTS.md.",
+    summary: "Generate IDE entrypoints from policy gateway file (AGENTS.md or CLAUDE.md).",
     options: [
         {
             kind: "string",
@@ -24,13 +25,17 @@ export const ideSyncSpec = {
 export async function cmdIdeSync(opts) {
     return wrapCommand({ command: "ide sync", rootOverride: opts.rootOverride }, async () => {
         const resolved = await opts.deps.getResolvedProject("ide sync");
-        const agentsPath = path.join(resolved.gitRoot, "AGENTS.md");
+        const gateway = await resolvePolicyGatewayForRepo({
+            gitRoot: resolved.gitRoot,
+            fallbackFlavor: "codex",
+        });
+        const agentsPath = gateway.absPath;
         const agentsText = await readFile(agentsPath, "utf8");
         const header = [
             "<!--",
             "  AUTOGENERATED by agentplane ide sync.",
             "  DO NOT EDIT MANUALLY.",
-            "  Source: AGENTS.md",
+            `  Source: ${gateway.fileName}`,
             "-->",
             "",
         ].join("\n");

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

@@ -1 +1 @@
-{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../../../../../src/cli/run-cli/commands/init/ui.ts"],"names":[],"mappings":"AAyBA,wBAAgB,iBAAiB,IAAI,MAAM,CAY1C;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAG5E"}
+{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../../../../../src/cli/run-cli/commands/init/ui.ts"],"names":[],"mappings":"AAyBA,wBAAgB,iBAAiB,IAAI,MAAM,CAW1C;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAG5E"}

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

@@ -26,12 +26,11 @@ export function renderInitWelcome() {
         "░█▀█░█░█░█▀▀░█░█░░█░░▄▀░░█▀▀░█░░░█▀█░█░█░█▀▀",
         "░▀░▀░▀▀▀░▀▀▀░▀░▀░░▀░░▀░░░▀░░░▀▀▀░▀░▀░▀░▀░▀▀▀",
     ].map((line) => color(line, "36"));
-    const subtitle = color("agent/plane", "36");
     const intro = [
         color("Bootstrap an agent-first workflow in this repository.", "1"),
         "This interactive setup runs once; daily work is executed by agents.",
     ];
-    return `${logo.join("\n")}\n${subtitle}\n\n${box(intro)}\n\n`;
+    return `${logo.join("\n")}\n\n${box(intro)}\n\n`;
 }
 export function renderInitSection(title, description) {
     const header = color(`[${title}]`, "33");

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

@@ -1,8 +1,10 @@
 import type { WorkflowMode } from "../../../../agents/agents-template.js";
+import { type PolicyGatewayFlavor } from "../../../../shared/policy-gateway.js";
 export declare function ensureAgentsFiles(opts: {
     gitRoot: string;
     agentplaneDir: string;
     workflow: WorkflowMode;
+    policyGateway: PolicyGatewayFlavor;
     configPathAbs: string;
     backendPathAbs: string;
 }): Promise<{

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

@@ -1 +1 @@
-{"version":3,"file":"write-agents.d.ts","sourceRoot":"","sources":["../../../../../src/cli/run-cli/commands/init/write-agents.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAC;AAkC1E,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,YAAY,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;CACxB,GAAG,OAAO,CAAC;IAAE,YAAY,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAuCtC"}
+{"version":3,"file":"write-agents.d.ts","sourceRoot":"","sources":["../../../../../src/cli/run-cli/commands/init/write-agents.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAC;AAQ1E,OAAO,EAGL,KAAK,mBAAmB,EACzB,MAAM,sCAAsC,CAAC;AA6B9C,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,YAAY,CAAC;IACvB,aAAa,EAAE,mBAAmB,CAAC;IACnC,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;CACxB,GAAG,OAAO,CAAC;IAAE,YAAY,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAwDtC"}