docs: design for bundled-prompts overhaul
Externalize all prose prompts to editable files, collapse system+agent, add an inline roadblock protocol detected by StreamAnalyzer. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
mika kuns
@@ -0,0 +1,231 @@
|
|||||||
|
# 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.
|
||||||
|
```
|
||||||
|
|
||||||
|
### `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.
|
||||||
|
```
|
||||||
Reference in New Issue
Block a user