@orderful/droid 0.50.0 → 0.52.0

package/dist/tools/project/skills/project/references/pulling.md

@@ -0,0 +1,57 @@
+# Pulling from Codex
+
+**Trigger:** `/project pull [codex:{name}]`
+
+Pull shared organizational context into an existing local project.
+
+## Procedure
+
+1. **Resolve codex project name:**
+   - If `codex:{name}` provided → use it, save to PROJECT.md frontmatter as `codex_project: {name}`
+   - If not provided → read `codex_project` from PROJECT.md frontmatter
+   - If neither → ask user
+
+2. **Identify the local project:**
+   - If in a loaded project session → use that project
+   - If no project loaded → search and load first (same as `/project search`)
+
+3. **Load codex entry:**
+   - Run `droid config --get tools.codex` and get `codex_repo` from the JSON output
+   - Sync: `git -C {codex_repo} pull --rebase --quiet`
+   - Locate `{codex_repo}/projects/{name}/`
+   - If not found → error with suggestions from available codex projects
+
+4. **Read codex documents:**
+   - PRD.md → goals, requirements, status
+   - TECH-DESIGN.md → architecture, patterns, key paths
+   - DECISIONS.md → recent decisions
+   - Any other docs in the codex project folder
+
+5. **Read current PROJECT.md** and identify:
+   - Sections that overlap with codex content
+   - Codex content that's newer or more detailed
+   - Local content that has no codex equivalent (leave untouched)
+
+6. **Propose updates** (never auto-apply):
+   - **Be highly selective** — PROJECT.md has context limits. Only propose content that is critical for the AI to have when working on this project.
+   - Categorise: "New from codex", "Updated in codex", "No change needed"
+   - Preserve local implementation details — codex updates should ADD context, not overwrite working notes
+   - Prefer links to codex over copying large sections
+
+7. **After approval:**
+   - Apply approved changes
+   - Update frontmatter: `codex_project: {name}`
+   - Add `## Codex Sync` entry or update existing one:
+     ```
+     **Last pulled:** {date} from codex:{name}
+     ```
+   - Determine version bump (patch for context updates, minor if goals/scope changed)
+   - Add changelog entry noting codex pull
+
+## Key Principles
+
+- **Selective, not exhaustive** — only pull what's critical for project context. The project file has size limits.
+- **Additive, not destructive** — codex updates enrich the local project, they don't replace local work
+- **User reviews every change** — always propose, never auto-apply
+- **Provenance tracked** — changelog and sync date show where context came from
+- **Links over copies** — for large sections, link to codex rather than duplicating

package/dist/tools/project/skills/project/references/pushing.md

@@ -0,0 +1,79 @@
+# Pushing to Codex
+
+**Trigger:** `/project push [codex:{name}]`
+
+Push team-relevant content from a local project back to the shared codex.
+
+## What Gets Shared
+
+Not everything in a project is codex-worthy. Extract only team-relevant content:
+
+| Share | Don't Share |
+|-------|-------------|
+| Architecture decisions with rationale | Personal work notes |
+| New patterns discovered during implementation | In-progress tasks |
+| Updated technical constraints | Session logs or worklogs |
+| Status changes (shipped, blocked, pivoted) | Brain docs or research drafts |
+| Key file paths or API changes | Local configuration |
+
+## Procedure
+
+1. **Resolve codex project name:**
+   - If `codex:{name}` provided → use it, save to PROJECT.md frontmatter as `codex_project: {name}`
+   - If not provided → read `codex_project` from PROJECT.md frontmatter
+   - If neither → ask user which codex project to update, save to frontmatter
+   - Codex project must already exist. If it doesn't, suggest `/codex new project {name}` first.
+
+2. **Identify the local project:**
+   - If in a loaded project session → use that project
+   - If no project loaded → search and load first
+
+3. **Read PROJECT.md** and companion docs (DECISIONS.md, WORKLOG.md if they exist)
+
+4. **Load codex entry:**
+   - Run `droid config --get tools.codex` and get `codex_repo` from the JSON output
+   - Sync: `git -C {codex_repo} pull --rebase --quiet`
+   - Read existing codex project docs
+
+5. **Extract and categorise shareable content:**
+   - **Decisions:** New entries from DECISIONS.md or inline decisions in PROJECT.md
+   - **Architecture:** Changes to technical approach, new patterns, updated diagrams
+   - **Status:** Phase changes, milestones hit, scope changes
+   - **Constraints:** Newly discovered technical constraints or gotchas
+
+6. **Propose codex updates** (never auto-apply):
+   - For each item, show:
+     - What will be added/changed in codex
+     - Which codex file it targets (DECISIONS.md, TECH-DESIGN.md, PRD.md)
+     - A diff preview
+   - Let user accept, reject, or edit each item
+
+7. **After approval:**
+   - Use codex git scripts for the write operation:
+     ```bash
+     # Start write
+     droid config --get tools.codex | droid exec codex git-start-write --config - \
+       --branch codex/sync-{project-name}
+
+     # Make changes to codex files
+
+     # Normalize frontmatter
+     droid config --get tools.codex | droid exec codex normalize-frontmatter --config -
+
+     # Finish write (commit + PR)
+     droid config --get tools.codex | droid exec codex git-finish-write --config - \
+       --message "sync({project}): {summary}" \
+       --pr-title "sync({project}): Update from local project" \
+       --pr-body "{description of changes}"
+     ```
+   - Update local PROJECT.md sync marker:
+     ```
+     **Last pushed:** {date} to codex:{name}
+     ```
+
+## Key Principles
+
+- **Curated, not automated** — user explicitly reviews what gets shared
+- **PR-based** — codex changes go through PR review, not direct commits
+- **Additive** — adds to codex content, doesn't overwrite others' contributions
+- **Idempotent** — running `/project push` twice proposes only new/changed content

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,190 @@
+---
+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": "object — 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": "object — 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. Raw API responses or data snapshots as a JSON object.                                         | 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`     | Raw arguments passed directly to the tool. No wrapping or nesting — exactly what the tool expects.                                               |
+
+## 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.
+
+## 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,85 @@
+{
+  "$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": "object",
+          "description": "Raw source data from research",
+          "additionalProperties": true
+        },
+        "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": "object",
+            "description": "Arguments to pass to the MCP tool",
+            "additionalProperties": true
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orderful/droid",
-  "version": "0.50.0",
+  "version": "0.52.0",
   "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
  */