@orderful/droid 0.34.1 → 0.35.1

package/.claude-plugin/marketplace.json

@@ -61,7 +61,7 @@
     {
       "name": "droid-codex",
       "description": "Shared organizational knowledge - PRDs, tech designs, domains, proposals, patterns, and explored topics. Use when loading project context, searching codex, capturing decisions, or creating new entries.",
-      "version": "0.1.10",
+      "version": "0.2.1",
       "source": {
         "source": "github",
         "repo": "orderful/droid",

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @orderful/droid
 
+## 0.35.1
+
+### Patch Changes
+
+- [#211](https://github.com/Orderful/droid/pull/211) [`6df8a25`](https://github.com/Orderful/droid/commit/6df8a2511a1680bec65618d0f5e6e684811cd922) Thanks [@frytyler](https://github.com/frytyler)! - Bump codex tool version to force reinstall with fixed subdirectory copying
+
+  Users who installed codex 0.2.0 before the fix would be missing references/review/ subdirectory. Bumping to 0.2.1 ensures they get the complete installation with all reference files.
+
+- [#211](https://github.com/Orderful/droid/pull/211) [`6df8a25`](https://github.com/Orderful/droid/commit/6df8a2511a1680bec65618d0f5e6e684811cd922) Thanks [@frytyler](https://github.com/frytyler)! - Fix skill installation not copying reference and script subdirectories
+
+  The installSkill() function was only copying top-level files from references/ and scripts/ directories, causing subdirectories to be skipped. This blocked the /codex review feature which relies on references/review/workflow.md.
+
+  Added a generic copyDirectoryRecursive() helper that preserves directory structure while maintaining the existing file type filters (.md for references, .ts/.js/.py for scripts). Applied to both references/ and scripts/ copying.
+
+## 0.35.0
+
+### Minor Changes
+
+- [#209](https://github.com/Orderful/droid/pull/209) [`74cbdbb`](https://github.com/Orderful/droid/commit/74cbdbba131741412f3a5d490472ff8b4c22e286) Thanks [@frytyler](https://github.com/frytyler)! - feat(codex): add review skill for conversational document reviews
+
+  New capability for reviewing structured documents (tech designs, PRDs) conversationally in the CLI.
+
+  Features:
+  - Generic review workflow for structured docs
+  - Tech design document type support
+  - Section-based navigation ("Show me the rollout section")
+  - Context search in thought docs ("Why was X rejected?")
+  - MVP scope (read-only, CLI navigation)
+
+  Commands:
+  - `/codex review {type} --pr {number}` - Load and review a PR
+
 ## 0.34.1
 
 ### Patch Changes

package/dist/bin/droid.js

@@ -1305,6 +1305,22 @@ function updateAllSkills() {
   }
   return result;
 }
+function copyDirectoryRecursive(source, target, fileFilter) {
+  if (!existsSync6(target)) {
+    mkdirSync4(target, { recursive: true });
+  }
+  const entries = readdirSync5(source, { withFileTypes: true });
+  for (const entry of entries) {
+    const sourcePath = join7(source, entry.name);
+    const targetPath = join7(target, entry.name);
+    if (entry.isDirectory()) {
+      copyDirectoryRecursive(sourcePath, targetPath, fileFilter);
+    } else if (entry.isFile() && fileFilter(entry.name)) {
+      const content = readFileSync6(sourcePath, "utf-8");
+      writeFileSync4(targetPath, content);
+    }
+  }
+}
 function installSkill(skillName) {
   const config = loadConfig();
   const skillPath = findSkillPath(skillName);
@@ -1418,34 +1434,20 @@ function installSkill(skillName) {
   const referencesSource = join7(skillDir, "references");
   if (existsSync6(referencesSource)) {
     const targetReferencesDir = join7(targetSkillDir, "references");
-    if (!existsSync6(targetReferencesDir)) {
-      mkdirSync4(targetReferencesDir, { recursive: true });
-    }
-    const referenceFiles = readdirSync5(referencesSource).filter(
+    copyDirectoryRecursive(
+      referencesSource,
+      targetReferencesDir,
       (f) => f.endsWith(".md")
     );
-    for (const file of referenceFiles) {
-      const sourcePath = join7(referencesSource, file);
-      const targetPath = join7(targetReferencesDir, file);
-      const content = readFileSync6(sourcePath, "utf-8");
-      writeFileSync4(targetPath, content);
-    }
   }
   const scriptsSource = join7(skillDir, "scripts");
   if (existsSync6(scriptsSource)) {
     const targetScriptsDir = join7(targetSkillDir, "scripts");
-    if (!existsSync6(targetScriptsDir)) {
-      mkdirSync4(targetScriptsDir, { recursive: true });
-    }
-    const scriptFiles = readdirSync5(scriptsSource).filter(
+    copyDirectoryRecursive(
+      scriptsSource,
+      targetScriptsDir,
       (f) => f.endsWith(".ts") || f.endsWith(".js") || f.endsWith(".py")
     );
-    for (const file of scriptFiles) {
-      const sourcePath = join7(scriptsSource, file);
-      const targetPath = join7(targetScriptsDir, file);
-      const content = readFileSync6(sourcePath, "utf-8");
-      writeFileSync4(targetPath, content);
-    }
   }
   const activePlatforms = getActivePlatforms(config);
   const targetPlatforms = activePlatforms.length > 0 ? activePlatforms : [config.platform];

package/dist/index.js

@@ -1262,6 +1262,22 @@ function updateAllSkills() {
   }
   return result;
 }
+function copyDirectoryRecursive(source, target, fileFilter) {
+  if (!existsSync6(target)) {
+    mkdirSync4(target, { recursive: true });
+  }
+  const entries = readdirSync5(source, { withFileTypes: true });
+  for (const entry of entries) {
+    const sourcePath = join7(source, entry.name);
+    const targetPath = join7(target, entry.name);
+    if (entry.isDirectory()) {
+      copyDirectoryRecursive(sourcePath, targetPath, fileFilter);
+    } else if (entry.isFile() && fileFilter(entry.name)) {
+      const content = readFileSync6(sourcePath, "utf-8");
+      writeFileSync4(targetPath, content);
+    }
+  }
+}
 function installSkill(skillName) {
   const config = loadConfig();
   const skillPath = findSkillPath(skillName);
@@ -1375,34 +1391,20 @@ function installSkill(skillName) {
   const referencesSource = join7(skillDir, "references");
   if (existsSync6(referencesSource)) {
     const targetReferencesDir = join7(targetSkillDir, "references");
-    if (!existsSync6(targetReferencesDir)) {
-      mkdirSync4(targetReferencesDir, { recursive: true });
-    }
-    const referenceFiles = readdirSync5(referencesSource).filter(
+    copyDirectoryRecursive(
+      referencesSource,
+      targetReferencesDir,
       (f) => f.endsWith(".md")
     );
-    for (const file of referenceFiles) {
-      const sourcePath = join7(referencesSource, file);
-      const targetPath = join7(targetReferencesDir, file);
-      const content = readFileSync6(sourcePath, "utf-8");
-      writeFileSync4(targetPath, content);
-    }
   }
   const scriptsSource = join7(skillDir, "scripts");
   if (existsSync6(scriptsSource)) {
     const targetScriptsDir = join7(targetSkillDir, "scripts");
-    if (!existsSync6(targetScriptsDir)) {
-      mkdirSync4(targetScriptsDir, { recursive: true });
-    }
-    const scriptFiles = readdirSync5(scriptsSource).filter(
+    copyDirectoryRecursive(
+      scriptsSource,
+      targetScriptsDir,
       (f) => f.endsWith(".ts") || f.endsWith(".js") || f.endsWith(".py")
     );
-    for (const file of scriptFiles) {
-      const sourcePath = join7(scriptsSource, file);
-      const targetPath = join7(targetScriptsDir, file);
-      const content = readFileSync6(sourcePath, "utf-8");
-      writeFileSync4(targetPath, content);
-    }
   }
   const activePlatforms = getActivePlatforms(config);
   const targetPlatforms = activePlatforms.length > 0 ? activePlatforms : [config.platform];

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

@@ -1 +1 @@
-{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/lib/skills.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/lib/skills.ts"],"names":[],"mappings":"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"}

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

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

package/dist/tools/codex/TOOL.yaml

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

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

@@ -1,7 +1,7 @@
 ---
 name: codex
-description: "Shared organizational knowledge - PRDs, tech designs, patterns, and explored topics. Use when loading project context ('load transaction-templates'), searching codex ('search webhook'), capturing decisions ('codex decision'), or adding explored topics ('add topic'). User prompts like 'check the codex', 'what's in the codex about X', 'load the PRD for Y'."
-argument-hint: "[projects | domains | proposals | patterns | topics | {name} | search {query} | new {type} {name} | decision {text}]"
+description: "Shared organizational knowledge - PRDs, tech designs, patterns, and explored topics. Use when loading project context ('load transaction-templates'), searching codex ('search webhook'), reviewing documents ('review tech-design'), capturing decisions ('codex decision'), or adding explored topics ('add topic'). User prompts like 'check the codex', 'what's in the codex about X', 'load the PRD for Y'."
+argument-hint: "[projects | domains | proposals | patterns | topics | {name} | search {query} | review {type} | new {type} {name} | decision {text}]"
 allowed-tools:
   [
     Read,
@@ -173,6 +173,7 @@ The codex has five categories:
 | `/codex search {query}`                      | Search and load entry (searches all categories)         |
 | `/codex search {query} -- {instruction}`     | Search, load, then execute follow-up instruction        |
 | `/codex {category} search {query}`           | Search within a specific category only                  |
+| `/codex review {type} --pr {number}`         | Conversational review of a document PR                  |
 | `/codex new {category} {name}`               | Scaffold new entry (project/domain/proposal/pattern/topic) |
 | `/codex decision {text}`                     | Append to active project's DECISIONS.md                 |
 | `/codex snapshot {type} {file} {name}` | Import PDF/markdown to codex (uses agent)       |
@@ -360,6 +361,20 @@ Artifacts are supplementary documents that support a project but aren't core doc
 
 Artifacts get lighter frontmatter with `type: artifact` and source like `interview`, `transcript`, `notes`, `meeting`, `research`, `spike`, or `analysis`.
 
+## Reviewing Documents
+
+**Trigger:** `/codex review {type} --pr {number}`
+
+**Procedure:**
+
+1. **Run preamble:** `droid config --get tools.codex | droid exec codex git-preamble --config -`
+2. **Fetch PR info:** `gh pr view {number} --json files,title`
+3. **Filter & Load:** Identify the primary document (e.g., `TECH-DESIGN.md`) and context (e.g., `thought-doc.md`) based on the `{type}` definition.
+4. **Interactive Review:** Guide the user through the document sections.
+
+Full procedure: `references/review/workflow.md`
+Type definitions: `references/review/{type}.md`
+
 ## Creating New Entries
 
 **Trigger:** `/codex new {category} {name}`

package/dist/tools/codex/skills/codex/references/review/tech-design.md

@@ -0,0 +1,34 @@
+# Tech Design Document Type
+
+Configuration for reviewing Tech Design documents via `/codex review tech-design`.
+
+## File Patterns
+
+| Role | Pattern | Description |
+| --- | --- | --- |
+| **Primary** | `**/TECH-DESIGN.md` | The main document being reviewed. Sections are parsed from here. |
+| **Context** | `**/thought-doc.md` | Backstory, alternatives, and trade-offs. Used for "why" questions. |
+
+*Note: In the MVP, we assume a single TECH-DESIGN.md per PR.*
+
+## Section Parsing
+Sections in `TECH-DESIGN.md` are defined by H2 headers (`## `). H3 headers (`###`) are treated as content within sections for MVP.
+
+**The tool dynamically discovers ALL sections present in the document.** It does not filter for specific section names.
+
+**Common sections** (examples, not exhaustive):
+- TL;DR
+- Problem
+- Scope
+- Solution
+- Key Decisions
+- Risks
+- Rollout
+- Implementation Phases
+
+Authors may include additional sections (e.g., "Security", "Performance", "Alternatives Considered") and the tool will present them for navigation.
+
+## Consistency Checks (Deferred)
+*Future feature: Rules to automatically check consistency.*
+- "Risks" section must list mitigations
+- "Implementation Phases" must match "Rollout" steps

package/dist/tools/codex/skills/codex/references/review/workflow.md

@@ -0,0 +1,250 @@
+# Generic Document Review Workflow
+
+The `/codex review` command provides a conversational interface for reviewing structured documents (tech designs, PRDs, etc.) directly in the CLI.
+
+## 1. Loading the PR
+
+**Trigger:** `/codex review {type} --pr {number}`
+
+**Step 1: Preamble**
+Run the git preamble to ensure we are on a clean state (though we're mostly reading).
+```bash
+droid config --get tools.codex | droid exec codex git-preamble --config -
+```
+
+**Step 2: Fetch PR Details**
+Get the PR metadata to validate it exists and get the file list.
+
+```bash
+# Get codex repo path from config
+codex_repo=$(droid config --get tools.codex.codex_dir)
+
+# Fetch PR info
+gh pr view {number} --json files,title,url,headRefName --repo "$codex_repo"
+```
+
+Check exit code: if non-zero, PR not found (see Error Handling below).
+
+**Step 3: Checkout PR Branch**
+Check out the PR to read files easily.
+
+```bash
+cd "$codex_repo"
+gh pr checkout {number}
+```
+
+This creates/switches to the PR branch locally.
+
+**Step 4: Identify Files**
+Match the file list against patterns in `references/review/{type}.md`.
+
+For tech-design:
+- **Primary:** `**/TECH-DESIGN.md`
+- **Context:** `**/thought-doc.md` (optional)
+
+Find files using:
+```bash
+find . -name "TECH-DESIGN.md" -type f
+find . -name "thought-doc.md" -type f
+```
+
+**Step 5: Read Content**
+Read identified files using the Read tool. Count lines for display.
+
+```bash
+wc -l {path_to_primary}  # Get line count
+```
+
+**Error Handling:**
+
+**PR not found:**
+```bash
+gh pr view {number} --repo "$codex_repo"
+# Check exit code
+if [ $? -ne 0 ]; then
+  echo "❌ PR #{number} not found in codex repo"
+  exit 1
+fi
+```
+
+**TECH-DESIGN.md not found:**
+If `find . -name "TECH-DESIGN.md"` returns nothing:
+```
+❌ No TECH-DESIGN.md found in PR #{number}
+
+This PR doesn't appear to contain a tech design document.
+```
+
+**thought-doc.md missing (optional):**
+If not found, continue without it:
+```
+⚠️  No thought-doc.md found - context search will be limited
+```
+
+**gh CLI fails:**
+```
+❌ Failed to fetch PR details. Is gh CLI authenticated?
+
+Try: gh auth status
+```
+
+## 2. Parsing Structure
+
+**Step 1: Parse Sections**
+Read the **Primary** document and extract H2 headers (lines starting with `## `).
+
+Extract using pattern: `^##\s+(.+)$`
+- Match lines starting with `##` followed by whitespace
+- Capture everything after as the section name
+- Strip leading/trailing whitespace
+- Ignore H3 headers (`###`) for MVP - treat as content within sections
+
+Example parsing:
+```
+## TL;DR           → Section: "TL;DR"
+## Problem         → Section: "Problem"
+### Sub-problem   → (ignored, part of Problem section)
+## Solution        → Section: "Solution"
+```
+
+**Step 2: Display Overview**
+Output a dynamic summary based on the actual PR content:
+
+```
+📋 Review: {PR Title} (PR #{number})
+
+Documents loaded:
+✓ {path_to_primary} ({line_count} lines)
+✓ {path_to_context} ({line_count} lines) [if found]
+
+Structure ({count} sections):
+1. {First section name}
+2. {Second section name}
+...
+{N}. {Last section name}
+
+What would you like to do?
+- Show me a specific section (e.g., "show me the {example section}")
+- Ask questions about decisions (e.g., "why was X rejected?")
+- Walk through section by section
+```
+
+**Note:** All values are dynamic:
+- PR title comes from `gh pr view`
+- File paths come from what's actually in the PR
+- Section count and names come from parsing the TECH-DESIGN.md H2 headers
+- If thought-doc.md not found, only show the primary document
+
+**Example output:**
+```
+📋 Review: Transaction Templates Tech Design (PR #128)
+
+Documents loaded:
+✓ projects/transaction-templates/TECH-DESIGN.md (250 lines)
+✓ projects/transaction-templates/artifacts/thought-doc.md (380 lines)
+
+Structure (8 sections):
+1. TL;DR
+2. Problem
+3. Scope
+4. Solution
+5. Key Decisions
+6. Risks
+7. Rollout
+8. Implementation Phases
+
+What would you like to do?
+- Show me a specific section (e.g., "show me the rollout")
+- Ask questions about decisions (e.g., "why was X rejected?")
+- Walk through section by section
+```
+
+**Step 3: Wait for User Request**
+User can now navigate conversationally.
+
+## 3. Conversational Navigation
+
+Map user requests to actions:
+
+**"Show me {section}"**
+1. Match the section name (see Section Matching below)
+2. Read the Primary file
+3. Extract content between `## {Match}` and the next `## ` header
+4. Display the section content
+
+**Section Matching Algorithm:**
+
+Use case-insensitive substring matching:
+
+1. Normalize user input and section names to lowercase
+2. Check if user input is substring of any section name
+3. If single match: use it
+4. If multiple matches: pick the first one (or ask user to clarify)
+5. If no matches: list available sections
+
+**Examples:**
+- User: "show rollout" → matches "Rollout"
+- User: "security" → matches "Security Considerations"
+- User: "risks" → matches "Risks"
+- User: "key decisions" → matches "Key Decisions"
+
+**"Walk me through it"**
+1. Start with the first section
+2. Display content
+3. Ask "Continue to {Next Section}?"
+4. Repeat until user stops or end of document
+
+**"Jump to {section}"**
+Same as "Show me {section}".
+
+## 4. Contextual Search (Thought Docs)
+
+**Trigger Detection:**
+
+If user query contains any of: "why", "rejected", "alternative", "decision", "reason", "chose", "didn't"
+→ Enter context search mode
+
+**Term Extraction:**
+
+Extract key phrases from the question:
+- Strip question words: "why was", "why did we", "what about"
+- Extract 2-4 word phrases: "event-based approach", "webhook pattern", "async processing"
+- If user mentions specific terms in quotes, use those exactly
+
+**Examples:**
+- "Why was event-based rejected?" → search for "event-based"
+- "Why did we choose sync over async?" → search for "sync" and "async"
+- "What about the webhook approach?" → search for "webhook"
+
+**Search Process:**
+
+1. Search the **Context** document (e.g., `thought-doc.md`) first:
+   ```bash
+   grep -C 5 -i "{term}" {path_to_context}
+   ```
+
+2. Display results with context (5 lines before/after)
+
+3. If multiple matches found: show first 3 matches
+
+4. If no match in context doc: search Primary document
+
+5. If still no match: "No mentions of '{term}' found in design docs"
+
+**Display Format:**
+
+```
+Searching thought doc for "event-based"...
+
+Found in Key Decisions section:
+
+> Event-based was rejected because of complexity in guaranteeing
+> order and handling failures. The synchronous API approach is
+> simpler and sufficient for the MVP requirements. We considered
+> event streaming but decided it was premature optimization.
+
+Anything else?
+```
+
+## 5. Posting Feedback (MVP: Deferred)
+*For MVP, we just display content. Users can use `gh pr comment` manually if they want, but the tool focuses on reading.*

package/package.json

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

package/src/lib/skills.ts

@@ -393,6 +393,39 @@ export function updateAllSkills(): {
   return result;
 }
 
+/**
+ * Recursively copy a directory and all its contents
+ * @param source Source directory path
+ * @param target Target directory path
+ * @param fileFilter Function that returns true if the file should be copied
+ */
+function copyDirectoryRecursive(
+  source: string,
+  target: string,
+  fileFilter: (filename: string) => boolean,
+): void {
+  if (!existsSync(target)) {
+    mkdirSync(target, { recursive: true });
+  }
+
+  const entries = readdirSync(source, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const sourcePath = join(source, entry.name);
+    const targetPath = join(target, entry.name);
+
+    if (entry.isDirectory()) {
+      // Recursively copy subdirectory
+      copyDirectoryRecursive(sourcePath, targetPath, fileFilter);
+    } else if (entry.isFile() && fileFilter(entry.name)) {
+      // Copy file if it passes the filter
+      const content = readFileSync(sourcePath, 'utf-8');
+      writeFileSync(targetPath, content);
+    }
+    // Ignore files that don't pass the filter
+  }
+}
+
 /**
  * Install a skill
  */
@@ -553,36 +586,20 @@ export function installSkill(skillName: string): {
   const referencesSource = join(skillDir, 'references');
   if (existsSync(referencesSource)) {
     const targetReferencesDir = join(targetSkillDir, 'references');
-    if (!existsSync(targetReferencesDir)) {
-      mkdirSync(targetReferencesDir, { recursive: true });
-    }
-    const referenceFiles = readdirSync(referencesSource).filter((f) =>
+    copyDirectoryRecursive(referencesSource, targetReferencesDir, (f) =>
       f.endsWith('.md'),
     );
-    for (const file of referenceFiles) {
-      const sourcePath = join(referencesSource, file);
-      const targetPath = join(targetReferencesDir, file);
-      const content = readFileSync(sourcePath, 'utf-8');
-      writeFileSync(targetPath, content);
-    }
   }
 
   // Copy scripts if present (deterministic CLI scripts for the skill)
   const scriptsSource = join(skillDir, 'scripts');
   if (existsSync(scriptsSource)) {
     const targetScriptsDir = join(targetSkillDir, 'scripts');
-    if (!existsSync(targetScriptsDir)) {
-      mkdirSync(targetScriptsDir, { recursive: true });
-    }
-    const scriptFiles = readdirSync(scriptsSource).filter(
+    copyDirectoryRecursive(
+      scriptsSource,
+      targetScriptsDir,
       (f) => f.endsWith('.ts') || f.endsWith('.js') || f.endsWith('.py'),
     );
-    for (const file of scriptFiles) {
-      const sourcePath = join(scriptsSource, file);
-      const targetPath = join(targetScriptsDir, file);
-      const content = readFileSync(sourcePath, 'utf-8');
-      writeFileSync(targetPath, content);
-    }
   }
 
   // Get active platforms for multi-platform install

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

@@ -1,6 +1,6 @@
 {
   "name": "droid-codex",
-  "version": "0.1.10",
+  "version": "0.2.1",
   "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.10
+version: 0.2.1
 status: beta
 
 includes:

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

@@ -1,7 +1,7 @@
 ---
 name: codex
-description: "Shared organizational knowledge - PRDs, tech designs, patterns, and explored topics. Use when loading project context ('load transaction-templates'), searching codex ('search webhook'), capturing decisions ('codex decision'), or adding explored topics ('add topic'). User prompts like 'check the codex', 'what's in the codex about X', 'load the PRD for Y'."
-argument-hint: "[projects | domains | proposals | patterns | topics | {name} | search {query} | new {type} {name} | decision {text}]"
+description: "Shared organizational knowledge - PRDs, tech designs, patterns, and explored topics. Use when loading project context ('load transaction-templates'), searching codex ('search webhook'), reviewing documents ('review tech-design'), capturing decisions ('codex decision'), or adding explored topics ('add topic'). User prompts like 'check the codex', 'what's in the codex about X', 'load the PRD for Y'."
+argument-hint: "[projects | domains | proposals | patterns | topics | {name} | search {query} | review {type} | new {type} {name} | decision {text}]"
 allowed-tools:
   [
     Read,
@@ -173,6 +173,7 @@ The codex has five categories:
 | `/codex search {query}`                      | Search and load entry (searches all categories)         |
 | `/codex search {query} -- {instruction}`     | Search, load, then execute follow-up instruction        |
 | `/codex {category} search {query}`           | Search within a specific category only                  |
+| `/codex review {type} --pr {number}`         | Conversational review of a document PR                  |
 | `/codex new {category} {name}`               | Scaffold new entry (project/domain/proposal/pattern/topic) |
 | `/codex decision {text}`                     | Append to active project's DECISIONS.md                 |
 | `/codex snapshot {type} {file} {name}` | Import PDF/markdown to codex (uses agent)       |
@@ -360,6 +361,20 @@ Artifacts are supplementary documents that support a project but aren't core doc
 
 Artifacts get lighter frontmatter with `type: artifact` and source like `interview`, `transcript`, `notes`, `meeting`, `research`, `spike`, or `analysis`.
 
+## Reviewing Documents
+
+**Trigger:** `/codex review {type} --pr {number}`
+
+**Procedure:**
+
+1. **Run preamble:** `droid config --get tools.codex | droid exec codex git-preamble --config -`
+2. **Fetch PR info:** `gh pr view {number} --json files,title`
+3. **Filter & Load:** Identify the primary document (e.g., `TECH-DESIGN.md`) and context (e.g., `thought-doc.md`) based on the `{type}` definition.
+4. **Interactive Review:** Guide the user through the document sections.
+
+Full procedure: `references/review/workflow.md`
+Type definitions: `references/review/{type}.md`
+
 ## Creating New Entries
 
 **Trigger:** `/codex new {category} {name}`

package/src/tools/codex/skills/codex/references/review/tech-design.md

@@ -0,0 +1,34 @@
+# Tech Design Document Type
+
+Configuration for reviewing Tech Design documents via `/codex review tech-design`.
+
+## File Patterns
+
+| Role | Pattern | Description |
+| --- | --- | --- |
+| **Primary** | `**/TECH-DESIGN.md` | The main document being reviewed. Sections are parsed from here. |
+| **Context** | `**/thought-doc.md` | Backstory, alternatives, and trade-offs. Used for "why" questions. |
+
+*Note: In the MVP, we assume a single TECH-DESIGN.md per PR.*
+
+## Section Parsing
+Sections in `TECH-DESIGN.md` are defined by H2 headers (`## `). H3 headers (`###`) are treated as content within sections for MVP.
+
+**The tool dynamically discovers ALL sections present in the document.** It does not filter for specific section names.
+
+**Common sections** (examples, not exhaustive):
+- TL;DR
+- Problem
+- Scope
+- Solution
+- Key Decisions
+- Risks
+- Rollout
+- Implementation Phases
+
+Authors may include additional sections (e.g., "Security", "Performance", "Alternatives Considered") and the tool will present them for navigation.
+
+## Consistency Checks (Deferred)
+*Future feature: Rules to automatically check consistency.*
+- "Risks" section must list mitigations
+- "Implementation Phases" must match "Rollout" steps

package/src/tools/codex/skills/codex/references/review/workflow.md

@@ -0,0 +1,250 @@
+# Generic Document Review Workflow
+
+The `/codex review` command provides a conversational interface for reviewing structured documents (tech designs, PRDs, etc.) directly in the CLI.
+
+## 1. Loading the PR
+
+**Trigger:** `/codex review {type} --pr {number}`
+
+**Step 1: Preamble**
+Run the git preamble to ensure we are on a clean state (though we're mostly reading).
+```bash
+droid config --get tools.codex | droid exec codex git-preamble --config -
+```
+
+**Step 2: Fetch PR Details**
+Get the PR metadata to validate it exists and get the file list.
+
+```bash
+# Get codex repo path from config
+codex_repo=$(droid config --get tools.codex.codex_dir)
+
+# Fetch PR info
+gh pr view {number} --json files,title,url,headRefName --repo "$codex_repo"
+```
+
+Check exit code: if non-zero, PR not found (see Error Handling below).
+
+**Step 3: Checkout PR Branch**
+Check out the PR to read files easily.
+
+```bash
+cd "$codex_repo"
+gh pr checkout {number}
+```
+
+This creates/switches to the PR branch locally.
+
+**Step 4: Identify Files**
+Match the file list against patterns in `references/review/{type}.md`.
+
+For tech-design:
+- **Primary:** `**/TECH-DESIGN.md`
+- **Context:** `**/thought-doc.md` (optional)
+
+Find files using:
+```bash
+find . -name "TECH-DESIGN.md" -type f
+find . -name "thought-doc.md" -type f
+```
+
+**Step 5: Read Content**
+Read identified files using the Read tool. Count lines for display.
+
+```bash
+wc -l {path_to_primary}  # Get line count
+```
+
+**Error Handling:**
+
+**PR not found:**
+```bash
+gh pr view {number} --repo "$codex_repo"
+# Check exit code
+if [ $? -ne 0 ]; then
+  echo "❌ PR #{number} not found in codex repo"
+  exit 1
+fi
+```
+
+**TECH-DESIGN.md not found:**
+If `find . -name "TECH-DESIGN.md"` returns nothing:
+```
+❌ No TECH-DESIGN.md found in PR #{number}
+
+This PR doesn't appear to contain a tech design document.
+```
+
+**thought-doc.md missing (optional):**
+If not found, continue without it:
+```
+⚠️  No thought-doc.md found - context search will be limited
+```
+
+**gh CLI fails:**
+```
+❌ Failed to fetch PR details. Is gh CLI authenticated?
+
+Try: gh auth status
+```
+
+## 2. Parsing Structure
+
+**Step 1: Parse Sections**
+Read the **Primary** document and extract H2 headers (lines starting with `## `).
+
+Extract using pattern: `^##\s+(.+)$`
+- Match lines starting with `##` followed by whitespace
+- Capture everything after as the section name
+- Strip leading/trailing whitespace
+- Ignore H3 headers (`###`) for MVP - treat as content within sections
+
+Example parsing:
+```
+## TL;DR           → Section: "TL;DR"
+## Problem         → Section: "Problem"
+### Sub-problem   → (ignored, part of Problem section)
+## Solution        → Section: "Solution"
+```
+
+**Step 2: Display Overview**
+Output a dynamic summary based on the actual PR content:
+
+```
+📋 Review: {PR Title} (PR #{number})
+
+Documents loaded:
+✓ {path_to_primary} ({line_count} lines)
+✓ {path_to_context} ({line_count} lines) [if found]
+
+Structure ({count} sections):
+1. {First section name}
+2. {Second section name}
+...
+{N}. {Last section name}
+
+What would you like to do?
+- Show me a specific section (e.g., "show me the {example section}")
+- Ask questions about decisions (e.g., "why was X rejected?")
+- Walk through section by section
+```
+
+**Note:** All values are dynamic:
+- PR title comes from `gh pr view`
+- File paths come from what's actually in the PR
+- Section count and names come from parsing the TECH-DESIGN.md H2 headers
+- If thought-doc.md not found, only show the primary document
+
+**Example output:**
+```
+📋 Review: Transaction Templates Tech Design (PR #128)
+
+Documents loaded:
+✓ projects/transaction-templates/TECH-DESIGN.md (250 lines)
+✓ projects/transaction-templates/artifacts/thought-doc.md (380 lines)
+
+Structure (8 sections):
+1. TL;DR
+2. Problem
+3. Scope
+4. Solution
+5. Key Decisions
+6. Risks
+7. Rollout
+8. Implementation Phases
+
+What would you like to do?
+- Show me a specific section (e.g., "show me the rollout")
+- Ask questions about decisions (e.g., "why was X rejected?")
+- Walk through section by section
+```
+
+**Step 3: Wait for User Request**
+User can now navigate conversationally.
+
+## 3. Conversational Navigation
+
+Map user requests to actions:
+
+**"Show me {section}"**
+1. Match the section name (see Section Matching below)
+2. Read the Primary file
+3. Extract content between `## {Match}` and the next `## ` header
+4. Display the section content
+
+**Section Matching Algorithm:**
+
+Use case-insensitive substring matching:
+
+1. Normalize user input and section names to lowercase
+2. Check if user input is substring of any section name
+3. If single match: use it
+4. If multiple matches: pick the first one (or ask user to clarify)
+5. If no matches: list available sections
+
+**Examples:**
+- User: "show rollout" → matches "Rollout"
+- User: "security" → matches "Security Considerations"
+- User: "risks" → matches "Risks"
+- User: "key decisions" → matches "Key Decisions"
+
+**"Walk me through it"**
+1. Start with the first section
+2. Display content
+3. Ask "Continue to {Next Section}?"
+4. Repeat until user stops or end of document
+
+**"Jump to {section}"**
+Same as "Show me {section}".
+
+## 4. Contextual Search (Thought Docs)
+
+**Trigger Detection:**
+
+If user query contains any of: "why", "rejected", "alternative", "decision", "reason", "chose", "didn't"
+→ Enter context search mode
+
+**Term Extraction:**
+
+Extract key phrases from the question:
+- Strip question words: "why was", "why did we", "what about"
+- Extract 2-4 word phrases: "event-based approach", "webhook pattern", "async processing"
+- If user mentions specific terms in quotes, use those exactly
+
+**Examples:**
+- "Why was event-based rejected?" → search for "event-based"
+- "Why did we choose sync over async?" → search for "sync" and "async"
+- "What about the webhook approach?" → search for "webhook"
+
+**Search Process:**
+
+1. Search the **Context** document (e.g., `thought-doc.md`) first:
+   ```bash
+   grep -C 5 -i "{term}" {path_to_context}
+   ```
+
+2. Display results with context (5 lines before/after)
+
+3. If multiple matches found: show first 3 matches
+
+4. If no match in context doc: search Primary document
+
+5. If still no match: "No mentions of '{term}' found in design docs"
+
+**Display Format:**
+
+```
+Searching thought doc for "event-based"...
+
+Found in Key Decisions section:
+
+> Event-based was rejected because of complexity in guaranteeing
+> order and handling failures. The synchronous API approach is
+> simpler and sufficient for the MVP requirements. We considered
+> event streaming but decided it was premature optimization.
+
+Anything else?
+```
+
+## 5. Posting Feedback (MVP: Deferred)
+*For MVP, we just display content. Users can use `gh pr comment` manually if they want, but the tool focuses on reading.*