Foundation Bundle¶

Overview¶

The Foundation Bundle is the default bundle that ships with Amplifier, providing essential tools and agents for general-purpose software development workflows. It forms the backbone of most development tasks, offering file operations, code search, shell access, web research capabilities, and a suite of 16 specialized agents for common development patterns.

Key Characteristics:

• Universal Coverage: Handles 80% of common development tasks
• Production-Ready: Battle-tested tools with robust error handling
• Zero Configuration: Works out of the box with sensible defaults
• Extensible: Serves as a foundation for specialized bundles
• Token-Efficient: Agents absorb context cost via the Context Sink Pattern

The Foundation Bundle is automatically loaded when Amplifier starts, making its tools and agents immediately available without additional configuration.

Tools Included¶

Tool Details¶

Filesystem Tools¶

The read_file, write_file, and edit_file tools provide comprehensive file manipulation:

• Support for absolute and relative paths
• Bundle resource access via @bundle:path syntax
• Automatic backup before destructive operations
• Line-based reading for large files with offset/limit parameters

Search Tools¶

grep and glob enable fast codebase navigation:

• grep: Regex-based content search with ripgrep performance
• glob: Fast file pattern matching with ignore rules
• Both exclude common directories (node_modules, .venv, .git) by default
• Pagination support for large result sets

Shell Access¶

The bash tool provides controlled shell access:

• Safe execution with destructive command blocking
• Background process support for dev servers
• Output truncation to prevent context overflow
• Proper handling of exit codes and errors

Agents Included¶

The Foundation Bundle ships with 16 specialized agents, all prefixed with foundation:.

Core Concept: The Context Sink Pattern¶

The most important reason to delegate to agents is the Context Sink Pattern. When an agent reads 20 files during an investigation, those ~20,000 tokens are consumed inside the agent's context window. When the agent finishes, it returns only a ~500-token summary to the parent session. The parent gets the insight without the cost.

This means delegation is not an optimization -- it is the primary operating mode. Every tool call made directly in the parent session permanently consumes its context window. Agents absorb that cost and return only what matters.

Rule of thumb: If a task requires reading more than 2 files, or matches any agent's specialty, delegate.

Agent Domain Honoring¶

When an agent's description uses the words MUST, REQUIRED, or ALWAYS for a domain, you must delegate to that agent rather than working directly. The agent exists because it has safety protocols, specialized knowledge, or structural guarantees that direct tool use cannot replicate.

Critical domain rules:

• session-analyst -- MUST be used for events.jsonl files (lines can exceed 100k tokens and will crash other tools)
• git-ops -- MUST be used for git commits and PRs (has safety checks, proper attribution, commit message standards)
• security-guardian -- REQUIRED checkpoint before any production deployment
• modular-builder -- REQUIRES a complete specification; will stop and ask if one is missing

Agent Details¶

explorer¶

Deep local-context reconnaissance agent. Has zero prior context on each invocation -- every call must include the full objective, scope hints (directories, file types, keywords), and any constraints.

Capabilities:

• Analyzes project structure and technology stack
• Maps dependencies and relationships between modules
• Identifies entry points and core modules
• Generates architecture summaries from multi-file surveys

Best For:

• First-time project exploration
• Onboarding to unfamiliar codebases
• Pre-implementation reconnaissance
• Gathering information that spans many files

zen-architect¶

Operates in three explicit modes: ANALYZE (break down problems, design solutions), ARCHITECT (system design, module specification), and REVIEW (code quality assessment). Embodies ruthless simplicity and analysis-first development. Creates specifications that modular-builder then implements.

Capabilities:

• Designs system architecture and component boundaries
• Plans implementation strategies with concrete specifications
• Creates technical specs with file paths, interfaces, and success criteria
• Evaluates design tradeoffs and reviews implementations

Best For:

• Major feature planning
• Refactoring large systems
• API and schema design
• Code review and quality assessment

modular-builder¶

Implementation-only agent. Requires a complete specification with file paths, interfaces, patterns, and success criteria. If any of these are missing, use zen-architect first to produce the spec. Will stop and ask if the specification is incomplete -- do not send under-specified tasks.

Capabilities:

• Implements features following best practices from a finished spec
• Creates modular, testable code
• Writes comprehensive tests as part of implementation
• Documents public APIs

Prerequisites (all required):

• Clear file paths to create or modify
• Complete function signatures with types
• Pattern reference or explicit design freedom
• Success criteria defined

bug-hunter¶

Specialized debugging expert focused on systematic, hypothesis-driven investigation. Must be used when errors, unexpected behavior, or test failures are encountered.

Capabilities:

• Investigates test failures and runtime errors
• Traces execution paths with hypothesis-driven methodology
• Identifies root causes through evidence gathering
• Proposes and implements fixes

Best For:

• Debugging failing tests
• Investigating production issues
• Performance problems
• Unexpected behavior after changes

git-ops¶

All git and GitHub operations must be delegated to this agent. It has safety protocols, creates quality commit messages with proper context and co-author attribution, and handles GitHub API interactions.

Capabilities:

• Creates commits with proper formatting and Amplifier co-author attribution
• Creates and manages pull requests
• Handles branch operations and conflict resolution
• GitHub API interactions (issues, checks, releases)
• Repository discovery via gh repo list (finds private repos)
• Multi-repo sync operations (fetch, pull, status)

Best For:

• Any commit or PR creation
• Branch management and conflict resolution
• GitHub issue and release workflows
• Finding repositories (including private ones)

session-analyst¶

Required agent for analyzing, debugging, searching, and repairing Amplifier sessions. Has specialized knowledge for safely extracting data from large session logs without context overflow. Never attempt to read events.jsonl directly -- always delegate to this agent.

Capabilities:

• Investigates why sessions failed or will not resume
• Safely analyzes events.jsonl files (which contain 100k+ token lines)
• Diagnoses API errors, missing tool results, or corrupted transcripts
• Searches for sessions by ID, project, date, or topic
• Rewinds sessions to a prior point (truncates history to retry from a clean state)

Best For:

• Session failure investigation
• Understanding past conversations
• Session repair and rewind
• Safe event log analysis

web-research¶

Web research agent for searching and fetching information from the internet. Handles web searches, fetching URL content, and synthesizing information from multiple sources.

Capabilities:

• Performs web searches across multiple sources
• Fetches and extracts content from URLs
• Synthesizes information from multiple pages
• Finds official documentation and examples

Best For:

• Looking up external documentation
• Researching libraries and packages
• Finding code examples and best practices
• Gathering external context for decisions

file-ops¶

Focused file operations agent for reading, writing, editing, and searching files. Use for targeted file system operations when you need precise changes without the broader exploration scope of explorer.

Capabilities:

• Reads file contents (single or batch)
• Writes new files and makes targeted edits
• Finds files by glob pattern
• Searches file contents with grep

Best For:

• Single-file or small-batch operations
• Precise read/edit on known files
• Content search across the codebase
• File discovery by pattern

security-guardian¶

Required checkpoint before production deployments. Must be used when adding features that handle user data, integrating third-party services, refactoring auth code, or handling payment data.

Capabilities:

• OWASP Top 10 vulnerability assessment
• Hardcoded secrets detection
• Input/output validation review
• Cryptographic implementation review
• Dependency vulnerability scanning

Best For:

• Pre-deployment security review (required)
• New API endpoint review
• Third-party integration audit
• Periodic security assessments

integration-specialist¶

Expert at integrating with external services, APIs, and MCP servers while maintaining simplicity. Also analyzes and manages dependencies for security, compatibility, and technical debt.

Capabilities:

• Creates clean, maintainable external connections
• Sets up MCP server integrations
• Handles API authentication and configuration
• Analyzes dependencies for vulnerabilities and compatibility

Best For:

• External API integration
• MCP server setup
• Dependency health analysis
• Service connection configuration

test-coverage¶

Expert at analyzing test coverage, identifying gaps, and suggesting comprehensive test cases. Use when writing new features, after bug fixes, or during test reviews.

Capabilities:

• Analyzes existing test coverage
• Identifies gaps in test suites
• Suggests comprehensive test cases for modules
• Evaluates test quality and strategy

Best For:

• Post-implementation test review
• Test gap analysis
• Test strategy planning
• Ensuring quality after bug fixes

post-task-cleanup¶

Use after completing a todo list or major task to ensure codebase hygiene. Reviews git status, identifies all touched files, removes temporary artifacts, and eliminates unnecessary complexity.

Capabilities:

• Reviews what was changed during a task
• Identifies and removes temporary files and debugging artifacts
• Checks for unnecessary complexity
• Ensures adherence to project philosophy principles

Best For:

• Post-feature cleanup
• Post-refactoring review
• Removing debugging artifacts
• Maintaining codebase simplicity

ecosystem-expert¶

Amplifier ecosystem development specialist for working across multiple repositories or coordinating changes that span core, foundation, modules, and bundles.

Capabilities:

• Multi-repo coordination (changes spanning core + foundation + modules)
• Testing local changes across repositories via shadow environments
• Cross-repo workflow and dependency management
• Working memory patterns for long sessions

Best For:

• Changes that span multiple Amplifier repositories
• Testing local source changes across the ecosystem
• Understanding ecosystem architecture and dependencies
• Safe push ordering across repos

shell-exec¶

Shell command execution agent for running terminal commands with proper output capture and exit code reporting.

Capabilities:

• Runs build and test commands (pytest, npm test, cargo build, make)
• Handles package management operations (pip, npm, cargo, brew)
• Manages process lifecycle and system administration tasks
• Captures and reports structured output from shell commands

Best For:

• Build and test execution
• Package management across ecosystems
• Script execution with output capture
• System administration tasks

amplifier-smoke-test¶

Amplifier-specialized smoke test agent for validating changes in shadow environments. Extends the generic shadow-smoke-test with Amplifier ecosystem knowledge.

Capabilities:

• Validates amplifier_core imports (Session, Coordinator, etc.)
• Verifies provider installation and configuration
• Checks bundle loading and agent availability
• Tests Amplifier CLI commands and workflows
• Returns objective VERDICT: PASS/FAIL with evidence

Best For:

• Validating Amplifier changes in shadow environments
• Verifying multi-repo changes work together
• Post-shadow-operator environment validation
• Integration testing across local source changes

foundation-expert¶

The authoritative expert on Amplifier Foundation applications, bundle composition, and agent authoring. Must be consulted before writing bundle YAML or agent descriptions.

Capabilities:

• Guides bundle composition using the thin bundle pattern
• Advises on agent authoring (description requirements, context sink pattern)
• Provides working examples and pattern references
• Applies modular design philosophy to practical decisions
• Assists with behavior creation and context de-duplication

Best For:

• Creating or modifying bundles (required before writing bundle YAML)
• Writing agent descriptions
• Design decisions about context or composition
• Finding working examples and patterns

Key Patterns¶

The Design-First Pattern¶

The canonical workflow for building features follows a strict sequence that prevents under-specified work from reaching the implementation phase:

zen-architect (ANALYZE) -> zen-architect (ARCHITECT) -> modular-builder (implement) -> zen-architect (REVIEW)

1. Analyze: zen-architect breaks down the problem, explores alternatives, finds generalization opportunities
2. Architect: zen-architect produces a complete specification with file paths, interfaces, patterns, and success criteria
3. Implement: modular-builder builds exactly what was specified
4. Review: zen-architect reviews the implementation for quality and spec compliance

Never send under-specified tasks to modular-builder. If requirements are unclear, use zen-architect first.

Multi-Agent Patterns¶

Foundation agents support several patterns for coordinating work across multiple agents:

Parallel Dispatch

Launch multiple agents simultaneously when tasks are independent. Each agent runs in its own context and returns a summary.

You: "Audit this codebase for quality and security"
Amplifier: [Launches security-guardian and test-coverage simultaneously]

Context Sharing

Use context_scope="agents" so that a later agent can see the results returned by earlier agents. This lets agent B build on agent A's findings without re-doing the work.

1. explorer analyzes the codebase -> returns summary
2. zen-architect designs changes (with context_scope="agents", sees explorer's summary)
3. modular-builder implements (sees both prior summaries)

Session Resumption

Pass session_id back to an agent to continue a previous conversation with all accumulated context intact. Useful for iterative workflows where an agent needs to refine its previous work.

Self-Delegation

Use agent="self" to spawn yourself as a sub-agent. The sub-agent absorbs the token cost of a complex sub-task and returns only a summary. This is the ultimate token conservation technique for long sessions.

Complementary Agent Combinations¶

Certain agents work especially well together:

Getting Started¶

Basic Usage¶

The Foundation Bundle is active by default. Simply start using Amplifier and all Foundation tools and agents are immediately available.

Example 1: Reading and Editing Code

You: "Find all TODO comments in the src/ directory"
Amplifier: [Uses grep tool to search for TODO patterns]

You: "Update the authentication logic in auth.py"
Amplifier: [Uses read_file to inspect, then edit_file to modify]

Example 2: Delegating to Agents

You: "I need to understand this legacy codebase"
Amplifier: [Launches explorer agent to analyze structure]

You: "Design a new caching layer for this system"
Amplifier: [Launches zen-architect to create design]

You: "Now implement that design"
Amplifier: [Launches modular-builder to write code from the spec]

Agent Workflows¶

Agents can be chained for complex workflows:

1. Full Feature Development:
2. explorer -- Understand existing code
3. zen-architect -- Design the feature (produces spec)
4. modular-builder -- Implement from spec with tests
5. zen-architect -- Review the implementation

6. git-ops -- Commit and create PR

7. Bug Investigation and Fix:

8. bug-hunter -- Diagnose the issue
9. modular-builder -- Implement fix (if complex)
10. test-coverage -- Add regression tests

11. git-ops -- Create fix PR

12. Code Quality and Security Audit:

13. explorer -- Survey the codebase
14. security-guardian -- Check for vulnerabilities
15. test-coverage -- Ensure adequate testing

16. post-task-cleanup -- Clean up any issues found

17. Session Recovery:

18. session-analyst -- Investigate why a session failed
19. session-analyst -- Rewind to a clean state if needed
20. Resume work from the repaired session

Configuration¶

The Foundation Bundle works with zero configuration, but can be customized via .amplifier/config.yaml:

bundles:
  foundation:
    enabled: true
    agents:
      # Customize agent behavior
      explorer:
        max_depth: 5
      bug-hunter:
        auto_fix: false

When to Use¶

Perfect For:¶

• General software development -- Most common programming tasks
• Project exploration -- Understanding new codebases
• Feature implementation -- Building new functionality from design through delivery
• Bug fixing -- Systematic debugging and resolution
• Code refactoring -- Improving code structure with safety
• Git workflows -- Managing version control with proper attribution
• Test development -- Writing and maintaining tests
• Security review -- Pre-deployment vulnerability assessment
• Session management -- Debugging and repairing Amplifier sessions
• Multi-repo coordination -- Working across the Amplifier ecosystem

Consider Specialized Bundles For:¶

• Python development -- Use python-dev bundle for enhanced Python tools and LSP integration
• Design work -- Use design-intelligence bundle for UI/UX design agents
• Browser testing -- Use browser-tester bundle for live web interaction
• Deliberate development -- Use deliberate-development bundle for planning-first methodology

Complementary Bundles¶

The Foundation Bundle works well alongside:

• python-dev: Adds Python-specific linting, type checking, LSP-based code intelligence
• design-intelligence: Adds UI/UX design agents and tools
• recipes: Adds workflow automation and multi-stage processes
• deliberate-development: Adds deliberate planner, implementer, reviewer, and debugger agents

Multiple bundles can be loaded simultaneously, with their tools and agents available together.

Best Practices¶

Tool Selection¶

Use specialized tools first:

• Prefer read_file over bash cat for reading files
• Use grep instead of bash grep for searching
• Use glob for file discovery before manual searching

Delegate to agents -- do not work directly:

• If a task requires reading more than 2 files, delegate to an agent
• If a task matches any agent's specialty, delegate
• Use the delegate tool when work requires multiple operations
• Let agents operate autonomously instead of micromanaging

Agent Usage¶

Honor domain boundaries:

• explorer for understanding, not building
• zen-architect for design, not implementation
• modular-builder for implementation from specs, not debugging or design
• bug-hunter for diagnosis and fixes
• git-ops for all git operations (never use bash directly for commits)
• session-analyst for all session log analysis (never read events.jsonl directly)
• security-guardian before any production deployment (required, not optional)

Provide clear instructions:

Good: "Use bug-hunter to investigate why test_auth.py::test_login fails
      with a KeyError on the 'refresh_token' key"
Bad:  "Fix the tests"

Include full context for stateless agents:

Every agent invocation is stateless. Provide the complete objective, relevant file paths, and constraints in each instruction. Do not assume the agent remembers anything from a previous call (unless you pass a session_id to resume).

Workflow Patterns¶

1. Design-First (recommended for all new features)

zen-architect (analyze) -> zen-architect (architect) -> modular-builder -> zen-architect (review)

2. Exploration First Before major changes, understand the codebase:

explorer -> zen-architect -> modular-builder

3. Test-Driven Development Write tests before implementation:

zen-architect -> test-coverage -> modular-builder

4. Iterative Refinement Build, test, improve:

modular-builder -> test-coverage -> post-task-cleanup

Common Patterns¶

Pattern: Safe Refactoring¶

1. Search -- Find all usages with grep
2. Analyze -- Review with explorer
3. Plan -- Design changes with zen-architect
4. Execute -- Implement with modular-builder
5. Verify -- Test with test-coverage
6. Commit -- Save with git-ops

Pattern: New Feature Development¶

1. Explore -- Use explorer to understand integration points
2. Design -- Use zen-architect (ANALYZE then ARCHITECT) to plan architecture and produce spec
3. Build -- Use modular-builder to implement from spec
4. Review -- Use zen-architect (REVIEW) to assess the implementation
5. Test -- Use test-coverage to ensure quality
6. Secure -- Use security-guardian for security check
7. Clean -- Use post-task-cleanup to verify codebase hygiene
8. Ship -- Create PR with git-ops

Pattern: Bug Fix Workflow¶

1. Reproduce -- Verify the issue with bash to run tests
2. Investigate -- Use bug-hunter to diagnose
3. Fix -- Implement solution (often done by bug-hunter itself)
4. Test -- Add regression test via test-coverage
5. Commit -- Save fix with git-ops

Pattern: Production Deployment Checklist¶

1. Security -- Use security-guardian (REQUIRED checkpoint)
2. Tests -- Use test-coverage to verify coverage
3. Cleanup -- Use post-task-cleanup to remove artifacts
4. Ship -- Use git-ops to create PR

Try It Yourself¶

Exercise 1: Project Exploration¶

Try exploring a new project:

1. Launch explorer agent to analyze project structure
2. Use grep to find all exported functions
3. Use glob to list all test files
4. Read package.json or requirements.txt to understand dependencies

Exercise 2: Design-First Feature Implementation¶

Build a feature using the design-first pattern:

1. Use zen-architect (ANALYZE) to break down the problem
2. Use zen-architect (ARCHITECT) to produce a complete spec
3. Launch modular-builder to implement from the spec
4. Use zen-architect (REVIEW) to assess the result
5. Use test-coverage to ensure it is tested
6. Use post-task-cleanup to verify hygiene
7. Use git-ops to commit changes

Exercise 3: Bug Hunt¶

Practice systematic debugging:

1. Run tests with bash to identify failures
2. Launch bug-hunter to investigate with hypothesis-driven methodology
3. Review the proposed fix
4. Run tests again to verify
5. Commit the fix with git-ops

Exercise 4: Multi-Agent Parallel Dispatch¶

Try launching agents in parallel:

1. Simultaneously launch explorer and security-guardian on a codebase
2. Review both summaries
3. Use zen-architect to design improvements based on combined findings

Exercise 5: Session Recovery¶

Practice session management:

1. Use session-analyst to search for a past session by topic
2. Analyze what happened in the session
3. If it failed, use session-analyst to rewind to a clean state

Advanced Usage¶

Multi-Agent Workflows¶

Launch multiple agents in parallel for complex tasks:

You: "Audit this codebase for quality and security"
Amplifier: [Launches security-guardian and test-coverage simultaneously]
         [Both return summaries; parent synthesizes findings]

Context Sharing Across Agents¶

Chain agents so later ones can see earlier results:

You: "Analyze the auth module, then design improvements"
Amplifier: [Launches explorer with context_scope="agents"]
         [Launches zen-architect with context_scope="agents" -- sees explorer's results]

Session Resumption¶

Continue an agent's work across multiple turns:

You: "Continue the architect session to refine the design"
Amplifier: [Passes session_id to zen-architect, resuming with full prior context]

Self-Delegation for Token Conservation¶

Spawn yourself as a sub-agent to handle expensive sub-tasks:

Main session: "I need to analyze 50 config files and summarize the patterns"
Amplifier: [Delegates to agent="self", which reads all 50 files]
         [Sub-agent returns ~500 token summary]
         [Main session continues with full context budget intact]

Custom Agent Instructions¶

Provide detailed context for better results:

You: "Use explorer to map the authentication flow, focusing on JWT token
validation and refresh logic. Document the security boundaries.
Scope: src/auth/ and src/middleware/. Keywords: jwt, token, refresh."

Combining Tools and Agents¶

Mix direct tool usage with agent delegation:

1. Use glob to find all API route files
2. Launch explorer to analyze the route structure
3. Use zen-architect to design improvements
4. Launch modular-builder to implement from the spec

Integration¶

With Other Bundles¶

Foundation provides the base layer for specialized bundles:

• python-dev extends Foundation with Python-specific tools and LSP code intelligence
• design-intelligence adds design agents while using Foundation's filesystem tools
• deliberate-development adds planning-first methodology agents that complement Foundation's implementation agents
• Custom bundles can leverage Foundation's agents in their workflows

With Recipes¶

Foundation agents are frequently used in recipes:

stages:
  - name: analyze
    agent: foundation:explorer
    instruction: "Analyze project structure"

  - name: design
    agent: foundation:zen-architect
    instruction: "Design new feature based on analysis"

  - name: implement
    agent: foundation:modular-builder
    instruction: "Implement the designed feature from the spec"

  - name: review
    agent: foundation:zen-architect
    instruction: "Review the implementation for quality and spec compliance"

Troubleshooting¶

Common Issues¶

Agent not responding or slow:

• Check if the task is too broad -- provide more specific instructions
• Ensure you included full context (agents are stateless per invocation)
• Break large tasks into smaller delegations

Search returning too many results:

• Use more specific regex patterns with grep
• Add file type filters with glob
• Use head_limit parameter to paginate

File operations failing:

• Verify file paths are correct
• Check file permissions
• Ensure files exist before editing

modular-builder refusing to start:

• It requires a complete specification. Use zen-architect first to produce one
• Ensure you have provided file paths, interfaces, patterns, and success criteria

Session analysis crashing:

• Never read events.jsonl directly -- always delegate to session-analyst
• Event log lines can exceed 100k tokens and will overflow other tools

Getting Help¶

• Use load_skill to access domain-specific knowledge
• Launch web-research for finding external documentation
• Launch ecosystem-expert for multi-repo Amplifier coordination questions

What's Next?¶

• Explore LSP Python Bundle for enhanced Python tools
• Learn about Design Intelligence Bundle for UI/UX work
• Check out Recipes Bundle for workflow automation
• Read Advanced Topics for complex patterns

The Foundation Bundle provides everything you need for general-purpose development. Master these tools and agents -- especially the Context Sink Pattern and Design-First workflow -- and you will be productive in any programming environment.