codebyplan 1.11.1 → 1.11.2

package/templates/skills/cbp-build-cc-agent/SKILL.md

@@ -1,7 +1,7 @@
 ---
 scope: org-shared
 name: cbp-build-cc-agent
-description: Build a Claude Code subagent at .claude/agents/{name}/AGENT.md (CBP folder form) following the official sub-agents spec (frontmatter, tools, model, memory, hooks, skills preload, permission modes, isolation).
+description: Build a Claude Code subagent at .claude/agents/{name}.md (flat form, per the official sub-agents spec) following the official sub-agents spec (frontmatter, tools, model, memory, hooks, skills preload, permission modes, isolation).
 argument-hint: "[agent-name] [--scope=project|user] [--memory=project|user|local] [--isolation=worktree]"
 allowed-tools: Read, Write, Edit, Glob, Grep, Bash(mkdir *), Bash(chmod *)
 effort: xhigh
@@ -32,18 +32,18 @@ Do **not** create a subagent for one-off work — spawn `general-purpose` inline
 
 - Name must be lowercase kebab-case (a–z, 0–9, hyphens only)
 - Reject collisions with built-in agents: `Explore`, `Plan`, `general-purpose`, `statusline-setup`, `Claude Code Guide`
-- Reject if `.claude/agents/{name}/AGENT.md` already exists unless the user asked to update
+- Reject if `.claude/agents/{name}.md` already exists unless the user asked to update
 
 ### Step 2 — Pick scope
 
-CBP uses the **folder form** so an agent can bundle supporting docs/scripts next to `AGENT.md`.
+The default layout is **flat form** — a single `.claude/agents/{name}.md` file, matching the official Claude Code sub-agents spec and all 12 existing CBP agents. Use folder form `{name}/AGENT.md` only when the agent bundles supporting files (context, examples, scripts) next to it.
 
-| Scope   | Path                               | Use when                                |
-| ------- | ---------------------------------- | --------------------------------------- |
-| project | `.claude/agents/{name}/AGENT.md`   | Repo-specific, shared with team via git |
-| user    | `~/.claude/agents/{name}/AGENT.md` | Personal, reused across all projects    |
+| Scope   | Path                            | Use when                                |
+| ------- | ------------------------------- | --------------------------------------- |
+| project | `.claude/agents/{name}.md`      | Repo-specific, shared with team via git |
+| user    | `~/.claude/agents/{name}.md`    | Personal, reused across all projects    |
 
-Default: `project`. Pass `--scope=user` to override. Flat form (`.claude/agents/{name}.md`) is the Claude Code native layout but CBP's structure hook expects the folder form — always use that in this repo.
+Default: `project`. Pass `--scope=user` to override. Use folder form `{scope-path}/{name}/AGENT.md` only when bundling supporting files alongside the agent definition.
 
 ### Step 3 — Read the template and CBP context
 
@@ -89,8 +89,8 @@ Cross-references for complex cases:
 
 ### Step 6 — Write the agent file
 
-1. Create directory: `mkdir -p {scope-path}/{name}`
-2. Write `{scope-path}/{name}/AGENT.md`
+1. Write `{scope-path}/{name}.md` (flat form — default for all new agents)
+2. If the agent bundles supporting files (context, examples, scripts), create a folder instead: `mkdir -p {scope-path}/{name}` and write `{scope-path}/{name}/AGENT.md`
 3. Copy the template, fill frontmatter, then write the system prompt as the markdown body. The body becomes the agent's entire system prompt — no CLAUDE.md prefix, no Claude Code defaults.
 
 System prompt guidance:
@@ -100,16 +100,18 @@ System prompt guidance:
 - Output format it must return
 - Failure modes (when to return `blocked`, `failed`, `no_findings`)
 
-Supporting files (optional) live next to `AGENT.md` in the same folder: `{name}/context.md`, `{name}/examples/`, etc.
+Supporting files (optional) live next to the agent in a same-name folder: `{name}/context.md`, `{name}/examples/`, etc. Only create the folder when you are actually writing supporting files.
 
 ### Step 7 — Validate
 
 Run the validator:
 
 ```bash
-bash "${CLAUDE_SKILL_DIR}/scripts/validate-agent.sh" "{scope-path}/{name}/AGENT.md"
+bash "${CLAUDE_SKILL_DIR}/scripts/validate-agent.sh" "{scope-path}/{name}.md"
 ```
 
+(Pass `{scope-path}/{name}/AGENT.md` instead if folder form was chosen.)
+
 It checks: name format, frontmatter parses, required fields present (`name`, `description`, `scope`), tool names are valid, model alias is recognised.
 
 ### Step 8 — Surface to the user
@@ -126,7 +128,7 @@ Report:
 
 - **Triggered by**: user invocation
 - **Reads**: `${CLAUDE_SKILL_DIR}/templates/agent.md`, `${CLAUDE_SKILL_DIR}/reference/*.md` (including `cbp-quality.md`)
-- **Writes**: `.claude/agents/{name}/AGENT.md` or `~/.claude/agents/{name}/AGENT.md`
+- **Writes**: `.claude/agents/{name}.md` (flat default) or `.claude/agents/{name}/AGENT.md` (folder form, when bundling supporting files); same under `~/.claude/` for user scope
 - **Related skills**: `/cbp-build-cc-skill` (skill-level workflows), `/cbp-build-cc-settings` (session-level `SubagentStart`/`SubagentStop` hooks), `/cbp-build-cc-mode` (canonical model/effort matrix — audit or apply)
 
 ## Key Rules
@@ -136,4 +138,4 @@ Report:
 - `bypassPermissions` and `acceptEdits` inherited from the parent cannot be weakened by the child
 - Preloaded skills inject _full content_ at startup — don't preload `disable-model-invocation: true` skills
 - Restart the session or use `/agents` to load a newly written agent file
-- CBP folder form is required — the structure hook blocks flat agent files in this repo
+- Flat form `.claude/agents/{name}.md` is the default and matches all 12 existing CBP agents; folder form `{name}/AGENT.md` is optional and only for agents that bundle supporting files alongside them

package/templates/skills/cbp-build-cc-agent/reference/cbp-quality.md

@@ -4,11 +4,11 @@ scope: org-shared
 
 # Agent Authoring Quality
 
-Quality expectations and structure for `/.claude/agents/{name}/AGENT.md` files. This file adds CBP-specific constraints on top of the official Claude Code sub-agents spec.
+Quality expectations and structure for `/.claude/agents/{name}.md` files. This file adds CBP-specific constraints on top of the official Claude Code sub-agents spec.
 
-## CBP Folder Form
+## Agent Layout
 
-CBP uses the folder form `.claude/agents/{name}/AGENT.md`, not Claude Code's native flat `.claude/agents/{name}.md`. The structure hook enforces this. Folder form lets an agent bundle supporting files (context, examples, scripts) next to `AGENT.md`.
+CBP uses the flat form `.claude/agents/{name}.md` — the default per the official Claude Code sub-agents spec. All 12 existing CBP agents use this layout. Folder form `.claude/agents/{name}/AGENT.md` is optional and only appropriate when the agent bundles supporting files (context, examples, scripts) next to the definition.
 
 ## Required CBP Frontmatter
 
@@ -125,7 +125,7 @@ Agents that modify `.claude/` files MUST:
 
 | Situation                                | Action                                          |
 | ---------------------------------------- | ----------------------------------------------- |
-| Existing agent covers the domain         | Update its AGENT.md                             |
+| Existing agent covers the domain         | Update its agent definition file                |
 | New domain, no existing agent covers it  | Create new agent                                |
 | Existing agent is too large (>400 lines) | Split into orchestrator + specialist            |
 | One-off task, not recurring              | Don't create an agent — use inline instructions |

package/templates/skills/cbp-build-cc-agent/scripts/validate-agent.sh

@@ -1,11 +1,12 @@
 #!/bin/bash
-# Validate a Claude Code subagent file (CBP folder form).
-# Usage: validate-agent.sh <path-to-AGENT.md>
+# Validate a Claude Code subagent file (flat form or CBP folder form).
+# Usage: validate-agent.sh <path-to-agent-file>
+# Accepts: flat agents/{name}.md (spec default) or folder agents/{name}/AGENT.md (for bundling).
 # Exit 0 = valid, exit 1 = invalid (errors printed to stderr).
 
 set -uo pipefail
 
-FILE="${1:?Usage: validate-agent.sh <path-to-AGENT.md>}"
+FILE="${1:?Usage: validate-agent.sh <path-to-agent-file>}"
 
 if [ ! -f "$FILE" ]; then
   echo "ERROR: file not found: $FILE" >&2
@@ -15,10 +16,11 @@ fi
 errors=0
 err() { echo "  - $1" >&2; errors=$((errors + 1)); }
 
-# CBP folder form: .claude/agents/{name}/AGENT.md
+# Accept flat agents/{name}.md (spec default) or folder agents/{name}/AGENT.md (when bundling)
 case "$FILE" in
-  */AGENT.md) ;;
-  *) err "CBP expects folder form: .claude/agents/{name}/AGENT.md (got: $FILE)";;
+  */AGENT.md) ;;                # folder form (agent bundles supporting files)
+  */agents/*.md) ;;             # flat form — Claude Code spec default
+  *) err "expected a subagent markdown file under agents/ — flat agents/{name}.md or folder agents/{name}/AGENT.md (got: $FILE)";;
 esac
 
 # Frontmatter must be present

package/templates/skills/cbp-build-cc-mode/SKILL.md

@@ -1,7 +1,7 @@
 ---
 scope: org-shared
 name: cbp-build-cc-mode
-description: Audit + apply the CHK-109 model/effort matrix across every authoring skill and agent under `packages/codebyplan-package/templates/`. Bare invocation walks all SKILL.md and AGENT.md files and reports frontmatter gaps; with a path argument, edits the target file's frontmatter to the matrix-decided values.
+description: Audit + apply the CHK-109 model/effort matrix across every authoring skill and agent under `packages/codebyplan-package/templates/`. Bare invocation walks all SKILL.md and agent .md files and reports frontmatter gaps; with a path argument, edits the target file's frontmatter to the matrix-decided values.
 argument-hint: "[path-to-agent-or-skill]"
 allowed-tools: Read, Write, Edit, Glob, Grep
 effort: xhigh
@@ -23,7 +23,7 @@ Audit or apply the canonical `model:` + `effort:` frontmatter convention across
 
 `model: sonnet` + `effort: xhigh`
 
-Eleven of the 12 authoring agents take the default (`cbp-cc-executor`, `cbp-database-agent`, `cbp-improve-claude`, `cbp-improve-round`, `cbp-research`, `cbp-round-executor`, `cbp-security-agent`, `cbp-task-check`, `cbp-task-planner`, `cbp-test-e2e-agent`, `cbp-testing-qa-agent`). The 12th — `cbp-mechanical-edits` — is an explicit haiku-low exception (see below). 27 skills take the default: cbp-round-start, cbp-round-input, cbp-round-execute, cbp-task-create, cbp-task-start, cbp-task-complete, cbp-task-testing, cbp-checkpoint-create, cbp-checkpoint-check, cbp-checkpoint-end, cbp-build-cc-mode, cbp-build-cc-agent, cbp-build-cc-skill, cbp-build-cc-rule, cbp-build-cc-claude-file, cbp-build-cc-memory, cbp-build-cc-settings, cbp-frontend-a11y, cbp-frontend-design, cbp-frontend-ui, cbp-frontend-ux, cbp-session-end, cbp-ship, cbp-ship-configure, cbp-supabase-setup, cbp-supabase-migrate, cbp-supabase-branch-check.
+Fifteen of the 16 authoring agents take the default (`cbp-cc-executor`, `cbp-database-agent`, `cbp-improve-claude`, `cbp-improve-round`, `cbp-research`, `cbp-round-executor`, `cbp-security-agent`, `cbp-task-check`, `cbp-task-planner`, `cbp-testing-qa-agent`, `cbp-e2e-playwright`, `cbp-e2e-maestro`, `cbp-e2e-tauri`, `cbp-e2e-vscode`, `cbp-e2e-xcuitest`). The 16th — `cbp-mechanical-edits` — is an explicit haiku-low exception (see below). 27 skills take the default: cbp-round-start, cbp-round-input, cbp-round-execute, cbp-task-create, cbp-task-start, cbp-task-complete, cbp-task-testing, cbp-checkpoint-create, cbp-checkpoint-check, cbp-checkpoint-end, cbp-build-cc-mode, cbp-build-cc-agent, cbp-build-cc-skill, cbp-build-cc-rule, cbp-build-cc-claude-file, cbp-build-cc-memory, cbp-build-cc-settings, cbp-frontend-a11y, cbp-frontend-design, cbp-frontend-ui, cbp-frontend-ux, cbp-session-end, cbp-ship, cbp-ship-configure, cbp-supabase-setup, cbp-supabase-migrate, cbp-supabase-branch-check.
 
 ### Effort-lowered skills (5)
 
@@ -55,7 +55,7 @@ Eleven of the 12 authoring agents take the default (`cbp-cc-executor`, `cbp-data
 
 ### Haiku-low agents (1)
 
-`model: haiku` + `effort: low`. The 12th authoring agent — pure I/O mechanical work, never authors logic.
+`model: haiku` + `effort: low`. The 16th authoring agent — pure I/O mechanical work, never authors logic.
 
 | agent                | model | effort | reason                                                                              |
 | -------------------- | ----- | ------ | ----------------------------------------------------------------------------------- |
@@ -87,7 +87,7 @@ The audit is read-only — no edits performed.
 
 ## Apply Mode
 
-Invoked with a path argument (the target `SKILL.md` or `AGENT.md`). Procedure:
+Invoked with a path argument (the target `SKILL.md` or agent `.md`). Procedure:
 
 1. Read the file. Identify the skill or agent name from the `name:` frontmatter field (or from the path basename if `name:` is absent).
 2. Look up target `model` + `effort` from the matrix above.

package/templates/skills/cbp-checkpoint-check/SKILL.md

@@ -90,11 +90,9 @@ Re-run build/lint/types on current codebase to verify nothing regressed across t
 
 Aggregate the files touched across all tasks (reusing Step 4's deduplicated table) and run e2e once against the union of pages they affect.
 
-1. **Build `pages_affected`** — derive from Step 4's `files_changed` union using the same heuristic as `cbp-test-e2e-agent` Step 5.1 (Next.js: `app/<route>/page.tsx` chains; Expo: screen files; Tauri: route components; fallback: directory-based grouping). Deduplicate by route / screen.
+1. **Build `pages_affected`** — derive from Step 4's `files_changed` union using the same heuristic as `context/testing/e2e.md` Step 5.1 (Next.js: `app/<route>/page.tsx` chains; Expo: screen files; Tauri: route components; fallback: directory-based grouping). Deduplicate by route / screen.
 
-2. **Spawn `cbp-test-e2e-agent`** via the Agent tool with:
-
-   `test_strategy` is intentionally omitted — the agent auto-detects per-app via its Step 1.5 DB tech-stack lookup (`get_repos`) and Step 2 filesystem reconciliation. Mixed-framework monorepos disambiguate via `tech_stack.apps[]`; pre-pass `test_strategy` only when DB tech_stack is empty AND filesystem probe is ambiguous.
+2. **Config-driven dispatch** (per `context/testing/e2e.md` dispatch contract): read `.codebyplan/e2e.json`. If the file is absent or `frameworks` is empty, append `| Checkpoint E2E | n/a | no framework configured |` to the Step 5 QA Summary and continue to Step 6. Otherwise, for each entry where `enabled === true` AND `auto_run === true` whose `app` path intersects the aggregated `files_changed` union, spawn the matching `cbp-e2e-*` specialist via the Agent tool — one per eligible framework, in parallel. Inject `framework`, `app`, `platforms`, and `credential_vars` from `e2e.json` (authoritative; the agent does not auto-detect):
 
    ```yaml
    input:
@@ -105,18 +103,24 @@ Aggregate the files touched across all tasks (reusing Step 4's deduplicated tabl
      pages_affected: [aggregated]
      has_auth: [boolean, from .codebyplan/server.json + repo]
      dev_server_port: [from .codebyplan/server.json]
+     framework: [from e2e.json — authoritative]
+     app: [from e2e.json — e.g. apps/web]
+     platforms: [from e2e.json — e.g. ["web"]]
+     credential_vars: [from e2e.json — env var names only, never secrets]
    ```
 
-3. **Wait for completion.** The agent's output carries `whole_checkpoint_aggregated: true` confirming whole-checkpoint formatting.
+   Hold each specialist's output keyed by framework (an `e2e_outputs[framework]` map) for this skill's aggregation — checkpoint-check has no MCP round, so this lives in-memory during the run (persist to `checkpoint.context` via `update_checkpoint` at Step 7 if a durable record is needed). `test_strategy` is intentionally omitted — the agent resolves it from `.codebyplan/e2e.json` and the DB tech-stack record.
+
+3. **Wait for all specialists to complete.** Each agent's output carries `whole_checkpoint_aggregated: true` confirming whole-checkpoint formatting.
 
-4. **On pass** (`e2e_output.status === 'completed'` AND `e2e_output.test_results.failed === 0`): append a row to the Step 5 QA Summary table:
+4. **On pass** (every eligible framework `f`: `e2e_outputs[f].status === 'completed'` AND `e2e_outputs[f].test_results.failed === 0`): append a row to the Step 5 QA Summary table:
    ```
    | Checkpoint E2E | pass | aggregated |
    ```
    Continue to Step 6.
 
-5. **On fail** (`e2e_output.status === 'failed'` OR `e2e_output.test_results.failed > 0`): build a failure summary from `e2e_output.test_results.failures[]` grouped by `category`. Surface via `AskUserQuestion`:
-   - **(a) Create fix-task in CHK-{NNN} (recommended)** — invoke MCP `create_task` with `checkpoint_id=current_checkpoint_id`, `title="Fix checkpoint-level e2e failures (CHK-{NNN})"`, `requirements` containing the detailed failure breakdown (category counts, files involved, pages broken, screenshot paths from `e2e_output.screenshots[]`), AND `context: { source_checkpoint_id, e2e_failure_summary: { category_counts, pages_broken, screenshot_paths }, fix_type: "checkpoint_e2e" }` so downstream `cbp-task-planner` Phase 1.5 can verify failure premises programmatically without re-parsing the requirements text. Per `infra-issue-absorption.md` "Resolve-in-Current-Scope by Default", checkpoint-level e2e failures absorb into the active checkpoint — not standalone.
+5. **On fail** (any framework `f`: `e2e_outputs[f].status === 'failed'` OR `e2e_outputs[f].test_results.failed > 0`): build a failure summary from `e2e_outputs[*].test_results.failures[]` aggregated and grouped by `category`. Surface via `AskUserQuestion`:
+   - **(a) Create fix-task in CHK-{NNN} (recommended)** — invoke MCP `create_task` with `checkpoint_id=current_checkpoint_id`, `title="Fix checkpoint-level e2e failures (CHK-{NNN})"`, `requirements` containing the detailed failure breakdown (category counts, files involved, pages broken, screenshot paths from `e2e_outputs[*].screenshots[]`), AND `context: { source_checkpoint_id, e2e_failure_summary: { category_counts, pages_broken, screenshot_paths }, fix_type: "checkpoint_e2e" }` so downstream `cbp-task-planner` can verify failure premises. Per `infra-issue-absorption.md` "Resolve-in-Current-Scope by Default", checkpoint-level e2e failures absorb into the active checkpoint — not standalone.
    - **(b) Surface as warning only — proceed to checkpoint-end** — append `| Checkpoint E2E | warning | N failures (deferred) |` to Step 5 QA Summary; continue to Step 6.
    - **(c) Halt — review manually** — STOP and wait for the user.
 

package/templates/skills/cbp-checkpoint-plan/SKILL.md

@@ -63,7 +63,7 @@ Only relevant when an idea touches a UI surface AND you SUSPECT an existing flow
 
 1. Surface the suspicion: name the area + the specific pages/screens, and why you think it is broken.
 2. Ask the user via AskUserQuestion to confirm running the probe (it needs a running dev server).
-3. On confirm, spawn `cbp-test-e2e-agent` with `whole_checkpoint_mode: true`, `round_number: 0`, `files_changed: []`, the `pages_affected` you proposed, plus `repo_id` / `test_strategy` / `has_auth` / `dev_server_port`. Resolve `test_strategy` and `dev_server_port` per `reference/e2e-discovery-probe.md` (do not pass placeholder strings).
+3. On confirm, spawn the config-matched `cbp-e2e-*` specialist (for a web app, `cbp-e2e-playwright`) per the `context/testing/e2e.md` dispatch contract, with `whole_checkpoint_mode: true`, `round_number: 0`, `files_changed: []`, the `pages_affected` you proposed, plus `repo_id` / `test_strategy` / `has_auth` / `dev_server_port`. Resolve `test_strategy` and `dev_server_port` per `reference/e2e-discovery-probe.md` (do not pass placeholder strings).
 4. Record the probe outcome (what actually failed vs. what you assumed) in `context.discoveries[]` so the plan targets real defects.
 
 Skip this step entirely for non-UI checkpoints or when no breakage is suspected.
@@ -131,7 +131,7 @@ This skill does **NOT** activate the checkpoint and does **NOT** claim a user/wo
 
 - **Reads**: MCP `get_current_task`, `get_checkpoints`, `get_tasks`
 - **Writes**: MCP `update_checkpoint` (ideas assessment, context, plan, research), `create_task`
-- **Spawns**: `cbp-research` (level 2+ only), `cbp-test-e2e-agent` (opt-in discovery probe, `whole_checkpoint_mode`)
+- **Spawns**: `cbp-research` (level 2+ only), config-matched `cbp-e2e-*` specialist (opt-in discovery probe, `whole_checkpoint_mode` — see `context/testing/e2e.md` dispatch contract)
 - **Triggered by**: `/cbp-checkpoint-create` (auto), or user directly
 - **Triggers**: `/cbp-checkpoint-start` (auto when claimed at create; directive when left open)
 - **Never**: activates the checkpoint or claims a user/worktree — that is `/cbp-checkpoint-start`

package/templates/skills/cbp-checkpoint-plan/reference/e2e-discovery-probe.md

@@ -4,7 +4,7 @@ scope: org-shared
 
 # E2E Discovery Probe
 
-Loaded by `/cbp-checkpoint-plan` Step 4. The probe answers one question before you plan a fix: **is this area actually broken, and how?** It reuses `cbp-test-e2e-agent` (the sole owner of e2e execution) in `whole_checkpoint_mode` rather than introducing a second smoke-test path.
+Loaded by `/cbp-checkpoint-plan` Step 4. The probe answers one question before you plan a fix: **is this area actually broken, and how?** It reuses the config-matched `cbp-e2e-*` specialist (the framework owners of e2e execution) in `whole_checkpoint_mode` rather than introducing a second smoke-test path. See `context/testing/e2e.md` for the dispatch contract that selects which specialist to spawn.
 
 ## When to offer the probe
 
@@ -20,8 +20,8 @@ Skip silently for backend-only / infra / `claude_only` checkpoints, or when you
 1. **State the suspicion** — name the area, the specific pages/screens, and why you think it is broken (a stale selector, a route that 404s, a recent refactor nearby).
 2. **Confirm with the user** via AskUserQuestion — the probe needs a running dev server, so it is opt-in. Options: run the probe / skip and plan from assumption / let me name different pages.
 3. **Resolve the dev-server port** from `.codebyplan/server.json` `port_allocations[]` (pick the entry whose `server_type` matches the app, e.g. `nextjs`). If nothing is running there, ask the user to start it or skip.
-4. **Resolve `test_strategy`** — call MCP `get_repos()`, find the entry where `id === repo_id`, and read the affected app's platform + e2e framework from its `tech_stack` record. If the record has no e2e data, pass `null` for the unknown fields — the agent resolves them itself at its Step 1.5. Do NOT pass placeholder strings.
-5. **Spawn** `cbp-test-e2e-agent` with the payload below.
+4. **Resolve `test_strategy`** — call MCP `get_repos()`, find the entry where `id === repo_id`, and read the affected app's platform + e2e framework from its `tech_stack` record. If the record has no e2e data, pass `null` for the unknown fields — the agent resolves them itself. Do NOT pass placeholder strings.
+5. **Spawn** the config-matched `cbp-e2e-*` specialist per `context/testing/e2e.md` dispatch contract (e.g. `cbp-e2e-playwright` for a web app) with the payload below.
 6. **Interpret** the result: compare what actually failed against what you assumed. Record the delta in `context.discoveries[]` so the plan targets real defects, not imagined ones.
 
 ## Spawn payload (whole_checkpoint_mode)
@@ -52,6 +52,6 @@ The agent returns `test_results` (passed / failed / skipped + per-failure `categ
 - `category: 'env' | 'auth' | 'access' | 'flake'` → not the feature's fault; note it but do not plan a code fix around it.
 - A clean pass → your breakage suspicion was wrong; plan the actual requested change without a "fix" step you did not need.
 
-## Why reuse the agent (not a new smoke probe)
+## Why reuse the specialist agents (not a new smoke probe)
 
-`cbp-test-e2e-agent` is the declared sole owner of e2e: it auto-detects the platform, reconciles against the `tech_stack` DB record, configures the framework if missing, and classifies failures. A bespoke in-skill smoke check would duplicate that ownership and drift. The probe is a thin, opt-in caller of the existing agent.
+The `cbp-e2e-*` specialists are the declared framework owners of e2e: they configure the framework if missing, run preflight, and classify failures. A bespoke in-skill smoke check would duplicate that ownership and drift. The probe is a thin, opt-in caller of the matching existing agent (selected per `context/testing/e2e.md` dispatch contract).

package/templates/skills/cbp-e2e-setup/SKILL.md

@@ -0,0 +1,254 @@
+---
+scope: org-shared
+name: cbp-e2e-setup
+description: Detect installed E2E frameworks, ask which to enable, record credentials source (gitignored env-file path + var names only, never secrets), and write/refresh .codebyplan/e2e.json. Interactive, idempotent.
+argument-hint: "[--force]"
+model: sonnet
+effort: xhigh
+allowed-tools: Read, Write, Edit, Bash(cat *), Bash(jq *), Bash(which *), Bash(test *), Bash(mkdir *), Bash(cp *), Bash(echo *), Bash(date *), Bash(mv *), Bash(git check-ignore *), AskUserQuestion, mcp__codebyplan__get_repos
+---
+
+# E2E Setup
+
+Configure `.codebyplan/e2e.json` so the E2E test pipeline knows which frameworks are
+enabled, where each app lives, and where to read credentials at test time.
+
+Invoke at any time. Already-configured frameworks are preserved unless `--force` is passed.
+Pass `--force` to re-ask all questions including credentials blocks.
+
+## Arguments
+
+Inspect `$ARGUMENTS` for `--force`. If present, set `force_mode = true`.
+Absent: use idempotent mode — preserve existing credentials blocks, skip re-asking
+already-configured frameworks.
+
+## Step 1 — Detect installed frameworks
+
+Run both detection signals and merge:
+
+**Signal A — DB tech_stack** via `mcp__codebyplan__get_repos` (match `repo_id` from
+`.codebyplan/repo.json`). Scan `tech_stack[]` for: `playwright`, `maestro`, `xcuitest`,
+`webdriverio`, `@wdio/cli`, `@vscode/test-cli`.
+
+**Signal B — Filesystem probes:**
+
+```bash
+test -f playwright.config.ts  || test -f playwright.config.js  # → playwright
+test -f maestro/config.yaml   || test -d maestro               # → maestro
+test -d ios && find ios -name '*UITests' -maxdepth 2 | grep -q . # → xcuitest
+test -f wdio.conf.ts          || test -f wdio.conf.js          # → tauri (wdio)
+test -f .vscode-test.mjs      || test -d apps/vscode           # → vscode
+```
+
+**Signal C — Read existing `.codebyplan/e2e.json`** for idempotent merge:
+
+```bash
+cat .codebyplan/e2e.json 2>/dev/null || echo '{}'
+```
+
+A framework detected by A or B is "detected". A framework already in e2e.json is
+"configured". A framework with `enabled: false` in e2e.json is "configured-disabled".
+
+## Step 2 — Ask which to enable
+
+Display a summary table of detection results:
+
+```
+Framework   | Detected | Configured | Status
+----------- | -------- | ---------- | ------
+playwright  | yes      | yes        | enabled
+maestro     | no       | no         | absent
+xcuitest    | no       | no         | absent
+tauri       | no       | no         | absent
+vscode      | no       | no         | absent
+```
+
+AskUserQuestion (multi-select):
+
+```
+Which E2E frameworks should be enabled?
+Detected frameworks are pre-checked. Undetected ones can still be enabled.
+
+Select all that apply:
+A) playwright  (web — Next.js)
+B) maestro     (mobile — Expo/React Native)
+C) xcuitest    (iOS native — Apple Watch, HealthKit, system dialogs)
+D) tauri       (desktop — WebDriverIO + tauri-driver)
+E) vscode      (VS Code extension — @vscode/test-cli)
+```
+
+In `--force` mode: re-ask even for frameworks already enabled.
+Otherwise: frameworks already `enabled: true` in e2e.json are kept without asking.
+
+## Step 3 — Mobile platforms (conditional)
+
+If maestro or xcuitest is in the enabled set and the framework is not yet configured
+(or `--force`), AskUserQuestion:
+
+```
+Mobile platform target for <framework>:
+A) Android only
+B) iOS only
+C) Both Android and iOS
+```
+
+Record the answer as `platforms: ["android"]`, `["ios"]`, or `["android", "ios"]` on the
+framework config block.
+
+## Step 4 — Credentials source
+
+For each enabled framework that touches auth (playwright, maestro, xcuitest):
+
+**Idempotency gate** (skip if `--force` is absent AND
+`credentials.frameworks[framework].email_var` AND
+`credentials.frameworks[framework].password_var` are both set to non-empty strings —
+an empty `{}` entry counts as unconfigured, so prompt for it):
+
+```
+Credentials block for <framework> already configured — use --force to reset.
+  env_file: <path>
+  email_var: <var>
+  password_var: <var>
+```
+
+Print the preserved values and continue to Step 5.
+
+**Otherwise**, AskUserQuestion (one question per framework, step-by-step):
+
+```
+Credentials source for <framework>
+
+1. Gitignored env-file path that holds the secrets
+   (default: .codebyplan/e2e.env — a dedicated file, separate from app .env.local)
+   Path: ___
+
+2. Email env var name (default: E2E_TEST_EMAIL for playwright, TEST_EMAIL for others)
+   Var name: ___
+
+3. Password env var name (default: E2E_TEST_PASSWORD for playwright, TEST_PASSWORD for others)
+   Var name: ___
+
+4. (Optional) Provision script path — the skill only records the path, never creates it
+   (convention: scripts/provision-e2e-user.ts — leave blank to skip)
+   Path: ___
+```
+
+After collecting the env-file path, verify it is gitignored and capture the result —
+this boolean is persisted as the required `credentials.gitignored` field:
+
+```bash
+git check-ignore -q <env_file_path> && GITIGNORED=true || GITIGNORED=false
+```
+
+If NOT ignored (`GITIGNORED=false`): warn and offer to append it:
+
+```
+Warning: <path> is not in .gitignore.
+This file will contain live credentials — committing it is a credential leak.
+Append <path> to .gitignore? (Y/n)
+```
+
+On yes: append the path to `.gitignore` and set `GITIGNORED=true`. On no: leave
+`GITIGNORED=false` and record in the output but do not block.
+
+Carry `gitignored: $GITIGNORED` into the credentials block assembled for Step 5 — the
+`E2eCredentials.gitignored` field is required, so it must always be populated.
+
+Never write secret values into e2e.json — only the path, var names, and provision_script
+reference are persisted.
+
+## Step 5 — Write .codebyplan/e2e.json
+
+Build the updated payload conforming to the `E2eConfig` schema
+(`packages/codebyplan-package/src/lib/types.ts`).
+
+For playwright, derive `base_url` from `.codebyplan/server.json`:
+
+```bash
+jq -r '.port_allocations[] | select(.label == "Web Dev") | "http://localhost:\(.port)"' \
+  .codebyplan/server.json | head -1
+```
+
+Match by the `Web Dev` label rather than `server_type == "nextjs"` — a repo can have
+several `nextjs` allocations (e.g. one per sibling worktree), so array-position
+`head -1` is not stable. Confirm the derived URL with the user before writing
+(`Derived base_url: <url> — correct? (Y/n)`) and allow an override. Store as
+`frameworks.playwright.base_url`.
+
+Idempotency rule: the jq object-merge (`. + {...}`) REPLACES top-level keys, so build
+`$CREDENTIALS_JSON` as a deep-merge of the existing block and the newly-collected data
+BEFORE the write — otherwise a second run for an additional framework would clobber the
+first framework's credentials. Assemble it in the shell:
+
+```bash
+EXISTING_CREDS=$(jq -c '.credentials // {}' .codebyplan/e2e.json)
+CREDENTIALS_JSON=$(echo "$EXISTING_CREDS" | jq -c --argjson new "$NEW_CREDS_JSON" '. * $new')
+```
+
+The `*` operator deep-merges, so frameworks skipped by the idempotency gate keep their
+prior entry. Then write atomically using jq temp+mv to avoid partial writes (only the two
+schema fields `frameworks` and `credentials` are written — `E2eConfig` defines no other):
+
+```bash
+jq --argjson frameworks "$FRAMEWORKS_JSON" \
+   --argjson credentials "$CREDENTIALS_JSON" \
+   '. + {frameworks: $frameworks, credentials: $credentials}' \
+   .codebyplan/e2e.json > .codebyplan/e2e.json.tmp \
+   && mv .codebyplan/e2e.json.tmp .codebyplan/e2e.json
+```
+
+Framework config shape per framework:
+
+| Field        | playwright          | maestro / xcuitest   | tauri / vscode |
+| ------------ | ------------------- | -------------------- | -------------- |
+| `enabled`    | true                | true                 | true           |
+| `app`        | `apps/web` (nextjs) | `apps/<expo-app>`    | `apps/desktop` / `apps/vscode` |
+| `config_path`| `playwright.config.ts` | `maestro/config.yaml` | `wdio.conf.ts` / `.vscode-test.mjs` |
+| `auto_run`   | false               | false                | false          |
+| `test_dir`   | `apps/web/e2e`      | —                    | —              |
+| `base_url`   | from server.json    | —                    | —              |
+| `platforms`  | —                   | from Step 3          | —              |
+
+Disabled frameworks get `enabled: false`; all other fields are preserved from their
+prior configured state.
+
+## Step 6 — Verify and report
+
+Re-read `.codebyplan/e2e.json` and emit a per-framework summary:
+
+```
+E2E Setup — Complete
+
+Framework   | Status   | App        | base_url / platforms  | Creds source
+----------- | -------- | ---------- | --------------------- | ------------
+playwright  | enabled  | apps/web   | http://localhost:3010 | .codebyplan/e2e.env (E2E_TEST_EMAIL)
+maestro     | disabled | —          | —                     | —
+...
+
+e2e.json written to .codebyplan/e2e.json
+
+Next steps per framework — see reference docs:
+  playwright  → reference/playwright.md
+  maestro     → reference/maestro.md
+  xcuitest    → reference/xcuitest.md
+  tauri       → reference/tauri.md
+  vscode      → reference/vscode.md
+```
+
+## Key Rules
+
+- Never write secret values into e2e.json — only env-file path + var names
+- Gitignore guard runs before any credentials are persisted
+- Preserved credentials blocks are printed verbatim so the user can verify them
+- Atomic write (tmp + mv) — never leaves e2e.json in a partial state
+- `auto_run: false` by default — the user opts in explicitly
+
+## Additional resources
+
+- Playwright install + auth + CI: [reference/playwright.md](reference/playwright.md)
+- Maestro install + flows + CI: [reference/maestro.md](reference/maestro.md)
+- Tauri (WebDriverIO): [reference/tauri.md](reference/tauri.md)
+- VS Code extension testing: [reference/vscode.md](reference/vscode.md)
+- XCUITest (iOS native): [reference/xcuitest.md](reference/xcuitest.md)
+- E2E schema types: `packages/codebyplan-package/src/lib/types.ts` (E2eConfig)
+- Shared E2E conventions: `.claude/context/testing/e2e.md`