@orderful/droid 0.51.0 → 0.52.1

package/.claude-plugin/plugin.json

@@ -28,6 +28,7 @@
     "./src/tools/pii/skills/pii/SKILL.md",
     "./src/tools/plan/skills/plan/SKILL.md",
     "./src/tools/project/skills/project/SKILL.md",
+    "./src/tools/propose-plan/skills/propose-plan/SKILL.md",
     "./src/tools/release/skills/release/SKILL.md",
     "./src/tools/share/skills/share/SKILL.md",
     "./src/tools/status-update/skills/status-update/SKILL.md",

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @orderful/droid
 
+## 0.52.1
+
+### Patch Changes
+
+- [#321](https://github.com/Orderful/droid/pull/321) [`235a4b3`](https://github.com/Orderful/droid/commit/235a4b32d735136c79b66aacca6097f42559c94c) Thanks [@frytyler](https://github.com/frytyler)! - Align propose-plan skill with Zod v4 structured output constraint: payload and sourceRaw as JSON-stringified strings
+
+## 0.52.0
+
+### Minor Changes
+
+- [#320](https://github.com/Orderful/droid/pull/320) [`89e37e0`](https://github.com/Orderful/droid/commit/89e37e03899ce34d01de09ed43ad2fff2c171af8) Thanks [@frytyler](https://github.com/frytyler)! - Add `propose-plan` tool — structured plans with evidence and actions for human-in-the-loop approval
+
+### Patch Changes
+
+- [#318](https://github.com/Orderful/droid/pull/318) [`87bb797`](https://github.com/Orderful/droid/commit/87bb797bb1cd53d89c4a946401abdb9210542eab) Thanks [@frytyler](https://github.com/frytyler)! - Add `--tool` flag to `droid pack` for single-tool downloads
+
 ## 0.51.0
 
 ### Minor Changes

package/dist/bin/droid.js

@@ -5215,7 +5215,7 @@ function collectToolArtifacts(tool) {
     }
     const refsDir = join14(skillDir, "references");
     if (existsSync12(refsDir)) {
-      const refFiles = readdirSync7(refsDir).filter((f) => f.endsWith(".md"));
+      const refFiles = readdirSync7(refsDir).filter((f) => !f.startsWith("."));
       for (const file of refFiles) {
         artifacts.push({
           sourcePath: join14(refsDir, file),
@@ -5269,9 +5269,9 @@ function generateClaudeMd(tools) {
   lines.push("");
   return lines.join("\n");
 }
-function generateReadme(audience, tools) {
+function generateReadme(label, tools) {
   const lines = [
-    `# Droid Pack: ${audience}`,
+    `# Droid Pack: ${label}`,
     "",
     "This pack contains AI skills, commands, and agents for Claude Desktop.",
     "",
@@ -5317,6 +5317,49 @@ function checkDependencies(tools) {
   }
   return warnings;
 }
+async function buildToolPack(options) {
+  const { toolName, outputDir } = options;
+  const allTools = getBundledTools();
+  const tool = allTools.find((t) => t.name === toolName);
+  if (!tool) {
+    return {
+      success: false,
+      message: `Tool '${toolName}' not found`
+    };
+  }
+  const tools = [tool];
+  const warnings = checkDependencies(tools);
+  const filename = `droid-${toolName}.zip`;
+  const outputPath = join14(outputDir, filename);
+  return new Promise((resolve) => {
+    const output = createWriteStream(outputPath);
+    const archive = archiver("zip", { zlib: { level: 9 } });
+    output.on("close", () => {
+      resolve({
+        success: true,
+        message: `Pack created: ${filename}`,
+        outputPath,
+        toolCount: 1,
+        warnings: warnings.length > 0 ? warnings : void 0
+      });
+    });
+    archive.on("error", (err) => {
+      resolve({
+        success: false,
+        message: `Failed to create pack: ${err.message}`
+      });
+    });
+    archive.pipe(output);
+    const artifacts = collectToolArtifacts(tool);
+    for (const artifact of artifacts) {
+      const content = readFileSync11(artifact.sourcePath, "utf-8");
+      archive.append(content, { name: artifact.zipPath });
+    }
+    archive.append(generateClaudeMd(tools), { name: "CLAUDE.md" });
+    archive.append(generateReadme(toolName, tools), { name: "README.md" });
+    archive.finalize();
+  });
+}
 async function buildPack(options) {
   const { audience, outputDir } = options;
   const tools = getToolsForAudience(audience);
@@ -5381,9 +5424,34 @@ async function packCommand(audience, options) {
     console.log("");
     return;
   }
+  if (options.tool) {
+    const outputDir2 = options.output || process.cwd();
+    console.log(
+      chalk10.bold(`
+Packing tool ${chalk10.cyan(options.tool)}...`)
+    );
+    const result2 = await buildToolPack({ toolName: options.tool, outputDir: outputDir2 });
+    if (!result2.success) {
+      console.error(chalk10.red(`
+${result2.message}`));
+      process.exit(1);
+    }
+    console.log(chalk10.green(`
+${result2.message}`));
+    console.log(chalk10.gray(`  Output: ${result2.outputPath}`));
+    if (result2.warnings && result2.warnings.length > 0) {
+      console.log(chalk10.yellow("\nWarnings:"));
+      for (const warning of result2.warnings) {
+        console.log(chalk10.yellow(`  - ${warning}`));
+      }
+    }
+    console.log("");
+    return;
+  }
   if (!audience) {
     console.error(chalk10.red("\nError: audience argument required"));
     console.log(chalk10.gray("Usage: droid pack <audience>"));
+    console.log(chalk10.gray("       droid pack --tool <name>"));
     console.log(chalk10.gray("       droid pack --list"));
     process.exit(1);
   }
@@ -6051,7 +6119,7 @@ program.command("install <tool>").description("Install a tool and run its setup
 program.command("uninstall <tool>").description("Uninstall a tool").action(uninstallCommand);
 program.command("update").description("Update droid and installed tools").option("--tools", "Only update tools").option("--cli", "Only update the CLI").argument("[tool]", "Update a specific tool").action(updateCommand);
 program.command("tui").description("Launch interactive TUI dashboard").action(tuiCommand);
-program.command("pack").description("Create audience-filtered zip packs for distribution").argument("[audience]", "Target audience (e.g., engineering, customer-support)").option("-l, --list", "List available audiences and tool counts").option("-o, --output <dir>", "Output directory (default: cwd)").action(packCommand);
+program.command("pack").description("Create zip packs for distribution").argument("[audience]", "Target audience (e.g., engineering, customer-support)").option("-l, --list", "List available audiences and tool counts").option("-t, --tool <name>", "Pack a single tool by name").option("-o, --output <dir>", "Output directory (default: cwd)").action(packCommand);
 program.command("exec <tool> <script>").description("Execute a tool script").argument("[args...]", "Arguments to pass to the script").allowUnknownOption().action(execCommand);
 var integrations = program.command("integrations").description("Manage external service integrations");
 var integrationsSetup = integrations.command("setup").description("Set up an integration");

package/dist/commands/pack.d.ts

@@ -1,5 +1,6 @@
 export declare function packCommand(audience: string | undefined, options: {
     list?: boolean;
     output?: string;
+    tool?: string;
 }): Promise<void>;
 //# sourceMappingURL=pack.d.ts.map

package/dist/commands/pack.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pack.d.ts","sourceRoot":"","sources":["../../src/commands/pack.ts"],"names":[],"mappings":"AAQA,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,OAAO,EAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAC3C,OAAO,CAAC,IAAI,CAAC,CAiEf"}
+{"version":3,"file":"pack.d.ts","sourceRoot":"","sources":["../../src/commands/pack.ts"],"names":[],"mappings":"AAQA,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,OAAO,EAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAC1D,OAAO,CAAC,IAAI,CAAC,CA+Ff"}

package/dist/lib/pack.d.ts

@@ -8,6 +8,10 @@ export interface PackOptions {
     audience: ToolAudience;
     outputDir: string;
 }
+export interface ToolPackOptions {
+    toolName: string;
+    outputDir: string;
+}
 export interface PackResult {
     success: boolean;
     message: string;
@@ -24,6 +28,10 @@ export declare function getToolsForAudience(audience: ToolAudience): ToolManifes
  * Get audience info for all audiences that have tools
  */
 export declare function getAudienceInfo(): AudienceInfo[];
+/**
+ * Build a zip pack for a single tool
+ */
+export declare function buildToolPack(options: ToolPackOptions): Promise<PackResult>;
 /**
  * Build a zip pack for the given audience
  */

package/dist/lib/pack.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pack.d.ts","sourceRoot":"","sources":["../../src/lib/pack.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,SAAS,CAAC;AAE1D,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,YAAY,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,YAAY,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,YAAY,GACrB,YAAY,EAAE,CAehB;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,YAAY,EAAE,CAsBhD;AA4JD;;GAEG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CA4DzE"}
+{"version":3,"file":"pack.d.ts","sourceRoot":"","sources":["../../src/lib/pack.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,SAAS,CAAC;AAE1D,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,YAAY,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,YAAY,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,YAAY,GACrB,YAAY,EAAE,CAehB;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,YAAY,EAAE,CAsBhD;AA4JD;;GAEG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC,CAqDjF;AAED;;GAEG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CA4DzE"}

package/dist/tools/propose-plan/.claude-plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "droid-propose-plan",
+  "version": "0.1.0",
+  "description": "Produce structured plans with evidence and actions for human approval in Orderful Agents. Use when an agent must propose write operations that require human-in-the-loop review before execution.",
+  "author": {
+    "name": "Orderful",
+    "url": "https://github.com/orderful"
+  },
+  "repository": "https://github.com/orderful/droid",
+  "license": "MIT",
+  "keywords": [
+    "droid",
+    "ai",
+    "propose-plan"
+  ],
+  "skills": [
+    "./skills/propose-plan/SKILL.md"
+  ]
+}

package/dist/tools/propose-plan/TOOL.yaml

@@ -0,0 +1,17 @@
+name: propose-plan
+description: "Produce structured plans with evidence and actions for human approval in Orderful Agents. Use when an agent must propose write operations that require human-in-the-loop review before execution."
+version: 0.1.0
+status: beta
+audience:
+  - all
+
+includes:
+  skills:
+    - name: propose-plan
+      required: true
+  commands: []
+  agents: []
+
+dependencies: []
+
+config_schema: {}

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

@@ -0,0 +1,172 @@
+---
+name: propose-plan
+description: "Produce a structured plan with evidence and actions for human approval. Use when an agent must propose write operations, research current state before making changes, or produce actions that require human-in-the-loop review before execution."
+globs: []
+alwaysApply: false
+allowed-tools: []
+---
+
+# Propose Plan
+
+Structure your findings into a plan for human approval. Use this skill when you've researched the current state, understand what needs to happen, and are ready to propose the specific actions to take.
+
+This skill teaches you how to package what you've learned into structured evidence and discrete actions that a reviewer can approve, modify, or reject before anything is executed.
+
+Never call write tools directly. Each proposed write is described as an **action** in your plan output. Approved actions are executed separately after human review.
+
+## Plan Structure
+
+A plan has two parts:
+
+1. **Evidence** — your analysis of the gathered context: what it shows, why changes are needed, and what will happen if the plan is approved
+2. **Actions** — an ordered list of discrete operations to execute, each mapped to a specific tool call
+
+The human reviewer sees your evidence first (the reasoning and impact), then reviews each action. Clear evidence builds trust; vague evidence gets rejected.
+
+## Output Format
+
+Produce a single JSON object matching the schema in `references/output-schema.json`. The shape:
+
+```json
+{
+  "name": "string — short human-readable plan name (optional)",
+  "category": "string — grouping category, e.g. org-provisioning (optional)",
+  "evidence": {
+    "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)",
+    "impactSummary": "string — what will change if this plan is approved",
+    "caveats": ["string — anything uncertain, auto-generated, or requiring follow-up"]
+  },
+  "actions": [
+    {
+      "type": "mcp_call",
+      "config": {
+        "tool": "string — the tool name exactly as you see it in your available tools"
+      },
+      "description": "string — human-readable description of what this action does",
+      "payload": "string — JSON-stringified arguments to pass to the tool"
+    }
+  ]
+}
+```
+
+### 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.                    |
+| `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.    |
+| `caveats`       | Optional. Flag anything uncertain, auto-generated, or needing manual follow-up.                         | Prevents surprises. Reviewers appreciate honesty about gaps. |
+
+### Action Fields
+
+| Field         | Purpose                                                                                                                                          |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `type`        | Action category. Use `mcp_call` for MCP tool invocations.                                                                                   |
+| `config`      | Identifies which tool to call. For `mcp_call`: `{ "tool": "create_org" }`. Use the tool name exactly as it appears in your available tools. |
+| `description` | Human-readable summary. The reviewer sees this before expanding the payload. Write it for someone who won't read the raw payload.                |
+| `payload`     | JSON-stringified arguments passed to the tool. Stringify the object — `JSON.stringify({...})` — don't nest it raw.                                |
+
+## Building Evidence From What You Know
+
+By the time you're writing a plan, you've already done the research — queried tools, read documents, collected the data you need. Your job now is to analyse what you found and structure it into a plan.
+
+If read tools are still available, use them to **verify and fill gaps** — check for conflicts, confirm preconditions, resolve ambiguities. But the research phase is behind you. Focus on structuring what you know into clear evidence and precise actions.
+
+When writing evidence:
+
+1. **Cite the gathered data** — reference specific entities, IDs, and values. A reviewer can't verify "the account exists" but they can verify "Salesforce account SF-001234 (Acme Corp) has no OrgID".
+2. **Flag conflicts** — if the gathered data reveals duplicates, collisions, or unexpected state, surface that prominently.
+3. **Note gaps** — if data is missing or ambiguous, say so in caveats rather than guessing. A plan with honest gaps is more useful than one with invented data.
+
+## Writing Actions
+
+Each action represents one tool call. `config.tool` identifies which tool to call, and `payload` carries the arguments — both must be precise.
+
+**Order matters.** List actions in dependency order — if action B depends on the result of action A, action A comes first. The execution step processes them sequentially.
+
+**One action per tool call.** Don't batch multiple operations into a single action. If provisioning requires creating an org, then creating a billing customer, those are two separate actions.
+
+**Only propose tools from your available list.** You've been given a set of write tools you can propose actions for. If a required operation isn't in that list, note it as a caveat — don't invent actions for tools that don't exist.
+
+**Payloads must be complete.** Include every required field the tool expects. Don't leave placeholders or TODOs in payloads. For values that don't exist yet because they come from a prior action, use a template reference (see below). If you can't determine a value at all, flag it in caveats and omit the action.
+
+### Action Dependencies (Template References)
+
+When an action needs a value produced by a prior action — like an org ID that doesn't exist until the org is created — use a Handlebars template reference in the payload value.
+
+**Syntax:** `{{ actions.N.result.path }}` where `N` is the zero-based action index and `path` navigates the result object.
+
+At execution time, the system resolves these references using the actual results from completed actions. The human reviewer sees the template expression and understands the data flow — they're approving the intent ("use the org ID from step 1"), not the literal runtime value.
+
+**Rules:**
+
+- Only reference actions that come _before_ the current action (lower index)
+- Use dot-path navigation to reach nested values: `{{ actions.0.result.org.id }}`
+- Static values and template references can coexist in the same payload
+- Every other payload field should still use concrete values you already know
+
+**Example:**
+
+```json
+{
+  "type": "mcp_call",
+  "config": { "tool": "create_billing_customer" },
+  "description": "Create ChargeBee billing customer for Acme Corp using new org ID",
+  "payload": "{\"orgId\":\"{{ actions.0.result.id }}\",\"orgName\":\"Acme Corp\",\"contactEmail\":\"jane@acme.com\"}"
+}
+```
+
+Here `orgId` will be resolved at runtime from the result of action 0 (e.g., `create_org`). The reviewer sees that billing depends on the org creation step. Note the payload is JSON-stringified — template references work inside the string and are resolved before parsing.
+
+## Example
+
+Say you've been asked to provision an Orderful org for a new customer. You've queried Salesforce, searched for existing orgs, and gathered the relevant data. Your plan output might look like:
+
+```json
+{
+  "evidence": {
+    "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\":[]}}",
+    "impactSummary": "Creates Orderful org 'Acme Corp' with ISA ID 'ACME001', creates billing customer in ChargeBee, and sends welcome email to jane@acme.com.",
+    "caveats": ["ARR not found in Salesforce — billing customer will be created without revenue data. Manual update may be needed."]
+  },
+  "actions": [
+    {
+      "type": "mcp_call",
+      "config": { "tool": "create_org" },
+      "description": "Create Orderful org 'Acme Corp' with ISA ID 'ACME001'",
+      "payload": "{\"name\":\"Acme Corp\",\"isaId\":\"ACME001\",\"contactEmail\":\"jane@acme.com\"}"
+    },
+    {
+      "type": "mcp_call",
+      "config": { "tool": "create_billing_customer" },
+      "description": "Create ChargeBee billing customer for Acme Corp using new org ID",
+      "payload": "{\"orgId\":\"{{ actions.0.result.id }}\",\"orgName\":\"Acme Corp\",\"contactEmail\":\"jane@acme.com\"}"
+    },
+    {
+      "type": "mcp_call",
+      "config": { "tool": "invite_user" },
+      "description": "Send welcome email to jane@acme.com for Acme Corp org",
+      "payload": "{\"email\":\"jane@acme.com\",\"orgId\":\"{{ actions.0.result.id }}\"}"
+    }
+  ]
+}
+```
+
+## What Not To Do
+
+These are hard rules. Violating any of them will cause the plan to be rejected or produce incorrect results.
+
+- **Don't call write tools directly.** Your job is to propose, not execute. Every write operation must be described as an action in your plan output. If you call a write tool yourself, the approval flow is bypassed and there is no audit trail.
+- **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 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

@@ -0,0 +1,83 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "PlanOutput",
+  "description": "Structured plan output produced by an LLM agent for human review and approval",
+  "type": "object",
+  "required": ["evidence", "actions"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Short human-readable name for the plan"
+    },
+    "category": {
+      "type": "string",
+      "description": "Grouping category for the plan (e.g. org-provisioning)"
+    },
+    "evidence": {
+      "type": "object",
+      "description": "Research findings and rationale supporting the plan",
+      "required": ["reasoning", "sourceSummary", "impactSummary"],
+      "properties": {
+        "reasoning": {
+          "type": "string",
+          "description": "Analysis of what needs to happen and why"
+        },
+        "sourceSummary": {
+          "type": "string",
+          "description": "Concise summary of research findings with entity names and IDs"
+        },
+        "sourceRaw": {
+          "type": "string",
+          "description": "JSON-stringified raw source data from research"
+        },
+        "impactSummary": {
+          "type": "string",
+          "description": "What changes if the plan is approved"
+        },
+        "caveats": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Risks or caveats to flag for review"
+        }
+      },
+      "additionalProperties": false
+    },
+    "actions": {
+      "type": "array",
+      "description": "Ordered list of MCP tool calls to execute",
+      "items": {
+        "type": "object",
+        "required": ["type", "config", "description", "payload"],
+        "properties": {
+          "type": {
+            "type": "string",
+            "const": "mcp_call",
+            "description": "Action category — v0 only supports mcp_call"
+          },
+          "config": {
+            "type": "object",
+            "description": "Configuration specifying which MCP tool to invoke",
+            "required": ["tool"],
+            "properties": {
+              "tool": {
+                "type": "string",
+                "description": "Tool name as it appears in the available tools"
+              }
+            },
+            "additionalProperties": false
+          },
+          "description": {
+            "type": "string",
+            "description": "Human-readable description of what this action does"
+          },
+          "payload": {
+            "type": "string",
+            "description": "JSON-stringified arguments to pass to the MCP tool"
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/package.json

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

package/src/bin/droid.ts

@@ -106,9 +106,10 @@ program
 
 program
   .command('pack')
-  .description('Create audience-filtered zip packs for distribution')
+  .description('Create zip packs for distribution')
   .argument('[audience]', 'Target audience (e.g., engineering, customer-support)')
   .option('-l, --list', 'List available audiences and tool counts')
+  .option('-t, --tool <name>', 'Pack a single tool by name')
   .option('-o, --output <dir>', 'Output directory (default: cwd)')
   .action(packCommand);
 

package/src/commands/pack.ts

@@ -1,6 +1,6 @@
 import chalk from 'chalk';
 import { ToolAudience } from '../lib/types';
-import { getAudienceInfo, buildPack } from '../lib/pack';
+import { getAudienceInfo, buildPack, buildToolPack } from '../lib/pack';
 
 function isValidAudience(value: string): value is ToolAudience {
   return Object.values(ToolAudience).includes(value as ToolAudience);
@@ -8,7 +8,7 @@ function isValidAudience(value: string): value is ToolAudience {
 
 export async function packCommand(
   audience: string | undefined,
-  options: { list?: boolean; output?: string },
+  options: { list?: boolean; output?: string; tool?: string },
 ): Promise<void> {
   // --list mode: show audiences and tool counts
   if (options.list) {
@@ -29,10 +29,40 @@ export async function packCommand(
     return;
   }
 
+  // --tool mode: pack a single tool
+  if (options.tool) {
+    const outputDir = options.output || process.cwd();
+
+    console.log(
+      chalk.bold(`\nPacking tool ${chalk.cyan(options.tool)}...`),
+    );
+
+    const result = await buildToolPack({ toolName: options.tool, outputDir });
+
+    if (!result.success) {
+      console.error(chalk.red(`\n${result.message}`));
+      process.exit(1);
+    }
+
+    console.log(chalk.green(`\n${result.message}`));
+    console.log(chalk.gray(`  Output: ${result.outputPath}`));
+
+    if (result.warnings && result.warnings.length > 0) {
+      console.log(chalk.yellow('\nWarnings:'));
+      for (const warning of result.warnings) {
+        console.log(chalk.yellow(`  - ${warning}`));
+      }
+    }
+
+    console.log('');
+    return;
+  }
+
   // Require audience argument
   if (!audience) {
     console.error(chalk.red('\nError: audience argument required'));
     console.log(chalk.gray('Usage: droid pack <audience>'));
+    console.log(chalk.gray('       droid pack --tool <name>'));
     console.log(chalk.gray('       droid pack --list'));
     process.exit(1);
   }

package/src/lib/pack.test.ts

@@ -1,6 +1,9 @@
 import { describe, it, expect } from 'bun:test';
+import { existsSync, unlinkSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
 import { ToolAudience } from './types';
-import { getToolsForAudience, getAudienceInfo } from './pack';
+import { getToolsForAudience, getAudienceInfo, buildToolPack } from './pack';
 
 // Uses real bundled tools for integration-style tests
 
@@ -83,3 +86,25 @@ describe('getAudienceInfo', () => {
     expect(engineering!.toolNames).toContain('brain');
   });
 });
+
+describe('buildToolPack', () => {
+  it('should create a zip for a single tool', async () => {
+    const outputDir = tmpdir();
+    const result = await buildToolPack({ toolName: 'brain', outputDir });
+
+    expect(result.success).toBe(true);
+    expect(result.toolCount).toBe(1);
+    expect(result.outputPath).toContain('droid-brain.zip');
+    expect(existsSync(result.outputPath!)).toBe(true);
+
+    // Cleanup
+    unlinkSync(result.outputPath!);
+  });
+
+  it('should return error for unknown tool', async () => {
+    const result = await buildToolPack({ toolName: 'nonexistent', outputDir: tmpdir() });
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain('not found');
+  });
+});

package/src/lib/pack.ts

@@ -15,6 +15,11 @@ export interface PackOptions {
   outputDir: string;
 }
 
+export interface ToolPackOptions {
+  toolName: string;
+  outputDir: string;
+}
+
 export interface PackResult {
   success: boolean;
   message: string;
@@ -100,7 +105,7 @@ function collectToolArtifacts(
     // references/
     const refsDir = join(skillDir, 'references');
     if (existsSync(refsDir)) {
-      const refFiles = readdirSync(refsDir).filter((f) => f.endsWith('.md'));
+      const refFiles = readdirSync(refsDir).filter((f) => !f.startsWith('.'));
       for (const file of refFiles) {
         artifacts.push({
           sourcePath: join(refsDir, file),
@@ -170,9 +175,9 @@ function generateClaudeMd(tools: ToolManifest[]): string {
 /**
  * Generate README.md with install instructions
  */
-function generateReadme(audience: ToolAudience, tools: ToolManifest[]): string {
+function generateReadme(label: string, tools: ToolManifest[]): string {
   const lines = [
-    `# Droid Pack: ${audience}`,
+    `# Droid Pack: ${label}`,
     '',
     'This pack contains AI skills, commands, and agents for Claude Desktop.',
     '',
@@ -227,6 +232,64 @@ function checkDependencies(tools: ToolManifest[]): string[] {
   return warnings;
 }
 
+/**
+ * Build a zip pack for a single tool
+ */
+export async function buildToolPack(options: ToolPackOptions): Promise<PackResult> {
+  const { toolName, outputDir } = options;
+
+  const allTools = getBundledTools();
+  const tool = allTools.find((t) => t.name === toolName);
+
+  if (!tool) {
+    return {
+      success: false,
+      message: `Tool '${toolName}' not found`,
+    };
+  }
+
+  const tools = [tool];
+  const warnings = checkDependencies(tools);
+
+  const filename = `droid-${toolName}.zip`;
+  const outputPath = join(outputDir, filename);
+
+  return new Promise((resolve) => {
+    const output = createWriteStream(outputPath);
+    const archive = archiver('zip', { zlib: { level: 9 } });
+
+    output.on('close', () => {
+      resolve({
+        success: true,
+        message: `Pack created: ${filename}`,
+        outputPath,
+        toolCount: 1,
+        warnings: warnings.length > 0 ? warnings : undefined,
+      });
+    });
+
+    archive.on('error', (err: Error) => {
+      resolve({
+        success: false,
+        message: `Failed to create pack: ${err.message}`,
+      });
+    });
+
+    archive.pipe(output);
+
+    const artifacts = collectToolArtifacts(tool);
+    for (const artifact of artifacts) {
+      const content = readFileSync(artifact.sourcePath, 'utf-8');
+      archive.append(content, { name: artifact.zipPath });
+    }
+
+    archive.append(generateClaudeMd(tools), { name: 'CLAUDE.md' });
+    archive.append(generateReadme(toolName, tools), { name: 'README.md' });
+
+    archive.finalize();
+  });
+}
+
 /**
  * Build a zip pack for the given audience
  */

package/src/tools/propose-plan/.claude-plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "droid-propose-plan",
+  "version": "0.1.0",
+  "description": "Produce structured plans with evidence and actions for human approval in Orderful Agents. Use when an agent must propose write operations that require human-in-the-loop review before execution.",
+  "author": {
+    "name": "Orderful",
+    "url": "https://github.com/orderful"
+  },
+  "repository": "https://github.com/orderful/droid",
+  "license": "MIT",
+  "keywords": [
+    "droid",
+    "ai",
+    "propose-plan"
+  ],
+  "skills": [
+    "./skills/propose-plan/SKILL.md"
+  ]
+}

package/src/tools/propose-plan/TOOL.yaml

@@ -0,0 +1,17 @@
+name: propose-plan
+description: "Produce structured plans with evidence and actions for human approval in Orderful Agents. Use when an agent must propose write operations that require human-in-the-loop review before execution."
+version: 0.1.0
+status: beta
+audience:
+  - all
+
+includes:
+  skills:
+    - name: propose-plan
+      required: true
+  commands: []
+  agents: []
+
+dependencies: []
+
+config_schema: {}

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

@@ -0,0 +1,172 @@
+---
+name: propose-plan
+description: "Produce a structured plan with evidence and actions for human approval. Use when an agent must propose write operations, research current state before making changes, or produce actions that require human-in-the-loop review before execution."
+globs: []
+alwaysApply: false
+allowed-tools: []
+---
+
+# Propose Plan
+
+Structure your findings into a plan for human approval. Use this skill when you've researched the current state, understand what needs to happen, and are ready to propose the specific actions to take.
+
+This skill teaches you how to package what you've learned into structured evidence and discrete actions that a reviewer can approve, modify, or reject before anything is executed.
+
+Never call write tools directly. Each proposed write is described as an **action** in your plan output. Approved actions are executed separately after human review.
+
+## Plan Structure
+
+A plan has two parts:
+
+1. **Evidence** — your analysis of the gathered context: what it shows, why changes are needed, and what will happen if the plan is approved
+2. **Actions** — an ordered list of discrete operations to execute, each mapped to a specific tool call
+
+The human reviewer sees your evidence first (the reasoning and impact), then reviews each action. Clear evidence builds trust; vague evidence gets rejected.
+
+## Output Format
+
+Produce a single JSON object matching the schema in `references/output-schema.json`. The shape:
+
+```json
+{
+  "name": "string — short human-readable plan name (optional)",
+  "category": "string — grouping category, e.g. org-provisioning (optional)",
+  "evidence": {
+    "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)",
+    "impactSummary": "string — what will change if this plan is approved",
+    "caveats": ["string — anything uncertain, auto-generated, or requiring follow-up"]
+  },
+  "actions": [
+    {
+      "type": "mcp_call",
+      "config": {
+        "tool": "string — the tool name exactly as you see it in your available tools"
+      },
+      "description": "string — human-readable description of what this action does",
+      "payload": "string — JSON-stringified arguments to pass to the tool"
+    }
+  ]
+}
+```
+
+### 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.                    |
+| `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.    |
+| `caveats`       | Optional. Flag anything uncertain, auto-generated, or needing manual follow-up.                         | Prevents surprises. Reviewers appreciate honesty about gaps. |
+
+### Action Fields
+
+| Field         | Purpose                                                                                                                                          |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `type`        | Action category. Use `mcp_call` for MCP tool invocations.                                                                                   |
+| `config`      | Identifies which tool to call. For `mcp_call`: `{ "tool": "create_org" }`. Use the tool name exactly as it appears in your available tools. |
+| `description` | Human-readable summary. The reviewer sees this before expanding the payload. Write it for someone who won't read the raw payload.                |
+| `payload`     | JSON-stringified arguments passed to the tool. Stringify the object — `JSON.stringify({...})` — don't nest it raw.                                |
+
+## Building Evidence From What You Know
+
+By the time you're writing a plan, you've already done the research — queried tools, read documents, collected the data you need. Your job now is to analyse what you found and structure it into a plan.
+
+If read tools are still available, use them to **verify and fill gaps** — check for conflicts, confirm preconditions, resolve ambiguities. But the research phase is behind you. Focus on structuring what you know into clear evidence and precise actions.
+
+When writing evidence:
+
+1. **Cite the gathered data** — reference specific entities, IDs, and values. A reviewer can't verify "the account exists" but they can verify "Salesforce account SF-001234 (Acme Corp) has no OrgID".
+2. **Flag conflicts** — if the gathered data reveals duplicates, collisions, or unexpected state, surface that prominently.
+3. **Note gaps** — if data is missing or ambiguous, say so in caveats rather than guessing. A plan with honest gaps is more useful than one with invented data.
+
+## Writing Actions
+
+Each action represents one tool call. `config.tool` identifies which tool to call, and `payload` carries the arguments — both must be precise.
+
+**Order matters.** List actions in dependency order — if action B depends on the result of action A, action A comes first. The execution step processes them sequentially.
+
+**One action per tool call.** Don't batch multiple operations into a single action. If provisioning requires creating an org, then creating a billing customer, those are two separate actions.
+
+**Only propose tools from your available list.** You've been given a set of write tools you can propose actions for. If a required operation isn't in that list, note it as a caveat — don't invent actions for tools that don't exist.
+
+**Payloads must be complete.** Include every required field the tool expects. Don't leave placeholders or TODOs in payloads. For values that don't exist yet because they come from a prior action, use a template reference (see below). If you can't determine a value at all, flag it in caveats and omit the action.
+
+### Action Dependencies (Template References)
+
+When an action needs a value produced by a prior action — like an org ID that doesn't exist until the org is created — use a Handlebars template reference in the payload value.
+
+**Syntax:** `{{ actions.N.result.path }}` where `N` is the zero-based action index and `path` navigates the result object.
+
+At execution time, the system resolves these references using the actual results from completed actions. The human reviewer sees the template expression and understands the data flow — they're approving the intent ("use the org ID from step 1"), not the literal runtime value.
+
+**Rules:**
+
+- Only reference actions that come _before_ the current action (lower index)
+- Use dot-path navigation to reach nested values: `{{ actions.0.result.org.id }}`
+- Static values and template references can coexist in the same payload
+- Every other payload field should still use concrete values you already know
+
+**Example:**
+
+```json
+{
+  "type": "mcp_call",
+  "config": { "tool": "create_billing_customer" },
+  "description": "Create ChargeBee billing customer for Acme Corp using new org ID",
+  "payload": "{\"orgId\":\"{{ actions.0.result.id }}\",\"orgName\":\"Acme Corp\",\"contactEmail\":\"jane@acme.com\"}"
+}
+```
+
+Here `orgId` will be resolved at runtime from the result of action 0 (e.g., `create_org`). The reviewer sees that billing depends on the org creation step. Note the payload is JSON-stringified — template references work inside the string and are resolved before parsing.
+
+## Example
+
+Say you've been asked to provision an Orderful org for a new customer. You've queried Salesforce, searched for existing orgs, and gathered the relevant data. Your plan output might look like:
+
+```json
+{
+  "evidence": {
+    "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\":[]}}",
+    "impactSummary": "Creates Orderful org 'Acme Corp' with ISA ID 'ACME001', creates billing customer in ChargeBee, and sends welcome email to jane@acme.com.",
+    "caveats": ["ARR not found in Salesforce — billing customer will be created without revenue data. Manual update may be needed."]
+  },
+  "actions": [
+    {
+      "type": "mcp_call",
+      "config": { "tool": "create_org" },
+      "description": "Create Orderful org 'Acme Corp' with ISA ID 'ACME001'",
+      "payload": "{\"name\":\"Acme Corp\",\"isaId\":\"ACME001\",\"contactEmail\":\"jane@acme.com\"}"
+    },
+    {
+      "type": "mcp_call",
+      "config": { "tool": "create_billing_customer" },
+      "description": "Create ChargeBee billing customer for Acme Corp using new org ID",
+      "payload": "{\"orgId\":\"{{ actions.0.result.id }}\",\"orgName\":\"Acme Corp\",\"contactEmail\":\"jane@acme.com\"}"
+    },
+    {
+      "type": "mcp_call",
+      "config": { "tool": "invite_user" },
+      "description": "Send welcome email to jane@acme.com for Acme Corp org",
+      "payload": "{\"email\":\"jane@acme.com\",\"orgId\":\"{{ actions.0.result.id }}\"}"
+    }
+  ]
+}
+```
+
+## What Not To Do
+
+These are hard rules. Violating any of them will cause the plan to be rejected or produce incorrect results.
+
+- **Don't call write tools directly.** Your job is to propose, not execute. Every write operation must be described as an action in your plan output. If you call a write tool yourself, the approval flow is bypassed and there is no audit trail.
+- **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 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/src/tools/propose-plan/skills/propose-plan/references/output-schema.json

@@ -0,0 +1,83 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "PlanOutput",
+  "description": "Structured plan output produced by an LLM agent for human review and approval",
+  "type": "object",
+  "required": ["evidence", "actions"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Short human-readable name for the plan"
+    },
+    "category": {
+      "type": "string",
+      "description": "Grouping category for the plan (e.g. org-provisioning)"
+    },
+    "evidence": {
+      "type": "object",
+      "description": "Research findings and rationale supporting the plan",
+      "required": ["reasoning", "sourceSummary", "impactSummary"],
+      "properties": {
+        "reasoning": {
+          "type": "string",
+          "description": "Analysis of what needs to happen and why"
+        },
+        "sourceSummary": {
+          "type": "string",
+          "description": "Concise summary of research findings with entity names and IDs"
+        },
+        "sourceRaw": {
+          "type": "string",
+          "description": "JSON-stringified raw source data from research"
+        },
+        "impactSummary": {
+          "type": "string",
+          "description": "What changes if the plan is approved"
+        },
+        "caveats": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Risks or caveats to flag for review"
+        }
+      },
+      "additionalProperties": false
+    },
+    "actions": {
+      "type": "array",
+      "description": "Ordered list of MCP tool calls to execute",
+      "items": {
+        "type": "object",
+        "required": ["type", "config", "description", "payload"],
+        "properties": {
+          "type": {
+            "type": "string",
+            "const": "mcp_call",
+            "description": "Action category — v0 only supports mcp_call"
+          },
+          "config": {
+            "type": "object",
+            "description": "Configuration specifying which MCP tool to invoke",
+            "required": ["tool"],
+            "properties": {
+              "tool": {
+                "type": "string",
+                "description": "Tool name as it appears in the available tools"
+              }
+            },
+            "additionalProperties": false
+          },
+          "description": {
+            "type": "string",
+            "description": "Human-readable description of what this action does"
+          },
+          "payload": {
+            "type": "string",
+            "description": "JSON-stringified arguments to pass to the MCP tool"
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}