@promptbook/cli 0.114.0-5 → 0.114.0-50

package/src/book-components/Chat/utils/timeoutToolCallPresentation.ts

@@ -2,12 +2,37 @@ import type { TODO_any } from '../../../utils/organization/TODO_any';
 import { formatToolCallDateTime } from './formatToolCallDateTime';
 import { formatToolCallTranslationTemplate } from './formatToolCallTranslationTemplate';
 
+/**
+ * Tool name of one scheduled wake-up, used by every producer of timeout chips.
+ *
+ * @private internal timeout-chat constant
+ */
+export const SET_TIMEOUT_TOOL_CALL_NAME = 'set_timeout';
+
+/**
+ * Tool name of one re-planned wake-up, used by every producer of timeout chips.
+ *
+ * @private internal timeout-chat constant
+ */
+export const UPDATE_TIMEOUT_TOOL_CALL_NAME = 'update_timeout';
+
+/**
+ * Tool name of one cancelled wake-up, used by every producer of timeout chips.
+ *
+ * @private internal timeout-chat constant
+ */
+export const CANCEL_TIMEOUT_TOOL_CALL_NAME = 'cancel_timeout';
+
 /**
  * Tool names handled by timeout-specific chat presentation.
  *
  * @private internal timeout-chat constant
  */
-const TIMEOUT_TOOL_NAMES = ['set_timeout', 'cancel_timeout'] as const;
+const TIMEOUT_TOOL_NAMES = [
+    SET_TIMEOUT_TOOL_CALL_NAME,
+    UPDATE_TIMEOUT_TOOL_CALL_NAME,
+    CANCEL_TIMEOUT_TOOL_CALL_NAME,
+] as const;
 
 /**
  * Milliseconds in one second.
@@ -412,9 +437,15 @@ function formatTimeoutDurationCompact(milliseconds: number): string {
 /**
  * Converts timeout duration into natural language sentence fragments.
  *
- * @private internal timeout-chat helper
+ * Shared by every timeout surface: the chat chips, the goal-chat planned messages of the Agents
+ * Server, and the planned-message prompt section of the agent-folder runner.
+ *
+ * @param milliseconds - Duration or repeat interval in milliseconds.
+ * @returns Label such as `5 minutes` or `1 hour 30 minutes`.
+ *
+ * @private internal utility of `<Chat/>` and the Agents Server planned messages
  */
-function formatTimeoutDurationHuman(milliseconds: number): string {
+export function formatTimeoutDurationHuman(milliseconds: number): string {
     const normalizedMilliseconds = Math.max(0, Math.floor(milliseconds));
     const totalSeconds = Math.max(1, Math.floor(normalizedMilliseconds / SECOND_IN_MILLISECONDS));
 

package/src/cli/$initializePromptbookCliProgram.ts

@@ -0,0 +1,89 @@
+import type { Command } from 'commander';
+import { CLAIM } from '../config';
+import { PROMPTBOOK_ENGINE_VERSION } from '../version';
+import { $initializeAboutCommand } from './cli-commands/about';
+import { $initializeAgentCommand } from './cli-commands/agent';
+import { $initializeAgentFolderCommand } from './cli-commands/agent-folder';
+import { $initializeAgentsServerCommand } from './cli-commands/agents-server';
+import { $initializeCoderCommand } from './cli-commands/coder';
+import { $initializeCoderInitCommand } from './cli-commands/coder/init';
+import { $initializeHelloCommand } from './cli-commands/hello';
+import { $initializeListModelsCommand } from './cli-commands/list-models';
+import { $initializeListScrapersCommand } from './cli-commands/list-scrapers';
+import { $initializeLoginCommand } from './cli-commands/login';
+import { $initializeMakeCommand } from './cli-commands/make';
+import { $initializePrettifyCommand } from './cli-commands/prettify';
+import { $initializeRunCommand } from './cli-commands/run';
+import { $initializeStartAgentsServerCommand } from './cli-commands/start-agents-server';
+import { $initializeStartPipelinesServerCommand } from './cli-commands/start-pipelines-server';
+import { $initializeTestCommand } from './cli-commands/test-command';
+import { $addGlobalOptionsToCommand } from './common/$addGlobalOptionsToCommand';
+import { $deprecateCliCommand } from './common/$deprecateCliCommand';
+
+/**
+ * Shared deprecation text for top-level CLI commands backed by the old pipeline system.
+ */
+const OLD_PIPELINE_SYSTEM_DEPRECATION_MESSAGE = 'This command is part of the old pipeline system.';
+
+/**
+ * Shared deprecation text for top-level CLI commands backed by the old pre-agent system.
+ */
+const OLD_SYSTEM_DEPRECATION_MESSAGE = 'This command is part of the old system.';
+
+/**
+ * Deprecation guidance for top-level `ptbk` commands that remain for compatibility.
+ */
+const DEPRECATED_TOP_LEVEL_COMMAND_MESSAGES: Readonly<Record<string, string>> = {
+    run: OLD_PIPELINE_SYSTEM_DEPRECATION_MESSAGE,
+    login: OLD_PIPELINE_SYSTEM_DEPRECATION_MESSAGE,
+    make: OLD_PIPELINE_SYSTEM_DEPRECATION_MESSAGE,
+    prettify: OLD_PIPELINE_SYSTEM_DEPRECATION_MESSAGE,
+    test: OLD_PIPELINE_SYSTEM_DEPRECATION_MESSAGE,
+    'list-models': OLD_SYSTEM_DEPRECATION_MESSAGE,
+    'list-scrapers': OLD_SYSTEM_DEPRECATION_MESSAGE,
+    'start-agents-server': 'Use `ptbk agents-server start` instead.',
+    'start-pipelines-server': OLD_PIPELINE_SYSTEM_DEPRECATION_MESSAGE,
+};
+
+/**
+ * Registers the CLI commands on a fresh Commander program without parsing arguments or running an action.
+ * Tests can configure output and exit handling before registration, so subcommands inherit those settings.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export function $initializePromptbookCliProgram(program: Command): void {
+    program.name('promptbook');
+    program.alias('ptbk');
+    program.version(PROMPTBOOK_ENGINE_VERSION);
+    program.description(CLAIM);
+
+    // Commands are listed in registration order. Keep `coder` first and hide deprecated commands below.
+    $initializeCoderCommand(program);
+    $initializeCoderInitCommand(program);
+    $initializeAgentCommand(program);
+    $initializeAgentFolderCommand(program);
+    $initializeAgentsServerCommand(program);
+    $initializeAboutCommand(program);
+    $initializeHelloCommand(program);
+    $initializeRunCommand(program);
+    $initializeLoginCommand(program);
+    $initializeMakeCommand(program);
+    $initializePrettifyCommand(program);
+    $initializeTestCommand(program);
+    $initializeListModelsCommand(program);
+    $initializeListScrapersCommand(program);
+    $initializeStartAgentsServerCommand(program);
+    $initializeStartPipelinesServerCommand(program);
+
+    for (const command of program.commands) {
+        const deprecationMessage = DEPRECATED_TOP_LEVEL_COMMAND_MESSAGES[command.name()];
+
+        if (deprecationMessage !== undefined) {
+            $deprecateCliCommand(command, deprecationMessage);
+        }
+    }
+
+    program.commands.forEach($addGlobalOptionsToCommand);
+}
+
+// Note: [🟡] Code for CLI command registration [$initializePromptbookCliProgram](src/cli/$initializePromptbookCliProgram.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/agent/chat.ts

@@ -1,3 +1,9 @@
+import {
+    addProjectPathOption,
+    addProjectContextOption,
+    normalizeProjectCliOptions,
+    resolveProjectDirectory,
+} from '../common/projectCliOptions';
 import type {
     Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
 } from 'commander';
@@ -32,10 +38,13 @@ export function $initializeAgentChatCommand(program: Program): $side_effect {
     command.requiredOption('--agent <agent-book-path>', 'Path to the agent .book file');
     addPromptRunnerSelectionOptions(command);
     addPromptRunnerRuntimeOptions(command);
-    command.option('--context <context-or-file>', 'Append extra context either inline or from a file path');
+    addProjectPathOption(command);
+    addProjectContextOption(command);
 
     command.action(
         handleActionErrors(async (cliOptions, commandProgram) => {
+            const projectOptions = normalizeProjectCliOptions(cliOptions);
+            const projectPath = await resolveProjectDirectory(projectOptions.projectDirectory);
             const options = cliOptions as AgentCommandCliOptions;
             const runnerOptions = normalizeAgentCommandRunnerOptions(options, commandProgram as Program);
             const { runAgentChat } = await import('../../../../scripts/run-agent-chat/runAgentChat');
@@ -43,7 +52,7 @@ export function $initializeAgentChatCommand(program: Program): $side_effect {
             await runAgentChat({
                 agentPath: resolveRequiredAgentPath(options),
                 context: options.context,
-                currentWorkingDirectory: process.cwd(),
+                currentWorkingDirectory: projectPath,
                 ...runnerOptions,
             });
         }),

package/src/cli/cli-commands/agent/exec.ts

@@ -1,3 +1,9 @@
+import {
+    addProjectPathOption,
+    addProjectContextOption,
+    normalizeProjectCliOptions,
+    resolveProjectDirectory,
+} from '../common/projectCliOptions';
 import type {
     Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
 } from 'commander';
@@ -37,10 +43,13 @@ export function $initializeAgentExecCommand(program: Program): $side_effect {
     command.requiredOption('--message <message>', 'User message to send to the agent');
     addPromptRunnerSelectionOptions(command);
     addPromptRunnerRuntimeOptions(command);
-    command.option('--context <context-or-file>', 'Append extra context either inline or from a file path');
+    addProjectPathOption(command);
+    addProjectContextOption(command);
 
     command.action(
         handleActionErrors(async (cliOptions, commandProgram) => {
+            const projectOptions = normalizeProjectCliOptions(cliOptions);
+            const projectPath = await resolveProjectDirectory(projectOptions.projectDirectory);
             const options = cliOptions as AgentCommandCliOptions;
             const runnerOptions = normalizeAgentCommandRunnerOptions(options, commandProgram as Program);
             const { runAgentExec } = await import('../../../../scripts/run-agent-chat/runAgentExec');
@@ -49,7 +58,7 @@ export function $initializeAgentExecCommand(program: Program): $side_effect {
                 agentPath: resolveRequiredAgentPath(options),
                 context: options.context,
                 message: resolveRequiredAgentMessage(options),
-                currentWorkingDirectory: process.cwd(),
+                currentWorkingDirectory: projectPath,
                 ...runnerOptions,
             });
         }),

package/src/cli/cli-commands/agent-folder/init.ts

@@ -1,3 +1,4 @@
+import { addProjectPathOption, normalizeProjectCliOptions, resolveProjectDirectory } from '../common/projectCliOptions';
 import type {
     Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
 } from 'commander';
@@ -36,9 +37,12 @@ export function $initializeAgentInitCommand(program: Program): $side_effect {
         `),
     );
 
+    addProjectPathOption(command);
     command.action(
-        handleActionErrors(async () => {
-            const summary = await initializeAgentProjectConfiguration(process.cwd());
+        handleActionErrors(async (cliOptions) => {
+            const projectOptions = normalizeProjectCliOptions(cliOptions);
+            const projectPath = await resolveProjectDirectory(projectOptions.projectDirectory);
+            const summary = await initializeAgentProjectConfiguration(projectPath);
             printAgentInitializationSummary(summary);
         }),
     );

package/src/cli/cli-commands/agent-folder/initializeAgentRunnerCommand.ts

@@ -1,3 +1,4 @@
+import { addProjectPathOption, normalizeProjectCliOptions, resolveProjectDirectory } from '../common/projectCliOptions';
 import colors from 'colors';
 import type {
     Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
@@ -61,12 +62,18 @@ export function $initializeAgentRunnerCommand(
 
     addPromptRunnerSelectionOptions(command);
     addPromptRunnerExecutionOptions(command);
+    addProjectPathOption(command);
     options.configureCommand?.(command);
 
     command.action(
         handleActionErrors(
             async (cliOptions) => {
-                const runOptions = createAgentRunOptionsFromCliOptions(cliOptions as AgentRunCliOptions);
+                const projectOptions = normalizeProjectCliOptions(cliOptions);
+                const projectPath = await resolveProjectDirectory(projectOptions.projectDirectory);
+                const runOptions = {
+                    ...createAgentRunOptionsFromCliOptions(cliOptions as AgentRunCliOptions),
+                    projectPath,
+                };
                 const execute = await options.loadExecutor();
 
                 if (options.executionMode === 'watch') {
@@ -76,7 +83,7 @@ export function $initializeAgentRunnerCommand(
 
                     await runPersistentAgentWatch({
                         commandDisplayName: `ptbk agent-folder ${options.commandName}`,
-                        logDirectoryPath: process.cwd(),
+                        logDirectoryPath: projectPath,
                         runWatch: async () => {
                             await execute(runOptions);
                         },

package/src/cli/cli-commands/agent-folder.ts

@@ -1,9 +1,9 @@
-import colors from 'colors';
 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 { $requireCliSubcommand } from '../common/$requireCliSubcommand';
 import { $initializeAgentInitCommand } from './agent-folder/init';
 import { $initializeAgentRunMultipleCommand } from './agent-folder/runMultiple';
 import { $initializeAgentRunCommand } from './agent-folder/run';
@@ -41,11 +41,7 @@ export function $initializeAgentFolderCommand(program: Program): $side_effect {
     $initializeAgentRunCommand(agentFolderCommand);
     $initializeAgentRunMultipleCommand(agentFolderCommand);
 
-    agentFolderCommand.action(() => {
-        console.info(colors.yellow('Please specify a subcommand.'));
-        console.info('');
-        agentFolderCommand.help();
-    });
+    $requireCliSubcommand(agentFolderCommand);
 }
 
 // Note: [🟡] Code for CLI command [agent-folder](src/cli/cli-commands/agent-folder.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/agent.ts

@@ -1,9 +1,9 @@
-import colors from 'colors';
 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 { $requireCliSubcommand } from '../common/$requireCliSubcommand';
 import { $initializeAgentChatCommand } from './agent/chat';
 import { $initializeAgentExecCommand } from './agent/exec';
 
@@ -33,11 +33,7 @@ export function $initializeAgentCommand(program: Program): $side_effect {
     $initializeAgentChatCommand(agentCommand);
     $initializeAgentExecCommand(agentCommand);
 
-    agentCommand.action(() => {
-        console.info(colors.yellow('Please specify a subcommand.'));
-        console.info('');
-        agentCommand.help();
-    });
+    $requireCliSubcommand(agentCommand);
 }
 
 // Note: [🟡] Code for CLI command [agent](src/cli/cli-commands/agent.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/agents-server/startAgentsServer/createLocalAgentRunOptions.ts

@@ -17,7 +17,7 @@ export function createLocalAgentRunOptions(
         noUi: options.noUi,
         thinkingLevel: options.thinkingLevel,
         noCommit: true,
-        ignoreGitChanges: true,
+        gitChanges: 'ignore',
         normalizeLineEndings: false,
         allowCredits: options.allowCredits,
         autoPush: false,

package/src/cli/cli-commands/agents-server.ts

@@ -1,9 +1,9 @@
-import colors from 'colors';
 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 { $requireCliSubcommand } from '../common/$requireCliSubcommand';
 import { $initializeAgentsServerInitCommand } from './agents-server/init';
 import {
     $initializeAgentsServerBuildCommand,
@@ -35,11 +35,7 @@ export function $initializeAgentsServerCommand(program: Program): $side_effect {
     $initializeAgentsServerInitCommand(agentsServerCommand);
     $initializeAgentsServerStartCommand(agentsServerCommand);
 
-    agentsServerCommand.action(() => {
-        console.info(colors.yellow('Please specify a subcommand.'));
-        console.info('');
-        agentsServerCommand.help();
-    });
+    $requireCliSubcommand(agentsServerCommand);
 }
 
 // Note: [🟡] Code for CLI command [agents-server](src/cli/cli-commands/agents-server.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/coder/$ensureCoderHarnessGitignoreRules.ts

@@ -0,0 +1,54 @@
+import colors from 'colors';
+import type { PromptRunnerHarnessName } from '../common/promptRunnerCliOptions';
+import type { NormalizedQuestionsCliOptions } from '../common/questionsCliOptions';
+import { $askForConfirmation } from '../common/$askForConfirmation';
+import { getHarnessDefinition } from '../common/harness/HarnessDefinition';
+import { ensureCoderGitignoreRules, getMissingCoderHarnessGitignoreRules } from './ensureCoderGitignoreFile';
+
+/**
+ * Offers to add missing project-local ignore rules for the selected coding harness.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it may ask the user and update `.gitignore`.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+export async function $ensureCoderHarnessGitignoreRules(
+    projectPath: string,
+    harnessName: PromptRunnerHarnessName | undefined,
+    questionsOptions: NormalizedQuestionsCliOptions,
+): Promise<void> {
+    if (harnessName === undefined) {
+        return;
+    }
+
+    const missingRules = await getMissingCoderHarnessGitignoreRules(projectPath, [harnessName]);
+
+    if (missingRules.length === 0) {
+        return;
+    }
+
+    const { label } = getHarnessDefinition(harnessName);
+    const formattedRules = formatGitignoreRules(missingRules);
+    const entryLabel = missingRules.length === 1 ? 'entry' : 'entries';
+    const isAdditionApproved = await $askForConfirmation(
+        `Add the missing ${label} ignore ${entryLabel} ${formattedRules} to \`.gitignore\` now?`,
+        questionsOptions,
+    );
+
+    if (!isAdditionApproved) {
+        console.info(colors.gray(`Skipped, add ${formattedRules} to \`.gitignore\` manually.`));
+        return;
+    }
+
+    await ensureCoderGitignoreRules(projectPath, missingRules);
+    console.info(colors.gray(`✔ Added ${formattedRules} to \`.gitignore\`.`));
+}
+
+/**
+ * Formats one or more `.gitignore` rules for a terminal confirmation message.
+ */
+function formatGitignoreRules(rules: ReadonlyArray<string>): string {
+    return rules.map((rule) => `\`${rule}\``).join(', ');
+}
+
+// Note: [🟡] Code for coder harness gitignore prompts [$ensureCoderHarnessGitignoreRules](src/cli/cli-commands/coder/$ensureCoderHarnessGitignoreRules.ts) should never be published outside of `@promptbook/cli`

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

@@ -0,0 +1,35 @@
+/**
+ * Supported values of the `--git-changes` option, which decides what happens with a dirty working tree.
+ *
+ * - `fail` — refuse to start while the working tree has uncommitted changes
+ * - `ignore` — start anyway and leave the uncommitted changes where they are
+ * - `continue` — resume the single prompt which was left in the middle of its implementation
+ *
+ * @private internal shared utility of `ptbk coder run`
+ */
+export const GIT_CHANGES_MODE_VALUES = ['fail', 'ignore', 'continue'] as const;
+
+/**
+ * Behavior requested for a working tree which has uncommitted changes.
+ *
+ * @private internal shared utility of `ptbk coder run`
+ */
+export type GitChangesMode = (typeof GIT_CHANGES_MODE_VALUES)[number];
+
+/**
+ * Mode applied when `--git-changes` is not used at all.
+ *
+ * @private internal shared utility of `ptbk coder run`
+ */
+export const DEFAULT_GIT_CHANGES_MODE: GitChangesMode = 'fail';
+
+/**
+ * Checks whether a value is a supported `--git-changes` mode.
+ *
+ * @private internal shared utility of `ptbk coder run`
+ */
+export function isGitChangesMode(value: string): value is GitChangesMode {
+    return GIT_CHANGES_MODE_VALUES.includes(value as GitChangesMode);
+}
+
+// Note: [🟡] Code for CLI command [run](src/cli/cli-commands/coder/run.ts) should never be published outside of `@promptbook/cli`

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

@@ -16,12 +16,23 @@ import {
     CODER_GIT_SYNC_DESCRIPTION,
     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 {
+    addQuestionsOption,
+    normalizeQuestionsCliOptions,
+    QUESTIONS_DESCRIPTION,
+    type NormalizedQuestionsCliOptions,
+    type QuestionsCliOptions,
+} from '../common/questionsCliOptions';
 import {
     buildCoderPromptSection,
     getDefaultCoderPromptTemplateDefinitions,
     PROMPTS_DIRECTORY_PATH,
     resolveCoderPromptTemplate,
+    type ResolvedCoderPromptTemplate,
 } from './boilerplateTemplates';
 
 /**
@@ -66,6 +77,8 @@ export function $initializeCoderAddCommand(program: Program): $side_effect {
                 - \`ptbk coder add\`
 
                 ${block(CODER_GIT_SYNC_DESCRIPTION)}
+
+                ${block(QUESTIONS_DESCRIPTION)}
             `,
         ),
     );
@@ -88,25 +101,35 @@ export function $initializeCoderAddCommand(program: Program): $side_effect {
         `),
     );
     addCoderGitSyncOptions(command);
+    addQuestionsOption(command);
+
+    addWorkspaceRepositoryOptions(command);
 
     command.action(
         handleActionErrors(async (descriptionArgument: string | undefined, cliOptions) => {
+            const projectOptions = normalizeProjectCliOptions(cliOptions);
             const { priority, template: templateOption } = cliOptions as {
                 readonly priority: number;
                 readonly template?: string;
             } & CoderGitSyncCliOptions;
 
             const gitSync = normalizeCoderGitSyncCliOptions(cliOptions as CoderGitSyncCliOptions);
-            const projectPath = process.cwd();
+            const questionsOptions = normalizeQuestionsCliOptions(cliOptions as QuestionsCliOptions);
+            const workspace = await $preflightWorkspaceRepository({
+                ...projectOptions,
+                policy: 'mutate',
+                ...questionsOptions,
+            });
+            const { projectPath } = workspace;
 
-            const description = await resolveCoderPromptDescription(descriptionArgument);
+            const description = await resolveCoderPromptDescription(descriptionArgument, questionsOptions);
 
             // Note: Import the git synchronization dynamically to keep the CLI fast for runs without `--commit`
-            const { $commitCoderChanges, $pullCoderChanges } = await import(
+            const { $commitCoderChanges, $startCoderGitSync } = await import(
                 '../../../../scripts/run-codex-prompts/git/coderGitSync'
             );
 
-            await $pullCoderChanges({ gitSync, projectPath });
+            const commitScope = await $startCoderGitSync({ gitSync, workspace });
 
             const { /* filePath,*/ emojiTag } = await addCoderPrompt({
                 projectPath,
@@ -117,7 +140,7 @@ export function $initializeCoderAddCommand(program: Program): $side_effect {
 
             await $commitCoderChanges({
                 gitSync,
-                projectPath,
+                commitScope,
                 commitMessage: `${emojiTag} Add prompt`,
             });
         }),
@@ -150,12 +173,46 @@ export async function addCoderPrompt({
     description,
     priority,
     templateOption,
+    promptTemplate,
 }: {
     readonly projectPath: string;
     readonly description: string;
     readonly priority: number;
     readonly templateOption?: string;
+    /** Internal authoring workflows may supply their own bounded instructions instead of the feature template. */
+    readonly promptTemplate?: ResolvedCoderPromptTemplate;
 }): Promise<AddCoderPromptResult> {
+    mkdirSync(join(projectPath, PROMPTS_DIRECTORY_PATH), { recursive: true });
+    const prepared = await prepareCoderPrompt({ projectPath, description, priority, templateOption, promptTemplate });
+    writeFileSync(join(projectPath, prepared.filePath), prepared.content, { encoding: 'utf-8', flag: 'wx' });
+    console.info(colors.green(`✓ Added prompt ${prepared.emojiTag} in ${prepared.filePath}`));
+    return { filePath: prepared.filePath, emojiTag: prepared.emojiTag };
+}
+
+/**
+ * Prepares a numbered, emoji-tagged prompt for preview without writing the prompt file.
+ * The offset reserves consecutive identities when a planning turn proposes several files.
+ *
+ * @private internal utility shared by `coder add` and `coder plan`
+ */
+export async function prepareCoderPrompt({
+    projectPath,
+    description,
+    priority,
+    templateOption,
+    numberOffset = 0,
+    reservedEmojiTag,
+    promptTemplate: providedPromptTemplate,
+}: {
+    readonly projectPath: string;
+    readonly description: string;
+    readonly priority: number;
+    readonly templateOption?: string;
+    readonly numberOffset?: number;
+    readonly reservedEmojiTag?: string;
+    /** Shared repair authoring preserves numbering and tags without appending ordinary implementation instructions. */
+    readonly promptTemplate?: ResolvedCoderPromptTemplate;
+}): Promise<AddCoderPromptResult & { readonly content: string }> {
     const normalizedDescription = description.trim();
     if (normalizedDescription === '') {
         throw new ParseError(
@@ -177,9 +234,9 @@ export async function addCoderPrompt({
     );
 
     const promptsDirectory = join(projectPath, PROMPTS_DIRECTORY_PATH);
-    mkdirSync(promptsDirectory, { recursive: true });
 
-    const promptTemplate = await resolveCoderPromptTemplate({ projectPath, templateOption });
+    const promptTemplate =
+        providedPromptTemplate ?? (await resolveCoderPromptTemplate({ projectPath, templateOption }));
 
     const promptNumbering = await getPromptNumbering({
         promptsDir: promptsDirectory,
@@ -187,9 +244,18 @@ export async function addCoderPrompt({
         ignoreGlobs: ['**/node_modules/**'],
     });
 
-    const { selectedEmojis } = await getFreshPromptEmojiTags({ count: 1, rootDir: projectPath });
-    const emoji = selectedEmojis[0]!;
-    const emojiTag = formatPromptEmojiTag(emoji);
+    const emojiTag =
+        reservedEmojiTag ||
+        formatPromptEmojiTag(
+            (
+                await getFreshPromptEmojiTags({
+                    count: 1,
+                    rootDir: projectPath,
+                    // Bounded internal authoring, such as check repair, needs no project-wide scan cache artifact.
+                    ...(providedPromptTemplate ? { isCacheWriteEnabled: false } : {}),
+                })
+            ).selectedEmojis[0]!,
+        );
 
     const [firstDescriptionLine, ...remainingDescriptionLines] = normalizedDescription.split('\n');
     const title = (firstDescriptionLine ?? '').trim();
@@ -205,15 +271,13 @@ export async function addCoderPrompt({
     });
 
     const slug = buildAddPromptSlug(promptTemplate.slugPrefix, title);
-    const filename = buildPromptFilename(promptNumbering.datePrefix, promptNumbering.startNumber, slug);
+    const filename = buildPromptFilename(
+        promptNumbering.datePrefix,
+        promptNumbering.startNumber + numberOffset * promptNumbering.step,
+        slug,
+    );
     const filePath = join(PROMPTS_DIRECTORY_PATH, filename);
-    const absoluteFilePath = join(projectPath, filePath);
-
-    writeFileSync(absoluteFilePath, `${section}\n`, 'utf-8');
-
-    console.info(colors.green(`✓ Added prompt ${emojiTag} in ${filePath}`));
-
-    return { filePath, emojiTag };
+    return { filePath, emojiTag, content: `${section}\n` };
 }
 
 /**
@@ -221,7 +285,10 @@ export async function addCoderPrompt({
  *
  * @private internal utility of `coder add` command
  */
-async function resolveCoderPromptDescription(descriptionArgument: string | undefined): Promise<string> {
+async function resolveCoderPromptDescription(
+    descriptionArgument: string | undefined,
+    { isAskingQuestionsEnabled }: NormalizedQuestionsCliOptions,
+): Promise<string> {
     if (descriptionArgument !== undefined && descriptionArgument.trim() !== '') {
         return descriptionArgument.trim();
     }
@@ -243,6 +310,17 @@ async function resolveCoderPromptDescription(descriptionArgument: string | undef
         return standardInputDescription;
     }
 
+    if (!isAskingQuestionsEnabled) {
+        throw new ParseError(
+            spaceTrim(`
+                Cannot add a prompt without a description.
+
+                The description can not be typed interactively because \`--no-questions\` is used — provide it as an argument or pipe it through stdin instead:
+                - \`ptbk coder add --no-questions "some new feature"\`
+            `),
+        );
+    }
+
     const { default: prompts } = await loadPromptsModule();
     const response = await prompts({
         type: 'text',