@@ -0,0 +1,598 @@
1+# Swarm Auto-Start and Provider Selection Implementation Plan
2+
3+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
4+
5+**Goal:** Add `--start-swarm` CLI flag and interactive provider/model selection when creating myses.
6+
7+**Architecture:** Add config defaults for provider/model, add CLI flag to auto-start idle myses, modify TUI input flow to prompt for provider/model with defaults.
8+
9+**Tech Stack:** Go 1.22, Cobra CLI, Bubble Tea TUI, TOML config
10+
11+---
12+
13+## Phase 1: Add Default Provider/Model to Config
14+
15+**Files:**
16+- Modify: `internal/config/config.go`
17+- Modify: `config.toml`
18+- Test: `internal/config/config_test.go`
19+
20+**Step 1: Update config struct**
21+
22+Add default provider/model fields to `Config` struct in `internal/config/config.go` (around line 15):
23+
24+```go
25+type Config struct {
26+ Swarm SwarmConfig `toml:"swarm"`
27+ Providers map[string]ProviderConfig `toml:"providers"`
28+ MCP MCPConfig `toml:"mcp"`
29+}
30+
31+type SwarmConfig struct {
32+ MaxMyses int `toml:"max_myses"`
33+ DefaultProvider string `toml:"default_provider"`
34+ DefaultModel string `toml:"default_model"`
35+}
36+```
37+
38+**Step 2: Update defaults**
39+
40+Modify `DefaultConfig()` function (around line 43) to include swarm defaults:
41+
42+```go
43+func DefaultConfig() *Config {
44+ return &Config{
45+ Swarm: SwarmConfig{
46+ MaxMyses: 16,
47+ DefaultProvider: "opencode_zen",
48+ DefaultModel: "gpt-5-nano",
49+ },
50+ Providers: map[string]ProviderConfig{
51+ // ... existing providers
52+ },
53+ // ... rest
54+ }
55+}
56+```
57+
58+**Step 3: Update config.toml**
59+
60+Modify `config.toml` (line 1-2):
61+
62+```toml
63+[swarm]
64+max_myses = 16
65+default_provider = "opencode_zen"
66+default_model = "gpt-5-nano"
67+```
68+
69+**Step 4: Write test**
70+
71+Add test to `internal/config/config_test.go`:
72+
73+```go
74+func TestLoadDefaultProviderModel(t *testing.T) {
75+ configContent := `
76+[swarm]
77+max_myses = 16
78+default_provider = "ollama"
79+default_model = "qwen3:8b"
80+
81+[providers.ollama]
82+endpoint = "http://localhost:11434"
83+model = "qwen3:8b"
84+`
85+ tmpFile := createTempConfig(t, configContent)
86+ defer os.Remove(tmpFile)
87+
88+ cfg, err := Load(tmpFile)
89+ if err != nil {
90+ t.Fatalf("Load failed: %v", err)
91+ }
92+
93+ if cfg.Swarm.DefaultProvider != "ollama" {
94+ t.Errorf("expected default_provider=ollama, got %s", cfg.Swarm.DefaultProvider)
95+ }
96+
97+ if cfg.Swarm.DefaultModel != "qwen3:8b" {
98+ t.Errorf("expected default_model=qwen3:8b, got %s", cfg.Swarm.DefaultModel)
99+ }
100+}
101+```
102+
103+**Step 5: Run test**
104+
105+```bash
106+go test ./internal/config -run TestLoadDefaultProviderModel -v
107+```
108+
109+Expected: PASS
110+
111+**Step 6: Build and verify**
112+
113+```bash
114+go build ./cmd/zoea
115+```
116+
117+Expected: SUCCESS
118+
119+**Step 7: Commit**
120+
121+```bash
122+git add internal/config/config.go internal/config/config_test.go config.toml
123+git commit -m "feat: add default provider/model to swarm config
124+
125+- Add DefaultProvider and DefaultModel to SwarmConfig
126+- Update config.toml with defaults (opencode_zen/gpt-5-nano)
127+- Add test for loading default provider/model"
128+```
129+
130+---
131+
132+## Phase 2: Add --start-swarm CLI Flag
133+
134+**Files:**
135+- Modify: `cmd/zoea/main.go`
136+- Test: Manual (CLI flag testing)
137+
138+**Step 1: Add flag definition**
139+
140+Modify `cmd/zoea/main.go` (around line 20-30) to add flag:
141+
142+```go
143+var (
144+ configPath string
145+ debugMode bool
146+ offlineMode bool
147+ startSwarm bool // New flag
148+)
149+
150+func init() {
151+ rootCmd.PersistentFlags().StringVar(&configPath, "config", "", "path to config file")
152+ rootCmd.PersistentFlags().BoolVar(&debugMode, "debug", false, "enable debug logging")
153+ rootCmd.PersistentFlags().BoolVar(&offlineMode, "offline", false, "run in offline mode (stub MCP server)")
154+ rootCmd.PersistentFlags().BoolVar(&startSwarm, "start-swarm", false, "auto-start all idle myses on launch")
155+}
156+```
157+
158+**Step 2: Pass flag to TUI**
159+
160+Modify the `run` function (around line 80-100) to pass flag to TUI:
161+
162+```go
163+func run(cmd *cobra.Command, args []string) error {
164+ // ... existing setup code ...
165+
166+ // Create TUI
167+ tuiApp := tui.New(commander, st, eventBus, startSwarm)
168+
169+ // ... rest of setup
170+}
171+```
172+
173+**Step 3: Update TUI constructor**
174+
175+Modify `internal/tui/app.go` TUI struct and constructor (around line 40-60):
176+
177+```go
178+type Model struct {
179+ // ... existing fields ...
180+ startSwarm bool // New field
181+}
182+
183+func New(commander *core.Commander, store *store.Store, events <-chan core.Event, startSwarm bool) *tea.Program {
184+ m := &Model{
185+ commander: commander,
186+ store: store,
187+ events: events,
188+ startSwarm: startSwarm,
189+ // ... rest
190+ }
191+ return tea.NewProgram(m, tea.WithAltScreen())
192+}
193+```
194+
195+**Step 4: Implement auto-start logic**
196+
197+Add auto-start in `Init()` method of `internal/tui/app.go` (around line 120):
198+
199+```go
200+func (m *Model) Init() tea.Cmd {
201+ // Auto-start idle myses if flag enabled
202+ if m.startSwarm {
203+ go m.autoStartIdleMyses()
204+ }
205+
206+ return tea.Batch(
207+ listenForEvents(m.events),
208+ tea.EnterAltScreen,
209+ )
210+}
211+
212+// autoStartIdleMyses starts all myses in idle state
213+func (m *Model) autoStartIdleMyses() {
214+ myses := m.commander.ListMyses()
215+ for _, mysis := range myses {
216+ if mysis.LastError == nil { // Check state is idle
217+ _ = m.commander.StartMysis(mysis.ID)
218+ }
219+ }
220+}
221+```
222+
223+**Step 5: Test manually**
224+
225+```bash
226+# Build
227+go build ./cmd/zoea
228+
229+# Test without flag (should not auto-start)
230+./zoea
231+
232+# Test with flag (should auto-start idle myses)
233+./zoea --start-swarm
234+```
235+
236+**Step 6: Commit**
237+
238+```bash
239+git add cmd/zoea/main.go internal/tui/app.go
240+git commit -m "feat: add --start-swarm CLI flag
241+
242+Auto-starts all idle myses on application launch when enabled.
243+Default: disabled (opt-in behavior)"
244+```
245+
246+---
247+
248+## Phase 3: Interactive Provider/Model Selection in TUI
249+
250+**Files:**
251+- Modify: `internal/tui/app.go`
252+- Test: Manual (TUI interaction)
253+
254+**Step 1: Add input stages enum**
255+
256+Add to `internal/tui/app.go` (around line 20):
257+
258+```go
259+// Input stages for multi-step mysis creation
260+type InputStage int
261+
262+const (
263+ InputStageName InputStage = iota
264+ InputStageProvider
265+ InputStageModel
266+)
267+```
268+
269+**Step 2: Update Model struct**
270+
271+Modify Model struct (around line 40):
272+
273+```go
274+type Model struct {
275+ // ... existing fields ...
276+
277+ // Multi-stage input for mysis creation
278+ inputStage InputStage
279+ pendingMysisName string
280+ pendingMysisProvider string
281+}
282+```
283+
284+**Step 3: Modify input prompt text**
285+
286+Update `Update()` method to show appropriate prompt based on stage (around line 200-250):
287+
288+```go
289+func (m *Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
290+ switch msg := msg.(type) {
291+ case tea.KeyMsg:
292+ switch m.inputMode {
293+ case InputModeNewMysis:
294+ if msg.Type == tea.KeyEnter {
295+ value := strings.TrimSpace(m.textInput.Value())
296+
297+ switch m.inputStage {
298+ case InputStageName:
299+ // Name is required
300+ if value == "" {
301+ m.err = fmt.Errorf("name cannot be empty")
302+ return m, nil
303+ }
304+ m.pendingMysisName = value
305+ m.inputStage = InputStageProvider
306+ m.textInput.SetValue("")
307+ m.textInput.Placeholder = "Provider (empty for default: " + m.config.Swarm.DefaultProvider + ")"
308+ return m, nil
309+
310+ case InputStageProvider:
311+ m.pendingMysisProvider = value
312+
313+ // If provider is empty, use defaults and create
314+ if value == "" {
315+ mysis, err := m.commander.CreateMysis(
316+ m.pendingMysisName,
317+ m.config.Swarm.DefaultProvider,
318+ )
319+ if err == nil {
320+ m.err = m.commander.StartMysis(mysis.ID())
321+ } else {
322+ m.err = err
323+ }
324+ m.resetInput()
325+ m.refreshMysisList()
326+ return m, nil
327+ }
328+
329+ // Provider chosen, ask for model
330+ m.inputStage = InputStageModel
331+ m.textInput.SetValue("")
332+
333+ // Get model from config for this provider
334+ defaultModel := ""
335+ if providerCfg, ok := m.config.Providers[value]; ok {
336+ defaultModel = providerCfg.Model
337+ }
338+ m.textInput.Placeholder = "Model (default: " + defaultModel + ")"
339+ return m, nil
340+
341+ case InputStageModel:
342+ // Model is required when provider was chosen
343+ if value == "" {
344+ m.err = fmt.Errorf("model required when provider is specified")
345+ return m, nil
346+ }
347+
348+ mysis, err := m.commander.CreateMysis(
349+ m.pendingMysisName,
350+ m.pendingMysisProvider,
351+ )
352+ if err == nil {
353+ // Update model (CreateMysis uses provider's default model)
354+ // Need to add UpdateMysisModel method or pass model to CreateMysis
355+ m.err = m.commander.StartMysis(mysis.ID())
356+ } else {
357+ m.err = err
358+ }
359+ m.resetInput()
360+ m.refreshMysisList()
361+ return m, nil
362+ }
363+ } else if msg.Type == tea.KeyEsc {
364+ m.resetInput()
365+ return m, nil
366+ }
367+ // ... rest of key handlers
368+ }
369+ // ... rest of message handlers
370+ }
371+
372+ // Update text input
373+ m.textInput, cmd = m.textInput.Update(msg)
374+ return m, cmd
375+}
376+```
377+
378+**Step 4: Add resetInput helper**
379+
380+Add helper method to reset input state (around line 600):
381+
382+```go
383+func (m *Model) resetInput() {
384+ m.inputMode = InputModeNormal
385+ m.inputStage = InputStageName
386+ m.pendingMysisName = ""
387+ m.pendingMysisProvider = ""
388+ m.textInput.SetValue("")
389+ m.textInput.Blur()
390+}
391+```
392+
393+**Step 5: Update View to show current stage**
394+
395+Modify `View()` method to show which stage user is on (around line 400-450):
396+
397+```go
398+func (m *Model) View() string {
399+ // ... existing view code ...
400+
401+ if m.inputMode == InputModeNewMysis {
402+ stageLabel := ""
403+ switch m.inputStage {
404+ case InputStageName:
405+ stageLabel = "Name"
406+ case InputStageProvider:
407+ stageLabel = "Provider (1/2)"
408+ case InputStageModel:
409+ stageLabel = "Model (2/2)"
410+ }
411+ footer := fmt.Sprintf("[%s] %s", stageLabel, m.textInput.View())
412+ // ... render footer
413+ }
414+
415+ // ... rest of view
416+}
417+```
418+
419+**Step 6: Store config in Model**
420+
421+Modify Model initialization to store config (around line 70):
422+
423+```go
424+func New(commander *core.Commander, store *store.Store, events <-chan core.Event, startSwarm bool) *tea.Program {
425+ // Load config
426+ cfg, err := config.Load("") // Use default path resolution
427+ if err != nil {
428+ // Use defaults if load fails
429+ cfg = config.DefaultConfig()
430+ }
431+
432+ m := &Model{
433+ commander: commander,
434+ store: store,
435+ events: events,
436+ startSwarm: startSwarm,
437+ config: cfg,
438+ inputStage: InputStageName,
439+ // ... rest
440+ }
441+ return tea.NewProgram(m, tea.WithAltScreen())
442+}
443+```
444+
445+**Step 7: Add config field to Model**
446+
447+```go
448+type Model struct {
449+ // ... existing fields ...
450+ config *config.Config
451+}
452+```
453+
454+**Step 8: Handle model parameter in CreateMysis**
455+
456+Note: `CreateMysis` currently doesn't accept a model parameter. It uses the provider's default model from config. This is actually correct behavior - the provider config already specifies the model.
457+
458+**Simplify Step 3:** Remove model input stage since provider selection already determines the model from config.
459+
460+**Revised Step 3 (simpler):**
461+
462+```go
463+case InputStageProvider:
464+ m.pendingMysisProvider = value
465+
466+ // If provider is empty, use defaults
467+ provider := value
468+ if provider == "" {
469+ provider = m.config.Swarm.DefaultProvider
470+ }
471+
472+ // Validate provider exists
473+ if _, ok := m.config.Providers[provider]; !ok {
474+ m.err = fmt.Errorf("provider '%s' not found in config", provider)
475+ m.resetInput()
476+ return m, nil
477+ }
478+
479+ // Create mysis with selected provider
480+ mysis, err := m.commander.CreateMysis(m.pendingMysisName, provider)
481+ if err == nil {
482+ m.err = m.commander.StartMysis(mysis.ID())
483+ } else {
484+ m.err = err
485+ }
486+ m.resetInput()
487+ m.refreshMysisList()
488+ return m, nil
489+```
490+
491+**Remove InputStageModel** - not needed since provider determines model.
492+
493+**Step 9: Test manually**
494+
495+```bash
496+go build ./cmd/zoea
497+./zoea
498+
499+# Test flow:
500+# 1. Press 'n'
501+# 2. Enter name: "test"
502+# 3. Press Enter
503+# 4. Enter provider: "" (empty for default)
504+# 5. Verify mysis created with opencode_zen/gpt-5-nano
505+
506+# Test custom provider:
507+# 1. Press 'n'
508+# 2. Enter name: "test2"
509+# 3. Press Enter
510+# 4. Enter provider: "ollama-llama"
511+# 5. Verify mysis created with ollama/llama3.1:8b
512+```
513+
514+**Step 10: Commit**
515+
516+```bash
517+git add internal/tui/app.go
518+git commit -m "feat: add interactive provider selection for new myses
519+
520+Multi-stage input flow:
521+1. Name (required)
522+2. Provider (optional, defaults to config default)
523+
524+Provider selection determines model from config.
525+Empty provider uses swarm.default_provider."
526+```
527+
528+---
529+
530+## Phase 4: Update Documentation
531+
532+**Files:**
533+- Modify: `README.md`
534+
535+**Step 1: Add CLI flag documentation**
536+
537+Add to README.md CLI section:
538+
539+```markdown
540+## CLI Flags
541+
542+- `--config <path>` - Path to config file (default: `./config.toml` or `~/.zoea-nova/config.toml`)
543+- `--debug` - Enable debug logging
544+- `--offline` - Run in offline mode (stub MCP server)
545+- `--start-swarm` - Auto-start all idle myses on launch (default: disabled)
546+```
547+
548+**Step 2: Document provider selection flow**
549+
550+Add to README.md:
551+
552+```markdown
553+## Creating a Mysis
554+
555+Press `n` to create a new mysis. You'll be prompted for:
556+
557+1. **Name** (required) - Unique identifier for the mysis
558+2. **Provider** (optional) - Leave empty to use default from config, or specify:
559+ - `ollama` - Local Ollama with qwen3:8b
560+ - `ollama-llama` - Local Ollama with llama3.1:8b
561+ - `opencode_zen` - OpenCode Zen with gpt-5-nano
562+ - `zen-pickle` - OpenCode Zen with big-pickle
563+
564+The model is determined by the provider's configuration in `config.toml`.
565+```
566+
567+**Step 3: Commit**
568+
569+```bash
570+git add README.md
571+git commit -m "docs: document --start-swarm flag and provider selection"
572+```
573+
574+---
575+
576+## Testing Checklist
577+
578+- [ ] Config loads default provider/model correctly
579+- [ ] `--start-swarm` flag starts idle myses on launch
580+- [ ] Creating mysis with empty provider uses defaults
581+- [ ] Creating mysis with specified provider uses that provider's model
582+- [ ] Invalid provider name shows error
583+- [ ] ESC key cancels mysis creation at any stage
584+- [ ] All existing myses still work after changes
585+
586+---
587+
588+## Success Criteria
589+
590+1. `--start-swarm` flag auto-starts idle myses on launch
591+2. Config has `default_provider` and `default_model` fields
592+3. New mysis flow prompts for name and provider
593+4. Empty provider uses config defaults
594+5. Specified provider uses that provider's configured model
595+6. Documentation updated
596+
597+---
598+