@promptbook/cli 0.114.0-33 → 0.114.0-34

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

@@ -24,6 +24,13 @@ export const PROMPTS_DONE_DIRECTORY_PATH = join(PROMPTS_DIRECTORY_PATH, 'done');
  */
 export const PROMPTS_TEMPLATES_DIRECTORY_PATH = join(PROMPTS_DIRECTORY_PATH, 'templates');
 
+/**
+ * Relative path to the project-agnostic `common` boilerplate template referenced by the default coder scripts.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+export const COMMON_PROMPT_TEMPLATE_FILE_PATH = join(PROMPTS_TEMPLATES_DIRECTORY_PATH, 'common.md');
+
 /**
  * Initialization statuses used when creating or updating coder configuration artifacts.
  *
@@ -66,26 +73,6 @@ export type CoderPromptTemplateDefinition = {
     readonly isDefaultProjectTemplate: boolean;
 };
 
-/**
- * Result of ensuring one default coder template file exists inside a project.
- *
- * @private internal utility of `ptbk coder`
- */
-export type EnsuredCoderPromptTemplateFile = {
-    /**
-     * Stable built-in identifier of the template.
-     */
-    readonly id: BuiltInCoderPromptTemplate;
-    /**
-     * Project-relative path of the materialized template file.
-     */
-    readonly relativeFilePath: string;
-    /**
-     * Status describing whether the file had to be created.
-     */
-    readonly status: InitializationStatus;
-};
-
 /**
  * Fully resolved boilerplate template used by `coder generate-boilerplates`.
  *
@@ -118,7 +105,7 @@ export type ResolvedCoderPromptTemplate = {
 const DEFAULT_CODER_PROMPT_TEMPLATE_DEFINITIONS = [
     {
         id: 'common',
-        relativeFilePath: join(PROMPTS_TEMPLATES_DIRECTORY_PATH, 'common.md'),
+        relativeFilePath: COMMON_PROMPT_TEMPLATE_FILE_PATH,
         slugPrefix: null,
         content: spaceTrim(`
             -   @@@
@@ -172,35 +159,21 @@ export function getDefaultCoderPromptTemplateDefinition(
 }
 
 /**
- * Ensures the default project-owned coder template files exist without overwriting user customizations.
+ * Ensures one project-owned coder template file exists without overwriting user customizations.
  *
  * @private internal utility of `ptbk coder`
  */
-export async function ensureDefaultCoderPromptTemplateFiles(
+export async function ensureDefaultCoderPromptTemplateFile(
     projectPath: string,
-): Promise<ReadonlyArray<EnsuredCoderPromptTemplateFile>> {
-    const ensuredTemplateFiles: Array<EnsuredCoderPromptTemplateFile> = [];
-
-    for (const definition of DEFAULT_CODER_PROJECT_PROMPT_TEMPLATE_DEFINITIONS) {
-        const absoluteTemplatePath = join(projectPath, definition.relativeFilePath);
-        if (await isExistingFile(absoluteTemplatePath)) {
-            ensuredTemplateFiles.push({
-                id: definition.id,
-                relativeFilePath: definition.relativeFilePath,
-                status: 'unchanged',
-            });
-            continue;
-        }
-
-        await writeFile(absoluteTemplatePath, `${definition.content}\n`, 'utf-8');
-        ensuredTemplateFiles.push({
-            id: definition.id,
-            relativeFilePath: definition.relativeFilePath,
-            status: 'created',
-        });
+    definition: CoderPromptTemplateDefinition,
+): Promise<InitializationStatus> {
+    const absoluteTemplatePath = join(projectPath, definition.relativeFilePath);
+    if (await isExistingFile(absoluteTemplatePath)) {
+        return 'unchanged';
     }
 
-    return ensuredTemplateFiles;
+    await writeFile(absoluteTemplatePath, `${definition.content}\n`, 'utf-8');
+    return 'created';
 }
 
 /**

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

@@ -0,0 +1,106 @@
+import { AGENTS_FILE_PATH, getDefaultCoderAgentsFileContent } from './agentsFile';
+import type { CoderPromptTemplateDefinition, InitializationStatus } from './boilerplateTemplates';
+import {
+    ensureDefaultCoderPromptTemplateFile,
+    getDefaultCoderProjectPromptTemplateDefinitions,
+} from './boilerplateTemplates';
+import { CODER_DEVELOPER_AGENT_FILE_PATH, ensureCoderDeveloperAgentFile } from './ensureCoderDeveloperAgentFile';
+import { ensureCoderMarkdownFile } from './ensureCoderMarkdownFile';
+
+/**
+ * Status of one artifact referenced by the default coder scripts.
+ *
+ * `not-referenced` means that no newly added script points at the artifact, so `ptbk coder init` left it alone.
+ *
+ * @private internal utility of `coder init` command
+ */
+export type CoderReferencedArtifactStatus = InitializationStatus | 'not-referenced';
+
+/**
+ * Result of ensuring one artifact referenced by the default coder scripts.
+ *
+ * @private internal utility of `coder init` command
+ */
+export type EnsuredCoderReferencedArtifact = {
+    /**
+     * Project-relative path of the referenced artifact.
+     */
+    readonly relativeFilePath: string;
+
+    /**
+     * Status describing whether the artifact had to be created.
+     */
+    readonly status: CoderReferencedArtifactStatus;
+};
+
+/**
+ * One project artifact which the default coder scripts point at.
+ */
+type CoderReferencedArtifactDefinition = {
+    /**
+     * Project-relative path which both identifies the artifact and locates it inside the project.
+     */
+    readonly relativeFilePath: string;
+
+    /**
+     * Creates the artifact when it is missing, never overwriting an existing one.
+     */
+    readonly ensureArtifactFile: (projectPath: string) => Promise<InitializationStatus>;
+};
+
+/**
+ * Creates the artifact definition of one project-owned coder prompt template.
+ */
+function createCoderPromptTemplateArtifactDefinition(
+    definition: CoderPromptTemplateDefinition,
+): CoderReferencedArtifactDefinition {
+    return {
+        relativeFilePath: definition.relativeFilePath,
+        ensureArtifactFile: (projectPath) => ensureDefaultCoderPromptTemplateFile(projectPath, definition),
+    };
+}
+
+/**
+ * Every artifact which the default coder scripts can reference.
+ */
+const CODER_REFERENCED_ARTIFACT_DEFINITIONS: ReadonlyArray<CoderReferencedArtifactDefinition> = [
+    {
+        relativeFilePath: CODER_DEVELOPER_AGENT_FILE_PATH,
+        ensureArtifactFile: ensureCoderDeveloperAgentFile,
+    },
+    {
+        relativeFilePath: AGENTS_FILE_PATH,
+        ensureArtifactFile: (projectPath) =>
+            ensureCoderMarkdownFile(projectPath, AGENTS_FILE_PATH, getDefaultCoderAgentsFileContent()),
+    },
+    ...getDefaultCoderProjectPromptTemplateDefinitions().map(createCoderPromptTemplateArtifactDefinition),
+];
+
+/**
+ * Creates only those referenced artifacts which the freshly added coder scripts point at.
+ *
+ * An artifact of a script which the project already defines is intentionally **not** created - the project-owned
+ * script is kept as is, so it does not reference the default artifact in the first place.
+ *
+ * @private function of `initializeCoderProjectConfiguration`
+ */
+export async function ensureCoderReferencedArtifacts(
+    projectPath: string,
+    referencedArtifactPaths: ReadonlySet<string>,
+): Promise<ReadonlyArray<EnsuredCoderReferencedArtifact>> {
+    const ensuredArtifacts: Array<EnsuredCoderReferencedArtifact> = [];
+
+    for (const { relativeFilePath, ensureArtifactFile } of CODER_REFERENCED_ARTIFACT_DEFINITIONS) {
+        if (!referencedArtifactPaths.has(relativeFilePath)) {
+            ensuredArtifacts.push({ relativeFilePath, status: 'not-referenced' });
+            continue;
+        }
+
+        ensuredArtifacts.push({ relativeFilePath, status: await ensureArtifactFile(projectPath) });
+    }
+
+    return ensuredArtifacts;
+}
+
+// Note: [🟡] Code for coder init referenced artifacts [coderReferencedArtifacts](src/cli/cli-commands/coder/coderReferencedArtifacts.ts) should never be published outside of `@promptbook/cli`
+// Note: [💞] Ignore a discrepancy between file name and exported helper names

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

@@ -1,5 +1,5 @@
-import type { InitializationStatus } from './boilerplateTemplates';
 import { getDefaultCoderPackageJsonScripts } from './getDefaultCoderPackageJsonScripts';
+import type { MergedStringRecordJsonFile } from './mergeStringRecordJsonFile';
 import { mergeStringRecordJsonFile } from './mergeStringRecordJsonFile';
 
 /**
@@ -10,9 +10,11 @@ const PACKAGE_JSON_FILE_PATH = 'package.json';
 /**
  * Ensures `package.json` contains the standalone Promptbook coder helper scripts.
  *
+ * Scripts which the project already defines are kept as they are, only missing ones are added.
+ *
  * @private function of `initializeCoderProjectConfiguration`
  */
-export async function ensureCoderPackageJsonFile(projectPath: string): Promise<InitializationStatus> {
+export async function ensureCoderPackageJsonFile(projectPath: string): Promise<MergedStringRecordJsonFile> {
     return mergeStringRecordJsonFile({
         projectPath,
         relativeFilePath: PACKAGE_JSON_FILE_PATH,

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

@@ -15,18 +15,22 @@ const VSCODE_DIRECTORY_PATH = '.vscode';
 /**
  * Ensures VS Code routes pasted prompt images into `prompts/screenshots`.
  *
+ * Settings which the project already defines are kept as they are, only missing ones are added.
+ *
  * @private function of `initializeCoderProjectConfiguration`
  */
 export async function ensureCoderVscodeSettingsFile(projectPath: string): Promise<InitializationStatus> {
     const [fieldPath, nextEntries] = resolveDefaultCoderVscodeSettingsEntry();
 
-    return mergeStringRecordJsonFile({
+    const { status } = await mergeStringRecordJsonFile({
         projectPath,
         relativeFilePath: VSCODE_SETTINGS_FILE_PATH,
         fieldPath,
         nextEntries,
         ensureParentDirectoryPath: VSCODE_DIRECTORY_PATH,
     });
+
+    return status;
 }
 
 /**

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

@@ -1,4 +1,4 @@
-import { mkdir, stat } from 'fs/promises';
+import { mkdir, readdir, stat } from 'fs/promises';
 import { join } from 'path';
 import type { InitializationStatus } from './boilerplateTemplates';
 
@@ -22,6 +22,25 @@ export async function ensureDirectory(
     return 'unchanged';
 }
 
+/**
+ * Checks whether a project-relative directory is missing or contains no entries.
+ *
+ * @private internal utility of `coder init` command
+ */
+export async function isDirectoryEmpty(projectPath: string, relativeDirectoryPath: string): Promise<boolean> {
+    const directoryPath = join(projectPath, relativeDirectoryPath);
+
+    try {
+        return (await readdir(directoryPath)).length === 0;
+    } catch (error) {
+        if (isNodeJsErrorWithCode(error, 'ENOENT')) {
+            return true;
+        }
+
+        throw error;
+    }
+}
+
 /**
  * Checks whether a path exists and is a directory.
  */
@@ -33,4 +52,11 @@ async function isExistingDirectory(path: string): Promise<boolean> {
     }
 }
 
+/**
+ * Checks whether a caught value is a Node.js error with the given error code.
+ */
+function isNodeJsErrorWithCode(error: unknown, code: string): error is NodeJS.ErrnoException {
+    return typeof error === 'object' && error !== null && 'code' in error && error.code === code;
+}
+
 // Note: [🟡] Code for coder init directory creation [ensureDirectory](src/cli/cli-commands/coder/ensureDirectory.ts) should never be published outside of `@promptbook/cli`

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

@@ -1,17 +1,78 @@
+import { AGENTS_FILE_PATH } from './agentsFile';
 import { DEFAULT_BOILERPLATE_COUNT_OPTION_VALUE } from './boilerplateCount';
+import { COMMON_PROMPT_TEMPLATE_FILE_PATH } from './boilerplateTemplates';
+import { CODER_DEVELOPER_AGENT_FILE_PATH } from './ensureCoderDeveloperAgentFile';
+import { formatDisplayPath } from './formatDisplayPath';
+
+/**
+ * Name of the npm script which `ptbk coder run` uses to verify the project.
+ */
+const CODER_TEST_SCRIPT_NAME = 'test-for-ptbk-coder';
+
+/**
+ * One npm script initialized by `ptbk coder init`.
+ */
+type CoderPackageJsonScriptDefinition = {
+    /**
+     * Name of the npm script.
+     */
+    readonly scriptName: string;
+
+    /**
+     * Shell command of the npm script.
+     */
+    readonly scriptCommand: string;
+
+    /**
+     * Project-relative paths of the artifacts the command points at.
+     *
+     * They are created only together with the script itself, never for a script the project already defines.
+     */
+    readonly referencedArtifactPaths: ReadonlyArray<string>;
+};
 
 /**
  * Default npm scripts initialized by `ptbk coder init`.
+ *
+ * Note: Using NPX because `ptbk` can be installed globally or locally, and NPX will resolve it correctly in either case.
  */
-const DEFAULT_CODER_PACKAGE_JSON_SCRIPTS = {
-    // Note: Using NPX because `ptbk` can be installed globally or locally, and NPX will resolve it correctly in either case.
-    'coder:generate-boilerplates': `npx ptbk coder generate-boilerplates --count ${DEFAULT_BOILERPLATE_COUNT_OPTION_VALUE} --template ./prompts/templates/common.md`,
-    'coder:add': 'npx ptbk coder add --template ./prompts/templates/common.md',
-    'coder:run':
-        'npx ptbk coder run --harness openai-codex --model gpt-5.6-terra --thinking-level max --agent agents/developer.book --context AGENTS.md --test-before yes-and-fix',
-    // 'coder:find-refactor-candidates': 'npx ptbk coder find-refactor-candidates',
-    'coder:verify': 'npx ptbk coder verify',
-} as const satisfies Readonly<Record<string, string>>;
+const DEFAULT_CODER_PACKAGE_JSON_SCRIPT_DEFINITIONS: ReadonlyArray<CoderPackageJsonScriptDefinition> = [
+    {
+        scriptName: 'coder:generate-boilerplates',
+        scriptCommand: `npx ptbk coder generate-boilerplates --count ${DEFAULT_BOILERPLATE_COUNT_OPTION_VALUE} --template ${formatCoderScriptFilePath(
+            COMMON_PROMPT_TEMPLATE_FILE_PATH,
+        )}`,
+        referencedArtifactPaths: [COMMON_PROMPT_TEMPLATE_FILE_PATH],
+    },
+    {
+        scriptName: 'coder:add',
+        scriptCommand: `npx ptbk coder add --template ${formatCoderScriptFilePath(COMMON_PROMPT_TEMPLATE_FILE_PATH)}`,
+        referencedArtifactPaths: [COMMON_PROMPT_TEMPLATE_FILE_PATH],
+    },
+    {
+        scriptName: 'coder:run',
+        scriptCommand: [
+            'npx ptbk coder run --harness openai-codex --model gpt-5.6-terra --thinking-level max',
+            `--agent ${formatDisplayPath(CODER_DEVELOPER_AGENT_FILE_PATH)}`,
+            `--context ${formatDisplayPath(AGENTS_FILE_PATH)}`,
+            `--test "npm run ${CODER_TEST_SCRIPT_NAME}" --test-before yes-and-fix`,
+        ].join(' '),
+        referencedArtifactPaths: [CODER_DEVELOPER_AGENT_FILE_PATH, AGENTS_FILE_PATH],
+    },
+    // { scriptName: 'coder:find-refactor-candidates', scriptCommand: 'npx ptbk coder find-refactor-candidates', referencedArtifactPaths: [] },
+    {
+        scriptName: 'coder:verify',
+        scriptCommand: 'npx ptbk coder verify',
+        referencedArtifactPaths: [],
+    },
+    {
+        // Note: The verification command of `coder:run` is a project-owned script, so every project can decide
+        //       what "verified" means without touching the `coder:run` script itself
+        scriptName: CODER_TEST_SCRIPT_NAME,
+        scriptCommand: 'npm test',
+        referencedArtifactPaths: [],
+    },
+];
 
 /**
  * Lists the default npm scripts initialized by `ptbk coder init`.
@@ -19,7 +80,35 @@ const DEFAULT_CODER_PACKAGE_JSON_SCRIPTS = {
  * @private internal utility of `coder init` command
  */
 export function getDefaultCoderPackageJsonScripts(): Readonly<Record<string, string>> {
-    return DEFAULT_CODER_PACKAGE_JSON_SCRIPTS;
+    return Object.fromEntries(
+        DEFAULT_CODER_PACKAGE_JSON_SCRIPT_DEFINITIONS.map(({ scriptName, scriptCommand }) => [
+            scriptName,
+            scriptCommand,
+        ]),
+    );
+}
+
+/**
+ * Collects the project-relative artifact paths referenced by the given default coder scripts.
+ *
+ * @private internal utility of `coder init` command
+ */
+export function resolveCoderPackageJsonScriptReferencedArtifactPaths(
+    scriptNames: ReadonlyArray<string>,
+): ReadonlySet<string> {
+    return new Set(
+        DEFAULT_CODER_PACKAGE_JSON_SCRIPT_DEFINITIONS.filter(({ scriptName }) => scriptNames.includes(scriptName))
+            .map(({ referencedArtifactPaths }) => referencedArtifactPaths)
+            .flat(),
+    );
+}
+
+/**
+ * Formats one project-relative path as an explicitly project-rooted path usable inside a shell command.
+ */
+function formatCoderScriptFilePath(relativeFilePath: string): string {
+    return `./${formatDisplayPath(relativeFilePath)}`;
 }
 
 // Note: [🟡] Code for coder init package scripts [getDefaultCoderPackageJsonScripts](src/cli/cli-commands/coder/getDefaultCoderPackageJsonScripts.ts) should never be published outside of `@promptbook/cli`
+// Note: [💞] Ignore a discrepancy between file name and exported helper names

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

@@ -13,16 +13,17 @@ import { handleActionErrors } from '../common/handleActionErrors';
 import { $ensureHarnessInstallations } from '../common/harness/$ensureHarnessInstallations';
 import { getHarnessDefinition } from '../common/harness/HarnessDefinition';
 import {
-    addHarnessUpdateOption,
-    normalizeHarnessUpdateCliOptions,
-    type HarnessUpdateCliOptions,
-} from '../common/harnessUpdateCliOptions';
+    addQuestionsOption,
+    normalizeQuestionsCliOptions,
+    QUESTIONS_DESCRIPTION,
+    type QuestionsCliOptions,
+} from '../common/questionsCliOptions';
 import type { PromptRunnerHarnessName } from '../common/promptRunnerCliOptions';
-import { AGENT_CODING_FILE_PATH } from './agentCodingFile';
 import { AGENTS_FILE_PATH } from './agentsFile';
 import { DEFAULT_BOILERPLATE_COUNT } from './boilerplateCount';
-import { getDefaultCoderProjectPromptTemplateDefinitions } from './boilerplateTemplates';
+import { getDefaultCoderProjectPromptTemplateDefinitions, PROMPTS_DIRECTORY_PATH } from './boilerplateTemplates';
 import { CODER_DEVELOPER_AGENT_FILE_PATH } from './ensureCoderDeveloperAgentFile';
+import { isDirectoryEmpty } from './ensureDirectory';
 import { formatDisplayPath } from './formatDisplayPath';
 import { generatePromptBoilerplate } from './generate-boilerplates';
 import { initializeCoderProjectConfiguration } from './initializeCoderProjectConfiguration';
@@ -61,33 +62,37 @@ export function $initializeCoderInitCommand(program: Program): $side_effect {
                 ${block(listDefaultCoderProjectPromptTemplateDisplayPaths())}
                 - ${CODER_DEVELOPER_AGENT_FILE_PATH}
                 - ${AGENTS_FILE_PATH}
-                - ${AGENT_CODING_FILE_PATH}
                 - .gitignore with local artifacts from every supported harness
                 - package.json
                 - .vscode/settings.json
 
+                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
+
                 Ensures required coding-agent environment variables in .env:
                 - CODING_AGENT_GIT_NAME
                 - CODING_AGENT_GIT_EMAIL
                 - CODING_AGENT_GIT_SIGNING_KEY
 
-                Checks that the coding harnesses are installed and up to date unless \`--no-harness-update\` is used:
+                Checks that the coding harnesses are installed and up to date unless \`--no-questions\` is used:
                 ${block(listCheckedHarnessLabels())}
 
                 ${block(CODER_GIT_SYNC_DESCRIPTION)}
+
+                ${block(QUESTIONS_DESCRIPTION)}
             `,
         ),
     );
 
     addCoderGitSyncOptions(command);
-    addHarnessUpdateOption(command);
+    addQuestionsOption(command);
 
     command.action(
         handleActionErrors(async (cliOptions) => {
             const gitSync = normalizeCoderGitSyncCliOptions(cliOptions as CoderGitSyncCliOptions);
-            const { isHarnessUpdateCheckEnabled } = normalizeHarnessUpdateCliOptions(
-                cliOptions as HarnessUpdateCliOptions,
-            );
+            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`
@@ -96,10 +101,14 @@ export function $initializeCoderInitCommand(program: Program): $side_effect {
             );
 
             const commitScope = await $startCoderGitSync({ gitSync, projectPath });
+            const isPromptsDirectoryEmpty = await isDirectoryEmpty(projectPath, PROMPTS_DIRECTORY_PATH);
 
             const summary = await initializeCoderProjectConfiguration(projectPath);
             printInitializationSummary(summary);
-            await generatePromptBoilerplate({ projectPath, boilerplateCount: DEFAULT_BOILERPLATE_COUNT });
+
+            if (isPromptsDirectoryEmpty) {
+                await generatePromptBoilerplate({ projectPath, boilerplateCount: DEFAULT_BOILERPLATE_COUNT });
+            }
 
             await $commitCoderChanges({
                 gitSync,
@@ -107,7 +116,7 @@ export function $initializeCoderInitCommand(program: Program): $side_effect {
                 commitMessage: 'Initialize Promptbook Coder',
             });
 
-            await $ensureHarnessInstallations(CODER_INIT_CHECKED_HARNESS_NAMES, isHarnessUpdateCheckEnabled);
+            await $ensureHarnessInstallations(CODER_INIT_CHECKED_HARNESS_NAMES, questionsOptions);
         }),
     );
 }

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

@@ -1,19 +1,18 @@
-import { AGENT_CODING_FILE_PATH, getDefaultCoderAgentCodingFileContent } from './agentCodingFile';
-import { AGENTS_FILE_PATH, getDefaultCoderAgentsFileContent } from './agentsFile';
-import type { EnsuredCoderPromptTemplateFile, InitializationStatus } from './boilerplateTemplates';
+import type { InitializationStatus } from './boilerplateTemplates';
 import {
-    ensureDefaultCoderPromptTemplateFiles,
     PROMPTS_DIRECTORY_PATH,
     PROMPTS_DONE_DIRECTORY_PATH,
     PROMPTS_TEMPLATES_DIRECTORY_PATH,
 } from './boilerplateTemplates';
-import { CODER_AGENTS_DIRECTORY_PATH, ensureCoderDeveloperAgentFile } from './ensureCoderDeveloperAgentFile';
+import type { EnsuredCoderReferencedArtifact } from './coderReferencedArtifacts';
+import { ensureCoderReferencedArtifacts } from './coderReferencedArtifacts';
+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';
 
 /**
  * Result summary returned after coder configuration initialization.
@@ -24,58 +23,50 @@ export type CoderInitializationSummary = {
     readonly promptsDirectoryStatus: InitializationStatus;
     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;
     readonly gitignoreFileStatus: InitializationStatus;
     readonly packageJsonFileStatus: InitializationStatus;
     readonly vscodeSettingsFileStatus: InitializationStatus;
+    readonly addedPackageJsonScriptNames: ReadonlyArray<string>;
+    readonly referencedArtifactStatuses: ReadonlyArray<EnsuredCoderReferencedArtifact>;
     readonly initializedEnvVariableNames: ReadonlyArray<string>;
 };
 
 /**
  * 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.
+ *
  * @private internal utility of `coder init` command
  */
 export async function initializeCoderProjectConfiguration(projectPath: string): Promise<CoderInitializationSummary> {
     const promptsDirectoryStatus = await ensureDirectory(projectPath, PROMPTS_DIRECTORY_PATH);
     const promptsDoneDirectoryStatus = await ensureDirectory(projectPath, PROMPTS_DONE_DIRECTORY_PATH);
     const promptsTemplatesDirectoryStatus = await ensureDirectory(projectPath, PROMPTS_TEMPLATES_DIRECTORY_PATH);
-    const promptTemplateFileStatuses = await ensureDefaultCoderPromptTemplateFiles(projectPath);
     const agentsDirectoryStatus = await ensureDirectory(projectPath, CODER_AGENTS_DIRECTORY_PATH);
-    const developerAgentFileStatus = await ensureCoderDeveloperAgentFile(projectPath);
-    const agentsFileStatus = await ensureCoderMarkdownFile(
-        projectPath,
-        AGENTS_FILE_PATH,
-        getDefaultCoderAgentsFileContent(),
-    );
-    const agentCodingFileStatus = await ensureCoderMarkdownFile(
-        projectPath,
-        AGENT_CODING_FILE_PATH,
-        getDefaultCoderAgentCodingFileContent(),
-    );
     const { envFileStatus, initializedEnvVariableNames } = await ensureCoderEnvFile(projectPath);
     const gitignoreFileStatus = await ensureCoderGitignoreFile(projectPath);
-    const packageJsonFileStatus = await ensureCoderPackageJsonFile(projectPath);
+    const { status: packageJsonFileStatus, addedEntryKeys: addedPackageJsonScriptNames } =
+        await ensureCoderPackageJsonFile(projectPath);
     const vscodeSettingsFileStatus = await ensureCoderVscodeSettingsFile(projectPath);
+    const referencedArtifactStatuses = await ensureCoderReferencedArtifacts(
+        projectPath,
+        resolveCoderPackageJsonScriptReferencedArtifactPaths(addedPackageJsonScriptNames),
+    );
 
     return {
         promptsDirectoryStatus,
         promptsDoneDirectoryStatus,
         promptsTemplatesDirectoryStatus,
-        promptTemplateFileStatuses,
         agentsDirectoryStatus,
-        developerAgentFileStatus,
-        agentsFileStatus,
-        agentCodingFileStatus,
         envFileStatus,
         gitignoreFileStatus,
         packageJsonFileStatus,
         vscodeSettingsFileStatus,
+        addedPackageJsonScriptNames,
+        referencedArtifactStatuses,
         initializedEnvVariableNames,
     };
 }

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

@@ -11,6 +11,7 @@ import {
     normalizePromptRunnerSelectionCliOptions,
     PROMPT_RUNNER_DESCRIPTION,
 } from '../common/promptRunnerCliOptions';
+import { addCoderAgentOption, type CoderAgentCliOptions } from './agentCliOptions';
 
 /**
  * Initializes `coder list` command for Promptbook CLI utilities.
@@ -30,35 +31,46 @@ export function $initializeCoderListCommand(program: Program): $side_effect {
             Features:
             - Lists only ready, fully authored prompts
             - Groups prompts from highest to lowest priority
-            - Optional --harness and --model filters show only prompts compatible with that runner
+            - Optional --harness, --model and --agent filters show only prompts compatible with that selection
             - Does not start a coding harness or modify prompt files
         `),
     );
 
     addPromptRunnerSelectionOptions(command);
+    addCoderAgentOption(command);
     addPromptPriorityOptions(command);
 
     command.action(
         handleActionErrors(async (cliOptions) => {
             const {
+                agent,
                 priority,
                 minPriority: minimumPriority,
                 maxPriority: maximumPriority,
             } = cliOptions as {
+                readonly agent?: string;
                 readonly priority?: number;
                 readonly minPriority?: number;
                 readonly maxPriority?: number;
-            } & PromptRunnerSelectionCliOptions;
+            } & PromptRunnerSelectionCliOptions & CoderAgentCliOptions;
             const runnerOptions = normalizePromptRunnerSelectionCliOptions(
                 cliOptions as PromptRunnerSelectionCliOptions,
                 { isAgentRequired: false },
             );
+            const resolvedCoderAgentBook =
+                agent === undefined
+                    ? undefined
+                    : await (await import('../../../../scripts/run-codex-prompts/common/resolveCoderAgent'))
+                          .resolveCoderAgentBook(agent, process.cwd());
             const promptRunnerIdentity =
-                runnerOptions.agentName === undefined && runnerOptions.model === undefined
+                runnerOptions.agentName === undefined &&
+                runnerOptions.model === undefined &&
+                resolvedCoderAgentBook === undefined
                     ? undefined
                     : {
                           harnessName: runnerOptions.agentName,
                           modelName: runnerOptions.model,
+                          agentReferences: resolvedCoderAgentBook?.agentReferences,
                       };
 
             // Note: Import dynamically to avoid loading prompt parsing dependencies until this command is used.