ClaudeDo/docs/prompts-inventory.md

ClaudeDo — Prompt & CLI Inventory

Snapshot of every string ClaudeDo sends to Claude CLI, plus the CLI-flag surface that shapes each run. Intended as a working doc for tomorrow's prompt-tuning pass.

Date: 2026-04-24

---

1. Task-execution prompts (agent-tagged tasks → Claude CLI)

Used for every "agent" task that the queue picks up or that RunNow dispatches. Orchestration lives in src/ClaudeDo.Worker/Runner/TaskRunner.cs and ClaudeArgsBuilder.cs.

1.1 User prompt (stdin) — TaskRunner.RunAsync ~L101–L110

Plain text, no template around it:

{task.Title}

{task.Description?.Trim()}        ← only if non-empty

## Sub-Tasks                      ← only if subtasks exist
- [ ] {subtask.Title}             ← "[x]" if completed
...

Notes

• Title is included verbatim — no leading # heading.
• No role tags, no XML, no delimiters between title and description — just blank lines.
• Sub-Tasks section uses markdown checkboxes. This is the only structural scaffolding.
• No context about the project, working dir, or git state is added here.

1.2 Retry prompt (on failure, when a session ID exists) — TaskRunner ~L126

The previous attempt failed with:

{result.ErrorMarkdown}

Try again and fix the issues.

Fired once per task via --resume <session_id>; if the retry also fails, the task is marked Failed.

1.3 Follow-up prompt (multi-turn ContinueAsync) — TaskRunner.ContinueAsync L159

The UI/hub supplies followUpPrompt as-is; no wrapping. The session is resumed via --resume. So the effective "prompt template" is whatever the user types in the Continue textbox.

1.4 System prompt — merged in TaskRunner ~L413–L418

Built by TaskRunner.MergeInstructions(global, list, task) which concatenates three optional strings with \n\n:

1. AppSettings.DefaultClaudeInstructions (global, set in Settings modal, default "")
2. list_config.SystemPrompt (per-list override)
3. task.SystemPrompt (per-task override)

The merged string is passed as --append-system-prompt <instructions> to the CLI. Empty/whitespace → flag is omitted entirely.

Currently the global DefaultClaudeInstructions ships as empty string (see AppSettingsEntity.cs L9). Anything in the system prompt today is whatever the user typed into Settings / List-Settings / Task-Settings.

1.5 CLI args — ClaudeArgsBuilder.Build (ClaudeArgsBuilder.cs)

Always on:

• -p
• --output-format stream-json
• --verbose
• --permission-mode {auto|acceptEdits|plan|default} (legacy bypassPermissions → auto)

Conditional:

• --model {sonnet|opus|haiku|...} — from task.Model ?? list.Model ?? AppSettings.DefaultModel (default sonnet)
• --max-turns {n} — AppSettings.DefaultMaxTurns (default 100)
• --append-system-prompt "{merged instructions}" — see 1.4
• --agents '[{"file":"{path}"}]' — from task or list override, points at an agent .md
• --resume {session_id} — for retries and ContinueAsync

Unused but pre-declared:

• ResultSchema — a {summary, files_changed, commit_type} JSON schema is serialized but never attached to args in Build. Dead code today; relevant if we turn on --output-schema.

---

2. Planning-agent prompts (/plan / Planning session)

Used by the Planning feature, which spawns a Claude session inside a git worktree with MCP tools so the agent can create Subtasks under the parent. Source: src/ClaudeDo.Worker/Planning/PlanningSessionManager.cs.

2.1 System prompt — BuildSystemPrompt() L290–L308

You are a planning assistant for ClaudeDo.
Your role is to help break down a task into smaller, actionable subtasks.
Your final goal WILL ALWAYS be the creation of Subtasks

ALWAYS invoke the `superpowers:brainstorming` skill via the Skill tool at the
start of every planning session, and follow its process end-to-end. It guides
you through clarifying questions, approach exploration, and design approval
BEFORE any subtasks are created. Do not create child tasks until the user has
approved a design.

NEVER Change files yourself. 

ALWAYS Use the available MCP tools (mcp__claudedo__*) to create child tasks once the
design is approved. When you are done planning, finalize the session.

Be concise and focused. Each subtask should be independently executable.

Written to {session-dir}/system-prompt.md at session start and fed via --append-system-prompt.

Notes / known oddities

• Trailing space on "NEVER Change files yourself. " and on the blank line above the ALWAYS/MCP block.
• Mixes voice ("Your role is", "ALWAYS invoke") — could be tightened.
• Implicitly relies on the superpowers:brainstorming skill being installed in the worktree's Claude config.
• Does not name the MCP tools explicitly (the mcp__claudedo__* wildcard assumes the agent discovers them via tool listing).

2.2 Initial prompt — BuildInitialPrompt(task) L310–L323

# Task: {task.Title}

{task.Description}     ← only if non-empty

---

Please analyze this task and break it down into concrete subtasks.

Written to {session-dir}/initial-prompt.txt; the Windows Terminal launcher pipes it to the Claude CLI on start.

2.3 Planning session CLI flags

PlanningSessionManager itself does not build CLI args — the WindowsTerminalPlanningLauncher does. Relevant facts:

• Permission mode: plan (per recent commit 8e9f09a "run planning agent in plan permission mode and enforce brainstorming skill").
• Runs with an .mcp.json that points at our local MCP server (http://127.0.0.1:{port}/mcp) with a per-session bearer token.
• .claude/settings.local.json sets "enableAllProjectMcpServers": true so the MCP tools auto-activate.

---

3. Commit-message template (not a prompt, but agent-visible)

Built by CommitMessageBuilder.Build (CommitMessageBuilder.cs). Format:

{commitType}({listSlug}): {title ≤60 chars}

{description ≤400 chars}        ← only if set

ClaudeDo-Task: {taskId}

• commitType comes from task.CommitType (default chore, list default configurable).
• Slug = lowercased list name with non-alphanumerics stripped, runs collapsed to -.
• The agent sees the resulting commit in git log during retries and follow-ups, so phrasing here bleeds into model behavior on multi-turn work.

---

4. Where each prompt is edited (UI surface)

Prompt slot	Edited in	Stored as
Global DefaultClaudeInstructions	Settings modal (SettingsModalViewModel)	app_settings.DefaultClaudeInstructions
Per-list system prompt	List-Settings modal	list_config.SystemPrompt
Per-task system prompt	Details island / task agent settings	tasks.system_prompt
Per-task agent file	Details island	tasks.agent_path (absolute .md path)
Default model / max turns / perms	Settings modal	app_settings.*
Planning system prompt	Hard-coded in PlanningSessionManager	not editable from UI
Planning initial prompt template	Hard-coded in PlanningSessionManager	not editable from UI
Retry prompt	Hard-coded in TaskRunner	not editable
Task prompt structure (title/desc)	Hard-coded in TaskRunner	not editable

---

5. Things worth reviewing tomorrow

1. Task-execution prompt has no frame at all. Just title + description. Consider whether a thin wrapper (goal / constraints / done-criteria) improves agent focus without bloating small tasks.
2. Global DefaultClaudeInstructions is empty out of the box. This is the cleanest place to put project-wide guardrails (commit format, branch etiquette, verify-before-done, no force push). Right now nothing is there.
3. Planning system prompt:
   • Typo-level: trailing spaces, inconsistent capitalization ("ALWAYS"/"NEVER"/"Always").
   • "Your final goal WILL ALWAYS be the creation of Subtasks" conflicts slightly with "Do not create child tasks until the user has approved a design" — rewordable.
   • Does not state how many subtasks is reasonable, nor how granular.
   • Does not describe the MCP tool surface; the agent has to discover mcp__claudedo__* tools.
4. Retry prompt is minimal. "Try again and fix the issues." — could be firmer about not repeating the same failure mode.
5. Sub-Tasks block is dumped as plain checkboxes with no instruction ("please complete all open items", "do them in order", etc.). If the user relies on subtasks for ordering, that intent isn't conveyed.
6. ResultSchema is defined but unused. Decide: drop it, or wire it up (--output-schema) and start asking for structured summaries.
7. Commit-message template never tells the agent what commit_type to pick when it has flexibility — the value is hard-coded per task. Consider exposing as a prompt hint or inferring from diffs.

---

6. File pointers

• src/ClaudeDo.Worker/Runner/TaskRunner.cs — user/retry/follow-up prompts, MergeInstructions
• src/ClaudeDo.Worker/Runner/ClaudeArgsBuilder.cs — CLI args + ResultSchema
• src/ClaudeDo.Worker/Runner/CommitMessageBuilder.cs — commit template
• src/ClaudeDo.Worker/Planning/PlanningSessionManager.cs — planning system + initial prompts
• src/ClaudeDo.Worker/Planning/WindowsTerminalPlanningLauncher.cs — planning CLI invocation
• src/ClaudeDo.Data/Models/AppSettingsEntity.cs — global defaults
• src/ClaudeDo.Ui/ViewModels/Modals/SettingsModalViewModel.cs — UI for global defaults
• src/ClaudeDo.Ui/ViewModels/Modals/ListSettingsModalViewModel.cs — UI for per-list overrides