@orderful/droid 0.32.0 → 0.33.1

package/.claude-plugin/marketplace.json

@@ -22,7 +22,7 @@
     {
       "name": "droid-brain",
       "description": "Your scratchpad (or brain) - a collaborative space for planning and research. Create docs with /brain plan, /brain research, or /brain review. Use @mentions for async discussion. Docs persist across sessions.",
-      "version": "0.3.3",
+      "version": "0.3.5",
       "source": {
         "source": "github",
         "repo": "orderful/droid",
@@ -35,7 +35,7 @@
     {
       "name": "droid-coach",
       "description": "Learning-mode AI assistance - AI as coach, not crutch. Use /coach plan for co-authored planning, /coach scaffold for structure with hints, /coach review for Socratic questions.",
-      "version": "0.2.1",
+      "version": "0.2.3",
       "source": {
         "source": "github",
         "repo": "orderful/droid",
@@ -48,7 +48,7 @@
     {
       "name": "droid-code-review",
       "description": "Comprehensive code review using specialized agents. Reviews PRs, staged changes, branches, or specific files with confidence scoring.",
-      "version": "0.2.1",
+      "version": "0.2.2",
       "source": {
         "source": "github",
         "repo": "orderful/droid",
@@ -61,7 +61,7 @@
     {
       "name": "droid-codex",
       "description": "Shared organizational knowledge - PRDs, tech designs, domains, proposals, patterns, and explored topics. Use when loading project context, searching codex, capturing decisions, or creating new entries.",
-      "version": "0.1.9",
+      "version": "0.1.10",
       "source": {
         "source": "github",
         "repo": "orderful/droid",
@@ -74,7 +74,7 @@
     {
       "name": "droid-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.3.1",
+      "version": "0.3.3",
       "source": {
         "source": "github",
         "repo": "orderful/droid",
@@ -84,10 +84,23 @@
         "name": "Orderful"
       }
     },
+    {
+      "name": "droid-plan",
+      "description": "Task-scoped planning with portable, structured plans. Use when planning implementation for a PR, ticket, or small feature. User prompts like 'let's plan this', 'can we start a plan', 'think through the implementation'.",
+      "version": "0.1.0",
+      "source": {
+        "source": "github",
+        "repo": "orderful/droid",
+        "path": "src/tools/plan"
+      },
+      "author": {
+        "name": "Orderful"
+      }
+    },
     {
       "name": "droid-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.3.2",
+      "version": "0.3.3",
       "source": {
         "source": "github",
         "repo": "orderful/droid",
@@ -100,7 +113,7 @@
     {
       "name": "droid-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.1",
+      "version": "0.2.3",
       "source": {
         "source": "github",
         "repo": "orderful/droid",
@@ -113,7 +126,7 @@
     {
       "name": "droid-wrapup",
       "description": "Session wrap-up that captures decisions, learnings, and open items to persistent docs.",
-      "version": "0.1.0",
+      "version": "0.1.2",
       "source": {
         "source": "github",
         "repo": "orderful/droid",

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # @orderful/droid
 
+## 0.33.1
+
+### Patch Changes
+
+- [#202](https://github.com/Orderful/droid/pull/202) [`03f1eb3`](https://github.com/Orderful/droid/commit/03f1eb369b09394fef18376c0c8713a20a737066) Thanks [@frytyler](https://github.com/frytyler)! - fix(wrapup): use unique session ID for temp files
+
+  Session brief files now use a unique timestamp-based ID (e.g., `/tmp/wrapup-20260118-153042.md`)
+  instead of a fixed path. This prevents concurrent sessions from clobbering each other's data.
+
+## 0.33.0
+
+### Minor Changes
+
+- [#199](https://github.com/Orderful/droid/pull/199) [`9416b9c`](https://github.com/Orderful/droid/commit/9416b9c7a0a9f04f34295304fffee9d2d033ee55) Thanks [@frytyler](https://github.com/frytyler)! - feat(tools): add plan tool for task-scoped planning
+
+  New tool for creating structured, portable plans for PRs, tickets, and small features.
+  Lighter-weight than /tech-design, heavier than just doing.
+
+  Commands:
+  - `/plan new {topic}` - Create plan with context loading
+  - `/plan search {topic}` - Find and load existing plan
+  - `/plan check` - Address @droid comments
+  - `/plan ready` - Finalize and validate
+  - `/plan implement` - Execute the plan
+
+### Patch Changes
+
+- [#195](https://github.com/Orderful/droid/pull/195) [`5a02a36`](https://github.com/Orderful/droid/commit/5a02a36b896e2cef5df56b4bbf03b9edf510287f) Thanks [@frytyler](https://github.com/frytyler)! - Add clarification for @mention directionality across all skills that reference comments
+
+  The @mention is the target, not the author:
+  - `> @droid ...` = User asking/telling the AI
+  - `> @user ...` = AI asking/telling the user
+
+  Updated: comments, brain, tech-design, code-review, coach
+
+- [#197](https://github.com/Orderful/droid/pull/197) [`f9949b7`](https://github.com/Orderful/droid/commit/f9949b713602037ca9caa7e1f15b733bef60dadb) Thanks [@frytyler](https://github.com/frytyler)! - Add tech-design and wrapup tools to README
+
+- [#200](https://github.com/Orderful/droid/pull/200) [`012efae`](https://github.com/Orderful/droid/commit/012efae265ef627ab4aaf26cd707c97e00f41570) Thanks [@frytyler](https://github.com/frytyler)! - fix: use `droid config` instead of reading overrides.yaml directly
+
+  All skills now use `droid config <tool>` to get merged configuration instead
+  of reading `~/.droid/skills/<tool>/overrides.yaml` directly. This provides:
+  - Consistent config access across all skills
+  - Global config values (user_mention, ai_mention) automatically included
+  - Single source of truth for configuration logic
+
+  **Updated tools:**
+  - wrapup (v0.1.1): Project file check uses `droid config project`
+  - project (v0.3.3): Removed unsafe defaults, requires explicit `projects_dir`
+  - brain (v0.3.5): All workflows use `droid config brain`
+  - codex (v0.1.10): Uses `droid config codex` for repo path
+  - comments (v0.3.3): Uses `droid config comments` for settings
+  - coach (v0.2.3): Uses `droid config coach` for settings
+  - tech-design (v0.2.3): Checks brain/codex config via `droid config`
+
+  Fixes #198
+
 ## 0.32.0
 
 ### Minor Changes

package/README.md

@@ -65,6 +65,8 @@ Browse available tools, see what's installed, and manage everything from one pla
 | **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 |
 
 ### Comments
 
@@ -106,6 +108,28 @@ Run comprehensive reviews with specialized agents:
 /code-review path/to/file   # Review specific file
 ```
 
+### Tech Design
+
+Three-document approach for technical designs (requires brain + codex):
+
+```bash
+/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:
+
+```bash
+/wrapup                     # Run session wrap-up
+```
+
+Extracts decisions, learnings, and open items to project files and brain docs.
+
 ## Configuration
 
 Config lives in `~/.droid/`:

package/dist/tools/brain/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "droid-brain",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Your scratchpad (or brain) - a collaborative space for planning and research. Create docs with /brain plan, /brain research, or /brain review. Use @mentions for async discussion. Docs persist across sessions.",
   "author": {
     "name": "Orderful",

package/dist/tools/brain/TOOL.yaml

@@ -1,6 +1,6 @@
 name: brain
 description: "Your scratchpad (or brain) - a collaborative space for planning and research. Create docs with /brain plan, /brain research, or /brain review. Use @mentions for async discussion. Docs persist across sessions."
-version: 0.3.3
+version: 0.3.5
 status: beta
 
 includes:

package/dist/tools/brain/skills/brain/SKILL.md

@@ -26,7 +26,7 @@ Your **scratchpad** (or **brain**) - a collaborative space for planning, researc
 
 ## Configuration
 
-**IMPORTANT:** Read `~/.droid/skills/brain/overrides.yaml` first. If `brain_dir` is not configured, **ask the user** where they want brain docs stored.
+**IMPORTANT:** Run `droid config brain` first and parse the JSON output. If `brain_dir` is not configured, **ask the user** where they want brain docs stored.
 
 | Setting        | Default | Description                                |
 | -------------- | ------- | ------------------------------------------ |
@@ -127,10 +127,12 @@ Full procedure: `references/workflows.md` § Finalizing
 
 ## Comment Conventions
 
-In markdown files, use blockquote `>` prefix for @mention comments:
+In markdown files, use blockquote `>` prefix for @mention comments. The @mention is the **target**, not the author:
 
-- `> @droid` - **User** leaves comment for AI to address
-- `> @{user}` - **AI** leaves comment for user
+| Comment        | Author | Target | Meaning                    |
+| -------------- | ------ | ------ | -------------------------- |
+| `> @droid ...` | User   | AI     | User asking/telling the AI |
+| `> @user ...`  | AI     | User   | AI asking/telling the user |
 
 Get `user_mention` from `droid config brain`. If droid's `comments` skill is installed, use `/comments check` for full support.
 

package/dist/tools/brain/skills/brain/references/workflows.md

@@ -9,8 +9,8 @@ Detailed procedures for each brain operation.
 **Steps:**
 
 1. **Read config first (MANDATORY)**
-   - Use the Read tool on `~/.droid/skills/brain/overrides.yaml`
-   - If file exists and contains `brain_dir:`, use that path
+   - Run `droid config brain` and parse the JSON output
+   - Use the `brain_dir` value from the config
    - If `brain_dir` is not configured, **ask the user** where they want brain docs stored
    - **Do NOT skip this step or assume defaults**
 
@@ -48,9 +48,8 @@ Detailed procedures for each brain operation.
 **Steps:**
 
 1. **Read config first (MANDATORY)**
-   - Use the Read tool on `~/.droid/skills/brain/overrides.yaml`
-   - If file exists and contains `brain_dir:`, use that path
-   - Also check for `inbox_folder` setting (e.g., `0-Inbox`)
+   - Run `droid config brain` and parse the JSON output
+   - Use the `brain_dir` and `inbox_folder` values from the config
    - If `brain_dir` is not configured, **ask the user** where they want brain docs stored
    - **Do NOT skip this step or assume defaults**
 
@@ -96,9 +95,8 @@ Detailed procedures for each brain operation.
 **Steps:**
 
 1. **Read config first (MANDATORY)**
-   - Use the Read tool on `~/.droid/skills/brain/overrides.yaml`
-   - If file exists and contains `brain_dir:`, use that path
-   - Also check for `inbox_folder` setting (e.g., `0-Inbox`)
+   - Run `droid config brain` and parse the JSON output
+   - Use the `brain_dir` and `inbox_folder` values from the config
    - If `brain_dir` is not configured, **ask the user** where they want brain docs stored
    - **Do NOT skip this step or assume defaults**
 
@@ -152,6 +150,13 @@ Detailed procedures for each brain operation.
 
 **Prefer `comments` skill:** If the `comments` skill is installed, use `/comments check` instead - it provides better comment detection, cleanup workflows, and supports the full `@droid`/`@user` convention. The workflow below is a fallback for basic comment handling.
 
+**Directionality:** The @mention is the **target**, not the author:
+
+| Comment        | Author | Target | Meaning                    |
+| -------------- | ------ | ------ | -------------------------- |
+| `> @droid ...` | User   | AI     | User asking/telling the AI |
+| `> @user ...`  | AI     | User   | AI asking/telling the user |
+
 **Steps:**
 
 1. **Check for active doc**
@@ -160,8 +165,8 @@ Detailed procedures for each brain operation.
 2. **Read active doc**
 
 3. **Check preserve_comments setting:**
-   - Read `~/.droid/skills/comments/overrides.yaml` if it exists
-   - Look for `preserve_comments` (default: `true`)
+   - Run `droid config comments` and parse the JSON output
+   - Use the `preserve_comments` value (default: `true`)
 
 4. **Find all `> @droid` comments**
    - Pattern: Lines starting with `> @droid` (blockquote with mention)
@@ -211,8 +216,8 @@ Detailed procedures for each brain operation.
 **Steps:**
 
 1. **Read config first (MANDATORY)**
-   - Use the Read tool on `~/.droid/skills/brain/overrides.yaml`
-   - If file exists and contains `brain_dir:`, use that path
+   - Run `droid config brain` and parse the JSON output
+   - Use the `brain_dir` value from the config
    - If `brain_dir` is not configured, **ask the user** where they want brain docs stored
    - **Do NOT skip this step or assume defaults**
 

package/dist/tools/coach/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "droid-coach",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Learning-mode AI assistance - AI as coach, not crutch. Use /coach plan for co-authored planning, /coach scaffold for structure with hints, /coach review for Socratic questions.",
   "author": {
     "name": "Orderful",

package/dist/tools/coach/TOOL.yaml

@@ -1,6 +1,6 @@
 name: coach
 description: "Learning-mode AI assistance - AI as coach, not crutch. Use /coach plan for co-authored planning, /coach scaffold for structure with hints, /coach review for Socratic questions."
-version: 0.2.1
+version: 0.2.3
 status: beta
 
 includes:

package/dist/tools/coach/skills/coach/SKILL.md

@@ -53,10 +53,11 @@ plan → AI scaffolds → human implements → AI coaches → iterate → ship
 | -------------------- | -------- | ------------------------------------------------------- |
 | `scaffold_verbosity` | `medium` | How detailed hints are: `minimal`, `medium`, `detailed` |
 
+<!-- Note: @mention is the target, not author. @fry = AI talking TO user, @droid = user talking TO AI -->
 > @fry Not yet - droid currently shows config as free text input. But we could add an `enum` type to the config schema that presents as a select dropdown in the TUI. Good feature request - want me to create an issue for it?
 > @droid yes lets do that
 
-Read from `~/.droid/skills/coach/overrides.yaml` if present.
+Run `droid config coach` to get the merged configuration.
 
 ---
 

package/dist/tools/code-review/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "droid-code-review",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Comprehensive code review using specialized agents. Reviews PRs, staged changes, branches, or specific files with confidence scoring.",
   "author": {
     "name": "Orderful",

package/dist/tools/code-review/TOOL.yaml

@@ -1,6 +1,6 @@
 name: code-review
 description: "Comprehensive code review using specialized agents. Reviews PRs, staged changes, branches, or specific files with confidence scoring."
-version: 0.2.1
+version: 0.2.2
 status: alpha
 
 includes:

package/dist/tools/code-review/skills/code-review/SKILL.md

@@ -64,7 +64,7 @@ Ask the user: **"Would you like the review results saved to a `/brain review` do
 
 - If yes: Create a brain review doc at the start using `/brain review {PR title or branch name}`
 - The final report will be written to the brain doc instead of just displayed
-- This allows for async discussion via `@droid`/`@{user}` comments
+- This allows for async discussion via `@droid`/`@{user}` comments (the @mention is the **target**: `@droid` = user asking AI, `@user` = AI asking user)
 
 If brain skill is not installed or user declines, proceed with normal terminal output.
 

package/dist/tools/codex/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "droid-codex",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "Shared organizational knowledge - PRDs, tech designs, domains, proposals, patterns, and explored topics. Use when loading project context, searching codex, capturing decisions, or creating new entries.",
   "author": {
     "name": "Orderful",

package/dist/tools/codex/TOOL.yaml

@@ -1,6 +1,6 @@
 name: codex
 description: "Shared organizational knowledge - PRDs, tech designs, domains, proposals, patterns, and explored topics. Use when loading project context, searching codex, capturing decisions, or creating new entries."
-version: 0.1.9
+version: 0.1.10
 status: beta
 
 includes:

package/dist/tools/codex/skills/codex/SKILL.md

@@ -141,7 +141,7 @@ fi
 
 ## Configuration
 
-**ALWAYS read `~/.droid/skills/codex/overrides.yaml` first.**
+**ALWAYS run `droid config codex` first and parse the JSON output.**
 
 | Setting          | Default                           | Description                   |
 | ---------------- | --------------------------------- | ----------------------------- |

package/dist/tools/codex/skills/codex/references/loading.md

@@ -6,7 +6,7 @@ Detailed procedure for loading entries from the codex.
 
 **IMPORTANT:** Use the index file for fast lookups. This avoids expensive file-by-file searching.
 
-1. **Get codex repo path** from `~/.droid/skills/codex/overrides.yaml`
+1. **Get codex repo path** by running `droid config codex` and parsing the JSON output
 2. **Read the index file** at `{codex_repo}/index.yaml`:
    ```yaml
    # index.yaml structure

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

@@ -1,6 +1,6 @@
 {
   "name": "droid-comments",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "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",

package/dist/tools/comments/TOOL.yaml

@@ -1,6 +1,6 @@
 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.3.1
+version: 0.3.3
 status: beta
 
 includes:

package/dist/tools/comments/skills/comments/SKILL.md

@@ -29,16 +29,18 @@ The AI will respond with `> @{user_mention}` (configured in droid setup, e.g., `
 
 **CRITICAL: The `@mention` is who you're talking TO, not who is speaking.**
 
+The directionality can be confusing. The @mention is the **target**, not the author:
+
+| Comment        | Author | Target | Meaning                    |
+| -------------- | ------ | ------ | -------------------------- |
+| `> @droid ...` | User   | AI     | User asking/telling the AI |
+| `> @user ...`  | AI     | User   | AI asking/telling the user |
+
 Think of it like addressing someone in conversation:
 
 - "Hey @droid, what do you think?" → User talking TO the AI
 - "Good point @fry, here's my take..." → AI talking TO the user
 
-| When you see... | Who wrote it | Who it's addressed to |
-| --------------- | ------------ | --------------------- |
-| `> @droid ...`  | User         | AI (droid)            |
-| `> @fry ...`    | AI           | User (fry)            |
-
 **Examples:**
 
 ```markdown
@@ -82,7 +84,7 @@ When you find a `@droid` marker:
 
 #### Pass 1: Read & Analyse
 
-1. **Read config first:** Check `~/.droid/skills/comments/overrides.yaml` for `preserve_comments` setting (default: `true`)
+1. **Read config first:** Run `droid config comments` and check `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
 4. **Read all comments before responding** - understand the full picture
@@ -107,7 +109,7 @@ When you find a `@droid` marker:
 
 ## Configuration
 
-Configured via `~/.droid/skills/comments/overrides.yaml` or inherits from global `~/.droid/config.yaml`:
+Configured via `droid config comments` (merges global config with skill overrides):
 
 ```yaml
 # Override the user mention (default: from global config)

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

@@ -0,0 +1,16 @@
+{
+  "name": "droid-plan",
+  "version": "0.1.0",
+  "description": "Task-scoped planning with portable, structured plans. Use when planning implementation for a PR, ticket, or small feature. User prompts like 'let's plan this', 'can we start a plan', 'think through the implementation'.",
+  "author": {
+    "name": "Orderful",
+    "url": "https://github.com/orderful"
+  },
+  "repository": "https://github.com/orderful/droid",
+  "license": "MIT",
+  "keywords": [
+    "droid",
+    "ai",
+    "plan"
+  ]
+}

package/dist/tools/plan/TOOL.yaml

@@ -0,0 +1,18 @@
+name: plan
+description: "Task-scoped planning with portable, structured plans. Use when planning implementation for a PR, ticket, or small feature. User prompts like 'let's plan this', 'can we start a plan', 'think through the implementation'."
+version: 0.1.0
+status: alpha
+
+includes:
+  skills:
+    - name: plan
+      required: true
+  commands:
+    - name: plan
+      is_alias: false
+
+dependencies:
+  - brain
+  - comments
+
+config_schema: {}

package/dist/tools/plan/commands/plan.md

@@ -0,0 +1,33 @@
+---
+name: plan
+description: "Task-scoped planning with portable, structured plans"
+argument-hint: "new|search|check|ready|implement [topic]"
+---
+
+# /plan
+
+**User invoked:** `/plan $ARGUMENTS`
+
+**Your task:** Invoke the **plan skill** with these arguments.
+
+## Quick Reference
+
+| Command | Action |
+|---------|--------|
+| `/plan new {topic}` | Create new plan, offer context loading |
+| `/plan search {topic}` | Find and load existing plan |
+| `/plan check` | Address @droid comments |
+| `/plan ready` | Finalize and validate |
+| `/plan implement` | Execute the plan |
+
+## Examples
+
+```bash
+/plan new auth-refactor      # Start planning auth refactor
+/plan search rate-limit      # Find existing rate limit plan
+/plan check                  # Address open comments
+/plan ready                  # Mark plan as ready
+/plan implement              # Execute the plan
+```
+
+See the **plan skill** for complete documentation.

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

@@ -0,0 +1,103 @@
+---
+name: plan
+description: "Task-scoped planning with portable, structured plans. Use when planning implementation for a PR, ticket, or small feature. User prompts like 'let's plan this', 'can we start a plan', 'think through the implementation'."
+allowed-tools: [Read, Edit, Write, Glob, Grep, Bash, Task, AskUserQuestion]
+---
+
+# Plan Skill
+
+Task-scoped planning for PRs, tickets, and small features. Lighter than `/tech-design` (epic-level), heavier than just doing.
+
+## When to Use
+
+- Implementation spans multiple files or steps
+- Decisions need documenting before coding
+- Work will span sessions or be handed off
+- User says "let's plan", "think through", "before we start"
+
+## When NOT to Use
+
+- Quick fixes or single-file changes
+- Epic-level work (use `/tech-design` instead)
+- Pure research (use `/brain research` instead)
+
+## Configuration
+
+Uses config from dependencies:
+- `droid config brain` → `brain_dir`, `inbox_dir`
+- `droid config comments` → `user_mention`
+
+## Commands
+
+| Command                | Action                                              |
+| ---------------------- | --------------------------------------------------- |
+| `/plan new {topic}`    | Create plan doc, offer context loading              |
+| `/plan search {topic}` | Find and load existing plan                         |
+| `/plan check`          | Address `@droid` comments, graduate to decisions    |
+| `/plan ready`          | Finalize: validate and update status                |
+| `/plan implement`      | Execute tasks, optionally convert to XML            |
+
+## `/plan new {topic}`
+
+1. Read config (`brain_dir`, `inbox_dir`, `user_mention`)
+2. Determine location:
+   - If `/project` active → offer: `{projects_dir}/{project}/plans/`
+   - Otherwise → `{brain_dir}/{inbox_dir}/plans/`
+3. Offer context loading (`/project`, `/codex` search)
+4. Ask clarifying questions (goal, scope, constraints)
+5. Generate plan from template (see `references/templates.md`)
+6. Set as active plan
+
+## `/plan search {topic}`
+
+1. Search `{brain_dir}/**/plan-*.md` for topic (fuzzy match)
+2. If multiple: prompt user to select
+3. Display summary (status, tasks, open discussions)
+4. Set as active plan
+
+## `/plan check`
+
+1. Find `> @droid` comments in active plan
+2. Address each, respond with `> @{user_mention}`
+3. Ask if resolved → graduate to Locked-In Decisions table
+4. Update the doc
+
+See `references/workflows.md` for graduation pattern.
+
+## `/plan ready`
+
+1. Check for unresolved discussions (warn if any)
+2. Validate required sections (Context, at least one Task)
+3. Update status to `ready`
+4. Offer: stay in brain, copy to PR description, link in project
+
+## `/plan implement`
+
+1. Parse tasks from `### Task N:` sections
+2. Optionally convert to XML (see `references/xml-conversion.md`)
+3. For each task:
+   - Execute per `**Files:**` section
+   - Run `**Verify:**` command
+   - Check `**Done:**` criteria
+   - Mark complete in plan doc
+4. Update status to `done`
+
+## Comment Conventions
+
+| Comment          | Written by | Addressed to |
+| ---------------- | ---------- | ------------ |
+| `> @droid ...`   | User       | AI           |
+| `> @{user} ...`  | AI         | User         |
+
+## Natural Language Triggers
+
+Recognise planning intent and offer `/plan new`:
+- "Can we plan this out?"
+- "Let's think through the implementation"
+- "Before we start coding..."
+
+## References
+
+- `references/templates.md` - Plan doc template with examples
+- `references/workflows.md` - Detailed command flows
+- `references/xml-conversion.md` - XML conversion for `/plan implement`