@orderful/droid 0.25.2 → 0.27.0

package/{dist/tools/codex/skills/droid-codex → src/tools/codex/skills/codex}/references/loading.md

@@ -36,6 +36,7 @@ Detailed procedure for loading entries from the codex.
    - Multiple matches → show list with category, let user pick
 
 **Fallback:** If `index.yaml` doesn't exist, fall back to directory scanning:
+
 ```bash
 ls {codex_repo}/projects/ | grep -i {name}
 ls {codex_repo}/domains/ | grep -i {name}
@@ -59,11 +60,11 @@ projects/transaction-templates/
 
 CONTEXT.md is the **first layer** - a synthesised summary that's enough for most queries. Only load full documents when deeper detail is needed.
 
-| Layer | What | When to use |
-|-------|------|-------------|
-| 1 | CONTEXT.md (~2KB) | General questions, getting oriented, "what is this project?" |
-| 2 | Specific file | Deep dives - "show me the full technical architecture" |
-| 3 | All files | Comprehensive review, major updates, onboarding |
+| Layer | What              | When to use                                                  |
+| ----- | ----------------- | ------------------------------------------------------------ |
+| 1     | CONTEXT.md (~2KB) | General questions, getting oriented, "what is this project?" |
+| 2     | Specific file     | Deep dives - "show me the full technical architecture"       |
+| 3     | All files         | Comprehensive review, major updates, onboarding              |
 
 ### Procedure
 
@@ -71,6 +72,7 @@ CONTEXT.md is the **first layer** - a synthesised summary that's enough for most
 2. **Check for CONTEXT.md:**
 
    **If CONTEXT.md exists:**
+
    ```
    📂 Loading transaction-templates
 
@@ -85,6 +87,7 @@ CONTEXT.md is the **first layer** - a synthesised summary that's enough for most
    - TECH-DESIGN.md - Architecture and implementation
    - DECISIONS.md - Decision log
    ```
+
    Load CONTEXT.md automatically. Only load additional files if user asks.
 
    **If no CONTEXT.md:**
@@ -125,83 +128,116 @@ topics/organization-hierarchy.md
 
 ## Auto-Generating CONTEXT.md
 
-If loading a project and no CONTEXT.md exists, generate it **asynchronously** so the user isn't blocked.
+If loading a project and no CONTEXT.md exists, generate it immediately.
 
 **User sees:**
+
 ```
 📂 Loading transaction-templates
 
-No CONTEXT.md found - I'll generate one in the background.
-Meanwhile, which file do you want to load?
+No CONTEXT.md found - generating summary from available artifacts...
 
-Available files:
-- PRD.md - Full requirements and goals
-- TECH-DESIGN.md - Architecture and implementation
-- DECISIONS.md - Decision log
+Reading PRD.md...
+  → Extracting problem statement, goals, success metrics
+Reading TECH-DESIGN.md...
+  → Extracting architecture overview, key decisions
+Reading DECISIONS.md...
+  → Extracting decision log summary
+
+Synthesising unified context...
 ```
 
 **Procedure:**
 
+Generate CONTEXT.md either synchronously or asynchronously:
+
+### Option A: Synchronous (works everywhere)
+
+1. **Inform user:** "No CONTEXT.md found - generating summary from available artifacts"
+2. **Read all available files:** PRD.md, TECH-DESIGN.md, DECISIONS.md
+3. **Generate unified summary** (see template below)
+4. **Create PR** (see git workflow below)
+5. **Output the new CONTEXT.md** with "need more detail?" options
+
+### Option B: Asynchronous (Claude Code only, optional)
+
 1. **Spawn background agent** to synthesize CONTEXT.md (non-blocking):
    ```
-   Use Task tool with subagent_type: "general-purpose" and run_in_background: true
+   Use Task tool with subagent_type: "general" and run_in_background: true
    Prompt: "Generate CONTEXT.md for {project} from PRD.md, TECH-DESIGN.md, DECISIONS.md. Create branch, commit, open PR."
    ```
 2. **Immediately ask user** which file to load (don't wait for synthesis)
 3. **Load selected file** and continue working
 4. **When background agent completes**, inform user: "CONTEXT.md ready - PR #{number}"
 
-### Background Agent Task
+**Choose whichever approach works best.** Synchronous is simpler and works everywhere. Asynchronous avoids blocking but requires background agent support.
 
-The background agent should:
+### CONTEXT.md Template
 
-1. **Read all available files:** PRD.md, TECH-DESIGN.md, DECISIONS.md
-2. **Generate unified summary:**
-   ```markdown
-   ---
-   title: {Project Name}
-   type: context
-   created: {today}
-   updated: {today}
-   confidence: high
-   source: implementation
-   ---
+Generate a unified summary from the project files:
 
-   # {Project Name} - Context
+```markdown
+---
+title: { Project Name }
+type: context
+created: { today }
+updated: { today }
+confidence: high
+source: implementation
+---
 
-   ## Overview
-   {Synthesised from PRD problem statement + goals}
+# {Project Name} - Context
 
-   ## Technical Approach
-   {Synthesised from TECH-DESIGN architecture + key decisions}
+## Overview
 
-   ## Key Decisions
-   {Summarised from DECISIONS.md}
+{Synthesised from PRD problem statement + goals}
 
-   ## Current Status
-   {Inferred from most recent updates}
+## Technical Approach
 
-   ---
-   *Auto-generated from PRD.md, TECH-DESIGN.md, and DECISIONS.md*
-   ```
-4. **Create PR:**
-   ```bash
-   cd {codex_repo}
-   git checkout -b auto/context-{project-name}
-   # Write CONTEXT.md
-   git add projects/{project}/CONTEXT.md
-   git commit -F - <<EOF
-   feat: auto-generate CONTEXT.md for {project}
-   EOF
-   git push -u origin auto/context-{project-name}
-   gh pr create --title "Auto-generated CONTEXT.md for {project}" --body "Synthesised from PRD, TECH-DESIGN, and DECISIONS."
-   ```
-5. **Return result** (background agent outputs to task output file):
-   ```
-   ✅ CONTEXT.md synthesised and PR #{number} created for {project}
-   ```
+{Synthesised from TECH-DESIGN architecture + key decisions}
+
+## Key Decisions
+
+{Summarised from DECISIONS.md}
 
-   The main conversation will be notified when the background task completes.
+## Current Status
+
+{Inferred from most recent updates}
+
+---
+
+_Auto-generated from PRD.md, TECH-DESIGN.md, and DECISIONS.md_
+```
+
+### Git Workflow for CONTEXT.md
+
+After generating the CONTEXT.md content:
+
+```bash
+cd {codex_repo}
+git checkout -b auto/context-{project-name}
+# Write CONTEXT.md to projects/{project}/CONTEXT.md
+git add projects/{project}/CONTEXT.md
+git commit -F - <<EOF
+feat: auto-generate CONTEXT.md for {project}
+EOF
+git push -u origin auto/context-{project-name}
+gh pr create --title "Auto-generated CONTEXT.md for {project}" --body "Synthesised from PRD, TECH-DESIGN, and DECISIONS."
+```
+
+Then inform the user:
+
+```
+✅ CONTEXT.md created and PR #{number} opened
+
+[Show CONTEXT.md content]
+
+---
+Need more detail? Available files:
+- PRD.md - Full requirements and goals
+- TECH-DESIGN.md - Architecture and implementation
+- DECISIONS.md - Decision log
+```
 
 ## Freshness Checking
 
@@ -219,16 +255,19 @@ After loading any file:
      Want me to verify it's still accurate?
      ```
 4. **Check codebase changes** (if `codebase_paths` present):
+
    ```bash
    cd {workspace}
    git log --oneline --since="{updated}" -- {codebase_paths}
    ```
+
    - If commits found:
      ```
      ⚠️ Files in {paths} have changed since this doc was updated.
      Recent commits: {list}
      Want me to review for needed updates?
      ```
+
 5. **Note confidence** (if `confidence: low`):
    ```
    ℹ️ This was a quick exploration and may be incomplete.

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

@@ -0,0 +1,16 @@
+{
+  "name": "droid-comments",
+  "version": "0.3.0",
+  "description": "Enable inline conversations using @droid/@user markers. Tag @droid to ask the AI, AI responds with @{your-name}. Use /comments check to address markers, /comments cleanup to remove resolved threads. Ideal for code review notes and async collaboration.",
+  "author": {
+    "name": "Orderful",
+    "url": "https://github.com/orderful"
+  },
+  "repository": "https://github.com/orderful/droid",
+  "license": "MIT",
+  "keywords": [
+    "droid",
+    "ai",
+    "comments"
+  ]
+}

package/src/tools/comments/TOOL.yaml

@@ -1,14 +1,15 @@
 name: comments
 description: "Enable inline conversations using @droid/@user markers. Tag @droid to ask the AI, AI responds with @{your-name}. Use /comments check to address markers, /comments cleanup to remove resolved threads. Ideal for code review notes and async collaboration."
-version: 0.2.6
+version: 0.3.0
 status: beta
 
 includes:
   skills:
-    - name: droid-comments
+    - name: comments
       required: true
   commands:
-    - comments
+    - name: comments
+      is_alias: false
   agents: []
 
 dependencies: []

package/src/tools/comments/commands/comments.md

@@ -1,29 +1,27 @@
 ---
-description: Check and respond to inline @droid comments in code and docs
+name: comments
+description: "Check and respond to inline @droid comments in code and docs"
 argument-hint: "[check [{path}] | cleanup]"
-allowed-tools: Read, Edit, Grep, Glob, Bash(git diff:*), Bash(git status:*)
 ---
 
-# /comments - Check and respond to inline comments
+# /comments
 
-Entry point for inline comment workflows. See the **comments skill** for full behavior.
+**User invoked:** `/comments $ARGUMENTS`
 
-## Arguments
+**Your task:** Invoke the **comments skill** with these arguments.
 
-$ARGUMENTS
+## Examples
 
-## Usage
+- `/comments` → Check all files in current directory for @droid markers
+- `/comments check src/lib` → Check specific directory for @droid markers
+- `/comments cleanup` → Remove resolved comment threads
+
+## Quick Reference
 
 ```
 /comments              # Check all files in cwd
-/comments check        # Same as above
 /comments check {path} # Check specific file or directory
 /comments cleanup      # Remove resolved comment threads
 ```
 
-## Behavior
-
-Refer to the comments skill for:
-- **Check**: How to find markers, determine intent (action vs question), respond appropriately
-- **Cleanup**: How to identify resolved threads and summarize decisions
-- **Configuration**: `user_mention`, `ai_mentions`, `preserve_comments` settings
+See the **comments skill** for complete documentation and procedures.

package/{dist/tools/comments/skills/droid-comments → src/tools/comments/skills/comments}/SKILL.md

@@ -1,10 +1,10 @@
 ---
-name: droid-comments
+name: comments
 description: "Inline conversations using @droid/@user markers in any file. Use when leaving async questions in code or having discussion that should stay near the code. User prompts like 'check for comments', 'address the @droid markers', 'clean up resolved comments'."
 globs:
   - "**/*"
 alwaysApply: false
-allowed-tools: Read, Grep, Glob, Edit
+allowed-tools: [Read, Grep, Glob, Edit]
 ---
 
 # Comments Skill
@@ -83,6 +83,7 @@ When you find a `@droid` marker:
 **Use a two-pass approach for coherent responses:**
 
 #### Pass 1: Read & Analyse
+
 1. **Read config first:** Check `~/.droid/skills/comments/overrides.yaml` for `preserve_comments` setting (default: `true`)
 2. Search for ALL `> @droid` comments (and any configured `ai_mentions`) in the specified scope
 3. If there's a `git diff`, check those files first for relevant context
@@ -91,6 +92,7 @@ When you find a `@droid` marker:
 6. Note any contradictions or tensions to address
 
 #### Pass 2: Respond & Write
+
 1. For each comment, determine intent:
    - **Action request** ("do X", "add Y", "fix Z") → Execute the action
    - **Question** ("what do you think", "should we") → Respond with `> @{user_mention}`

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

@@ -0,0 +1,15 @@
+{
+  "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.",
+  "author": {
+    "name": "Orderful",
+    "url": "https://github.com/orderful"
+  },
+  "repository": "https://github.com/orderful/droid",
+  "license": "MIT",
+  "keywords": [
+    "droid",
+    "ai"
+  ]
+}

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.2.1
+version: 0.4.0
 status: beta
 
 # System tool - always stays current regardless of auto-update settings

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

@@ -4,7 +4,7 @@ description: "Core droid meta-skill for updates and tool discovery. Use when che
 globs:
   - "**/*"
 alwaysApply: false
-allowed-tools: Bash
+allowed-tools: [Bash]
 ---
 
 # Droid

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

@@ -0,0 +1,16 @@
+{
+  "name": "droid-project",
+  "version": "0.3.0",
+  "description": "Manage project context files for persistent AI memory across sessions. Load, update, or create project context before working on multi-session features.",
+  "author": {
+    "name": "Orderful",
+    "url": "https://github.com/orderful"
+  },
+  "repository": "https://github.com/orderful/droid",
+  "license": "MIT",
+  "keywords": [
+    "droid",
+    "ai",
+    "project"
+  ]
+}

package/src/tools/project/TOOL.yaml

@@ -1,14 +1,15 @@
 name: project
 description: "Manage project context files for persistent AI memory across sessions. Load, update, or create project context before working on multi-session features."
-version: 0.2.0
+version: 0.3.0
 status: beta
 
 includes:
   skills:
-    - name: droid-project
+    - name: project
       required: true
   commands:
-    - project
+    - name: project
+      is_alias: false
   agents: []
 
 dependencies: []

package/src/tools/project/commands/project.md

@@ -1,45 +1,30 @@
 ---
-description: Manage project context files for persistent AI memory across sessions
+name: project
+description: "Manage project context files for persistent AI memory across sessions"
 argument-hint: "[{keywords} | update | create {name}]"
-allowed-tools: Read, Write, Edit, Glob, Bash(mkdir:*), Bash(ls:*)
 ---
 
 # /project
 
-Entry point for project context management. See the **project skill** for full behavior.
+**User invoked:** `/project $ARGUMENTS`
 
-## Arguments
+**Your task:** Invoke the **project skill** with these arguments.
 
-$ARGUMENTS
+## Example
 
-## Default Behavior
+If user typed `/project droid`, you should interpret this as: "Search for and load a project matching 'droid'"
 
-**IMPORTANT:** When given keywords (e.g., `/project audit-log`), the default action is to **SEARCH** for existing projects, NOT create. Only create a project when the `create` keyword is explicitly used.
+If user typed `/project create new-feature`, interpret as: "Create a new project named 'new-feature'"
 
-## Usage
+## Quick Reference
 
 ```
 /project                    # List and select a project
-/project {keywords}         # SEARCH: Fuzzy-match and load existing project
+/project {keywords}         # SEARCH for existing project (default action)
 /project update             # Update from conversation context
-/project update {name}      # Update specific project
-/project create             # Create new project interactively
-/project create {name}      # Create with name (requires "create" keyword)
+/project create {name}      # CREATE new project
 ```
 
-## Configuration
+**Default behavior:** When given keywords, SEARCH first (don't create unless "create" keyword is present).
 
-**ALWAYS read `~/.droid/skills/project/overrides.yaml` first.**
-
-- If `projects_dir` is set → use **ONLY** that path (do NOT also search defaults)
-- If not configured → use the default for current AI tool
-- `preset` - Template format: `markdown` or `obsidian`
-
-## Behavior
-
-Refer to the project skill for:
-- **Loading**: How to fuzzy-match, handle multiple matches, summarize after load
-- **Updating**: What to extract from conversation, versioning rules, changelog format
-- **Creating**: Template structure by preset, required files
-
-The skill's `references/` folder contains detailed specs for versioning, changelog formatting, and templates.
+See the **project skill** for complete documentation and procedures.

package/src/tools/project/skills/{droid-project → project}/SKILL.md

@@ -1,10 +1,10 @@
 ---
-name: droid-project
+name: project
 description: "Persistent project context for AI memory across sessions. Use when working on multi-session features, refactors, or any work that benefits from accumulated context. User prompts like 'load the project', 'update project context', 'what's the current project?'."
 globs:
   - "**/PROJECT.md"
 alwaysApply: false
-allowed-tools: Read, Write, Glob, Grep
+allowed-tools: [Read, Write, Glob, Grep]
 ---
 
 # Project Skill
@@ -33,24 +33,25 @@ Chat history disappears. Projects persist.
 - If `projects_dir` is configured → use **ONLY** that path (do NOT also search defaults)
 - If not configured → use the default for current AI tool
 
-| Setting | Default | Description |
-|---------|---------|-------------|
+| Setting        | Default     | Description                                       |
+| -------------- | ----------- | ------------------------------------------------- |
 | `projects_dir` | (see below) | Where projects are stored (use ONE location only) |
-| `preset` | `markdown` | Output format: `markdown` or `obsidian` |
+| `preset`       | `markdown`  | Output format: `markdown` or `obsidian`           |
 
 Default `projects_dir` by AI tool (only if overrides.yaml is missing or lacks `projects_dir`):
+
 - **claude-code**: `~/.claude/projects`
 - **opencode**: `~/.config/opencode/projects`
 
 ## Commands
 
-| Command | Action |
-|---------|--------|
-| `/project` | List and select a project |
-| `/project {keywords}` | **Search** for existing project (fuzzy-match and load) |
-| `/project create {name}` | Create new project (requires `create` keyword) |
-| `/project create --from codex:{name}` | Create project seeded with codex context |
-| `/project update` | Update from conversation context |
+| Command                               | Action                                                 |
+| ------------------------------------- | ------------------------------------------------------ |
+| `/project`                            | List and select a project                              |
+| `/project {keywords}`                 | **Search** for existing project (fuzzy-match and load) |
+| `/project create {name}`              | Create new project (requires `create` keyword)         |
+| `/project create --from codex:{name}` | Create project seeded with codex context               |
+| `/project update`                     | Update from conversation context                       |
 
 **IMPORTANT:** The default action for `/project {keywords}` is to **SEARCH** for existing projects, NOT create. Only use `/project create {name}` when the user explicitly wants to create a new project.
 

package/src/tools/tech-design/.claude-plugin/plugin.json

@@ -0,0 +1,16 @@
+{
+  "name": "droid-tech-design",
+  "version": "0.2.0",
+  "description": "Technical design authoring tool for engineers. Create structured tech design docs with /tech-design start, iterate in brain, publish to codex. Three-document approach: research doc (codebase discoveries) + thought doc (design workspace) + roll-up (clean summary for review).",
+  "author": {
+    "name": "Orderful",
+    "url": "https://github.com/orderful"
+  },
+  "repository": "https://github.com/orderful/droid",
+  "license": "MIT",
+  "keywords": [
+    "droid",
+    "ai",
+    "tech-design"
+  ]
+}

package/src/tools/tech-design/TOOL.yaml

@@ -0,0 +1,19 @@
+name: tech-design
+description: "Technical design authoring tool for engineers. Create structured tech design docs with /tech-design start, iterate in brain, publish to codex. Three-document approach: research doc (codebase discoveries) + thought doc (design workspace) + roll-up (clean summary for review)."
+version: 0.2.0
+status: beta
+
+includes:
+  skills:
+    - name: tech-design
+      required: true
+  commands:
+    - name: tech-design
+      is_alias: false
+  agents: []
+
+dependencies:
+  - brain
+  - codex
+
+config_schema: {}

package/src/tools/tech-design/commands/tech-design.md

@@ -0,0 +1,31 @@
+---
+name: tech-design
+description: "Write, iterate, and publish technical design documents using a three-document approach - research doc, thought doc, and roll-up"
+argument-hint: "[start --from codex:{project} | draft [section] | think [topic] | gaps | publish]"
+---
+
+# /tech-design
+
+**User invoked:** `/tech-design $ARGUMENTS`
+
+**Your task:** Invoke the **tech-design skill** with these arguments.
+
+## Examples
+
+- `/tech-design start --from codex:billing-v2` → Create research + thought docs from codex project
+- `/tech-design draft rollout` → Auto-generate the rollout section
+- `/tech-design think API design` → Guided exploration of API design, update research doc
+- `/tech-design gaps` → Show checklist of missing/empty sections
+- `/tech-design publish` → Generate roll-up and publish to codex
+
+## Quick Reference
+
+```
+/tech-design start --from codex:{project}  # Create research + thought docs
+/tech-design draft [section]               # Auto-generate section
+/tech-design think [topic]                 # Guided exploration
+/tech-design gaps                          # Missing sections checklist
+/tech-design publish                       # Publish to codex
+```
+
+See the **tech-design skill** for complete documentation and procedures.