@promptbook/cli 0.114.0-42 → 0.114.0-48

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

@@ -0,0 +1,152 @@
+import { randomUUID } from 'crypto';
+import { readFile, rename, stat, unlink, writeFile } from 'fs/promises';
+import { join } from 'path';
+import { spaceTrim } from 'spacetrim';
+import { createTeamToolName } from '../../../book-2.0/agent-source/createTeamToolName';
+import { filterCommitmentsForAgentModelRequirements } from '../../../book-2.0/agent-source/createAgentModelRequirementsWithCommitments/filterCommitmentsForAgentModelRequirements';
+import { parseAgentSourceWithCommitments } from '../../../book-2.0/agent-source/parseAgentSourceWithCommitments';
+import { parseTeamCommitmentContent } from '../../../book-2.0/agent-source/parseTeamCommitment';
+import type { string_book } from '../../../book-2.0/agent-source/string_book';
+import { ParseError } from '../../../errors/ParseError';
+import { createLocalAgentReferenceResolver } from '../common/createLocalAgentReferenceResolver';
+import { LocalAgentBookCollection } from '../common/LocalAgentBookCollection';
+import { resolveBundledAgentBookPath } from '../common/resolveBundledAgentBookPath';
+import { readCoderAgentBook } from './readCoderAgentBook';
+
+/**
+ * Adds only missing bundled TEAM commitments using canonical local Book identities.
+ * Role instructions come from the bundled Book, not from a harness or a second template here.
+ *
+ * @private internal utility of `coder init`
+ */
+export async function augmentCoderAgentTeam(
+    projectPath: string,
+    role: 'developer' | 'planner',
+): Promise<'augmented' | 'unchanged'> {
+    const filePath = join(projectPath, 'agents', `${role}.book`);
+    const source = await readCoderAgentBook(filePath);
+    const collection = new LocalAgentBookCollection(join(projectPath, 'agents'), projectPath, false);
+    await collection.initialize();
+    const book = await collection.readBook(filePath);
+    const resolver = createLocalAgentReferenceResolver(collection, book);
+
+    /** Resolves active TEAM commitments without fetching remote profiles or executing any tools. */
+    async function resolveTeamUrls(agentSource: string_book): Promise<Set<string>> {
+        const urls = new Set<string>();
+        const commitments = filterCommitmentsForAgentModelRequirements(
+            parseAgentSourceWithCommitments(agentSource).commitments,
+        );
+        for (const commitment of commitments.filter(({ type }) => type === 'TEAM')) {
+            const content = await resolver.resolveCommitmentContent('TEAM', commitment.content);
+            const teammates = parseTeamCommitmentContent(content);
+            if (teammates.length === 0) {
+                throw new ParseError(
+                    spaceTrim(
+                        `Cannot resolve \`TEAM ${commitment.content}\` on line ${commitment.lineNumber}. Use a supported agent reference such as \`{./lawyer.book}\`.`,
+                    ),
+                );
+            }
+            teammates.forEach(({ url }) => urls.add(url));
+        }
+        return urls;
+    }
+
+    const existingUrls = await resolveTeamUrls(source);
+    const bundledSource = (await readFile(
+        await resolveBundledAgentBookPath(`agents/default/${role}.book`),
+        'utf-8',
+    )) as string_book;
+    const defaultTeams = parseAgentSourceWithCommitments(bundledSource).commitments.filter(
+        ({ type }) => type === 'TEAM',
+    );
+    const additions: string[] = [];
+    const requiredUrls = new Set<string>();
+    for (const commitment of defaultTeams) {
+        const content = await resolver.resolveCommitmentContent('TEAM', commitment.content);
+        const teammates = parseTeamCommitmentContent(content);
+        // Each bundled default declares one helper. Refuse a mixed declaration rather than duplicating a teammate.
+        if (teammates.length !== 1) {
+            throw new ParseError(spaceTrim('A bundled default TEAM commitment must reference exactly one helper.'));
+        }
+        for (const { url } of teammates) requiredUrls.add(url);
+        if (teammates.every(({ url }) => existingUrls.has(url))) continue;
+        additions.push(`TEAM ${commitment.content}`);
+    }
+    await assertNoConflictingTeamTools(collection, book.url, existingUrls, requiredUrls);
+    if (additions.length === 0) return 'unchanged';
+
+    const augmentedSource = insertTeamCommitments(source, additions);
+    const augmentedUrls = await resolveTeamUrls(augmentedSource);
+    if ([...requiredUrls].some((url) => !augmentedUrls.has(url))) {
+        throw new ParseError(
+            spaceTrim(
+                'Existing structural commitments remove a default TEAM reference. Resolve that conflict before initializing the team.',
+            ),
+        );
+    }
+    await replaceUnchangedBook(filePath, source, augmentedSource);
+    return 'augmented';
+}
+
+/** Refuses local names which would cause an added helper to share another Book's generated TEAM tool. */
+async function assertNoConflictingTeamTools(
+    collection: LocalAgentBookCollection,
+    primaryBookUrl: string,
+    existingUrls: ReadonlySet<string>,
+    requiredUrls: ReadonlySet<string>,
+): Promise<void> {
+    const localOrigin = new URL(primaryBookUrl).origin;
+    const booksByToolName = new Map<string, { url: string; filePath?: string }>();
+    // Check required helpers first so a conflict between those two is reported as well.
+    for (const url of new Set([...requiredUrls, ...existingUrls])) {
+        if (new URL(url).origin !== localOrigin) continue;
+        // Local references were registered by the resolver; this does not fetch remote teammate profiles.
+        const book = await collection.getBook(url);
+        const toolName = createTeamToolName(url, book.profile.agentName);
+        const previousBook = booksByToolName.get(toolName);
+        if (previousBook && (requiredUrls.has(url) || requiredUrls.has(previousBook.url))) {
+            throw new ParseError(
+                spaceTrim(
+                    `TEAM tool \`${toolName}\` conflicts between \`${previousBook.filePath}\` and \`${book.filePath}\`. Give these Books distinct names or META FULLNAME values before adding the default helper reference.`,
+                ),
+            );
+        }
+        booksByToolName.set(toolName, book);
+    }
+}
+
+/** Inserts at a parser-provided block boundary, preserving CLOSED, code examples, prose, and line endings. */
+function insertTeamCommitments(source: string_book, additions: ReadonlyArray<string>): string_book {
+    const parsed = parseAgentSourceWithCommitments(source);
+    const boundaries = [...parsed.commitments, ...parsed.unknownCommitments].map(({ lineNumber }) => lineNumber);
+    const lineEnding = source.includes('\r\n') ? '\r\n' : '\n';
+    const insertedText = additions.join(lineEnding) + lineEnding;
+    if (boundaries.length === 0) {
+        return (source + (source.endsWith('\n') ? '' : lineEnding) + lineEnding + insertedText) as string_book;
+    }
+    // The last block may be CLOSED/OPEN, a multiline commitment, or an unknown extension. Keep it intact.
+    const insertionLine = Math.max(...boundaries) - 1;
+    const lines = source.match(/[^\n]*\n|[^\n]+$/g) || [];
+    const offset = lines.slice(0, insertionLine).join('').length;
+    return (source.slice(0, offset) + insertedText + lineEnding + source.slice(offset)) as string_book;
+}
+
+/** Prepares the complete edit before replacing the file and refuses concurrent project edits. */
+async function replaceUnchangedBook(filePath: string, originalSource: string_book, source: string_book): Promise<void> {
+    const temporaryPath = `${filePath}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporaryPath, source, { flag: 'wx', mode: (await stat(filePath)).mode });
+        if ((await readCoderAgentBook(filePath)) !== originalSource) {
+            throw new ParseError(
+                spaceTrim(
+                    `Book \`${filePath}\` changed during initialization. Its new content was preserved; run init again.`,
+                ),
+            );
+        }
+        await rename(temporaryPath, filePath);
+    } finally {
+        await unlink(temporaryPath).catch((error: NodeJS.ErrnoException) => {
+            if (error.code !== 'ENOENT') throw error;
+        });
+    }
+}

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

@@ -0,0 +1,22 @@
+import { CODER_DEVELOPER_AGENT_FILE_PATH } from './ensureCoderDeveloperAgentFile';
+import { CODER_PLANNER_AGENT_FILE_PATH } from './ensureCoderRoleAgentFile';
+
+/**
+ * Project-owned Book defaults for execution roles, independent of harness and model selection.
+ * Commands without an execution role, such as `coder list`, have no default Book filter.
+ *
+ * @private internal constant of `ptbk coder`
+ */
+export const CODER_DEFAULT_AGENT_BOOK_PATHS = {
+    developer: CODER_DEVELOPER_AGENT_FILE_PATH,
+    planner: CODER_PLANNER_AGENT_FILE_PATH,
+} as const;
+
+/**
+ * Execution role whose editable local Book is selected when `--agent` is omitted.
+ *
+ * @private internal type of `ptbk coder`
+ */
+export type CoderAgentRole = keyof typeof CODER_DEFAULT_AGENT_BOOK_PATHS;
+
+// Note: [💞] Ignore a discrepancy between file name and exported helper names

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

@@ -4,20 +4,19 @@ 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.
+ * Status of one default Book or 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';
+export type CoderReferencedArtifactStatus = InitializationStatus | 'augmented' | 'unresolved' | 'not-referenced';
 
 /**
- * Result of ensuring one artifact referenced by the default coder scripts.
+ * Result of ensuring one default Book or artifact referenced by the default coder scripts.
  *
  * @private internal utility of `coder init` command
  */
@@ -28,9 +27,12 @@ export type EnsuredCoderReferencedArtifact = {
     readonly relativeFilePath: string;
 
     /**
-     * Status describing whether the artifact had to be created.
+     * Status describing whether the artifact was created, augmented, preserved, or could not be resolved.
      */
     readonly status: CoderReferencedArtifactStatus;
+
+    /** Explanation of an unresolved file or TEAM declaration, with the original content preserved. */
+    readonly diagnostic?: string;
 };
 
 /**
@@ -64,10 +66,6 @@ function createCoderPromptTemplateArtifactDefinition(
  * 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) =>
@@ -77,10 +75,9 @@ const CODER_REFERENCED_ARTIFACT_DEFINITIONS: ReadonlyArray<CoderReferencedArtifa
 ];
 
 /**
- * Creates only those referenced artifacts which the freshly added coder scripts point at.
+ * Initializes artifacts referenced by freshly added scripts. Default Books are ensured separately.
  *
- * 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.
+ * For artifacts other than role Books, an existing project script does not cause default files to be created.
  *
  * @private function of `initializeCoderProjectConfiguration`
  */

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

@@ -0,0 +1,90 @@
+import { join } from 'path';
+import { spaceTrim } from 'spacetrim';
+import { ADAM_AGENT_BOOK_RELATIVE_PATH, ensureAdamAgentBook } from '../common/ensureAdamAgentBook';
+import { augmentCoderAgentTeam } from './augmentCoderAgentTeam';
+import type { EnsuredCoderReferencedArtifact } from './coderReferencedArtifacts';
+import { ensureCoderRoleAgentFile } from './ensureCoderRoleAgentFile';
+import { readCoderAgentBook } from './readCoderAgentBook';
+
+/** Project-owned roles created independently of package-script changes. */
+const CODER_DEFAULT_ROLES = ['developer', 'planner', 'lawyer', 'copywriter'] as const;
+
+/**
+ * Ensures every default Book independently, then adds missing helper declarations to the two primary roles.
+ * A failure leaves the affected Book intact and does not prevent the remaining files from being initialized.
+ *
+ * @private internal utility of `coder init`
+ */
+export async function ensureCoderDefaultAgentFiles(projectPath: string): Promise<EnsuredCoderReferencedArtifact[]> {
+    const artifacts: EnsuredCoderReferencedArtifact[] = [];
+    const definitions = [
+        {
+            relativeFilePath: `agents/${ADAM_AGENT_BOOK_RELATIVE_PATH}`,
+            ensureFile: () => ensureAdamAgentBook(join(projectPath, 'agents')),
+        },
+        ...CODER_DEFAULT_ROLES.map((role) => ({
+            relativeFilePath: `agents/${role}.book`,
+            ensureFile: () => ensureCoderRoleAgentFile(projectPath, role),
+        })),
+    ];
+    for (const { relativeFilePath, ensureFile } of definitions) {
+        try {
+            const filePath = join(projectPath, relativeFilePath);
+            let status: EnsuredCoderReferencedArtifact['status'] = 'unchanged';
+            try {
+                await readCoderAgentBook(filePath);
+            } catch (error) {
+                if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+                status = await ensureFile();
+                await readCoderAgentBook(filePath);
+            }
+            artifacts.push({ relativeFilePath, status });
+        } catch (error) {
+            artifacts.push({ relativeFilePath, status: 'unresolved', diagnostic: describeInitializationError(error) });
+        }
+    }
+
+    const unresolvedDependencies = artifacts.filter(
+        ({ relativeFilePath, status }) =>
+            status === 'unresolved' && !['agents/developer.book', 'agents/planner.book'].includes(relativeFilePath),
+    );
+    for (const role of ['developer', 'planner'] as const) {
+        const index = artifacts.findIndex(({ relativeFilePath }) => relativeFilePath === `agents/${role}.book`);
+        const artifact = artifacts[index]!;
+        if (artifact.status === 'unresolved') continue;
+        try {
+            if (unresolvedDependencies.length > 0) {
+                artifacts[index] = {
+                    ...artifact,
+                    status: 'unresolved',
+                    diagnostic: spaceTrim(
+                        `Default TEAM references could not be checked or added because these Books are unresolved: ${unresolvedDependencies
+                            .map(({ relativeFilePath }) => `\`${relativeFilePath}\``)
+                            .join(', ')}. Existing content was preserved.`,
+                    ),
+                };
+                continue;
+            }
+            const teamStatus = await augmentCoderAgentTeam(projectPath, role);
+            if (teamStatus === 'augmented' && artifact.status !== 'created') {
+                artifacts[index] = { ...artifact, status: teamStatus };
+            }
+        } catch (error) {
+            artifacts[index] = {
+                ...artifact,
+                status: 'unresolved',
+                diagnostic: spaceTrim(
+                    `Default TEAM references could not be safely added; existing content was preserved. ${describeInitializationError(
+                        error,
+                    )}`,
+                ),
+            };
+        }
+    }
+    return artifacts;
+}
+
+/** Retains filesystem error codes and Book diagnostics in the per-artifact initialization report. */
+function describeInitializationError(error: unknown): string {
+    return error instanceof Error ? error.message : String(error);
+}

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

@@ -1,7 +1,5 @@
-import { copyFile, stat } from 'fs/promises';
-import { join } from 'path';
-import { resolveBundledAgentBookPath } from '../common/resolveBundledAgentBookPath';
 import type { InitializationStatus } from './boilerplateTemplates';
+import { ensureCoderRoleAgentFile } from './ensureCoderRoleAgentFile';
 
 /**
  * Relative directory path for agents initialized by `ptbk coder init`.
@@ -30,24 +28,7 @@ export const DEFAULT_CODER_DEVELOPER_AGENT_SOURCE_FILE_PATH = 'agents/default/de
  * @private function of `initializeCoderProjectConfiguration`
  */
 export async function ensureCoderDeveloperAgentFile(projectPath: string): Promise<InitializationStatus> {
-    const absoluteFilePath = join(projectPath, CODER_DEVELOPER_AGENT_FILE_PATH);
-    if (await isExistingFile(absoluteFilePath)) {
-        return 'unchanged';
-    }
-
-    await copyFile(await resolveBundledAgentBookPath(DEFAULT_CODER_DEVELOPER_AGENT_SOURCE_FILE_PATH), absoluteFilePath);
-    return 'created';
-}
-
-/**
- * Checks whether a path exists and is a file.
- */
-async function isExistingFile(path: string): Promise<boolean> {
-    try {
-        return (await stat(path)).isFile();
-    } catch {
-        return false;
-    }
+    return ensureCoderRoleAgentFile(projectPath, 'developer');
 }
 
 // Note: [🟡] Code for coder init developer agent bootstrapping [ensureCoderDeveloperAgentFile](src/cli/cli-commands/coder/ensureCoderDeveloperAgentFile.ts) should never be published outside of `@promptbook/cli`

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

@@ -0,0 +1,36 @@
+import { constants } from 'fs';
+import { copyFile, mkdir } from 'fs/promises';
+import { join } from 'path';
+import { resolveBundledAgentBookPath } from '../common/resolveBundledAgentBookPath';
+import type { InitializationStatus } from './boilerplateTemplates';
+
+/**
+ * Project-owned planning role selected when `coder plan` has no explicit Book override.
+ * @private internal constant of Coder role resolution
+ */
+export const CODER_PLANNER_AGENT_FILE_PATH = 'agents/planner.book';
+
+/**
+ * Copies a bundled role without overwriting an existing project-owned Book, including on repeated init.
+ *
+ * @private internal utility of `coder init`
+ */
+export async function ensureCoderRoleAgentFile(
+    projectPath: string,
+    role: 'developer' | 'planner' | 'lawyer' | 'copywriter',
+): Promise<InitializationStatus> {
+    await mkdir(join(projectPath, 'agents'), { recursive: true });
+    try {
+        await copyFile(
+            await resolveBundledAgentBookPath(`agents/default/${role}.book`),
+            join(projectPath, 'agents', `${role}.book`),
+            constants.COPYFILE_EXCL,
+        );
+        return 'created';
+    } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === 'EEXIST') {
+            return 'unchanged';
+        }
+        throw error;
+    }
+}

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

@@ -4,6 +4,8 @@ import type {
 } from 'commander';
 import spaceTrim from 'spacetrim';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
+import { $preflightWorkspaceRepository } from '../common/workspaceRepository';
+import { addWorkspaceRepositoryOptions } from '../common/workspaceRepositoryCliOptions';
 import { handleActionErrors } from '../common/handleActionErrors';
 
 /**
@@ -25,15 +27,22 @@ export function $initializeCoderFindFreshEmojiTagCommand(program: Program): $sid
         `),
     );
 
+    addWorkspaceRepositoryOptions(command);
+
     command.action(
-        handleActionErrors(async () => {
+        handleActionErrors(async (cliOptions) => {
+            const workspace = await $preflightWorkspaceRepository({
+                policy: 'read-only',
+                isAskingQuestionsEnabled: cliOptions.questions,
+            });
+
             // Note: Import the function dynamically to avoid loading heavy dependencies until needed
             const { findFreshEmojiTag } = await import(
                 '../../../../scripts/find-fresh-emoji-tags/find-fresh-emoji-tags'
             );
 
             try {
-                await findFreshEmojiTag();
+                await findFreshEmojiTag(workspace.projectPath);
             } catch (error) {
                 console.error(colors.bgRed('Failed to find fresh emoji tags:'), error);
                 return process.exit(1);

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

@@ -13,6 +13,8 @@ import {
 import { assertsError } from '../../../errors/assertsError';
 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 { handleActionErrors } from '../common/handleActionErrors';
 
 /**
@@ -51,6 +53,8 @@ export function $initializeCoderFindRefactorCandidatesCommand(program: Program):
         createPositiveIntegerOptionParser('--limit'),
     );
 
+    addWorkspaceRepositoryOptions(command);
+
     command.action(
         handleActionErrors(async (cliOptions) => {
             const { level = DEFAULT_REFACTOR_CANDIDATE_LEVEL, limit } = cliOptions as {
@@ -58,13 +62,18 @@ export function $initializeCoderFindRefactorCandidatesCommand(program: Program):
                 readonly limit?: number;
             };
 
+            const workspace = await $preflightWorkspaceRepository({
+                policy: 'mutate',
+                isAskingQuestionsEnabled: cliOptions.questions,
+            });
+
             // Note: Import the function dynamically to avoid loading heavy dependencies until needed
             const { findRefactorCandidates } = await import(
                 '../../../../scripts/find-refactor-candidates/find-refactor-candidates'
             );
 
             try {
-                await findRefactorCandidates({ level, limit });
+                await findRefactorCandidates({ level, limit, projectPath: workspace.projectPath });
             } catch (error) {
                 assertsError(error);
                 console.error(colors.bgRed(`${error.name}`));

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

@@ -2,6 +2,8 @@ import colors from 'colors';
 import { Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */ } from 'commander';
 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 { handleActionErrors } from '../common/handleActionErrors';
 
 /**
@@ -16,19 +18,26 @@ export function $initializeCoderFindUnwrittenCommand(program: Program): $side_ef
     command.description('List all prompt sections that still need to be authored (contain @@@ placeholder)');
     command.option('--priority <minimum-priority>', 'Filter prompts by minimum priority level', parseIntOption, 0);
 
+    addWorkspaceRepositoryOptions(command);
+
     command.action(
         handleActionErrors(async (cliOptions) => {
             const { priority = 0 } = cliOptions as {
                 readonly priority?: number;
             };
 
+            const workspace = await $preflightWorkspaceRepository({
+                policy: 'read-only',
+                isAskingQuestionsEnabled: cliOptions.questions,
+            });
+
             // Note: Import the function dynamically to avoid loading heavy dependencies until needed
             const { findUnwrittenPrompts } = await import(
                 '../../../../scripts/run-codex-prompts/main/findUnwrittenPrompts'
             );
 
             try {
-                await findUnwrittenPrompts({ priority });
+                await findUnwrittenPrompts({ priority, projectPath: workspace.projectPath });
             } catch (error) {
                 assertsError(error);
                 console.error(colors.bgRed(`${error.name}`));

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

@@ -12,6 +12,8 @@ import {
     CODER_GIT_SYNC_DESCRIPTION,
     normalizeCoderGitSyncCliOptions,
 } from '../common/coderGitSyncCliOptions';
+import { $preflightWorkspaceRepository } from '../common/workspaceRepository';
+import { addWorkspaceRepositoryOptions } from '../common/workspaceRepositoryCliOptions';
 import { handleActionErrors } from '../common/handleActionErrors';
 import type { BoilerplateCount } from './boilerplateCount';
 import {
@@ -59,6 +61,8 @@ export function $initializeCoderGenerateBoilerplatesCommand(program: Program): $
     );
     addCoderGitSyncOptions(command);
 
+    addWorkspaceRepositoryOptions(command);
+
     command.action(
         handleActionErrors(async (cliOptions) => {
             const { count: countOption, template: templateOption } = cliOptions as {
@@ -68,14 +72,18 @@ export function $initializeCoderGenerateBoilerplatesCommand(program: Program): $
 
             const boilerplateCount = parseBoilerplateCount(countOption);
             const gitSync = normalizeCoderGitSyncCliOptions(cliOptions as CoderGitSyncCliOptions);
-            const projectPath = process.cwd();
+            const workspace = await $preflightWorkspaceRepository({
+                policy: 'mutate',
+                isAskingQuestionsEnabled: cliOptions.questions,
+            });
+            const { projectPath } = workspace;
 
             // Note: Import the git synchronization dynamically to keep the CLI fast for runs without `--commit`
             const { $commitCoderChanges, $startCoderGitSync } = await import(
                 '../../../../scripts/run-codex-prompts/git/coderGitSync'
             );
 
-            const commitScope = await $startCoderGitSync({ gitSync, projectPath });
+            const commitScope = await $startCoderGitSync({ gitSync, workspace });
 
             await generatePromptBoilerplate({
                 projectPath,
@@ -107,7 +115,7 @@ export async function generatePromptBoilerplate({
     readonly projectPath: string;
     readonly boilerplateCount: BoilerplateCount;
     readonly templateOption?: string;
-}): Promise<void> {
+}): Promise<ReadonlyArray<string>> {
     const { filesCount, promptsPerFileCount } = boilerplateCount;
 
     // Note: Import these dynamically to avoid circular dependencies and keep CLI fast
@@ -192,6 +200,7 @@ export async function generatePromptBoilerplate({
             ` Successfully created ${promptsCount} prompts in ${filesToCreate.length} prompt boilerplate files! `,
         ),
     );
+    return filesToCreate.map(({ filepath }) => filepath);
 }
 
 /**

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

@@ -0,0 +1,42 @@
+import { join, relative } from 'path';
+import type { WorkspaceRepositoryContext } from '../common/workspaceRepository';
+import { ADAM_AGENT_BOOK_RELATIVE_PATH } from '../common/ensureAdamAgentBook';
+import type { CoderReferencedArtifactStatus } from './coderReferencedArtifacts';
+import { CODER_AGENTS_DIRECTORY_PATH } from './ensureCoderDeveloperAgentFile';
+import type { CoderInitializationSummary } from './initializeCoderProjectConfiguration';
+
+/**
+ * Restricts an explicit initialization commit to the initializer's write set, in repository-relative paths.
+ * The shared snapshot still excludes pre-existing files that initialization did not actually change.
+ *
+ * @private internal utility of the shared project initializer
+ */
+export function getCoderInitializationCommitPaths(
+    workspace: WorkspaceRepositoryContext,
+    summary: CoderInitializationSummary,
+    boilerplatePaths: ReadonlyArray<string>,
+): ReadonlyArray<string> {
+    const artifacts: ReadonlyArray<{
+        readonly relativeFilePath: string;
+        readonly status: CoderReferencedArtifactStatus;
+    }> = [
+        { relativeFilePath: 'prompts/README.md', status: summary.promptsReadmeFileStatus },
+        {
+            relativeFilePath: `${CODER_AGENTS_DIRECTORY_PATH}/${ADAM_AGENT_BOOK_RELATIVE_PATH}`,
+            status: summary.adamAgentFileStatus,
+        },
+        { relativeFilePath: '.env', status: summary.envFileStatus },
+        { relativeFilePath: '.gitignore', status: summary.gitignoreFileStatus },
+        { relativeFilePath: 'package.json', status: summary.packageJsonFileStatus },
+        { relativeFilePath: '.vscode/settings.json', status: summary.vscodeSettingsFileStatus },
+        ...summary.referencedArtifactStatuses,
+    ];
+    return [
+        ...artifacts
+            .filter(({ status }) => status === 'created' || status === 'updated' || status === 'augmented')
+            .map(({ relativeFilePath }) => relativeFilePath),
+        ...boilerplatePaths,
+    ].map((path) => relative(workspace.repositoryRoot!, join(workspace.projectPath, path)).replace(/\\/gu, '/'));
+}
+
+// Note: [🟡] Code for initialization commit paths [getCoderInitializationCommitPaths](src/cli/cli-commands/coder/getCoderInitializationCommitPaths.ts) should never be published outside of `@promptbook/cli`

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

@@ -2,6 +2,7 @@ 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';
 
 /**
@@ -26,7 +27,7 @@ type CoderPackageJsonScriptDefinition = {
     /**
      * 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.
+     * Non-role artifacts are created with newly added scripts; role Books are always initialized when missing.
      */
     readonly referencedArtifactPaths: ReadonlyArray<string>;
 };
@@ -49,11 +50,15 @@ const DEFAULT_CODER_PACKAGE_JSON_SCRIPT_DEFINITIONS: ReadonlyArray<CoderPackageJ
         scriptCommand: `npx ptbk coder add --template ${formatCoderScriptFilePath(COMMON_PROMPT_TEMPLATE_FILE_PATH)}`,
         referencedArtifactPaths: [COMMON_PROMPT_TEMPLATE_FILE_PATH],
     },
+    {
+        scriptName: 'coder:plan',
+        scriptCommand: 'npx ptbk coder plan --harness openai-codex',
+        referencedArtifactPaths: [CODER_PLANNER_AGENT_FILE_PATH, COMMON_PROMPT_TEMPLATE_FILE_PATH],
+    },
     {
         scriptName: 'coder:run',
         scriptCommand: [
             'npx ptbk coder run --harness openai-codex --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(' '),