@promptbook/cli 0.114.0-42 → 0.114.0-48

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

@@ -2,6 +2,8 @@ import type {
     Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
 } from 'commander';
 import { spaceTrim } from 'spacetrim';
+import { ParseError } from '../../../errors/ParseError';
+import { EnvironmentMismatchError } from '../../../errors/EnvironmentMismatchError';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
 import { ADAM_AGENT_BOOK_RELATIVE_PATH } from '../common/ensureAdamAgentBook';
 import type { CoderGitSyncCliOptions } from '../common/coderGitSyncCliOptions';
@@ -10,6 +12,8 @@ import {
     CODER_GIT_SYNC_DESCRIPTION,
     normalizeCoderGitSyncCliOptions,
 } from '../common/coderGitSyncCliOptions';
+import { $preflightWorkspaceRepository } from '../common/workspaceRepository';
+import { addWorkspaceRepositoryOptions } from '../common/workspaceRepositoryCliOptions';
 import { handleActionErrors } from '../common/handleActionErrors';
 import { $ensureHarnessInstallations } from '../common/harness/$ensureHarnessInstallations';
 import { getHarnessDefinition } from '../common/harness/HarnessDefinition';
@@ -27,6 +31,7 @@ import { CODER_AGENTS_DIRECTORY_PATH, CODER_DEVELOPER_AGENT_FILE_PATH } from './
 import { isDirectoryEmpty } from './ensureDirectory';
 import { formatDisplayPath } from './formatDisplayPath';
 import { generatePromptBoilerplate } from './generate-boilerplates';
+import { getCoderInitializationCommitPaths } from './getCoderInitializationCommitPaths';
 import { initializeCoderProjectConfiguration } from './initializeCoderProjectConfiguration';
 import { printInitializationSummary } from './printInitializationSummary';
 
@@ -55,13 +60,22 @@ export function $initializeCoderInitCommand(program: Program): $side_effect {
     command.description(
         spaceTrim(
             (block) => `
-                Initialize Promptbook coder configuration for current project
+                Initialize Git and Promptbook coder configuration for current project
+
+                Equivalent entrypoints: \`ptbk init\`, \`ptbk coder init\`, and \`ptbk coder initialize\`.
+                Creates a local Git working tree automatically when missing, including with \`--no-questions\`.
+                Reuses an enclosing repository without changing its history, configuration or index.
+                Does not stage existing files or create a first commit unless \`--commit\` is explicitly requested.
 
                 Creates or updates:
                 - prompts/
+                - prompts/README.md (offline PRD and workflow guide; existing README is preserved)
                 - prompts/done/
                 ${block(listDefaultCoderProjectPromptTemplateDisplayPaths())}
                 - ${CODER_DEVELOPER_AGENT_FILE_PATH}
+                - agents/planner.book
+                - agents/lawyer.book
+                - agents/copywriter.book
                 - ${CODER_AGENTS_DIRECTORY_PATH}/${ADAM_AGENT_BOOK_RELATIVE_PATH}
                 - ${AGENTS_FILE_PATH}
                 - .gitignore with local artifacts from every supported harness
@@ -70,8 +84,11 @@ export function $initializeCoderInitCommand(program: Program): $side_effect {
 
                 Never overwrites what the project already owns:
                 - Existing package.json scripts and .vscode/settings.json settings are kept, only missing ones are added
-                - Files referenced by a script, like the agent and context of coder:run, are created only together
-                  with the script which references them
+                - Missing Developer, Planner, Lawyer, Copywriter and Adam Books are initialized even when scripts already exist
+                - Adds missing local Lawyer and Copywriter TEAM references to Developer and Planner, preserving existing content
+                - Helpers advise on relevant tasks; declaring TEAM does not run them for every task
+                - Reports created, augmented, unchanged and unresolved Books; invalid or conflicting files are left untouched
+                - Other referenced files, like coder:run context, are created with their newly added scripts
 
                 Ensures required coding-agent environment variables in .env:
                 - CODING_AGENT_GIT_NAME
@@ -91,34 +108,79 @@ export function $initializeCoderInitCommand(program: Program): $side_effect {
     addCoderGitSyncOptions(command);
     addQuestionsOption(command);
 
+    addWorkspaceRepositoryOptions(command);
+
     command.action(
         handleActionErrors(async (cliOptions) => {
             const gitSync = normalizeCoderGitSyncCliOptions(cliOptions as CoderGitSyncCliOptions);
             const questionsOptions = normalizeQuestionsCliOptions(cliOptions as QuestionsCliOptions);
-            const projectPath = process.cwd();
-
-            // Note: Import the git synchronization dynamically to keep the CLI fast for runs without `--commit`
-            const { $commitCoderChanges, $startCoderGitSync } = await import(
-                '../../../../scripts/run-codex-prompts/git/coderGitSync'
-            );
-
-            const commitScope = await $startCoderGitSync({ gitSync, projectPath });
-            const isPromptsDirectoryEmpty = await isDirectoryEmpty(projectPath, PROMPTS_DIRECTORY_PATH);
-
-            const summary = await initializeCoderProjectConfiguration(projectPath);
-            printInitializationSummary(summary);
-
-            if (isPromptsDirectoryEmpty) {
-                await generatePromptBoilerplate({ projectPath, boilerplateCount: DEFAULT_BOILERPLATE_COUNT });
+            const workspace = await $preflightWorkspaceRepository({ policy: 'initialize', ...questionsOptions });
+            const { projectPath } = workspace;
+
+            const completedSteps = [`Git repository ${workspace.repositoryStatus}: ${workspace.repositoryRoot}`];
+            try {
+                // Note: Import the git synchronization dynamically to keep the CLI fast for runs without `--commit`
+                const { $commitCoderChanges, $startCoderGitSync } = await import(
+                    '../../../../scripts/run-codex-prompts/git/coderGitSync'
+                );
+
+                const commitScope = await $startCoderGitSync({ gitSync, workspace });
+                completedSteps.push('Requested Git synchronization and initial change scope');
+                // Check before initialization adds the README, templates and archive directory.
+                const isPromptsDirectoryEmpty = await isDirectoryEmpty(projectPath, PROMPTS_DIRECTORY_PATH);
+
+                const summary = await initializeCoderProjectConfiguration(projectPath, (step) =>
+                    completedSteps.push(step),
+                );
+                printInitializationSummary(summary, workspace);
+
+                if (
+                    summary.adamAgentFileStatus === 'unresolved' ||
+                    summary.referencedArtifactStatuses.some(({ status }) => status === 'unresolved')
+                ) {
+                    throw new ParseError(
+                        spaceTrim(
+                            'Some default Books or TEAM references remain **unresolved**. Review the diagnostics above, fix the affected files, and run `ptbk coder init` again.',
+                        ),
+                    );
+                }
+
+                let boilerplatePaths: ReadonlyArray<string> = [];
+                if (isPromptsDirectoryEmpty) {
+                    boilerplatePaths = await generatePromptBoilerplate({
+                        projectPath,
+                        boilerplateCount: DEFAULT_BOILERPLATE_COUNT,
+                    });
+                    completedSteps.push('Prompt boilerplates');
+                }
+
+                await $commitCoderChanges({
+                    gitSync,
+                    commitScope,
+                    commitMessage: 'Initialize Promptbook Coder',
+                    relevantPaths: getCoderInitializationCommitPaths(workspace, summary, boilerplatePaths),
+                });
+
+                if (gitSync.isCommitEnabled) completedSteps.push('Scoped initialization commit');
+                await $ensureHarnessInstallations(CODER_INIT_CHECKED_HARNESS_NAMES, {
+                    isAskingQuestionsEnabled: questionsOptions.isAskingQuestionsEnabled && Boolean(process.stdin.isTTY),
+                });
+                console.info('Promptbook project initialized.');
+            } catch (error) {
+                throw new EnvironmentMismatchError(
+                    spaceTrim(
+                        (block) => `
+                    Promptbook project initialization is incomplete in \`${projectPath}\`.
+
+                    Completed setup steps:
+                    ${block(completedSteps.map((step) => `- ${step}`).join('\n'))}
+
+                    The failing step may have left partial files. Review them and rerun \`ptbk init\`.
+                    ${block(error instanceof Error ? error.message : String(error))}
+                `,
+                    ),
+                );
             }
-
-            await $commitCoderChanges({
-                gitSync,
-                commitScope,
-                commitMessage: 'Initialize Promptbook Coder',
-            });
-
-            await $ensureHarnessInstallations(CODER_INIT_CHECKED_HARNESS_NAMES, questionsOptions);
         }),
     );
 }

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

@@ -1,20 +1,22 @@
-import { join } from 'path';
-import { ensureAdamAgentBook } from '../common/ensureAdamAgentBook';
+import { ADAM_AGENT_BOOK_RELATIVE_PATH } from '../common/ensureAdamAgentBook';
 import type { InitializationStatus } from './boilerplateTemplates';
 import {
     PROMPTS_DIRECTORY_PATH,
     PROMPTS_DONE_DIRECTORY_PATH,
     PROMPTS_TEMPLATES_DIRECTORY_PATH,
 } from './boilerplateTemplates';
-import type { EnsuredCoderReferencedArtifact } from './coderReferencedArtifacts';
+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 { 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.
@@ -23,10 +25,12 @@ import { resolveCoderPackageJsonScriptReferencedArtifactPaths } from './getDefau
  */
 export type CoderInitializationSummary = {
     readonly promptsDirectoryStatus: InitializationStatus;
+    readonly promptsReadmeFileStatus: InitializationStatus;
     readonly promptsDoneDirectoryStatus: InitializationStatus;
     readonly promptsTemplatesDirectoryStatus: InitializationStatus;
     readonly agentsDirectoryStatus: InitializationStatus;
-    readonly adamAgentFileStatus: InitializationStatus;
+    readonly adamAgentFileStatus: CoderReferencedArtifactStatus;
+    readonly adamAgentFileDiagnostic?: string;
     readonly envFileStatus: InitializationStatus;
     readonly gitignoreFileStatus: InitializationStatus;
     readonly packageJsonFileStatus: InitializationStatus;
@@ -39,33 +43,75 @@ export type CoderInitializationSummary = {
 /**
  * Creates or updates all coder configuration artifacts required in the current project.
  *
- * Nothing the project already owns is ever overwritten - existing scripts, settings and files are kept as they are,
- * and the artifacts they would reference are created only together with the scripts which actually reference them.
+ * 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 agentsDirectoryStatus = await ensureDirectory(projectPath, CODER_AGENTS_DIRECTORY_PATH);
-    const adamAgentFileStatus = await ensureAdamAgentBook(join(projectPath, CODER_AGENTS_DIRECTORY_PATH));
-    const { envFileStatus, initializedEnvVariableNames } = await ensureCoderEnvFile(projectPath);
-    const gitignoreFileStatus = await ensureCoderGitignoreFile(projectPath);
-    const { status: packageJsonFileStatus, addedEntryKeys: addedPackageJsonScriptNames } =
-        await ensureCoderPackageJsonFile(projectPath);
-    const vscodeSettingsFileStatus = await ensureCoderVscodeSettingsFile(projectPath);
-    const referencedArtifactStatuses = await ensureCoderReferencedArtifacts(
-        projectPath,
-        resolveCoderPackageJsonScriptReferencedArtifactPaths(addedPackageJsonScriptNames),
+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 { status: packageJsonFileStatus, addedEntryKeys: addedPackageJsonScriptNames } = await completeStep(
+        'package.json',
+        ensureCoderPackageJsonFile(projectPath),
+    );
+    const vscodeSettingsFileStatus = await completeStep(
+        '.vscode/settings.json',
+        ensureCoderVscodeSettingsFile(projectPath),
+    );
+    const referencedArtifactStatuses = [
+        ...defaultAgentArtifacts.filter(({ relativeFilePath }) => relativeFilePath !== adamRelativeFilePath),
+        ...(await completeStep(
+            'Script-referenced artifacts checked',
+            ensureCoderReferencedArtifacts(
+                projectPath,
+                resolveCoderPackageJsonScriptReferencedArtifactPaths(addedPackageJsonScriptNames),
+            ),
+        )),
+    ];
 
     return {
         promptsDirectoryStatus,
+        promptsReadmeFileStatus,
         promptsDoneDirectoryStatus,
         promptsTemplatesDirectoryStatus,
         agentsDirectoryStatus,
-        adamAgentFileStatus,
+        adamAgentFileStatus: adamArtifact.status,
+        adamAgentFileDiagnostic: adamArtifact.diagnostic,
         envFileStatus,
         gitignoreFileStatus,
         packageJsonFileStatus,

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

@@ -3,6 +3,8 @@ 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 { handleActionErrors } from '../common/handleActionErrors';
 import { addPromptPriorityOptions } from '../common/promptPriorityCliOptions';
 import type { PromptRunnerSelectionCliOptions } from '../common/promptRunnerCliOptions';
@@ -40,6 +42,8 @@ export function $initializeCoderListCommand(program: Program): $side_effect {
     addCoderAgentOption(command);
     addPromptPriorityOptions(command);
 
+    addWorkspaceRepositoryOptions(command);
+
     command.action(
         handleActionErrors(async (cliOptions) => {
             const {
@@ -58,12 +62,13 @@ export function $initializeCoderListCommand(program: Program): $side_effect {
                 cliOptions as PromptRunnerSelectionCliOptions,
                 { isAgentRequired: false },
             );
+            const workspace = await $preflightWorkspaceRepository({ policy: 'read-only' });
             const resolvedCoderAgentBook =
                 agent === undefined
                     ? undefined
                     : await (
                           await import('../../../../scripts/run-codex-prompts/common/resolveCoderAgent')
-                      ).resolveCoderAgentBook(agent, process.cwd());
+                      ).resolveCoderAgentBook(agent, workspace.projectPath);
             const promptRunnerIdentity =
                 runnerOptions.agentName === undefined &&
                 runnerOptions.model === undefined &&
@@ -78,6 +83,7 @@ export function $initializeCoderListCommand(program: Program): $side_effect {
             // 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,

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

@@ -3,6 +3,8 @@ 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 { handleActionErrors } from '../common/handleActionErrors';
 import { $ensureHarnessInstallations } from '../common/harness/$ensureHarnessInstallations';
 import {
@@ -62,6 +64,8 @@ export function $initializeCoderPingCommand(program: Program): $side_effect {
         `),
     );
 
+    addWorkspaceRepositoryOptions(command);
+
     command.action(
         handleActionErrors(async (cliOptions) => {
             const { period: periodValue } = cliOptions as {
@@ -77,10 +81,13 @@ export function $initializeCoderPingCommand(program: Program): $side_effect {
             // Note: The period is validated before the harness installation check, so a mistyped duration fails fast
             const periodMs = parseOptionalPeriodDuration('--period', periodValue);
 
+            const workspace = await $preflightWorkspaceRepository({ policy: 'mutate', ...questionsOptions });
+
             await $ensureHarnessInstallations([runnerOptions.agentName], questionsOptions);
-            await $ensureCoderHarnessGitignoreRules(process.cwd(), runnerOptions.agentName, questionsOptions);
+            await $ensureCoderHarnessGitignoreRules(workspace.projectPath, runnerOptions.agentName, questionsOptions);
 
             const pingOptions = {
+                projectPath: workspace.projectPath,
                 agentName: runnerOptions.agentName,
                 model: runnerOptions.model,
                 thinkingLevel: runnerOptions.thinkingLevel,

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

@@ -0,0 +1,127 @@
+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 { handleActionErrors } from '../common/handleActionErrors';
+import {
+    addPromptRunnerRuntimeOptions,
+    addPromptRunnerSelectionOptions,
+    normalizePromptRunnerSelectionCliOptions,
+} from '../common/promptRunnerCliOptions';
+import { addCoderAgentOption } 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 Planner and review PRDs before saving them.
+
+        Run ptbk coder init first. Default Book: agents/planner.book; --agent overrides the Book,
+        independently of --harness and --model. 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);
+    addCoderAgentOption(command, 'planner');
+    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 { 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({
+                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 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,
+                        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.

package/src/cli/cli-commands/coder/planning/README.md

@@ -0,0 +1,37 @@
+# Coder planning
+
+Run `ptbk coder init`, then `ptbk coder plan --harness openai-codex` in an interactive terminal.
+The editable `agents/planner.book` uses the same implicit Adam inheritance as Developer. An explicit `--agent`
+overrides the Book through the shared resolver; planning resolves Books without initializing missing ancestors.
+
+The discussion retains messages, read results and saved paths across topics. Planner proposes changes as data.
+The CLI shows exact paths and changed text, then accepts `/save`, `/draft`, `/discard`, or another discussion turn.
+EOF and `/exit` discard unsaved proposals. Ctrl+C aborts inference. Saved files remain intact after failures.
+
+New PRDs use the same numbering, emoji tags, priority and template builder as `coder add`. The project-owned common
+template is selected when present; `--template` selects another. Drafts use `[-]`, pending tasks use `[ ]`.
+Edits replace one unique passage in one pending/draft task body, preserving identity, routing, priority, line endings,
+and other sections. Completed work requires a new follow-up task. Concurrent changes invalidate a preview.
+
+The execution boundary belongs to the command. Codex runs in a separate ignored `.promptbook/coder-plan` workspace
+with an empty repository root, ignored user configuration/rules, read-only sandboxing and disabled shell, delegation,
+plugins, connectors and hooks. Host-mediated list/read/search and fixed read-only Git operations provide context.
+No model-supplied command is executed. Older Codex versions lacking the required switches fail closed; unsupported
+harnesses are rejected. Authentication uses the installed Codex login. `--model default` uses Codex's built-in default
+because user configuration is isolated.
+
+Only the host can save. Writes stay in the active top-level `prompts/` queue, matching the existing queue loader.
+Archives, templates, reusable context, agent guidance and ignored Markdown remain available for inspection only.
+The host validates every path, rejects links, devices and special Git/shell path characters, checks the
+preview against current contents, stages outside the queue, and publishes each file atomically. Emoji previews disable
+the shared scanner's cache writes. Staging and commit runtime directories also reject links. A requested Git commit
+is restricted to the session's PRD write set; preexisting
+dirty PRDs must be revised without `--commit`, and later external edits prevent the session commit. Git sync and push
+are opt-in. Ending a conversation never launches the implementation queue.
+
+The fixture tests cover conversations, boundaries, cancellation, Git isolation and local/packed CLI entrypoints.
+The package test builds the production entrypoint and asset layout, runs `npm pack`, extracts the archive, supplies
+installed dependencies, and runs the real CLI against a mocked Codex installation and terminal. No live model is used.
+
+The Codex invocation uses the documented [configuration isolation switches](https://learn.chatgpt.com/docs/developer-commands?surface=cli)
+and [tool configuration](https://learn.chatgpt.com/docs/config-file/config-reference). Required unsupported flags cause startup to fail.

package/src/cli/cli-commands/coder/planning/assertPlanningCommitSafe.ts

@@ -0,0 +1,23 @@
+import { NotAllowed } from '../../../../errors/NotAllowed';
+import { resolvePromptbookTemporaryPath } from '../../../../utils/filesystem/promptbookTemporaryPath';
+import { spaceTrim } from '../../../../utils/organization/spaceTrim';
+import { assertPlanningRuntimePath } from './assertPlanningRuntimePath';
+
+/**
+ * Protects the shared authoring Git helper's temporary directory and shell-quoted absolute message path.
+ * PRD paths themselves are checked separately by the write boundary before every save and commit.
+ * @private internal execution boundary of `coder plan`
+ */
+export function assertPlanningCommitSafe(projectPath: string): void {
+    if (/[$`%"\r\n]/u.test(projectPath)) {
+        throw new NotAllowed(
+            spaceTrim(
+                'The shared Git helper cannot safely quote this project path. Plan without `--commit` and commit the reviewed PRDs separately.',
+            ),
+        );
+    }
+    assertPlanningRuntimePath(
+        projectPath,
+        resolvePromptbookTemporaryPath(projectPath, 'ptbk-coder', 'commit-messages'),
+    );
+}

package/src/cli/cli-commands/coder/planning/assertPlanningPrdCommitScope.ts

@@ -0,0 +1,57 @@
+import { execFile } from 'child_process';
+// cspell:ignore fsmonitor pathspecs
+import { promisify } from 'util';
+import { NotAllowed } from '../../../../errors/NotAllowed';
+import { spaceTrim } from '../../../../utils/organization/spaceTrim';
+import type { PlanningChange } from './preparePlanningChanges';
+
+/**
+ * Refuses to mix prior or concurrent user edits into a PRD that this session intends to commit.
+ * After the first save, the session's exact saved text is the baseline for subsequent revisions.
+ * @private internal execution boundary of `coder plan`
+ */
+export async function assertPlanningPrdCommitScope(
+    projectPath: string,
+    changes: ReadonlyArray<PlanningChange>,
+    savedContents: ReadonlyMap<string, string>,
+    preexistingChangedPaths: ReadonlySet<string>,
+): Promise<void> {
+    for (const change of changes) {
+        if (preexistingChangedPaths.has(change.path)) {
+            throw new NotAllowed(
+                spaceTrim(
+                    `\`${change.path}\` already had user changes before this --commit session. Restart without --commit to revise it without committing those changes.`,
+                ),
+            );
+        }
+        if (change.before === null) continue;
+        let isChangedOutsideSession: boolean;
+        if (savedContents.has(change.path)) {
+            isChangedOutsideSession = savedContents.get(change.path) !== change.before;
+        } else {
+            const { stdout } = await promisify(execFile)(
+                'git',
+                [
+                    '--no-optional-locks',
+                    '--literal-pathspecs',
+                    '-c',
+                    'core.fsmonitor=false',
+                    'status',
+                    '--porcelain',
+                    '--untracked-files=all',
+                    '--',
+                    change.path,
+                ],
+                { cwd: projectPath, windowsHide: true, timeout: 10000, maxBuffer: 65536 },
+            );
+            isChangedOutsideSession = stdout.trim() !== '';
+        }
+        if (isChangedOutsideSession) {
+            throw new NotAllowed(
+                spaceTrim(
+                    `\`${change.path}\` has concurrent user changes outside this planning session. Restart without --commit to revise it without committing those changes.`,
+                ),
+            );
+        }
+    }
+}