@sashabogi/foundation 0.1.10 → 0.1.11

package/docs/REFACTORING-PLAN.md

@@ -0,0 +1,374 @@
+# 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

package/docs/TESTING-WITH-NATIVE-SWARM.md

@@ -0,0 +1,266 @@
+# Testing Foundation with Native Swarm (claudesp)
+
+## Overview
+
+This guide explains how to test Foundation's multi-provider routing alongside Claude Code's native swarm features.
+
+---
+
+## Prerequisites
+
+### 1. claudesp (Native Swarm Enabled)
+
+```bash
+# Already installed at:
+/Users/sashabogojevic/.local/bin/claudesp
+
+# Verify
+claudesp --version
+# Expected: 2.1.22 (Claude Code)
+```
+
+### 2. Foundation MCP Server
+
+```bash
+cd /Users/sashabogojevic/development/foundation/foundation
+npm install
+npm run build
+```
+
+### 3. Provider API Keys
+
+Ensure these are set in `~/.foundation/config.yaml` or environment:
+- `ANTHROPIC_API_KEY`
+- `OPENAI_API_KEY` (optional)
+- `DEEPSEEK_API_KEY` (optional)
+- `KIMI_API_KEY` (optional)
+- `ZAI_API_KEY` (optional)
+
+---
+
+## Setup: Connect Foundation to claudesp
+
+### Option A: MCP Config File
+
+Create/edit `~/.claude-sneakpeek/claudesp/config/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "foundation": {
+      "command": "node",
+      "args": ["/Users/sashabogojevic/development/foundation/foundation/dist/index.js"],
+      "env": {
+        "ANTHROPIC_API_KEY": "${ANTHROPIC_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+### Option B: CLI Flag
+
+```bash
+claudesp --dangerously-skip-permissions --mcp-config /path/to/mcp-config.json
+```
+
+Where `mcp-config.json`:
+```json
+{
+  "mcpServers": {
+    "foundation": {
+      "command": "node",
+      "args": ["/Users/sashabogojevic/development/foundation/foundation/dist/index.js"]
+    }
+  }
+}
+```
+
+---
+
+## Test Scenarios
+
+### Test 1: Verify Foundation Tools Available
+
+```
+List all MCP tools available. Show any that start with "demerzel", "seldon", or "gaia".
+```
+
+**Expected:** 41 tools listed (before refactoring) or 23 tools (after)
+
+---
+
+### Test 2: Multi-Provider Routing (Foundation Core Value)
+
+```
+Use seldon_invoke with role "coder" and prompt "Write a Python function to calculate fibonacci numbers"
+```
+
+**Expected:**
+- Routes to configured coder provider (Kimi, DeepSeek, etc.)
+- Returns generated code
+- NOT using Claude (uses external provider)
+
+---
+
+### Test 3: Provider Comparison
+
+```
+Use seldon_compare to run "Write a hello world in Rust" through both the "coder" and "reviewer" roles
+```
+
+**Expected:**
+- Two different responses
+- Different providers used for each role
+
+---
+
+### Test 4: Native Swarm Team Creation
+
+```
+Use the Teammate tool to create a team called "foundation-test"
+```
+
+**Expected:**
+- Team created
+- You become team leader
+
+---
+
+### Test 5: Hybrid Workflow (Native + Foundation)
+
+This is the key test for the integrated architecture:
+
+```
+1. Create a team called "hybrid-test" using Teammate tool
+2. Use seldon_invoke with role "coder" to generate a Python script
+3. Use native SendMessage to broadcast the result to the team
+4. Create a task using TaskCreate for review
+```
+
+**Expected:**
+- Native swarm handles team/messaging
+- Foundation handles multi-provider routing
+- Both work together seamlessly
+
+---
+
+### Test 6: Verification Loop (Foundation Unique)
+
+```
+1. Use seldon_invoke role "coder" to write a function with this spec:
+   "Function that validates email addresses using regex"
+
+2. Use seldon_verify to check if it handles:
+   - Empty strings
+   - Missing @ symbol
+   - Invalid TLD
+
+3. Use seldon_fix if any issues found
+```
+
+**Expected:**
+- Code generated via external provider
+- Verification identifies gaps
+- Fix generates improvements
+
+---
+
+### Test 7: Demerzel Codebase Intelligence
+
+```
+1. Use demerzel_snapshot to create a snapshot of /Users/sashabogojevic/development/foundation/foundation
+2. Use demerzel_search to find "ProviderManager"
+3. Use demerzel_find_importers to see what uses ProviderManager
+```
+
+**Expected:**
+- Snapshot created
+- Search finds provider manager
+- Import graph shows dependencies
+
+---
+
+### Test 8: Gaia Learning (Post-Refactor)
+
+```
+1. Use gaia_learn to record: "Always use TypeScript strict mode"
+2. Use gaia_review to see accumulated learnings
+3. Use gaia_apply to write to CLAUDE.md
+```
+
+**Expected:**
+- Learning recorded
+- Can review learnings
+- Applied to CLAUDE.md
+
+---
+
+## Debugging
+
+### Check MCP Connection
+
+```bash
+# In claudesp, run:
+/mcp
+```
+
+Should show Foundation server connected.
+
+### Check Foundation Logs
+
+```bash
+# Run Foundation with debug logging:
+DEBUG=foundation:* node /Users/sashabogojevic/development/foundation/foundation/dist/index.js
+```
+
+### Check Provider Health
+
+```
+Use seldon_providers_list to see all providers and their health status
+```
+
+---
+
+## Common Issues
+
+### "Tool not found: seldon_invoke"
+
+Foundation MCP server not connected. Check:
+1. MCP config path is correct
+2. Foundation is built (`npm run build`)
+3. Node can execute the dist/index.js
+
+### "Provider error: 401"
+
+API key not set. Check:
+1. Environment variables
+2. `~/.foundation/config.yaml`
+
+### "Native swarm tools not available"
+
+Using regular `claude` instead of `claudesp`. The native swarm tools (Teammate, SendMessage) only appear in the patched version.
+
+---
+
+## Next Steps After Testing
+
+1. If all tests pass → Proceed with refactoring
+2. If Foundation tests fail → Debug MCP connection
+3. If hybrid tests fail → Check tool naming conflicts
+4. Document any issues in GitHub
+
+---
+
+## Test Results Log
+
+| Test | Date | Result | Notes |
+|------|------|--------|-------|
+| 1. Foundation tools | | | |
+| 2. Multi-provider | | | |
+| 3. Provider compare | | | |
+| 4. Native team | | | |
+| 5. Hybrid workflow | | | |
+| 6. Verification loop | | | |
+| 7. Demerzel | | | |
+| 8. Gaia learning | | | |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sashabogi/foundation",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "Unified MCP server for AI-assisted development: codebase intelligence, multi-agent orchestration, and workflow patterns",
   "type": "module",
   "main": "dist/index.js",