Skip to content

Latest commit

 

History

History

references

README.md

References Navigation Guide

This directory contains deep-dive documentation for building amplifier-foundation modules. Use this guide to find the right reference for your needs.

Quick Navigation

I want to... Read this
Understand module types MODULE_TYPES.md
Learn the development workflow DEVELOPMENT_WORKFLOW.md
Set up testing TESTING_GUIDE.md
Understand repository rules REPOSITORY_RULES.md
See working examples EXAMPLES.md
Learn API patterns API_PATTERNS.md
Use modular-builder agent MODULAR_BUILDER.md
Contribute modules CONTRIBUTING.md

By Experience Level

🌱 Beginner: Building Your First Module

Start here if you're new to amplifier-foundation:

  1. MODULE_TYPES.md - Understand the 5 module types (10 min read)
  2. EXAMPLES.md - Study complete working examples (15 min)
  3. DEVELOPMENT_WORKFLOW.md - Follow step-by-step process (20 min)
  4. TESTING_GUIDE.md - Set up testing (15 min)

Total time: ~60 minutes to first module

🌿 Intermediate: Building Production Modules

You've built a module and want to improve it:

  1. REPOSITORY_RULES.md - Ensure proper isolation
  2. API_PATTERNS.md - Follow common patterns
  3. TESTING_GUIDE.md - Achieve 85% coverage
  4. CONTRIBUTING.md - Prepare for publication

🌳 Advanced: Architecture and Patterns

You're designing complex modules:

  1. MODULE_TYPES.md - Deep dive on protocols
  2. API_PATTERNS.md - Advanced patterns
  3. MODULAR_BUILDER.md - AI-assisted development
  4. REPOSITORY_RULES.md - Architectural constraints

By Module Type

Building Tool Modules

  1. Start: MODULE_TYPES.md#tool-modules
  2. Examples: EXAMPLES.md#example-1-simple-tool-module
  3. API: API_PATTERNS.md#tool-module-patterns
  4. Testing: TESTING_GUIDE.md#testing-tool-modules

Building Hook Modules

  1. Start: MODULE_TYPES.md#hook-modules
  2. Examples: EXAMPLES.md#example-2-hook-module
  3. API: API_PATTERNS.md#hook-module-patterns
  4. Testing: TESTING_GUIDE.md#testing-hook-modules

Building Provider Modules

  1. Start: MODULE_TYPES.md#provider-modules
  2. Examples: EXAMPLES.md#example-3-provider-module
  3. API: API_PATTERNS.md#provider-module-patterns
  4. Testing: TESTING_GUIDE.md#testing-provider-modules

Building Context Modules

  1. Start: MODULE_TYPES.md#context-modules
  2. Examples: EXAMPLES.md#example-4-context-module
  3. API: API_PATTERNS.md#context-module-patterns
  4. Testing: TESTING_GUIDE.md#testing-context-modules

Building Orchestrator Modules

  1. Start: MODULE_TYPES.md#orchestrator-modules
  2. API: API_PATTERNS.md#orchestrator-module-patterns
  3. Testing: TESTING_GUIDE.md#testing-orchestrator-modules

By Task

Setting Up Development Environment

→ DEVELOPMENT_WORKFLOW.md#3-create-module-structure

Writing Tests

→ TESTING_GUIDE.md

Understanding Repository Rules

→ REPOSITORY_RULES.md

Publishing to GitHub

→ DEVELOPMENT_WORKFLOW.md#7-publishing-to-github

Using AI to Generate Modules

→ MODULAR_BUILDER.md

Contributing to Ecosystem

→ CONTRIBUTING.md

Document Details

MODULE_TYPES.md (~800 lines)

Deep dive on all 5 module types with protocols, examples, and testing strategies.

Read when:

  • Building your first module
  • Choosing the right module type
  • Understanding protocol requirements
  • Need type-specific testing guidance

DEVELOPMENT_WORKFLOW.md (~600 lines)

Complete step-by-step development process from idea to publication.

Read when:

  • Starting a new module
  • Setting up local development
  • Publishing to GitHub
  • Maintaining existing modules

TESTING_GUIDE.md (~700 lines)

Comprehensive testing documentation with pyramid strategy, async patterns, and coverage.

Read when:

  • Setting up tests
  • Improving coverage
  • Learning async testing
  • Configuring CI/CD

REPOSITORY_RULES.md (~500 lines)

Repository awareness constraints, naming conventions, and architectural principles.

Read when:

  • Understanding "bricks and studs"
  • Ensuring module isolation
  • Validating architecture
  • Avoiding common anti-patterns

EXAMPLES.md (~1000 lines)

Four complete working examples with full code, tests, and usage patterns.

Read when:

  • Need copy-paste-ready code
  • Learning by example
  • Comparing module types
  • Verifying understanding

API_PATTERNS.md (~400 lines)

Common implementation patterns for mount(), execute(), error handling, and configuration.

Read when:

  • Implementing mount() function
  • Structuring error handling
  • Managing configuration
  • Applying async patterns

MODULAR_BUILDER.md (~600 lines)

Guide to using the modular-builder AI agent for generating module scaffolding.

Read when:

  • Want to speed up development
  • Need boilerplate generation
  • Unsure about entry points
  • Prototyping ideas quickly

CONTRIBUTING.md (~300 lines)

Guidelines for contributing modules to the amplifier ecosystem.

Read when:

  • Ready to publish module
  • Want community feedback
  • Contributing to foundation
  • Following best practices

External Resources

Official Documentation

Related Skills

Community

Feedback

Found an error or have a suggestion? Please open an issue.