From ad7d74820a8c76b76de8f031839fa6256f799b0b Mon Sep 17 00:00:00 2001 From: mika kuns Date: Thu, 4 Jun 2026 13:20:24 +0200 Subject: [PATCH] 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 --- ...6-06-04-bundled-prompts-overhaul-design.md | 231 ++++++++++++++++++ 1 file changed, 231 insertions(+) create mode 100644 docs/superpowers/specs/2026-06-04-bundled-prompts-overhaul-design.md diff --git a/docs/superpowers/specs/2026-06-04-bundled-prompts-overhaul-design.md b/docs/superpowers/specs/2026-06-04-bundled-prompts-overhaul-design.md new file mode 100644 index 0000000..d727e66 --- /dev/null +++ b/docs/superpowers/specs/2026-06-04-bundled-prompts-overhaul-design.md @@ -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 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: ` 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: + +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. +``` \ No newline at end of file