@orderful/droid 0.25.2 → 0.27.0

package/dist/tools/tech-design/skills/tech-design/references/thought-doc-template.md

@@ -0,0 +1,72 @@
+# Thought Doc Template
+
+Used when creating thought doc via `/brain plan tech-design-{project}`.
+
+```markdown
+# [Tech Design] {Project Name}
+
+**Type:** plan
+**Status:** exploring
+**Created:** {YYYY-MM-DD}
+**PRD:** [[codex:projects/{project}/PRD]]
+**Research:** [[tech-design-{project}-research]]
+
+Tech design for {project}.
+
+## Background
+
+{Why we're doing this - 2-3 paragraphs from PRD}
+
+{What problem we're solving, who it's for, why it matters}
+
+See research doc for codebase context and discovered patterns.
+
+## Proposal
+
+{What we're building - to be drafted}
+
+## Open Questions
+
+{What we don't know yet - to be explored}
+```
+
+## Variable Substitutions
+
+| Variable         | Example                 | Notes                       |
+| ---------------- | ----------------------- | --------------------------- |
+| `{Project Name}` | "Transaction Templates" | Human-readable project name |
+| `{YYYY-MM-DD}`   | "2026-01-10"            | Current date                |
+| `{project}`      | "transaction-templates" | Codex project slug          |
+
+## Philosophy
+
+**Start minimal:** 3 sections (Background, Proposal, Open Questions)
+
+**Gaps surface more:** Use `/tech-design gaps` to discover what sections to add (Data Model, API Surface, Rollout Plan, etc.)
+
+**Research doc separation:** The thought doc references the research doc but doesn't duplicate codebase discoveries. Keep the thought doc focused on architectural decisions.
+
+## Sections That Can Be Added
+
+Via `/tech-design draft {section}` or `/tech-design gaps`:
+
+- **Scope** - What's in/out explicitly
+- **Data Model** - Tables, schemas, types
+- **API Surface** - Endpoints, methods, interfaces
+- **Implementation Plan** - Step-by-step approach
+- **Key Decisions** - Options considered, what we chose and why
+- **Trade-off Analysis** - Pros/cons of approach
+- **Risks & Mitigations** - What could go wrong, how to handle it
+- **Metrics** - What we'll measure
+- **Rollout Plan** - Phased deployment, feature flags, rollback
+- **Security Considerations** - Auth, validation, audit logging
+
+## Template Evolution
+
+The template starts with 3 sections, but the thought doc grows based on:
+
+1. **User adds via `/draft {section}`** - AI generates section from research
+2. **User explores via `/think {topic}`** - May add sections organically
+3. **User identifies via `/gaps`** - Shows what's missing, suggests adding
+
+The minimal start reduces cognitive load. Sections appear when needed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orderful/droid",
-  "version": "0.25.2",
+  "version": "0.27.0",
   "description": "AI workflow toolkit for sharing skills, commands, and agents across the team",
   "type": "module",
   "bin": {
@@ -8,7 +8,8 @@
   },
   "main": "dist/index.js",
   "scripts": {
-    "build": "bun run lint && bun scripts/build.ts",
+    "build": "bun run lint && bun scripts/build.ts && bun scripts/build-plugins.ts",
+    "build:plugins": "bun scripts/build-plugins.ts",
     "dev": "tsc --watch",
     "start": "bun dist/bin/droid.js",
     "test": "bun test src/",

package/scripts/build-plugins.ts

@@ -0,0 +1,207 @@
+#!/usr/bin/env bun
+/**
+ * Build Claude Code plugin manifests from src/tools/
+ *
+ * This script generates:
+ * - src/tools/{tool}/.claude-plugin/plugin.json (from TOOL.yaml)
+ * - .claude-plugin/marketplace.json (at repo root)
+ *
+ * No file duplication - skills, commands, and agents stay in place.
+ * The src/tools/ directory serves both TUI and plugin distribution.
+ *
+ * Note: All tools are published to the marketplace, including those with
+ * `system: true` in their TOOL.yaml. System tools can still be installed
+ * individually via the plugin system.
+ */
+
+import { mkdirSync, writeFileSync, existsSync, readdirSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { parse as parseYaml } from 'yaml';
+
+interface ToolManifest {
+  name: string;
+  description: string;
+  version: string;
+  status?: string;
+  system?: boolean;
+  includes: {
+    skills: Array<{ name: string; required: boolean; description?: string }>;
+    commands: string[];
+    agents: string[];
+  };
+  dependencies?: string[];
+  config_schema?: Record<string, unknown>;
+}
+
+interface PluginJson {
+  name: string;
+  version: string;
+  description: string;
+  author: {
+    name: string;
+    url?: string;
+  };
+  repository?: string;
+  license?: string;
+  keywords?: string[];
+}
+
+interface MarketplacePlugin {
+  name: string;
+  description: string;
+  version: string;
+  source: {
+    source: string;
+    repo: string;
+    path: string;
+  };
+  author: {
+    name: string;
+  };
+}
+
+interface MarketplaceJson {
+  name: string;
+  description: string;
+  owner: {
+    name: string;
+    url?: string;
+  };
+  plugins: MarketplacePlugin[];
+}
+
+const TOOLS_DIR = 'src/tools';
+const AUTHOR = {
+  name: 'Orderful',
+  url: 'https://github.com/orderful',
+};
+const REPO = 'https://github.com/orderful/droid';
+const REPO_SHORT = 'orderful/droid';
+
+/**
+ * Get the plugin name with droid- prefix (for namespace isolation).
+ * The 'droid' core tool keeps its name as-is to avoid 'droid-droid'.
+ */
+function getPluginName(toolName: string): string {
+  if (toolName === 'droid') return 'droid';
+  return toolName.startsWith('droid-') ? toolName : `droid-${toolName}`;
+}
+
+function loadToolManifest(toolDir: string): ToolManifest | null {
+  const manifestPath = join(toolDir, 'TOOL.yaml');
+  if (!existsSync(manifestPath)) {
+    return null;
+  }
+  try {
+    const content = readFileSync(manifestPath, 'utf-8');
+    const parsed = parseYaml(content) as ToolManifest;
+    if (!parsed.name || !parsed.description || !parsed.version) {
+      console.error(`Invalid TOOL.yaml in ${toolDir}: missing required fields (name, description, version)`);
+      return null;
+    }
+    return parsed;
+  } catch (err) {
+    console.error(`Failed to parse TOOL.yaml in ${toolDir}:`, err);
+    return null;
+  }
+}
+
+function getToolDirs(): string[] {
+  const entries = readdirSync(TOOLS_DIR, { withFileTypes: true });
+  return entries
+    .filter((e) => e.isDirectory())
+    .map((e) => join(TOOLS_DIR, e.name))
+    .filter((dir) => existsSync(join(dir, 'TOOL.yaml')));
+}
+
+function createPluginJson(manifest: ToolManifest, pluginName: string): PluginJson {
+  return {
+    name: pluginName,
+    version: manifest.version,
+    description: manifest.description,
+    author: AUTHOR,
+    repository: REPO,
+    license: 'MIT',
+    keywords: [...new Set(['droid', 'ai', manifest.name])],
+  };
+}
+
+function buildPluginManifest(toolDir: string): MarketplacePlugin | null {
+  const manifest = loadToolManifest(toolDir);
+  if (!manifest) {
+    return null;
+  }
+
+  const pluginName = getPluginName(manifest.name);
+
+  console.log(`Generating plugin.json for: ${pluginName} (v${manifest.version})`);
+
+  // Create .claude-plugin directory in the tool directory
+  const claudePluginDir = join(toolDir, '.claude-plugin');
+  mkdirSync(claudePluginDir, { recursive: true });
+
+  // Generate plugin.json
+  const pluginJson = createPluginJson(manifest, pluginName);
+  writeFileSync(join(claudePluginDir, 'plugin.json'), JSON.stringify(pluginJson, null, 2) + '\n');
+
+  // Return marketplace entry (path is relative to repo root)
+  return {
+    name: pluginName,
+    description: manifest.description,
+    version: manifest.version,
+    source: {
+      source: 'github',
+      repo: REPO_SHORT,
+      path: toolDir, // e.g., "src/tools/brain"
+    },
+    author: {
+      name: AUTHOR.name,
+    },
+  };
+}
+
+function buildMarketplace(plugins: MarketplacePlugin[]): void {
+  // Create marketplace.json at repo root for clean discovery
+  const marketplaceDir = '.claude-plugin';
+  mkdirSync(marketplaceDir, { recursive: true });
+
+  const marketplace: MarketplaceJson = {
+    name: 'droid',
+    description: 'AI-powered development tools for Claude Code',
+    owner: AUTHOR,
+    plugins: plugins.sort((a, b) => a.name.localeCompare(b.name)),
+  };
+
+  writeFileSync(join(marketplaceDir, 'marketplace.json'), JSON.stringify(marketplace, null, 2) + '\n');
+  console.log(`\nMarketplace manifest created at .claude-plugin/marketplace.json with ${plugins.length} plugins`);
+}
+
+function main(): void {
+  console.log('Generating Claude Code plugin manifests in src/tools/\n');
+
+  // Build plugin.json for each tool
+  const toolDirs = getToolDirs();
+  const plugins: MarketplacePlugin[] = [];
+
+  for (const toolDir of toolDirs) {
+    const plugin = buildPluginManifest(toolDir);
+    if (plugin) {
+      plugins.push(plugin);
+    }
+  }
+
+  // Build marketplace manifest
+  buildMarketplace(plugins);
+
+  console.log('\nPlugin manifest generation complete!');
+  console.log(`\nTo test locally:`);
+  console.log(`  /plugin marketplace add ${process.cwd()}`);
+  console.log(`  /plugin install droid-brain@droid`);
+}
+
+try {
+  main();
+} catch (err) {
+  console.error(err);
+  process.exit(1);
+}

package/src/commands/tui/components/Badge.test.tsx

@@ -29,7 +29,9 @@ describe('Badge', () => {
     const types = ['skill', 'command', 'agent'] as const;
     for (const type of types) {
       const { lastFrame } = render(<Badge type={type} />);
-      expect(lastFrame()).toContain(type.charAt(0).toUpperCase() + type.slice(1));
+      expect(lastFrame()).toContain(
+        type.charAt(0).toUpperCase() + type.slice(1),
+      );
     }
   });
 });
@@ -44,7 +46,7 @@ describe('ComponentBadges', () => {
         { name: 'skill1', required: true },
         { name: 'skill2', required: false },
       ],
-      commands: ['cmd1'],
+      commands: [{ name: 'cmd1', is_alias: false }],
       agents: [],
     },
   };
@@ -63,7 +65,11 @@ describe('ComponentBadges', () => {
   it('renders singular form for single item', () => {
     const singleSkillTool: ToolManifest = {
       ...mockTool,
-      includes: { skills: [{ name: 'skill1', required: true }], commands: [], agents: [] },
+      includes: {
+        skills: [{ name: 'skill1', required: true }],
+        commands: [],
+        agents: [],
+      },
     };
     const { lastFrame } = render(<ComponentBadges tool={singleSkillTool} />);
     expect(lastFrame()).toContain('1 skill');
@@ -82,7 +88,7 @@ describe('ComponentBadges', () => {
       ...mockTool,
       includes: {
         skills: [{ name: 's1', required: true }],
-        commands: ['c1'],
+        commands: [{ name: 'c1', is_alias: false }],
         agents: ['a1'],
       },
     };

package/src/commands/tui.tsx

@@ -14,7 +14,7 @@ import {
 import { configExists, loadConfig, getAutoUpdateConfig } from '../lib/config';
 import { Platform, type ConfigOption, type ToolManifest } from '../lib/types';
 import { getVersion } from '../lib/version';
-import { runToolMigrations } from '../lib/migrations';
+import { runPackageMigrations } from '../lib/migrations';
 import { type Tab, type View } from './tui/types';
 import { colors, MAX_VISIBLE_ITEMS } from './tui/constants';
 import { TabBar } from './tui/components/TabBar';
@@ -72,10 +72,10 @@ function App() {
       },
     });
 
-  // Run droid meta-tool migration on startup (sync installed tools across platforms)
+  // Run droid package migrations on startup (sync installed tools across platforms)
   useEffect(() => {
-    const droidVersion = getVersion();
-    runToolMigrations('droid', droidVersion);
+    const packageVersion = getVersion();
+    runPackageMigrations(packageVersion);
   }, []);
 
   // Auto-update app if enabled and update available

package/src/lib/migrations.ts

@@ -153,6 +153,14 @@ function createPlatformSyncMigration(version: string): Migration {
   };
 }
 
+/**
+ * Registry of package-level migrations
+ * These run when the @orderful/droid npm package updates
+ * Triggered by package version from package.json (e.g., 0.26.0)
+ * Run at TUI startup
+ */
+const PACKAGE_MIGRATIONS: Migration[] = [createPlatformSyncMigration('0.25.0')];
+
 /**
  * Registry of all tool migrations
  * Key: tool name (e.g., "brain", "comments")
@@ -169,8 +177,6 @@ const TOOL_MIGRATIONS: Record<string, Migration[]> = {
   comments: [createConfigDirMigration('droid-comments', '0.2.6')],
   project: [createConfigDirMigration('droid-project', '0.1.5')],
   coach: [createConfigDirMigration('droid-coach', '0.1.3')],
-  // Global migration for the droid meta-tool
-  droid: [createPlatformSyncMigration('0.25.0')],
 };
 
 /**
@@ -185,7 +191,18 @@ export function getToolMigrations(toolName: string): Migration[] {
  */
 export function getLastMigratedVersion(toolName: string): string {
   const config = loadConfig();
-  return config.migrations?.[toolName] ?? '0.0.0';
+
+  // Check new location first
+  if (config.migrations?.tools?.[toolName]) {
+    return config.migrations.tools[toolName];
+  }
+
+  // Fall back to old location (backward compatibility)
+  if (config.migrations && typeof config.migrations[toolName] === 'string') {
+    return config.migrations[toolName] as string;
+  }
+
+  return '0.0.0';
 }
 
 /**
@@ -196,10 +213,22 @@ export function setLastMigratedVersion(
   version: string,
 ): void {
   const config = loadConfig();
+
+  // Ensure new structure exists
   if (!config.migrations) {
     config.migrations = {};
   }
-  config.migrations[toolName] = version;
+  if (!config.migrations.tools) {
+    config.migrations.tools = {};
+  }
+
+  config.migrations.tools[toolName] = version;
+
+  // Clean up old location if it exists
+  if (typeof config.migrations[toolName] === 'string') {
+    delete config.migrations[toolName];
+  }
+
   saveConfig(config);
 }
 
@@ -273,3 +302,65 @@ export function runToolMigrations(
 
   return runMigrations(toolName, lastMigrated, installedVersion);
 }
+
+/**
+ * Run package-level migrations
+ * Call this on TUI startup with package version from package.json
+ */
+export function runPackageMigrations(packageVersion: string): {
+  success: boolean;
+  error?: string;
+} {
+  const config = loadConfig();
+  const lastMigrated = config.migrations?.package ?? '0.0.0';
+
+  // Only run if the package version is newer than last migrated
+  if (compareSemver(packageVersion, lastMigrated) <= 0) {
+    return { success: true };
+  }
+
+  // Filter migrations that need to run
+  const pendingMigrations = PACKAGE_MIGRATIONS.filter((m) => {
+    const afterFrom = compareSemver(m.version, lastMigrated) > 0;
+    const beforeOrAtTo = compareSemver(m.version, packageVersion) <= 0;
+    return afterFrom && beforeOrAtTo;
+  });
+
+  if (pendingMigrations.length === 0) {
+    // No migrations to run, but still update the version marker
+    config.migrations = config.migrations || {};
+    config.migrations.package = packageVersion;
+    saveConfig(config);
+    return { success: true };
+  }
+
+  const configDir = getConfigDir();
+
+  for (const migration of pendingMigrations) {
+    try {
+      migration.up(configDir);
+      logMigration('package', lastMigrated, migration.version, 'OK');
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+      logMigration(
+        'package',
+        lastMigrated,
+        migration.version,
+        'FAILED',
+        errorMessage,
+      );
+      // Don't update version marker on failure - will retry next time
+      return {
+        success: false,
+        error: `Package migration ${migration.version} failed: ${errorMessage}`,
+      };
+    }
+  }
+
+  // All migrations succeeded, update version marker
+  config.migrations = config.migrations || {};
+  config.migrations.package = packageVersion;
+  saveConfig(config);
+  return { success: true };
+}

package/src/lib/skill-config.ts

@@ -1,7 +1,11 @@
 import chalk from 'chalk';
 import inquirer from 'inquirer';
 import { saveSkillOverrides, loadConfig, loadSkillOverrides } from './config';
-import { ConfigOptionType, type SkillOverrides, type ConfigOption } from './types';
+import {
+  ConfigOptionType,
+  type SkillOverrides,
+  type ConfigOption,
+} from './types';
 
 /**
  * Prompt user to configure a skill after install
@@ -9,12 +13,15 @@ import { ConfigOptionType, type SkillOverrides, type ConfigOption } from './type
 export async function promptForSkillConfig(
   skillName: string,
   configSchema: Record<string, ConfigOption>,
-  askFirst: boolean = true
+  askFirst: boolean = true,
 ): Promise<void> {
   const globalConfig = loadConfig();
+  let shouldPrompt = true;
 
   if (askFirst) {
-    const { wantsConfigure } = await inquirer.prompt<{ wantsConfigure: boolean }>([
+    const { wantsConfigure } = await inquirer.prompt<{
+      wantsConfigure: boolean;
+    }>([
       {
         type: 'confirm',
         name: 'wantsConfigure',
@@ -23,73 +30,104 @@ export async function promptForSkillConfig(
       },
     ]);
 
-    if (!wantsConfigure) {
-      return;
-    }
+    shouldPrompt = wantsConfigure;
   }
 
-  console.log(chalk.bold(`\n⚙️  Configure ${skillName}\n`));
-
   // Load existing overrides to use as defaults
   const existingOverrides = loadSkillOverrides(skillName);
 
-  const questions = Object.entries(configSchema).map(([key, option]) => {
-    const baseQuestion = {
-      name: key,
-      message: option.description,
-    };
+  let overrides: SkillOverrides = {};
+
+  if (shouldPrompt) {
+    console.log(chalk.bold(`\n⚙️  Configure ${skillName}\n`));
 
-    // Use existing override as default if present
-    const existingValue = existingOverrides[key];
+    const questions = Object.entries(configSchema).map(([key, option]) => {
+      const baseQuestion = {
+        name: key,
+        message: option.description,
+      };
 
-    switch (option.type) {
-      case ConfigOptionType.Boolean:
-        return {
-          ...baseQuestion,
-          type: 'confirm' as const,
-          default: existingValue ?? option.default ?? false,
-        };
-      case ConfigOptionType.Select:
-        return {
-          ...baseQuestion,
-          type: 'list' as const,
-          choices: option.options || [],
-          default: existingValue ?? option.default,
-        };
-      case ConfigOptionType.String:
-      default: {
-        // For user_mention, default to global config value if no existing override
-        let defaultValue = existingValue ?? option.default ?? '';
-        if (key === 'user_mention' && !existingValue && globalConfig.user_mention) {
-          defaultValue = globalConfig.user_mention;
+      // Use existing override as default if present
+      const existingValue = existingOverrides[key];
+
+      switch (option.type) {
+        case ConfigOptionType.Boolean:
+          return {
+            ...baseQuestion,
+            type: 'confirm' as const,
+            default: existingValue ?? option.default ?? false,
+          };
+        case ConfigOptionType.Select:
+          return {
+            ...baseQuestion,
+            type: 'list' as const,
+            choices: option.options || [],
+            default: existingValue ?? option.default,
+          };
+        case ConfigOptionType.String:
+        default: {
+          // For user_mention, default to global config value if no existing override
+          let defaultValue = existingValue ?? option.default ?? '';
+          if (
+            key === 'user_mention' &&
+            !existingValue &&
+            globalConfig.user_mention
+          ) {
+            defaultValue = globalConfig.user_mention;
+          }
+          return {
+            ...baseQuestion,
+            type: 'input' as const,
+            default: defaultValue,
+          };
         }
-        return {
-          ...baseQuestion,
-          type: 'input' as const,
-          default: defaultValue,
-        };
+      }
+    });
+
+    const answers = await inquirer.prompt(questions);
+
+    // Save all answers (including defaults)
+    for (const [key, value] of Object.entries(answers)) {
+      // Save all non-empty values
+      if (value !== '' && value !== undefined && value !== null) {
+        overrides[key] = value as string | boolean | number;
       }
     }
-  });
+  } else {
+    // User declined to configure - use defaults from schema
+    for (const [key, option] of Object.entries(configSchema)) {
+      const existingValue = existingOverrides[key];
+      let defaultValue =
+        existingValue ??
+        option.default ??
+        (option.type === ConfigOptionType.Boolean ? false : '');
 
-  const answers = await inquirer.prompt(questions);
+      // Special handling for user_mention
+      if (
+        key === 'user_mention' &&
+        !existingValue &&
+        globalConfig.user_mention
+      ) {
+        defaultValue = globalConfig.user_mention;
+      }
 
-  // Filter out empty/default values to keep overrides minimal
-  const overrides: SkillOverrides = {};
-  for (const [key, value] of Object.entries(answers)) {
-    const schema = configSchema[key];
-    // Only save if different from default
-    if (value !== schema.default && value !== '' && value !== false) {
-      overrides[key] = value as string | boolean | number;
+      if (
+        defaultValue !== '' &&
+        defaultValue !== undefined &&
+        defaultValue !== null
+      ) {
+        overrides[key] = defaultValue as string | boolean | number;
+      }
     }
   }
 
-  if (Object.keys(overrides).length > 0) {
-    saveSkillOverrides(skillName, overrides);
-    // Strip droid- prefix for display since that's where the file actually goes
-    const displayName = skillName.replace(/^droid-/, '');
-    console.log(chalk.green(`\n✓ Configuration saved to ~/.droid/skills/${displayName}/overrides.yaml`));
-  } else {
-    console.log(chalk.gray('\nNo custom configuration set (using defaults).'));
-  }
+  // Always save overrides.yaml when a skill has a config schema
+  // Skills expect this file to exist even if all values are defaults
+  saveSkillOverrides(skillName, overrides);
+  const displayName = skillName.replace(/^droid-/, '');
+  console.log(
+    chalk.green(
+      `\n✓ Configuration saved to ~/.droid/skills/${displayName}/overrides.yaml`,
+    ),
+  );
 }