ClaudeDo/docs/superpowers/specs/2026-06-04-refine-task-design.md

Refine Task — Design

Date: 2026-06-04 Status: Approved (pending spec review)

Goal

Add a one-click Refine Task action to a task card. Clicking it spawns a headless Claude session that reads the task (and the repo), rewrites the task's description to be clearer and runnable autonomously, and — where it helps — breaks the work into subtasks. The user then reviews/hand-edits the result and queues the task manually.

This is not an interactive terminal session. It is a fire-and-forget headless run, structurally similar to the existing daily-prep ("Prime Claude") flow (PrimeRunner), not the interactive planning flow.

Non-goals / scope

• No new task status. The task stays Idle throughout; refine only mutates the task's Title/Description and its subtasks.
• No worktree, no interactive terminal, no auto-queue.
• No per-task refine config (model, turns) — uses the worker's defaults.
• Refine does not edit repository files; repo access is read-only.

User flow

1. User clicks the refine icon on an Idle task's card.
2. UI calls WorkerHub.RefineTask(taskId) → RefineRunner.
3. RefineRunner spawns claude -p headless in the list's working directory, seeded with a fixed refine prompt + the task's title/description/current subtasks + the task id.
4. Claude reads the repo (read-only), then calls:
   • mcp__claudedo__update_task to improve title/description, and
   • mcp__claudedo__add_subtask to add steps where useful. Each MCP call broadcasts TaskUpdated, so the description and Steps card update live in the UI.
5. Run finishes; the card's refine button returns to its idle state. User reviews, optionally hand-edits the description/steps, then queues manually.

Architecture

Worker — RefineRunner

• New Worker/Refine/RefineRunner.cs implementing IRefineRunner (Worker/Refine/Interfaces/IRefineRunner.cs). Modeled on PrimeRunner.
• Concurrency / single-flight: an in-flight HashSet<string> of task ids guarded by a lock (or SemaphoreSlim), so the same task cannot refine twice concurrently, but different tasks may refine in parallel. A second click on an already-refining task is a no-op.
• Guards: only runs when task.Status == Idle. Resolves the list's working directory. If the list has no valid working dir, fall back to a sandbox directory and run text-only (drop Read/Grep/Glob from the allowlist).
• CLI invocation (relies on the globally-registered claudedo MCP, like daily-prep — no --mcp-config):

  claude -p --output-format stream-json --verbose
         --permission-mode acceptEdits
         --max-turns <N>
         --allowedTools mcp__claudedo__get_task,mcp__claudedo__update_task,mcp__claudedo__add_subtask,Read,Grep,Glob
  

  Edit/Write/Bash are deliberately not whitelisted, so the run is read-only on the repo even under acceptEdits. (Chosen over plan mode to avoid the headless "exit plan mode to act" friction; the allowlist is the real read-only gate.)
• Logging: stream stdout to a per-run log at logs/refine-<taskId[:8]>.log, truncated at the start of each run.

Prompt — PromptKind.Refine

• Add Refine to the PromptKind enum in PromptFiles.cs, file prompts/refine.md, with a bundled default.
• Default prompt instructs: refine one ClaudeDo task so it is ready to run autonomously; ground the description in the actual code (read-only); keep scope tight (no scope creep into adjacent work); add steps as subtasks only when they genuinely help; use only get_task, update_task, add_subtask and the read-only tools; never edit files.
• Rendered via PromptFiles.Render with {taskId}, {title}, {description}, and the current subtask list seeded into the prompt so the agent knows which steps already exist.

MCP tool — add_subtask

• New [McpServerTool] on ExternalMcpService (part of the global claudedo MCP), signature add_subtask(taskId, title, orderNum?).
• Creates a SubtaskEntity via SubtaskRepository; orderNum defaults to append-at-end (max existing + 1). Refuses if the task is Running. Broadcasts TaskUpdated.
• Append semantics, not replace: the current subtasks are already in the prompt, so the agent only adds missing steps; re-running refine will not silently wipe steps the user hand-edited.
• update_task already exists (title/description/commitType) and is reused unchanged.

UI — button, icon, feedback

• Icon: add the supplied SVG as an Icon.Refine StreamGeometry in IslandStyles.axaml, rendered as a stroked Path (plan-icon style, fill none) — it is line art, so per the PathIcon-fills-geometry gotcha it must be stroked, not filled.
• Button: a new icon-btn in TaskRowView.axaml near the star button, visible only when the task is Idle. Bound to a new RefineTaskCommand on TasksIslandViewModel.
• Feedback: new broadcaster events RefineStarted(taskId) / RefineFinished(taskId, ok, error?) drive an IsRefining flag on TaskRowViewModel; the button shows a busy/disabled state while running. The description and Steps card update live via the existing TaskUpdated events fired by the MCP calls.
• Wire RefineTask through IWorkerClient / WorkerClient, the WorkerHub method, and update the hand-rolled test fakes in both test projects.

Testing

• add_subtask: creates the row, appends order correctly, refuses when Running, broadcasts TaskUpdated.
• Refine prompt builder and CLI-args builder produce the expected prompt/flags (including the text-only fallback when no working dir).
• RefineRunner guards: Idle-only, per-task single-flight no-op on a second concurrent call.
• No test spawns the real claude CLI (project rule). The end-to-end run is a manual smoke step.

Open implementation calls (decided)

• Permission mode: acceptEdits + restricted allowlist for read-only (rather than plan mode).
• add_subtask: append-only (rather than replace-all).