mirror of
https://github.com/tinyhumansai/openhuman.git
synced 2026-07-27 21:08:00 +00:00
docs: align ship-and-babysit guidance (#3445)
This commit is contained in:
Steven Enamakel
@@ -9,10 +9,12 @@ model: inherit
|
||||
You are running an end-to-end ship-and-babysit flow for the **openhuman** repo. Follow these phases in order. Be concise in user-facing text.
|
||||
|
||||
Repo facts:
|
||||
|
||||
- Upstream: `tinyhumansai/openhuman`. PRs target `main`.
|
||||
- Push branches to `origin` (the user's fork). Treat `upstream` as fetch-only.
|
||||
- PRs are opened with `--head <fork-owner>:<branch>` against `tinyhumansai/openhuman:main`.
|
||||
- PR template: `.github/PULL_REQUEST_TEMPLATE.md`.
|
||||
- Feature work requires matching E2E coverage before shipping.
|
||||
|
||||
Resolve the fork owner once at the start and reuse it:
|
||||
|
||||
@@ -29,6 +31,17 @@ If `origin` resolves to `tinyhumansai`, stop and ask the user to add a fork remo
|
||||
3. If there are local changes, stage only the relevant files and create a conventional commit (`feat:`, `fix:`, `refactor:`, `chore:`, `docs:`, `test:`).
|
||||
4. Do not bypass commit hooks for your own changes.
|
||||
|
||||
## Feature E2E rule
|
||||
|
||||
- Core, domain, persistence, CLI, and JSON-RPC feature changes need Rust E2E coverage in `tests/*_e2e.rs`; new or changed RPC surfaces usually belong in `tests/json_rpc_e2e.rs`.
|
||||
- Frontend user flows need Playwright E2E coverage in `app/test/e2e/specs/*.spec.ts`.
|
||||
- Mock backend calls all the way through with `scripts/mock-api-server.mjs`, `scripts/mock-api/*`, or `app/test/e2e/mock-server.ts`; do not hit real backend services or third-party APIs in E2E.
|
||||
- Use focused commands when possible:
|
||||
- `pnpm test:rust:e2e -- --suite <suite>`
|
||||
- `pnpm --filter openhuman-app test:e2e:web:build`
|
||||
- `bash app/scripts/e2e-web-session.sh test/e2e/specs/<spec>.spec.ts`
|
||||
- Unit tests still matter for narrow logic, but they do not replace E2E coverage for newly built features.
|
||||
|
||||
## Phase 2 — Push
|
||||
|
||||
1. Confirm the current branch is not `main`.
|
||||
@@ -45,6 +58,7 @@ gh pr list --repo tinyhumansai/openhuman --head <fork-owner>:<branch> --state op
|
||||
```
|
||||
|
||||
3. If no PR exists, write a title and a body that follows `.github/PULL_REQUEST_TEMPLATE.md` exactly. Inspect `git log main..HEAD` and `git diff main...HEAD` first.
|
||||
- Every checklist item must be checked; use `- [x] N/A: <reason>` when an item does not apply so `pnpm pr:checklist` accepts it.
|
||||
4. Create the PR against `main`.
|
||||
5. Capture the PR number and URL for the babysit loop.
|
||||
|
||||
|
||||
@@ -6,15 +6,19 @@ allowed-tools: Bash, Read, Edit, Write, Agent, Skill
|
||||
You are running an end-to-end ship-and-babysit flow for the **openhuman** repo. Follow these phases in order. Be concise in user-facing text — one short sentence per phase transition is enough.
|
||||
|
||||
Repo facts (from `CLAUDE.md`):
|
||||
|
||||
- Upstream: `tinyhumansai/openhuman` (not a fork). PRs target **`main`**.
|
||||
- Push branches to **`origin`** (the user's own fork of `tinyhumansai/openhuman`). Treat `upstream` as fetch-only.
|
||||
- PRs are opened with `--head <fork-owner>:<branch>` against `tinyhumansai/openhuman:main`.
|
||||
- PR template: `.github/PULL_REQUEST_TEMPLATE.md`. Issue templates under `.github/ISSUE_TEMPLATE/`.
|
||||
- Feature work requires matching E2E coverage before shipping.
|
||||
|
||||
**Resolve the fork owner once at the start** and reuse it for the rest of the flow:
|
||||
|
||||
```bash
|
||||
FORK_OWNER=$(git remote get-url origin | sed -E 's#.*[:/]([^/]+)/[^/]+(\.git)?$#\1#')
|
||||
```
|
||||
|
||||
The flow is **fork-only**: `origin` must be the user's fork. If `origin` resolves to `tinyhumansai` (the upstream org), stop and ask the user to add a fork remote — never push branches to the upstream repo.
|
||||
|
||||
## Phase 1 — Commit
|
||||
@@ -24,6 +28,17 @@ The flow is **fork-only**: `origin` must be the user's fork. If `origin` resolve
|
||||
3. If there are uncommitted changes, stage relevant files (avoid secrets / large binaries / `.env`), then create a commit using a conventional prefix (`feat:`, `fix:`, `refactor:`, `chore:`, `docs:`, `test:`). Use a HEREDOC for the message.
|
||||
4. Never use `--no-verify` to bypass commit hooks for your own changes. If a hook fails on your changes, fix the underlying issue and create a NEW commit (do not amend pushed commits).
|
||||
|
||||
## Feature E2E rule
|
||||
|
||||
- Core, domain, persistence, CLI, and JSON-RPC feature changes need Rust E2E coverage in `tests/*_e2e.rs`; new or changed RPC surfaces usually belong in `tests/json_rpc_e2e.rs`.
|
||||
- Frontend user flows need Playwright E2E coverage in `app/test/e2e/specs/*.spec.ts`.
|
||||
- Mock backend calls all the way through with `scripts/mock-api-server.mjs`, `scripts/mock-api/*`, or `app/test/e2e/mock-server.ts`; do not hit real backend services or third-party APIs in E2E.
|
||||
- Use focused commands when possible:
|
||||
- `pnpm test:rust:e2e -- --suite <suite>`
|
||||
- `pnpm --filter openhuman-app test:e2e:web:build`
|
||||
- `bash app/scripts/e2e-web-session.sh test/e2e/specs/<spec>.spec.ts`
|
||||
- Unit tests still matter for narrow logic, but they do not replace E2E coverage for newly built features.
|
||||
|
||||
## Phase 2 — Push
|
||||
|
||||
1. Determine current branch with `git rev-parse --abbrev-ref HEAD`. Confirm it follows the `feat/|fix/|refactor/|chore/|docs/|test/` prefix convention. Never push directly to `main`. If the branch doesn't match the convention, stop and ask the user to either rename it or confirm the deviation — don't auto-rename pushed branches.
|
||||
@@ -37,7 +52,7 @@ The flow is **fork-only**: `origin` must be the user's fork. If `origin` resolve
|
||||
`gh pr list --repo tinyhumansai/openhuman --head <fork-owner>:<branch> --state open --json number,url`
|
||||
- **If a PR exists**, capture its `number` and `url`, print the URL, skip steps 3–5, and proceed straight to Phase 4 with that PR#.
|
||||
3. If none exists, draft a title (<70 chars) and a body that follows `.github/PULL_REQUEST_TEMPLATE.md` exactly. Inspect commits with `git log main..HEAD` and the diff with `git diff main...HEAD` to write the summary. If you bypassed a pre-push hook, note it in the PR body.
|
||||
- When filling the Submission Checklist, write each item as `- [ ] N/A: <reason>` (the item text MUST start with `N/A:` for `scripts/check-pr-checklist.mjs` to count it as satisfied; trailing `— N/A: ...` won't match), or `- [x] <text>` for genuinely checked items.
|
||||
- When filling the Submission Checklist, every item must be checked. Use `- [x] N/A: <reason>` when an item does not apply; unchecked `N/A` items still fail `scripts/check-pr-checklist.mjs`.
|
||||
4. Create the PR:
|
||||
```bash
|
||||
gh pr create --repo tinyhumansai/openhuman --base main --head <fork-owner>:<branch> \
|
||||
@@ -62,19 +77,20 @@ Each tick:
|
||||
- `gh pr checks --json` returns a `link` field (an Actions URL like `…/actions/runs/<id>/job/<jobId>`), not a run id directly. Extract the run id with a regex that's robust to trailing slashes (`sed -nE 's#.*/actions/runs/([0-9]+)/.*#\1#p'`) — positional `awk -F/` is brittle when the URL has a trailing slash. Or skip URL parsing entirely and call `gh run list --repo tinyhumansai/openhuman --branch <branch> --json databaseId --limit 1 --jq '.[0].databaseId'`.
|
||||
- If any check is `FAILURE` or `CANCELLED`, branch by check type: when `link` matches `/actions/runs/<id>/` (Actions-backed), extract `<id>` and fetch logs with `gh run view <id> --log-failed --repo tinyhumansai/openhuman`; when it doesn't (e.g. the `CodeRabbit` virtual check or any other status posted directly via the Checks API without an Actions run), skip `gh run view` and work from the `name`/`state`/`description` fields plus any review comments. Then fix the underlying issue: edit code, commit (conventional prefix), push to `origin`. Do NOT skip hooks or disable failing tests to make CI green.
|
||||
- For local repro of common failures before pushing fixes:
|
||||
- Frontend: `pnpm typecheck`, `pnpm lint`, `pnpm format:check`, `pnpm test:unit`.
|
||||
- Frontend: `pnpm typecheck`, `pnpm lint`, `pnpm format:check`, `pnpm test`.
|
||||
- Rust: `cargo check --manifest-path Cargo.toml`, `cargo check --manifest-path app/src-tauri/Cargo.toml`, `pnpm test:rust`.
|
||||
- Feature E2E: `pnpm test:rust:e2e -- --suite <suite>` for core/RPC behavior, or `pnpm --filter openhuman-app test:e2e:web:build` plus `bash app/scripts/e2e-web-session.sh test/e2e/specs/<spec>.spec.ts` for frontend flows.
|
||||
- Coverage gate is **≥ 80% on changed lines** (`.github/workflows/coverage.yml`) — if coverage fails, add tests for changed lines, not just happy path.
|
||||
2. **Fetch CodeRabbit review comments**:
|
||||
`gh api repos/tinyhumansai/openhuman/pulls/<PR#>/comments --paginate`
|
||||
Filter for comments authored by `coderabbitai` / `coderabbitai[bot]`. Also check issue-level comments: `gh api repos/tinyhumansai/openhuman/issues/<PR#>/comments --paginate`.
|
||||
- For each unresolved CodeRabbit suggestion: read the file/line referenced and apply the fix if it is correct and in scope. If a suggestion is wrong or out of scope, reply *inside the existing thread* (so the reply attaches to the same conversation, not a brand-new review) before resolving:
|
||||
- For each unresolved CodeRabbit suggestion: read the file/line referenced and apply the fix if it is correct and in scope. If a suggestion is wrong or out of scope, reply _inside the existing thread_ (so the reply attaches to the same conversation, not a brand-new review) before resolving:
|
||||
```bash
|
||||
gh api repos/tinyhumansai/openhuman/pulls/comments/<comment_id>/replies \
|
||||
-X POST \
|
||||
-f body='**Dismissed:** <reason>'
|
||||
```
|
||||
(`<comment_id>` is the top-level review-comment id from `gh api repos/tinyhumansai/openhuman/pulls/<PR#>/comments`. `POST /pulls/<PR#>/reviews` would create a *new* review thread, not a reply.)
|
||||
(`<comment_id>` is the top-level review-comment id from `gh api repos/tinyhumansai/openhuman/pulls/<PR#>/comments`. `POST /pulls/<PR#>/reviews` would create a _new_ review thread, not a reply.)
|
||||
- After fixing, commit and push to `origin`.
|
||||
- Mark the corresponding review thread as resolved via the GraphQL API:
|
||||
```bash
|
||||
@@ -88,7 +104,7 @@ Each tick:
|
||||
- All required checks are `SUCCESS`. `PENDING` keeps the loop running, no exceptions — no "green" claim while CI is mid-run.
|
||||
- No unresolved CodeRabbit review threads remain.
|
||||
- No new CodeRabbit issue comments since the last tick that request changes. Track this by remembering the highest CodeRabbit issue-comment `id` seen on the previous tick (the GitHub issue-comment id is monotonic) and only treating ids strictly greater than that marker as new on the current tick.
|
||||
When the exit condition holds, do NOT call `ScheduleWakeup` — return a final one-line summary with the PR URL and current status.
|
||||
- When the exit condition holds, do NOT call `ScheduleWakeup` — return a final one-line summary with the PR URL and current status.
|
||||
4. **Pacing**: if exiting, stop. Otherwise call `ScheduleWakeup` with `delaySeconds: 270`, `prompt: "/ship-and-babysit"`, and a specific `reason` like "waiting on CI for PR #123" or "applied 2 CodeRabbit fixes, re-checking".
|
||||
|
||||
## Guardrails
|
||||
|
||||
@@ -1,12 +1,13 @@
|
||||
---
|
||||
name: ship-and-babysit
|
||||
description: Commit local changes, push the branch to the user's fork, open or reuse a PR against tinyhumansai/openhuman:main, then babysit CI and CodeRabbit feedback until the PR is green and clean.
|
||||
description: Commit local changes, push to the user's fork, open or reuse a PR against tinyhumansai/openhuman:main, then babysit CI and CodeRabbit feedback until the PR is green and clean.
|
||||
---
|
||||
|
||||
# Ship And Babysit
|
||||
|
||||
Canonical long-form workflow also lives at:
|
||||
Canonical long-form workflow lives at:
|
||||
|
||||
- [`.codex/skills/ship-and-babysit/SKILL.md`](../skills/ship-and-babysit/SKILL.md)
|
||||
- [`.agents/agents/ship-and-babysit.md`](../../.agents/agents/ship-and-babysit.md)
|
||||
|
||||
Use this command when you want an end-to-end ship flow for `tinyhumansai/openhuman`:
|
||||
@@ -18,9 +19,17 @@ Use this command when you want an end-to-end ship flow for `tinyhumansai/openhum
|
||||
5. Fix actionable issues, commit, and push follow-ups.
|
||||
6. Stop only when the PR is green and clean.
|
||||
|
||||
Feature testing rule:
|
||||
|
||||
- Feature work must ship with matching E2E coverage.
|
||||
- Core, domain, persistence, CLI, and JSON-RPC features need mocked Rust E2E coverage in `tests/*_e2e.rs`, commonly `tests/json_rpc_e2e.rs`.
|
||||
- Frontend user flows need mocked Playwright E2E coverage in `app/test/e2e/specs/*.spec.ts`.
|
||||
- Mock backend calls all the way through with the repo mock backend; do not hit real backend services or third-party APIs in E2E.
|
||||
|
||||
Guardrails:
|
||||
|
||||
- Never push to `upstream`.
|
||||
- Never push directly to `main`.
|
||||
- Never resolve a review thread without either fixing it or replying with a reasoned dismissal.
|
||||
- Do not merge the PR.
|
||||
- Fill `.github/PULL_REQUEST_TEMPLATE.md` exactly. Every checklist item must be checked; use `- [x] N/A: <reason>` when an item does not apply.
|
||||
|
||||
@@ -50,6 +50,16 @@ Use this skill for `tinyhumansai/openhuman` when the user wants a branch shipped
|
||||
6. Stage only relevant files and create a focused conventional commit message.
|
||||
7. If there are no local changes, continue without creating a commit.
|
||||
|
||||
### Feature E2E Requirement
|
||||
|
||||
Before shipping feature work, verify that the PR includes end-to-end coverage for the new behavior.
|
||||
|
||||
- Core, domain, persistence, CLI, or JSON-RPC feature changes need Rust E2E coverage in `tests/*_e2e.rs`, usually targeted through `pnpm test:rust:e2e -- --suite <suite>` or `bash scripts/test-rust-e2e.sh --suite <suite>`.
|
||||
- New or changed JSON-RPC surfaces should normally extend `tests/json_rpc_e2e.rs` unless a more focused `*_e2e.rs` suite owns the domain.
|
||||
- Frontend user flows need Playwright E2E coverage in `app/test/e2e/specs/*.spec.ts`; build/run targeted web E2E with `pnpm --filter openhuman-app test:e2e:web:build` and `bash app/scripts/e2e-web-session.sh test/e2e/specs/<spec>.spec.ts`.
|
||||
- Mock backend calls all the way through. Use the repo mock backend (`scripts/mock-api-server.mjs`, `scripts/mock-api/*`, `app/test/e2e/mock-server.ts`) and admin behavior endpoints; do not hit real backend services or third-party APIs.
|
||||
- Unit tests are still expected for narrow logic, but they do not replace E2E coverage for newly built features.
|
||||
|
||||
### Phase 2: Push
|
||||
|
||||
1. Push the current branch to `origin`.
|
||||
@@ -67,6 +77,7 @@ Use this skill for `tinyhumansai/openhuman` when the user wants a branch shipped
|
||||
4. If no PR exists:
|
||||
- inspect `git log main..HEAD` and `git diff main...HEAD`
|
||||
- fill `.github/PULL_REQUEST_TEMPLATE.md` exactly
|
||||
- mark every checklist item as checked; for non-applicable items use `- [x] N/A: <reason>` so `pnpm pr:checklist` accepts it
|
||||
- create the PR against `tinyhumansai/openhuman:main` with `--head <fork-owner>:<branch>`
|
||||
5. Print the PR URL to the user.
|
||||
6. Immediately after opening or reusing the PR, start proactive validation based on the touched area instead of waiting for remote CI to finish:
|
||||
@@ -118,17 +129,10 @@ Each tick:
|
||||
- rerun targeted validation
|
||||
- commit
|
||||
- push
|
||||
10. For incorrect, stale, or out-of-scope review feedback:
|
||||
- reply in the existing review thread with concrete reasoning
|
||||
- do not open a new unrelated review
|
||||
- resolve or dismiss only when the reasoning is explicit and the platform supports it
|
||||
10. For incorrect, stale, or out-of-scope review feedback, reply in the existing review thread with concrete reasoning. Do not open a new unrelated review, and resolve or dismiss only when the reasoning is explicit and the platform supports it.
|
||||
11. After addressing a review thread, resolve it through the GitHub review-thread API when appropriate.
|
||||
12. Track whether new issue-level CodeRabbit comments appeared since the previous tick so the loop does not exit while fresh bot feedback is waiting.
|
||||
13. Exit the loop only when all of these are true:
|
||||
- all required checks are `SUCCESS`
|
||||
- no unresolved actionable review threads remain
|
||||
- no new actionable CodeRabbit issue comments remain
|
||||
- the latest fixes are committed and pushed to the PR branch
|
||||
13. Exit the loop only when all required checks are `SUCCESS`, no unresolved actionable review threads remain, no new actionable CodeRabbit issue comments remain, and the latest fixes are committed and pushed to the PR branch.
|
||||
|
||||
If the loop reaches the hard cap, stop and report the PR URL, current CI snapshot, and any unresolved review threads or comments.
|
||||
|
||||
@@ -137,10 +141,13 @@ If the loop reaches the hard cap, stop and report the PR URL, current CI snapsho
|
||||
- `pnpm typecheck`
|
||||
- `pnpm lint`
|
||||
- `pnpm format:check`
|
||||
- `pnpm test:unit`
|
||||
- `pnpm test`
|
||||
- `cargo check --manifest-path Cargo.toml`
|
||||
- `cargo check --manifest-path app/src-tauri/Cargo.toml`
|
||||
- `pnpm test:rust`
|
||||
- `pnpm test:rust:e2e -- --suite <suite>`
|
||||
- `pnpm --filter openhuman-app test:e2e:web:build`
|
||||
- `bash app/scripts/e2e-web-session.sh test/e2e/specs/<spec>.spec.ts`
|
||||
|
||||
Prefer targeted test commands when the touched area is narrow, but do not claim validation passed if a command was not run.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user