@promptbook/cli 0.114.0-48 → 0.114.0-49

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/coder/add.ts

@@ -18,6 +18,7 @@ import {
 } 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,
@@ -105,6 +106,7 @@ export function $initializeCoderAddCommand(program: Program): $side_effect {
 
     command.action(
         handleActionErrors(async (descriptionArgument: string | undefined, cliOptions) => {
+            const projectOptions = normalizeProjectCliOptions(cliOptions);
             const { priority, template: templateOption } = cliOptions as {
                 readonly priority: number;
                 readonly template?: string;
@@ -112,7 +114,11 @@ export function $initializeCoderAddCommand(program: Program): $side_effect {
 
             const gitSync = normalizeCoderGitSyncCliOptions(cliOptions as CoderGitSyncCliOptions);
             const questionsOptions = normalizeQuestionsCliOptions(cliOptions as QuestionsCliOptions);
-            const workspace = await $preflightWorkspaceRepository({ policy: 'mutate', ...questionsOptions });
+            const workspace = await $preflightWorkspaceRepository({
+                ...projectOptions,
+                policy: 'mutate',
+                ...questionsOptions,
+            });
             const { projectPath } = workspace;
 
             const description = await resolveCoderPromptDescription(descriptionArgument, questionsOptions);

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

@@ -1,7 +1,8 @@
 import type {
     Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
 } from 'commander';
-import { CODER_DEFAULT_AGENT_BOOK_PATHS, type CoderAgentRole } from './coderAgentRole';
+import { addProjectContextOption } from '../common/projectCliOptions';
+import { CODER_DEFAULT_AGENT_BOOK_PATHS, DEFAULT_CODER_AGENT_ROLE, type CoderAgentRole } from './coderAgentRole';
 
 /**
  * Commander option bag for an optional Book agent used by coder commands.
@@ -34,5 +35,14 @@ export function addCoderAgentOption(command: Program, defaultRole?: CoderAgentRo
     command.option('--agent <agent-book-path>', `${CODER_AGENT_OPTION_DESCRIPTION}. ${defaultDescription}`);
 }
 
+/**
+ * Registers the shared optional persona and context for single-agent execution or authoring.
+ * @private internal CLI registration helper
+ */
+export function addCoderExecutionOptions(command: Program): void {
+    addCoderAgentOption(command, DEFAULT_CODER_AGENT_ROLE);
+    addProjectContextOption(command);
+}
+
 // Note: [🟡] Code for CLI coder agent options 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/coderAgentRole.ts

@@ -19,4 +19,10 @@ export const CODER_DEFAULT_AGENT_BOOK_PATHS = {
  */
 export type CoderAgentRole = keyof typeof CODER_DEFAULT_AGENT_BOOK_PATHS;
 
+/**
+ * Shared persona for optional single-agent execution and authoring; capabilities belong to the command.
+ * @private internal constant of project CLI commands
+ */
+export const DEFAULT_CODER_AGENT_ROLE: CoderAgentRole = 'developer';
+
 // Note: [💞] Ignore a discrepancy between file name and exported helper names

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

@@ -75,9 +75,9 @@ const CODER_REFERENCED_ARTIFACT_DEFINITIONS: ReadonlyArray<CoderReferencedArtifa
 ];
 
 /**
- * Initializes artifacts referenced by freshly added scripts. Default Books are ensured separately.
+ * Initializes essential context and artifacts referenced by freshly added scripts. Books are ensured separately.
  *
- * For artifacts other than role Books, an existing project script does not cause default files to be created.
+ * AGENTS.md is essential even when every script already exists or uses implicit defaults.
  *
  * @private function of `initializeCoderProjectConfiguration`
  */
@@ -88,7 +88,7 @@ export async function ensureCoderReferencedArtifacts(
     const ensuredArtifacts: Array<EnsuredCoderReferencedArtifact> = [];
 
     for (const { relativeFilePath, ensureArtifactFile } of CODER_REFERENCED_ARTIFACT_DEFINITIONS) {
-        if (!referencedArtifactPaths.has(relativeFilePath)) {
+        if (relativeFilePath !== AGENTS_FILE_PATH && !referencedArtifactPaths.has(relativeFilePath)) {
             ensuredArtifacts.push({ relativeFilePath, status: 'not-referenced' });
             continue;
         }

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

@@ -1,6 +1,8 @@
 import { getDefaultCoderPackageJsonScripts } from './getDefaultCoderPackageJsonScripts';
 import type { MergedStringRecordJsonFile } from './mergeStringRecordJsonFile';
 import { mergeStringRecordJsonFile } from './mergeStringRecordJsonFile';
+import { prepareCoderPackageJsonScripts, type PreparedCoderPackageJsonScripts } from './prepareCoderPackageJsonScripts';
+import { findLegacyCoderCheckCallers } from './findLegacyCoderCheckCallers';
 
 /**
  * Relative path to `package.json` in the initialized project.
@@ -10,17 +12,34 @@ 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.
+ * Project definitions are preserved; missing scripts and narrowly recognized generated migrations are applied.
  *
  * @private function of `initializeCoderProjectConfiguration`
  */
-export async function ensureCoderPackageJsonFile(projectPath: string): Promise<MergedStringRecordJsonFile> {
-    return mergeStringRecordJsonFile({
+export async function ensureCoderPackageJsonFile(
+    projectPath: string,
+): Promise<MergedStringRecordJsonFile & Omit<PreparedCoderPackageJsonScripts, 'scripts'>> {
+    let preparation: PreparedCoderPackageJsonScripts;
+    const mergedFile = await mergeStringRecordJsonFile({
         projectPath,
         relativeFilePath: PACKAGE_JSON_FILE_PATH,
         fieldPath: 'scripts',
         nextEntries: getDefaultCoderPackageJsonScripts(),
+        transformExistingEntries: async (entries) => {
+            const legacyNames = Object.keys(entries).filter(
+                (name) => name === 'test-for-ptbk-coder' || name === 'check-for-ptbk-coder',
+            );
+            const externalCallers = await findLegacyCoderCheckCallers(projectPath, legacyNames);
+            preparation = prepareCoderPackageJsonScripts(entries, externalCallers);
+            return preparation.scripts;
+        },
     });
+    return {
+        ...mergedFile,
+        checkScriptSummary: preparation!.checkScriptSummary,
+        migrationInstructions: preparation!.migrationInstructions,
+        isCheckConfigured: preparation!.isCheckConfigured,
+    };
 }
 
 // Note: [🟡] Code for coder init package.json bootstrapping [ensureCoderPackageJsonFile](src/cli/cli-commands/coder/ensureCoderPackageJsonFile.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/coder/find-fresh-emoji-tags.ts

@@ -6,6 +6,7 @@ import spaceTrim from 'spacetrim';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
 import { $preflightWorkspaceRepository } from '../common/workspaceRepository';
 import { addWorkspaceRepositoryOptions } from '../common/workspaceRepositoryCliOptions';
+import { normalizeProjectCliOptions } from '../common/projectCliOptions';
 import { handleActionErrors } from '../common/handleActionErrors';
 
 /**
@@ -31,7 +32,9 @@ export function $initializeCoderFindFreshEmojiTagCommand(program: Program): $sid
 
     command.action(
         handleActionErrors(async (cliOptions) => {
+            const projectOptions = normalizeProjectCliOptions(cliOptions);
             const workspace = await $preflightWorkspaceRepository({
+                ...projectOptions,
                 policy: 'read-only',
                 isAskingQuestionsEnabled: cliOptions.questions,
             });

package/src/cli/cli-commands/coder/find-refactor-candidates.ts

@@ -15,6 +15,7 @@ import type { $side_effect } from '../../../utils/organization/$side_effect';
 import { createPositiveIntegerOptionParser } from '../common/createPositiveIntegerOptionParser';
 import { $preflightWorkspaceRepository } from '../common/workspaceRepository';
 import { addWorkspaceRepositoryOptions } from '../common/workspaceRepositoryCliOptions';
+import { normalizeProjectCliOptions } from '../common/projectCliOptions';
 import { handleActionErrors } from '../common/handleActionErrors';
 
 /**
@@ -57,12 +58,14 @@ export function $initializeCoderFindRefactorCandidatesCommand(program: Program):
 
     command.action(
         handleActionErrors(async (cliOptions) => {
+            const projectOptions = normalizeProjectCliOptions(cliOptions);
             const { level = DEFAULT_REFACTOR_CANDIDATE_LEVEL, limit } = cliOptions as {
                 readonly level?: RefactorCandidateLevel;
                 readonly limit?: number;
             };
 
             const workspace = await $preflightWorkspaceRepository({
+                ...projectOptions,
                 policy: 'mutate',
                 isAskingQuestionsEnabled: cliOptions.questions,
             });

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

@@ -4,6 +4,7 @@ import { assertsError } from '../../../errors/assertsError';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
 import { $preflightWorkspaceRepository } from '../common/workspaceRepository';
 import { addWorkspaceRepositoryOptions } from '../common/workspaceRepositoryCliOptions';
+import { normalizeProjectCliOptions } from '../common/projectCliOptions';
 import { handleActionErrors } from '../common/handleActionErrors';
 
 /**
@@ -22,11 +23,13 @@ export function $initializeCoderFindUnwrittenCommand(program: Program): $side_ef
 
     command.action(
         handleActionErrors(async (cliOptions) => {
+            const projectOptions = normalizeProjectCliOptions(cliOptions);
             const { priority = 0 } = cliOptions as {
                 readonly priority?: number;
             };
 
             const workspace = await $preflightWorkspaceRepository({
+                ...projectOptions,
                 policy: 'read-only',
                 isAskingQuestionsEnabled: cliOptions.questions,
             });

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

@@ -0,0 +1,87 @@
+import { readFile, readdir } from 'fs/promises';
+import type { Dirent } from 'fs';
+import { join } from 'path';
+
+// cspell:ignore Procfile
+
+/** Runtime/dependency/history directories do not contain maintained project callers. */
+const IGNORED_CALLER_DIRECTORIES = new Set([
+    'node_modules',
+    '.git',
+    '.promptbook',
+    '.next',
+    '.tmp',
+    'dist',
+    'build',
+    'coverage',
+]);
+
+/** Only Coder's known task-history paths are excluded; the same names elsewhere can hold active callers. */
+const IGNORED_CALLER_HISTORY_PATHS = new Set(['prompts/done', 'prompts/traces']);
+
+/** Source and workflow files whose references must be preserved during npm script migration. */
+const CALLER_FILE_PATTERN = /\.(?:[cm]?jsx?|tsx?|json|ya?ml|md|sh|bash|ps1|cmd|bat|py|toml|xml|groovy)$/iu;
+
+/** Conventional workflow files which have no filename extension. */
+const CALLER_FILE_NAMES = new Set(['Makefile', 'Dockerfile', 'Jenkinsfile', 'Procfile']);
+
+/**
+ * Finds external project callers conservatively; it never rewrites their shell expressions.
+ * @private migration safety check for the Coder initializer
+ */
+export async function findLegacyCoderCheckCallers(
+    projectPath: string,
+    legacyNames: ReadonlyArray<string>,
+): Promise<Readonly<Record<string, ReadonlyArray<string>>>> {
+    const callers: Record<string, string[]> = Object.fromEntries(legacyNames.map((name) => [name, []]));
+    if (legacyNames.length === 0) return callers;
+
+    /** Scans maintained text files without following symlinks or inspecting runtime state. */
+    async function visit(relativeDirectory: string): Promise<void> {
+        let entries: Dirent[];
+        try {
+            entries = await readdir(join(projectPath, relativeDirectory), { withFileTypes: true });
+        } catch {
+            for (const legacyName of legacyNames)
+                callers[legacyName]!.push(`${relativeDirectory} (unreadable directory; review manually)`);
+            return;
+        }
+        for (const entry of entries) {
+            const relativePath = relativeDirectory ? `${relativeDirectory}/${entry.name}` : entry.name;
+            if (entry.isSymbolicLink()) {
+                if (!IGNORED_CALLER_DIRECTORIES.has(entry.name)) {
+                    for (const legacyName of legacyNames)
+                        callers[legacyName]!.push(`${relativePath} (symbolic link; review manually)`);
+                }
+                continue;
+            }
+            if (entry.isDirectory()) {
+                if (!IGNORED_CALLER_DIRECTORIES.has(entry.name) && !IGNORED_CALLER_HISTORY_PATHS.has(relativePath))
+                    await visit(relativePath);
+            } else if (entry.isFile() && (CALLER_FILE_PATTERN.test(entry.name) || CALLER_FILE_NAMES.has(entry.name))) {
+                try {
+                    let content = await readFile(join(projectPath, relativePath), 'utf-8');
+                    if (relativePath === 'package.json') {
+                        // Script callers are already handled by the merge. Other project-owned metadata may also
+                        // reference a script, so it must be included when deciding whether removal is safe.
+                        const packageMetadata = JSON.parse(content);
+                        delete packageMetadata.scripts;
+                        content = JSON.stringify(packageMetadata);
+                    }
+                    for (const legacyName of legacyNames) {
+                        if (content.includes(legacyName))
+                            callers[legacyName]!.push(
+                                relativePath === 'package.json' ? 'package.json (outside scripts)' : relativePath,
+                            );
+                    }
+                } catch {
+                    // An unreadable file cannot prove that deletion is safe. Keep the entry and explain why.
+                    for (const legacyName of legacyNames)
+                        callers[legacyName]!.push(`${relativePath} (unreadable; review manually)`);
+                }
+            }
+        }
+    }
+    await visit('');
+    return callers;
+}

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

@@ -14,6 +14,7 @@ import {
 } from '../common/coderGitSyncCliOptions';
 import { $preflightWorkspaceRepository } from '../common/workspaceRepository';
 import { addWorkspaceRepositoryOptions } from '../common/workspaceRepositoryCliOptions';
+import { normalizeProjectCliOptions } from '../common/projectCliOptions';
 import { handleActionErrors } from '../common/handleActionErrors';
 import type { BoilerplateCount } from './boilerplateCount';
 import {
@@ -65,6 +66,7 @@ export function $initializeCoderGenerateBoilerplatesCommand(program: Program): $
 
     command.action(
         handleActionErrors(async (cliOptions) => {
+            const projectOptions = normalizeProjectCliOptions(cliOptions);
             const { count: countOption, template: templateOption } = cliOptions as {
                 readonly count: string;
                 readonly template?: string;
@@ -73,6 +75,7 @@ export function $initializeCoderGenerateBoilerplatesCommand(program: Program): $
             const boilerplateCount = parseBoilerplateCount(countOption);
             const gitSync = normalizeCoderGitSyncCliOptions(cliOptions as CoderGitSyncCliOptions);
             const workspace = await $preflightWorkspaceRepository({
+                ...projectOptions,
                 policy: 'mutate',
                 isAskingQuestionsEnabled: cliOptions.questions,
             });

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

@@ -2,13 +2,13 @@ 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 { CODER_PLANNER_AGENT_FILE_PATH } from './ensureCoderRoleAgentFile';
 import { formatDisplayPath } from './formatDisplayPath';
+import { CHECK_SETUP_PLACEHOLDER_COMMAND } from '../../../../scripts/run-codex-prompts/checks/projectCheck';
 
 /**
  * Name of the npm script which `ptbk coder run` uses to verify the project.
  */
-const CODER_TEST_SCRIPT_NAME = 'test-for-ptbk-coder';
+const CHECK_SCRIPT_NAME = 'check';
 
 /**
  * One npm script initialized by `ptbk coder init`.
@@ -53,14 +53,13 @@ const DEFAULT_CODER_PACKAGE_JSON_SCRIPT_DEFINITIONS: ReadonlyArray<CoderPackageJ
     {
         scriptName: 'coder:plan',
         scriptCommand: 'npx ptbk coder plan --harness openai-codex',
-        referencedArtifactPaths: [CODER_PLANNER_AGENT_FILE_PATH, COMMON_PROMPT_TEMPLATE_FILE_PATH],
+        referencedArtifactPaths: [CODER_DEVELOPER_AGENT_FILE_PATH, AGENTS_FILE_PATH, COMMON_PROMPT_TEMPLATE_FILE_PATH],
     },
     {
         scriptName: 'coder:run',
         scriptCommand: [
             'npx ptbk coder run --harness openai-codex --thinking-level max',
-            `--context ${formatDisplayPath(AGENTS_FILE_PATH)}`,
-            `--test "npm run ${CODER_TEST_SCRIPT_NAME}" --test-before yes-and-fix`,
+            `--check "npm run ${CHECK_SCRIPT_NAME}" --check-before yes-and-fix`,
         ].join(' '),
         referencedArtifactPaths: [CODER_DEVELOPER_AGENT_FILE_PATH, AGENTS_FILE_PATH],
     },
@@ -73,8 +72,8 @@ const DEFAULT_CODER_PACKAGE_JSON_SCRIPT_DEFINITIONS: ReadonlyArray<CoderPackageJ
     {
         // 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',
+        scriptName: CHECK_SCRIPT_NAME,
+        scriptCommand: CHECK_SETUP_PLACEHOLDER_COMMAND,
         referencedArtifactPaths: [],
     },
 ];

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

@@ -14,6 +14,7 @@ import {
 } from '../common/coderGitSyncCliOptions';
 import { $preflightWorkspaceRepository } from '../common/workspaceRepository';
 import { addWorkspaceRepositoryOptions } from '../common/workspaceRepositoryCliOptions';
+import { normalizeProjectCliOptions } from '../common/projectCliOptions';
 import { handleActionErrors } from '../common/handleActionErrors';
 import { $ensureHarnessInstallations } from '../common/harness/$ensureHarnessInstallations';
 import { getHarnessDefinition } from '../common/harness/HarnessDefinition';
@@ -88,7 +89,7 @@ export function $initializeCoderInitCommand(program: Program): $side_effect {
                 - 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
+                - Missing AGENTS.md is initialized independently of scripts; existing content is preserved
 
                 Ensures required coding-agent environment variables in .env:
                 - CODING_AGENT_GIT_NAME
@@ -112,9 +113,14 @@ export function $initializeCoderInitCommand(program: Program): $side_effect {
 
     command.action(
         handleActionErrors(async (cliOptions) => {
+            const projectOptions = normalizeProjectCliOptions(cliOptions);
             const gitSync = normalizeCoderGitSyncCliOptions(cliOptions as CoderGitSyncCliOptions);
             const questionsOptions = normalizeQuestionsCliOptions(cliOptions as QuestionsCliOptions);
-            const workspace = await $preflightWorkspaceRepository({ policy: 'initialize', ...questionsOptions });
+            const workspace = await $preflightWorkspaceRepository({
+                ...projectOptions,
+                policy: 'initialize',
+                ...questionsOptions,
+            });
             const { projectPath } = workspace;
 
             const completedSteps = [`Git repository ${workspace.repositoryStatus}: ${workspace.repositoryRoot}`];

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

@@ -38,6 +38,12 @@ export type CoderInitializationSummary = {
     readonly addedPackageJsonScriptNames: ReadonlyArray<string>;
     readonly referencedArtifactStatuses: ReadonlyArray<EnsuredCoderReferencedArtifact>;
     readonly initializedEnvVariableNames: ReadonlyArray<string>;
+    /** Actual preserved or generated scope of the project check. */
+    readonly checkScriptSummary: string;
+    /** Manual steps needed for custom or conflicting legacy entries. */
+    readonly migrationInstructions: ReadonlyArray<string>;
+    /** Whether validation is configured rather than still requiring setup. */
+    readonly isCheckConfigured: boolean;
 };
 
 /**
@@ -85,10 +91,13 @@ export async function initializeCoderProjectConfiguration(
     )!;
     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 {
+        status: packageJsonFileStatus,
+        addedEntryKeys: addedPackageJsonScriptNames,
+        checkScriptSummary,
+        migrationInstructions,
+        isCheckConfigured,
+    } = await completeStep('package.json', ensureCoderPackageJsonFile(projectPath));
     const vscodeSettingsFileStatus = await completeStep(
         '.vscode/settings.json',
         ensureCoderVscodeSettingsFile(projectPath),
@@ -119,6 +128,9 @@ export async function initializeCoderProjectConfiguration(
         addedPackageJsonScriptNames,
         referencedArtifactStatuses,
         initializedEnvVariableNames,
+        checkScriptSummary,
+        migrationInstructions,
+        isCheckConfigured,
     };
 }
 

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

@@ -5,6 +5,7 @@ import { spaceTrim } from 'spacetrim';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
 import { $preflightWorkspaceRepository } from '../common/workspaceRepository';
 import { addWorkspaceRepositoryOptions } from '../common/workspaceRepositoryCliOptions';
+import { normalizeProjectCliOptions } from '../common/projectCliOptions';
 import { handleActionErrors } from '../common/handleActionErrors';
 import { addPromptPriorityOptions } from '../common/promptPriorityCliOptions';
 import type { PromptRunnerSelectionCliOptions } from '../common/promptRunnerCliOptions';
@@ -46,6 +47,7 @@ export function $initializeCoderListCommand(program: Program): $side_effect {
 
     command.action(
         handleActionErrors(async (cliOptions) => {
+            const projectOptions = normalizeProjectCliOptions(cliOptions);
             const {
                 agent,
                 priority,
@@ -62,7 +64,10 @@ export function $initializeCoderListCommand(program: Program): $side_effect {
                 cliOptions as PromptRunnerSelectionCliOptions,
                 { isAgentRequired: false },
             );
-            const workspace = await $preflightWorkspaceRepository({ policy: 'read-only' });
+            const workspace = await $preflightWorkspaceRepository({
+                ...projectOptions,
+                policy: 'read-only',
+            });
             const resolvedCoderAgentBook =
                 agent === undefined
                     ? undefined

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

@@ -28,6 +28,10 @@ type MergeStringRecordJsonFileOptions = {
     readonly fieldPath: string;
     readonly nextEntries: Readonly<Record<string, string>>;
     readonly ensureParentDirectoryPath?: string;
+    /** Optional narrowly scoped migration of existing entries before missing defaults are added. */
+    readonly transformExistingEntries?: (
+        entries: Readonly<Record<string, string>>,
+    ) => Readonly<Record<string, string>> | Promise<Readonly<Record<string, string>>>;
 };
 
 /**
@@ -60,8 +64,8 @@ const DEFAULT_JSON_FILE_NEWLINE = '\n';
 /**
  * Ensures one JSON object field contains the provided string-record entries.
  *
- * Entries which the project already defines are **never** overridden - only missing keys are added,
- * so hand-tuned scripts and settings survive every repeated `ptbk coder init`.
+ * Entries are additive unless a caller explicitly supplies a scoped migration callback.
+ * Hand-tuned scripts and settings survive repeated `ptbk coder init`; migrations recognize generated entries only.
  *
  * @private function of `initializeCoderProjectConfiguration`
  */
@@ -71,6 +75,7 @@ export async function mergeStringRecordJsonFile({
     fieldPath,
     nextEntries,
     ensureParentDirectoryPath,
+    transformExistingEntries,
 }: MergeStringRecordJsonFileOptions): Promise<MergedStringRecordJsonFile> {
     if (ensureParentDirectoryPath) {
         await mkdir(join(projectPath, ensureParentDirectoryPath), { recursive: true });
@@ -83,7 +88,7 @@ export async function mergeStringRecordJsonFile({
     const existingEntries = getStringRecordOrDefault(jsonObject[fieldPath], relativeFilePath, fieldPath);
 
     const addedEntryKeys: Array<string> = [];
-    const mergedEntries = { ...existingEntries };
+    const mergedEntries = { ...((await transformExistingEntries?.(existingEntries)) ?? existingEntries) };
     for (const [entryKey, entryValue] of Object.entries(nextEntries)) {
         if (Object.prototype.hasOwnProperty.call(mergedEntries, entryKey)) {
             // Note: The project already defines this entry, keep its own value untouched
@@ -93,8 +98,13 @@ export async function mergeStringRecordJsonFile({
         mergedEntries[entryKey] = entryValue;
         addedEntryKeys.push(entryKey);
     }
+    for (const entryKey of Object.keys(mergedEntries)) {
+        if (!Object.prototype.hasOwnProperty.call(existingEntries, entryKey) && !addedEntryKeys.includes(entryKey)) {
+            addedEntryKeys.push(entryKey);
+        }
+    }
 
-    const hasChanges = fileContent === undefined || addedEntryKeys.length > 0;
+    const hasChanges = fileContent === undefined || JSON.stringify(mergedEntries) !== JSON.stringify(existingEntries);
     if (!hasChanges) {
         return { status: 'unchanged', addedEntryKeys };
     }