The three build-opening prompts live in prompts/ as markdown, like every other agent-facing prompt (#1347)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: suleimansh

packages/framework/prompts/README.md

@@ -6,6 +6,7 @@ is written in TypeScript any more, so prompting can change without touching the
 | file | what it is |
 |---|---|
 | `system_prompt.md` | The built-in system prompt (#326). Rom's doc. |
+| `build_prompt.md` / `extend_prompt.md` / `scaffold_prompt.md` | The prompts a build session opens with (#1347): greenfield, existing codebase (#185), and the scaffold retry (#182). `${{ tf.prompt }}` is the user's intent. |
 | `protocols/await.md` | How to emit an awaited choice so the turn-boundary gate can detect it (#337/#339). |
 | `protocols/signal.md` | How to emit `setSessionName()` / `setReadyForMerge()` (#326). |
 | `presets/*.md` | One file per preset button: research (#331), readability (#360), maintainability (#361), security_audit (#461), ux (#472). |

packages/framework/prompts/SPEC.md

@@ -13,6 +13,7 @@ Every prompt The Framework sends an agent lives here as markdown. Nothing agent-
 - **The data-branch protocol** - where the framework's own data lives and how to read and write it without putting it on a code branch.
 - **The protocols** - how an agent signals: awaited choices, session name and ready for merge, plus the sections added only when it has a browser, when it runs hands-off, and when nothing can answer its questions.
 - **The presets** - one file per launcher button and per routine prompt.
+- **The build-opening prompts** - the three framings a build agent can open with: the greenfield build, the existing-codebase variant, and the scaffold retry for a build that produced nothing.
 - **The on-before-mergeable prompt** - the optional extra turn a finished agent gets, queueing quality follow-ups and folding what it learned into the knowledge base.
 - **Prompts are reviewed before they land** - a prompt change goes through review like any other change.
 
@@ -46,6 +47,7 @@ See `## User story`.
 - **The triage scope rule** — the one-paragraph rule appended to both triage presets, that a triage only queues work and never implements it.
 - **The protocols** — how an agent signals to The Framework, and what this particular agent can do.
 - **The presets** — one file per preset: the launcher's buttons and the daemon's routine prompts.
+- **The build-opening prompts** — the greenfield build, the existing-codebase variant chosen when the workspace already holds source, and the scaffold retry sent when a build's opening turn left the workspace empty.
 - **The on-before-mergeable prompt** — the extra turn an agent gets when it signals ready for merge, if the user turned that on.
 
 ### Prompts are reviewed before they land

packages/framework/prompts/build_prompt.SPEC.md

@@ -0,0 +1,9 @@
+The greenfield build prompt: the opening prompt of a build agent whose workspace holds no app yet.
+
+## Business logic
+
+It frames a from-scratch, end-to-end build of the user's intent: the workspace may be empty, and if so the agent is to scaffold the whole project — package manifest with scripts, all config, every source file — install the dependencies, and make the app run, then summarize what it built in one short paragraph. The user's intent fills the first line; the stack is deliberately left to the agent.
+
+## Before modifying/creating SPEC.md files
+
+You must always read and respect https://raw.githubusercontent.com/brillout/sdd/refs/heads/main/sdd.md

packages/framework/prompts/build_prompt.md

@@ -0,0 +1,5 @@
+Build this app end to end: ${{ tf.prompt }}
+The workspace may be empty — if so, scaffold the whole project from scratch:
+create package.json with scripts, all config, and every source file, install
+the dependencies, and make the app run.
+When done, summarize what you built in one short paragraph.

packages/framework/prompts/extend_prompt.SPEC.md

@@ -0,0 +1,9 @@
+The existing-codebase prompt: the opening prompt of a build agent whose workspace already holds source.
+
+## Business logic
+
+It names the one thing the agent cannot infer — this codebase already exists — and the work to deliver, then asks for a one-paragraph summary of what changed. Nothing more: the how-to-behave rules it once carried (do not re-scaffold, read the existing code first, smallest coherent change set) were dropped as babysitting a capable agent, and it never suggests the workspace might be empty, because it is not.
+
+## Before modifying/creating SPEC.md files
+
+You must always read and respect https://raw.githubusercontent.com/brillout/sdd/refs/heads/main/sdd.md

packages/framework/prompts/extend_prompt.md

@@ -0,0 +1,2 @@
+Work within the existing codebase in this workspace to deliver: ${{ tf.prompt }}
+When done, summarize what you changed in one short paragraph.

packages/framework/prompts/scaffold_prompt.SPEC.md

@@ -0,0 +1,9 @@
+The scaffold retry prompt: the hard directive sent when a build's opening turn left the workspace empty.
+
+## Business logic
+
+A build agent sometimes stalls rather than scaffolding — waiting for code that does not exist, or refusing because the directory is empty. This retry states plainly that no app exists yet and the agent must create the entire app from scratch now: an empty directory is expected, not a reason to refuse or wait, and the agent is not to stop until the requested features exist and the app runs. The user's intent fills the first line.
+
+## Before modifying/creating SPEC.md files
+
+You must always read and respect https://raw.githubusercontent.com/brillout/sdd/refs/heads/main/sdd.md

packages/framework/prompts/scaffold_prompt.md

@@ -0,0 +1,5 @@
+The workspace is empty — no app exists here yet. You must create the entire app now from scratch: ${{ tf.prompt }}
+This is a from-scratch build, not an edit: do not wait for existing code, and do
+not refuse because the directory is empty — that is expected. Scaffold the full
+project (package.json with scripts, config, and every source file), install
+dependencies, and do not stop until the requested features exist and the app runs.

packages/framework/src/steps.SPEC.md

@@ -2,9 +2,7 @@ The prompts a build agent opens with, and the one check that decides between the
 
 ## Business logic — TL;DR
 
-- **Greenfield build prompt** - frames a from-scratch build of the user's intent: the workspace may be empty, so scaffold the whole project (package manifest and scripts, config, every source file), install dependencies, make the app run, and summarize in one short paragraph.
-- **Existing-codebase prompt** - chosen when the workspace already holds source at build time. It names the one thing the agent cannot infer — this codebase already exists — and the work to deliver, and nothing more; the how-to-behave rules it once carried (do not re-scaffold, read the existing code first, smallest coherent change set) were dropped as babysitting a capable agent.
-- **Scaffold retry prompt** - a hard "the app does not exist yet — create it from scratch now" directive, used when a build's opening turn left the workspace empty: the agent stalled rather than scaffolding, and this retry tells it an empty directory is expected, not a reason to refuse or wait.
+- **Three build-opening prompts, filled with the user's intent** - the greenfield build prompt, the existing-codebase prompt (chosen when the workspace already holds source at build time), and the scaffold retry (sent when a build's opening turn left the workspace empty). Each prompt's text is authored as markdown in the prompts directory like every other agent-facing prompt; what happens here is only the choice between them and filling in the intent.
 - **Workspace-emptiness check** - a workspace counts as empty when it holds no source file the agent could have produced: lockfiles, dotfiles, and dependency/output directories (node_modules, .git, dist, build caches) do not count. Best-effort and cheap — it stops at the first real file, treats an unreadable or missing directory as empty, and never throws.
 
 ## Before modifying/creating SPEC.md files

packages/framework/src/steps.ts

@@ -1,56 +1,35 @@
 import { readdirSync } from 'node:fs'
 import { join } from 'node:path'
+import { BUILD_PROMPT, EXTEND_PROMPT, SCAFFOLD_PROMPT } from './prompts.generated.js'
+import { renderTemplate } from './prompt-template.js'
 
 /**
  * The prompts a build session opens with, and the one check that decides between them.
  *
- * This was the driver-backed half of ai-autopilot's `Bootstrap` spine: injectable build / improve
- * steps whose results were wrapped in a synthetic supervised agent so the narration could show a
- * phase. The spine went with the review loop (A3/A5), and the session that used it is now one
- * prompt honoring gates (D2), so what survives is the prompt text itself.
+ * The prompt text lives in `prompts/*_prompt.md` like every other agent-facing prompt (#551/#1347);
+ * these functions only fill the user's intent into the compiled templates. `tf.prompt` is the same
+ * name the system prompt gives the user's prompt.
  */
 
-/** Compose the build prompt for an intent. The stack is the agent's call (#545). */
+/** The greenfield build prompt (`prompts/build_prompt.md`). The stack is the agent's call (#545). */
 export function buildPrompt(intent: string): string {
-  return [
-    `Build this app end to end: ${intent}`,
-    'The workspace may be empty — if so, scaffold the whole project from scratch:',
-    'create package.json with scripts, all config, and every source file, install',
-    'the dependencies, and make the app run.',
-    'When done, summarize what you built in one short paragraph.',
-  ].join('\n')
+  return renderTemplate(BUILD_PROMPT, { tf: { prompt: intent } })
 }
 
 /**
- * Framing for an agent against an *existing* codebase. The greenfield {@link buildPrompt} tells the
- * agent the workspace may be empty and to scaffold from scratch, which is the wrong instruction
- * when the user pointed the framework at a project that already exists (#185).
- *
- * Naming the workspace is the whole job. The rules that used to follow it (do not re-scaffold,
- * read the existing code first, make the smallest coherent set of changes) were dropped in #1224:
- * they told a capable agent how to do its work rather than what the work was, and the one thing it
- * cannot infer, that this codebase already exists, is in the first line. Chosen when the workspace
- * already holds source at build time.
+ * The existing-codebase prompt (`prompts/extend_prompt.md`), chosen when the workspace already
+ * holds source at build time (#185).
  */
 export function extendPrompt(intent: string): string {
-  return [
-    `Work within the existing codebase in this workspace to deliver: ${intent}`,
-    'When done, summarize what you changed in one short paragraph.',
-  ].join('\n')
+  return renderTemplate(EXTEND_PROMPT, { tf: { prompt: intent } })
 }
 
 /**
- * A hard "the app does not exist yet — create it from scratch" directive, for a build whose
- * opening turn left the workspace empty: the agent stalled rather than scaffolding (#182).
+ * The scaffold retry prompt (`prompts/scaffold_prompt.md`), for a build whose opening turn left
+ * the workspace empty (#182).
  */
 export function scaffoldPrompt(intent: string): string {
-  return [
-    `The workspace is empty — no app exists here yet. You must create the entire app now from scratch: ${intent}`,
-    'This is a from-scratch build, not an edit: do not wait for existing code, and do',
-    'not refuse because the directory is empty — that is expected. Scaffold the full',
-    'project (package.json with scripts, config, and every source file), install',
-    'dependencies, and do not stop until the requested features exist and the app runs.',
-  ].join('\n')
+  return renderTemplate(SCAFFOLD_PROMPT, { tf: { prompt: intent } })
 }
 
 const IGNORED_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', '.turbo', '.cache', '.vite'])