@stackwright-pro/otters 1.0.0-alpha.6 → 1.0.0-alpha.60

package/LICENSE

@@ -0,0 +1,21 @@
+PROPRIETARY SOFTWARE LICENSE
+
+Copyright (c) 2024-2026 Per Aspera LLC. All Rights Reserved.
+
+This software and associated documentation files (the "Software") are the
+proprietary and confidential property of Per Aspera LLC ("Company").
+
+RESTRICTIONS: You may not use, copy, modify, merge, publish, distribute,
+sublicense, sell, or otherwise exploit this Software or any portion thereof
+without the express prior written consent of the Company.
+
+GOVERNMENT USE: Use, duplication, or disclosure by the U.S. Government is
+subject to restrictions as set forth in FAR 52.227-19 (Commercial Computer
+Software - Restricted Rights) and DFARS 252.227-7013 (Rights in Technical
+Data and Computer Software), as applicable.
+
+THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED. IN NO EVENT SHALL THE COMPANY BE LIABLE FOR ANY CLAIM, DAMAGES, OR
+OTHER LIABILITY ARISING FROM THE USE OF THE SOFTWARE.
+
+For licensing inquiries: legal@peraspera.com

package/README.md

@@ -118,12 +118,13 @@ When Pro otters combine with the OSS raft, these capabilities emerge:
 
 ## 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                                           |
+| 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                                                             |
+| `stackwright-pro-domain-expert-otter` | Utility              | Answers specialist questions from the use case document in non-interactive mode |
 
 ---
 

package/package.json

@@ -1,19 +1,20 @@
 {
   "name": "@stackwright-pro/otters",
-  "version": "1.0.0-alpha.6",
+  "version": "1.0.0-alpha.60",
   "description": "Stackwright Pro Otter Raft - AI agents for enterprise features (CAC auth, API dashboards, government use cases)",
-  "license": "MIT",
+  "license": "SEE LICENSE IN LICENSE",
   "repository": {
     "type": "git",
     "url": "https://github.com/Per-Aspera-LLC/stackwright-pro"
   },
   "devDependencies": {
-    "vitest": "^4.0.18",
-    "zod": "^3.22.4"
+    "vitest": "^4.1.8",
+    "zod": "^4.4.3"
   },
   "exports": {
     "./src": "./src",
-    "./pro-foreman": "./src/stackwright-pro-foreman-otter.json"
+    "./pro-foreman": "./src/stackwright-pro-foreman-otter.json",
+    "./pro-workflow": "./src/stackwright-pro-form-wizard-otter.json"
   },
   "files": [
     "scripts",
@@ -23,7 +24,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@stackwright-pro/mcp": "^0.2.0-alpha.1"
+    "@stackwright-pro/mcp": "^0.2.0-alpha.92"
   },
   "scripts": {
     "generate-checksums": "node scripts/generate-checksums.js",

package/scripts/generate-checksums.js

@@ -35,7 +35,6 @@ async function generateChecksums() {
   const manifest = {
     version: '1.0',
     algorithm: 'sha256',
-    generated: new Date().toISOString(),
     files,
   };
 

package/scripts/install-agents.js

@@ -8,14 +8,17 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 
-const AGENTS_DIR = path.join(os.homedir(), '.code_puppy', 'agents');
+// Allow test overrides via env vars — production paths are the default.
+// STACKWRIGHT_AGENTS_DIR: override destination (normally ~/.code_puppy/agents/)
+// STACKWRIGHT_OTTERS_SRC_DIR: override source (normally <package>/src/)
+const AGENTS_DIR = process.env.STACKWRIGHT_AGENTS_DIR || path.join(os.homedir(), '.code_puppy', 'agents');
 
 // Resolve package root relative to this script's location
 const scriptDir = __dirname;
 const packageRoot = path.resolve(scriptDir, '..');
 
 // All Pro otters are in the src/ directory
-const srcDir = path.join(packageRoot, 'src');
+const srcDir = process.env.STACKWRIGHT_OTTERS_SRC_DIR || path.join(packageRoot, 'src');
 
 async function installAgents() {
   try {

package/scripts/launch-raft.cjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+
+// ⚠️ DEPRECATED — This launcher has been replaced by @stackwright-pro/raft.
+// Run: npx @stackwright-pro/raft
+// This file is kept for users who may have cached a previous install.
+// It will be removed in a future release.
+
+console.error('⚠️  launch-raft in @stackwright-pro/otters is deprecated.');
+console.error('   Use: npx @stackwright-pro/raft');
+console.error('');
+console.error('   Install: npm install -g @stackwright-pro/raft');
+console.error('   Or run directly: npx @stackwright-pro/raft');
+process.exit(1);

package/scripts/strip-artifact-schemas.cjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+/**
+ * strip-artifact-schemas.cjs
+ *
+ * Removes hardcoded artifact schema JSON blocks from specialist otter system_prompts.
+ * These are now injected dynamically via build_specialist_prompt (REQUIRED_ARTIFACT_SCHEMA).
+ *
+ * Run: node packages/otters/scripts/strip-artifact-schemas.cjs
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const OTTERS_DIR = path.join(__dirname, '..', 'src');
+const REFERENCE_LINE =
+  '**Artifact shape:** See the **REQUIRED_ARTIFACT_SCHEMA** section in your prompt for the canonical artifact shape. Use it when calling `stackwright_pro_validate_artifact`.';
+
+function stripArtifactSchemaFromArray(promptArray) {
+  // Strategy: find the index of the ```json opening fence,
+  // then find the matching closing ``` fence.
+  // Replace everything from the fence through the closing fence + surrounding context
+  // with the REFERENCE_LINE.
+
+  const result = [];
+  let i = 0;
+  let stripped = false;
+
+  while (i < promptArray.length) {
+    const item = promptArray[i];
+
+    // Detect start of a JSON code block fence
+    if (typeof item === 'string' && item.trim() === '```json') {
+      // Find the closing fence
+      let j = i + 1;
+      while (j < promptArray.length && promptArray[j].trim() !== '```') {
+        j++;
+      }
+      // j now points to the closing ``` (or end of array)
+
+      // Replace this entire block with the reference line
+      // (but only the first JSON block per otter — the artifact schema block)
+      if (!stripped) {
+        result.push(REFERENCE_LINE);
+        stripped = true;
+      }
+
+      // Skip past the closing fence
+      i = j + 1;
+      continue;
+    }
+
+    result.push(item);
+    i++;
+  }
+
+  return result;
+}
+
+function stripArtifactSchemaFromString(str) {
+  // For cases where the schema is embedded in a longer string as a ```json...``` block
+  // Replace the first ```json ... ``` block with the reference line
+  const jsonFenceRegex = /```json[\s\S]*?```/;
+  if (jsonFenceRegex.test(str)) {
+    return str.replace(jsonFenceRegex, REFERENCE_LINE);
+  }
+  return str;
+}
+
+function processOtterFile(filePath) {
+  const raw = fs.readFileSync(filePath, 'utf-8');
+  const otter = JSON.parse(raw);
+
+  if (!Array.isArray(otter.system_prompt)) {
+    console.log(`  ⚠️  ${path.basename(filePath)}: system_prompt is not an array — skipping`);
+    return false;
+  }
+
+  // Check if the artifact schema block is spread across array elements (```json as its own element)
+  // or embedded within a longer string
+  const hasFenceAsElement = otter.system_prompt.some(
+    (s) => typeof s === 'string' && s.trim() === '```json'
+  );
+
+  const hasEmbeddedFence = otter.system_prompt.some(
+    (s) => typeof s === 'string' && s.includes('```json')
+  );
+
+  let modified = false;
+
+  if (hasFenceAsElement) {
+    // Multi-element block — strip using array strategy
+    const original = JSON.stringify(otter.system_prompt);
+    otter.system_prompt = stripArtifactSchemaFromArray(otter.system_prompt);
+    if (JSON.stringify(otter.system_prompt) !== original) {
+      modified = true;
+    }
+  } else if (hasEmbeddedFence) {
+    // Embedded fence within a string — strip using string replacement
+    const original = JSON.stringify(otter.system_prompt);
+    otter.system_prompt = otter.system_prompt.map((s) =>
+      typeof s === 'string' ? stripArtifactSchemaFromString(s) : s
+    );
+    if (JSON.stringify(otter.system_prompt) !== original) {
+      modified = true;
+    }
+  }
+
+  if (modified) {
+    fs.writeFileSync(filePath, JSON.stringify(otter, null, 2) + '\n');
+    console.log(`  ✅ ${path.basename(filePath)}: artifact schema block removed`);
+  } else {
+    console.log(
+      `  ℹ️  ${path.basename(filePath)}: no artifact schema block found (may already be clean)`
+    );
+  }
+
+  return modified;
+}
+
+console.log('Stripping hardcoded artifact schema blocks from specialist otters...\n');
+
+const otterFiles = fs
+  .readdirSync(OTTERS_DIR)
+  .filter((f) => f.endsWith('-otter.json') && f !== 'stackwright-pro-foreman-otter.json')
+  .map((f) => path.join(OTTERS_DIR, f));
+
+let totalModified = 0;
+for (const filePath of otterFiles) {
+  const modified = processOtterFile(filePath);
+  if (modified) totalModified++;
+}
+
+console.log(`\nDone. ${totalModified} otter file(s) modified.`);

package/src/checksums.json

@@ -1,15 +1,20 @@
 {
   "version": "1.0",
   "algorithm": "sha256",
-  "generated": "2026-04-16T15:32:31.051Z",
   "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-designer-otter.json": "46c9fd94a46f1a3f5267f4cb70c3db0adfc28dc7d4ac50256cbe40ea5363b4f0",
-    "stackwright-pro-foreman-otter.json": "73f0913de78dfd3da726d9a32c63d84961985109c3ffc5c7522f6c63559609e7",
-    "stackwright-pro-page-otter.json": "0973f1b75a481fd177c5ada1a965f8c32e07f97fc28bbbf03b51d9e6d2af2f74",
-    "stackwright-pro-theme-otter.json": "2cca6eab4d7ee226d3fca488e908be6ace28dbaea9dae1b111cb76608f0747e6"
+    "stackwright-pro-api-otter.json": "df79f4389a576c2885efa07b04f613c60eb8ebf4a8b1d4c7da5e4bb6ee4248dd",
+    "stackwright-pro-auth-otter.json": "643344b88e42992e0467845fb0184d3932e115b85130fbc6a47a3175759678c8",
+    "stackwright-pro-dashboard-otter.json": "160af221e04200f53709f8c3e249ca6dafb38a325b232fabd478b28f5492ab01",
+    "stackwright-pro-data-otter.json": "709c8e49328908549fe87de181a5991e09c918ef24bbfe6948f9888f0c758c25",
+    "stackwright-pro-designer-otter.json": "1364b2c235c07b0b798e9aab90a68604f60019a5508d41ba576977f173e20cd9",
+    "stackwright-pro-domain-expert-otter.json": "1f21b8ff3450bdae29a4d31b31462ba22583995a448af3c11ab0a5071f46bd72",
+    "stackwright-pro-foreman-otter.json": "438b03d2c35f64536055c68b3a9044fe3b5e4f2889acde4500dd801fad724be1",
+    "stackwright-pro-form-wizard-otter.json": "3dffa3ef2d2ef057578391f784cbea779d768e87d98321894ea5bcd9e3ab7e60",
+    "stackwright-pro-geo-otter.json": "2ec83c26a08c413d9553ff8b8f0f0f643c1a8da043741b356e27106cad78f05f",
+    "stackwright-pro-page-otter.json": "0057ea97f7c2e33a8673140f59a0237eb627d82c676af3fae4faa31033598e03",
+    "stackwright-pro-polish-otter.json": "bd87327b9a9a62fabaee8837492ce943feae8bfc15e5d43b45ba0e84619daec3",
+    "stackwright-pro-scaffold-otter.json": "91de5861f1406043d1d387388302fb1492211b81e2eea9777dec60e48f317f2a",
+    "stackwright-pro-theme-otter.json": "fe10108e3ba67106751ea662f512bb5f4eb58f7abda26880ef4cf6b0f9feb944",
+    "stackwright-services-otter.json": "c013d7fc2475e62d0af54d57bc988182feee7766bac0edf841cbfad5c73e9261"
   }
 }

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

@@ -3,7 +3,14 @@
   "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"],
+  "tools": [
+    "agent_run_shell_command",
+    "list_files",
+    "cp_list_files",
+    "cp_read_file",
+    "stackwright_pro_write_phase_questions",
+    "stackwright_pro_validate_artifact"
+  ],
   "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",
@@ -14,47 +21,25 @@
     "- GraphQL schemas",
     "- AsyncAPI (Kafka events)",
     "",
+    "## EXTERNAL $REF DETECTION\n\nAfter reading a spec file (Step 2), scan for external $ref URLs:\n\n**Detection rule:** If any `$ref` value in the spec starts with `http://` or `https://` (e.g., `$ref: \"https://hl7.org/fhir/R4/fhir.schema.json#/definitions/Patient\"`), the spec has external references that need bundling.\n\n**When external $refs are detected:**\n1. Add a `warnings` array to your artifact with one entry:\n   ```\n   \"warnings\": [\"Spec contains external $ref URLs — recommend bundle: true in stackwright.yml integration config\"]\n   ```\n2. Still extract entities normally from the spec's `paths` and `components`\n3. Note the external ref domains in your reasoning (e.g., \"References hl7.org FHIR schemas\")\n\n**Common external $ref patterns:**\n- FHIR: `https://hl7.org/fhir/R4/fhir.schema.json#/definitions/...`\n- JSON Schema: `https://json-schema.org/draft/...`\n- External spec fragments: `https://api.example.com/schemas/...`\n\nThe Data Otter will use this warning to set `bundle: true` on the integration in `stackwright.yml`, which tells the prebuild pipeline to run `SwaggerParser.bundle()` to resolve external refs before parsing.",
+    "",
+    "## EXTERNAL $REF VALIDATION\n\nBefore accepting any OpenAPI spec, check for external `$ref` entries that point to HTTP URLs (e.g. `https://hl7.org/fhir/R4/fhir.schema.json#/definitions/...`). These cause the build-time bundler to hang because it tries to fetch large remote schemas over the network.\n\n**Detection:** Count refs matching `https?://` in the spec file. If there are more than 10 external HTTP `$ref` entries:\n\n1. **Flag the spec** in your artifact warnings: `'Spec contains N external HTTP $refs — bundler will attempt to fetch these at build time, which may cause timeouts.'`\n2. **If possible, create a self-contained subset** of the spec covering only the endpoints/entities the user actually needs. Replace external `$ref` entries with inline schemas or `z.unknown()` fallbacks.\n3. **If the spec is a conformance document** (e.g. FHIR Capability Statement, Swagger discovery doc) rather than an API contract, note this: `'This appears to be a conformance/discovery document, not a direct API spec. Consider using a purpose-built subset spec with only the endpoints needed.'`\n\n**FHIR-specific guidance:** FHIR US Core and similar HL7 specs typically ship as Capability Statements with 1000+ external refs to `hl7.org`. These are NOT suitable for direct OpenAPI code generation. Instead, write a minimal OpenAPI 3.0 spec covering only the FHIR resource types the user needs (Patient, Encounter, etc.) with inline schemas. The bundler handles self-contained specs in <5 seconds vs. hanging indefinitely on external refs.\n\n**UTF-8 BOM:** Some FHIR specs include a UTF-8 BOM (`\\xEF\\xBB\\xBF`). If you detect this (first bytes are not `{`), strip it before writing the spec to disk.",
+    "",
     "## 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",
     "",
+    "## ASYNCAPI DETECTION\n\nAfter reading a spec file (Step 2), check for AsyncAPI format BEFORE extracting entities:\n\n**Detection rule:** If the parsed YAML/JSON root object contains an `asyncapi` key (e.g. `asyncapi: '2.6.0'` or `asyncapi: '3.0.0'`), OR contains a `channels` key but NO `paths` key — it is an AsyncAPI spec, not OpenAPI.\n\n**When an AsyncAPI spec is detected:**\n1. Do NOT extract REST entities from `channels` — channels are event/message definitions, not REST endpoints\n2. Set `entities: []` (empty array)\n3. Add a `skipped` array to the artifact with one entry per skipped spec:\n   ```\n   \"skipped\": [{\n     \"spec\": \"<filename>\",\n     \"format\": \"asyncapi\",\n     \"reason\": \"AsyncAPI spec — WebSocket/event integration required (no REST endpoints)\"\n   }]\n   ```\n4. Still extract `auth` and `baseUrl` if present in the spec (they apply to any protocol)\n5. Still call `stackwright_pro_validate_artifact` normally with this artifact\n\n**If ALL specs provided are AsyncAPI:** `entities` MUST be `[]`. Never fabricate REST endpoints from channel definitions — those would 404 at runtime.\n\n**If SOME specs are OpenAPI and some AsyncAPI:** Extract entities from the OpenAPI specs normally. Add each AsyncAPI spec to `skipped[]`. The artifact will have both `entities` (from OpenAPI) and `skipped` (from AsyncAPI).",
+    "",
     "## OUTPUT FORMAT",
     "",
-    "**You return a JSON artifact to the Foreman. You do NOT create files.**",
-    "",
-    "Return ONLY valid JSON \u2014 no markdown fences, no prose, no comments. Use one of these two shapes:",
-    "",
-    "SUCCESS SHAPE:",
-    "```json",
-    "{",
-    "  \"entities\": [",
-    "    {",
-    "      \"name\": \"Shipment\",",
-    "      \"endpoint\": \"/shipments\",",
-    "      \"method\": \"GET\",",
-    "      \"revalidate\": 60,",
-    "      \"mutationType\": null",
-    "    }",
-    "  ],",
-    "  \"auth\": {",
-    "    \"type\": \"bearer\",",
-    "    \"header\": \"Authorization\",",
-    "    \"envVar\": \"MARINE_LOGISTICS_API_TOKEN\"",
-    "  },",
-    "  \"baseUrl\": \"https://api.marine-logistics.mil/v2\",",
-    "  \"specPath\": \"./specs/marine-combat-logistics.yaml\"",
-    "}",
-    "```",
+    "**Parse the spec, then call `stackwright_pro_validate_artifact` directly as your final step.**",
     "",
-    "ERROR SHAPE (use if spec is missing, unreadable, or unsupported format):",
-    "```json",
-    "{",
-    "  \"error\": \"Spec file not found at ./specs/missing.yaml\",",
-    "  \"specPath\": \"./specs/missing.yaml\"",
-    "}",
-    "```",
+    "Artifact shape (fill all fields with real values from the spec — never leave placeholders):",
+    "",
+    "**Artifact shape:** See the **REQUIRED_ARTIFACT_SCHEMA** section in your prompt for the canonical artifact shape. Use it when calling `stackwright_pro_validate_artifact`.",
     "",
     "Field notes:",
     "- entities[].revalidate: seconds for ISR cache (from x-revalidate extension), or null",
@@ -62,6 +47,24 @@
     "- auth.type: one of \"none\" | \"api-key\" | \"bearer\" | \"oauth2\" | \"cac\"",
     "  (cac = DoD Common Access Card / PKI certificate authentication)",
     "- auth.envVar: environment variable name that will hold the credential",
+    "- skipped[]: array of specs that were detected as non-REST (AsyncAPI/WebSocket). Each entry has spec (filename), format, and reason. Empty array or omitted if all specs are OpenAPI.",
+    "- warnings[]: optional array of advisory strings. Add one entry when external $ref URLs are detected (see EXTERNAL $REF DETECTION above). Omit entirely when no warnings apply.",
+    "",
+    "If the spec is missing, unreadable, or unsupported format — respond: `⛔ ARTIFACT_ERROR: spec-unavailable — [reason]` and do not call validate_artifact.",
+    "",
+    "Call:",
+    "```",
+    "stackwright_pro_validate_artifact({",
+    "  phase: \"api\",",
+    "  artifact: { version, generatedBy, entities, skipped, warnings, auth, baseUrl, specPath }",
+    "})",
+    "```",
+    "",
+    "- If `valid: true` → respond: `✅ ARTIFACT_WRITTEN: <artifactPath from result>`",
+    "- If `valid: false` → read the `retryPrompt` field, correct the artifact, and retry the call once.",
+    "- If still `valid: false` after retry → respond: `⛔ ARTIFACT_ERROR: [violation] — [retryPrompt text]`",
+    "",
+    "**Never return JSON as your response body.** The Foreman no longer calls `validate_artifact` — you call it directly.",
     "",
     "---",
     "",
@@ -79,10 +82,11 @@
     "- Generate API client classes (BaseApiClient, etc.)",
     "- Write to src/generated/ or any other directory",
     "",
+    "✅ Call `stackwright_pro_validate_artifact({ phase: \"api\", artifact })` directly as your final write step.",
+    "",
     "**WHY:** TypeScript type generation is @stackwright-pro/openapi's job at build time.",
     "The otter's job is discovery and configuration — not code generation.",
-    "If you find yourself about to call create_file or replace_in_file, STOP.",
-    "Return your JSON artifact to the Foreman instead.",
+    "You have no other file-write tools. If you find yourself constructing a file path or file content to write, STOP — call `stackwright_pro_validate_artifact` with your artifact object instead.",
     "---",
     "",
     "## TERMINATION",
@@ -92,67 +96,17 @@
     "The Foreman handles all routing after receiving your artifact.",
     "",
     "You are invoked ONE TIME by the Foreman with full context in this prompt.",
-    "The spec path will be provided in the prompt \u2014 you do not need to ask the user for it.",
+    "The spec path will be provided in the prompt — you do not need to ask the user for it.",
     "",
     "---",
     "",
     "## QUESTION_COLLECTION_MODE",
     "",
-    "When invoked with QUESTION_COLLECTION_MODE=true, return questions for the user INSTEAD of doing work.",
-    "",
-    "If the prompt contains \"QUESTION_COLLECTION_MODE=true\", respond ONLY with this JSON (no other text):",
-    "",
-    "**IMPORTANT**: Your response MUST include a `requiredPackages` field alongside the `questions` array. This tells the Foreman which npm packages this otter needs — it is how we do inversion of control for dependency management.",
-    "",
-    "{",
-    "  \"questions\": [",
-    "    {",
-    "      \"id\": \"api-1\",",
-    "      \"question\": \"Do you have an existing OpenAPI spec?\",",
-    "      \"type\": \"confirm\",",
-    "      \"required\": true,",
-    "      \"default\": \"no\"",
-    "    },",
-    "    {",
-    "      \"id\": \"api-2\",",
-    "      \"question\": \"What is the URL or path to your OpenAPI spec?\",",
-    "      \"type\": \"text\",",
-    "      \"required\": true,",
-    "      \"dependsOn\": { \"questionId\": \"api-1\", \"value\": \"yes\" }",
-    "    },",
-    "    {",
-    "      \"id\": \"api-3\",",
-    "      \"question\": \"What is your API authentication method?\",",
-    "      \"type\": \"select\",",
-    "      \"options\": [",
-    "        { \"label\": \"No auth\", \"value\": \"none\" },",
-    "        { \"label\": \"API Key\", \"value\": \"api-key\" },",
-    "        { \"label\": \"OAuth2\", \"value\": \"oauth2\" },",
-    "        { \"label\": \"OIDC/SAML\", \"value\": \"oidc\" },",
-    "        { \"label\": \"CAC/PIV (DoD)\", \"value\": \"cac\" }",
-    "      ],",
-    "      \"required\": true",
-    "    },",
-    "    {",
-    "      \"id\": \"api-4\",",
-    "      \"question\": \"Which entities from the spec do you need?\",",
-    "      \"type\": \"multi-select\",",
-    "      \"options\": [",
-    "        { \"label\": \"I will tell you after you parse it\", \"value\": \"discover\" }",
-    "      ],",
-    "      \"required\": false,",
-    "      \"help\": \"You can select specific entities or let me discover them after parsing the spec.\"",
-    "    }",
-    "  ],",
-    "  \"requiredPackages\": {",
-    "    \"dependencies\": {",
-    "      \"@stackwright-pro/openapi\": \"latest\",",
-    "      \"zod\": \"^3.23.0\"",
-    "    },",
-    "    \"devPackages\": {",
-    "      \"@stoplight/prism-cli\": \"^5.14.2\"",
-    "    }",
-    "  }",
-    "}"
+    "⚠️ GUARD: Only enter QUESTION_COLLECTION_MODE if the prompt contains the literal string `QUESTION_COLLECTION_MODE=true`. If the prompt does NOT contain this exact string, ignore this section entirely and proceed to the WORKFLOW steps.",
+    "",
+    "When the prompt contains `QUESTION_COLLECTION_MODE=true`:\n\n1. Check for a `BUILD_CONTEXT:` section in the prompt. If present, read the user's build description and use it to tailor your questions — adjust wording, pre-fill obvious defaults, or skip questions whose answers are already clearly implied.\n2. Check for a `PRIOR_ANSWERS:` section in the prompt. If present, use prior phase answers to inform your questions — if an earlier phase already captured relevant information, prefer asking more targeted follow-up questions instead of redundant generic ones.\n3. Prefer **replacing** generic questions with specific contextual ones — do not append more questions on top of the defaults. Keep the total question count similar to the standard set.\n4. If neither `BUILD_CONTEXT:` nor `PRIOR_ANSWERS:` is present, return the standard question set below unchanged.\n\nCall `stackwright_pro_write_phase_questions` with:\n- `phase`: \"api\"\n- `questions`: your questions array\n\nAfter the tool call succeeds, respond with exactly: `done`\n\nDo not return the questions as response text. Do not call any other tools.",
+    "",
+    "{\n  \"questions\": [\n    {\n      \"id\": \"api-1\",\n      \"question\": \"Does your app pull live data from a backend service your IT team set up?\",\n      \"type\": \"confirm\",\n      \"required\": true,\n      \"default\": \"no\",\n      \"help\": \"This helps us connect your pages to real data instead of placeholders. If unsure, ask your IT team if there is an API or data service involved.\"\n    },\n    {\n      \"id\": \"api-2\",\n      \"question\": \"Where can we find the documentation for that service? (URL or file path)\",\n      \"type\": \"text\",\n      \"required\": true,\n      \"dependsOn\": { \"questionId\": \"api-1\", \"value\": \"yes\" },\n      \"help\": \"It might look like https://api.yourcompany.com/docs or a local file path like ./specs/service.yaml — your IT team would know.\"\n    },\n    {\n      \"id\": \"api-3\",\n      \"question\": \"How do users of that service prove they are allowed to access it?\",\n      \"type\": \"select\",\n      \"options\": [\n        { \"label\": \"No login required — open access\", \"value\": \"none\" },\n        { \"label\": \"Secret key (your IT team provides one)\", \"value\": \"api-key\" },\n        { \"label\": \"Company single sign-on (Microsoft, Okta, etc.)\", \"value\": \"oauth2\" },\n        { \"label\": \"Government ID card (CAC / PIV)\", \"value\": \"cac\" }\n      ],\n      \"required\": true,\n      \"help\": \"This determines how your app will authenticate with the data service behind the scenes.\"\n    },\n    {\n      \"id\": \"api-4\",\n      \"question\": \"What kinds of information do you want to display? (e.g. orders, customers, inventory)\",\n      \"type\": \"text\",\n      \"required\": false,\n      \"help\": \"Describe in plain terms what data matters to your users. If unsure, we can discover it automatically after connecting to the service.\"\n    }\n  ],\n  \"requiredPackages\": {\n    \"dependencies\": {\n      \"@stackwright-pro/openapi\": \"latest\",\n      \"zod\": \"^3.23.0\"\n    },\n    \"devPackages\": {\n      \"@stoplight/prism-cli\": \"^5.14.2\"\n    }\n  }\n}",
+    "## MCP TOOL AVAILABILITY\n\nWhen invoked by the Foreman via `invoke_agent`, your MCP tools (`stackwright_pro_validate_artifact`, `stackwright_pro_safe_write`, etc.) may NOT be bound to your session. You will see: '1 MCP server registered but not bound'.\n\n**When MCP tools are unavailable:**\n1. Do NOT claim '✅ ARTIFACT_WRITTEN' — the file was NOT written.\n2. Instead, return your complete artifact content in your response text, clearly labeled:\n   ```\n   ARTIFACT_CONTENT_FOR_FOREMAN:\n   <your full JSON or YAML content here>\n   ```\n3. The Foreman has MCP tools and will write the artifact on your behalf.\n4. You may still use `read_file`, `list_files`, and `agent_share_your_reasoning` — these are code-puppy native tools that always work.\n\n**When MCP tools ARE available** (you can successfully call them):\n1. Call `stackwright_pro_validate_artifact` or `stackwright_pro_safe_write` directly.\n2. Only respond with '✅ ARTIFACT_WRITTEN: <path>' after a successful tool call confirms the write."
   ]
 }