@promptbook/cli 0.112.0-99 → 0.112.0

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

@@ -8,6 +8,10 @@ import {
     PROMPTS_TEMPLATES_DIRECTORY_PATH,
 } from './boilerplateTemplates';
 import { ensureCoderEnvFile } from './ensureCoderEnvFile';
+import {
+    CODER_AGENTS_DIRECTORY_PATH,
+    ensureCoderDeveloperAgentFile,
+} from './ensureCoderDeveloperAgentFile';
 import { ensureCoderGitignoreFile } from './ensureCoderGitignoreFile';
 import { ensureCoderMarkdownFile } from './ensureCoderMarkdownFile';
 import { ensureCoderPackageJsonFile } from './ensureCoderPackageJsonFile';
@@ -25,6 +29,8 @@ export type CoderInitializationSummary = {
     readonly promptsDoneDirectoryStatus: InitializationStatus;
     readonly promptsTemplatesDirectoryStatus: InitializationStatus;
     readonly promptTemplateFileStatuses: ReadonlyArray<EnsuredCoderPromptTemplateFile>;
+    readonly agentsDirectoryStatus: InitializationStatus;
+    readonly developerAgentFileStatus: InitializationStatus;
     readonly agentsFileStatus: InitializationStatus;
     readonly agentCodingFileStatus: InitializationStatus;
     readonly envFileStatus: InitializationStatus;
@@ -44,6 +50,8 @@ export async function initializeCoderProjectConfiguration(projectPath: string):
     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,
@@ -66,6 +74,8 @@ export async function initializeCoderProjectConfiguration(projectPath: string):
         promptsDoneDirectoryStatus,
         promptsTemplatesDirectoryStatus,
         promptTemplateFileStatuses,
+        agentsDirectoryStatus,
+        developerAgentFileStatus,
         agentsFileStatus,
         agentCodingFileStatus,
         envFileStatus,

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

@@ -2,6 +2,7 @@ import colors from 'colors';
 import { AGENT_CODING_FILE_PATH } from './agentCodingFile';
 import { AGENTS_FILE_PATH } from './agentsFile';
 import type { InitializationStatus } from './boilerplateTemplates';
+import { CODER_DEVELOPER_AGENT_FILE_PATH } from './ensureCoderDeveloperAgentFile';
 import { formatDisplayPath } from './formatDisplayPath';
 import type { CoderInitializationSummary } from './initializeCoderProjectConfiguration';
 
@@ -23,6 +24,8 @@ export function printInitializationSummary(summary: CoderInitializationSummary):
         );
     }
 
+    printInitializationStatusLine('agents/', summary.agentsDirectoryStatus);
+    printInitializationStatusLine(CODER_DEVELOPER_AGENT_FILE_PATH, summary.developerAgentFileStatus);
     printInitializationStatusLine(AGENTS_FILE_PATH, summary.agentsFileStatus);
     printInitializationStatusLine(AGENT_CODING_FILE_PATH, summary.agentCodingFileStatus);
     printInitializationStatusLine('.env', summary.envFileStatus);

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

@@ -11,6 +11,10 @@ import {
     normalizePromptRunnerCliOptions,
     PROMPT_RUNNER_DESCRIPTION,
 } from '../common/promptRunnerCliOptions';
+import {
+    DEFAULT_WAIT_AFTER_ERROR_MS,
+    parseOptionalWaitDuration,
+} from './waitOptions';
 
 /**
  * Initializes `coder run` command for Promptbook CLI utilities
@@ -42,6 +46,10 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
 
     command.option('--dry-run', 'Print unwritten prompts without executing', false);
     addPromptRunnerSelectionOptions(command);
+    command.option(
+        '--agent <agent-book-path>',
+        'Path to a .book file whose compiled system message is prepended to each coding prompt',
+    );
     command.option(
         '--context <context-or-file>',
         'Append extra instructions either inline or from a file path relative to the current project',
@@ -57,7 +65,33 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
     );
     addPromptRunnerExecutionOptions(command);
     command.option('--priority <minimum-priority>', 'Filter prompts by minimum priority level', parseIntOption, 0);
-    command.option('--no-wait', 'Skip user prompts between processing');
+    command.option(
+        '--wait-after-prompt <duration>',
+        spaceTrim(`
+            Wait this long after each prompt has been implemented, verified and committed before starting the next prompt.
+            Accepts durations like 1h, 30m, 5s. Defaults to 0 (no wait).
+        `),
+    );
+    command.option(
+        '--wait-between-prompts <duration>',
+        spaceTrim(`
+            Pace prompts so that each next prompt starts at least this long after the previous one began.
+            If the previous prompt already took longer than this, the next prompt starts immediately.
+            Accepts durations like 1h, 30m, 5s. Defaults to 0 (no pacing).
+        `),
+    );
+    command.option(
+        '--wait-after-error <duration>',
+        spaceTrim(`
+            Wait this long before retrying a prompt after an error occurs (up to 3 retries before giving up).
+            Accepts durations like 1h, 30m, 5s. Defaults to 10m.
+        `),
+    );
+    // Note: --no-auto disables the default auto behaviour and waits for user confirmation before each prompt
+    command.option(
+        '--no-auto',
+        'Wait for user confirmation before each prompt instead of running automatically through the queue',
+    );
     command.option(
         '--auto-migrate',
         'Run testing-server database migrations automatically after each successfully processed prompt',
@@ -69,31 +103,62 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
 
     command.action(
         handleActionErrors(async (cliOptions) => {
-            const { dryRun, context, test, preserveLogs, priority, wait, autoMigrate, allowDestructiveAutoMigrate } =
-                cliOptions as {
-                    readonly dryRun: boolean;
-                    readonly context?: string;
-                    readonly test?: string | string[];
-                    readonly preserveLogs: boolean;
-                    readonly priority: number;
-                    readonly wait: boolean;
-                    readonly autoMigrate: boolean;
-                    readonly allowDestructiveAutoMigrate: boolean;
-                } & PromptRunnerCliOptions;
+            const {
+                dryRun,
+                agent,
+                context,
+                test,
+                preserveLogs,
+                priority,
+                waitAfterPrompt: waitAfterPromptValue,
+                waitBetweenPrompts: waitBetweenPromptsValue,
+                waitAfterError: waitAfterErrorValue,
+                auto,
+                autoMigrate,
+                allowDestructiveAutoMigrate,
+            } = cliOptions as {
+                readonly dryRun: boolean;
+                readonly agent?: string;
+                readonly context?: string;
+                readonly test?: string | string[];
+                readonly preserveLogs: boolean;
+                readonly priority: number;
+                readonly waitAfterPrompt?: string;
+                readonly waitBetweenPrompts?: string;
+                readonly waitAfterError?: string;
+                readonly auto: boolean;
+                readonly autoMigrate: boolean;
+                readonly allowDestructiveAutoMigrate: boolean;
+            } & PromptRunnerCliOptions;
 
             const testCommand = normalizeCommandOptionValue(test);
             const runnerOptions = normalizePromptRunnerCliOptions(cliOptions as PromptRunnerCliOptions, {
                 isAgentRequired: !dryRun,
             });
 
+            // [1] Parse the wait options and --no-auto:
+            //   default: run automatically through the queue (no waiting between prompts)
+            //   --no-auto: wait for user confirmation before each prompt (interactive mode)
+            //   --wait-after-prompt: pause after a successful round before starting the next prompt
+            //   --wait-between-prompts: pace from start of one prompt to start of next
+            //   --wait-after-error: wait before retrying after an error (default 10m)
+            const waitForUser = !auto;
+            const waitAfterPrompt = parseOptionalWaitDuration(waitAfterPromptValue, 0);
+            const waitBetweenPrompts = parseOptionalWaitDuration(waitBetweenPromptsValue, 0);
+            const waitAfterError = parseOptionalWaitDuration(waitAfterErrorValue, DEFAULT_WAIT_AFTER_ERROR_MS);
+
             // Convert commander options to RunOptions format
             const runOptions = {
                 dryRun,
-                waitForUser: wait,
+                waitForUser,
+                waitAfterPrompt,
+                waitBetweenPrompts,
+                waitAfterError,
                 noCommit: runnerOptions.noCommit,
                 ignoreGitChanges: runnerOptions.ignoreGitChanges,
                 agentName: runnerOptions.agentName,
                 model: runnerOptions.model,
+                agent,
                 context,
                 testCommand,
                 preserveLogs,

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

@@ -0,0 +1,259 @@
+import colors from 'colors';
+import { Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */ } from 'commander';
+import { Option } from 'commander';
+import { spaceTrim } from 'spacetrim';
+import { NETWORK_LIMITS } from '../../../constants';
+import { assertsError } from '../../../errors/assertsError';
+import { NotAllowed } from '../../../errors/NotAllowed';
+import type { number_port } from '../../../types/number_positive';
+import type { $side_effect } from '../../../utils/organization/$side_effect';
+import { handleActionErrors } from '../common/handleActionErrors';
+import type { PromptRunnerCliOptions } from '../common/promptRunnerCliOptions';
+import {
+    addPromptRunnerExecutionOptions,
+    addPromptRunnerSelectionOptions,
+    normalizePromptRunnerCliOptions,
+    PROMPT_RUNNER_DESCRIPTION,
+} from '../common/promptRunnerCliOptions';
+import { DEFAULT_WAIT_AFTER_ERROR_MS, parseOptionalWaitDuration } from './waitOptions';
+
+/**
+ * Default port used by `ptbk coder server`.
+ *
+ * @private internal constant of `ptbk coder server`
+ */
+const DEFAULT_CODER_SERVER_PORT = '4441';
+
+/**
+ * Initializes `coder server` command for Promptbook CLI utilities.
+ *
+ * Runs the same prompt processing logic as `ptbk coder run` but keeps the process alive
+ * and serves a kanban web UI on the configured port.
+ *
+ * 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 $initializeCoderServerCommand(program: Program): $side_effect {
+    const command = program.command('server');
+    command.description(
+        spaceTrim(`
+            Start a coder server that watches for prompts and serves a kanban web UI
+
+            ${PROMPT_RUNNER_DESCRIPTION}
+
+            Features:
+            - Runs the same prompt processing as \`ptbk coder run\`
+            - Does not exit when all prompts are done; polls for new prompt files instead
+            - Serves a kanban board at http://localhost:<port> for visual progress tracking
+            - Allows editing prompt files directly from the browser (Trello-style)
+            - Play / pause button in the browser stays in sync with the CLI pause state
+            - Press "p" in the terminal to pause / resume (same as \`ptbk coder run\`)
+        `),
+    );
+
+    command.addOption(
+        new Option('--port <port>', 'Port to start the coder server on')
+            .env('PTBK_CODER_SERVER_PORT')
+            .default(DEFAULT_CODER_SERVER_PORT),
+    );
+    command.option('--dry-run', 'Print unwritten prompts without executing', false);
+    addPromptRunnerSelectionOptions(command);
+    command.option(
+        '--agent <agent-book-path>',
+        'Path to a .book file whose compiled system message is prepended to each coding prompt',
+    );
+    command.option(
+        '--context <context-or-file>',
+        'Append extra instructions either inline or from a file path relative to the current project',
+    );
+    command.option(
+        '--test <test-command...>',
+        'Run a verification command after each prompt; quote it when the command itself contains top-level flags',
+    );
+    command.option(
+        '--preserve-logs',
+        'Keep generated temp prompt/log artifacts after successful rounds for debugging and analytics',
+        false,
+    );
+    addPromptRunnerExecutionOptions(command);
+    command.option('--priority <minimum-priority>', 'Filter prompts by minimum priority level', parseIntOption, 0);
+    command.option(
+        '--wait-after-prompt <duration>',
+        spaceTrim(`
+            Wait this long after each prompt has been implemented, verified and committed before starting the next prompt.
+            Accepts durations like 1h, 30m, 5s. Defaults to 0 (no wait).
+        `),
+    );
+    command.option(
+        '--wait-between-prompts <duration>',
+        spaceTrim(`
+            Pace prompts so that each next prompt starts at least this long after the previous one began.
+            If the previous prompt already took longer than this, the next prompt starts immediately.
+            Accepts durations like 1h, 30m, 5s. Defaults to 0 (no pacing).
+        `),
+    );
+    command.option(
+        '--wait-after-error <duration>',
+        spaceTrim(`
+            Wait this long before retrying a prompt after an error occurs (up to 3 retries before giving up).
+            Accepts durations like 1h, 30m, 5s. Defaults to 10m.
+        `),
+    );
+    command.option(
+        '--no-auto',
+        'Wait for user confirmation before each prompt instead of running automatically through the queue',
+    );
+    command.option(
+        '--auto-migrate',
+        'Run testing-server database migrations automatically after each successfully processed prompt',
+    );
+    command.option(
+        '--allow-destructive-auto-migrate',
+        'Allow auto-migrate even when heuristic SQL safety check flags destructive pending migrations',
+    );
+
+    command.action(
+        handleActionErrors(async (cliOptions) => {
+            const {
+                port: rawPort,
+                dryRun,
+                agent,
+                context,
+                test,
+                preserveLogs,
+                priority,
+                waitAfterPrompt: waitAfterPromptValue,
+                waitBetweenPrompts: waitBetweenPromptsValue,
+                waitAfterError: waitAfterErrorValue,
+                auto,
+                autoMigrate,
+                allowDestructiveAutoMigrate,
+            } = cliOptions as {
+                readonly port: string;
+                readonly dryRun: boolean;
+                readonly agent?: string;
+                readonly context?: string;
+                readonly test?: string | string[];
+                readonly preserveLogs: boolean;
+                readonly priority: number;
+                readonly waitAfterPrompt?: string;
+                readonly waitBetweenPrompts?: string;
+                readonly waitAfterError?: string;
+                readonly auto: boolean;
+                readonly autoMigrate: boolean;
+                readonly allowDestructiveAutoMigrate: boolean;
+            } & PromptRunnerCliOptions;
+
+            const port = parseCoderServerPort(rawPort);
+            const testCommand = normalizeCommandOptionValue(test);
+            const runnerOptions = normalizePromptRunnerCliOptions(cliOptions as PromptRunnerCliOptions, {
+                isAgentRequired: !dryRun,
+            });
+
+            // [1] Parse the wait options and --no-auto (same logic as `coder run`)
+            const waitForUser = !auto;
+            const waitAfterPrompt = parseOptionalWaitDuration(waitAfterPromptValue, 0);
+            const waitBetweenPrompts = parseOptionalWaitDuration(waitBetweenPromptsValue, 0);
+            const waitAfterError = parseOptionalWaitDuration(waitAfterErrorValue, DEFAULT_WAIT_AFTER_ERROR_MS);
+
+            const runOptions = {
+                port,
+                dryRun,
+                waitForUser,
+                waitAfterPrompt,
+                waitBetweenPrompts,
+                waitAfterError,
+                noCommit: runnerOptions.noCommit,
+                ignoreGitChanges: runnerOptions.ignoreGitChanges,
+                agentName: runnerOptions.agentName,
+                model: runnerOptions.model,
+                agent,
+                context,
+                testCommand,
+                preserveLogs,
+                noUi: runnerOptions.noUi,
+                thinkingLevel: runnerOptions.thinkingLevel,
+                priority,
+                normalizeLineEndings: runnerOptions.normalizeLineEndings,
+                allowCredits: runnerOptions.allowCredits,
+                autoMigrate,
+                allowDestructiveAutoMigrate,
+                autoPush: runnerOptions.autoPush,
+                autoPull: runnerOptions.autoPull,
+            };
+
+            // Note: Import dynamically to avoid loading heavy dependencies until needed
+            const { runCodexPromptsServer } = await import(
+                '../../../../scripts/run-codex-prompts/main/runCodexPromptsServer'
+            );
+
+            try {
+                await runCodexPromptsServer(runOptions);
+            } catch (error) {
+                assertsError(error);
+                console.error(colors.bgRed(`${error.name}`));
+                console.error(colors.red(error.stack || error.message));
+                return process.exit(1);
+            }
+
+            return process.exit(0);
+        }),
+    );
+}
+
+/**
+ * Parses and validates the coder server port number.
+ *
+ * @private internal utility of `coder server` command
+ */
+function parseCoderServerPort(rawPort: string): number_port {
+    const port = Number.parseInt(rawPort, 10);
+
+    if (!Number.isInteger(port) || port <= 0 || port > NETWORK_LIMITS.MAX_PORT) {
+        throw new NotAllowed(
+            spaceTrim(`
+                Invalid coder server port: \`${rawPort}\`.
+
+                Use \`--port\` or \`PTBK_CODER_SERVER_PORT\` with an integer between \`1\` and \`${NETWORK_LIMITS.MAX_PORT}\`.
+            `),
+        );
+    }
+
+    return port as number_port;
+}
+
+/**
+ * Parses an integer option value.
+ *
+ * @private internal utility of `coder server` command
+ */
+function parseIntOption(value: string): number {
+    const parsed = parseInt(value, 10);
+    if (isNaN(parsed)) {
+        throw new Error(`Invalid number: ${value}`);
+    }
+    return parsed;
+}
+
+/**
+ * Joins one Commander option that may be parsed either as a single string or a variadic token array.
+ *
+ * @private internal utility of `coder server` command
+ */
+function normalizeCommandOptionValue(value: string | string[] | undefined): string | undefined {
+    if (value === undefined) {
+        return undefined;
+    }
+
+    const parts = Array.isArray(value) ? value : [value];
+    const normalizedValue = parts
+        .map((part) => part.trim())
+        .filter(Boolean)
+        .join(' ')
+        .trim();
+    return normalizedValue === '' ? undefined : normalizedValue;
+}
+
+// Note: [🟡] Code for CLI command [server](src/cli/cli-commands/coder/server.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/waitOptions.ts

@@ -0,0 +1,24 @@
+import { parseDuration } from '../../../../scripts/run-codex-prompts/common/parseDuration';
+
+/**
+ * Default wait duration applied before retrying a prompt round after an error (10 minutes).
+ *
+ * @private internal constant of `ptbk coder` wait handling
+ */
+export const DEFAULT_WAIT_AFTER_ERROR_MS = 10 * 60 * 1000;
+
+/**
+ * Parses an optional Commander duration string and returns the resolved milliseconds.
+ *
+ * Returns `defaultMs` when the flag was not provided or was provided without a non-empty value.
+ *
+ * @private internal utility of `ptbk coder` wait handling
+ */
+export function parseOptionalWaitDuration(value: string | undefined, defaultMs: number): number {
+    if (typeof value !== 'string' || value === '') {
+        return defaultMs;
+    }
+    return parseDuration(value);
+}
+
+// Note: [💞] Ignore a discrepancy between file name and entity name

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

@@ -6,9 +6,11 @@ import { spaceTrim } from 'spacetrim';
 import type { $side_effect } from '../../utils/organization/$side_effect';
 import { $initializeCoderFindFreshEmojiTagCommand } from './coder/find-fresh-emoji-tags';
 import { $initializeCoderFindRefactorCandidatesCommand } from './coder/find-refactor-candidates';
+import { $initializeCoderFindUnwrittenCommand } from './coder/find-unwritten';
 import { $initializeCoderGenerateBoilerplatesCommand } from './coder/generate-boilerplates';
 import { $initializeCoderInitCommand } from './coder/init';
 import { $initializeCoderRunCommand } from './coder/run';
+import { $initializeCoderServerCommand } from './coder/server';
 import { $initializeCoderVerifyCommand } from './coder/verify';
 
 /**
@@ -36,7 +38,9 @@ export function $initializeCoderCommand(program: Program): $side_effect {
             - init: Initialize coder configuration in current project
             - generate-boilerplates: Generate prompt boilerplate files
             - find-refactor-candidates: Find files that need refactoring
+            - find-unwritten: List prompt sections that still need to be authored
             - run: Run coding prompts with AI agents
+            - server: Start a long-running coder server with a kanban web UI
             - verify: Verify completed prompts
             - find-fresh-emoji-tags: Find unused emoji tags
         `),
@@ -46,7 +50,9 @@ export function $initializeCoderCommand(program: Program): $side_effect {
     $initializeCoderInitCommand(coderCommand);
     $initializeCoderGenerateBoilerplatesCommand(coderCommand);
     $initializeCoderFindRefactorCandidatesCommand(coderCommand);
+    $initializeCoderFindUnwrittenCommand(coderCommand);
     $initializeCoderRunCommand(coderCommand);
+    $initializeCoderServerCommand(coderCommand);
     $initializeCoderVerifyCommand(coderCommand);
     $initializeCoderFindFreshEmojiTagCommand(coderCommand);
 

package/src/cli/cli-commands/common/promptRunnerCliOptions.ts

@@ -6,48 +6,28 @@ import {
 import { spaceTrim } from 'spacetrim';
 import type { ThinkingLevel } from '../coder/ThinkingLevel';
 import { THINKING_LEVEL_VALUES } from '../coder/ThinkingLevel';
+import {
+    CLI_AGENT_HARNESS_NAMES,
+    PTBK_HARNESS_ENV,
+    PTBK_MODEL_ENV,
+    PTBK_THINKING_LEVEL_ENV,
+} from '../../../book-3.0/cliAgentEnv';
 
-/**
- * Runner identifiers supported by Promptbook CLI agent orchestration commands.
- *
- * @private internal utility of `promptbookCli`
- */
-export const PROMPT_RUNNER_AGENT_NAMES = [
-    'openai-codex',
-    'github-copilot',
-    'cline',
-    'claude-code',
-    'opencode',
-    'gemini',
-] as const;
-
-/**
- * Environment variable used as the default runner identifier when `--agent` is omitted.
- *
- * @private internal utility of `promptbookCli`
- */
-export const PTBK_AGENT_ENV = 'PTBK_AGENT';
-
-/**
- * Environment variable used as the default runner model when `--model` is omitted.
- *
- * @private internal utility of `promptbookCli`
- */
-export const PTBK_MODEL_ENV = 'PTBK_MODEL';
+export { PTBK_HARNESS_ENV, PTBK_MODEL_ENV, PTBK_THINKING_LEVEL_ENV };
 
 /**
- * Environment variable used as the default runner thinking level when `--thinking-level` is omitted.
+ * Runner identifiers supported by Promptbook CLI agent orchestration commands.
  *
  * @private internal utility of `promptbookCli`
  */
-export const PTBK_THINKING_LEVEL_ENV = 'PTBK_THINKING_LEVEL';
+export const PROMPT_RUNNER_HARNESS_NAMES = CLI_AGENT_HARNESS_NAMES;
 
 /**
  * Runner identifier supported by Promptbook CLI agent orchestration commands.
  *
  * @private internal utility of `promptbookCli`
  */
-export type PromptRunnerAgentName = (typeof PROMPT_RUNNER_AGENT_NAMES)[number];
+export type PromptRunnerHarnessName = (typeof PROMPT_RUNNER_HARNESS_NAMES)[number];
 
 /**
  * Commander option bag for shared runner flags.
@@ -55,7 +35,7 @@ export type PromptRunnerAgentName = (typeof PROMPT_RUNNER_AGENT_NAMES)[number];
  * @private internal utility of `promptbookCli`
  */
 export type PromptRunnerCliOptions = {
-    readonly agent?: string;
+    readonly harness?: string;
     readonly model?: string;
     readonly ui: boolean;
     readonly thinkingLevel?: ThinkingLevel;
@@ -74,7 +54,7 @@ export type PromptRunnerCliOptions = {
  */
 export type PromptRunnerSelectionCliOptions = Pick<
     PromptRunnerCliOptions,
-    'agent' | 'model' | 'ui' | 'thinkingLevel' | 'allowCredits'
+    'harness' | 'model' | 'ui' | 'thinkingLevel' | 'allowCredits'
 >;
 
 /**
@@ -83,7 +63,7 @@ export type PromptRunnerSelectionCliOptions = Pick<
  * @private internal utility of `promptbookCli`
  */
 export type NormalizedPromptRunnerCliOptions = {
-    readonly agentName?: PromptRunnerAgentName;
+    readonly agentName?: PromptRunnerHarnessName;
     readonly model?: string;
     readonly noUi: boolean;
     readonly thinkingLevel?: ThinkingLevel;
@@ -121,11 +101,11 @@ export const PROMPT_RUNNER_DESCRIPTION = spaceTrim(`
 `);
 
 /**
- * Commander description for the `--agent` option.
+ * Commander description for the `--harness` option.
  *
  * @private internal utility of `promptbookCli`
  */
-export const PROMPT_RUNNER_AGENT_OPTION_DESCRIPTION =
+export const PROMPT_RUNNER_HARNESS_OPTION_DESCRIPTION =
     'Select runner: openai-codex, github-copilot, cline, claude-code, opencode, gemini (required for non-dry-run)';
 
 /**
@@ -146,7 +126,9 @@ export const PROMPT_RUNNER_MODEL_OPTION_DESCRIPTION = spaceTrim(`
  * @private internal utility of `promptbookCli`
  */
 export function addPromptRunnerSelectionOptions(command: Program): void {
-    command.addOption(new Option('--agent <agent-name>', PROMPT_RUNNER_AGENT_OPTION_DESCRIPTION).env(PTBK_AGENT_ENV));
+    command.addOption(
+        new Option('--harness <harness-name>', PROMPT_RUNNER_HARNESS_OPTION_DESCRIPTION).env(PTBK_HARNESS_ENV),
+    );
     command.addOption(new Option('--model <model>', PROMPT_RUNNER_MODEL_OPTION_DESCRIPTION).env(PTBK_MODEL_ENV));
 }
 
@@ -227,7 +209,7 @@ export function normalizePromptRunnerSelectionCliOptions(
     },
 ): NormalizedPromptRunnerSelectionCliOptions {
     return {
-        agentName: resolvePromptRunnerAgentName(cliOptions.agent, options),
+        agentName: resolvePromptRunnerHarnessName(cliOptions.harness, options),
         model: cliOptions.model,
         noUi: !cliOptions.ui,
         thinkingLevel: cliOptions.thinkingLevel,
@@ -236,38 +218,40 @@ export function normalizePromptRunnerSelectionCliOptions(
 }
 
 /**
- * Parses and validates one runner agent name.
+ * Parses and validates one runner harness name.
  */
-function resolvePromptRunnerAgentName(
-    agent: string | undefined,
+function resolvePromptRunnerHarnessName(
+    harness: string | undefined,
     options: {
         readonly isAgentRequired: boolean;
     },
-): PromptRunnerAgentName | undefined {
-    if (!agent) {
+): PromptRunnerHarnessName | undefined {
+    if (!harness) {
         if (!options.isAgentRequired) {
             return undefined;
         }
 
         throw new Error(
             colors.red(
-                'You must choose an agent using --agent <openai-codex|github-copilot|cline|claude-code|opencode|gemini>',
+                'You must choose a harness using --harness <openai-codex|github-copilot|cline|claude-code|opencode|gemini>',
             ),
         );
     }
 
-    if (isPromptRunnerAgentName(agent)) {
-        return agent;
+    if (isPromptRunnerHarnessName(harness)) {
+        return harness;
     }
 
-    throw new Error(colors.red(`Invalid agent "${agent}". Must be one of: ${PROMPT_RUNNER_AGENT_NAMES.join(', ')}`));
+    throw new Error(
+        colors.red(`Invalid harness "${harness}". Must be one of: ${PROMPT_RUNNER_HARNESS_NAMES.join(', ')}`),
+    );
 }
 
 /**
- * Checks whether a string is one supported runner agent name.
+ * Checks whether a string is one supported runner harness name.
  */
-function isPromptRunnerAgentName(agent: string): agent is PromptRunnerAgentName {
-    return PROMPT_RUNNER_AGENT_NAMES.includes(agent as PromptRunnerAgentName);
+function isPromptRunnerHarnessName(harness: string): harness is PromptRunnerHarnessName {
+    return PROMPT_RUNNER_HARNESS_NAMES.includes(harness as PromptRunnerHarnessName);
 }
 
 // Note: [🟡] Code for CLI runner options [promptRunnerCliOptions](src/cli/cli-commands/common/promptRunnerCliOptions.ts) should never be published outside of `@promptbook/cli`