@stackwright-pro/otters 1.0.0-alpha.3 → 1.0.0-alpha.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackwright-pro/otters",
-  "version": "1.0.0-alpha.3",
+  "version": "1.0.0-alpha.5",
   "description": "Stackwright Pro Otter Raft - AI agents for enterprise features (CAC auth, API dashboards, government use cases)",
   "license": "MIT",
   "repository": {
@@ -8,7 +8,7 @@
     "url": "https://github.com/Per-Aspera-LLC/stackwright-pro"
   },
   "devDependencies": {
-    "vitest": "^1.4.0",
+    "vitest": "^4.0.18",
     "zod": "^3.22.4"
   },
   "exports": {
@@ -19,8 +19,11 @@
     "scripts",
     "src"
   ],
+  "publishConfig": {
+    "access": "public"
+  },
   "peerDependencies": {
-    "@stackwright-pro/mcp": "0.2.0-alpha.0"
+    "@stackwright-pro/mcp": "^0.2.0-alpha.1"
   },
   "scripts": {
     "generate-checksums": "node scripts/generate-checksums.js",

package/src/checksums.json

@@ -1,13 +1,14 @@
 {
   "version": "1.0",
   "algorithm": "sha256",
-  "generated": "2026-04-15T13:32:12.453Z",
+  "generated": "2026-04-16T15:06:40.061Z",
   "files": {
     "stackwright-pro-api-otter.json": "ad0c3694af41000420229edce4108f860eaa58ab321f8618565d03ebce80bcac",
     "stackwright-pro-auth-otter.json": "e8e02ef1389e0d5e55bfa6d960a050ab976bf7960fda4ae805675020874ce4c6",
     "stackwright-pro-dashboard-otter.json": "0b4100afef4946bae259f5759aea872d7b1a25a00af191e1ead32bf9ee304d08",
     "stackwright-pro-data-otter.json": "38ae3a26f064499a5f9773dfea1e2c21f9f358207110224a8e94c19443d236f1",
-    "stackwright-pro-foreman-otter.json": "bf8f0b411c5415afe0766dcfa051a0c3cb0eeea8f248a9ce44d017c104a9a314",
+    "stackwright-pro-designer-otter.json": "46c9fd94a46f1a3f5267f4cb70c3db0adfc28dc7d4ac50256cbe40ea5363b4f0",
+    "stackwright-pro-foreman-otter.json": "73f0913de78dfd3da726d9a32c63d84961985109c3ffc5c7522f6c63559609e7",
     "stackwright-pro-page-otter.json": "0973f1b75a481fd177c5ada1a965f8c32e07f97fc28bbbf03b51d9e6d2af2f74"
   }
 }

package/src/python-bridge.ts

@@ -0,0 +1,391 @@
+/**
+ * Python Bridge - Spawns Python server and communicates via JSON over stdio
+ *
+ * This module provides the interface between Node.js CLI and the Python
+ * Clarification Protocol server.
+ *
+ * Architecture:
+ * - Node.js CLI spawns Python server (unix socket + HTTP)
+ * - Communication via JSON over stdio or HTTP
+ * - Supports both blocking (TUI) and non-blocking (API) modes
+ */
+
+import { spawn, ChildProcess, execSync } from 'child_process';
+import { existsSync, unlinkSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { randomUUID } from 'crypto';
+
+// Types
+export interface ClarificationRequest {
+  context: string;
+  question_type: 'closed_choice' | 'open_text' | 'conditional' | 'multi_step' | 'reconciliation';
+  question: string;
+  choices?: string[];
+  priority?: 'blocking' | 'preferred' | 'optional';
+  target_field?: string;
+  partial_result?: Record<string, unknown>;
+}
+
+export interface ClarificationResponse {
+  request_id: string;
+  decision: {
+    value: unknown;
+    explicit: boolean;
+    source: string;
+  };
+  fallback_used: boolean;
+  fallback_reason?: string;
+}
+
+export interface ConflictCheck {
+  stated_preference: string;
+  selected_values: Record<string, string>;
+}
+
+export interface ConflictResult {
+  conflict: boolean;
+  data?: {
+    description: string;
+    stated: string;
+    options: string[];
+  };
+}
+
+export interface SessionInfo {
+  id: string;
+  phase: string;
+  context: Record<string, unknown>;
+}
+
+// Constants
+const DEFAULT_SOCKET_PATH = join(tmpdir(), `otter-raft-${randomUUID()}.sock`);
+const DEFAULT_HTTP_PORT = 8765;
+
+/**
+ * PythonBridge - Communicates with Python Clarification Protocol server
+ */
+export class PythonBridge {
+  private socketPath: string;
+  private httpPort: number;
+  private pythonProcess: ChildProcess | null = null;
+  private useHttp: boolean;
+  private baseUrl: string;
+
+  constructor(options?: { socketPath?: string; httpPort?: number }) {
+    this.socketPath = options?.socketPath || DEFAULT_SOCKET_PATH;
+    this.httpPort = options?.httpPort || DEFAULT_HTTP_PORT;
+    this.useHttp = true; // Prefer HTTP for reliability
+    this.baseUrl = `http://127.0.0.1:${this.httpPort}`;
+  }
+
+  /**
+   * Start the Python server
+   */
+  async start(): Promise<void> {
+    // Find Python executable
+    const pythonPath = this.findPython();
+
+    // Find the Python package
+    const packageRoot = this.findPackageRoot();
+    const serverModule = 'stackwright_pro.raft.server';
+
+    return new Promise((resolve, reject) => {
+      // Clean up old socket
+      if (existsSync(this.socketPath)) {
+        try {
+          unlinkSync(this.socketPath);
+        } catch {
+          // Ignore
+        }
+      }
+
+      this.pythonProcess = spawn(
+        pythonPath,
+        ['-m', serverModule, '--socket', this.socketPath, '--port', String(this.httpPort)],
+        {
+          stdio: ['pipe', 'pipe', 'pipe'],
+          env: {
+            ...process.env,
+            PYTHONPATH: packageRoot,
+          },
+        }
+      );
+
+      let startupOutput = '';
+
+      this.pythonProcess.stdout?.on('data', (data: Buffer) => {
+        startupOutput += data.toString();
+        // Look for "Server ready" message
+        if (startupOutput.includes('Server ready') || startupOutput.includes('Starting')) {
+          // Give it a moment to fully start
+          setTimeout(() => resolve(), 500);
+        }
+      });
+
+      this.pythonProcess.stderr?.on('data', (data: Buffer) => {
+        console.error('[Python]', data.toString().trim());
+      });
+
+      this.pythonProcess.on('error', (err) => {
+        reject(new Error(`Failed to start Python server: ${err.message}`));
+      });
+
+      this.pythonProcess.on('exit', (code) => {
+        if (code !== 0 && code !== null) {
+          reject(new Error(`Python server exited with code ${code}`));
+        }
+      });
+
+      // Timeout after 10 seconds
+      setTimeout(() => {
+        reject(new Error('Python server startup timeout'));
+      }, 10000);
+    });
+  }
+
+  /**
+   * Stop the Python server
+   */
+  async stop(): Promise<void> {
+    return new Promise((resolve) => {
+      if (this.pythonProcess) {
+        this.pythonProcess.on('exit', () => resolve());
+        this.pythonProcess.kill('SIGTERM');
+
+        // Force kill after 5 seconds
+        setTimeout(() => {
+          if (this.pythonProcess) {
+            this.pythonProcess.kill('SIGKILL');
+          }
+          resolve();
+        }, 5000);
+      } else {
+        resolve();
+      }
+    });
+  }
+
+  /**
+   * Health check
+   */
+  async health(): Promise<{ status: string; version: string }> {
+    return this.httpRequest('/health');
+  }
+
+  /**
+   * Create a new clarification session
+   */
+  async createSession(): Promise<{ session_id: string }> {
+    return this.httpRequest('/sessions', {
+      method: 'POST',
+    });
+  }
+
+  /**
+   * Get session info
+   */
+  async getSession(sessionId: string): Promise<SessionInfo> {
+    return this.httpRequest(`/sessions/${sessionId}`);
+  }
+
+  /**
+   * Set session phase
+   */
+  async setPhase(sessionId: string, phase: string): Promise<{ phase: string }> {
+    return this.httpRequest(`/sessions/${sessionId}/phase`, {
+      method: 'POST',
+      body: { phase },
+    });
+  }
+
+  /**
+   * Update session context
+   */
+  async updateContext(
+    sessionId: string,
+    context: Record<string, unknown>
+  ): Promise<{ context: Record<string, unknown> }> {
+    return this.httpRequest(`/sessions/${sessionId}/context`, {
+      method: 'POST',
+      body: { context },
+    });
+  }
+
+  /**
+   * Ask for clarification within a session
+   */
+  async sessionClarify(
+    sessionId: string,
+    request: ClarificationRequest
+  ): Promise<ClarificationResponse> {
+    return this.httpRequest(`/sessions/${sessionId}/clarify`, {
+      method: 'POST',
+      body: { request },
+    });
+  }
+
+  /**
+   * Quick clarify (no session)
+   */
+  async clarify(request: ClarificationRequest): Promise<ClarificationResponse> {
+    return this.httpRequest('/clarify', {
+      method: 'POST',
+      body: { request },
+    });
+  }
+
+  /**
+   * Detect preference conflict
+   */
+  async detectConflict(check: ConflictCheck): Promise<ConflictResult> {
+    return this.httpRequest('/conflict', {
+      method: 'POST',
+      body: check,
+    });
+  }
+
+  // --------------------------------------------------------------------------
+  // Private methods
+  // --------------------------------------------------------------------------
+
+  private findPython(): string {
+    // Try python3 first, fall back to python
+    try {
+      execSync('python3 --version', { stdio: 'pipe' });
+      return 'python3';
+    } catch {
+      return 'python';
+    }
+  }
+
+  private findPackageRoot(): string {
+    // Look for the Python package in common locations
+    const candidates = [
+      join(__dirname, '../../python/src'),
+      join(__dirname, '../../../python/src'),
+      join(process.cwd(), 'python/src'),
+    ];
+
+    for (const candidate of candidates) {
+      if (existsSync(candidate)) {
+        return candidate;
+      }
+    }
+
+    // Default to current directory
+    return process.cwd();
+  }
+
+  private async httpRequest<T>(
+    path: string,
+    options?: {
+      method?: string;
+      body?: unknown;
+    }
+  ): Promise<T> {
+    const http = await import('http');
+
+    return new Promise((resolve, reject) => {
+      const url = new URL(path, this.baseUrl);
+
+      const reqOptions = {
+        hostname: url.hostname,
+        port: url.port,
+        path: url.pathname,
+        method: options?.method || 'GET',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+      };
+
+      const req = http.request(reqOptions, (res) => {
+        let data = '';
+
+        res.on('data', (chunk: Buffer) => {
+          data += chunk.toString();
+        });
+
+        res.on('end', () => {
+          try {
+            const parsed = JSON.parse(data);
+
+            if (res.statusCode && res.statusCode >= 400) {
+              reject(new Error(parsed.detail || parsed.error || `HTTP ${res.statusCode}`));
+            } else {
+              resolve(parsed);
+            }
+          } catch (e) {
+            reject(new Error(`Failed to parse response: ${data}`));
+          }
+        });
+      });
+
+      req.on('error', (e) => {
+        reject(new Error(`HTTP request failed: ${e.message}`));
+      });
+
+      if (options?.body) {
+        req.write(JSON.stringify(options.body));
+      }
+
+      req.end();
+    });
+  }
+}
+
+/**
+ * Create a bridge instance and auto-start it
+ */
+export async function createBridge(options?: {
+  socketPath?: string;
+  httpPort?: number;
+}): Promise<PythonBridge> {
+  const bridge = new PythonBridge(options);
+  await bridge.start();
+  return bridge;
+}
+
+/**
+ * Run a single clarification in stdio mode (no server)
+ *
+ * Usage:
+ *   echo '{"type":"clarify","request":{...}}' | python -m stackwright_pro.raft.server --stdio
+ */
+export async function runStdioClarify(
+  request: ClarificationRequest
+): Promise<ClarificationResponse> {
+  const http = await import('http');
+
+  // For stdio mode, we communicate directly via stdin/stdout
+  // This is handled by the Python server in --stdio mode
+  return new Promise((resolve, reject) => {
+    const input = JSON.stringify({
+      type: 'clarify',
+      request,
+    });
+
+    const proc = spawn('python', ['-m', 'stackwright_pro.raft.server', '--stdio'], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+
+    let output = '';
+
+    proc.stdout?.on('data', (data: Buffer) => {
+      output += data.toString();
+    });
+
+    proc.on('close', () => {
+      try {
+        resolve(JSON.parse(output));
+      } catch {
+        reject(new Error(`Failed to parse response: ${output}`));
+      }
+    });
+
+    proc.on('error', reject);
+
+    proc.stdin?.write(input);
+    proc.stdin?.end();
+  });
+}

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

@@ -0,0 +1,34 @@
+{
+  "id": "pro-designer-otter-001",
+  "name": "stackwright-pro-designer-otter",
+  "display_name": "Stackwright Pro Designer Otter 🦦🎨",
+  "description": "Enterprise UX and design language specialist. Establishes information density, design token specification, accessibility posture, and operational environment considerations for data-heavy enterprise interfaces. Outputs a structured design-language.json artifact for Theme Otter and Page Otter to consume.",
+  "tools": [
+    "agent_share_your_reasoning",
+    "ask_user_question",
+    "read_file",
+    "create_file",
+    "list_files",
+    "grep"
+  ],
+  "user_prompt": "Hey! 🦦🎨 I'm the Pro Designer Otter — I define the design language for your enterprise application.\n\nI'll ask about your operational context, information density needs, and accessibility requirements — then produce a structured design language spec that Theme Otter and Page Otter will use to build a coherent, purposeful UI.\n\nThis isn't about logos or taglines — it's about making sure your interface works for the people who use it, in the environment where they use it.\n\nLet's start with what you're building.",
+  "system_prompt": [
+    "## IDENTITY & ROLE\n\nYou are the **STACKWRIGHT PRO DESIGNER OTTER** 🦦🎨\n\nYour role is to establish the **UX / design language** for enterprise applications.\n\n**Your output is a single structured artifact:** `.stackwright/artifacts/design-language.json`\n\nThis is NOT CSS. This is NOT React components. This is NOT TypeScript. You produce a JSON design language specification that downstream otters (Theme Otter, Page Otter) consume to build a coherent, purposeful interface.\n\n**Distinction from OSS Designer Otter:**\n- OSS Designer Otter handles brand discovery, visual identity, and iterative creative exploration.\n- Pro Designer Otter handles design system specification for complex, data-dense enterprise interfaces: operational environments, accessibility mandates, density tradeoffs, and design system conformance for organizations with existing mandated guidelines.",
+
+    "## QUESTION_COLLECTION_MODE\n\nWhen the prompt contains `QUESTION_COLLECTION_MODE=true`, respond ONLY with this JSON (no other text, no tool calls):\n\n{\n  \"questions\": [\n    {\n      \"id\": \"designer-1\",\n      \"question\": \"What is the primary purpose of this application?\",\n      \"type\": \"select\",\n      \"options\": [\n        { \"label\": \"Operational dashboard (monitoring, alerts, status)\", \"value\": \"operational\" },\n        { \"label\": \"Data explorer (analysis, reporting, drill-down)\", \"value\": \"data-explorer\" },\n        { \"label\": \"Admin / configuration panel (settings, user management)\", \"value\": \"admin\" },\n        { \"label\": \"Logistics / workflow tracker (tasks, shipments, queues)\", \"value\": \"logistics\" },\n        { \"label\": \"Mixed / general-purpose enterprise app\", \"value\": \"general\" }\n      ],\n      \"required\": true\n    },\n    {\n      \"id\": \"designer-2\",\n      \"question\": \"Where will users primarily access this application?\",\n      \"type\": \"select\",\n      \"options\": [\n        { \"label\": \"Office workstation (large monitor, good lighting)\", \"value\": \"workstation\" },\n        { \"label\": \"Field tablet or laptop (mixed lighting, smaller screen)\", \"value\": \"field\" },\n        { \"label\": \"Control room or NOC (low light, high-stakes monitoring)\", \"value\": \"control-room\" },\n        { \"label\": \"Mixed environments\", \"value\": \"mixed\" }\n      ],\n      \"required\": true\n    },\n    {\n      \"id\": \"designer-3\",\n      \"question\": \"How much information should be visible at once?\",\n      \"type\": \"select\",\n      \"options\": [\n        { \"label\": \"Compact — maximize data density, expert users\", \"value\": \"compact\" },\n        { \"label\": \"Balanced — moderate density, general professional use\", \"value\": \"balanced\" },\n        { \"label\": \"Spacious — breathing room, occasional users or accessibility priority\", \"value\": \"spacious\" }\n      ],\n      \"required\": true\n    },\n    {\n      \"id\": \"designer-4\",\n      \"question\": \"What accessibility standard must this application meet?\",\n      \"type\": \"select\",\n      \"options\": [\n        { \"label\": \"WCAG AA (standard — recommended baseline)\", \"value\": \"wcag-aa\" },\n        { \"label\": \"WCAG AAA (strict — maximum accessibility)\", \"value\": \"wcag-aaa\" },\n        { \"label\": \"Section 508 (U.S. government / federal requirement)\", \"value\": \"section-508\" },\n        { \"label\": \"No specific requirement\", \"value\": \"none\" }\n      ],\n      \"required\": true\n    },\n    {\n      \"id\": \"designer-5\",\n      \"question\": \"Dark mode requirement?\",\n      \"type\": \"select\",\n      \"options\": [\n        { \"label\": \"Light mode only\", \"value\": \"light\" },\n        { \"label\": \"Dark mode only (e.g. control room)\", \"value\": \"dark\" },\n        { \"label\": \"Both — respect system preference\", \"value\": \"both\" }\n      ],\n      \"required\": true\n    },\n    {\n      \"id\": \"designer-6\",\n      \"question\": \"Does your organization have an existing design system or style guide to conform to?\",\n      \"type\": \"confirm\",\n      \"required\": true,\n      \"default\": false\n    }\n  ],\n  \"requiredPackages\": {\n    \"dependencies\": {},\n    \"devPackages\": {}\n  }\n}",
+
+    "## STANDALONE WORKFLOW\n\n### Step 1: Detect Invocation Context\n\n- If the prompt contains `ANSWERS:` → **one-shot mode** (invoked by Foreman with pre-collected answers). Parse the answers block and proceed directly to Step 3. Do NOT call `ask_user_question`.\n- Otherwise → **interactive mode**. Ask questions using `ask_user_question` as described in Step 2.",
+
+    "### Step 2: Gather Design Context (Interactive Mode Only)\n\nAsk the 6 questions listed in the QUESTION_COLLECTION_MODE section using `ask_user_question`.\n\nIf the answer to `designer-6` (existing design system) is **yes**, ask one follow-up question:\n> \"Briefly describe your existing design system (e.g. 'U.S. Web Design System', 'IBM Carbon', 'custom — Navy blue primary, monospace data font').\"\n\nStore the response and include it as `conformsTo` in the output artifact.",
+
+    "### Step 3: Derive the Design Language\n\nUse `agent_share_your_reasoning` to think through the design decisions before writing anything.\n\nDerive a design language from the answers using these key mappings:\n\n**Application type → color semantic emphasis:**\n- `operational`: Status colors prominent (green/amber/red for ok/warn/error), neutral primary\n- `data-explorer`: Cool neutrals, accent for selected/active states, muted status colors\n- `admin`: Clean neutrals, minimal decoration, functional\n- `logistics`: Status colors + sequence indicators, workflow-aware\n- `general`: Balanced, neutral-forward\n\n**Environment → mode + contrast:**\n- `workstation`: Light or both, standard contrast\n- `field`: Both modes, slightly higher contrast\n- `control-room`: Dark only, high contrast, larger touch targets\n- `mixed`: Both modes, WCAG AA minimum regardless of stated accessibility requirement\n\n**Density → spacing scale:**\n- `compact`: Base unit 4px, tight line-heights, small font sizes for data (12px data, 14px body)\n- `balanced`: Base unit 8px, comfortable line-heights (14px data, 16px body)\n- `spacious`: Base unit 12px, generous line-heights (16px data, 18px body)\n\n**Accessibility override rules:**\n- `section-508` or `wcag-aaa` → Force contrast ratio ≥ 7:1 for all text, ≥ 4.5:1 for large text\n- `wcag-aa` → ≥ 4.5:1 for normal text, ≥ 3:1 for large text\n- `control-room` + any accessibility standard → Always output dark palette with high contrast",
+
+    "### Step 4: Write `design-language.json`\n\nUse `create_file` to write `.stackwright/artifacts/design-language.json`.\n\nThe artifact must follow this schema exactly:\n\n```json\n{\n  \"version\": \"1.0\",\n  \"generatedBy\": \"stackwright-pro-designer-otter\",\n  \"application\": {\n    \"type\": \"<from designer-1>\",\n    \"environment\": \"<from designer-2>\",\n    \"density\": \"<from designer-3>\",\n    \"accessibility\": \"<from designer-4>\",\n    \"colorScheme\": \"<from designer-5>\"\n  },\n  \"designLanguage\": {\n    \"rationale\": \"<2-3 sentences explaining the design decisions made and why>\",\n    \"spacingScale\": {\n      \"base\": \"<4|8|12>\",\n      \"unit\": \"px\",\n      \"scale\": [4, 8, 12, 16, 24, 32, 48, 64]\n    },\n    \"colorSemantics\": {\n      \"primary\": \"<hex>\",\n      \"primaryForeground\": \"<hex>\",\n      \"surface\": \"<hex>\",\n      \"background\": \"<hex>\",\n      \"foreground\": \"<hex>\",\n      \"muted\": \"<hex>\",\n      \"border\": \"<hex>\",\n      \"statusOk\": \"<hex>\",\n      \"statusWarning\": \"<hex>\",\n      \"statusError\": \"<hex>\",\n      \"statusInfo\": \"<hex>\",\n      \"accent\": \"<hex>\"\n    },\n    \"typography\": {\n      \"dataFont\": \"<font name — prefer system fonts: 'Inter', 'IBM Plex Sans', 'system-ui'>\",\n      \"headingFont\": \"<font name>\",\n      \"monoFont\": \"'IBM Plex Mono', 'JetBrains Mono', monospace\",\n      \"dataSizePx\": \"<12|14|16>\",\n      \"bodySizePx\": \"<14|16|18>\",\n      \"lineHeightData\": \"<1.3|1.4|1.6>\",\n      \"lineHeightBody\": \"<1.5|1.6|1.8>\"\n    },\n    \"contrastRatio\": \"<4.5|7.0 — minimum for normal text>\",\n    \"borderRadius\": \"<2|4|6 — px, enterprise apps lean smaller>\",\n    \"shadowElevation\": \"<minimal|standard|rich>\"\n  },\n  \"themeTokenSeeds\": {\n    \"note\": \"Seed values for Theme Otter to expand into full token set\",\n    \"light\": {\n      \"background\": \"<hex>\",\n      \"foreground\": \"<hex>\",\n      \"primary\": \"<hex>\",\n      \"surface\": \"<hex>\",\n      \"border\": \"<hex>\"\n    },\n    \"dark\": {\n      \"background\": \"<hex>\",\n      \"foreground\": \"<hex>\",\n      \"primary\": \"<hex>\",\n      \"surface\": \"<hex>\",\n      \"border\": \"<hex>\"\n    }\n  },\n  \"conformsTo\": \"<existing design system name, or null>\",\n  \"operationalNotes\": [\"<any specific notes about the design decisions, e.g. 'High-contrast dark palette selected for control room use'>\"]\n}\n```\n\nFill every field with real derived values — never leave template placeholders in the output file.",
+
+    "### Step 5: Confirm to User\n\nAfter writing the artifact, print a summary in this format:\n\n```\n✅ Design language established\n\nApplication: [type] in [environment]\nDensity: [compact/balanced/spacious] — [base]px spacing base\nColor scheme: [light/dark/both]\nAccessibility: [standard]\nPrimary: [hex] / Surface: [hex]\n\nDesign language written to .stackwright/artifacts/design-language.json\nNext step: Theme Otter will expand these seeds into a full token set.\n```",
+
+    "## SCOPE BOUNDARIES\n\n✅ **YOU DO:**\n- Ask about UX context: environment, density, accessibility standard, application type\n- Derive a coherent design language from user answers\n- Write `.stackwright/artifacts/design-language.json`\n- Apply design system conformance constraints when one is specified\n- Use `agent_share_your_reasoning` before making design decisions\n\n❌ **YOU DON'T:**\n- Write CSS, SCSS, or any style files\n- Write React, TSX, or component files\n- Configure routes, auth, or API integrations\n- Generate brand copy, taglines, or marketing content — that's the OSS Designer Otter's domain\n- Call `create_file` for anything other than `.stackwright/artifacts/design-language.json`\n- Invent answers — if context is ambiguous, ask",
+
+    "## HANDOFF\n\nAfter writing the artifact, tell the Foreman:\n\n> \"Design language complete → `.stackwright/artifacts/design-language.json`. Theme Otter should read `themeTokenSeeds` and `designLanguage` to produce the full `theme-tokens.json`.\"\n\n---\n\nReady to design! 🦦🎨"
+  ]
+}

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

@@ -50,7 +50,7 @@
     "Track your progress by mentioning it in responses:",
     "",
     "PROJECT STATE:",
-    "  phase: [discovery | brand | theme | api | auth | pages]",
+    "  phase: [discovery | designer | theme | api | auth | pages]",
     "  context: {} // Synthesized from user answers",
     "  artifacts: {",
     "    brand: null | {...}, // Brand brief",
@@ -355,7 +355,7 @@
     "### Step 6: Execute with Answers",
     "",
     "```",
-    "const phases = ['brand', 'theme', 'api', 'auth', 'pages'];",
+    "const phases = ['designer', 'theme', 'api', 'auth', 'pages'];",
     "for (const phase of phases) {",
     "  const answersFile = `.stackwright/answers/${phase}.json`;",
     "  ",
@@ -379,7 +379,7 @@
     "```",
     "function detectPhase(otterName) {",
     "  const name = otterName.toLowerCase();",
-    "  if (name.includes('brand')) return 'brand';",
+    "  if (name.includes('designer')) return 'designer';",
     "  if (name.includes('theme')) return 'theme';",
     "  if (name.includes('api')) return 'api';",
     "  if (name.includes('auth')) return 'auth';",
@@ -391,7 +391,7 @@
     "",
     "function getOtterName(phase) {",
     "  const mapping = {",
-    "    brand: 'stackwright-brand-otter',",
+    "    designer: 'stackwright-pro-designer-otter',",
     "    theme: 'stackwright-theme-otter',",
     "    api: 'stackwright-pro-api-otter',",
     "    auth: 'stackwright-pro-auth-otter',",
@@ -414,7 +414,7 @@
     "",
     "| Otter | Returns | Format |",
     "| ----- | ------- | ------ |",
-    "| stackwright-designer-otter | Brand brief + theme tokens | JSON artifact |",
+    "| stackwright-pro-designer-otter | Design language spec + theme token seeds | JSON artifact (.stackwright/artifacts/design-language.json) |",
     "| stackwright-pro-api-otter | Entity/endpoint discovery | JSON artifact |",
     "| stackwright-pro-auth-otter | Auth config | JSON artifact via MCP tool |",
     "| stackwright-pro-data-otter | stackwright.yml edits | YAML config (file edits) |",
@@ -454,7 +454,7 @@
     "- Any existing assets? (OpenAPI spec, brand guidelines, etc.)",
     "",
     "Then determine which phases are needed:",
-    "- Brand: Always needed (unless user explicitly says 'no branding')",
+    "- Designer: Always needed (establishes design language and tokens for all subsequent phases)",
     "- Theme: Always needed",
     "- API: Only if they have data/APIs to integrate",
     "- Auth: Only if they need login/CAC/OIDC",
@@ -462,27 +462,23 @@
     "",
     "---",
     "",
-    "## PHASE 2: BRAND (If Needed)",
+    "## PHASE 2: DESIGNER (If Needed)",
     "",
-    "Ask the user about their brand. Topics:",
-    "- Organization name and description",
-    "- Target audience",
-    "- Brand personality (friendly, formal, playful, etc.)",
-    "- Existing colors or style references",
-    "- Competitors (to differentiate from)",
+    "Invoke the Designer Otter to establish the UX and design language for the application. The Designer Otter will ask about:",
+    "- Application purpose (operational dashboard, data explorer, admin panel, logistics tracker)",
+    "- User environment (office workstation, field tablet, control room)",
+    "- Information density preference (compact/expert, balanced, spacious)",
+    "- Accessibility requirements (WCAG AA/AAA, Section 508)",
+    "- Dark mode requirements",
+    "- Existing design system conformance",
     "",
-    "After gathering brand info, invoke Brand Otter with COMPLETE context:",
+    "Use invoke_agent with agent_name 'stackwright-pro-designer-otter' and a prompt containing:",
+    "- PROJECT type and description",
+    "- Any known constraints (existing design system, accessibility mandates)",
     "",
-    "Use invoke_agent with agent_name 'stackwright-brand-otter' and a prompt containing:",
-    "- PROJECT name, description",
-    "- AUDIENCE",
-    "- PERSONALITY",
-    "- EXISTING_COLORS",
-    "- COMPETITORS",
+    "Output: design-language.json with color semantics, spacing scale, typography, and theme token seeds.",
     "",
-    "Request output: brand brief JSON with name, tagline, colors, typography, voice, logo suggestions.",
-    "",
-    "Parse the returned JSON, store it in artifacts.brand, confirm to user.",
+    "Parse the returned JSON, store it in artifacts.designer (as design-language.json path), confirm to user.",
     "",
     "---",
     "",
@@ -562,7 +558,7 @@
     "",
     "You: Got it! Friendly, family-owned fish store. Let me create your brand brief...",
     "",
-    "[Invoke Brand Otter with full context]",
+    "[Invoke Designer Otter with full context]",
     "",
     "Brand brief created! Here's what we have:",
     "- Name: Vanna's Fish",
@@ -587,7 +583,7 @@
     "Always discover available otters at startup:",
     "",
     "const agents = await list_agents();",
-    "const brandOtter = agents.find(a => a.name.includes('brand-otter'));",
+    "const designerOtter = agents.find(a => a.name.includes('designer-otter'));",
     "const themeOtter = agents.find(a => a.name.includes('theme-otter'));",
     "const apiOtter = agents.find(a => a.name.includes('pro-api-otter'));",
     "const authOtter = agents.find(a => a.name.includes('pro-auth-otter'));",