@promptbook/cli 0.114.0-5 → 0.114.0-50

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

@@ -0,0 +1,48 @@
+import type {
+    Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
+} from 'commander';
+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.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+export type CoderAgentCliOptions = {
+    readonly agent?: string;
+};
+
+/**
+ * Description shared by coder commands which accept an agent Book.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+export const CODER_AGENT_OPTION_DESCRIPTION =
+    'Book agent providing persona, instructions, identity and task routing; --harness selects the coding tool and --model selects its model';
+
+/**
+ * Registers the shared `--agent` option for coder commands.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+export function addCoderAgentOption(command: Program, defaultRole?: CoderAgentRole): void {
+    const defaultDescription = defaultRole
+        ? `Defaults to the project's ${defaultRole === 'developer' ? 'Developer' : 'Planner'} (${
+              CODER_DEFAULT_AGENT_BOOK_PATHS[defaultRole]
+          }); --agent overrides this Book`
+        : 'No default Book filter; omitting --agent includes tasks for all agents';
+    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/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/boilerplateCount.ts

@@ -29,7 +29,7 @@ export type BoilerplateCount = {
      * Number of prompts written into each generated file.
      *
      * Note: More than one prompt per file is an advanced option - each prompt is one separate
-     *       coding task separated by `---` and tagged with its own fresh emoji tag.
+     *       coding task separated by `---`, with all prompts in the file sharing its fresh emoji tag.
      */
     readonly promptsPerFileCount: number;
 };

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,30 +105,18 @@ 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(`
             -   @@@
             -   Keep in mind the DRY _(don't repeat yourself)_ principle.
             -   Do a proper analysis of the current functionality before you start implementing.
-            -   Add the changes into the [changelog](changelog/_current-preversion.md)
+            -   Add the changes into the [changelog](CHANGELOG.md)
+            -   Update the [README](README.md) if needed.
+            -   Update the [AGENTS.md](AGENTS.md) for the next job to be done if it makes sense.
         `),
         isDefaultProjectTemplate: true,
     },
-    {
-        id: 'agents-server',
-        relativeFilePath: join(PROMPTS_TEMPLATES_DIRECTORY_PATH, 'agents-server.md'),
-        slugPrefix: 'agents-server',
-        content: spaceTrim(`
-            -   @@@
-            -   Keep in mind the DRY _(don't repeat yourself)_ principle.
-            -   Do a proper analysis of the current functionality before you start implementing.
-            -   You are working with the [Agents Server](apps/agents-server)
-            -   If you need to do the database migration, do it
-            -   Add the changes into the [changelog](changelog/_current-preversion.md)
-        `),
-        isDefaultProjectTemplate: false,
-    },
 ] as const satisfies ReadonlyArray<CoderPromptTemplateDefinition>;
 
 /**
@@ -184,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/coderAgentRole.ts

@@ -0,0 +1,28 @@
+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;
+
+/**
+ * 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

@@ -0,0 +1,103 @@
+import { AGENTS_FILE_PATH, getDefaultCoderAgentsFileContent } from './agentsFile';
+import type { CoderPromptTemplateDefinition, InitializationStatus } from './boilerplateTemplates';
+import {
+    ensureDefaultCoderPromptTemplateFile,
+    getDefaultCoderProjectPromptTemplateDefinitions,
+} from './boilerplateTemplates';
+import { ensureCoderMarkdownFile } from './ensureCoderMarkdownFile';
+
+/**
+ * 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 | 'augmented' | 'unresolved' | 'not-referenced';
+
+/**
+ * Result of ensuring one default Book or 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 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;
+};
+
+/**
+ * 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: AGENTS_FILE_PATH,
+        ensureArtifactFile: (projectPath) =>
+            ensureCoderMarkdownFile(projectPath, AGENTS_FILE_PATH, getDefaultCoderAgentsFileContent()),
+    },
+    ...getDefaultCoderProjectPromptTemplateDefinitions().map(createCoderPromptTemplateArtifactDefinition),
+];
+
+/**
+ * Initializes essential context and artifacts referenced by freshly added scripts. Books are ensured separately.
+ *
+ * AGENTS.md is essential even when every script already exists or uses implicit defaults.
+ *
+ * @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 (relativeFilePath !== AGENTS_FILE_PATH && !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/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,8 +1,5 @@
-import { copyFile, stat } from 'fs/promises';
-import { join } from 'path';
-import { spaceTrim } from 'spacetrim';
-import { NotAllowed } from '../../../errors/NotAllowed';
 import type { InitializationStatus } from './boilerplateTemplates';
+import { ensureCoderRoleAgentFile } from './ensureCoderRoleAgentFile';
 
 /**
  * Relative directory path for agents initialized by `ptbk coder init`.
@@ -31,49 +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 resolveDefaultCoderDeveloperAgentFilePath(), absoluteFilePath);
-    return 'created';
-}
-
-/**
- * Resolves the bundled developer agent from a source checkout or generated CLI package.
- */
-async function resolveDefaultCoderDeveloperAgentFilePath(): Promise<string> {
-    const candidates = [
-        join(__dirname, '..', DEFAULT_CODER_DEVELOPER_AGENT_SOURCE_FILE_PATH),
-        join(__dirname, '..', '..', '..', '..', DEFAULT_CODER_DEVELOPER_AGENT_SOURCE_FILE_PATH),
-    ];
-
-    for (const candidate of candidates) {
-        if (await isExistingFile(candidate)) {
-            return candidate;
-        }
-    }
-
-    throw new NotAllowed(
-        spaceTrim(`
-            Cannot find the bundled Promptbook developer agent.
-
-            Checked:
-            ${candidates.map((candidate) => `- \`${candidate}\``).join('\n')}
-        `),
-    );
-}
-
-/**
- * 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/ensureCoderGitattributesFile.ts

@@ -0,0 +1,25 @@
+import { ensureProjectTextFile } from '../common/ensureProjectTextFile';
+import type { InitializationStatus } from './boilerplateTemplates';
+
+/**
+ * Project-relative path to the Git attributes initialized by Promptbook Coder.
+ *
+ * @private internal constant of `coder init`
+ */
+export const CODER_GITATTRIBUTES_FILE_PATH = '.gitattributes';
+
+/**
+ * Default Git attributes for automatic text detection and consistent LF line endings.
+ */
+const DEFAULT_CODER_GITATTRIBUTES_CONTENT = '* text=auto eol=lf';
+
+/**
+ * Creates default Git attributes when missing, preserving project-owned attributes.
+ *
+ * @private function of `initializeCoderProjectConfiguration`
+ */
+export async function ensureCoderGitattributesFile(projectPath: string): Promise<InitializationStatus> {
+    return ensureProjectTextFile(projectPath, CODER_GITATTRIBUTES_FILE_PATH, DEFAULT_CODER_GITATTRIBUTES_CONTENT);
+}
+
+// Note: [🟡] Code for coder init Git attributes bootstrapping [ensureCoderGitattributesFile](src/cli/cli-commands/coder/ensureCoderGitattributesFile.ts) should never be published outside of `@promptbook/cli`