@stackwright-pro/otters 0.2.3 → 0.3.0-alpha.0

package/README.md

@@ -1,21 +1,99 @@
 # @stackwright-pro/otters
 
-🦦🦦 **Stackwright Pro Otter Raft** — AI agents for full-stack API integration.
+🦦🦦 **Pro Otter Ecosystem** — Enterprise features that emerge when Pro otters join the raft.
 
-A coordinated team of specialized AI agents (otters) that extend the OSS otter raft with API-first capabilities, live data dashboards, and enterprise auth integration.
+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
+
+# 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
@@ -24,80 +102,128 @@ 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 |
-| 🦦📡 **API Otter** | OpenAPI discovery | API entity types, endpoints |
-| 🦦📊 **Dashboard Otter** | Live data views | Typed API components |
-| 🦦🔗 **Data Otter** | Endpoint integration | ISR config, filters |
+| 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.
 
 ---
 
-## Pro vs OSS Otters
+## 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
 
-| Feature | OSS | Pro |
-|---------|-----|-----|
-| Static site generation | ✅ | ✅ |
-| OpenAPI integration | ❌ | ✅ |
-| Live data dashboards | ❌ | ✅ |
-| Zod schema generation | ❌ | ✅ |
-| Typed API clients | ❌ | ✅ |
-| ISR configuration | ❌ | ✅ |
+# ISR configuration (extends Data layer)
+code-puppy -i -a stackwright-pro-data-otter
+```
 
 ---
 
-## How It Works
+## The Pro Pipeline
 
-### The Pro Pipeline
+When a Pro otter joins an active OSS build:
 
 ```
 User Request (with OpenAPI spec)
      │
      ▼
 ┌────────────────────────┐
-│  Pro Foreman Otter     │ ◄── Entry point (extends OSS Foreman)
-│  "Starting API build..."│
+│  OSS Foreman Otter     │ ◄── Base coordinator
+│  (Pro-aware)           │
 └───────┬────────────────┘
-        │
+        │ discovers Pro capabilities
         ▼
 ┌────────────────────────┐
-│  API Otter             │ ◄── OpenAPI → typed client
-│  (entity discovery)   │
+│  Pro API Otter          │ ◄── OpenAPI → typed client
+│  (entity discovery)    │   (extends OSS build)
 └───────┬────────────────┘
         │ creates src/generated/*
         ▼
 ┌────────────────────────┐
-│  Dashboard Otter       │ ◄── Live API data views
-│  (components)          │
+│  Pro Dashboard Otter   │ ◄── Live API data views
+│  (emerges with data)   │
 └───────┬────────────────┘
         │ creates pages/api/*
         ▼
 ┌────────────────────────┐
-│  Data Otter            │ ◄── ISR + endpoint config
-│  (filters, refresh)    │
+│  Pro Data Otter        │ ◄── ISR + endpoint config
+│  (configures refresh)  │
 └───────┬────────────────┘
         ▼
      USER
 ```
 
-### Invoking Pro Otters
-
-```bash
-# Full-stack API build
-code-puppy -i -a stackwright-pro-foreman-otter
-
-# API entity discovery
-code-puppy -i -a stackwright-pro-api-otter
-
-# Live dashboard generation
-code-puppy -i -a stackwright-pro-dashboard-otter
-
-# ISR configuration
-code-puppy -i -a stackwright-pro-data-otter
-```
-
 ---
 
 ## Package Structure
@@ -106,10 +232,10 @@ code-puppy -i -a stackwright-pro-data-otter
 @stackwright-pro/otters/
 ├── package.json
 ├── README.md
-├── MCP_TOOLS.md              # MCP tool documentation
-├── PRO_OTTER_ARCHITECTURE.md # Architecture details
+├── MCP_TOOLS.md                  # MCP tool documentation
+├── PRO_OTTER_ARCHITECTURE.md     # Architecture details
 ├── scripts/
-│   └── install-agents.js     # Postinstall script
+│   └── install-agents.js         # Postinstall script
 ├── stackwright-pro-foreman-otter.json
 ├── stackwright-pro-api-otter.json
 ├── stackwright-pro-dashboard-otter.json
@@ -127,6 +253,19 @@ Pro otters require:
 
 ---
 
+## 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

package/package.json

@@ -1,19 +1,25 @@
 {
   "name": "@stackwright-pro/otters",
-  "version": "0.2.3",
-  "description": "Stackwright Pro Otter Raft - AI agents for full-stack API integration",
+  "version": "0.3.0-alpha.0",
+  "description": "Stackwright Pro Otter Raft - AI agents for enterprise features (CAC auth, API dashboards, government use cases)",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/Per-Aspera-LLC/stackwright-pro"
   },
+  "exports": {
+    "./src": "./src",
+    "./pro-foreman": "./src/stackwright-pro-foreman-otter.json"
+  },
   "files": [
-    "scripts"
+    "scripts",
+    "src"
   ],
   "peerDependencies": {
     "@stackwright-pro/mcp": "*"
   },
   "scripts": {
-    "postinstall": "node scripts/install-agents.js"
+    "postinstall": "node scripts/install-agents.js",
+    "test": "echo 'Pro otters are configuration-only'"
   }
 }

package/scripts/install-agents.js

@@ -12,22 +12,25 @@ const AGENTS_DIR = path.join(os.homedir(), '.code_puppy', 'agents');
 
 // Resolve package root relative to this script's location
 const scriptDir = __dirname;
-const packageRoot = scriptDir.endsWith('/scripts') 
+const packageRoot = scriptDir.endsWith('/scripts')
   ? path.dirname(scriptDir)  // Running from within the package
   : path.join(scriptDir, 'packages', 'otters');  // Running from monorepo root
 
+// All Pro otters are in the src/ directory
+const OTTERS_DIR = path.join(packageRoot, 'src');
+
 async function installAgents() {
   try {
     // Ensure ~/.code_puppy/agents/ exists
     await fs.promises.mkdir(AGENTS_DIR, { recursive: true });
 
-    // Copy all JSON files from package root to ~/.code_puppy/agents/
-    const files = await fs.promises.readdir(packageRoot);
+    // Copy all JSON files from src/ to ~/.code_puppy/agents/
+    const files = await fs.promises.readdir(OTTERS_DIR);
 
     let installedCount = 0;
     for (const file of files) {
       if (file.endsWith('-otter.json')) {
-        const srcPath = path.join(packageRoot, file);
+        const srcPath = path.join(OTTERS_DIR, file);
         const destPath = path.join(AGENTS_DIR, file);
 
         await fs.promises.copyFile(srcPath, destPath);

package/src/stackwright-pro-api-otter.json

@@ -0,0 +1,32 @@
+{
+  "id": "pro-api-otter-001",
+  "name": "stackwright-pro-api-otter",
+  "display_name": "Stackwright Pro API Otter 🦦",
+  "description": "Analyzes API specs and extracts entity definitions",
+  "tools": ["agent_run_shell_command", "list_files", "cp_list_files", "cp_read_file"],
+  "user_prompt": "Hey! 🦦 I'm the API Otter. Give me an OpenAPI spec path and I'll extract what entities and endpoints it exposes.",
+  "system_prompt": [
+    "## YOUR JOB",
+    "Analyze API specs. Extract entities, schemas, and endpoints.",
+    "",
+    "## SPEC TYPES YOU HANDLE",
+    "- OpenAPI 3.x (YAML or JSON)",
+    "- GraphQL schemas",
+    "- AsyncAPI (Kafka events)",
+    "",
+    "## YOUR WORKFLOW",
+    "1. Accept spec path from user or find in project",
+    "2. Parse spec file (use cp_read_file for local, curl for URLs)",
+    "3. Extract: endpoints, schemas, auth requirements",
+    "4. List available entities for user selection",
+    "",
+    "## OUTPUT FORMAT",
+    "Report findings as a simple list:",
+    "- Entities: {list}",
+    "- Auth: {type}",
+    "- Base URL: {url}",
+    "",
+    "## PASS TO DATA OTTER",
+    "After analysis, invoke pro-data-otter to wire collections."
+  ]
+}