@orderful/droid 0.18.0 → 0.20.0

package/dist/tools/codex/skills/droid-codex/references/topics.md

@@ -0,0 +1,213 @@
+# Adding Topics
+
+Detailed procedure for capturing explored codebase areas as institutional knowledge.
+
+## When to Use
+
+- After a deep exploration of a codebase area
+- User asks to save/capture exploration
+- `/codex add topic {name}` command
+- Converting ad-hoc research into persistent knowledge
+
+## The Value
+
+Topics turn ephemeral exploration into institutional memory:
+- Next time someone needs to understand this area, context is ready
+- AI can load it instantly instead of re-exploring
+- Freshness tracking ensures it stays current
+
+## Procedure
+
+### 1. Determine Topic Name
+
+From user input or infer from exploration:
+- Use kebab-case: `organization-hierarchy`, `webhook-processing`
+- Be specific but concise
+
+### 2. Gather Content
+
+From the current conversation/exploration, extract:
+- **Overview:** What is this area of the codebase?
+- **Key Concepts:** Important terms, patterns, relationships
+- **Architecture:** How components fit together
+- **Key Files:** Important files and their purposes
+- **Common Patterns:** Recurring patterns in this area
+- **Gotchas:** Things to watch out for
+
+### 3. Determine Metadata
+
+Ask user or infer:
+- **Confidence:** How thorough was the exploration?
+  - `high` - Comprehensive, covered most aspects
+  - `medium` - Good coverage but may have gaps
+  - `low` - Quick exploration, definitely incomplete
+- **Codebase paths:** Which directories/files were explored?
+
+### 4. Read Template
+
+```bash
+cat {codex_repo}/templates/TOPIC.md
+```
+
+### 5. Create Topic File
+
+```bash
+# Create the file
+touch {codex_repo}/topics/{name}.md
+```
+
+Fill in content:
+
+```markdown
+---
+title: {Topic Title}
+type: topic
+created: {today}
+updated: {today}
+confidence: {high|medium|low}
+source: exploration
+codebase_paths:
+  - {path/explored/1}
+  - {path/explored/2}
+---
+
+# {Topic Title}
+
+## Overview
+
+{Brief description of this area of the codebase}
+
+## Key Concepts
+
+### {Concept 1}
+
+{Explanation}
+
+### {Concept 2}
+
+{Explanation}
+
+## Architecture
+
+{How components fit together}
+
+```
+{Diagram or structure if helpful}
+```
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `{path/to/file}` | {What it does} |
+
+## Common Patterns
+
+{Patterns used in this area}
+
+## Gotchas
+
+- {Thing to watch out for}
+- {Another gotcha}
+
+## Related
+
+- {Links to related topics, PRDs, or external docs}
+```
+
+### 6. Create Branch and PR
+
+```bash
+cd {codex_repo}
+git checkout -b codex/topic-{name}
+git add topics/{name}.md
+git commit -F - <<EOF
+topic: add {name}
+EOF
+git push -u origin codex/topic-{name}
+gh pr create --title "Topic: {name}" --body "New topic from codebase exploration"
+```
+
+### 7. Confirm to User
+
+```
+✅ Added topic: {name}
+
+📚 {codex_repo}/topics/{name}.md
+Confidence: {confidence}
+Paths covered: {codebase_paths}
+
+PR: {pr_url}
+(Auto-merges for new files)
+
+Next time someone asks about {topic}, I can load this context instantly.
+```
+
+## Example
+
+**User:** (after exploring organization hierarchy) `/codex add topic organization-hierarchy`
+
+**Result:**
+
+```markdown
+---
+title: Organization Hierarchy
+type: topic
+created: 2026-01-07
+updated: 2026-01-07
+confidence: high
+source: exploration
+codebase_paths:
+  - apps/platform-api/src/modules/organization/
+  - libs/shared/src/types/organization.ts
+---
+
+# Organization Hierarchy
+
+## Overview
+
+Orderful's multi-tenant organization structure with parent-child relationships, enabling enterprise customers to manage multiple business units under a single account.
+
+## Key Concepts
+
+### Organization
+
+The top-level entity. Has settings, billing, users.
+
+### Child Organizations
+
+Organizations can have children, creating a hierarchy. Children inherit some settings from parents.
+
+### Organization Context
+
+Request-scoped context determining which org's data to access.
+
+## Architecture
+
+```
+Organization (parent)
+├── Organization (child 1)
+│   └── Organization (grandchild)
+└── Organization (child 2)
+```
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `organization.entity.ts` | TypeORM entity with parent/child relations |
+| `organization.service.ts` | Business logic for org operations |
+| `organization-context.middleware.ts` | Sets org context from request |
+
+## Common Patterns
+
+- Always check org context before data access
+- Use `organizationId` foreign key on tenant-scoped entities
+- Hierarchy queries use recursive CTEs
+
+## Gotchas
+
+- Child orgs don't automatically inherit all parent settings
+- Deleting a parent doesn't cascade to children (soft delete)
+- API keys are scoped to single org, not hierarchy
+```

package/dist/tools/comments/TOOL.yaml

@@ -1,6 +1,6 @@
 name: comments
 description: "Enable inline conversations using @droid/@user markers. Tag @droid to ask the AI, AI responds with @{your-name}. Use /comments check to address markers, /comments cleanup to remove resolved threads. Ideal for code review notes and async collaboration."
-version: 0.2.5
+version: 0.2.6
 status: beta
 
 includes:

package/dist/tools/droid/skills/droid/SKILL.md

@@ -147,6 +147,7 @@ for f in $(npm root -g)/@orderful/droid/dist/tools/*/TOOL.yaml; do echo "---"; c
 | **brain** | Collaborative scratchpad for planning and research |
 | **coach** | Learning-mode AI - scaffolds don't implement, questions don't fix |
 | **code-review** | Code review with specialized agents and confidence scoring |
+| **codex** | Shared organizational knowledge - PRDs, tech designs, patterns, topics |
 | **comments** | Inline conversations using @droid/@user markers |
 | **project** | Project context for persistent AI memory across sessions |
 
@@ -170,6 +171,12 @@ Comprehensive code review using specialized agents. Reviews PRs, staged changes,
 **Commands:** `/code-review`
 **Agents:** edi-standards-reviewer, error-handling-reviewer, test-coverage-analyzer, type-reviewer
 
+#### codex
+Shared organizational knowledge - PRDs, tech designs, patterns, and explored topics. Load project context, search across the codex, capture decisions during implementation.
+
+**Commands:** `/codex`, `/codex projects`, `/codex search`, `/codex decision`, `/codex add topic`
+**Requires:** gh CLI, orderful-codex repo cloned locally
+
 #### comments
 Enable inline conversations using @droid/@user markers. Tag @droid to ask the AI, AI responds with @{your-name}. Ideal for code review notes and async collaboration.
 
@@ -215,6 +222,7 @@ Run `droid` to see all available tools or install new ones.
 | brain | Planning and research scratchpad with `/brain` commands |
 | coach | Learning-mode AI that asks questions instead of giving answers |
 | code-review | PR review with specialized agents |
+| codex | Shared knowledge - PRDs, tech designs, patterns, topics |
 | comments | Inline @droid/@user conversations in any file |
 | project | Persistent project context across sessions |
 

package/dist/tools/project/TOOL.yaml

@@ -1,6 +1,6 @@
 name: project
 description: "Manage project context files for persistent AI memory across sessions. Load, update, or create project context before working on multi-session features."
-version: 0.1.4
+version: 0.1.5
 status: beta
 
 includes:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orderful/droid",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "AI workflow toolkit for sharing skills, commands, and agents across the team",
   "type": "module",
   "bin": {

package/src/lib/config.ts

@@ -160,11 +160,21 @@ export function getConfigDir(): string {
   return CONFIG_DIR;
 }
 
+/**
+ * Normalize skill name for config paths.
+ * Strips 'droid-' prefix since that was added as a workaround for Claude Code bug.
+ * Config paths should stay intuitive (e.g., ~/.droid/skills/brain/ not ~/.droid/skills/droid-brain/)
+ */
+function normalizeSkillNameForConfig(skillName: string): string {
+  return skillName.replace(/^droid-/, '');
+}
+
 /**
  * Get skill-specific overrides path
  */
 export function getSkillOverridesPath(skillName: string): string {
-  return join(CONFIG_DIR, 'skills', skillName, 'overrides.yaml');
+  const normalizedName = normalizeSkillNameForConfig(skillName);
+  return join(CONFIG_DIR, 'skills', normalizedName, 'overrides.yaml');
 }
 
 /**
@@ -189,8 +199,9 @@ export function loadSkillOverrides(skillName: string): SkillOverrides {
  * Save skill-specific overrides
  */
 export function saveSkillOverrides(skillName: string, overrides: SkillOverrides): void {
+  const normalizedName = normalizeSkillNameForConfig(skillName);
   const overridesPath = getSkillOverridesPath(skillName);
-  const skillDir = join(CONFIG_DIR, 'skills', skillName);
+  const skillDir = join(CONFIG_DIR, 'skills', normalizedName);
 
   if (!existsSync(skillDir)) {
     mkdirSync(skillDir, { recursive: true });

package/src/lib/migrations.test.ts

@@ -0,0 +1,163 @@
+import { describe, it, expect, beforeEach, afterEach } from 'bun:test';
+import { existsSync, mkdirSync, rmSync, writeFileSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { getToolMigrations } from './migrations';
+
+describe('migrations', () => {
+  let testDir: string;
+
+  beforeEach(() => {
+    testDir = join(tmpdir(), `droid-migration-test-${Date.now()}`);
+    mkdirSync(testDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    if (existsSync(testDir)) {
+      rmSync(testDir, { recursive: true });
+    }
+  });
+
+  describe('getToolMigrations', () => {
+    it('should return migrations for known tools', () => {
+      const brainMigrations = getToolMigrations('brain');
+      expect(brainMigrations.length).toBeGreaterThan(0);
+      expect(brainMigrations[0].version).toBe('0.2.3');
+    });
+
+    it('should return empty array for unknown tools', () => {
+      const migrations = getToolMigrations('unknown-tool');
+      expect(migrations).toEqual([]);
+    });
+
+    it('should have migrations for all renamed tools', () => {
+      const tools = ['brain', 'comments', 'project', 'coach'];
+      for (const tool of tools) {
+        const migrations = getToolMigrations(tool);
+        expect(migrations.length).toBeGreaterThan(0);
+      }
+    });
+  });
+
+  describe('config directory migration', () => {
+    it('should move old prefixed directory to unprefixed', () => {
+      // Setup: create old prefixed directory with config
+      const skillsDir = join(testDir, 'skills');
+      const oldDir = join(skillsDir, 'droid-brain');
+      const newDir = join(skillsDir, 'brain');
+
+      mkdirSync(oldDir, { recursive: true });
+      writeFileSync(join(oldDir, 'overrides.yaml'), 'brain_dir: /test/path\n');
+
+      // Get the migration and run it
+      const migrations = getToolMigrations('brain');
+      const migration = migrations[0];
+      migration.up(testDir);
+
+      // Verify
+      expect(existsSync(oldDir)).toBe(false);
+      expect(existsSync(newDir)).toBe(true);
+      expect(readFileSync(join(newDir, 'overrides.yaml'), 'utf-8')).toBe('brain_dir: /test/path\n');
+    });
+
+    it('should be idempotent - no error if old directory already moved', () => {
+      // Setup: only new directory exists (already migrated)
+      const skillsDir = join(testDir, 'skills');
+      const newDir = join(skillsDir, 'brain');
+
+      mkdirSync(newDir, { recursive: true });
+      writeFileSync(join(newDir, 'overrides.yaml'), 'brain_dir: /test/path\n');
+
+      // Get the migration and run it - should not throw
+      const migrations = getToolMigrations('brain');
+      const migration = migrations[0];
+
+      expect(() => migration.up(testDir)).not.toThrow();
+      expect(existsSync(newDir)).toBe(true);
+    });
+
+    it('should handle collision by removing old directory', () => {
+      // Setup: both old and new directories exist
+      const skillsDir = join(testDir, 'skills');
+      const oldDir = join(skillsDir, 'droid-brain');
+      const newDir = join(skillsDir, 'brain');
+
+      mkdirSync(oldDir, { recursive: true });
+      mkdirSync(newDir, { recursive: true });
+      writeFileSync(join(oldDir, 'overrides.yaml'), 'old: true\n');
+      writeFileSync(join(newDir, 'overrides.yaml'), 'new: true\n');
+
+      // Run migration
+      const migrations = getToolMigrations('brain');
+      const migration = migrations[0];
+      migration.up(testDir);
+
+      // Old should be removed, new should be preserved
+      expect(existsSync(oldDir)).toBe(false);
+      expect(existsSync(newDir)).toBe(true);
+      expect(readFileSync(join(newDir, 'overrides.yaml'), 'utf-8')).toBe('new: true\n');
+    });
+
+    it('should do nothing if neither directory exists', () => {
+      // Setup: empty skills directory
+      const skillsDir = join(testDir, 'skills');
+      mkdirSync(skillsDir, { recursive: true });
+
+      // Run migration - should not throw
+      const migrations = getToolMigrations('brain');
+      const migration = migrations[0];
+
+      expect(() => migration.up(testDir)).not.toThrow();
+    });
+
+    it('should create parent directory if needed', () => {
+      // Setup: old directory exists but skills/ parent doesn't exist for new
+      const oldDir = join(testDir, 'skills', 'droid-brain');
+      mkdirSync(oldDir, { recursive: true });
+      writeFileSync(join(oldDir, 'overrides.yaml'), 'test: true\n');
+
+      // Run migration
+      const migrations = getToolMigrations('brain');
+      const migration = migrations[0];
+      migration.up(testDir);
+
+      // Should have moved successfully
+      const newDir = join(testDir, 'skills', 'brain');
+      expect(existsSync(newDir)).toBe(true);
+      expect(existsSync(oldDir)).toBe(false);
+    });
+  });
+
+  describe('migration versions', () => {
+    it('brain migration should be version 0.2.3', () => {
+      const migrations = getToolMigrations('brain');
+      expect(migrations[0].version).toBe('0.2.3');
+    });
+
+    it('comments migration should be version 0.2.6', () => {
+      const migrations = getToolMigrations('comments');
+      expect(migrations[0].version).toBe('0.2.6');
+    });
+
+    it('project migration should be version 0.1.5', () => {
+      const migrations = getToolMigrations('project');
+      expect(migrations[0].version).toBe('0.1.5');
+    });
+
+    it('coach migration should be version 0.1.3', () => {
+      const migrations = getToolMigrations('coach');
+      expect(migrations[0].version).toBe('0.1.3');
+    });
+  });
+
+  describe('migration descriptions', () => {
+    it('should have descriptive migration descriptions', () => {
+      const tools = ['brain', 'comments', 'project', 'coach'];
+      for (const tool of tools) {
+        const migrations = getToolMigrations(tool);
+        expect(migrations[0].description).toContain('config');
+        expect(migrations[0].description).toContain('unprefixed');
+      }
+    });
+  });
+});

package/src/lib/migrations.ts

@@ -0,0 +1,182 @@
+import { existsSync, appendFileSync, mkdirSync, renameSync, rmSync } from 'fs';
+import { join, dirname } from 'path';
+import { loadConfig, saveConfig, getConfigDir } from './config';
+import { type Migration } from './types';
+import { compareSemver } from './version';
+
+const MIGRATIONS_LOG_FILE = '.migrations.log';
+
+/**
+ * Get the path to the migrations log file
+ */
+function getMigrationsLogPath(): string {
+  return join(getConfigDir(), MIGRATIONS_LOG_FILE);
+}
+
+/**
+ * Log a migration event to the hidden log file
+ */
+function logMigration(
+  toolName: string,
+  fromVersion: string,
+  toVersion: string,
+  status: 'OK' | 'FAILED',
+  error?: string
+): void {
+  const timestamp = new Date().toISOString();
+  const logEntry = error
+    ? `${timestamp} ${toolName} ${fromVersion} → ${toVersion} ${status}: ${error}\n`
+    : `${timestamp} ${toolName} ${fromVersion} → ${toVersion} ${status}\n`;
+
+  const logPath = getMigrationsLogPath();
+  const logDir = dirname(logPath);
+
+  if (!existsSync(logDir)) {
+    mkdirSync(logDir, { recursive: true });
+  }
+
+  appendFileSync(logPath, logEntry);
+}
+
+// ============================================================================
+// Tool Migrations Registry
+// Define migrations here, keyed by tool name
+// ============================================================================
+
+/**
+ * Migration: Move droid-prefixed config directories to unprefixed names
+ * e.g., ~/.droid/skills/droid-brain/ → ~/.droid/skills/brain/
+ *
+ * This fixes a bug where config was saved to prefixed paths but SKILL.md
+ * tells Claude to read from unprefixed paths.
+ */
+function createConfigDirMigration(skillName: string, version: string): Migration {
+  const unprefixedName = skillName.replace(/^droid-/, '');
+  return {
+    version,
+    description: `Move ${skillName} config to unprefixed location`,
+    up: (configDir: string) => {
+      const oldDir = join(configDir, 'skills', skillName);
+      const newDir = join(configDir, 'skills', unprefixedName);
+
+      // Only migrate if old exists and new doesn't
+      if (existsSync(oldDir) && !existsSync(newDir)) {
+        // Ensure parent directory exists
+        const parentDir = dirname(newDir);
+        if (!existsSync(parentDir)) {
+          mkdirSync(parentDir, { recursive: true });
+        }
+        renameSync(oldDir, newDir);
+      } else if (existsSync(oldDir) && existsSync(newDir)) {
+        // Both exist - remove the old one (new takes precedence)
+        rmSync(oldDir, { recursive: true });
+      }
+    },
+  };
+}
+
+/**
+ * Registry of all tool migrations
+ * Key: tool name (e.g., "brain", "comments")
+ * Value: array of migrations sorted by version
+ *
+ * Migration versions are set to the next version after each tool's current version:
+ * - brain: 0.2.2 → 0.2.3
+ * - comments: 0.2.5 → 0.2.6
+ * - project: 0.1.4 → 0.1.5
+ * - coach: 0.1.2 → 0.1.3
+ */
+const TOOL_MIGRATIONS: Record<string, Migration[]> = {
+  brain: [createConfigDirMigration('droid-brain', '0.2.3')],
+  comments: [createConfigDirMigration('droid-comments', '0.2.6')],
+  project: [createConfigDirMigration('droid-project', '0.1.5')],
+  coach: [createConfigDirMigration('droid-coach', '0.1.3')],
+};
+
+/**
+ * Get migrations for a tool
+ */
+export function getToolMigrations(toolName: string): Migration[] {
+  return TOOL_MIGRATIONS[toolName] ?? [];
+}
+
+/**
+ * Get the last migrated version for a tool
+ */
+export function getLastMigratedVersion(toolName: string): string {
+  const config = loadConfig();
+  return config.migrations?.[toolName] ?? '0.0.0';
+}
+
+/**
+ * Update the last migrated version for a tool
+ */
+export function setLastMigratedVersion(toolName: string, version: string): void {
+  const config = loadConfig();
+  if (!config.migrations) {
+    config.migrations = {};
+  }
+  config.migrations[toolName] = version;
+  saveConfig(config);
+}
+
+/**
+ * Run migrations for a tool between two versions
+ * Returns true if all migrations succeeded, false otherwise
+ */
+export function runMigrations(
+  toolName: string,
+  fromVersion: string,
+  toVersion: string
+): { success: boolean; error?: string } {
+  const migrations = getToolMigrations(toolName);
+
+  // Filter migrations that need to run (version > fromVersion && version <= toVersion)
+  const pendingMigrations = migrations.filter((m) => {
+    const afterFrom = compareSemver(m.version, fromVersion) > 0;
+    const beforeOrAtTo = compareSemver(m.version, toVersion) <= 0;
+    return afterFrom && beforeOrAtTo;
+  });
+
+  if (pendingMigrations.length === 0) {
+    // No migrations to run, but still update the version marker
+    setLastMigratedVersion(toolName, toVersion);
+    return { success: true };
+  }
+
+  const configDir = getConfigDir();
+
+  for (const migration of pendingMigrations) {
+    try {
+      migration.up(configDir);
+      logMigration(toolName, fromVersion, migration.version, 'OK');
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      logMigration(toolName, fromVersion, migration.version, 'FAILED', errorMessage);
+      // Don't update version marker on failure - will retry next time
+      return { success: false, error: `Migration ${migration.version} failed: ${errorMessage}` };
+    }
+  }
+
+  // All migrations succeeded, update version marker
+  setLastMigratedVersion(toolName, toVersion);
+  return { success: true };
+}
+
+/**
+ * Run migrations for a tool after install/update
+ * Call this after installSkill() completes
+ */
+export function runToolMigrations(
+  toolName: string,
+  installedVersion: string
+): { success: boolean; error?: string } {
+  const lastMigrated = getLastMigratedVersion(toolName);
+
+  // Only run if the installed version is newer than last migrated
+  if (compareSemver(installedVersion, lastMigrated) <= 0) {
+    return { success: true };
+  }
+
+  return runMigrations(toolName, lastMigrated, installedVersion);
+}

package/src/lib/skill-config.ts

@@ -86,7 +86,9 @@ export async function promptForSkillConfig(
 
   if (Object.keys(overrides).length > 0) {
     saveSkillOverrides(skillName, overrides);
-    console.log(chalk.green(`\n✓ Configuration saved to ~/.droid/skills/${skillName}/overrides.yaml`));
+    // 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).'));
   }

package/src/lib/skills.ts

@@ -1,5 +1,5 @@
 import { existsSync, readdirSync, readFileSync, mkdirSync, writeFileSync, rmSync } from 'fs';
-import { join, dirname } from 'path';
+import { join, dirname, basename } from 'path';
 import { fileURLToPath } from 'url';
 import YAML from 'yaml';
 import { loadConfig, saveConfig } from './config';
@@ -7,6 +7,7 @@ import { Platform, SkillStatus, type SkillManifest, type InstalledSkill, getPlat
 import { getInstalledAgentsDir, installAgentFromPath, uninstallAgent, isAgentInstalled } from './agents';
 import { getSkillsPath, getCommandsPath, getConfigPath } from './platforms';
 import { loadToolManifest } from './tools';
+import { runToolMigrations } from './migrations';
 
 // Marker comments for CLAUDE.md skill registration
 const DROID_SKILLS_START = '<!-- droid-skills-start -->';
@@ -542,6 +543,14 @@ export function installSkill(skillName: string): { success: boolean; message: st
   const installedSkillNames = Object.keys(updatedTools);
   updatePlatformConfigSkills(config.platform, installedSkillNames);
 
+  // Run tool migrations (keyed by tool name, not skill name)
+  const toolName = basename(toolDir);
+  const migrationResult = runToolMigrations(toolName, manifest.version);
+  if (!migrationResult.success) {
+    // Log warning but don't fail the install - migration will retry next time
+    console.warn(`Warning: Migration failed for ${toolName}: ${migrationResult.error}`);
+  }
+
   return { success: true, message: `Installed ${skillName} v${manifest.version}` };
 }