@orderful/droid 0.28.0 → 0.29.0

package/.claude-plugin/marketplace.json

@@ -8,8 +8,8 @@
   "plugins": [
     {
       "name": "droid",
-      "description": "Core droid meta-skill for update awareness and tool discovery. Checks for updates and helps users find the right tools.",
-      "version": "0.4.0",
+      "description": "Core droid meta-skill for update awareness, tool discovery, and usage help. Checks for updates, helps users find tools, and answers 'how do I...' questions about droid workflows.",
+      "version": "0.5.0",
       "source": {
         "source": "github",
         "repo": "orderful/droid",

package/.github/workflows/claude-code-review.yml

@@ -1,23 +1,17 @@
 name: Claude Code Review
 
 on:
-  pull_request:
-    # Run only when PR is opened or converted from draft to ready
-    types: [opened, ready_for_review]
-    # Optional: Only run on specific file changes
-    # paths:
-    #   - "src/**/*.ts"
-    #   - "src/**/*.tsx"
-    #   - "src/**/*.js"
-    #   - "src/**/*.jsx"
+  issue_comment:
+    types: [created]
 
 jobs:
   claude-review:
-    # Optional: Filter by PR author
-    # if: |
-    #   github.event.pull_request.user.login == 'external-contributor' ||
-    #   github.event.pull_request.user.login == 'new-developer' ||
-    #   github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
+    # Only run on PR comments that mention claude and review, but not from bots
+    if: |
+      github.event.issue.pull_request &&
+      github.event.comment.user.type != 'Bot' &&
+      contains(github.event.comment.body, 'claude') &&
+      contains(github.event.comment.body, 'review')
 
     runs-on: ubuntu-latest
     permissions:
@@ -39,16 +33,23 @@ jobs:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
           prompt: |
             REPO: ${{ github.repository }}
-            PR NUMBER: ${{ github.event.pull_request.number }}
+            PR NUMBER: ${{ github.event.issue.number }}
 
-            Please review this pull request and provide feedback on:
-            - Code quality and best practices
-            - Potential bugs or issues
-            - Performance considerations
-            - Security concerns
-            - Test coverage
+            Please review this pull request and identify **HIGH SEVERITY ISSUES ONLY**.
 
-            Use the repository's CLAUDE.md for guidance on style and conventions. Be constructive and helpful in your feedback.
+            Focus on:
+            - Critical bugs that could cause crashes, data loss, or incorrect behaviour
+            - Security vulnerabilities (injection attacks, authentication/authorisation flaws, secrets exposure)
+            - Performance issues that could significantly impact production (N+1 queries, memory leaks, infinite loops)
+            - Breaking changes or backwards compatibility issues
+
+            **Do not report:**
+            - Style/formatting issues
+            - Minor refactoring opportunities
+            - Low-impact suggestions
+            - Trivial improvements
+
+            Use the repository's CLAUDE.md for guidance on conventions. Be direct and focus only on the most critical issues.
 
             Use `gh pr comment` with your Bash tool to leave your review as a comment on the PR.
 

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @orderful/droid
 
+## 0.29.0
+
+### Minor Changes
+
+- [#170](https://github.com/Orderful/droid/pull/170) [`8e2b62f`](https://github.com/Orderful/droid/commit/8e2b62f773aeca43dc1dac511dfff1587b2b29c8) Thanks [@frytyler](https://github.com/frytyler)! - Add usage guides and automatic update notifications to droid
+
+  **Usage guides:** The droid skill now answers common workflow questions like:
+  - "How do I add context to my thread?"
+  - "Remind me the tools you have"
+  - "How do I find something in the codex?"
+  - "What's the best way to start a session?"
+
+  Includes guides for: starting sessions right, loading project context, searching codex, planning before implementing, using comments for async work, coach mode, and code review.
+
+  **Update notifications:** New `droid-bootstrap` skill with `alwaysApply: true` checks for droid updates once per session and shows a notification if a newer version is available. Lightweight (~20 lines) to minimize context overhead.
+
+## 0.28.1
+
+### Patch Changes
+
+- [#163](https://github.com/Orderful/droid/pull/163) [`8bc0e51`](https://github.com/Orderful/droid/commit/8bc0e5104c735a970d6f64e09a58c467ba41e569) Thanks [@frytyler](https://github.com/frytyler)! - Fix agent cleanup during tool uninstall and retry command cleanup migration.
+  - **Agent cleanup**: Previously, agents were only removed if tracked in config's bundled_agents field. Now uninstall also checks the tool's bundled agents directory directly, ensuring cleanup even if config tracking failed or is missing.
+  - **Command cleanup**: Retry migration to remove non-alias commands from ~/.claude/commands/ (original 0.28.0 migration did not execute properly for some users)
+
 ## 0.28.0
 
 ### Minor Changes

package/dist/bin/droid.js

@@ -698,10 +698,6 @@ function createClaudeCodeCommandCleanupMigration(version2) {
     version: version2,
     description: "Remove non-alias commands from Claude Code",
     up: () => {
-      const config = loadConfig();
-      if (config.platform !== "claude-code" /* ClaudeCode */) {
-        return;
-      }
       const commandsPath = getCommandsPath("claude-code" /* ClaudeCode */);
       if (!existsSync4(commandsPath)) {
         return;
@@ -736,7 +732,9 @@ var PACKAGE_MIGRATIONS = [
   createPlatformSyncMigration("0.25.0"),
   createConfigSkillNameMigration("0.27.2"),
   createOpenCodeSkillsPathMigration("0.28.0"),
-  createClaudeCodeCommandCleanupMigration("0.28.0")
+  createClaudeCodeCommandCleanupMigration("0.28.0"),
+  // Retry: 0.28.0 migration had platform check that prevented running after platform switch
+  createClaudeCodeCommandCleanupMigration("0.28.1")
 ];
 var TOOL_MIGRATIONS = {
   brain: [createConfigDirMigration("droid-brain", "0.2.3")],
@@ -1026,6 +1024,36 @@ function updateSkill(skillName) {
   }
   return result;
 }
+function updateAllSkills() {
+  const config = loadConfig();
+  const tools = getPlatformTools(config);
+  const result = {
+    updated: [],
+    failed: [],
+    upToDate: 0
+  };
+  for (const skillName of Object.keys(tools)) {
+    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;
+}
 function installSkill(skillName) {
   const config = loadConfig();
   const skillPath = findSkillPath(skillName);
@@ -1251,11 +1279,22 @@ function uninstallSkill(skillName) {
     }
   }
   const installedSkillInfo = tools[skillName];
+  const agentsToRemove = /* @__PURE__ */ new Set();
   if (installedSkillInfo?.bundled_agents) {
     for (const agentName of installedSkillInfo.bundled_agents) {
-      uninstallAgent(agentName);
+      agentsToRemove.add(agentName);
+    }
+  }
+  const agentsSource = skillPath ? join7(skillPath.toolDir, "agents") : null;
+  if (agentsSource && existsSync5(agentsSource)) {
+    const agentFiles = readdirSync4(agentsSource, { withFileTypes: true }).filter((dirent) => dirent.isFile() && dirent.name.endsWith(".md")).map((dirent) => dirent.name.replace(".md", ""));
+    for (const agentName of agentFiles) {
+      agentsToRemove.add(agentName);
     }
   }
+  for (const agentName of agentsToRemove) {
+    uninstallAgent(agentName);
+  }
   const { [skillName]: removed, ...remainingTools } = tools;
   setPlatformTools(config, remainingTools);
   saveConfig(config);
@@ -1824,12 +1863,23 @@ async function updateCommand(tool, options) {
     return;
   }
   if (options?.tools) {
-    console.log(chalk8.yellow("\n\u26A0 Tool-only updates not implemented yet"));
-    console.log(
-      chalk8.gray(
-        "Tools are bundled with the CLI - run `droid update` to update all."
-      )
-    );
+    console.log(chalk8.bold("\n\u{1F916} Syncing tools...\n"));
+    const result = updateAllSkills();
+    if (result.updated.length > 0) {
+      console.log(chalk8.green("\u2713 Updated:"));
+      for (const skill of result.updated) {
+        console.log(chalk8.gray(`  ${skill.name}: ${skill.from} \u2192 ${skill.to}`));
+      }
+    }
+    if (result.failed.length > 0) {
+      console.log(chalk8.red("\n\u2717 Failed:"));
+      for (const skill of result.failed) {
+        console.log(chalk8.gray(`  ${skill.name}: ${skill.error}`));
+      }
+    }
+    if (result.updated.length === 0 && result.failed.length === 0) {
+      console.log(chalk8.green("\u2713 All tools up to date"));
+    }
     return;
   }
   console.log(chalk8.bold("\n\u{1F916} Updating Droid...\n"));

package/dist/commands/update.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../src/commands/update.ts"],"names":[],"mappings":"AAIA,UAAU,aAAa;IACrB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,wBAAsB,aAAa,CACjC,IAAI,CAAC,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,IAAI,CAAC,CA6Df"}
+{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../src/commands/update.ts"],"names":[],"mappings":"AAKA,UAAU,aAAa;IACrB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,wBAAsB,aAAa,CACjC,IAAI,CAAC,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,IAAI,CAAC,CA6Ef"}

package/dist/index.js

@@ -671,10 +671,6 @@ function createClaudeCodeCommandCleanupMigration(version) {
     version,
     description: "Remove non-alias commands from Claude Code",
     up: () => {
-      const config = loadConfig();
-      if (config.platform !== "claude-code" /* ClaudeCode */) {
-        return;
-      }
       const commandsPath = getCommandsPath("claude-code" /* ClaudeCode */);
       if (!existsSync4(commandsPath)) {
         return;
@@ -709,7 +705,9 @@ var PACKAGE_MIGRATIONS = [
   createPlatformSyncMigration("0.25.0"),
   createConfigSkillNameMigration("0.27.2"),
   createOpenCodeSkillsPathMigration("0.28.0"),
-  createClaudeCodeCommandCleanupMigration("0.28.0")
+  createClaudeCodeCommandCleanupMigration("0.28.0"),
+  // Retry: 0.28.0 migration had platform check that prevented running after platform switch
+  createClaudeCodeCommandCleanupMigration("0.28.1")
 ];
 var TOOL_MIGRATIONS = {
   brain: [createConfigDirMigration("droid-brain", "0.2.3")],
@@ -1229,11 +1227,22 @@ function uninstallSkill(skillName) {
     }
   }
   const installedSkillInfo = tools[skillName];
+  const agentsToRemove = /* @__PURE__ */ new Set();
   if (installedSkillInfo?.bundled_agents) {
     for (const agentName of installedSkillInfo.bundled_agents) {
-      uninstallAgent(agentName);
+      agentsToRemove.add(agentName);
+    }
+  }
+  const agentsSource = skillPath ? join7(skillPath.toolDir, "agents") : null;
+  if (agentsSource && existsSync5(agentsSource)) {
+    const agentFiles = readdirSync4(agentsSource, { withFileTypes: true }).filter((dirent) => dirent.isFile() && dirent.name.endsWith(".md")).map((dirent) => dirent.name.replace(".md", ""));
+    for (const agentName of agentFiles) {
+      agentsToRemove.add(agentName);
     }
   }
+  for (const agentName of agentsToRemove) {
+    uninstallAgent(agentName);
+  }
   const { [skillName]: removed, ...remainingTools } = tools;
   setPlatformTools(config, remainingTools);
   saveConfig(config);

package/dist/lib/migrations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"migrations.d.ts","sourceRoot":"","sources":["../../src/lib/migrations.ts"],"names":[],"mappings":"AAUA,OAAO,EACL,KAAK,SAAS,EAIf,MAAM,SAAS,CAAC;AA+WjB;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,CAE/D;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAc/D;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,IAAI,CAmBN;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAChB;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CA2CtC;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,gBAAgB,EAAE,MAAM,GACvB;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAStC;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,cAAc,EAAE,MAAM,GAAG;IAC5D,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAyDA"}
+{"version":3,"file":"migrations.d.ts","sourceRoot":"","sources":["../../src/lib/migrations.ts"],"names":[],"mappings":"AAUA,OAAO,EACL,KAAK,SAAS,EAIf,MAAM,SAAS,CAAC;AA4WjB;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,CAE/D;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAc/D;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,IAAI,CAmBN;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAChB;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CA2CtC;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,gBAAgB,EAAE,MAAM,GACvB;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAStC;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,cAAc,EAAE,MAAM,GAAG;IAC5D,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAyDA"}

package/dist/lib/skills.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/lib/skills.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/lib/skills.ts"],"names":[],"mappings":"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"}

package/dist/tools/droid/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "droid",
-  "version": "0.4.0",
-  "description": "Core droid meta-skill for update awareness and tool discovery. Checks for updates and helps users find the right tools.",
+  "version": "0.5.0",
+  "description": "Core droid meta-skill for update awareness, tool discovery, and usage help. Checks for updates, helps users find tools, and answers 'how do I...' questions about droid workflows.",
   "author": {
     "name": "Orderful",
     "url": "https://github.com/orderful"

package/dist/tools/droid/TOOL.yaml

@@ -1,6 +1,6 @@
 name: droid
-description: "Core droid meta-skill for update awareness and tool discovery. Checks for updates and helps users find the right tools."
-version: 0.4.0
+description: "Core droid meta-skill for update awareness, tool discovery, and usage help. Checks for updates, helps users find tools, and answers 'how do I...' questions about droid workflows."
+version: 0.5.0
 status: beta
 
 # System tool - always stays current regardless of auto-update settings
@@ -10,6 +10,8 @@ includes:
   skills:
     - name: droid
       required: true
+    - name: droid-bootstrap
+      required: true
   commands: []
   agents: []
 

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

@@ -1,6 +1,6 @@
 ---
 name: droid
-description: "Core droid meta-skill for updates and tool discovery. Use when checking for droid updates or discovering available tools. User prompts like 'any droid updates?', 'what tools do I have?', 'is droid up to date?'."
+description: "Core droid meta-skill for updates, tool discovery, and usage help. Use when checking for droid updates, discovering available tools, or answering 'how do I...' questions about droid workflows. User prompts like 'any droid updates?', 'what tools do I have?', 'how do I add context?', 'remind me how to use codex', 'what's the best way to start a session?'."
 globs:
   - "**/*"
 alwaysApply: false
@@ -9,7 +9,7 @@ allowed-tools: [Bash]
 
 # Droid
 
-Core meta-skill for droid update awareness and tool discovery.
+Core meta-skill for droid update awareness, tool discovery, and usage guidance.
 
 ## Purpose
 
@@ -240,3 +240,214 @@ Run `droid install <tool>` or just `droid` to browse and install.
 
 They work well together: research in brain docs, capture decisions in project files.
 ```
+
+---
+
+## Usage Guides
+
+When users ask "how do I..." questions about droid workflows, use these guides.
+
+### Starting a Session Right
+
+**User asks:** "How do I add context?", "How do I start a session?", "Remind me how to set up context"
+
+**Answer:**
+
+```
+[● ●] Great question! Starting with context makes everything better.
+
+**Option 1: Load project context**
+`/project {name}` - Loads your project file with goals, decisions, and current work.
+
+**Option 2: Load shared knowledge**
+`/codex search {topic}` - Find relevant PRDs, tech designs, or patterns from the codex.
+
+**Option 3: Both**
+Start with `/project` for your working context, then `/codex search` if you need org knowledge.
+
+**Pro tip:** Context at the start of a thread beats adding it mid-conversation.
+```
+
+### Finding Things in the Codex
+
+**User asks:** "How do I find something in the codex?", "How do I search codex?"
+
+**Answer:**
+
+```
+[● ●] Use `/codex search {keywords}` to find content across the codex.
+
+Examples:
+- `/codex search webhooks` - Find docs mentioning webhooks
+- `/codex search partnership automation` - Find the partnership automation PRD
+- `/codex search error handling patterns` - Find relevant patterns
+
+The search looks across PRDs, tech designs, patterns, and explored topics.
+```
+
+### Loading Project Context
+
+**User asks:** "How do I load my project?", "How does project work?"
+
+**Answer:**
+
+```
+[● ●] Use `/project {name}` to load a project file.
+
+Examples:
+- `/project transaction-templates` - Load the transaction templates project
+- `/project droid` - Load the droid project context
+
+**What it gives me:**
+- Project goals and background
+- Key technical decisions and rationale
+- Current work in progress
+- Relevant code locations
+
+**Pro tip:** Load your project at the start of each session. I'll have full context immediately.
+```
+
+### Planning Before Implementing
+
+**User asks:** "How do I plan something?", "Should I plan first?"
+
+**Answer:**
+
+```
+[● ●] Yes! Planning before implementing helps me help you better.
+
+**Option 1: Brain doc (async, iterative)**
+`/brain plan {topic}` - Creates a planning doc you can iterate on with @mentions.
+
+**Option 2: Tech design (larger features)**
+`/tech-design {feature}` - For features that need research, alternatives, and rollout plans.
+
+**Why plan?**
+- I understand the full scope before writing code
+- We catch issues early, not mid-implementation
+- The plan becomes documentation
+```
+
+### Using Comments for Async Work
+
+**User asks:** "How do comments work?", "How do I leave notes for the AI?"
+
+**Answer:**
+
+```
+[● ●] Use @mentions to have async conversations in any file.
+
+**Leave a question:**
+Add `> @droid why is this pattern used here?` in a comment
+
+**Check for questions:**
+`/comments check` - I'll find and respond to all @droid mentions
+
+**Clean up:**
+`/comments cleanup` - Remove resolved comment threads
+
+Works great for code review notes and async collaboration.
+```
+
+### Learning vs Velocity Mode
+
+**User asks:** "What's coach mode?", "How do I learn instead of just getting answers?"
+
+**Answer:**
+
+```
+[● ●] Use `/coach` when you want to learn, not just ship.
+
+**Normal mode:** I implement for you (fast, but you don't learn)
+**Coach mode:** I guide you to implement yourself (slower, but you grow)
+
+Examples:
+- `/coach plan auth-refactor` - I'll ask questions to help YOU design it
+- `/coach review my-code.ts` - I'll ask Socratic questions, not give answers
+
+Good for: learning new codebases, building skills, understanding deeply.
+```
+
+### Code Review
+
+**User asks:** "How do I get a code review?", "Can you review my changes?"
+
+**Answer:**
+
+```
+[● ●] Use `/code-review` to review code with specialized agents.
+
+Examples:
+- `/code-review` - Review staged changes
+- `/code-review --pr 123` - Review a specific PR
+- `/code-review src/auth/` - Review specific files
+
+**What I check:**
+- Error handling and edge cases
+- Test coverage gaps
+- Type safety issues
+- EDI/partnership patterns (if applicable)
+
+Each finding has a confidence score so you can prioritize.
+```
+
+### Quick Reference
+
+| Question | Answer |
+|----------|--------|
+| "Add context to my thread" | `/project {name}` or `/codex search {topic}` |
+| "Find something in the codex" | `/codex search {keywords}` |
+| "Start planning" | `/brain plan {topic}` or `/tech-design {feature}` |
+| "Leave a note for AI" | Add `> @droid {question}` then `/comments check` |
+| "Learn instead of copy-paste" | `/coach {command}` |
+| "Review my code" | `/code-review` |
+| "Capture a decision" | `/codex decision {summary}` |
+| "Update project context" | `/project update` |
+
+### Example Dialogue
+
+**User:** "Hey droid, remind me the tools you have"
+
+```
+[● ●] Here's what you have installed:
+
+**Context loading:**
+- `/project {name}` - Load your project's working context
+- `/codex search {topic}` - Find shared knowledge (PRDs, tech designs, patterns)
+
+**Planning & thinking:**
+- `/brain plan {topic}` - Create a planning scratchpad
+- `/tech-design {feature}` - Design larger features
+
+**Collaboration:**
+- `/comments check` - Respond to @droid mentions
+- `/code-review` - Get AI code review with specialized agents
+
+**Learning:**
+- `/coach` - AI as guide, not implementer
+
+**Pro tip:** Start threads with `/project` or `/codex search` for best results.
+```
+
+**User:** "How should I approach this new feature?"
+
+```
+[● ●] Here's my suggested workflow:
+
+1. **Load context first**
+   `/project {your-project}` - So I know the codebase
+   `/codex search {related-topic}` - For any relevant patterns
+
+2. **Plan before coding**
+   `/brain plan {feature}` - Sketch out the approach
+   Iterate with @droid/@{you} comments until it feels right
+
+3. **Implement with context**
+   Now I have full context - ask me to implement
+
+4. **Review before shipping**
+   `/code-review` - Catch issues before PR
+
+5. **Capture learnings**
+   `/project update` - Save decisions for next session
+```

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

@@ -0,0 +1,44 @@
+---
+name: droid-bootstrap
+description: "Lightweight droid bootstrap for update awareness. Checks for droid updates once per session."
+globs: []
+alwaysApply: true
+allowed-tools: [Bash]
+---
+
+# Droid Bootstrap
+
+**Once per session**, check if a droid update is available.
+
+## Update Check
+
+Get latest version from npm (timeout 3s, fail silently):
+
+```bash
+timeout 3 npm view @orderful/droid version 2>/dev/null
+```
+
+Get installed version:
+
+```bash
+droid --version
+```
+
+If a newer version exists, ask the user:
+
+```
+[● ●] Droid v{latest} is available (you have v{current}).
+Would you like me to update now?
+```
+
+If user says yes, run these commands:
+
+```bash
+droid update && droid update --tools
+```
+
+The first command updates the npm package, the second syncs skill files to the install location. After updating, tell the user to restart their AI tool (Claude Code/OpenCode) to load the new skills.
+
+If user declines, continue with their request. Don't ask again this session.
+
+If the check fails (network issues, timeout), skip silently.

package/package.json

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

package/src/commands/update.ts

@@ -1,6 +1,7 @@
 import chalk from 'chalk';
 import { execSync } from 'child_process';
 import { getVersion } from '../lib/version';
+import { updateAllSkills } from '../lib/skills';
 
 interface UpdateOptions {
   tools?: boolean;
@@ -22,14 +23,30 @@ export async function updateCommand(
     return;
   }
 
-  // If --tools flag, update tools only
+  // If --tools flag, sync skills from bundled package to install location
   if (options?.tools) {
-    console.log(chalk.yellow('\n⚠ Tool-only updates not implemented yet'));
-    console.log(
-      chalk.gray(
-        'Tools are bundled with the CLI - run `droid update` to update all.',
-      ),
-    );
+    console.log(chalk.bold('\n🤖 Syncing tools...\n'));
+
+    const result = updateAllSkills();
+
+    if (result.updated.length > 0) {
+      console.log(chalk.green('✓ Updated:'));
+      for (const skill of result.updated) {
+        console.log(chalk.gray(`  ${skill.name}: ${skill.from} → ${skill.to}`));
+      }
+    }
+
+    if (result.failed.length > 0) {
+      console.log(chalk.red('\n✗ Failed:'));
+      for (const skill of result.failed) {
+        console.log(chalk.gray(`  ${skill.name}: ${skill.error}`));
+      }
+    }
+
+    if (result.updated.length === 0 && result.failed.length === 0) {
+      console.log(chalk.green('✓ All tools up to date'));
+    }
+
     return;
   }
 

package/src/lib/migrations.ts

@@ -299,13 +299,8 @@ function createClaudeCodeCommandCleanupMigration(version: string): Migration {
     version,
     description: 'Remove non-alias commands from Claude Code',
     up: () => {
-      const config = loadConfig();
-
-      // Only run for Claude Code platform
-      if (config.platform !== Platform.ClaudeCode) {
-        return;
-      }
-
+      // Clean up Claude Code commands directory regardless of current platform
+      // Users may have switched platforms, leaving orphaned commands
       const commandsPath = getCommandsPath(Platform.ClaudeCode);
       if (!existsSync(commandsPath)) {
         return;
@@ -360,6 +355,8 @@ const PACKAGE_MIGRATIONS: Migration[] = [
   createConfigSkillNameMigration('0.27.2'),
   createOpenCodeSkillsPathMigration('0.28.0'),
   createClaudeCodeCommandCleanupMigration('0.28.0'),
+  // Retry: 0.28.0 migration had platform check that prevented running after platform switch
+  createClaudeCodeCommandCleanupMigration('0.28.1'),
 ];
 
 /**

package/src/lib/skills.test.ts

@@ -355,3 +355,68 @@ describe('platform-specific command installation', () => {
     }
   });
 });
+
+describe('uninstallSkill agent cleanup', () => {
+  let testToolsDir: string;
+  let testAgentsDir: string;
+  let testSkillsDir: string;
+  let originalConfig: any;
+
+  beforeEach(() => {
+    originalConfig = loadConfig();
+
+    testToolsDir = join(tmpdir(), `droid-test-tools-${Date.now()}`);
+    testAgentsDir = join(tmpdir(), `droid-test-agents-${Date.now()}`);
+    testSkillsDir = join(tmpdir(), `droid-test-skills-${Date.now()}`);
+
+    mkdirSync(testToolsDir, { recursive: true });
+    mkdirSync(testAgentsDir, { recursive: true });
+    mkdirSync(testSkillsDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    saveConfig(originalConfig);
+
+    if (existsSync(testToolsDir)) {
+      rmSync(testToolsDir, { recursive: true });
+    }
+    if (existsSync(testAgentsDir)) {
+      rmSync(testAgentsDir, { recursive: true });
+    }
+    if (existsSync(testSkillsDir)) {
+      rmSync(testSkillsDir, { recursive: true });
+    }
+  });
+
+  it('should check both config and tool manifest for agents to remove', () => {
+    // Create a mock tool structure with agents
+    const toolDir = join(testToolsDir, 'test-tool');
+    const agentsDir = join(toolDir, 'agents');
+    mkdirSync(agentsDir, { recursive: true });
+
+    // Create agent files
+    writeFileSync(join(agentsDir, 'agent-in-manifest.md'), '---\nname: agent-in-manifest\n---\nAgent content');
+    writeFileSync(join(agentsDir, 'agent-in-both.md'), '---\nname: agent-in-both\n---\nAgent content');
+
+    // This test verifies the logic exists to check both sources
+    // The actual uninstallSkill would need more mocking to test fully
+    expect(existsSync(join(agentsDir, 'agent-in-manifest.md'))).toBe(true);
+    expect(existsSync(join(agentsDir, 'agent-in-both.md'))).toBe(true);
+  });
+
+  it('should use Set to deduplicate agents from both sources', () => {
+    // Verify Set behavior for deduplication
+    const agents = new Set<string>();
+
+    // Simulate adding from config
+    agents.add('agent1');
+    agents.add('agent2');
+
+    // Simulate adding from manifest (agent2 is duplicate)
+    agents.add('agent2');
+    agents.add('agent3');
+
+    expect(agents.size).toBe(3);
+    expect(Array.from(agents)).toEqual(['agent1', 'agent2', 'agent3']);
+  });
+});

package/src/lib/skills.ts

@@ -697,13 +697,33 @@ export function uninstallSkill(skillName: string): {
   }
 
   // Remove bundled agents if they were installed with this skill
+  // Check both config tracking AND tool manifest to ensure cleanup
   const installedSkillInfo = tools[skillName];
+  const agentsToRemove = new Set<string>();
+
+  // Add agents from config tracking (if available)
   if (installedSkillInfo?.bundled_agents) {
     for (const agentName of installedSkillInfo.bundled_agents) {
-      uninstallAgent(agentName);
+      agentsToRemove.add(agentName);
+    }
+  }
+
+  // Also check tool manifest for bundled agents (ensures cleanup even if tracking failed)
+  const agentsSource = skillPath ? join(skillPath.toolDir, 'agents') : null;
+  if (agentsSource && existsSync(agentsSource)) {
+    const agentFiles = readdirSync(agentsSource, { withFileTypes: true })
+      .filter((dirent) => dirent.isFile() && dirent.name.endsWith('.md'))
+      .map((dirent) => dirent.name.replace('.md', ''));
+    for (const agentName of agentFiles) {
+      agentsToRemove.add(agentName);
     }
   }
 
+  // Remove all agents
+  for (const agentName of agentsToRemove) {
+    uninstallAgent(agentName);
+  }
+
   // Remove from config (destructure to omit the skill being removed)
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
   const { [skillName]: removed, ...remainingTools } = tools;

package/src/tools/droid/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "droid",
-  "version": "0.4.0",
-  "description": "Core droid meta-skill for update awareness and tool discovery. Checks for updates and helps users find the right tools.",
+  "version": "0.5.0",
+  "description": "Core droid meta-skill for update awareness, tool discovery, and usage help. Checks for updates, helps users find tools, and answers 'how do I...' questions about droid workflows.",
   "author": {
     "name": "Orderful",
     "url": "https://github.com/orderful"

package/src/tools/droid/TOOL.yaml

@@ -1,6 +1,6 @@
 name: droid
-description: "Core droid meta-skill for update awareness and tool discovery. Checks for updates and helps users find the right tools."
-version: 0.4.0
+description: "Core droid meta-skill for update awareness, tool discovery, and usage help. Checks for updates, helps users find tools, and answers 'how do I...' questions about droid workflows."
+version: 0.5.0
 status: beta
 
 # System tool - always stays current regardless of auto-update settings
@@ -10,6 +10,8 @@ includes:
   skills:
     - name: droid
       required: true
+    - name: droid-bootstrap
+      required: true
   commands: []
   agents: []
 

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

@@ -1,6 +1,6 @@
 ---
 name: droid
-description: "Core droid meta-skill for updates and tool discovery. Use when checking for droid updates or discovering available tools. User prompts like 'any droid updates?', 'what tools do I have?', 'is droid up to date?'."
+description: "Core droid meta-skill for updates, tool discovery, and usage help. Use when checking for droid updates, discovering available tools, or answering 'how do I...' questions about droid workflows. User prompts like 'any droid updates?', 'what tools do I have?', 'how do I add context?', 'remind me how to use codex', 'what's the best way to start a session?'."
 globs:
   - "**/*"
 alwaysApply: false
@@ -9,7 +9,7 @@ allowed-tools: [Bash]
 
 # Droid
 
-Core meta-skill for droid update awareness and tool discovery.
+Core meta-skill for droid update awareness, tool discovery, and usage guidance.
 
 ## Purpose
 
@@ -240,3 +240,214 @@ Run `droid install <tool>` or just `droid` to browse and install.
 
 They work well together: research in brain docs, capture decisions in project files.
 ```
+
+---
+
+## Usage Guides
+
+When users ask "how do I..." questions about droid workflows, use these guides.
+
+### Starting a Session Right
+
+**User asks:** "How do I add context?", "How do I start a session?", "Remind me how to set up context"
+
+**Answer:**
+
+```
+[● ●] Great question! Starting with context makes everything better.
+
+**Option 1: Load project context**
+`/project {name}` - Loads your project file with goals, decisions, and current work.
+
+**Option 2: Load shared knowledge**
+`/codex search {topic}` - Find relevant PRDs, tech designs, or patterns from the codex.
+
+**Option 3: Both**
+Start with `/project` for your working context, then `/codex search` if you need org knowledge.
+
+**Pro tip:** Context at the start of a thread beats adding it mid-conversation.
+```
+
+### Finding Things in the Codex
+
+**User asks:** "How do I find something in the codex?", "How do I search codex?"
+
+**Answer:**
+
+```
+[● ●] Use `/codex search {keywords}` to find content across the codex.
+
+Examples:
+- `/codex search webhooks` - Find docs mentioning webhooks
+- `/codex search partnership automation` - Find the partnership automation PRD
+- `/codex search error handling patterns` - Find relevant patterns
+
+The search looks across PRDs, tech designs, patterns, and explored topics.
+```
+
+### Loading Project Context
+
+**User asks:** "How do I load my project?", "How does project work?"
+
+**Answer:**
+
+```
+[● ●] Use `/project {name}` to load a project file.
+
+Examples:
+- `/project transaction-templates` - Load the transaction templates project
+- `/project droid` - Load the droid project context
+
+**What it gives me:**
+- Project goals and background
+- Key technical decisions and rationale
+- Current work in progress
+- Relevant code locations
+
+**Pro tip:** Load your project at the start of each session. I'll have full context immediately.
+```
+
+### Planning Before Implementing
+
+**User asks:** "How do I plan something?", "Should I plan first?"
+
+**Answer:**
+
+```
+[● ●] Yes! Planning before implementing helps me help you better.
+
+**Option 1: Brain doc (async, iterative)**
+`/brain plan {topic}` - Creates a planning doc you can iterate on with @mentions.
+
+**Option 2: Tech design (larger features)**
+`/tech-design {feature}` - For features that need research, alternatives, and rollout plans.
+
+**Why plan?**
+- I understand the full scope before writing code
+- We catch issues early, not mid-implementation
+- The plan becomes documentation
+```
+
+### Using Comments for Async Work
+
+**User asks:** "How do comments work?", "How do I leave notes for the AI?"
+
+**Answer:**
+
+```
+[● ●] Use @mentions to have async conversations in any file.
+
+**Leave a question:**
+Add `> @droid why is this pattern used here?` in a comment
+
+**Check for questions:**
+`/comments check` - I'll find and respond to all @droid mentions
+
+**Clean up:**
+`/comments cleanup` - Remove resolved comment threads
+
+Works great for code review notes and async collaboration.
+```
+
+### Learning vs Velocity Mode
+
+**User asks:** "What's coach mode?", "How do I learn instead of just getting answers?"
+
+**Answer:**
+
+```
+[● ●] Use `/coach` when you want to learn, not just ship.
+
+**Normal mode:** I implement for you (fast, but you don't learn)
+**Coach mode:** I guide you to implement yourself (slower, but you grow)
+
+Examples:
+- `/coach plan auth-refactor` - I'll ask questions to help YOU design it
+- `/coach review my-code.ts` - I'll ask Socratic questions, not give answers
+
+Good for: learning new codebases, building skills, understanding deeply.
+```
+
+### Code Review
+
+**User asks:** "How do I get a code review?", "Can you review my changes?"
+
+**Answer:**
+
+```
+[● ●] Use `/code-review` to review code with specialized agents.
+
+Examples:
+- `/code-review` - Review staged changes
+- `/code-review --pr 123` - Review a specific PR
+- `/code-review src/auth/` - Review specific files
+
+**What I check:**
+- Error handling and edge cases
+- Test coverage gaps
+- Type safety issues
+- EDI/partnership patterns (if applicable)
+
+Each finding has a confidence score so you can prioritize.
+```
+
+### Quick Reference
+
+| Question | Answer |
+|----------|--------|
+| "Add context to my thread" | `/project {name}` or `/codex search {topic}` |
+| "Find something in the codex" | `/codex search {keywords}` |
+| "Start planning" | `/brain plan {topic}` or `/tech-design {feature}` |
+| "Leave a note for AI" | Add `> @droid {question}` then `/comments check` |
+| "Learn instead of copy-paste" | `/coach {command}` |
+| "Review my code" | `/code-review` |
+| "Capture a decision" | `/codex decision {summary}` |
+| "Update project context" | `/project update` |
+
+### Example Dialogue
+
+**User:** "Hey droid, remind me the tools you have"
+
+```
+[● ●] Here's what you have installed:
+
+**Context loading:**
+- `/project {name}` - Load your project's working context
+- `/codex search {topic}` - Find shared knowledge (PRDs, tech designs, patterns)
+
+**Planning & thinking:**
+- `/brain plan {topic}` - Create a planning scratchpad
+- `/tech-design {feature}` - Design larger features
+
+**Collaboration:**
+- `/comments check` - Respond to @droid mentions
+- `/code-review` - Get AI code review with specialized agents
+
+**Learning:**
+- `/coach` - AI as guide, not implementer
+
+**Pro tip:** Start threads with `/project` or `/codex search` for best results.
+```
+
+**User:** "How should I approach this new feature?"
+
+```
+[● ●] Here's my suggested workflow:
+
+1. **Load context first**
+   `/project {your-project}` - So I know the codebase
+   `/codex search {related-topic}` - For any relevant patterns
+
+2. **Plan before coding**
+   `/brain plan {feature}` - Sketch out the approach
+   Iterate with @droid/@{you} comments until it feels right
+
+3. **Implement with context**
+   Now I have full context - ask me to implement
+
+4. **Review before shipping**
+   `/code-review` - Catch issues before PR
+
+5. **Capture learnings**
+   `/project update` - Save decisions for next session
+```

package/src/tools/droid/skills/droid-bootstrap/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: droid-bootstrap
+description: "Lightweight droid bootstrap for update awareness. Checks for droid updates once per session."
+globs: []
+alwaysApply: true
+allowed-tools: [Bash]
+---
+
+# Droid Bootstrap
+
+**Once per session**, check if a droid update is available.
+
+## Update Check
+
+Get latest version from npm (timeout 3s, fail silently):
+
+```bash
+timeout 3 npm view @orderful/droid version 2>/dev/null
+```
+
+Get installed version:
+
+```bash
+droid --version
+```
+
+If a newer version exists, ask the user:
+
+```
+[● ●] Droid v{latest} is available (you have v{current}).
+Would you like me to update now?
+```
+
+If user says yes, run these commands:
+
+```bash
+droid update && droid update --tools
+```
+
+The first command updates the npm package, the second syncs skill files to the install location. After updating, tell the user to restart their AI tool (Claude Code/OpenCode) to load the new skills.
+
+If user declines, continue with their request. Don't ask again this session.
+
+If the check fails (network issues, timeout), skip silently.