Stackwright Otter Agents: AI-assisted site generation pipeline

[perasperaactual]

Overview

Four specialized AI agents that orchestrate Stackwright site generation from conversation to deployed pages:

• 🦦🏗️ Foreman Otter (otters/stackwright-foreman-otter.json) - Coordinator and user-facing interface
• 🦦🎨 Brand Otter (otters/stackwright-brand-otter.json) - Brand discovery through conversation
• 🦦🌈 Theme Otter (otters/stackwright-theme-otter.json) - Visual design (colors, typography, spacing)
• 🦦📄 Page Otter (otters/stackwright-page-otter.json) - Content architecture and page composition

Pipeline

User: "Build me a law firm website"
  ↓
Foreman Otter:
  1. Scaffolds project (stackwright_scaffold_project MCP tool)
  2. Invokes Brand Otter → BRAND_BRIEF.md
  3. Invokes Theme Otter → stackwright.yml
  4. Invokes Page Otter → pages/*.yml
  5. Visual verification (render home page)
  6. Handoff to user with next steps

Current Status

✅ Completed:

• Created otter agent JSON configs
• Documented architecture (OTTER_ARCHITECTURE.md, OTTERS_SHIPPED.md)
• Fixed foreman scaffolding to use MCP tools instead of global CLI
• Added otter files to repository (otters/ directory)
• Created installation/setup guide (otters/README.md)
• Updated documentation to reflect MCP-first approach

🔧 Next Steps:

• Test end-to-end workflow (brand → theme → pages)
• Build 3-5 diverse example sites using the otters
• Capture learnings and edge cases
• Refine handoff protocol between otters
• Add Collection Otter for blogs/docs (Phase 2)

Key Architectural Decisions

1. MCP-First Architecture

The Foreman Otter uses MCP tools (stackwright_scaffold_project, stackwright_validate_site) instead of shell commands. This works without requiring global CLI installation and is project-aware.

2. Sequential, Not Parallel

Otters are invoked sequentially because of dependencies:

• Theme Otter needs BRAND_BRIEF.md from Brand Otter
• Page Otter needs BRAND_BRIEF.md + stackwright.yml from Theme Otter

3. File-Based Handoffs

State is preserved via files (BRAND_BRIEF.md, stackwright.yml, pages/*.yml) rather than in-memory, enabling:

• Pausable workflows (stop after brand, resume later)
• Human readability (users can edit the brief manually)
• Git-friendly version control
• Debuggable intermediate state

4. Separation of Concerns

Each otter owns one domain:

• Brand = Strategy layer
• Theme = Design layer
• Page = Content layer

This follows SOLID principles and makes each otter independently reusable.

Related Files

Agent Configs

• otters/stackwright-foreman-otter.json
• otters/stackwright-brand-otter.json
• otters/stackwright-theme-otter.json
• otters/stackwright-page-otter.json
• otters/README.md

Documentation

• OTTERS_SHIPPED.md - Implementation notes and success metrics
• OTTER_ARCHITECTURE.md - Architecture diagrams and data flow
• PHILOSOPHY.md - Why the otter architecture exists

MCP Integration

• packages/mcp/src/tools/project.ts - stackwright_scaffold_project tool
• packages/mcp/src/tools/site.ts - Site validation tools
• packages/mcp/src/tools/pages.ts - Page authoring tools
• packages/mcp/src/tools/render.ts - Visual rendering tools

Branch

Work completed in: feat/otter-agents-scaffold-fix

Success Criteria

A successful otter-built site includes:

• ✅ BRAND_BRIEF.md in project root
• ✅ stackwright.yml with customTheme section
• ✅ pages/*.yml for all requested pages
• ✅ All YAML validates (no schema errors)
• ✅ Screenshots showing home page (desktop + mobile)
• ✅ User can run pnpm dev and see their site

References

• MCP scaffolding tool: packages/mcp/src/tools/project.ts
• CLI programmatic API: packages/cli/src/index.ts
• Content type schemas: packages/types/src/types/