@promptbook/utils 0.114.0-47 → 0.114.0-49

package/README.md

@@ -710,7 +710,7 @@ Promptbook Coder is **not another standalone coding model**. It is an orchestrat
 
 -   prompt files with explicit statuses like `[ ]`, `[^]`, `[x]`, and `[-]`
 -   automatic selection of the next runnable task, including priority support
--   optional shared repo context loaded from a file such as `AGENTS.md`
+-   shared project context loaded from `AGENTS.md` by default
 -   automatic `git add`, commit, and push after each successful prompt
 -   dedicated coding-agent Git identity and optional GPG signing
 -   verification and repair flow for work that is done, partial, or broken
@@ -732,7 +732,7 @@ Prompts marked with `[-]` are not ready yet, prompts containing `@@@` are treate
 #### Features
 
 -   **Multi-runner execution:** `openai-codex`, `github-copilot`, `cline`, `claude-code`, `opencode`, `gemini`, `qwen-code`
--   **Context injection:** `--agent agents/coding/developer.book --context AGENTS.md` or inline extra instructions
+-   **Project defaults:** Developer, invocation cwd, and project `AGENTS.md`; `--agent`, `--path`, and `--context` independently override them
 -   **Reasoning control:** `--thinking-level low|medium|high|xhigh` for supported runners
 -   **Unattended or interactive runs:** default auto mode, or `--no-auto` to wait for user confirmation before each prompt
 -   **Git safety:** clean working tree check by default, or `--git-changes ignore` to keep the changes and `--git-changes continue` to resume an interrupted prompt
@@ -752,11 +752,11 @@ npx ts-node ./src/cli/test/ptbk.ts coder generate-boilerplates --template prompt
 
 npx ts-node ./src/cli/test/ptbk.ts coder generate-boilerplates --template prompts/templates/agents-server.md
 
-npx ts-node ./src/cli/test/ptbk.ts coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --context AGENTS.md
+npx ts-node ./src/cli/test/ptbk.ts coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book
 
-npx ts-node ./src/cli/test/ptbk.ts coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --context AGENTS.md --auto-push
+npx ts-node ./src/cli/test/ptbk.ts coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --auto-push
 
-npx ts-node ./src/cli/test/ptbk.ts coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --context AGENTS.md --git-changes ignore
+npx ts-node ./src/cli/test/ptbk.ts coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --git-changes ignore
 
 npx ts-node ./src/cli/test/ptbk.ts coder find-refactor-candidates
 
@@ -778,11 +778,11 @@ ptbk coder generate-boilerplates
 
 ptbk coder generate-boilerplates --template prompts/templates/common.md
 
-ptbk coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --context AGENTS.md --test npm run test
+ptbk coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --check "npm run check"
 
-ptbk coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --context AGENTS.md --auto-push
+ptbk coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --auto-push
 
-ptbk coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --context AGENTS.md --test npm run test --git-changes ignore
+ptbk coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --check "npm run check" --git-changes ignore
 
 ptbk coder find-refactor-candidates
 
@@ -799,33 +799,52 @@ ptbk coder verify
 | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | ------ | ---- | ----- | ------------------------------------------------------------------------ |
 | `ptbk coder init`                     | Creates `prompts/`, `prompts/done/`, the project-generic template files materialized in `prompts/templates/` (currently `common.md`), and a starter `AGENTS.md`; ensures `.env` contains `CODING_AGENT_GIT_NAME`, `CODING_AGENT_GIT_EMAIL`, and `CODING_AGENT_GIT_SIGNING_KEY`; adds helper coder scripts to `package.json`; ensures `.gitignore` contains `/.promptbook`; and configures `.vscode/settings.json` to save pasted prompt images into `prompts/screenshots/`. |
 | `ptbk coder generate-boilerplates`    | Creates new prompt markdown files with fresh emoji tags so you can quickly fill in coding tasks; `--template` accepts either a built-in alias or a markdown file path relative to the project root.                                                                                                                                                                                                                                                                         |
-| `ptbk coder run`                      | Picks the next ready prompt, can run tests before coding to stop or repair pre-existing failures, appends optional context, runs it through the selected coding agent, can optionally verify each attempt with a shell test command and feed failing output back for retries, then marks success or failure, commits the result, and pushes only when `--auto-push` is enabled.                                                                                             |
+| `ptbk coder run`                      | Picks the next ready prompt, can run project checks before coding to stop or repair pre-existing failures, appends optional context, runs it through the selected coding agent, can optionally check each attempt with the project command and feed failing output back for retries, then marks success or failure, commits the result, and pushes only when `--auto-push` is enabled.                                                                                      |
 | `ptbk coder find-refactor-candidates` | Scans the repository for oversized or overpacked files and writes prompt files for likely refactors; `--level <xlow                                                                                                                                                                                                                                                                                                                                                         | low | medium | high | xhigh | extreme>` ranges from a very benevolent scan to a very aggressive sweep. |
 | `ptbk coder verify`                   | Walks through completed prompts, archives truly finished work, and adds follow-up repair prompts for unfinished results.                                                                                                                                                                                                                                                                                                                                                    |
 
 #### Most useful `ptbk coder run` flags
 
-| Flag                       | Purpose                                                                                                                                                                                |
-| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--harness <name>`         | Selects the coding harness.                                                                                                                                                            |
-| `--model <model>`          | Chooses the runner model; required for `openai-codex`, `gemini` and `qwen-code`, optional for `github-copilot`.                                                                        |
-| `--context <text-or-file>` | Appends extra instructions inline or from a file like `AGENTS.md`.                                                                                                                     |
-| `--test <command>`         | Runs a verification command after each prompt attempt and feeds failing output back for retries.                                                                                       |
-| `--test-before <mode>`     | Runs tests before coding: `no` (default), `yes-and-fail` (stop with results), or `yes-and-fix` (create one repair prompt first); defaults to `npm test` when enabled without `--test`. |
-| `--thinking-level <level>` | Sets reasoning effort for supported runners.                                                                                                                                           |
-| `--no-auto`                | Waits for user confirmation before each prompt instead of running automatically through the queue.                                                                                     |
-| `--git-changes <mode>`     | Decides what happens with a dirty working tree: `fail` (default), `ignore` to keep the changes, or `continue` to resume the single interrupted `[^]` prompt with them.                 |
-| `--priority <n>`           | Runs only prompts at or above the given priority.                                                                                                                                      |
-| `--dry-run`                | Prints which prompts are ready instead of executing them.                                                                                                                              |
-| `--allow-credits`          | Lets OpenAI Codex spend credits when required.                                                                                                                                         |
-| `--auto-push`              | Pushes each successful coding-agent commit to the configured remote.                                                                                                                   |
-| `--auto-migrate`           | Runs testing-server database migrations after each successful prompt.                                                                                                                  |
+A **check** is the project's aggregate validation: tests, linting, typechecking, builds, generated-code consistency,
+and other quality checks. `ptbk init` and `ptbk coder init` preserve an existing `scripts.check`, or compose available
+validation scripts and report their scope. Configure the failing setup placeholder if the project has none.
+
+```bash
+ptbk coder run --harness openai-codex --check "npm run check" --check-before yes-and-fix
+ptbk coder run --harness openai-codex --check "npm run lint && npm run build && npm test"
+```
+
+The default preflight mode remains `no`. Enabled preflight uses `npm run check` when no command is supplied;
+post-prompt verification remains opt-in. Initial checks and repairs use the same command and actual process result.
+Replace retired `--test` and `--test-before` with `--check` and `--check-before`. Init migrates recognized generated
+scripts while preserving custom validation. For conflicts or custom callers, it reports the exact entries/files to
+review: preserve the required validation in `check`, update references, then remove the unused legacy entry.
+Automation that invokes `npm run test-for-ptbk-coder` must switch to `npm run check`. Restart an already-running
+Coder invocation with the new flags to release its captured legacy command; initialization creates no compatibility alias.
+
+| Flag                       | Purpose                                                                                                                                                                                               |
+| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--harness <name>`         | Selects the coding harness.                                                                                                                                                                           |
+| `--agent <book>`           | Selects the primary Book; defaults to the selected project's `agents/developer.book`.                                                                                                                 |
+| `--path <directory>`       | Selects the project; defaults to invocation cwd. Relative paths start there, not at the CLI installation or enclosing Git root.                                                                       |
+| `--model <model>`          | Chooses the runner model; required for `openai-codex`, `gemini` and `qwen-code`, optional for `github-copilot`.                                                                                       |
+| `--context <text-or-file>` | Replaces the default project `AGENTS.md` with inline instructions or a project-relative file; an empty value disables context.                                                                        |
+| `--check <command>`        | Runs a verification command after each prompt attempt and feeds failing output back for retries.                                                                                                      |
+| `--check-before <mode>`    | Runs project checks before coding: `no` (default), `yes-and-fail` (stop with results), or `yes-and-fix` (create one repair prompt first); defaults to `npm run check` when enabled without `--check`. |
+| `--thinking-level <level>` | Sets reasoning effort for supported runners.                                                                                                                                                          |
+| `--no-auto`                | Waits for user confirmation before each prompt instead of running automatically through the queue.                                                                                                    |
+| `--git-changes <mode>`     | Decides what happens with a dirty working tree: `fail` (default), `ignore` to keep the changes, or `continue` to resume the single interrupted `[^]` prompt with them.                                |
+| `--priority <n>`           | Runs only prompts at or above the given priority.                                                                                                                                                     |
+| `--dry-run`                | Prints which prompts are ready instead of executing them.                                                                                                                                             |
+| `--allow-credits`          | Lets OpenAI Codex spend credits when required.                                                                                                                                                        |
+| `--auto-push`              | Pushes each successful coding-agent commit to the configured remote.                                                                                                                                  |
+| `--auto-migrate`           | Runs testing-server database migrations after each successful prompt.                                                                                                                                 |
 
 #### Typical usage pattern
 
 1. Initialize once with `ptbk coder init`.
 2. Customize `prompts/templates/*.md` if needed, then create or write prompt files in `prompts/`.
-3. Customize the starter `AGENTS.md` with repository-specific instructions, then pass `--agent agents/coding/developer.book --context AGENTS.md`.
+3. Customize `agents/developer.book` and `AGENTS.md`; the runner selects both automatically. Use `--path` for another project or `--agent` and `--context` for explicit overrides.
 4. Run unattended batches by default, or pass `--no-auto` to confirm each prompt interactively.
 5. Finish with `ptbk coder verify` so resolved prompts are archived and broken ones get explicit repair follow-ups.
 

package/esm/index.es.js

@@ -17,7 +17,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.114.0-47';
+const PROMPTBOOK_ENGINE_VERSION = '0.114.0-49';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name

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

@@ -20,3 +20,8 @@ export declare const CODER_AGENT_OPTION_DESCRIPTION = "Book agent providing pers
  * @private internal utility of `ptbk coder`
  */
 export declare function addCoderAgentOption(command: Program, defaultRole?: CoderAgentRole): void;
+/**
+ * Registers the shared optional persona and context for single-agent execution or authoring.
+ * @private internal CLI registration helper
+ */
+export declare function addCoderExecutionOptions(command: Program): void;

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

@@ -14,3 +14,8 @@ export declare const CODER_DEFAULT_AGENT_BOOK_PATHS: {
  * @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 declare const DEFAULT_CODER_AGENT_ROLE: CoderAgentRole;

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

@@ -25,9 +25,9 @@ export type EnsuredCoderReferencedArtifact = {
     readonly diagnostic?: string;
 };
 /**
- * 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`
  */

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

@@ -1,9 +1,10 @@
 import type { MergedStringRecordJsonFile } from './mergeStringRecordJsonFile';
+import { type PreparedCoderPackageJsonScripts } from './prepareCoderPackageJsonScripts';
 /**
  * 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 declare function ensureCoderPackageJsonFile(projectPath: string): Promise<MergedStringRecordJsonFile>;
+export declare function ensureCoderPackageJsonFile(projectPath: string): Promise<MergedStringRecordJsonFile & Omit<PreparedCoderPackageJsonScripts, 'scripts'>>;

package/esm/src/cli/cli-commands/coder/ensureCoderPackageJsonFile.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,5 @@
+/**
+ * Finds external project callers conservatively; it never rewrites their shell expressions.
+ * @private migration safety check for the Coder initializer
+ */
+export declare function findLegacyCoderCheckCallers(projectPath: string, legacyNames: ReadonlyArray<string>): Promise<Readonly<Record<string, ReadonlyArray<string>>>>;

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

@@ -20,6 +20,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;
 };
 /**
  * Creates or updates all coder configuration artifacts required in the current project.

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

@@ -8,6 +8,8 @@ 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>>>;
 };
 /**
  * Result of one additive string-record merge into a JSON file.
@@ -27,10 +29,10 @@ export type MergedStringRecordJsonFile = {
 /**
  * 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`
  */
-export declare function mergeStringRecordJsonFile({ projectPath, relativeFilePath, fieldPath, nextEntries, ensureParentDirectoryPath, }: MergeStringRecordJsonFileOptions): Promise<MergedStringRecordJsonFile>;
+export declare function mergeStringRecordJsonFile({ projectPath, relativeFilePath, fieldPath, nextEntries, ensureParentDirectoryPath, transformExistingEntries, }: MergeStringRecordJsonFileOptions): Promise<MergedStringRecordJsonFile>;
 export {};

package/esm/src/cli/cli-commands/coder/planning/runPlanningSession.d.ts

@@ -1,3 +1,4 @@
+import { type ResolvedCoderProjectContext } from '../../../../../scripts/run-codex-prompts/common/resolveCoderProjectContext';
 import type { NormalizedPromptRunnerSelectionCliOptions } from '../../common/promptRunnerCliOptions';
 import { runPlanningHarness } from './runPlanningHarness';
 /**
@@ -16,6 +17,8 @@ export type PlanningSessionIo = {
 export declare function runPlanningSession(options: NormalizedPromptRunnerSelectionCliOptions & {
     readonly projectPath: string;
     readonly agent?: string;
+    readonly context?: string;
+    readonly projectContext?: ResolvedCoderProjectContext;
     readonly template?: string;
     readonly preexistingChangedPaths?: ReadonlySet<string>;
 }, io: PlanningSessionIo, harness?: typeof runPlanningHarness): Promise<ReadonlyMap<string, string>>;

package/esm/src/cli/cli-commands/coder/prepareCoderPackageJsonScripts.d.ts

@@ -0,0 +1,12 @@
+/** Result of preparing project-owned checks and migrating recognized generated callers. @private internal initializer result */
+export type PreparedCoderPackageJsonScripts = {
+    readonly scripts: Readonly<Record<string, string>>;
+    readonly checkScriptSummary: string;
+    readonly migrationInstructions: ReadonlyArray<string>;
+    readonly isCheckConfigured: boolean;
+};
+/**
+ * Preserves project scripts, creates one canonical check, and migrates only exact generated caller forms.
+ * @private shared package-script preparation for Coder initialization
+ */
+export declare function prepareCoderPackageJsonScripts(existing: Readonly<Record<string, string>>, externalCallers?: Readonly<Record<string, ReadonlyArray<string>>>): PreparedCoderPackageJsonScripts;

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

@@ -6,7 +6,7 @@ import type { $side_effect } from '../../utils/organization/$side_effect';
  * The coder command provides utilities for automated coding:
  * - init: Initialize coder configuration in current project
  * - add: Add one ready-to-run prompt file to the queue
- * - plan: Discuss features with Planner and author reviewed PRDs
+ * - plan: Discuss features with Developer and author reviewed PRDs
  * - generate-boilerplates: Generate prompt boilerplate files
  * - find-refactor-candidates: Find files that need refactoring
  * - list: List ready prompts in priority order without running them

package/esm/src/cli/cli-commands/common/coderCheckCliOptions.d.ts

@@ -0,0 +1,21 @@
+import { Command } from 'commander';
+/**
+ * Retired aggregate option spellings and their canonical replacements, used only for migration diagnostics.
+ * @private shared CLI migration definitions for Coder execution
+ */
+export declare const LEGACY_CODER_CHECK_OPTIONS: readonly [readonly ["--test", "--check"], readonly ["--test-before", "--check-before"]];
+/**
+ * Registers the shared project check command and rejects retired aggregate-test spellings.
+ * @private shared CLI registration for Coder execution
+ */
+export declare function addCoderCheckOptions(command: Command, isCheckBeforeSupported: boolean): void;
+/**
+ * Builds the same actionable migration diagnostic for registered and direct-script entrypoints.
+ * @private shared CLI diagnostic for Coder execution
+ */
+export declare function formatLegacyCoderCheckOptionError(legacyFlag: string, replacementFlag: string): string;
+/**
+ * Normalizes shell command tokens without parsing a quoted command again or losing spaced argument boundaries.
+ * @private shared command normalization for Coder execution
+ */
+export declare function normalizeCheckCommandOption(value: string | ReadonlyArray<string> | undefined): string | undefined;

package/esm/src/cli/cli-commands/common/coderCheckCliOptions.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/src/cli/cli-commands/common/projectCliOptions.d.ts

@@ -0,0 +1,30 @@
+import type { Command } from 'commander';
+/**
+ * Optional project selection shared by workspace actions, independently of Book and harness selection.
+ * @private internal CLI options
+ */
+export type ProjectCliOptions = {
+    readonly path?: string;
+};
+/**
+ * Registers project selection without capturing a directory during command registration.
+ * @private internal CLI registration helper
+ */
+export declare function addProjectPathOption(command: Command): void;
+/**
+ * Registers additional context independently of primary-agent selection.
+ * @private internal CLI registration helper
+ */
+export declare function addProjectContextOption(command: Command): void;
+/**
+ * Captures an invocation's directory at action time. No process-global state is changed.
+ * @private internal CLI normalization helper
+ */
+export declare function normalizeProjectCliOptions(options: ProjectCliOptions, invocationDirectory?: string): {
+    readonly projectDirectory: string;
+};
+/**
+ * Validates the selected directory before any setup writes, without selecting an enclosing Git root.
+ * @private shared project resolution for CLI services
+ */
+export declare function resolveProjectDirectory(projectDirectory: string): Promise<string>;

package/esm/src/cli/cli-commands/common/projectCliOptions.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/src/cli/cli-commands/common/promptbook-cli/$checkPromptbookCliInstallations.d.ts

@@ -6,4 +6,4 @@ import type { PromptbookCliInstallationStatus } from './PromptbookCliInstallatio
  *
  * @private internal utility of `promptbookCli`
  */
-export declare function $checkPromptbookCliInstallations(): Promise<ReadonlyArray<PromptbookCliInstallationStatus>>;
+export declare function $checkPromptbookCliInstallations(projectPath?: string): Promise<ReadonlyArray<PromptbookCliInstallationStatus>>;

package/esm/src/cli/cli-commands/common/promptbook-cli/$ensurePromptbookCliInstallations.d.ts

@@ -12,4 +12,4 @@ import type { NormalizedQuestionsCliOptions } from '../questionsCliOptions';
  * @returns `true` when at least one installation was updated and the current coder run should stop
  * @private internal utility of `promptbookCli`
  */
-export declare function $ensurePromptbookCliInstallations(questionsOptions: NormalizedQuestionsCliOptions): Promise<boolean>;
+export declare function $ensurePromptbookCliInstallations(questionsOptions: NormalizedQuestionsCliOptions, projectPath?: string): Promise<boolean>;

package/esm/src/cli/cli-commands/common/promptbook-cli/$resolvePromptbookCliInstallations.d.ts

@@ -9,4 +9,4 @@ import { type PromptbookCliInstallation } from './PromptbookCliInstallation';
  *
  * @private internal utility of `promptbookCli`
  */
-export declare function $resolvePromptbookCliInstallations(): Promise<ReadonlyArray<PromptbookCliInstallation>>;
+export declare function $resolvePromptbookCliInstallations(projectPath?: string): Promise<ReadonlyArray<PromptbookCliInstallation>>;

package/esm/src/cli/cli-commands/common/promptbook-cli/$updatePromptbookCliInstallation.d.ts

@@ -7,4 +7,4 @@ import type { PromptbookCliInstallationStatus } from './PromptbookCliInstallatio
  * @returns `true` when the package update succeeds, `false` when it fails
  * @private internal utility of `promptbookCli`
  */
-export declare function $updatePromptbookCliInstallation(status: PromptbookCliInstallationStatus): Promise<boolean>;
+export declare function $updatePromptbookCliInstallation(status: PromptbookCliInstallationStatus, projectPath?: string): Promise<boolean>;

package/esm/src/version.d.ts

@@ -15,7 +15,7 @@ export declare const BOOK_LANGUAGE_VERSION: string_semantic_version;
 export declare const PROMPTBOOK_ENGINE_VERSION: string_promptbook_version;
 /**
  * Represents the version string of the Promptbook engine.
- * It follows semantic versioning (e.g., `0.114.0-47`).
+ * It follows semantic versioning (e.g., `0.114.0-48`).
  *
  * @generated
  */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/utils",
-    "version": "0.114.0-47",
+    "version": "0.114.0-49",
     "description": "Promptbook: Create persistent AI agents that turn your company's scattered knowledge into action",
     "private": false,
     "sideEffects": false,

package/umd/index.umd.js

@@ -23,7 +23,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.114.0-47';
+    const PROMPTBOOK_ENGINE_VERSION = '0.114.0-49';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name

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

@@ -20,3 +20,8 @@ export declare const CODER_AGENT_OPTION_DESCRIPTION = "Book agent providing pers
  * @private internal utility of `ptbk coder`
  */
 export declare function addCoderAgentOption(command: Program, defaultRole?: CoderAgentRole): void;
+/**
+ * Registers the shared optional persona and context for single-agent execution or authoring.
+ * @private internal CLI registration helper
+ */
+export declare function addCoderExecutionOptions(command: Program): void;

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

@@ -14,3 +14,8 @@ export declare const CODER_DEFAULT_AGENT_BOOK_PATHS: {
  * @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 declare const DEFAULT_CODER_AGENT_ROLE: CoderAgentRole;

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

@@ -25,9 +25,9 @@ export type EnsuredCoderReferencedArtifact = {
     readonly diagnostic?: string;
 };
 /**
- * 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`
  */

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

@@ -1,9 +1,10 @@
 import type { MergedStringRecordJsonFile } from './mergeStringRecordJsonFile';
+import { type PreparedCoderPackageJsonScripts } from './prepareCoderPackageJsonScripts';
 /**
  * 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 declare function ensureCoderPackageJsonFile(projectPath: string): Promise<MergedStringRecordJsonFile>;
+export declare function ensureCoderPackageJsonFile(projectPath: string): Promise<MergedStringRecordJsonFile & Omit<PreparedCoderPackageJsonScripts, 'scripts'>>;

package/umd/src/cli/cli-commands/coder/ensureCoderPackageJsonFile.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,5 @@
+/**
+ * Finds external project callers conservatively; it never rewrites their shell expressions.
+ * @private migration safety check for the Coder initializer
+ */
+export declare function findLegacyCoderCheckCallers(projectPath: string, legacyNames: ReadonlyArray<string>): Promise<Readonly<Record<string, ReadonlyArray<string>>>>;

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

@@ -20,6 +20,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;
 };
 /**
  * Creates or updates all coder configuration artifacts required in the current project.

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

@@ -8,6 +8,8 @@ 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>>>;
 };
 /**
  * Result of one additive string-record merge into a JSON file.
@@ -27,10 +29,10 @@ export type MergedStringRecordJsonFile = {
 /**
  * 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`
  */
-export declare function mergeStringRecordJsonFile({ projectPath, relativeFilePath, fieldPath, nextEntries, ensureParentDirectoryPath, }: MergeStringRecordJsonFileOptions): Promise<MergedStringRecordJsonFile>;
+export declare function mergeStringRecordJsonFile({ projectPath, relativeFilePath, fieldPath, nextEntries, ensureParentDirectoryPath, transformExistingEntries, }: MergeStringRecordJsonFileOptions): Promise<MergedStringRecordJsonFile>;
 export {};

package/umd/src/cli/cli-commands/coder/planning/runPlanningSession.d.ts

@@ -1,3 +1,4 @@
+import { type ResolvedCoderProjectContext } from '../../../../../scripts/run-codex-prompts/common/resolveCoderProjectContext';
 import type { NormalizedPromptRunnerSelectionCliOptions } from '../../common/promptRunnerCliOptions';
 import { runPlanningHarness } from './runPlanningHarness';
 /**
@@ -16,6 +17,8 @@ export type PlanningSessionIo = {
 export declare function runPlanningSession(options: NormalizedPromptRunnerSelectionCliOptions & {
     readonly projectPath: string;
     readonly agent?: string;
+    readonly context?: string;
+    readonly projectContext?: ResolvedCoderProjectContext;
     readonly template?: string;
     readonly preexistingChangedPaths?: ReadonlySet<string>;
 }, io: PlanningSessionIo, harness?: typeof runPlanningHarness): Promise<ReadonlyMap<string, string>>;

package/umd/src/cli/cli-commands/coder/prepareCoderPackageJsonScripts.d.ts

@@ -0,0 +1,12 @@
+/** Result of preparing project-owned checks and migrating recognized generated callers. @private internal initializer result */
+export type PreparedCoderPackageJsonScripts = {
+    readonly scripts: Readonly<Record<string, string>>;
+    readonly checkScriptSummary: string;
+    readonly migrationInstructions: ReadonlyArray<string>;
+    readonly isCheckConfigured: boolean;
+};
+/**
+ * Preserves project scripts, creates one canonical check, and migrates only exact generated caller forms.
+ * @private shared package-script preparation for Coder initialization
+ */
+export declare function prepareCoderPackageJsonScripts(existing: Readonly<Record<string, string>>, externalCallers?: Readonly<Record<string, ReadonlyArray<string>>>): PreparedCoderPackageJsonScripts;

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

@@ -6,7 +6,7 @@ import type { $side_effect } from '../../utils/organization/$side_effect';
  * The coder command provides utilities for automated coding:
  * - init: Initialize coder configuration in current project
  * - add: Add one ready-to-run prompt file to the queue
- * - plan: Discuss features with Planner and author reviewed PRDs
+ * - plan: Discuss features with Developer and author reviewed PRDs
  * - generate-boilerplates: Generate prompt boilerplate files
  * - find-refactor-candidates: Find files that need refactoring
  * - list: List ready prompts in priority order without running them

package/umd/src/cli/cli-commands/common/coderCheckCliOptions.d.ts

@@ -0,0 +1,21 @@
+import { Command } from 'commander';
+/**
+ * Retired aggregate option spellings and their canonical replacements, used only for migration diagnostics.
+ * @private shared CLI migration definitions for Coder execution
+ */
+export declare const LEGACY_CODER_CHECK_OPTIONS: readonly [readonly ["--test", "--check"], readonly ["--test-before", "--check-before"]];
+/**
+ * Registers the shared project check command and rejects retired aggregate-test spellings.
+ * @private shared CLI registration for Coder execution
+ */
+export declare function addCoderCheckOptions(command: Command, isCheckBeforeSupported: boolean): void;
+/**
+ * Builds the same actionable migration diagnostic for registered and direct-script entrypoints.
+ * @private shared CLI diagnostic for Coder execution
+ */
+export declare function formatLegacyCoderCheckOptionError(legacyFlag: string, replacementFlag: string): string;
+/**
+ * Normalizes shell command tokens without parsing a quoted command again or losing spaced argument boundaries.
+ * @private shared command normalization for Coder execution
+ */
+export declare function normalizeCheckCommandOption(value: string | ReadonlyArray<string> | undefined): string | undefined;

package/umd/src/cli/cli-commands/common/coderCheckCliOptions.test.d.ts

@@ -0,0 +1 @@
+export {};

package/umd/src/cli/cli-commands/common/projectCliOptions.d.ts

@@ -0,0 +1,30 @@
+import type { Command } from 'commander';
+/**
+ * Optional project selection shared by workspace actions, independently of Book and harness selection.
+ * @private internal CLI options
+ */
+export type ProjectCliOptions = {
+    readonly path?: string;
+};
+/**
+ * Registers project selection without capturing a directory during command registration.
+ * @private internal CLI registration helper
+ */
+export declare function addProjectPathOption(command: Command): void;
+/**
+ * Registers additional context independently of primary-agent selection.
+ * @private internal CLI registration helper
+ */
+export declare function addProjectContextOption(command: Command): void;
+/**
+ * Captures an invocation's directory at action time. No process-global state is changed.
+ * @private internal CLI normalization helper
+ */
+export declare function normalizeProjectCliOptions(options: ProjectCliOptions, invocationDirectory?: string): {
+    readonly projectDirectory: string;
+};
+/**
+ * Validates the selected directory before any setup writes, without selecting an enclosing Git root.
+ * @private shared project resolution for CLI services
+ */
+export declare function resolveProjectDirectory(projectDirectory: string): Promise<string>;

package/umd/src/cli/cli-commands/common/projectCliOptions.test.d.ts

@@ -0,0 +1 @@
+export {};

package/umd/src/cli/cli-commands/common/promptbook-cli/$checkPromptbookCliInstallations.d.ts

@@ -6,4 +6,4 @@ import type { PromptbookCliInstallationStatus } from './PromptbookCliInstallatio
  *
  * @private internal utility of `promptbookCli`
  */
-export declare function $checkPromptbookCliInstallations(): Promise<ReadonlyArray<PromptbookCliInstallationStatus>>;
+export declare function $checkPromptbookCliInstallations(projectPath?: string): Promise<ReadonlyArray<PromptbookCliInstallationStatus>>;

package/umd/src/cli/cli-commands/common/promptbook-cli/$ensurePromptbookCliInstallations.d.ts

@@ -12,4 +12,4 @@ import type { NormalizedQuestionsCliOptions } from '../questionsCliOptions';
  * @returns `true` when at least one installation was updated and the current coder run should stop
  * @private internal utility of `promptbookCli`
  */
-export declare function $ensurePromptbookCliInstallations(questionsOptions: NormalizedQuestionsCliOptions): Promise<boolean>;
+export declare function $ensurePromptbookCliInstallations(questionsOptions: NormalizedQuestionsCliOptions, projectPath?: string): Promise<boolean>;

package/umd/src/cli/cli-commands/common/promptbook-cli/$resolvePromptbookCliInstallations.d.ts

@@ -9,4 +9,4 @@ import { type PromptbookCliInstallation } from './PromptbookCliInstallation';
  *
  * @private internal utility of `promptbookCli`
  */
-export declare function $resolvePromptbookCliInstallations(): Promise<ReadonlyArray<PromptbookCliInstallation>>;
+export declare function $resolvePromptbookCliInstallations(projectPath?: string): Promise<ReadonlyArray<PromptbookCliInstallation>>;

package/umd/src/cli/cli-commands/common/promptbook-cli/$updatePromptbookCliInstallation.d.ts

@@ -7,4 +7,4 @@ import type { PromptbookCliInstallationStatus } from './PromptbookCliInstallatio
  * @returns `true` when the package update succeeds, `false` when it fails
  * @private internal utility of `promptbookCli`
  */
-export declare function $updatePromptbookCliInstallation(status: PromptbookCliInstallationStatus): Promise<boolean>;
+export declare function $updatePromptbookCliInstallation(status: PromptbookCliInstallationStatus, projectPath?: string): Promise<boolean>;

package/umd/src/version.d.ts

@@ -15,7 +15,7 @@ export declare const BOOK_LANGUAGE_VERSION: string_semantic_version;
 export declare const PROMPTBOOK_ENGINE_VERSION: string_promptbook_version;
 /**
  * Represents the version string of the Promptbook engine.
- * It follows semantic versioning (e.g., `0.114.0-47`).
+ * It follows semantic versioning (e.g., `0.114.0-48`).
  *
  * @generated
  */