@orderful/droid 0.6.0 → 0.8.0

package/src/lib/skills.ts

@@ -5,6 +5,7 @@ import { fileURLToPath } from 'url';
 import YAML from 'yaml';
 import { loadConfig, saveConfig } from './config.js';
 import { AITool, SkillStatus, type SkillManifest, type InstalledSkill } from './types.js';
+import { getInstalledAgentsDir, installAgentFromPath, uninstallAgent, isAgentInstalled } from './agents.js';
 
 // Marker comments for CLAUDE.md skill registration
 const DROID_SKILLS_START = '<!-- droid-skills-start -->';
@@ -336,6 +337,22 @@ export function installSkill(skillName: string): { success: boolean; message: st
         }
       }
     }
+
+    // Check bundled agent collisions
+    const agentsSource = join(bundledSkillDir, 'agents');
+    if (existsSync(agentsSource)) {
+      const agentDirs = readdirSync(agentsSource, { withFileTypes: true })
+        .filter(dirent => dirent.isDirectory())
+        .map(dirent => dirent.name);
+      for (const agentName of agentDirs) {
+        if (isAgentInstalled(agentName)) {
+          return {
+            success: false,
+            message: `Cannot install: agent '${agentName}' already exists at ${getInstalledAgentsDir()}`,
+          };
+        }
+      }
+    }
   }
 
   // Ensure skills directory exists
@@ -354,6 +371,22 @@ export function installSkill(skillName: string): { success: boolean; message: st
     writeFileSync(skillMdTarget, content);
   }
 
+  // Copy references if present (skill documentation files)
+  const referencesSource = join(bundledSkillDir, 'references');
+  if (existsSync(referencesSource)) {
+    const targetReferencesDir = join(targetSkillDir, 'references');
+    if (!existsSync(targetReferencesDir)) {
+      mkdirSync(targetReferencesDir, { recursive: true });
+    }
+    const referenceFiles = readdirSync(referencesSource).filter(f => f.endsWith('.md'));
+    for (const file of referenceFiles) {
+      const sourcePath = join(referencesSource, file);
+      const targetPath = join(targetReferencesDir, file);
+      const content = readFileSync(sourcePath, 'utf-8');
+      writeFileSync(targetPath, content);
+    }
+  }
+
   // Copy commands if present
   const commandsSource = join(bundledSkillDir, 'commands');
   if (existsSync(commandsSource)) {
@@ -369,10 +402,29 @@ export function installSkill(skillName: string): { success: boolean; message: st
     }
   }
 
+  // Install bundled agents if present
+  const installedAgents: string[] = [];
+  const agentsSource = join(bundledSkillDir, 'agents');
+  if (existsSync(agentsSource)) {
+    const agentDirs = readdirSync(agentsSource, { withFileTypes: true })
+      .filter(dirent => dirent.isDirectory())
+      .map(dirent => dirent.name);
+
+    for (const agentName of agentDirs) {
+      // Use the skill's bundled agent path instead of global agents
+      const agentDir = join(agentsSource, agentName);
+      const result = installAgentFromPath(agentDir, agentName);
+      if (result.success) {
+        installedAgents.push(agentName);
+      }
+    }
+  }
+
   // Update config
   config.skills[skillName] = {
     version: manifest.version,
     installed_at: new Date().toISOString(),
+    ...(installedAgents.length > 0 && { bundled_agents: installedAgents }),
   };
   saveConfig(config);
 
@@ -414,6 +466,14 @@ export function uninstallSkill(skillName: string): { success: boolean; message:
     }
   }
 
+  // Remove bundled agents if they were installed with this skill
+  const installedSkillInfo = config.skills[skillName];
+  if (installedSkillInfo?.bundled_agents) {
+    for (const agentName of installedSkillInfo.bundled_agents) {
+      uninstallAgent(agentName);
+    }
+  }
+
   // Remove from config
   delete config.skills[skillName];
   saveConfig(config);

package/src/lib/types.ts

@@ -43,6 +43,7 @@ export interface DroidConfig {
 export interface InstalledSkill {
   version: string;
   installed_at: string;
+  bundled_agents?: string[]; // Agents installed with this skill
 }
 
 export interface SkillExample {

package/src/skills/brain/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: brain
+description: >-
+  Collaborative scratch pad for planning and research. Triggers on phrases like
+  "let's use our brain", "let's think through this", or "plan this out" to capture
+  AI output into a persistent doc. Create docs with /brain plan, /brain research,
+  or /brain review. Use @mentions for async discussion. Docs persist across sessions.
+globs:
+  - "**/brain/**/*.md"
+alwaysApply: false
+---
+
+# Brain Skill
+
+Scratch pad for planning, research, and design docs that persist across sessions.
+
+## Why Brain Docs?
+
+Ideas develop through iteration, not single prompts.
+
+- **Thinking space** - Work through problems before committing to code
+- **Async collaboration** - Leave `@mentions` for discussion across sessions (see comments skill for full support)
+- **Persistent context** - Docs survive after chat history disappears
+
+## When to Use
+
+- Planning implementation for a feature
+- Researching a problem or technology
+- Design work that benefits from written iteration
+- User says "brain", "let's think through", "plan this out"
+- Optionally, to capture output from plan mode sessions
+
+## When NOT to Use
+
+- Quick questions that don't need persistence
+- Tasks with clear implementation path
+- One-off lookups or simple fixes
+
+## Configuration
+
+**IMPORTANT:** Before using any default paths, ALWAYS read `~/.droid/skills/brain/overrides.yaml` first. If `brain_dir` is configured there, use that path. Only fall back to defaults if the file doesn't exist or lacks a `brain_dir` setting.
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `brain_dir` | (see below) | Where docs are stored |
+| `inbox_folder` | (empty) | Optional subfolder for new docs (omit for flat structure) |
+
+Default `brain_dir` by AI tool (only if not configured):
+- **claude-code**: `~/.claude/brain`
+- **opencode**: `~/.config/opencode/brain`
+
+## Core Concepts
+
+**Active doc:** Opening or creating a brain doc makes it "active" for the session. Subsequent `/brain add` commands append to it without specifying a path.
+
+**Doc types:**
+- `plan` - Structured: Context → Exploration → Decision → Next Steps
+- `research` - Open-ended exploration of a topic
+- `review` - Code review, document review, or any evaluation task
+- `note` - Quick capture (fire-and-forget, doesn't become active)
+
+**Comment conventions:** Use `@droid` / `@{user}` markers for async back-and-forth. If droid's `comments` skill is installed, use `/comments check` for full support.
+
+**Status lifecycle:** `exploring` → `drafting` → `decided` → `done`
+
+## Commands
+
+| Command | Action |
+|---------|--------|
+| `/brain` | List recent docs or create new |
+| `/brain {topic}` | **Search** for existing doc (fuzzy match) → becomes active |
+| `/brain plan {topic}` | Create planning doc (requires `plan` keyword) |
+| `/brain research {topic}` | Create research doc (requires `research` keyword) |
+| `/brain review {topic}` | Create review doc (requires `review` keyword) |
+| `/brain note {text}` | Quick capture (standalone, doesn't become active) |
+| `/brain add {text}` | Append to active doc |
+| `/brain check` | Address @droid comments in active doc |
+| `/brain done` | Finalize active doc, update status |
+
+**IMPORTANT:** The default action for `/brain {topic}` is to **SEARCH** for existing docs, NOT create. Only use `/brain plan {topic}` or `/brain research {topic}` when the user explicitly wants to create a new doc.
+
+## Opening a Doc
+
+**Trigger:** `/brain {topic}` or user asks to open a brain doc
+
+**TLDR:** Search for and open an existing doc. Fuzzy-match topic against existing docs, read content, set as active.
+
+Full procedure: `references/workflows.md` § Opening
+
+## Creating a Doc
+
+**Trigger:** `/brain plan {topic}` or `/brain research {topic}`
+
+**TLDR:** Create doc from template, set as active, gather initial context.
+
+Full procedure: `references/workflows.md` § Creating
+Templates: `references/templates.md`
+Naming: `references/naming.md`
+
+## Quick Notes
+
+**Trigger:** `/brain note {text}`
+
+**TLDR:** Fire-and-forget capture to inbox. Does not become active doc.
+
+Full procedure: `references/workflows.md` § Notes
+
+## Adding Content
+
+**Trigger:** `/brain add {text}`
+
+**TLDR:** Append text to active doc with timestamp.
+
+Full procedure: `references/workflows.md` § Adding
+
+## Checking Comments
+
+**Trigger:** `/brain check`
+
+**TLDR:** Find `> @droid` comments in active doc, address each one.
+
+Full procedure: `references/workflows.md` § Checking
+
+## Finalizing
+
+**Trigger:** `/brain done`
+
+**TLDR:** Review doc, update status to `done`, suggest next steps.
+
+Full procedure: `references/workflows.md` § Finalizing
+
+## Extensions
+
+Before creating or modifying brain docs, check if any `brain-*` extension skills are installed:
+
+```
+~/.claude/skills/brain-*/SKILL.md
+~/.droid/skills/brain-*/SKILL.md
+```
+
+If found (e.g., `brain-obsidian`), **ALWAYS** use the extension's templates, workflows, and configuration instead of this skill's defaults. Extensions may provide:
+- Alternative template formats (YAML frontmatter, wikilinks)
+- Folder organization (PARA structure)
+- Additional commands or integrations
+
+The base brain skill provides simple markdown. Extensions layer on advanced features.

package/src/skills/brain/SKILL.yaml

@@ -0,0 +1,31 @@
+name: brain
+description: >-
+  Collaborative scratch pad for planning and research. Triggers on phrases like
+  "let's use our brain", "let's think through this", or "plan this out" to capture
+  AI output into a persistent doc. Create docs with /brain plan, /brain research,
+  or /brain review. Use @mentions for async discussion. Docs persist across sessions.
+version: 0.1.1
+status: beta
+dependencies: []
+provides_output: false
+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/src/skills/brain/commands/README.md

@@ -0,0 +1,7 @@
+# Brain Skill Commands
+
+Commands in this folder are installed to `~/.claude/commands/` (or equivalent for other AI tools).
+
+## /brain
+
+Main entry point for brain doc management. See `brain.md` for details.

package/src/skills/brain/commands/brain.md

@@ -0,0 +1,50 @@
+---
+description: Collaborative scratch pad for planning and research
+argument-hint: "[{topic} | plan|research|review {topic} | note|add {text} | check|done]"
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash(mkdir:*), Bash(ls:*)
+---
+
+# /brain
+
+Entry point for brain doc management. See the **brain skill** for full behavior.
+
+## Arguments
+
+$ARGUMENTS
+
+## Default Behavior
+
+**IMPORTANT:** When given just a topic (e.g., `/brain auth-refactor`), the default action is to **SEARCH** for existing docs, NOT create. Only create docs with explicit `/brain plan {topic}` or `/brain research {topic}`.
+
+## Usage
+
+```
+/brain                      # List recent docs or create new
+/brain {topic}              # SEARCH: Open existing doc (fuzzy match) → active
+/brain plan {topic}         # CREATE: New planning doc → active
+/brain research {topic}     # Create research doc → active
+/brain review {topic}       # Create review doc → active
+/brain note {text}          # Quick capture (fire-and-forget)
+/brain add {text}           # Append to active doc
+/brain check                # Address @droid comments in active doc
+/brain done                 # Finalize active doc
+```
+
+## Configuration
+
+**ALWAYS read `~/.droid/skills/brain/overrides.yaml` first.** Use configured values if present, only fall back to defaults if missing.
+
+- `brain_dir` - Where docs live (default varies by AI tool)
+- `inbox_folder` - Subfolder for new docs (empty = flat)
+
+## Behavior
+
+Refer to the brain skill for:
+- **Opening**: How to fuzzy-match, handle multiple matches, set active
+- **Creating**: Template structure by preset, naming conventions
+- **Notes**: Quick capture workflow
+- **Adding**: Append to active doc with timestamp
+- **Checking**: Find and address @droid comments
+- **Finalizing**: Update status, suggest next steps
+
+The skill's `references/` folder contains detailed specs for workflows, templates, naming, and metadata.

package/src/skills/brain/references/metadata.md

@@ -0,0 +1,59 @@
+# Brain Doc Metadata
+
+Inline metadata and status lifecycle for brain docs.
+
+## Format
+
+Status and type tracked inline at top of doc:
+
+```markdown
+# {Topic}
+
+**Type:** plan
+**Status:** exploring
+**Created:** 2025-01-15
+
+...
+```
+
+Simple and portable. Works anywhere markdown is supported.
+
+## Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `Type` | Yes | Doc type: `plan`, `research`, `review`, or `note` |
+| `Status` | Yes (except notes) | Current lifecycle stage |
+| `Created` | Yes | Creation date |
+| `Updated` | No | Last modification date (add when doc changes) |
+
+## Status Lifecycle
+
+```
+exploring → drafting → decided → done
+    ↓          ↓          ↓
+  stale      stale      stale
+```
+
+### Status Definitions
+
+| Status | Meaning | Typical Actions |
+|--------|---------|-----------------|
+| `exploring` | Initial discovery, gathering information | Research, ask questions, explore options |
+| `drafting` | Forming opinions, narrowing options | Document trade-offs, propose approaches |
+| `decided` | Decision made, ready to act | Document decision rationale, plan implementation |
+| `done` | Work complete, doc is reference material | Archive or link from project |
+| `stale` | Abandoned or outdated | Review for archival or deletion |
+
+### Transitions
+
+- **exploring → drafting**: When you have enough info to start forming opinions
+- **drafting → decided**: When a clear decision/direction emerges
+- **decided → done**: When the work is complete
+- **any → stale**: When doc hasn't been touched in 30+ days without resolution
+
+## Updating Metadata
+
+When modifying a doc:
+1. Add or update the `Updated` field to current date
+2. Update `Status` if the work has progressed

package/src/skills/brain/references/naming.md

@@ -0,0 +1,48 @@
+# Brain Doc Naming
+
+Conventions for naming brain docs.
+
+## Format
+
+```
+{type}-{topic-slug}.md
+```
+
+## Components
+
+| Component | Description | Examples |
+|-----------|-------------|----------|
+| `{type}` | Doc type: `plan`, `research`, `note` | `plan`, `research`, `note` |
+| `{topic-slug}` | Lowercase, hyphen-separated topic | `auth-refactor`, `caching-strategies` |
+
+## Slug Rules
+
+1. **Lowercase** all words
+2. **Replace spaces** with hyphens
+3. **Remove special characters** (keep alphanumeric and hyphens only)
+4. **Limit length** to ~50 characters (truncate at word boundary)
+5. **No trailing hyphens**
+
+## Examples
+
+| Input | Filename |
+|-------|----------|
+| `/brain plan Auth Refactor` | `plan-auth-refactor.md` |
+| `/brain research Caching Strategies` | `research-caching-strategies.md` |
+| `/brain plan Transaction Template Rendering` | `plan-transaction-template-rendering.md` |
+| `/brain note Remember to check rate limits` | `note-20250115-remember-to-check-rate.md` |
+
+## Notes
+
+For notes, include the date in the filename:
+```
+note-{YYYYMMDD}-{slug}.md
+```
+
+This prevents collisions and allows chronological sorting.
+
+## Uniqueness
+
+If a file with the generated name already exists:
+1. Check if user wants to open existing doc
+2. Or append a numeric suffix: `plan-auth-refactor-2.md`

package/src/skills/brain/references/templates.md

@@ -0,0 +1,102 @@
+# Brain Doc Templates
+
+Templates for each doc type. All templates use simple markdown.
+
+## Plan Template
+
+```markdown
+# {Topic}
+
+**Type:** plan
+**Status:** exploring
+**Created:** {date}
+
+Planning {brief description}.
+
+## Context
+
+What we're solving and why.
+
+## Exploration
+
+Options and approaches considered.
+
+## Decision
+
+What we chose and why.
+
+## Next Steps
+
+- [ ] Action items
+```
+
+## Research Template
+
+```markdown
+# {Topic}
+
+**Type:** research
+**Status:** exploring
+**Created:** {date}
+
+Researching {brief description}.
+
+## Questions
+
+What we're trying to understand.
+
+## Findings
+
+What we've learned.
+
+## Summary
+
+Key takeaways.
+```
+
+## Review Template
+
+```markdown
+# {Topic}
+
+**Type:** review
+**Status:** exploring
+**Created:** {date}
+
+Reviewing {brief description}.
+
+## Overview
+
+What's being reviewed and scope.
+
+## Observations
+
+Key findings and notes.
+
+## Recommendations
+
+Suggested changes or actions.
+
+## Verdict
+
+Overall assessment.
+```
+
+## Note Template
+
+```markdown
+# Note: {Brief Title}
+
+**Created:** {date}
+
+{content}
+```
+
+## Template Variables
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `{Topic}` | Doc title from user input | "Auth Refactor" |
+| `{date}` | Current date (YYYY-MM-DD) | "2025-01-15" |
+| `{brief description}` | Context from conversation | "refactoring the authentication system" |
+| `{content}` | User-provided text | (for notes) |