docs(superpowers): add default-agents plan and design spec
This commit is contained in:
mika kuns
177
docs/superpowers/specs/2026-04-23-default-agents-design.md
Normal file
177
docs/superpowers/specs/2026-04-23-default-agents-design.md
Normal file
@@ -0,0 +1,177 @@
|
||||
# Default Agents — Design
|
||||
|
||||
**Date:** 2026-04-23
|
||||
**Status:** Approved
|
||||
|
||||
## Goal
|
||||
|
||||
Ship ClaudeDo with a curated set of default agents so that users have useful agents available on first launch, without losing the file-based ownership model (user-editable, user-deletable). Provide a "Restore defaults" action to recover missing defaults on demand.
|
||||
|
||||
## Agents to Ship
|
||||
|
||||
Six markdown agents covering the common stages of task execution plus one general-purpose agent:
|
||||
|
||||
| File | Focus |
|
||||
|---|---|
|
||||
| `code-reviewer.md` | Review diff for bugs, logic errors, convention adherence. Flags only high-confidence issues. |
|
||||
| `test-writer.md` | Generate unit/integration tests for changed code. Follows existing test patterns. |
|
||||
| `debugger.md` | Systematic root-cause analysis — reproduce, isolate, hypothesize, verify. |
|
||||
| `security-reviewer.md` | OWASP-style audit focused on auth, SQL injection, input handling, secret exposure. |
|
||||
| `explorer.md` | Fast codebase navigation and answering "where/how" questions. Terse output. |
|
||||
| `researcher.md` | General-purpose research, doc summarization, analysis, investigation. Non-code. |
|
||||
|
||||
Each file uses Claude Code's standard agent frontmatter:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: <agent name>
|
||||
description: <one-line description>
|
||||
---
|
||||
|
||||
<system prompt body>
|
||||
```
|
||||
|
||||
Content target: ~20–40 lines per file. Style matches the existing Claude Code agent conventions.
|
||||
|
||||
## Behavior
|
||||
|
||||
**Seed on first launch, restore on demand:**
|
||||
|
||||
1. Bundled agents live alongside the Worker binary at `<AppContext.BaseDirectory>/DefaultAgents/*.md`.
|
||||
2. At Worker startup, for each bundled file: if `~/.todo-app/agents/<name>.md` does NOT exist, copy it in. If it exists, leave it alone — the user owns their copy.
|
||||
3. A "Restore default agents" button in the settings modal re-runs the same check, restoring any that the user has deleted.
|
||||
|
||||
The seed path and the restore path are the same code — only the invocation differs (startup vs. hub call).
|
||||
|
||||
## Components
|
||||
|
||||
### `DefaultAgents/*.md` (bundled content)
|
||||
|
||||
Location: `src/ClaudeDo.Worker/DefaultAgents/`
|
||||
Packaging: `<Content Include="DefaultAgents\*.md" CopyToOutputDirectory="PreserveNewest" />` in `ClaudeDo.Worker.csproj`.
|
||||
At runtime they land at `<AppContext.BaseDirectory>/DefaultAgents/*.md` next to the executable.
|
||||
|
||||
### `DefaultAgentSeeder` (new service)
|
||||
|
||||
Location: `src/ClaudeDo.Worker/Services/DefaultAgentSeeder.cs`
|
||||
|
||||
```
|
||||
public sealed class DefaultAgentSeeder
|
||||
{
|
||||
public DefaultAgentSeeder(string bundleDir, string targetDir);
|
||||
public Task<SeedResult> SeedMissingAsync(CancellationToken ct = default);
|
||||
}
|
||||
|
||||
public sealed record SeedResult(int Copied, int Skipped);
|
||||
```
|
||||
|
||||
Behavior of `SeedMissingAsync`:
|
||||
- If `bundleDir` doesn't exist, log warning and return `(0, 0)`.
|
||||
- Enumerate `*.md` in `bundleDir`.
|
||||
- For each file, if the target path (`targetDir/<filename>`) is missing, copy it; else increment `Skipped`.
|
||||
- Create `targetDir` if missing (consistent with existing `AgentFileService.WriteAsync`).
|
||||
- Per-file exceptions are caught and logged; the seeder continues with the next file. The method itself does not throw for individual file failures.
|
||||
|
||||
### `Program.cs` wiring
|
||||
|
||||
After `AgentFileService` registration and before `app.Run()`:
|
||||
|
||||
```csharp
|
||||
var bundleDir = Path.Combine(AppContext.BaseDirectory, "DefaultAgents");
|
||||
var seeder = new DefaultAgentSeeder(bundleDir, agentsDir);
|
||||
await seeder.SeedMissingAsync();
|
||||
builder.Services.AddSingleton(seeder);
|
||||
```
|
||||
|
||||
The seeder is also registered as a singleton so the hub can invoke it for the restore flow.
|
||||
|
||||
### `WorkerHub.RestoreDefaultAgents`
|
||||
|
||||
Location: add method to existing `src/ClaudeDo.Worker/Hub/WorkerHub.cs`.
|
||||
|
||||
Signature: `public async Task<SeedResult> RestoreDefaultAgents()`
|
||||
|
||||
Behavior:
|
||||
- Calls `DefaultAgentSeeder.SeedMissingAsync()`.
|
||||
- Returns the `SeedResult` to the caller.
|
||||
- No separate broadcast — the UI will call `GetAgents` after the restore returns, reusing the existing refresh path.
|
||||
|
||||
### UI — Settings Modal
|
||||
|
||||
Location: `src/ClaudeDo.Ui/Views/Modals/SettingsModalView.axaml` + `SettingsModalViewModel`.
|
||||
|
||||
Add a "Restore default agents" button to the modal. On click:
|
||||
1. Disable the button, show a spinner label.
|
||||
2. Call `WorkerClient.RestoreDefaultAgentsAsync()`.
|
||||
3. Show a brief inline confirmation: `"Restored {Copied} agent(s)"` or `"All defaults already present"`.
|
||||
4. Trigger the existing agent list refresh so the new files appear immediately in the rest of the UI.
|
||||
|
||||
### `WorkerClient` method
|
||||
|
||||
Add `Task<SeedResult> RestoreDefaultAgentsAsync(CancellationToken ct = default)` to `WorkerClient` — thin wrapper that invokes the hub method.
|
||||
|
||||
## Data Flow
|
||||
|
||||
**Startup:**
|
||||
```
|
||||
Worker starts → DefaultAgentSeeder.SeedMissingAsync()
|
||||
→ copies missing files into ~/.todo-app/agents/
|
||||
AgentFileService.ScanAsync() (on first GetAgents call) → sees the seeded files
|
||||
```
|
||||
|
||||
**User restores:**
|
||||
```
|
||||
Settings modal button click
|
||||
→ WorkerClient.RestoreDefaultAgentsAsync()
|
||||
→ WorkerHub.RestoreDefaultAgents()
|
||||
→ DefaultAgentSeeder.SeedMissingAsync()
|
||||
→ returns SeedResult(copied, skipped)
|
||||
UI shows confirmation, triggers GetAgents refresh
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Failure | Behavior |
|
||||
|---|---|
|
||||
| Missing `DefaultAgents/` bundle dir | Log warning, return `(0, 0)`. Startup proceeds. |
|
||||
| Individual file copy failure (disk, permissions) | Catch per-file, log, continue with the remaining files. |
|
||||
| Corrupt bundled markdown (no valid frontmatter) | Copied anyway — the `AgentFileService` frontmatter parser already falls back to filename-as-name. |
|
||||
| Startup seeder exception (unexpected) | Log as warning, do not crash the Worker. Agents can still be restored via the button. |
|
||||
| Hub `RestoreDefaultAgents` exception | Propagate to client as SignalR error; UI shows a generic "Restore failed" message. |
|
||||
|
||||
## Testing
|
||||
|
||||
**Unit:** `tests/ClaudeDo.Worker.Tests/Services/DefaultAgentSeederTests.cs`
|
||||
|
||||
- Seeds all files when target dir is empty.
|
||||
- Skips files that already exist.
|
||||
- Preserves existing user-modified files (file mtime / content unchanged).
|
||||
- Returns accurate `SeedResult` counts.
|
||||
- Handles missing bundle dir gracefully (returns `(0, 0)`, no throw).
|
||||
- Creates target dir if it doesn't exist.
|
||||
|
||||
**Integration:** extend `tests/ClaudeDo.Worker.Tests/Hub/AgentSettingsHubTests.cs`
|
||||
|
||||
- `RestoreDefaultAgents` invokes the seeder and returns the count.
|
||||
|
||||
**No UI tests.** The project has no UI test harness; settings modal behavior is exercised manually.
|
||||
|
||||
## Build / Packaging
|
||||
|
||||
`src/ClaudeDo.Worker/ClaudeDo.Worker.csproj` gains:
|
||||
|
||||
```xml
|
||||
<ItemGroup>
|
||||
<Content Include="DefaultAgents\*.md">
|
||||
<CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
|
||||
</Content>
|
||||
</ItemGroup>
|
||||
```
|
||||
|
||||
No new NuGet dependencies.
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- Editing bundled agents in-place (user edits their copy under `~/.todo-app/agents/`; bundle is read-only by convention).
|
||||
- Versioning / updating user copies when the bundled version changes. If a bundled agent is improved in a later release, the user's copy is not overwritten. A future release may add a "diff / reset to bundled" flow, but not now.
|
||||
- Packaging as embedded resources. Content files copied to output are simpler, inspectable on disk, and consistent with the file-based agent model.
|
||||
Reference in New Issue
Block a user