feat: preserve software engineer agent and OCR delegation setup

README.md

@@ -424,7 +424,7 @@ The generated links are ignored by Git, so another machine gets its own paths.
 line, developer instructions, app preferences, portable notifications/hooks,
 MCP servers, Git marketplace/plugin preferences, global instructions and custom
 agents. It also saves the local `worktree`, `worktree-cleanup` and
-`ics-jira-dev-ready` skills. Run it after changing Codex settings, then review
+`software-engineer` skills. Run it after changing Codex settings, then review
 the diff. Home paths in configuration are stored as `{{HOME}}`; unrecognised
 top-level settings are reported for review instead of silently omitted.
 
@@ -452,6 +452,27 @@ configuration is tracked; plugin caches are not copied. Shared skills under
 
 Requires Python 3.11+ (`tomllib`).
 
+**Implementation and review.** The personal `software_engineer` agent discovers
+each project's conventions, implements scoped changes, and verifies behavior.
+It inherits the parent session's model and available MCP connections, including
+Serena, Context7 and Firecrawl. Its usage guide travels with it during export
+and restore: [`codex/agents/software-engineer-guide.md`](codex/agents/software-engineer-guide.md).
+In a new Codex session, select **Software Engineer** in the skills picker or
+type `$software-engineer implement [task]`. This user-scope skill loads the
+same agent instructions and can delegate to the custom role when useful.
+
+**Sharing with the team:** [Software Engineer setup and usage](codex/README.md)
+explains the workflow, installation without adopting these other dotfiles,
+example requests, optional tools, and subscription usage.
+
+`codex-sync install --external` also installs Open Code Review CLI **1.11.7**
+and its native Codex plugin. Global instructions default OCR to **delegation
+mode**, which uses the current Codex session for reasoning without a separate
+OCR LLM endpoint. Ask `@Open Code Review review my current changes` in a new
+session. Subscription-authenticated Codex uses its subscription allowance;
+external services such as Firecrawl can consume separate credits. No OCR
+credentials or plugin caches are tracked.
+
 ## Not included, on purpose
 
 - **Docker Desktop** — its installer needs a sudo password, so this uses

bin/codex-sync

@@ -136,7 +136,7 @@ def main():
         config = tomllib.loads((live / "config.toml").read_text())
         write(tracked / "config.toml", dumps(portable(capture(config), Path.home())))
         shutil.copy2(live / "AGENTS.md", tracked / "AGENTS.md")
-        for agent in (live / "agents").glob("*.toml"):
+        for agent in [*(live / "agents").glob("*.toml"), *(live / "agents").glob("*.md")]:
             shutil.copy2(agent, tracked / "agents" / agent.name)
         for name in manifest["local_skills"]:
             shutil.copytree(live / "skills" / name, tracked / "skills" / name, dirs_exist_ok=True)
@@ -163,6 +163,7 @@ def main():
         backup_file(config_path)
         write(config_path, restored)
     sources = [tracked / "AGENTS.md", *(tracked / "agents").glob("*.toml"),
+               *(tracked / "agents").glob("*.md"),
                *(p for p in (tracked / "skills").rglob("*") if p.is_file())]
     for source in sources:
         dest = live / source.relative_to(tracked)

codex/AGENTS.md

@@ -81,6 +81,10 @@ different jobs. Use `/code-review` for correctness on a diff. Use the Matt
 Pocock one when the question is whether the change matches a written spec or
 the repo's documented standards. Say which you ran.
 
+When Open Code Review is selected, use its `open-code-review-delegate` skill by
+default. Do not run `ocr review` or configure an OCR LLM endpoint unless the
+user explicitly requests OCR-managed review with their own API credentials.
+
 ## Scope
 
 `critical-developer-mindset` declares itself always-on. Treat it as applying to

codex/README.md

@@ -0,0 +1,150 @@
+# Software Engineer for Codex
+
+A reusable implementation workflow for your team's existing Codex setup.
+Give it a feature, bug, or refactor; it reads the relevant code, makes the
+change, and checks that the requested behavior works.
+
+It is useful across projects because it discovers each repository's stack,
+commands, and conventions. It inherits your selected Codex model and permissions.
+
+## What it does
+
+1. **Understands the task.** Reads project instructions, locates the code and its
+   callers, and identifies what would demonstrate success. Asks about missing
+   product decisions when they affect the implementation.
+2. **Implements the change.** Follows existing patterns, preserves unrelated work,
+   and updates affected callers and error handling. Adds meaningful regression
+   coverage for bugs where feasible.
+3. **Verifies the result.** Runs relevant tests and project-required checks,
+   inspects the diff, and reports what passed and what remains unverified.
+
+Small tasks proceed directly. Larger tasks get a short working plan. The workflow
+does not require a separate planning interview for every edit. Repository rules
+for security, financial calculations, migrations, and approvals still apply.
+
+## Use it
+
+Start a new Codex conversation inside the project after installation. Select
+**Software Engineer** in the skills picker or type:
+
+```text
+$software-engineer implement pagination for the customer list. Show 20 customers
+per page and preserve the current filters when switching pages.
+```
+
+Other examples:
+
+```text
+$software-engineer fix the search filter resetting when I return from a detail page.
+Add a regression test and run the relevant checks.
+```
+
+```text
+$software-engineer refactor the CSV parser while preserving its public behavior.
+Work in the current thread.
+```
+
+Describe the desired behavior and any constraints. For bugs, include reproduction
+steps or an error message if you have them. You do not need to name every tool.
+
+The **skill** (`software-engineer`, with a hyphen) is the selectable entry point.
+The **custom agent** (`software_engineer`, with an underscore) is a role Codex can
+spawn for a bounded implementation assignment. Both use the same instructions.
+The custom role itself is not an `@` plugin picker entry.
+
+For small tasks the skill can work in the current conversation. For useful
+delegated work it can launch the custom agent; if that role is unavailable it
+uses the same instructions in the current conversation and says so. To avoid
+the extra context of an implementation subagent, explicitly ask to work in the
+current thread, as in the example above.
+
+## Install just this workflow
+
+Use an up-to-date Codex client with skills and custom-agent support, signed into
+your own account. Obtain a checkout of this dotfiles repository containing this
+README, then run the following **from the repository root**:
+
+```bash
+engineer_codex_dir="${CODEX_HOME:-$HOME/.codex}"
+mkdir -p "$engineer_codex_dir/agents" "$engineer_codex_dir/skills/software-engineer/agents"
+cp -i codex/agents/software-engineer.toml "$engineer_codex_dir/agents/"
+cp -i codex/agents/software-engineer-guide.md "$engineer_codex_dir/agents/"
+cp -i codex/skills/software-engineer/SKILL.md "$engineer_codex_dir/skills/software-engineer/"
+cp -i codex/skills/software-engineer/agents/openai.yaml "$engineer_codex_dir/skills/software-engineer/agents/"
+```
+
+`cp -i` asks before replacing an existing file. Start a new conversation afterward;
+restart Codex if the skill list has not refreshed. This installs at user scope,
+making the workflow available across repositories on that machine.
+
+These commands install only this workflow. The repository's full `install.sh`
+and `codex-sync install` also restore the owner's other dotfile/Codex preferences;
+teammates do not need to adopt those to use this agent.
+
+## Open Code Review and costs
+
+For substantial or high-risk changes, the engineer uses **Open Code Review
+delegation mode** when installed. OCR supplies file selection and review rules;
+the implementing Codex thread performs the review, addresses findings, and
+reruns affected checks. It does not launch a separate reviewer by default.
+Small changes receive a direct self-review.
+
+To install the optional OCR integration:
+
+```bash
+npm install -g @alibaba-group/open-code-review@1.11.7
+codex plugin marketplace add alibaba/open-code-review
+codex plugin add open-code-review-codex@open-code-review
+```
+
+OCR requires Git 2.41 or later. Start a new Codex conversation after installing
+the plugin. The engineer's instructions select delegation mode; no OCR LLM
+endpoint needs configuring. If invoking the plugin directly outside the engineer
+workflow, say `@Open Code Review use delegation mode to review my current changes`.
+
+**Delegation is not free reasoning.** With subscription-authenticated Codex,
+implementation and review consume your subscription allowance. No separate OCR
+model API credentials are required. A Codex session authenticated through an API
+uses that account's billing instead. Optional services, including hosted
+Firecrawl, may charge or use their own credits. Token savings have not been measured.
+
+## Optional tools
+
+The agent uses tools already connected to your Codex session. Installing the
+agent does not install these servers or copy anyone's credentials.
+
+| Tool | When it helps |
+| --- | --- |
+| Serena | Find symbols, definitions, and callers without reading entire files. |
+| Context7 or a dedicated docs MCP | Check version-sensitive library APIs. |
+| Firecrawl | Research public documentation gaps with focused queries. |
+| Project tests and browser/device tools | Verify behavior and visible UI changes. |
+| Matt Pocock engineering skills | Apply test-first, debugging, or interface-design guidance when relevant. |
+
+Optional tools have fallbacks: targeted local searches, existing project tests,
+and explicit reporting of checks that could not run. Private code, client data,
+and credentials should not be sent in public web queries.
+
+[Matt Pocock's skills](https://github.com/mattpocock/skills),
+[Serena](https://github.com/oraios/serena), and
+[Aider](https://github.com/Aider-AI/aider) informed the approach.
+[OpenHands](https://github.com/OpenHands/OpenHands) was researched as an option
+for always-on orchestration. Aider and OpenHands are separate applications;
+neither is embedded in this agent.
+
+## What is ready, and what has been tested
+
+The user-scope skill is discoverable by Codex. The custom role successfully
+completed a disposable pagination fix: it reported three regression tests failing
+before the fix, all five tests passed afterward, and an unrelated file was
+preserved. Dotfiles restore tests cover the skill, agent, guide, and OCR settings.
+
+This is a working setup with a small implementation smoke test, not an enterprise
+reliability benchmark. That trial did not exercise every optional tool or a full
+OCR review. Test it against your team's real tasks and retain your normal review
+and CI requirements. It is not an unattended background service; it works when
+invoked, within the session's permissions and requested scope.
+
+Maintainers: [agent instructions](agents/software-engineer.toml),
+[skill entry point](skills/software-engineer/SKILL.md), and
+[design notes](agents/software-engineer-guide.md).

codex/agents/software-engineer-guide.md

@@ -0,0 +1,83 @@
+# Software engineer agent
+
+Start a new Codex session, then ask:
+
+> Use the software_engineer agent to implement [change]. Done means [observable behavior].
+
+For a bug, include what happens, what should happen, and a reproduction if known.
+Assign an existing worktree and file ownership when other sessions are editing.
+For tiny edits, working directly in the parent avoids the extra agent context.
+
+## Installation and portability
+
+`software-engineer.toml` is a personal agent under the active Codex home's
+`agents/` directory. To reuse it on another machine, copy that file to the
+equivalent directory and start a new session. Project-scoped installation uses
+`.codex/agents/software-engineer.toml`. Avoid defining the same role in both
+places unless an intentional project override is desired.
+
+The agent inherits the parent model, reasoning effort, MCP connections, and
+permission settings. It has no embedded provider credentials or project paths.
+Its LLM work uses the parent session's authentication and billing arrangement;
+with subscription-authenticated Codex it consumes that subscription's allowance.
+Separate services can have their own billing. Inheritance does not make them free.
+
+## Tool choices
+
+| Need | Preferred tool | Fallback |
+| --- | --- | --- |
+| Locate code and callers | Serena symbol definitions/references | Scoped rg and file reads |
+| Check a library API | Context7 or the project's dedicated docs MCP | Official version-matched docs |
+| Public web research | Firecrawl MCP or CLI; narrow queries, cached results | Available approved web tool |
+| Verify behavior | Project tests, lint, typecheck, browser/device tools | Report unverified behavior explicitly |
+| Review substantial changes | Open Code Review delegation skill | Explicit self-review |
+
+Connections come from the host session. Copying the TOML file alone does not
+install MCP servers or skills. Existing tools are reused, and missing optional
+tools have fallbacks. Credentials stay in the host configuration/environment.
+OCR-managed API calls require explicit authorization. Firecrawl's hosted service
+can consume separate credits; local Serena navigation does not require an LLM API key.
+
+## Working style
+
+Understand the relevant path, implement a complete change, verify the observable
+result. Small tasks proceed directly. Larger changes use a short working plan;
+project-required financial, security, migration, and review gates still apply.
+Routine test boundaries are inferred from approved behavior and existing patterns.
+Specialist skills load only for the relevant task, rather than starting a fixed
+chain of interviews and documents for every edit.
+
+The host can still bring a large tool/skill catalog into context. Selective tool
+use limits retrieved output but does not remove that startup cost. Disable unused
+plugins in the host deliberately if that becomes a measured problem. No percentage
+token savings or enterprise reliability claim has been established for this agent.
+
+## Sources and design decisions
+
+Reviewed 2026-09-10. These are references, not installed nested coding agents.
+
+- [Matt Pocock skills](https://github.com/mattpocock/skills): small composable skills, public-interface tests, short feedback loops. Uses the already installed bundle; preserves the user's preference for minimal ceremony.
+- [Serena](https://github.com/oraios/serena): semantic code navigation can retrieve definitions and references without loading entire files. Actual savings depend on task and language support.
+- [Aider](https://github.com/Aider-AI/aider): immediate lint/test feedback is a useful implementation practice. Aider itself is a separate coding client and was not installed; its API setup is unnecessary for this Codex agent.
+- [OpenHands](https://github.com/OpenHands/OpenHands): Agent Canvas supports local/remote agent backends and automations. Consider it for always-on infrastructure or team orchestration; those concerns are outside this personal agent's job.
+- [Codex custom agents](https://learn.chatgpt.com/docs/agent-configuration/subagents): personal/project TOML agent definitions and inherited settings.
+
+## Evaluation
+
+A valid TOML file only establishes parseability. A meaningful trial must launch
+the actual custom role, exercise an implementation with a failing regression test,
+rerun it after the fix, and check unrelated work was preserved. A small fixture is
+a smoke test, not a benchmark of production engineering quality. Repeat on actual
+tasks before making claims about speed, cost, or reliability.
+
+2026-09-10 smoke result: a normal Codex CLI session successfully launched exactly
+one `software_engineer` role on a disposable Node.js pagination fixture. The agent
+reported 3 failing and 2 passing tests before the fix; independent reruns after
+the fix passed all 5 tests. The unrelated notes file retained its SHA-256 checksum.
+The agent configuration omitted model/reasoning/tool overrides. This trial did
+not exercise Serena, Firecrawl, UI tools, or a complete OCR review.
+
+An earlier `codex exec --ephemeral` launch failed with `collab spawn failed: no
+thread with id`. A regular session succeeded; use that path for this installation.
+The host also warned that skill descriptions were shortened to fit its context
+budget. These are observed limitations, not proven problems in other versions.