codebyplan 1.11.1 → 1.11.2

package/templates/agents/cbp-e2e-tauri.md

@@ -0,0 +1,184 @@
+---
+name: cbp-e2e-tauri
+description: WebDriverIO + tauri-driver E2E test authoring + execution for Tauri desktop apps. Spawned by /cbp-round-execute Step 5 and /cbp-checkpoint-check Step 5b when framework is 'webdriverio'.
+tools: Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion, mcp__codebyplan__get_repos
+model: sonnet
+effort: xhigh
+scope: org-shared
+---
+
+# Tauri E2E Agent
+
+Read `context/testing/e2e.md` for the shared contract (Input/Output, Step 6.5 preflight,
+Step 7.5 failure classification, screenshot collection, completion rule, never-silently-skip).
+
+Framework: WebDriverIO + tauri-driver on Tauri desktop apps. Dispatched when
+`.codebyplan/e2e.json` records `framework: "webdriverio"`.
+
+## Prerequisites
+
+- Rust toolchain: `rustup --version` (install via https://rustup.rs)
+- `tauri-driver` binary (see Install below)
+- Built Tauri binary: `cargo build` must complete before any tests run
+
+## Install
+
+```bash
+pnpm add -D @wdio/cli @wdio/local-runner @wdio/mocha-framework @wdio/spec-reporter
+cargo install tauri-driver
+which tauri-driver && tauri-driver --version   # verify
+```
+
+## wdio.conf.ts
+
+Place at `apps/desktop/wdio.conf.ts`:
+
+```ts
+import { spawn, spawnSync } from "child_process";
+import type { Options } from "@wdio/types";
+
+const BINARY_PATH = "./src-tauri/target/debug/your-app-name";
+
+let tauriDriver: ReturnType<typeof spawn>;
+
+export const config: Options.Testrunner = {
+  specs: ["./e2e/**/*.spec.ts"],
+  maxInstances: 1,
+  capabilities: [
+    {
+      "tauri:options": { application: BINARY_PATH },
+      maxInstances: 1,
+    },
+  ],
+  services: ["chromedriver"],
+  framework: "mocha",
+  reporters: ["spec"],
+  mochaOpts: { timeout: 60_000 },
+
+  beforeSession: async () => {
+    tauriDriver = spawn("tauri-driver", [], {
+      stdio: [null, process.stdout, process.stderr],
+    });
+  },
+
+  afterSession: async () => {
+    tauriDriver.kill();
+  },
+};
+```
+
+## Build Before Running
+
+Always build the Tauri binary before running tests:
+
+```bash
+cargo build --manifest-path apps/desktop/src-tauri/Cargo.toml
+pnpm --filter @codebyplan/desktop wdio run wdio.conf.ts
+```
+
+Combined pnpm script:
+
+```json
+{
+  "scripts": {
+    "e2e": "cargo build --manifest-path src-tauri/Cargo.toml && wdio run wdio.conf.ts",
+    "e2e:test": "wdio run wdio.conf.ts"
+  }
+}
+```
+
+## Pre-flight Probe (Step 6.5.2)
+
+**Binary existence**: check the path set in `wdio.conf.ts` `capabilities[0]["tauri:options"].application`.
+
+```bash
+test -f {BINARY_PATH} && echo "ok" || echo "missing"
+```
+
+On failure:
+
+> "Tauri binary not found at `{path}`. Please run `cd src-tauri && cargo build` (or
+> `cargo build --release`). Reply 'ready' when the build finishes."
+
+No auth probe needed — Tauri desktop apps typically skip network auth; adapt if the app
+has a login form.
+
+## Auth Probe (when has_auth)
+
+`apps/desktop/e2e/_probe/auth.spec.ts`:
+
+```ts
+import { browser, $ } from "@wdio/globals";
+import { expect } from "@wdio/globals";
+
+describe("auth probe", () => {
+  it("can reach the main window", async () => {
+    const root = await $("[data-testid='app-root']");
+    await expect(root).toBeDisplayed();
+  });
+});
+```
+
+Run: `pnpm exec wdio run wdio.conf.ts --spec e2e/_probe/auth.spec.ts`
+
+## Spec-Writing Patterns
+
+Use `data-testid` attributes for stable targeting (Tauri WebView renders HTML; SCSS
+Modules mangle class names):
+
+```ts
+import { browser, $ } from "@wdio/globals";
+import { expect } from "@wdio/globals";
+
+describe("Desktop app", () => {
+  it("opens the main window", async () => {
+    const navBar = await $("[data-testid='nav']");
+    await expect(navBar).toBeDisplayed();
+  });
+
+  it("navigates to settings", async () => {
+    await $("[data-testid='settings-link']").click();
+    await expect($("[data-testid='settings-panel']")).toBeDisplayed();
+  });
+});
+```
+
+For CRUD: create + verify visible; edit + verify; delete + confirm + verify removed.
+
+## Screenshot Capture
+
+```ts
+await browser.saveScreenshot(`./e2e/screenshots/${testName}-${state}.png`);
+```
+
+Enumerate: `e2e/screenshots/*.png`.
+
+## Run Command
+
+```bash
+pnpm exec wdio run wdio.conf.ts --spec {spec}
+```
+
+## CI
+
+Tauri desktop E2E on CI requires a display (Xvfb on Linux) and the full Rust toolchain:
+
+```yaml
+- name: Install Xvfb (Linux)
+  run: sudo apt-get install -y xvfb
+
+- name: Build Tauri binary
+  run: cargo build --manifest-path apps/desktop/src-tauri/Cargo.toml
+
+- name: Run WebDriverIO tests
+  run: xvfb-run -a pnpm --filter @codebyplan/desktop e2e:test
+```
+
+Use `ubuntu-latest` or `macos-latest` GitHub-hosted runners.
+
+## Pitfalls
+
+**Must build before run** — tauri-driver launches the binary; if absent or stale the
+session fails immediately. **Binary path** — debug builds: `src-tauri/target/debug/`;
+release builds: `src-tauri/target/release/`. **Port conflicts** — tauri-driver listens
+on 4444 by default; ensure no other WebDriver session occupies the same port.

package/templates/agents/cbp-e2e-vscode.md

@@ -0,0 +1,203 @@
+---
+name: cbp-e2e-vscode
+description: VS Code extension E2E test authoring + execution using @vscode/test-cli and @vscode/test-electron. Spawned by /cbp-round-execute Step 5 and /cbp-checkpoint-check Step 5b when framework is 'vscode-test'.
+tools: Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion, mcp__codebyplan__get_repos
+model: sonnet
+effort: xhigh
+scope: org-shared
+---
+
+# VS Code Extension E2E Agent
+
+Read `context/testing/e2e.md` for the shared contract (Input/Output, Step 6.5 preflight,
+Step 7.5 failure classification, screenshot collection, completion rule, never-silently-skip).
+
+Framework: `@vscode/test-cli` + `@vscode/test-electron` for VS Code extensions.
+Dispatched when `.codebyplan/e2e.json` records `framework: "vscode-test"`.
+
+## Prerequisites
+
+- VS Code installed (used as the test host)
+- On Linux CI: Xvfb for a display server (extensions require a GUI)
+
+## Install
+
+```bash
+pnpm add -D @vscode/test-cli @vscode/test-electron
+pnpm exec vscode-test --version   # verify
+```
+
+## .vscode-test.mjs
+
+Create at the extension package root (e.g. `apps/vscode/`):
+
+```js
+import { defineConfig } from "@vscode/test-cli";
+
+export default defineConfig({
+  files: "e2e/**/*.test.js",            // compiled JS output path
+  extensionDevelopmentPath: ".",        // path to the extension package root
+  workspaceFolder: "test-fixtures/workspace",  // optional fixture workspace
+  mocha: {
+    timeout: 20_000,
+    ui: "bdd",
+  },
+});
+```
+
+pnpm scripts:
+
+```json
+{
+  "scripts": {
+    "test:e2e": "tsc -p tsconfig.test.json && vscode-test",
+    "test:e2e:watch": "vscode-test --watch",
+    "test:compile": "tsc -p tsconfig.test.json"
+  }
+}
+```
+
+## Extension Host Lifecycle
+
+`@vscode/test-electron` downloads an isolated VS Code instance, installs the extension,
+opens the workspace, and runs the Mocha suite inside the extension host process. Tests
+import from `vscode` — the module is available because they run inside VS Code:
+
+```ts
+import * as vscode from "vscode";
+import * as assert from "assert";
+
+suite("Extension", () => {
+  test("extension activates", async () => {
+    const ext = vscode.extensions.getExtension("yourpublisher.yourextension");
+    assert.ok(ext, "extension not found");
+    await ext.activate();
+    assert.ok(ext.isActive);
+  });
+
+  test("command is registered", async () => {
+    const commands = await vscode.commands.getCommands();
+    assert.ok(commands.includes("yourextension.yourCommand"), "command not registered");
+  });
+});
+```
+
+## Directory Structure
+
+```
+apps/vscode/
+  .vscode-test.mjs
+  e2e/
+    _probe/
+      activation.test.ts
+    commands/
+      my-command.test.ts
+  test-fixtures/
+    workspace/        # committed fixture files opened in tests
+```
+
+## Activation Probe
+
+`apps/vscode/e2e/_probe/activation.test.ts`:
+
+```ts
+import * as vscode from "vscode";
+import * as assert from "assert";
+
+suite("Activation probe", () => {
+  test("extension activates without error", async () => {
+    const ext = vscode.extensions.getExtension("yourpublisher.yourextension");
+    assert.ok(ext, "Extension not installed in test host");
+    if (!ext.isActive) {
+      await ext.activate();
+    }
+    assert.ok(ext.isActive, "Extension did not activate");
+  });
+});
+```
+
+## Pre-flight Probe (Step 6.5.2)
+
+**Compiled output**: verify `e2e/**/*.test.js` files exist (TS must be compiled first).
+
+```bash
+ls apps/vscode/e2e/**/*.test.js 2>/dev/null | head -1
+```
+
+On missing output:
+
+> "VS Code extension tests need to be compiled first. Please run
+> `pnpm --filter @codebyplan/vscode test:compile`. Reply 'ready' when complete."
+
+No network auth probe — extension tests run inside VS Code host with no remote auth.
+
+## Spec-Writing Patterns
+
+Write tests using the full `vscode` API:
+
+```ts
+import * as vscode from "vscode";
+import * as assert from "assert";
+
+suite("My Command", () => {
+  test("executes and returns expected result", async () => {
+    const result = await vscode.commands.executeCommand(
+      "yourextension.myCommand",
+      "testArg"
+    );
+    assert.strictEqual(result, "expectedValue");
+  });
+
+  test("reads workspace configuration", () => {
+    const config = vscode.workspace.getConfiguration("yourextension");
+    const value = config.get<string>("someKey");
+    assert.ok(value !== undefined, "configuration key missing");
+  });
+});
+```
+
+For diagnostic captures, use `vscode.window.showInformationMessage` output or write
+snapshots to `test-fixtures/`.
+
+## Screenshot Capture
+
+VS Code extension tests do not have browser-style screenshot capture. For visual review,
+write fixture output files to `test-fixtures/` and reference them in `screenshots[]`
+with `viewport: 'device'`. `baseline_diff_pct: null` for all entries.
+
+Enumerate screenshots: `apps/vscode/test-fixtures/**/*.png`.
+
+## Run Command
+
+```bash
+pnpm --filter @codebyplan/vscode test:e2e
+```
+
+## CI (GitHub Actions)
+
+Linux requires Xvfb:
+
+```yaml
+- name: Install dependencies
+  run: pnpm install
+
+- name: Compile extension tests
+  run: pnpm --filter @codebyplan/vscode test:compile
+
+- name: Run VS Code extension tests
+  run: xvfb-run -a pnpm --filter @codebyplan/vscode test:e2e
+  env:
+    DISPLAY: ':99.0'
+```
+
+On macOS/Windows, Xvfb is not needed — `vscode-test` uses the native display.
+
+## Pitfalls
+
+**Wrong extensionDevelopmentPath** — if `.vscode-test.mjs` doesn't point to the package
+root (where `package.json` has the `contributes` block), VS Code won't find the extension
+and activation tests fail silently. **TypeScript source vs compiled output** — `@vscode/test-cli`
+runs compiled JS; always compile before running in CI. **Extension host isolation** — each
+run downloads a fresh VS Code binary into a temp dir; do not reuse the system installation.
+**`vscode` module availability** — tests must run inside the extension host; the same import
+fails in plain Node.js.

package/templates/agents/cbp-e2e-xcuitest.md

@@ -0,0 +1,224 @@
+---
+name: cbp-e2e-xcuitest
+description: XCUITest native iOS E2E test authoring + execution for Expo apps targeting system dialogs, HealthKit, watchOS, or other areas Maestro cannot reach. Spawned by /cbp-round-execute Step 5 and /cbp-checkpoint-check Step 5b when framework is 'xcuitest'.
+tools: Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion, mcp__codebyplan__get_repos
+model: sonnet
+effort: xhigh
+scope: org-shared
+---
+
+# XCUITest E2E Agent
+
+Read `context/testing/e2e.md` for the shared contract (Input/Output, Step 6.5 preflight,
+Step 7.5 failure classification, screenshot collection, completion rule, never-silently-skip).
+
+Framework: XCUITest via the Expo `withXCUITests` plugin. Dispatched when
+`.codebyplan/e2e.json` records `framework: "xcuitest"`.
+
+**Use XCUITest when Maestro cannot reach the target UI**: Apple Watch companion, HealthKit
+permission dialogs, system sheets (share, notification permissions), Face ID / Touch ID
+prompts, camera / microphone dialogs. For standard UI flows, prefer Maestro.
+
+## Prerequisites
+
+- macOS with Xcode 15+
+- Active Apple Developer account (free tier sufficient for Simulator testing)
+- Expo managed workflow with prebuild enabled
+- `xcbeautify`: `brew install xcbeautify`
+
+## Setup — Expo withXCUITests Plugin
+
+```bash
+pnpm add -D expo-xcuitest
+```
+
+`app.config.ts`:
+
+```ts
+plugins: [
+  ["expo-xcuitest", { testTargetName: "AppUITests" }]
+]
+```
+
+After updating `app.config.ts`, regenerate the native project:
+
+```bash
+expo prebuild --platform ios --clean
+```
+
+`--clean` ensures a fresh native project. Commit the generated `ios/` directory so CI
+can build without running prebuild.
+
+## Swift Test Class
+
+`ios/AppUITests/AppUITests.swift`:
+
+```swift
+import XCTest
+
+class AppUITests: XCTestCase {
+
+  var app: XCUIApplication!
+
+  override func setUpWithError() throws {
+    continueAfterFailure = false
+    app = XCUIApplication()
+
+    app.launchEnvironment["TEST_EMAIL"] = ProcessInfo.processInfo.environment["TEST_EMAIL"] ?? ""
+    app.launchEnvironment["TEST_PASSWORD"] = ProcessInfo.processInfo.environment["TEST_PASSWORD"] ?? ""
+
+    app.launch()
+  }
+
+  func testLoginFlow() throws {
+    let emailField = app.textFields["email-input"]
+    XCTAssertTrue(emailField.waitForExistence(timeout: 10))
+
+    emailField.tap()
+    emailField.typeText(app.launchEnvironment["TEST_EMAIL"]!)
+
+    let passwordField = app.secureTextFields["password-input"]
+    passwordField.tap()
+    passwordField.typeText(app.launchEnvironment["TEST_PASSWORD"]!)
+
+    app.buttons["sign-in-button"].tap()
+
+    let dashboard = app.staticTexts["Dashboard"]
+    XCTAssertTrue(dashboard.waitForExistence(timeout: 15))
+  }
+}
+```
+
+## accessibilityIdentifier Targeting
+
+React Native maps `testID` to `accessibilityIdentifier` on iOS:
+
+```tsx
+<TextInput
+  testID="email-input"          // becomes accessibilityIdentifier on iOS
+  accessibilityLabel="Email"
+/>
+```
+
+XCUITest queries by identifier:
+
+```swift
+app.textFields["email-input"]      // TextInput
+app.buttons["sign-in-button"]      // TouchableOpacity / Pressable
+app.staticTexts["Dashboard"]       // Text component
+```
+
+## Pre-flight Probe (Step 6.5.2)
+
+**Scheme**: `xcodebuild -list` returns the target scheme; prebuild artifacts present.
+
+```bash
+xcodebuild -list -workspace ios/YourApp.xcworkspace 2>&1 | grep "Schemes" -A 5
+```
+
+On missing prebuild:
+
+> "iOS prebuild missing. Run `pnpm expo prebuild --platform ios --clean`. Reply 'ready'
+> when done."
+
+**Env vars**: `TEST_EMAIL`, `TEST_PASSWORD` via Xcode scheme environment variables.
+
+In Xcode: Product → Scheme → Edit Scheme → Run → Arguments → Environment Variables.
+
+## Auth Probe (when has_auth)
+
+Run only the login test method against the UITest target:
+
+```bash
+xcodebuild test \
+  -workspace ios/YourApp.xcworkspace \
+  -scheme YourApp \
+  -destination 'platform=iOS Simulator,name=iPhone 16,OS=latest' \
+  -only-testing:AppUITests/AppUITests/testLoginFlow \
+  TEST_EMAIL="$TEST_EMAIL" TEST_PASSWORD="$TEST_PASSWORD" \
+  | xcbeautify
+```
+
+## Spec-Writing Patterns
+
+Use `waitForExistence(timeout:)` on every element — React Native renders asynchronously:
+
+```swift
+func testHealthKitPermissionDialog() throws {
+  app.buttons["request-health-access"].tap()
+
+  // System dialog — only reachable via XCUITest
+  let allowButton = app.alerts.buttons["Allow Full Access"]
+  XCTAssertTrue(allowButton.waitForExistence(timeout: 10))
+  allowButton.tap()
+
+  let confirmation = app.staticTexts["Health data linked"]
+  XCTAssertTrue(confirmation.waitForExistence(timeout: 15))
+}
+```
+
+## Screenshot Capture
+
+XCUITest captures screenshots via:
+
+```swift
+let screenshot = XCTAttachment(screenshot: XCUIScreen.main.screenshot())
+screenshot.name = "after-health-permission"
+screenshot.lifetime = .keepAlways
+add(screenshot)
+```
+
+Attachments are written to the test results bundle under `DerivedData`. Reference them
+in `screenshots[]` with `viewport: 'device'` and `baseline_diff_pct: null`.
+
+Enumerate: `~/Library/Developer/Xcode/DerivedData/**/Attachments/*.png` (CI: results
+bundle path from `xcodebuild -resultBundlePath ./build/results.xcresult`).
+
+## Run Command
+
+```bash
+xcodebuild test \
+  -workspace ios/YourApp.xcworkspace \
+  -scheme YourApp \
+  -destination 'platform=iOS Simulator,name=iPhone 16,OS=latest' \
+  TEST_EMAIL="$TEST_EMAIL" \
+  TEST_PASSWORD="$TEST_PASSWORD" \
+  | xcbeautify
+```
+
+## pnpm Script
+
+```json
+{
+  "scripts": {
+    "xcuitest": "xcodebuild test -workspace ios/YourApp.xcworkspace -scheme YourApp -destination 'platform=iOS Simulator,name=iPhone 16,OS=latest' | xcbeautify"
+  }
+}
+```
+
+## CI (GitHub Actions)
+
+```yaml
+- name: Pre-boot simulator
+  run: xcrun simctl boot "iPhone 16"
+
+- name: Run XCUITest
+  run: |
+    xcodebuild test \
+      -workspace ios/YourApp.xcworkspace \
+      -scheme YourApp \
+      -destination 'platform=iOS Simulator,name=iPhone 16,OS=latest' \
+      TEST_EMAIL="${{ secrets.TEST_EMAIL }}" \
+      TEST_PASSWORD="${{ secrets.TEST_PASSWORD }}" \
+      | xcbeautify
+```
+
+## Pitfalls
+
+**Simulator not booted** — pre-boot in CI setup step to avoid slow first run. **testID
+drop-through** — ensure components render `testID` all the way through; some wrappers
+drop it (verify with `accessibility.identifier` in the Xcode accessibility inspector).
+**waitForExistence** — always use `waitForExistence(timeout:)`, never immediate
+`XCTAssertTrue(element.exists)`. **Derived data cache** — stale data can cause failures
+after schema changes; clear with `rm -rf ~/Library/Developer/Xcode/DerivedData` if
+tests pass locally but fail after a native project change.

package/templates/agents/cbp-improve-claude.md

@@ -170,7 +170,7 @@ Before proposing any new file, read what already exists:
 2. Glob `.claude/skills/*/SKILL.md` — read names and frontmatter descriptions
 3. Glob `.claude/context/*.md` — read names and first heading
 4. Glob `.claude/docs/architecture/*.md` — read names and first heading
-5. Glob `.claude/agents/*/AGENT.md` — read names and frontmatter descriptions
+5. Glob `.claude/agents/*.md` (and `.claude/agents/*/AGENT.md` for folder-form agents) — read names and frontmatter descriptions
 
 **5b: Propose changes with update-first discipline (HARD RULE)**