codebyplan 1.11.1 → 1.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codebyplan",
-  "version": "1.11.1",
+  "version": "1.12.0",
   "description": "CLI for CodeByPlan — AI-powered development planning and tracking",
   "type": "module",
   "bin": {

package/templates/README.md

@@ -11,7 +11,7 @@ This directory holds the installed content that the `codebyplan claude install`
 | Path      | Count                                | Shape                                                                                           |
 | --------- | ------------------------------------ | ----------------------------------------------------------------------------------------------- |
 | `skills/` | 41 folders                           | each is a `SKILL.md` plus optional `templates/`, `reference/`, `examples/`, `scripts/` siblings |
-| `agents/` | 12 files                             | flat `.md` agent prompts (NOT `AGENT.md` subdirs)                                               |
+| `agents/` | 16 files                             | flat `.md` agent prompts (NOT `AGENT.md` subdirs)                                               |
 | `hooks/`  | 20 `.sh` + `hooks.json` + `README.md` | event hooks and manifest                                                                        |
 | `rules/`  | 1+ files                             | flat `<name>.md` rule files; see `rules/README.md` for bar and format                           |
 

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

@@ -82,7 +82,7 @@ Before processing any change, build a fresh inventory:
 
 1. Glob `.claude/rules/*.md` — read name + frontmatter
 2. Glob `.claude/skills/*/SKILL.md` — read name + description
-3. Glob `.claude/agents/*/AGENT.md` — read name + description
+3. Glob `.claude/agents/*.md` (and `.claude/agents/*/AGENT.md` for folder-form agents) — read name + description
 4. Glob `.claude/context/**/*.md` — read path + first heading
 5. Glob `.claude/docs/architecture/*.md` — read path + first heading
 6. Glob `.claude/hooks/*.sh` — read path + header block

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

@@ -0,0 +1,202 @@
+---
+name: cbp-e2e-maestro
+description: Maestro E2E flow authoring + execution for Expo/React Native mobile apps (android + ios). Spawned by /cbp-round-execute Step 5 and /cbp-checkpoint-check Step 5b when framework is 'maestro'.
+tools: Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion, mcp__codebyplan__get_repos
+model: sonnet
+effort: xhigh
+scope: org-shared
+---
+
+# Maestro 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: Maestro on Expo / React Native. Dispatched when `.codebyplan/e2e.json`
+records `framework: "maestro"`.
+
+## Prerequisites
+
+- Java 17+: `java -version` (install via `brew install openjdk@17` on macOS)
+- Android emulator OR iOS Simulator
+- Expo app bundled and running on target device/emulator
+
+## Install
+
+```bash
+# macOS
+curl -fsSL "https://get.maestro.mobile.dev" | bash
+# or: brew tap mobile-dev-inc/tap && brew install maestro
+maestro --version   # verify
+```
+
+## maestro/config.yaml
+
+```yaml
+appId: com.yourorg.yourapp   # must match app.config.ts ios.bundleIdentifier / android.package
+env:
+  TEST_EMAIL: ${TEST_EMAIL}
+  TEST_PASSWORD: ${TEST_PASSWORD}
+  APP_ID: com.yourorg.yourapp
+screenshotsDir: maestro/screenshots
+```
+
+## Shared Login Flow
+
+`maestro/flows/_shared/login.yaml`:
+
+```yaml
+appId: ${APP_ID}
+---
+- launchApp:
+    clearState: true
+- assertVisible: "Sign in"
+- tapOn: "Email"
+- inputText: ${TEST_EMAIL}
+- tapOn: "Password"
+- inputText: ${TEST_PASSWORD}
+- tapOn: "Sign in"
+- assertVisible:
+    text: ".*"        # Replace with a post-login element (e.g. "Dashboard")
+    timeout: 15000
+```
+
+Reference from other flows: `- runFlow: _shared/login.yaml`
+
+## Auth Probe
+
+`maestro/flows/_probe/auth.yaml`:
+
+```yaml
+appId: ${APP_ID}
+tags:
+  - probe
+---
+- launchApp:
+    clearState: true
+- assertVisible: "Sign in"
+- tapOn: "Email"
+- inputText: ${TEST_EMAIL}
+- tapOn: "Password"
+- inputText: ${TEST_PASSWORD}
+- tapOn: "Sign in"
+- assertVisible:
+    text: ".*"
+    timeout: 15000
+```
+
+Run probe: `maestro test maestro/flows/_probe/auth.yaml`
+
+## Pre-flight Probes (Step 6.5.2)
+
+**iOS**: `xcrun simctl list devices booted | grep -q Booted`
+
+> "No iOS Simulator is booted. Open Simulator.app or run `xcrun simctl boot 'iPhone 15'`.
+> Reply 'ready' when the simulator home screen is visible."
+
+**Android**: `adb devices | grep -w device`
+
+> "No Android device/emulator connected. Start an emulator from Android Studio or run
+> `emulator -avd {name}`. Reply 'ready' when unlocked."
+
+## Platform Targeting
+
+```bash
+# iOS
+maestro --platform=ios test maestro/flows/
+
+# Android
+maestro --platform=android test maestro/flows/
+
+# Specific device
+maestro test --device <device-id> maestro/flows/
+```
+
+## Directory Structure
+
+```
+maestro/
+  config.yaml
+  flows/
+    _shared/
+      login.yaml
+      open-side-menu.yaml
+    _probe/
+      auth.yaml
+    onboarding/
+      signup.yaml
+    home/
+      dashboard.yaml
+```
+
+One subdirectory per app module. Shared flows under `_shared/`. Probe under `_probe/`.
+
+## Spec-Writing Patterns
+
+**One flow per screen/feature.** Steps:
+
+```yaml
+appId: ${APP_ID}
+tags:
+  - home
+---
+- runFlow: _shared/login.yaml
+- assertVisible: "Dashboard"
+- takeScreenshot: "dashboard-loaded"
+- tapOn: "Create"
+- assertVisible: "New item"
+- takeScreenshot: "create-modal-open"
+```
+
+Use text-based targeting first (`tapOn: "Button"`); use testID when ambiguous
+(`tapOn: { id: "btn" }`). For CRUD: create + verify visible; edit + verify updated;
+delete + confirm + verify removed.
+
+## Screenshot Capture
+
+```yaml
+- takeScreenshot: "flow-name-after-state"
+```
+
+Screenshots written to `maestro/screenshots/` (via `screenshotsDir` in `config.yaml`).
+Enumerate: `maestro/screenshots/*.png`.
+
+## Run Command
+
+```bash
+maestro test maestro/flows/{module}/{flow}.yaml --format=junit --output maestro/results.xml
+```
+
+## pnpm Scripts
+
+```json
+{
+  "scripts": {
+    "maestro:test": "maestro test maestro/flows/",
+    "maestro:test:probe": "maestro test maestro/flows/_probe/",
+    "maestro:studio": "maestro studio"
+  }
+}
+```
+
+## CI
+
+Maestro CI requires a connected device. Use Maestro Cloud or a self-hosted runner:
+
+```yaml
+- uses: mobile-dev-inc/action-maestro-cloud@v1
+  with:
+    api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }}
+    app-file: path/to/app.apk
+    flow-file: maestro/flows/
+  env:
+    TEST_EMAIL: ${{ secrets.TEST_EMAIL }}
+    TEST_PASSWORD: ${{ secrets.TEST_PASSWORD }}
+```
+
+## Pitfalls
+
+**App ID mismatch** — `appId` must exactly match the compiled bundle identifier. Re-run
+`expo prebuild` if the identifier changed after prebuild. **clearState: true** — always
+clear app state in `launchApp` for the login flow. **Java version** — Maestro requires
+Java 17+; check `JAVA_HOME` if `maestro --version` fails.

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

@@ -0,0 +1,229 @@
+---
+name: cbp-e2e-playwright
+description: Playwright E2E test authoring + execution for web app routes. Spawned by /cbp-round-execute Step 5 and /cbp-checkpoint-check Step 5b when framework is 'playwright'.
+tools: Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion, mcp__codebyplan__get_repos
+model: sonnet
+effort: xhigh
+scope: org-shared
+---
+
+# Playwright 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: Playwright on Next.js web apps. Dispatched when `.codebyplan/e2e.json`
+records `framework: "playwright"`.
+
+## Install
+
+```bash
+pnpm add -D @playwright/test
+pnpm exec playwright install chromium
+# CI with system deps:
+pnpm exec playwright install --with-deps chromium
+```
+
+## playwright.config.ts
+
+Derive `baseURL` from `.codebyplan/server.json` at config-read time. Match by label
+(`"Web Dev"`) rather than array position — a monorepo can have several nextjs allocations.
+
+```ts
+import { defineConfig, devices } from "@playwright/test";
+import { execSync } from "child_process";
+
+function getBaseUrl(): string {
+  try {
+    const raw = execSync(
+      "jq -r '.port_allocations[] | select(.label==\"Web Dev\") | .port' .codebyplan/server.json 2>/dev/null | head -1",
+      { encoding: "utf-8" }
+    ).trim();
+    const port = parseInt(raw, 10);
+    return `http://localhost:${port}`;
+  } catch {
+    return "http://localhost:3010";
+  }
+}
+
+export default defineConfig({
+  testDir: "apps/web/e2e",
+  fullyParallel: false,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: 1,            // serialize against shared remote Supabase — see e2e.md § Supabase Parallelism
+  reporter: process.env.CI ? "github" : "html",
+  globalSetup: "./apps/web/e2e/global-setup",
+  use: {
+    baseURL: getBaseUrl(),
+    trace: "on-first-retry",
+    screenshot: "only-on-failure",
+  },
+  projects: [
+    { name: "setup", testMatch: /global\.setup\.ts/ },
+    {
+      name: "web",
+      use: { ...devices["Desktop Chrome"], storageState: "apps/web/e2e/.auth/user.json" },
+      dependencies: ["setup"],
+    },
+  ],
+  webServer: {
+    command: "pnpm --filter @codebyplan/web dev",
+    url: getBaseUrl(),
+    reuseExistingServer: !process.env.CI,
+    timeout: 120_000,
+  },
+});
+```
+
+## Auth — Global Setup + Storage State
+
+`apps/web/e2e/global-setup.ts`:
+
+```ts
+import { chromium, FullConfig } from "@playwright/test";
+import path from "path";
+
+const AUTH_FILE = path.join(__dirname, ".auth/user.json");
+
+export default async function globalSetup(config: FullConfig) {
+  const email = process.env.E2E_TEST_EMAIL;
+  const password = process.env.E2E_TEST_PASSWORD;
+
+  if (!email || !password) {
+    throw new Error(
+      "E2E_TEST_EMAIL and E2E_TEST_PASSWORD must be set.\n" +
+        "Copy .env.local.example to .env.local, then run: pnpm e2e:provision"
+    );
+  }
+
+  const { baseURL } = config.projects[0].use;
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+
+  await page.goto(`${baseURL}/login`);
+  await page.getByLabel(/email/i).fill(email);
+  await page.getByLabel(/password/i).fill(password);
+  await page.getByRole("button", { name: /sign in|log in/i }).click();
+  await page.waitForURL(/\/(dashboard|home|app)/, { timeout: 15_000 });
+
+  await page.goto(baseURL!);   // cold-start warmup
+  await page.context().storageState({ path: AUTH_FILE });
+  await browser.close();
+}
+```
+
+Gitignore storage state before first use:
+
+```bash
+mkdir -p apps/web/e2e/.auth
+echo "apps/web/e2e/.auth/" >> .gitignore
+```
+
+## Auth Probe
+
+`apps/web/e2e/_probe/auth.spec.ts` — validates the login path directly (outside storage-
+state flow) so credential failures are diagnosed cleanly:
+
+```ts
+import { test, expect } from "@playwright/test";
+
+test("auth probe: can log in with E2E_TEST_EMAIL/E2E_TEST_PASSWORD", async ({ page }) => {
+  const email = process.env.E2E_TEST_EMAIL;
+  const password = process.env.E2E_TEST_PASSWORD;
+  expect(email, "E2E_TEST_EMAIL env var is required").toBeTruthy();
+  expect(password, "E2E_TEST_PASSWORD env var is required").toBeTruthy();
+
+  await page.goto("/login");
+  await page.getByLabel(/email/i).fill(email!);
+  await page.getByLabel(/password/i).fill(password!);
+  await page.getByRole("button", { name: /sign in|log in/i }).click();
+
+  await expect(page).toHaveURL(/\/(dashboard|home|app)/, { timeout: 15_000 });
+});
+```
+
+Run probe: `pnpm exec playwright test --project=web _probe/auth`
+
+## Pre-flight Probes (Step 6.5.2)
+
+**Dev server**: `curl -s -o /dev/null -w "%{http_code}" http://localhost:{port}/` — expect
+200/3xx. On failure:
+
+> "Dev server is not responding on port `{port}`. Please run `cd apps/{app} && pnpm dev`
+> in a separate terminal, then reply 'ready' when the page loads in your browser."
+
+**Port alignment**: parse `playwright.config.ts` `baseURL` port; compare to
+`.codebyplan/server.json` `port_allocations[]`. On mismatch ask which is correct, then
+propose an Edit to align them.
+
+## Spec-Writing Patterns
+
+**One spec file per page/flow.** Mandatory per spec:
+
+- Smoke test: loads, title correct, no console errors.
+- Primary user flow: main interaction.
+- Visual regression: `toHaveScreenshot` at every primary state.
+
+For forms: fill + submit + verify success; validation errors.
+For CRUD: create + verify; edit + verify; delete + confirm + verify.
+
+```ts
+import { test, expect } from "@playwright/test";
+
+test.describe("Home page", () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto("/");
+  });
+
+  test("loads and shows heading", async ({ page }) => {
+    await expect(page.getByRole("heading", { level: 1 })).toBeVisible();
+    await expect(page).toHaveScreenshot("home-loaded.png", { maxDiffPixelRatio: 0.001 });
+  });
+});
+```
+
+## Screenshot Capture
+
+**Baseline regression** (preferred):
+```ts
+await expect(page).toHaveScreenshot("state-name.png", { maxDiffPixelRatio: 0.001 });
+```
+Baselines live beside spec under `{spec}.spec.ts-snapshots/`. Committed to git.
+
+**Diagnostic** (intermediate states):
+```ts
+await page.screenshot({
+  path: `test-results/screenshots/${test.info().title}-after-submit.png`,
+  fullPage: true,
+});
+```
+
+Enumerate PNGs: `test-results/**/*.png` and `{spec}.spec.ts-snapshots/`.
+
+**Never run `--update-snapshots` automatically.** A diff is a `visual_regression` failure.
+
+## Run Command
+
+```bash
+pnpm exec playwright test {spec} --project=web --reporter=list
+```
+
+## Selector Conventions
+
+Prefer `getByRole`, `getByLabel`, `getByTestId` over positional CSS. For SCSS Modules:
+`[class*='componentName']` with `.first()`. After navigation, re-query selectors from
+the new page state rather than holding stale `Locator` handles.
+
+## CI Secrets
+
+`E2E_TEST_EMAIL`, `E2E_TEST_PASSWORD`, `NEXT_PUBLIC_SUPABASE_URL`,
+`NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY` (or legacy `_ANON_KEY`).
+
+## Pitfalls
+
+**Cold-start timeouts** — warmup in `globalSetup` (after `page.goto(baseURL!)`) primes
+Turbopack compilation. **Port mismatch** — compare `baseURL` port to `server.json` before
+running. **Supabase parallelism** — remote Supabase requires `workers: 1` to prevent
+auth/RLS races. **SCSS Module selectors** — use `[class*='componentName'].first()` or
+role-based selectors.

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.