@orderful/droid 0.53.0 → 0.55.0

package/.claude-plugin/plugin.json

@@ -33,6 +33,8 @@
     "./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"
   ],
   "commands": [
@@ -52,6 +54,8 @@
     "./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"
   ],
   "agents": [

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @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
+
+- [#329](https://github.com/Orderful/droid/pull/329) [`ee57191`](https://github.com/Orderful/droid/commit/ee57191e4c13e23703df561b3d56182fe6da62b7) Thanks [@theabuitendyk](https://github.com/theabuitendyk)! - Add webform tool
+
+### Patch Changes
+
+- [#326](https://github.com/Orderful/droid/pull/326) [`d5b2cca`](https://github.com/Orderful/droid/commit/d5b2ccabe1486086ec3f5f1bbd9c36a64a3387f0) Thanks [@frytyler](https://github.com/frytyler)! - Add findings-only and partial plan support to propose-plan skill
+
 ## 0.53.0
 
 ### Minor Changes

package/README.md

@@ -116,6 +116,7 @@ Browse available tools, see what's installed, and manage everything from one pla
 | **tech-design** | Three-document approach for technical designs                     | beta   |
 | **wrapup**      | Session wrap-up that captures decisions to persistent docs        | alpha  |
 | **status-update** | Generate and post project status updates to Slack               | beta   |
+| **webform**       | Generate PrintView webform templates for EDI transaction types  | beta   |
 
 ### Comments
 
@@ -187,7 +188,26 @@ Post project status updates to Slack:
 /status-update              # Generate and post status update
 ```
 
-Pulls context from codex projects and Jira, formats with phase checklists, posts to Slack (or prints to terminal). Requires one-time setup:
+Pulls context from codex projects and Jira, formats with phase checklists, posts to Slack (or prints to terminal).
+
+### Webform
+
+Generate PrintView webform templates from Orderful JSON schemas and sample transactions:
+
+```bash
+/webform 850 ~/Downloads/sample-850.json   # Generate from sample
+/webform 812 ~/Downloads/812.edi           # Generate from EDI file
+/webform 997                               # Start (will ask for sample)
+```
+
+Proposes a visual layout for approval, then generates template code with reusable subsection items. Requires configuration:
+
+```bash
+droid config --set tools.webform.schema_repo="~/Projects/orderful-workspace"
+droid config --set tools.webform.ui_repo="~/Projects/o2-app-ui"
+```
+
+Requires one-time setup:
 
 ```bash
 droid auth slack            # Set up Slack OAuth (per user)

package/dist/tools/propose-plan/skills/propose-plan/SKILL.md

@@ -23,6 +23,10 @@ A plan has two parts:
 
 The human reviewer sees your evidence first (the reasoning and impact), then reviews each action. Clear evidence builds trust; vague evidence gets rejected.
 
+**An empty actions array is valid.** If your research shows no writes are needed — conflicts block all operations, the work is already done, or the situation requires human input before any action can be proposed — return `"actions": []` with evidence explaining why. This is a "findings only" output. The reviewer still gets your analysis.
+
+**Partial plans are also valid.** If some items are blocked but others are clear, include actions only for the clear ones. Flag blocked items in caveats with specific reasons. Don't skip the entire plan because one item has a conflict.
+
 ## Output Format
 
 Produce a single JSON object matching the schema in `references/output-schema.json`. The shape:
@@ -169,7 +173,8 @@ These are hard rules. Violating any of them will cause the plan to be rejected o
 - **Don't include read operations as actions.** Actions are for writes only — things that change state and need human approval. Reading data is research, not an action. If you need to look something up, use read tools directly during your research phase.
 - **Don't fabricate data.** If a value wasn't in your research and you can't verify it with read tools, say so in caveats. Never guess IDs, names, emails, or configuration values. A plan with honest gaps gets sent back for more research. A plan with invented data gets approved and breaks things.
 - **Don't produce actions for tools outside your available list.** You can only propose actions for tools you've been given. If an operation requires a tool you don't have, note it as a caveat — don't invent an action for it. The execution step will reject unknown tools.
-- **Don't skip evidence.** A plan without evidence will be rejected. The reviewer needs to see what you found, what it means, and what will change. Evidence is not optional filler — it is how the reviewer decides whether to approve.
+- **Don't skip evidence.** A plan without evidence will be rejected — even if the actions array is empty. The reviewer needs to see what you found, what it means, and what will change. Evidence is not optional filler — it is how the reviewer decides whether to approve.
+- **Don't force actions when none are possible.** If conflicts or preconditions block all operations, return an empty actions array with evidence explaining why. A findings-only plan is better than a plan with actions that will fail.
 - **Don't combine multiple operations into one action.** Each action is one tool call. "Create org and set up billing" is two actions, not one. The execution step calls each action individually — a combined action will fail.
 - **Don't hardcode values from actions that haven't run yet.** If action 2 needs the org ID from action 1, don't guess or invent a value — use a template reference: `"orgId": "{{ actions.0.result.id }}"`. The execution step resolves these at runtime. Never put a placeholder like `"TBD"` or `"<org-id>"` in a payload.
 - **Don't use vague descriptions.** "Create org" tells the reviewer nothing. "Create Orderful org 'Acme Corp' with ISA ID 'ACME001'" tells them exactly what will happen. The description is what the reviewer reads before deciding whether to expand the payload.

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"}