@orderful/droid 0.47.0 → 0.50.0

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.1",
+  "version": "0.4.2",
   "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",

package/src/tools/brain/TOOL.yaml

@@ -1,7 +1,9 @@
 name: brain
 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."
-version: 0.4.1
+version: 0.4.2
 status: beta
+audience:
+  - all
 
 includes:
   skills:

package/src/tools/brain/skills/brain/SKILL.md

@@ -121,10 +121,12 @@ Full procedure: `references/workflows.md` § Adding
 
 ## Checking Comments
 
-**Trigger:** `/brain check`
+**Trigger:** `/brain check` or `/brain check --holistic`
 
 Find `> @droid` comments in active doc and address each. Preserve original comment, add response below with `> @{user_mention}`.
 
+With `--holistic`: group related comments into thematic clusters and respond cohesively to each cluster instead of one-by-one. Unrelated comments still get individual responses. See `comments` skill for full holistic mode behaviour.
+
 Full procedure: `references/workflows.md` § Checking
 
 ## Cleaning Up Resolved Threads

package/src/tools/brain/skills/brain/references/workflows.md

@@ -150,9 +150,11 @@ Detailed procedures for each brain operation.
 
 ## Checking
 
-**Trigger:** `/brain check`
+**Trigger:** `/brain check` or `/brain check --holistic`
 
-**Prefer `comments` skill:** If the `comments` skill is installed, use `/comments check` instead - it provides better comment detection, cleanup workflows, and supports the full `@droid`/`@user` convention. The workflow below is a fallback for basic comment handling.
+**Prefer `comments` skill:** If the `comments` skill is installed, use `/comments check` (or `/comments check --holistic`) instead - it provides better comment detection, cleanup workflows, and supports the full `@droid`/`@user` convention. The workflow below is a fallback for basic comment handling.
+
+**Holistic mode (`--holistic`):** Pass the flag through to the comments skill. If using the fallback workflow below, apply the same principle: after step 4 (finding all comments), group related comments into thematic clusters and respond cohesively to each cluster at the last comment in the group. Unrelated comments get individual responses as normal.
 
 **Directionality:** The @mention is the **target**, not the author:
 

package/src/tools/coach/TOOL.yaml

@@ -2,6 +2,10 @@ name: coach
 description: "Learning-mode AI assistance - AI as coach, not crutch. Use /coach plan for co-authored planning, /coach scaffold for structure with hints, /coach review for Socratic questions."
 version: 0.3.0
 status: beta
+audience:
+  - engineering
+  - product
+  - design
 
 includes:
   skills:

package/src/tools/code-review/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "droid-code-review",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "Comprehensive code review using specialized agents. Reviews PRs, staged changes, branches, or specific files with confidence scoring.",
   "author": {
     "name": "Orderful",
@@ -23,6 +23,7 @@
     "./agents/edi-standards-reviewer.md",
     "./agents/error-handling-reviewer.md",
     "./agents/test-coverage-analyzer.md",
-    "./agents/type-reviewer.md"
+    "./agents/type-reviewer.md",
+    "./agents/codex-context-researcher.md"
   ]
 }

package/src/tools/code-review/TOOL.yaml

@@ -1,7 +1,9 @@
 name: code-review
 description: "Comprehensive code review using specialized agents. Reviews PRs, staged changes, branches, or specific files with confidence scoring."
-version: 0.2.4
+version: 0.3.0
 status: alpha
+audience:
+  - engineering
 
 includes:
   skills:
@@ -15,5 +17,6 @@ includes:
     - error-handling-reviewer
     - test-coverage-analyzer
     - type-reviewer
+    - codex-context-researcher
 
 dependencies: []

package/src/tools/code-review/agents/codex-context-researcher.md

@@ -0,0 +1,99 @@
+---
+name: codex-context-researcher
+description: "Search codex for domain knowledge relevant to code changes. Enriches code review findings with organisational context from PRDs, tech designs, and architectural decisions."
+tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+color: cyan
+---
+
+You are a codex research agent that finds organisational domain knowledge relevant to a set of code changes. Your output enriches code review findings — you do NOT review code yourself.
+
+## Inputs
+
+You will receive:
+
+- A list of changed file paths
+- A brief summary of the diff (module names, domain concepts)
+- Optionally, custom instructions from the user
+
+## Procedure
+
+### Step 1: Check Codex Availability
+
+Run: `droid config --get tools.codex`
+
+Parse the output for `codex_repo`. If not set or the command fails, return:
+
+```json
+{
+  "status": "not_configured",
+  "entries_searched": 0,
+  "entries_matched": 0,
+  "domain_context": "",
+  "sources": []
+}
+```
+
+### Step 2: Read Index
+
+Read `{codex_repo}/index.yaml` — this is the codex inventory. It lists every entry by category (projects, patterns, topics, domains, proposals) with names, titles, and aliases.
+
+If the index doesn't exist or is empty, return `status: "not_configured"`.
+
+### Step 3: Extract Search Terms
+
+From the changed file paths, extract terms to match against the index:
+
+- **Module/service names** from paths (e.g., `transactionTemplate` from `src/modules/transactionTemplate/`)
+- **Directory segments** that suggest feature areas (e.g., `billing`, `partnership`, `webhook`)
+
+Do NOT hardcode domain concepts — let the index be the source of truth for what knowledge exists.
+
+### Step 4: Match Against Index
+
+Match extracted terms against index entry names, titles, and aliases across all categories. Select up to **5** most relevant entries. Prioritise:
+
+1. Exact name/alias matches
+2. Partial matches on entry titles
+3. Related entries where extracted terms appear in the name or title
+
+If no entries match, return `status: "no_relevant_entries"`.
+
+### Step 5: Read and Extract
+
+For each matched entry, read the full content. Extract **only**:
+
+- Key patterns and conventions
+- Architectural decisions and their rationale
+- Gotchas, constraints, and explicit rules
+- Domain-specific validation requirements
+
+**Skip** generic content, background sections, and anything not actionable for a code reviewer.
+
+### Step 6: Return Structured Output
+
+Return a JSON block:
+
+```json
+{
+  "status": "ok",
+  "entries_searched": 12,
+  "entries_matched": 3,
+  "domain_context": "Bullet points of reviewer-actionable domain knowledge (~300 words max)",
+  "sources": ["entry-name-1", "entry-name-2"]
+}
+```
+
+- `entries_searched`: total entries in index
+- `entries_matched`: entries that matched search terms
+- `domain_context`: concise, reviewer-actionable bullet points. Focus on what a reviewer should look for or verify. Max ~300 words
+- `sources`: entry names used (for citation in the review report)
+
+## Important
+
+- Do NOT review code. Your job is context retrieval only.
+- Keep `domain_context` focused and actionable — reviewers will read this alongside their own findings.
+- If codex isn't configured or has no relevant entries, return early with the appropriate status. Don't fabricate context.