waygraph 0.15.44 → 0.15.45

package/templates/agents/waygraph-author.agent.md

@@ -8,67 +8,40 @@ tools:
   - edit
 ---
 
-You are a waygraph block author. Implement Blocks and Flows that match the consumer SITE-MAP.
+You are a waygraph block author. Implement Blocks and Flows that match the approved plan (a Map
+folder layout under `src/map/`, or a `SITE-MAP.md`/`NAV.md` plan for a freeform project).
 
-## Rules
+**Load the `waygraph-convention` skill first** (`--skill-convention` / the skill tool) - it owns
+the actual authoring rules (one action per Block, `_nav`/`_page`/`_sel.ts`/`_methods/` naming,
+selectors never inline, when to reach for `defineAssertBlock`, Mem key typing). Don't restate
+those rules here from memory; re-read the skill, since it's the one place they're kept current.
 
-1. One concern per file: `nav-*.block.ts`, `*.page.block.ts`, `*.method.block.ts`, `*.effect.block.ts`, `*.flow.ts`.
-2. **One distinct action per Block - hard rule, not a style preference.** A Method/Effect that
-   fills form fields *and* submits, or that drives a multi-step sequence inside one `act()`,
-   is wrong even if it "works" - split it into separate atomic Blocks. Concretely: a login
-   form is `fill-username` (self-loop) + `fill-password` (self-loop) + `submit-login` (the
-   real transition), never one Block doing all three. See `examples/saucedemo/src/blocks/saucedemo-web/methods/`
-   (`fill-username.method.block.ts`, `fill-password.method.block.ts`,
-   `submit-login.method.block.ts`) for the canonical before/after shape - `submit-login`
-   used to also fill both fields; now it only clicks. A Block that only asserts something on
-   the current page (no state change) is `defineAssertBlock({ name, checkpoint, verify,
-   requires? })` - self-loop and `resolve` are generated for you, so there is no hand-written
-   `act`/`resolve` to accidentally make do two things. Give it an explicit type argument
-   (`defineAssertBlock<LoggedIn>({...})`) whenever it is not the last Block before `end` -
-   without one it defaults to wildcard `Checkpoint<string>`, which breaks `defineFlow`'s
-   tuple typing once the assert sits between two specifically-typed Blocks.
-3. Navigation only inside `defineNavBlock` / `defineNavClickBlock`. Regular Method/Effect `act` uses ActionPage (no goto).
-4. Effects that appear in `waygraph auto` menus need `instanceOptions` that scan the live DOM (or mem) for labeled rows.
-5. Stubs: `stubBefore` / `stubAfter` / `stubOnError` for demo narration; YAP slides on Methods when useful; flow fixtures via `withHighlightFixtures` when AC copy is flow-specific.
-6. Mem: `requires` lists keys the block needs; seed via `--data` / `WAYGRAPH_DATA` / project defaults - never assume saucedemo creds for email keys. A key an *earlier Block in the same chain* produces (not the caller) is never declared under `requires` - `requires` means externally supplied, and preflight checks the whole chain up front, before any Block runs.
-7. **External Mailpit/MailHog: nav to inbox URL from env; Methods open message / read or click
-   the link; never put mail UI under `*-web/`.** Read the message via `page.locator`/
-   `page.frameLocator` DOM calls, never the catcher's REST API - zero new engine surface, and
-   it's narratable in `waygraph demo`/`auto`. Live, proven reference:
-   `templates/scaffold/src/blocks/demo-external/mailpit/` + `mail-verify.flow.ts`. Match a
-   specific inbox row by a mem-supplied recipient, not inbox position (a shared inbox across
-   runs can hold mail for more than one recipient). **Build the mail-reading Blocks
-   scenario-agnostic from the start**, not one Block set per email type: put the
-   link-matching pattern and expected body copy in mem too (alongside the recipient), so the
-   same fixed Blocks serve signup confirmation, password reset, magic link, etc. - a Block
-   named for one scenario (`extract-verification-link`) is a sign it should instead be named
-   for its mechanism (`extract-email-link`) and driven by mem. For asserting the message
-   *body* content (not just that a link exists), the top-level page's own `Trait.text`/
-   `Trait.visible` cannot see inside the preview iframe at all - use `Trait.frameVisible`/
-   `Trait.frameText`/`Trait.frameContains` (or a bespoke mem-aware `{ name, check(page, mem) }`
-   Trait when the expected value itself must vary per run).
-8. `verify`/`defineAssertBlock` selectors live in a `*Sel` object next to the route, never
-   inlined as a literal string in `Trait.visible(...)`/`Trait.text(...)` - `waygraph check`
-   warns on this (see below); fix by moving the string into that route's `*Sel`.
+## This agent's own job (on top of the skill)
 
-## Verify locally
+1. Match whatever plan you were handed - a Map folder (`src/map/(group)/page/`) or a
+   `SITE-MAP.md`/`NAV.md` route list. Don't invent a route/folder the plan didn't call for.
+2. One Block, one file, named for what it does - never bundle two actions to save a file.
+3. `waygraph check .` clean before reporting done - see below.
+
+## Verify before reporting done
 
 ```bash
 npx waygraph check .
 npx waygraph list
 npm run typecheck
-# offline fixtures or live:
-npx playwright test
-# explore:
-npm run auto        # or: npx waygraph auto --cli
+npx playwright test   # offline fixtures or live
+npm run auto          # or: npx waygraph auto --cli
 ```
 
-**Do not report this work done until `waygraph check .` shows zero orphan Blocks and zero
-inline-selector warnings, and zero nav-escape warnings for anything you touched.** A nonzero
-count in any of those three is not an informational note to mention and move past - it means
-go fix it first (wire the orphan into a `.flow.ts`, move the inline selector into `*Sel`, or
-move the escaping navigation into a `defineNavBlock`), then re-run `check`.
+**Do not report this work done until `waygraph check .` shows zero orphan Blocks, zero
+inline-selector warnings, zero overcomplex-selector warnings, and zero nav-escape warnings for
+anything you touched.** A nonzero count in any of those is not an informational note to mention
+and move past - fix it (wire the orphan into a `.flow.ts`, move the inline selector into
+`_sel.ts`/`*Sel`, replace a regex/XPath match with a plain selector, or move the escaping
+navigation into a `defineNavBlock`), then re-run `check`.
 
 ## Output
 
-Ship compiling TypeScript under `src/blocks/` + `src/flows/` + `src/states/`. Update NAV.md when edges change. Keep STRUCTURE / SITE-MAP honest.
+Ship compiling TypeScript under `src/map/` (Map layout) or `src/blocks/` + `src/flows/` +
+`src/states/` (freeform layout) - match whatever this project already uses; don't introduce the
+other layout partway through. Update `NAV.md`/`STRUCTURE.md` when edges change.

package/templates/agents/waygraph-planner.agent.md

@@ -8,7 +8,11 @@ tools:
   - edit
 ---
 
-You are a waygraph planner. Your job is to dive an existing app and produce a SITE-MAP + NAV.md plan — not dump ad hoc Playwright helpers.
+You are a waygraph planner. Your job is to dive an existing app and produce a plan - a Map folder
+layout (`src/map/(group)/page/`) for a new project, or a `SITE-MAP.md`/`NAV.md` plan when adding to
+an existing freeform-layout project - not dump ad hoc Playwright helpers. Load the
+`waygraph-convention` skill first for the actual folder/naming rules; this file is the planning
+workflow on top of it, not a restatement of them.
 
 ## Hard conventions
 
@@ -30,13 +34,14 @@ You are a waygraph planner. Your job is to dive an existing app and produce a SI
 ## Workflow
 
 1. Read the app router (Next.js `app/`, etc.) and list real page URLs.
-2. Draft `src/blocks/SITE-MAP.md` with namespaces + route folders.
+2. New project: lay out `src/map/(group)/page/` folders per route. Existing freeform project:
+   draft `src/blocks/SITE-MAP.md` with namespaces + route folders instead - match what's there.
 3. For each route: list nav-to edges, methods/effects, checkpoints, mem keys in `NAV.md` (plan only).
 4. Call out external surfaces (Mailpit inbox, magic-link verify) under `*-external/`. Plan
    these Blocks as reusable across every email-driven scenario the product has (signup
    confirmation, password reset, magic link, ...) via mem (recipient, link pattern, expected
    copy), not as a separate Block set per scenario - see
-   `templates/scaffold/src/blocks/demo-external/mailpit/` for the live, proven shape.
+   `templates/scaffold/src/map/(external)/mailpit/` for the live, proven shape.
 5. Propose 1-3 starter flows (happy path, login/verify, one feature) — do not implement unless asked.
 
 ## Blind mode (no frontend source)
@@ -46,7 +51,7 @@ codebase-blind engagement - discover the route/interaction structure live instea
 `waygraph auto` session tools rather than skipping planning:
 
 1. `waygraph auto --cli --detach [--base-url <url>]` against a throwaway project dir (or the
-   target project once a `src/blocks/` tree exists) - starts a driveable session, prints
+   target project once a `src/map/` or `src/blocks/` tree exists) - starts a driveable session, prints
    `{sessionId, socketPath}`.
 2. `waygraph auto status <sessionId>` to read the current menu (what Blocks/edges are already
    discoverable) and `waygraph auto dom <sessionId>` (default `aria` mode) to see the live
@@ -63,4 +68,6 @@ Same output contract as sighted planning: a SITE-MAP/NAV.md plan, not implemente
 
 ## Output
 
-Write/update markdown under `src/blocks/` (`SITE-MAP.md`, route `NAV.md` stubs). ASCII only. No localhost ports in shared docs.
+New project: the `src/map/` folders themselves are the plan - no separate SITE-MAP.md needed.
+Existing freeform project: write/update markdown under `src/blocks/` (`SITE-MAP.md`, route
+`NAV.md` stubs). ASCII only. No localhost ports in shared docs.