@orderful/droid 0.37.0 → 0.39.0

package/src/lib/platforms.ts

@@ -4,9 +4,20 @@ import { execSync } from 'child_process';
 import { existsSync } from 'fs';
 import { Platform, type DroidConfig } from './types';
 
+// Re-export Codex-specific functions from platform.codex.ts
+export {
+  CODEX_SKILLS_PATH,
+  createCodexSymlink,
+  removeCodexSymlink,
+  removeAllCodexSymlinks,
+} from './platform.codex';
+
+import { createCodexSymlink } from './platform.codex';
+
 /**
  * Unified skills path - all platforms read from ~/.claude/skills/
  * This is the Agent Skills standard location supported by Claude Code, OpenCode, and Cursor.
+ * OpenAI Codex reads from ~/.codex/skills/, so we create symlinks there (see platform.codex.ts).
  */
 const UNIFIED_SKILLS_PATH = join(homedir(), '.claude', 'skills');
 
@@ -16,8 +27,17 @@ const UNIFIED_SKILLS_PATH = join(homedir(), '.claude', 'skills');
  *
  * Note: Skills are unified to ~/.claude/skills/ (all platforms read this location).
  * Commands and agents remain platform-specific as there's no cross-platform compatibility.
+ * OpenAI Codex only supports skills (via symlinks) - no commands, agents, or config integration.
  */
-export const PLATFORM_PATHS = {
+export const PLATFORM_PATHS: Record<
+  Platform,
+  {
+    skills: string;
+    commands: string | null;
+    agents: string | null;
+    config: string | null;
+  }
+> = {
   [Platform.ClaudeCode]: {
     skills: UNIFIED_SKILLS_PATH,
     commands: join(homedir(), '.claude', 'commands'),
@@ -38,9 +58,16 @@ export const PLATFORM_PATHS = {
     agents: join(homedir(), '.cursor', 'agents'),
     config: join(homedir(), '.cursor', 'rules'),
   },
-} as const;
+  [Platform.OpenAICodex]: {
+    // Codex reads from ~/.codex/skills/ but we install to unified path and symlink
+    skills: UNIFIED_SKILLS_PATH,
+    commands: null, // Not supported - Codex has built-in commands only
+    agents: null, // Not supported - Codex is single-agent
+    config: null, // No config file integration
+  },
+};
 
-export type PlatformPaths = typeof PLATFORM_PATHS[Platform];
+export type PlatformPaths = (typeof PLATFORM_PATHS)[Platform];
 
 /**
  * Get all paths for a platform
@@ -58,25 +85,42 @@ export function getSkillsPath(platform: Platform): string {
 
 /**
  * Get commands install path for a platform
+ * Returns null for platforms that don't support custom commands (e.g., OpenAI Codex)
  */
-export function getCommandsPath(platform: Platform): string {
+export function getCommandsPath(platform: Platform): string | null {
   return PLATFORM_PATHS[platform].commands;
 }
 
 /**
  * Get agents install path for a platform
+ * Returns null for platforms that don't support custom agents (e.g., OpenAI Codex)
  */
-export function getAgentsPath(platform: Platform): string {
+export function getAgentsPath(platform: Platform): string | null {
   return PLATFORM_PATHS[platform].agents;
 }
 
 /**
  * Get platform config file path (CLAUDE.md or AGENTS.md)
+ * Returns null for platforms without config file integration (e.g., OpenAI Codex)
  */
-export function getConfigPath(platform: Platform): string {
+export function getConfigPath(platform: Platform): string | null {
   return PLATFORM_PATHS[platform].config;
 }
 
+/**
+ * Check if a platform supports custom commands
+ */
+export function platformSupportsCommands(platform: Platform): boolean {
+  return PLATFORM_PATHS[platform].commands !== null;
+}
+
+/**
+ * Check if a platform supports custom agents
+ */
+export function platformSupportsAgents(platform: Platform): boolean {
+  return PLATFORM_PATHS[platform].agents !== null;
+}
+
 /**
  * Detect ALL installed platforms
  * Returns array of all platforms that are installed on the system
@@ -106,6 +150,12 @@ export function detectAllPlatforms(): Platform[] {
     // OpenCode not found
   }
 
+  // OpenAI Codex: check if .codex directory exists
+  const codexDir = join(homedir(), '.codex');
+  if (existsSync(codexDir)) {
+    detected.push(Platform.OpenAICodex);
+  }
+
   return detected;
 }
 
@@ -117,3 +167,74 @@ export function getActivePlatforms(config: DroidConfig): Platform[] {
   const ignored = config.ignored_platforms ?? [];
   return detected.filter(p => !ignored.includes(p));
 }
+
+/**
+ * Sync installed tools to newly detected platforms.
+ * Called early in common commands to handle platforms added after initial setup.
+ *
+ * Returns array of newly synced platforms (empty if none).
+ */
+export function syncNewPlatforms(config: DroidConfig): Platform[] {
+  const detected = detectAllPlatforms();
+  const ignored = config.ignored_platforms ?? [];
+  const active = detected.filter(p => !ignored.includes(p));
+
+  // Platforms already in config (have been initialized)
+  const initializedPlatforms = Object.keys(config.platforms ?? {}) as Platform[];
+
+  // Find newly detected platforms that aren't in config yet
+  const newPlatforms = active.filter(p => !initializedPlatforms.includes(p));
+
+  if (newPlatforms.length === 0) {
+    return [];
+  }
+
+  // Get installed skills from primary platform (claude-code)
+  const primaryTools = config.platforms?.['claude-code']?.tools ?? {};
+
+  // Initialize each new platform
+  for (const platform of newPlatforms) {
+    initializePlatformTools(platform, primaryTools, config);
+  }
+
+  return newPlatforms;
+}
+
+/**
+ * Initialize a newly detected platform with installed tools.
+ *
+ * For Codex: creates symlinks for tracked skills only (commands/agents not supported)
+ * For other platforms: would install commands/agents (not yet implemented)
+ */
+function initializePlatformTools(
+  platform: Platform,
+  primaryTools: Record<string, { version: string; installed_at: string; bundled_agents?: string[] }>,
+  config: DroidConfig,
+): void {
+  if (platform === Platform.OpenAICodex) {
+    // Codex: create symlinks only for skills tracked in config (not all skills in directory)
+    // This avoids syncing personal skills that weren't installed via droid
+    for (const skillName of Object.keys(primaryTools)) {
+      createCodexSymlink(skillName);
+    }
+
+    // Initialize platform section in config (mirrors primary platform's tools)
+    if (!config.platforms) {
+      config.platforms = {};
+    }
+    config.platforms[platform] = {
+      tools: { ...primaryTools },
+    };
+    return;
+  }
+
+  // For other platforms (Cursor, OpenCode): would need to install commands/agents
+  // This is a future enhancement - for now, just mark as initialized
+  if (!config.platforms) {
+    config.platforms = {};
+  }
+  config.platforms[platform] = {
+    tools: { ...primaryTools },
+  };
+}
+

package/src/lib/secrets.ts

@@ -0,0 +1,12 @@
+/**
+ * Secret/token helpers - reads from environment variables only
+ * Users manage their own tokens in shell config (e.g., ~/.zshrc)
+ */
+
+export function getSlackToken(): string | undefined {
+  return process.env.SLACK_USER_TOKEN;
+}
+
+export function hasSlackToken(): boolean {
+  return !!process.env.SLACK_USER_TOKEN;
+}

package/src/lib/skills.ts

@@ -29,6 +29,8 @@ import {
   getCommandsPath,
   getConfigPath,
   getActivePlatforms,
+  createCodexSymlink,
+  removeCodexSymlink,
 } from './platforms';
 import { loadToolManifest, isToolInstalled } from './tools';
 import { runToolMigrations } from './migrations';
@@ -56,15 +58,17 @@ export function getSkillsInstallPath(platform: Platform): string {
 
 /**
  * Get the commands installation path based on platform
+ * Returns null for platforms that don't support commands (e.g., OpenAI Codex)
  */
-export function getCommandsInstallPath(platform: Platform): string {
+export function getCommandsInstallPath(platform: Platform): string | null {
   return getCommandsPath(platform);
 }
 
 /**
  * Get the path to the platform's main config markdown file
+ * Returns null for platforms without config file integration (e.g., OpenAI Codex)
  */
-export function getPlatformConfigPath(platform: Platform): string {
+export function getPlatformConfigPath(platform: Platform): string | null {
   return getConfigPath(platform);
 }
 
@@ -77,6 +81,11 @@ export function updatePlatformConfigSkills(
 ): void {
   const configPath = getPlatformConfigPath(platform);
 
+  // Skip platforms without config file integration (e.g., OpenAI Codex)
+  if (!configPath) {
+    return;
+  }
+
   let content = '';
   if (existsSync(configPath)) {
     content = readFileSync(configPath, 'utf-8');
@@ -472,7 +481,7 @@ export function installSkill(skillName: string): {
 
   const skillsPath = getSkillsInstallPath(config.platform);
   const targetSkillDir = join(skillsPath, skillName);
-  const commandsPath = getCommandsInstallPath(config.platform);
+  const commandsPath = getCommandsInstallPath(config.platform); // null for platforms without commands
   const tools = getPlatformTools(config);
 
   // Clean up old droid- prefixed directories from v0.18.x (Claude Code bug workaround)
@@ -527,7 +536,8 @@ export function installSkill(skillName: string): {
     const toolName = basename(toolDir);
 
     // Check command file collisions (these could conflict with other skills)
-    if (existsSync(commandsSource)) {
+    // Skip for platforms that don't support commands (e.g., OpenAI Codex)
+    if (commandsPath && existsSync(commandsSource)) {
       const commandFiles = readdirSync(commandsSource).filter(
         (f) => f.endsWith('.md') && f.toLowerCase() !== 'readme.md',
       );
@@ -608,8 +618,14 @@ export function installSkill(skillName: string): {
     ? activePlatforms
     : [config.platform]; // Fallback to primary platform
 
+  // Create Codex symlink if Codex is an active platform
+  // Codex reads from ~/.codex/skills/ but skills are installed to ~/.claude/skills/
+  if (targetPlatforms.includes(Platform.OpenAICodex)) {
+    createCodexSymlink(skillName);
+  }
+
   // Copy commands if present (from tool level)
-  // Install to EACH active platform
+  // Install to EACH active platform that supports commands
   if (existsSync(commandsSource)) {
     const commandFiles = readdirSync(commandsSource).filter(
       (f) => f.endsWith('.md') && f.toLowerCase() !== 'readme.md',
@@ -617,6 +633,10 @@ export function installSkill(skillName: string): {
 
     for (const platform of targetPlatforms) {
       const platformCommandsPath = getCommandsInstallPath(platform);
+      // Skip platforms that don't support commands (e.g., OpenAI Codex)
+      if (!platformCommandsPath) {
+        continue;
+      }
       if (!existsSync(platformCommandsPath)) {
         mkdirSync(platformCommandsPath, { recursive: true });
       }
@@ -725,6 +745,9 @@ export function uninstallSkill(skillName: string): {
     ? activePlatforms
     : [config.platform]; // Fallback to primary platform
 
+  // Remove Codex symlink if it exists (before removing the actual skill)
+  removeCodexSymlink(skillName);
+
   // Remove skill files from unified location
   const skillsPath = getSkillsInstallPath(config.platform);
   const skillDir = join(skillsPath, skillName);
@@ -732,7 +755,7 @@ export function uninstallSkill(skillName: string): {
     rmSync(skillDir, { recursive: true });
   }
 
-  // Remove command files from EACH active platform
+  // Remove command files from EACH active platform that supports commands
   const skillPath = findSkillPath(skillName);
   const commandsSource = skillPath ? join(skillPath.toolDir, 'commands') : null;
   if (commandsSource && existsSync(commandsSource)) {
@@ -742,6 +765,10 @@ export function uninstallSkill(skillName: string): {
 
     for (const platform of targetPlatforms) {
       const platformCommandsPath = getCommandsInstallPath(platform);
+      // Skip platforms that don't support commands (e.g., OpenAI Codex)
+      if (!platformCommandsPath) {
+        continue;
+      }
       for (const file of commandFiles) {
         const commandPath = join(platformCommandsPath, file);
         if (existsSync(commandPath)) {
@@ -829,6 +856,11 @@ export function isCommandInstalled(
   const config = loadConfig();
   const commandsPath = getCommandsInstallPath(config.platform);
 
+  // Platform doesn't support commands (e.g., OpenAI Codex)
+  if (!commandsPath) {
+    return false;
+  }
+
   // Command filename is derived from the command name after the skill prefix
   // e.g., "comments check" from skill "comments" → "check.md"
   const cmdPart = commandName.startsWith(skillName + ' ')
@@ -884,6 +916,13 @@ export function installCommand(
 
   // Ensure commands directory exists
   const commandsPath = getCommandsInstallPath(config.platform);
+  // Platform doesn't support commands (e.g., OpenAI Codex)
+  if (!commandsPath) {
+    return {
+      success: false,
+      message: `Platform ${config.platform} does not support custom commands`,
+    };
+  }
   if (!existsSync(commandsPath)) {
     mkdirSync(commandsPath, { recursive: true });
   }
@@ -919,6 +958,14 @@ export function uninstallCommand(
 
   const commandsPath = getCommandsInstallPath(config.platform);
 
+  // Platform doesn't support commands (e.g., OpenAI Codex)
+  if (!commandsPath) {
+    return {
+      success: false,
+      message: `Platform ${config.platform} does not support custom commands`,
+    };
+  }
+
   // Find the installed command file
   const cmdPart = commandName.startsWith(skillName + ' ')
     ? commandName.slice(skillName.length + 1)

package/src/lib/types.ts

@@ -2,6 +2,7 @@ export enum Platform {
   ClaudeCode = 'claude-code',
   OpenCode = 'opencode',
   Cursor = 'cursor',
+  OpenAICodex = 'openai-codex',
 }
 
 // Backwards compatibility alias - using different names to avoid redeclare error

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

@@ -1,6 +1,6 @@
 {
   "name": "droid-brain",
-  "version": "0.3.9",
+  "version": "0.4.0",
   "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",
@@ -12,5 +12,12 @@
     "droid",
     "ai",
     "brain"
+  ],
+  "skills": [
+    "./skills/brain/SKILL.md",
+    "./skills/brain-obsidian/SKILL.md"
+  ],
+  "commands": [
+    "./commands/brain.md"
   ]
 }

package/src/tools/brain/TOOL.yaml

@@ -1,6 +1,6 @@
 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.3.9
+version: 0.4.0
 status: beta
 
 includes:

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

@@ -32,6 +32,7 @@ Your **scratchpad** (or **brain**) - a collaborative space for planning, researc
 | -------------- | ------- | ------------------------------------------ |
 | `brain_dir`    | (none)  | Where docs are stored - **must be configured** |
 | `inbox_folder` | (empty) | Root folder for new docs (e.g., `0-Inbox`) |
+| `override`     | (none)  | User-defined behaviour overrides |
 
 **If not configured:** Ask the user:
 > "Where would you like to store brain docs? Common choices:
@@ -39,11 +40,13 @@ Your **scratchpad** (or **brain**) - a collaborative space for planning, researc
 > - `~/src/github.com/brain` - With your other repos
 > - An existing Obsidian vault path"
 
-Then write their choice to `~/.droid/skills/brain/overrides.yaml`:
-```yaml
-brain_dir: "{user's choice}"
+Then set their choice:
+```bash
+droid config --set tools.brain.brain_dir="{user's choice}"
 ```
 
+**Overrides:** This skill supports user-defined overrides. See `/droid` skill § Skill Overrides for how to create, register, and use overrides.
+
 ## Commands
 
 **Reserved keywords:** `search`, `add`, `check`, `cleanup`, `done`

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

@@ -14,7 +14,11 @@ Detailed procedures for each brain operation.
    - If `brain_dir` is not configured, **ask the user** where they want brain docs stored
    - **Do NOT skip this step or assume defaults**
 
-2. **Search for matches**
+2. **Check for override** (see `/droid` skill § Override Lookup)
+   - If override applies for `search` command, follow override instructions instead of step 3
+   - Fall back to step 3 if override fails
+
+3. **Search for matches** (default behaviour)
 
    ```
    Glob: {brain_dir}/**/*{topic}*.md
@@ -22,20 +26,20 @@ Detailed procedures for each brain operation.
 
    Fuzzy match the topic against doc filenames
 
-3. **Handle results:**
+4. **Handle results:**
    - **No matches**: Offer to create a new doc with that topic
    - **One match**: Open it
    - **Multiple matches**: Present list, let user choose
 
-4. **Read the doc** and summarize key points:
+5. **Read the doc** and summarize key points:
    - Current status
    - Main topic/context
    - Any open `@droid` comments
    - Recent updates
 
-5. **Set as active doc** - Remember path for subsequent `/brain add` and `/brain check` commands
+6. **Set as active doc** - Remember path for subsequent `/brain add` and `/brain check` commands
 
-6. **If `-- {instruction}` provided:** Execute the follow-up instruction against the loaded doc
+7. **If `-- {instruction}` provided:** Execute the follow-up instruction against the loaded doc
 
 ## Creating
 

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

@@ -33,6 +33,8 @@ droid config --set tools.brain.brain_dir=~/path/to/your/vault
 | `areas_folder`     | `1-Areas`     | Area docs (PARA only)           |
 | `resources_folder` | `3-Resources` | Reference material (PARA only)  |
 
+**Overrides:** This skill supports user-defined overrides. See `/droid` skill § Skill Overrides.
+
 ## What This Adds
 
 | Feature             | Description                                |

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

@@ -12,5 +12,11 @@
     "droid",
     "ai",
     "coach"
+  ],
+  "skills": [
+    "./skills/coach/SKILL.md"
+  ],
+  "commands": [
+    "./commands/coach.md"
   ]
 }

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

@@ -52,6 +52,9 @@ plan → AI scaffolds → human implements → AI coaches → iterate → ship
 | Setting              | Default  | Description                                             |
 | -------------------- | -------- | ------------------------------------------------------- |
 | `scaffold_verbosity` | `medium` | How detailed hints are: `minimal`, `medium`, `detailed` |
+| `override`           | (none)   | User-defined behaviour overrides                        |
+
+**Overrides:** This skill supports user-defined overrides. See `/droid` skill § Skill Overrides.
 
 <!-- Note: @mention is the target, not author. @{user} = AI talking TO user, @droid = user talking TO AI -->
 > @{user} Not yet - droid currently shows config as free text input. But we could add an `enum` type to the config schema that presents as a select dropdown in the TUI. Good feature request - want me to create an issue for it?

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

@@ -12,5 +12,17 @@
     "droid",
     "ai",
     "code-review"
+  ],
+  "skills": [
+    "./skills/code-review/SKILL.md"
+  ],
+  "commands": [
+    "./commands/code-review.md"
+  ],
+  "agents": [
+    "./agents/edi-standards-reviewer.md",
+    "./agents/error-handling-reviewer.md",
+    "./agents/test-coverage-analyzer.md",
+    "./agents/type-reviewer.md"
   ]
 }

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

@@ -16,6 +16,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
 
+**Overrides:** This skill supports user-defined overrides. See `/droid` skill § Skill Overrides.
+
 ## How It Works
 
 The `/code-review` command orchestrates multiple specialized agents in parallel:

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

@@ -12,5 +12,14 @@
     "droid",
     "ai",
     "codex"
+  ],
+  "skills": [
+    "./skills/codex/SKILL.md"
+  ],
+  "commands": [
+    "./commands/codex.md"
+  ],
+  "agents": [
+    "./agents/codex-document-processor.md"
   ]
 }

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

@@ -82,6 +82,9 @@ If prerequisites fail, guide user to fix:
 |---------|---------|-------------|
 | codex_repo | ~/src/github.com/orderful-codex | Path to local codex repo |
 | freshness_days | 30 | Days before staleness warning |
+| override | (none) | User-defined behaviour overrides |
+
+**Overrides:** This skill supports user-defined overrides. See `/droid` skill § Skill Overrides.
 
 ## Commands
 

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

@@ -12,5 +12,11 @@
     "droid",
     "ai",
     "comments"
+  ],
+  "skills": [
+    "./skills/comments/SKILL.md"
+  ],
+  "commands": [
+    "./commands/comments.md"
   ]
 }

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

@@ -122,8 +122,13 @@ ai_mentions: "@claude"
 
 # Keep comments after addressing them (default: true)
 preserve_comments: true
+
+# User-defined behaviour overrides (see /droid skill)
+override: ...
 ```
 
+**Overrides:** This skill supports user-defined overrides. See `/droid` skill § Skill Overrides.
+
 ## File Type Support
 
 Works in any text file. Respects `.gitignore` and skips common build directories (node_modules, dist, .git, etc.).

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

@@ -1,6 +1,6 @@
 {
   "name": "droid",
-  "version": "0.5.3",
+  "version": "0.7.0",
   "description": "Core droid meta-skill for update awareness, tool discovery, and usage help. Checks for updates, helps users find tools, and answers 'how do I...' questions about droid workflows.",
   "author": {
     "name": "Orderful",
@@ -11,5 +11,12 @@
   "keywords": [
     "droid",
     "ai"
+  ],
+  "skills": [
+    "./skills/droid/SKILL.md",
+    "./skills/droid-bootstrap/SKILL.md"
+  ],
+  "commands": [
+    "./commands/setup.md"
   ]
 }

package/src/tools/droid/TOOL.yaml

@@ -1,6 +1,6 @@
 name: droid
 description: "Core droid meta-skill for update awareness, tool discovery, and usage help. Checks for updates, helps users find tools, and answers 'how do I...' questions about droid workflows."
-version: 0.5.3
+version: 0.7.0
 status: beta
 
 # System tool - always stays current regardless of auto-update settings
@@ -12,7 +12,9 @@ includes:
       required: true
     - name: droid-bootstrap
       required: true
-  commands: []
+  commands:
+    - name: setup
+      is_alias: false
   agents: []
 
 dependencies: []