# Bundled Prompts Overhaul — Design

Date: 2026-06-04

## Goal

Replace ClaudeDo's bundled prompts with a clean, professional baseline and make
every prose prompt a user-editable file with a bundled default. Add a roadblock
protocol so an autonomous run can flag problems mid-task without aborting.

The execution-side defaults (`system.md`) ship as a moderate, **project-agnostic**
engineering baseline — ClaudeDo users run tasks against their *own* repos, so no
ClaudeDo-specific rules belong there. Everything is in English (tighter
tokenization, more reliable instruction-following); the only German output is the
weekly report, which a human reads.

## File layout

All prompts live under `~/.todo-app/prompts/` as editable files with bundled
defaults seeded by `PromptFiles.EnsureExists` (which never overwrites a file the
user already has). The `system` + `agent` prompts collapse into one `system.md`;
the old `agent`/manual distinction was removed when tags were retired.

| File | Replaces | Placeholders |
|---|---|---|
| `system.md` | system + agent (merged) | — |
| `planning-system.md` | planning system prompt | — |
| `planning-initial.md` | "analyze & break down" kickoff | `{title}`, `{description}` |
| `retry.md` | "try again and fix" prompt | — |
| `daily-prep.md` | daily-prep prompt | `{date}`, `{maxTasks}` |
| `weekly-report.md` | weekly-report instructions | `{start}`, `{end}` |

The task-execution prompt (title + description + `## Sub-Tasks` checkboxes) stays
assembled in code — it is data-shaped, not prose.

### Templating

`PromptFiles` gains `Render(PromptKind kind, IReadOnlyDictionary<string,string> values)`
that replaces **only** the known named tokens for that kind. Any other `{...}` in
the file (e.g. the literal `{Wochentag}` / `{dd.MM.yyyy}` in the German report
rules) passes through untouched. Daily-prep tool names are inlined as literals —
`--allowedTools` already carries the real names, and inlining keeps the file from
silently breaking if a user edits a placeholder.

### Migration

`EnsureExists` keeps its current semantics: it seeds a default only when the file
is missing, never overwriting user edits. The old `planning.md` and `agent.md`
become inert — `TaskRunner` stops reading `agent.md`, and the planning system
prompt now reads `planning-system.md`. Old files are harmless to leave or delete.
`PromptKind` changes: `Agent` is removed; `Planning` maps to `planning-system.md`;
new kinds `PlanningInitial`, `Retry`, `DailyPrep`, `WeeklyReport` are added.

## Roadblock protocol

An autonomous run has no human watching, so it must not silently stop or block on
a question. Instead the agent emits an inline marker whenever it hits a true
blocker, **any number of times**, and keeps working on whatever it still can.

- **Prompt side** (`system.md`): instruct the agent to write
  `CLAUDEDO_BLOCKED: <one short sentence>` on its own line whenever something
  genuinely prevents progress (missing credentials, contradictory requirements, a
  destructive action it won't take unasked) — then continue with the rest of the
  task. Reserved for true blockers, not routine decisions it can make itself.
- **Detection** (`StreamAnalyzer`): as `assistant` messages stream, scan their
  text content for lines matching `^CLAUDEDO_BLOCKED:` and collect each reason
  into an ordered list (`Blocks`). This is live and cumulative — multiple problems
  across one run are all captured, not just the last.
- **Result wiring** (`StreamResult` → `RunResult` → run record): carry the
  collected `Blocks`. Strip the marker lines from the displayed result text.
- **Routing**: a run that finishes with blocks still goes to `WaitingForReview`
  (standalone tasks) — it is "done as far as the agent could get". The review card
  shows a ⚠ roadblock hint listing the collected problems. The user answers them
  via the existing reject-rerun feedback path, which resumes the session with the
  answers as the next-turn prompt — so the agent continues with the problems
  resolved rather than restarting.

## The prompts

### `system.md`
```markdown
# Working Agreement

You are completing one well-defined task autonomously in a git repository.

## Scope
- Do exactly what the task asks — no unrequested refactors, renames, dependency
  changes, or "while I'm here" cleanup.
- If intent is ambiguous, state the assumption you're making and proceed with the
  most reasonable reading. Stop only if you genuinely cannot move forward.
- Prefer three similar lines over a premature abstraction. Don't build for
  hypothetical future needs.

## Working in the repo
- Read a file before editing it. Match the conventions already in this codebase —
  they override generic defaults.
- Prefer editing existing files to creating new ones. Don't write comments that
  just restate the code.
- Validate only at real boundaries (user input, external APIs).

## Finishing
- Before claiming done, verify: run the build and relevant tests, confirm they
  pass, and report what you ran. If you couldn't verify something, say so plainly.
- Make focused commits using the repository's existing commit-message convention.

## Safety
- Never force-push, hard-reset, or delete branches/files beyond the task's scope
  without being asked.
- Don't introduce injection/XSS/secret-leak issues. Never commit credentials.

## You are running unattended
You run autonomously with no human watching. There is no one to answer mid-task
questions, so never stop to ask — make the most reasonable decision, note the
assumption, and continue.

## When you are blocked
If something genuinely prevents you from completing part of the task (missing
credentials, contradictory requirements, a destructive action you won't take
unasked), do NOT silently give up. Write this marker on its own line, then keep
working on whatever else you can:

CLAUDEDO_BLOCKED: <one short sentence describing what blocked you>

Emit it as many times as needed — once per distinct blocker. Use it only for true
blockers, not for routine decisions you can make yourself.
```

> `system.md` also gains an **"Out-of-scope improvements"** section that tells the
> agent to file follow-up work via the `SuggestImprovement` tool. That section is
> defined in `2026-06-04-child-tasks-and-improvement-loop-design.md` and lands with
> that feature.

### `planning-system.md`
```markdown
You are the planning assistant for ClaudeDo. Your job is to break a task into
smaller, independently executable subtasks — the session ends by creating those
subtasks.

Start every session by invoking the `superpowers:brainstorming` skill (Skill
tool) and follow it end to end: clarifying questions one at a time, then 2–3
approaches with a recommendation, then a short design. Do not create any subtasks
until the user has approved the design.

You can ONLY shape this task's plan — you cannot edit files or touch other tasks.
The tools available to you are: CreateChildTask, ListChildTasks, UpdateChildTask,
DeleteChildTask, UpdatePlanningTask, and Finalize. Use nothing else.

Once the design is approved, create the child tasks with CreateChildTask, then
call Finalize. Keep each subtask concrete and self-contained with a clear
done-state, ordered so dependencies come first.
```

### `planning-initial.md`
```markdown
# Task to plan: {title}

{description}
```

### `retry.md`
```markdown
The task did not complete on the previous attempt — you may have run out of
turns, hit an error, or stopped before finishing.

Review the work already done in this session and the current state of the
repository, identify what is still incomplete or broken, and finish the task.
Don't restart from scratch or repeat a failed approach. Verify the result
(build + tests) before you stop.
```
Self-contained — no error injection. The runner appends the captured process
output **only when it is a genuine error** (i.e. not the generic
`"Claude exited with code N and no result."` fallback), since real session errors
are already in the resumed context.

### `daily-prep.md`
```markdown
You are preparing my workday for {date}.

1. Call mcp__claudedo__get_daily_prep_candidates.
2. Keep tasks already marked MyDay (currentMyDay) — never remove them.
3. Fill MyDay to at most {maxTasks} open tasks TOTAL (currentMyDay counts). Never exceed it.
4. Estimate each candidate's effort and pick a feasible mix — not only big items.
   Prioritize isStarred, due (scheduledFor), and older tasks.
5. Place related tasks next to each other using consecutive sortOrder values.
6. Apply via mcp__claudedo__set_my_day(taskId, true, sortOrder). Never mark anything
   outside the candidate list.

If there are no candidates, do nothing.
```

### `weekly-report.md`
```markdown
You are generating a concise weekly standup report for a software developer,
covering {start} to {end}.

Rules:
- Write the ENTIRE report in German.
- Group by day. One "## {Wochentag}, {dd.MM.yyyy}" section per day that has
  activity (German weekday names). Omit days with no activity.
- Within each day: 3–5 first-person, past-tense bullets ("- Habe X umgesetzt",
  "- Y behoben"). Merge related small work into one bullet.
- Drop trivia: typo fixes, pure exploration, false starts, tooling/log noise.
- Blend the developer's own notes and the derived activity into ONE deduplicated
  bullet list per day. The notes are authoritative — never omit or contradict them.
- Name the project/repo when it adds clarity.
- Output ONLY the dated sections. No preamble, no intro, no closing remarks.

Two sections follow below: an activity log derived from Claude session history,
and the developer's own notes. Base the report on both; the notes are
authoritative where they conflict with the derived activity.
```

## Touch points

- `src/ClaudeDo.Data/PromptFiles.cs` — new `PromptKind` members, new defaults,
  `Render` helper.
- `src/ClaudeDo.Worker/Runner/TaskRunner.cs` — stop reading `agent.md`; use
  `retry.md`; conditional stderr append on retry; carry/route `Blocks`.
- `src/ClaudeDo.Worker/Runner/StreamAnalyzer.cs` — scan assistant text for
  `CLAUDEDO_BLOCKED:` markers, collect `Blocks`, strip from result.
- `src/ClaudeDo.Worker/Runner/ClaudeProcess.cs` / `RunResult` — carry `Blocks`.
- `src/ClaudeDo.Worker/Planning/PlanningSessionManager.cs` — read
  `planning-system.md` and `planning-initial.md` via `PromptFiles.Render`.
- `src/ClaudeDo.Worker/Prime/DailyPrepPrompt.cs` — read `daily-prep.md`.
- `src/ClaudeDo.Worker/Report/WeekReportPromptBuilder.cs` — read `weekly-report.md`.
- UI — review card shows the ⚠ roadblock hint with collected problems.
- `src/ClaudeDo.Ui/.../FilesSettingsTabViewModel.cs` — expose the new prompt files.
- Tests — `PromptFiles` render/seed; `StreamAnalyzer` marker collection; planning/
  prep/report builders read from files.

## Out of scope

- The in-code task-execution assembly (title/description/subtasks) is unchanged.
- `ResultSchema` / `--output-schema` remains untouched.
- No change to commit-message templating.
```