@orderful/droid

"Droid, teaching your AI new tricks"

AI workflow toolkit for sharing tools, commands, and agents across the engineering team.

Why Droid?

• Lower the barrier to entry - Get started with AI coding tools (Claude Code, OpenCode) without configuring from scratch
• Share what works - Power users discover great workflows, everyone benefits
• Consistent experience - Common patterns like @droid/@user comments work the same across the team

Prerequisites

Before installing droid:

| Requirement | Why | Install | | -------------------------- | -------------------------------------------- | ---------------------------------------- | | npm login to @orderful | Droid is published to our private npm org | npm login (use Orderful credentials) | | bun | Required for droid exec scripts | bun.sh | | gh (GitHub CLI) | Highly recommended for PR workflows | cli.github.com | | Obsidian | Recommended for brain/codex markdown editing | obsidian.md |

Setup Gotchas

Things that trip people up:

Claude Code not found after install

If claude command isn't found in new terminal windows, add to your shell rc file (.bashrc, .zshrc):

export PATH="$HOME/.local/bin:$PATH"

Then restart your terminal or source the file.

Check your settings before diving in

After install, review your configuration before starting a session:

droid config                    # View global settings
droid                           # TUI → Settings tab for tool-specific config

Make sure username, paths, and tool settings match what you want.

Updates require restart

When droid auto-updates (or you run droid update), the package updates but you need to:

1. Restart droid to pick up the new version
2. Run tool updates separately if needed (droid update in TUI)

Cursor support

Cursor integration currently requires the nightly build of Cursor.

nodenv/nvm/asdf users

After global npm install, run nodenv rehash (or equivalent for your version manager) to update shims.

Quick Start

Option A: TUI Dashboard (Recommended)

npm install -g @orderful/droid
droid

The TUI guides you through setup and tool installation. Works with both Claude Code and OpenCode.

Option B: Claude Code Plugin

Install directly through Claude Code's plugin system:

# Add the Droid marketplace
/plugin marketplace add orderful/droid

# Install all droid tools
/plugin install droid@droid

The TUI

Run droid to launch the interactive dashboard:

┌─────────────────────────────────────────┐
│  @orderful/droid                        │
│  "Droid, teaching your AI new tricks"   │
├─────────────────────────────────────────┤
│  > Tools      Browse and install tools  │
│    Settings   View/edit configuration   │
└─────────────────────────────────────────┘

Browse available tools, see what's installed, and manage everything from one place.

Available Tools

| Tool | Description | Status | | --------------- | ----------------------------------------------------------------- | ------ | | comments | Inline @droid/@user conversations in any file | beta | | project | Persistent project context across sessions | beta | | brain | Collaborative scratch pad for planning & research | beta | | plan | Task-scoped planning with portable, structured plans | alpha | | 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 | | tech-design | Three-document approach for technical designs | beta | | wrapup | Session wrap-up that captures decisions to persistent docs | alpha | | status-update | Generate and post project status updates to Slack | beta | | webform | Generate PrintView webform templates for EDI transaction types | beta |

Comments

Leave notes for your AI with @droid, get responses addressed to you:

> @droid Should we cache this query?

> @fry Yes, add Redis caching. The query runs on every request.

Project

Maintain context across sessions for long-running work:

/project myfeature      # Load project context
/project update         # Capture new learnings
/project create auth    # Start a new project

Brain

Collaborative thinking space for planning and research:

/brain plan auth refactor   # Create planning doc
/brain research caching     # Research doc
/brain check                # Check for @mentions

Code Review

Run comprehensive reviews with specialized agents:

/code-review #123           # Review a PR
/code-review staged         # Review staged changes
/code-review path/to/file   # Review specific file

Tech Design

Three-document approach for technical designs (requires brain + codex):

/tech-design start auth-refactor   # Start a new tech design
/tech-design draft api             # Draft a section
/tech-design publish               # Publish roll-up to codex

Creates: research doc (codebase discoveries) → thought doc (design workspace) → roll-up (clean summary).

Wrapup

Capture session context before ending:

/wrapup                     # Run session wrap-up

Extracts decisions, learnings, and open items to project files and brain docs.

Status Update

Post project status updates to Slack:

/status-update              # Generate and post status update

Pulls context from codex projects and Jira, formats with phase checklists, posts to Slack (or prints to terminal).

Webform

Generate PrintView webform templates from Orderful JSON schemas and sample transactions:

/webform 850 ~/Downloads/sample-850.json   # Generate from sample
/webform 812 ~/Downloads/812.edi           # Generate from EDI file
/webform 997                               # Start (will ask for sample)

Proposes a visual layout for approval, then generates template code with reusable subsection items. Requires configuration:

droid config --set tools.webform.schema_repo="~/Projects/orderful-workspace"
droid config --set tools.webform.ui_repo="~/Projects/o2-app-ui"

Requires one-time setup:

droid auth slack            # Set up Slack OAuth (per user)

Configuration

Config lives in ~/.droid/:

~/.droid/
├── config.yaml                    # Global config (platform, user settings, tool config)
└── skill_overrides/               # User-defined skill behaviour overrides
    ├── _template.md               # Template and instructions
    └── {skill}.md                 # Override for specific skill

Key sections in config.yaml:

• platform - Primary platform (claude-code, opencode, cursor)
• user_mention - Your @mention for comments (e.g., @fry)
• tools - Per-tool configuration (brain paths, codex repo, etc.)
• auto_update - Auto-update settings for app and tools
• repos - Known repositories for context

Skill Overrides

Customize skill behaviour without forking droid. Create override files in ~/.droid/skill_overrides/ to replace specific commands with your own instructions.

Example: Use semantic search with qmd instead of filename matching for /brain search:

1. Ask droid: "Create an override for brain search that uses qmd"
2. Droid creates ~/.droid/skill_overrides/brain.md with your instructions
3. Droid registers it in config
4. Next /brain search uses your qmd workflow

See ~/.droid/skill_overrides/_template.md for format details.

Where tools install:

Skills are unified across all platforms to ~/.claude/skills/. Commands and agents are platform-specific:

| Platform | Skills | Commands | Agents | | ----------- | ------------------- | ----------------------------- | --------------------------- | | Claude Code | ~/.claude/skills/ | ~/.claude/commands/ | ~/.claude/agents/ | | OpenCode | ~/.claude/skills/ | ~/.config/opencode/command/ | ~/.config/opencode/agent/ | | Cursor | ~/.claude/skills/ | ~/.cursor/commands/ | ~/.cursor/agents/ |

CLI Reference

While the TUI is the primary interface, direct commands are available:

| Command | Description | | ----------------------------- | ---------------------------------- | | droid | Launch TUI dashboard | | droid setup | Run setup wizard | | droid install <tool> | Install a tool | | droid uninstall <tool> | Remove a tool | | droid update | Update droid and tools | | droid config | View/edit config | | droid auth | Show authentication status | | droid auth slack | Set up Slack OAuth for status updates | | droid exec <skill> <script> | Run a skill's deterministic script |

Development

git clone https://github.com/orderful/droid.git
cd droid && bun install
bun run build
bun dist/bin/droid.js

# to test TUI
bun link
bun unlink

# to build plugin packages
bun run build:plugins

Adding Tools

See 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.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. Run bun run build:plugins to generate plugin manifests
6. Submit a PR

The build script generates:

• .claude-plugin/marketplace.json at repo root (lists all plugins)
• src/tools/{name}/.claude-plugin/plugin.json for each tool

These must be committed for plugin installation to work.

License

MIT