@orderful/droid 0.4.1 → 0.5.1

package/src/lib/skills.ts

@@ -1,4 +1,4 @@
-import { existsSync, readdirSync, readFileSync, mkdirSync, writeFileSync, cpSync, rmSync } from 'fs';
+import { existsSync, readdirSync, readFileSync, mkdirSync, writeFileSync, rmSync } from 'fs';
 import { join, dirname } from 'path';
 import { homedir } from 'os';
 import { fileURLToPath } from 'url';
@@ -156,6 +156,129 @@ export function getInstalledSkill(skillName: string): InstalledSkill | null {
   return config.skills[skillName] || null;
 }
 
+/**
+ * Check if a skill has an update available
+ */
+export function getSkillUpdateStatus(skillName: string): {
+  hasUpdate: boolean;
+  installedVersion: string | null;
+  bundledVersion: string | null;
+} {
+  const installed = getInstalledSkill(skillName);
+  const bundledSkillDir = join(BUNDLED_SKILLS_DIR, skillName);
+  const manifest = existsSync(bundledSkillDir) ? loadSkillManifest(bundledSkillDir) : null;
+
+  if (!installed || !manifest) {
+    return {
+      hasUpdate: false,
+      installedVersion: installed?.version || null,
+      bundledVersion: manifest?.version || null,
+    };
+  }
+
+  return {
+    hasUpdate: manifest.version !== installed.version,
+    installedVersion: installed.version,
+    bundledVersion: manifest.version,
+  };
+}
+
+/**
+ * Get all installed skills that have updates available
+ */
+export function getSkillsWithUpdates(): Array<{
+  name: string;
+  installedVersion: string;
+  bundledVersion: string;
+}> {
+  const config = loadConfig();
+  const updates: Array<{ name: string; installedVersion: string; bundledVersion: string }> = [];
+
+  for (const skillName of Object.keys(config.skills)) {
+    const status = getSkillUpdateStatus(skillName);
+    if (status.hasUpdate && status.installedVersion && status.bundledVersion) {
+      updates.push({
+        name: skillName,
+        installedVersion: status.installedVersion,
+        bundledVersion: status.bundledVersion,
+      });
+    }
+  }
+
+  return updates;
+}
+
+/**
+ * Update a skill to the latest bundled version
+ */
+export function updateSkill(skillName: string): { success: boolean; message: string } {
+  const status = getSkillUpdateStatus(skillName);
+
+  if (!status.installedVersion) {
+    return { success: false, message: `Skill '${skillName}' is not installed` };
+  }
+
+  if (!status.bundledVersion) {
+    return { success: false, message: `Skill '${skillName}' not found in bundled skills` };
+  }
+
+  if (!status.hasUpdate) {
+    return { success: false, message: `Skill '${skillName}' is already at latest version (${status.installedVersion})` };
+  }
+
+  // Reinstall the skill (install handles overwriting existing files)
+  const result = installSkill(skillName);
+  if (result.success) {
+    return {
+      success: true,
+      message: `Updated ${skillName} from ${status.installedVersion} to ${status.bundledVersion}`,
+    };
+  }
+
+  return result;
+}
+
+/**
+ * Update all installed skills that have newer bundled versions
+ */
+export function updateAllSkills(): {
+  updated: Array<{ name: string; from: string; to: string }>;
+  failed: Array<{ name: string; error: string }>;
+  upToDate: number;
+} {
+  const config = loadConfig();
+  const result = {
+    updated: [] as Array<{ name: string; from: string; to: string }>,
+    failed: [] as Array<{ name: string; error: string }>,
+    upToDate: 0,
+  };
+
+  for (const skillName of Object.keys(config.skills)) {
+    const status = getSkillUpdateStatus(skillName);
+
+    if (!status.hasUpdate) {
+      result.upToDate++;
+      continue;
+    }
+
+    const updateResult = updateSkill(skillName);
+    if (updateResult.success) {
+      result.updated.push({
+        name: skillName,
+        from: status.installedVersion!,
+        to: status.bundledVersion!,
+      });
+    } else {
+      result.failed.push({
+        name: skillName,
+        error: updateResult.message,
+      });
+    }
+  }
+
+  return result;
+}
+
 /**
  * Install a skill
  */
@@ -186,6 +309,34 @@ export function installSkill(skillName: string): { success: boolean; message: st
 
   const skillsPath = getSkillsInstallPath(config.ai_tool);
   const targetSkillDir = join(skillsPath, skillName);
+  const commandsPath = getCommandsInstallPath(config.ai_tool);
+
+  // Check for collisions BEFORE installing (only if not already installed by droid)
+  if (!config.skills[skillName]) {
+    // Check skill folder collision
+    if (existsSync(targetSkillDir)) {
+      return {
+        success: false,
+        message: `Cannot install: skill folder '${skillName}' already exists at ${targetSkillDir}`,
+      };
+    }
+
+    // Check command file collisions
+    const commandsSource = join(bundledSkillDir, 'commands');
+    if (existsSync(commandsSource)) {
+      const commandFiles = readdirSync(commandsSource).filter(f => f.endsWith('.md') && f.toLowerCase() !== 'readme.md');
+      for (const file of commandFiles) {
+        const targetCommandPath = join(commandsPath, file);
+        if (existsSync(targetCommandPath)) {
+          const commandName = file.replace('.md', '');
+          return {
+            success: false,
+            message: `Cannot install: command /${commandName} already exists at ${targetCommandPath}`,
+          };
+        }
+      }
+    }
+  }
 
   // Ensure skills directory exists
   if (!existsSync(skillsPath)) {
@@ -206,11 +357,16 @@ export function installSkill(skillName: string): { success: boolean; message: st
   // Copy commands if present
   const commandsSource = join(bundledSkillDir, 'commands');
   if (existsSync(commandsSource)) {
-    const commandsPath = getCommandsInstallPath(config.ai_tool);
     if (!existsSync(commandsPath)) {
       mkdirSync(commandsPath, { recursive: true });
     }
-    cpSync(commandsSource, commandsPath, { recursive: true });
+    const commandFiles = readdirSync(commandsSource).filter(f => f.endsWith('.md') && f.toLowerCase() !== 'readme.md');
+    for (const file of commandFiles) {
+      const sourcePath = join(commandsSource, file);
+      const targetPath = join(commandsPath, file);
+      const content = readFileSync(sourcePath, 'utf-8');
+      writeFileSync(targetPath, content);
+    }
   }
 
   // Update config
@@ -249,7 +405,7 @@ export function uninstallSkill(skillName: string): { success: boolean; message:
   const commandsSource = join(bundledSkillDir, 'commands');
   if (existsSync(commandsSource)) {
     const commandsPath = getCommandsInstallPath(config.ai_tool);
-    const commandFiles = readdirSync(commandsSource);
+    const commandFiles = readdirSync(commandsSource).filter(f => f.endsWith('.md') && f.toLowerCase() !== 'readme.md');
     for (const file of commandFiles) {
       const commandPath = join(commandsPath, file);
       if (existsSync(commandPath)) {

package/src/skills/comments/SKILL.md

@@ -1,6 +1,10 @@
 ---
 name: comments
-description: Inline conversation in any file via @droid/@user markers
+description: >-
+  Enable inline code conversations using @droid markers. Leave comments like
+  "> @droid should we cache this?" and get responses inline. Use /comments check
+  to scan for markers and address them, /comments cleanup to remove resolved threads.
+  Ideal for code review notes, quick questions, and async collaboration in any file.
 globs:
   - "**/*"
 alwaysApply: false
@@ -28,10 +32,29 @@ The AI will respond with `> @{user_mention}` (configured in droid setup, e.g., `
 
 ## Tag Convention
 
-| Who | Tag |
-|-----|-----|
-| AI | `@droid` (+ any configured aliases) |
-| User | Configured (e.g., `@fry`) |
+| Tag | Who's Speaking | Purpose |
+|-----|----------------|---------|
+| `@droid` | User | User leaving notes/questions for AI |
+| `@{user}` (e.g., `@fry`) | AI | AI leaving responses/questions for user |
+
+**The pattern:** The tag indicates who you're addressing, not who's writing. When you write `> @droid`, you're talking TO the AI. When the AI writes `> @fry`, it's talking TO you.
+
+## When NOT to Use
+
+- **Multi-file refactors** → describe in a task or issue, not scattered comments
+- **Formal code review** → use PR review process
+- **Questions needing persistent answers** → capture in dedicated documentation
+
+Inline comments shine for localized questions and actions within a file. For longer back-and-forth discussions in documents, they work great too - just be mindful that very long threads may be better moved to dedicated docs.
+
+## Context Gathering
+
+When you find a `@droid` marker:
+
+1. **Read surrounding context** - 20-30 lines around the comment
+2. **Check git status** - Prioritize files with uncommitted changes
+3. **Look for related markers** - Multiple comments in same file may be connected
+4. **Consider file type** - Match response format to the file (code comments vs markdown)
 
 ## Commands
 

package/src/skills/comments/SKILL.yaml

@@ -1,6 +1,10 @@
 name: comments
-description: Inline conversation in any file via @droid/@user markers
-version: 0.1.0
+description: >-
+  Enable inline code conversations using @droid markers. Leave comments like
+  "> @droid should we cache this?" and get responses inline. Use /comments check
+  to scan for markers and address them, /comments cleanup to remove resolved threads.
+  Ideal for code review notes, quick questions, and async collaboration in any file.
+version: 0.2.0
 status: beta
 dependencies: []
 provides_output: false

package/src/skills/comments/commands/comments.md

@@ -1,6 +1,16 @@
+---
+description: Check and respond to inline @droid comments in code and docs
+argument-hint: [check|cleanup] [path]
+allowed-tools: Read, Edit, Grep, Glob, Bash(git diff:*), Bash(git status:*)
+---
+
 # /comments - Check and respond to inline comments
 
-Check for `> @droid` comments (and configured aliases like `@claude`) in files and address them.
+Entry point for inline comment workflows. See the **comments skill** for full behavior.
+
+## Arguments
+
+$ARGUMENTS
 
 ## Usage
 
@@ -11,38 +21,9 @@ Check for `> @droid` comments (and configured aliases like `@claude`) in files a
 /comments cleanup      # Remove resolved comment threads
 ```
 
-## Arguments
-
-$ACTION - The action to perform: check (default) or cleanup
-$PATH - Optional path to scope the search
-
 ## Behavior
 
-When you find a `> @droid` comment (or configured alias):
-
-1. **Read the context** - Understand what the comment is asking by reading surrounding code/text
-2. **Determine intent**:
-   - If it's an **action request** (e.g., "add error handling", "refactor this"):
-     - Execute the requested action
-     - Remove the comment (unless preserve_comments is true)
-   - If it's a **question** (e.g., "what do you think?", "is this approach good?"):
-     - Respond with `> @{user_mention}` on a new line below
-     - Keep the original comment for context
-3. **Check git diff first** - If there's uncommitted changes, prioritize checking those files
-
-## Response Format
-
-When responding to questions, use the configured user tag:
-
-```markdown
-> @droid Should we use async/await here?
-
-> @fry Yes, async/await would be cleaner here because...
-```
-
-## Configuration
-
-Check `~/.droid/skills/comments/overrides.yaml` for:
-- `user_mention` - Your @mention for responses
-- `ai_mentions` - Additional mentions to recognize (e.g., `@claude`)
-- `preserve_comments` - Keep or remove addressed comments
+Refer to the comments skill for:
+- **Check**: How to find markers, determine intent (action vs question), respond appropriately
+- **Cleanup**: How to identify resolved threads and summarize decisions
+- **Configuration**: `user_mention`, `ai_mentions`, `preserve_comments` settings

package/src/skills/project/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: project
+description: >-
+  Manage project context files for persistent AI memory across sessions.
+  Load project context before working (/project {name}), update with
+  new learnings (/project update), or create new projects (/project create).
+  Use when working on multi-session features, refactors, or any work that
+  benefits from accumulated context.
+globs:
+  - "**/PROJECT.md"
+alwaysApply: false
+---
+
+# Project Skill
+
+Persistent project context that survives across sessions. Projects are folders containing `PROJECT.md` + `CHANGELOG.md`.
+
+## Why Projects?
+
+Chat history disappears. Projects persist.
+
+- **Context accumulates** - Each session starts with full project knowledge
+- **Decisions are captured** - No re-explaining why something was built a certain way
+- **Progress is tracked** - Semantic versioning + changelog show evolution
+
+## When NOT to Use
+
+- One-off tasks that don't need persistence
+- Simple questions or lookups
+- Tasks with sufficient context already in conversation
+- Quick fixes that don't warrant project tracking
+
+## Configuration
+
+Check `~/.droid/skills/project/overrides.yaml` for user settings:
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `projects_dir` | `~/{ai_tool}/projects` | Where projects are stored (varies by AI tool) |
+| `preset` | `markdown` | Output format: `markdown` or `obsidian` |
+
+Default `projects_dir` by AI tool:
+- **claude-code**: `~/.claude/projects`
+- **opencode**: `~/.opencode/projects`
+
+## Commands
+
+| Command | Action |
+|---------|--------|
+| `/project` | List and select a project |
+| `/project {keywords}` | Fuzzy-match and load |
+| `/project create {name}` | Create new project |
+| `/project update` | Update from conversation context |
+
+## Loading a Project
+
+**Trigger:** `/project {keywords}` or user asks to load/open a project
+
+**TLDR:** Fuzzy-match keywords against project folders, read PROJECT.md, summarize context.
+
+Full procedure: `references/loading.md`
+
+## Updating a Project
+
+**Trigger:** `/project update` or user asks to capture/save learnings
+
+**TLDR:** Analyze conversation for decisions/patterns/progress, propose changes, bump version, update changelog.
+
+Full procedure: `references/updating.md`
+Version rules: `references/versioning.md`
+Changelog format: `references/changelog.md`
+
+## Creating a Project
+
+**Trigger:** `/project create {name?}` or user asks to start a new project
+
+**TLDR:** Create folder in `projects_dir`, generate PROJECT.md + CHANGELOG.md from templates.
+
+Full procedure: `references/creating.md`
+Templates: `references/templates.md`
+
+## The Flywheel
+
+Projects work best in a cycle:
+
+1. **Load** - `/project {name}` gives Claude full context
+2. **Research/Plan** - Explore the problem, consider approaches
+3. **Document** - Capture decisions in PROJECT.md before implementing
+4. **Implement** - Build with full context of why decisions were made
+5. **Capture** - `/project update` saves new learnings
+6. **Repeat** - Next session starts with accumulated knowledge
+
+Each cycle starts further ahead than the last.

package/src/skills/project/SKILL.yaml

@@ -0,0 +1,35 @@
+name: project
+description: >-
+  Manage project context files for persistent AI memory across sessions.
+  Load project context before working (/project {name}), update with
+  new learnings (/project update), or create new projects (/project create).
+  Use when working on multi-session features, refactors, or any work that
+  benefits from accumulated context.
+version: 0.1.0
+status: beta
+dependencies: []
+provides_output: false
+config_schema:
+  projects_dir:
+    type: string
+    description: Path to projects directory (default varies by AI tool)
+  preset:
+    type: select
+    description: Output format for templates
+    default: "markdown"
+    options:
+      - markdown
+      - obsidian
+examples:
+  - title: "Load project by name"
+    code: |
+      /project transaction templates
+      # Fuzzy matches "transaction-templates" folder
+  - title: "Update after work session"
+    code: |
+      /project update
+      # Analyzes conversation, proposes PROJECT.md updates
+  - title: "Create new project"
+    code: |
+      /project create billing-refactor
+      # Creates folder with PROJECT.md and CHANGELOG.md

package/src/skills/project/commands/README.md

@@ -0,0 +1,26 @@
+# Project Commands
+
+Commands for managing project context files.
+
+## Available Commands
+
+| Command | Description |
+|---------|-------------|
+| `/project` | Main command - load, update, or create projects |
+
+## How It Works
+
+The `/project` command handles multiple operations via subcommands:
+
+- `/project` or `/project {keywords}` - Load a project
+- `/project load {name}` - Explicit load
+- `/project update {name?}` - Update project from conversation
+- `/project create {name?}` - Create new project
+
+## Adding Commands
+
+If you want to add additional project-related commands (like `/project stats` or `/project archive`), create a new `.md` file in this directory. The command will be namespaced under the skill name.
+
+Example: `project-stats.md` -> `/project stats` (if following the hyphenated naming convention)
+
+See the skill's SKILL.md for the full behavior specification.

package/src/skills/project/commands/project.md

@@ -0,0 +1,39 @@
+---
+description: Manage project context files for persistent AI memory across sessions
+argument-hint: [name | update [name] | create [name]]
+allowed-tools: Read, Write, Edit, Glob, Bash(mkdir:*), Bash(ls:*)
+---
+
+# /project
+
+Entry point for project context management. See the **project skill** for full behavior.
+
+## Arguments
+
+$ARGUMENTS
+
+## Usage
+
+```
+/project                    # List and select a project
+/project {keywords}         # Fuzzy-match and load
+/project update             # Update from conversation context
+/project update {name}      # Update specific project
+/project create             # Create new project interactively
+/project create {name}      # Create with name
+```
+
+## Configuration
+
+From `~/.droid/skills/project/overrides.yaml`:
+- `projects_dir` - Where projects live (default varies by AI tool)
+- `preset` - Template format: `markdown` or `obsidian`
+
+## Behavior
+
+Refer to the project skill for:
+- **Loading**: How to fuzzy-match, handle multiple matches, summarize after load
+- **Updating**: What to extract from conversation, versioning rules, changelog format
+- **Creating**: Template structure by preset, required files
+
+The skill's `references/` folder contains detailed specs for versioning, changelog formatting, and templates.

package/src/skills/project/references/changelog.md

@@ -0,0 +1,70 @@
+# Changelog Formatting
+
+Projects use a split file pattern to minimize context usage when loading.
+
+## File Structure
+
+- `CHANGELOG.md` (sibling to PROJECT.md) - Complete version history
+- `PROJECT.md` - Only 3 most recent entries + link to full history
+
+## On Update
+
+1. **Check for CHANGELOG.md** sibling
+   - If missing: Create it and migrate any existing entries from PROJECT.md
+
+2. **Add new entry to CHANGELOG.md** (prepend after header)
+
+3. **Update PROJECT.md changelog section**
+   - Keep only 3 most recent entries
+   - Ensure link to full history exists
+
+## CHANGELOG.md Format
+
+```markdown
+# Changelog
+
+All notable changes to the {Project Name} project.
+
+## X.Y.Z - YYYY-MM-DD
+- [Change description]
+- [Another change]
+
+## X.Y.Z - YYYY-MM-DD
+- [Previous changes]
+```
+
+## PROJECT.md Changelog Section Format
+
+**Markdown preset:**
+```markdown
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for full history.
+
+### X.Y.Z - YYYY-MM-DD
+- [Most recent]
+
+### X.Y.Z - YYYY-MM-DD
+- [Second most recent]
+
+### X.Y.Z - YYYY-MM-DD
+- [Third most recent]
+```
+
+**Obsidian preset:**
+```markdown
+## Changelog
+
+See [[CHANGELOG|full history]].
+
+### X.Y.Z - YYYY-MM-DD
+- [Most recent]
+```
+
+## Guidelines
+
+- Use present tense ("Add feature" not "Added feature")
+- Keep entries concise but descriptive
+- Group related changes in a single bullet when appropriate
+- Most recent version at the top
+- Use `##` headers in CHANGELOG.md, `###` in PROJECT.md

package/src/skills/project/references/creating.md

@@ -0,0 +1,58 @@
+# Creating a Project
+
+**Trigger:** `/project create {name?}` or user asks to start a new project
+
+## Procedure
+
+1. **Get project name**
+   - Use provided name, or ask if not provided
+   - Convert to kebab-case for folder name
+   - Convert to Title Case for display name
+
+2. **Create project folder**
+   - Path: `{projects_dir}/{kebab-case-name}/`
+   - Verify folder doesn't already exist
+
+3. **Create files from templates** (see `templates.md`)
+   - `PROJECT.md` - Main context file
+   - `CHANGELOG.md` - Version history
+   - Format varies by `preset` config (markdown vs obsidian)
+
+4. **Confirm creation**
+   - Show created folder path
+   - Offer to help fill in sections (Overview, Goals, Technical Details)
+
+## Naming Convention
+
+| Input | Folder Name | Display Name |
+|-------|-------------|--------------|
+| "billing refactor" | `billing-refactor` | "Billing Refactor" |
+| "API v2" | `api-v2` | "API V2" |
+| "my-feature" | `my-feature` | "My Feature" |
+
+## Example
+
+```
+User: /project create billing refactor
+
+Claude: Creating new project...
+
+Created: ~/.claude/projects/billing-refactor/
+├── PROJECT.md
+└── CHANGELOG.md
+
+Project "Billing Refactor" initialized at v0.1.0.
+
+Would you like help filling in the Overview, Goals, or Technical Details sections?
+```
+
+## Initial Structure
+
+New projects start minimal and grow organically. Common sections added over time:
+
+- **Current Work** - Active tasks and focus areas
+- **Decisions Log** - Key decisions with rationale
+- **Related** - Links to other docs, tickets, repos
+- **Roadmap** - Future phases
+
+See `templates.md` for the full initial template.

package/src/skills/project/references/loading.md

@@ -0,0 +1,40 @@
+# Loading a Project
+
+**Trigger:** `/project {keywords}` or user asks to load/open a project
+
+## Procedure
+
+1. **List projects** in configured `projects_dir`
+   - Each subfolder with a `PROJECT.md` is a project
+
+2. **If no name provided:**
+   - Use AskUserQuestion to present available projects
+   - Let user select which to load
+
+3. **If name/keywords provided:**
+   - Parse as space-separated keywords (e.g., "transaction templates" → `["transaction", "templates"]`)
+   - Find folders where name contains ALL keywords (case-insensitive, hyphens as word separators)
+
+4. **Based on matches:**
+   - **No matches**: List available projects, ask user to select
+   - **One match**: Read `{folder}/PROJECT.md`
+   - **Multiple matches**: Use AskUserQuestion to select from matches
+
+5. **After loading:**
+   - Confirm which project was loaded
+   - Summarize key context (2-3 sentences)
+   - Use project contents for all subsequent work in the session
+
+## Example
+
+```
+User: /project transaction templates
+
+Claude: Found project "transaction-templates". Loading...
+
+Loaded #project-transaction-templates (v1.16.1)
+
+This project covers Handlebars templates for EDI transaction generation.
+Key focus areas: template rendering service, permission controls, and
+the upcoming UI for template management.
+```