From ae9494ab26f1428dbbf225d32ceb7bfea1679e78 Mon Sep 17 00:00:00 2001 From: Lukas Oppermann Date: Mon, 19 Oct 2026 14:25:41 +0200 Subject: [PATCH] docs(starter): streamline authoring and validation guidance Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 1b58255f-30de-4528-8072-7441ea94f202 --- .../context-templates/BROWSER-VALIDATION.md | 15 +-- .../context-templates/DESIGN-SYSTEM.md | 3 +- .../skills/browser-canvas-validation/SKILL.md | 22 ++--- .../browser-canvas-validation/WORKFLOW.md | 25 ++--- .../.agents/skills/create-prototype/SKILL.md | 8 +- .../create-prototype/references/authoring.md | 24 +++-- .../create-prototype/workflows/iterate.md | 11 ++- starter/AGENTS.md | 91 +++++++++++-------- starter/README.md | 17 ++-- 9 files changed, 109 insertions(+), 107 deletions(-) diff --git a/starter/.agents/context-templates/BROWSER-VALIDATION.md b/starter/.agents/context-templates/BROWSER-VALIDATION.md index c1b47de..638b31e 100644 --- a/starter/.agents/context-templates/BROWSER-VALIDATION.md +++ b/starter/.agents/context-templates/BROWSER-VALIDATION.md @@ -30,10 +30,9 @@ alone does not prove application bootstrap or route readiness. ## Canvas host and identifiers -Find the intended Copilot host, handle reuse and page-identifier contracts. -Record where runtime identifiers come from, not universal fixed IDs. Runtime -discovery is authoritative for current schemas and actions. Configuration is -not availability. Missing canvas support does not authorize silent substitution. +Find the intended Copilot host, handle reuse and page-identifier contracts. Record where runtime identifiers come from, not universal fixed IDs. Runtime discovery is authoritative for current schemas and actions. Inspect a schema before the first required operation, then reuse it only for the same provider and session. Rediscover after provider reload/reconnect, a schema mismatch or an explicit request to check changed capabilities; a timeout alone does not invalidate it. + +Configuration is not availability. Missing canvas support does not authorize silent substitution. Keep `canvasId` and `instanceId` distinct. Actions addressed by the panel handle need no separate page acquisition. Record separate page identifiers only when @@ -105,13 +104,7 @@ Identify what the run may close without disturbing user-owned sessions. Link lifecycle policy in [REPOSITORY.md](./REPOSITORY.md). Do not install tools, repair daemons, create auth or start undeclared infrastructure during validation. -Allow one bounded same-panel recovery attempt: check documented readiness, -refocus the same owned instance, rediscover schemas, and retry inspection once -only if required runtime identifiers are available. Do not loop or open duplicate -panels. A timed-out interaction may already have succeeded; inspect its resulting -state before considering another action. Do not restart a healthy server because -its canvas timed out. A separate MCP browser starts with a fresh read of the -authorized route, not a replay or an assumption of shared state. +Allow one bounded same-panel recovery attempt: check documented readiness, refocus the same owned instance, and retry inspection once only if required runtime identifiers are available. Reuse the current schema unless its invalidation condition applies. Do not loop or open duplicate panels. A timed-out interaction may already have succeeded; inspect its resulting state before considering another action. Do not restart a healthy server because its canvas timed out. A separate MCP browser starts with a fresh read of the authorized route, not a replay or an assumption of shared state. If MCP is unavailable, report the actual blocker, repository trust/fresh-session setup and remaining checks as unverified. Do not silently install browser engines. diff --git a/starter/.agents/context-templates/DESIGN-SYSTEM.md b/starter/.agents/context-templates/DESIGN-SYSTEM.md index f8e0dfe..c03f3c5 100644 --- a/starter/.agents/context-templates/DESIGN-SYSTEM.md +++ b/starter/.agents/context-templates/DESIGN-SYSTEM.md @@ -29,8 +29,7 @@ and tasks belong in [RESPONSIVE-DESIGN.md](./RESPONSIVE-DESIGN.md). ## Navigation primitives -Distinguish tabs, breadcrumbs, side navigation, and action menus. Verify link -versus button semantics, selection and focus behavior. Product owns destinations. +Distinguish tabs, breadcrumbs, side navigation, and action menus. Verify link versus button semantics, selection and focus behavior. Product owns destinations. For a standalone link that preserves existing navigation structure, identify the semantic link guidance and any shared navigation rules that apply without requiring research into unrelated composite patterns. Read composition-specific guidance when a navigation pattern is introduced or changed. ## Forms diff --git a/starter/.agents/skills/browser-canvas-validation/SKILL.md b/starter/.agents/skills/browser-canvas-validation/SKILL.md index d01f0c3..c1719c1 100644 --- a/starter/.agents/skills/browser-canvas-validation/SKILL.md +++ b/starter/.agents/skills/browser-canvas-validation/SKILL.md @@ -27,17 +27,16 @@ If a required companion or sibling skill is missing, stop and name its path before checks. Do not auto-install dependencies. Select the first existing root, `.agents/context/`, then `.github/contexts/`. -Read `PRODUCT-DESIGN.md`, `REPOSITORY.md` and `BROWSER-VALIDATION.md` -directly there. Read `DESIGN-SYSTEM.md` for component-specific assertions. -No manifest or canvas-specific pack file is required. Never mix roots. +Read the applicable `BROWSER-VALIDATION.md` sections and owner topics for target/readiness, canvas identifiers, safe state and recovery. In the shared template, these are `Target and readiness`, `Canvas host and identifiers`, `Sessions, safe state and artifacts`, and `Recovery and cleanup`. Read `Configured Playwright MCP fallback` or `Existing CLI adapter` only when that fallback is needed. + +Read the applicable `REPOSITORY.md` section for the target (`Where UI lives` in the shared template), `Commands` when a command is needed, and `Constraints` for relevant permissions or lifecycle. Follow applicable owner links. If a consumer uses different headings, select the equivalent sections by owner rather than reading the entire file. + +Read `PRODUCT-DESIGN.md` when expected product behavior is unresolved, when assessing scenario behavior or fidelity, or when checking forms, persistence, destructive actions or externally visible changes. A fully specified, read-only route or menu check can use the request as its expected outcome. Read `DESIGN-SYSTEM.md` for component-specific assertions, `ACCESSIBILITY.md` for accessibility checks and `RESPONSIVE-DESIGN.md` for responsive checks. No manifest or canvas-specific pack file is required. Never mix roots. Missing required context stops validation. Report the selected root/file and offer `setup-skills` to author or refresh context under the shared resolution rules. Do not invoke it -automatically. Never read drafts as active context. Follow relevant owner links -and evidence anchors, preserve `proposed-default` labels and disclose conflicts. -Read current owner guidance on every run. Product context owns scenarios and -state policy. Browser context owns target URL, server, routes and recovery. +automatically. Never read drafts as active context. Follow relevant owner links and evidence anchors, preserve `proposed-default` labels and disclose conflicts. Read the complete applicable owner sections, not unrelated sections or topics. Product context owns scenarios and state policy. Browser context owns target URL, server, routes and recovery. Use only permitted sources. Do not research remotely or broaden exclusions during validation. Request explicit refresh if required documentation is stale @@ -45,12 +44,9 @@ or missing. A document with gaps does not prove runtime capabilities. ## Runtime contract -Discover the available canvas types. If `browser` or the necessary canvas tools -are absent, report the missing runtime and stop this path, not a pass or a silent -backend substitution. Use the explicit configured MCP handoff in -[WORKFLOW.md](./WORKFLOW.md) if available. Call `list_canvas_capabilities` for the actual browser -type before opening or acting. Use its advertised open input and action schemas. -No frozen action list in this skill overrides the runtime. +Do not discover canvas capabilities for source-only tasks. For rendered checks, identify the browser canvas and inspect its actual schemas before the first required operation. Reuse a schema already discovered for the same provider in this session. Rediscover only after provider reload/reconnect, a schema mismatch or an explicit request to check for changed capabilities; a timeout alone does not invalidate it. Never carry schemas across providers or sessions. + +If the browser canvas or required tools are absent, report the blocker and use only the explicit configured MCP handoff in [WORKFLOW.md](./WORKFLOW.md) when applicable. Use the advertised open input and action schemas; no frozen action list overrides the runtime. Keep the canvas type and caller-chosen `instanceId` handle distinct. Address the panel with that handle through `invoke_canvas_action`. If the diff --git a/starter/.agents/skills/browser-canvas-validation/WORKFLOW.md b/starter/.agents/skills/browser-canvas-validation/WORKFLOW.md index 1adb44f..72a53bd 100644 --- a/starter/.agents/skills/browser-canvas-validation/WORKFLOW.md +++ b/starter/.agents/skills/browser-canvas-validation/WORKFLOW.md @@ -2,11 +2,9 @@ ## Browser selection -Use the browser canvas first for every agent-driven rendered check, interaction -test, screenshot and visual, responsive or accessibility review. Discover its -current capabilities rather than assuming an earlier host's limitations. -The Replica prototype canvas remains the preview and publishing surface; -discover the separate browser canvas for page inspection. +Use the browser canvas first for every agent-driven rendered check, interaction test, screenshot and visual, responsive or accessibility review. Discover its current capabilities before the first required operation, then reuse the same-provider schema in this session until it is invalidated under [the runtime contract](./SKILL.md#runtime-contract). Source-only work does not enter this workflow. + +The Replica prototype canvas remains the preview and publishing surface; use the separate browser canvas for page inspection. Use configured Playwright MCP only when the canvas is unavailable for the required check: absent runtime, absent action, unsatisfied required identifier @@ -26,18 +24,13 @@ derive branch instance IDs from another repository's scripts. A missing running target is a blocker unless starting the declared server is already authorized. Never start a second infrastructure project to supply validation. -Read the requested outcome and product-design scenario/state owner. Establish -expected results before interacting. Use the smallest connected flow that proves -the request. Invalid-input submission, destination and reload-persistence checks -apply when the requested behavior needs them and test mutations are authorized. -Otherwise report those assertions untested. Do not submit real data to prove a -read-only audit, or treat a disabled button alone as proof of safe persistence. +Read the requested outcome and establish expected results before interacting. Read product-design guidance when required by the [context requirements](./SKILL.md#required-reads-and-dependencies). Use the smallest connected flow that proves the request. Invalid-input submission, destination and reload-persistence checks apply when the requested behavior needs them and test mutations are authorized. Otherwise report those assertions untested. Do not submit real data to prove a read-only audit, or treat a disabled button alone as proof of safe persistence. ## Discover, read, act, assert -Inspect browser canvas capabilities and satisfy the actual schemas as described -in [SKILL.md](./SKILL.md). Call `open_canvas` with the declared type and a session -handle. Use `invoke_canvas_action` with that same handle to address the instance. +Use browser canvas capabilities and schemas as described in [SKILL.md](./SKILL.md). +Call `open_canvas` with the declared type and a session handle. Use +`invoke_canvas_action` with that same handle to address the instance. Action inputs follow the discovered schema. When an action takes only the panel handle and its advertised inputs, invoke it directly without page acquisition. Supply a separate page identifier only if that schema requires one and the @@ -76,9 +69,7 @@ For follow-up changes reuse the correct session preview, assert changed content and relevant behavior. If content is missing, use supported reload and re-read once before reporting stale rendering. -A read timeout can be retried once after checking the declared readiness signal. -Refocus the same owned panel, rediscover capabilities and retry inspection only -with valid required identifiers. Do not loop or create duplicate panels. +A read timeout can be retried once after checking the declared readiness signal. Refocus the same owned panel and retry inspection only with valid required identifiers and the existing schema. Rediscover only if the runtime contract's invalidation condition applies, not because a read timed out. Do not loop or create duplicate panels. For further failures use only the repository's authorized recovery procedure. Do not replay a timed-out state-changing action, its effect may already have occurred. Inspect resulting state first. Restarting servers, installing packages diff --git a/starter/.agents/skills/create-prototype/SKILL.md b/starter/.agents/skills/create-prototype/SKILL.md index b2e695d..21f63e3 100644 --- a/starter/.agents/skills/create-prototype/SKILL.md +++ b/starter/.agents/skills/create-prototype/SKILL.md @@ -22,7 +22,9 @@ prototype" is iteration. | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | Clear new build, such as "build an offline inventory prototype" | [create](./workflows/create.md) | | Change to an existing prototype, such as "add filtering to this page" | [iterate](./workflows/iterate.md) | +| Candidate narrow edit to an existing prototype | [iterate](./workflows/iterate.md), then apply the root instructions' narrow-edit path | | Consequential missing information, including an unresolved target or create-versus-iterate choice | [clarify](./workflows/clarify.md), then the selected build or iteration workflow | +| Behavior-preserving test-only work | Use the root instructions' task-scope guidance; do not load a prototype workflow | | Unrelated task or routine command | Stop using this skill and continue the original task | Load only the selected workflow, not all companions as a required-read bundle. @@ -40,8 +42,10 @@ different destination. A reference URL is not permission to fork, duplicate, publish, delete or activate anything. Approved references are 1:1 requirements except for the requested delta, not design inspiration. -The selected workflow reads the shared -[authoring reference](./references/authoring.md) before implementation. +The selected create or normal iteration workflow reads the shared +[authoring reference](./references/authoring.md) before implementation. A +candidate narrow edit follows the iteration workflow's classification step and, +when eligible, skips that reference and its context dependencies. It owns context resolution, design evidence, data boundaries and completion. It does not load another workflow. Install `product-design`, `setup-skills` and the `context-templates` library alongside this skill. diff --git a/starter/.agents/skills/create-prototype/references/authoring.md b/starter/.agents/skills/create-prototype/references/authoring.md index 752bef7..82a09aa 100644 --- a/starter/.agents/skills/create-prototype/references/authoring.md +++ b/starter/.agents/skills/create-prototype/references/authoring.md @@ -7,11 +7,17 @@ This reference does not dispatch or load workflow companions. Read [context resolution](../../product-design/references/context-resolution.md). Select the first existing root, `.agents/context/`, then `.github/contexts/`. -Read `DESIGN-SYSTEM.md`, `PRODUCT-DESIGN.md`, `REPOSITORY.md` and -`BROWSER-VALIDATION.md` directly there. No manifest or prototype-specific pack -file is required. Never mix roots or read drafts as active context. -Read `SEED-DATA.md` for new or changed fixtures, `RESPONSIVE-DESIGN.md` for -responsive decisions and `ACCESSIBILITY.md` for product accessibility environments. +For application work, read the applicable sections of these owners and follow relevant topic links: + +- `REPOSITORY.md`: `Where UI lives`, `Commands` and `Constraints`. +- `DESIGN-SYSTEM.md`: shared defaults and task-relevant sections before component, token or pattern decisions. +- `PRODUCT-DESIGN.md`: when creating or changing behavior, states, flows, messaging or product decisions. +- `BROWSER-VALIDATION.md`: before starting a preview or performing rendered validation. +- `SEED-DATA.md`: for new or changed fixtures; `RESPONSIVE-DESIGN.md`: for responsive decisions; `ACCESSIBILITY.md`: for product accessibility environments. + +If a consumer uses different headings, select the equivalent sections by owner rather than reading the entire file. + +Read only relevant sections and directly linked owner topics, retaining shared authority, safety rules and limitations. Use the resolution rules to determine when an owner topic applies; do not read every topic as a checklist. A missing conditional document blocks only the decision that needs it. No manifest or prototype-specific pack file is required. Never mix context roots or read drafts as active context. Read shared defaults, safety rules, relevant headings and limitations. Follow relevant owner links, evidence anchors and local documentation indexes @@ -29,10 +35,7 @@ installed files, including this reference or [product-design](../../product-design/SKILL.md), stop affected work with the exact path. Do not install dependencies or invent fallback policy. -Use product-design's workflow for relevant UI decisions and convert its -context-backed behavior into implementation checks. Unrelated known gaps do -not block supported work. Consequential contradictions or missing rules remain -unresolved and return to the selected workflow's conditional clarification. +Use product-design's workflow for relevant UI decisions and convert its context-backed behavior into implementation checks. Reuse unchanged decisions already established for the task rather than repeating a design pass. Select additional audit or review skills only when the user requests them or their applicable skill/repository instructions require them. Loading a skill is not evidence that its review was completed; preserve required accessibility checks and visual-approval boundaries, and report incomplete reviews as incomplete. Unrelated known gaps do not block supported work. Consequential contradictions or missing rules remain unresolved and return to the selected workflow's conditional clarification. ## Task inputs, not setup requirements @@ -78,6 +81,7 @@ named page or a catalog example is the target implementation. Use the active design-system context's declared evidence sources, installed APIs and fallback rules under context resolution's applied-guidance contract. +Reuse an established composition when it satisfies the requested behavior. Use a consumer-declared recipe, catalogue or research tool only when a specific composition or requirement remains unresolved; do not repeat lookup for general reassurance. When a named gap requires source inspection, read full relevant component, token and pattern sections, including accessibility requirements, not whole catalogues. Local documentation is sufficient when the context declares it. For MCP @@ -96,6 +100,8 @@ verify their names, semantic roles and applicable constraints. Do not guess from a token name or substitute another provider. Use existing supported compositions rather than recreating primitives. +For a JavaScript package, resolve a public import from its package metadata: follow the applicable `exports` condition, including `types` when checking declarations, or its declared `types`, `typings` or package entry. Follow re-exports to the component definition. Package metadata and the installed version are authoritative; do not guess a component path from its name. Use the consumer's documented resolver when one exists. Other ecosystems use their declared package and API discovery mechanisms. + Stop API discovery once the selected import, composition, required props, states, narrow behavior and keyboard/focus contract are established for this task. Evidence may combine approved guidance and installed source; implementation diff --git a/starter/.agents/skills/create-prototype/workflows/iterate.md b/starter/.agents/skills/create-prototype/workflows/iterate.md index 7e47aa9..daaa83f 100644 --- a/starter/.agents/skills/create-prototype/workflows/iterate.md +++ b/starter/.agents/skills/create-prototype/workflows/iterate.md @@ -7,11 +7,12 @@ Read only after the entrypoint selects a change to an existing prototype. route and worktree. If several targets fit and the choice changes what will be edited, read [clarify](./clarify.md), then return here. Do not silently create a duplicate route, fork, branch or session. -2. Read the shared [authoring reference](../references/authoring.md) before +2. Read the target's directly affected implementation and nearest focused test. If the change might qualify for the root instructions' narrow-edit path, classify it now. For an eligible change, follow that path and skip the remaining authoring and context reads. If eligibility is uncertain or scope grows, continue with the normal workflow. +3. Read the shared [authoring reference](../references/authoring.md) before editing. Reuse unchanged, already-read evidence only when it still resolves the current decision. Do not repeat setup, intake, scaffolding or broad repository orientation merely because this is a follow-up. -3. Read the target's directly relevant implementation, styles and data wiring. +4. Read the target's directly relevant implementation, styles and data wiring. Identify the requested delta, acceptance inputs and affected behavior from the request and existing answers. A new reference is not required. Preserve the existing page structure, navigation, data sources, persistence and unrelated content. @@ -19,16 +20,16 @@ Read only after the entrypoint selects a change to an existing prototype. When moving or recreating UI at an explicitly requested destination, inspect the approved source and preserve its layout, copy, states and interactions. Do not redesign it or remove the source unless separately authorized. -4. Use `product-design` for new or changed behavior. If any consequential scope +5. Use `product-design` for new or changed behavior. If any consequential scope or behavior gap remains, read [clarify](./clarify.md), not the create workflow. Make the smallest complete change across the necessary files. New domain fields follow the shared data boundary, not component-local mock collections. -5. Reuse the current preview when available. If its location or runtime is +6. Reuse the current preview when available. If its location or runtime is unknown, follow the consumer's documented discovery/recovery procedure. Do not guess a port, restart a healthy server or rerun scaffolding just to recover a URL. Update registration only when the requested change needs it, using the repository's documented mechanism and preserving the target. -6. Follow the authoring reference's completion checks for the changed surface +7. Follow the authoring reference's completion checks for the changed surface and directly affected behavior. Verify reference fidelity where applicable. Do not tour unrelated flows or claim unchanged regions were retested. diff --git a/starter/AGENTS.md b/starter/AGENTS.md index 428b05c..d8365dc 100644 --- a/starter/AGENTS.md +++ b/starter/AGENTS.md @@ -2,7 +2,9 @@ This neutral Vite + React app and its local skills in `.agents/skills/` are copied into a new, independent repository using the Replica installer or the local-checkout -bootstrap script. Read `README.md` before editing the app. +bootstrap script. Use these instructions to select the task workflow. The README +is human onboarding; read it when a task needs its setup or connection details, +not as a default implementation requirement. Check `node --version` before installing dependencies. Use an existing Node.js installation matching `engines.node` in [package.json](package.json). On macOS or Linux, if a compatible installation is missing, ask for approval before installing [nodenv](https://github.com/nodenv/nodenv), [node-build](https://github.com/nodenv/node-build), or Node.js, or changing shell configuration. Do not install automatically. Verify a compatible Node.js version is active before `npm ci`. @@ -13,13 +15,39 @@ update a prototype, or explore new ideas and alternative designs. Favor focused, tangible iterations that help users evaluate the experience, reusing existing components and patterns rather than adding production infrastructure unless requested. +## Task scope + +Source-only explanations, documentation edits and automated tests do not need canvas discovery or a preview unless the user explicitly requests rendered evidence. + +For behavior-preserving test-only changes, inspect the affected implementation, its nearest relevant tests and runner configuration, then run the smallest relevant selection. Do not apply UI component preflight or canvas setup just because a test uses JSX. If the test fix changes application behavior, classify that implementation change separately. + +### Narrow edits + +A change to an existing prototype is narrow only when all of these conditions hold: + +- The request, an existing test or adjacent canonical implementation fully determines the result. No product, component, interaction, accessibility or data decision remains. +- The implementation only changes visible copy in existing elements, swaps an icon in its existing position, changes a link to a verified route in the repository's route registration, or changes a scalar literal that directly controls existing display or navigation. +- No UI element or component is added, removed, replaced or reordered. An icon swap may change only the icon component and its import. +- No other imports, styles, tokens, route definitions, hooks, handlers, conditional rendering, state, data shape, fixtures or seeds change. +- Accessible names change only when they follow the edited visible text. Do not change ARIA attributes, heading levels, landmarks, label associations or focus order. +- The change is not destructive-action, legal, privacy, error or status copy, nor a timeout or limit. + +Update an existing focused test expectation when needed; do not add test infrastructure or unrelated coverage. If any condition is false or uncertain, use the normal workflow. + +For a narrow edit: + +- Read the directly affected implementation and nearest focused test, then make only the requested change. +- Skip component preflight, product/design/repository context reads, Replica canvas preflight and the preview-before-edit requirement. +- If a changed navigation destination needs rendered acceptance, follow the browser workflow and its applicable target and safety context requirements. +- Run the smallest relevant existing test and the repository's declared type check. +- Do not start a preview solely for a narrow edit without authorization. If required rendered evidence cannot be collected, report it as unverified. +- Honor explicitly requested rendered checks. If scope grows or a relevant check exposes a broader issue, return to the normal workflow. + ## UI component preflight -Before UI changes, consult the project's existing component, design-system and -repository guidance. Follow applicable skills' required context and setup rules; -this preflight does not replace them. Replica skills resolve approved context from -`.agents/context/` first, then the legacy `.github/contexts/` root; do not mix roots -or treat drafts as approved guidance. +Except for [narrow edits](#narrow-edits), consult the project's existing component, design-system and repository guidance before UI changes. Follow applicable skills' required context and setup rules; this preflight does not replace them. + +Replica skills resolve approved context from `.agents/context/` first, then the legacy `.github/contexts/` root. Do not mix roots or treat drafts as approved guidance. Choose the page or layout root first where relevant, then map affected navigation, headers, controls, disclosures, actions and states to existing design-system, @@ -42,7 +70,8 @@ introduced roles before implementing them and disclose approved deviations. Finish a coherent set of UI changes and corresponding tests, then run applicable builds, checks and the smallest relevant tests once, rather than after every UI edit. Fix failures and rerun affected checks. Do not run the full suite by default; -follow any explicit project requirements. +follow any explicit project requirements. [Narrow edits](#narrow-edits) use their +focused checks instead of this broader timing and preview policy. Discover actual commands from project guidance, scripts and configuration. Use them where they exist; do not invent build or test commands or assume npm. @@ -52,35 +81,19 @@ validation and unverified behavior rather than claiming success. ## Replica prototype canvas -Before UI edits, starting a local preview or opening one in Copilot, complete the -[canvas preflight](README.md#canvas-preflight). Discover `replica-prototype` -and use it to open the actual running preview URL. Session setup owns plugin -installation and CLI enablement; agents check canvas availability and explain -recovery using the preflight's missing-canvas instructions. In a canvas-capable -host, stop before UI edits or preview startup until the canvas is available. -Skills such as `review-hub-feedback` keep their own missing-canvas blocker rules. - -For prototype work with a local preview, discover and use the project's actual -development command and running server URL. Verify the server is responsive; -do not guess its port or assume npm, Vite or a route scheme. - -As soon as the authorized route is known and its preview is running, show its -current state before UI edits and keep the preview on that route while working. -Starting a server still requires the repository's startup authorization. - -In environments supporting canvases, when `replica-prototype` is available, -call `list_canvas_capabilities({ canvasId: "replica-prototype" })` to discover all -actions, their purposes, and input schemas. Proactively open or focus it with the actual -`prototypeUrl`. If an available canvas fails to open after the documented -connection checks, disclose the runtime blocker and use the authorized route -in a browser canvas or supported local browser. This fallback does not bypass -missing-plugin setup, approval or a required fresh session. -An unavailable canvas is different from a disconnected Hub; a Hub connection -problem does not require replacing a working local preview. -Use a browser canvas separately for route and interaction checks; -it does not replace the Replica canvas's prototype and publishing controls. -If the host lacks canvas support or plugin management, follow the preflight's -local-preview fallback without claiming canvas validation. +Except for [narrow edits](#narrow-edits) and source-only tasks, complete the [canvas preflight](README.md#canvas-preflight) before UI edits, preview startup or opening a preview in Copilot. Use `replica-prototype` to open the actual running preview URL. + +Session setup owns plugin installation and CLI enablement; agents check canvas availability and explain recovery using the preflight's missing-canvas instructions. In a canvas-capable host, stop before UI edits or preview startup until the canvas is available. Skills such as `review-hub-feedback` keep their own missing-canvas blocker rules. + +For prototype work with a local preview, discover and use the project's actual development command and running server URL. Verify the server is responsive; do not guess its port or assume npm, Vite or a route scheme. + +As soon as the authorized route is known and its preview is running, show its current state before UI edits and keep the preview on that route while working. Starting a server still requires the repository's startup authorization. + +In a canvas-capable host, discover `replica-prototype` schemas before the first required operation and reuse them for the same provider in this session. Rediscover after provider reload/reconnect, schema mismatch or an explicit capability-refresh request. Open or focus the canvas with the actual `prototypeUrl`. + +If an available canvas fails to open after the documented connection checks, disclose the runtime blocker and use the authorized route in a browser canvas or supported local browser. This fallback does not bypass missing-plugin setup, approval or a required fresh session. An unavailable canvas is different from a disconnected Hub; a Hub connection problem does not require replacing a working local preview. + +Use a browser canvas separately for route and interaction checks; it does not replace the Replica canvas's prototype and publishing controls. If the host lacks canvas support or plugin management, follow the preflight's local-preview fallback without claiming canvas validation. If multiple providers register `replica-prototype`, confirm the intended provider and disambiguate calls using its discovered provider ID; never hardcode one. @@ -122,12 +135,16 @@ entry-page checks; report unverified landing pages. ## Browser validation and Playwright fallback +Do not discover browser canvas capabilities for source-only tasks or carry schemas between providers or sessions. Reuse a schema already discovered for the same provider in this session until that provider reloads or reconnects, a schema mismatch occurs, or the user requests a capability refresh. A timeout alone does not invalidate a schema. + +Authorization, readiness and rendered state must still be checked for each operation. + Use the browser canvas first for all agent-driven rendered checks, interaction tests, screenshots and visual, responsive or accessibility reviews. Keep the normal prototype preview open; its publishing controls do not replace browser inspection. Follow the [shared browser workflow](.agents/skills/browser-canvas-validation/WORKFLOW.md) for discovery, fresh refs, safe interactions, recovery, isolation and evidence. -Discover actual schemas and address actions with the panel's `instanceId`. +Use the actual discovered schemas and address actions with the panel's `instanceId`. Actions taking only that handle need no separate page acquisition; obtain a separate identifier from the runtime only when its schema requires one. diff --git a/starter/README.md b/starter/README.md index 2e01c85..30960e9 100644 --- a/starter/README.md +++ b/starter/README.md @@ -187,12 +187,9 @@ npm run dev Open the URL printed by Vite. -As soon as the route for the requested work is known, show its current state -before UI edits and keep the preview on that route. In Copilot, complete the -[canvas preflight](#canvas-preflight) before UI edits or preview startup, then -use the Replica prototype canvas. Use a browser preview only under the -preflight's fallback conditions and disclose the limitation. A disconnected Hub is not -the same as an unavailable canvas and does not prevent a local preview. +Show the requested route before ordinary UI edits and keep the preview on that route. Source-only work and eligible [narrow edits](AGENTS.md#narrow-edits) do not require preview-before-edit. + +In Copilot, complete the [canvas preflight](#canvas-preflight) before ordinary UI edits or preview startup, then use the Replica prototype canvas. Normal workflows use a browser preview only under the preflight's fallback conditions; narrow navigation acceptance follows the browser validation skill without the Replica canvas preflight. A disconnected Hub is not the same as an unavailable canvas and does not prevent a local preview. ## Connect the Replica canvas @@ -225,11 +222,9 @@ Keep only one Replica provider active. ### Canvas preflight -Agents complete this gate before UI edits, prototype preview, publishing or Hub -comment work. When `replica-prototype` is available, discover its capabilities -and use the existing provider without reinstalling or updating it. If several -providers are available, ask which to keep before changing plugin or extension -settings. +Agents complete this gate before ordinary UI edits, prototype preview, publishing or Hub comment work. Source-only tasks and eligible [narrow edits](AGENTS.md#narrow-edits) do not require this preflight unless the user requests an authorized canvas operation. + +When `replica-prototype` is available, discover its capabilities before the first required operation and reuse the same-provider schema in this session. Rediscover after a provider reload/reconnect, schema mismatch or explicit request to check for changed capabilities; a timeout alone does not invalidate a schema. Use the existing provider without reinstalling or updating it. If several providers are available, ask which to keep before changing plugin or extension settings. When the canvas is missing in a canvas-capable host, stop before UI edits or preview startup and tell the user: Open **Customization**, select **Installed**