@orderful/droid 0.4.0 → 0.5.0

package/dist/skills/project/references/updating.md

@@ -0,0 +1,64 @@
+# Updating a Project
+
+**Trigger:** `/project update` or user asks to capture/save learnings
+
+## Procedure
+
+1. **Identify the project:**
+   - If name provided: Find matching project (same logic as loading)
+   - If no name: Check conversation for prior project load
+   - If still unclear: List projects and ask which to update
+
+2. **Analyze the conversation for:**
+   - New implementation details or patterns
+   - Key decisions and rationale
+   - Technical constraints discovered
+   - Progress on features
+   - Important file paths or code locations
+   - Bug fixes or gotchas encountered
+
+3. **If significant new information found:**
+   - Propose specific sections/content to add or update
+   - Show what will be changed
+   - Ask for confirmation before proceeding
+
+4. **If no obvious updates:**
+   - Ask what the user would like to update
+   - Suggest sections: metadata, implementation details, technical decisions, notes
+
+5. **After approval:**
+   - Read current project file
+   - Make approved updates, preserving existing structure
+   - Determine version bump (see `versioning.md`)
+   - Add changelog entry (see `changelog.md`)
+   - Confirm what was updated
+
+## What to Capture
+
+Good project updates include:
+
+| Type | Examples |
+|------|----------|
+| **Decisions** | "Chose cursor-based pagination over offset" |
+| **Patterns** | "Using repository pattern for data access" |
+| **Constraints** | "Must support backwards compatibility with v1 API" |
+| **Gotchas** | "Watch out for timezone handling in date fields" |
+| **Progress** | "Completed validation layer, starting on UI" |
+| **File locations** | "Key files: `src/services/template.service.ts`" |
+
+## Example
+
+```
+User: /project update
+
+Claude: I'll update #project-transaction-templates with learnings from this session.
+
+Proposed changes:
+- Add "Permission Controls" section documenting the new RBAC approach
+- Update Technical Details with the Handlebars helper patterns we established
+- Note the decision to use soft deletes
+
+This looks like a minor version bump (0.16.0 → 0.17.0).
+
+Proceed with these updates?
+```

package/dist/skills/project/references/versioning.md

@@ -0,0 +1,36 @@
+# Version Bumping Rules
+
+Use semantic versioning for project docs.
+
+## When to Bump
+
+| Type | When | Examples |
+|------|------|----------|
+| **Major** | Breaking changes, complete rewrites, fundamental architecture changes | New approach that invalidates previous docs |
+| **Minor** | New features, new sections, significant additions | New helper added, new endpoint, new workflow |
+| **Patch** | Clarifications, small updates, typo fixes, status changes | Wording tweaks, deferred features, bug notes |
+
+## Auto-Determination
+
+Analyze the changes being made:
+
+1. Default to **minor** for most content additions
+2. Use **patch** for small clarifications or status updates
+3. Use **major** only for fundamental changes (rare)
+4. Only ask user if genuinely ambiguous
+
+## Examples
+
+**Patch (0.1.0 -> 0.1.1):**
+- Fixed typo in technical details
+- Updated status from active to reference
+- Added note about known limitation
+
+**Minor (0.1.1 -> 0.2.0):**
+- Added new "Authentication" section
+- Documented new API endpoint
+- Added architecture diagram
+
+**Major (0.2.0 -> 1.0.0):**
+- Complete rewrite of implementation approach
+- Switched from REST to GraphQL (invalidates prior docs)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orderful/droid",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "AI workflow toolkit for sharing skills, commands, and agents across the team",
   "type": "module",
   "bin": {
@@ -41,8 +41,6 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@opentui/core": "^0.1.59",
-    "@opentui/react": "^0.1.59",
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
     "ink": "^6.5.1",

package/src/commands/tui.tsx

@@ -11,6 +11,8 @@ import {
   getInstalledSkill,
   installSkill,
   uninstallSkill,
+  updateSkill,
+  getSkillUpdateStatus,
   isCommandInstalled,
   installCommand,
   uninstallCommand,
@@ -62,7 +64,23 @@ function getCommandsFromSkills(): Command[] {
       const content = readFileSync(join(commandsDir, file), 'utf-8');
       const lines = content.split('\n');
 
-      const headerMatch = lines[0]?.match(/^#\s+\/(\S+)\s*-?\s*(.*)/);
+      // Skip YAML frontmatter if present
+      let startLine = 0;
+      if (lines[0]?.trim() === '---') {
+        for (let i = 1; i < lines.length; i++) {
+          if (lines[i]?.trim() === '---') {
+            startLine = i + 1;
+            break;
+          }
+        }
+      }
+
+      // Find first H1 header
+      let headerMatch: RegExpMatchArray | null = null;
+      for (let i = startLine; i < lines.length; i++) {
+        headerMatch = lines[i]?.match(/^#\s+\/(\S+)\s*-?\s*(.*)/);
+        if (headerMatch) break;
+      }
       if (!headerMatch) continue;
 
       const usage: string[] = [];
@@ -393,6 +411,7 @@ function SkillItem({
 }) {
   const installed = isSkillInstalled(skill.name);
   const installedInfo = getInstalledSkill(skill.name);
+  const updateStatus = getSkillUpdateStatus(skill.name);
 
   return (
     <Box paddingX={1} backgroundColor={isActive ? colors.bgSelected : undefined}>
@@ -401,6 +420,7 @@ function SkillItem({
         <Text color={isSelected || isActive ? colors.text : colors.textMuted}>{skill.name}</Text>
         {installed && installedInfo && <Text color={colors.textDim}> v{installedInfo.version}</Text>}
         {installed && <Text color={colors.success}> *</Text>}
+        {updateStatus.hasUpdate && <Text color={colors.primary}> ↑</Text>}
       </Text>
     </Box>
   );
@@ -444,12 +464,16 @@ function SkillDetails({
   }
 
   const installed = isSkillInstalled(skill.name);
+  const updateStatus = getSkillUpdateStatus(skill.name);
   const skillCommands = getCommandsFromSkills().filter((c) => c.skillName === skill.name);
 
   const actions = installed
     ? [
         { id: 'view', label: 'View', variant: 'default' },
-        { id: 'configure', label: 'Configure', variant: 'primary' },
+        ...(updateStatus.hasUpdate
+          ? [{ id: 'update', label: `Update (${updateStatus.bundledVersion})`, variant: 'primary' }]
+          : []),
+        { id: 'configure', label: 'Configure', variant: 'default' },
         { id: 'uninstall', label: 'Uninstall', variant: 'danger' },
       ]
     : [
@@ -466,6 +490,9 @@ function SkillDetails({
           {skill.version}
           {skill.status && ` · ${skill.status}`}
           {installed && <Text color={colors.success}> · installed</Text>}
+          {updateStatus.hasUpdate && (
+            <Text color={colors.primary}> · update available ({updateStatus.installedVersion} → {updateStatus.bundledVersion})</Text>
+          )}
         </Text>
       </Box>
 
@@ -1184,7 +1211,9 @@ function App() {
         if (activeTab === 'skills') {
           const skill = skills[selectedIndex];
           const installed = skill ? isSkillInstalled(skill.name) : false;
-          maxActions = installed ? 2 : 1; // View, Configure, Uninstall or View, Install
+          const hasUpdate = skill ? getSkillUpdateStatus(skill.name).hasUpdate : false;
+          // View, [Update], Configure, Uninstall or View, Install
+          maxActions = installed ? (hasUpdate ? 3 : 2) : 1;
         } else if (activeTab === 'agents') {
           maxActions = 1; // View, Install/Uninstall
         } else if (activeTab === 'commands') {
@@ -1199,20 +1228,38 @@ function App() {
         const skill = skills[selectedIndex];
         if (skill) {
           const installed = isSkillInstalled(skill.name);
-          // Actions: installed = [View, Configure, Uninstall], not installed = [View, Install]
-          if (selectedAction === 0) {
-            // View
+          const skillUpdateStatus = getSkillUpdateStatus(skill.name);
+          // Build actions array to match SkillDetails
+          const skillActions = installed
+            ? [
+                { id: 'view' },
+                ...(skillUpdateStatus.hasUpdate ? [{ id: 'update' }] : []),
+                { id: 'configure' },
+                { id: 'uninstall' },
+              ]
+            : [{ id: 'view' }, { id: 'install' }];
+
+          const actionId = skillActions[selectedAction]?.id;
+
+          if (actionId === 'view') {
             const skillMdPath = join(getBundledSkillsDir(), skill.name, 'SKILL.md');
             if (existsSync(skillMdPath)) {
               const content = readFileSync(skillMdPath, 'utf-8');
               setReadmeContent({ title: `${skill.name}/SKILL.md`, content });
               setView('readme');
             }
-          } else if (installed && selectedAction === 1) {
-            // Configure
+          } else if (actionId === 'update') {
+            const result = updateSkill(skill.name);
+            setMessage({
+              text: result.success ? `✓ ${result.message}` : `✗ ${result.message}`,
+              type: result.success ? 'success' : 'error',
+            });
+            if (result.success) {
+              setSelectedAction(0);
+            }
+          } else if (actionId === 'configure') {
             setView('configure');
-          } else if (installed && selectedAction === 2) {
-            // Uninstall
+          } else if (actionId === 'uninstall') {
             const result = uninstallSkill(skill.name);
             setMessage({
               text: result.success ? `✓ Uninstalled ${skill.name}` : `✗ ${result.message}`,
@@ -1222,8 +1269,7 @@ function App() {
               setView('menu');
               setSelectedAction(0);
             }
-          } else if (!installed && selectedAction === 1) {
-            // Install
+          } else if (actionId === 'install') {
             const result = installSkill(skill.name);
             setMessage({
               text: result.success ? `✓ Installed ${skill.name}` : `✗ ${result.message}`,
@@ -1486,6 +1532,13 @@ function App() {
           )}
         </Box>
 
+        {/* Message */}
+        {message && (
+          <Box paddingX={1} marginTop={1}>
+            <Text color={message.type === 'success' ? colors.success : colors.error}>{message.text}</Text>
+          </Box>
+        )}
+
         {/* Footer */}
         <Box paddingX={1} marginTop={1}>
           <Text color={colors.textDim}>
@@ -1510,13 +1563,6 @@ function App() {
       {activeTab === 'agents' && (
         <AgentDetails agent={selectedAgent} isFocused={view === 'detail'} selectedAction={selectedAction} />
       )}
-
-      {/* Message */}
-      {message && (
-        <Box position="absolute" marginTop={12}>
-          <Text color={message.type === 'success' ? colors.success : colors.error}>{message.text}</Text>
-        </Box>
-      )}
     </Box>
   );
 }

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