@orderful/droid 0.23.0 → 0.24.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @orderful/droid
 
+## 0.24.0
+
+### Minor Changes
+
+- [#118](https://github.com/Orderful/droid/pull/118) [`9a9b27c`](https://github.com/Orderful/droid/commit/9a9b27c439d7fdbfb246faa6121495d0249b007c) Thanks [@frytyler](https://github.com/frytyler)! - Add domains and proposals categories to codex
+  - Add `domains/` category for business domain knowledge (the "what" and "why")
+  - Add `proposals/` category for ideas and future direction (not yet committed)
+  - Unify creation commands under `/codex new`:
+    - `/codex new domain {name}`
+    - `/codex new proposal {name}`
+    - `/codex new topic {name}` (replaces `/codex add topic`)
+    - `/codex new pattern {name}`
+  - Add list commands: `/codex domains`, `/codex proposals`
+  - Update document processor agent to support domain and proposal types
+
+### Patch Changes
+
+- [#121](https://github.com/Orderful/droid/pull/121) [`8895c54`](https://github.com/Orderful/droid/commit/8895c547aea2070e7e97749028baa6100e2c85c0) Thanks [@frytyler](https://github.com/frytyler)! - Update codex skill to use index.yaml for fast entry lookups instead of searching through all categories
+
 ## 0.23.0
 
 ### Minor Changes

package/dist/tools/codex/TOOL.yaml

@@ -1,5 +1,5 @@
 name: codex
-description: "Shared organizational knowledge - PRDs, tech designs, patterns, and explored topics. Use when loading project context, searching codex, capturing decisions, or adding explored topics."
+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.0
 status: beta
 

package/dist/tools/codex/agents/codex-document-processor.md

@@ -14,7 +14,7 @@ You are a document processor for the Orderful codex. Your job is to transform so
 
 You will receive:
 1. **File path** - The source document to process
-2. **Document type** - One of: `prd`, `tech-design`, `topic`, `pattern`, `artifact`
+2. **Document type** - One of: `prd`, `tech-design`, `topic`, `pattern`, `domain`, `proposal`, `artifact`
 3. **Project/entry name** - Where this should be stored in the codex
 4. **Codex repo path** - The local path to orderful-codex repository
 5. **Artifact filename** (optional, for artifacts) - Name for the artifact file
@@ -23,7 +23,7 @@ You will receive:
 
 Before processing, validate all inputs:
 
-1. **Document type** - Must be one of: `prd`, `tech-design`, `topic`, `pattern`, `artifact`. Reject anything else.
+1. **Document type** - Must be one of: `prd`, `tech-design`, `topic`, `pattern`, `domain`, `proposal`, `artifact`. Reject anything else.
 2. **File path** - Must exist and be readable. Use Read tool to verify.
 3. **Project/entry name** - Must be safe for filesystem paths:
    - Only allow: alphanumeric, dashes, underscores
@@ -47,11 +47,11 @@ From the content, identify:
 - **Codebase paths** (if tech-design) - Any code paths mentioned
 - **Source** - Default based on type:
   - PRD/tech-design: `confluence`
-  - Topic/pattern: `exploration`
+  - Topic/pattern/domain/proposal: `exploration`
   - Artifact: infer from content (`interview`, `transcript`, `notes`, `meeting`, `research`, `spike`, `analysis`)
 - **Status** - Default based on type:
   - PRD/tech-design: `draft` (new imports start as drafts)
-  - Topic/pattern/artifact: `active`
+  - Topic/pattern/domain/proposal/artifact: `active`
 
 ### 3. Read and Apply Frontmatter Template
 
@@ -63,6 +63,8 @@ From the content, identify:
 | `tech-design` | `{codex_repo}/templates/TECH-DESIGN.md` |
 | `topic` | `{codex_repo}/templates/TOPIC.md` |
 | `pattern` | `{codex_repo}/templates/PATTERN.md` |
+| `domain` | `{codex_repo}/templates/DOMAIN.md` |
+| `proposal` | `{codex_repo}/templates/PROPOSAL.md` |
 | `artifact` | `{codex_repo}/templates/ARTIFACT.md` |
 
 1. Read the appropriate template file
@@ -95,6 +97,8 @@ Write the processed markdown to the correct location:
 | `tech-design` | `{codex_repo}/projects/{name}/TECH-DESIGN.md` |
 | `topic` | `{codex_repo}/topics/{name}.md` |
 | `pattern` | `{codex_repo}/patterns/{name}.md` |
+| `domain` | `{codex_repo}/domains/{name}.md` |
+| `proposal` | `{codex_repo}/proposals/{name}.md` |
 | `artifact` | `{codex_repo}/projects/{name}/artifacts/{filename}.md` |
 
 For artifacts, derive `{filename}` from the artifact filename input or the source file's name (slugified).

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

@@ -1,6 +1,6 @@
 ---
-description: Shared organizational knowledge - PRDs, tech designs, patterns, and explored topics
-argument-hint: "[projects | patterns | topics | {name} | search {query} | new {name} | decision {text} | add topic {name}]"
+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:*)
 ---
 
@@ -24,16 +24,23 @@ Before first use, verify:
 ## Usage
 
 ```bash
-/codex                           # Show categories (projects, patterns, topics)
+/codex                           # Show categories (5 total)
 /codex projects                  # List projects
+/codex domains                   # List domains
+/codex proposals                 # List proposals
 /codex patterns                  # List patterns
 /codex topics                    # List topics
 /codex {name}                    # Load entry (searches all categories)
 /codex search {query}            # Search across everything
-/codex new {name}                # Scaffold new project from templates
+/codex new {name}                # Scaffold new project (shorthand)
+/codex new project {name}        # Scaffold new project from templates
+/codex new domain {name}         # Scaffold new domain entry
+/codex new proposal {name}       # Scaffold new proposal entry
+/codex new pattern {name}        # Scaffold new pattern entry
+/codex new topic {name}          # Scaffold new topic entry
 /codex decision {text}           # Append to active project's DECISIONS.md
-/codex snapshot {file} {name}    # Import PDF/markdown to project
-/codex add topic {name}          # Add explored topic with freshness metadata
+/codex snapshot {type} {file} {name}  # Import PDF/markdown to codex
+/codex artifact {file} {project}      # Add supporting artifact to project
 ```
 
 ## Configuration
@@ -48,8 +55,7 @@ Before first use, verify:
 Refer to the codex skill for:
 - **Loading**: How to search, handle matches, check freshness, auto-generate CONTEXT.md
 - **Decisions**: How to append to active project's DECISIONS.md
-- **Topics**: How to capture explored codebase areas with freshness metadata
-- **Creating**: How to scaffold new projects from templates
+- **Creating**: How to scaffold new entries (projects, domains, proposals, patterns, topics)
 
 The skill's `references/` folder contains detailed procedures for each workflow.
 
@@ -65,6 +71,8 @@ The skill's `references/` folder contains detailed procedures for each workflow.
 # Capture a decision during implementation
 /codex decision "Using UUIDv7 for IDs because it's sortable and includes timestamp"
 
-# Save today's exploration as a topic
-/codex add topic organization-hierarchy
+# Create new entries
+/codex new domain partnerships
+/codex new proposal caching-layer
+/codex new topic organization-hierarchy
 ```

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

@@ -102,11 +102,13 @@ fi
 
 ## Categories
 
-The codex has three categories:
+The codex has five categories:
 
 | Category | Path | Purpose |
 |----------|------|---------|
 | `projects` | `{codex_repo}/projects/` | Feature/project context (PRD, tech design, decisions) |
+| `domains` | `{codex_repo}/domains/` | Business domain knowledge - the "what" and "why" |
+| `proposals` | `{codex_repo}/proposals/` | Ideas and future direction - not yet committed |
 | `patterns` | `{codex_repo}/patterns/` | Cross-cutting technical patterns |
 | `topics` | `{codex_repo}/topics/` | Explored codebase areas with freshness tracking |
 
@@ -116,15 +118,21 @@ The codex has three categories:
 |---------|--------|
 | `/codex` | Show categories overview |
 | `/codex projects` | List all projects |
+| `/codex domains` | List all domains |
+| `/codex proposals` | List all proposals |
 | `/codex patterns` | List all patterns |
 | `/codex topics` | List all topics |
 | `/codex {name}` | Load entry (searches all categories) |
 | `/codex search {query}` | Search across everything |
-| `/codex new {name}` | Scaffold new project from templates |
+| `/codex new {name}` | Scaffold new project (shorthand) |
+| `/codex new project {name}` | Scaffold new project from templates |
+| `/codex new domain {name}` | Scaffold new domain entry |
+| `/codex new proposal {name}` | Scaffold new proposal entry |
+| `/codex new pattern {name}` | Scaffold new pattern entry |
+| `/codex new topic {name}` | Scaffold new topic entry |
 | `/codex decision {text}` | Append to active project's DECISIONS.md |
 | `/codex snapshot {type} {file} {name}` | Import PDF/markdown to codex (uses agent) |
 | `/codex artifact {file} {project}` | Add supporting artifact to project (uses agent) |
-| `/codex add topic {name}` | Add explored topic with freshness metadata |
 
 ## Loading an Entry
 
@@ -132,12 +140,15 @@ The codex has three categories:
 
 **Procedure:**
 
-1. Search for `{name}` across all categories (fuzzy match on folder/file names)
-2. If multiple matches → show list, let user pick
-3. If single match → load it
-4. For projects with multiple files → show file list, let user pick which to load
-5. Check freshness (see below)
-6. Output loaded content
+1. **Read `{codex_repo}/index.yaml`** - this contains all entry names and aliases for fast lookup
+2. Match `{name}` against index keys and aliases (case-insensitive, partial match)
+3. If multiple matches → show list, let user pick
+4. If single match → load directly from the matched path
+5. For projects with multiple files → show file list, let user pick which to load
+6. Check freshness (see below)
+7. Output loaded content
+
+**Why index?** Avoids expensive file-by-file searching. One read to find any entry by name or alias.
 
 **If no CONTEXT.md exists for a project:**
 - Synthesise unified context from PRD.md + TECH-DESIGN.md + DECISIONS.md
@@ -153,7 +164,7 @@ All codex files have frontmatter:
 ```yaml
 ---
 title: Feature Name
-type: prd | tech-design | context | decisions | pattern | topic
+type: prd | tech-design | context | decisions | pattern | topic | domain | proposal
 status: draft | active | complete | archived
 created: 2026-01-07
 updated: 2026-01-07
@@ -164,14 +175,12 @@ codebase_paths:
 ---
 ```
 
-**Status values:**
+**Status values (unified across all categories):**
 - `draft` - Initial capture, not ready for consumption
 - `active` - Current, being used for implementation
 - `complete` - Project shipped, kept for reference
 - `archived` - No longer relevant, kept for history
 
-Note: Topics use `draft | active | archived` (no "complete"). Patterns use `active | archived` (no draft phase).
-
 **When loading any file:**
 
 1. Parse frontmatter for `updated` date
@@ -217,7 +226,7 @@ Full procedure: `references/decisions.md`
 
 ## Adding Topics
 
-**Trigger:** `/codex add topic {name}` or user wants to save exploration
+**Trigger:** `/codex new topic {name}` or user wants to save exploration
 
 **Procedure:**
 
@@ -297,9 +306,22 @@ 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`.
 
-## Creating New Projects
+## Creating New Entries
+
+The `/codex new` command scaffolds new entries from templates:
+
+```bash
+/codex new {name}              # Shorthand for new project
+/codex new project {name}      # Explicit project creation
+/codex new domain {name}       # New domain entry
+/codex new proposal {name}     # New proposal entry
+/codex new pattern {name}      # New pattern entry
+/codex new topic {name}        # New topic entry
+```
+
+### Projects
 
-**Trigger:** `/codex new {name}` or user wants to start new project entry
+**Trigger:** `/codex new {name}` or `/codex new project {name}`
 
 **Procedure:**
 
@@ -311,6 +333,41 @@ Artifacts get lighter frontmatter with `type: artifact` and source like `intervi
 3. Fill in frontmatter with today's date
 4. Create branch, commit, and open PR via `gh pr create`
 
+### Domains
+
+**Trigger:** `/codex new domain {name}`
+
+**Procedure:**
+
+1. Create `{codex_repo}/domains/{name}.md`
+2. Use template from `{codex_repo}/templates/DOMAIN.md`
+3. Fill in frontmatter with today's date
+4. Guide user through sections: Overview, Key Concepts, Entities, Lifecycle/States, Integration Points, Related
+5. Create branch, commit, and open PR via `gh pr create`
+
+### Proposals
+
+**Trigger:** `/codex new proposal {name}`
+
+**Procedure:**
+
+1. Create `{codex_repo}/proposals/{name}.md`
+2. Use template from `{codex_repo}/templates/PROPOSAL.md`
+3. Fill in frontmatter with today's date
+4. Guide user through sections: Summary, Problem, Proposed Solution, Alternatives Considered, Open Questions, Next Steps
+5. Create branch, commit, and open PR via `gh pr create`
+
+### Patterns and Topics
+
+**Trigger:** `/codex new pattern {name}` or `/codex new topic {name}`
+
+**Procedure:**
+
+1. Create file at `{codex_repo}/patterns/{name}.md` or `{codex_repo}/topics/{name}.md`
+2. Use template from `{codex_repo}/templates/PATTERN.md` or `{codex_repo}/templates/TOPIC.md`
+3. Fill in frontmatter with today's date
+4. Create branch, commit, and open PR via `gh pr create`
+
 Full procedure: `references/creating.md`
 
 ## Integration with /project

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

@@ -4,23 +4,44 @@ Detailed procedure for loading entries from the codex.
 
 ## Search and Match
 
-1. **Get codex repo path** from `~/.droid/skills/codex/overrides.yaml`
-2. **Search all categories** for `{name}`:
-   ```bash
-   # Search projects
-   ls {codex_repo}/projects/ | grep -i {name}
-
-   # Search patterns
-   ls {codex_repo}/patterns/ | grep -i {name}
+**IMPORTANT:** Use the index file for fast lookups. This avoids expensive file-by-file searching.
 
-   # Search topics
-   ls {codex_repo}/topics/ | grep -i {name}
+1. **Get codex repo path** from `~/.droid/skills/codex/overrides.yaml`
+2. **Read the index file** at `{codex_repo}/index.yaml`:
+   ```yaml
+   # index.yaml structure
+   projects:
+     partnership-automation:
+       title: "Partnership Automation & Sample Transaction Engine"
+       aliases: ["transaction-templates", "template-transactions"]
+   patterns:
+     jsdoc-config-directives:
+       title: "JSDoc @config Directives"
+       aliases: ["config-directives", "comment-directives"]
+   topics:
+     handlebars-template-security:
+       title: "Handlebars Template Security"
+       aliases: []
+   domains: {}
+   proposals: {}
    ```
-3. **Handle matches:**
-   - No matches → "No codex entry found for '{name}'. Did you mean one of these?" + list recent entries
-   - Single match → proceed to load
+3. **Match `{name}` against the index:**
+   - Check each entry's key (folder/file name)
+   - Check each entry's `aliases` array
+   - Match is case-insensitive and supports partial matching
+   - Example: "template transactions" matches `partnership-automation` via alias "template-transactions"
+4. **Handle matches:**
+   - No matches → "No codex entry found for '{name}'. Did you mean one of these?" + suggest entries from index
+   - Single match → proceed to load from the matched category/path
    - Multiple matches → show list with category, let user pick
 
+**Fallback:** If `index.yaml` doesn't exist, fall back to directory scanning:
+```bash
+ls {codex_repo}/projects/ | grep -i {name}
+ls {codex_repo}/domains/ | grep -i {name}
+# ... etc
+```
+
 ## Loading a Project
 
 Projects are folders with multiple files:
@@ -50,6 +71,21 @@ projects/transaction-templates/
 4. Set project as **active** for scoped operations
 5. Check freshness (see below)
 
+## Loading a Domain or Proposal
+
+Domains and proposals are single files:
+
+```
+domains/partnerships.md
+proposals/caching-layer.md
+```
+
+**Procedure:**
+
+1. Read the file
+2. Check freshness
+3. Output content
+
 ## Loading a Pattern or Topic
 
 Patterns and topics are single files:

package/package.json

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

package/src/tools/codex/TOOL.yaml

@@ -1,5 +1,5 @@
 name: codex
-description: "Shared organizational knowledge - PRDs, tech designs, patterns, and explored topics. Use when loading project context, searching codex, capturing decisions, or adding explored topics."
+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.0
 status: beta
 

package/src/tools/codex/agents/codex-document-processor.md

@@ -14,7 +14,7 @@ You are a document processor for the Orderful codex. Your job is to transform so
 
 You will receive:
 1. **File path** - The source document to process
-2. **Document type** - One of: `prd`, `tech-design`, `topic`, `pattern`, `artifact`
+2. **Document type** - One of: `prd`, `tech-design`, `topic`, `pattern`, `domain`, `proposal`, `artifact`
 3. **Project/entry name** - Where this should be stored in the codex
 4. **Codex repo path** - The local path to orderful-codex repository
 5. **Artifact filename** (optional, for artifacts) - Name for the artifact file
@@ -23,7 +23,7 @@ You will receive:
 
 Before processing, validate all inputs:
 
-1. **Document type** - Must be one of: `prd`, `tech-design`, `topic`, `pattern`, `artifact`. Reject anything else.
+1. **Document type** - Must be one of: `prd`, `tech-design`, `topic`, `pattern`, `domain`, `proposal`, `artifact`. Reject anything else.
 2. **File path** - Must exist and be readable. Use Read tool to verify.
 3. **Project/entry name** - Must be safe for filesystem paths:
    - Only allow: alphanumeric, dashes, underscores
@@ -47,11 +47,11 @@ From the content, identify:
 - **Codebase paths** (if tech-design) - Any code paths mentioned
 - **Source** - Default based on type:
   - PRD/tech-design: `confluence`
-  - Topic/pattern: `exploration`
+  - Topic/pattern/domain/proposal: `exploration`
   - Artifact: infer from content (`interview`, `transcript`, `notes`, `meeting`, `research`, `spike`, `analysis`)
 - **Status** - Default based on type:
   - PRD/tech-design: `draft` (new imports start as drafts)
-  - Topic/pattern/artifact: `active`
+  - Topic/pattern/domain/proposal/artifact: `active`
 
 ### 3. Read and Apply Frontmatter Template
 
@@ -63,6 +63,8 @@ From the content, identify:
 | `tech-design` | `{codex_repo}/templates/TECH-DESIGN.md` |
 | `topic` | `{codex_repo}/templates/TOPIC.md` |
 | `pattern` | `{codex_repo}/templates/PATTERN.md` |
+| `domain` | `{codex_repo}/templates/DOMAIN.md` |
+| `proposal` | `{codex_repo}/templates/PROPOSAL.md` |
 | `artifact` | `{codex_repo}/templates/ARTIFACT.md` |
 
 1. Read the appropriate template file
@@ -95,6 +97,8 @@ Write the processed markdown to the correct location:
 | `tech-design` | `{codex_repo}/projects/{name}/TECH-DESIGN.md` |
 | `topic` | `{codex_repo}/topics/{name}.md` |
 | `pattern` | `{codex_repo}/patterns/{name}.md` |
+| `domain` | `{codex_repo}/domains/{name}.md` |
+| `proposal` | `{codex_repo}/proposals/{name}.md` |
 | `artifact` | `{codex_repo}/projects/{name}/artifacts/{filename}.md` |
 
 For artifacts, derive `{filename}` from the artifact filename input or the source file's name (slugified).

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

@@ -1,6 +1,6 @@
 ---
-description: Shared organizational knowledge - PRDs, tech designs, patterns, and explored topics
-argument-hint: "[projects | patterns | topics | {name} | search {query} | new {name} | decision {text} | add topic {name}]"
+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:*)
 ---
 
@@ -24,16 +24,23 @@ Before first use, verify:
 ## Usage
 
 ```bash
-/codex                           # Show categories (projects, patterns, topics)
+/codex                           # Show categories (5 total)
 /codex projects                  # List projects
+/codex domains                   # List domains
+/codex proposals                 # List proposals
 /codex patterns                  # List patterns
 /codex topics                    # List topics
 /codex {name}                    # Load entry (searches all categories)
 /codex search {query}            # Search across everything
-/codex new {name}                # Scaffold new project from templates
+/codex new {name}                # Scaffold new project (shorthand)
+/codex new project {name}        # Scaffold new project from templates
+/codex new domain {name}         # Scaffold new domain entry
+/codex new proposal {name}       # Scaffold new proposal entry
+/codex new pattern {name}        # Scaffold new pattern entry
+/codex new topic {name}          # Scaffold new topic entry
 /codex decision {text}           # Append to active project's DECISIONS.md
-/codex snapshot {file} {name}    # Import PDF/markdown to project
-/codex add topic {name}          # Add explored topic with freshness metadata
+/codex snapshot {type} {file} {name}  # Import PDF/markdown to codex
+/codex artifact {file} {project}      # Add supporting artifact to project
 ```
 
 ## Configuration
@@ -48,8 +55,7 @@ Before first use, verify:
 Refer to the codex skill for:
 - **Loading**: How to search, handle matches, check freshness, auto-generate CONTEXT.md
 - **Decisions**: How to append to active project's DECISIONS.md
-- **Topics**: How to capture explored codebase areas with freshness metadata
-- **Creating**: How to scaffold new projects from templates
+- **Creating**: How to scaffold new entries (projects, domains, proposals, patterns, topics)
 
 The skill's `references/` folder contains detailed procedures for each workflow.
 
@@ -65,6 +71,8 @@ The skill's `references/` folder contains detailed procedures for each workflow.
 # Capture a decision during implementation
 /codex decision "Using UUIDv7 for IDs because it's sortable and includes timestamp"
 
-# Save today's exploration as a topic
-/codex add topic organization-hierarchy
+# Create new entries
+/codex new domain partnerships
+/codex new proposal caching-layer
+/codex new topic organization-hierarchy
 ```

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

@@ -102,11 +102,13 @@ fi
 
 ## Categories
 
-The codex has three categories:
+The codex has five categories:
 
 | Category | Path | Purpose |
 |----------|------|---------|
 | `projects` | `{codex_repo}/projects/` | Feature/project context (PRD, tech design, decisions) |
+| `domains` | `{codex_repo}/domains/` | Business domain knowledge - the "what" and "why" |
+| `proposals` | `{codex_repo}/proposals/` | Ideas and future direction - not yet committed |
 | `patterns` | `{codex_repo}/patterns/` | Cross-cutting technical patterns |
 | `topics` | `{codex_repo}/topics/` | Explored codebase areas with freshness tracking |
 
@@ -116,15 +118,21 @@ The codex has three categories:
 |---------|--------|
 | `/codex` | Show categories overview |
 | `/codex projects` | List all projects |
+| `/codex domains` | List all domains |
+| `/codex proposals` | List all proposals |
 | `/codex patterns` | List all patterns |
 | `/codex topics` | List all topics |
 | `/codex {name}` | Load entry (searches all categories) |
 | `/codex search {query}` | Search across everything |
-| `/codex new {name}` | Scaffold new project from templates |
+| `/codex new {name}` | Scaffold new project (shorthand) |
+| `/codex new project {name}` | Scaffold new project from templates |
+| `/codex new domain {name}` | Scaffold new domain entry |
+| `/codex new proposal {name}` | Scaffold new proposal entry |
+| `/codex new pattern {name}` | Scaffold new pattern entry |
+| `/codex new topic {name}` | Scaffold new topic entry |
 | `/codex decision {text}` | Append to active project's DECISIONS.md |
 | `/codex snapshot {type} {file} {name}` | Import PDF/markdown to codex (uses agent) |
 | `/codex artifact {file} {project}` | Add supporting artifact to project (uses agent) |
-| `/codex add topic {name}` | Add explored topic with freshness metadata |
 
 ## Loading an Entry
 
@@ -132,12 +140,15 @@ The codex has three categories:
 
 **Procedure:**
 
-1. Search for `{name}` across all categories (fuzzy match on folder/file names)
-2. If multiple matches → show list, let user pick
-3. If single match → load it
-4. For projects with multiple files → show file list, let user pick which to load
-5. Check freshness (see below)
-6. Output loaded content
+1. **Read `{codex_repo}/index.yaml`** - this contains all entry names and aliases for fast lookup
+2. Match `{name}` against index keys and aliases (case-insensitive, partial match)
+3. If multiple matches → show list, let user pick
+4. If single match → load directly from the matched path
+5. For projects with multiple files → show file list, let user pick which to load
+6. Check freshness (see below)
+7. Output loaded content
+
+**Why index?** Avoids expensive file-by-file searching. One read to find any entry by name or alias.
 
 **If no CONTEXT.md exists for a project:**
 - Synthesise unified context from PRD.md + TECH-DESIGN.md + DECISIONS.md
@@ -153,7 +164,7 @@ All codex files have frontmatter:
 ```yaml
 ---
 title: Feature Name
-type: prd | tech-design | context | decisions | pattern | topic
+type: prd | tech-design | context | decisions | pattern | topic | domain | proposal
 status: draft | active | complete | archived
 created: 2026-01-07
 updated: 2026-01-07
@@ -164,14 +175,12 @@ codebase_paths:
 ---
 ```
 
-**Status values:**
+**Status values (unified across all categories):**
 - `draft` - Initial capture, not ready for consumption
 - `active` - Current, being used for implementation
 - `complete` - Project shipped, kept for reference
 - `archived` - No longer relevant, kept for history
 
-Note: Topics use `draft | active | archived` (no "complete"). Patterns use `active | archived` (no draft phase).
-
 **When loading any file:**
 
 1. Parse frontmatter for `updated` date
@@ -217,7 +226,7 @@ Full procedure: `references/decisions.md`
 
 ## Adding Topics
 
-**Trigger:** `/codex add topic {name}` or user wants to save exploration
+**Trigger:** `/codex new topic {name}` or user wants to save exploration
 
 **Procedure:**
 
@@ -297,9 +306,22 @@ 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`.
 
-## Creating New Projects
+## Creating New Entries
+
+The `/codex new` command scaffolds new entries from templates:
+
+```bash
+/codex new {name}              # Shorthand for new project
+/codex new project {name}      # Explicit project creation
+/codex new domain {name}       # New domain entry
+/codex new proposal {name}     # New proposal entry
+/codex new pattern {name}      # New pattern entry
+/codex new topic {name}        # New topic entry
+```
+
+### Projects
 
-**Trigger:** `/codex new {name}` or user wants to start new project entry
+**Trigger:** `/codex new {name}` or `/codex new project {name}`
 
 **Procedure:**
 
@@ -311,6 +333,41 @@ Artifacts get lighter frontmatter with `type: artifact` and source like `intervi
 3. Fill in frontmatter with today's date
 4. Create branch, commit, and open PR via `gh pr create`
 
+### Domains
+
+**Trigger:** `/codex new domain {name}`
+
+**Procedure:**
+
+1. Create `{codex_repo}/domains/{name}.md`
+2. Use template from `{codex_repo}/templates/DOMAIN.md`
+3. Fill in frontmatter with today's date
+4. Guide user through sections: Overview, Key Concepts, Entities, Lifecycle/States, Integration Points, Related
+5. Create branch, commit, and open PR via `gh pr create`
+
+### Proposals
+
+**Trigger:** `/codex new proposal {name}`
+
+**Procedure:**
+
+1. Create `{codex_repo}/proposals/{name}.md`
+2. Use template from `{codex_repo}/templates/PROPOSAL.md`
+3. Fill in frontmatter with today's date
+4. Guide user through sections: Summary, Problem, Proposed Solution, Alternatives Considered, Open Questions, Next Steps
+5. Create branch, commit, and open PR via `gh pr create`
+
+### Patterns and Topics
+
+**Trigger:** `/codex new pattern {name}` or `/codex new topic {name}`
+
+**Procedure:**
+
+1. Create file at `{codex_repo}/patterns/{name}.md` or `{codex_repo}/topics/{name}.md`
+2. Use template from `{codex_repo}/templates/PATTERN.md` or `{codex_repo}/templates/TOPIC.md`
+3. Fill in frontmatter with today's date
+4. Create branch, commit, and open PR via `gh pr create`
+
 Full procedure: `references/creating.md`
 
 ## Integration with /project

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

@@ -4,23 +4,44 @@ Detailed procedure for loading entries from the codex.
 
 ## Search and Match
 
-1. **Get codex repo path** from `~/.droid/skills/codex/overrides.yaml`
-2. **Search all categories** for `{name}`:
-   ```bash
-   # Search projects
-   ls {codex_repo}/projects/ | grep -i {name}
-
-   # Search patterns
-   ls {codex_repo}/patterns/ | grep -i {name}
+**IMPORTANT:** Use the index file for fast lookups. This avoids expensive file-by-file searching.
 
-   # Search topics
-   ls {codex_repo}/topics/ | grep -i {name}
+1. **Get codex repo path** from `~/.droid/skills/codex/overrides.yaml`
+2. **Read the index file** at `{codex_repo}/index.yaml`:
+   ```yaml
+   # index.yaml structure
+   projects:
+     partnership-automation:
+       title: "Partnership Automation & Sample Transaction Engine"
+       aliases: ["transaction-templates", "template-transactions"]
+   patterns:
+     jsdoc-config-directives:
+       title: "JSDoc @config Directives"
+       aliases: ["config-directives", "comment-directives"]
+   topics:
+     handlebars-template-security:
+       title: "Handlebars Template Security"
+       aliases: []
+   domains: {}
+   proposals: {}
    ```
-3. **Handle matches:**
-   - No matches → "No codex entry found for '{name}'. Did you mean one of these?" + list recent entries
-   - Single match → proceed to load
+3. **Match `{name}` against the index:**
+   - Check each entry's key (folder/file name)
+   - Check each entry's `aliases` array
+   - Match is case-insensitive and supports partial matching
+   - Example: "template transactions" matches `partnership-automation` via alias "template-transactions"
+4. **Handle matches:**
+   - No matches → "No codex entry found for '{name}'. Did you mean one of these?" + suggest entries from index
+   - Single match → proceed to load from the matched category/path
    - Multiple matches → show list with category, let user pick
 
+**Fallback:** If `index.yaml` doesn't exist, fall back to directory scanning:
+```bash
+ls {codex_repo}/projects/ | grep -i {name}
+ls {codex_repo}/domains/ | grep -i {name}
+# ... etc
+```
+
 ## Loading a Project
 
 Projects are folders with multiple files:
@@ -50,6 +71,21 @@ projects/transaction-templates/
 4. Set project as **active** for scoped operations
 5. Check freshness (see below)
 
+## Loading a Domain or Proposal
+
+Domains and proposals are single files:
+
+```
+domains/partnerships.md
+proposals/caching-layer.md
+```
+
+**Procedure:**
+
+1. Read the file
+2. Check freshness
+3. Output content
+
 ## Loading a Pattern or Topic
 
 Patterns and topics are single files: