@orderful/droid 0.32.0 → 0.33.1

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

@@ -6,10 +6,10 @@
 
 ## Procedure
 
-1. **Determine projects directory (pick ONE)**
-   - Read `~/.droid/skills/project/overrides.yaml`
-   - If `projects_dir` is set → use ONLY that path, do NOT search defaults
-   - If not configured → use default for current AI tool (`~/.claude/projects` or `~/.config/opencode/projects`)
+1. **Determine projects directory**
+   - Run `droid config project` and parse the JSON output
+   - Use the `projects_dir` value
+   - If not configured → inform user to create `~/.droid/skills/project/overrides.yaml` with `projects_dir: /path/to/projects`
 
 2. **List projects** in the single configured directory
    - Each subfolder with a `PROJECT.md` is a project

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

@@ -1,6 +1,6 @@
 {
   "name": "droid-tech-design",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "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",

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

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

package/dist/tools/tech-design/skills/tech-design/SKILL.md

@@ -28,8 +28,8 @@ The `/tech-design` skill brings tech design authoring into the same AI-augmented
 
 Before using tech-design, verify:
 
-1. **Brain skill configured:** Check if `~/.droid/skills/brain/overrides.yaml` exists
-2. **Codex skill configured:** Check if `~/.droid/skills/codex/overrides.yaml` exists
+1. **Brain skill configured:** Run `droid config brain` and check if `brain_dir` is set
+2. **Codex skill configured:** Run `droid config codex` and check if `codex_repo` is set
 3. **gh CLI:** Required for PR workflows
 
 If prerequisites fail, guide user to configure:
@@ -65,7 +65,7 @@ Tech-design has no configuration of its own. It delegates to:
 2. **Thought doc** = Design workspace
    - References research doc for context
    - Focuses on architectural decisions
-   - Iterates with `@droid`/`@user` comments
+   - Iterates with `@droid`/`@user` comments (the @mention is the **target**: `@droid` = user asking AI, `@user` = AI asking user)
    - Captures the "why" behind choices
 
 3. **Roll-up** = Reviewer artifact

package/dist/tools/tech-design/skills/tech-design/references/publish.md

@@ -25,7 +25,7 @@ if [ ! -f "$research_doc_path" ]; then
 fi
 
 # Codex repo must be configured (read from codex skill config)
-codex_repo=$(grep '^codex_repo:' ~/.droid/skills/codex/overrides.yaml | cut -d' ' -f2-)
+codex_repo=$(droid config codex | grep -o '"codex_repo": *"[^"]*"' | cut -d'"' -f4)
 if [ -z "$codex_repo" ]; then
   echo "Error: Codex not configured."
   echo "Set up with: /codex"

package/dist/tools/tech-design/skills/tech-design/references/start.md

@@ -12,8 +12,8 @@
 
 Check that required tools are configured:
 
-- **Brain skill:** Check if `~/.droid/skills/brain/overrides.yaml` exists
-- **Codex skill:** Check if `~/.droid/skills/codex/overrides.yaml` exists
+- **Brain skill:** Run `droid config brain` and check if `brain_dir` is set
+- **Codex skill:** Run `droid config codex` and check if `codex_repo` is set
 
 If prerequisites fail, guide user to configure:
 

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

@@ -1,6 +1,6 @@
 {
   "name": "droid-wrapup",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Session wrap-up that captures decisions, learnings, and open items to persistent docs.",
   "author": {
     "name": "Orderful",

package/dist/tools/wrapup/TOOL.yaml

@@ -1,6 +1,6 @@
 name: wrapup
 description: "Session wrap-up that captures decisions, learnings, and open items to persistent docs."
-version: 0.1.0
+version: 0.1.2
 status: alpha
 
 includes:

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

@@ -15,7 +15,7 @@ To avoid triggering compaction mid-wrapup, offload heavy lifting to fresh-contex
 
 ## Phase 1: Quick Context Extraction
 
-You have the conversation history. Quickly extract and write to `/tmp/wrapup-session-brief.md`:
+You have the conversation history. Generate a unique session ID (e.g., timestamp like `20260118-153042`) and write to `/tmp/wrapup-{session-id}.md`:
 
 ```markdown
 # Session Brief
@@ -41,9 +41,11 @@ You have the conversation history. Quickly extract and write to `/tmp/wrapup-ses
 
 Do this IMMEDIATELY. Don't analyse deeply—just dump what you know.
 
+**Important:** Remember your session brief path for Phase 2 subagents.
+
 ## Phase 2: Artifact Analysis
 
-Spawn subagents **in parallel** to analyse artifacts. Each reads your session brief and analyses one area.
+Spawn subagents **in parallel** to analyse artifacts. Pass your session brief path to each subagent.
 
 | Subagent | Type | Analyses |
 |----------|------|----------|

package/dist/tools/wrapup/skills/wrapup/references/subagent-prompts.md

@@ -2,6 +2,8 @@
 
 Detailed prompts for Phase 2 artifact analysis. Spawn these in parallel using the Task tool.
 
+**Note:** Replace `{session_brief_path}` with the actual path from Phase 1 (e.g., `/tmp/wrapup-20260118-153042.md`).
+
 ## Git State Analysis
 
 **Subagent type:** Bash
@@ -24,21 +26,27 @@ Output format:
 
 ## Project File Check
 
-**Subagent type:** Explore
+**Subagent type:** Bash
 
 ```
-Read /tmp/wrapup-session-brief.md for session context.
+Read {session_brief_path} for session context.
 
-Check if ~/.droid/project.md exists. If it does:
-1. Read the current project file
-2. Compare against session brief
-3. Identify:
+First, run `droid config project` to get the project skill configuration.
+Parse the JSON output to find the `projects_dir` value.
+
+If `projects_dir` is not set, skip project file analysis.
+
+If configured:
+1. Search the projects directory for recently modified PROJECT.md files (last 7 days)
+2. Read the most recently modified project file
+3. Compare against session brief
+4. Identify:
    - Stale entries that should be updated or removed
    - New items from the session to add (decisions, blockers, next steps)
    - Status changes (completed items, new blockers)
 
 Output specific proposed updates with exact text to add/change.
-If no project file exists, note that and skip.
+If no active project found, note that and skip.
 ```
 
 ## Brain Doc Check
@@ -46,9 +54,9 @@ If no project file exists, note that and skip.
 **Subagent type:** Explore
 
 ```
-Read /tmp/wrapup-session-brief.md for session context.
+Read {session_brief_path} for session context.
 
-First, check ~/.droid/skills/brain/overrides.yaml for the brain_dir setting.
+First, run `droid config brain` and parse the JSON output for the `brain_dir` setting.
 If not configured, skip brain doc analysis.
 
 If configured:
@@ -68,9 +76,9 @@ Output:
 **Subagent type:** Explore
 
 ```
-Read /tmp/wrapup-session-brief.md for session context.
+Read {session_brief_path} for session context.
 
-Check if the codex skill is installed (~/.droid/skills/codex/overrides.yaml).
+Run `droid config codex` and check if `codex_repo` is set.
 If not configured, skip codex analysis.
 
 If the session involved:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orderful/droid",
-  "version": "0.32.0",
+  "version": "0.33.1",
   "description": "AI workflow toolkit for sharing skills, commands, and agents across the team",
   "type": "module",
   "bin": {

package/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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`