@sashabogi/foundation 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sasha Bogojevic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,341 @@
+# 🏛️ Foundation
+
+**The unified MCP server for AI-assisted development.**
+
+Three pillars from Asimov's Foundation universe, working together:
+
+| Module | Character | Purpose | Tools |
+|--------|-----------|---------|-------|
+| **Demerzel** | R. Daneel Olivaw | Codebase intelligence - 20,000 years of perfect memory | 9 |
+| **Seldon** | Hari Seldon | Multi-agent orchestration - the Plan guides the future | 19 |
+| **Gaia** | The Collective | Workflow patterns - "We are all one, and one is all" | 13 |
+
+**One install. One config. 41 tools.**
+
+---
+
+## Quick Start
+
+```bash
+# Install
+npm install -g @sashabogi/foundation
+
+# Setup wizard (configure providers)
+foundation init
+
+# Add to Claude Code
+foundation mcp install
+```
+
+Restart Claude Code. Foundation is now available.
+
+---
+
+## Modules
+
+### 🤖 Demerzel: Codebase Intelligence
+
+*"I have been watching for 20,000 years."*
+
+Named after R. Daneel Olivaw/Demerzel - the robot who guided humanity across millennia with perfect memory and silent observation.
+
+```bash
+# Create a snapshot of your codebase
+demerzel_snapshot path="." enhanced=true
+
+# Search (zero AI cost)
+demerzel_search path=".foundation/snapshot.txt" pattern="TODO"
+
+# Find where a symbol is defined (zero AI cost)
+demerzel_find_symbol path=".foundation/snapshot.txt" symbol="AuthProvider"
+
+# Deep AI analysis (~500 tokens)
+demerzel_analyze path=".foundation/snapshot.txt" query="How does authentication work?"
+```
+
+**Tools**: `demerzel_snapshot`, `demerzel_search`, `demerzel_find_files`, `demerzel_find_symbol`, `demerzel_find_importers`, `demerzel_get_deps`, `demerzel_get_context`, `demerzel_analyze`, `demerzel_semantic_search`
+
+---
+
+### 📊 Seldon: Multi-Agent Orchestration
+
+*"The future is not set, but it can be guided."*
+
+Named after Hari Seldon - the mathematician who created psychohistory to predict and guide humanity's future through the Seldon Plan.
+
+#### Agent Invocation
+```bash
+# Invoke a specific agent role
+seldon_invoke role="critic" task="Review this architectural decision..."
+
+# Compare multiple agents on the same task
+seldon_compare roles=["critic", "reviewer"] task="Evaluate this approach..."
+
+# Get code review
+seldon_review code="function auth() { ... }" focus=["security", "performance"]
+```
+
+#### Planning
+```bash
+# Generate a detailed implementation plan
+seldon_plan intent="Add OAuth2 authentication" context="Express backend"
+
+# Break work into phases
+seldon_phase_create intent="Build user dashboard with real-time updates"
+
+# View phase status
+seldon_phase_list
+```
+
+#### Verification Loop (The Key Innovation)
+```
+Plan → Execute → Verify → Fix → Re-verify → ✓ Next Phase
+                   ↑_____________|
+                   (automatic, with severity thresholds)
+```
+
+```bash
+# Verify implementation against a plan
+seldon_verify planId="plan_abc123" runTests=true
+
+# Generate fixes for issues
+seldon_fix verificationId="ver_xyz789" severityThreshold="major" autoApply=true
+
+# YOLO Mode: Execute with automatic verify/fix loop
+seldon_execute_verified \
+  phaseId="phase_abc123" \
+  maxAttempts=3 \
+  severityThreshold="major" \
+  autoFix=true
+
+# Execute multiple phases in parallel (each in its own worktree)
+seldon_execute_parallel \
+  phaseIds=["phase_1", "phase_2", "phase_3"] \
+  worktreePerPhase=true \
+  mergeStrategy="sequential"
+```
+
+#### Pipelines
+```bash
+# Create and execute pipelines
+seldon_pipeline_create name="feature-dev" steps=[...]
+seldon_pipeline_execute pipelineId="pipe_abc123"
+```
+
+**Agent Roles**: `orchestrator`, `coder`, `critic`, `reviewer`, `designer`, `researcher`, `verifier`
+
+**Providers**: Anthropic, OpenAI, Google Gemini, DeepSeek, Groq, Together, Fireworks, OpenRouter, Z.AI, Kimi, Ollama, Perplexity
+
+**Tools**:
+- *Invocation*: `seldon_invoke`, `seldon_compare`, `seldon_critique`, `seldon_review`, `seldon_design`
+- *Planning*: `seldon_plan`, `seldon_phase_create`, `seldon_phase_list`
+- *Verification*: `seldon_verify`, `seldon_fix`, `seldon_execute_verified`, `seldon_execute_parallel`
+- *Pipelines*: `seldon_pipeline_create`, `seldon_pipeline_execute`, `seldon_pipeline_status`
+- *Tasks*: `seldon_task_execute`, `seldon_task_claim`
+- *Providers*: `seldon_providers_list`, `seldon_providers_test`
+
+---
+
+### 🌍 Gaia: Workflow Patterns
+
+*"We are all one, and one is all."*
+
+Named after Gaia - the planet-wide collective consciousness where every individual shares memory and learns as one.
+
+#### Parallel Worktrees
+*"The single biggest productivity unlock"*
+
+```bash
+# Create worktrees for parallel Claude sessions
+gaia_worktree_create branch="feature/auth" alias="a" purpose="OAuth implementation"
+gaia_worktree_create branch="bugfix/login" alias="b" purpose="Fix login crash"
+
+# Quick switch (generates shell aliases)
+# alias za='cd /path/to/project-a && claude'
+# alias zb='cd /path/to/project-b && claude'
+```
+
+#### Collective Learning
+*"Every correction benefits all future sessions"*
+
+```bash
+# Capture a correction
+gaia_learn \
+  mistake="Used any type instead of proper typing" \
+  correction="Always use explicit types, never any" \
+  category="code_style"
+
+# Apply to CLAUDE.md
+gaia_apply
+```
+
+#### Session Memory
+
+```bash
+# Register a session
+gaia_session_register purpose="Implementing OAuth2" taskType="feature"
+
+# Create handoff document for another session
+gaia_session_handoff sessionId="sess_abc123" includeGitStatus=true
+
+# Remember context for later
+gaia_remember name="pre-refactor" notes="Before auth rewrite"
+
+# Recall a memory
+gaia_recall name="pre-refactor"
+```
+
+**Tools**: `gaia_worktree_create`, `gaia_worktree_list`, `gaia_worktree_switch`, `gaia_worktree_cleanup`, `gaia_session_register`, `gaia_session_status`, `gaia_session_handoff`, `gaia_session_complete`, `gaia_learn`, `gaia_apply`, `gaia_review`, `gaia_remember`, `gaia_recall`
+
+---
+
+## Configuration
+
+Foundation uses a single YAML config file:
+
+**Location**: `~/.foundation/config.yaml`
+
+```yaml
+version: "1.0"
+
+# Global defaults
+defaults:
+  temperature: 0.7
+  max_tokens: 4096
+  timeout_ms: 60000
+
+# Provider API keys (use environment variables)
+providers:
+  anthropic:
+    api_key: ${ANTHROPIC_API_KEY}
+    access_mode: session  # Use current Claude session when possible
+  openai:
+    api_key: ${OPENAI_API_KEY}
+    default_model: gpt-4o
+  deepseek:
+    api_key: ${DEEPSEEK_API_KEY}
+    default_model: deepseek-reasoner
+  ollama:
+    base_url: http://localhost:11434
+    default_model: llama3.3:70b
+
+# Role assignments with fallback chains
+roles:
+  orchestrator:
+    provider: anthropic
+    model: claude-sonnet-4-20250514
+  coder:
+    provider: deepseek
+    model: deepseek-reasoner
+    needs_worktree: true
+    fallback_chain:
+      - provider: openai
+        model: gpt-4o
+  critic:
+    provider: deepseek
+    model: deepseek-reasoner
+    temperature: 0.3
+  reviewer:
+    provider: openai
+    model: gpt-4o
+
+# Demerzel settings (codebase intelligence)
+demerzel:
+  provider: ollama
+  model: qwen2.5-coder:7b
+  snapshot_max_age_hours: 24
+
+# Gaia settings (workflow patterns)
+worktrees:
+  base_dir: .foundation/worktrees
+  max_count: 10
+  auto_cleanup: true
+
+learning:
+  auto_apply: false
+```
+
+---
+
+## The Foundation Trilogy
+
+Just as in Asimov's universe, the three work together:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      FOUNDATION                              │
+│                                                              │
+│   DEMERZEL          SELDON              GAIA                │
+│   (The Observer)    (The Planner)       (The Memory)        │
+│                                                              │
+│   Knows the         Orchestrates        Preserves context   │
+│   codebase          the agents          across sessions     │
+│   perfectly         and plans           and learns          │
+│                                                              │
+│   "I have been      "The future is      "We are all one,    │
+│    watching for      not set, but it     and one is all"    │
+│    20,000 years"     can be guided"                         │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Data Storage
+
+```
+~/.foundation/
+├── config.yaml              # Main configuration
+├── state/
+│   ├── worktrees.json       # Active worktrees
+│   ├── sessions.json        # Session tracking
+│   ├── learnings.json       # Global learnings
+│   ├── pipelines.json       # Pipeline state
+│   ├── tasks.json           # Task queue
+│   ├── snapshots.json       # Context memories
+│   └── provider-health.json # Provider health tracking
+└── cache/
+    └── ...
+
+.foundation/                 # Project-level (in repo root)
+├── config.yaml              # Project overrides
+├── snapshot.txt             # Codebase snapshot (Demerzel)
+├── learnings.json           # Project-specific learnings (Gaia)
+└── sessions.json            # Project sessions (Gaia)
+```
+
+---
+
+## Development
+
+```bash
+# Clone and install
+git clone https://github.com/sashabogi/foundation.git
+cd foundation
+npm install
+
+# Build
+npm run build
+
+# Development with watch
+npm run dev
+
+# Run directly
+npm start
+```
+
+---
+
+## Credits
+
+Foundation consolidates work from:
+- [Argus](https://github.com/sashabogi/argus) → **Demerzel**
+- [Hari Seldon](https://github.com/sashabogi/hari-seldon) → **Seldon**
+- Claude Workflow Orchestrator → **Gaia**
+
+Inspired by Isaac Asimov's Foundation series.
+
+---
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * Foundation CLI
+ *
+ * Commands:
+ * - foundation init     Setup wizard for configuration
+ * - foundation start    Start the MCP server
+ * - foundation mcp      MCP installation helpers
+ * - foundation status   Check Foundation status
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;GAQG"}

package/dist/cli.js

@@ -0,0 +1,308 @@
+#!/usr/bin/env node
+/**
+ * Foundation CLI
+ *
+ * Commands:
+ * - foundation init     Setup wizard for configuration
+ * - foundation start    Start the MCP server
+ * - foundation mcp      MCP installation helpers
+ * - foundation status   Check Foundation status
+ */
+import { Command } from 'commander';
+import chalk from 'chalk';
+import ora from 'ora';
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import { ConfigService } from './services/config.service.js';
+const VERSION = '0.1.0';
+const CONFIG_DIR = join(homedir(), '.foundation');
+const CONFIG_FILE = join(CONFIG_DIR, 'config.yaml');
+const program = new Command();
+program
+    .name('foundation')
+    .description('Unified MCP server for AI-assisted development')
+    .version(VERSION);
+// ============================================================================
+// foundation init
+// ============================================================================
+program
+    .command('init')
+    .description('Initialize Foundation configuration')
+    .option('-f, --force', 'Overwrite existing configuration')
+    .action(async (options) => {
+    const spinner = ora('Initializing Foundation...').start();
+    try {
+        // Create config directory
+        if (!existsSync(CONFIG_DIR)) {
+            mkdirSync(CONFIG_DIR, { recursive: true });
+            spinner.text = 'Created ~/.foundation directory';
+        }
+        // Check for existing config
+        if (existsSync(CONFIG_FILE) && !options.force) {
+            spinner.warn('Configuration already exists. Use --force to overwrite.');
+            console.log(chalk.gray(`  Config: ${CONFIG_FILE}`));
+            return;
+        }
+        // Create default config
+        const defaultConfig = `# Foundation Configuration
+# https://github.com/sashabogi/foundation
+
+version: "1.0"
+
+# Global defaults
+defaults:
+  temperature: 0.7
+  max_tokens: 4096
+  timeout_ms: 60000
+
+# Provider API keys (use environment variables for security)
+providers:
+  anthropic:
+    api_key: \${ANTHROPIC_API_KEY}
+    access_mode: session  # 'api', 'session', or 'auto'
+  
+  openai:
+    api_key: \${OPENAI_API_KEY}
+    default_model: gpt-4o
+  
+  # deepseek:
+  #   api_key: \${DEEPSEEK_API_KEY}
+  #   default_model: deepseek-reasoner
+  
+  # ollama:
+  #   base_url: http://localhost:11434
+  #   default_model: llama3.3:70b
+
+# Role assignments
+roles:
+  orchestrator:
+    provider: anthropic
+    model: claude-sonnet-4-20250514
+  
+  coder:
+    provider: anthropic
+    model: claude-sonnet-4-20250514
+    needs_worktree: true
+  
+  critic:
+    provider: anthropic
+    model: claude-sonnet-4-20250514
+    temperature: 0.3
+  
+  reviewer:
+    provider: anthropic
+    model: claude-sonnet-4-20250514
+  
+  designer:
+    provider: anthropic
+    model: claude-sonnet-4-20250514
+  
+  researcher:
+    provider: anthropic
+    model: claude-sonnet-4-20250514
+  
+  verifier:
+    provider: anthropic
+    model: claude-sonnet-4-20250514
+    temperature: 0.2
+
+# Demerzel settings (codebase intelligence)
+demerzel:
+  provider: anthropic
+  model: claude-sonnet-4-20250514
+  snapshot_max_age_hours: 24
+  auto_refresh: false
+
+# Gaia settings (workflow patterns)
+worktrees:
+  base_dir: .foundation/worktrees
+  max_count: 10
+  auto_cleanup: true
+  stale_after_hours: 48
+
+learning:
+  auto_apply: false
+  categories:
+    - code_style
+    - architecture
+    - testing
+    - performance
+    - security
+    - documentation
+`;
+        writeFileSync(CONFIG_FILE, defaultConfig);
+        spinner.succeed('Foundation initialized!');
+        console.log();
+        console.log(chalk.green('✓') + ' Configuration created at ' + chalk.cyan(CONFIG_FILE));
+        console.log();
+        console.log(chalk.bold('Next steps:'));
+        console.log('  1. Edit ' + chalk.cyan('~/.foundation/config.yaml') + ' to add your API keys');
+        console.log('  2. Run ' + chalk.cyan('foundation mcp install') + ' to add to Claude Code');
+        console.log('  3. Restart Claude Code');
+        console.log();
+    }
+    catch (error) {
+        spinner.fail('Failed to initialize Foundation');
+        console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+        process.exit(1);
+    }
+});
+// ============================================================================
+// foundation start
+// ============================================================================
+program
+    .command('start')
+    .description('Start the Foundation MCP server')
+    .option('-v, --verbose', 'Enable verbose logging')
+    .action(async (options) => {
+    console.log(chalk.bold('Foundation MCP Server'));
+    console.log(chalk.gray('Press Ctrl+C to stop'));
+    console.log();
+    // Import and start the server
+    const { startServer } = await import('./index.js');
+    await startServer();
+});
+// ============================================================================
+// foundation mcp
+// ============================================================================
+const mcpCommand = program
+    .command('mcp')
+    .description('MCP installation helpers');
+mcpCommand
+    .command('install')
+    .description('Add Foundation to Claude Code MCP configuration')
+    .action(async () => {
+    const spinner = ora('Adding Foundation to Claude Code...').start();
+    try {
+        // Find Claude Code config location
+        const possiblePaths = [
+            join(homedir(), '.config', 'claude-code', 'mcp.json'),
+            join(homedir(), 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json'),
+            join(homedir(), '.claude', 'mcp.json'),
+        ];
+        let configPath = null;
+        for (const path of possiblePaths) {
+            if (existsSync(path)) {
+                configPath = path;
+                break;
+            }
+        }
+        // Determine the Foundation executable path
+        const foundationPath = process.argv[1]; // Current CLI path
+        const serverPath = foundationPath.replace('cli.js', 'index.js');
+        const mcpEntry = {
+            foundation: {
+                command: 'node',
+                args: [serverPath],
+                env: {
+                    ANTHROPIC_API_KEY: '${ANTHROPIC_API_KEY}',
+                    OPENAI_API_KEY: '${OPENAI_API_KEY}',
+                },
+            },
+        };
+        if (configPath) {
+            // Update existing config
+            const existing = JSON.parse(readFileSync(configPath, 'utf-8'));
+            existing.mcpServers = existing.mcpServers || {};
+            existing.mcpServers.foundation = mcpEntry.foundation;
+            writeFileSync(configPath, JSON.stringify(existing, null, 2));
+            spinner.succeed('Updated Claude Code configuration');
+            console.log(chalk.gray(`  Config: ${configPath}`));
+        }
+        else {
+            // Create new config (Claude Desktop format)
+            const claudeDesktopPath = join(homedir(), 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+            const claudeDir = join(homedir(), 'Library', 'Application Support', 'Claude');
+            if (!existsSync(claudeDir)) {
+                mkdirSync(claudeDir, { recursive: true });
+            }
+            const newConfig = { mcpServers: mcpEntry };
+            writeFileSync(claudeDesktopPath, JSON.stringify(newConfig, null, 2));
+            spinner.succeed('Created Claude Desktop configuration');
+            console.log(chalk.gray(`  Config: ${claudeDesktopPath}`));
+        }
+        console.log();
+        console.log(chalk.bold('Restart Claude Code/Desktop to activate Foundation.'));
+        console.log();
+        console.log('Available tools:');
+        console.log(chalk.cyan('  Demerzel (9)') + ' - Codebase intelligence');
+        console.log(chalk.cyan('  Seldon (19)') + '  - Multi-agent orchestration');
+        console.log(chalk.cyan('  Gaia (13)') + '    - Workflow patterns');
+        console.log();
+    }
+    catch (error) {
+        spinner.fail('Failed to install MCP configuration');
+        console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+        process.exit(1);
+    }
+});
+mcpCommand
+    .command('config')
+    .description('Print MCP configuration JSON for manual installation')
+    .action(() => {
+    const serverPath = process.argv[1].replace('cli.js', 'index.js');
+    const config = {
+        mcpServers: {
+            foundation: {
+                command: 'node',
+                args: [serverPath],
+                env: {
+                    ANTHROPIC_API_KEY: '${ANTHROPIC_API_KEY}',
+                    OPENAI_API_KEY: '${OPENAI_API_KEY}',
+                },
+            },
+        },
+    };
+    console.log(JSON.stringify(config, null, 2));
+});
+// ============================================================================
+// foundation status
+// ============================================================================
+program
+    .command('status')
+    .description('Check Foundation status and configuration')
+    .action(async () => {
+    console.log(chalk.bold('Foundation Status'));
+    console.log();
+    // Check config
+    const configExists = existsSync(CONFIG_FILE);
+    console.log((configExists ? chalk.green('✓') : chalk.red('✗')) +
+        ' Configuration: ' +
+        (configExists ? chalk.cyan(CONFIG_FILE) : chalk.gray('Not found')));
+    if (configExists) {
+        try {
+            const config = ConfigService.getInstance();
+            const providers = config.getProviders();
+            console.log();
+            console.log(chalk.bold('Configured Providers:'));
+            for (const [name, providerConfig] of Object.entries(providers)) {
+                if (providerConfig) {
+                    const hasKey = providerConfig.api_key && !providerConfig.api_key.includes('${');
+                    console.log('  ' +
+                        (hasKey ? chalk.green('✓') : chalk.yellow('○')) +
+                        ' ' + name +
+                        (hasKey ? '' : chalk.gray(' (needs API key)')));
+                }
+            }
+        }
+        catch (error) {
+            console.log(chalk.yellow('  Could not parse configuration'));
+        }
+    }
+    // Check state directory
+    const stateDir = join(CONFIG_DIR, 'state');
+    const stateExists = existsSync(stateDir);
+    console.log();
+    console.log((stateExists ? chalk.green('✓') : chalk.gray('○')) +
+        ' State directory: ' +
+        (stateExists ? chalk.cyan(stateDir) : chalk.gray('Not created yet')));
+    console.log();
+    console.log(chalk.gray('Run `foundation init` to create configuration'));
+    console.log(chalk.gray('Run `foundation mcp install` to add to Claude Code'));
+});
+// ============================================================================
+// Parse and run
+// ============================================================================
+program.parse();
+//# sourceMappingURL=cli.js.map