# 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 |