@orderful/droid 0.2.0 → 0.4.0

package/dist/skills/README.md

@@ -0,0 +1,85 @@
+# Contributing Skills
+
+Skills are reusable AI capabilities that can be installed into Claude Code or OpenCode.
+
+## Directory Structure
+
+Each skill is a directory containing:
+
+```
+skills/
+└── my-skill/
+    ├── SKILL.yaml      # Required: Manifest with metadata
+    ├── SKILL.md        # Required: Instructions for the AI
+    └── commands/       # Optional: Slash commands
+        └── my-command.md
+```
+
+## SKILL.yaml (Manifest)
+
+```yaml
+name: my-skill                          # Must match directory name
+description: Short description          # Shown in TUI and listings
+version: 1.0.0                          # Semver
+status: beta                            # alpha | beta | stable (optional)
+dependencies: []                        # Other skills required (optional)
+provides_output: false                  # Can this skill be an output target?
+
+# Configuration schema (optional)
+config_schema:
+  option_name:
+    type: string                        # string | boolean
+    description: What this option does
+    default: "default value"            # Optional default
+
+# Examples shown in TUI (optional)
+examples:
+  - title: "Example name"
+    code: |
+      // Example code block
+```
+
+## SKILL.md (AI Instructions)
+
+The SKILL.md file contains instructions for the AI. It must have YAML frontmatter:
+
+```markdown
+---
+name: my-skill
+description: Short description (must match SKILL.yaml)
+globs:
+  - "**/*"                              # File patterns this skill applies to
+alwaysApply: false                      # Always include in context?
+---
+
+# My Skill
+
+Instructions for the AI on how to use this skill...
+```
+
+## Commands (Optional)
+
+Commands are slash commands the user can invoke. Each is a markdown file:
+
+```
+commands/
+└── do-thing.md
+```
+
+The command file is just markdown instructions. The filename becomes the command name (`/do-thing`).
+
+## Testing Your Skill
+
+1. Run `npm run build` to compile
+2. Run `droid` to open the TUI
+3. Navigate to Skills tab
+4. Install your skill
+5. Test in Claude Code with `/your-command` or by referencing the skill
+
+## Checklist
+
+- [ ] `SKILL.yaml` has all required fields (name, description, version)
+- [ ] `SKILL.md` has valid YAML frontmatter
+- [ ] Name in frontmatter matches directory name
+- [ ] Description matches between SKILL.yaml and SKILL.md
+- [ ] Tests pass: `bun test src/lib/skills.test.ts`

package/dist/skills/comments/SKILL.md

@@ -1,3 +1,11 @@
+---
+name: comments
+description: Inline conversation in any file via @droid/@user markers
+globs:
+  - "**/*"
+alwaysApply: false
+---
+
 # Comments Skill
 
 Enable inline conversation in any file using `> @droid` and `> @{user}` markers.

package/dist/skills/comments/SKILL.yaml

@@ -16,3 +16,35 @@ config_schema:
     type: boolean
     description: Keep original comments after addressing (vs removing them)
     default: false
+examples:
+  - title: "Action request"
+    code: |
+      // @droid use PascalCase for enum keys
+      enum Status {
+        PENDING = 'pending'
+      }
+  - title: "Ask a question"
+    code: |
+      > @droid Should we cache this?
+
+      > @fry Yes, add Redis caching here...
+  - title: "TODO with context"
+    code: |
+      // @droid TODO: refactor to async/await
+      // The callback pattern is unwieldy
+      function fetchData(callback) {
+        api.get('/data', callback);
+      }
+  - title: "Code review note"
+    code: |
+      // @droid potential memory leak here
+      // Clear interval on unmount?
+      useEffect(() => {
+        setInterval(poll, 1000);
+      }, []);
+  - title: "Multi-line discussion"
+    code: |
+      > @droid Best approach for pagination?
+      > We have ~10k records.
+
+      > @fry Use cursor-based, limit 50.

package/dist/skills/comments/commands/README.md

@@ -0,0 +1,58 @@
+# Contributing Commands
+
+Commands are slash commands that users invoke in Claude Code or OpenCode. They're bundled with skills.
+
+## Location
+
+Commands live in a `commands/` subdirectory within a skill:
+
+```
+skills/
+└── my-skill/
+    ├── SKILL.yaml
+    ├── SKILL.md
+    └── commands/
+        ├── README.md       # This file
+        ├── check.md        # /check command
+        └── cleanup.md      # /cleanup command
+```
+
+## Command File Format
+
+Each command is a simple markdown file. The filename (without `.md`) becomes the command name.
+
+**Example: `commands/check.md`**
+
+```markdown
+Scan the codebase for @droid comments and address each one.
+
+## Behavior
+
+1. Search for `> @droid` markers in files
+2. For each comment found:
+   - If it's an action request → execute and remove
+   - If it's a question → respond with `> @{user_mention}`
+
+## Arguments
+
+- `{path}` - Optional path to scope the search (default: current directory)
+
+## Examples
+
+- `/comments check` - Check all files
+- `/comments check src/` - Check only src directory
+```
+
+## Naming Convention
+
+Commands are namespaced by skill. If your skill is `comments`, your commands become:
+
+- `commands/check.md` → `/comments check`
+- `commands/cleanup.md` → `/comments cleanup`
+
+## Best Practices
+
+1. **Be specific** - Describe exactly what the command does
+2. **Include examples** - Show common usage patterns
+3. **Document arguments** - List any parameters the command accepts
+4. **Explain behavior** - Break down the steps the AI should follow

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orderful/droid",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "AI workflow toolkit for sharing skills, commands, and agents across the team",
   "type": "module",
   "bin": {
@@ -8,7 +8,7 @@
   },
   "main": "dist/index.js",
   "scripts": {
-    "build": "tsc && cp -r src/skills dist/",
+    "build": "tsc && cp -r src/skills dist/ && cp -r src/agents dist/",
     "dev": "tsc --watch",
     "start": "bun dist/bin/droid.js",
     "test": "bun test src/",
@@ -36,21 +36,34 @@
   "engines": {
     "node": ">=18.0.0"
   },
+  "publishConfig": {
+    "access": "public",
+    "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",
+    "ink-select-input": "^6.2.0",
+    "ink-text-input": "^6.0.0",
     "inquirer": "^9.2.15",
     "ora": "^8.0.1",
+    "react": "^19.2.1",
     "yaml": "^2.4.1"
   },
   "devDependencies": {
     "@changesets/changelog-github": "^0.5.2",
     "@changesets/cli": "^2.29.8",
     "@types/bun": "latest",
+    "@types/ink-text-input": "^2.0.5",
     "@types/inquirer": "^9.0.7",
     "@types/node": "^20.11.24",
+    "@types/react": "^19.2.7",
     "@typescript-eslint/eslint-plugin": "^8.49.0",
     "@typescript-eslint/parser": "^8.49.0",
+    "esbuild": "^0.27.1",
     "eslint": "^8.57.0",
     "prettier": "^3.2.5",
     "typescript": "^5.4.2"

package/src/agents/README.md

@@ -0,0 +1,137 @@
+# Contributing Agents
+
+Agents are specialized AI personas with specific expertise or roles. They augment the AI's capabilities for particular tasks.
+
+## Directory Structure
+
+Each agent is a directory containing:
+
+```
+agents/
+└── my-agent/
+    ├── AGENT.yaml      # Required: Manifest with metadata and persona
+    └── AGENT.md        # Required: Documentation for users
+```
+
+## AGENT.yaml (Manifest)
+
+```yaml
+name: my-agent                          # Must match directory name
+description: Short description          # Shown in TUI and listings
+version: 1.0.0                          # Semver
+status: alpha                           # alpha | beta | stable (optional)
+
+# Agent type (required)
+mode: subagent                          # primary | subagent | all
+
+# Tools this agent can use (optional)
+tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+
+# Suggested triggers - phrases that might invoke this agent
+triggers:
+  - "review my code"
+  - "check for bugs"
+
+# Persona - system prompt additions for this agent (used if AGENT.md is minimal)
+persona: |
+  You are a specialized assistant focused on...
+
+  Your priorities are:
+  1. First priority
+  2. Second priority
+
+  Always be specific and constructive.
+```
+
+### Agent Modes
+
+- **`primary`** - Main agents you interact with directly. Cycle through them with Tab key.
+- **`subagent`** - Specialized helpers invoked via @mention (e.g., `@code-reviewer check this`) or by primary agents.
+- **`all`** - Agent works as both primary and subagent.
+
+## AGENT.md (Documentation)
+
+The AGENT.md file documents the agent for users:
+
+```markdown
+---
+name: my-agent
+description: Short description (must match AGENT.yaml)
+---
+
+# My Agent
+
+Description of what this agent does and when to use it.
+
+## What It Does
+
+- Bullet points of capabilities
+- What it focuses on
+- What it ignores
+
+## Usage
+
+Examples of how to invoke or use this agent.
+
+## Output Format
+
+Description of how the agent formats its responses.
+```
+
+## Example Agent
+
+See `code-reviewer/` for a complete example:
+
+- Reviews code for bugs, security issues, style
+- Categorizes issues by severity (critical/warning/suggestion)
+- References specific file and line numbers
+
+## Ideas for Agents
+
+- **test-writer** - Generates unit tests for code
+- **doc-writer** - Writes documentation and comments
+- **refactorer** - Suggests and applies refactoring patterns
+- **security-auditor** - Deep security analysis
+- **performance-optimizer** - Identifies performance bottlenecks
+
+## Installation
+
+When you install an agent via the TUI, droid:
+
+1. Reads `AGENT.yaml` for metadata (name, description, tools)
+2. Reads `AGENT.md` for the agent's instructions/persona
+3. Combines them into a single `.md` file with frontmatter
+4. Writes to `~/.claude/agents/{name}.md`
+
+The installed format matches what Claude Code expects:
+
+```markdown
+---
+name: my-agent
+description: Short description
+tools: Read, Glob, Grep, Bash
+---
+
+[Content from AGENT.md]
+```
+
+## Testing Your Agent
+
+1. Run `npm run build` to compile
+2. Run `droid` to open the TUI
+3. Navigate to Agents tab
+4. Verify your agent appears with correct metadata
+5. Install and verify it appears in `~/.claude/agents/`
+
+## Checklist
+
+- [ ] `AGENT.yaml` has all required fields (name, description, version, mode)
+- [ ] `AGENT.md` contains the agent's instructions/persona
+- [ ] Name matches directory name
+- [ ] Description is clear and concise
+- [ ] Mode is appropriate (subagent for specialized tasks, primary for main assistants)
+- [ ] Tools list only includes what the agent needs

package/src/bin/droid.ts

@@ -7,6 +7,7 @@ import { skillsCommand } from '../commands/skills.js';
 import { installCommand } from '../commands/install.js';
 import { uninstallCommand } from '../commands/uninstall.js';
 import { updateCommand } from '../commands/update.js';
+import { tuiCommand } from '../commands/tui.js';
 import { getVersion, checkForUpdates } from '../lib/version.js';
 
 const version = getVersion();
@@ -52,7 +53,17 @@ program
   .argument('[skill]', 'Update a specific skill')
   .action(updateCommand);
 
+program
+  .command('tui')
+  .description('Launch interactive TUI dashboard')
+  .action(tuiCommand);
+
 // Check for updates on any command (non-blocking)
 checkForUpdates().catch(() => {});
 
-program.parse();
+// If no command provided, launch TUI
+if (process.argv.length === 2) {
+  tuiCommand();
+} else {
+  program.parse();
+}

package/src/commands/setup.ts

@@ -1,10 +1,24 @@
 import inquirer from 'inquirer';
 import chalk from 'chalk';
 import { execSync } from 'child_process';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
 import { loadConfig, saveConfig, configExists } from '../lib/config.js';
 import { getBundledSkills } from '../lib/skills.js';
 import { AITool, BuiltInOutput, type DroidConfig, type OutputPreference } from '../lib/types.js';
 
+/**
+ * Permissions droid needs to operate without constant prompts
+ */
+const DROID_PERMISSIONS = [
+  'Read(~/.droid/**)',
+  'Write(~/.droid/**)',
+  'Edit(~/.droid/**)',
+  'Glob(~/.droid/**)',
+  'Grep(~/.droid/**)',
+];
+
 /**
  * Detect which AI tool is installed
  */
@@ -37,6 +51,60 @@ function detectGitUsername(): string {
   }
 }
 
+/**
+ * Configure AI tool permissions for droid
+ */
+export function configureAIToolPermissions(aiTool: AITool): { added: string[]; alreadyPresent: boolean } {
+  const added: string[] = [];
+
+  if (aiTool === AITool.ClaudeCode) {
+    const settingsPath = join(homedir(), '.claude', 'settings.json');
+
+    // Ensure .claude directory exists
+    const claudeDir = join(homedir(), '.claude');
+    if (!existsSync(claudeDir)) {
+      mkdirSync(claudeDir, { recursive: true });
+    }
+
+    // Load or create settings
+    let settings: { permissions?: { allow?: string[]; deny?: string[]; ask?: string[] } } = {};
+    if (existsSync(settingsPath)) {
+      try {
+        settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+      } catch {
+        // Invalid JSON, start fresh
+        settings = {};
+      }
+    }
+
+    // Ensure permissions structure exists
+    if (!settings.permissions) {
+      settings.permissions = {};
+    }
+    if (!Array.isArray(settings.permissions.allow)) {
+      settings.permissions.allow = [];
+    }
+
+    // Add missing permissions
+    for (const perm of DROID_PERMISSIONS) {
+      if (!settings.permissions.allow.includes(perm)) {
+        settings.permissions.allow.push(perm);
+        added.push(perm);
+      }
+    }
+
+    // Save if we added anything
+    if (added.length > 0) {
+      writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+    }
+
+    return { added, alreadyPresent: added.length === 0 };
+  }
+
+  // OpenCode - TODO: implement when we know the settings path
+  return { added: [], alreadyPresent: true };
+}
+
 /**
  * Get available output options (built-in + skills that provide output)
  */
@@ -145,5 +213,14 @@ export async function setupCommand(): Promise<void> {
   saveConfig(config);
 
   console.log(chalk.green('\n✓ Config saved to ~/.droid/config.yaml'));
+
+  // Configure AI tool permissions
+  const { added, alreadyPresent } = configureAIToolPermissions(answers.ai_tool);
+  if (added.length > 0) {
+    console.log(chalk.green(`✓ Added droid permissions to ${answers.ai_tool} settings`));
+  } else if (alreadyPresent) {
+    console.log(chalk.gray(`  Droid permissions already configured in ${answers.ai_tool}`));
+  }
+
   console.log(chalk.gray('\nRun `droid skills` to browse and install skills.'));
 }