@orderful/droid 0.50.0 → 0.51.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @orderful/droid
 
+## 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/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
 

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

@@ -0,0 +1,57 @@
+# Pulling from Codex
+
+**Trigger:** `/project pull [codex:{name}]`
+
+Pull shared organizational context into an existing local project.
+
+## Procedure
+
+1. **Resolve codex project name:**
+   - If `codex:{name}` provided → use it, save to PROJECT.md frontmatter as `codex_project: {name}`
+   - If not provided → read `codex_project` from PROJECT.md frontmatter
+   - If neither → ask user
+
+2. **Identify the local project:**
+   - If in a loaded project session → use that project
+   - If no project loaded → search and load first (same as `/project search`)
+
+3. **Load codex entry:**
+   - Run `droid config --get tools.codex` and get `codex_repo` from the JSON output
+   - Sync: `git -C {codex_repo} pull --rebase --quiet`
+   - Locate `{codex_repo}/projects/{name}/`
+   - If not found → error with suggestions from available codex projects
+
+4. **Read codex documents:**
+   - PRD.md → goals, requirements, status
+   - TECH-DESIGN.md → architecture, patterns, key paths
+   - DECISIONS.md → recent decisions
+   - Any other docs in the codex project folder
+
+5. **Read current PROJECT.md** and identify:
+   - Sections that overlap with codex content
+   - Codex content that's newer or more detailed
+   - Local content that has no codex equivalent (leave untouched)
+
+6. **Propose updates** (never auto-apply):
+   - **Be highly selective** — PROJECT.md has context limits. Only propose content that is critical for the AI to have when working on this project.
+   - Categorise: "New from codex", "Updated in codex", "No change needed"
+   - Preserve local implementation details — codex updates should ADD context, not overwrite working notes
+   - Prefer links to codex over copying large sections
+
+7. **After approval:**
+   - Apply approved changes
+   - Update frontmatter: `codex_project: {name}`
+   - Add `## Codex Sync` entry or update existing one:
+     ```
+     **Last pulled:** {date} from codex:{name}
+     ```
+   - Determine version bump (patch for context updates, minor if goals/scope changed)
+   - Add changelog entry noting codex pull
+
+## Key Principles
+
+- **Selective, not exhaustive** — only pull what's critical for project context. The project file has size limits.
+- **Additive, not destructive** — codex updates enrich the local project, they don't replace local work
+- **User reviews every change** — always propose, never auto-apply
+- **Provenance tracked** — changelog and sync date show where context came from
+- **Links over copies** — for large sections, link to codex rather than duplicating

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

@@ -0,0 +1,79 @@
+# Pushing to Codex
+
+**Trigger:** `/project push [codex:{name}]`
+
+Push team-relevant content from a local project back to the shared codex.
+
+## What Gets Shared
+
+Not everything in a project is codex-worthy. Extract only team-relevant content:
+
+| Share | Don't Share |
+|-------|-------------|
+| Architecture decisions with rationale | Personal work notes |
+| New patterns discovered during implementation | In-progress tasks |
+| Updated technical constraints | Session logs or worklogs |
+| Status changes (shipped, blocked, pivoted) | Brain docs or research drafts |
+| Key file paths or API changes | Local configuration |
+
+## Procedure
+
+1. **Resolve codex project name:**
+   - If `codex:{name}` provided → use it, save to PROJECT.md frontmatter as `codex_project: {name}`
+   - If not provided → read `codex_project` from PROJECT.md frontmatter
+   - If neither → ask user which codex project to update, save to frontmatter
+   - Codex project must already exist. If it doesn't, suggest `/codex new project {name}` first.
+
+2. **Identify the local project:**
+   - If in a loaded project session → use that project
+   - If no project loaded → search and load first
+
+3. **Read PROJECT.md** and companion docs (DECISIONS.md, WORKLOG.md if they exist)
+
+4. **Load codex entry:**
+   - Run `droid config --get tools.codex` and get `codex_repo` from the JSON output
+   - Sync: `git -C {codex_repo} pull --rebase --quiet`
+   - Read existing codex project docs
+
+5. **Extract and categorise shareable content:**
+   - **Decisions:** New entries from DECISIONS.md or inline decisions in PROJECT.md
+   - **Architecture:** Changes to technical approach, new patterns, updated diagrams
+   - **Status:** Phase changes, milestones hit, scope changes
+   - **Constraints:** Newly discovered technical constraints or gotchas
+
+6. **Propose codex updates** (never auto-apply):
+   - For each item, show:
+     - What will be added/changed in codex
+     - Which codex file it targets (DECISIONS.md, TECH-DESIGN.md, PRD.md)
+     - A diff preview
+   - Let user accept, reject, or edit each item
+
+7. **After approval:**
+   - Use codex git scripts for the write operation:
+     ```bash
+     # Start write
+     droid config --get tools.codex | droid exec codex git-start-write --config - \
+       --branch codex/sync-{project-name}
+
+     # Make changes to codex files
+
+     # Normalize frontmatter
+     droid config --get tools.codex | droid exec codex normalize-frontmatter --config -
+
+     # Finish write (commit + PR)
+     droid config --get tools.codex | droid exec codex git-finish-write --config - \
+       --message "sync({project}): {summary}" \
+       --pr-title "sync({project}): Update from local project" \
+       --pr-body "{description of changes}"
+     ```
+   - Update local PROJECT.md sync marker:
+     ```
+     **Last pushed:** {date} to codex:{name}
+     ```
+
+## Key Principles
+
+- **Curated, not automated** — user explicitly reviews what gets shared
+- **PR-based** — codex changes go through PR review, not direct commits
+- **Additive** — adds to codex content, doesn't overwrite others' contributions
+- **Idempotent** — running `/project push` twice proposes only new/changed content

package/package.json

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

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

package/src/tools/project/skills/project/references/pulling.md

@@ -0,0 +1,57 @@
+# Pulling from Codex
+
+**Trigger:** `/project pull [codex:{name}]`
+
+Pull shared organizational context into an existing local project.
+
+## Procedure
+
+1. **Resolve codex project name:**
+   - If `codex:{name}` provided → use it, save to PROJECT.md frontmatter as `codex_project: {name}`
+   - If not provided → read `codex_project` from PROJECT.md frontmatter
+   - If neither → ask user
+
+2. **Identify the local project:**
+   - If in a loaded project session → use that project
+   - If no project loaded → search and load first (same as `/project search`)
+
+3. **Load codex entry:**
+   - Run `droid config --get tools.codex` and get `codex_repo` from the JSON output
+   - Sync: `git -C {codex_repo} pull --rebase --quiet`
+   - Locate `{codex_repo}/projects/{name}/`
+   - If not found → error with suggestions from available codex projects
+
+4. **Read codex documents:**
+   - PRD.md → goals, requirements, status
+   - TECH-DESIGN.md → architecture, patterns, key paths
+   - DECISIONS.md → recent decisions
+   - Any other docs in the codex project folder
+
+5. **Read current PROJECT.md** and identify:
+   - Sections that overlap with codex content
+   - Codex content that's newer or more detailed
+   - Local content that has no codex equivalent (leave untouched)
+
+6. **Propose updates** (never auto-apply):
+   - **Be highly selective** — PROJECT.md has context limits. Only propose content that is critical for the AI to have when working on this project.
+   - Categorise: "New from codex", "Updated in codex", "No change needed"
+   - Preserve local implementation details — codex updates should ADD context, not overwrite working notes
+   - Prefer links to codex over copying large sections
+
+7. **After approval:**
+   - Apply approved changes
+   - Update frontmatter: `codex_project: {name}`
+   - Add `## Codex Sync` entry or update existing one:
+     ```
+     **Last pulled:** {date} from codex:{name}
+     ```
+   - Determine version bump (patch for context updates, minor if goals/scope changed)
+   - Add changelog entry noting codex pull
+
+## Key Principles
+
+- **Selective, not exhaustive** — only pull what's critical for project context. The project file has size limits.
+- **Additive, not destructive** — codex updates enrich the local project, they don't replace local work
+- **User reviews every change** — always propose, never auto-apply
+- **Provenance tracked** — changelog and sync date show where context came from
+- **Links over copies** — for large sections, link to codex rather than duplicating

package/src/tools/project/skills/project/references/pushing.md

@@ -0,0 +1,79 @@
+# Pushing to Codex
+
+**Trigger:** `/project push [codex:{name}]`
+
+Push team-relevant content from a local project back to the shared codex.
+
+## What Gets Shared
+
+Not everything in a project is codex-worthy. Extract only team-relevant content:
+
+| Share | Don't Share |
+|-------|-------------|
+| Architecture decisions with rationale | Personal work notes |
+| New patterns discovered during implementation | In-progress tasks |
+| Updated technical constraints | Session logs or worklogs |
+| Status changes (shipped, blocked, pivoted) | Brain docs or research drafts |
+| Key file paths or API changes | Local configuration |
+
+## Procedure
+
+1. **Resolve codex project name:**
+   - If `codex:{name}` provided → use it, save to PROJECT.md frontmatter as `codex_project: {name}`
+   - If not provided → read `codex_project` from PROJECT.md frontmatter
+   - If neither → ask user which codex project to update, save to frontmatter
+   - Codex project must already exist. If it doesn't, suggest `/codex new project {name}` first.
+
+2. **Identify the local project:**
+   - If in a loaded project session → use that project
+   - If no project loaded → search and load first
+
+3. **Read PROJECT.md** and companion docs (DECISIONS.md, WORKLOG.md if they exist)
+
+4. **Load codex entry:**
+   - Run `droid config --get tools.codex` and get `codex_repo` from the JSON output
+   - Sync: `git -C {codex_repo} pull --rebase --quiet`
+   - Read existing codex project docs
+
+5. **Extract and categorise shareable content:**
+   - **Decisions:** New entries from DECISIONS.md or inline decisions in PROJECT.md
+   - **Architecture:** Changes to technical approach, new patterns, updated diagrams
+   - **Status:** Phase changes, milestones hit, scope changes
+   - **Constraints:** Newly discovered technical constraints or gotchas
+
+6. **Propose codex updates** (never auto-apply):
+   - For each item, show:
+     - What will be added/changed in codex
+     - Which codex file it targets (DECISIONS.md, TECH-DESIGN.md, PRD.md)
+     - A diff preview
+   - Let user accept, reject, or edit each item
+
+7. **After approval:**
+   - Use codex git scripts for the write operation:
+     ```bash
+     # Start write
+     droid config --get tools.codex | droid exec codex git-start-write --config - \
+       --branch codex/sync-{project-name}
+
+     # Make changes to codex files
+
+     # Normalize frontmatter
+     droid config --get tools.codex | droid exec codex normalize-frontmatter --config -
+
+     # Finish write (commit + PR)
+     droid config --get tools.codex | droid exec codex git-finish-write --config - \
+       --message "sync({project}): {summary}" \
+       --pr-title "sync({project}): Update from local project" \
+       --pr-body "{description of changes}"
+     ```
+   - Update local PROJECT.md sync marker:
+     ```
+     **Last pushed:** {date} to codex:{name}
+     ```
+
+## Key Principles
+
+- **Curated, not automated** — user explicitly reviews what gets shared
+- **PR-based** — codex changes go through PR review, not direct commits
+- **Additive** — adds to codex content, doesn't overwrite others' contributions
+- **Idempotent** — running `/project push` twice proposes only new/changed content