@orderful/droid 0.23.0 → 0.25.0

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

@@ -35,15 +35,54 @@ If prerequisites fail, guide user to fix:
 - Repo missing: `git clone git@github.com:orderful/orderful-codex.git {path}`
 - gh missing: `brew install gh && gh auth login`
 
-## Sync Before Reading
+## Git Hygiene (CRITICAL)
 
-**Before any read operation** (loading, searching, listing), pull latest:
+**Users should never see git complexity.** Use the deterministic scripts below - they handle all git operations silently and recover gracefully. Non-engineers use this tool - if they hit a git error, they're stuck.
+
+### Scripts
+
+The codex skill includes three git scripts. **Always use these instead of raw git commands.**
+
+| Script | Purpose | When to use |
+|--------|---------|-------------|
+| `git-preamble` | Ensure clean main + pull latest | Before ANY operation |
+| `git-start-write` | Preamble + create branch | Before write operations |
+| `git-finish-write` | Commit + PR + return to main | After write operations |
+
+### Read Operations (search, load, list)
+
+```bash
+droid config codex | droid exec droid-codex git-preamble --config -
+# Then proceed with the read
+```
+
+### Write Operations (new, decision, snapshot, artifact)
 
 ```bash
-git -C {codex_repo} pull --rebase --quiet
+# 1. Start write (runs preamble + creates branch)
+droid config codex | droid exec droid-codex git-start-write --config - --branch codex/{action}-{name}
+
+# 2. Make your changes (write files)
+
+# 3. Finish write (commit + PR + return to main)
+droid config codex | droid exec droid-codex git-finish-write --config - \
+  --message "{commit message}" \
+  --pr-title "{PR title}" \
+  --pr-body "{PR description}"
 ```
 
-This ensures shared knowledge is always current. The pull is quiet to avoid noise, but if it fails (conflicts, network), warn the user.
+The scripts return JSON with success/failure status. Check the result before proceeding.
+
+### Error Handling
+
+The scripts handle errors internally:
+- Silent recovery for transient issues
+- Clear error messages in JSON output
+- Automatic return to main even on partial failure
+
+If a script fails, check the JSON `error` field and report a user-friendly message:
+- "I hit a sync issue with the codex. Let me try again..."
+- Only escalate as last resort: "The codex repo needs manual attention."
 
 ## Security
 
@@ -102,11 +141,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 +157,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 +179,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 +203,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 +214,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
@@ -199,36 +247,24 @@ Scoped operations (`decision`, `snapshot`) require an active project:
 **Procedure:**
 
 1. Verify active project exists (if not, prompt to select)
-2. Read `{codex_repo}/projects/{active}/DECISIONS.md`
-3. Append new decision with today's date:
-   ```markdown
-   ## {YYYY-MM-DD}: {Decision summary from text}
-
-   **Context:** {Extract from conversation}
-
-   **Decision:** {The decision}
-
-   **Rationale:** {Why this choice}
-   ```
+2. **Run `git-start-write`** with branch `codex/decision-{short-summary}`
+3. Read and append to `{codex_repo}/projects/{active}/DECISIONS.md`
 4. Update `updated` date in frontmatter
-5. Create branch, commit, and open PR via `gh pr create`
+5. **Run `git-finish-write`** with appropriate commit message and PR title
 
 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:**
 
-1. Create `{codex_repo}/topics/{name}.md`
-2. Use template from `{codex_repo}/templates/TOPIC.md`
-3. Fill in frontmatter:
-   - `explored`: today's date
-   - `confidence`: ask user or infer from exploration depth
-   - `codebase_paths`: paths that were explored
+1. **Run `git-start-write`** with branch `codex/topic-{name}`
+2. Create `{codex_repo}/topics/{name}.md` from template
+3. Fill in frontmatter (explored, confidence, codebase_paths)
 4. Fill in content from current exploration/conversation
-5. Create branch, commit, and open PR via `gh pr create`
+5. **Run `git-finish-write`** with appropriate commit message and PR title
 
 Full procedure: `references/topics.md`
 
@@ -241,21 +277,15 @@ Full procedure: `references/topics.md`
 **Procedure:**
 
 1. Determine the document type (required): `prd`, `tech-design`, `topic`, or `pattern`
-2. Spawn the `codex-document-processor` agent with:
+2. **Run `git-start-write`** with branch `codex/snapshot-{name}`
+3. Spawn the `codex-document-processor` agent with:
    - File path to the source document
    - Document type
    - Project/entry name
    - Codex repo path from config
-3. Agent processes the document:
-   - Reads and extracts content
-   - Applies appropriate frontmatter template
-   - Writes to correct location in codex repo
-   - Returns file path and summary
-4. **Back in main conversation:** Handle git workflow
-   - Create branch: `codex/snapshot-{name}`
-   - Commit the new file
-   - Push and create PR via `gh pr create`
-5. Share PR link with user
+4. Agent writes the processed document to codex repo
+5. **Run `git-finish-write`** with appropriate commit message and PR title
+6. Share PR link with user
 
 **Example invocations:**
 
@@ -284,9 +314,10 @@ Artifacts are supplementary documents that support a project but aren't core doc
 
 **Procedure:**
 
-1. Use the `codex-document-processor` agent with type `artifact`
-2. Agent writes to `{codex_repo}/projects/{project}/artifacts/{filename}.md`
-3. Handle git workflow (branch, commit, PR)
+1. **Run `git-start-write`** with branch `codex/artifact-{project}-{filename}`
+2. Use the `codex-document-processor` agent with type `artifact`
+3. Agent writes to `{codex_repo}/projects/{project}/artifacts/{filename}.md`
+4. **Run `git-finish-write`** with appropriate commit message and PR title
 
 **Example invocations:**
 
@@ -297,19 +328,63 @@ 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
 
-**Trigger:** `/codex new {name}` or user wants to start new project entry
+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 `/codex new project {name}`
+
+**Procedure:**
+
+1. **Run `git-start-write`** with branch `codex/new-{name}`
+2. Create `{codex_repo}/projects/{name}/`
+3. Copy templates: PRD.md, TECH-DESIGN.md, DECISIONS.md
+4. Fill in frontmatter with today's date
+5. **Run `git-finish-write`** with appropriate commit message and PR title
+
+### Domains
+
+**Trigger:** `/codex new domain {name}`
 
 **Procedure:**
 
-1. Create `{codex_repo}/projects/{name}/`
-2. Copy templates from `{codex_repo}/templates/`:
-   - PRD.md
-   - TECH-DESIGN.md
-   - DECISIONS.md
+1. **Run `git-start-write`** with branch `codex/domain-{name}`
+2. Create `{codex_repo}/domains/{name}.md` from template
+3. Fill in frontmatter, guide user through sections
+4. **Run `git-finish-write`** with appropriate commit message and PR title
+
+### Proposals
+
+**Trigger:** `/codex new proposal {name}`
+
+**Procedure:**
+
+1. **Run `git-start-write`** with branch `codex/proposal-{name}`
+2. Create `{codex_repo}/proposals/{name}.md` from template
+3. Fill in frontmatter, guide user through sections
+4. **Run `git-finish-write`** with appropriate commit message and PR title
+
+### Patterns and Topics
+
+**Trigger:** `/codex new pattern {name}` or `/codex new topic {name}`
+
+**Procedure:**
+
+1. **Run `git-start-write`** with branch `codex/{pattern|topic}-{name}`
+2. Create file from template
 3. Fill in frontmatter with today's date
-4. Create branch, commit, and open PR via `gh pr create`
+4. **Run `git-finish-write`** with appropriate commit message and PR title
 
 Full procedure: `references/creating.md`
 
@@ -330,12 +405,10 @@ When user runs `/project create --from codex:{name}`:
 
 ## Git Workflow
 
-**All codex changes must go through PRs** (main branch is protected):
-
-1. Create branch: `codex/{action}-{name}` (e.g., `codex/decision-uuid-format`)
-2. Make changes
-3. Commit with descriptive message
-4. Push and create PR via `gh pr create`
-5. Share PR link with user
+**See "Git Hygiene (CRITICAL)" section above.** All codex changes go through PRs (main branch is protected).
 
-Safe changes (new files, decision appends) are auto-merged by GitHub Action. Modifications to existing content require review.
+**Key points:**
+- Always run the preamble before any operation (ensures clean main + latest)
+- Write operations: branch → commit → PR → **return to main**
+- Safe changes (new files, decision appends) auto-merge via GitHub Action
+- Never leave the repo on a feature branch

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

@@ -28,15 +28,18 @@ A project named '{name}' already exists. Did you mean to load it?
 → /codex {name}
 ```
 
-### 3. Create Project Directory
+### 3. Start Write Operation
 
 ```bash
-mkdir -p {codex_repo}/projects/{name}
+droid config codex | droid exec droid-codex git-start-write --config - --branch codex/new-{name}
 ```
 
-### 4. Copy Templates
+This runs the git preamble (ensures clean main + pulls latest) and creates the branch.
+
+### 4. Create Project Directory and Copy Templates
 
 ```bash
+mkdir -p {codex_repo}/projects/{name}
 cp {codex_repo}/templates/PRD.md {codex_repo}/projects/{name}/
 cp {codex_repo}/templates/TECH-DESIGN.md {codex_repo}/projects/{name}/
 cp {codex_repo}/templates/DECISIONS.md {codex_repo}/projects/{name}/
@@ -56,19 +59,17 @@ If user provides context, fill in what we know:
 - TECH-DESIGN.md: Any architectural decisions mentioned
 - DECISIONS.md: Leave as template (decisions come during impl)
 
-### 7. Create Branch and PR
+### 7. Finish Write Operation
 
 ```bash
-cd {codex_repo}
-git checkout -b codex/new-{name}
-git add projects/{name}/
-git commit -F - <<EOF
-feat(codex): scaffold {name} project
-EOF
-git push -u origin codex/new-{name}
-gh pr create --title "New project: {name}" --body "Scaffold for {name} project"
+droid config codex | droid exec droid-codex git-finish-write --config - \
+  --message "feat(codex): scaffold {name} project" \
+  --pr-title "New project: {name}" \
+  --pr-body "Scaffold for {name} project"
 ```
 
+This commits, pushes, creates PR, and returns to main.
+
 ### 8. Confirm to User
 
 ```
@@ -109,42 +110,3 @@ Next steps:
 
 Want me to help fill in any of these based on what we've discussed?
 ```
-
-## With Pre-Existing Context
-
-If the user has already discussed the feature:
-
-**User:** "We're building audit logging to track all API changes for compliance. It'll use an event sourcing pattern."
-
-**User:** `/codex new audit-logging`
-
-**Result:** (PRD.md pre-filled with discussed context)
-
-```markdown
----
-title: Audit Logging
-type: prd
-created: 2026-01-07
-updated: 2026-01-07
-confidence: medium
-source: implementation
----
-
-# Audit Logging - PRD
-
-## Problem Statement
-
-Need to track all API changes for compliance requirements.
-
-## Goals
-
-- Track all API changes
-- Support compliance auditing
-- {More goals to be defined}
-
-## Non-Goals
-
-- {To be defined}
-
-...
-```

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

@@ -39,15 +39,19 @@ I'll add this decision. Can you clarify:
 - Were there alternatives you considered?
 ```
 
-### 3. Read Existing DECISIONS.md
+### 3. Start Write Operation
 
 ```bash
-cat {codex_repo}/projects/{active}/DECISIONS.md
+droid config codex | droid exec droid-codex git-start-write --config - --branch codex/decision-{short-summary}
 ```
 
-### 4. Append New Decision
+### 4. Read and Update DECISIONS.md
+
+```bash
+cat {codex_repo}/projects/{active}/DECISIONS.md
+```
 
-Add at the end, before the template marker:
+Append new decision at the end:
 
 ```markdown
 ---
@@ -68,26 +72,18 @@ Add at the end, before the template marker:
 - {Expected outcomes, trade-offs}
 ```
 
-### 5. Update Frontmatter
-
-Update the `updated` field to today's date.
+Update the `updated` field in frontmatter to today's date.
 
-### 6. Create Branch and PR
+### 5. Finish Write Operation
 
 ```bash
-cd {codex_repo}
-git checkout -b codex/decision-{short-summary}
-git add projects/{active}/DECISIONS.md
-git commit -F - <<EOF
-decision({active}): {summary}
-EOF
-git push -u origin codex/decision-{short-summary}
-gh pr create --title "Decision: {summary}" --body-file - <<EOF
-{full decision text}
-EOF
+droid config codex | droid exec droid-codex git-finish-write --config - \
+  --message "decision({active}): {summary}" \
+  --pr-title "Decision: {summary}" \
+  --pr-body "{full decision text}"
 ```
 
-### 7. Confirm to User
+### 6. Confirm to User
 
 ```
 ✅ Added decision to {active}/DECISIONS.md:

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/dist/tools/codex/skills/droid-codex/references/topics.md

@@ -43,13 +43,19 @@ Ask user or infer:
   - `low` - Quick exploration, definitely incomplete
 - **Codebase paths:** Which directories/files were explored?
 
-### 4. Read Template
+### 4. Start Write Operation
+
+```bash
+droid config codex | droid exec droid-codex git-start-write --config - --branch codex/topic-{name}
+```
+
+### 5. Read Template
 
 ```bash
 cat {codex_repo}/templates/TOPIC.md
 ```
 
-### 5. Create Topic File
+### 6. Create Topic File
 
 ```bash
 # Create the file
@@ -115,20 +121,16 @@ codebase_paths:
 - {Links to related topics, PRDs, or external docs}
 ```
 
-### 6. Create Branch and PR
+### 7. Finish Write Operation
 
 ```bash
-cd {codex_repo}
-git checkout -b codex/topic-{name}
-git add topics/{name}.md
-git commit -F - <<EOF
-topic: add {name}
-EOF
-git push -u origin codex/topic-{name}
-gh pr create --title "Topic: {name}" --body "New topic from codebase exploration"
+droid config codex | droid exec droid-codex git-finish-write --config - \
+  --message "topic: add {name}" \
+  --pr-title "Topic: {name}" \
+  --pr-body "New topic from codebase exploration"
 ```
 
-### 7. Confirm to User
+### 8. Confirm to User
 
 ```
 ✅ Added topic: {name}

package/dist/tools/codex/skills/droid-codex/scripts/git-finish-write.d.ts

@@ -0,0 +1,31 @@
+#!/usr/bin/env bun
+/**
+ * codex git-finish-write
+ *
+ * Completes a write operation by committing, pushing, creating a PR,
+ * and returning to main.
+ *
+ * Usage:
+ *   droid config codex | droid exec droid-codex git-finish-write --config - \
+ *     --message "feat: add new topic" \
+ *     --pr-title "New topic: caching" \
+ *     --pr-body "Added exploration of caching patterns"
+ *
+ * Options:
+ *   --config <json>     Config with codex_repo path (required)
+ *   --message <text>    Commit message (required)
+ *   --pr-title <text>   PR title (required)
+ *   --pr-body <text>    PR body (optional, defaults to commit message)
+ *
+ * What it does:
+ *   1. Stage all changes
+ *   2. Commit with message
+ *   3. Push branch to origin
+ *   4. Create PR via gh CLI
+ *   5. Return to main branch
+ *
+ * Output (JSON):
+ *   { "success": true, "pr_url": "https://github.com/...", "branch": "codex/topic-caching" }
+ */
+export {};
+//# sourceMappingURL=git-finish-write.d.ts.map

package/dist/tools/codex/skills/droid-codex/scripts/git-finish-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-finish-write.d.ts","sourceRoot":"","sources":["../../../../../../src/tools/codex/skills/droid-codex/scripts/git-finish-write.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG"}