@orderful/droid 0.24.0 → 0.25.1

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
-git -C {codex_repo} pull --rebase --quiet
+droid config codex | droid exec droid-codex git-preamble --config -
+# Then proceed with the read
 ```
 
-This ensures shared knowledge is always current. The pull is quiet to avoid noise, but if it fails (conflicts, network), warn the user.
+### Write Operations (new, decision, snapshot, artifact)
+
+```bash
+# 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}"
+```
+
+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
 
@@ -140,13 +179,17 @@ The codex has five categories:
 
 **Procedure:**
 
-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
+1. **Run preamble first:**
+   ```bash
+   droid config codex | droid exec droid-codex git-preamble --config -
+   ```
+2. **Read `{codex_repo}/index.yaml`** - this contains all entry names and aliases for fast lookup
+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
+7. Check freshness (see below)
+8. Output loaded content
 
 **Why index?** Avoids expensive file-by-file searching. One read to find any entry by name or alias.
 
@@ -208,19 +251,10 @@ 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`
 
@@ -230,14 +264,11 @@ Full procedure: `references/decisions.md`
 
 **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`
 
@@ -250,21 +281,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:**
 
@@ -293,9 +318,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:**
 
@@ -325,13 +351,11 @@ The `/codex new` command scaffolds new entries from templates:
 
 **Procedure:**
 
-1. Create `{codex_repo}/projects/{name}/`
-2. Copy templates from `{codex_repo}/templates/`:
-   - PRD.md
-   - TECH-DESIGN.md
-   - DECISIONS.md
-3. Fill in frontmatter with today's date
-4. Create branch, commit, and open PR via `gh pr create`
+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
 
@@ -339,11 +363,10 @@ The `/codex new` command scaffolds new entries from templates:
 
 **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`
+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
 
@@ -351,11 +374,10 @@ The `/codex new` command scaffolds new entries from templates:
 
 **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`
+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
 
@@ -363,10 +385,10 @@ The `/codex new` command scaffolds new entries from templates:
 
 **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`
+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`
 
@@ -387,12 +409,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/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"}