@orderful/droid 0.54.0 → 0.55.0

package/.claude-plugin/plugin.json

@@ -33,6 +33,7 @@
     "./src/tools/share/skills/share/SKILL.md",
     "./src/tools/status-update/skills/status-update/SKILL.md",
     "./src/tools/tech-design/skills/tech-design/SKILL.md",
+    "./src/tools/test-blueprints/skills/test-blueprints/SKILL.md",
     "./src/tools/webform/skills/webform/SKILL.md",
     "./src/tools/wrapup/skills/wrapup/SKILL.md"
   ],
@@ -53,6 +54,7 @@
     "./src/tools/share/commands/share.md",
     "./src/tools/status-update/commands/status-update.md",
     "./src/tools/tech-design/commands/tech-design.md",
+    "./src/tools/test-blueprints/commands/test-blueprints.md",
     "./src/tools/webform/commands/webform.md",
     "./src/tools/wrapup/commands/wrapup.md"
   ],

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @orderful/droid
 
+## 0.55.0
+
+### Minor Changes
+
+- [#330](https://github.com/Orderful/droid/pull/330) [`490323a`](https://github.com/Orderful/droid/commit/490323a23b49a420ebbbc5a02cb021afb1387d29) Thanks [@DenisSa](https://github.com/DenisSa)! - Add test-blueprints tool for writing and verifying EDI test blueprint HBS templates
+
 ## 0.54.0
 
 ### Minor Changes

package/dist/tools/test-blueprints/.claude-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "droid-test-blueprints",
+  "version": "0.1.0",
+  "description": "Write and verify test blueprint HBS templates for EDI transaction types. Automates scenario design, template creation, registration, and Zod schema validation.",
+  "author": {
+    "name": "Orderful",
+    "url": "https://github.com/orderful"
+  },
+  "repository": "https://github.com/orderful/droid",
+  "license": "MIT",
+  "keywords": [
+    "droid",
+    "ai",
+    "test-blueprints"
+  ],
+  "skills": [
+    "./skills/test-blueprints/SKILL.md"
+  ],
+  "commands": [
+    "./commands/test-blueprints.md"
+  ]
+}

package/dist/tools/test-blueprints/TOOL.yaml

@@ -0,0 +1,22 @@
+name: test-blueprints
+description: "Write and verify test blueprint HBS templates for EDI transaction types. Automates scenario design, template creation, registration, and Zod schema validation."
+version: 0.1.0
+status: beta
+audience:
+  - engineering
+
+includes:
+  skills:
+    - name: test-blueprints
+      required: true
+  commands:
+    - name: test-blueprints
+      is_alias: false
+  agents: []
+
+dependencies: []
+
+prerequisites:
+  - "ts-node and tsconfig-paths must be available in the target workspace (used by the validate script)"
+
+config_schema: {}

package/dist/tools/test-blueprints/commands/test-blueprints.md

@@ -0,0 +1,27 @@
+---
+name: test-blueprints
+description: "Write and verify test blueprint HBS templates for EDI transaction types."
+argument-hint: "[write {type} | verify {type}]"
+---
+
+# /test-blueprints
+
+**User invoked:** `/test-blueprints $ARGUMENTS`
+
+**Your task:** Invoke the **test-blueprints skill** with these arguments.
+
+## Examples
+
+- `/test-blueprints write 943`
+- `/test-blueprints verify 943`
+- `/test-blueprints 944`
+
+## Quick Reference
+
+```bash
+/test-blueprints write {type}   # Full create flow: schema → scenarios → templates → register → validate
+/test-blueprints verify {type}  # Validate existing blueprints against Zod schema
+/test-blueprints {type}         # Alias for write {type}
+```
+
+See the **test-blueprints skill** for full behaviour and validation rules.

package/dist/tools/test-blueprints/skills/test-blueprints/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: test-blueprints
+description: "Write and verify test blueprint HBS templates for EDI transaction types. Use when creating test scenarios for a new transaction type (e.g., 'create blueprints for 943'), verifying existing blueprints against their Zod schema (e.g., 'verify 943 blueprints', 'validate the 855 templates'), or adding test blueprints to the testTransformation module. User prompts like 'create test blueprints for 940', 'generate 944 test templates', 'verify 943 blueprints', 'validate the 855 templates', 'check if 944 blueprints are valid'."
+argument-hint: "[write {type} | verify {type}]"
+allowed-tools: [Read, Write, Edit, Glob, Grep, Bash, Agent]
+---
+
+# Test Blueprints Skill
+
+Write and verify test blueprint HBS templates for EDI transaction types in the Orderful platform. Each blueprint is a JSON file conforming to the transaction type's simplified Zod schema, representing a distinct business scenario.
+
+## Commands
+
+| Command | Action |
+|---------|--------|
+| `/test-blueprints write {type}` | Full workflow: discover schema, design scenarios, create templates, register, validate |
+| `/test-blueprints verify {type}` | Validate existing blueprints against the Zod schema and report results |
+| `/test-blueprints {type}` | Alias for `write {type}` |
+
+---
+
+## Command: verify
+
+Validate existing blueprint templates against their Zod schema. Use this to check that all templates for a transaction type are still valid after schema changes, or to spot-check templates at any time.
+
+### Steps
+
+1. **Locate files.** Read `references/codebase-paths.md` for exact paths.
+   - Find the Zod schema for the transaction type
+   - Find the blueprint directory (`testBlueprints/{type}s/`)
+   - If no blueprints exist for the type, report that and stop
+
+2. **Read the Zod schema** to determine the schema export name and import path.
+
+3. **Run the validation script:**
+```bash
+droid exec test-blueprints validate \
+  --workspace {workspace-root} \
+  --schema-import "{import-path}" \
+  --schema-name "{SchemaExportName}" \
+  --blueprints-dir "{path-to-blueprints-dir}"
+```
+
+The script automatically:
+- Discovers all `.json.hbs` files in the blueprints directory
+- Skips templates containing Handlebars expressions (validated at render time, not statically)
+- Validates remaining templates against the Zod schema via ts-node
+- Returns structured JSON with per-file pass/fail/skip results
+
+4. **Report results.** Parse the JSON output and show a summary table:
+   - PASS / FAIL / SKIP status per template
+   - For failures: the exact field path and error message
+   - Suggest fixes for common mistakes (see Common Validation Pitfalls below)
+
+---
+
+## Command: write
+
+Full workflow to create test blueprint templates for a transaction type.
+
+### Phase 1: Discovery
+
+Identify the transaction type and locate the required files. Read `references/codebase-paths.md` for exact paths.
+
+1. **Find the Zod schema** for the transaction type. This is the source of truth for the template shape. Read it fully - every field, every enum value, every `metaEnum` definition. Also read `shared.zod.ts` for all imported shared types and their enum values.
+
+2. **Find the example JSON** (if one exists) in the simplified schema examples directory. This shows realistic field values.
+
+3. **Check TransactionTypeName** to confirm the enum key exists (e.g., `T943`).
+
+4. **Check existing blueprints** to see if templates already exist for this type. If they do, ask the user whether to replace or augment.
+
+5. **Determine if the template is static or templated.** This is an EDI domain question, not a codebase config lookup — the config may not exist yet for the transaction type.
+
+   Ask: **"Is this transaction type a direct response that echoes back data from a specific inbound document?"**
+
+   - **Static** — The transaction originates from the sender's own system data. The sender generates it from their own records (WMS, ERP, inventory system) without referencing a specific inbound EDI document. Templates are pure JSON with no Handlebars expressions.
+     - Examples: 846 (inventory report from seller's system), 943 (warehouse ships from WMS data), 944 (warehouse reports what it received), 940 (depositor issues a shipping order)
+   - **Templated** — The transaction is a direct response to a specific inbound document and structurally echoes back fields from it (line items, PO numbers, product IDs). Templates use Handlebars expressions to pull from the upstream document's data.
+     - Examples: 855 (acknowledges an 850's line items), 856 (ships against an 850), 810 (invoices against an 856)
+
+   If unsure, check existing templates for similar transaction types in the same document family.
+
+### Phase 2: Scenario Design
+
+Analyse the Zod schema to identify the key variability dimensions, then design scenarios.
+
+**Identify dimensions of variability:**
+- Enum fields (especially top-level ones like reporting codes, purpose codes, status codes) - each distinct value is a potential scenario axis
+- Optional object blocks (parties, dates, notes, references, carrier details) - presence/absence is a scenario axis
+- Array fields (line items, pallets) - single vs. multiple is a scenario axis
+- Nested optional structures (exception details, physical details, lot tracking) - exercising these is important
+
+**Select 8-12 scenarios** ranked by business impact. Always include:
+1. **Standard/baseline** - the happy path with typical fields populated
+2. **Comprehensive** - every field populated (mirrors `810_comprehensive` / `846_comprehensive` pattern)
+3. **Minimal** - only required fields, everything optional absent
+
+Then select the remaining scenarios based on what the schema uniquely supports. Prioritise:
+- Each distinct enum value for top-level enums (e.g., different reporting codes)
+- Key structural variations (pallets vs. loose items, single vs. multi-line)
+- Industry-specific scenarios (cold chain, lot tracking, ocean shipment, returns)
+- Correction/amendment flows (if the schema has a purpose/action code)
+
+**Present the scenario list to the user** with a brief rationale for each before creating files. Wait for approval.
+
+### Phase 3: Template Creation
+
+Create the blueprint files.
+
+1. **Create the directory** at:
+   ```
+   apps/platform-api/src/modules/testTransformation/data/testBlueprints/{type}s/
+   ```
+   where `{type}` is the three-digit transaction number (e.g., `943s`, `944s`).
+
+2. **Write each template** as a `.json.hbs` file. Follow these rules:
+   - File naming: `{type}_{scenarioName}.json.hbs` (e.g., `943_standard.json.hbs`)
+   - If static: pure JSON, no Handlebars expressions
+   - If templated: use Handlebars expressions to reference upstream context (e.g., `{{purchaseOrder.*}}`, `{{#each purchaseOrder.lineItems}}`). See existing 855 templates for the PO-response pattern.
+   - Use realistic but clearly fictional data (company names, addresses, product descriptions)
+   - Use distinct data across templates - don't copy-paste the same parties/products everywhere
+   - Every enum value must be a valid value from the Zod schema's `metaEnum` definition - use the simplified name (e.g., `"commonCarrier"`), not the X12 code (e.g., not `"M"`)
+
+### Phase 4: Registration
+
+Register the blueprints in the repository.
+
+1. **Edit `testBlueprint.repository.ts`**:
+   - Add imports for each template file (follow the existing naming convention)
+   - Add a new entry in `blueprintsByTransactionType` under the appropriate `TransactionTypeName` key
+   - Place it in alphabetical/numerical order relative to existing entries
+
+### Phase 5: Validation
+
+Run the **verify** command for the newly created templates. Fix any errors and re-run until all pass.
+
+### Phase 6: Summary
+
+Report to the user:
+- How many templates were created
+- A table of template names and the scenario each covers
+- The file edited for registration
+- Validation result (all pass)
+
+---
+
+## Common Validation Pitfalls
+
+These are the most frequent errors when writing blueprints. Check `shared.zod.ts` to verify exact enum values.
+
+| Mistake | Fix |
+|---------|-----|
+| `"motor"` for transportation method | Use `"commonCarrier"` |
+| `"truck"` for transportation method | Use `"commonCarrier"` or `"privateCarrier"` |
+| `"inches"` for dimension UOM | Use `"inch"` |
+| `"assignedByBuyer"` for identification code type | Use `"receiversId"` or a value from the enum |
+| X12 codes like `"M"`, `"F"`, `"01"` | Use simplified names like `"commonCarrier"`, `"fullDetail"`, `"damaged"` |
+| `"lbs"` or `"kg"` for weight UOM | Use `"pound"` or `"kilogram"` |
+| `"EA"` or `"CS"` for unit of measure | Use `"each"` or `"case"` (lowercase simplified names) |

package/dist/tools/test-blueprints/skills/test-blueprints/references/codebase-paths.md

@@ -0,0 +1,79 @@
+# Codebase Paths Reference
+
+All paths are relative to the orderful-workspace root.
+
+## Zod Schemas (source of truth for template shape)
+
+```
+libs/schemas/src/lib/data/simplifiedSchemas/
+```
+
+To find the Zod schema for a transaction type, search the index:
+```bash
+grep -r "TransactionTypeName.T<number>" libs/schemas/src/lib/data/simplifiedSchemas/index.ts
+```
+
+Then find the schema file and export name from the import.
+
+## Example JSON (realistic field values)
+
+```
+libs/schemas/src/lib/data/simplifiedSchemas/examples/
+```
+
+Pattern: `simplified-<schemaName>.json`
+
+## Shared Zod Schemas (enum values, shared types)
+
+```
+libs/schemas/src/lib/data/simplifiedSchemas/shared.zod.ts
+```
+
+This file defines all shared types used across transaction schemas:
+- `PartySchema` - party identification with contacts
+- `QuantitySchema` - value + unit of measure
+- `PhysicalDetailsSchema` - pack, weight, dimensions
+- `LineItemIdentifiersSchema` - product IDs (buyer, vendor, GTIN)
+- `ProductAttributeDetailsSchema` - description, color, size, material
+- `RoutingDetailsSchema` - carrier and transportation method
+- `EquipmentDetailsSchema` - trailer, container, seal
+- `FOBDetailsSchema` - freight payment terms
+- `SpecialHandlingDetailsSchema` - handling codes
+- `CarrierWeightDetailsSchema` - shipment weight totals
+- `NoteDetailsSchema` - notes with text array
+- `PalletExchangeSchema` - pallet exchange/return enum
+- `ContactSchema` - contact person details
+
+## TransactionTypeName Enum
+
+```
+libs/platform-types/src/lib/transactionTypeNames.ts
+```
+
+Check this file for the exact enum key (e.g., `T943`, `T944`).
+
+## Blueprint Templates
+
+```
+apps/platform-api/src/modules/testTransformation/data/testBlueprints/
+```
+
+Organised by type: `810s/`, `846s/`, `855s/`, `856s/`, `943s/`, etc.
+
+## Blueprint Repository (registration)
+
+```
+apps/platform-api/src/modules/testTransformation/repositories/testBlueprint.repository.ts
+```
+
+This file:
+1. Imports all `.json.hbs` template files
+2. Registers them in `blueprintsByTransactionType` under the `TransactionTypeName` key
+3. Optionally registers upstream blueprints in `upstreamBlueprints`
+
+## Validation Script Execution
+
+```bash
+cd <workspace-root> && npx ts-node -r tsconfig-paths/register \
+  --project apps/platform-api/tsconfig.json <path-to-script>
+```

package/dist/tools/test-blueprints/skills/test-blueprints/scripts/validate.d.ts

@@ -0,0 +1,28 @@
+#!/usr/bin/env bun
+/**
+ * test-blueprints validate
+ *
+ * Validate blueprint .json.hbs templates against their Zod schema.
+ * Generates a temporary validation script in the workspace and runs it
+ * via ts-node so that tsconfig paths resolve correctly.
+ *
+ * Usage:
+ *   droid exec test-blueprints validate \
+ *     --workspace /path/to/orderful-workspace \
+ *     --schema-import "simplifiedSchemas/schemaFile" \
+ *     --schema-name "Simplified943Schema" \
+ *     --blueprints-dir "apps/platform-api/src/modules/testTransformation/data/testBlueprints/943s"
+ *
+ * Output (JSON):
+ *   {
+ *     "success": true,
+ *     "results": [
+ *       { "file": "943_standard.json.hbs", "status": "pass" },
+ *       { "file": "943_templated.json.hbs", "status": "skip", "reason": "contains Handlebars expressions" },
+ *       { "file": "943_bad.json.hbs", "status": "fail", "errors": [{ "path": "header.type", "message": "Invalid enum value" }] }
+ *     ],
+ *     "summary": { "pass": 8, "fail": 1, "skip": 2, "total": 11 }
+ *   }
+ */
+export {};
+//# sourceMappingURL=validate.d.ts.map

package/dist/tools/test-blueprints/skills/test-blueprints/scripts/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../../../../src/tools/test-blueprints/skills/test-blueprints/scripts/validate.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG"}

package/dist/tools/test-blueprints/skills/test-blueprints/scripts/validate.ts

@@ -0,0 +1,250 @@
+#!/usr/bin/env bun
+/**
+ * test-blueprints validate
+ *
+ * Validate blueprint .json.hbs templates against their Zod schema.
+ * Generates a temporary validation script in the workspace and runs it
+ * via ts-node so that tsconfig paths resolve correctly.
+ *
+ * Usage:
+ *   droid exec test-blueprints validate \
+ *     --workspace /path/to/orderful-workspace \
+ *     --schema-import "simplifiedSchemas/schemaFile" \
+ *     --schema-name "Simplified943Schema" \
+ *     --blueprints-dir "apps/platform-api/src/modules/testTransformation/data/testBlueprints/943s"
+ *
+ * Output (JSON):
+ *   {
+ *     "success": true,
+ *     "results": [
+ *       { "file": "943_standard.json.hbs", "status": "pass" },
+ *       { "file": "943_templated.json.hbs", "status": "skip", "reason": "contains Handlebars expressions" },
+ *       { "file": "943_bad.json.hbs", "status": "fail", "errors": [{ "path": "header.type", "message": "Invalid enum value" }] }
+ *     ],
+ *     "summary": { "pass": 8, "fail": 1, "skip": 2, "total": 11 }
+ *   }
+ */
+
+import { execSync } from 'child_process';
+import { existsSync, writeFileSync, unlinkSync, readdirSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+interface ValidationError {
+  path: string;
+  message: string;
+}
+
+interface FileResult {
+  file: string;
+  status: 'pass' | 'fail' | 'skip';
+  reason?: string;
+  errors?: ValidationError[];
+}
+
+interface ValidateResult {
+  success: boolean;
+  results?: FileResult[];
+  summary?: { pass: number; fail: number; skip: number; total: number };
+  error?: string;
+}
+
+interface ParsedArgs {
+  workspace?: string;
+  schemaImport?: string;
+  schemaName?: string;
+  blueprintsDir?: string;
+}
+
+function parseArgs(args: string[]): ParsedArgs {
+  const result: ParsedArgs = {};
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--workspace' && args[i + 1]) {
+      result.workspace = args[++i];
+    } else if (arg === '--schema-import' && args[i + 1]) {
+      result.schemaImport = args[++i];
+    } else if (arg === '--schema-name' && args[i + 1]) {
+      result.schemaName = args[++i];
+    } else if (arg === '--blueprints-dir' && args[i + 1]) {
+      result.blueprintsDir = args[++i];
+    }
+  }
+
+  return result;
+}
+
+function expandPath(p: string): string {
+  if (p.startsWith('~/')) {
+    return p.replace('~', process.env.HOME || '');
+  }
+  if (p.startsWith('$HOME/')) {
+    return p.replace('$HOME', process.env.HOME || '');
+  }
+  return p;
+}
+
+function validate(parsed: ParsedArgs): ValidateResult {
+  if (!parsed.workspace) {
+    return { success: false, error: 'Missing --workspace' };
+  }
+  if (!parsed.schemaImport) {
+    return { success: false, error: 'Missing --schema-import' };
+  }
+  if (!parsed.schemaName) {
+    return { success: false, error: 'Missing --schema-name' };
+  }
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(parsed.schemaName)) {
+    return { success: false, error: 'Invalid --schema-name: must be a valid identifier' };
+  }
+  if (/['"\n\r]/.test(parsed.schemaImport)) {
+    return { success: false, error: 'Invalid --schema-import: must not contain quotes or newlines' };
+  }
+  if (!parsed.blueprintsDir) {
+    return { success: false, error: 'Missing --blueprints-dir' };
+  }
+
+  const workspace = expandPath(parsed.workspace);
+  if (!existsSync(workspace)) {
+    return { success: false, error: `Workspace not found: ${workspace}` };
+  }
+
+  const blueprintsDir = parsed.blueprintsDir.startsWith('/')
+    ? parsed.blueprintsDir
+    : join(workspace, parsed.blueprintsDir);
+
+  if (!existsSync(blueprintsDir)) {
+    return { success: false, error: `Blueprints directory not found: ${blueprintsDir}` };
+  }
+
+  // Find .json.hbs files
+  const files = readdirSync(blueprintsDir).filter(f => f.endsWith('.json.hbs'));
+  if (files.length === 0) {
+    return { success: false, error: `No .json.hbs files found in ${blueprintsDir}` };
+  }
+
+  // Pre-check for Handlebars templates (skip these from Zod validation)
+  const results: FileResult[] = [];
+  const filesToValidate: string[] = [];
+
+  for (const file of files) {
+    const content = readFileSync(join(blueprintsDir, file), 'utf-8');
+    if (content.includes('{{')) {
+      results.push({ file, status: 'skip', reason: 'contains Handlebars expressions' });
+    } else {
+      // Check JSON parsability before sending to ts-node
+      try {
+        JSON.parse(content);
+        filesToValidate.push(file);
+      } catch (e) {
+        const err = e as Error;
+        results.push({ file, status: 'fail', errors: [{ path: '(root)', message: `Invalid JSON: ${err.message}` }] });
+      }
+    }
+  }
+
+  // If all files are skipped or failed JSON parse, return early
+  if (filesToValidate.length === 0) {
+    const summary = {
+      pass: 0,
+      fail: results.filter(r => r.status === 'fail').length,
+      skip: results.filter(r => r.status === 'skip').length,
+      total: results.length,
+    };
+    return { success: summary.fail === 0, results, summary };
+  }
+
+  // Generate validation script
+  const validationScript = `
+import { ${parsed.schemaName} } from '${parsed.schemaImport}';
+import * as fs from 'fs';
+import * as path from 'path';
+
+const dir = ${JSON.stringify(blueprintsDir)};
+const filesToValidate: string[] = ${JSON.stringify(filesToValidate)};
+const results: Array<{ file: string; status: string; errors?: Array<{ path: string; message: string }> }> = [];
+
+for (const file of filesToValidate) {
+  const content = fs.readFileSync(path.join(dir, file), 'utf-8');
+  const parsed = JSON.parse(content);
+  const result = ${parsed.schemaName}.safeParse(parsed);
+
+  if (result.success) {
+    results.push({ file, status: 'pass' });
+  } else {
+    results.push({
+      file,
+      status: 'fail',
+      errors: result.error.issues.map((issue: { path: (string | number)[]; message: string }) => ({
+        path: issue.path.join('.'),
+        message: issue.message,
+      })),
+    });
+  }
+}
+
+console.log(JSON.stringify(results));
+`.trim();
+
+  const scriptPath = join(tmpdir(), `_validate-${Date.now()}.ts`);
+
+  try {
+    writeFileSync(scriptPath, validationScript, 'utf-8');
+
+    const output = execSync(
+      `npx ts-node -r tsconfig-paths/register --project apps/platform-api/tsconfig.json ${JSON.stringify(scriptPath)}`,
+      {
+        cwd: workspace,
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+        timeout: 60_000,
+      }
+    );
+
+    let zodResults: Array<{ file: string; status: string; errors?: ValidationError[] }>;
+    try {
+      zodResults = JSON.parse(output.trim());
+    } catch {
+      return { success: false, error: `Failed to parse validation output: ${output}` };
+    }
+
+    for (const r of zodResults) {
+      results.push({
+        file: r.file,
+        status: r.status as 'pass' | 'fail',
+        errors: r.errors,
+      });
+    }
+  } catch (err: unknown) {
+    const error = err as { stderr?: string; message?: string };
+    return {
+      success: false,
+      error: `Validation script failed: ${error.stderr || error.message}`,
+    };
+  } finally {
+    try { unlinkSync(scriptPath); } catch { /* ignore cleanup errors */ }
+  }
+
+  // Sort results to match original file order
+  results.sort((a, b) => files.indexOf(a.file) - files.indexOf(b.file));
+
+  const summary = {
+    pass: results.filter(r => r.status === 'pass').length,
+    fail: results.filter(r => r.status === 'fail').length,
+    skip: results.filter(r => r.status === 'skip').length,
+    total: results.length,
+  };
+
+  return { success: summary.fail === 0, results, summary };
+}
+
+// Main
+const args = process.argv.slice(2);
+const parsed = parseArgs(args);
+const result = validate(parsed);
+console.log(JSON.stringify(result, null, 2));
+
+if (!result.success) {
+  process.exit(1);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orderful/droid",
-  "version": "0.54.0",
+  "version": "0.55.0",
   "description": "AI workflow toolkit for sharing skills, commands, and agents across the team",
   "type": "module",
   "bin": {

package/src/tools/test-blueprints/.claude-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "droid-test-blueprints",
+  "version": "0.1.0",
+  "description": "Write and verify test blueprint HBS templates for EDI transaction types. Automates scenario design, template creation, registration, and Zod schema validation.",
+  "author": {
+    "name": "Orderful",
+    "url": "https://github.com/orderful"
+  },
+  "repository": "https://github.com/orderful/droid",
+  "license": "MIT",
+  "keywords": [
+    "droid",
+    "ai",
+    "test-blueprints"
+  ],
+  "skills": [
+    "./skills/test-blueprints/SKILL.md"
+  ],
+  "commands": [
+    "./commands/test-blueprints.md"
+  ]
+}

package/src/tools/test-blueprints/TOOL.yaml

@@ -0,0 +1,22 @@
+name: test-blueprints
+description: "Write and verify test blueprint HBS templates for EDI transaction types. Automates scenario design, template creation, registration, and Zod schema validation."
+version: 0.1.0
+status: beta
+audience:
+  - engineering
+
+includes:
+  skills:
+    - name: test-blueprints
+      required: true
+  commands:
+    - name: test-blueprints
+      is_alias: false
+  agents: []
+
+dependencies: []
+
+prerequisites:
+  - "ts-node and tsconfig-paths must be available in the target workspace (used by the validate script)"
+
+config_schema: {}

package/src/tools/test-blueprints/commands/test-blueprints.md

@@ -0,0 +1,27 @@
+---
+name: test-blueprints
+description: "Write and verify test blueprint HBS templates for EDI transaction types."
+argument-hint: "[write {type} | verify {type}]"
+---
+
+# /test-blueprints
+
+**User invoked:** `/test-blueprints $ARGUMENTS`
+
+**Your task:** Invoke the **test-blueprints skill** with these arguments.
+
+## Examples
+
+- `/test-blueprints write 943`
+- `/test-blueprints verify 943`
+- `/test-blueprints 944`
+
+## Quick Reference
+
+```bash
+/test-blueprints write {type}   # Full create flow: schema → scenarios → templates → register → validate
+/test-blueprints verify {type}  # Validate existing blueprints against Zod schema
+/test-blueprints {type}         # Alias for write {type}
+```
+
+See the **test-blueprints skill** for full behaviour and validation rules.

package/src/tools/test-blueprints/skills/test-blueprints/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: test-blueprints
+description: "Write and verify test blueprint HBS templates for EDI transaction types. Use when creating test scenarios for a new transaction type (e.g., 'create blueprints for 943'), verifying existing blueprints against their Zod schema (e.g., 'verify 943 blueprints', 'validate the 855 templates'), or adding test blueprints to the testTransformation module. User prompts like 'create test blueprints for 940', 'generate 944 test templates', 'verify 943 blueprints', 'validate the 855 templates', 'check if 944 blueprints are valid'."
+argument-hint: "[write {type} | verify {type}]"
+allowed-tools: [Read, Write, Edit, Glob, Grep, Bash, Agent]
+---
+
+# Test Blueprints Skill
+
+Write and verify test blueprint HBS templates for EDI transaction types in the Orderful platform. Each blueprint is a JSON file conforming to the transaction type's simplified Zod schema, representing a distinct business scenario.
+
+## Commands
+
+| Command | Action |
+|---------|--------|
+| `/test-blueprints write {type}` | Full workflow: discover schema, design scenarios, create templates, register, validate |
+| `/test-blueprints verify {type}` | Validate existing blueprints against the Zod schema and report results |
+| `/test-blueprints {type}` | Alias for `write {type}` |
+
+---
+
+## Command: verify
+
+Validate existing blueprint templates against their Zod schema. Use this to check that all templates for a transaction type are still valid after schema changes, or to spot-check templates at any time.
+
+### Steps
+
+1. **Locate files.** Read `references/codebase-paths.md` for exact paths.
+   - Find the Zod schema for the transaction type
+   - Find the blueprint directory (`testBlueprints/{type}s/`)
+   - If no blueprints exist for the type, report that and stop
+
+2. **Read the Zod schema** to determine the schema export name and import path.
+
+3. **Run the validation script:**
+```bash
+droid exec test-blueprints validate \
+  --workspace {workspace-root} \
+  --schema-import "{import-path}" \
+  --schema-name "{SchemaExportName}" \
+  --blueprints-dir "{path-to-blueprints-dir}"
+```
+
+The script automatically:
+- Discovers all `.json.hbs` files in the blueprints directory
+- Skips templates containing Handlebars expressions (validated at render time, not statically)
+- Validates remaining templates against the Zod schema via ts-node
+- Returns structured JSON with per-file pass/fail/skip results
+
+4. **Report results.** Parse the JSON output and show a summary table:
+   - PASS / FAIL / SKIP status per template
+   - For failures: the exact field path and error message
+   - Suggest fixes for common mistakes (see Common Validation Pitfalls below)
+
+---
+
+## Command: write
+
+Full workflow to create test blueprint templates for a transaction type.
+
+### Phase 1: Discovery
+
+Identify the transaction type and locate the required files. Read `references/codebase-paths.md` for exact paths.
+
+1. **Find the Zod schema** for the transaction type. This is the source of truth for the template shape. Read it fully - every field, every enum value, every `metaEnum` definition. Also read `shared.zod.ts` for all imported shared types and their enum values.
+
+2. **Find the example JSON** (if one exists) in the simplified schema examples directory. This shows realistic field values.
+
+3. **Check TransactionTypeName** to confirm the enum key exists (e.g., `T943`).
+
+4. **Check existing blueprints** to see if templates already exist for this type. If they do, ask the user whether to replace or augment.
+
+5. **Determine if the template is static or templated.** This is an EDI domain question, not a codebase config lookup — the config may not exist yet for the transaction type.
+
+   Ask: **"Is this transaction type a direct response that echoes back data from a specific inbound document?"**
+
+   - **Static** — The transaction originates from the sender's own system data. The sender generates it from their own records (WMS, ERP, inventory system) without referencing a specific inbound EDI document. Templates are pure JSON with no Handlebars expressions.
+     - Examples: 846 (inventory report from seller's system), 943 (warehouse ships from WMS data), 944 (warehouse reports what it received), 940 (depositor issues a shipping order)
+   - **Templated** — The transaction is a direct response to a specific inbound document and structurally echoes back fields from it (line items, PO numbers, product IDs). Templates use Handlebars expressions to pull from the upstream document's data.
+     - Examples: 855 (acknowledges an 850's line items), 856 (ships against an 850), 810 (invoices against an 856)
+
+   If unsure, check existing templates for similar transaction types in the same document family.
+
+### Phase 2: Scenario Design
+
+Analyse the Zod schema to identify the key variability dimensions, then design scenarios.
+
+**Identify dimensions of variability:**
+- Enum fields (especially top-level ones like reporting codes, purpose codes, status codes) - each distinct value is a potential scenario axis
+- Optional object blocks (parties, dates, notes, references, carrier details) - presence/absence is a scenario axis
+- Array fields (line items, pallets) - single vs. multiple is a scenario axis
+- Nested optional structures (exception details, physical details, lot tracking) - exercising these is important
+
+**Select 8-12 scenarios** ranked by business impact. Always include:
+1. **Standard/baseline** - the happy path with typical fields populated
+2. **Comprehensive** - every field populated (mirrors `810_comprehensive` / `846_comprehensive` pattern)
+3. **Minimal** - only required fields, everything optional absent
+
+Then select the remaining scenarios based on what the schema uniquely supports. Prioritise:
+- Each distinct enum value for top-level enums (e.g., different reporting codes)
+- Key structural variations (pallets vs. loose items, single vs. multi-line)
+- Industry-specific scenarios (cold chain, lot tracking, ocean shipment, returns)
+- Correction/amendment flows (if the schema has a purpose/action code)
+
+**Present the scenario list to the user** with a brief rationale for each before creating files. Wait for approval.
+
+### Phase 3: Template Creation
+
+Create the blueprint files.
+
+1. **Create the directory** at:
+   ```
+   apps/platform-api/src/modules/testTransformation/data/testBlueprints/{type}s/
+   ```
+   where `{type}` is the three-digit transaction number (e.g., `943s`, `944s`).
+
+2. **Write each template** as a `.json.hbs` file. Follow these rules:
+   - File naming: `{type}_{scenarioName}.json.hbs` (e.g., `943_standard.json.hbs`)
+   - If static: pure JSON, no Handlebars expressions
+   - If templated: use Handlebars expressions to reference upstream context (e.g., `{{purchaseOrder.*}}`, `{{#each purchaseOrder.lineItems}}`). See existing 855 templates for the PO-response pattern.
+   - Use realistic but clearly fictional data (company names, addresses, product descriptions)
+   - Use distinct data across templates - don't copy-paste the same parties/products everywhere
+   - Every enum value must be a valid value from the Zod schema's `metaEnum` definition - use the simplified name (e.g., `"commonCarrier"`), not the X12 code (e.g., not `"M"`)
+
+### Phase 4: Registration
+
+Register the blueprints in the repository.
+
+1. **Edit `testBlueprint.repository.ts`**:
+   - Add imports for each template file (follow the existing naming convention)
+   - Add a new entry in `blueprintsByTransactionType` under the appropriate `TransactionTypeName` key
+   - Place it in alphabetical/numerical order relative to existing entries
+
+### Phase 5: Validation
+
+Run the **verify** command for the newly created templates. Fix any errors and re-run until all pass.
+
+### Phase 6: Summary
+
+Report to the user:
+- How many templates were created
+- A table of template names and the scenario each covers
+- The file edited for registration
+- Validation result (all pass)
+
+---
+
+## Common Validation Pitfalls
+
+These are the most frequent errors when writing blueprints. Check `shared.zod.ts` to verify exact enum values.
+
+| Mistake | Fix |
+|---------|-----|
+| `"motor"` for transportation method | Use `"commonCarrier"` |
+| `"truck"` for transportation method | Use `"commonCarrier"` or `"privateCarrier"` |
+| `"inches"` for dimension UOM | Use `"inch"` |
+| `"assignedByBuyer"` for identification code type | Use `"receiversId"` or a value from the enum |
+| X12 codes like `"M"`, `"F"`, `"01"` | Use simplified names like `"commonCarrier"`, `"fullDetail"`, `"damaged"` |
+| `"lbs"` or `"kg"` for weight UOM | Use `"pound"` or `"kilogram"` |
+| `"EA"` or `"CS"` for unit of measure | Use `"each"` or `"case"` (lowercase simplified names) |

package/src/tools/test-blueprints/skills/test-blueprints/references/codebase-paths.md

@@ -0,0 +1,79 @@
+# Codebase Paths Reference
+
+All paths are relative to the orderful-workspace root.
+
+## Zod Schemas (source of truth for template shape)
+
+```
+libs/schemas/src/lib/data/simplifiedSchemas/
+```
+
+To find the Zod schema for a transaction type, search the index:
+```bash
+grep -r "TransactionTypeName.T<number>" libs/schemas/src/lib/data/simplifiedSchemas/index.ts
+```
+
+Then find the schema file and export name from the import.
+
+## Example JSON (realistic field values)
+
+```
+libs/schemas/src/lib/data/simplifiedSchemas/examples/
+```
+
+Pattern: `simplified-<schemaName>.json`
+
+## Shared Zod Schemas (enum values, shared types)
+
+```
+libs/schemas/src/lib/data/simplifiedSchemas/shared.zod.ts
+```
+
+This file defines all shared types used across transaction schemas:
+- `PartySchema` - party identification with contacts
+- `QuantitySchema` - value + unit of measure
+- `PhysicalDetailsSchema` - pack, weight, dimensions
+- `LineItemIdentifiersSchema` - product IDs (buyer, vendor, GTIN)
+- `ProductAttributeDetailsSchema` - description, color, size, material
+- `RoutingDetailsSchema` - carrier and transportation method
+- `EquipmentDetailsSchema` - trailer, container, seal
+- `FOBDetailsSchema` - freight payment terms
+- `SpecialHandlingDetailsSchema` - handling codes
+- `CarrierWeightDetailsSchema` - shipment weight totals
+- `NoteDetailsSchema` - notes with text array
+- `PalletExchangeSchema` - pallet exchange/return enum
+- `ContactSchema` - contact person details
+
+## TransactionTypeName Enum
+
+```
+libs/platform-types/src/lib/transactionTypeNames.ts
+```
+
+Check this file for the exact enum key (e.g., `T943`, `T944`).
+
+## Blueprint Templates
+
+```
+apps/platform-api/src/modules/testTransformation/data/testBlueprints/
+```
+
+Organised by type: `810s/`, `846s/`, `855s/`, `856s/`, `943s/`, etc.
+
+## Blueprint Repository (registration)
+
+```
+apps/platform-api/src/modules/testTransformation/repositories/testBlueprint.repository.ts
+```
+
+This file:
+1. Imports all `.json.hbs` template files
+2. Registers them in `blueprintsByTransactionType` under the `TransactionTypeName` key
+3. Optionally registers upstream blueprints in `upstreamBlueprints`
+
+## Validation Script Execution
+
+```bash
+cd <workspace-root> && npx ts-node -r tsconfig-paths/register \
+  --project apps/platform-api/tsconfig.json <path-to-script>
+```

package/src/tools/test-blueprints/skills/test-blueprints/scripts/validate.ts

@@ -0,0 +1,250 @@
+#!/usr/bin/env bun
+/**
+ * test-blueprints validate
+ *
+ * Validate blueprint .json.hbs templates against their Zod schema.
+ * Generates a temporary validation script in the workspace and runs it
+ * via ts-node so that tsconfig paths resolve correctly.
+ *
+ * Usage:
+ *   droid exec test-blueprints validate \
+ *     --workspace /path/to/orderful-workspace \
+ *     --schema-import "simplifiedSchemas/schemaFile" \
+ *     --schema-name "Simplified943Schema" \
+ *     --blueprints-dir "apps/platform-api/src/modules/testTransformation/data/testBlueprints/943s"
+ *
+ * Output (JSON):
+ *   {
+ *     "success": true,
+ *     "results": [
+ *       { "file": "943_standard.json.hbs", "status": "pass" },
+ *       { "file": "943_templated.json.hbs", "status": "skip", "reason": "contains Handlebars expressions" },
+ *       { "file": "943_bad.json.hbs", "status": "fail", "errors": [{ "path": "header.type", "message": "Invalid enum value" }] }
+ *     ],
+ *     "summary": { "pass": 8, "fail": 1, "skip": 2, "total": 11 }
+ *   }
+ */
+
+import { execSync } from 'child_process';
+import { existsSync, writeFileSync, unlinkSync, readdirSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+interface ValidationError {
+  path: string;
+  message: string;
+}
+
+interface FileResult {
+  file: string;
+  status: 'pass' | 'fail' | 'skip';
+  reason?: string;
+  errors?: ValidationError[];
+}
+
+interface ValidateResult {
+  success: boolean;
+  results?: FileResult[];
+  summary?: { pass: number; fail: number; skip: number; total: number };
+  error?: string;
+}
+
+interface ParsedArgs {
+  workspace?: string;
+  schemaImport?: string;
+  schemaName?: string;
+  blueprintsDir?: string;
+}
+
+function parseArgs(args: string[]): ParsedArgs {
+  const result: ParsedArgs = {};
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--workspace' && args[i + 1]) {
+      result.workspace = args[++i];
+    } else if (arg === '--schema-import' && args[i + 1]) {
+      result.schemaImport = args[++i];
+    } else if (arg === '--schema-name' && args[i + 1]) {
+      result.schemaName = args[++i];
+    } else if (arg === '--blueprints-dir' && args[i + 1]) {
+      result.blueprintsDir = args[++i];
+    }
+  }
+
+  return result;
+}
+
+function expandPath(p: string): string {
+  if (p.startsWith('~/')) {
+    return p.replace('~', process.env.HOME || '');
+  }
+  if (p.startsWith('$HOME/')) {
+    return p.replace('$HOME', process.env.HOME || '');
+  }
+  return p;
+}
+
+function validate(parsed: ParsedArgs): ValidateResult {
+  if (!parsed.workspace) {
+    return { success: false, error: 'Missing --workspace' };
+  }
+  if (!parsed.schemaImport) {
+    return { success: false, error: 'Missing --schema-import' };
+  }
+  if (!parsed.schemaName) {
+    return { success: false, error: 'Missing --schema-name' };
+  }
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(parsed.schemaName)) {
+    return { success: false, error: 'Invalid --schema-name: must be a valid identifier' };
+  }
+  if (/['"\n\r]/.test(parsed.schemaImport)) {
+    return { success: false, error: 'Invalid --schema-import: must not contain quotes or newlines' };
+  }
+  if (!parsed.blueprintsDir) {
+    return { success: false, error: 'Missing --blueprints-dir' };
+  }
+
+  const workspace = expandPath(parsed.workspace);
+  if (!existsSync(workspace)) {
+    return { success: false, error: `Workspace not found: ${workspace}` };
+  }
+
+  const blueprintsDir = parsed.blueprintsDir.startsWith('/')
+    ? parsed.blueprintsDir
+    : join(workspace, parsed.blueprintsDir);
+
+  if (!existsSync(blueprintsDir)) {
+    return { success: false, error: `Blueprints directory not found: ${blueprintsDir}` };
+  }
+
+  // Find .json.hbs files
+  const files = readdirSync(blueprintsDir).filter(f => f.endsWith('.json.hbs'));
+  if (files.length === 0) {
+    return { success: false, error: `No .json.hbs files found in ${blueprintsDir}` };
+  }
+
+  // Pre-check for Handlebars templates (skip these from Zod validation)
+  const results: FileResult[] = [];
+  const filesToValidate: string[] = [];
+
+  for (const file of files) {
+    const content = readFileSync(join(blueprintsDir, file), 'utf-8');
+    if (content.includes('{{')) {
+      results.push({ file, status: 'skip', reason: 'contains Handlebars expressions' });
+    } else {
+      // Check JSON parsability before sending to ts-node
+      try {
+        JSON.parse(content);
+        filesToValidate.push(file);
+      } catch (e) {
+        const err = e as Error;
+        results.push({ file, status: 'fail', errors: [{ path: '(root)', message: `Invalid JSON: ${err.message}` }] });
+      }
+    }
+  }
+
+  // If all files are skipped or failed JSON parse, return early
+  if (filesToValidate.length === 0) {
+    const summary = {
+      pass: 0,
+      fail: results.filter(r => r.status === 'fail').length,
+      skip: results.filter(r => r.status === 'skip').length,
+      total: results.length,
+    };
+    return { success: summary.fail === 0, results, summary };
+  }
+
+  // Generate validation script
+  const validationScript = `
+import { ${parsed.schemaName} } from '${parsed.schemaImport}';
+import * as fs from 'fs';
+import * as path from 'path';
+
+const dir = ${JSON.stringify(blueprintsDir)};
+const filesToValidate: string[] = ${JSON.stringify(filesToValidate)};
+const results: Array<{ file: string; status: string; errors?: Array<{ path: string; message: string }> }> = [];
+
+for (const file of filesToValidate) {
+  const content = fs.readFileSync(path.join(dir, file), 'utf-8');
+  const parsed = JSON.parse(content);
+  const result = ${parsed.schemaName}.safeParse(parsed);
+
+  if (result.success) {
+    results.push({ file, status: 'pass' });
+  } else {
+    results.push({
+      file,
+      status: 'fail',
+      errors: result.error.issues.map((issue: { path: (string | number)[]; message: string }) => ({
+        path: issue.path.join('.'),
+        message: issue.message,
+      })),
+    });
+  }
+}
+
+console.log(JSON.stringify(results));
+`.trim();
+
+  const scriptPath = join(tmpdir(), `_validate-${Date.now()}.ts`);
+
+  try {
+    writeFileSync(scriptPath, validationScript, 'utf-8');
+
+    const output = execSync(
+      `npx ts-node -r tsconfig-paths/register --project apps/platform-api/tsconfig.json ${JSON.stringify(scriptPath)}`,
+      {
+        cwd: workspace,
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+        timeout: 60_000,
+      }
+    );
+
+    let zodResults: Array<{ file: string; status: string; errors?: ValidationError[] }>;
+    try {
+      zodResults = JSON.parse(output.trim());
+    } catch {
+      return { success: false, error: `Failed to parse validation output: ${output}` };
+    }
+
+    for (const r of zodResults) {
+      results.push({
+        file: r.file,
+        status: r.status as 'pass' | 'fail',
+        errors: r.errors,
+      });
+    }
+  } catch (err: unknown) {
+    const error = err as { stderr?: string; message?: string };
+    return {
+      success: false,
+      error: `Validation script failed: ${error.stderr || error.message}`,
+    };
+  } finally {
+    try { unlinkSync(scriptPath); } catch { /* ignore cleanup errors */ }
+  }
+
+  // Sort results to match original file order
+  results.sort((a, b) => files.indexOf(a.file) - files.indexOf(b.file));
+
+  const summary = {
+    pass: results.filter(r => r.status === 'pass').length,
+    fail: results.filter(r => r.status === 'fail').length,
+    skip: results.filter(r => r.status === 'skip').length,
+    total: results.length,
+  };
+
+  return { success: summary.fail === 0, results, summary };
+}
+
+// Main
+const args = process.argv.slice(2);
+const parsed = parseArgs(args);
+const result = validate(parsed);
+console.log(JSON.stringify(result, null, 2));
+
+if (!result.success) {
+  process.exit(1);
+}