@sashabogi/foundation 0.1.0 → 0.1.1

package/docs/PRD.md

@@ -0,0 +1,255 @@
+# Foundation MCP Server - Product Requirements Document
+
+## Executive Summary
+
+**Foundation** is a unified MCP server that consolidates three specialized tools into a single, cohesive platform for AI-assisted development, themed around Asimov's Foundation universe:
+
+1. **Demerzel** - Codebase intelligence beyond context limits (R. Daneel Olivaw)
+2. **Seldon** - Multi-agent orchestration with provider routing (Hari Seldon)
+3. **Gaia** - Session management and collective learning (The Collective Consciousness)
+
+The result is a comprehensive toolkit that any Claude Code user (CLI or GUI) can leverage, while visual frontends like Ludicrous Ralphy become thin clients that consume Foundation's capabilities via MCP.
+
+---
+
+## Problem Statement
+
+Currently, developers using Claude Code must:
+- Install and configure 3+ separate MCP servers
+- Deal with overlapping functionality (worktrees in 2 places, reviews in 2 places)
+- Manage separate configuration files for each tool
+- Hope that tools don't conflict with each other
+
+Ludicrous Ralphy has internal implementations (ArgusManager, AgentRouter) that duplicate MCP server functionality, creating maintenance burden and feature drift.
+
+---
+
+## Solution
+
+**One MCP server. One configuration. Complete AI development toolkit.**
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                         FOUNDATION                                │
+│                                                                   │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐               │
+│  │  DEMERZEL   │  │   SELDON    │  │    GAIA     │               │
+│  │ (Codebase)  │  │  (Agents)   │  │ (Workflow)  │               │
+│  └─────────────┘  └─────────────┘  └─────────────┘               │
+│         │                │                │                       │
+│         └────────────────┼────────────────┘                       │
+│                          ▼                                        │
+│  ┌──────────────────────────────────────────────────────────┐    │
+│  │                    SHARED SERVICES                        │    │
+│  │  • StorageService (unified JSON persistence)              │    │
+│  │  • GitService (worktrees, branches, diffs)                │    │
+│  │  • ProviderService (13+ AI providers with failover)       │    │
+│  │  • ConfigService (single ~/.foundation/config.yaml)       │    │
+│  └──────────────────────────────────────────────────────────┘    │
+│                          │                                        │
+│                          ▼                                        │
+│                    MCP STDIO TRANSPORT                            │
+└──────────────────────────────────────────────────────────────────┘
+                           │
+            ┌──────────────┼──────────────┐
+            ▼              ▼              ▼
+      Claude Code    Ludicrous      Other MCP
+         (CLI)       Ralphy (GUI)    Clients
+```
+
+---
+
+## Modules
+
+### Module 1: Demerzel (Codebase Intelligence)
+
+**Source:** `@sashabogi/argus-mcp`
+**Character:** R. Daneel Olivaw/Demerzel - 20,000 years of perfect memory, observing silently
+
+**Purpose:** Understand codebases that exceed LLM context limits through intelligent snapshots and progressive disclosure.
+
+**Tools (9):**
+
+| Tool | Description | Token Cost |
+|------|-------------|------------|
+| `demerzel_snapshot` | Create codebase snapshot | 0 |
+| `demerzel_search` | Regex search across codebase | 0 |
+| `demerzel_find_files` | Glob pattern file matching | 0 |
+| `demerzel_find_symbol` | Locate function/class definitions | 0 |
+| `demerzel_find_importers` | Find files that import a module | 0 |
+| `demerzel_get_deps` | Get file dependencies | 0 |
+| `demerzel_get_context` | Get lines around a location | 0 |
+| `demerzel_analyze` | AI-powered deep analysis | ~500 |
+| `demerzel_semantic_search` | Natural language code search | ~100 |
+
+**Key Features:**
+- Enhanced snapshots with import graph and export index
+- Zero-cost tools for 90% of queries
+- Configurable AI provider for deep analysis
+- Snapshot staleness detection
+
+---
+
+### Module 2: Seldon (Multi-Agent Orchestration)
+
+**Source:** `hari-seldon`
+**Character:** Hari Seldon - Created psychohistory, the Plan guides humanity's future
+
+**Purpose:** Route tasks to specialized AI agents across 13+ providers with intelligent failover. Includes verification loop for automated plan → execute → verify → fix cycles.
+
+**Tools (19):**
+
+| Tool | Description |
+|------|-------------|
+| **Agent Invocation** | |
+| `seldon_invoke` | Invoke a single agent by role |
+| `seldon_compare` | Run same task through multiple agents |
+| `seldon_critique` | Get adversarial plan critique |
+| `seldon_review` | Get code review feedback |
+| `seldon_design` | Get UI/UX design feedback |
+| **Planning** | |
+| `seldon_plan` | Generate detailed implementation plan from intent |
+| `seldon_phase_create` | Break work into sequential, verifiable phases |
+| `seldon_phase_list` | View all phases and their status |
+| **Verification Loop** | |
+| `seldon_verify` | Verify implementation against plan (critical/major/minor) |
+| `seldon_fix` | Generate fixes for verification issues |
+| `seldon_execute_verified` | YOLO Mode - execute with auto verify/fix loop |
+| `seldon_execute_parallel` | Execute phases in parallel worktrees |
+| **Pipelines** | |
+| `seldon_pipeline_create` | Create multi-step DAG workflow |
+| `seldon_pipeline_execute` | Execute a pipeline |
+| `seldon_pipeline_status` | Get pipeline execution status |
+| **Tasks** | |
+| `seldon_task_execute` | Execute task in isolated worktree |
+| `seldon_task_claim` | Claim next available task (worker pattern) |
+| **Providers** | |
+| `seldon_providers_list` | List available providers and health |
+| `seldon_providers_test` | Test provider connectivity |
+
+**Agent Roles:**
+- `orchestrator` - Task synthesis, planning
+- `coder` - Code generation (uses worktrees)
+- `critic` - Adversarial plan review
+- `reviewer` - Code review
+- `designer` - UI/UX feedback
+- `researcher` - Information gathering
+- `verifier` - Implementation verification against plans
+
+**Key Features:**
+- 13+ AI providers (OpenAI, Anthropic, Gemini, DeepSeek, Ollama, etc.)
+- Intelligent failover with health tracking and circuit breakers
+- Cost-aware routing
+- Session delegation mode for Claude Code (zero-cost Anthropic calls)
+- DAG pipeline execution with dependency resolution
+- **Verification Loop:** Plan → Execute → Verify → Fix → Re-verify (automatic)
+- **Severity Thresholds:** Critical, Major, Minor issue categorization
+- **Parallel Execution:** Multiple phases in separate worktrees simultaneously
+
+---
+
+### Module 3: Gaia (Workflow Patterns)
+
+**Source:** `claude-workflow-orchestrator`
+**Character:** Gaia - The collective consciousness, "We are all one, and one is all"
+
+**Purpose:** Implement proven workflow patterns from the Claude Code team. Collective learning and memory.
+
+**Tools (13):**
+
+| Tool | Description |
+|------|-------------|
+| `gaia_worktree_create` | Create git worktree with session |
+| `gaia_worktree_list` | List active worktrees |
+| `gaia_worktree_switch` | Navigate between worktrees |
+| `gaia_worktree_cleanup` | Remove stale worktrees |
+| `gaia_session_register` | Track Claude session purpose |
+| `gaia_session_status` | View active sessions |
+| `gaia_session_handoff` | Prepare context for handoff |
+| `gaia_session_complete` | Mark session as done |
+| `gaia_learn` | Record correction for CLAUDE.md |
+| `gaia_apply` | Write learnings to CLAUDE.md |
+| `gaia_review` | Review accumulated learnings |
+| `gaia_remember` | Save context state |
+| `gaia_recall` | Restore previous context |
+
+**Key Features:**
+- Self-learning CLAUDE.md (capture mistakes, apply fixes)
+- Session handoff documents with git status, changes, next steps
+- Context memories for project state preservation
+- Shell alias generation for quick worktree navigation
+
+---
+
+## Tool Naming Convention
+
+All tools are prefixed by module for clarity:
+
+- `demerzel_*` - Codebase intelligence (The Observer)
+- `seldon_*` - Agent orchestration (The Planner)
+- `gaia_*` - Workflow patterns (The Memory)
+
+This prevents conflicts and makes tool discovery intuitive.
+
+---
+
+## Migration Plan
+
+### Phase 1: Foundation Core (Week 1)
+- [x] Project setup (TypeScript, MCP SDK, Zod)
+- [x] ConfigService with YAML parsing
+- [x] StorageService with JSON persistence
+- [x] GitService with worktree operations
+- [x] Basic MCP server with stdio transport
+
+### Phase 2: Demerzel Module (Week 2)
+- [ ] Port snapshot creation (basic + enhanced)
+- [ ] Port search tools (regex, glob, symbol, importers)
+- [ ] Port context tools (get_context, get_deps)
+- [ ] Port AI analysis (with provider abstraction)
+- [ ] Add semantic search
+
+### Phase 3: Seldon Module (Week 3)
+- [ ] Port ProviderService with all 13+ providers
+- [ ] Port failover system (health, circuit breakers)
+- [ ] Port agent invocation tools
+- [ ] Port pipeline execution (DAG)
+- [ ] Port task execution with worktree isolation
+
+### Phase 4: Gaia Module (Week 4)
+- [ ] Port worktree tools (unified with GitService)
+- [ ] Port session management
+- [ ] Port learning capture/apply
+- [ ] Port context memories
+- [ ] Add shell alias generation
+
+### Phase 5: Integration & Polish (Week 5)
+- [ ] CLI interface
+- [ ] Setup wizard
+- [ ] Documentation
+- [ ] Testing
+- [ ] Ludicrous Ralphy integration guide
+
+---
+
+## Success Metrics
+
+1. **Single Install:** One `npm install` provides all capabilities
+2. **Single Config:** One `~/.foundation/config.yaml` for everything
+3. **No Duplication:** Each feature exists in exactly one place
+4. **Full Coverage:** All features from all 3 projects are preserved
+5. **Clean API:** Intuitive tool naming and consistent patterns
+6. **Backward Compat:** Existing Argus/Hari Seldon users can migrate easily
+
+---
+
+## Appendix: Tool Count Summary
+
+| Module | Tools | From | Character |
+|--------|-------|------|-----------|
+| Demerzel | 9 | argus-mcp | R. Daneel Olivaw |
+| Seldon | 19 | hari-seldon | Hari Seldon |
+| Gaia | 13 | workflow-orchestrator | The Collective |
+| **Total** | **41** | | |
+
+**Final Count: 41 unique tools** (after adding verification loop)

package/docs/USER-GUIDE.md

@@ -0,0 +1,608 @@
+# Foundation User Guide
+
+A practical guide to using Foundation's 41 tools for AI-assisted development.
+
+---
+
+## Quick Start
+
+After installing Foundation, these three commands get you started:
+
+```
+Create a snapshot of this codebase
+```
+
+```
+What's the architecture of this project?
+```
+
+```
+Plan how to add [your feature here]
+```
+
+---
+
+## Demerzel: Codebase Intelligence
+
+*"I have been watching for 20,000 years."*
+
+Demerzel gives you instant, token-efficient codebase understanding.
+
+### Creating Snapshots
+
+**First time setup (do this once per project):**
+```
+Create a Foundation snapshot of this project
+```
+
+**With enhanced metadata (imports, exports, dependencies):**
+```
+Create an enhanced snapshot of this codebase
+```
+
+**Refresh stale snapshot:**
+```
+Refresh the codebase snapshot - it's out of date
+```
+
+### Searching (Zero AI Cost)
+
+**Find patterns:**
+```
+Search the codebase for TODO comments
+```
+
+```
+Search for all uses of useState in this project
+```
+
+```
+Find all files that import the auth module
+```
+
+**Find definitions:**
+```
+Where is AuthProvider defined?
+```
+
+```
+Find the symbol handlePayment
+```
+
+**Find dependencies:**
+```
+What files depend on the user service?
+```
+
+```
+What does src/api/routes.ts import?
+```
+
+### Understanding (AI-Powered)
+
+**Architecture questions:**
+```
+How is this codebase organized? What are the main modules?
+```
+
+```
+Explain the data flow from API request to database
+```
+
+**Specific flows:**
+```
+How does authentication work in this project?
+```
+
+```
+Trace how a payment gets processed from checkout to confirmation
+```
+
+**Pattern discovery:**
+```
+What patterns are used for error handling?
+```
+
+```
+How are API responses structured across the codebase?
+```
+
+---
+
+## Seldon: Multi-Agent Orchestration
+
+*"The future is not set, but it can be guided."*
+
+Seldon coordinates multiple AI agents to plan, execute, and verify your work.
+
+### Agent Invocation
+
+**Get a code review:**
+```
+Review this code for security and performance issues
+```
+
+```
+Review the auth middleware for potential vulnerabilities
+```
+
+**Get design feedback:**
+```
+Review this component design for accessibility
+```
+
+```
+Critique the UX of this checkout flow
+```
+
+**Get critical analysis:**
+```
+Critique this architectural decision - what could go wrong?
+```
+
+```
+What are the risks of using MongoDB for this use case?
+```
+
+**Compare perspectives:**
+```
+Compare what a critic and a coder think about this approach
+```
+
+```
+Get opinions from reviewer and designer on this PR
+```
+
+### Planning
+
+**Generate implementation plan:**
+```
+Plan how to add user authentication with OAuth2
+```
+
+```
+Plan the migration from REST to GraphQL
+```
+
+```
+Plan how to add real-time notifications
+```
+
+**Break into phases:**
+```
+Create implementation phases for adding Stripe payments
+```
+
+```
+Break down the dashboard redesign into manageable phases
+```
+
+**View phases:**
+```
+Show me all phases for the current plan
+```
+
+```
+What's the status of each implementation phase?
+```
+
+### Verification Loop
+
+**Verify implementation:**
+```
+Verify the current implementation against our plan
+```
+
+```
+Run tests and check if phase 2 meets the requirements
+```
+
+**Fix issues:**
+```
+Fix the issues found in verification - apply automatically
+```
+
+```
+Generate fixes for major issues only
+```
+
+**Execute with auto-verification (YOLO mode):**
+```
+Execute phase 1 with verification - fix any issues automatically
+```
+
+```
+Execute the auth implementation, verify, and fix up to 3 times
+```
+
+**Execute with quality gates:**
+```
+Execute phase 2 but stop on any major issues - I want to review those
+```
+
+```
+Execute with strict verification - fail on warnings too
+```
+
+### Parallel Execution
+
+**Run independent phases together:**
+```
+Execute phases 2, 3, and 4 in parallel - they're independent
+```
+
+```
+Run the API and frontend phases simultaneously in separate worktrees
+```
+
+**With merge strategy:**
+```
+Execute phases in parallel, then merge sequentially
+```
+
+```
+Run parallel phases and merge in dependency order
+```
+
+### Pipelines
+
+**Create reusable pipeline:**
+```
+Create a pipeline for our standard feature development flow
+```
+
+**Execute pipeline:**
+```
+Run the feature-dev pipeline for the notifications feature
+```
+
+**Check pipeline status:**
+```
+What's the status of the running pipeline?
+```
+
+### Provider Management
+
+**Check provider health:**
+```
+Test all AI providers and show their status
+```
+
+```
+Which providers are currently available?
+```
+
+**List configurations:**
+```
+Show me all configured agent roles and their providers
+```
+
+---
+
+## Gaia: Workflow Patterns
+
+*"We are all one, and one is all."*
+
+Gaia manages parallel work, session continuity, and collective learning.
+
+### Worktrees (Parallel Development)
+
+**Create worktree for a feature:**
+```
+Create a worktree for the auth feature
+```
+
+```
+Create a worktree called "payments" for the Stripe integration
+```
+
+**Create multiple worktrees:**
+```
+Create worktrees for auth, dashboard, and api-refactor
+```
+
+**List active worktrees:**
+```
+Show me all active worktrees
+```
+
+```
+What worktrees are currently active and what are they for?
+```
+
+**Switch context:**
+```
+Switch to the payments worktree
+```
+
+**Clean up:**
+```
+Clean up worktrees for merged branches
+```
+
+```
+Remove the auth worktree - that feature is done
+```
+
+### Session Management
+
+**Register a session:**
+```
+Register this session - I'm working on the OAuth2 integration
+```
+
+```
+Start a new session for debugging the payment bug
+```
+
+**Check session status:**
+```
+What's the current session status?
+```
+
+```
+Show me active sessions across all worktrees
+```
+
+**Create handoff:**
+```
+Create a handoff document - I need to continue tomorrow
+```
+
+```
+Generate a handoff with git status and recent changes
+```
+
+**Complete session:**
+```
+Mark this session complete - the feature is done
+```
+
+### Collective Learning
+
+**Capture a code style correction:**
+```
+Learn this: never use any type - always use explicit types
+```
+
+```
+Learn: we use early returns instead of nested if statements
+```
+
+**Capture architectural decisions:**
+```
+Learn: we use the repository pattern for all database access
+```
+
+```
+Learn: API responses always use the standard envelope format
+```
+
+**Capture project conventions:**
+```
+Learn: test files go in __tests__ folders next to the source
+```
+
+```
+Learn: we prefix private methods with underscore
+```
+
+**Apply learnings:**
+```
+Apply all learnings to CLAUDE.md
+```
+
+```
+Apply pending learnings to the project configuration
+```
+
+**Review learnings:**
+```
+Show me all learnings for this project
+```
+
+```
+What have we learned about error handling?
+```
+
+### Context Memory
+
+**Save a checkpoint:**
+```
+Remember this as "pre-refactor" - I might need to come back
+```
+
+```
+Save current state as "working-auth" before I experiment
+```
+
+**Recall checkpoint:**
+```
+Recall the pre-refactor state
+```
+
+```
+What was the context when I saved "working-auth"?
+```
+
+---
+
+## Complete Workflow Examples
+
+### Example 1: New Feature Development
+
+```
+1. Create a Foundation snapshot of this project
+
+2. How does the current user system work?
+
+3. Plan how to add user roles and permissions
+
+4. Critique this plan - what am I missing?
+
+5. Create implementation phases for user roles
+
+6. Create a worktree for the roles feature
+
+7. Register this session - implementing user roles
+
+8. Execute phase 1 (database schema) with verification
+
+9. Execute phase 2 (role service) with verification
+
+10. Review the roles code for security issues
+
+11. Learn: role checks should happen in middleware, not controllers
+
+12. Create a handoff document - continuing tomorrow
+```
+
+### Example 2: Bug Investigation & Fix
+
+```
+1. Search the codebase for payment processing
+
+2. How does the checkout flow work?
+
+3. What files depend on the payment service?
+
+4. Register this session - debugging payment timeout
+
+5. Plan how to fix the payment timeout issue
+
+6. Execute the fix with verification
+
+7. Learn: always set explicit timeouts for external API calls
+```
+
+### Example 3: Parallel Feature Development
+
+```
+1. Create worktrees for auth-upgrade and dashboard-v2
+
+2. In auth worktree: Execute the OAuth migration phases
+
+3. In dashboard worktree: Execute the redesign phases
+
+4. Run both feature branches in parallel with separate verification
+
+5. Review both features for consistency
+
+6. Clean up worktrees after merge
+```
+
+### Example 4: Code Review & Learning
+
+```
+1. Review the PR changes for security issues
+
+2. Compare critic and reviewer perspectives on this approach
+
+3. What patterns should we avoid based on this review?
+
+4. Learn: validate all user input at API boundaries
+
+5. Apply learnings to project CLAUDE.md
+```
+
+### Example 5: Onboarding to New Codebase
+
+```
+1. Create an enhanced snapshot of this project
+
+2. What's the architecture? Main technologies?
+
+3. How is the code organized? Key directories?
+
+4. How does authentication work?
+
+5. What are the main API endpoints?
+
+6. What testing patterns are used?
+
+7. What should I know before making changes?
+```
+
+---
+
+## Tips & Best Practices
+
+### Demerzel Tips
+- Create enhanced snapshots for better import/export tracking
+- Use zero-cost searches before AI analysis to save tokens
+- Refresh snapshots when you've made significant changes
+
+### Seldon Tips
+- Always get a critique before executing a big plan
+- Use verification loops for anything touching critical paths
+- Run independent phases in parallel to save time
+- Set severity thresholds appropriate to the task
+
+### Gaia Tips
+- Use worktrees for any work that might take multiple sessions
+- Register sessions to track what you're doing
+- Capture learnings immediately when you discover patterns
+- Create handoffs before ending sessions on incomplete work
+
+### General Tips
+- Start every project with a snapshot
+- Use phases for any feature taking more than an hour
+- Let verification catch issues before they become problems
+- Build up project learnings over time - they compound
+
+---
+
+## Command Reference
+
+### Demerzel Commands
+| Command | Purpose |
+|---------|---------|
+| `demerzel_snapshot` | Create codebase snapshot |
+| `demerzel_search` | Regex search (free) |
+| `demerzel_find_files` | Glob pattern search (free) |
+| `demerzel_find_symbol` | Find where symbol is defined (free) |
+| `demerzel_find_importers` | Find files that import a module (free) |
+| `demerzel_get_deps` | Get file dependencies (free) |
+| `demerzel_get_context` | Get code around a location (free) |
+| `demerzel_analyze` | AI-powered analysis (~500 tokens) |
+| `demerzel_semantic_search` | Natural language search |
+
+### Seldon Commands
+| Command | Purpose |
+|---------|---------|
+| `seldon_invoke` | Invoke an agent role |
+| `seldon_compare` | Compare multiple agents |
+| `seldon_critique` | Get critical review |
+| `seldon_review` | Code review |
+| `seldon_design` | Design feedback |
+| `seldon_plan` | Generate implementation plan |
+| `seldon_phase_create` | Break plan into phases |
+| `seldon_phase_list` | View all phases |
+| `seldon_verify` | Verify implementation |
+| `seldon_fix` | Generate fixes for issues |
+| `seldon_execute_verified` | Execute with verification loop |
+| `seldon_execute_parallel` | Execute phases in parallel |
+| `seldon_pipeline_create` | Create reusable pipeline |
+| `seldon_pipeline_execute` | Run a pipeline |
+| `seldon_pipeline_status` | Check pipeline status |
+| `seldon_task_execute` | Execute a task |
+| `seldon_task_claim` | Claim a task |
+| `seldon_providers_list` | List providers |
+| `seldon_providers_test` | Test provider health |
+
+### Gaia Commands
+| Command | Purpose |
+|---------|---------|
+| `gaia_worktree_create` | Create a worktree |
+| `gaia_worktree_list` | List worktrees |
+| `gaia_worktree_switch` | Switch to worktree |
+| `gaia_worktree_cleanup` | Clean up worktrees |
+| `gaia_session_register` | Register a session |
+| `gaia_session_status` | Check session status |
+| `gaia_session_handoff` | Create handoff document |
+| `gaia_session_complete` | Mark session complete |
+| `gaia_learn` | Capture a learning |
+| `gaia_apply` | Apply learnings |
+| `gaia_review` | Review learnings |
+| `gaia_remember` | Save context snapshot |
+| `gaia_recall` | Recall saved context |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sashabogi/foundation",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Unified MCP server for AI-assisted development: codebase intelligence, multi-agent orchestration, and workflow patterns",
   "type": "module",
   "main": "dist/index.js",
@@ -79,6 +79,7 @@
   },
   "files": [
     "dist",
+    "docs",
     "README.md",
     "LICENSE"
   ]