From 4622560fac34f435135be8f3c055741df6af251a Mon Sep 17 00:00:00 2001 From: Sojan Jose Date: Mon, 9 Feb 2026 20:56:40 -0800 Subject: [PATCH] chore(dev): document codex worktree local setup (#13494) This PR standardizes local Codex worktree usage with a simple dynamic-port workflow and ensures local-only artifacts stay out of version control. To reproduce: create a Codex worktree, run the setup script from `.codex/environments/environment.toml`, and verify that it generates per-worktree DB and port values along with a `Procfile.worktree` for Overmind. Changes included: - Add `.codex/` and `Procfile.worktree` to `.gitignore` - Document the Codex Worktree Workflow in `AGENTS.md`, outlining expected local setup conventions Tested locally by running the setup script with `CODEX_SKIP_INSTALL=1` and `CODEX_SKIP_DB_PREPARE=1`. Verified successful output, dynamic `FRONTEND_URL` / Vite port generation, and that `git diff` contains only the intended documentation and ignore updates. --- .gitignore | 2 ++ AGENTS.md | 7 +++++++ 2 files changed, 9 insertions(+) diff --git a/.gitignore b/.gitignore index bcc83c1ef..dbdd35bcd 100644 --- a/.gitignore +++ b/.gitignore @@ -94,6 +94,7 @@ yarn-debug.log* .vscode .claude/settings.local.json .cursor +.codex/ CLAUDE.local.md # Histoire deployment @@ -101,3 +102,4 @@ CLAUDE.local.md .histoire .pnpm-store/* local/ +Procfile.worktree diff --git a/AGENTS.md b/AGENTS.md index 474fe6e7f..3b1bcb024 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -50,6 +50,13 @@ - Prefer `with_modified_env` (from spec helpers) over stubbing `ENV` directly in specs - Specs in parallel/reloading environments: prefer comparing `error.class.name` over constant class equality when asserting raised errors +## Codex Worktree Workflow + +- Use a separate git worktree + branch per task to keep changes isolated. +- Keep Codex-specific local setup under `.codex/` and use `Procfile.worktree` for worktree process orchestration. +- The setup workflow in `.codex/environments/environment.toml` should dynamically generate per-worktree DB/port values (Rails, Vite, Redis DB index) to avoid collisions. +- Start each worktree with its own Overmind socket/title so multiple instances can run at the same time. + ## Commit Messages - Prefer Conventional Commits: `type(scope): subject` (scope optional)