# Foundation Refactoring Plan: Native Swarm Integration

**Date:** February 1, 2026
**Branch:** `feature/native-swarm-integration`
**Status:** Planning

---

## Executive Summary

Claude Code has native multi-agent orchestration (swarm mode) behind a feature flag. This changes Foundation's role from "full orchestration stack" to "multi-provider routing layer." This plan documents what to keep, remove, and modify.

---

## Context

### Native Swarm Capabilities (confirmed working)

| Tool | Operations | What It Does |
|------|------------|--------------|
| **Teammate** | 6 ops | Team creation, discovery, join/approve workflow |
| **SendMessage** | 4 ops | Direct messages, broadcasts, protocol requests |
| **Task*** | 4 tools | Shared task list across teammates |
| **ExitPlanMode** | Extended | `launchSwarm`, `teammateCount` parameters |

### What Native Swarm Does NOT Have

- Multi-provider support (Claude only)
- Role-based routing (coder → Kimi, designer → Gemini)
- Provider failover and health tracking
- Verification loops (verify → fix → re-verify)
- Codebase intelligence (Demerzel)
- Self-learning CLAUDE.md (Gaia learning)

---

## Refactoring Strategy

### Principle: Foundation = Provider Layer, Native = Orchestration Layer

```
┌─────────────────────────────────────────────────────────────┐
│              CLAUDE CODE (with native swarm)                 │
│  • Teammate tool (team management)                           │
│  • SendMessage tool (inter-agent communication)              │
│  • Task* tools (shared task list)                            │
│  • Worktree management (built-in)                            │
└──────────────────────────┬──────────────────────────────────┘
                           │ MCP Connection
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                 FOUNDATION (Refactored)                      │
│                                                              │
│  DEMERZEL (unchanged)     SELDON (simplified)    GAIA       │
│  ├─ snapshot              ├─ invoke             (learning   │
│  ├─ search                ├─ compare             only)      │
│  ├─ find_files            ├─ verify             ├─ learn    │
│  ├─ find_symbol           ├─ fix                ├─ apply    │
│  ├─ find_importers        ├─ execute_verified   ├─ review   │
│  ├─ get_deps              ├─ providers_list     ├─ remember │
│  ├─ get_context           └─ providers_test     └─ recall   │
│  ├─ analyze                                                  │
│  └─ semantic_search                                          │
│                                                              │
│  REMOVED:                                                    │
│  ✗ gaia_worktree_* (use native)                             │
│  ✗ gaia_session_* (use native Teammate)                     │
│  ✗ seldon_task_* (use native Task*)                         │
│  ✗ seldon_phase_* (use native launchSwarm)                  │
│  ✗ seldon_pipeline_* (simplify to invoke/verify)            │
└─────────────────────────────────────────────────────────────┘
```

---

## Detailed Changes

### DEMERZEL Module (9 tools) — NO CHANGES

All Demerzel tools remain unchanged. Native swarm has no codebase intelligence.

| Tool | Status | Reason |
|------|--------|--------|
| `demerzel_snapshot` | ✅ Keep | Unique value |
| `demerzel_search` | ✅ Keep | Unique value |
| `demerzel_find_files` | ✅ Keep | Unique value |
| `demerzel_find_symbol` | ✅ Keep | Unique value |
| `demerzel_find_importers` | ✅ Keep | Unique value |
| `demerzel_get_deps` | ✅ Keep | Unique value |
| `demerzel_get_context` | ✅ Keep | Unique value |
| `demerzel_analyze` | ✅ Keep | Unique value |
| `demerzel_semantic_search` | ✅ Keep | Unique value |

---

### SELDON Module (19 → 7 tools) — MAJOR SIMPLIFICATION

#### Keep (7 tools)

| Tool | Reason |
|------|--------|
| `seldon_invoke` | Core multi-provider routing |
| `seldon_compare` | Run task through multiple providers |
| `seldon_critique` | Convenience wrapper for critic role |
| `seldon_review` | Convenience wrapper for reviewer role |
| `seldon_verify` | Verification against plan (unique) |
| `seldon_fix` | Generate fixes for issues (unique) |
| `seldon_execute_verified` | Verify/fix loop (unique) |
| `seldon_providers_list` | Provider health visibility |
| `seldon_providers_test` | Provider connectivity check |

#### Remove (12 tools)

| Tool | Reason | Native Replacement |
|------|--------|-------------------|
| `seldon_plan` | Use Claude's native planning | `EnterPlanMode` |
| `seldon_phase_create` | Use native swarm | `ExitPlanMode({ launchSwarm })` |
| `seldon_phase_list` | Use native swarm | `TaskList` |
| `seldon_execute_parallel` | Use native swarm | `launchSwarm` + `teammateCount` |
| `seldon_pipeline_create` | Over-engineered | Remove |
| `seldon_pipeline_execute` | Over-engineered | Remove |
| `seldon_pipeline_status` | Over-engineered | Remove |
| `seldon_task_execute` | Use native | `Task` with `team_name` |
| `seldon_task_claim` | Use native | `TaskUpdate` with owner |
| `seldon_design` | Rarely used | Keep `seldon_invoke` with role |

---

### GAIA Module (13 → 5 tools) — MAJOR SIMPLIFICATION

#### Keep (5 tools)

| Tool | Reason |
|------|--------|
| `gaia_learn` | Self-learning CLAUDE.md (unique) |
| `gaia_apply` | Write learnings (unique) |
| `gaia_review` | Review learnings (unique) |
| `gaia_remember` | Context snapshots (useful) |
| `gaia_recall` | Restore context (useful) |

#### Remove (8 tools)

| Tool | Reason | Native Replacement |
|------|--------|-------------------|
| `gaia_worktree_create` | Native has worktrees | Native swarm worktrees |
| `gaia_worktree_list` | Native has worktrees | Native swarm |
| `gaia_worktree_switch` | Native has worktrees | Native swarm |
| `gaia_worktree_cleanup` | Native has worktrees | `Teammate({ operation: "cleanup" })` |
| `gaia_session_register` | Native has teams | `Teammate({ operation: "spawnTeam" })` |
| `gaia_session_status` | Native has teams | `Teammate({ operation: "discoverTeams" })` |
| `gaia_session_handoff` | Simplify | Can be done manually |
| `gaia_session_complete` | Native has teams | `Teammate({ operation: "cleanup" })` |

---

## Tool Count Summary

| Module | Before | After | Removed |
|--------|--------|-------|---------|
| Demerzel | 9 | 9 | 0 |
| Seldon | 19 | 9 | 10 |
| Gaia | 13 | 5 | 8 |
| **Total** | **41** | **23** | **18** |

**44% reduction in tool count** while maintaining core value.

---

## Services Changes

### Keep Unchanged
- `ConfigService` — Still needed for provider config
- `ProviderService` — Core value, multi-provider routing
- `StorageService` — Still needed for learnings, provider health

### Simplify
- `GitService` — Remove worktree functions, keep only diff/branch utilities

### Remove
- Worktree state management in StorageService
- Session state management in StorageService

---

## Configuration Simplification

### Before (`~/.foundation/config.yaml`)

```yaml
version: "1.0"

providers:
  anthropic: { ... }
  openai: { ... }
  deepseek: { ... }
  kimi: { ... }
  zai: { ... }

roles:
  orchestrator: { provider: anthropic, model: claude-sonnet-4 }
  coder: { provider: kimi, model: kimi-2.5, fallback_chain: [...] }
  critic: { provider: deepseek, model: deepseek-reasoner }
  reviewer: { provider: openai, model: gpt-4o }
  designer: { provider: google, model: gemini-2.5-pro }

demerzel: { ... }

# REMOVE THESE:
worktrees:
  base_dir: .foundation/worktrees
  max_count: 10

sessions:
  auto_handoff: true
```

### After

```yaml
version: "2.0"

providers:
  anthropic: { ... }
  openai: { ... }
  deepseek: { ... }
  kimi: { ... }
  zai: { ... }

roles:
  orchestrator: { provider: anthropic, model: claude-sonnet-4 }
  coder: { provider: kimi, model: kimi-2.5, fallback_chain: [...] }
  critic: { provider: deepseek, model: deepseek-reasoner }
  reviewer: { provider: openai, model: gpt-4o }

demerzel:
  provider: ollama
  model: qwen2.5-coder:7b

learning:
  auto_apply: false
  target_file: CLAUDE.md
```

---

## Migration Path

### Phase 1: Create Branch & Scaffold (Day 1)
1. Create `feature/native-swarm-integration` branch
2. Update package.json version to 0.2.0-alpha
3. Create feature flag for gradual rollout

### Phase 2: Remove Gaia Session/Worktree Tools (Day 1-2)
1. Remove 8 Gaia tools
2. Update Gaia index.ts
3. Remove worktree state from StorageService
4. Remove session state from StorageService
5. Update tests

### Phase 3: Simplify Seldon (Day 2-3)
1. Remove 10 Seldon tools
2. Keep verification loop intact
3. Update Seldon index.ts
4. Update tests

### Phase 4: Update Configuration (Day 3)
1. Bump config version to 2.0
2. Remove worktree/session config sections
3. Add migration script for existing configs

### Phase 5: Documentation & Testing (Day 4)
1. Update README
2. Update USER-GUIDE
3. Test with claudesp (native swarm)
4. Test with regular Claude Code (fallback mode)

### Phase 6: Ludicrous Ralphy Integration (Day 5+)
1. Remove AgentRouter from LR
2. Remove old Hari Seldon from LR
3. Add Foundation MCP connection
4. Test full flow: LR Dashboard → Foundation → Providers

---

## Testing Strategy

### Test Environment

```bash
# Terminal 1: Foundation MCP server
cd /Users/sashabogojevic/development/foundation/foundation
npm run dev

# Terminal 2: Claude Code with native swarm + Foundation
claudesp --dangerously-skip-permissions --mcp-config ~/.claude/mcp.json
```

### Test Cases

#### 1. Multi-Provider Routing (Foundation)
```
Use seldon_invoke with role "coder" to write a Python function
```
Expected: Routes to Kimi/GLM per config

#### 2. Native Swarm Team Creation
```
Use Teammate tool to create a team called "test-team"
```
Expected: Team created, can spawn workers

#### 3. Hybrid Flow (Foundation + Native)
```
1. Create a team with Teammate
2. Use seldon_invoke to get code from Kimi
3. Use SendMessage to coordinate
```
Expected: Best of both worlds

#### 4. Verification Loop (Foundation)
```
1. seldon_invoke: Generate code with coder role
2. seldon_verify: Check against requirements
3. seldon_fix: Fix any issues
```
Expected: Verify/fix loop works

---

## Rollback Plan

If native swarm is disabled or changes:

1. Foundation maintains full functionality independently
2. Feature flag allows reverting to full tool set
3. Config version 1.0 still supported

---

## Success Criteria

1. **Tool count reduced** from 41 to 23 (44% reduction)
2. **Multi-provider routing works** with Kimi, GLM, DeepSeek, etc.
3. **Native swarm integration** works for team/task management
4. **Verification loop** remains functional
5. **Ludicrous Ralphy** can use Foundation as sole backend

---

## Open Questions

1. Should we keep `seldon_plan` as convenience even though native has planning?
2. Should `gaia_remember/recall` be moved to Demerzel (context = codebase)?
3. Do we need a "compatibility mode" for non-swarm Claude Code users?

---

## Appendix: Native Swarm API Reference

See: `/Users/sashabogojevic/development/claude-native-swarm-analysis/CONFIRMED-API.md`

### Teammate Tool
- `spawnTeam` — Create team (become leader)
- `discoverTeams` — Find available teams
- `requestJoin` — Request to join team
- `approveJoin` — Approve join (leader)
- `rejectJoin` — Reject join (leader)
- `cleanup` — Remove team files

### SendMessage Tool
- `message` — Direct message to teammate
- `broadcast` — Message all teammates
- `request` — Protocol request (shutdown, plan_approval)
- `response` — Respond to request
