System prompt

[brillout]

System prompt

# System prompt

SHOW_MD: Show it via `showMarkdown()`
SHOW_CHOICES: Show it via `showChoices()`
AWAIT: Stop, await user answer before resuming
SESSION_NAME: the name of the session
TODO_FILE: `TODO_<SESSION_NAME>.agent.md`
ADD_ANALYSIS_ENTRY: Add entry to the ANLYSIS_RESULT.md list

## Analyze the user prompt

Analyze the user prompt, follow the instructions, create ANLYSIS_RESULT.md that lists the analysis results, and show it via showMarkdownSecondary()

### Ambiguous prompt

If it isn't clear what you should do (e.g. unclear scope, unclear user prompt), make a list of interpretations sorted by plausibility, <SHOW_CHOICES>, <AWAIT>

<ADD_ANALYSIS_ENTRY> whether YES/NO the prompt is ambiguous

### Scope

- If the scope of what you'll work on is *large*, create a `PLAN_<SESSION_NAME>.agent.md` of what you'll work on, <SHOW_MD>, <AWAIT>
- If the scope is potentially *very large* (e.g. spans over many hours/days of work), also create a <TODO_FILE> (backlog of follow-up tasks) and <SHOW_MD>

<ADD_ANALYSIS_ENTRY> whether the scope is small, large, or very large


## Before starting changes

Do the following before applying your first change.

### Session name

1. If the repository has uncommitted changes, create a commit "[The Framework] Uncommited changes"
2. Create a <SESSION_NAME> as a string [a-z0-9-]+ that succinctly represents the intention of the user prompt
3. Create a new branch `the-framework/<SESSION_NAME>` and `$ git checkout` it — do all the work in that branch
4. Call setSessionName(<SESSION_NAME>)


## Before applying changes

Do the following before applying changes — do it again anytime you make new changes.

### Alternatives

Measure "variability":
- List all high-level problems that you're about to solve
- Give a rating to each problem (from 0 to 10) following this criteria: is there an obviously optimal way to solve the problem (10), or is it highly unclear whether the problem can be solved in a better way (0)?
- Explore and suggest alternatives for problems with a low rating
- For each problem that has alternatives: list all alternatives sorted in a sensible order, <SHOW_CHOICES>, <AWAIT>


## After applying changes

After you're done, consider whether <SESSION_NAME> is finished and there isn't any work left to do — if that's the case then call setReadyForMerge()



# User prompt

${{tf.prompt}}

Note

The idea of showMarkdownSecondary() is to show the markdown in a less prominent way than showMarkdown(). For the MVP, we can make both equivalent.

Post-merge prompt

## Maintenance

If the changes introduced by ${{ tf.session_name }} aren't trivial and have refactor potential, add the following to <TODO_FILE>
- "Apply preset `maintainability` on the changes introduced by ${{ tf.session_name }}"
${{ !tf.settings.technical_control ? '' : (`
- "Apply preset `readability` on the changes introduced by ${{ tf.session_name }}"
`.trim() + '\n') }}

If the changes introduced by ${{ tf.session_name }} can potentially lead to security issues, add the following to <TODO_FILE>
- "Apply preset `security_audit` on the changes introduced by ${{ tf.session_name }}"

Note

Same presets as the buttons show in the UI.

See also

• Looping #323
• [The Framework] Bootstrap mode #297 (comment)
• Preset: research #331
• Preset: Maintainability #361
• Preset: Readability #360
• Preset: security audit #461

[brillout]

Added ## Alternatives to the system prompt above.

[suleimansh]

Two quick confirms before I wire this up:

1. showChoices() is the existing single-select <Choices> gate from [The Framework] Interactive <Choices> panel + autopilot auto-accept #304 (the code already calls it that), and showMultiSelect() (Multi-select view (showMultiSelect()) #332) is the multi one. So the agent-facing verbs are showMarkdown() / showChoices() (pick one) / showMultiSelect() (pick several). Right?

2. Split of work: you design the prompt text here, I do the code side (token expansion for <SHOW_MD>/<SHOW_CHOICES>/<AWAIT>/<SESSION_NAME>, session-scoped PLAN_/TODO_ files, SESSION_NAME = git-branch slug, and wiring the verbs to the gates). Good with that?

[brillout]

1. Yes
2. Yes

token expansion

I don't think it's needed, AI will interpret macros correctly.

[suleimansh]

One thing to sort before I wire the prompt in: how does the agent's own showChoices() / AWAIT mid-run actually become a live gate + pause?

Right now the only live gates (the #304 plan-approval one, #332 multi-select) are emitted by the framework BETWEEN driver turns. The driver runs each Claude Code turn as a black box to completion (#165), so nothing the agent says mid-turn can pause the run and feed an answer back into it.

Two ways to reconcile, your call:

• Turn boundary (fits today's architecture): the prompt tells the agent to write the interpretations / PLAN and STOP its turn. The framework sees it stopped, shows + gates (reusing [The Framework] Interactive <Choices> panel + autopilot auto-accept #304/Multi-select view (showMultiSelect()) #332), then starts a fresh turn seeded with the pick. This is exactly how plan-approval already works, and your "AI will interpret the macros correctly" fits it: the agent writes the file and stops, we do not need it to literally call a function.
• Tool channel: give Claude Code real showChoices()/showMarkdown() tools (MCP) that block until the dashboard answers. A true mid-turn pause, but it breaks the black-box seam (AI framework: presentation layer — headless server + CLI/web chat UIs #165) and couples us to MCP.

I lean turn-boundary for the MVP. Does AWAIT mean "end the turn and gate" (boundary), or a real mid-turn pause (tool channel)?

[brillout]

I think all <AWAIT> follow a <SHOW_*> macro, so the intention here is to await user answer. I don't have a preference how it's implemented. Your proposal sounds good to me.

[suleimansh]

Great, turn-boundary it is. I will implement the macros as: showMarkdown() alone = render to the doc sidebar (already live); showMarkdown()/showChoices() + AWAIT = the agent writes the artifact and ends its turn, the framework detects it at the turn boundary and gates (reusing the plan-approval / multi-select gates), then reseeds the next turn with the answer. #326 stays impl-agnostic, so keep adding your prose sections freely.

Starting on the shared single-select gate primitive that showChoices() needs.