@promptbook/cli 0.114.0-5 → 0.114.0-50

package/src/cli/cli-commands/coder/initializeCoderProjectConfiguration.ts

@@ -1,19 +1,23 @@
-import { AGENT_CODING_FILE_PATH, getDefaultCoderAgentCodingFileContent } from './agentCodingFile';
-import { AGENTS_FILE_PATH, getDefaultCoderAgentsFileContent } from './agentsFile';
-import type { EnsuredCoderPromptTemplateFile, InitializationStatus } from './boilerplateTemplates';
+import { ADAM_AGENT_BOOK_RELATIVE_PATH } from '../common/ensureAdamAgentBook';
+import type { InitializationStatus } from './boilerplateTemplates';
 import {
-    ensureDefaultCoderPromptTemplateFiles,
     PROMPTS_DIRECTORY_PATH,
     PROMPTS_DONE_DIRECTORY_PATH,
     PROMPTS_TEMPLATES_DIRECTORY_PATH,
 } from './boilerplateTemplates';
-import { CODER_AGENTS_DIRECTORY_PATH, ensureCoderDeveloperAgentFile } from './ensureCoderDeveloperAgentFile';
+import type { CoderReferencedArtifactStatus, EnsuredCoderReferencedArtifact } from './coderReferencedArtifacts';
+import { ensureCoderReferencedArtifacts } from './coderReferencedArtifacts';
+import { ensureCoderDefaultAgentFiles } from './ensureCoderDefaultAgentFiles';
+import { CODER_AGENTS_DIRECTORY_PATH } from './ensureCoderDeveloperAgentFile';
 import { ensureCoderEnvFile } from './ensureCoderEnvFile';
+import { CODER_GITATTRIBUTES_FILE_PATH, ensureCoderGitattributesFile } from './ensureCoderGitattributesFile';
 import { ensureCoderGitignoreFile } from './ensureCoderGitignoreFile';
 import { ensureCoderMarkdownFile } from './ensureCoderMarkdownFile';
 import { ensureCoderPackageJsonFile } from './ensureCoderPackageJsonFile';
 import { ensureCoderVscodeSettingsFile } from './ensureCoderVscodeSettingsFile';
 import { ensureDirectory } from './ensureDirectory';
+import { resolveCoderPackageJsonScriptReferencedArtifactPaths } from './getDefaultCoderPackageJsonScripts';
+import { PROMPTS_README_FILE_PATH, PROMPTS_README_TEMPLATE } from './promptsReadmeTemplate';
 
 /**
  * Result summary returned after coder configuration initialization.
@@ -22,61 +26,118 @@ import { ensureDirectory } from './ensureDirectory';
  */
 export type CoderInitializationSummary = {
     readonly promptsDirectoryStatus: InitializationStatus;
+    readonly promptsReadmeFileStatus: InitializationStatus;
     readonly promptsDoneDirectoryStatus: InitializationStatus;
     readonly promptsTemplatesDirectoryStatus: InitializationStatus;
-    readonly promptTemplateFileStatuses: ReadonlyArray<EnsuredCoderPromptTemplateFile>;
     readonly agentsDirectoryStatus: InitializationStatus;
-    readonly developerAgentFileStatus: InitializationStatus;
-    readonly agentsFileStatus: InitializationStatus;
-    readonly agentCodingFileStatus: InitializationStatus;
+    readonly adamAgentFileStatus: CoderReferencedArtifactStatus;
+    readonly adamAgentFileDiagnostic?: string;
     readonly envFileStatus: InitializationStatus;
     readonly gitignoreFileStatus: InitializationStatus;
+    readonly gitattributesFileStatus: InitializationStatus;
     readonly packageJsonFileStatus: InitializationStatus;
     readonly vscodeSettingsFileStatus: InitializationStatus;
+    readonly addedPackageJsonScriptNames: ReadonlyArray<string>;
+    readonly referencedArtifactStatuses: ReadonlyArray<EnsuredCoderReferencedArtifact>;
     readonly initializedEnvVariableNames: ReadonlyArray<string>;
+    /** Actual preserved or generated scope of the project check. */
+    readonly checkScriptSummary: string;
+    /** Manual steps needed for custom or conflicting legacy entries. */
+    readonly migrationInstructions: ReadonlyArray<string>;
+    /** Whether validation is configured rather than still requiring setup. */
+    readonly isCheckConfigured: boolean;
 };
 
 /**
  * Creates or updates all coder configuration artifacts required in the current project.
  *
+ * Existing scripts, settings and Books are preserved. Missing Books and helper TEAM declarations are added
+ * independently of package scripts, with unresolved artifacts reported without replacing project content.
+ *
  * @private internal utility of `coder init` command
  */
-export async function initializeCoderProjectConfiguration(projectPath: string): Promise<CoderInitializationSummary> {
-    const promptsDirectoryStatus = await ensureDirectory(projectPath, PROMPTS_DIRECTORY_PATH);
-    const promptsDoneDirectoryStatus = await ensureDirectory(projectPath, PROMPTS_DONE_DIRECTORY_PATH);
-    const promptsTemplatesDirectoryStatus = await ensureDirectory(projectPath, PROMPTS_TEMPLATES_DIRECTORY_PATH);
-    const promptTemplateFileStatuses = await ensureDefaultCoderPromptTemplateFiles(projectPath);
-    const agentsDirectoryStatus = await ensureDirectory(projectPath, CODER_AGENTS_DIRECTORY_PATH);
-    const developerAgentFileStatus = await ensureCoderDeveloperAgentFile(projectPath);
-    const agentsFileStatus = await ensureCoderMarkdownFile(
-        projectPath,
-        AGENTS_FILE_PATH,
-        getDefaultCoderAgentsFileContent(),
+export async function initializeCoderProjectConfiguration(
+    projectPath: string,
+    onStepCompleted?: (step: string) => void,
+): Promise<CoderInitializationSummary> {
+    /** Records only completed setup steps so callers can explain partial failures. */
+    async function completeStep<Result>(step: string, operation: Promise<Result>): Promise<Result> {
+        const result = await operation;
+        onStepCompleted?.(step);
+        return result;
+    }
+    const promptsDirectoryStatus = await completeStep('prompts/', ensureDirectory(projectPath, PROMPTS_DIRECTORY_PATH));
+    const promptsReadmeFileStatus = await completeStep(
+        'prompts/README.md',
+        ensureCoderMarkdownFile(projectPath, PROMPTS_README_FILE_PATH, PROMPTS_README_TEMPLATE),
+    );
+    const promptsDoneDirectoryStatus = await completeStep(
+        'prompts/done/',
+        ensureDirectory(projectPath, PROMPTS_DONE_DIRECTORY_PATH),
+    );
+    const promptsTemplatesDirectoryStatus = await completeStep(
+        'prompts/templates/',
+        ensureDirectory(projectPath, PROMPTS_TEMPLATES_DIRECTORY_PATH),
+    );
+    const agentsDirectoryStatus = await completeStep(
+        'agents/',
+        ensureDirectory(projectPath, CODER_AGENTS_DIRECTORY_PATH),
+    );
+    const defaultAgentArtifacts = await completeStep(
+        'Default Books and TEAM references checked',
+        ensureCoderDefaultAgentFiles(projectPath),
+    );
+    const adamRelativeFilePath = `${CODER_AGENTS_DIRECTORY_PATH}/${ADAM_AGENT_BOOK_RELATIVE_PATH}`;
+    const adamArtifact = defaultAgentArtifacts.find(
+        ({ relativeFilePath }) => relativeFilePath === adamRelativeFilePath,
+    )!;
+    const { envFileStatus, initializedEnvVariableNames } = await completeStep('.env', ensureCoderEnvFile(projectPath));
+    const gitignoreFileStatus = await completeStep('.gitignore', ensureCoderGitignoreFile(projectPath));
+    const gitattributesFileStatus = await completeStep(
+        CODER_GITATTRIBUTES_FILE_PATH,
+        ensureCoderGitattributesFile(projectPath),
     );
-    const agentCodingFileStatus = await ensureCoderMarkdownFile(
-        projectPath,
-        AGENT_CODING_FILE_PATH,
-        getDefaultCoderAgentCodingFileContent(),
+    const {
+        status: packageJsonFileStatus,
+        addedEntryKeys: addedPackageJsonScriptNames,
+        checkScriptSummary,
+        migrationInstructions,
+        isCheckConfigured,
+    } = await completeStep('package.json', ensureCoderPackageJsonFile(projectPath));
+    const vscodeSettingsFileStatus = await completeStep(
+        '.vscode/settings.json',
+        ensureCoderVscodeSettingsFile(projectPath),
     );
-    const { envFileStatus, initializedEnvVariableNames } = await ensureCoderEnvFile(projectPath);
-    const gitignoreFileStatus = await ensureCoderGitignoreFile(projectPath);
-    const packageJsonFileStatus = await ensureCoderPackageJsonFile(projectPath);
-    const vscodeSettingsFileStatus = await ensureCoderVscodeSettingsFile(projectPath);
+    const referencedArtifactStatuses = [
+        ...defaultAgentArtifacts.filter(({ relativeFilePath }) => relativeFilePath !== adamRelativeFilePath),
+        ...(await completeStep(
+            'Script-referenced artifacts checked',
+            ensureCoderReferencedArtifacts(
+                projectPath,
+                resolveCoderPackageJsonScriptReferencedArtifactPaths(addedPackageJsonScriptNames),
+            ),
+        )),
+    ];
 
     return {
         promptsDirectoryStatus,
+        promptsReadmeFileStatus,
         promptsDoneDirectoryStatus,
         promptsTemplatesDirectoryStatus,
-        promptTemplateFileStatuses,
         agentsDirectoryStatus,
-        developerAgentFileStatus,
-        agentsFileStatus,
-        agentCodingFileStatus,
+        adamAgentFileStatus: adamArtifact.status,
+        adamAgentFileDiagnostic: adamArtifact.diagnostic,
         envFileStatus,
         gitignoreFileStatus,
+        gitattributesFileStatus,
         packageJsonFileStatus,
         vscodeSettingsFileStatus,
+        addedPackageJsonScriptNames,
+        referencedArtifactStatuses,
         initializedEnvVariableNames,
+        checkScriptSummary,
+        migrationInstructions,
+        isCheckConfigured,
     };
 }
 

package/src/cli/cli-commands/coder/list.ts

@@ -0,0 +1,102 @@
+import type {
+    Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
+} from 'commander';
+import { spaceTrim } from 'spacetrim';
+import type { $side_effect } from '../../../utils/organization/$side_effect';
+import { $preflightWorkspaceRepository } from '../common/workspaceRepository';
+import { addWorkspaceRepositoryOptions } from '../common/workspaceRepositoryCliOptions';
+import { normalizeProjectCliOptions } from '../common/projectCliOptions';
+import { handleActionErrors } from '../common/handleActionErrors';
+import { addPromptPriorityOptions } from '../common/promptPriorityCliOptions';
+import type { PromptRunnerSelectionCliOptions } from '../common/promptRunnerCliOptions';
+import {
+    addPromptRunnerSelectionOptions,
+    normalizePromptRunnerSelectionCliOptions,
+    PROMPT_RUNNER_DESCRIPTION,
+} from '../common/promptRunnerCliOptions';
+import { addCoderAgentOption, type CoderAgentCliOptions } from './agentCliOptions';
+
+/**
+ * Initializes `coder list` command for Promptbook CLI utilities.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it registers a command in the CLI.
+ *
+ * @private internal function of `promptbookCli`
+ */
+export function $initializeCoderListCommand(program: Program): $side_effect {
+    const command = program.command('list');
+    command.description(
+        spaceTrim(`
+            List ready coding prompts by priority without executing them
+
+            ${PROMPT_RUNNER_DESCRIPTION}
+
+            Features:
+            - Lists only ready, fully authored prompts
+            - Groups prompts from highest to lowest priority
+            - Optional --harness, --model and --agent filters show only prompts compatible with that selection
+            - Does not start a coding harness or modify prompt files
+        `),
+    );
+
+    addPromptRunnerSelectionOptions(command);
+    addCoderAgentOption(command);
+    addPromptPriorityOptions(command);
+
+    addWorkspaceRepositoryOptions(command);
+
+    command.action(
+        handleActionErrors(async (cliOptions) => {
+            const projectOptions = normalizeProjectCliOptions(cliOptions);
+            const {
+                agent,
+                priority,
+                minPriority: minimumPriority,
+                maxPriority: maximumPriority,
+            } = cliOptions as {
+                readonly agent?: string;
+                readonly priority?: number;
+                readonly minPriority?: number;
+                readonly maxPriority?: number;
+            } & PromptRunnerSelectionCliOptions &
+                CoderAgentCliOptions;
+            const runnerOptions = normalizePromptRunnerSelectionCliOptions(
+                cliOptions as PromptRunnerSelectionCliOptions,
+                { isAgentRequired: false },
+            );
+            const workspace = await $preflightWorkspaceRepository({
+                ...projectOptions,
+                policy: 'read-only',
+            });
+            const resolvedCoderAgentBook =
+                agent === undefined
+                    ? undefined
+                    : await (
+                          await import('../../../../scripts/run-codex-prompts/common/resolveCoderAgent')
+                      ).resolveCoderAgentBook(agent, workspace.projectPath);
+            const promptRunnerIdentity =
+                runnerOptions.agentName === undefined &&
+                runnerOptions.model === undefined &&
+                resolvedCoderAgentBook === undefined
+                    ? undefined
+                    : {
+                          harnessName: runnerOptions.agentName,
+                          modelName: runnerOptions.model,
+                          agentReferences: resolvedCoderAgentBook?.agentReferences,
+                      };
+
+            // Note: Import dynamically to avoid loading prompt parsing dependencies until this command is used.
+            const { listCoderPrompts } = await import('../../../../scripts/run-codex-prompts/main/listCoderPrompts');
+            await listCoderPrompts({
+                projectPath: workspace.projectPath,
+                priority,
+                minimumPriority,
+                maximumPriority,
+                promptRunnerIdentity,
+            });
+        }),
+    );
+}
+
+// Note: [🟡] Code for CLI command [list](src/cli/cli-commands/coder/list.ts) should never be published outside of `@promptbook/cli`
+// Note: [💞] Ignore a discrepancy between file name and entity name

package/src/cli/cli-commands/coder/mergeStringRecordJsonFile.ts

@@ -28,6 +28,27 @@ type MergeStringRecordJsonFileOptions = {
     readonly fieldPath: string;
     readonly nextEntries: Readonly<Record<string, string>>;
     readonly ensureParentDirectoryPath?: string;
+    /** Optional narrowly scoped migration of existing entries before missing defaults are added. */
+    readonly transformExistingEntries?: (
+        entries: Readonly<Record<string, string>>,
+    ) => Readonly<Record<string, string>> | Promise<Readonly<Record<string, string>>>;
+};
+
+/**
+ * Result of one additive string-record merge into a JSON file.
+ *
+ * @private internal utility of `coder init` command
+ */
+export type MergedStringRecordJsonFile = {
+    /**
+     * Status describing whether the JSON file had to be created or updated.
+     */
+    readonly status: InitializationStatus;
+
+    /**
+     * Keys which were missing in the JSON file and therefore added by the merge.
+     */
+    readonly addedEntryKeys: ReadonlyArray<string>;
 };
 
 /**
@@ -43,6 +64,9 @@ const DEFAULT_JSON_FILE_NEWLINE = '\n';
 /**
  * Ensures one JSON object field contains the provided string-record entries.
  *
+ * Entries are additive unless a caller explicitly supplies a scoped migration callback.
+ * Hand-tuned scripts and settings survive repeated `ptbk coder init`; migrations recognize generated entries only.
+ *
  * @private function of `initializeCoderProjectConfiguration`
  */
 export async function mergeStringRecordJsonFile({
@@ -51,7 +75,8 @@ export async function mergeStringRecordJsonFile({
     fieldPath,
     nextEntries,
     ensureParentDirectoryPath,
-}: MergeStringRecordJsonFileOptions): Promise<InitializationStatus> {
+    transformExistingEntries,
+}: MergeStringRecordJsonFileOptions): Promise<MergedStringRecordJsonFile> {
     if (ensureParentDirectoryPath) {
         await mkdir(join(projectPath, ensureParentDirectoryPath), { recursive: true });
     }
@@ -62,23 +87,32 @@ export async function mergeStringRecordJsonFile({
     const jsonObject = fileContent === undefined ? {} : await parseJsonObjectFile(relativeFilePath, fileContent);
     const existingEntries = getStringRecordOrDefault(jsonObject[fieldPath], relativeFilePath, fieldPath);
 
-    let hasChanges = fileContent === undefined;
-    const mergedEntries = { ...existingEntries };
+    const addedEntryKeys: Array<string> = [];
+    const mergedEntries = { ...((await transformExistingEntries?.(existingEntries)) ?? existingEntries) };
     for (const [entryKey, entryValue] of Object.entries(nextEntries)) {
-        if (mergedEntries[entryKey] !== entryValue) {
-            mergedEntries[entryKey] = entryValue;
-            hasChanges = true;
+        if (Object.prototype.hasOwnProperty.call(mergedEntries, entryKey)) {
+            // Note: The project already defines this entry, keep its own value untouched
+            continue;
+        }
+
+        mergedEntries[entryKey] = entryValue;
+        addedEntryKeys.push(entryKey);
+    }
+    for (const entryKey of Object.keys(mergedEntries)) {
+        if (!Object.prototype.hasOwnProperty.call(existingEntries, entryKey) && !addedEntryKeys.includes(entryKey)) {
+            addedEntryKeys.push(entryKey);
         }
     }
 
+    const hasChanges = fileContent === undefined || JSON.stringify(mergedEntries) !== JSON.stringify(existingEntries);
     if (!hasChanges) {
-        return 'unchanged';
+        return { status: 'unchanged', addedEntryKeys };
     }
 
     const nextJsonObject: JsonObject = { ...jsonObject };
     nextJsonObject[fieldPath] = mergedEntries;
     await writeFile(absoluteFilePath, serializeJsonObject(nextJsonObject, formatting), 'utf-8');
-    return fileContent === undefined ? 'created' : 'updated';
+    return { status: fileContent === undefined ? 'created' : 'updated', addedEntryKeys };
 }
 
 /**

package/src/cli/cli-commands/coder/ping.ts

@@ -3,8 +3,17 @@ import type {
 } from 'commander';
 import { spaceTrim } from 'spacetrim';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
+import { $preflightWorkspaceRepository } from '../common/workspaceRepository';
+import { addWorkspaceRepositoryOptions } from '../common/workspaceRepositoryCliOptions';
+import { normalizeProjectCliOptions } from '../common/projectCliOptions';
 import { handleActionErrors } from '../common/handleActionErrors';
 import { $ensureHarnessInstallations } from '../common/harness/$ensureHarnessInstallations';
+import {
+    addQuestionsOption,
+    normalizeQuestionsCliOptions,
+    QUESTIONS_DESCRIPTION,
+    type QuestionsCliOptions,
+} from '../common/questionsCliOptions';
 import type { PromptRunnerSelectionCliOptions } from '../common/promptRunnerCliOptions';
 import {
     addPromptRunnerRuntimeOptions,
@@ -12,6 +21,8 @@ import {
     normalizePromptRunnerSelectionCliOptions,
     PROMPT_RUNNER_DESCRIPTION,
 } from '../common/promptRunnerCliOptions';
+import { parseOptionalPeriodDuration } from './waitOptions';
+import { $ensureCoderHarnessGitignoreRules } from './$ensureCoderHarnessGitignoreRules';
 
 /**
  * Initializes `coder ping` command for Promptbook CLI utilities
@@ -23,47 +34,90 @@ import {
 export function $initializeCoderPingCommand(program: Program): $side_effect {
     const command = program.command('ping');
     command.description(
-        spaceTrim(`
-            Send one tiny dummy prompt to a harness and model to measure and warm them up
+        spaceTrim(
+            (block) => `
+                Send one tiny dummy prompt to a harness and model to measure and warm them up
 
-            ${PROMPT_RUNNER_DESCRIPTION}
+                ${block(PROMPT_RUNNER_DESCRIPTION)}
 
-            Features:
-            - Verifies that the selected harness, model, thinking level and authentication really work
-            - Reports the answer of the harness, the response time and the reported usage
-            - Starts the hourly/weekly quota window before you need it, so it is already refreshing when you do
-            - Leaves the project exactly as it was — nothing is read, written, changed or committed
-            - Use --no-ui to stream the raw harness output instead of only the compact result
-        `),
+                ${block(QUESTIONS_DESCRIPTION)}
+
+                Features:
+                - Verifies that the selected harness, model, thinking level and authentication really work
+                - Reports the answer of the harness, the response time and the reported usage
+                - Starts the hourly/weekly quota window before you need it, so it is already refreshing when you do
+                - Optional --period keeps the quota window refreshing by pinging once per period until stopped
+                - Makes no coding changes or commits; if the selected harness has missing local ignore rules, offers to add them to .gitignore
+                - Checks that the selected harness is installed and up to date unless --no-questions is used
+                - Use --no-ui to stream the raw harness output instead of only the compact result
+            `,
+        ),
     );
 
     addPromptRunnerSelectionOptions(command);
+    addQuestionsOption(command);
     addPromptRunnerRuntimeOptions(command);
+    command.option(
+        '--period <duration>',
+        spaceTrim(`
+            Keep pinging once per period instead of pinging only once.
+            Accepts durations like 5h, 30m, 1h30m and repeats until it is stopped with CTRL+C.
+        `),
+    );
+
+    addWorkspaceRepositoryOptions(command);
 
     command.action(
         handleActionErrors(async (cliOptions) => {
+            const projectOptions = normalizeProjectCliOptions(cliOptions);
+            const { period: periodValue } = cliOptions as {
+                readonly period?: string;
+            } & PromptRunnerSelectionCliOptions;
+
             const runnerOptions = normalizePromptRunnerSelectionCliOptions(
                 cliOptions as PromptRunnerSelectionCliOptions,
                 { isAgentRequired: true },
             );
+            const questionsOptions = normalizeQuestionsCliOptions(cliOptions as QuestionsCliOptions);
 
-            await $ensureHarnessInstallations([runnerOptions.agentName]);
+            // Note: The period is validated before the harness installation check, so a mistyped duration fails fast
+            const periodMs = parseOptionalPeriodDuration('--period', periodValue);
 
-            // Note: Import the ping dynamically to avoid loading heavy dependencies until needed
-            const { pingCoderHarness } = await import('../../../../scripts/run-codex-prompts/ping/pingCoderHarness');
-            const { printCoderPingResult } = await import(
-                '../../../../scripts/run-codex-prompts/ping/printCoderPingResult'
-            );
+            const workspace = await $preflightWorkspaceRepository({
+                ...projectOptions,
+                policy: 'mutate',
+                ...questionsOptions,
+            });
+
+            await $ensureHarnessInstallations([runnerOptions.agentName], questionsOptions);
+            await $ensureCoderHarnessGitignoreRules(workspace.projectPath, runnerOptions.agentName, questionsOptions);
 
-            const result = await pingCoderHarness({
+            const pingOptions = {
+                projectPath: workspace.projectPath,
                 agentName: runnerOptions.agentName,
                 model: runnerOptions.model,
                 thinkingLevel: runnerOptions.thinkingLevel,
                 allowCredits: runnerOptions.allowCredits,
                 shouldPrintLiveOutput: runnerOptions.noUi,
-            });
+            };
+
+            // Note: Import the ping dynamically to avoid loading heavy dependencies until needed
+            if (periodMs !== undefined) {
+                const { pingCoderHarnessPeriodically } = await import(
+                    '../../../../scripts/run-codex-prompts/ping/pingCoderHarnessPeriodically'
+                );
+
+                // Note: This never returns - it keeps pinging until the user stops the process
+                await pingCoderHarnessPeriodically({ ...pingOptions, periodMs });
+                return;
+            }
+
+            const { pingCoderHarness } = await import('../../../../scripts/run-codex-prompts/ping/pingCoderHarness');
+            const { printCoderPingResult } = await import(
+                '../../../../scripts/run-codex-prompts/ping/printCoderPingResult'
+            );
 
-            printCoderPingResult(result);
+            printCoderPingResult(await pingCoderHarness(pingOptions));
         }),
     );
 }

package/src/cli/cli-commands/coder/plan.ts

@@ -0,0 +1,139 @@
+import { join, relative } from 'path';
+import type { Command as Program } from 'commander';
+import { readFile } from 'fs/promises';
+import { NotAllowed } from '../../../errors/NotAllowed';
+import type { $side_effect } from '../../../utils/organization/$side_effect';
+import { spaceTrim } from '../../../utils/organization/spaceTrim';
+import { addCoderGitSyncOptions, normalizeCoderGitSyncCliOptions } from '../common/coderGitSyncCliOptions';
+import { $preflightWorkspaceRepository } from '../common/workspaceRepository';
+import { addWorkspaceRepositoryOptions } from '../common/workspaceRepositoryCliOptions';
+import { normalizeProjectCliOptions } from '../common/projectCliOptions';
+import { handleActionErrors } from '../common/handleActionErrors';
+import {
+    addPromptRunnerRuntimeOptions,
+    addPromptRunnerSelectionOptions,
+    normalizePromptRunnerSelectionCliOptions,
+} from '../common/promptRunnerCliOptions';
+import { addCoderExecutionOptions } from './agentCliOptions';
+
+/**
+ * Registers the repository-aware, planning-only conversation under the existing coder command group.
+ * @private internal utility of `promptbookCli`
+ */
+export function $initializeCoderPlanCommand(program: Program): $side_effect {
+    const command = program.command('plan').description(
+        spaceTrim(`
+        Discuss features with the project's Developer Book and review PRDs before saving them.
+
+        Run ptbk coder init first. Default Book: agents/developer.book; --agent overrides the Book,
+        independently of --harness and --model. Use --agent ./agents/planner.book for Planner. Currently supports openai-codex with restricted tools.
+        Requires an interactive terminal and a Codex version supporting --ignore-user-config and --ignore-rules.
+        Codex configuration, plugins, hooks and native tools are isolated; --model default uses Codex's built-in default.
+        /save applies reviewed proposals, /draft saves [-] drafts, /discard drops proposals, /exit ends.
+        Only PRD Markdown files under prompts/ can change. No implementation or queue launch occurs.
+        Git sync is opt-in: --auto-pull before planning, --commit for session PRDs, --auto-push only with --commit.
+    `),
+    );
+    addPromptRunnerSelectionOptions(command);
+    addPromptRunnerRuntimeOptions(command);
+    addCoderExecutionOptions(command);
+    addCoderGitSyncOptions(command);
+    command.option(
+        '--template <path>',
+        'PRD template (defaults to the project-owned prompts/templates/common.md when present)',
+    );
+    addWorkspaceRepositoryOptions(command);
+
+    command.action(
+        handleActionErrors(async (cliOptions) => {
+            const projectOptions = normalizeProjectCliOptions(cliOptions);
+            const { createPlanningTerminal } = await import('./planning/createPlanningTerminal');
+            const { runPlanningSession } = await import('./planning/runPlanningSession');
+            const { resolvePlanningPath } = await import('./planning/resolvePlanningPath');
+            const { assertPlanningHarnessSupported } = await import('./planning/runPlanningHarness');
+            const { assertPlanningCommitSafe } = await import('./planning/assertPlanningCommitSafe');
+            const { $startCoderGitSync, $commitCoderChanges } = await import(
+                '../../../../scripts/run-codex-prompts/git/coderGitSync'
+            );
+            const options = normalizePromptRunnerSelectionCliOptions(cliOptions, { isAgentRequired: true });
+            assertPlanningHarnessSupported(options.agentName);
+            const gitSync = normalizeCoderGitSyncCliOptions(cliOptions);
+            const workspace = await $preflightWorkspaceRepository({
+                ...projectOptions,
+                policy: 'mutate',
+                isAskingQuestionsEnabled: cliOptions.questions,
+            });
+            if (cliOptions.questions === false) {
+                throw new NotAllowed(
+                    spaceTrim(
+                        '`ptbk coder plan` requires an interactive conversation and review. Run it without `--no-questions` in a terminal.',
+                    ),
+                );
+            }
+            const { resolveCoderProjectContext } = await import(
+                '../../../../scripts/run-codex-prompts/common/resolveCoderProjectContext'
+            );
+            const projectContext = await resolveCoderProjectContext({
+                ...cliOptions,
+                projectPath: workspace.projectPath,
+            });
+            const terminal = createPlanningTerminal();
+            try {
+                const { projectPath } = workspace;
+                if (gitSync.isCommitEnabled) {
+                    assertPlanningCommitSafe(projectPath);
+                    assertPlanningCommitSafe(workspace.repositoryRoot!);
+                }
+                const commitScope = await $startCoderGitSync({ workspace, gitSync });
+                const saved = await runPlanningSession(
+                    {
+                        ...options,
+                        projectPath,
+                        agent: cliOptions.agent,
+                        context: cliOptions.context,
+                        projectContext,
+                        template: cliOptions.template,
+                        preexistingChangedPaths: gitSync.isCommitEnabled
+                            ? new Set(
+                                  Array.from(commitScope.snapshotBeforeOperation.changedFileHashes.keys(), (path) =>
+                                      relative(projectPath, join(workspace.repositoryRoot!, path)).replace(/\\/gu, '/'),
+                                  ),
+                              )
+                            : undefined,
+                    },
+                    terminal,
+                );
+                if (terminal.signal.aborted) return;
+                // A file edited by the user after saving must not be swept into a session commit either.
+                if (gitSync.isCommitEnabled) {
+                    assertPlanningCommitSafe(projectPath);
+                    for (const [path, content] of saved) {
+                        if ((await readFile(resolvePlanningPath(projectPath, path, true), 'utf-8')) !== content) {
+                            throw new NotAllowed(
+                                spaceTrim(
+                                    `\`${path}\` changed after planning saved it. The planning commit was skipped; review the working tree.`,
+                                ),
+                            );
+                        }
+                    }
+                }
+                await $commitCoderChanges({
+                    gitSync,
+                    commitScope,
+                    commitMessage: 'Plan project tasks',
+                    relevantPaths: [...saved.keys()].map((path) =>
+                        relative(workspace.repositoryRoot!, join(projectPath, path)).replace(/\\/gu, '/'),
+                    ),
+                });
+            } catch (error) {
+                if (!terminal.signal.aborted) throw error;
+                console.info('Planning cancelled. Saved PRDs remain intact.');
+            } finally {
+                terminal.close();
+            }
+        }),
+    );
+}
+
+// Note: [🟡] CLI planning must never be published outside of `@promptbook/cli`.
+// Note: [💞] Ignore a discrepancy between file name and entity name.