docs(superpowers): add default-agents plan and design spec

2026-04-23 13:08:23 +02:00
parent 3c420acd54
commit a135485339
2 changed files with 1029 additions and 0 deletions
--- a/docs/superpowers/plans/2026-04-23-default-agents.md
+++ b/docs/superpowers/plans/2026-04-23-default-agents.md
@@ -0,0 +1,852 @@
 # Default Agents Implementation Plan
 > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
 **Goal:** Ship ClaudeDo with 6 default agents (code-reviewer, test-writer, debugger, security-reviewer, explorer, researcher) that seed into `~/.todo-app/agents/` on first launch, with a "Restore defaults" button in the settings modal.
 **Architecture:** Bundled `.md` files in `src/ClaudeDo.Worker/DefaultAgents/` are copied to the Worker output folder. A new `DefaultAgentSeeder` service copies any missing file into the user's agents dir — run once at startup, and again on demand via a new `WorkerHub.RestoreDefaultAgents` method invoked by a button in `SettingsModalView`.
 **Tech Stack:** .NET 8 / ASP.NET Core / SignalR / Avalonia 12 / CommunityToolkit.Mvvm / xUnit
 ---
 ## File Structure
 **Create:**
 - `src/ClaudeDo.Worker/DefaultAgents/code-reviewer.md`
 - `src/ClaudeDo.Worker/DefaultAgents/test-writer.md`
 - `src/ClaudeDo.Worker/DefaultAgents/debugger.md`
 - `src/ClaudeDo.Worker/DefaultAgents/security-reviewer.md`
 - `src/ClaudeDo.Worker/DefaultAgents/explorer.md`
 - `src/ClaudeDo.Worker/DefaultAgents/researcher.md`
 - `src/ClaudeDo.Worker/Services/DefaultAgentSeeder.cs`
 - `tests/ClaudeDo.Worker.Tests/Services/DefaultAgentSeederTests.cs`
 **Modify:**
 - `src/ClaudeDo.Worker/ClaudeDo.Worker.csproj` — add Content item group for `DefaultAgents\*.md`
 - `src/ClaudeDo.Worker/Program.cs` — register seeder, run `SeedMissingAsync()` once at startup
 - `src/ClaudeDo.Worker/Hub/WorkerHub.cs` — inject `DefaultAgentSeeder`, add `RestoreDefaultAgents` method
 - `src/ClaudeDo.Ui/Services/WorkerClient.cs` — add `RestoreDefaultAgentsAsync` method + `SeedResultDto` record
 - `src/ClaudeDo.Ui/ViewModels/Modals/SettingsModalViewModel.cs` — add `RestoreDefaultAgentsCommand`
 - `src/ClaudeDo.Ui/Views/Modals/SettingsModalView.axaml` — add button section
 - `tests/ClaudeDo.Worker.Tests/Hub/AgentSettingsHubTests.cs` — add seeder integration test
 ---
 ### Task 1: Bundle default agent markdown files
 **Files:**
 - Create: `src/ClaudeDo.Worker/DefaultAgents/code-reviewer.md`
 - Create: `src/ClaudeDo.Worker/DefaultAgents/test-writer.md`
 - Create: `src/ClaudeDo.Worker/DefaultAgents/debugger.md`
 - Create: `src/ClaudeDo.Worker/DefaultAgents/security-reviewer.md`
 - Create: `src/ClaudeDo.Worker/DefaultAgents/explorer.md`
 - Create: `src/ClaudeDo.Worker/DefaultAgents/researcher.md`
 - [ ] **Step 1: Write `code-reviewer.md`**
 ```markdown
 ---
 name: code-reviewer
 description: Reviews code changes for bugs, logic errors, and convention violations. Flags only high-confidence issues.
 ---
 You are a code reviewer. Your job is to inspect the diff for real problems, not nitpicks.
 Focus on:
 - Logic errors, off-by-one bugs, null/empty handling
 - Broken invariants, race conditions, resource leaks
 - Violations of the project's established conventions (read nearby code first)
 - Missing error handling at system boundaries (external input, IO, network)
 Skip:
 - Style preferences the codebase doesn't enforce
 - Speculative "what if" concerns
 - Renaming for its own sake
 Output: a short list of concrete issues with file:line references. If the diff is clean, say so in one sentence. Do not rewrite the code — call out the problem and let the implementer fix it.
 ```
 - [ ] **Step 2: Write `test-writer.md`**
 ```markdown
 ---
 name: test-writer
 description: Generates unit and integration tests for existing or new code. Follows the project's test patterns and frameworks.
 ---
 You are a test-writer. Your job is to write focused, useful tests for code under review.
 Process:
 1. Read the target code and identify the observable behavior.
 2. Read existing tests nearby to match the framework, fixtures, naming, and assertion style.
 3. Write tests covering the happy path, boundary conditions, and the specific failure modes that matter.
 Rules:
 - One behavior per test. Clear Arrange/Act/Assert.
 - No tests for private implementation details — exercise public API.
 - No mocks where real objects are cheap (in-memory DBs, temp dirs).
 - Skip trivially-correct tests (getter returns what you set).
 Output: the test file(s) ready to compile, matching the project's conventions. Include the command to run them.
 ```
 - [ ] **Step 3: Write `debugger.md`**
 ```markdown
 ---
 name: debugger
 description: Systematic root-cause analysis for bugs, test failures, and unexpected behavior. Hypothesize, isolate, verify.
 ---
 You are a debugger. You do NOT guess at fixes — you find the root cause first.
 Process:
 1. Reproduce. Get a minimal, deterministic repro. If you can't reproduce it, say so and stop.
 2. Isolate. Narrow the failing path (bisect, binary search, or tracing).
 3. Hypothesize. State a specific, falsifiable cause.
 4. Verify. Prove the hypothesis by observation (logs, debugger, targeted print) — not by "this seems likely".
 5. Fix at the root, not the symptom. If the only fix is a workaround, explain why.
 Anti-patterns to avoid:
 - Making changes to "see if it works"
 - Adding try/catch to silence errors
 - Declaring the bug fixed without reproducing the fix
 Output: repro steps, root cause, and the minimal fix. Include evidence (log excerpt, command output) that proves the cause.
 ```
 - [ ] **Step 4: Write `security-reviewer.md`**
 ```markdown
 ---
 name: security-reviewer
 description: Audits code for OWASP-class security issues — auth, injection, input handling, secret exposure.
 ---
 You are a security reviewer. Focus on real, exploitable weaknesses — not theoretical hardening.
 Check for:
 - Injection: SQL, command, path traversal, XSS, template injection
 - Auth: missing authorization, token handling, session fixation
 - Input validation at system boundaries (HTTP, files, IPC)
 - Secrets: hardcoded credentials, tokens in logs, leaked env vars
 - Unsafe deserialization, XXE, SSRF
 - Cryptography misuse (custom crypto, weak algorithms, fixed IVs)
 Ignore:
 - Internal trust-boundary assumptions the project already documents
 - Defense-in-depth ideas with no concrete attack path
 Output: a prioritized list — severity, file:line, the exploit path, the fix. If nothing is wrong, say so plainly.
 ```
 - [ ] **Step 5: Write `explorer.md`**
 ```markdown
 ---
 name: explorer
 description: Fast codebase navigation — find files, search for patterns, answer "where/how" questions. Terse output.
 ---
 You are an explorer. Your job is to find things in the codebase quickly and report back concisely.
 Use:
 - Glob/Grep for searches
 - Read only for files you need to quote from
 Do NOT:
 - Refactor, edit, or "improve" anything
 - Read files that aren't relevant to the question
 - Dump raw tool output — summarize
 Output style:
 - Lead with the answer in one sentence.
 - Back it up with file:line references.
 - If you found nothing, say "no match" and what you searched for.
 Keep responses short. The caller wants facts, not prose.
 ```
 - [ ] **Step 6: Write `researcher.md`**
 ```markdown
 ---
 name: researcher
 description: General-purpose research and analysis for non-code tasks — summarize docs, investigate questions, draft prose.
 ---
 You are a researcher. You handle tasks that don't fit the code-review/test/debug shape.
 Good fits:
 - Summarizing documents, specs, or long outputs
 - Investigating an open question (what does X do, how does Y work, what are the tradeoffs)
 - Drafting non-code text (release notes, emails, docs)
 - Analyzing structured data (logs, CSV, JSON) and reporting findings
 Process:
 1. Restate the task in one sentence so you know what "done" looks like.
 2. Gather just enough information — stop when you can answer, not when you run out of sources.
 3. Distinguish facts ("the file says X") from inference ("so likely Y").
 4. Cite sources (file:line, URL, log excerpt) for every claim.
 Output: direct answer first, supporting evidence second. Keep it short unless asked for depth.
 ```
 - [ ] **Step 7: Commit**
 ```bash
 git add src/ClaudeDo.Worker/DefaultAgents/
 git commit -m "feat(worker): add bundled default agent definitions"
 ```
 ---
 ### Task 2: Wire bundled agents into build output
 **Files:**
 - Modify: `src/ClaudeDo.Worker/ClaudeDo.Worker.csproj`
 - [ ] **Step 1: Add Content item group for DefaultAgents**
 Edit `src/ClaudeDo.Worker/ClaudeDo.Worker.csproj`. After the existing `<ItemGroup>` blocks and before the final `<PropertyGroup>`, add:
 ```xml
  <ItemGroup>
    <Content Include="DefaultAgents\*.md">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </Content>
  </ItemGroup>
 ```
 - [ ] **Step 2: Build the worker and verify the files land in output**
 Run: `dotnet build src/ClaudeDo.Worker/ClaudeDo.Worker.csproj`
 Expected: build succeeds.
 Then verify output:
 Run: `ls src/ClaudeDo.Worker/bin/Debug/net8.0/DefaultAgents/`
 Expected: all 6 `.md` files present.
 - [ ] **Step 3: Commit**
 ```bash
 git add src/ClaudeDo.Worker/ClaudeDo.Worker.csproj
 git commit -m "build(worker): ship DefaultAgents folder in build output"
 ```
 ---
 ### Task 3: Write DefaultAgentSeeder tests (failing)
 **Files:**
 - Create: `tests/ClaudeDo.Worker.Tests/Services/DefaultAgentSeederTests.cs`
 The service doesn't exist yet — these tests will fail to compile initially. That's fine; the next task implements it.
 - [ ] **Step 1: Write the test file**
 Create `tests/ClaudeDo.Worker.Tests/Services/DefaultAgentSeederTests.cs`:
 ```csharp
 using ClaudeDo.Worker.Services;
 namespace ClaudeDo.Worker.Tests.Services;
 public sealed class DefaultAgentSeederTests : IDisposable
 {
    private readonly string _bundleDir;
    private readonly string _targetDir;
    public DefaultAgentSeederTests()
    {
        var root = Path.Combine(Path.GetTempPath(), $"claudedo_seeder_{Guid.NewGuid():N}");
        _bundleDir = Path.Combine(root, "bundle");
        _targetDir = Path.Combine(root, "target");
        Directory.CreateDirectory(_bundleDir);
        Directory.CreateDirectory(_targetDir);
    }
    public void Dispose()
    {
        try { Directory.Delete(Path.GetDirectoryName(_bundleDir)!, true); } catch { }
    }
    private async Task WriteBundleAsync(string name, string content)
    {
        await File.WriteAllTextAsync(Path.Combine(_bundleDir, name), content);
    }
    [Fact]
    public async Task SeedMissing_CopiesAllFiles_WhenTargetEmpty()
    {
        await WriteBundleAsync("a.md", "A");
        await WriteBundleAsync("b.md", "B");
        var seeder = new DefaultAgentSeeder(_bundleDir, _targetDir);
        var result = await seeder.SeedMissingAsync();
        Assert.Equal(2, result.Copied);
        Assert.Equal(0, result.Skipped);
        Assert.True(File.Exists(Path.Combine(_targetDir, "a.md")));
        Assert.True(File.Exists(Path.Combine(_targetDir, "b.md")));
    }
    [Fact]
    public async Task SeedMissing_SkipsExistingFiles()
    {
        await WriteBundleAsync("a.md", "bundled");
        await File.WriteAllTextAsync(Path.Combine(_targetDir, "a.md"), "user-modified");
        var seeder = new DefaultAgentSeeder(_bundleDir, _targetDir);
        var result = await seeder.SeedMissingAsync();
        Assert.Equal(0, result.Copied);
        Assert.Equal(1, result.Skipped);
        var content = await File.ReadAllTextAsync(Path.Combine(_targetDir, "a.md"));
        Assert.Equal("user-modified", content);
    }
    [Fact]
    public async Task SeedMissing_MixedState_CopiesOnlyMissing()
    {
        await WriteBundleAsync("a.md", "A");
        await WriteBundleAsync("b.md", "B");
        await File.WriteAllTextAsync(Path.Combine(_targetDir, "a.md"), "existing");
        var seeder = new DefaultAgentSeeder(_bundleDir, _targetDir);
        var result = await seeder.SeedMissingAsync();
        Assert.Equal(1, result.Copied);
        Assert.Equal(1, result.Skipped);
        Assert.Equal("existing", await File.ReadAllTextAsync(Path.Combine(_targetDir, "a.md")));
        Assert.Equal("B", await File.ReadAllTextAsync(Path.Combine(_targetDir, "b.md")));
    }
    [Fact]
    public async Task SeedMissing_ReturnsZero_WhenBundleDirMissing()
    {
        var missingBundle = Path.Combine(Path.GetTempPath(), $"claudedo_missing_{Guid.NewGuid():N}");
        var seeder = new DefaultAgentSeeder(missingBundle, _targetDir);
        var result = await seeder.SeedMissingAsync();
        Assert.Equal(0, result.Copied);
        Assert.Equal(0, result.Skipped);
    }
    [Fact]
    public async Task SeedMissing_CreatesTargetDir_IfMissing()
    {
        await WriteBundleAsync("a.md", "A");
        var missingTarget = Path.Combine(_targetDir, "nested", "created");
        var seeder = new DefaultAgentSeeder(_bundleDir, missingTarget);
        var result = await seeder.SeedMissingAsync();
        Assert.Equal(1, result.Copied);
        Assert.True(File.Exists(Path.Combine(missingTarget, "a.md")));
    }
    [Fact]
    public async Task SeedMissing_IgnoresNonMarkdownFiles()
    {
        await WriteBundleAsync("a.md", "A");
        await File.WriteAllTextAsync(Path.Combine(_bundleDir, "readme.txt"), "not an agent");
        var seeder = new DefaultAgentSeeder(_bundleDir, _targetDir);
        var result = await seeder.SeedMissingAsync();
        Assert.Equal(1, result.Copied);
        Assert.False(File.Exists(Path.Combine(_targetDir, "readme.txt")));
    }
 }
 ```
 - [ ] **Step 2: Run tests to confirm they fail to compile**
 Run: `dotnet test tests/ClaudeDo.Worker.Tests --filter "FullyQualifiedName~DefaultAgentSeederTests"`
 Expected: compile error — `The type or namespace name 'DefaultAgentSeeder' could not be found`.
 This confirms the tests target the not-yet-written service.
 ---
 ### Task 4: Implement DefaultAgentSeeder
 **Files:**
 - Create: `src/ClaudeDo.Worker/Services/DefaultAgentSeeder.cs`
 - [ ] **Step 1: Write the service**
 Create `src/ClaudeDo.Worker/Services/DefaultAgentSeeder.cs`:
 ```csharp
 using Microsoft.Extensions.Logging;
 namespace ClaudeDo.Worker.Services;
 public sealed record SeedResult(int Copied, int Skipped);
 public sealed class DefaultAgentSeeder
 {
    private readonly string _bundleDir;
    private readonly string _targetDir;
    private readonly ILogger<DefaultAgentSeeder>? _logger;
    public DefaultAgentSeeder(string bundleDir, string targetDir, ILogger<DefaultAgentSeeder>? logger = null)
    {
        _bundleDir = bundleDir;
        _targetDir = targetDir;
        _logger = logger;
    }
    public async Task<SeedResult> SeedMissingAsync(CancellationToken ct = default)
    {
        if (!Directory.Exists(_bundleDir))
        {
            _logger?.LogWarning("DefaultAgents bundle dir not found: {Dir}", _bundleDir);
            return new SeedResult(0, 0);
        }
        Directory.CreateDirectory(_targetDir);
        int copied = 0;
        int skipped = 0;
        foreach (var src in Directory.EnumerateFiles(_bundleDir, "*.md"))
        {
            ct.ThrowIfCancellationRequested();
            var fileName = Path.GetFileName(src);
            var dst = Path.Combine(_targetDir, fileName);
            if (File.Exists(dst))
            {
                skipped++;
                continue;
            }
            try
            {
                using var input = File.OpenRead(src);
                using var output = File.Create(dst);
                await input.CopyToAsync(output, ct);
                copied++;
            }
            catch (Exception ex)
            {
                _logger?.LogWarning(ex, "Failed to copy default agent {File}", fileName);
            }
        }
        return new SeedResult(copied, skipped);
    }
 }
 ```
 - [ ] **Step 2: Run the tests and verify they pass**
 Run: `dotnet test tests/ClaudeDo.Worker.Tests --filter "FullyQualifiedName~DefaultAgentSeederTests"`
 Expected: 6 tests pass.
 - [ ] **Step 3: Commit**
 ```bash
 git add src/ClaudeDo.Worker/Services/DefaultAgentSeeder.cs tests/ClaudeDo.Worker.Tests/Services/DefaultAgentSeederTests.cs
 git commit -m "feat(worker): add DefaultAgentSeeder for first-launch agent seeding"
 ```
 ---
 ### Task 5: Wire seeder into Worker startup
 **Files:**
 - Modify: `src/ClaudeDo.Worker/Program.cs`
 - [ ] **Step 1: Register seeder and run SeedMissingAsync at startup**
 In `src/ClaudeDo.Worker/Program.cs`, replace the "Agent file management." block (currently lines 36–39):
 Find:
 ```csharp
 // Agent file management.
 var agentsDir = Path.Combine(ClaudeDo.Data.Paths.AppDataRoot(), "agents");
 Directory.CreateDirectory(agentsDir);
 builder.Services.AddSingleton(new AgentFileService(agentsDir));
 ```
 Replace with:
 ```csharp
 // Agent file management.
 var agentsDir = Path.Combine(ClaudeDo.Data.Paths.AppDataRoot(), "agents");
 Directory.CreateDirectory(agentsDir);
 builder.Services.AddSingleton(new AgentFileService(agentsDir));
 var defaultAgentsBundleDir = Path.Combine(AppContext.BaseDirectory, "DefaultAgents");
 builder.Services.AddSingleton(sp => new DefaultAgentSeeder(
    defaultAgentsBundleDir,
    agentsDir,
    sp.GetService<Microsoft.Extensions.Logging.ILogger<DefaultAgentSeeder>>()));
 ```
 Then, after `var app = builder.Build();` and before `app.MapHub<WorkerHub>("/hub");`, add:
 Find:
 ```csharp
 using (var scope = app.Services.CreateScope())
 {
    ClaudeDoDbContext.MigrateAndConfigure(
        scope.ServiceProvider.GetRequiredService<ClaudeDoDbContext>());
 }
 app.MapHub<WorkerHub>("/hub");
 ```
 Replace with:
 ```csharp
 using (var scope = app.Services.CreateScope())
 {
    ClaudeDoDbContext.MigrateAndConfigure(
        scope.ServiceProvider.GetRequiredService<ClaudeDoDbContext>());
 }
 try
 {
    var seeder = app.Services.GetRequiredService<DefaultAgentSeeder>();
    var seedResult = await seeder.SeedMissingAsync();
    app.Logger.LogInformation(
        "Default agents seeded: {Copied} copied, {Skipped} already present",
        seedResult.Copied, seedResult.Skipped);
 }
 catch (Exception ex)
 {
    app.Logger.LogWarning(ex, "Default agent seeding failed");
 }
 app.MapHub<WorkerHub>("/hub");
 ```
 - [ ] **Step 2: Build worker to verify compile**
 Run: `dotnet build src/ClaudeDo.Worker/ClaudeDo.Worker.csproj`
 Expected: build succeeds.
 - [ ] **Step 3: Commit**
 ```bash
 git add src/ClaudeDo.Worker/Program.cs
 git commit -m "feat(worker): seed default agents on startup"
 ```
 ---
 ### Task 6: Add RestoreDefaultAgents hub method (TDD)
 **Files:**
 - Modify: `tests/ClaudeDo.Worker.Tests/Hub/AgentSettingsHubTests.cs`
 - Modify: `src/ClaudeDo.Worker/Hub/WorkerHub.cs`
 The existing `AgentSettingsHubTests` doesn't exercise `WorkerHub` directly (it tests the repository). We'll add a new test file that tests the seeder restore flow end-to-end without SignalR plumbing — constructing the seeder with temp dirs and asserting the `SeedResult` round-trip. This mirrors how the file is structured today and keeps tests simple.
 - [ ] **Step 1: Add a restore test**
 Add to `tests/ClaudeDo.Worker.Tests/Hub/AgentSettingsHubTests.cs`. Inside the existing `AgentSettingsHubTests` class (before the closing brace), add:
 ```csharp
    [Fact]
    public async Task RestoreDefaultAgents_CopiesMissingBundledFiles()
    {
        var root = Path.Combine(Path.GetTempPath(), $"claudedo_hub_restore_{Guid.NewGuid():N}");
        var bundleDir = Path.Combine(root, "bundle");
        var targetDir = Path.Combine(root, "target");
        try
        {
            Directory.CreateDirectory(bundleDir);
            Directory.CreateDirectory(targetDir);
            await File.WriteAllTextAsync(Path.Combine(bundleDir, "code-reviewer.md"), "body");
            var seeder = new ClaudeDo.Worker.Services.DefaultAgentSeeder(bundleDir, targetDir);
            var result = await seeder.SeedMissingAsync();
            Assert.Equal(1, result.Copied);
            Assert.Equal(0, result.Skipped);
            Assert.True(File.Exists(Path.Combine(targetDir, "code-reviewer.md")));
        }
        finally
        {
            try { Directory.Delete(root, true); } catch { }
        }
    }
 ```
 - [ ] **Step 2: Run the test to confirm it passes (seeder already exists)**
 Run: `dotnet test tests/ClaudeDo.Worker.Tests --filter "FullyQualifiedName~AgentSettingsHubTests.RestoreDefaultAgents_CopiesMissingBundledFiles"`
 Expected: 1 test passes.
 - [ ] **Step 3: Add RestoreDefaultAgents to WorkerHub**
 Edit `src/ClaudeDo.Worker/Hub/WorkerHub.cs`.
 Add a new DTO record near the top with the other DTOs (after the `ListConfigDto` line on line 30):
 ```csharp
 public record SeedResultDto(int Copied, int Skipped);
 ```
 Update the class field block. Find:
 ```csharp
    private readonly QueueService _queue;
    private readonly AgentFileService _agentService;
    private readonly HubBroadcaster _broadcaster;
    private readonly IDbContextFactory<ClaudeDoDbContext> _dbFactory;
    private readonly WorktreeMaintenanceService _wtMaintenance;
    private readonly TaskResetService _resetService;
    private readonly TaskMergeService _mergeService;
 ```
 Replace with:
 ```csharp
    private readonly QueueService _queue;
    private readonly AgentFileService _agentService;
    private readonly DefaultAgentSeeder _seeder;
    private readonly HubBroadcaster _broadcaster;
    private readonly IDbContextFactory<ClaudeDoDbContext> _dbFactory;
    private readonly WorktreeMaintenanceService _wtMaintenance;
    private readonly TaskResetService _resetService;
    private readonly TaskMergeService _mergeService;
 ```
 Update the constructor. Find:
 ```csharp
    public WorkerHub(
        QueueService queue,
        AgentFileService agentService,
        HubBroadcaster broadcaster,
        IDbContextFactory<ClaudeDoDbContext> dbFactory,
        WorktreeMaintenanceService wtMaintenance,
        TaskResetService resetService,
        TaskMergeService mergeService)
    {
        _queue = queue;
        _agentService = agentService;
        _broadcaster = broadcaster;
        _dbFactory = dbFactory;
        _wtMaintenance = wtMaintenance;
        _resetService = resetService;
        _mergeService = mergeService;
    }
 ```
 Replace with:
 ```csharp
    public WorkerHub(
        QueueService queue,
        AgentFileService agentService,
        DefaultAgentSeeder seeder,
        HubBroadcaster broadcaster,
        IDbContextFactory<ClaudeDoDbContext> dbFactory,
        WorktreeMaintenanceService wtMaintenance,
        TaskResetService resetService,
        TaskMergeService mergeService)
    {
        _queue = queue;
        _agentService = agentService;
        _seeder = seeder;
        _broadcaster = broadcaster;
        _dbFactory = dbFactory;
        _wtMaintenance = wtMaintenance;
        _resetService = resetService;
        _mergeService = mergeService;
    }
 ```
 Then add the hub method. After the existing `RefreshAgents` method (currently line 126):
 ```csharp
    public async Task<SeedResultDto> RestoreDefaultAgents()
    {
        var result = await _seeder.SeedMissingAsync();
        return new SeedResultDto(result.Copied, result.Skipped);
    }
 ```
 - [ ] **Step 4: Build worker to verify compile**
 Run: `dotnet build src/ClaudeDo.Worker/ClaudeDo.Worker.csproj`
 Expected: build succeeds.
 - [ ] **Step 5: Run all Worker tests to confirm no regressions**
 Run: `dotnet test tests/ClaudeDo.Worker.Tests`
 Expected: all tests pass.
 - [ ] **Step 6: Commit**
 ```bash
 git add src/ClaudeDo.Worker/Hub/WorkerHub.cs tests/ClaudeDo.Worker.Tests/Hub/AgentSettingsHubTests.cs
 git commit -m "feat(worker): expose RestoreDefaultAgents hub method"
 ```
 ---
 ### Task 7: Add RestoreDefaultAgentsAsync to WorkerClient
 **Files:**
 - Modify: `src/ClaudeDo.Ui/Services/WorkerClient.cs`
 - [ ] **Step 1: Add the DTO record**
 At the bottom of `src/ClaudeDo.Ui/Services/WorkerClient.cs`, alongside the other public record declarations (after `ListConfigDto`, currently line 350), add:
 ```csharp
 public sealed record SeedResultDto(int Copied, int Skipped);
 ```
 - [ ] **Step 2: Add the client method**
 In the `WorkerClient` class, after the `RefreshAgentsAsync` method (currently line 232), add:
 ```csharp
    public async Task<SeedResultDto?> RestoreDefaultAgentsAsync()
    {
        try
        {
            return await _hub.InvokeAsync<SeedResultDto>("RestoreDefaultAgents");
        }
        catch
        {
            return null;
        }
    }
 ```
 - [ ] **Step 3: Build UI to verify compile**
 Run: `dotnet build src/ClaudeDo.Ui/ClaudeDo.Ui.csproj`
 Expected: build succeeds.
 - [ ] **Step 4: Commit**
 ```bash
 git add src/ClaudeDo.Ui/Services/WorkerClient.cs
 git commit -m "feat(ui): add RestoreDefaultAgentsAsync to WorkerClient"
 ```
 ---
 ### Task 8: Add restore button to Settings modal
 **Files:**
 - Modify: `src/ClaudeDo.Ui/ViewModels/Modals/SettingsModalViewModel.cs`
 - Modify: `src/ClaudeDo.Ui/Views/Modals/SettingsModalView.axaml`
 - [ ] **Step 1: Add the command to the viewmodel**
 In `src/ClaudeDo.Ui/ViewModels/Modals/SettingsModalViewModel.cs`, add a new command method. Place it after the existing `ConfirmResetAll` method (currently ending line 162), before the `OpenPath` method:
 ```csharp
    [RelayCommand]
    private async Task RestoreDefaultAgents()
    {
        IsBusy = true;
        StatusMessage = "";
        try
        {
            var result = await _worker.RestoreDefaultAgentsAsync();
            if (result is null)
                StatusMessage = "Worker offline.";
            else if (result.Copied == 0 && result.Skipped == 0)
                StatusMessage = "No default agents bundled.";
            else if (result.Copied == 0)
                StatusMessage = "All default agents already present.";
            else
                StatusMessage = $"Restored {result.Copied} default agent(s).";
            await _worker.RefreshAgentsAsync();
        }
        catch (Exception ex)
        {
            StatusMessage = $"Restore failed: {ex.Message}";
        }
        finally { IsBusy = false; }
    }
 ```
 - [ ] **Step 2: Add a button to the settings view**
 Edit `src/ClaudeDo.Ui/Views/Modals/SettingsModalView.axaml`. Add a new section after the `WORKTREES` StackPanel block (which ends with `</StackPanel>` around line 185) and before the `ABOUT` section (`<!-- ABOUT -->` around line 187).
 Find:
 ```xml
          </StackPanel>
          <!-- ABOUT -->
 ```
 Replace with:
 ```xml
          </StackPanel>
          <!-- AGENTS -->
          <StackPanel Spacing="0">
            <TextBlock Classes="section-label" Text="AGENTS"/>
            <Border Classes="section">
              <StackPanel Spacing="8">
                <TextBlock Text="Restore bundled default agents (code-reviewer, test-writer, debugger, security-reviewer, explorer, researcher). Existing files are not overwritten."
                           FontSize="11"
                           TextWrapping="Wrap"
                           Foreground="{DynamicResource TextDimBrush}"/>
                <Button Content="Restore default agents"
                        Command="{Binding RestoreDefaultAgentsCommand}"
                        IsEnabled="{Binding !IsBusy}"
                        HorizontalAlignment="Left"/>
              </StackPanel>
            </Border>
          </StackPanel>
          <!-- ABOUT -->
 ```
 - [ ] **Step 3: Build UI to verify compile**
 Run: `dotnet build src/ClaudeDo.Ui/ClaudeDo.Ui.csproj`
 Expected: build succeeds.
 - [ ] **Step 4: Manual smoke test**
 Start the worker and the UI. Open Settings (3-dots next to username). The AGENTS section should appear with a "Restore default agents" button.
 1. With `~/.todo-app/agents/` empty (delete any existing `.md` files first, back them up if needed): click the button. Status should read "Restored N default agent(s)." The files should appear in the folder.
 2. Click again. Status should read "All default agents already present."
 3. Modify one of the restored files. Click restore. The modified file content should be preserved.
 If any step fails, stop and fix before committing.
 - [ ] **Step 5: Commit**
 ```bash
 git add src/ClaudeDo.Ui/ViewModels/Modals/SettingsModalViewModel.cs src/ClaudeDo.Ui/Views/Modals/SettingsModalView.axaml
 git commit -m "feat(ui): add Restore default agents button to Settings modal"
 ```
 ---
 ## Verification
 At the end, run the full test suite and build all projects:
 ```bash
 dotnet build src/ClaudeDo.Worker/ClaudeDo.Worker.csproj
 dotnet build src/ClaudeDo.Ui/ClaudeDo.Ui.csproj
 dotnet build src/ClaudeDo.Data/ClaudeDo.Data.csproj
 dotnet test tests/ClaudeDo.Worker.Tests
 ```
 Expected: all builds succeed, all tests pass.
 Additionally, start the Worker once with an empty `~/.todo-app/agents/` folder and confirm the log line:
 > `Default agents seeded: 6 copied, 0 already present`
 Then confirm `~/.todo-app/agents/` contains all 6 markdown files.
--- a/docs/superpowers/specs/2026-04-23-default-agents-design.md
+++ b/docs/superpowers/specs/2026-04-23-default-agents-design.md
@@ -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.