Skip to content

Commit c5f419e

Browse files
suleimanshclaude
andauthored
The build-opening prompts live in prompts/ as markdown (#1347) (#1683)
* 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> * Dedup: the prompt SPECs stop re-narrating their prompts, one fill helper renders all three (#1347) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
1 parent d4b879a commit c5f419e

10 files changed

Lines changed: 71 additions & 37 deletions

File tree

packages/framework/prompts/README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ is written in TypeScript any more, so prompting can change without touching the
66
| file | what it is |
77
|---|---|
88
| `system_prompt.md` | The built-in system prompt (#326). Rom's doc. |
9+
| `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. |
910
| `protocols/await.md` | How to emit an awaited choice so the turn-boundary gate can detect it (#337/#339). |
1011
| `protocols/signal.md` | How to emit `setSessionName()` / `setReadyForMerge()` (#326). |
1112
| `presets/*.md` | One file per preset button: research (#331), readability (#360), maintainability (#361), security_audit (#461), ux (#472). |

packages/framework/prompts/SPEC.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ Every prompt The Framework sends an agent lives here as markdown. Nothing agent-
1313
- **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.
1414
- **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.
1515
- **The presets** - one file per launcher button and per routine prompt.
16+
- **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.
1617
- **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.
1718
- **Prompts are reviewed before they land** - a prompt change goes through review like any other change.
1819

@@ -46,6 +47,7 @@ See `## User story`.
4647
- **The triage scope rule** — the one-paragraph rule appended to both triage presets, that a triage only queues work and never implements it.
4748
- **The protocols** — how an agent signals to The Framework, and what this particular agent can do.
4849
- **The presets** — one file per preset: the launcher's buttons and the daemon's routine prompts.
50+
- **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.
4951
- **The on-before-mergeable prompt** — the extra turn an agent gets when it signals ready for merge, if the user turned that on.
5052

5153
### Prompts are reviewed before they land
Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
The greenfield build prompt: the opening prompt of a build agent whose workspace holds no app yet.
2+
3+
## Business logic
4+
5+
Sent as the opening prompt when the workspace holds no source at build time; the user's intent fills the `${{ tf.prompt }}` slot. The prompt file beside this spec is itself the prose of what the agent is told.
6+
7+
## Rationale
8+
9+
The stack is deliberately not prescribed — it is the agent's call.
10+
11+
## Before modifying/creating SPEC.md files
12+
13+
You must always read and respect https://raw.githubusercontent.com/brillout/sdd/refs/heads/main/sdd.md
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
Build this app end to end: ${{ tf.prompt }}
2+
The workspace may be empty — if so, scaffold the whole project from scratch:
3+
create package.json with scripts, all config, and every source file, install
4+
the dependencies, and make the app run.
5+
When done, summarize what you built in one short paragraph.
Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
The existing-codebase prompt: the opening prompt of a build agent whose workspace already holds source.
2+
3+
## Business logic
4+
5+
Sent as the opening prompt when the workspace already holds source at build time; the user's intent fills the `${{ tf.prompt }}` slot. The prompt file beside this spec is itself the prose of what the agent is told.
6+
7+
## Rationale
8+
9+
It names the one thing the agent cannot infer — that this codebase already exists — 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, and it never suggests the workspace might be empty, because it is not.
10+
11+
## Before modifying/creating SPEC.md files
12+
13+
You must always read and respect https://raw.githubusercontent.com/brillout/sdd/refs/heads/main/sdd.md
Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
Work within the existing codebase in this workspace to deliver: ${{ tf.prompt }}
2+
When done, summarize what you changed in one short paragraph.
Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
The scaffold retry prompt: the hard directive sent when a build's opening turn left the workspace empty.
2+
3+
## Business logic
4+
5+
Sent as a retry when the opening build turn produced no source — the agent stalled waiting for code that does not exist, or refused because the directory is empty; the user's intent fills the `${{ tf.prompt }}` slot. The prompt file beside this spec is itself the prose of what the agent is told.
6+
7+
## Rationale
8+
9+
Its insistence that an empty directory is expected — not a reason to refuse or wait — exists because that stall is exactly how the failed builds looked.
10+
11+
## Before modifying/creating SPEC.md files
12+
13+
You must always read and respect https://raw.githubusercontent.com/brillout/sdd/refs/heads/main/sdd.md
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
The workspace is empty — no app exists here yet. You must create the entire app now from scratch: ${{ tf.prompt }}
2+
This is a from-scratch build, not an edit: do not wait for existing code, and do
3+
not refuse because the directory is empty — that is expected. Scaffold the full
4+
project (package.json with scripts, config, and every source file), install
5+
dependencies, and do not stop until the requested features exist and the app runs.

packages/framework/src/steps.SPEC.md

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,7 @@ The prompts a build agent opens with, and the one check that decides between the
22

33
## Business logic — TL;DR
44

5-
- **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.
6-
- **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.
7-
- **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.
5+
- **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.
86
- **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.
97

108
## Before modifying/creating SPEC.md files

packages/framework/src/steps.ts

Lines changed: 16 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,56 +1,38 @@
11
import { readdirSync } from 'node:fs'
22
import { join } from 'node:path'
3+
import { BUILD_PROMPT, EXTEND_PROMPT, SCAFFOLD_PROMPT } from './prompts.generated.js'
4+
import { renderTemplate } from './prompt-template.js'
35

46
/**
57
* The prompts a build session opens with, and the one check that decides between them.
68
*
7-
* This was the driver-backed half of ai-autopilot's `Bootstrap` spine: injectable build / improve
8-
* steps whose results were wrapped in a synthetic supervised agent so the narration could show a
9-
* phase. The spine went with the review loop (A3/A5), and the session that used it is now one
10-
* prompt honoring gates (D2), so what survives is the prompt text itself.
9+
* The prompt text lives in `prompts/*_prompt.md` like every other agent-facing prompt (#551/#1347);
10+
* these functions only fill the user's intent into the compiled templates. `tf.prompt` is the same
11+
* name the system prompt gives the user's prompt.
1112
*/
1213

13-
/** Compose the build prompt for an intent. The stack is the agent's call (#545). */
14+
/** Fill the user's intent into a compiled build-opening template. */
15+
const fill = (template: string, intent: string): string => renderTemplate(template, { tf: { prompt: intent } })
16+
17+
/** The greenfield build prompt (`prompts/build_prompt.md`). The stack is the agent's call (#545). */
1418
export function buildPrompt(intent: string): string {
15-
return [
16-
`Build this app end to end: ${intent}`,
17-
'The workspace may be empty — if so, scaffold the whole project from scratch:',
18-
'create package.json with scripts, all config, and every source file, install',
19-
'the dependencies, and make the app run.',
20-
'When done, summarize what you built in one short paragraph.',
21-
].join('\n')
19+
return fill(BUILD_PROMPT, intent)
2220
}
2321

2422
/**
25-
* Framing for an agent against an *existing* codebase. The greenfield {@link buildPrompt} tells the
26-
* agent the workspace may be empty and to scaffold from scratch, which is the wrong instruction
27-
* when the user pointed the framework at a project that already exists (#185).
28-
*
29-
* Naming the workspace is the whole job. The rules that used to follow it (do not re-scaffold,
30-
* read the existing code first, make the smallest coherent set of changes) were dropped in #1224:
31-
* they told a capable agent how to do its work rather than what the work was, and the one thing it
32-
* cannot infer, that this codebase already exists, is in the first line. Chosen when the workspace
33-
* already holds source at build time.
23+
* The existing-codebase prompt (`prompts/extend_prompt.md`), chosen when the workspace already
24+
* holds source at build time (#185).
3425
*/
3526
export function extendPrompt(intent: string): string {
36-
return [
37-
`Work within the existing codebase in this workspace to deliver: ${intent}`,
38-
'When done, summarize what you changed in one short paragraph.',
39-
].join('\n')
27+
return fill(EXTEND_PROMPT, intent)
4028
}
4129

4230
/**
43-
* A hard "the app does not exist yet — create it from scratch" directive, for a build whose
44-
* opening turn left the workspace empty: the agent stalled rather than scaffolding (#182).
31+
* The scaffold retry prompt (`prompts/scaffold_prompt.md`), for a build whose opening turn left
32+
* the workspace empty (#182).
4533
*/
4634
export function scaffoldPrompt(intent: string): string {
47-
return [
48-
`The workspace is empty — no app exists here yet. You must create the entire app now from scratch: ${intent}`,
49-
'This is a from-scratch build, not an edit: do not wait for existing code, and do',
50-
'not refuse because the directory is empty — that is expected. Scaffold the full',
51-
'project (package.json with scripts, config, and every source file), install',
52-
'dependencies, and do not stop until the requested features exist and the app runs.',
53-
].join('\n')
35+
return fill(SCAFFOLD_PROMPT, intent)
5436
}
5537

5638
const IGNORED_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', '.turbo', '.cache', '.vite'])

0 commit comments

Comments
 (0)