@orderful/droid 0.26.0 → 0.27.0

package/src/lib/skills.ts

@@ -411,6 +411,15 @@ export function installSkill(skillName: string): {
     };
   }
 
+  // Load tool manifest to get command metadata (for is_alias flag)
+  const toolManifest = loadToolManifest(toolDir);
+  if (!toolManifest) {
+    return {
+      success: false,
+      message: `Invalid tool manifest for tool containing '${skillName}'`,
+    };
+  }
+
   // Check dependencies
   if (manifest.dependencies) {
     for (const dep of manifest.dependencies) {
@@ -428,49 +437,39 @@ export function installSkill(skillName: string): {
   const commandsPath = getCommandsInstallPath(config.platform);
   const tools = getPlatformTools(config);
 
-  // Clean up old skill directory if this is a renamed skill (v0.18.0 workaround for Claude Code bug)
-  // Renamed skills have 'droid-' prefix, so check for old directory without prefix
-  // Bug: https://github.com/anthropics/claude-code/issues/14945
-  //
-  // TO REVERSE WHEN BUG IS FIXED:
-  // 1. Rename directories: droid-comments/ → comments/, droid-brain/ → brain/, etc.
-  // 2. Update TOOL.yaml manifests back to original skill names
-  // 3. Update SKILL.md frontmatter back to original names
-  // 4. Replace this cleanup logic with inverse:
-  //    const renamedSkills = ['comments', 'brain', 'project', 'coach', 'code-review', 'brain-obsidian'];
-  //    if (renamedSkills.includes(skillName)) {
-  //      const droidPrefixedName = `droid-${skillName}`;
-  //      const droidPrefixedDir = join(skillsPath, droidPrefixedName);
-  //      if (existsSync(droidPrefixedDir)) {
-  //        rmSync(droidPrefixedDir, { recursive: true });
-  //      }
-  //      if (tools[droidPrefixedName]) {
-  //        delete tools[droidPrefixedName];
-  //      }
-  //    }
-  // 5. Bump tool versions and create changeset
-  // Migration logic: Handle skills renamed from {name} to droid-{name} (v0.18.0 workaround)
-  // This handles both fresh installs and updates where old directory/config entries exist
-  if (skillName.startsWith('droid-')) {
-    const oldSkillName = skillName.replace(/^droid-/, '');
-    const oldSkillDir = join(skillsPath, oldSkillName);
-
-    // Remove or migrate old skill directory
-    if (existsSync(oldSkillDir)) {
+  // Clean up old droid- prefixed directories from v0.18.x (Claude Code bug workaround)
+  // CLEANUP: Remove after v0.22.0 or 2026-04-01 (3 months post-v0.21.0 release)
+  // Migration for droid- prefix removal (v0.18.x → v0.21.0)
+  // These skills were temporarily renamed with droid- prefix, now back to original names
+  const renamedSkills = [
+    'comments',
+    'brain',
+    'project',
+    'coach',
+    'code-review',
+    'codex',
+    'tech-design',
+    'brain-obsidian',
+  ];
+  if (renamedSkills.includes(skillName)) {
+    const droidPrefixedName = `droid-${skillName}`;
+    const droidPrefixedDir = join(skillsPath, droidPrefixedName);
+
+    // Remove old droid- prefixed directory
+    if (existsSync(droidPrefixedDir)) {
       try {
-        rmSync(oldSkillDir, { recursive: true });
+        rmSync(droidPrefixedDir, { recursive: true });
       } catch (error) {
         // Non-fatal: Log warning but continue installation
         console.warn(
-          `Warning: Could not remove old skill directory ${oldSkillDir}: ${error}`,
+          `Warning: Could not remove old skill directory ${droidPrefixedDir}: ${error}`,
         );
       }
     }
 
     // Migrate old config entry if it exists
-    // This allows tools to show as "update available" rather than "not installed"
-    if (tools[oldSkillName]) {
-      delete tools[oldSkillName];
+    if (tools[droidPrefixedName]) {
+      delete tools[droidPrefixedName];
       // Save immediately to ensure cleanup is persisted (matches pattern in tools.ts)
       setPlatformTools(config, tools);
       saveConfig(config);
@@ -484,23 +483,10 @@ export function installSkill(skillName: string): {
   // Check for collisions BEFORE installing (only if not already installed by droid)
   // Note: If skill folder exists but skill isn't in config, we allow overwriting (stale state
   // from platform switch or manual cleanup). Command/agent collisions still checked.
-  //
-  // Special handling for droid- prefix migration (temporary workaround for Claude Code bug #14945):
-  // If installing droid-comments, check if 'comments' is in config (old naming)
-  const oldSkillName = skillName.startsWith('droid-')
-    ? skillName.replace(/^droid-/, '')
-    : null;
-  const isAlreadyInstalled =
-    tools[skillName] || (oldSkillName && tools[oldSkillName]);
+  const isAlreadyInstalled = tools[skillName];
 
   if (!isAlreadyInstalled) {
-    // For collision detection, also check if this is the same tool (with/without droid- prefix)
-    // E.g., installing droid-comments should be allowed to overwrite existing comments.md
-    //
-    // TO REVERSE WHEN BUG #14945 IS FIXED:
-    // Remove the normalizedToolName logic - tools will have original names without droid- prefix
     const toolName = basename(toolDir);
-    const normalizedToolName = toolName.replace(/^droid-/, '');
 
     // Check command file collisions (these could conflict with other skills)
     if (existsSync(commandsSource)) {
@@ -512,9 +498,9 @@ export function installSkill(skillName: string): {
         if (existsSync(targetCommandPath)) {
           const commandName = file.replace('.md', '');
 
-          // Allow overwrite if the command name matches the tool name (with/without prefix)
+          // Allow overwrite if the command name matches the tool name
           // E.g., installing 'comments' tool can overwrite 'comments.md'
-          if (commandName === toolName || commandName === normalizedToolName) {
+          if (commandName === toolName) {
             continue; // Same tool, allow overwrite
           }
 
@@ -595,6 +581,7 @@ export function installSkill(skillName: string): {
   }
 
   // Copy commands if present (from tool level)
+  // Platform-specific: Only install primary commands on OpenCode, always install aliases
   if (existsSync(commandsSource)) {
     if (!existsSync(commandsPath)) {
       mkdirSync(commandsPath, { recursive: true });
@@ -602,11 +589,25 @@ export function installSkill(skillName: string): {
     const commandFiles = readdirSync(commandsSource).filter(
       (f) => f.endsWith('.md') && f.toLowerCase() !== 'readme.md',
     );
+
     for (const file of commandFiles) {
-      const sourcePath = join(commandsSource, file);
-      const targetPath = join(commandsPath, file);
-      const content = readFileSync(sourcePath, 'utf-8');
-      writeFileSync(targetPath, content);
+      const commandName = file.replace('.md', '');
+
+      // Find this command in the tool manifest to check if it's an alias
+      const commandMeta = toolManifest.includes.commands.find(
+        (cmd) => (typeof cmd === 'string' ? cmd : cmd.name) === commandName,
+      );
+      const isAlias = typeof commandMeta === 'object' && commandMeta.is_alias;
+
+      // Install if: OpenCode (all commands) OR alias (both platforms)
+      const shouldInstall = config.platform === Platform.OpenCode || isAlias;
+
+      if (shouldInstall) {
+        const sourcePath = join(commandsSource, file);
+        const targetPath = join(commandsPath, file);
+        const content = readFileSync(sourcePath, 'utf-8');
+        writeFileSync(targetPath, content);
+      }
     }
   }
 

package/src/lib/tools.ts

@@ -3,7 +3,12 @@ import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import YAML from 'yaml';
 import { loadConfig, saveConfig } from './config';
-import { type ToolManifest, type ToolIncludes, getPlatformTools, setPlatformTools } from './types';
+import {
+  type ToolManifest,
+  type ToolIncludes,
+  getPlatformTools,
+  setPlatformTools,
+} from './types';
 import { compareSemver } from './version';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -78,15 +83,15 @@ export function isToolInstalled(toolName: string): boolean {
   const installedTools = getPlatformTools(config);
 
   // A tool is installed if any of its required skills are in the installed tools
-  const tool = getBundledTools().find(t => t.name === toolName);
+  const tool = getBundledTools().find((t) => t.name === toolName);
   if (!tool) return false;
 
   const requiredSkills = tool.includes.skills
-    .filter(s => s.required)
-    .map(s => s.name);
+    .filter((s) => s.required)
+    .map((s) => s.name);
 
   // Tool is installed if at least one required skill is installed
-  return requiredSkills.some(skillName => skillName in installedTools);
+  return requiredSkills.some((skillName) => skillName in installedTools);
 }
 
 /**
@@ -96,13 +101,13 @@ export function getInstalledToolVersion(toolName: string): string | null {
   const config = loadConfig();
   const installedTools = getPlatformTools(config);
 
-  const tool = getBundledTools().find(t => t.name === toolName);
+  const tool = getBundledTools().find((t) => t.name === toolName);
   if (!tool) return null;
 
   // Get version from the first installed required skill
   const requiredSkills = tool.includes.skills
-    .filter(s => s.required)
-    .map(s => s.name);
+    .filter((s) => s.required)
+    .map((s) => s.name);
 
   for (const skillName of requiredSkills) {
     if (installedTools[skillName]) {
@@ -139,7 +144,7 @@ export interface ToolUpdateInfo {
  */
 export function getToolUpdateStatus(toolName: string): ToolUpdateInfo {
   const installedVersion = getInstalledToolVersion(toolName);
-  const tool = getBundledTools().find(t => t.name === toolName);
+  const tool = getBundledTools().find((t) => t.name === toolName);
   const bundledVersion = tool?.version || null;
 
   if (!installedVersion || !bundledVersion) {
@@ -176,10 +181,12 @@ export function getToolsWithUpdates(): ToolUpdateInfo[] {
   for (const tool of bundledTools) {
     // Find if any of the tool's required skills are installed
     const requiredSkills = tool.includes.skills
-      .filter(s => s.required)
-      .map(s => s.name);
+      .filter((s) => s.required)
+      .map((s) => s.name);
 
-    const isInstalled = requiredSkills.some(skillName => skillName in installedTools);
+    const isInstalled = requiredSkills.some(
+      (skillName) => skillName in installedTools,
+    );
 
     if (isInstalled) {
       const updateStatus = getToolUpdateStatus(tool.name);

package/src/lib/types.ts

@@ -43,7 +43,7 @@ export interface PlatformConfig {
 }
 
 export interface AutoUpdateConfig {
-  app: boolean;   // Auto-update droid CLI (default: false)
+  app: boolean; // Auto-update droid CLI (default: false)
   tools: boolean; // Auto-update installed tools (default: true)
 }
 
@@ -54,7 +54,12 @@ export interface DroidConfig {
   git_username: string;
   platforms: Record<string, PlatformConfig>;
   auto_update?: AutoUpdateConfig;
-  migrations?: Record<string, string>; // tool name -> last migrated version
+  migrations?: {
+    package?: string; // Last package version migrated
+    tools?: Record<string, string>; // tool name -> last tool version migrated
+    // Legacy: old configs may have tool names at root level
+    [key: string]: string | Record<string, string> | undefined;
+  };
 }
 
 // Legacy config structure for migration
@@ -69,14 +74,19 @@ export interface LegacyDroidConfig {
 /**
  * Get installed tools for the current platform
  */
-export function getPlatformTools(config: DroidConfig): Record<string, InstalledSkill> {
+export function getPlatformTools(
+  config: DroidConfig,
+): Record<string, InstalledSkill> {
   return config.platforms[config.platform]?.tools ?? {};
 }
 
 /**
  * Set installed tools for the current platform
  */
-export function setPlatformTools(config: DroidConfig, tools: Record<string, InstalledSkill>): void {
+export function setPlatformTools(
+  config: DroidConfig,
+  tools: Record<string, InstalledSkill>,
+): void {
   if (!config.platforms[config.platform]) {
     config.platforms[config.platform] = { tools: {} };
   }
@@ -145,9 +155,14 @@ export interface ToolSkillInclude {
   examples?: SkillExample[];
 }
 
+export interface ToolCommandInclude {
+  name: string;
+  is_alias: boolean;
+}
+
 export interface ToolIncludes {
   skills: ToolSkillInclude[];
-  commands: string[];
+  commands: ToolCommandInclude[];
   agents: string[];
 }
 

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

@@ -1,6 +1,6 @@
 {
   "name": "droid-brain",
-  "version": "0.2.3",
+  "version": "0.3.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",

package/src/tools/brain/TOOL.yaml

@@ -1,18 +1,20 @@
 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.2.3
+version: 0.3.0
 status: beta
 
 includes:
   skills:
-    - name: droid-brain
+    - name: brain
       required: true
-    - name: droid-brain-obsidian
+    - name: brain-obsidian
       required: false
       description: "Obsidian vault integration with YAML frontmatter and wikilinks"
   commands:
-    - brain
-    - scratchpad
+    - name: brain
+      is_alias: false
+    - name: scratchpad
+      is_alias: true
   agents: []
 
 dependencies: []

package/src/tools/brain/commands/brain.md

@@ -1,65 +1,33 @@
 ---
-description: Collaborative scratchpad for planning and research
+name: brain
+description: "Collaborative scratchpad for planning and research"
 argument-hint: "[{topic} | plan|research|review {topic} | idea|add {text} | check|done]"
-allowed-tools: [Read, Write, Edit, Glob, Grep, Bash(mkdir:*), Bash(ls:*)]
 ---
 
 # /brain
 
-Entry point for brain doc management. See the **brain skill** for full behavior.
+**User invoked:** `/brain $ARGUMENTS`
 
-> **Alias:** This command also works as `/scratchpad` - use whichever feels natural.
-
-## Arguments
-
-$ARGUMENTS
-
-## Default Behavior
+**Your task:** Invoke the **brain skill** with these arguments.
 
-**IMPORTANT:** When given just a topic (e.g., `/brain auth-refactor`), the default action is to **SEARCH** for existing docs, NOT create. Only create docs with explicit `/brain plan {topic}` or `/brain research {topic}`.
-
-## Usage
-
-```
-/brain                      # List recent docs or create new
-/brain {topic}              # SEARCH: Open existing doc (fuzzy match) → active
-/brain plan {topic}         # CREATE: New planning doc → plans/
-/brain research {topic}     # Create research doc → research/
-/brain review {topic}       # Create review doc → reviews/
-/brain idea {text}          # Quick capture → ideas/ (fire-and-forget)
-/brain add {text}           # Append to active doc
-/brain check                # Address @droid comments in active doc
-/brain done                 # Finalize active doc
-```
-
-## Configuration
-
-**ALWAYS read `~/.droid/skills/brain/overrides.yaml` first.** Use configured values if present, only fall back to defaults if missing.
+> **Alias:** This command also works as `/scratchpad` - use whichever feels natural.
 
-- `brain_dir` - Where docs live (default varies by AI tool)
-- `inbox_folder` - Root for type folders (e.g., `0-Inbox`)
+## Examples
 
-## Folder Structure
+- `/brain auth-refactor` → Search for existing doc about "auth-refactor"
+- `/brain plan new-feature` → Create a new planning doc for "new-feature"
+- `/brain add found a bug in the parser` → Append text to active doc
 
-Docs are organized by type:
+## Quick Reference
 
 ```
-{brain_dir}/{inbox_folder}/
-├── plans/
-├── research/
-├── reviews/
-└── ideas/
+/brain {topic}              # SEARCH for existing doc (default action)
+/brain plan {topic}         # CREATE new planning doc
+/brain research {topic}     # CREATE new research doc
+/brain idea {text}          # Quick capture to ideas/
+/brain check                # Address @droid comments
 ```
 
-## Behavior
-
-Refer to the brain skill for:
-
-- **Opening**: How to fuzzy-match, handle multiple matches, set active
-- **Creating**: Template structure by preset, naming conventions
-- **Ideas**: Quick capture workflow
-- **Adding**: Append to active doc with timestamp
-- **Checking**: Find and address @droid comments
-- **Finalizing**: Update status, suggest next steps
+**Default behavior:** When given just a topic, SEARCH first (don't create unless plan/research/review keyword is present).
 
-The skill's `references/` folder contains detailed specs for workflows, templates, naming, and metadata.
+See the **brain skill** for complete documentation and procedures.

package/src/tools/brain/commands/scratchpad.md

@@ -1,65 +1,28 @@
 ---
-description: Collaborative scratchpad for planning and research
-argument-hint: "[{topic} | plan|research|review {topic} | idea|add {text} | check|done]"
-allowed-tools: [Read, Write, Edit, Glob, Grep, Bash(mkdir:*), Bash(ls:*)]
+name: scratchpad
+description: "Alias for brain. See brain skill for full behavior."
 ---
 
 # /scratchpad
 
-Your scratchpad for planning, research, and design. See the **brain skill** for full behavior.
+**User invoked:** `/scratchpad $ARGUMENTS`
 
-> **Alias:** This command also works as `/brain` - use whichever feels natural.
+**Your task:** Invoke the **brain skill** with these arguments (scratchpad is an alias for brain).
 
-## Arguments
+## Examples
 
-$ARGUMENTS
+- `/scratchpad auth-refactor` → Search for existing doc about "auth-refactor"
+- `/scratchpad plan new-feature` → Create a new planning doc for "new-feature"
 
-## Default Behavior
+## Quick Reference
 
-**IMPORTANT:** When given just a topic (e.g., `/scratchpad auth-refactor`), the default action is to **SEARCH** for existing docs, NOT create. Only create docs with explicit `/scratchpad plan {topic}` or `/scratchpad research {topic}`.
-
-## Usage
+Same as `/brain` - use whichever name feels natural:
 
 ```
-/scratchpad                      # List recent docs or create new
-/scratchpad {topic}              # SEARCH: Open existing doc (fuzzy match) → active
-/scratchpad plan {topic}         # CREATE: New planning doc → plans/
-/scratchpad research {topic}     # Create research doc → research/
-/scratchpad review {topic}       # Create review doc → reviews/
-/scratchpad idea {text}          # Quick capture → ideas/ (fire-and-forget)
-/scratchpad add {text}           # Append to active doc
-/scratchpad check                # Address @droid comments in active doc
-/scratchpad done                 # Finalize active doc
+/scratchpad {topic}         # SEARCH for existing doc
+/scratchpad plan {topic}    # CREATE new planning doc
 ```
 
-## Configuration
-
-**ALWAYS read `~/.droid/skills/brain/overrides.yaml` first.** Use configured values if present, only fall back to defaults if missing.
-
-- `brain_dir` - Where docs live (default varies by AI tool)
-- `inbox_folder` - Root for type folders (e.g., `0-Inbox`)
-
-## Folder Structure
-
-Docs are organized by type:
-
-```
-{brain_dir}/{inbox_folder}/
-├── plans/
-├── research/
-├── reviews/
-└── ideas/
-```
-
-## Behavior
-
-Refer to the brain skill for:
-
-- **Opening**: How to fuzzy-match, handle multiple matches, set active
-- **Creating**: Template structure by preset, naming conventions
-- **Ideas**: Quick capture workflow
-- **Adding**: Append to active doc with timestamp
-- **Checking**: Find and address @droid comments
-- **Finalizing**: Update status, suggest next steps
+**Default behavior:** SEARCH first, don't create unless plan/research/review keyword is present.
 
-The skill's `references/` folder contains detailed specs for workflows, templates, naming, and metadata.
+See `/brain` or the **brain skill** for complete documentation.

package/{dist/tools/brain/skills/droid-brain → src/tools/brain/skills/brain}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: droid-brain
+name: brain
 description: "Collaborative scratchpad for planning and research. Use when planning a feature, exploring a problem, or capturing thinking that should persist across sessions. User prompts like 'let's think through', 'open a scratchpad', 'plan this out', 'use our brain'."
 globs:
   - "**/brain/**/*.md"
@@ -39,10 +39,10 @@ Ideas develop through iteration, not single prompts.
 
 **IMPORTANT:** Before using any default paths, ALWAYS read `~/.droid/skills/brain/overrides.yaml` first. If `brain_dir` is configured there, use that path. Only fall back to defaults if the file doesn't exist or lacks a `brain_dir` setting.
 
-| Setting        | Default     | Description                                   |
-| -------------- | ----------- | --------------------------------------------- |
-| `brain_dir`    | (see below) | Where docs are stored                         |
-| `inbox_folder` | (empty)     | Root folder for new docs (e.g., `0-Inbox`)    |
+| Setting        | Default     | Description                                |
+| -------------- | ----------- | ------------------------------------------ |
+| `brain_dir`    | (see below) | Where docs are stored                      |
+| `inbox_folder` | (empty)     | Root folder for new docs (e.g., `0-Inbox`) |
 
 Default `brain_dir` by AI tool (only if not configured):
 

package/src/tools/brain/skills/{droid-brain-obsidian → brain-obsidian}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: droid-brain-obsidian
+name: brain-obsidian
 description: "Obsidian extension for brain skill with YAML frontmatter, wikilinks, and PARA folder organization. Use when your brain docs live in an Obsidian vault."
 globs:
   - "**/brain/**/*.md"
@@ -114,10 +114,10 @@ When running `/brain done`:
 
 Same commands as brain skill, but with Obsidian output:
 
-| Command                   | Obsidian Behavior                             |
-| ------------------------- | --------------------------------------------- |
-| `/brain plan {topic}`     | Creates in `plans/` with frontmatter          |
-| `/brain research {topic}` | Creates in `research/` with frontmatter       |
-| `/brain review {topic}`   | Creates in `reviews/` with frontmatter        |
-| `/brain idea {text}`      | Quick capture to `ideas/`                     |
-| `/brain done`             | Updates status, suggests archive/PARA move    |
+| Command                   | Obsidian Behavior                          |
+| ------------------------- | ------------------------------------------ |
+| `/brain plan {topic}`     | Creates in `plans/` with frontmatter       |
+| `/brain research {topic}` | Creates in `research/` with frontmatter    |
+| `/brain review {topic}`   | Creates in `reviews/` with frontmatter     |
+| `/brain idea {text}`      | Quick capture to `ideas/`                  |
+| `/brain done`             | Updates status, suggests archive/PARA move |

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

@@ -1,6 +1,6 @@
 {
   "name": "droid-coach",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "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.",
   "author": {
     "name": "Orderful",

package/src/tools/coach/TOOL.yaml

@@ -1,14 +1,15 @@
 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.1.3
+version: 0.2.0
 status: beta
 
 includes:
   skills:
-    - name: droid-coach
+    - name: coach
       required: true
   commands:
-    - coach
+    - name: coach
+      is_alias: false
   agents: []
 
 dependencies: