@orderful/droid 0.52.1 → 0.54.0

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:
@@ -32,6 +36,7 @@ Produce a single JSON object matching the schema in `references/output-schema.js
   "name": "string — short human-readable plan name (optional)",
   "category": "string — grouping category, e.g. org-provisioning (optional)",
   "evidence": {
+    "planSummary": "string — one-line plain-language summary, e.g. 'Provision org and billing for Acme Corp' (optional)",
     "reasoning": "string — your analysis of what needs to happen and why",
     "sourceSummary": "string — concise summary of what you found during research",
     "sourceRaw": "string — JSON-stringified raw source data from research (optional)",
@@ -53,9 +58,10 @@ Produce a single JSON object matching the schema in `references/output-schema.js
 
 ### Evidence Fields
 
-| Field           | Purpose                                                                                                 | Reviewer Experience                                          |
-| --------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
-| `reasoning`     | Your analysis — what needs to happen and why. Cite actual data from your research, not assumptions.     | First thing they read. Establishes trust.                    |
+| Field           | Purpose                                                                                                       | Reviewer Experience                                          |
+| --------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| `planSummary`   | Optional. One-line plain-language summary of the plan. Keep it short and specific — entity names, not jargon. | Shown in headers and card previews. Quick scan context.      |
+| `reasoning`     | Your analysis — what needs to happen and why. Cite actual data from your research, not assumptions.           | First thing they read. Establishes trust.                    |
 | `sourceSummary` | Concise summary of what you found. Include entity names, IDs, and states.                               | Quick scan to verify you looked at the right things.         |
 | `sourceRaw`     | Optional. JSON-stringified raw API responses or data snapshots.                                         | Expandable detail for reviewers who want to verify.          |
 | `impactSummary` | What changes if the plan is approved. Be specific — "creates org X with ISA ID Y" not "creates an org". | The core decision point. Reviewer approves based on this.    |
@@ -129,6 +135,7 @@ Say you've been asked to provision an Orderful org for a new customer. You've qu
 ```json
 {
   "evidence": {
+    "planSummary": "Provision org, billing, and welcome email for Acme Corp",
     "reasoning": "Salesforce account Acme Corp (SF-001234) was signed on 2026-03-01 and has no Orderful OrgID. No existing Orderful org matches by name or ISA ID. The account's primary contact is jane@acme.com. ISA ID derived from Customer_ISA_ID__c field: ACME001.",
     "sourceSummary": "Salesforce: Acme Corp (SF-001234), signed 2026-03-01, no OrgID. Orderful: no org named 'Acme Corp', no ISA ID 'ACME001' in use.",
     "sourceRaw": "{\"salesforce_account\":{\"Id\":\"SF-001234\",\"Name\":\"Acme Corp\",\"OrgID__c\":null,\"Customer_ISA_ID__c\":\"ACME001\"},\"orderful_org_search\":{\"results\":[]}}",
@@ -166,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/propose-plan/skills/propose-plan/references/output-schema.json

@@ -18,6 +18,10 @@
       "description": "Research findings and rationale supporting the plan",
       "required": ["reasoning", "sourceSummary", "impactSummary"],
       "properties": {
+        "planSummary": {
+          "type": "string",
+          "description": "One-line plain-language summary of the plan"
+        },
         "reasoning": {
           "type": "string",
           "description": "Analysis of what needs to happen and why"

package/dist/tools/webform/.claude-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "droid-webform",
+  "version": "0.1.0",
+  "description": "Generate PrintView webform templates for EDI transaction types. Reads Orderful JSON schemas and sample transactions, proposes a visual layout, then generates template code with reusable subsection items.",
+  "author": {
+    "name": "Orderful",
+    "url": "https://github.com/orderful"
+  },
+  "repository": "https://github.com/orderful/droid",
+  "license": "MIT",
+  "keywords": [
+    "droid",
+    "ai",
+    "webform"
+  ],
+  "skills": [
+    "./skills/webform/SKILL.md"
+  ],
+  "commands": [
+    "./commands/webform.md"
+  ]
+}

package/dist/tools/webform/TOOL.yaml

@@ -0,0 +1,26 @@
+name: webform
+description: "Generate PrintView webform templates for EDI transaction types. Reads Orderful JSON schemas and sample transactions, proposes a visual layout, then generates template code with reusable subsection items."
+version: 0.1.0
+status: beta
+audience:
+  - engineering
+  - product
+
+includes:
+  skills:
+    - name: webform
+      required: true
+  commands:
+    - name: webform
+      is_alias: false
+  agents: []
+
+dependencies: []
+
+config_schema:
+  schema_repo:
+    type: string
+    description: "Path to orderful-workspace repo (contains Orderful JSON schemas)"
+  ui_repo:
+    type: string
+    description: "Path to o2-app-ui repo (contains PrintView templates and subsection items)"

package/dist/tools/webform/commands/webform.md

@@ -0,0 +1,17 @@
+---
+name: webform
+description: "Generate PrintView webform templates for EDI transaction types"
+argument-hint: "{transaction-type} [sample-transaction-path-or-inline-json]"
+---
+
+# /webform
+
+**User invoked:** `/webform $ARGUMENTS`
+
+**Your task:** Invoke the **webform skill** with these arguments.
+
+## Examples
+
+- `/webform 850 ~/Downloads/sample-850.json` → Generate 850 template from sample
+- `/webform 812 ~/Downloads/812.edi` → Generate 812 template from EDI file
+- `/webform 997` → Start 997 template (will ask for sample transaction)

package/dist/tools/webform/skills/webform/SKILL.md

@@ -0,0 +1,354 @@
+---
+name: webform
+description: "Generate PrintView webform templates for EDI transaction types. Reads Orderful JSON schemas and sample transactions, proposes a visual layout, then generates template code with reusable subsection items. User prompts like '/webform 850 sample.json', 'create a webform for 810'."
+argument-hint: "{transaction-type} [sample-transaction-path-or-inline-json]"
+globs: []
+alwaysApply: false
+allowed-tools: [Read, Write, Edit, Glob, Grep, Bash, Agent]
+---
+
+# Webform Skill
+
+Generate PrintView webform templates for Orderful EDI transaction types.
+
+## When to Use
+
+- Creating a new webform/PrintView template for a transaction type
+- User says "webform", "print view", "create a template for {type}"
+
+## When NOT to Use
+
+- Modifying existing templates (just edit directly)
+- Working on forms-mapper shapes/node mappers (different system)
+
+## Configuration
+
+**IMPORTANT:** Run `droid config --get tools.webform` first and parse the JSON output. If paths are not configured, **ask the user** for them.
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `schema_repo` | (none) | Path to orderful-workspace repo (contains Orderful JSON schemas) |
+| `ui_repo` | (none) | Path to o2-app-ui repo (contains PrintView templates) |
+| `override` | (none) | User-defined behaviour overrides |
+
+**If not configured:** Ask the user:
+> "I need two repo paths to generate webform templates:
+> 1. **orderful-workspace** — where are the Orderful JSON schemas? (e.g., `~/Projects/orderful-workspace`)
+> 2. **o2-app-ui** — where are the PrintView templates? (e.g., `~/Projects/o2-app-ui`)"
+
+Then set their choices:
+```bash
+droid config --set tools.webform.schema_repo="{user's choice}"
+droid config --set tools.webform.ui_repo="{user's choice}"
+```
+
+### Derived Paths
+
+Once configured, derive all paths from the config:
+
+- **Schema location:** `{schema_repo}/libs/schemas/src/lib/data/transactionSchemas/orderful/{type}.schema.json`
+- **Template location:** `{ui_repo}/src/pages/Transaction/PrintView/templates/`
+- **Subsection items:** `{ui_repo}/src/pages/Transaction/PrintView/templates/subsectionItems/`
+- **Helpers:** `{ui_repo}/src/pages/Transaction/PrintView/templates/helpers.ts`
+- **Types:** `{ui_repo}/src/pages/Transaction/PrintView/types/index.ts`
+- **Tests:** `{ui_repo}/src/pages/Transaction/PrintView/templates/tests/templates.spec.ts`
+- **Allowed types:** `{ui_repo}/src/pages/Transaction/CreateTransaction/index.tsx`
+- **Print view routing:** `{ui_repo}/src/shared/helpers/printViewHelpers/getPrintViewComponentAndCsv.ts`
+
+**Overrides:** This skill supports user-defined overrides. See `/droid` skill § Skill Overrides for how to create, register, and use overrides.
+
+## Invocation
+
+```
+/webform {transaction-type} {sample-transaction}
+```
+
+- `transaction-type`: e.g., `850`, `810`, `997`
+- `sample-transaction`: file path to a JSON file, or inline JSON pasted by the user. If not provided, ask for it.
+
+## Workflow
+
+Follow these steps in order. Do NOT skip the visual layout step.
+
+### Step 1: Load Inputs
+
+1. **Read config** — run `droid config --get tools.webform` and parse the JSON. If not configured, ask the user.
+
+2. **Read the Orderful JSON schema** for the transaction type:
+   ```
+   {schema_repo}/libs/schemas/src/lib/data/transactionSchemas/orderful/{type}.schema.json
+   ```
+   This gives you field names (camelCase), titles, descriptions, and nesting structure. Pay attention to:
+   - `schemaType`: `element`, `segment`, `segmentArray`, `loop`, `loopArray`
+   - `title`: human-readable name like "BEG03 - Purchase Order Number"
+   - `segmentIdentifier`: X12 segment ID like "BEG", "N1", "PO1"
+
+3. **Parse the sample transaction** (file or inline JSON). This determines which segments/loops are actually used and should appear in the template. **Only model what's in the sample — not every possible field in the schema.**
+
+### Step 2: Inventory Existing Subsection Items
+
+Scan the existing subsection items directory:
+```
+{ui_repo}/src/pages/Transaction/PrintView/templates/subsectionItems/
+```
+
+Build a map of what already exists. Read the `index.ts` barrel file and glob for all `.ts` files. For each item, note:
+- The segment/loop it handles (e.g., `BEG`, `N1_loop`, `DTM`)
+- Whether it exports a block, table, or both variants
+- The `parentPath` it expects
+
+**CRITICAL: X12 is composed of shared building blocks. The same segment (N1, DTM, REF, etc.) appears across many transaction types. ALWAYS reuse existing subsection items. NEVER duplicate.**
+
+**NAMING: Subsection items must NOT include transaction type suffixes (e.g., `CDD_loop`, not `CDD_loop_812`).** Subsection items represent reusable X12 building blocks, not transaction-specific components. Some existing items like `PO1_loop_850` have this antipattern — do not follow that convention. Name items after the segment/loop they represent (e.g., `BCD`, `SHD`, `CDD_loop`).
+
+### Step 3: Map Sample to Subsection Items
+
+Walk the sample transaction's `transactionSets` structure. For each segment or loop present:
+
+1. **Check if a subsection item already exists** → mark as EXISTING
+2. **Check if it exists but needs additional fields** for this transaction type → mark as EXTEND
+3. **No subsection item exists** → mark as NEW
+
+Use the schema to determine:
+- Field labels (from `title`, strip the element ID prefix like "BEG03 - ")
+- Field types (`ElementType`: Alphanumeric, Numeric, Date, Time, etc. — infer from `X12DataElementType` or schema `type`)
+- Whether a field value comes from a qualifier code (use `QualifiedValueFieldMapItem` or `QualifiedLabelFieldMapItem`)
+- Whether data is a single record (→ block) or repeating array (→ table)
+
+### Step 4: Propose Visual Layout
+
+Present an ASCII/markdown layout to the user showing the proposed template structure. This is the most important step — **wait for user approval before generating any code.**
+
+Format:
+
+```
+# Proposed Webform: {type} - {title}
+
+## Section 1: {Section Title}
+
+  [{SEGMENT}] {Description} (block) ← EXISTING
+   • {Field Label}    • {Field Label}    • {Field Label}
+   • {Field Label}    • {Field Label}
+
+  [{SEGMENT}] {Description} (table) ← NEW
+   | {Column 1} | {Column 2} | {Column 3} |
+
+## Section 2: {Section Title}
+
+  [{LOOP}] {Description} (block, 2-col) ← EXISTING
+   • {Field Label}    • {Field Label}
+   ...
+
+## Section N: Totals
+
+  [footer] ← EXISTING (footer_CTT_loop)
+   Left: {fields}    Right: {fields}
+```
+
+For each subsection item, clearly indicate:
+- `EXISTING` — will import and reuse as-is
+- `EXTEND` — exists but needs fields added (list which fields)
+- `NEW` — will create a new reusable subsection item
+
+**Grouping guidance** (based on existing templates):
+- Header/general info segments go in the first section (BEG/BAK/BIG + CUR, PER, CSH, REF, N9)
+- Allowances/charges (SAC_loop) get their own section if present
+- Additional info segments together (ITD, FOB, DTM, PID, TD5, etc.)
+- Party identification (N1_loop) gets its own section, typically as `block--two-col`
+- Line items loop gets its own section with `countPath`
+- Totals/footer in the last section
+
+### Step 5: Iterate on Feedback
+
+The user may request changes:
+- Regroup sections
+- Add/remove fields
+- Change block ↔ table rendering
+- Adjust column layout for tables
+
+Iterate until the user confirms the layout.
+
+### Step 6: Generate Code
+
+Once approved, generate the template and any new subsection items.
+
+#### Template File
+
+Create `{ui_repo}/src/pages/Transaction/PrintView/templates/{type}.template.ts`
+
+Follow the exact patterns from existing templates. Example structure:
+
+```typescript
+import { PrintViewTemplate } from './types';
+import {
+  BEG,
+  CUR,
+  // ... other imports from subsectionItems
+} from './subsectionItems';
+
+export const template: PrintViewTemplate = [
+  {
+    sectionTitle: 'Section Title',
+    subsections: [
+      [BEG],
+      [CUR],
+    ],
+  },
+  // ... more sections
+];
+```
+
+Key patterns:
+- Each section is a `PrintViewPredefinedSection` with `sectionTitle` and `subsections`
+- `subsections` is an array of arrays — each inner array is a group of subsection items rendered together
+- Line item sections use `countPath` pointing to the loop array path (e.g., `'PO1_loop'`)
+- Party sections typically use `block--two-col` layout via the subsection item's `subsectionType`
+
+#### New Subsection Items
+
+For each NEW item, create a file in `subsectionItems/`:
+```
+{ui_repo}/src/pages/Transaction/PrintView/templates/subsectionItems/{Name}.ts
+```
+
+Follow existing patterns exactly. Key rules:
+- Import types from `'../types'`
+- Use `ElementType` enum for field value types
+- For blocks: set `subsectionType: 'block'` or `'block--two-col'`
+- For tables: set `subsectionType: 'table'`
+- For footers: set `subsectionType: 'footer'` with `leftFieldMap` and `rightFieldMap`
+- `parentPath` should use the Orderful JSON path (e.g., `'beginningSegmentForPurchaseOrder'`)
+- Field `valuePath` is relative to the parentPath
+- For qualifier fields, use `valueQualifierPath` or `labelQualifierPath`
+- Export the item as a named const
+
+#### Extended Subsection Items
+
+For EXTEND items, propose the specific `Edit` changes to add new fields to the existing file. Show the user what will change before applying.
+
+#### Register in helpers.ts
+
+Add the new template to the `loadPrintViewTemplate` switch/map in:
+```
+{ui_repo}/src/pages/Transaction/PrintView/templates/helpers.ts
+```
+
+#### Update barrel exports
+
+Add any new subsection items to:
+```
+{ui_repo}/src/pages/Transaction/PrintView/templates/subsectionItems/index.ts
+```
+
+#### Add TransactionType enum value
+
+If this transaction type isn't already in the `TransactionType` enum, add it to:
+```
+{ui_repo}/src/pages/Transaction/PrintView/types/index.ts
+```
+
+Follow the naming convention: `SCREAMING_SNAKE_CASE = '{type}_{SCREAMING_SNAKE_NAME}'` (e.g., `CREDIT_DEBIT_ADJUSTMENT = '812_CREDIT_DEBIT_ADJUSTMENT'`).
+
+#### Add to ALLOWED_TRANSACTION_TYPES
+
+If this is a new transaction type, add it to the `ALLOWED_TRANSACTION_TYPES` array in:
+```
+{ui_repo}/src/pages/Transaction/CreateTransaction/index.tsx
+```
+
+#### Wire up PrintView component
+
+Update the print view routing in:
+```
+{ui_repo}/src/shared/helpers/printViewHelpers/getPrintViewComponentAndCsv.ts
+```
+
+If there's an existing legacy component for this transaction type, replace it with `PrintView`. If there's no existing case, add one:
+```typescript
+case '{type_enum_value}':
+  printViewComponent = PrintView;
+  break;
+```
+
+#### Add to test coverage
+
+Add the transaction type to `testedTransactionSets` in:
+```
+{ui_repo}/src/pages/Transaction/PrintView/templates/tests/templates.spec.ts
+```
+
+This test validates that all paths in the template exist in the schema. The template **must** pass this test — if paths don't resolve, the field names in subsection items are wrong.
+
+### Step 7: Summary
+
+After generating, provide a summary:
+- Files created (with paths)
+- Files modified (with description of changes)
+- Existing subsection items reused
+- Any items that were extended
+
+## Type Reference
+
+Quick reference for the template type system (defined in `templates/types.ts`):
+
+### Subsection Item Types
+
+| Type | Use When | Key Fields |
+|------|----------|------------|
+| Block (static header) | Single record, fixed title | `subsectionType`, `header`, `parentPath`, `fieldMap` |
+| Block (dynamic header) | Single record, title from data | `subsectionType`, `headerQualifierPath`, `parentPath`, `fieldMap` |
+| Table (static header) | Repeating records, fixed title | `subsectionType`, `header`, `parentPath`, `columns` |
+| Table (dynamic header) | Repeating records, title from data | `subsectionType`, `headerQualifierPath`, `parentPath`, `columns` |
+| Footer | Totals/summary | `subsectionType: 'footer'`, `parentPath`, `leftFieldMap`, `rightFieldMap` |
+| Hierarchy | HL loops (856 only) | `subsectionType: 'hierarchy'`, complex nesting |
+
+### FieldMapItem Types
+
+| Type | Use When | Key Fields |
+|------|----------|------------|
+| DirectFieldMapItem | Simple label + value | `label`, `valuePath`, `valueType` |
+| QualifiedLabelFieldMapItem | Label comes from a code qualifier | `labelQualifierPath`, `valuePath`, `valueType` |
+| QualifiedValueFieldMapItem | The qualifier code IS the display value | `label`, `valueQualifierPath` |
+
+### Table Column Types
+
+| Type | Use When | Key Fields |
+|------|----------|------------|
+| TableStaticValueColumn | Simple column | `header`, `valuePath`, `valueType` |
+| TableQualifiedValueColumn | Column value from qualifier | `header`, `valueQualifierPath` |
+| TableFieldMapColumn | Multiple fields in one column | `header`, `fieldMap` |
+| NestedTableColumn | Blocks nested inside column | `header`, `subsections` |
+
+### ValueFormat
+
+Use `valueFormat` on DirectFieldMapItem when needed:
+- `'currency'` — e.g., $123.45
+- `'signedCurrency'` — with +/- sign
+- `'percent'` — e.g., 15%
+- `'decimalPercent'` — e.g., 0.15
+
+### ElementType
+
+Common values: `Alphanumeric`, `Numeric`, `Date`, `Time`, `ID`
+
+## Existing Subsection Items
+
+**Do NOT hardcode this list — always scan the subsectionItems directory at runtime.** This list is for reference only and may be outdated.
+
+### High Reuse (4+ templates)
+N1_loop, DTM (table + block), REF (table + block), SAC_loop, SAC_loop_block, FOB (table + block), TD5 (table + block), PID (table + block)
+
+### Medium Reuse (2-3 templates)
+CUR, PER, CSH, ITD, MEA (table + block), TD1, NTE, MAN, LIN, AMT, CAD, PKG, QTY, TXI
+
+### Transaction-Specific Headers
+BEG (850), BAK (855), BIG (810), BIA (846), BSN (856), G82 (875/880), BCD (812)
+
+### Line Item Loops
+PO1_loop_850, PO1_loop_855, IT1_loop_810, CDD_loop, G68_loop, G83_loop, HL_loop + HL_loop_items
+
+### Footers
+footer_CTT, footer_CTT_loop, footer_TDS_CTT, footer_G76, footer_G84
+
+### Other
+ISS_loop, LIN_loop, R4, V1, SDQ, SCH, LDT, PRF, PO4, SN1, IT3, TD3, TD4_block, MTX, YNQ, N9 (block + loop + table), SHD, G01-G86 (grocery segments), constants

package/package.json

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

package/src/bin/droid.ts

@@ -21,6 +21,7 @@ import { integrationsSetupSlackCommand, integrationsStatusCommand, slackPostComm
 import { getVersion } from '../lib/version';
 import { loadConfig, saveConfig, configExists } from '../lib/config';
 import { syncNewPlatforms } from '../lib/platforms';
+import { copySkillsCommand } from '../commands/copy-skills';
 
 const version = getVersion();
 
@@ -120,6 +121,14 @@ program
   .allowUnknownOption()
   .action(execCommand);
 
+program
+  .command('copy-skills')
+  .description('Copy bundled skills to a destination directory')
+  .requiredOption('-d, --dest <dir>', 'Destination directory')
+  .option('-m, --manifest <file>', 'JSON file with array of skill names')
+  .option('-n, --names <names...>', 'Skill names to copy')
+  .action(copySkillsCommand);
+
 // Integrations command with subcommands
 const integrations = program
   .command('integrations')

package/src/commands/copy-skills.ts

@@ -0,0 +1,66 @@
+import chalk from 'chalk';
+import { readFileSync } from 'fs';
+import { copySkillsToDir } from '../lib/skills';
+
+interface CopySkillsOptions {
+  dest: string;
+  manifest?: string;
+  names?: string[];
+}
+
+/**
+ * Copy bundled skills to a destination directory.
+ *
+ * Usage:
+ *   droid copy-skills -d dist/assets/skills -m droid-skills.json
+ *   droid copy-skills -d dist/assets/skills -n propose-plan edi-schema
+ */
+export function copySkillsCommand(options: CopySkillsOptions): void {
+  const { dest, manifest, names } = options;
+
+  // Resolve skill names from manifest file or --names flag
+  let skillNames: string[];
+
+  if (manifest) {
+    try {
+      const content = readFileSync(manifest, 'utf-8');
+      skillNames = JSON.parse(content);
+      if (!Array.isArray(skillNames)) {
+        console.error(
+          chalk.red('Manifest must be a JSON array of skill names'),
+        );
+        process.exit(1);
+      }
+    } catch (err) {
+      console.error(chalk.red(`Failed to read manifest: ${err}`));
+      process.exit(1);
+    }
+  } else if (names?.length) {
+    skillNames = names;
+  } else {
+    console.error(
+      chalk.red('Provide either --manifest <file> or --names <names...>'),
+    );
+    process.exit(1);
+  }
+
+  if (skillNames.length === 0) {
+    console.log(chalk.yellow('No skills to copy.'));
+    return;
+  }
+
+  const results = copySkillsToDir(skillNames, dest);
+
+  for (const result of results) {
+    if (result.success) {
+      console.log(chalk.green(`  ✓ ${result.name} → ${result.dest}`));
+    } else {
+      console.error(chalk.red(`  ✗ ${result.name}: ${result.error}`));
+    }
+  }
+
+  const failed = results.filter((r) => !r.success);
+  if (failed.length > 0) {
+    process.exit(1);
+  }
+}

package/src/index.ts

@@ -2,4 +2,6 @@
 export * from './lib/types';
 export * from './lib/config';
 export * from './lib/skills';
+export * from './lib/tools';
+export * from './lib/pack';
 export * from './lib/version';

package/src/lib/skills.ts

@@ -213,6 +213,69 @@ export function findSkillPath(
   return null;
 }
 
+/**
+ * Resolve the absolute path to a bundled skill directory by name.
+ * Returns null if the skill is not found.
+ *
+ * This is the stable public API for consumers who need to locate skill
+ * assets (e.g., for copying into a build output). It encapsulates droid's
+ * internal `tools/{tool}/skills/{name}/` directory structure.
+ */
+export function getSkillPath(skillName: string): string | null {
+  const result = findSkillPath(skillName);
+  return result?.skillDir ?? null;
+}
+
+/**
+ * Copy bundled skills to a destination directory.
+ * Each skill is copied as `{dest}/{skillName}/` with SKILL.md, references/, etc.
+ *
+ * @param skillNames - Array of skill names to copy
+ * @param dest - Target directory (created if it doesn't exist)
+ * @returns Results per skill: success/failure with paths
+ */
+export function copySkillsToDir(
+  skillNames: string[],
+  dest: string,
+): Array<{ name: string; success: boolean; dest?: string; error?: string }> {
+  if (!existsSync(dest)) {
+    mkdirSync(dest, { recursive: true });
+  }
+
+  const results: Array<{
+    name: string;
+    success: boolean;
+    dest?: string;
+    error?: string;
+  }> = [];
+
+  for (const name of skillNames) {
+    const skillDir = getSkillPath(name);
+    if (!skillDir) {
+      results.push({
+        name,
+        success: false,
+        error: `Skill '${name}' not found in bundled tools`,
+      });
+      continue;
+    }
+
+    const targetDir = join(dest, name);
+    try {
+      copyDirectoryRecursive(skillDir, targetDir, () => true);
+      results.push({ name, success: true, dest: targetDir });
+    } catch (err) {
+      results.push({
+        name,
+        success: false,
+        error: `Failed to copy: ${err}`,
+      });
+    }
+  }
+
+  return results;
+}
+
 /**
  * Get all bundled skills from all tools
  */