npm package: @stackwright-pro/otters
Description: Stackwright Pro Otter Raft - AI agents for enterprise features (CAC auth, API dashboards, government use cases)
Latest version: 0.3.0-alpha.1

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

```typescript
// 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

```bash
# Install Pro otters
npm install @stackwright-pro/otters

# Or with pnpm
pnpm add @stackwright-pro/otters
```

The postinstall script automatically installs Pro otters to `~/.code_puppy/agents/` for code-puppy discovery.

```bash
# 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:

```bash
node node_modules/@stackwright-pro/otters/scripts/install-agents.js
```

---

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

```bash
# 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-otter
```

---

## The 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)  │
└───────┬────────────────┘
        ▼
     USER
```

---

## Package 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.json
```

---

## Dependencies

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