# 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