@orderful/droid 0.50.0 → 0.52.0

package/.claude-plugin/plugin.json

@@ -28,6 +28,7 @@
     "./src/tools/pii/skills/pii/SKILL.md",
     "./src/tools/plan/skills/plan/SKILL.md",
     "./src/tools/project/skills/project/SKILL.md",
+    "./src/tools/propose-plan/skills/propose-plan/SKILL.md",
     "./src/tools/release/skills/release/SKILL.md",
     "./src/tools/share/skills/share/SKILL.md",
     "./src/tools/status-update/skills/status-update/SKILL.md",

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @orderful/droid
 
+## 0.52.0
+
+### Minor Changes
+
+- [#320](https://github.com/Orderful/droid/pull/320) [`89e37e0`](https://github.com/Orderful/droid/commit/89e37e03899ce34d01de09ed43ad2fff2c171af8) Thanks [@frytyler](https://github.com/frytyler)! - Add `propose-plan` tool — structured plans with evidence and actions for human-in-the-loop approval
+
+### Patch Changes
+
+- [#318](https://github.com/Orderful/droid/pull/318) [`87bb797`](https://github.com/Orderful/droid/commit/87bb797bb1cd53d89c4a946401abdb9210542eab) Thanks [@frytyler](https://github.com/frytyler)! - Add `--tool` flag to `droid pack` for single-tool downloads
+
+## 0.51.0
+
+### Minor Changes
+
+- [#315](https://github.com/Orderful/droid/pull/315) [`71ea142`](https://github.com/Orderful/droid/commit/71ea14245f3a2339a3b0e1fb3bf816df669405af) Thanks [@frytyler](https://github.com/frytyler)! - Project tool improvements: project-aware routing for plan/brain skills, `/project pull` and `/project push` for bidirectional codex sync
+
+### Patch Changes
+
+- [#313](https://github.com/Orderful/droid/pull/313) [`82d14c3`](https://github.com/Orderful/droid/commit/82d14c3a60f5935829d5a3cfbaf583d9a1f4329d) Thanks [@frytyler](https://github.com/frytyler)! - Plan tool improvements: plan mode review in `/plan implement` (with `--no-review` escape hatch), cleanup folded into `/plan ready`, plan mode integration guidance
+
 ## 0.50.0
 
 ### Minor Changes

package/dist/bin/droid.js

@@ -5215,7 +5215,7 @@ function collectToolArtifacts(tool) {
     }
     const refsDir = join14(skillDir, "references");
     if (existsSync12(refsDir)) {
-      const refFiles = readdirSync7(refsDir).filter((f) => f.endsWith(".md"));
+      const refFiles = readdirSync7(refsDir).filter((f) => !f.startsWith("."));
       for (const file of refFiles) {
         artifacts.push({
           sourcePath: join14(refsDir, file),
@@ -5269,9 +5269,9 @@ function generateClaudeMd(tools) {
   lines.push("");
   return lines.join("\n");
 }
-function generateReadme(audience, tools) {
+function generateReadme(label, tools) {
   const lines = [
-    `# Droid Pack: ${audience}`,
+    `# Droid Pack: ${label}`,
     "",
     "This pack contains AI skills, commands, and agents for Claude Desktop.",
     "",
@@ -5317,6 +5317,49 @@ function checkDependencies(tools) {
   }
   return warnings;
 }
+async function buildToolPack(options) {
+  const { toolName, outputDir } = options;
+  const allTools = getBundledTools();
+  const tool = allTools.find((t) => t.name === toolName);
+  if (!tool) {
+    return {
+      success: false,
+      message: `Tool '${toolName}' not found`
+    };
+  }
+  const tools = [tool];
+  const warnings = checkDependencies(tools);
+  const filename = `droid-${toolName}.zip`;
+  const outputPath = join14(outputDir, filename);
+  return new Promise((resolve) => {
+    const output = createWriteStream(outputPath);
+    const archive = archiver("zip", { zlib: { level: 9 } });
+    output.on("close", () => {
+      resolve({
+        success: true,
+        message: `Pack created: ${filename}`,
+        outputPath,
+        toolCount: 1,
+        warnings: warnings.length > 0 ? warnings : void 0
+      });
+    });
+    archive.on("error", (err) => {
+      resolve({
+        success: false,
+        message: `Failed to create pack: ${err.message}`
+      });
+    });
+    archive.pipe(output);
+    const artifacts = collectToolArtifacts(tool);
+    for (const artifact of artifacts) {
+      const content = readFileSync11(artifact.sourcePath, "utf-8");
+      archive.append(content, { name: artifact.zipPath });
+    }
+    archive.append(generateClaudeMd(tools), { name: "CLAUDE.md" });
+    archive.append(generateReadme(toolName, tools), { name: "README.md" });
+    archive.finalize();
+  });
+}
 async function buildPack(options) {
   const { audience, outputDir } = options;
   const tools = getToolsForAudience(audience);
@@ -5381,9 +5424,34 @@ async function packCommand(audience, options) {
     console.log("");
     return;
   }
+  if (options.tool) {
+    const outputDir2 = options.output || process.cwd();
+    console.log(
+      chalk10.bold(`
+Packing tool ${chalk10.cyan(options.tool)}...`)
+    );
+    const result2 = await buildToolPack({ toolName: options.tool, outputDir: outputDir2 });
+    if (!result2.success) {
+      console.error(chalk10.red(`
+${result2.message}`));
+      process.exit(1);
+    }
+    console.log(chalk10.green(`
+${result2.message}`));
+    console.log(chalk10.gray(`  Output: ${result2.outputPath}`));
+    if (result2.warnings && result2.warnings.length > 0) {
+      console.log(chalk10.yellow("\nWarnings:"));
+      for (const warning of result2.warnings) {
+        console.log(chalk10.yellow(`  - ${warning}`));
+      }
+    }
+    console.log("");
+    return;
+  }
   if (!audience) {
     console.error(chalk10.red("\nError: audience argument required"));
     console.log(chalk10.gray("Usage: droid pack <audience>"));
+    console.log(chalk10.gray("       droid pack --tool <name>"));
     console.log(chalk10.gray("       droid pack --list"));
     process.exit(1);
   }
@@ -6051,7 +6119,7 @@ program.command("install <tool>").description("Install a tool and run its setup
 program.command("uninstall <tool>").description("Uninstall a tool").action(uninstallCommand);
 program.command("update").description("Update droid and installed tools").option("--tools", "Only update tools").option("--cli", "Only update the CLI").argument("[tool]", "Update a specific tool").action(updateCommand);
 program.command("tui").description("Launch interactive TUI dashboard").action(tuiCommand);
-program.command("pack").description("Create audience-filtered zip packs for distribution").argument("[audience]", "Target audience (e.g., engineering, customer-support)").option("-l, --list", "List available audiences and tool counts").option("-o, --output <dir>", "Output directory (default: cwd)").action(packCommand);
+program.command("pack").description("Create zip packs for distribution").argument("[audience]", "Target audience (e.g., engineering, customer-support)").option("-l, --list", "List available audiences and tool counts").option("-t, --tool <name>", "Pack a single tool by name").option("-o, --output <dir>", "Output directory (default: cwd)").action(packCommand);
 program.command("exec <tool> <script>").description("Execute a tool script").argument("[args...]", "Arguments to pass to the script").allowUnknownOption().action(execCommand);
 var integrations = program.command("integrations").description("Manage external service integrations");
 var integrationsSetup = integrations.command("setup").description("Set up an integration");

package/dist/commands/pack.d.ts

@@ -1,5 +1,6 @@
 export declare function packCommand(audience: string | undefined, options: {
     list?: boolean;
     output?: string;
+    tool?: string;
 }): Promise<void>;
 //# sourceMappingURL=pack.d.ts.map

package/dist/commands/pack.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pack.d.ts","sourceRoot":"","sources":["../../src/commands/pack.ts"],"names":[],"mappings":"AAQA,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,OAAO,EAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAC3C,OAAO,CAAC,IAAI,CAAC,CAiEf"}
+{"version":3,"file":"pack.d.ts","sourceRoot":"","sources":["../../src/commands/pack.ts"],"names":[],"mappings":"AAQA,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,OAAO,EAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAC1D,OAAO,CAAC,IAAI,CAAC,CA+Ff"}

package/dist/lib/pack.d.ts

@@ -8,6 +8,10 @@ export interface PackOptions {
     audience: ToolAudience;
     outputDir: string;
 }
+export interface ToolPackOptions {
+    toolName: string;
+    outputDir: string;
+}
 export interface PackResult {
     success: boolean;
     message: string;
@@ -24,6 +28,10 @@ export declare function getToolsForAudience(audience: ToolAudience): ToolManifes
  * Get audience info for all audiences that have tools
  */
 export declare function getAudienceInfo(): AudienceInfo[];
+/**
+ * Build a zip pack for a single tool
+ */
+export declare function buildToolPack(options: ToolPackOptions): Promise<PackResult>;
 /**
  * Build a zip pack for the given audience
  */

package/dist/lib/pack.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pack.d.ts","sourceRoot":"","sources":["../../src/lib/pack.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,SAAS,CAAC;AAE1D,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,YAAY,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,YAAY,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,YAAY,GACrB,YAAY,EAAE,CAehB;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,YAAY,EAAE,CAsBhD;AA4JD;;GAEG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CA4DzE"}
+{"version":3,"file":"pack.d.ts","sourceRoot":"","sources":["../../src/lib/pack.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,SAAS,CAAC;AAE1D,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,YAAY,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,YAAY,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,YAAY,GACrB,YAAY,EAAE,CAehB;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,YAAY,EAAE,CAsBhD;AA4JD;;GAEG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC,CAqDjF;AAED;;GAEG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CA4DzE"}

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

@@ -1,6 +1,6 @@
 {
   "name": "droid-brain",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "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.4.2
+version: 0.4.3
 status: beta
 audience:
   - all

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

@@ -34,6 +34,8 @@ Your **scratchpad** (or **brain**) - a collaborative space for planning, researc
 | `inbox_folder` | (empty) | Root folder for new docs (e.g., `0-Inbox`) |
 | `override`     | (none)  | User-defined behaviour overrides |
 
+**Optional dependency:** `droid config --get tools.project` → `save_related_in_project` (for project-aware routing)
+
 **If not configured:** Ask the user:
 > "Where would you like to store brain docs? Common choices:
 > - `~/Documents/brain` - Easy to find in Finder
@@ -107,6 +109,8 @@ Full procedure: `references/workflows.md` § Opening
 
 Templates vary by category (see `references/templates.md`), but all follow the same creation flow.
 
+**Project-aware routing:** When a `/project` is active and `save_related_in_project` is true (check `droid config --get tools.project`), ALL new docs route to `{project_folder}/{category}s/` instead of the brain inbox — no category filtering. Plans, research, ideas, thoughts, spikes, whatever the user creates. If it's related to the project, it lives with the project. Disable with `save_related_in_project: false` in project config.
+
 **Note:** `idea` category docs do NOT become active (fire-and-forget capture).
 
 Full procedure: `references/workflows.md` § Creating

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

@@ -62,13 +62,27 @@ Detailed procedures for each brain operation.
    - Example: `auth-refactor.md` or `caching-strategies.md`
 
 3. **Determine target path based on category:**
-   - Base: `{brain_dir}/{inbox_folder}` (or just `{brain_dir}` if no inbox_folder)
-   - Category becomes plural folder: `{base}/{category}s/{filename}`
-   - Examples:
-     - `plan` → `{base}/plans/{filename}`
-     - `research` → `{base}/research/{filename}`
-     - `spike` → `{base}/spikes/{filename}`
-     - `meeting` → `{base}/meetings/{filename}`
+
+   a. **Check for active project:**
+      - If `/project` is active in session AND `save_related_in_project` is true
+        (run `droid config --get tools.project` to check):
+        - Route ALL categories to project folder: `{projects_dir}/{project}/{category}s/{filename}`
+        - No category filtering — plans, research, ideas, thoughts, spikes, anything goes
+        - Example: `/brain research caching` with project "droid" active
+          → `{projects_dir}/droid/research/caching.md`
+        - Example: `/brain idea wild-thought` with project "droid" active
+          → `{projects_dir}/droid/ideas/wild-thought.md`
+      - If `/project` active but `save_related_in_project` is false (default), OR no project active:
+        - Fall through to default routing below
+
+   b. **Default routing (no active project or opt-out):**
+      - Base: `{brain_dir}/{inbox_folder}` (or just `{brain_dir}` if no inbox_folder)
+      - Category becomes plural folder: `{base}/{category}s/{filename}`
+      - Examples:
+        - `plan` → `{base}/plans/{filename}`
+        - `research` → `{base}/research/{filename}`
+        - `spike` → `{base}/spikes/{filename}`
+        - `meeting` → `{base}/meetings/{filename}`
 
 4. **Create directory** if needed (category folder may not exist yet)
 

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

@@ -1,6 +1,6 @@
 {
   "name": "droid-plan",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "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",

package/dist/tools/plan/TOOL.yaml

@@ -1,6 +1,6 @@
 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.6
+version: 0.1.8
 status: alpha
 audience:
   - engineering

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

@@ -19,7 +19,7 @@ argument-hint: "new|search|check|cleanup|ready|implement [topic]"
 | `/plan check` | Address @droid comments |
 | `/plan cleanup` | Resolve threads, log decisions |
 | `/plan ready` | Finalize and validate |
-| `/plan implement` | Execute the plan |
+| `/plan implement` | Review plan, then execute |
 
 ## Examples
 
@@ -29,7 +29,8 @@ argument-hint: "new|search|check|cleanup|ready|implement [topic]"
 /plan check                  # Address open comments
 /plan cleanup                # Resolve threads, log decisions
 /plan ready                  # Mark plan as ready
-/plan implement              # Execute the plan
+/plan implement              # Review plan, then execute
+/plan implement --no-review  # Skip review, execute directly
 ```
 
 See the **plan skill** for complete documentation.

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

@@ -27,6 +27,7 @@ Task-scoped planning for PRs, tickets, and small features. Lighter than `/tech-d
 Uses config from dependencies:
 - `droid config --get tools.brain` → `brain_dir`, `inbox_folder`
 - `droid config --get user_mention` → `user_mention` (global config)
+- `droid config --get tools.project` → `save_related_in_project` (optional, for project-aware routing)
 
 **Overrides:** This skill supports user-defined overrides. See `/droid` skill § Skill Overrides.
 
@@ -45,7 +46,7 @@ Example: `/plan new auth-refactor -- we must stay backward compatible with v1 cl
 | `/plan check`          | Address `@droid` comments, respond to questions     |
 | `/plan cleanup`        | Resolve threads, apply changes, log decisions       |
 | `/plan ready`          | Finalize: validate and update status                |
-| `/plan implement`      | Execute tasks, optionally convert to XML            |
+| `/plan implement`      | Review plan, then execute tasks                     |
 
 ## `/plan new {topic}`
 
@@ -54,7 +55,8 @@ Example: `/plan new auth-refactor -- we must stay backward compatible with v1 cl
    - Run `droid config --get user_mention` for user's mention tag
    - If `brain_dir` not configured, ask user where to store plans
 2. Determine location:
-   - If `/project` active → offer: `{projects_dir}/{project}/plans/`
+   - If `/project` active AND `save_related_in_project` is true (check `droid config --get tools.project`) → use `{projects_dir}/{project}/plans/` (no prompt)
+   - If `/project` active AND `save_related_in_project` is false (default) → offer choice between project folder and inbox
    - Otherwise → `{brain_dir}/{inbox_folder}/plans/`
 3. Offer context loading (`/project`, `/codex` search)
 4. Ask clarifying questions (goal, scope, constraints)
@@ -90,21 +92,26 @@ See `references/workflows.md` § Cleanup for the full 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
+1. **Run cleanup pass** — graduate resolved threads to decisions, archive (same as `/plan cleanup`)
+2. Check for unresolved discussions (warn if any)
+3. Validate required sections (Context, at least one Task)
+4. Update status to `ready`
+5. 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:
+1. Load plan (warn if status is not `ready`)
+2. **Review plan** — validate tasks against codebase, identify gaps (uses platform plan mode if available, otherwise structured self-review)
+3. Parse tasks from `### Task N:` sections
+4. Optionally convert to XML (see `references/xml-conversion.md`)
+5. For each task:
    - Execute per `**Files:**` section
    - Run `**Verify:**` command
    - Check `**Done:**` criteria
    - Mark complete in plan doc
-4. Update status to `done`
+6. Update status to `done`
+
+Use `--no-review` to skip the review step (e.g., re-running after partial implementation).
 
 ## Comment Conventions
 
@@ -122,6 +129,20 @@ Recognise planning intent and offer `/plan new`:
 - "Let's think through the implementation"
 - "Before we start coding..."
 
+## Plan Review Integration
+
+Plan docs and the review step in `/plan implement` are complementary:
+
+| Plan doc (persistent) | Review step (ephemeral) |
+|-----------------------|-------------------------|
+| Captures decisions and intent (*why*) | Validates against codebase (*how*) |
+| Shareable, auditable trail | Private to the session |
+| Survives across sessions | Scoped to current session |
+
+**The workflow:** Write the plan doc to capture decisions. The review step validates and refines before implementing — it enriches, not duplicates.
+
+**Platform-adaptive:** Some platforms offer a dedicated plan/review mode (e.g., Claude Code). Others get a structured self-review. The behaviour is the same — validate the plan against the codebase before executing.
+
 ## References
 
 - `references/templates.md` - Plan doc template with examples

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

@@ -15,9 +15,15 @@ If brain not configured, ask user for `brain_dir` location.
 
 ### Step 2: Determine Location
 
-Check if `/project` is active (check `{projects_dir}/{project}/PROJECT.md` exists):
+Check if `/project` is active (check `{projects_dir}/{project}/PROJECT.md` exists) and read `save_related_in_project` from `droid config --get tools.project`:
 
-**If project active:**
+**If project active AND `save_related_in_project` is true:**
+```
+Use: {projects_dir}/{project}/plans/plan-{topic}.md
+(No prompt — project folder is the default when opted in)
+```
+
+**If project active AND `save_related_in_project` is false (default):**
 ```
 Offer choice via AskUserQuestion:
 - "Project folder" → {projects_dir}/{project}/plans/plan-{topic}.md
@@ -221,13 +227,18 @@ Report what was cleaned up:
 
 If no active plan, prompt to search for one.
 
-### Step 2: Check Unresolved Discussions
+### Step 2: Run Cleanup Pass
 
-Search for `### Open:` sections:
+Run the same logic as `/plan cleanup`:
+- Find resolved `@droid` / `@{user_mention}` threads
+- Graduate decisions to the Locked-In Decisions table
+- Archive resolved threads to Discussion Log
 
-```bash
-grep -c "### Open:" {plan_path}
-```
+If nothing to clean up, this is a no-op. `/plan cleanup` still exists as a standalone command for mid-iteration use.
+
+### Step 3: Check Unresolved Discussions
+
+Search for remaining `@droid` / `@{user_mention}` threads that weren't resolved:
 
 If any found, warn:
 ```
@@ -236,7 +247,7 @@ If any found, warn:
 - "Mark ready anyway" → Continue
 ```
 
-### Step 3: Validate Required Sections
+### Step 4: Validate Required Sections
 
 Check for:
 - `## Context` section with content
@@ -244,11 +255,11 @@ Check for:
 
 If missing, warn and list what's needed.
 
-### Step 4: Update Status
+### Step 5: Update Status
 
 Change `**Status:** draft` or `**Status:** in-progress` to `**Status:** ready`
 
-### Step 5: Offer Distribution
+### Step 6: Offer Distribution
 
 Ask via AskUserQuestion:
 ```
@@ -271,7 +282,26 @@ Check status - warn if not `ready`:
 "This plan is still '{status}'. Implement anyway?"
 ```
 
-### Step 2: Parse Tasks
+### Step 2: Plan Review
+
+**Default behaviour.** Skip if user passes `--no-review` (or says "skip review", "just implement").
+
+Review the plan against the codebase before executing:
+
+1. **Read each task's `**Files:**` section** — verify referenced files and patterns exist in the codebase
+2. **Check for gaps** — missing files, outdated patterns, unaccounted dependencies between tasks
+3. **Validate `**Verify:**` commands** — confirm they're runnable
+4. **Note concerns or refinements** — anything that needs adjusting before execution
+
+If the platform supports a dedicated plan/review mode, use it for this step. Otherwise, perform the review inline as a structured self-review before proceeding.
+
+**Plan preservation:** If the review produces material refinements, save the revised plan as `{original-name}-implementation.md` alongside the original. The original plan is **never modified** during review — it's the decision record. The implementation variant includes `Parent plan: [[{original-name}]]` at the top.
+
+After review, implementation executes from whichever plan came out of this step:
+- No material changes → execute from the original
+- Revised plan produced → execute from the `-implementation` variant
+
+### Step 3: Parse Tasks
 
 Find all `### Task N:` sections. For each, extract:
 - **Name** from header
@@ -280,7 +310,7 @@ Find all `### Task N:` sections. For each, extract:
 - **Verify** from `**Verify:**` line
 - **Done** from `**Done:**` line
 
-### Step 3: Optional XML Conversion
+### Step 4: Optional XML Conversion
 
 For complex multi-task plans, offer:
 ```
@@ -289,7 +319,7 @@ For complex multi-task plans, offer:
 - "No" → Use markdown as-is
 ```
 
-### Step 4: Execute Tasks
+### Step 5: Execute Tasks
 
 For each task in order:
 
@@ -308,7 +338,7 @@ If verification fails:
 - "Stop implementation"
 ```
 
-### Step 5: Update Status
+### Step 6: Update Status
 
 When all tasks complete, change `**Status:** ready` to `**Status:** done`
 

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

@@ -1,6 +1,6 @@
 {
   "name": "droid-project",
-  "version": "0.4.0",
+  "version": "0.5.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",

package/dist/tools/project/TOOL.yaml

@@ -1,6 +1,6 @@
 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.4.0
+version: 0.5.0
 status: beta
 audience:
   - all
@@ -21,6 +21,10 @@ config_schema:
     type: string
     description: Path to projects directory (required - no default)
     required: true
+  save_related_in_project:
+    type: boolean
+    description: "When true, plan/brain skills default to saving artifacts under the active project folder"
+    default: false
   preset:
     type: select
     description: "Link style: obsidian uses [[wikilinks]], markdown uses [standard](links)"

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

@@ -1,7 +1,7 @@
 ---
 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?'."
-argument-hint: "[{keywords} | update | create {name}]"
+argument-hint: "[search {keywords} | update | create {name} | pull [codex:{name}] | push [codex:{name}]]"
 allowed-tools: [Read, Write, Glob, Grep, Bash]
 ---
 
@@ -32,6 +32,7 @@ Chat history disappears. Projects persist.
 | -------------- | ------------ | -------------------------------------------------- |
 | `projects_dir` | **required** | Where projects are stored (must be configured)     |
 | `preset`       | `markdown`   | Link style: `obsidian` uses `[[wikilinks]]`, `markdown` uses `[standard](links)` |
+| `save_related_in_project` | `false` | When true, plan/brain skills default to saving artifacts under the active project folder instead of the brain inbox |
 | `override`     | (none)       | User-defined behaviour overrides                   |
 
 **Overrides:** This skill supports user-defined overrides. See `/droid` skill § Skill Overrides.
@@ -58,9 +59,17 @@ echo "projects_dir: /path/to/projects" >> ~/.droid/skills/project/overrides.yaml
 | `/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                       |
+| `/project pull [codex:{name}]`        | Pull codex updates into existing project               |
+| `/project push [codex:{name}]`        | Push team-relevant content to codex via PR             |
 
 **IMPORTANT:** Use `/project search {keywords}` to find and load existing projects. Only use `/project create {name}` when the user explicitly wants to create a new project.
 
+## PROJECT.md Frontmatter
+
+| Field            | Purpose                                                              |
+| ---------------- | -------------------------------------------------------------------- |
+| `codex_project`  | Codex project name for pull/push (set on first use, remembered)      |
+
 ## Loading a Project
 
 **Trigger:** `/project search {keywords}` or user asks to load/open a project
@@ -86,6 +95,28 @@ Full procedure: `references/updating.md`
 Version rules: `references/versioning.md`
 Changelog format: `references/changelog.md`
 
+## Pulling from Codex
+
+**Trigger:** `/project pull [codex:{name}]`
+
+**TLDR:** Read codex project docs, diff against current PROJECT.md, propose only critical updates that fit within context limits, apply with changelog entry.
+
+First use: `/project pull codex:transaction-templates` — saves `codex_project` to frontmatter.
+Subsequent: `/project pull` — reads from frontmatter.
+
+Full procedure: `references/pulling.md`
+
+## Pushing to Codex
+
+**Trigger:** `/project push` or user asks to push learnings to codex
+
+**TLDR:** Extract team-relevant decisions, patterns, and architecture updates from PROJECT.md. Propose codex updates via PR.
+
+First use: `/project push codex:transaction-templates` — saves `codex_project` to frontmatter.
+Subsequent: `/project push` — reads from frontmatter. Either push or pull can set it first.
+
+Full procedure: `references/pushing.md`
+
 ## Creating a Project
 
 **Trigger:** `/project create {name?}` or user asks to start a new project

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

@@ -34,6 +34,7 @@
    - Use project contents for all subsequent work in the session
    - **Do NOT read companion docs by default** — CHANGELOG.md, DECISIONS.md, and WORKLOG.md exist for on-demand lookup only. PROJECT.md already references them; that is enough context.
    - If the user asks about decisions, past work, or history, THEN read the relevant companion doc.
+   - **Cross-skill routing:** When `save_related_in_project` is true (check `droid config --get tools.project`), signal to the session that related artifacts (plans, research, ideas) should default to `{project_folder}/plans/`, `{project_folder}/research/`, etc. Other skills (plan, brain) check for an active project and route accordingly.
 
 7. **If `-- {instruction}` provided:** Execute the follow-up instruction against the loaded project