npm - @promptbook/cli - Versions diffs - 0.112.0-121 → 0.112.0-124 - Mend

@promptbook/cli 0.112.0-121 → 0.112.0-124

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (55) hide show

package/esm/scripts/run-codex-prompts/common/resolveAgentSystemMessage.d.ts ADDED Viewed

@@ -0,0 +1,6 @@
+/**
+ * Reads an optional agent `.book` file and compiles its system message for injection into coder prompts.
+ *
+ * Returns `undefined` when no agent path is provided.
+ */
+export declare function resolveAgentSystemMessage(agentPath: string | undefined, currentWorkingDirectory: string): Promise<string | undefined>;

package/esm/scripts/run-codex-prompts/main/findUnwrittenPrompts.d.ts ADDED Viewed

@@ -0,0 +1,19 @@
+/**
+ * Options for `findUnwrittenPrompts`.
+ */
+export type FindUnwrittenPromptsOptions = {
+    /**
+     * Minimum priority level — sections below this threshold are excluded.
+     * @default 0
+     */
+    readonly priority?: number;
+};
+/**
+ * Lists and prints all prompt sections that still need to be authored (contain `@@@` placeholder).
+ *
+ * Reuses the same filtering logic as `ptbk coder run --dry-run`.
+ *
+ * @returns the number of unwritten prompts found
+ * @public exported from `@promptbook/cli`
+ */
+export declare function findUnwrittenPrompts(options?: FindUnwrittenPromptsOptions): Promise<number>;

package/esm/scripts/run-codex-prompts/main/runCodexPromptsServer.d.ts ADDED Viewed

@@ -0,0 +1,27 @@
+import type { number_port } from '../../../src/types/number_positive';
+import type { RunOptions } from '../cli/RunOptions';
+/**
+ * Options for `ptbk coder server` combining the standard run options with a server port.
+ *
+ * @private internal type of `ptbk coder server`
+ */
+export type CoderServerRunOptions = RunOptions & {
+    /**
+     * TCP port on which the kanban HTTP server will listen.
+     */
+    port: number_port;
+};
+/**
+ * Starts the coder server: runs prompt processing in keepAlive mode while serving a
+ * kanban web UI and REST API on the given port.
+ *
+ * Differences from `runCodexPrompts`:
+ * - Does not exit when no runnable prompts are available; instead it polls every few seconds
+ *   and resumes processing as soon as a new prompt becomes ready.
+ * - Starts a lightweight HTTP server that serves a kanban board at `http://localhost:<port>`
+ *   and exposes REST endpoints for reading prompts, controlling pause state, and editing
+ *   prompt files directly from the browser.
+ *
+ * @private internal function of `ptbk coder server`
+ */
+export declare function runCodexPromptsServer(options: CoderServerRunOptions): Promise<void>;

package/esm/scripts/run-codex-prompts/main/runPromptRound.d.ts CHANGED Viewed

@@ -17,6 +17,7 @@ type RunPromptRoundOptions = {
     nextPrompt: PromptSelection;
     promptLabel: string;
     resolvedCoderContext?: string;
+    resolvedAgentSystemMessage?: string;
     isRichUiEnabled: boolean;
     progressDisplay?: CliProgressDisplay;
     uiHandle?: CoderRunUiHandle;
@@ -27,5 +28,5 @@ type RunPromptRoundOptions = {
  *
  * @private function of runCodexPrompts
  */
-export declare function runPromptRound({ options, runner, runnerMetadata, nextPrompt, promptLabel, resolvedCoderContext, isRichUiEnabled, progressDisplay, uiHandle, waitForRequestedPause, }: RunPromptRoundOptions): Promise<void>;
+export declare function runPromptRound({ options, runner, runnerMetadata, nextPrompt, promptLabel, resolvedCoderContext, resolvedAgentSystemMessage, isRichUiEnabled, progressDisplay, uiHandle, waitForRequestedPause, }: RunPromptRoundOptions): Promise<void>;
 export {};

package/esm/scripts/run-codex-prompts/server/coderServerHtml.d.ts ADDED Viewed

@@ -0,0 +1,9 @@
+/**
+ * HTML source for the coder server kanban UI.
+ *
+ * The canonical source lives in `apps/coder-server/index.html`.
+ * Keep both files in sync when updating the frontend.
+ *
+ * @private internal constant of `ptbk coder server`
+ */
+export declare const CODER_SERVER_HTML = "<!DOCTYPE html>\n<html lang=\"en\">\n<head>\n  <meta charset=\"UTF-8\">\n  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\n  <title>Ptbk Coder Server</title>\n  <style>\n    * { box-sizing: border-box; margin: 0; padding: 0; }\n    body {\n      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;\n      background: #f4f5f7;\n      color: #172b4d;\n      min-height: 100vh;\n    }\n\n    header {\n      background: #0052cc;\n      color: white;\n      padding: 12px 20px;\n      display: flex;\n      align-items: center;\n      gap: 12px;\n      position: sticky;\n      top: 0;\n      z-index: 10;\n      box-shadow: 0 2px 8px rgba(0,0,0,0.2);\n    }\n    header h1 { font-size: 17px; font-weight: 700; flex-shrink: 0; }\n\n    .status-badge {\n      padding: 3px 10px;\n      border-radius: 12px;\n      font-size: 11px;\n      font-weight: 700;\n      letter-spacing: 0.5px;\n      text-transform: uppercase;\n      flex-shrink: 0;\n    }\n    .status-RUNNING  { background: #00875a; color: white; }\n    .status-PAUSING  { background: #ff8b00; color: white; }\n    .status-PAUSED   { background: #bf2600; color: white; }\n\n    #pause-label {\n      font-size: 12px;\n      color: rgba(255,255,255,0.75);\n      flex: 1;\n      min-width: 0;\n      overflow: hidden;\n      text-overflow: ellipsis;\n      white-space: nowrap;\n    }\n\n    .btn {\n      padding: 6px 14px;\n      border: none;\n      border-radius: 4px;\n      cursor: pointer;\n      font-size: 13px;\n      font-weight: 600;\n      transition: opacity 0.15s;\n      flex-shrink: 0;\n    }\n    .btn:hover { opacity: 0.85; }\n    .btn-pause  { background: #ffc400; color: #172b4d; }\n    .btn-resume { background: #00875a; color: white; }\n\n    .board {\n      display: flex;\n      gap: 14px;\n      padding: 16px;\n      overflow-x: auto;\n      min-height: calc(100vh - 52px);\n      align-items: flex-start;\n    }\n\n    .column {\n      background: #ebecf0;\n      border-radius: 8px;\n      padding: 10px;\n      min-width: 250px;\n      width: 270px;\n      flex-shrink: 0;\n    }\n\n    .column-header {\n      font-size: 12px;\n      font-weight: 700;\n      text-transform: uppercase;\n      letter-spacing: 0.6px;\n      color: #5e6c84;\n      margin-bottom: 10px;\n      display: flex;\n      align-items: center;\n      justify-content: space-between;\n    }\n\n    .column-count {\n      background: #dfe1e6;\n      border-radius: 10px;\n      padding: 1px 7px;\n      font-size: 11px;\n      color: #5e6c84;\n    }\n\n    .column-cards { min-height: 40px; }\n\n    .card {\n      background: white;\n      border-radius: 6px;\n      padding: 10px 12px;\n      margin-bottom: 8px;\n      box-shadow: 0 1px 3px rgba(0,0,0,0.08);\n      cursor: pointer;\n      transition: box-shadow 0.15s, transform 0.1s;\n      border-left: 3px solid transparent;\n    }\n    .card:hover {\n      box-shadow: 0 4px 10px rgba(0,0,0,0.14);\n      transform: translateY(-1px);\n    }\n    .card-todo      { border-left-color: #0052cc; }\n    .card-not-ready { border-left-color: #8993a4; }\n    .card-done      { border-left-color: #00875a; }\n    .card-failed    { border-left-color: #bf2600; }\n\n    .card-file {\n      font-size: 10px;\n      color: #8993a4;\n      margin-bottom: 5px;\n      font-weight: 500;\n    }\n\n    .card-summary {\n      font-size: 13px;\n      line-height: 1.5;\n      color: #172b4d;\n      word-break: break-word;\n      white-space: pre-wrap;\n      max-height: 78px;\n      overflow: hidden;\n      display: -webkit-box;\n      -webkit-line-clamp: 4;\n      -webkit-box-orient: vertical;\n    }\n\n    .card-priority {\n      margin-top: 6px;\n      color: #ff8b00;\n      font-size: 11px;\n      font-weight: 700;\n    }\n\n    .card-edit-hint {\n      font-size: 10px;\n      color: #c1c7d0;\n      margin-top: 6px;\n      display: none;\n    }\n    .card:hover .card-edit-hint { display: block; }\n\n    .empty-column {\n      color: #b3bac5;\n      font-size: 12px;\n      padding: 10px 4px;\n      text-align: center;\n    }\n\n    .modal-overlay {\n      position: fixed;\n      inset: 0;\n      background: rgba(9,30,66,0.54);\n      display: flex;\n      align-items: flex-start;\n      justify-content: center;\n      padding: 60px 16px 16px;\n      z-index: 100;\n      animation: fadeIn 0.1s ease;\n    }\n    .modal-overlay.hidden { display: none; }\n\n    @keyframes fadeIn { from { opacity: 0; } to { opacity: 1; } }\n\n    .modal {\n      background: white;\n      border-radius: 8px;\n      width: 100%;\n      max-width: 620px;\n      padding: 20px;\n      box-shadow: 0 8px 32px rgba(0,0,0,0.25);\n      animation: slideIn 0.15s ease;\n    }\n    @keyframes slideIn { from { transform: translateY(-8px); opacity: 0; } to { transform: none; opacity: 1; } }\n\n    .modal-header {\n      display: flex;\n      align-items: flex-start;\n      justify-content: space-between;\n      margin-bottom: 14px;\n      gap: 12px;\n    }\n\n    .modal-meta { flex: 1; min-width: 0; }\n    .modal-file { font-size: 11px; color: #8993a4; margin-bottom: 4px; }\n    .modal-section-label { font-size: 13px; font-weight: 600; color: #172b4d; }\n\n    .modal-status {\n      font-size: 11px;\n      font-weight: 700;\n      padding: 2px 8px;\n      border-radius: 10px;\n      text-transform: uppercase;\n      letter-spacing: 0.4px;\n      flex-shrink: 0;\n    }\n    .status-todo      { background: #deebff; color: #0052cc; }\n    .status-not-ready { background: #f4f5f7; color: #5e6c84; }\n    .status-done      { background: #e3fcef; color: #006644; }\n    .status-failed    { background: #ffebe6; color: #bf2600; }\n\n    .modal-close {\n      background: none;\n      border: none;\n      color: #8993a4;\n      cursor: pointer;\n      font-size: 18px;\n      padding: 0 4px;\n      line-height: 1;\n      flex-shrink: 0;\n    }\n    .modal-close:hover { color: #172b4d; }\n\n    textarea {\n      width: 100%;\n      min-height: 220px;\n      font-family: 'SFMono-Regular', 'Consolas', 'Courier New', monospace;\n      font-size: 13px;\n      border: 2px solid #dfe1e6;\n      border-radius: 4px;\n      padding: 10px 12px;\n      resize: vertical;\n      line-height: 1.65;\n      color: #172b4d;\n      transition: border-color 0.15s;\n    }\n    textarea:focus {\n      outline: none;\n      border-color: #0052cc;\n      box-shadow: 0 0 0 3px rgba(0,82,204,0.12);\n    }\n\n    .modal-hint {\n      font-size: 11px;\n      color: #8993a4;\n      margin-top: 6px;\n    }\n\n    .modal-actions {\n      display: flex;\n      gap: 8px;\n      margin-top: 14px;\n      justify-content: flex-end;\n    }\n\n    .btn-save   { background: #0052cc; color: white; }\n    .btn-cancel { background: #f4f5f7; color: #172b4d; }\n    .btn-cancel:hover { background: #ebecf0; opacity: 1; }\n\n    .error-banner {\n      background: #ffebe6;\n      border-bottom: 2px solid #bf2600;\n      color: #bf2600;\n      padding: 8px 20px;\n      font-size: 13px;\n      font-weight: 500;\n    }\n    .error-banner.hidden { display: none; }\n  </style>\n</head>\n<body>\n\n  <div id=\"error-banner\" class=\"error-banner hidden\"></div>\n\n  <header>\n    <h1>&#128295; Ptbk Coder Server</h1>\n    <span id=\"status-badge\" class=\"status-badge status-RUNNING\">RUNNING</span>\n    <span id=\"pause-label\"></span>\n    <button id=\"toggle-btn\" class=\"btn btn-pause\">&#9646;&#9646; Pause</button>\n  </header>\n\n  <div class=\"board\">\n    <div class=\"column\">\n      <div class=\"column-header\">\n        To Do\n        <span class=\"column-count\" id=\"count-todo\">0</span>\n      </div>\n      <div class=\"column-cards\" id=\"cards-todo\">\n        <div class=\"empty-column\">Loading&hellip;</div>\n      </div>\n    </div>\n\n    <div class=\"column\">\n      <div class=\"column-header\">\n        Not Ready\n        <span class=\"column-count\" id=\"count-not-ready\">0</span>\n      </div>\n      <div class=\"column-cards\" id=\"cards-not-ready\"></div>\n    </div>\n\n    <div class=\"column\">\n      <div class=\"column-header\">\n        Done\n        <span class=\"column-count\" id=\"count-done\">0</span>\n      </div>\n      <div class=\"column-cards\" id=\"cards-done\"></div>\n    </div>\n\n    <div class=\"column\">\n      <div class=\"column-header\">\n        Failed\n        <span class=\"column-count\" id=\"count-failed\">0</span>\n      </div>\n      <div class=\"column-cards\" id=\"cards-failed\"></div>\n    </div>\n  </div>\n\n  <div class=\"modal-overlay hidden\" id=\"modal-overlay\">\n    <div class=\"modal\">\n      <div class=\"modal-header\">\n        <div class=\"modal-meta\">\n          <div class=\"modal-file\" id=\"modal-file\"></div>\n          <div class=\"modal-section-label\" id=\"modal-section-label\"></div>\n        </div>\n        <span class=\"modal-status\" id=\"modal-status-badge\"></span>\n        <button class=\"modal-close\" onclick=\"closeModal()\" title=\"Close (Esc)\">&#x2715;</button>\n      </div>\n\n      <textarea id=\"modal-content\" placeholder=\"Prompt content&hellip;\"></textarea>\n      <div class=\"modal-hint\">Tip: press Ctrl+Enter to save, Esc to cancel.</div>\n\n      <div class=\"modal-actions\">\n        <button class=\"btn btn-cancel\" onclick=\"closeModal()\">Cancel</button>\n        <button class=\"btn btn-save\" onclick=\"saveModal()\">Save</button>\n      </div>\n    </div>\n  </div>\n\n  <script>\n    'use strict';\n\n    let modalState = null;\n    let lastPauseState = 'RUNNING';\n\n    function showError(msg) {\n      const banner = document.getElementById('error-banner');\n      banner.textContent = '\\u26a0 ' + msg;\n      banner.classList.remove('hidden');\n      clearTimeout(banner._timer);\n      banner._timer = setTimeout(() => banner.classList.add('hidden'), 6000);\n    }\n\n    function escapeHtml(str) {\n      const d = document.createElement('div');\n      d.textContent = String(str);\n      return d.innerHTML;\n    }\n\n    async function fetchStatus() {\n      try {\n        const res = await fetch('/api/status');\n        if (!res.ok) { showError('Status API error: ' + res.status); return; }\n        const data = await res.json();\n\n        lastPauseState = data.pauseState;\n\n        const badge = document.getElementById('status-badge');\n        badge.textContent = data.pauseState;\n        badge.className = 'status-badge status-' + data.pauseState;\n\n        const btn   = document.getElementById('toggle-btn');\n        const label = document.getElementById('pause-label');\n\n        if (data.pauseState === 'RUNNING') {\n          btn.textContent = '\\u23f8 Pause';\n          btn.className   = 'btn btn-pause';\n          label.textContent = '';\n        } else if (data.pauseState === 'PAUSING') {\n          btn.textContent = '\\u23f5 Resume';\n          btn.className   = 'btn btn-resume';\n          label.textContent = 'Pausing before: ' + (data.pauseTargetLabel || '\\u2026');\n        } else {\n          btn.textContent = '\\u23f5 Resume';\n          btn.className   = 'btn btn-resume';\n          label.textContent = 'Paused before: ' + (data.pauseTargetLabel || '\\u2026');\n        }\n      } catch (e) {\n        showError('Could not reach coder server: ' + e.message);\n      }\n    }\n\n    async function fetchPrompts() {\n      try {\n        const res = await fetch('/api/prompts');\n        if (!res.ok) { showError('Prompts API error: ' + res.status); return; }\n        renderBoard(await res.json());\n      } catch (e) {\n        showError('Could not load prompts: ' + e.message);\n      }\n    }\n\n    function renderBoard(promptFiles) {\n      const columns = { 'todo': [], 'not-ready': [], 'done': [], 'failed': [] };\n\n      for (const file of promptFiles) {\n        for (const section of file.sections) {\n          const col = columns[section.status];\n          if (col) col.push({ file, section });\n        }\n      }\n\n      for (const [status, cards] of Object.entries(columns)) {\n        const container = document.getElementById('cards-' + status);\n        const countEl   = document.getElementById('count-' + status);\n        if (!container) continue;\n\n        countEl.textContent = cards.length;\n        container.innerHTML = '';\n\n        if (cards.length === 0) {\n          container.innerHTML = '<div class=\"empty-column\">Empty</div>';\n          continue;\n        }\n\n        for (const { file, section } of cards) {\n          const card = document.createElement('div');\n          card.className = 'card card-' + section.status;\n          card.innerHTML =\n            '<div class=\"card-file\">' + escapeHtml(file.fileName) + ' &bull; #' + (section.index + 1) + '</div>' +\n            '<div class=\"card-summary\">' + escapeHtml(section.summary) + '</div>' +\n            (section.priority > 0\n              ? '<div class=\"card-priority\">' + '!'.repeat(section.priority) + ' priority ' + section.priority + '</div>'\n              : '') +\n            '<div class=\"card-edit-hint\">Click to edit</div>';\n          card.onclick = () => openModal(file, section);\n          container.appendChild(card);\n        }\n      }\n    }\n\n    function openModal(file, section) {\n      modalState = { filePath: file.filePath, sectionIndex: section.index };\n\n      document.getElementById('modal-file').textContent          = file.fileName;\n      document.getElementById('modal-section-label').textContent = 'Section ' + (section.index + 1);\n\n      const badge = document.getElementById('modal-status-badge');\n      badge.textContent = section.status.replace('-', '\\u2011');\n      badge.className   = 'modal-status status-' + section.status;\n\n      document.getElementById('modal-content').value = section.content;\n      document.getElementById('modal-overlay').classList.remove('hidden');\n      setTimeout(() => document.getElementById('modal-content').focus(), 50);\n    }\n\n    function closeModal() {\n      document.getElementById('modal-overlay').classList.add('hidden');\n      modalState = null;\n    }\n\n    async function saveModal() {\n      if (!modalState) return;\n\n      const content = document.getElementById('modal-content').value;\n      const saveBtn = document.querySelector('.btn-save');\n      saveBtn.disabled    = true;\n      saveBtn.textContent = 'Saving\\u2026';\n\n      try {\n        const res = await fetch('/api/prompts/update', {\n          method: 'PUT',\n          headers: { 'Content-Type': 'application/json' },\n          body: JSON.stringify({\n            filePath:     modalState.filePath,\n            sectionIndex: modalState.sectionIndex,\n            content,\n          }),\n        });\n        if (!res.ok) throw new Error('HTTP ' + res.status);\n        closeModal();\n        fetchPrompts();\n      } catch (e) {\n        showError('Save failed: ' + e.message);\n      } finally {\n        saveBtn.disabled    = false;\n        saveBtn.textContent = 'Save';\n      }\n    }\n\n    document.getElementById('toggle-btn').onclick = async () => {\n      try {\n        const endpoint = lastPauseState === 'RUNNING' ? '/api/pause' : '/api/resume';\n        await fetch(endpoint, { method: 'POST' });\n        await fetchStatus();\n      } catch (e) {\n        showError('Toggle failed: ' + e.message);\n      }\n    };\n\n    document.addEventListener('keydown', (e) => {\n      if (e.key === 'Escape') { closeModal(); return; }\n      if ((e.ctrlKey || e.metaKey) && e.key === 'Enter') { saveModal(); return; }\n    });\n\n    document.getElementById('modal-overlay').addEventListener('click', (e) => {\n      if (e.target === document.getElementById('modal-overlay')) closeModal();\n    });\n\n    fetchStatus();\n    fetchPrompts();\n    setInterval(fetchStatus,  2000);\n    setInterval(fetchPrompts, 5000);\n  </script>\n</body>\n</html>";

package/esm/scripts/run-codex-prompts/server/runCoderHttpServer.d.ts ADDED Viewed

@@ -0,0 +1,23 @@
+import type { number_port } from '../../../src/types/number_positive';
+/**
+ * Handle returned by the running coder HTTP server.
+ *
+ * @private internal type of `ptbk coder server`
+ */
+export type CoderHttpServerHandle = {
+    close: () => void;
+};
+/**
+ * Starts the lightweight HTTP server that serves the coder kanban UI and REST API.
+ *
+ * API endpoints:
+ * - `GET /`                    → HTML kanban page
+ * - `GET /api/prompts`         → JSON list of all prompt files and sections
+ * - `GET /api/status`          → JSON current pause state
+ * - `POST /api/pause`          → request pause
+ * - `POST /api/resume`         → request resume
+ * - `PUT /api/prompts/update`  → update prompt section content
+ *
+ * @private internal utility of `ptbk coder server`
+ */
+export declare function startCoderHttpServer(port: number_port): CoderHttpServerHandle;

package/esm/scripts/run-codex-prompts/server/updatePromptSection.d.ts ADDED Viewed

@@ -0,0 +1,9 @@
+/**
+ * Overwrites the body of one prompt section with new content, preserving the status line.
+ *
+ * The `newContent` string is the prompt text without the status marker.
+ * The status line (`[ ]`, `[x]`, `[!]`, `[-]`) is kept intact.
+ *
+ * @private internal utility of `ptbk coder server`
+ */
+export declare function updatePromptSection(filePath: string, sectionIndex: number, newContent: string): Promise<void>;

package/esm/src/cli/cli-commands/coder/ensureCoderDeveloperAgentFile.d.ts ADDED Viewed

@@ -0,0 +1,25 @@
+import type { InitializationStatus } from './boilerplateTemplates';
+/**
+ * Relative directory path for agents initialized by `ptbk coder init`.
+ *
+ * @private internal utility of `coder init` command
+ */
+export declare const CODER_AGENTS_DIRECTORY_PATH = "agents";
+/**
+ * Relative file path to the default developer agent initialized by `ptbk coder init`.
+ *
+ * @private internal utility of `coder init` command
+ */
+export declare const CODER_DEVELOPER_AGENT_FILE_PATH = "agents/developer.book";
+/**
+ * Source file path of the bundled developer agent inside the Promptbook repository.
+ *
+ * @private internal utility of `coder init` command
+ */
+export declare const DEFAULT_CODER_DEVELOPER_AGENT_SOURCE_FILE_PATH = "agents/default/developer.book";
+/**
+ * Ensures the default developer agent exists in the initialized project.
+ *
+ * @private function of `initializeCoderProjectConfiguration`
+ */
+export declare function ensureCoderDeveloperAgentFile(projectPath: string): Promise<InitializationStatus>;

package/esm/src/cli/cli-commands/coder/find-unwritten.d.ts ADDED Viewed

@@ -0,0 +1,10 @@
+import { Command as Program } from 'commander';
+import type { $side_effect } from '../../../utils/organization/$side_effect';
+/**
+ * Initializes `coder find-unwritten` command for Promptbook CLI utilities
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it registers a command in the CLI
+ *
+ * @private internal function of `promptbookCli`
+ */
+export declare function $initializeCoderFindUnwrittenCommand(program: Program): $side_effect;

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

@@ -9,6 +9,8 @@ export type CoderInitializationSummary = {
     readonly promptsDoneDirectoryStatus: InitializationStatus;
     readonly promptsTemplatesDirectoryStatus: InitializationStatus;
     readonly promptTemplateFileStatuses: ReadonlyArray<EnsuredCoderPromptTemplateFile>;
+    readonly agentsDirectoryStatus: InitializationStatus;
+    readonly developerAgentFileStatus: InitializationStatus;
     readonly agentsFileStatus: InitializationStatus;
     readonly agentCodingFileStatus: InitializationStatus;
     readonly envFileStatus: InitializationStatus;

package/esm/src/cli/cli-commands/coder/server.d.ts ADDED Viewed

@@ -0,0 +1,13 @@
+import { Command as Program } from 'commander';
+import type { $side_effect } from '../../../utils/organization/$side_effect';
+/**
+ * Initializes `coder server` command for Promptbook CLI utilities.
+ *
+ * Runs the same prompt processing logic as `ptbk coder run` but keeps the process alive
+ * and serves a kanban web UI on the configured port.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it registers a command in the CLI
+ *
+ * @private internal function of `promptbookCli`
+ */
+export declare function $initializeCoderServerCommand(program: Program): $side_effect;

package/esm/src/version.d.ts CHANGED Viewed

@@ -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.112.0-119`).
+ * It follows semantic versioning (e.g., `0.112.0-123`).
  *
  * @generated
  */

package/package.json CHANGED Viewed

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

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

@@ -0,0 +1,79 @@
+import { copyFile, stat } from 'fs/promises';
+import { join } from 'path';
+import { spaceTrim } from 'spacetrim';
+import { NotAllowed } from '../../../errors/NotAllowed';
+import type { InitializationStatus } from './boilerplateTemplates';
+/**
+ * Relative directory path for agents initialized by `ptbk coder init`.
+ *
+ * @private internal utility of `coder init` command
+ */
+export const CODER_AGENTS_DIRECTORY_PATH = 'agents';
+/**
+ * Relative file path to the default developer agent initialized by `ptbk coder init`.
+ *
+ * @private internal utility of `coder init` command
+ */
+export const CODER_DEVELOPER_AGENT_FILE_PATH = 'agents/developer.book';
+/**
+ * Source file path of the bundled developer agent inside the Promptbook repository.
+ *
+ * @private internal utility of `coder init` command
+ */
+export const DEFAULT_CODER_DEVELOPER_AGENT_SOURCE_FILE_PATH = 'agents/default/developer.book';
+/**
+ * Ensures the default developer agent exists in the initialized project.
+ *
+ * @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;
+    }
+}
+// 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/find-unwritten.ts ADDED Viewed

@@ -0,0 +1,58 @@
+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 { handleActionErrors } from '../common/handleActionErrors';
+/**
+ * Initializes `coder find-unwritten` command for Promptbook CLI utilities
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it registers a command in the CLI
+ *
+ * @private internal function of `promptbookCli`
+ */
+export function $initializeCoderFindUnwrittenCommand(program: Program): $side_effect {
+    const command = program.command('find-unwritten');
+    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);
+    command.action(
+        handleActionErrors(async (cliOptions) => {
+            const { priority = 0 } = cliOptions as {
+                readonly priority?: number;
+            };
+            // 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 });
+            } catch (error) {
+                assertsError(error);
+                console.error(colors.bgRed(`${error.name}`));
+                console.error(colors.red(error.stack || error.message));
+                return process.exit(1);
+            }
+            return process.exit(0);
+        }),
+    );
+}
+/**
+ * Parses an integer option value
+ *
+ * @private internal utility of `coder find-unwritten` command
+ */
+function parseIntOption(value: string): number {
+    const parsed = parseInt(value, 10);
+    if (isNaN(parsed)) {
+        throw new Error(`Invalid number: ${value}`);
+    }
+    return parsed;
+}
+// Note: [🟡] Code for CLI command [find-unwritten](src/cli/cli-commands/coder/find-unwritten.ts) should never be published outside of `@promptbook/cli`
+// Note: [💞] Ignore a discrepancy between file name and entity name

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

@@ -4,7 +4,7 @@
 const DEFAULT_CODER_PACKAGE_JSON_SCRIPTS = {
     'coder:generate-boilerplates': 'ptbk coder generate-boilerplates --template ./prompts/templates/common.md',
     'coder:run':
-        'ptbk coder run --harness openai-codex --model gpt-5.4 --thinking-level xhigh --context AGENTS.md --no-wait',
+        'ptbk coder run --harness openai-codex --model gpt-5.4 --thinking-level xhigh --agent agents/developer.book --context AGENTS.md --no-wait',
     // 'coder:find-refactor-candidates': 'ptbk coder find-refactor-candidates',
     'coder:verify': 'ptbk coder verify',
 } as const satisfies Readonly<Record<string, string>>;

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

@@ -7,7 +7,9 @@ import { handleActionErrors } from '../common/handleActionErrors';
 import { AGENT_CODING_FILE_PATH } from './agentCodingFile';
 import { AGENTS_FILE_PATH } from './agentsFile';
 import { getDefaultCoderProjectPromptTemplateDefinitions } from './boilerplateTemplates';
+import { CODER_DEVELOPER_AGENT_FILE_PATH } from './ensureCoderDeveloperAgentFile';
 import { formatDisplayPath } from './formatDisplayPath';
+import { generatePromptBoilerplate } from './generate-boilerplates';
 import { initializeCoderProjectConfiguration } from './initializeCoderProjectConfiguration';
 import { printInitializationSummary } from './printInitializationSummary';
@@ -33,6 +35,7 @@ export function $initializeCoderInitCommand(program: Program): $side_effect {
             - prompts/
             - prompts/done/
             ${listDefaultCoderProjectPromptTemplateDisplayPaths()}
+            - ${CODER_DEVELOPER_AGENT_FILE_PATH}
             - ${AGENTS_FILE_PATH}
             - ${AGENT_CODING_FILE_PATH}
             - .gitignore
@@ -48,8 +51,10 @@ export function $initializeCoderInitCommand(program: Program): $side_effect {
     command.action(
         handleActionErrors(async () => {
-            const summary = await initializeCoderProjectConfiguration(process.cwd());
+            const projectPath = process.cwd();
+            const summary = await initializeCoderProjectConfiguration(projectPath);
             printInitializationSummary(summary);
+            await generatePromptBoilerplate({ projectPath, filesCount: 5 });
         }),
     );
 }

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

@@ -8,6 +8,10 @@ import {
     PROMPTS_TEMPLATES_DIRECTORY_PATH,
 } from './boilerplateTemplates';
 import { ensureCoderEnvFile } from './ensureCoderEnvFile';
+import {
+    CODER_AGENTS_DIRECTORY_PATH,
+    ensureCoderDeveloperAgentFile,
+} from './ensureCoderDeveloperAgentFile';
 import { ensureCoderGitignoreFile } from './ensureCoderGitignoreFile';
 import { ensureCoderMarkdownFile } from './ensureCoderMarkdownFile';
 import { ensureCoderPackageJsonFile } from './ensureCoderPackageJsonFile';
@@ -25,6 +29,8 @@ export type CoderInitializationSummary = {
     readonly promptsDoneDirectoryStatus: InitializationStatus;
     readonly promptsTemplatesDirectoryStatus: InitializationStatus;
     readonly promptTemplateFileStatuses: ReadonlyArray<EnsuredCoderPromptTemplateFile>;
+    readonly agentsDirectoryStatus: InitializationStatus;
+    readonly developerAgentFileStatus: InitializationStatus;
     readonly agentsFileStatus: InitializationStatus;
     readonly agentCodingFileStatus: InitializationStatus;
     readonly envFileStatus: InitializationStatus;
@@ -44,6 +50,8 @@ export async function initializeCoderProjectConfiguration(projectPath: string):
     const promptsDoneDirectoryStatus = await ensureDirectory(projectPath, PROMPTS_DONE_DIRECTORY_PATH);
     const promptsTemplatesDirectoryStatus = await ensureDirectory(projectPath, PROMPTS_TEMPLATES_DIRECTORY_PATH);
     const promptTemplateFileStatuses = await ensureDefaultCoderPromptTemplateFiles(projectPath);
+    const agentsDirectoryStatus = await ensureDirectory(projectPath, CODER_AGENTS_DIRECTORY_PATH);
+    const developerAgentFileStatus = await ensureCoderDeveloperAgentFile(projectPath);
     const agentsFileStatus = await ensureCoderMarkdownFile(
         projectPath,
         AGENTS_FILE_PATH,
@@ -66,6 +74,8 @@ export async function initializeCoderProjectConfiguration(projectPath: string):
         promptsDoneDirectoryStatus,
         promptsTemplatesDirectoryStatus,
         promptTemplateFileStatuses,
+        agentsDirectoryStatus,
+        developerAgentFileStatus,
         agentsFileStatus,
         agentCodingFileStatus,
         envFileStatus,

package/src/cli/cli-commands/coder/printInitializationSummary.ts CHANGED Viewed

@@ -2,6 +2,7 @@ import colors from 'colors';
 import { AGENT_CODING_FILE_PATH } from './agentCodingFile';
 import { AGENTS_FILE_PATH } from './agentsFile';
 import type { InitializationStatus } from './boilerplateTemplates';
+import { CODER_DEVELOPER_AGENT_FILE_PATH } from './ensureCoderDeveloperAgentFile';
 import { formatDisplayPath } from './formatDisplayPath';
 import type { CoderInitializationSummary } from './initializeCoderProjectConfiguration';
@@ -23,6 +24,8 @@ export function printInitializationSummary(summary: CoderInitializationSummary):
         );
     }
+    printInitializationStatusLine('agents/', summary.agentsDirectoryStatus);
+    printInitializationStatusLine(CODER_DEVELOPER_AGENT_FILE_PATH, summary.developerAgentFileStatus);
     printInitializationStatusLine(AGENTS_FILE_PATH, summary.agentsFileStatus);
     printInitializationStatusLine(AGENT_CODING_FILE_PATH, summary.agentCodingFileStatus);
     printInitializationStatusLine('.env', summary.envFileStatus);

package/src/cli/cli-commands/coder/run.ts CHANGED Viewed

@@ -43,6 +43,10 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
     command.option('--dry-run', 'Print unwritten prompts without executing', false);
     addPromptRunnerSelectionOptions(command);
+    command.option(
+        '--agent <agent-book-path>',
+        'Path to a .book file whose compiled system message is prepended to each coding prompt',
+    );
     command.option(
         '--context <context-or-file>',
         'Append extra instructions either inline or from a file path relative to the current project',
@@ -80,17 +84,27 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
     command.action(
         handleActionErrors(async (cliOptions) => {
-            const { dryRun, context, test, preserveLogs, priority, wait, autoMigrate, allowDestructiveAutoMigrate } =
-                cliOptions as {
-                    readonly dryRun: boolean;
-                    readonly context?: string;
-                    readonly test?: string | string[];
-                    readonly preserveLogs: boolean;
-                    readonly priority: number;
-                    readonly wait: boolean | string;
-                    readonly autoMigrate: boolean;
-                    readonly allowDestructiveAutoMigrate: boolean;
-                } & PromptRunnerCliOptions;
+            const {
+                dryRun,
+                agent,
+                context,
+                test,
+                preserveLogs,
+                priority,
+                wait,
+                autoMigrate,
+                allowDestructiveAutoMigrate,
+            } = cliOptions as {
+                readonly dryRun: boolean;
+                readonly agent?: string;
+                readonly context?: string;
+                readonly test?: string | string[];
+                readonly preserveLogs: boolean;
+                readonly priority: number;
+                readonly wait: boolean | string;
+                readonly autoMigrate: boolean;
+                readonly allowDestructiveAutoMigrate: boolean;
+            } & PromptRunnerCliOptions;
             const testCommand = normalizeCommandOptionValue(test);
             const runnerOptions = normalizePromptRunnerCliOptions(cliOptions as PromptRunnerCliOptions, {
@@ -119,6 +133,7 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
                 ignoreGitChanges: runnerOptions.ignoreGitChanges,
                 agentName: runnerOptions.agentName,
                 model: runnerOptions.model,
+                agent,
                 context,
                 testCommand,
                 preserveLogs,