@orderful/droid 0.13.0 → 0.15.0

package/src/lib/skills.ts

@@ -6,6 +6,7 @@ import { loadConfig, saveConfig } from './config.js';
 import { Platform, SkillStatus, type SkillManifest, type InstalledSkill, getPlatformTools, setPlatformTools } from './types.js';
 import { getInstalledAgentsDir, installAgentFromPath, uninstallAgent, isAgentInstalled } from './agents.js';
 import { getSkillsPath, getCommandsPath, getConfigPath } from './platforms.js';
+import { loadToolManifest } from './tools.js';
 
 // Marker comments for CLAUDE.md skill registration
 const DROID_SKILLS_START = '<!-- droid-skills-start -->';
@@ -84,22 +85,57 @@ export function updatePlatformConfigSkills(platform: Platform, installedSkills:
   writeFileSync(configPath, content, 'utf-8');
 }
 
+/**
+ * Parse YAML frontmatter from SKILL.md content
+ */
+function parseSkillFrontmatter(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 {
+    return YAML.parse(frontmatterContent);
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Load a skill manifest from a skill directory
+ * Reads frontmatter from SKILL.md, version from TOOL.yaml
  */
 export function loadSkillManifest(skillDir: string): SkillManifest | null {
-  const manifestPath = join(skillDir, 'SKILL.yaml');
+  const skillMdPath = join(skillDir, 'SKILL.md');
 
-  if (!existsSync(manifestPath)) {
+  // Read SKILL.md and parse frontmatter
+  if (!existsSync(skillMdPath)) {
     return null;
   }
 
-  try {
-    const content = readFileSync(manifestPath, 'utf-8');
-    return YAML.parse(content) as SkillManifest;
-  } catch {
+  const content = readFileSync(skillMdPath, 'utf-8');
+  const frontmatter = parseSkillFrontmatter(content);
+
+  if (!frontmatter || !frontmatter.name) {
     return null;
   }
+
+  // Get version and other tool-level info from TOOL.yaml
+  const toolDir = dirname(dirname(skillDir)); // skillDir is tools/{tool}/skills/{skill}, toolDir is tools/{tool}
+  const toolManifest = loadToolManifest(toolDir);
+
+  return {
+    name: frontmatter.name as string,
+    description: frontmatter.description as string || '',
+    version: toolManifest?.version || '0.0.0',
+    status: toolManifest?.status,
+    dependencies: toolManifest?.dependencies,
+    config_schema: toolManifest?.config_schema,
+  };
 }
 
 /**
@@ -120,7 +156,8 @@ export function findSkillPath(skillName: string): { toolDir: string; skillDir: s
     if (!existsSync(skillsDir)) continue;
 
     const skillDir = join(skillsDir, skillName);
-    if (existsSync(skillDir) && existsSync(join(skillDir, 'SKILL.yaml'))) {
+    // Check for SKILL.md (content file) - metadata now comes from TOOL.yaml
+    if (existsSync(skillDir) && existsSync(join(skillDir, 'SKILL.md'))) {
       return {
         toolDir: join(BUNDLED_SKILLS_DIR, toolName),
         skillDir,
@@ -385,7 +422,7 @@ export function installSkill(skillName: string): { success: boolean; message: st
     mkdirSync(skillsPath, { recursive: true });
   }
 
-  // Copy SKILL.md (the actual skill file for Claude Code / OpenCode)
+  // Copy SKILL.md (includes its own frontmatter)
   const skillMdSource = join(skillDir, 'SKILL.md');
   if (existsSync(skillMdSource)) {
     if (!existsSync(targetSkillDir)) {

package/src/lib/types.ts

@@ -127,6 +127,11 @@ export interface ToolSkillInclude {
   name: string;
   required: boolean;
   description?: string;
+  // Skill-specific metadata (injected as frontmatter on install)
+  globs?: string[];
+  alwaysApply?: boolean;
+  provides_output?: boolean;
+  examples?: SkillExample[];
 }
 
 export interface ToolIncludes {

package/src/tools/README.md

@@ -1,55 +1,63 @@
-# Contributing Skills
+# Contributing Tools
 
-Skills are reusable AI capabilities that can be installed into Claude Code or OpenCode.
+Tools are bundles of skills, commands, and agents that can be installed into Claude Code or OpenCode.
 
 ## Directory Structure
 
-Each skill is a directory containing:
-
 ```
-skills/
-└── my-skill/
-    ├── SKILL.yaml      # Required: Manifest with metadata
-    ├── SKILL.md        # Required: Instructions for the AI
-    └── commands/       # Optional: Slash commands
-        └── my-command.md
+tools/
+└── my-tool/
+    ├── TOOL.yaml              # Required: Tool manifest
+    ├── skills/
+    │   └── my-skill/
+    │       ├── SKILL.md       # Required: Skill instructions + frontmatter
+    │       └── references/    # Optional: Additional context files
+    ├── commands/
+    │   └── my-command.md      # Command instructions + frontmatter
+    └── agents/
+        └── my-agent.md        # Agent instructions + frontmatter
 ```
 
-## SKILL.yaml (Manifest)
+## TOOL.yaml (Manifest)
+
+The tool manifest defines what's included and tool-level metadata:
 
 ```yaml
-name: my-skill                          # Must match directory name
-description: Short description          # Shown in TUI and listings
-version: 1.0.0                          # Semver
-status: beta                            # alpha | beta | stable (optional)
-dependencies: []                        # Other skills required (optional)
-provides_output: false                  # Can this skill be an output target?
-
-# Configuration schema (optional)
-config_schema:
+name: my-tool
+description: "Short description shown in TUI"
+version: 1.0.0
+status: beta                    # alpha | beta | stable
+
+includes:
+  skills:
+    - name: my-skill
+      required: true            # Must be installed with tool
+  commands:
+    - my-command                # Just the name (no extension)
+  agents:
+    - my-agent                  # Just the name (no extension)
+
+dependencies: []                # Other tools required
+
+config_schema:                  # Optional configuration
   option_name:
-    type: string                        # string | boolean
+    type: string
     description: What this option does
-    default: "default value"            # Optional default
-
-# Examples shown in TUI (optional)
-examples:
-  - title: "Example name"
-    code: |
-      // Example code block
+    default: "default value"
 ```
 
-## SKILL.md (AI Instructions)
+## Skills
 
-The SKILL.md file contains instructions for the AI. It must have YAML frontmatter:
+Skills provide context and instructions to the AI. Create `skills/{name}/SKILL.md`:
 
 ```markdown
 ---
 name: my-skill
-description: Short description (must match SKILL.yaml)
+description: "What this skill does"
 globs:
-  - "**/*"                              # File patterns this skill applies to
-alwaysApply: false                      # Always include in context?
+  - "**/*.ts"                   # File patterns this skill applies to
+alwaysApply: false              # Always include in context?
+allowed-tools: Read, Grep, Glob # Pre-authorize tools (reduces permission prompts)
 ---
 
 # My Skill
@@ -57,29 +65,50 @@ alwaysApply: false                      # Always include in context?
 Instructions for the AI on how to use this skill...
 ```
 
-## Commands (Optional)
+Skills can have a `references/` subdirectory for additional context files.
 
-Commands are slash commands the user can invoke. Each is a markdown file:
+## Commands
 
+Commands are slash commands the user can invoke. Create `commands/{name}.md`:
+
+```markdown
+---
+name: my-command
+description: "What this command does"
+---
+
+Instructions for what to do when /my-command is invoked...
 ```
-commands/
-└── do-thing.md
-```
 
-The command file is just markdown instructions. The filename becomes the command name (`/do-thing`).
+## Agents
+
+Agents are specialized AI personas. Create `agents/{name}.md`:
+
+```markdown
+---
+name: my-agent
+description: "What this agent does"
+tools:
+  - Read
+  - Grep
+  - Glob
+color: purple                   # Display colour (Claude Code only)
+---
+
+You are a specialized agent that...
+```
 
-## Testing Your Skill
+## Testing Your Tool
 
-1. Run `npm run build` to compile
-2. Run `droid` to open the TUI
-3. Navigate to Skills tab
-4. Install your skill
-5. Test in Claude Code with `/your-command` or by referencing the skill
+1. Run `bun run build` to compile
+2. Run `bun run start` to open the TUI
+3. Navigate to your tool
+4. Install the tool
+5. Test in Claude Code
 
 ## Checklist
 
-- [ ] `SKILL.yaml` has all required fields (name, description, version)
-- [ ] `SKILL.md` has valid YAML frontmatter
-- [ ] Name in frontmatter matches directory name
-- [ ] Description matches between SKILL.yaml and SKILL.md
-- [ ] Tests pass: `bun test src/lib/skills.test.ts`
+- [ ] `TOOL.yaml` has all required fields (name, description, version, includes)
+- [ ] All .md files have valid YAML frontmatter with `name` and `description`
+- [ ] Names in frontmatter match the file/directory names
+- [ ] Tests pass: `bun test`

package/src/tools/brain/TOOL.yaml

@@ -1,5 +1,5 @@
 name: brain
-description: "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."
+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.0
 status: beta
 

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

@@ -4,6 +4,7 @@ description: "Your scratchpad (or brain) - a collaborative space for planning an
 globs:
   - "**/brain/**/*.md"
 alwaysApply: false
+allowed-tools: Read, Write, Glob, Grep, Bash
 ---
 
 # Brain Skill

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

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

package/src/tools/coach/TOOL.yaml

@@ -17,5 +17,5 @@ dependencies:
 config_schema:
   scaffold_verbosity:
     type: string
-    description: "How detailed scaffold hints should be: minimal, medium, detailed"
+    description: "How detailed scaffold hints should be: minimal (signatures only), medium (hints), detailed (pseudocode)"
     default: "medium"

package/src/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/{dist/tools/code-review/agents/edi-standards-reviewer/AGENT.md → src/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/src/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/{dist/tools/code-review/agents/test-coverage-analyzer/AGENT.md → src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/dist/tools/brain/skills/brain/SKILL.yaml

@@ -1,29 +0,0 @@
-name: brain
-description: "Your scratchpad (or brain) - a collaborative space for planning and research. Triggers on phrases like 'let's use our brain', 'open a scratchpad', or 'plan this out' to capture AI output into a persistent doc. Create docs with /brain plan (or /scratchpad plan), /brain research, or /brain review. Use @mentions for async discussion. Docs persist across sessions."
-version: 0.2.0
-status: beta
-dependencies: []
-provides_output: false
-command_aliases:
-  scratchpad: brain
-config_schema:
-  brain_dir:
-    type: string
-    description: Directory for brain docs (default varies by AI tool)
-  inbox_folder:
-    type: string
-    description: Subfolder for new docs (empty = flat structure)
-    default: ""
-examples:
-  - title: "Start a planning doc"
-    code: |
-      /brain plan auth refactor
-      # Creates planning doc, becomes active for session
-  - title: "Quick note capture"
-    code: |
-      /brain note Remember to check rate limits on the API
-      # Fire-and-forget to inbox
-  - title: "Check for comments"
-    code: |
-      /brain check
-      # Find and address @mentions in active doc

package/dist/tools/brain/skills/brain-obsidian/SKILL.yaml

@@ -1,42 +0,0 @@
-name: brain-obsidian
-description: "Obsidian extension for brain skill. Adds YAML frontmatter, wikilinks, and folder organization. Requires brain skill. Install this to use brain docs with your Obsidian vault."
-version: 0.1.0
-status: beta
-dependencies:
-  - brain
-  # Optional: project skill enables linking features
-provides_output: false
-config_schema:
-  inbox_folder:
-    type: string
-    description: Folder for new brain docs
-    default: "0-Inbox"
-  archive_folder:
-    type: string
-    description: Folder for archived/stale docs
-    default: "4-Archives"
-  para_structure:
-    type: boolean
-    description: Enable full PARA folder organization
-    default: false
-  projects_folder:
-    type: string
-    description: Folder for active project docs (when para_structure is true)
-    default: "1-Projects"
-  areas_folder:
-    type: string
-    description: Folder for area docs (when para_structure is true)
-    default: "1-Areas"
-  resources_folder:
-    type: string
-    description: Folder for reference material (when para_structure is true)
-    default: "3-Resources"
-examples:
-  - title: "Create planning doc in vault"
-    code: |
-      /brain plan auth refactor
-      # Creates in vault's 0-Inbox/ with YAML frontmatter
-  - title: "Link to project"
-    code: |
-      /brain plan feature-x
-      # Frontmatter includes project: "[[feature-x]]"

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

@@ -1,25 +0,0 @@
-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."
-version: 0.1.0
-status: beta
-dependencies:
-  - comments
-provides_output: false
-config_schema:
-  scaffold_verbosity:
-    type: string
-    description: "How detailed scaffold hints should be: minimal (signatures only), medium (hints), detailed (pseudocode)"
-    default: "medium"
-examples:
-  - title: "Start co-authored planning"
-    code: |
-      /coach plan add user authentication
-      # AI asks questions, proposes structure, offers to create brain doc
-  - title: "Get scaffold for implementation"
-    code: |
-      /coach scaffold
-      # AI generates types/signatures with hint comments, you fill in logic
-  - title: "Review your implementation"
-    code: |
-      /coach review src/auth/login.ts
-      # AI adds inline // @you questions via comments skill