@stackwright-pro/otters
v1.0.0-alpha.31
Published
Stackwright Pro Otter Raft - AI agents for enterprise features (CAC auth, API dashboards, government use cases)
Readme
@stackwright-pro/otters
🦦🦦 Pro Otter Ecosystem — Enterprise features that emerge when Pro otters join the raft.
Pro otters don't replace the OSS raft — they extend it. When a Pro otter joins, the entire ecosystem adapts. Page Otter discovers Dashboard Otter and offers live data. Theme Otter discovers CAC requirements and suggests secure variants. The raft self-organizes.
Dynamic Discovery
All Pro otters use list_agents() for dynamic discovery at startup. This pattern ensures:
- Automatic coordination — Pro otters find each other and OSS counterparts
- Graceful degradation — Fall back to MCP tools if an otter is missing
- Context-aware behavior — Adapt based on available teammates
// Every Pro otter discovers at startup
const agents = await list_agents();
const proOtters = agents.filter((a) => a.name.includes('pro-'));
const ossOtters = agents.filter((a) => a.name.includes('-otter') && !a.name.includes('pro-'));Pro + OSS Integration
When Pro otters join an OSS raft, the following capabilities emerge:
| OSS Otter | Pro Enhancement | What Emerges | | ------------- | --------------- | -------------------------------------- | | Brand Otter | Pro Specs | Brand validation against approved APIs | | Theme Otter | Pro Auth | CAC-enabled secure themes | | Page Otter | Pro Dashboard | Live data page generation | | Foreman Otter | Pro Delegation | Enterprise orchestration with fallback |
How Pro Otters Discover the OSS Raft
┌────────────────────────────────────────────────────────┐
│ DISCOVERY SEQUENCE │
├────────────────────────────────────────────────────────┤
│ │
│ code-puppy -i -a stackwright-pro-foreman-otter │
│ │
│ 1. Pro Foreman starts │
│ │
│ 2. list_agents() scans for otters: │
│ ├─► OSS Foreman detected: stackwright-foreman-otter │
│ ├─► Pro specialists detected: │
│ │ ├─► stackwright-pro-api-otter │
│ │ ├─► stackwright-pro-data-otter │
│ │ └─► stackwright-pro-dashboard-otter │
│ └─► OSS raft detected: │
│ ├─► stackwright-brand-otter │
│ ├─► stackwright-theme-otter │
│ └─► stackwright-page-otter │
│ │
│ 3. Pro Foreman delegates to OSS Foreman: │
│ "Delegating Brand → Theme → Pages to OSS Foreman" │
│ │
│ 4. Pro capabilities available for addition: │
│ "API dashboards, CAC auth, OIDC ready" │
│ │
└────────────────────────────────────────────────────────┘Installation
# Install Pro otters
npm install @stackwright-pro/otters
# Or with pnpm
pnpm add @stackwright-pro/ottersThe postinstall script automatically installs Pro otters to ~/.code_puppy/agents/ for code-puppy discovery.
# User has OSS otters installed
code-puppy -i -a stackwright-foreman-otter
# Found: Brand ✓, Theme ✓, Page ✓
# User installs Pro otters
npm install @stackwright-pro/otters
# Now with Pro discovery
code-puppy -i -a stackwright-foreman-otter
# Found: Brand ✓, Theme ✓, Page ✓
# Pro detected: API Otter ✓, Data Otter ✓, Dashboard Otter ✓
# "Live API dashboards now available - want some?"The OSS Foreman Otter orchestrates the base pipeline. When Pro otters are present, they extend it silently — offering capabilities without overwhelming users who don't need them.
If you need to re-run the installation:
node node_modules/@stackwright-pro/otters/scripts/install-agents.jsThe Pro + OSS Raft: What Emerges
When Pro otters combine with the OSS raft, these capabilities emerge:
| Combined Otters | Emergent Capability | | ---------------------------- | --------------------------------------- | | Page Otter + Dashboard Otter | "Add live data to this page?" | | Theme Otter + Pro Auth | "Enable CAC on this theme?" | | Brand Otter + Pro Specs | "Validate brand against approved APIs?" | | Foreman + All Pro Otters | Enterprise orchestration | | All Otters + Enterprise Mode | Security posture auto-detected |
The Pro Otter Raft
| Otter | Role | Output | | ------------------------ | -------------------- | ------------------------------------------------------------- | | 🦦🦦 Foreman Otter | Project coordinator | Orchestrates full-stack builds (delegates to unified Foreman) | | 🦦📡 API Otter | OpenAPI discovery | API entity types, endpoints | | 🦦📊 Dashboard Otter | Live data views | Typed API components | | 🦦🔗 Data Otter | Endpoint integration | ISR config, filters |
Pro vs OSS Integration
| Feature | OSS | Pro Integration | | ---------------------- | ------------ | ------------------------------ | | Brand discovery | ✅ OSS Otter | ✅ Pro can extend | | Theme design | ✅ OSS Otter | ✅ Enterprise themes available | | Page building | ✅ OSS Otter | ✅ Live data pages emerge | | API dashboards | ❌ | ✅ Discovered dynamically | | CAC auth | ❌ | ✅ Suggested when available | | Static site generation | ✅ | ✅ Extended with ISR |
The key insight: Pro doesn't replace OSS — it amplifies it. The OSS raft handles static content, SEO, and standard pages. Pro otters discover gaps in the raft and fill them with enterprise capabilities.
How Pro Integrates
The Discovery Flow
┌─────────────────────────────────────────────────────────────────────┐
│ CODE-PUPPY DISCOVERY │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ code-puppy -i -a stackwright-foreman-otter │
│ │
│ 1. Lists all available agents │
│ │
│ 2. Filters for OSS raft: │
│ ├─► Brand Otter ✓ │
│ ├─► Theme Otter ✓ │
│ ├─► Page Otter ✓ │
│ └─► Foreman Otter ✓ │
│ │
│ 3. Pro Foreman extends OSS Foreman: │
│ ├─► Adds API discovery hooks │
│ ├─► Adds ISR configuration │
│ └─► Adds Dashboard Otter coordination │
│ │
│ 4. Emergent suggestions: │
│ "API spec detected → Generate dashboard?" │
│ │
└─────────────────────────────────────────────────────────────────────┘Invoking Pro Otters
# Full-stack API build (via Foreman delegation)
code-puppy -i -a stackwright-foreman-otter
# API entity discovery (Pro otters work alongside OSS)
code-puppy -i -a stackwright-pro-api-otter
# Live dashboard generation (extends Page Otter)
code-puppy -i -a stackwright-pro-dashboard-otter
# ISR configuration (extends Data layer)
code-puppy -i -a stackwright-pro-data-otterThe Pro Pipeline
When a Pro otter joins an active OSS build:
User Request (with OpenAPI spec)
│
▼
┌────────────────────────┐
│ OSS Foreman Otter │ ◄── Base coordinator
│ (Pro-aware) │
└───────┬────────────────┘
│ discovers Pro capabilities
▼
┌────────────────────────┐
│ Pro API Otter │ ◄── OpenAPI → typed client
│ (entity discovery) │ (extends OSS build)
└───────┬────────────────┘
│ creates src/generated/*
▼
┌────────────────────────┐
│ Pro Dashboard Otter │ ◄── Live API data views
│ (emerges with data) │
└───────┬────────────────┘
│ creates pages/api/*
▼
┌────────────────────────┐
│ Pro Data Otter │ ◄── ISR + endpoint config
│ (configures refresh) │
└───────┬────────────────┘
▼
USERPackage Structure
@stackwright-pro/otters/
├── package.json
├── README.md
├── MCP_TOOLS.md # MCP tool documentation
├── PRO_OTTER_ARCHITECTURE.md # Architecture details
├── scripts/
│ └── install-agents.js # Postinstall script
├── stackwright-pro-foreman-otter.json
├── stackwright-pro-api-otter.json
├── stackwright-pro-dashboard-otter.json
└── stackwright-pro-data-otter.jsonDependencies
Pro otters require:
- @stackwright-pro/mcp — MCP server for API tooling
- @stackwright/otters — OSS otters (installed automatically)
Emergent Capabilities
When Pro otters join the raft, unexpected capabilities emerge:
| Discovery | Emergent Feature | | ---------------------------- | --------------------------------------- | | Page Otter + Dashboard Otter | "Add live data to this page?" | | Theme Otter + Pro Auth | "Enable CAC on this theme?" | | Brand Otter + Pro Specs | "Validate brand against approved APIs?" | | All otters + Enterprise | Security posture auto-detected |
License
MIT