@orderful/droid 0.24.0 → 0.25.1

package/.eslintrc.json

@@ -3,9 +3,7 @@
     "node": true,
     "es2022": true
   },
-  "extends": [
-    "eslint:recommended"
-  ],
+  "extends": ["eslint:recommended"],
   "parser": "@typescript-eslint/parser",
   "parserOptions": {
     "ecmaVersion": "latest",
@@ -14,7 +12,11 @@
   "plugins": ["@typescript-eslint"],
   "rules": {
     "no-unused-vars": "off",
-    "@typescript-eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_" }]
+    "@typescript-eslint/no-unused-vars": [
+      "error",
+      { "argsIgnorePattern": "^_" }
+    ],
+    "quotes": ["error", "single", { "avoidEscape": true }]
   },
   "ignorePatterns": ["dist/", "node_modules/", "*.test.ts"]
 }

package/AGENTS.md

@@ -73,3 +73,61 @@ Don't consolidate them. Using Ink for simple prompts would be overkill.
 - Prefer `const` over `let`
 - Use Canadian/British spelling (behaviour, colour, favourite)
 - Use "allow list/deny list" not "whitelist/blacklist"
+
+## Common Gotchas
+
+Things that will bite you if you don't know:
+
+| Gotcha | Why | What to do |
+|--------|-----|------------|
+| Single-line YAML descriptions | Claude Code's frontmatter parser doesn't handle multiline YAML (`>-`) | Use single-line quoted strings in frontmatter |
+| Skill directories have `droid-` prefix | Workaround for Claude Code bug where directories matching command names block invocation | Name skill dirs `droid-{name}/`, commands stay as `{name}.md` |
+| Bump tool version when skill content changes | Users won't get updates otherwise | Patch bump the tool's TOOL.yaml version |
+| Config-first in commands | User overrides must take precedence | Always read `~/.droid/skills/{skill}/overrides.yaml` before using defaults |
+| Changeset package name | npm package is scoped | Use `"@orderful/droid"` not `"droid"` in changesets |
+
+## Testing
+
+```bash
+bun test src/           # Unit tests (lib/, commands/)
+bun run test:tui        # Ink component tests (Badge, TabBar, etc.)
+bun run test:e2e        # E2E with Playwright + ttyd (requires ttyd installed)
+bun run screenshot      # On-demand TUI screenshot for visual verification
+```
+
+**When to run what:**
+- Changed core logic (`lib/`) → `bun test src/`
+- Changed TUI components → `bun run test:tui`
+- Visual changes you want to verify → `bun run screenshot`
+- E2E tests aren't in CI (ttyd not on runners) - use locally for visual feedback
+
+## Adding a New Skill
+
+1. Create directory: `src/tools/{tool}/skills/{skill}/`
+2. Add `SKILL.md` with frontmatter:
+   ```yaml
+   ---
+   name: droid-{skill}
+   description: "{What it does}. Use when {scenarios}. User prompts like {examples}."
+   globs: []
+   alwaysApply: false
+   allowed-tools: [Read, Edit, Write, Glob, Grep, Bash, Task]
+   ---
+   ```
+3. Add skill name to `TOOL.yaml` under `includes.skills`
+4. Bump tool version in `TOOL.yaml`
+5. Add changeset: `.changeset/{name}.md`
+
+**Optional:** Add `references/` for context files, `scripts/` for deterministic CLI scripts.
+
+## Key Architecture Decisions
+
+Decisions that affect how you work:
+
+| Decision | Rationale |
+|----------|-----------|
+| "Scripts" not "tools" for skill CLIs | Avoids terminology collision—droid "tools" are packages, skill "scripts" are executables |
+| Parallel skills (`{skill}-next`) for risky refactors | Dogfood new implementation alongside original, swap when confident |
+| Each .md owns its metadata | Single source of truth per artifact, contributors can bring existing skills as-is |
+| Ink + Inquirer (not consolidated) | Ink for stateful TUI, Inquirer for simple prompts—right tool for each job |
+| Collision detection over prefixing | Detect conflicts at install time rather than polluting command names with prefixes |

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # @orderful/droid
 
+## 0.25.1
+
+### Patch Changes
+
+- [#129](https://github.com/Orderful/droid/pull/129) [`d3264c4`](https://github.com/Orderful/droid/commit/d3264c493e1c243e812ab742103351888092ac79) Thanks [@frytyler](https://github.com/frytyler)! - fix(codex): add git preamble to Loading procedure
+
+  The "Loading an Entry" procedure wasn't running the git preamble before
+  reading files, causing potential stale data issues. Now explicitly calls
+  `git-preamble` as step 1 before reading the index.
+
+## 0.25.0
+
+### Minor Changes
+
+- [#123](https://github.com/Orderful/droid/pull/123) [`9e8bdff`](https://github.com/Orderful/droid/commit/9e8bdffccfb2e0ddbc02c1e9022a803f07f70240) Thanks [@frytyler](https://github.com/frytyler)! - Add deterministic git scripts to codex skill for bulletproof git hygiene
+  - `git-preamble.ts` - Ensure clean main + pull latest
+  - `git-start-write.ts` - Preamble + create branch
+  - `git-finish-write.ts` - Commit + PR + return to main
+
+  These scripts prevent PM-unfriendly git errors by making git operations deterministic and recoverable.
+
+- [#94](https://github.com/Orderful/droid/pull/94) [`3ddd79d`](https://github.com/Orderful/droid/commit/3ddd79d77da9c0ef78d70165066e3a3464422795) Thanks [@frytyler](https://github.com/frytyler)! - Add `droid exec` command for running deterministic skill scripts
+  - New `droid exec <skill> <script> [args]` command
+  - New `droid config <skill>` outputs merged config as JSON for scripts
+  - Skills can include a `scripts/` directory with TypeScript/Python tools
+  - Scripts are copied during skill installation
+
+- [#126](https://github.com/Orderful/droid/pull/126) [`e36d0ce`](https://github.com/Orderful/droid/commit/e36d0cee1b09313a454ce53f8daee0f2f427e670) Thanks [@frytyler](https://github.com/frytyler)! - Add platform sync migration to auto-detect installed tools. When switching between Claude Code and OpenCode, droid now automatically detects installed tools and syncs them to config.
+
+### Patch Changes
+
+- [#127](https://github.com/Orderful/droid/pull/127) [`316ac96`](https://github.com/Orderful/droid/commit/316ac96d7c89444a0506bbb392375e1fb155fd69) Thanks [@frytyler](https://github.com/frytyler)! - Fix agent installation bug where agents weren't copied during tool install/update. The code was filtering for directories but agents are .md files.
+
+- [#126](https://github.com/Orderful/droid/pull/126) [`e36d0ce`](https://github.com/Orderful/droid/commit/e36d0cee1b09313a454ce53f8daee0f2f427e670) Thanks [@frytyler](https://github.com/frytyler)! - Fix platform switching collision detection. Allow tools to overwrite their own command files when reinstalling across platforms (Claude Code ↔ OpenCode).
+
 ## 0.24.0
 
 ### Minor Changes

package/README.md

@@ -46,6 +46,8 @@ Browse available tools, see what's installed, and manage everything from one pla
 | **comments** | Inline `@droid`/`@user` conversations in any file | beta |
 | **project** | Persistent project context across sessions | beta |
 | **brain** | Collaborative scratch pad for planning & research | beta |
+| **coach** | Learning-mode AI - scaffolds don't implement, questions don't fix | beta |
+| **codex** | Shared organizational knowledge - PRDs, tech designs, patterns | beta |
 | **code-review** | Multi-agent code review with specialized checkers | alpha |
 
 ### Comments
@@ -95,9 +97,9 @@ Config lives in `~/.droid/`:
 ```
 ~/.droid/
 ├── config.yaml                    # Global config
-└── tools/
-    └── {tool}/
-        └── overrides.yaml         # Per-tool overrides
+└── skills/
+    └── {skill}/
+        └── overrides.yaml         # Per-skill overrides
 ```
 
 Tools install to your AI platform's location:
@@ -116,6 +118,7 @@ While the TUI is the primary interface, direct commands are available:
 | `droid uninstall <tool>` | Remove a tool |
 | `droid update` | Update droid and tools |
 | `droid config` | View/edit config |
+| `droid exec <skill> <script>` | Run a skill's deterministic script |
 
 ## Development
 
@@ -132,10 +135,12 @@ bun unlink
 
 ### Adding Tools
 
+See [AGENTS.md](AGENTS.md) for detailed contributor guidance. Quick overview:
+
 1. Create `src/tools/{name}/TOOL.yaml` (manifest)
-2. Add skills in `src/tools/{name}/skills/{skill}/SKILL.yaml` and `SKILL.md`
-3. Add commands in `src/tools/{name}/commands/*.md`
-4. Add agents in `src/tools/{name}/agents/{agent}/AGENT.yaml` and `AGENT.md`
+2. Add skills in `src/tools/{name}/skills/{skill}/SKILL.md` (frontmatter + instructions)
+3. Add commands in `src/tools/{name}/commands/{command}.md` (frontmatter + instructions)
+4. Add agents in `src/tools/{name}/agents/{agent}.md` (frontmatter + instructions)
 5. Submit a PR
 
 ## License