@orderful/droid 0.48.0 → 0.51.0

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/release/TOOL.yaml

@@ -2,6 +2,8 @@ name: release
 description: "Release ceremony automation — create release PRs, check status, notify Slack."
 version: 0.2.2
 status: alpha
+audience:
+  - engineering
 
 includes:
   skills:

package/dist/tools/share/TOOL.yaml

@@ -2,6 +2,8 @@ name: share
 description: "Share content to external platforms. Publish docs to Confluence or post summaries to Slack."
 version: 0.1.1
 status: beta
+audience:
+  - all
 
 includes:
   skills:

package/dist/tools/status-update/TOOL.yaml

@@ -2,6 +2,10 @@ name: status-update
 description: "Generate and post project status updates. Aggregates context from codex projects, Jira epics, and manual input. Posts to Slack or prints to terminal."
 version: 0.2.2
 status: beta
+audience:
+  - engineering
+  - product
+  - design
 
 includes:
   skills:

package/dist/tools/tech-design/TOOL.yaml

@@ -2,6 +2,8 @@ name: tech-design
 description: "Technical design authoring tool for engineers. Create structured tech design docs with /tech-design start, iterate in brain, publish to codex. Three-document approach: research doc (codebase discoveries) + thought doc (design workspace) + roll-up (clean summary for review)."
 version: 0.3.1
 status: beta
+audience:
+  - engineering
 
 includes:
   skills:

package/dist/tools/wrapup/TOOL.yaml

@@ -2,6 +2,8 @@ name: wrapup
 description: "Session wrap-up that captures decisions, learnings, and open items to persistent docs."
 version: 0.1.5
 status: alpha
+audience:
+  - all
 
 includes:
   skills:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orderful/droid",
-  "version": "0.48.0",
+  "version": "0.51.0",
   "description": "AI workflow toolkit for sharing skills, commands, and agents across the team",
   "type": "module",
   "bin": {
@@ -46,6 +46,7 @@
   },
   "dependencies": {
     "@slack/web-api": "^7.13.0",
+    "archiver": "^7.0.1",
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
     "ink": "^6.5.1",
@@ -60,6 +61,7 @@
     "@changesets/changelog-github": "^0.5.2",
     "@changesets/cli": "^2.29.8",
     "@playwright/test": "^1.57.0",
+    "@types/archiver": "^7.0.0",
     "@types/bun": "latest",
     "@types/ink-text-input": "^2.0.5",
     "@types/inquirer": "^9.0.7",

package/scripts/build.ts

@@ -65,9 +65,10 @@ async function main() {
     packages: 'external',
   });
 
-  // Copy tools directory
+  // Copy tools directory (exclude test files — they don't belong in installed skills)
   console.log('Copying tools...');
-  cpSync('src/tools', 'dist/tools', { recursive: true });
+  const skipTestFiles = (src: string) => !/\.test\.ts$/.test(src);
+  cpSync('src/tools', 'dist/tools', { recursive: true, filter: skipTestFiles });
 
   // Copy integrations directory (references, etc.)
   console.log('Copying integrations...');

package/src/bin/droid.ts

@@ -10,6 +10,7 @@ import { uninstallCommand } from '../commands/uninstall';
 import { updateCommand } from '../commands/update';
 import { tuiCommand } from '../commands/tui';
 import { execCommand } from '../commands/exec';
+import { packCommand } from '../commands/pack';
 import {
   reposListCommand,
   reposAddCommand,
@@ -103,6 +104,14 @@ program
   .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('exec <tool> <script>')
   .description('Execute a tool script')

package/src/commands/pack.ts

@@ -0,0 +1,77 @@
+import chalk from 'chalk';
+import { ToolAudience } from '../lib/types';
+import { getAudienceInfo, buildPack } from '../lib/pack';
+
+function isValidAudience(value: string): value is ToolAudience {
+  return Object.values(ToolAudience).includes(value as ToolAudience);
+}
+
+export async function packCommand(
+  audience: string | undefined,
+  options: { list?: boolean; output?: string },
+): Promise<void> {
+  // --list mode: show audiences and tool counts
+  if (options.list) {
+    const infos = getAudienceInfo();
+
+    if (infos.length === 0) {
+      console.log(chalk.yellow('No tools with audience metadata found.'));
+      return;
+    }
+
+    console.log(chalk.bold('\nAvailable audiences:\n'));
+    for (const info of infos) {
+      console.log(
+        `  ${chalk.cyan(info.audience.padEnd(24))} ${chalk.gray(`${info.toolCount} tools`)}  ${chalk.gray(info.toolNames.join(', '))}`,
+      );
+    }
+    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 --list'));
+    process.exit(1);
+  }
+
+  // Validate audience
+  if (!isValidAudience(audience)) {
+    console.error(chalk.red(`\nError: unknown audience '${audience}'`));
+    console.log(chalk.gray('\nValid audiences:'));
+    for (const a of Object.values(ToolAudience)) {
+      if (a !== ToolAudience.All) {
+        console.log(chalk.gray(`  - ${a}`));
+      }
+    }
+    process.exit(1);
+  }
+
+  const outputDir = options.output || process.cwd();
+
+  console.log(
+    chalk.bold(`\nPacking tools for ${chalk.cyan(audience)}...`),
+  );
+
+  const result = await buildPack({ audience, 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(`  ${result.toolCount} tools included`));
+  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('');
+}

package/src/lib/pack.test.ts

@@ -0,0 +1,85 @@
+import { describe, it, expect } from 'bun:test';
+import { ToolAudience } from './types';
+import { getToolsForAudience, getAudienceInfo } from './pack';
+
+// Uses real bundled tools for integration-style tests
+
+describe('getToolsForAudience', () => {
+  it('should include "all" audience tools in any audience pack', () => {
+    const tools = getToolsForAudience(ToolAudience.Engineering);
+    const toolNames = tools.map((t) => t.name);
+    // brain is audience: [all]
+    expect(toolNames).toContain('brain');
+    // comments is audience: [all]
+    expect(toolNames).toContain('comments');
+  });
+
+  it('should include audience-specific tools', () => {
+    const tools = getToolsForAudience(ToolAudience.Engineering);
+    const toolNames = tools.map((t) => t.name);
+    // code-review is audience: [engineering]
+    expect(toolNames).toContain('code-review');
+    // release is audience: [engineering]
+    expect(toolNames).toContain('release');
+  });
+
+  it('should include tools with prerequisites (codex)', () => {
+    const tools = getToolsForAudience(ToolAudience.Engineering);
+    const toolNames = tools.map((t) => t.name);
+    expect(toolNames).toContain('codex');
+  });
+
+  it('should not include tools from other audiences', () => {
+    // edi-schema is engineering-only
+    const tools = getToolsForAudience(ToolAudience.Product);
+    const toolNames = tools.map((t) => t.name);
+    expect(toolNames).not.toContain('edi-schema');
+  });
+
+  it('should return tools for audiences with only "all" tools', () => {
+    const tools = getToolsForAudience(ToolAudience.CustomerSupport);
+    // customer-support has no specific tools but gets all 'all' audience tools
+    expect(tools.length).toBeGreaterThan(0);
+    // Every tool should have audience 'all'
+    for (const tool of tools) {
+      expect(tool.audience).toContain(ToolAudience.All);
+    }
+  });
+
+  it('should skip tools without audience metadata', () => {
+    const tools = getToolsForAudience(ToolAudience.Engineering);
+    for (const tool of tools) {
+      expect(tool.audience).toBeDefined();
+      expect(tool.audience!.length).toBeGreaterThan(0);
+    }
+  });
+});
+
+describe('getAudienceInfo', () => {
+  it('should return info for audiences that have tools', () => {
+    const infos = getAudienceInfo();
+    expect(infos.length).toBeGreaterThan(0);
+
+    // Engineering should be present (has edi-schema, code-review, etc.)
+    const engineering = infos.find(
+      (i) => i.audience === ToolAudience.Engineering,
+    );
+    expect(engineering).toBeDefined();
+    expect(engineering!.toolCount).toBeGreaterThan(0);
+  });
+
+  it('should not include the "all" audience itself', () => {
+    const infos = getAudienceInfo();
+    const all = infos.find((i) => i.audience === ToolAudience.All);
+    expect(all).toBeUndefined();
+  });
+
+  it('should count "all" audience tools in each audience', () => {
+    const infos = getAudienceInfo();
+    const engineering = infos.find(
+      (i) => i.audience === ToolAudience.Engineering,
+    );
+    // Engineering should include 'all' tools like brain, comments
+    expect(engineering!.toolNames).toContain('brain');
+  });
+});

package/src/lib/pack.ts

@@ -0,0 +1,293 @@
+import { existsSync, readdirSync, readFileSync, createWriteStream } from 'fs';
+import { join } from 'path';
+import archiver from 'archiver';
+import { getBundledTools, getBundledToolsDir } from './tools';
+import { ToolAudience, type ToolManifest } from './types';
+
+export interface AudienceInfo {
+  audience: ToolAudience;
+  toolCount: number;
+  toolNames: string[];
+}
+
+export interface PackOptions {
+  audience: ToolAudience;
+  outputDir: string;
+}
+
+export interface PackResult {
+  success: boolean;
+  message: string;
+  outputPath?: string;
+  toolCount?: number;
+  warnings?: string[];
+}
+
+/**
+ * Get tools filtered by audience
+ * Tools with audience 'all' are always included
+ */
+export function getToolsForAudience(
+  audience: ToolAudience,
+): ToolManifest[] {
+  const allTools = getBundledTools();
+
+  return allTools.filter((tool) => {
+    // Skip tools without audience metadata
+    if (!tool.audience || tool.audience.length === 0) {
+      return false;
+    }
+
+    // Must match the requested audience OR be audience 'all'
+    return (
+      tool.audience.includes(audience) ||
+      tool.audience.includes(ToolAudience.All)
+    );
+  });
+}
+
+/**
+ * Get audience info for all audiences that have tools
+ */
+export function getAudienceInfo(): AudienceInfo[] {
+  const allTools = getBundledTools();
+  const audiences = Object.values(ToolAudience).filter(
+    (a) => a !== ToolAudience.All,
+  );
+
+  return audiences
+    .map((audience) => {
+      const tools = allTools.filter(
+        (tool) =>
+          tool.audience &&
+          (tool.audience.includes(audience) ||
+            tool.audience.includes(ToolAudience.All)),
+      );
+
+      return {
+        audience,
+        toolCount: tools.length,
+        toolNames: tools.map((t) => t.name),
+      };
+    })
+    .filter((info) => info.toolCount > 0);
+}
+
+/**
+ * Collect all artifact paths for a tool (skills, commands, agents)
+ * Returns paths relative to the zip root (installed format)
+ */
+function collectToolArtifacts(
+  tool: ToolManifest,
+): Array<{ sourcePath: string; zipPath: string }> {
+  const artifacts: Array<{ sourcePath: string; zipPath: string }> = [];
+  const toolDir = join(getBundledToolsDir(), tool.name);
+
+  // Skills
+  for (const skill of tool.includes.skills) {
+    const skillDir = join(toolDir, 'skills', skill.name);
+    if (!existsSync(skillDir)) continue;
+
+    // SKILL.md
+    const skillMd = join(skillDir, 'SKILL.md');
+    if (existsSync(skillMd)) {
+      artifacts.push({
+        sourcePath: skillMd,
+        zipPath: `skills/${skill.name}/SKILL.md`,
+      });
+    }
+
+    // references/
+    const refsDir = join(skillDir, 'references');
+    if (existsSync(refsDir)) {
+      const refFiles = readdirSync(refsDir).filter((f) => f.endsWith('.md'));
+      for (const file of refFiles) {
+        artifacts.push({
+          sourcePath: join(refsDir, file),
+          zipPath: `skills/${skill.name}/references/${file}`,
+        });
+      }
+    }
+  }
+
+  // Commands
+  const commandsDir = join(toolDir, 'commands');
+  if (existsSync(commandsDir)) {
+    const commandFiles = readdirSync(commandsDir).filter(
+      (f) => f.endsWith('.md') && f.toLowerCase() !== 'readme.md',
+    );
+    for (const file of commandFiles) {
+      artifacts.push({
+        sourcePath: join(commandsDir, file),
+        zipPath: `commands/${file}`,
+      });
+    }
+  }
+
+  // Agents
+  const agentsDir = join(toolDir, 'agents');
+  if (existsSync(agentsDir)) {
+    const agentFiles = readdirSync(agentsDir).filter(
+      (f) => f.endsWith('.md') && f.toLowerCase() !== 'readme.md',
+    );
+    for (const file of agentFiles) {
+      artifacts.push({
+        sourcePath: join(agentsDir, file),
+        zipPath: `agents/${file}`,
+      });
+    }
+  }
+
+  return artifacts;
+}
+
+/**
+ * Generate CLAUDE.md content with skill registration links
+ */
+function generateClaudeMd(tools: ToolManifest[]): string {
+  const skillNames: string[] = [];
+  for (const tool of tools) {
+    for (const skill of tool.includes.skills) {
+      skillNames.push(skill.name);
+    }
+  }
+
+  const lines = [
+    '# Droid Skills',
+    '',
+    'Skills installed from a Droid pack. Each skill teaches your AI new capabilities.',
+    '',
+  ];
+
+  for (const name of skillNames) {
+    lines.push(`- [${name}](skills/${name}/SKILL.md)`);
+  }
+
+  lines.push('');
+  return lines.join('\n');
+}
+
+/**
+ * Generate README.md with install instructions
+ */
+function generateReadme(audience: ToolAudience, tools: ToolManifest[]): string {
+  const lines = [
+    `# Droid Pack: ${audience}`,
+    '',
+    'This pack contains AI skills, commands, and agents for Claude Desktop.',
+    '',
+    '## Installation',
+    '',
+    '1. Unzip this archive',
+    '2. Copy the contents into your `~/.claude/` directory:',
+    '',
+    '```bash',
+    '# From the directory where you unzipped:',
+    'cp -r skills/ ~/.claude/skills/',
+    'cp -r commands/ ~/.claude/commands/',
+    'cp -r agents/ ~/.claude/agents/',
+    '```',
+    '',
+    '3. Append the contents of `CLAUDE.md` to your `~/.claude/CLAUDE.md`:',
+    '',
+    '```bash',
+    'cat CLAUDE.md >> ~/.claude/CLAUDE.md',
+    '```',
+    '',
+    '## Included Tools',
+    '',
+  ];
+
+  for (const tool of tools) {
+    lines.push(`- **${tool.name}** (v${tool.version}) — ${tool.description}`);
+  }
+
+  lines.push('');
+  return lines.join('\n');
+}
+
+/**
+ * Check for missing dependencies and return warnings
+ */
+function checkDependencies(tools: ToolManifest[]): string[] {
+  const warnings: string[] = [];
+  const toolNames = new Set(tools.map((t) => t.name));
+
+  for (const tool of tools) {
+    if (!tool.dependencies) continue;
+    for (const dep of tool.dependencies) {
+      if (!toolNames.has(dep)) {
+        warnings.push(
+          `Tool '${tool.name}' depends on '${dep}' which is not included in this pack`,
+        );
+      }
+    }
+  }
+
+  return warnings;
+}
+
+/**
+ * Build a zip pack for the given audience
+ */
+export async function buildPack(options: PackOptions): Promise<PackResult> {
+  const { audience, outputDir } = options;
+
+  // Get filtered tools
+  const tools = getToolsForAudience(audience);
+
+  if (tools.length === 0) {
+    return {
+      success: false,
+      message: `No tools found for audience '${audience}'`,
+    };
+  }
+
+  // Check dependencies
+  const warnings = checkDependencies(tools);
+
+  // Build the zip
+  const filename = `droid-${audience}-pack.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: tools.length,
+        warnings: warnings.length > 0 ? warnings : undefined,
+      });
+    });
+
+    archive.on('error', (err: Error) => {
+      resolve({
+        success: false,
+        message: `Failed to create pack: ${err.message}`,
+      });
+    });
+
+    archive.pipe(output);
+
+    // Add all tool artifacts
+    for (const tool of tools) {
+      const artifacts = collectToolArtifacts(tool);
+      for (const artifact of artifacts) {
+        const content = readFileSync(artifact.sourcePath, 'utf-8');
+        archive.append(content, { name: artifact.zipPath });
+      }
+    }
+
+    // Add generated CLAUDE.md
+    archive.append(generateClaudeMd(tools), { name: 'CLAUDE.md' });
+
+    // Add generated README.md
+    archive.append(generateReadme(audience, tools), { name: 'README.md' });
+
+    archive.finalize();
+  });
+}

package/src/lib/types.ts

@@ -219,12 +219,31 @@ export interface ToolIncludes {
   agents: string[];
 }
 
+export enum ToolAudience {
+  All = 'all',
+  Engineering = 'engineering',
+  Product = 'product',
+  Design = 'design',
+  IntegrationDevelopers = 'integration-developers',
+  CustomerSupport = 'customer-support',
+  NetworkOperations = 'network-operations',
+}
+
+export interface ToolPrerequisite {
+  name: string;
+  description: string;
+  check: string;
+  install_hint: string;
+}
+
 export interface ToolManifest {
   name: string;
   description: string;
   version: string;
   status?: SkillStatus;
+  audience?: ToolAudience[];
   includes: ToolIncludes;
   dependencies?: string[];
+  prerequisites?: ToolPrerequisite[];
   config_schema?: Record<string, ConfigOption>;
 }

package/src/tools/brain/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "droid-brain",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "Your scratchpad (or brain) - a collaborative space for planning and research. Create docs with /brain plan, /brain research, or /brain review. Use @mentions for async discussion. Docs persist across sessions.",
   "author": {
     "name": "Orderful",