@orderful/droid 0.35.4 → 0.36.0

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

@@ -1,250 +1,60 @@
-# Generic Document Review Workflow
+# Review Workflow
 
-The `/codex review` command provides a conversational interface for reviewing structured documents (tech designs, PRDs, etc.) directly in the CLI.
+The `/codex review` command provides conversational PR review for codex documents.
 
-## 1. Loading the PR
+## Architecture
 
-**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 -
-```
+**Generic flow:** Defined in `{codex_repo}/.codex/workflows/reviewing.md`
+- Loading PR branch
+- Identifying documents
+- Progressive disclosure
+- Conversational navigation
+- Providing feedback
 
-**Step 2: Fetch PR Details**
-Get the PR metadata to validate it exists and get the file list.
+**Review type specifics:** Defined in `references/review/{type}.md` (this folder)
+- File patterns for each document type
+- Section parsing rules
+- Type-specific facilitation guidance
+- Consistency checks
 
-```bash
-# Get codex repo path from config
-codex_repo=$(droid config --get tools.codex.codex_dir)
+## Using the Workflow
 
-# Fetch PR info
-gh pr view {number} --json files,title,url,headRefName --repo "$codex_repo"
-```
+**Trigger:** `/codex review {type} --pr {number}`
 
-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:**
+**Procedure:**
 
-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:
+1. **Read generic workflow:**
    ```bash
-   grep -C 5 -i "{term}" {path_to_context}
+   cat {codex_repo}/.codex/workflows/reviewing.md
    ```
 
-2. Display results with context (5 lines before/after)
+2. **Read type-specific guidance:**
 
-3. If multiple matches found: show first 3 matches
+       cat references/review/{type}.md
 
-4. If no match in context doc: search Primary document
+   For example:
+   - `/codex review tech-design --pr 123` → Read `references/review/tech-design.md`
+   - `/codex review prd --pr 456` → Read `references/review/prd.md`
 
-5. If still no match: "No mentions of '{term}' found in design docs"
+3. **Follow both:**
+   - Generic workflow for overall flow (from codex repo)
+   - Type-specific guidance for facilitation details (from this folder)
 
-**Display Format:**
+## Available Review Types
 
-```
-Searching thought doc for "event-based"...
+| Type | File | Purpose |
+|------|------|---------|
+| tech-design | tech-design.md | Technical design document review with section navigation |
+| prd | prd.md | Product requirements document review with section navigation |
 
-Found in Key Decisions section:
+## Facilitation Guidance
 
-> 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.
+Review types provide specialized AI instructions for:
 
-Anything else?
-```
+- **Progressive disclosure:** How to reveal sections
+- **Contextual search:** Where to find "why" context (thought docs, research)
+- **Navigation patterns:** Natural language commands ("show alternatives", "next")
+- **Consistency checks:** Type-specific validation rules
+- **Feedback format:** How to structure review comments
 
-## 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.*
+This ensures the AI facilitates an effective review rather than just reading the document.

package/package.json

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

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

@@ -1,7 +1,7 @@
 {
   "name": "droid-codex",
-  "version": "0.2.2",
-  "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.3.0",
+  "description": "Shared organizational knowledge - PRDs, tech designs, domains, proposals, patterns, and explored topics. Self-describing: structure and workflows defined in codex repo. Use when loading project context, searching codex, capturing decisions, or creating new entries.",
   "author": {
     "name": "Orderful",
     "url": "https://github.com/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.2.2
+description: "Shared organizational knowledge - PRDs, tech designs, domains, proposals, patterns, and explored topics. Self-describing: structure and workflows defined in codex repo. Use when loading project context, searching codex, capturing decisions, or creating new entries."
+version: 0.3.0
 status: beta
 
 includes:

package/src/tools/codex/commands/codex.md

@@ -1,6 +1,6 @@
 ---
 name: codex
-description: "Shared organizational knowledge - PRDs, tech designs, patterns, domains, proposals, and explored topics"
+description: "Shared organizational knowledge - PRDs, tech designs, patterns, domains, proposals, and explored topics. Self-describing: structure and workflows defined in codex repo."
 argument-hint: "[projects | search {query} | {category} search {query} | new {category} {name} | decision {text}]"
 ---