diff --git a/.agents/agent-workflow.yml b/.agents/agent-workflow.yml
new file mode 100644
index 0000000..a128061
--- /dev/null
+++ b/.agents/agent-workflow.yml
@@ -0,0 +1,12 @@
+---
+base_branch: main
+follow_up_prefix: "Follow-up:"
+review_gate: AI reviewers are advisory unless they confirm a blocker; merge gate is the full `gh pr checks` list green (not --required) + all threads resolved + mergeable clean
+approval_exempt: at batch closeout, auto-merge ready low-risk PRs that pass the merge gate; keep high-risk (CI/workflow, build-config, dependency or runtime bumps, broad refactors, release) maintainer-gated
+coordination_backend: private shakacode/agent-coordination (claims/heartbeats namespaced by full repo name)
+changelog: n/a
+benchmark_labels: n/a
+merge_ledger: n/a
+ci_parity_environment: n/a — reproduce CI-only failures from the matching job in .github/workflows/**
+hosted_ci_trigger: n/a — CI runs on every PR if configured
+ci_change_detector: n/a
diff --git a/.agents/bin/README.md b/.agents/bin/README.md
new file mode 100644
index 0000000..7747e28
--- /dev/null
+++ b/.agents/bin/README.md
@@ -0,0 +1,18 @@
+# Agent Workflow Scripts
+
+Standard entry points that portable agent-workflow skills call, so a skill can
+run `.agents/bin/<name>` in any repo without knowing this repo's specific
+commands. Each script is a thin, repo-owned wrapper. A script that is **absent**
+means that capability is n/a here.
+
+| Script | Purpose | This repo runs |
+| --- | --- | --- |
+| `setup` | Install dependencies and prepare the development database | `bin/setup` |
+| `validate` | Pre-push gate | `bin/test ci "$@"` |
+| `test` | Run tests, including test database preparation | `bin/test "$@"` |
+| `lint` | Lint / format | n/a |
+| `build` | Build / type-check | n/a |
+| `docs` | Docs checks | n/a |
+| `ci-detect` | CI change detector | n/a |
+
+Non-command policy lives in [`../agent-workflow.yml`](../agent-workflow.yml).
diff --git a/.agents/bin/setup b/.agents/bin/setup
new file mode 100755
index 0000000..56d84e1
--- /dev/null
+++ b/.agents/bin/setup
@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+# Generated by shakacode/agent-workflows bin/push-downstream.
+# Install dependencies and prepare the development database.
+set -euo pipefail
+cd "$(CDPATH= cd -- "$(dirname -- "$0")/../.." && pwd)"
+exec bin/setup "$@"
diff --git a/.agents/bin/test b/.agents/bin/test
new file mode 100755
index 0000000..009f278
--- /dev/null
+++ b/.agents/bin/test
@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+# Generated by shakacode/agent-workflows bin/push-downstream.
+# Run the repository test entry point, including test database preparation.
+set -euo pipefail
+cd "$(CDPATH= cd -- "$(dirname -- "$0")/../.." && pwd)"
+exec bin/test "$@"
diff --git a/.agents/bin/validate b/.agents/bin/validate
new file mode 100755
index 0000000..2a126a8
--- /dev/null
+++ b/.agents/bin/validate
@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+# Generated by shakacode/agent-workflows bin/push-downstream.
+# Pre-push gate: the repository's CI-core test tier.
+set -euo pipefail
+cd "$(CDPATH= cd -- "$(dirname -- "$0")/../.." && pwd)"
+exec bin/test ci "$@"
diff --git a/AGENTS.md b/AGENTS.md
index 1df0835..af038f7 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -430,3 +430,9 @@ Codex does not need to ask again before running `gh pr ready` under those
 conditions. If required checks are failing, review-app verification is broken,
 or blocking feedback remains unresolved, leave the pull request as draft and
 report the blocker instead.
+
+## Agent Workflow Configuration
+
+Portable shared skills resolve this repo's commands and policy through:
+- **Commands** — run `.agents/bin/<name>` (`setup`, `validate`, `test`, ...); see `.agents/bin/README.md`. A missing script means that capability is n/a here.
+- **Policy / config** — `.agents/agent-workflow.yml`.
diff --git a/README.md b/README.md
index a8eb948..4f6a173 100644
--- a/README.md
+++ b/README.md
@@ -104,6 +104,11 @@ bin/dev static --no-open-browser --route=dashboard
 bin/dev prod --no-open-browser --route=dashboard
 ```
 
+`bin/setup` also installs the project-pinned Chromium binary used by the
+Playwright smoke checks. On a minimal Linux image, provision Playwright's
+system packages separately with `pnpm exec playwright install --with-deps chromium`
+when the image build has the required system-package privileges.
+
 `bin/dev` starts Rails, Rspack, Solid Queue, the React on Rails Pro Node
 renderer, and the RSC bundle watcher. Development defaults to live reload; use
 the HMR command only when testing HMR behavior.
diff --git a/bin/setup b/bin/setup
index 6945566..6ee64b9 100755
--- a/bin/setup
+++ b/bin/setup
@@ -19,6 +19,9 @@ FileUtils.chdir APP_ROOT do
   puts "\n== Installing JavaScript dependencies =="
   system! "pnpm install"
 
+  puts "\n== Installing Playwright Chromium =="
+  system! "pnpm", "exec", "playwright", "install", "chromium"
+
   puts "\n== Preparing database =="
   system! "bin/rails db:prepare"
   system! "bin/rails db:seed"