chore: bootstrap Mavis agent team for the repo

[EtienneLescot]

Description

Add a root AGENTS.md (open agents.md standard) and a .harness/ Mavis
multi-agent team so any AI coding agent opening this repo gets canonical
setup / layout / style / test / PR conventions, and the orchestrator can
route work to the right specialist.

• AGENTS.md — canonical setup commands, project layout, code style
  (TS strict, Biome 2.4, tabs / 100-col / double quotes), testing
  instructions (Vitest + Playwright), PR conventions, security notes.
  Consumed by OpenCode, Codex, Cursor, Aider, Devin, Gemini CLI.
• .harness/agent.md — orchestrator (routes incoming work).
• .harness/reins/ — three generalists:
  • openscreen-dev — implementer
  • openscreen-tester — Vitest + Playwright
  • openscreen-reviewer — PR quality gate
• .harness/docs/ — architecture overview, git workflow.
• .harness/hooks/ — pre-commit (Biome + tsc + Vitest), post-commit
  (push/review reminder).
• .harness/memory/ — durable team facts.

Motivation

First-time bootstrap so future AI coding agents (including the Mavis
team) have a single canonical source of truth about how to work in
this repo. Avoids re-deriving conventions from source on every session.

Type of Change

• Documentation Update
• Other (please specify): repo scaffolding for AI agent tooling

Related Issue(s)

None.

Testing

• Verify file tree renders correctly on GitHub.
• Optionally run mavis harness list after merging to confirm the
  team is picked up by the local Mavis runtime.
• Sanity check: AGENTS.md passes standard agents.md lint
  (one file at repo root, has setup / layout / style / test sections).

Checklist

• I have performed a self-review of my code.
• I have added any necessary screenshots or videos. (N/A)
• I have linked related issue(s) and updated the changelog if applicable. (N/A)

Summary by CodeRabbit

• Documentation
  • Added internal development documentation including architecture overview, Git workflow conventions, and development process guides to support team operations.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[coderabbitai]

Warning

Review limit reached

@EtienneLescot, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 4 minutes and 56 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan refill rate.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, the refill rate gradually slows as usage increases. The highest same-day bursts are limited more strictly.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: c8b6211a-f92c-4193-a29f-f7bd735057f3

📥 Commits

Reviewing files that changed from the base of the PR and between d194574 and 132bc4b.

📒 Files selected for processing (4)

• .harness/memory/MEMORY.md
• .harness/reins/openscreen-dev/agent.md
• .harness/reins/openscreen-tester/agent.md
• AGENTS.md

📝 Walkthrough

Walkthrough

This PR bootstraps a complete Mavis multi-agent harness for the OpenScreen repo. It adds a canonical AGENTS.md root guide, an orchestrator agent definition, three specialist rein agents (dev, tester, reviewer), shared architecture and git-workflow documentation, a shared memory file, and pre/post-commit hook definitions.

Changes

Mavis harness configuration

Layer / File(s)	Summary
Canonical agent root guide AGENTS.md	Defines repo-wide operating instructions for AI agents: setup/build/test commands, project layout, TypeScript/React/formatting conventions, test run guidance, PR/commit rules, security notes, platform/i18n/build pipeline guidance, and a pointer to .harness/.
Orchestrator definition and shared knowledge .harness/agent.md, .harness/docs/architecture-overview.md, .harness/docs/git-workflow.md, .harness/memory/MEMORY.md	Orchestrator agent defines routing rules to the three specialist reins, direct-handling cases, verification steps, and stop conditions. Architecture-overview and git-workflow docs provide shared factual context. MEMORY.md holds four durable operational notes covering i18n, native helper testing, Biome ownership, and build commands.
Specialist rein agent definitions .harness/reins/openscreen-dev/agent.md, .harness/reins/openscreen-tester/agent.md, .harness/reins/openscreen-reviewer/agent.md	Three rein agent files define scope, working conventions, and stop/pass criteria: dev covers renderer, Electron, and native helpers with i18n requirements; tester covers Vitest unit/browser and Playwright e2e with i18n validation; reviewer covers the quality gate checklist, native-change requirements, and PASS vs. CHANGES REQUESTED rules.
Commit hook definitions .harness/hooks/pre-commit.md, .harness/hooks/post-commit.md	Pre-commit gate runs Biome on staged files, project-wide tsc --noEmit, and vitest --changed, with pass/fail and bypass behavior documented. Post-commit reminder prints commit-ahead count and suggests next action without blocking or auto-pushing.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐇 A harness of docs, a warren of reins,
The orchestrator hops through branching lanes.
Pre-commit gates lint, tsc, and test—
Each specialist rein knows what it does best.
No auto-push, no phantom review spawned,
Just tidy markdown notes the agents have donned! 🌿

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'chore: bootstrap Mavis agent team for the repo' directly and clearly describes the main change: setting up a Mavis multi-agent team configuration for the repository.
Description check	✅ Passed	The description includes a clear summary, motivation, type of change (documentation/scaffolding), testing instructions, and a self-review checklist. However, it does not include the 'Related issue' section from the template (N/A is noted but field is empty).
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/agent-bootstrap

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

AGENTS.md (1)

32-32: 🧹 Nitpick | 🔵 Trivial | 💤 Low value

Minor clarity improvement: explicit coexistence language.

Line 32 states "Husky + lint-staged runs Biome..." which is correct but could be more explicit about the layering. Consider: "Husky with lint-staged applies Biome..." or "Biome is applied via Husky + lint-staged..." to avoid ambiguity about whether they are a single component.

This is a nitpick on an otherwise clear line. Low urgency.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@AGENTS.md` at line 32, On line 32 of AGENTS.md, the text states "Husky +
lint-staged runs Biome..." but this phrasing creates ambiguity about whether
these are separate components or one unified tool. Rephrase this section to be
more explicit about the layering, such as by using "applies," "via," or "with"
to clarify that Biome is a tool that is applied through the Husky and
lint-staged pipeline. The goal is to make it unambiguous that Husky,
lint-staged, and Biome are distinct components working together in sequence.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.harness/memory/MEMORY.md:
- Around line 13-14: The heading hierarchy in the MEMORY.md file is incorrect.
The file starts with a main h1 heading, and the first subsection heading about
i18n locales (starting with "i18n: 13 locales must stay in sync") is currently
marked as h3 (three hash marks) when it should be h2 (two hash marks). Change
the three hash marks to two hash marks for the i18n subsection heading to
maintain proper markdown hierarchy after the main h1 title.

In @.harness/reins/openscreen-dev/agent.md:
- Line 18: Update line 18 in the agent.md file to replace the non-existent
directory references `.harness/docs/architecture/` and
`.harness/docs/engineering/` with actual existing documentation file paths in
the repository. Verify which specific documentation files currently exist in the
`.harness/docs/` directory and update the line to reference those actual files
(such as `.harness/docs/architecture-overview.md` or other relevant existing
files) so that developers can successfully locate and read the correct
documentation when changes touch the recording pipeline, IPC, or native bridge.

---

Nitpick comments:
In `@AGENTS.md`:
- Line 32: On line 32 of AGENTS.md, the text states "Husky + lint-staged runs
Biome..." but this phrasing creates ambiguity about whether these are separate
components or one unified tool. Rephrase this section to be more explicit about
the layering, such as by using "applies," "via," or "with" to clarify that Biome
is a tool that is applied through the Husky and lint-staged pipeline. The goal
is to make it unambiguous that Husky, lint-staged, and Biome are distinct
components working together in sequence.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 2a8f667a-afcd-43f8-92d3-fe603fe55827

📥 Commits

Reviewing files that changed from the base of the PR and between 8ced98d and d194574.

📒 Files selected for processing (10)

• .harness/agent.md
• .harness/docs/architecture-overview.md
• .harness/docs/git-workflow.md
• .harness/hooks/post-commit.md
• .harness/hooks/pre-commit.md
• .harness/memory/MEMORY.md
• .harness/reins/openscreen-dev/agent.md
• .harness/reins/openscreen-reviewer/agent.md
• .harness/reins/openscreen-tester/agent.md
• AGENTS.md

[EtienneLescot]

Self-review pass against the actual repo surfaced two repeated factual errors that would mislead any AI agent reading these docs. Fixed in commit 0c8d202:

1. Native helper paths (4 occurrences)

• Was: electron/<platform>-helper/ (e.g. electron/macos-helper/, electron/windows-helper/)
• Now: electron/native/screencapturekit/ (Swift / macOS ScreenCaptureKit) and electron/native/wgc-capture/ (C++/Win32 WGC)
• Source of truth: electron/native/ directory layout + Package.swift + CMakeLists.txt in the actual repo

2. i18n locales path (4 occurrences)

• Was: src/locales/
• Now: src/i18n/locales/<locale>/ (e.g. src/i18n/locales/en/settings.json)
• Source of truth: scripts/i18n-check.mjs:11 does LOCALES_DIR = path.resolve("src/i18n/locales") — the i18n:check script only works against the actual path

Files touched: AGENTS.md, .harness/reins/openscreen-dev/agent.md, .harness/reins/openscreen-tester/agent.md, .harness/memory/MEMORY.md (4 files, +11/-11).

Also bumped MEMORY.md entry dates from 2026-06-21 (placeholder copy-paste) to 2026-06-22 (actual bootstrap date).

Ready for re-review. The remaining nits from my self-review (PR description mentions .harness/.gitignore + .gitattributes as added files but they weren't committed; hooks are .md specs not actual git hooks) are non-blocking and can be addressed in a follow-up.

[EtienneLescot]

Follow-up on top of 0c8d202: removed the ## Agent team section from AGENTS.md to keep it strictly agent-agnostic.

The previous version said "This repo has a Mavis multi-agent team configured in .harness/." — that leaks a specific runtime name (Mavis) into a file that's meant to be readable by any AI coding agent (OpenCode, Codex, Cursor, Aider, Devin, Gemini CLI, etc.). Naming one runtime breaks the contract: a Cursor user shouldn't see "Mavis" mentioned in their project conventions.

Discovery still works the other way:

• The Mavis reins in .harness/reins/*/agent.md already start with "Read AGENTS.md at the repo root before touching anything" — so Mavis finds AGENTS.md via the reins.
• Non-Mavis agents never need to know that Mavis exists.

New commit: 132bc4b (1 file, -4 lines). Branch now at 132bc4b, PR #16 auto-updated.