ClaudeDo/docs/superpowers/specs/2026-06-04-bundled-prompts-overhaul-design.md

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

# 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

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

# Task to plan: {title}

{description}

retry.md

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

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

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.