@orderful/droid 0.48.0 → 0.50.0

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

@@ -2,6 +2,8 @@ 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.2
 status: beta
+audience:
+  - all
 
 includes:
   skills:

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.

package/src/tools/code-review/skills/code-review/SKILL.md

@@ -15,6 +15,8 @@ Code-review has no configuration of its own. Optional integration with other too
 
 - **Brain skill** (optional): If installed, offers to save review results to a `/brain review` doc
   - Check with: `droid config --get tools.brain` to see if `brain_dir` is configured
+- **Codex skill** (optional): If configured, enriches EDI findings with organisational domain knowledge
+  - Check with: `droid config --get tools.codex` to see if `codex_repo` is configured
 
 **Overrides:** This skill supports user-defined overrides. See `/droid` skill § Skill Overrides.
 
@@ -32,6 +34,7 @@ The `/code-review` command orchestrates multiple specialized agents in parallel:
 2. **test-coverage-analyzer** - Test completeness and edge cases
 3. **error-handling-reviewer** - Silent failures, missing error handling
 4. **type-reviewer** - TypeScript type design, interface contracts
+5. **codex-context-researcher** (optional) - Domain knowledge from codex for EDI enrichment
 
 Each agent returns issues with confidence scores (0-100). Issues below 80% confidence are filtered out to reduce noise.
 
@@ -117,14 +120,19 @@ For PR reviews, also fetch:
 
 ### Step 3: Parallel Agent Reviews
 
+**Check codex availability** before launching agents:
+
+Run `droid config --get tools.codex`. If `codex_repo` is configured, you will launch 5 agents. If not, launch the standard 4.
+
 Launch these agents in parallel using the Task tool with `run_in_background: true`:
 
 1. **edi-standards-reviewer**: EDI patterns, partnership handling, billing concerns
 2. **test-coverage-analyzer**: Test completeness and edge cases
 3. **error-handling-reviewer**: Silent failures, missing error handling
 4. **type-reviewer**: Type design, interface contracts
+5. **codex-context-researcher** (only if codex is configured): Pass changed file paths and a brief summary of the diff (module names, domain concepts extracted from paths and PR description). Do NOT pass full diff content — this agent reads codex, not code.
 
-Pass each agent:
+Pass agents 1–4:
 
 1. The diff content
 2. The full file content for changed files (for context)
@@ -139,6 +147,17 @@ Filter out issues with confidence < 80.
 
 ### Step 5: Synthesize Report
 
+**Codex enrichment** (if codex-context-researcher returned `status: "ok"` with non-empty `domain_context`):
+
+Before compiling the EDI findings, prefix the EDI section with a "Domain Context" block:
+
+> **Domain context** (from codex: entry-name-1, entry-name-2)
+> - Bullet points from the researcher's domain_context
+
+Use this context to strengthen or re-prioritise EDI findings. For example, if codex says "partnership billing events must always include account_id" and the EDI reviewer flagged a missing field, elevate that finding's priority.
+
+If codex returned `status: "not_configured"` or `"no_relevant_entries"`, omit the domain context block silently.
+
 Compile findings into a prioritized report:
 
 **PR #123: "Add partnership billing events"** (if reviewing a PR)

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

@@ -1,6 +1,6 @@
 {
   "name": "droid-codex",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Shared organizational knowledge - PRDs, tech designs, domains, proposals, patterns, and explored topics. Self-describing: structure and workflows defined in codex repo. Use when loading project context, searching codex, capturing decisions, or creating new entries.",
   "author": {
     "name": "Orderful",

package/src/tools/codex/TOOL.yaml

@@ -1,7 +1,9 @@
 name: codex
 description: "Shared organizational knowledge - PRDs, tech designs, domains, proposals, patterns, and explored topics. Self-describing: structure and workflows defined in codex repo. Use when loading project context, searching codex, capturing decisions, or creating new entries."
-version: 0.3.1
+version: 0.4.0
 status: beta
+audience:
+  - all
 
 includes:
   skills:

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

@@ -145,6 +145,7 @@ The codex skill includes three git scripts. **Always use these instead of raw gi
 |--------|---------|-------------|
 | git-preamble | Ensure clean main + pull latest | Before ANY operation |
 | git-start-write | Preamble + create branch | Before write operations |
+| normalize-frontmatter | Normalize YAML frontmatter format | After writing, before commit |
 | git-finish-write | Commit + PR + return to main | After write operations |
 
 ### Read Operations
@@ -159,7 +160,10 @@ The codex skill includes three git scripts. **Always use these instead of raw gi
 
     # 2. Make your changes (write files)
 
-    # 3. Finish write (commit + PR + return to main)
+    # 3. Normalize frontmatter (prevents fix-frontmatter PRs)
+    droid config --get tools.codex | droid exec codex normalize-frontmatter --config -
+
+    # 4. Finish write (commit + PR + return to main)
     droid config --get tools.codex | droid exec codex git-finish-write --config - \
       --message "{commit message}" \
       --pr-title "{PR title}" \