@orderful/droid 0.37.0 → 0.39.0

package/src/tools/droid/commands/setup.md

@@ -0,0 +1,125 @@
+---
+name: setup
+description: "Configure Droid after marketplace installation"
+argument-hint: ""
+---
+
+# /setup
+
+**User invoked:** `/setup`
+
+**Your task:** Guide the user through initial Droid configuration.
+
+## When to Use
+
+Run this command after installing Droid plugins via the marketplace (when `~/.droid/config.yaml` doesn't exist).
+
+## Configuration Flow
+
+### 1. Check Existing Configuration
+
+```bash
+ls -la ~/.droid/config.yaml 2>/dev/null || echo "No config found"
+```
+
+- If config exists: Ask "You already have a config. Reconfigure? [y/N]"
+- If no config: Proceed with setup
+
+### 2. Create Config Directory
+
+```bash
+mkdir -p ~/.droid
+```
+
+### 3. Detect Git Username
+
+```bash
+git config user.name
+```
+
+Store this for `git_username` in config.
+
+### 4. Gather Global Settings
+
+Ask the user:
+
+> **What handle should be used for @mentions in code comments?**
+> (This is used by the comments tool for async collaboration)
+> Default: `@droid`
+
+### 5. Detect Installed Tools
+
+Check which Droid plugins are installed by looking for skill files:
+
+```bash
+# Check Claude Code skills directory and plugin cache
+ls ~/.claude/skills/ 2>/dev/null | grep -E '^(brain|project|codex|wrapup|code-review|tech-design|comments|coach|plan)-' || true
+find ~/.claude/plugins/cache -name "SKILL.md" -path "*droid*" 2>/dev/null | head -20 || true
+```
+
+### 6. Configure Tools That Need Settings
+
+For each detected tool that requires configuration:
+
+**brain:**
+> **Where should brain docs be stored?**
+> Default: `~/brain`
+> (This directory will be created if it doesn't exist)
+
+**project:**
+> **Where are your projects located?**
+> Default: `~/Projects`
+> (Used to find and link project-level context)
+
+**codex:**
+> **Where is your shared codex repository?**
+> Default: `~/codex`
+> (Leave blank to skip codex configuration)
+
+### 7. Write Configuration
+
+Create `~/.droid/config.yaml` with the gathered settings:
+
+```yaml
+# Droid global configuration
+# Generated by /setup
+
+user_mention: "@droid"  # Or user's chosen handle
+git_username: "detected-name"
+
+# Tool-specific settings
+brain:
+  brain_dir: "~/brain"
+
+project:
+  projects_dir: "~/Projects"
+
+codex:
+  codex_dir: "~/codex"  # Only if provided
+```
+
+### 8. Confirm Success
+
+Display a summary:
+
+```
+Droid configured successfully!
+
+Global settings:
+  - User mention: @droid
+  - Git username: Your Name
+
+Tool settings:
+  - brain: ~/brain
+  - project: ~/Projects
+  - codex: ~/codex
+
+You can edit these settings anytime at ~/.droid/config.yaml
+```
+
+## Notes
+
+- All paths should be expanded (~ to full home directory) when written
+- Only include tool sections for tools that are actually installed
+- If a required directory doesn't exist, offer to create it
+- Skip tools that aren't installed rather than configuring them

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

@@ -1,7 +1,7 @@
 ---
 name: droid
-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?', 'what tools do you have?', 'remind me what tools you have', 'hey droid what can you do', 'how do I add context?', 'remind me how to use codex', 'what's the best way to start a session?'."
-allowed-tools: [Bash]
+description: "Core droid meta-skill for updates, tool discovery, usage help, and skill overrides. Use when checking for droid updates, discovering available tools, answering 'how do I...' questions about droid workflows, or customizing skill behaviour. User prompts like 'any droid updates?', 'what tools do I have?', 'what tools do you have?', 'remind me what tools you have', 'hey droid what can you do', 'how do I add context?', 'remind me how to use codex', 'what's the best way to start a session?', 'customize brain search', 'create an override for brain'."
+allowed-tools: [Bash, Read, Write]
 ---
 
 # Droid
@@ -87,3 +87,118 @@ When answering "how do I..." questions:
 1. `/project search {name}` - Load working context
 2. `/codex search {topic}` - Find relevant org knowledge (if needed)
 3. Then start working with full context
+
+## Skill Overrides
+
+Users can customize skill behaviour by creating override files in `~/.droid/skill_overrides/`.
+
+**When:** User asks to customize a skill, use a different tool for a command, or mentions overrides.
+
+### Creating an Override
+
+1. **Explain** the override system:
+   - Override files live in `~/.droid/skill_overrides/{skill}.md`
+   - Use YAML frontmatter to declare which commands are overridden
+   - Template available at `~/.droid/skill_overrides/_template.md`
+
+2. **Create** the override file with proper structure:
+   ```markdown
+   ---
+   overrides: [command1, command2]
+   ---
+
+   ## command1
+
+   Custom instructions for this command...
+   ```
+
+3. **Register** the override in config:
+   ```bash
+   # Set override path (use tool name in config path, skill name for file)
+   droid config --set tools.{tool}.override.path="~/.droid/skill_overrides/{skill}.md"
+
+   # Set overridden commands (as JSON array)
+   droid config --set tools.{tool}.override.commands='["command1", "command2"]'
+
+   # Enable the override (can toggle off later)
+   droid config --set tools.{tool}.override.enabled=true
+   ```
+
+   Note: Config uses tool name (e.g., `tools.brain`), file uses skill name. Usually the same, but tools can contain multiple skills.
+
+   **Toggle off:** `droid config --set tools.{tool}.override.enabled=false` to disable without removing.
+
+4. **Confirm** the override is active
+
+### Registering an Existing Override
+
+If user says "I added an override for {tool}" or "register my {tool} override":
+
+1. **Read** `~/.droid/skill_overrides/{skill}.md`
+2. **Parse** YAML frontmatter to extract `overrides: [...]` array
+3. **Register** using the config commands above (with tool name in config path)
+4. **Confirm** registration
+
+### Override Visibility
+
+When an override is active, skills show:
+```
+[override] brain/search → ~/.droid/skill_overrides/brain.md
+```
+
+This helps users know customisation is being used and where to find it.
+
+### Example: qmd for Brain Search
+
+User: "I want brain search to use qmd for semantic search"
+
+Create `~/.droid/skill_overrides/brain.md`:
+```markdown
+---
+overrides: [search]
+---
+
+## search
+
+Use qmd for semantic search instead of filename matching.
+
+**Prerequisites:** qmd installed, brain collection indexed (`qmd index brain -p {brain_dir}`)
+
+**Workflow:**
+
+1. Check if qmd collection exists: `qmd ls brain`
+2. If exists, run: `qmd query "{query}" -c brain -n 10 --files`
+3. Parse CSV output (format: `docid,score,filepath,context`)
+4. Extract filepath (field 3) from each row
+5. Present matches sorted by score
+6. If qmd fails or collection doesn't exist, fall back to Glob: `{brain_dir}/**/*{query}*.md`
+```
+
+Then register:
+```bash
+droid config --set tools.brain.override.path="~/.droid/skill_overrides/brain.md"
+droid config --set tools.brain.override.commands='["search"]'
+droid config --set tools.brain.override.enabled=true
+```
+
+### Override Lookup (for all skills)
+
+When executing any skill command, check for overrides:
+
+1. **Get tool config:** `droid config --get tools.{tool}`
+
+2. **Check if override applies:**
+   - Config has `override` section AND
+   - `override.enabled` is `true` (or not set) AND
+   - `override.commands` includes the current command
+
+3. **If override applies:**
+   - Show: `[override] {skill}/{command} → {override.path}`
+   - Read the override file at `override.path`
+   - Find the `## {command}` section
+   - Follow those instructions instead of default workflow
+   - If override fails or instructions unclear, fall back to default
+
+4. **If no override:** Use default skill behaviour
+
+This lookup is the same for all skills - config is per-tool, but the lookup workflow is universal.

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

@@ -12,5 +12,11 @@
     "droid",
     "ai",
     "plan"
+  ],
+  "skills": [
+    "./skills/plan/SKILL.md"
+  ],
+  "commands": [
+    "./commands/plan.md"
   ]
 }

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

@@ -28,6 +28,8 @@ Uses config from dependencies:
 - `droid config --get tools.brain` → `brain_dir`, `inbox_folder`
 - `droid config --get user_mention` → `user_mention` (global config)
 
+**Overrides:** This skill supports user-defined overrides. See `/droid` skill § Skill Overrides.
+
 ## Commands
 
 | Command                | Action                                              |

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

@@ -12,5 +12,11 @@
     "droid",
     "ai",
     "project"
+  ],
+  "skills": [
+    "./skills/project/SKILL.md"
+  ],
+  "commands": [
+    "./commands/project.md"
   ]
 }

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

@@ -32,6 +32,9 @@ Chat history disappears. Projects persist.
 | -------------- | ------------ | -------------------------------------------------- |
 | `projects_dir` | **required** | Where projects are stored (must be configured)     |
 | `preset`       | `markdown`   | Output format: `markdown` or `obsidian`            |
+| `override`     | (none)       | User-defined behaviour overrides                   |
+
+**Overrides:** This skill supports user-defined overrides. See `/droid` skill § Skill Overrides.
 
 If `projects_dir` is not configured, inform the user they need to set it up:
 ```bash

package/src/tools/status-update/.claude-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "droid-status-update",
+  "version": "0.1.0",
+  "description": "Generate and post project status updates. Aggregates context from codex projects, Jira epics, and manual input. Posts to Slack or prints to terminal.",
+  "author": {
+    "name": "Orderful",
+    "url": "https://github.com/orderful"
+  },
+  "repository": "https://github.com/orderful/droid",
+  "license": "MIT",
+  "keywords": [
+    "droid",
+    "ai",
+    "status-update"
+  ],
+  "skills": [
+    "./skills/status-update/SKILL.md"
+  ],
+  "commands": [
+    "./commands/status-update.md"
+  ]
+}

package/src/tools/status-update/TOOL.yaml

@@ -0,0 +1,21 @@
+name: status-update
+description: "Generate and post project status updates. Aggregates context from codex projects, Jira epics, and manual input. Posts to Slack or prints to terminal."
+version: 0.1.0
+status: beta
+
+includes:
+  skills:
+    - name: status-update
+      required: true
+  commands:
+    - name: status-update
+      is_alias: false
+  agents: []
+
+dependencies: []
+
+config_schema:
+  default_crosspost_channel:
+    type: string
+    description: Default channel for cross-posting updates (e.g., rnd-updates)
+    required: false

package/src/tools/status-update/commands/status-update.md

@@ -0,0 +1,27 @@
+---
+name: status-update
+description: "Generate and post project status updates. Pulls from codex, Jira, and manual input. Posts to Slack or prints to terminal."
+argument-hint: "[{project}]"
+---
+
+# /status-update
+
+**User invoked:** `/status-update $ARGUMENTS`
+
+**Your task:** Invoke the **status-update skill** with these arguments.
+
+## Examples
+
+- `/status-update` → Prompt for project or use active project
+- `/status-update partnership-automation` → Generate update for specific project
+- `/status-update --no-slack` → Generate update but print to terminal instead of posting
+
+## Quick Reference
+
+```
+/status-update                      # Interactive - prompts for everything
+/status-update {project}            # Use codex project for metadata
+/status-update --no-slack           # Output to terminal instead of Slack
+```
+
+See the **status-update skill** for complete documentation.

package/src/tools/status-update/skills/status-update/SKILL.md

@@ -0,0 +1,253 @@
+---
+name: status-update
+description: "Generate and post project status updates. Aggregates context from codex projects, Jira epics, and manual input. Posts to Slack or prints to terminal."
+argument-hint: "[{project}]"
+allowed-tools:
+  [
+    Read,
+    Glob,
+    Grep,
+    Bash(git:*),
+    Bash(curl:*),
+    Bash(droid:*),
+  ]
+---
+
+# Status Update Skill
+
+Generate formatted project status updates from multiple sources and post to Slack (or print to terminal).
+
+## Data Sources (All Optional)
+
+| Source | When available | What it provides |
+|--------|----------------|------------------|
+| **Codex project** | If project name matches a codex project | Metadata (slack, jira, links) + git history |
+| **Jira MCP** | If jira.epic configured + MCP connected | Ticket status for in-flight/up-next drafts |
+| **Manual input** | Always | User-provided status, phase, bullets |
+
+## Output Destinations
+
+| Destination | When available | Fallback |
+|-------------|----------------|----------|
+| **Slack** | If slack.channel configured + SLACK_USER_TOKEN set | Print to terminal |
+
+## Procedure
+
+### 1. Resolve Project Context
+
+**If project name provided:**
+
+1. Check if codex is configured:
+   ```bash
+   droid config --get tools.codex
+   ```
+
+2. If codex configured, look for matching project:
+   ```bash
+   ls {codex_repo}/projects/ | grep -i {project}
+   ```
+
+3. If found, read CONTEXT.md frontmatter:
+   - `title` - Project name
+   - `slack.channel` - Primary Slack channel
+   - `slack.crosspost_channel` - Optional crosspost channel
+   - `slack.canvas_id` - Optional canvas for update log
+   - `jira.epic` - Optional Jira epic key
+   - `links.prd`, `links.tech_design`, `links.figma` - Optional doc links
+
+**If no project name provided:**
+
+1. Check for active project in conversation context
+2. If none, ask: "Which project is this update for?"
+3. If user provides a name, attempt to match to codex project
+4. If no match, continue without codex metadata (prompt for details manually)
+
+**If no codex match:**
+
+Prompt user for:
+- Project name (for display)
+- Slack channel (optional - skip to print to terminal)
+- Jira epic key (optional)
+
+### 2. Generate Draft Content
+
+Attempt to generate draft bullets from available sources.
+
+#### Source A: Codex Git History (if codex project found)
+
+```bash
+git -C {codex_repo} log --oneline --since="7 days ago" -- projects/{project}/
+```
+
+Parse commits to understand recent activity:
+- DECISIONS.md changes → decisions made
+- New artifacts → meetings, documents produced
+- CONTEXT.md changes → project evolution
+- PRD.md/TECH-DESIGN.md changes → documentation progress
+
+Generate human-readable draft bullets from the git history.
+
+#### Source B: Jira MCP (if configured)
+
+**Check MCP availability:**
+```
+mcp__atlassian__getAccessibleAtlassianResources
+```
+
+If available and `jira.epic` is set, run two JQL queries:
+
+1. **Recently completed + in progress:**
+   ```
+   parent = {jira.epic} AND (status changed to Done AFTER -7d OR statusCategory in ("In Progress"))
+   ```
+
+2. **Up next:**
+   ```
+   parent = {jira.epic} AND statusCategory = "To Do"
+   ```
+
+Categorise tickets:
+
+| Jira Status | Category |
+|-------------|----------|
+| Done (last 7 days) | In flight (completed) |
+| In Progress, In Review, In QA | In flight (active) |
+| To Do, Backlog | Up next |
+
+#### Combine Sources
+
+If multiple sources available:
+- Deduplicate where codex change and Jira ticket describe the same work
+- Prefer Jira summaries for ticket-tracked work
+- Include codex-only changes (decisions, meetings) not in Jira
+
+**Present draft to user** for review/editing before finalising.
+
+### 3. Gather Update Content
+
+Ask user for (pre-fill from drafts where available):
+
+1. **Status** - One of:
+   - `on_track` (green) - Everything proceeding as planned
+   - `at_risk` (yellow) - Some concerns or blockers emerging
+   - `blocked` (red) - Cannot proceed without resolution
+
+2. **Current phase** - One of:
+   - `discovery` - Research and requirements gathering
+   - `post_discovery_feedback` - Incorporating discovery feedback
+   - `design` - Prototype and design work
+   - `post_design_feedback` - Incorporating design feedback
+   - `prd` - Writing PRD
+   - `tech_design` - Writing Tech Design
+   - `development` - Active implementation
+   - `qa` - QA & Testing
+   - `release` - Released to production
+
+3. **In flight this week** - Bullet points (from draft or manual)
+
+4. **Up next** - Bullet points (from draft or manual)
+
+### 4. Format Message
+
+See `references/formatting.md` for detailed formatting rules.
+
+**Structure:**
+```
+*Status:* {status_emoji} *{status_text}*
+
+*Where we're at*
+{phase_checklist}
+
+*In flight this week*
+• {bullet 1}
+• {bullet 2}
+
+*Up next*
+• {bullet 1}
+• {bullet 2}
+
+{links_footer if configured}
+
+Posted with help from :droid:
+```
+
+Add ` & :codex:` to footer if codex project was used.
+
+### 5. Output
+
+#### If Slack configured (channel + SLACK_USER_TOKEN):
+
+**Post to primary channel:**
+```bash
+curl -s -X POST https://slack.com/api/chat.postMessage \
+  -H "Authorization: Bearer $SLACK_USER_TOKEN" \
+  -H "Content-Type: application/json; charset=utf-8" \
+  -d '{
+    "channel": "{slack.channel}",
+    "text": "{formatted_message}",
+    "unfurl_links": false
+  }'
+```
+
+Check response for `"ok": true`. Save `ts` and `channel` from response.
+
+**Crosspost (if crosspost_channel configured):**
+
+Post summary version with link to full update:
+```
+*{project_title}*
+
+{status_line}
+{current_phase_only}
+
+{in_flight_section}
+
+:link: <{message_url}|View full update>
+```
+
+Message URL format: `https://orderful.slack.com/archives/{channel_id}/p{ts_without_dot}`
+
+**Update canvas log (if canvas_id configured):**
+```bash
+curl -s -X POST https://slack.com/api/canvases.edit \
+  -H "Authorization: Bearer $SLACK_USER_TOKEN" \
+  -H "Content-Type: application/json; charset=utf-8" \
+  -d '{
+    "canvas_id": "{slack.canvas_id}",
+    "changes": [{
+      "operation": "insert_at_start",
+      "document_content": {
+        "type": "markdown",
+        "markdown": "### {date}\n{status} · {current_phase}\n[View update]({message_url})\n\n---"
+      }
+    }]
+  }'
+```
+
+**Confirm to user:**
+- "Posted update to #{channel}"
+- "Cross-posted to #{crosspost_channel}" (if applicable)
+- "Added to canvas log" (if applicable)
+
+#### If Slack NOT configured:
+
+Print the formatted message to terminal.
+
+Tell user: "Slack not configured. To post updates directly, add `slack.channel` to your project's CONTEXT.md and set `SLACK_USER_TOKEN` in your environment."
+
+### Error Handling
+
+| Error | Action |
+|-------|--------|
+| No SLACK_USER_TOKEN | Print to terminal, suggest setup |
+| Slack API error | Show error, offer to print instead |
+| Jira MCP not available | Skip Jira, continue with other sources |
+| No codex project found | Continue with manual input |
+
+## Configuration
+
+No required configuration. Optional settings via `droid config`:
+
+| Setting | Description |
+|---------|-------------|
+| `default_crosspost_channel` | Default channel for cross-posts if not in project metadata |