codebyplan 1.11.1 → 1.11.2

package/templates/agents/cbp-round-executor.md

@@ -69,14 +69,14 @@ output:
   specialist_needs:            # What specialist agents are needed post-execution
     tests_written:
       unit_tests: string[]     # Unit test files written inline (Step 3.6)
-      e2e_tests: string[]      # Always empty — e2e test files are written by cbp-test-e2e-agent (spawned by /cbp-round-execute Step 5, NOT by this executor)
+      e2e_tests: string[]      # Always empty — e2e test files are written by the cbp-e2e-* specialist agents (dispatched per context/testing/e2e.md), spawned by /cbp-round-execute Step 5, NOT by this executor
       framework_configured: boolean  # True if test/lint framework was set up
     review_needed:
       ui_review: boolean       # Visual design review needed
       ux_review: boolean       # UX flow review needed
       security_review: boolean # Security scan needed
-  testing_profile: string      # Read from task.context.testing_profile (and round.context.testing_profile_override if set); surfaced for /cbp-round-execute Step 5 per-wave cbp-testing-qa-agent + cbp-test-e2e-agent skip logic per rules/testing-profile.md
-  # NOTE: e2e_output is populated by /cbp-round-execute Step 5 (NOT this agent) and lives at round.context.e2e_output. The executor's Step 3.8 cbp-frontend-ui invocation runs with phase: 'style_only' and never sees screenshots; the post-e2e screenshot review happens at Step 5b.
+  testing_profile: string      # Read from task.context.testing_profile (and round.context.testing_profile_override if set); surfaced for /cbp-round-execute Step 5 per-wave cbp-testing-qa-agent + cbp-e2e-* specialist skip logic per rules/testing-profile.md
+  # NOTE: e2e output is populated by /cbp-round-execute Step 5 (NOT this agent) and lives at round.context.e2e_outputs (a framework-keyed map, one entry per eligible cbp-e2e-* specialist). The executor's Step 3.8 cbp-frontend-ui invocation runs with phase: 'style_only' and never sees screenshots; the post-e2e screenshot review happens at Step 5b.
 ```
 
 ## Tools Available
@@ -165,7 +165,7 @@ Before ANY Write/Edit invocation during execution, the target path MUST appear i
 
 **Exemptions** — paths that may be edited without an entry in `files_to_modify[]`:
 
-- Test files written by Step 3.6 (unit only — e2e is written by `cbp-test-e2e-agent` post-executor, not by this agent) when the plan flagged `tests_written` as a deliverable
+- Test files written by Step 3.6 (unit only — e2e is written by the `cbp-e2e-*` specialist agents post-executor, not by this agent) when the plan flagged `tests_written` as a deliverable
 - Lockfiles regenerated by `pnpm install` after `package.json` edits already in scope
 - Generated TypeScript types (e.g. `apps/web/src/lib/database.types.ts`) when DB migrations are in scope
 - Auto-formatted prettier rewrites of files already in `files_to_modify[]`
@@ -181,7 +181,7 @@ Two categories of work are NOT performed by this agent and must be returned to t
 | Action | Why excluded | Where it goes |
 |--------|--------------|---------------|
 | MCP `create_task`, `update_task`, `complete_task`, `add_round`, etc. (any DB-side state mutation) | Executor frontmatter does NOT include MCP DB tools. Tool-not-available errors force orchestrator improvisation. | Surface as `improvements_noted` entry; orchestrator runs the MCP call after this agent returns. Executor never tries to invoke MCP DB tools. |
-| Spawning `cbp-test-e2e-agent` | Executor's tools list (Read/Write/Edit/Glob/Grep/Bash/TaskUpdate/AskUserQuestion/Skill) does NOT include the `Task` / Agent tool. E2E execution belongs to `/cbp-round-execute` Step 5 (parallel with `cbp-testing-qa-agent`) and is invoked by the orchestrator. | Set `specialist_needs.review_needed.ux_review` / `ui_review` if applicable. Do NOT attempt to spawn the agent from inside the executor. |
+| Spawning `cbp-e2e-*` specialist agents | Executor's tools list (Read/Write/Edit/Glob/Grep/Bash/TaskUpdate/AskUserQuestion/Skill) does NOT include the `Task` / Agent tool. E2E execution is owned by the `cbp-e2e-*` specialist agents (dispatched per `context/testing/e2e.md`), spawned by `/cbp-round-execute` Step 5 (parallel with `cbp-testing-qa-agent`) and is invoked by the orchestrator. | Set `specialist_needs.review_needed.ux_review` / `ui_review` if applicable. Do NOT attempt to spawn any e2e agent from inside the executor. |
 
 If the plan implies either action, complete the rest of the work and surface the carved-out steps in `improvements_noted[]` for the orchestrator to handle.
 
@@ -358,7 +358,7 @@ When the approved plan includes specialized work, delegate to sub-executor agent
 
 After implementing features in Step 3, write unit tests for all new/modified code. Tests are deliverables — they ship with the code in the same round.
 
-**Reference**: Read `.claude/context/testing/unit.md` (when present) for platform-specific patterns and setup instructions.
+**Reference**: Read `.claude/context/testing/unit.md` (when present) for platform-specific patterns and setup instructions. E2E test authoring is owned by the `cbp-e2e-*` specialist agents — do NOT write e2e specs here.
 
 **Platform detection** from `test_strategy` in approved plan (set by `cbp-task-planner` Phase 2.9):
 
@@ -383,7 +383,7 @@ After implementing features in Step 3, write unit tests for all new/modified cod
 
 ### Step 3.7: REMOVED — E2E execution moved to /cbp-round-execute Step 5
 
-E2E test authoring + execution is owned by `cbp-test-e2e-agent`, spawned in parallel with `cbp-testing-qa-agent` by `/cbp-round-execute` Step 5. The executor does NOT spawn it (Step 0.2 carve-out). When the plan declares e2e work is needed, the executor's only obligation is to set `specialist_needs.review_needed.ui_review` / `ux_review` if applicable; the orchestrator handles the rest.
+E2E test authoring + execution is owned by the `cbp-e2e-*` specialist agents (dispatched per `context/testing/e2e.md`), spawned in parallel with `cbp-testing-qa-agent` by `/cbp-round-execute` Step 5. The executor does NOT spawn them (Step 0.2 carve-out). When the plan declares e2e work is needed, the executor's only obligation is to set `specialist_needs.review_needed.ui_review` / `ux_review` if applicable; the orchestrator handles the rest.
 
 ### Step 3.65: Defensive React Checklist (after writing component code)
 
@@ -396,7 +396,7 @@ E2E test authoring + execution is owned by `cbp-test-e2e-agent`, spawned in para
 
 ### Step 3.8: Frontend Self-Review (UI + UX, style-only)
 
-After unit tests (Step 3.6) and the defensive React checklist (Step 3.65), run inline style-quality self-review on the round's UI work BEFORE Step 4 quality checks. This pass runs WITHOUT e2e screenshots — the screenshot-driven Phase 6.5 of `cbp-frontend-ui` runs separately at `/cbp-round-execute` Step 5b once `cbp-test-e2e-agent` has produced screenshots. Mirror counterpart of Step 2.7's pre-implementation `cbp-frontend-design` pass — design decided up-front, polish reviewed at the end of execution.
+After unit tests (Step 3.6) and the defensive React checklist (Step 3.65), run inline style-quality self-review on the round's UI work BEFORE Step 4 quality checks. This pass runs WITHOUT e2e screenshots — the screenshot-driven Phase 6.5 of `cbp-frontend-ui` runs separately at `/cbp-round-execute` Step 5b once the `cbp-e2e-*` specialist agent has produced screenshots. Mirror counterpart of Step 2.7's pre-implementation `cbp-frontend-design` pass — design decided up-front, polish reviewed at the end of execution.
 
 **Trigger gate** — fire when `files_changed` contains ANY of:
 
@@ -461,7 +461,7 @@ Analyze the completed work and populate `specialist_needs`:
 
 **Tests written** (execution phase — completed in Step 3.6):
 - `unit_tests_written`: List unit test files written inline by executor (Step 3.6)
-- `e2e_tests_written`: Always empty here — E2E test authoring is owned by `cbp-test-e2e-agent`, spawned by `/cbp-round-execute` Step 5 (post-executor)
+- `e2e_tests_written`: Always empty here — E2E test authoring is owned by the `cbp-e2e-*` specialist agents (dispatched per `context/testing/e2e.md`), spawned by `/cbp-round-execute` Step 5 (post-executor)
 - `framework_configured`: true if a unit-test/lint framework was set up from scratch
 
 **Review needed** (validation phase — these review quality):
@@ -515,7 +515,7 @@ This gate makes the contract enforceable. Without it, Step 3.4 can be silently s
 
 #### Subagent Cost Recording
 
-When ANY background subagents were spawned during execution (general-purpose, cbp-database-agent, cbp-test-e2e-agent, etc.), populate `round.context.subagent_summaries[]` with one entry per agent:
+When ANY background subagents were spawned during execution (general-purpose, cbp-database-agent, etc.), populate `round.context.subagent_summaries[]` with one entry per agent:
 
 ```yaml
 subagent_summaries:
@@ -583,7 +583,7 @@ Which would you prefer?
 - **Spawned by**: `/cbp-round-execute` Step 3 (single-wave 3-AGENT path or per-wave 3-WAVE path)
 - **Returns to**: `/cbp-round-execute` which collects output and runs per-wave `cbp-testing-qa-agent`
 - **Depends on**: `cbp-task-planner` agent (provides approved plan)
-- **May spawn**: `cbp-database-agent` as sub-executor for Supabase operations. (NOT `cbp-test-e2e-agent` — that is owned by `/cbp-round-execute` Step 5 per Step 0.2 carve-out.)
+- **May spawn**: `cbp-database-agent` as sub-executor for Supabase operations. (NOT any `cbp-e2e-*` specialist — those are owned by the `cbp-e2e-*` specialist agents (dispatched per `context/testing/e2e.md`), spawned by `/cbp-round-execute` Step 5 per Step 0.2 carve-out.)
 
 ## Structure Knowledge
 

package/templates/agents/cbp-task-check.md

@@ -82,7 +82,7 @@ Review all QA items across all rounds:
 - **Auto items**: Verify all passed (build, lint, types, tests)
 - **Default items**: Verify all resolved (pass or skipped with reason)
 
-**E2E pass vs skipped distinction**: When reading `auto_qa.items[]` for `check: 'e2e'`, do NOT conflate `status: 'pass'` with `status: 'skipped'`. A spec that ran with `passed === 0 && skipped > 0` for any path touching `files_changed` is a hard fail, not a pass — verdict text MUST explicitly call this out: "E2E spec authored but assertions did not execute (skip-gated)." Do NOT issue a READY verdict on a zero-assertion e2e run; route to a fix round per `rules/spec-skip-vs-execute.md`.
+**E2E pass vs skipped distinction**: When reading `auto_qa.items[]` for `check: 'e2e'`, do NOT conflate `status: 'pass'` with `status: 'skipped'`. A spec that ran with `passed === 0 && skipped > 0` for any path touching `files_changed` is a hard fail, not a pass — verdict text MUST explicitly call this out: "E2E spec authored but assertions did not execute (skip-gated)." Do NOT issue a READY verdict on a zero-assertion e2e run; route to a fix round per `rules/e2e-mandatory.md`.
 
 List any pending or failed items. Determine if they are blockers.
 

package/templates/agents/cbp-task-planner.md

@@ -502,6 +502,8 @@ plan.testing_profile: 'claude_only' | 'web' | 'desktop' | 'backend' | 'full_matr
 
 User may override at round-start via `$ARGUMENTS`. Planner's detection is the default — not a hard gate.
 
+**E2E eligibility is config-driven at execute time, not here.** `/cbp-round-execute` Step 5 reads `.codebyplan/e2e.json` and dispatches a `cbp-e2e-*` specialist for every framework that is `enabled && auto_run` and whose `app` path intersects the round's `files_changed` (see `rules/e2e-mandatory.md`). `testing_profile` and `has_ui_work` are **hints only**: they short-circuit e2e solely for `claude_only` / `backend`-only rounds — they do not decide eligibility for any other profile. Do not gate e2e on `has_ui_work` in the plan. Optionally, if `.codebyplan/e2e.json` exists, read each framework's `app` path to seed `pages_affected` for the routes the round touches.
+
 ### Phase 5: Design Solution
 
 Honor locked decisions. Create solution design with files, integration points.

package/templates/agents/cbp-testing-qa-agent.md

@@ -20,7 +20,7 @@ Single agent that handles non-e2e quality validation in the per-wave validation
 - Apply default production checklist items
 - Detect unrelated issues and missing tests
 
-E2E execution (Playwright / Maestro / WebDriverIO / XCUITest / vscode-test) is owned by `cbp-test-e2e-agent`, spawned in parallel with this agent by `/cbp-round-execute` Step 5. **The two agents are fully independent — this agent does NOT read `round.context.e2e_output` or `round.context.frontend_ui_review`.** This agent emits auto QA items and default checklist items. Baseline-regression findings surface as a BLOCKING gate at `/cbp-round-end` Step 7 (an explicit accept-or-fix user decision; baselines are NEVER auto-accepted).
+E2E execution (Playwright / Maestro / WebDriverIO / XCUITest / vscode-test) is owned by the `cbp-e2e-*` specialist agents (dispatched per `context/testing/e2e.md`), spawned in parallel with this agent by `/cbp-round-execute` Step 5. **The agents are fully independent — this agent does NOT read `round.context.e2e_outputs` or `round.context.frontend_ui_review`.** This agent emits auto QA items and default checklist items. Baseline-regression findings surface as a BLOCKING gate at `/cbp-round-end` Step 7 (an explicit accept-or-fix user decision; baselines are NEVER auto-accepted).
 
 ## Input Contract
 
@@ -92,7 +92,7 @@ output:
     passed: number
     warnings: number
     failed: number
-    hard_fail: boolean        # true if build/lint/types failed, unit tests (vitest/jest/cargo) failed when applicable, OR npm audit found critical/high vulnerabilities. E2E hard_fail is owned by test-e2e-agent and surfaced via round.context.e2e_output.
+    hard_fail: boolean        # true if build/lint/types failed, unit tests (vitest/jest/cargo) failed when applicable, OR npm audit found critical/high vulnerabilities. E2E hard_fail is owned by the cbp-e2e-* specialist agents and surfaced via round.context.e2e_outputs.
   critical_issues: string[]
   captured_tasks:
     - issue_index: number       # index into unrelated_issues[]
@@ -147,7 +147,7 @@ Apply `testing_profile` from input before running any checks. When `testing_prof
 | full_matrix | Run all checks |
 | cross_app | Run union of touched apps' checks (intersection by detected files) |
 
-E2E (Playwright / Maestro / WebDriverIO / XCUITest / vscode-test) is NEVER run by this agent under any profile — it's owned by `cbp-test-e2e-agent` (parallel sibling spawned by `/cbp-round-execute` Step 5).
+E2E (Playwright / Maestro / WebDriverIO / XCUITest / vscode-test) is NEVER run by this agent under any profile — it's owned by the `cbp-e2e-*` specialist agents (dispatched per `context/testing/e2e.md`; parallel siblings spawned by `/cbp-round-execute` Step 5).
 
 **CRITICAL: Within your profile's allowed check set (see Profile Gate Matrix above), every applicable command MUST be executed. No skipping an in-scope check without an explicit, logged reason.**
 
@@ -187,7 +187,7 @@ Procedure:
 
 This closes the cycle where R2 adds a flat-config and the QA pass lints only R2 files, only for `/cbp-task-check` to later lint the full task and surface dozens of errors on R1 files — wasting an entire corrective round. Plan-time premise verification does not catch this; only test-time scope expansion does.
 
-**Hard fail means: if any of build/lint/types/unit fails or is not executed when applicable, set `totals.hard_fail = true`. The round CANNOT complete.** E2E hard_fail is set independently by `test-e2e-agent` and surfaced via `round.context.e2e_output`; `/cbp-round-execute` Step 6 considers both signals.
+**Hard fail means: if any of build/lint/types/unit fails or is not executed when applicable, set `totals.hard_fail = true`. The round CANNOT complete.** E2E hard_fail is set independently by the `cbp-e2e-*` specialist agents and surfaced via `round.context.e2e_outputs`; `/cbp-round-execute` Step 6 considers both signals.
 
 **Step 3a: Execute conditional unit-test checks (HARD FAIL when applicable):**
 
@@ -209,7 +209,7 @@ Run the unit-test runners detected in Step 1:
 If condition is met and test fails: set `totals.hard_fail = true`.
 If condition is not met (no applicable files changed): log `SKIPPED: <command> (reason: no applicable files changed)`.
 
-E2E commands and their preflight (dev server / simulator / emulator / built binary / auth probe) are owned by `cbp-test-e2e-agent`. See `agents/test-e2e-agent.md` Step 6.5 for the canonical preflight contract.
+E2E commands and their preflight (dev server / simulator / emulator / built binary / auth probe) are owned by the `cbp-e2e-*` specialist agents. See `context/testing/e2e.md` for the canonical preflight contract (Step 6.5 and the shared workflow).
 
 **Step 3b: Execute conditional checks (soft):**
 
@@ -360,7 +360,7 @@ Return complete output contract.
 - Auto and default QA items generated
 - `hard_fail` flag correctly set
 - **Vitest/Jest/Cargo unit-test hard_fail enforced** when source files changed
-- E2E execution + preflight delegated entirely to `test-e2e-agent` (this agent never runs Playwright/Maestro/wdio/etc.)
+- E2E execution + preflight delegated entirely to the `cbp-e2e-*` specialist agents (this agent never runs Playwright/Maestro/wdio/etc.)
 
 ## Failure Modes
 
@@ -373,6 +373,6 @@ Return complete output contract.
 
 ## Integration
 
-- **Spawned by**: `/cbp-round-execute` Step 5 (per-wave; runs in parallel with `test-e2e-agent` and may also run in parallel with next wave's executor)
-- **Parallel sibling**: `cbp-test-e2e-agent` (fully independent — no cross-read; both agents complete on their own timeline using only their own inputs)
-- **Output consumed by**: `/cbp-round-execute` Step 6 (hard-fail routing — this agent's `totals.hard_fail` is OR'd with `e2e_output.test_results.failed > 0` and `e2e_output.status === 'failed'`), `/cbp-round-end` Step 3 (reads this agent's `auto_qa[]` and `default_checklist[]`). This agent does not emit `user_qa` items; baseline-regression findings surface as a BLOCKING gate at `/cbp-round-end` Step 7 (an explicit accept-or-fix user decision; baselines are NEVER auto-accepted).
+- **Spawned by**: `/cbp-round-execute` Step 5 (per-wave; runs in parallel with the `cbp-e2e-*` specialists and may also run in parallel with next wave's executor)
+- **Parallel siblings**: `cbp-e2e-*` specialist agents (fully independent — no cross-read; all agents complete on their own timeline using only their own inputs)
+- **Output consumed by**: `/cbp-round-execute` Step 6 (hard-fail routing — this agent's `totals.hard_fail` is OR'd across `round.context.e2e_outputs` entries: any `e2e_outputs[f].test_results.failed > 0` or `e2e_outputs[f].status === 'failed'`, plus the `e2e_eligible_skipped` signal), `/cbp-round-end` Step 3 (reads this agent's `auto_qa[]` and `default_checklist[]`). This agent does not emit `user_qa` items; baseline-regression findings surface as a BLOCKING gate at `/cbp-round-end` Step 7 (an explicit accept-or-fix user decision; baselines are NEVER auto-accepted).

package/templates/context/testing/e2e.md

@@ -0,0 +1,303 @@
+---
+scope: org-shared
+---
+
+# E2E Shared Workflow Contract
+
+Loaded by every `cbp-e2e-*` specialist agent. Defines the shared Input/Output contract,
+pre-flight loop, failure classification, screenshot rules, dispatch routing, and
+never-silently-skip obligations. Framework-specific commands live in each agent's body.
+
+## Input Contract
+
+Passed by the dispatching skill (`/cbp-round-execute` Step 5, `/cbp-checkpoint-check`
+Step 5b, or `/cbp-checkpoint-plan` Step 4 discovery probe). The dispatching skill reads
+`.codebyplan/e2e.json` and injects `framework`, `app`, `platforms`, and credential var
+names — agents do NOT auto-detect platform; the config is authoritative.
+
+```yaml
+input:
+  repo_id: string                            # UUID — used to resolve tech_stack from DB
+  round_number: number                       # 1-based; 0 is the sentinel for whole_checkpoint_mode
+  files_changed: [{path, action}]
+  prior_round_files_changed:                 # Required when round_number >= 2
+    - path: string
+      action: string
+      user_approved: boolean
+  whole_checkpoint_mode: boolean             # Default false. When true, run full pages_affected
+  test_strategy:
+    platform: string
+    e2e_framework: string                    # playwright | maestro | webdriverio | xcuitest | vscode-test
+  pages_affected: string[]                   # Routes or screen names changed
+  has_auth: boolean
+  dev_server_port: number | null
+  framework: string                          # From .codebyplan/e2e.json — authoritative
+  app: string                                # App path (e.g. apps/web)
+  platforms: string[]                        # e.g. ["web"] | ["ios","android"] | ["desktop"]
+  credential_vars:                           # Env var names to probe at Step 6.5.1
+    email: string | null
+    password: string | null
+```
+
+## Output Contract
+
+```yaml
+output:
+  status: 'completed' | 'failed'          # 'blocked' is NOT valid — resolve via AskUserQuestion
+  tests_written: [{path, action: 'created' | 'modified'}]
+  tests_run: boolean                      # MUST be true when status == 'completed'
+  test_results:
+    passed: number
+    failed: number
+    skipped: number
+    failures:
+      - test_name: string
+        error: string
+        file: string
+        category: 'env' | 'auth' | 'access' | 'flake' | 'real' | 'visual_regression'
+        classification_reason: string
+  framework_configured: boolean
+  preflight:
+    dev_server:     { required: bool, ok: bool, port: number | null, notes: string }
+    simulator:      { required: bool, ok: bool, device: string | null, notes: string }
+    built_binary:   { required: bool, ok: bool, path: string | null, notes: string }
+    env_vars:       { required: string[], missing: string[], ok: bool }
+    auth_probe:     { ran: bool, ok: bool, probe_path: string | null, error: string | null }
+  screenshots:
+    - test_name: string
+      path: string                        # Absolute or repo-relative path to PNG
+      page_or_screen: string
+      viewport: 'desktop' | 'mobile' | 'tablet' | 'device'
+      is_new: bool
+      baseline_diff_pct: number | null
+  user_interactions: [{question, answer}]
+  tech_stack_reconciliation:
+    db_framework: string | null
+    fs_framework: string | null
+    resolution: 'follow_db' | 'follow_fs' | 'configure_missing' | 'skip_app' | 'no_mismatch' | 'no_db_data'
+    decided_at: string
+  round2_skip_set:
+    - spec_path: string
+      reason: string
+  whole_checkpoint_aggregated: boolean
+  critical_issues:
+    - type: string
+      spec_path: string | null
+      reason: string
+```
+
+## Step 5.1 — Page Filter (Round 2+, non-checkpoint mode)
+
+When `round_number >= 2` AND `whole_checkpoint_mode === false`:
+
+1. Build `unapproved_files` from `prior_round_files_changed` where `user_approved === false`.
+2. For each page in `pages_affected[]`, derive contributing source files:
+   - Next.js: `app/<route>/page.tsx` + layout chain + imported components
+   - Expo / React Native: screen file + imported components
+   - Tauri: route component + Rust handler files
+   - Fallback: any file whose path starts with the page's directory
+3. A page **survives** when ANY contributing file is in `unapproved_files`.
+4. A page **is skipped** when ALL contributing files are user-approved.
+5. Record skipped pages in `round2_skip_set[]`.
+6. Replace `pages_affected` with the surviving subset.
+
+When `round_number === 1` OR `whole_checkpoint_mode === true`, use `pages_affected` verbatim.
+
+## Step 6.5 — Pre-flight (MANDATORY)
+
+Never proceed with `tests_run: false`. Resolve every failing check via `AskUserQuestion`
+in a loop — re-probe after user confirmation. An explicit abort returns `status: 'failed'`
+with the blocking preflight field populated.
+
+### 6.5.1 Environment Variables
+
+Check `apps/{app}/.env.local` and process env. Framework-specific required var names come
+from the `credential_vars` input field (the dispatching skill reads them from
+`.codebyplan/e2e.json`). Naming conventions:
+
+- Playwright uses `E2E_TEST_*` (avoids collision with non-E2E `TEST_*` vars).
+- Maestro/XCUITest stay on `TEST_*` per `rules/maestro-auth-state-reset.md`.
+
+For any missing var:
+
+> "Missing required E2E env vars: `{names}`. Set them in `apps/{app}/.env.local` now,
+> then reply 'ready'. (Or reply 'skip' to abort this e2e run.)"
+
+**Hard rule**: Specs MUST NOT contain in-spec env skip gates (`test.skip(!process.env.X, ...)`)
+— those bypass preflight and produce zero-assertion runs. See `rules/e2e-mandatory.md`.
+
+### 6.5.2 Runtime Readiness
+
+Framework-specific probes are in each agent's body. General obligations:
+
+- Playwright: dev server responding at `baseURL` port (curl HTTP 200/3xx).
+- Maestro (iOS): booted simulator (`xcrun simctl list devices booted | grep Booted`).
+- Maestro (Android): connected device/emulator (`adb devices | grep -w device`).
+- WebDriverIO: built Tauri binary present at the path in `wdio.conf.ts`.
+- XCUITest: `xcodebuild -list` returns the scheme; Expo prebuild artifacts present.
+- vscode-test: compiled test JS present (`e2e/**/*.test.js`).
+
+On any failure, `AskUserQuestion` with remediation steps; re-probe after "ready". Never
+silently skip a required runtime prerequisite.
+
+**Port alignment (Playwright only)**: parse `playwright.config.ts` `baseURL` and compare
+to `.codebyplan/server.json` `port_allocations[]` for the app. On mismatch ask which is
+correct before running.
+
+### 6.5.3 Auth Probe (only when `has_auth`)
+
+Run the dedicated auth probe — not the full suite. Probe paths per framework are in each
+agent's body.
+
+If the probe fails, classify the reason (see Step 7.5 below) and ask:
+
+> "Auth probe failed: `{category}` — `{error_summary}`. Common causes: wrong credentials,
+> expired state, auth backend paused, captcha. Options: (1) delete storage state + retry,
+> (2) fix credentials + reply 'ready', (3) abort e2e."
+
+On "ready", re-run the probe. Loop up to 3 times before escalating with a new
+`AskUserQuestion` that summarises all 3 attempts' errors.
+
+## Step 7.5 — Failure Classification
+
+For each failed test, assign exactly one category:
+
+| Category | Signals | Resolution |
+|---|---|---|
+| `env` | `process.env.X is undefined`, `ECONNREFUSED`, missing config | Loop to Step 6.5.1 |
+| `auth` | Login-page redirect, 401 after credential submit, `invalid_grant`, `email_not_confirmed` | AskUserQuestion per Step 6.5.3 |
+| `access` | 403/404 on an accessible route, RLS denial text, missing seed data | AskUserQuestion: "Test failed with access error: `{error}`. Options: (1) fix + reply steps, (2) abort." |
+| `flake` | Timeout on first run, passes on immediate retry, network jitter | Retry up to 3 times before reclassifying to `real` |
+| `visual_regression` | `toHaveScreenshot` pixel-diff exceeded threshold | Do NOT retry. Include baseline + actual paths in `screenshots[]` with `baseline_diff_pct`. Do NOT auto-accept baselines. |
+| `real` | Assertion failure on app behavior (wrong text, state, navigation) | Attempt fix (selector, timeout, assertion), max 3 attempts, then report |
+
+`env`, `auth`, `access` failures MUST NOT count toward `test_results.failed` until
+preflight passes — they block the run instead.
+
+## Screenshot Collection Rule
+
+After every run, enumerate all PNGs produced and populate `screenshots[]`. Framework-
+specific paths are in each agent's body. Every entry requires:
+`{test_name, path, page_or_screen, viewport, is_new, baseline_diff_pct}`.
+
+Screenshots flow to `cbp-frontend-ui` invoked by `/cbp-round-execute` Step 5b with
+`phase: 'screenshot_review'` — NOT inline by `round-executor` Step 3.8 (which runs
+`phase: 'style_only'` without e2e output).
+
+**Baselines are never auto-accepted.** A `toHaveScreenshot` diff is `visual_regression`;
+the user decides via QA whether to update baselines.
+
+## Completion Rule
+
+`status: 'completed'` is allowed ONLY when:
+
+- `tests_run === true`
+- `preflight.*.ok === true` for every required prerequisite
+- Every failure has `category` other than `env`, `auth`, or `access`
+
+Otherwise return `status: 'failed'`.
+
+## Never-Silently-Skip Rules
+
+- Missing simulator / server / binary / env / auth → always `AskUserQuestion`, never `tests_run: false`.
+- No testable targets despite `has_ui_work` → return `status: 'failed'` with reason "no testable targets".
+- All-skipped run (`passed === 0 && skipped > 0` for a spec in `files_changed`) → `status: 'failed'`, add `critical_issues[]` entry `{type: 'e2e_all_skipped', ...}`.
+- User aborts preflight → `status: 'failed'`, add `critical_issues[]` entry `{type: 'preflight_aborted', ...}`.
+
+## Dispatch / Eligibility Routing Contract
+
+The dispatching skill (`/cbp-round-execute` Step 5 or `/cbp-checkpoint-check` Step 5b)
+selects one specialist per app. Config is in `.codebyplan/e2e.json` (authoritative).
+
+| `framework` in e2e.json | Agent spawned | Typical app type |
+|---|---|---|
+| `playwright` | `cbp-e2e-playwright` | Next.js web routes |
+| `maestro` | `cbp-e2e-maestro` | Expo / React Native (android + ios) |
+| `webdriverio` | `cbp-e2e-tauri` | Tauri desktop |
+| `vscode-test` | `cbp-e2e-vscode` | VS Code extension |
+| `xcuitest` | `cbp-e2e-xcuitest` | Native iOS (system dialogs, HealthKit, watchOS) |
+
+**Eligibility is config-driven.** A framework is **eligible** in a round when its
+`.codebyplan/e2e.json` entry has `enabled === true` AND `auto_run === true` AND its `app`
+source path intersects the round's `files_changed` (repo root for single-app repos). An
+eligible framework's specialist MUST run — see `rules/e2e-mandatory.md` for the opt-out
+contract and the `e2e_eligible_skipped` hard-fail.
+
+An agent is NOT spawned when ANY of the following hold:
+
+- `testing_profile` is `claude_only` or `backend` (no UI surface) — a short-circuit hint, applied before reading `e2e.json`.
+- The framework's `enabled` or `auto_run` is `false`, or the `app` path does not intersect `files_changed`.
+- `frameworks` in `e2e.json` is absent or empty (no e2e configured) — zero eligible, no hard-fail.
+- `platforms[]` in `e2e.json` does not include the current CI target (e.g., iOS-only config skipped on a Linux runner without a simulator) — a recorded valid skip per `rules/e2e-mandatory.md`.
+
+`has_ui_work` and `testing_profile` (beyond the `claude_only` / `backend` short-circuit) are
+**hints only** — they never suppress an eligible framework. Config is authoritative.
+
+**Multi-app monorepos**: the dispatching skill reads `e2e.json` per app path and may
+spawn multiple specialists in the same round (one per eligible framework). Agents run in
+parallel with `cbp-testing-qa-agent`. Each specialist's output is stored under
+`round.context.e2e_outputs[framework]` (a framework-keyed map); `/cbp-round-execute` Step 5b
+aggregates `screenshots[]` across all entries before the `cbp-frontend-ui` review.
+
+**whole_checkpoint_mode dispatch** (`/cbp-checkpoint-check` Step 5b and `/cbp-checkpoint-plan`
+Step 4): pass `round_number: 0`, `whole_checkpoint_mode: true`, and the aggregated
+`files_changed` union. The agent ignores `prior_round_files_changed` in this mode.
+
+This contract is the single source of truth for dispatch logic. Config-driven dispatch is
+implemented in `/cbp-round-execute` Step 5 and `/cbp-checkpoint-check` Step 5b (CHK-145); the
+routing table above is the authoritative reference those gates match. Enforcement (the
+`e2e_eligible_skipped` hard-fail and the no-in-spec-env-skip gate) lives in
+`rules/e2e-mandatory.md`.
+
+## Playwright Auth Provisioning Convention
+
+Every repo with Playwright auth ships:
+
+- `scripts/provision-e2e-user.ts` — idempotent script creating the canonical E2E user
+  and (for multi-tenant repos) a `test` subdomain. Wired to `pnpm e2e:provision`.
+- `.env.local.example` — lists every env var `globalSetup` requires.
+- CI secrets: `E2E_TEST_EMAIL`, `E2E_TEST_PASSWORD`, `NEXT_PUBLIC_SUPABASE_URL`,
+  `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY` (or legacy `_ANON_KEY`).
+
+Per-repo specifics (email, vault name, remaining-spec migration list) live in the repo's
+own `docs/e2e-setup.md`, not in this shared file.
+
+## Auth State Gitignore
+
+Before writing any storage state under `playwright/.auth/`, `tests/.auth/`, or
+`e2e/.auth/`, verify the path is in the nearest `.gitignore`. If absent, ADD the entry
+first. Auth state files contain live session cookies — committing one is a credential
+leak. See `rules/playwright-auth-gitignore.md`.
+
+## Supabase Parallelism (Playwright)
+
+When `NEXT_PUBLIC_SUPABASE_URL` references a remote project (not localhost), set
+`workers: 1` in `playwright.config.ts` to prevent auth/RLS races. Not needed with a
+local Supabase emulator. Detect via: `grep -E "127\.0\.0\.1|localhost" apps/{app}/.env.local | grep SUPABASE_URL`.
+
+## Mock Server for Server-Side Fetch
+
+`page.route()` intercepts browser-process requests only. For Next.js server actions,
+route handlers, or middleware (Node-process fetch), spin up a real local HTTP server in
+`globalSetup` and point the dev server at it via `webServer.env`. See
+`rules/playwright-server-side-mocking.md`.
+
+## Cold-Start Warmup (Playwright / Next.js)
+
+Next.js dev mode (Turbopack) compiles routes lazily. Add a warmup fetch at the end of
+`globalSetup`, after mock server starts, before specs run. Use `redirect: 'manual'` for
+auth-protected routes. Wrap in `try/catch` — warmup is best-effort.
+
+## Locator Hygiene (Playwright)
+
+Prefer stable accessibility-driven selectors (`getByRole`, `getByLabel`, `getByTestId`)
+over positional CSS selectors (`.locator('.class').nth(N)`). After `page.goto()` inside
+a loop, snapshot text/href BEFORE navigation rather than holding stale `Locator` handles.
+
+## Visual Baseline Workflow
+
+| Situation | What happens |
+|---|---|
+| No baseline (new screen) | Playwright creates on first run; test passes; `cbp-frontend-ui` at Step 5b reviews semantically. |
+| Baseline exists, diff ≤ threshold | Test passes. |
+| Baseline exists, diff > threshold | `visual_regression` failure. Agent does NOT retry. `cbp-frontend-ui` at Step 5b flags it; `/cbp-round-end` Step 3b constructs user QA item. User decides: fix-task or `--update-snapshots`. |

package/templates/hooks/validate-structure-lengths.sh

@@ -19,12 +19,14 @@ _get_limit() {
     /CHANGELOG.md|*/CHANGELOG.md|*/user-input.md|/.claude/docs/research/*) echo ""; return;;
     # Managed .claude/ files
     /.claude/rules/*.md)                                echo "100 200"; return;;
+    /.claude/context/testing/e2e.md)                    echo "300 600"; return;;   # consolidated E2E shared-workflow + dispatch contract (CHK-145)
     /.claude/context/*.md|/.claude/context/*/*.md)      echo "200 400"; return;;
     /.claude/skills/*/SKILL.md)                         echo "300 600"; return;;
     /.claude/skills/*/reference/*.md)                   echo "200 400"; return;;
     /.claude/skills/*/examples/*.md|/.claude/skills/*/templates/*) echo "100 200"; return;;
     /.claude/agents/*/AGENT.md)                         echo "400 800"; return;;
     /.claude/agents/*/*.md)                             echo "200 400"; return;;
+    /.claude/agents/*.md)                               echo "400 800"; return;;
     /.claude/hooks/*.sh)                                echo "150 300"; return;;
     /.claude/docs/architecture/*.md|/.claude/docs/server/*.md) echo "200 400"; return;;
     /.claude/docs/stack/*/index.md|/.claude/docs/stack/*/guide.md) echo "150 300"; return;;

package/templates/hooks/validate-structure-smoke.sh

@@ -62,7 +62,8 @@ run_case() {
 
 # ===== Good fixtures (must exit 0) =====
 run_case "good-skill"   good/skill.md /.claude/skills/cbp-fixture/SKILL.md 0
-run_case "good-agent"   good/agent.md /.claude/agents/cbp-fixture/AGENT.md 0
+run_case "good-agent"      good/agent.md /.claude/agents/cbp-fixture/AGENT.md 0
+run_case "good-agent-flat" good/agent.md /.claude/agents/cbp-fixture.md 0
 run_case "good-rule"    good/rule.md  /.claude/rules/cbp-fixture.md 0
 run_case "good-hook"    good/hook.sh  /.claude/hooks/cbp-fixture.sh 0
 

package/templates/hooks/validate-structure-templates.sh

@@ -12,6 +12,7 @@ TEMPLATE=""
 case "$REL_PATH" in
   /.claude/skills/*)              TEMPLATE="/packages/codebyplan-package/templates/skills/build-cc-skill/reference/cbp-quality.md" ;;
   /.claude/agents/*/AGENT.md)     TEMPLATE="/packages/codebyplan-package/templates/skills/build-cc-agent/reference/cbp-quality.md" ;;
+  /.claude/agents/*.md)           TEMPLATE="/packages/codebyplan-package/templates/skills/build-cc-agent/reference/cbp-quality.md" ;;
   /.claude/docs/research/*/1-*)   TEMPLATE="/docs/templates/.claude/docs/research/1-problem.md" ;;
   /.claude/docs/research/*/2-*)   TEMPLATE="/docs/templates/.claude/docs/research/2-claude-default.md" ;;
   /.claude/docs/research/*/3-*)   TEMPLATE="/docs/templates/.claude/docs/research/3-official-docs.md" ;;

package/templates/rules/context-file-loading.md

@@ -14,8 +14,11 @@ paths:
 | Context File | Loaded By | Phase | Purpose |
 |--------------|-----------|-------|---------|
 | `context/testing/unit.md` | `cbp-round-executor` | Step 3.6 | Unit test patterns per framework |
-| `context/testing/e2e.md` | `cbp-test-e2e-agent` | Entry | E2E framework setup + spec patterns |
+| `context/testing/e2e.md` | `cbp-e2e-playwright`, `cbp-e2e-maestro`, `cbp-e2e-tauri`, `cbp-e2e-vscode`, `cbp-e2e-xcuitest` | Entry | Shared contract: Input/Output, preflight, failure classification, dispatch routing |
 | `context/testing/e2e.md` | `cbp-testing-qa-agent` | Preflight | Env var list per framework |
+| `context/testing/e2e.md` | `cbp-checkpoint-plan` | Step 4 | Discovery probe dispatch contract |
+| `context/testing/e2e.md` | `cbp-round-execute` | Step 5 | E2E specialist dispatch routing |
+| `context/testing/e2e.md` | `cbp-checkpoint-check` | Step 5b | Whole-checkpoint e2e dispatch |
 | `context/testing/eslint.md` | `cbp-task-planner` | Phase 1.5 | ESLint Compliance Checklist |
 | `context/testing/eslint.md` | `cbp-improve-round` | Phase 1.5 | Config-file compliance audit |
 | `context/mcp-docs.md` | `cbp-task-planner` | Phase 2.6 | MCP library doc lookup contract — per-dependency consultation via DocsByPlan MCP tools (resolve_library_id → search_chunks/lookup_symbol → get_chunk) |

package/templates/rules/e2e-mandatory.md

@@ -0,0 +1,70 @@
+---
+scope: org-shared
+---
+
+# E2E Mandatory Run Contract
+
+E2E is **opt-out, not opt-in**. Whenever a framework configured in `.codebyplan/e2e.json`
+covers an app whose source changed in a round, the matching `cbp-e2e-*` specialist runs —
+there is no per-round decision to "add" e2e. This rule defines *when a run is obligatory*
+and *what makes a skip legitimate*. The companion Input/Output contract and the
+framework → agent dispatch routing table live in `context/testing/e2e.md`.
+
+## Opt-Out Contract
+
+A framework is **eligible** in a round when ALL hold:
+
+- `.codebyplan/e2e.json` `frameworks.{name}.enabled === true` AND `auto_run === true`.
+- The framework's `app` source path intersects the round's `files_changed` (repo root for
+  single-app repos).
+
+When eligible, `/cbp-round-execute` Step 5 spawns the matching specialist in parallel with
+`cbp-testing-qa-agent`; `/cbp-checkpoint-check` Step 5b does the same against the aggregated
+file union with `whole_checkpoint_mode: true`.
+
+`has_ui_work` and `testing_profile` are **hints only** — they short-circuit e2e *solely* for
+`claude_only` / `backend`-only rounds (no UI surface). For every other profile config is
+authoritative: a `has_ui_work === false` inference never suppresses an eligible framework.
+
+When `frameworks` is absent or empty, zero frameworks are eligible — no specialist runs and
+no hard-fail fires.
+
+## `e2e_eligible_skipped` Hard-Fail
+
+If a framework was eligible this round but no specialist ran AND no valid skip reason is
+recorded, the round **hard-fails** and `/cbp-round-execute` Step 6 auto-triggers
+`/cbp-round-input`. Silent skips are bugs, not conveniences — this is the enforcement behind
+the opt-out contract.
+
+**Valid skip reasons** (must be recorded in `round.context.e2e_outputs[framework]` or the
+round failure context):
+
+- User explicitly aborted preflight → specialist returns `status: 'failed'` with a
+  `critical_issues[].type === 'preflight_aborted'` entry.
+- Environmental block: `preflight.*.ok === false` (missing simulator / server / binary / env)
+  persists after the Step 6.5 AskUserQuestion loop — an env block, not a spec failure.
+- `platforms[]` in `e2e.json` excludes the current CI target (e.g. an iOS-only config on a
+  Linux runner with no simulator).
+- Round type is `survey` (no code executed).
+
+No other skip reason is valid. "Looked UI-light", "tests are slow", or "covered by unit
+tests" are NOT valid skips.
+
+## No In-Spec Env-Skip Gate
+
+Spec files MUST NOT contain in-spec env skip gates such as `test.skip(!process.env.X, ...)`.
+They bypass preflight, produce zero-assertion runs, and hide missing env vars behind a green
+check. Pre-flight (`context/testing/e2e.md` Step 6.5.1) is the only mechanism for
+env-conditional skipping.
+
+A spec that ran with `passed === 0 && skipped > 0` for any path touching `files_changed` is a
+**hard fail**, not a pass — `cbp-task-check` (`agents/cbp-task-check.md`) refuses a READY
+verdict on a zero-assertion e2e run and routes to a fix round per this rule.
+
+## Cross-References
+
+- `context/testing/e2e.md` — Input/Output contract, pre-flight loop, failure classification,
+  and the dispatch routing table (framework → agent).
+- `agents/cbp-task-check.md` — enforces the zero-assertion hard-fail at verdict time.
+- `skills/cbp-round-execute/SKILL.md` Step 5/6, `skills/cbp-checkpoint-check/SKILL.md` Step 5b
+  — the config-driven dispatch and `e2e_eligible_skipped` gate implementations.