Skip to content

Open source Grok Bot alternative, Bring your own agent and subscription: message Claude Code, Codex, Gemini CLI, Cursor, Copilot and 40+ AI agents as bots on your own computer, from iPhone, Mac, Windows, Linux or terminal. Agent-agnostic and free. Also a Muse and Dots alternative. Built in Rust.

docs: add Codex post-change review workflow

leepokaia7b42cc1cb11
diff --git a/.agents/skills/after-change/SKILL.md b/.agents/skills/after-change/SKILL.md
new file mode 100644
index 00000000..bf631a99
--- /dev/null
+++ b/.agents/skills/after-change/SKILL.md
@@ -0,0 +1,72 @@
+---
+name: after-change
+description: Review, fix, clean up, and end-to-end test a finished Codync code change before commit. Use after affected tests pass or when explicitly asked to run the after-change workflow.
+---
+
+# After change
+
+Run Codync's review → fix → E2E workflow with Codex's available agent and computer-use tools. This is an instruction-driven skill; it does not execute the Claude workflow JavaScript or require Claude Code.
+
+## Scope and inputs
+
+Resolve the repository root from the current working directory. Read its `AGENTS.md` and [clean-code guide](../../../docs/guides/clean-code.md#after-every-change-review-e2e-cleanup), plus instructions for the affected directories. Resolve all repository paths against that root, including when invoked from `host/` or another subdirectory.
+
+Accept ordinary language or an object with:
+
+- `change`: what changed and which flows to walk; default to this task's committed and uncommitted work.
+- `base`: comparison ref, default `origin/dev`.
+- `e2e`: `minimal` or `full`; default to minimal, but use full for platform code, packaging, desktop main-process changes, or an explicit full request.
+
+Record the absolute worktree path, base commit, owned files/hunks, relevant tests already run, and changed user flows. Inspect `git diff <base>` and `git status --short`, including new files. The diff is candidate scope, not permission to change other agents' work. If the base does not exist, report it and resolve the intended base before review. Do not reset or stash work to obtain a clean diff.
+
+For docs/config-only changes with no runtime behavior, validate the affected artifacts and report E2E as `not_run` with the reason; do not launch apps or the full review pipeline. Executable tools and behavior-changing configuration still need applicable checks. Finish prerequisite tests before reviewing code, or explicitly report why they cannot run.
+
+## Review
+
+Use three read-only subagents in parallel when delegation is available; otherwise perform the three reviews yourself and disclose the fallback. Respect the session's concurrency limit and reuse finished agents for later phases.
+
+Give every reviewer the same absolute worktree, base commit, owned scope, change description, and relevant repository instructions. They must not edit, commit, start apps, or spawn further agents.
+
+| Reviewer | Focus |
+| --- | --- |
+| Correctness | Concrete bugs, regressions, error handling, security, and compatibility with older hosts/clients; consult `docs/reference/compatibility.md`. |
+| Completeness | All affected clients, stale documentation, missing behavioral tests, release versions and iOS What's New requirements. |
+| Refactor | Responsibility splits, files over ~500 lines, long functions, layer leaks, missed reuse, and applicable language conventions. Only suggestions worth their diff. |
+
+Each finding includes file, line when available, severity (`high`, `medium`, `low`), summary, concrete failure scenario (or cost of leaving a refactor), and suggested fix. Empty results are valid. Style preferences alone are not defects.
+
+After all reviews finish, have a read-only verifier try to refute each correctness/completeness finding against the code. Deduplicate findings; return `confirmed` and `refuted`, with evidence or reasons. Unsupported claims are refuted rather than silently promoted to bugs; unavailable evidence must be disclosed. Keep refactor suggestions separate. If a reviewer or verifier fails, retry or perform that work yourself; missing output is not an empty successful review.
+
+## Fix and cleanup
+
+Assign one editor ownership of the scoped files/hunks, or do the editing yourself. Tell any editor it is not alone in the codebase: preserve other agents' edits and adapt to them. Reviewers remain read-only, and subagents never commit or merge.
+
+In one pass, fix confirmed findings at their root cause, apply worthwhile refactors, and clean up the change's own dead code, duplication, unclear names/comments and unused imports. Keep unrelated work out. Record applied changes and skipped suggestions with reasons. Follow the repository's release/version rules when shipped code changes; do not bump for this skill or documentation alone.
+
+Run the affected builds/tests after the edits. Reuse still-valid results; rerun when new edits or failures warrant it. Do not proceed to app E2E with an unresolved build/test failure. Preserve enough separation to commit refactors apart from behavior changes as required by the repository.
+
+## E2E
+
+Give one tester (or yourself) the final change, exact flows and E2E mode. Read the relevant parts of `docs/guides/development.md`, `docs/guides/dev-app.md`, and, for Windows, `docs/guides/windows-testing.md` before starting apps.
+
+- Stop only this task's old app/host processes before rebuilding or installing. Never stop the shared Codync Dev, production app, or another session's sandbox. Track what you start.
+- Prefer `npm run dev` in `apps/desktop` in the change's isolated worktree. When testing from the shared checkout, use its documented sandbox mode. Restart for main-process/preload changes. Package only when the flow needs capabilities unavailable unpackaged.
+- When `host/` is unchanged, reuse a compatible built host through `CODYNC_HOST_BIN` as the development guide describes. When it changed, build the correct host for this worktree. Apple build output stays in this checkout's `build/dd`.
+- Walk the changed flows with available Computer Use tools on the actual apps. iPhone checks use an iOS Simulator through Device Hub; Android checks use its emulator. Builds and unit tests do not substitute for UI checks. No changed client UI here means no UI parity work.
+- Minimal E2E covers this computer's platform. Full E2E also covers installed Lima Linux and UTM Windows VMs; report absent VMs rather than creating them. Validate affected clients as required by repository instructions, and report unavailable tools/devices explicitly.
+- Walk each flow once, using short bot messages. Record `platform`, `flow`, `result` (`pass`, `fail`, `preexisting`, `not_run`), and observed evidence or reason. Use `preexisting` only with evidence it fails without this change; otherwise retain the uncertainty as a failure. Never disturb another worktree to prove a baseline.
+
+Fix change-caused E2E failures, run the checks touched by the fix, and walk only the failed flows again. Keep retries bounded to one E2E fix/retest round; if still failing, report unresolved failures and keep the work available for follow-up instead of calling it green.
+
+## Report and handoff
+
+Report:
+
+- Review: confirmed findings and their disposition; refuted findings and why; incomplete review work.
+- Fix: fixes/cleanup/refactors applied, suggestions skipped and why, builds/tests and results.
+- E2E: each check's platform, flow, result and evidence; checks not run and why.
+- Next: readiness to commit, any unresolved failures or material skipped fixes, and any task-owned processes still running.
+
+Do not label missing validation as passed. Follow the existing task's commit/merge/push authorization and the repository's handoff rules; the skill itself does not authorize publishing unrelated work. Only the coordinator performs git handoff.
+
+Keep the change's development app running through review and until its merge is successfully pushed. On merge/push failure, preserve the worktree and its app. After successful push, stop the task-owned app, Vite and sandbox host, verify they exited, leave the worktree, and follow the clean-code guide's worktree/sandbox cleanup. Confirm the worktree contains no unmerged or other agents' work before removal; never remove the shared checkout. Stop other temporary processes you started when no longer needed.
diff --git a/.agents/skills/after-change/agents/openai.yaml b/.agents/skills/after-change/agents/openai.yaml
new file mode 100644
index 00000000..d7532245
--- /dev/null
+++ b/.agents/skills/after-change/agents/openai.yaml
@@ -0,0 +1,4 @@
+interface:
+ display_name: "After Change"
+ short_description: "Review, fix, and verify Codync changes"
+ default_prompt: "Use $after-change to review, fix, and end-to-end test the current Codync change."
diff --git a/AGENTS.md b/AGENTS.md
index f3b848bd..90e24f6f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -58,7 +58,7 @@ Name Swift files after their main `UpperCamelCase` type; use `snake_case.rs` and
## Clean code
- Keep code modular and clean on every change: reuse before writing, one responsibility per file/type, no new code appended to files past ~500 lines (split first), views/components hold no I/O or logic, short single-purpose functions, enums over flags, no dead code, no swallowed errors. Full rules: [docs/guides/clean-code.md](docs/guides/clean-code.md).
-- After every code change (tests green, before commit): review → fix, refactor and cleanup → end-to-end test (in Claude Code, the `after-change` workflow runs all of it): [after every change](docs/guides/clean-code.md#after-every-change-review-e2e-cleanup).
+- After every code change (tests green, before commit): review → fix, refactor and cleanup → end-to-end test. In Codex, use the [after-change skill](.agents/skills/after-change/SKILL.md); in Claude Code, use the `after-change` workflow: [after every change](docs/guides/clean-code.md#after-every-change-review-e2e-cleanup).
## Cross-platform UI changes
diff --git a/docs/guides/clean-code.md b/docs/guides/clean-code.md
index 51061f6e..117f1957 100644
--- a/docs/guides/clean-code.md
+++ b/docs/guides/clean-code.md
@@ -47,6 +47,14 @@ Once a code change works (its tests pass) and before commit, it goes through thr
In Claude Code, the `after-change` workflow (`.claude/workflows/after-change.js`) runs all three: start it from the change's worktree with `{"change": "<what changed and which flows to walk>", "e2e": "minimal"}` (`"full"` for platform code, packaging or the desktop main process; `"base"` if the change isn't against `origin/dev`). It returns the confirmed and refuted findings, what the fix pass changed or skipped (refactors included), and the e2e checks. The worktree's `npm run dev` keeps running through it.
+In Codex, use the repository's [after-change skill](../../.agents/skills/after-change/SKILL.md). It uses Codex subagents for the three reviews and verification, then one editor and one E2E tester; without subagents, the coordinator performs the same stages. It accepts the same `change`, `base` and `e2e` inputs in ordinary language or as an object. For example:
+
+```text
+$after-change change="Fix desktop reconnect; walk disconnect and reconnect" base=origin/dev e2e=minimal
+```
+
+The skill lives in `.agents/skills/after-change`, the repository skill location supported by [Codex](https://learn.chatgpt.com/docs/build-skills#where-codex-loads-local-skills). If it is missing from the current session's skill list, ask Codex to read that `SKILL.md` directly, or restart Codex to refresh discovery. This is a skill-driven workflow, not a Claude JavaScript runner or an automatic hook. Keep the two implementations aligned when changing this procedure.
+
Once it's green, the change is committed, merged into `dev` and pushed. Only after that merge is pushed are the worktree's `npm run dev` (its Electron app and sandbox host) stopped and the worktree deleted (a failed merge or push keeps both): stop it, leave the worktree, then from the main checkout `git worktree remove --force <path>`, `git branch -D <branch>` and `npm run dev -- --prune` in `apps/desktop` (deletes its sandbox). Nothing started from the worktree keeps running.
Agents touch only the change's own hunks, never another agent's uncommitted work. Keep refactors in `refactor` commits apart from the behavior change. The final report lists the review findings (fixed, or refuted and why), each e2e check that ran or couldn't and why, what the cleanup changed, and each refactor applied or skipped with one line why. Docs- or config-only changes skip this; a tool without subagents does the stages itself.