projmux: Instructions file for Codex

Agent Guide

Scope

• projmux is a standalone tmux session-management application.
• Supported build targets are Linux and macOS on amd64 and arm64. That matrix is the whole contract: the release workflow builds only those four, no CI job builds any other GOOS, and GOOS=windows compilation is not supported or guaranteed. The repository carries no _windows.go files and no //go:build windows or //go:build !windows constraints; do not add them. WSL is not a separate target — it runs the Linux build under the Linux contract, and WSL-specific behavior such as PROJMUX_WSL_TOAST_ICON_DIR stays inside that build.
• Keep portable session-management behavior in projmux.
• Keep machine-local policy outside the application unless the migration plan explicitly calls for it.
• Keep AGENTS.md focused on repo contract. Personal agent recipes, reverse-engineering notes, and machine-local operating memos belong in external local docs (Obsidian/dotfiles anchors), not this tracked file.
• Local-only agent overlays may live in an untracked AGENTS.local.md anchored via dotfiles. This tracked file stays shareable and tool-agnostic.

Startup Checks

• Confirm you are in the intended checkout/worktree with pwd.
• Check local state with git status --short.

Branch And Checkout Rules

• Use one branch per task. Preferred names: feat/<topic>, fix/<topic>, docs/<topic>, refactor/<topic>, chore/<topic>.
• Use a dedicated checkout/worktree per task when parallel work would otherwise collide.
• Keep one agent per checkout/worktree. Do not share a dirty checkout across agents.
• If another agent owns a file, do not overwrite their changes. Adjust around them or coordinate a handoff.
• Keep changes narrow. Split docs, bootstrap, migration, and feature work into separate branches unless they are inseparable.

Branch Protection And PR Flow

• main is protected by the repository ruleset main-protect. Direct pushes to main are blocked even for repository admins.
• Every change ships through a pull request. The required status checks are five CI job names: Format, Unit Tests, NPM Packages, Integration Tests, E2E Tests. The aggregate Test job is not required; it fans in every child, including the security and Darwin jobs the ruleset does not require.
• A required check is a job name. Renaming or splitting one of those five stops that context from ever being reported, and GitHub holds the PR at expected forever — every check green, merge blocked. Keep a thin aggregate job under the original name with needs: [<new jobs>] and if: always(); without if: always() the job skips on child failure, which is neither green nor red. test/e2e/shard-contract.sh fails when the E2E Tests aggregate is missing.
• Admin bypass mode is pull_request: the admin can self-merge a PR without approvals, but the PR itself is mandatory.
• Default merge method is squash. The PR title becomes the squash commit subject and is what release-please parses, so write it as a Conventional Commit. Follow docs/pr-guideline.md for full conventions.
• make install cannot run before the PR is merged into main. The full team-lead loop is: push branch → open PR → wait for CI → merge → git pull --ff-only → make install.