199 lines
9.9 KiB
Markdown
199 lines
9.9 KiB
Markdown
# 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
|