@orderful/droid 0.24.0 → 0.25.0

package/src/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
 
@@ -208,19 +247,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 +260,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 +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:**
 
@@ -293,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:**
 
@@ -325,13 +347,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 +359,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 +370,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 +381,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 +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/src/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/src/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/src/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/src/tools/codex/skills/droid-codex/scripts/git-finish-write.ts

@@ -0,0 +1,236 @@
+#!/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" }
+ */
+
+import { execSync } from 'child_process';
+import { readFileSync, existsSync } from 'fs';
+
+interface Config {
+  codex_repo: string;
+}
+
+interface Result {
+  success: boolean;
+  pr_url?: string;
+  branch?: string;
+  error?: string;
+}
+
+function parseArgs(args: string[]): {
+  config: Config | null;
+  message: string | null;
+  prTitle: string | null;
+  prBody: string | null;
+} {
+  let config: Config | null = null;
+  let message: string | null = null;
+  let prTitle: string | null = null;
+  let prBody: string | null = null;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--config' && args[i + 1]) {
+      const configArg = args[++i];
+      if (configArg === '-') {
+        const stdin = readFileSync(0, 'utf-8').trim();
+        config = JSON.parse(stdin) as Config;
+      } else {
+        config = JSON.parse(configArg) as Config;
+      }
+    } else if (arg === '--message' && args[i + 1]) {
+      message = args[++i];
+    } else if (arg === '--pr-title' && args[i + 1]) {
+      prTitle = args[++i];
+    } else if (arg === '--pr-body' && args[i + 1]) {
+      prBody = args[++i];
+    }
+  }
+
+  return { config, message, prTitle, prBody };
+}
+
+function expandPath(p: string): string {
+  if (p.startsWith('~/')) {
+    return p.replace('~', process.env.HOME || '');
+  }
+  return p;
+}
+
+function run(cmd: string, cwd: string): { ok: boolean; output: string } {
+  try {
+    const output = execSync(cmd, {
+      cwd,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return { ok: true, output: output.trim() };
+  } catch (err: unknown) {
+    const error = err as { stderr?: string; stdout?: string; message?: string };
+    return { ok: false, output: error.stderr || error.stdout || error.message || 'Unknown error' };
+  }
+}
+
+function gitFinishWrite(
+  repoPath: string,
+  commitMessage: string,
+  prTitle: string,
+  prBody: string
+): Result {
+  const cwd = expandPath(repoPath);
+
+  // Verify repo exists
+  if (!existsSync(cwd)) {
+    return { success: false, error: `Codex repo not found at ${cwd}` };
+  }
+
+  // Get current branch
+  const branchResult = run('git branch --show-current', cwd);
+  if (!branchResult.ok) {
+    return { success: false, error: `Failed to get current branch: ${branchResult.output}` };
+  }
+  const branch = branchResult.output;
+
+  // Don't allow commits directly to main
+  if (branch === 'main') {
+    return { success: false, error: 'Cannot commit directly to main. Use git-start-write first to create a branch.' };
+  }
+
+  // 1. Stage all changes
+  const add = run('git add -A', cwd);
+  if (!add.ok) {
+    return { success: false, error: `Failed to stage changes: ${add.output}` };
+  }
+
+  // Check if there are changes to commit
+  const status = run('git status --porcelain', cwd);
+  if (status.ok && status.output.length === 0) {
+    return { success: false, error: 'No changes to commit' };
+  }
+
+  // 2. Commit (use heredoc-style to avoid injection)
+  // Write commit message to a temp approach using -F -
+  const commit = run(`git commit -m "${commitMessage.replace(/"/g, '\\"')}"`, cwd);
+  if (!commit.ok) {
+    return { success: false, error: `Failed to commit: ${commit.output}` };
+  }
+
+  // 3. Push to origin
+  const push = run(`git push -u origin ${branch}`, cwd);
+  if (!push.ok) {
+    // Try force push if branch exists with different history
+    const forcePush = run(`git push -u origin ${branch} --force-with-lease`, cwd);
+    if (!forcePush.ok) {
+      return { success: false, error: `Failed to push: ${forcePush.output}` };
+    }
+  }
+
+  // 4. Create PR via gh CLI
+  const escapedTitle = prTitle.replace(/"/g, '\\"');
+  const escapedBody = prBody.replace(/"/g, '\\"');
+  const prCreate = run(
+    `gh pr create --title "${escapedTitle}" --body "${escapedBody}" 2>&1 || gh pr view --json url -q .url`,
+    cwd
+  );
+
+  let prUrl = '';
+  if (prCreate.ok) {
+    // Output might be the PR URL directly or JSON
+    const output = prCreate.output;
+    if (output.startsWith('https://')) {
+      prUrl = output.split('\n')[0]; // First line is the URL
+    } else {
+      // Try to extract URL from output
+      const urlMatch = output.match(/https:\/\/github\.com\/[^\s]+/);
+      if (urlMatch) {
+        prUrl = urlMatch[0];
+      }
+    }
+  }
+
+  // 5. Return to main
+  const checkoutMain = run('git checkout main', cwd);
+  if (!checkoutMain.ok) {
+    // Non-fatal - PR was created, just warn
+    console.error(`Warning: Failed to return to main: ${checkoutMain.output}`);
+  }
+
+  return {
+    success: true,
+    pr_url: prUrl || 'PR created (check GitHub)',
+    branch,
+  };
+}
+
+// Main
+const args = process.argv.slice(2);
+const { config, message, prTitle, prBody } = parseArgs(args);
+
+if (!config) {
+  console.log(JSON.stringify({
+    success: false,
+    error: 'Missing --config. Usage: droid config codex | droid exec droid-codex git-finish-write --config - --message "..." --pr-title "..."',
+  }));
+  process.exit(1);
+}
+
+if (!config.codex_repo) {
+  console.log(JSON.stringify({
+    success: false,
+    error: 'Missing codex_repo in config',
+  }));
+  process.exit(1);
+}
+
+if (!message) {
+  console.log(JSON.stringify({
+    success: false,
+    error: 'Missing --message argument',
+  }));
+  process.exit(1);
+}
+
+if (!prTitle) {
+  console.log(JSON.stringify({
+    success: false,
+    error: 'Missing --pr-title argument',
+  }));
+  process.exit(1);
+}
+
+const result = gitFinishWrite(
+  config.codex_repo,
+  message,
+  prTitle,
+  prBody || message
+);
+console.log(JSON.stringify(result, null, 2));
+
+if (!result.success) {
+  process.exit(1);
+}