@orderful/droid 0.25.2 → 0.26.0

package/dist/tools/tech-design/skills/droid-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.26.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/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`,
+    ),
+  );
 }

package/src/lib/skills.ts

@@ -25,7 +25,7 @@ import {
   isAgentInstalled,
 } from './agents';
 import { getSkillsPath, getCommandsPath, getConfigPath } from './platforms';
-import { loadToolManifest } from './tools';
+import { loadToolManifest, isToolInstalled } from './tools';
 import { runToolMigrations } from './migrations';
 
 // Marker comments for CLAUDE.md skill registration
@@ -414,7 +414,7 @@ export function installSkill(skillName: string): {
   // Check dependencies
   if (manifest.dependencies) {
     for (const dep of manifest.dependencies) {
-      if (!isSkillInstalled(dep)) {
+      if (!isToolInstalled(dep)) {
         return {
           success: false,
           message: `Missing dependency: '${dep}'. Install it first with \`droid install ${dep}\``,

package/src/tools/README.md

@@ -57,7 +57,7 @@ description: "What this skill does"
 globs:
   - "**/*.ts"                   # File patterns this skill applies to
 alwaysApply: false              # Always include in context?
-allowed-tools: Read, Grep, Glob # Pre-authorize tools (reduces permission prompts)
+allowed-tools: [Read, Grep, Glob]  # Pre-authorize tools (reduces permission prompts)
 ---
 
 # My Skill

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

@@ -0,0 +1,16 @@
+{
+  "name": "droid-brain",
+  "version": "0.2.3",
+  "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",
+    "url": "https://github.com/orderful"
+  },
+  "repository": "https://github.com/orderful/droid",
+  "license": "MIT",
+  "keywords": [
+    "droid",
+    "ai",
+    "brain"
+  ]
+}

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

@@ -1,7 +1,7 @@
 ---
 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:*)
+allowed-tools: [Read, Write, Edit, Glob, Grep, Bash(mkdir:*), Bash(ls:*)]
 ---
 
 # /brain

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

@@ -1,7 +1,7 @@
 ---
 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:*)
+allowed-tools: [Read, Write, Edit, Glob, Grep, Bash(mkdir:*), Bash(ls:*)]
 ---
 
 # /scratchpad

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

@@ -4,7 +4,7 @@ description: "Collaborative scratchpad for planning and research. Use when plann
 globs:
   - "**/brain/**/*.md"
 alwaysApply: false
-allowed-tools: Read, Write, Glob, Grep, Bash
+allowed-tools: [Read, Write, Glob, Grep, Bash]
 ---
 
 # Brain Skill

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

@@ -4,7 +4,7 @@ description: "Obsidian extension for brain skill with YAML frontmatter, wikilink
 globs:
   - "**/brain/**/*.md"
 alwaysApply: false
-allowed-tools: Read, Write, Glob, Grep, Bash
+allowed-tools: [Read, Write, Glob, Grep, Bash]
 ---
 
 # Brain Obsidian Extension

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

@@ -0,0 +1,16 @@
+{
+  "name": "droid-coach",
+  "version": "0.1.3",
+  "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",
+    "url": "https://github.com/orderful"
+  },
+  "repository": "https://github.com/orderful/droid",
+  "license": "MIT",
+  "keywords": [
+    "droid",
+    "ai",
+    "coach"
+  ]
+}

package/src/tools/coach/commands/coach.md

@@ -1,7 +1,7 @@
 ---
 description: "Learning-mode AI assistance - scaffolds don't implement, questions don't fix"
 argument-hint: "[plan {task} | scaffold [{path}] | review [{path}] | check | challenge [{path}]]"
-allowed-tools: Read, Write, Edit, Glob, Grep, Bash(ls:*)
+allowed-tools: [Read, Write, Edit, Glob, Grep, Bash(ls:*)]
 ---
 
 # /coach

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

@@ -2,7 +2,7 @@
 name: droid-coach
 description: "Learning-mode AI assistance - scaffolds don't implement, questions don't fix. Use when learning a new codebase, wanting to understand deeply, or building skills to retain. User prompts like 'coach me on', 'help me think through', 'I want to learn how to', 'don't just give me the answer'."
 alwaysApply: false
-allowed-tools: Read, Grep, Glob
+allowed-tools: [Read, Grep, Glob]
 ---
 
 # Coach Skill

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

@@ -0,0 +1,16 @@
+{
+  "name": "droid-code-review",
+  "version": "0.1.2",
+  "description": "Comprehensive code review using specialized agents. Reviews PRs, staged changes, branches, or specific files with confidence scoring.",
+  "author": {
+    "name": "Orderful",
+    "url": "https://github.com/orderful"
+  },
+  "repository": "https://github.com/orderful/droid",
+  "license": "MIT",
+  "keywords": [
+    "droid",
+    "ai",
+    "code-review"
+  ]
+}

package/src/tools/code-review/commands/code-review.md

@@ -1,7 +1,7 @@
 ---
 description: Run comprehensive code review using specialized agents. Accepts PR number, 'staged', 'branch', or file path.
 argument-hint: "[#123 | staged | branch | path/to/file.ts]"
-allowed-tools: Task, Bash(git:*), Bash(gh:*), Read, Glob
+allowed-tools: [Task, Bash(git:*), Bash(gh:*), Read, Glob]
 ---
 
 # /code-review - Run comprehensive code review using specialized agents

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

@@ -4,7 +4,7 @@ description: "Comprehensive code review using specialized agents. Use when revie
 globs:
   - "**/*"
 alwaysApply: false
-allowed-tools: Read, Grep, Glob, Bash, Task
+allowed-tools: [Read, Grep, Glob, Bash, Task]
 ---
 
 # Code Review Skill

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

@@ -0,0 +1,16 @@
+{
+  "name": "droid-codex",
+  "version": "0.1.5",
+  "description": "Shared organizational knowledge - PRDs, tech designs, domains, proposals, patterns, and explored topics. Use when loading project context, searching codex, capturing decisions, or creating new entries.",
+  "author": {
+    "name": "Orderful",
+    "url": "https://github.com/orderful"
+  },
+  "repository": "https://github.com/orderful/droid",
+  "license": "MIT",
+  "keywords": [
+    "droid",
+    "ai",
+    "codex"
+  ]
+}