@orderful/droid 0.25.1 → 0.26.0

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.3
+version: 0.1.5
 status: beta
 
 includes:
@@ -24,7 +24,7 @@ prerequisites:
 config_schema:
   codex_repo:
     type: string
-    description: Path to local orderful-codex repository (required)
+    description: Path to local orderful-codex repository
     required: true
     default: "~/src/github.com/orderful-codex"
   freshness_days:

package/dist/tools/codex/commands/codex.md

@@ -1,7 +1,7 @@
 ---
 description: Shared organizational knowledge - PRDs, tech designs, patterns, domains, proposals, and explored topics
 argument-hint: "[projects | domains | proposals | patterns | topics | {name} | search {query} | new {type} {name} | decision {text}]"
-allowed-tools: Read, Write, Edit, Glob, Grep, Bash(gh:*), Bash(git:*), Bash(ls:*), Bash(mkdir:*)
+allowed-tools: [Read, Write, Edit, Glob, Grep, Bash(gh:*), Bash(git:*), Bash(ls:*), Bash(mkdir:*)]
 ---
 
 # /codex

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

@@ -7,7 +7,7 @@ globs:
   - "**/CONTEXT.md"
   - "**/DECISIONS.md"
 alwaysApply: false
-allowed-tools: Read, Write, Edit, Glob, Grep, Bash(gh:*), Bash(git:*), Bash(ls:*), Bash(mkdir:*)
+allowed-tools: [Read, Write, Edit, Glob, Grep, Bash(gh:*), Bash(git:*), Bash(ls:*), Bash(mkdir:*)]
 ---
 
 # Codex Skill
@@ -187,16 +187,22 @@ The codex has five categories:
 3. Match `{name}` against index keys and aliases (case-insensitive, partial match)
 4. If multiple matches → show list, let user pick
 5. If single match → load directly from the matched path
-6. For projects with multiple files → show file list, let user pick which to load
+6. **For projects → use progressive disclosure:**
+   - If CONTEXT.md exists → load it automatically (layer 1)
+   - Offer deeper files only if user needs more detail
+   - If no CONTEXT.md → synthesise one first (see below)
 7. Check freshness (see below)
-8. Output loaded content
+8. Output loaded content with "need more detail?" options
 
 **Why index?** Avoids expensive file-by-file searching. One read to find any entry by name or alias.
 
+**Progressive disclosure:** CONTEXT.md is the first layer - a synthesised summary (~2KB) that handles most queries. Only load full PRD/TECH-DESIGN/DECISIONS files when deeper detail is explicitly needed. This avoids loading 30KB+ of docs for simple context questions.
+
 **If no CONTEXT.md exists for a project:**
-- Synthesise unified context from PRD.md + TECH-DESIGN.md + DECISIONS.md
-- Create branch, commit CONTEXT.md, open PR
-- Inform user: "I've created a CONTEXT.md summarising this project - PR #{number}"
+- Spawn background agent to synthesise (non-blocking)
+- Immediately ask user which file to load - don't make them wait
+- Background agent: reads PRD.md + TECH-DESIGN.md + DECISIONS.md, synthesises, creates PR
+- Notify user when complete: "CONTEXT.md ready - PR #{number}"
 
 Full procedure: `references/loading.md`
 

package/dist/tools/codex/skills/droid-codex/references/loading.md

@@ -51,25 +51,47 @@ projects/transaction-templates/
 ├── PRD.md
 ├── TECH-DESIGN.md
 ├── DESIGN.md        # Optional
-├── CONTEXT.md       # Optional, auto-generated
+├── CONTEXT.md       # Auto-generated summary (progressive disclosure layer 1)
 └── DECISIONS.md
 ```
 
-**Procedure:**
+### Progressive Disclosure
+
+CONTEXT.md is the **first layer** - a synthesised summary that's enough for most queries. Only load full documents when deeper detail is needed.
+
+| Layer | What | When to use |
+|-------|------|-------------|
+| 1 | CONTEXT.md (~2KB) | General questions, getting oriented, "what is this project?" |
+| 2 | Specific file | Deep dives - "show me the full technical architecture" |
+| 3 | All files | Comprehensive review, major updates, onboarding |
+
+### Procedure
 
-1. List files in project folder
-2. Show file list to user:
+1. **List files** in project folder
+2. **Check for CONTEXT.md:**
+
+   **If CONTEXT.md exists:**
    ```
-   Found transaction-templates with:
-   - PRD.md (updated 2026-01-05)
-   - TECH-DESIGN.md (updated 2026-01-03)
-   - DECISIONS.md (updated 2026-01-07)
+   📂 Loading transaction-templates
+
+   CONTEXT.md available (updated 2026-01-05, ~2KB)
+   → Loading summary for general context...
+
+   [CONTEXT.md content]
 
-   Which files should I load? (or 'all' for everything)
+   ---
+   Need more detail? Available files:
+   - PRD.md - Full requirements and goals
+   - TECH-DESIGN.md - Architecture and implementation
+   - DECISIONS.md - Decision log
    ```
-3. Load selected file(s)
-4. Set project as **active** for scoped operations
-5. Check freshness (see below)
+   Load CONTEXT.md automatically. Only load additional files if user asks.
+
+   **If no CONTEXT.md:**
+   → Trigger auto-generation (see below)
+
+3. **Set project as active** for scoped operations
+4. **Check freshness** (see below)
 
 ## Loading a Domain or Proposal
 
@@ -103,11 +125,38 @@ topics/organization-hierarchy.md
 
 ## Auto-Generating CONTEXT.md
 
-If loading a project and no CONTEXT.md exists:
+If loading a project and no CONTEXT.md exists, generate it **asynchronously** so the user isn't blocked.
+
+**User sees:**
+```
+📂 Loading transaction-templates
+
+No CONTEXT.md found - I'll generate one in the background.
+Meanwhile, which file do you want to load?
 
-1. **Inform user:** "No CONTEXT.md found. I'll synthesise one from the available artifacts."
-2. **Read all available files:** PRD.md, TECH-DESIGN.md, DECISIONS.md
-3. **Generate unified summary:**
+Available files:
+- PRD.md - Full requirements and goals
+- TECH-DESIGN.md - Architecture and implementation
+- DECISIONS.md - Decision log
+```
+
+**Procedure:**
+
+1. **Spawn background agent** to synthesize CONTEXT.md (non-blocking):
+   ```
+   Use Task tool with subagent_type: "general-purpose" and run_in_background: true
+   Prompt: "Generate CONTEXT.md for {project} from PRD.md, TECH-DESIGN.md, DECISIONS.md. Create branch, commit, open PR."
+   ```
+2. **Immediately ask user** which file to load (don't wait for synthesis)
+3. **Load selected file** and continue working
+4. **When background agent completes**, inform user: "CONTEXT.md ready - PR #{number}"
+
+### Background Agent Task
+
+The background agent should:
+
+1. **Read all available files:** PRD.md, TECH-DESIGN.md, DECISIONS.md
+2. **Generate unified summary:**
    ```markdown
    ---
    title: {Project Name}
@@ -147,7 +196,12 @@ If loading a project and no CONTEXT.md exists:
    git push -u origin auto/context-{project-name}
    gh pr create --title "Auto-generated CONTEXT.md for {project}" --body "Synthesised from PRD, TECH-DESIGN, and DECISIONS."
    ```
-5. **Inform user:** "Created PR #{number} with auto-generated CONTEXT.md"
+5. **Return result** (background agent outputs to task output file):
+   ```
+   ✅ CONTEXT.md synthesised and PR #{number} created for {project}
+   ```
+
+   The main conversation will be notified when the background task completes.
 
 ## Freshness Checking
 

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

@@ -0,0 +1,16 @@
+{
+  "name": "droid-comments",
+  "version": "0.2.6",
+  "description": "Enable inline conversations using @droid/@user markers. Tag @droid to ask the AI, AI responds with @{your-name}. Use /comments check to address markers, /comments cleanup to remove resolved threads. Ideal for code review notes and async collaboration.",
+  "author": {
+    "name": "Orderful",
+    "url": "https://github.com/orderful"
+  },
+  "repository": "https://github.com/orderful/droid",
+  "license": "MIT",
+  "keywords": [
+    "droid",
+    "ai",
+    "comments"
+  ]
+}

package/dist/tools/comments/commands/comments.md

@@ -1,7 +1,7 @@
 ---
 description: Check and respond to inline @droid comments in code and docs
 argument-hint: "[check [{path}] | cleanup]"
-allowed-tools: Read, Edit, Grep, Glob, Bash(git diff:*), Bash(git status:*)
+allowed-tools: [Read, Edit, Grep, Glob, Bash(git diff:*), Bash(git status:*)]
 ---
 
 # /comments - Check and respond to inline comments

package/dist/tools/comments/skills/droid-comments/SKILL.md

@@ -4,7 +4,7 @@ description: "Inline conversations using @droid/@user markers in any file. Use w
 globs:
   - "**/*"
 alwaysApply: false
-allowed-tools: Read, Grep, Glob, Edit
+allowed-tools: [Read, Grep, Glob, Edit]
 ---
 
 # Comments Skill

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

@@ -0,0 +1,15 @@
+{
+  "name": "droid",
+  "version": "0.4.0",
+  "description": "Core droid meta-skill for update awareness and tool discovery. Checks for updates and helps users find the right tools.",
+  "author": {
+    "name": "Orderful",
+    "url": "https://github.com/orderful"
+  },
+  "repository": "https://github.com/orderful/droid",
+  "license": "MIT",
+  "keywords": [
+    "droid",
+    "ai"
+  ]
+}

package/dist/tools/droid/TOOL.yaml

@@ -1,6 +1,6 @@
 name: droid
 description: "Core droid meta-skill for update awareness and tool discovery. Checks for updates and helps users find the right tools."
-version: 0.2.1
+version: 0.4.0
 status: beta
 
 # System tool - always stays current regardless of auto-update settings

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

@@ -4,7 +4,7 @@ description: "Core droid meta-skill for updates and tool discovery. Use when che
 globs:
   - "**/*"
 alwaysApply: false
-allowed-tools: Bash
+allowed-tools: [Bash]
 ---
 
 # Droid

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

@@ -0,0 +1,16 @@
+{
+  "name": "droid-project",
+  "version": "0.2.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",
+    "url": "https://github.com/orderful"
+  },
+  "repository": "https://github.com/orderful/droid",
+  "license": "MIT",
+  "keywords": [
+    "droid",
+    "ai",
+    "project"
+  ]
+}

package/dist/tools/project/commands/project.md

@@ -1,7 +1,7 @@
 ---
 description: Manage project context files for persistent AI memory across sessions
 argument-hint: "[{keywords} | update | create {name}]"
-allowed-tools: Read, Write, Edit, Glob, Bash(mkdir:*), Bash(ls:*)
+allowed-tools: [Read, Write, Edit, Glob, Bash(mkdir:*), Bash(ls:*)]
 ---
 
 # /project

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

@@ -4,7 +4,7 @@ description: "Persistent project context for AI memory across sessions. Use when
 globs:
   - "**/PROJECT.md"
 alwaysApply: false
-allowed-tools: Read, Write, Glob, Grep
+allowed-tools: [Read, Write, Glob, Grep]
 ---
 
 # Project Skill

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

@@ -0,0 +1,16 @@
+{
+  "name": "droid-tech-design",
+  "version": "0.1.0",
+  "description": "Technical design authoring tool for engineers. Create structured tech design docs with /tech-design start, iterate in brain, publish to codex. Three-document approach: research doc (codebase discoveries) + thought doc (design workspace) + roll-up (clean summary for review).",
+  "author": {
+    "name": "Orderful",
+    "url": "https://github.com/orderful"
+  },
+  "repository": "https://github.com/orderful/droid",
+  "license": "MIT",
+  "keywords": [
+    "droid",
+    "ai",
+    "tech-design"
+  ]
+}

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

@@ -0,0 +1,18 @@
+name: tech-design
+description: "Technical design authoring tool for engineers. Create structured tech design docs with /tech-design start, iterate in brain, publish to codex. Three-document approach: research doc (codebase discoveries) + thought doc (design workspace) + roll-up (clean summary for review)."
+version: 0.1.0
+status: beta
+
+includes:
+  skills:
+    - name: droid-tech-design
+      required: true
+  commands:
+    - tech-design
+  agents: []
+
+dependencies:
+  - brain
+  - codex
+
+config_schema: {}

package/dist/tools/tech-design/commands/tech-design.md

@@ -0,0 +1,93 @@
+---
+description: Write, iterate, and publish technical design documents using a two-document approach - messy thought docs in brain, clean roll-ups in codex
+argument-hint: "[start --from codex:{project} | draft [section] | think [topic] | gaps | publish]"
+allowed-tools: [Read, Write, Edit, Glob, Grep, Bash(gh:*), Bash(git:*), Bash(mkdir:*), Task]
+---
+
+# /tech-design
+
+Entry point for technical design authoring. See the **tech-design skill** for full behavior.
+
+> Tech designs are where architectural decisions get made. Make them AI-friendly.
+
+## Arguments
+
+$ARGUMENTS
+
+## Why `/tech-design` not `/design`?
+
+Leaves `/design` open for actual design tooling (Figma workflows, design system docs, UI/UX review).
+
+## Prerequisites
+
+Before first use, verify:
+
+1. **Brain configured** - For thought doc drafting
+2. **Codex configured** - For PRD context and publishing
+3. **gh CLI** - For creating PRs
+
+## Usage
+
+```bash
+# Core Authoring (v1)
+/tech-design start --from codex:{project}  # Create thought doc, pull PRD/DESIGN context
+/tech-design draft [section]                # Auto-generate from PRD + codebase research
+/tech-design think [topic]                  # Guided exploration, stress-test ideas
+/tech-design gaps                           # Checklist of missing/empty sections
+/tech-design publish                        # Generate roll-up + thought doc, open PR to codex
+
+# Self-Review & Interaction (v2 - not yet implemented)
+# /tech-design critic [persona]   # Multi-persona review with severity scoring
+# /tech-design respond {question} # Author tool: search thought doc to draft reply
+# /tech-design ask {question}     # Reviewer tool: search both docs to answer questions
+```
+
+## Configuration
+
+Tech-design has no configuration of its own. It delegates to:
+
+- **Brain skill** - Thought doc location (`brain_dir`, `inbox_folder`)
+- **Codex skill** - Repository location (`codex_repo`)
+
+## Behavior
+
+Refer to the tech-design skill for:
+
+- **Starting**: How to create thought doc from codex context
+- **Drafting**: Research-first, structure-second content generation
+- **Thinking**: Guided exploration to stress-test ideas
+- **Gap Analysis**: What sections are missing or empty
+- **Publishing**: Generate clean roll-up and create PR
+
+The skill's `references/` folder contains detailed procedures for each workflow.
+
+## Two-Document Approach
+
+| Document        | Purpose                                 | Location      |
+| --------------- | --------------------------------------- | ------------- |
+| **Thought doc** | Messy iteration, @mentions, exploration | Brain         |
+| **Roll-up**     | Clean, reviewable, decision-focused     | Codex project |
+
+Both documents published to codex on `/tech-design publish` for full transparency.
+
+## Examples
+
+```bash
+# Start a new tech design from codex project context
+/tech-design start --from codex:transaction-templates
+
+# Draft the entire doc from PRD and codebase research
+/tech-design draft
+
+# Explore a specific idea before committing to it
+/tech-design think "Should we use events or polling for status updates?"
+
+# Draft just the rollout section
+/tech-design draft rollout
+
+# See what's missing
+/tech-design gaps
+
+# Publish to codex when ready for review
+/tech-design publish
+```

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

@@ -0,0 +1,218 @@
+---
+name: droid-tech-design
+description: "Technical design authoring with three-document approach - research doc (codebase discoveries), thought doc (design iteration), and roll-up (clean summary). Use when writing tech designs, drafting sections, exploring architectural ideas, or publishing to codex. User prompts like 'start tech design for X', 'draft the rollout section', 'let's think through the API design', 'publish this to codex'."
+globs: []
+alwaysApply: false
+allowed-tools:
+  [Read, Write, Edit, Glob, Grep, Bash(gh:*), Bash(git:*), Bash(mkdir:*), Task]
+---
+
+# Tech Design Skill
+
+> Tech designs are where architectural decisions get made. Make them AI-friendly.
+
+Technical design authoring for engineers using a three-document approach: research doc captures codebase discoveries, thought doc for design iteration, roll-up for reviewers. Markdown in GitHub, version-controlled, PR-reviewed.
+
+## Why This Matters
+
+Tech designs are often:
+
+- Written in Confluence (slow, disconnected from code)
+- Missing key sections (no template enforcement)
+- Hard to iterate on (not AI-friendly)
+- Siloed (reviewer can't see the author's thinking)
+- Re-discovering the same patterns every time
+
+The `/tech-design` skill brings tech design authoring into the same AI-augmented workflow engineers already use for coding, with persistent codebase knowledge.
+
+## Prerequisites
+
+Before using tech-design, verify:
+
+1. **Brain skill configured:** Check if `~/.droid/skills/brain/overrides.yaml` exists
+2. **Codex skill configured:** Check if `~/.droid/skills/codex/overrides.yaml` exists
+3. **gh CLI:** Required for PR workflows
+
+If prerequisites fail, guide user to configure:
+
+- Brain missing: Direct to `/brain` command to set up brain directory
+- Codex missing: Direct to `/codex` command to set up codex repository
+- gh missing: `brew install gh && gh auth login`
+
+## Configuration
+
+Tech-design has no configuration of its own. It delegates to:
+
+- **Brain skill** for research + thought doc location (`brain_dir`, `inbox_folder`)
+- **Codex skill** for repository location (`codex_repo`)
+
+## Three-Document Approach
+
+| Document        | Created When | Purpose                                         | Location      | Audience    |
+| --------------- | ------------ | ----------------------------------------------- | ------------- | ----------- |
+| **Research**    | `/start`     | Deep dive: codex project + codebase discoveries | Brain         | Author + AI |
+| **Thought doc** | `/start`     | Design iteration: decisions, @mentions, drafts  | Brain         | Author + AI |
+| **Roll-up**     | `/publish`   | Clean summary: decisions only, reviewable       | Codex project | Reviewers   |
+
+**Why three documents?**
+
+1. **Research doc** = Persistent memory of codebase exploration
+   - Project-specific patterns discovered
+   - Existing implementations found
+   - Dependencies identified
+   - Stack/framework details
+   - Lives across sessions, not just context window
+
+2. **Thought doc** = Design workspace
+   - References research doc for context
+   - Focuses on architectural decisions
+   - Iterates with `@droid`/`@user` comments
+   - Captures the "why" behind choices
+
+3. **Roll-up** = Reviewer artifact
+   - Synthesized from thought doc
+   - Decision-focused, no exploration noise
+   - Ready for PR review
+
+**Philosophy:** Research captures "what exists", thought doc explores "what we'll build", roll-up communicates "what we decided".
+
+Both thought doc and roll-up are published to codex. Research doc stays in brain as project-specific knowledge base.
+
+## Commands
+
+| Command                                     | Action                                                   | Status |
+| ------------------------------------------- | -------------------------------------------------------- | ------ |
+| `/tech-design start --from codex:{project}` | Create research + thought docs, pull PRD/DESIGN context  | v1     |
+| `/tech-design draft [section]`              | Auto-generate from research doc + codebase exploration   | v1     |
+| `/tech-design think [topic]`                | Guided exploration, updates research doc with findings   | v1     |
+| `/tech-design gaps`                         | Checklist of missing/empty sections                      | v1     |
+| `/tech-design publish`                      | Generate roll-up, publish thought doc + roll-up to codex | v1     |
+| `/tech-design critic [persona]`             | Multi-persona review with severity scoring               | v2     |
+| `/tech-design respond {question}`           | Author tool: search thought doc to draft reply           | v2     |
+| `/tech-design ask {question}`               | Reviewer tool: search both docs to answer questions      | v2     |
+
+## Conversational Skill Matching
+
+Commands are explicit entry points, but most usage will be natural conversation. Match these patterns:
+
+| User says                              | Interpret as                                         |
+| -------------------------------------- | ---------------------------------------------------- |
+| "Let's draft the rollout section"      | `/draft rollout` - draft that section with research  |
+| "Can you write up the data model?"     | `/draft data-model` - draft Data Model section       |
+| "I'm thinking about using events here" | `/think` - explore first, stress-test the idea       |
+| "Write that up"                        | After `/think`, transition to `/draft` for that idea |
+| "What's missing?"                      | `/gaps` - show checklist of empty sections           |
+| "Let's think through the API"          | `/think api` - guided exploration of API design      |
+
+## Starting a Tech Design
+
+**Trigger:** `/tech-design start --from codex:{project}` or user wants to start a new tech design
+
+**TLDR:** Create research + thought docs in brain, pull PRD/DESIGN context from codex, perform deep codebase dive, set as active.
+
+**Full procedure:** See `references/start.md` for detailed implementation steps, error handling, and examples.
+
+## Drafting Content
+
+**Trigger:** `/tech-design draft [section]` or user wants to generate content
+
+**TLDR:** Research doc first, then draft. Use research doc as knowledge base. Explore codebase if needed, update research doc with findings.
+
+**Full procedure:** See `references/draft.md` for research strategies, section-specific guidance, and examples.
+
+## Thinking Through Ideas
+
+**Trigger:** `/tech-design think [topic]` or user wants to explore an idea
+
+**TLDR:** Think = explore/stress-test; Draft = write to doc. Updates research doc with findings. Often flows: think → decide → draft.
+
+**Full procedure:** See `references/think.md` for questioning strategies, directed vs freeform modes, and examples.
+
+**Cross-platform approach:** Use prose-based questioning (works on OpenCode + Claude Code). Don't rely on interactive prompts.
+
+## Gap Analysis
+
+**Trigger:** `/tech-design gaps` or user asks "what's missing?"
+
+**TLDR:** Show checklist of sections that are empty or missing. Offer `/think` for each.
+
+**Full procedure:** See `references/gaps.md` for criticality logic, PRD-based inference, and examples.
+
+## Publishing to Codex
+
+**Trigger:** `/tech-design publish` or user wants to create PR for review
+
+**TLDR:** Generate clean roll-up from thought doc, publish thought doc + roll-up to codex (research doc stays in brain).
+
+**Full procedure:** See `references/publish.md` for roll-up generation, git workflow, quality checklist, and examples.
+
+## Active Doc Tracking
+
+Leverage brain's active doc tracking:
+
+- When `/tech-design start` creates research + thought docs, thought doc becomes active
+- Subsequent commands operate on active thought doc without specifying path
+- Research doc is referenced by path when needed (stays as reference knowledge)
+- User can also use `/brain` or `/scratchpad` to work on the thought doc
+
+**Integration nudge:** Always remind users they can use brain commands:
+
+- "You can add notes with `/brain add` or check comments with `/brain check`"
+
+## Template Philosophy
+
+**Research doc:** Codebase discovery log - captures patterns, implementations, stack details. Project-specific knowledge base.
+
+**Thought doc:** Start minimal (3 sections), grow as needed:
+
+- **Background** - Why we're doing this
+- **Proposal** - What we're building
+- **Open Questions** - What we don't know yet
+
+Use `/gaps` to surface what's missing. Don't overwhelm at the start.
+
+**Roll-up:** Clean summary for reviewers - decisions only, no exploration noise.
+
+## Related Skills
+
+- **Brain** - Thought doc drafting location, active doc tracking, @mention comments
+- **Codex** - Context input (PRD/DESIGN), output location (TECH-DESIGN.md), PR creation
+- **Project** - Personal working memory (different from shared codex knowledge)
+
+## V2 Features (Not Yet Implemented)
+
+The following features are planned for v2 but not yet available:
+
+### Critic Personas
+
+Run thought doc through multiple personas via parallel sub-agents:
+
+| Persona           | Focus                                     |
+| ----------------- | ----------------------------------------- |
+| Security          | Input validation, auth, rate limiting     |
+| Ops/SRE           | Monitoring, alerting, runbooks            |
+| Junior Engineer   | Clarity, documentation, "why X over Y?"   |
+| Product Owner     | Does this solve the user problem?         |
+| Future Maintainer | Will someone understand this in 6 months? |
+
+Output with severity scoring:
+
+```
+🔴 Security: No input validation mentioned for user-provided templates
+🔴 Ops: Missing monitoring/alerting strategy
+🟡 Future Maintainer: Decision rationale for X over Y is thin
+🟢 Product: Aligns well with PRD requirements
+🟢 Junior: Implementation plan is clear
+```
+
+### Interaction Tools
+
+- `/tech-design respond {question}` - Author tool: search thought doc to draft reply to reviewer questions
+- `/tech-design ask {question}` - Reviewer tool: search both docs to answer questions
+
+## Notes
+
+- Only create thought docs when user explicitly starts a tech design (don't be proactive)
+- Always check for existing thought doc before creating new one
+- Respect user's draft location preference (don't hardcode paths)
+- If codex project missing: warn but continue (common during early adoption)