@orderful/droid 0.13.0 → 0.15.0

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

@@ -2,6 +2,7 @@
 name: coach
 description: "Learning-mode AI assistance - AI as coach, not crutch. Triggers on phrases like 'help me think through', 'coach me on', 'I want to learn how to', or 'don't just give me the answer'. Use /coach plan for co-authored planning, /coach scaffold for structure with hints, /coach review for Socratic questions on your code."
 alwaysApply: false
+allowed-tools: Read, Grep, Glob
 ---
 
 # Coach Skill

package/{src/tools/code-review/agents/edi-standards-reviewer/AGENT.md → dist/tools/code-review/agents/edi-standards-reviewer.md}

@@ -1,3 +1,13 @@
+---
+name: edi-standards-reviewer
+description: "Review code for EDI integration patterns, partnership handling, and billing system concerns. Use PROACTIVELY when changes touch trading partners, transactions, or billing."
+tools:
+  - Read
+  - Grep
+  - Glob
+color: blue
+---
+
 You are a domain-aware code reviewer that understands EDI patterns and integration best practices.
 
 ## How to Review

package/dist/tools/code-review/agents/{error-handling-reviewer/AGENT.md → error-handling-reviewer.md}

@@ -1,3 +1,13 @@
+---
+name: error-handling-reviewer
+description: "Hunt for silent failures and missing error handling. Use PROACTIVELY to find try/catch blocks that swallow errors, promises without rejection handling, and missing validation."
+tools:
+  - Read
+  - Grep
+  - Glob
+color: orange
+---
+
 You are a reliability engineer hunting for silent failures.
 
 ## Silent Failure Patterns

package/{src/tools/code-review/agents/test-coverage-analyzer/AGENT.md → dist/tools/code-review/agents/test-coverage-analyzer.md}

@@ -1,3 +1,14 @@
+---
+name: test-coverage-analyzer
+description: "Analyze test coverage for code changes. Use PROACTIVELY when reviewing PRs or before merging to ensure adequate test coverage."
+tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+color: green
+---
+
 You are a testing specialist focused on comprehensive coverage.
 
 ## Review Process

package/dist/tools/code-review/agents/{type-reviewer/AGENT.md → type-reviewer.md}

@@ -1,3 +1,13 @@
+---
+name: type-reviewer
+description: "Review TypeScript type design and interface contracts. Check for proper typing, avoid `any`, ensure domain types are used correctly."
+tools:
+  - Read
+  - Grep
+  - Glob
+color: purple
+---
+
 You are a TypeScript expert focused on type safety and design.
 
 ## Review Focus

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

@@ -4,6 +4,7 @@ description: "Comprehensive code review using specialized agents. Reviews PRs, s
 globs:
   - "**/*"
 alwaysApply: false
+allowed-tools: Read, Grep, Glob, Bash, Task
 ---
 
 # Code Review Skill

package/dist/tools/comments/TOOL.yaml

@@ -1,5 +1,5 @@
 name: comments
-description: "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."
+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.3
 status: beta
 
@@ -19,7 +19,7 @@ config_schema:
     description: Override the global user mention for this skill
   ai_mentions:
     type: string
-    description: Additional AI mentions to recognize (comma-separated)
+    description: Additional AI mentions to recognize (comma-separated, e.g., "@claude,@ai")
     default: ""
   preserve_comments:
     type: boolean

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

@@ -4,6 +4,7 @@ description: "Enable inline conversations using @droid/@user markers. Tag @droid
 globs:
   - "**/*"
 alwaysApply: false
+allowed-tools: Read, Grep, Glob, Edit
 ---
 
 # Comments Skill

package/dist/tools/droid/TOOL.yaml

@@ -1,6 +1,6 @@
 name: droid
-description: "Core droid meta-skill for update awareness and discovery. Notifies about droid updates from within Claude Code."
-version: 0.1.0
+description: "Core droid meta-skill for update awareness and tool discovery. Checks for updates and helps users find the right tools."
+version: 0.2.0
 status: beta
 
 # System tool - always stays current regardless of auto-update settings

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

@@ -1,18 +1,20 @@
 ---
 name: droid
-description: "Core droid meta-skill for update awareness. Checks for droid updates and notifies users from within Claude Code."
+description: "Core droid meta-skill for update awareness and tool discovery. Checks for updates and helps users find the right tools."
 globs:
   - "**/*"
 alwaysApply: false
+allowed-tools: Bash
 ---
 
 # Droid
 
-Core meta-skill for droid update awareness.
+Core meta-skill for droid update awareness and tool discovery.
 
 ## Purpose
 
-Notify users about droid CLI updates from within Claude Code. Users who don't run `droid` often may miss updates - this skill proactively nudges them.
+1. **Update awareness** - Notify users about droid CLI updates from within Claude Code
+2. **Tool discovery** - Help users find the right tools for their workflow
 
 ## Update Checking
 
@@ -115,3 +117,118 @@ Run `droid` when you're ready to update.
 - If the npm check fails (network issues), silently skip - don't error
 - The droid eyes `[● ●]` and Star Wars quote are intentional branding - always include them
 - Be helpful but not annoying - one nudge per session is enough
+
+---
+
+## Tool Catalog
+
+When users ask about droid tools ("what tools do I have?", "what's available?", "what can droid do?"), use this catalog.
+
+### Checking Installed Tools
+
+```bash
+cat ~/.droid/config.yaml
+```
+
+Look for the `tools:` section under the current platform (e.g., `claude_code:`).
+
+### Available Tools
+
+To get tool info (version, status, description), read TOOL.yaml from the droid package:
+
+```bash
+for f in $(npm root -g)/@orderful/droid/dist/tools/*/TOOL.yaml; do echo "---"; cat "$f"; done
+```
+
+**Tools:**
+
+| Tool | Description |
+|------|-------------|
+| **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 |
+| **comments** | Inline conversations using @droid/@user markers |
+| **project** | Project context for persistent AI memory across sessions |
+
+### Tool Details
+
+#### brain
+Collaborative scratchpad for planning and research. Create docs with `/brain plan`, `/brain research`, or `/brain review`. Use @mentions for async discussion. Docs persist across sessions.
+
+**Commands:** `/brain`, `/scratchpad`
+**Optional extension:** brain-obsidian (Obsidian vault integration with YAML frontmatter and wikilinks)
+
+#### coach
+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.
+
+**Commands:** `/coach`
+**Requires:** comments tool
+
+#### code-review
+Comprehensive code review using specialized agents. Reviews PRs, staged changes, branches, or specific files with confidence scoring.
+
+**Commands:** `/code-review`
+**Agents:** edi-standards-reviewer, error-handling-reviewer, test-coverage-analyzer, type-reviewer
+
+#### 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.
+
+**Commands:** `/comments check`, `/comments cleanup`
+
+#### project
+Manage project context files for persistent AI memory across sessions. Load, update, or create project context before working on multi-session features.
+
+**Commands:** `/project`, `/project update`, `/project create`
+
+### Installing Tools
+
+To install a tool:
+```bash
+droid install <tool-name>
+```
+
+Or run `droid` to open the TUI and browse available tools.
+
+### Example Responses
+
+**User:** "What droid tools do I have installed?"
+
+```
+Let me check your installed tools...
+
+[● ●] You have these droid tools installed:
+
+- **comments** (v0.2.3) - Inline @droid/@user conversations
+- **brain** (v0.2.0) - Planning and research scratchpad
+- **project** (v0.1.2) - Project context management
+
+Run `droid` to see all available tools or install new ones.
+```
+
+**User:** "What tools are available?"
+
+```
+[● ●] Here are the droid tools you can install:
+
+| Tool | What it does |
+|------|--------------|
+| 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 |
+| comments | Inline @droid/@user conversations in any file |
+| project | Persistent project context across sessions |
+
+Run `droid install <tool>` or just `droid` to browse and install.
+```
+
+**User:** "What's the difference between brain and project?"
+
+```
+[● ●] Good question!
+
+**brain** - For ephemeral thinking: plans, research, reviews. Use `/brain plan auth-refactor` to start a planning doc, iterate with @mentions, then archive when done.
+
+**project** - For persistent context: what the project is, key decisions, current work. Load with `/project myapp` at the start of a session so I have context.
+
+They work well together: research in brain docs, capture decisions in project files.
+```

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

@@ -4,6 +4,7 @@ description: "Manage project context files for persistent AI memory across sessi
 globs:
   - "**/PROJECT.md"
 alwaysApply: false
+allowed-tools: Read, Write, Glob, Grep
 ---
 
 # Project Skill

package/package.json

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

package/src/bin/droid.ts

@@ -8,7 +8,7 @@ import { installCommand } from '../commands/install.js';
 import { uninstallCommand } from '../commands/uninstall.js';
 import { updateCommand } from '../commands/update.js';
 import { tuiCommand } from '../commands/tui.js';
-import { getVersion, checkForUpdates } from '../lib/version.js';
+import { getVersion } from '../lib/version.js';
 
 const version = getVersion();
 
@@ -58,9 +58,6 @@ program
   .description('Launch interactive TUI dashboard')
   .action(tuiCommand);
 
-// Check for updates on any command (non-blocking)
-checkForUpdates().catch(() => {});
-
 // If no command provided, launch TUI
 if (process.argv.length === 2) {
   tuiCommand();

package/src/commands/tui.tsx

@@ -911,12 +911,11 @@ function ToolExplorer({ tool, onViewSource, onClose }: ToolExplorerProps) {
       });
     }
 
-    // Add agents
     for (const agent of tool.includes.agents) {
       result.push({
         type: 'agent',
         name: agent,
-        path: join(toolDir, tool.name, 'agents', agent, 'AGENT.md'),
+        path: join(toolDir, tool.name, 'agents', `${agent}.md`),
       });
     }
 

package/src/lib/agents.ts

@@ -5,6 +5,7 @@ import YAML from 'yaml';
 import { loadConfig } from './config.js';
 import { Platform } from './types.js';
 import { getAgentsPath } from './platforms.js';
+import { loadToolManifest } from './tools.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const BUNDLED_TOOLS_DIR = join(__dirname, '../tools');
@@ -33,23 +34,58 @@ export interface AgentManifest {
 }
 
 /**
- * Load an agent manifest from an agent directory
+ * Parse YAML frontmatter from agent file content
  */
-export function loadAgentManifest(agentDir: string): AgentManifest | null {
-  const manifestPath = join(agentDir, 'AGENT.yaml');
-
-  if (!existsSync(manifestPath)) {
+function parseAgentFrontmatter(content: string): Record<string, unknown> | null {
+  const trimmed = content.trimStart();
+  if (!trimmed.startsWith('---')) {
     return null;
   }
-
+  const endMatch = trimmed.slice(3).indexOf('---');
+  if (endMatch === -1) {
+    return null;
+  }
+  const frontmatterContent = trimmed.slice(3, 3 + endMatch);
   try {
-    const content = readFileSync(manifestPath, 'utf-8');
-    return YAML.parse(content) as AgentManifest;
+    return YAML.parse(frontmatterContent);
   } catch {
     return null;
   }
 }
 
+/**
+ * Load an agent manifest from an agent file (agents/{name}.md)
+ * Reads frontmatter from the .md file, version from TOOL.yaml
+ */
+export function loadAgentManifest(agentPath: string): AgentManifest | null {
+  if (!existsSync(agentPath)) {
+    return null;
+  }
+
+  const content = readFileSync(agentPath, 'utf-8');
+  const frontmatter = parseAgentFrontmatter(content);
+
+  if (!frontmatter || !frontmatter.name) {
+    return null;
+  }
+
+  // Get version from TOOL.yaml
+  // agentPath is tools/{tool}/agents/{name}.md, toolDir is tools/{tool}
+  const toolDir = dirname(dirname(agentPath));
+  const toolManifest = loadToolManifest(toolDir);
+
+  return {
+    name: frontmatter.name as string,
+    description: frontmatter.description as string || '',
+    version: toolManifest?.version || '0.0.0',
+    status: toolManifest?.status as 'alpha' | 'beta' | 'stable' | undefined,
+    mode: frontmatter.mode as 'primary' | 'subagent' | 'all' | undefined,
+    model: frontmatter.model as string | undefined,
+    color: frontmatter.color as string | undefined,
+    tools: frontmatter.tools as string[] | undefined,
+  };
+}
+
 /**
  * Get all bundled agents from tools
  */
@@ -61,7 +97,7 @@ export function getBundledAgents(): AgentManifest[] {
     return agents;
   }
 
-  // Get agents from tools/*/agents/
+  // Get agents from tools/*/agents/*.md
   const toolDirs = readdirSync(BUNDLED_TOOLS_DIR, { withFileTypes: true })
     .filter((dirent) => dirent.isDirectory())
     .map((dirent) => dirent.name);
@@ -70,12 +106,12 @@ export function getBundledAgents(): AgentManifest[] {
     const toolAgentsDir = join(BUNDLED_TOOLS_DIR, toolName, 'agents');
     if (!existsSync(toolAgentsDir)) continue;
 
-    const agentDirs = readdirSync(toolAgentsDir, { withFileTypes: true })
-      .filter((dirent) => dirent.isDirectory())
+    const agentFiles = readdirSync(toolAgentsDir, { withFileTypes: true })
+      .filter((dirent) => dirent.isFile() && dirent.name.endsWith('.md'))
       .map((dirent) => dirent.name);
 
-    for (const agentDir of agentDirs) {
-      const manifest = loadAgentManifest(join(toolAgentsDir, agentDir));
+    for (const agentFile of agentFiles) {
+      const manifest = loadAgentManifest(join(toolAgentsDir, agentFile));
       if (manifest && !seenNames.has(manifest.name)) {
         agents.push(manifest);
         seenNames.add(manifest.name);
@@ -166,35 +202,23 @@ function generateOpenCodeAgent(manifest: AgentManifest, agentContent: string): s
 }
 
 /**
- * Install an agent from a specific path
+ * Install an agent from a specific path (agents/{name}.md)
  * Generates the appropriate format based on the configured AI tool
  */
-export function installAgentFromPath(agentDir: string, agentName: string): { success: boolean; message: string } {
+export function installAgentFromPath(agentPath: string, agentName: string): { success: boolean; message: string } {
   const config = loadConfig();
-  const manifestPath = join(agentDir, 'AGENT.yaml');
-  const contentPath = join(agentDir, 'AGENT.md');
 
-  if (!existsSync(manifestPath)) {
+  // Load manifest from agent file frontmatter
+  const manifest = loadAgentManifest(agentPath);
+  if (!manifest) {
     return { success: false, message: `Agent manifest not found: ${agentName}` };
   }
 
   try {
-    // Load manifest
-    const manifest = YAML.parse(readFileSync(manifestPath, 'utf-8')) as AgentManifest;
-
-    // Load content (AGENT.md)
-    let agentContent = '';
-    if (existsSync(contentPath)) {
-      const rawContent = readFileSync(contentPath, 'utf-8');
-      // Strip frontmatter from AGENT.md if present (we'll use AGENT.yaml for metadata)
-      const frontmatterMatch = rawContent.match(/^---\n[\s\S]*?\n---\n?/);
-      agentContent = frontmatterMatch ? rawContent.slice(frontmatterMatch[0].length) : rawContent;
-    }
-
-    // If no AGENT.md content, use persona from AGENT.yaml
-    if (!agentContent.trim() && manifest.persona) {
-      agentContent = manifest.persona;
-    }
+    // Load content (strip frontmatter)
+    const rawContent = readFileSync(agentPath, 'utf-8');
+    const frontmatterMatch = rawContent.match(/^---\n[\s\S]*?\n---\n?/);
+    const agentContent = frontmatterMatch ? rawContent.slice(frontmatterMatch[0].length) : rawContent;
 
     // Generate format based on platform
     const installedContent = config.platform === Platform.ClaudeCode
@@ -222,7 +246,7 @@ export function installAgentFromPath(agentDir: string, agentName: string): { suc
 }
 
 /**
- * Find the path to an agent within the tools directory structure
+ * Find the path to an agent file within the tools directory structure
  */
 export function findAgentPath(agentName: string): string | null {
   if (!existsSync(BUNDLED_TOOLS_DIR)) {
@@ -234,9 +258,9 @@ export function findAgentPath(agentName: string): string | null {
     .map((dirent) => dirent.name);
 
   for (const toolName of toolDirs) {
-    const agentDir = join(BUNDLED_TOOLS_DIR, toolName, 'agents', agentName);
-    if (existsSync(agentDir) && existsSync(join(agentDir, 'AGENT.yaml'))) {
-      return agentDir;
+    const agentPath = join(BUNDLED_TOOLS_DIR, toolName, 'agents', `${agentName}.md`);
+    if (existsSync(agentPath)) {
+      return agentPath;
     }
   }
 
@@ -245,14 +269,13 @@ export function findAgentPath(agentName: string): string | null {
 
 /**
  * Install an agent from the tools directory
- * Combines AGENT.yaml metadata with AGENT.md content into a single .md file
  */
 export function installAgent(agentName: string): { success: boolean; message: string } {
-  const agentDir = findAgentPath(agentName);
-  if (!agentDir) {
+  const agentPath = findAgentPath(agentName);
+  if (!agentPath) {
     return { success: false, message: `Agent '${agentName}' not found` };
   }
-  return installAgentFromPath(agentDir, agentName);
+  return installAgentFromPath(agentPath, agentName);
 }
 
 /**

package/src/lib/skills.test.ts

@@ -11,6 +11,7 @@ import {
   getPlatformConfigPath,
   getSkillStatusDisplay,
   getBundledSkillsDir,
+  loadSkillManifest,
 } from './skills.js';
 
 /**
@@ -180,58 +181,52 @@ function getAllSkillPaths(toolsDir: string): Array<{ skillName: string; skillDir
 }
 
 describe('bundled skills validation', () => {
-  it('all skills should have SKILL.md with valid frontmatter', () => {
+  it('all skills should have SKILL.md', () => {
     const toolsDir = getBundledSkillsDir();
     const skillPaths = getAllSkillPaths(toolsDir);
 
     expect(skillPaths.length).toBeGreaterThan(0);
 
-    for (const { skillName, skillDir } of skillPaths) {
+    for (const { skillDir } of skillPaths) {
       const skillMdPath = join(skillDir, 'SKILL.md');
       expect(existsSync(skillMdPath)).toBe(true);
-
-      const content = readFileSync(skillMdPath, 'utf-8');
-      const frontmatter = parseFrontmatter(content);
-
-      expect(frontmatter).not.toBeNull();
-      expect(frontmatter?.name).toBe(skillName);
-      expect(typeof frontmatter?.description).toBe('string');
     }
   });
 
-  it('all skills should have SKILL.yaml manifest', () => {
+  it('all skills should have metadata in TOOL.yaml', () => {
     const toolsDir = getBundledSkillsDir();
     const skillPaths = getAllSkillPaths(toolsDir);
 
     for (const { skillName, skillDir } of skillPaths) {
-      const yamlPath = join(skillDir, 'SKILL.yaml');
-      expect(existsSync(yamlPath)).toBe(true);
-
-      const content = readFileSync(yamlPath, 'utf-8');
-      const manifest = YAML.parse(content);
-
-      expect(manifest.name).toBe(skillName);
-      expect(typeof manifest.description).toBe('string');
-      expect(typeof manifest.version).toBe('string');
+      // Get the parent tool directory
+      const toolDir = join(skillDir, '..', '..');
+      const toolYamlPath = join(toolDir, 'TOOL.yaml');
+      expect(existsSync(toolYamlPath)).toBe(true);
+
+      const toolContent = readFileSync(toolYamlPath, 'utf-8');
+      const toolManifest = YAML.parse(toolContent);
+
+      // Find the skill in includes.skills
+      const skillInclude = toolManifest.includes?.skills?.find(
+        (s: { name: string }) => s.name === skillName
+      );
+      expect(skillInclude).toBeDefined();
+      expect(typeof toolManifest.description).toBe('string');
+      expect(typeof toolManifest.version).toBe('string');
     }
   });
 
-  it('SKILL.md frontmatter should match SKILL.yaml', () => {
+  it('loadSkillManifest should return valid manifest from TOOL.yaml', () => {
     const toolsDir = getBundledSkillsDir();
     const skillPaths = getAllSkillPaths(toolsDir);
 
-    for (const { skillDir } of skillPaths) {
-      const mdPath = join(skillDir, 'SKILL.md');
-      const yamlPath = join(skillDir, 'SKILL.yaml');
-
-      const mdContent = readFileSync(mdPath, 'utf-8');
-      const yamlContent = readFileSync(yamlPath, 'utf-8');
-
-      const frontmatter = parseFrontmatter(mdContent);
-      const manifest = YAML.parse(yamlContent);
+    for (const { skillName, skillDir } of skillPaths) {
+      const manifest = loadSkillManifest(skillDir);
 
-      expect(frontmatter?.name).toBe(manifest.name);
-      expect(frontmatter?.description).toBe(manifest.description);
+      expect(manifest).not.toBeNull();
+      expect(manifest?.name).toBe(skillName);
+      expect(typeof manifest?.description).toBe('string');
+      expect(typeof manifest?.version).toBe('string');
     }
   });
 });