diff --git a/AGENTS.md b/AGENTS.md index 2e6655673..12179554b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -73,6 +73,12 @@ cargo check --manifest-path app/src-tauri/Cargo.toml **Quality**: ESLint + Prettier + Husky in the `app` workspace. +### Codex web / Linear-launched PR checklist + +Before opening AI-authored PRs from Codex web sessions or Linear-launched implementation agents, follow [`docs/agent-workflows/codex-pr-checklist.md`](docs/agent-workflows/codex-pr-checklist.md). + +This checklist is required for remote agents because OpenHuman has several merge gates that are easy to miss in partial environments: Prettier, Rust formatting, TypeScript typecheck, focused Vitest coverage, controller dispatch parity, and Tauri vendored dependency availability. If a command cannot run in the remote environment, the PR body must report the exact blocked command and error instead of claiming validation passed. + ### Agent debug runners (`scripts/debug/`) Use these wrappers instead of invoking Vitest / WDIO / cargo directly when iterating — they keep stdout summary-sized and tee full output to `target/debug-logs/--.log`. Add `--verbose` to also stream raw output. See [`scripts/debug/README.md`](scripts/debug/README.md). @@ -631,4 +637,4 @@ Stats: 20 obs (8,333t read) | 593,112t work | 99% savings 2882 " 🔵 openhuman Eval Infra: Does Not Exist; Phase D Requires Bootstrap from Scratch Access 593k tokens of past work via get_observations([IDs]) or mem-search skill. - \ No newline at end of file + diff --git a/docs/agent-workflows/codex-pr-checklist.md b/docs/agent-workflows/codex-pr-checklist.md new file mode 100644 index 000000000..cc705102b --- /dev/null +++ b/docs/agent-workflows/codex-pr-checklist.md @@ -0,0 +1,108 @@ +# Codex PR Checklist + +Use this checklist for Codex web sessions, Linear-launched implementation agents, and any other remote agent that opens OpenHuman PRs. + +## Required Preflight + +Run this before editing files: + +```bash +pwd +git status --porcelain +git branch --show-current +git remote -v +test -f AGENTS.md +test -f docs/src/README.md +test -f Cargo.toml +test -f app/package.json +``` + +Expected repository path in Codex web is `/workspace/openhuman`. If the checkout is missing or the command shows another project, stop immediately and report the environment binding problem. Do not edit files in the wrong repository. + +## Launch Trigger Rule + +Use exactly one Codex trigger per Linear issue. + +Preferred launch pattern: + +```md +@Codex use the Codex environment for jwalin-shah/openhuman. + +Work issue . +Expected path: /workspace/openhuman. +Start from latest origin/main. +Create branch codex/-. +Follow docs/agent-workflows/codex-pr-checklist.md exactly. +Do not open duplicate PRs. If validation is blocked, report exact command and error in the PR body and Linear. +``` + +Do not also set `delegate: Codex` when posting an explicit `@Codex` launch comment. Linear delegate metadata can start its own Codex thread, so combining both mechanisms can double-trigger the same issue. + +If using `delegate: Codex` as the only trigger for an integration that requires it, do not add an `@Codex` comment. Record in the issue which trigger was used. + +## Branch And PR Rules + +- Start from latest `origin/main` unless the Linear issue explicitly says otherwise. +- Use one branch and one PR per Linear issue. +- Name branches `codex/-`. +- Do not open duplicate PRs for the same issue. If a retry is needed, update the existing PR branch or close the stale duplicate and state which PR is canonical. +- PRs should target `jwalin-shah/openhuman:main` unless upstream permissions allow `tinyhumansai/openhuman:main`. + +## Validation Before PR + +Run the smallest checks that prove the changed surface, plus the relevant merge gates: + +```bash +# Always run for app or docs-visible app changes +pnpm --filter openhuman-app format:check +pnpm typecheck + +# Focused app tests for changed TS/React behavior +pnpm --dir app exec vitest run --config test/vitest.config.ts + +# Root Rust changes +cargo fmt --manifest-path Cargo.toml --all --check + +# Tauri shell changes +cargo fmt --manifest-path app/src-tauri/Cargo.toml --all --check +``` + +For Rust behavior changes, prefer focused tests through the repo wrappers where available: + +```bash +pnpm debug rust +``` + +If a command cannot run because the environment lacks vendored files or system packages, do not claim it passed. Copy the exact command and blocker into the PR body. + +## Refactor Parity Rules + +For behavior extraction and architecture refactors: + +- Identify the old guard order, fallback order, dispatch contract, or public API being preserved. +- Add focused parity tests when the behavior can be tested without broad integration setup. +- Do not reorder guards, fallback layers, RPC methods, or dispatch paths unless the issue explicitly asks for a behavior change. +- When adding a drift guard, verify it checks the source of truth as it exists in this repo. Do not assume generated strings are written literally in source files. + +## PR Body Requirements + +Every AI-authored PR must include: + +- Linear issue key and URL. +- Branch name. +- Commit SHA. +- Files changed summary. +- Validation commands run. +- Validation commands blocked, with exact error text. +- Behavior intentionally changed, or `No intended behavior change`. +- Any duplicate/stale PRs that were closed or superseded. + +## Review Before Handoff + +Before handing off: + +- Re-check GitHub CI status for the PR. +- Pull failed check logs before guessing. +- Fix format/type/test failures that are local to the PR. +- Leave broad system dependency or environment failures as explicit blockers. +- Update the Linear issue with PR URL, commit SHA, validations, and blockers.