You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 051d70e
Browse filesBrowse the repository at this point in the historyBrowse files
docs(starter): streamline authoring and browser workflows (#29)
## Why
Agent workflows currently repeat repository and browser setup for small,
fully specified changes, and they can inspect unchanged design-system
evidence more broadly than needed. This slows focused work without
improving confidence, while the normal safety and quality checks remain
essential for substantive UI changes.
## What changes
The starter now distinguishes behavior-preserving test-only work and
tightly bounded narrow edits from full prototype iterations. It scopes
context reads to the task, resolves JavaScript package APIs through
installed package metadata, reuses an established composition before
optional recipe research, and avoids repeating design decisions or
launching unrelated reviews.
Browser guidance now reuses same-provider schemas within a session,
avoids capability discovery for source-only work, and selects repository
and product context by the validation task. It keeps authorization,
readiness, fresh rendered state, bounded recovery and fallback
requirements intact. The design-system context template also explains
when standalone links do not need research into unrelated composite
navigation patterns.
Copilot-Session: 1b58255f-30de-4528-8072-7441ea94f202
Copy file name to clipboardExpand all lines: starter/.agents/context-templates/BROWSER-VALIDATION.md
+4-11Lines changed: 4 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -30,10 +30,9 @@ alone does not prove application bootstrap or route readiness.
30
30
31
31
## Canvas host and identifiers
32
32
33
-
Find the intended Copilot host, handle reuse and page-identifier contracts.
34
-
Record where runtime identifiers come from, not universal fixed IDs. Runtime
35
-
discovery is authoritative for current schemas and actions. Configuration is
36
-
not availability. Missing canvas support does not authorize silent substitution.
33
+
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.
34
+
35
+
Configuration is not availability. Missing canvas support does not authorize silent substitution.
37
36
38
37
Keep `canvasId` and `instanceId` distinct. Actions addressed by the panel handle
39
38
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.
105
104
Link lifecycle policy in [REPOSITORY.md](./REPOSITORY.md). Do not install tools,
106
105
repair daemons, create auth or start undeclared infrastructure during validation.
107
106
108
-
Allow one bounded same-panel recovery attempt: check documented readiness,
109
-
refocus the same owned instance, rediscover schemas, and retry inspection once
110
-
only if required runtime identifiers are available. Do not loop or open duplicate
111
-
panels. A timed-out interaction may already have succeeded; inspect its resulting
112
-
state before considering another action. Do not restart a healthy server because
113
-
its canvas timed out. A separate MCP browser starts with a fresh read of the
114
-
authorized route, not a replay or an assumption of shared state.
107
+
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.
115
108
116
109
If MCP is unavailable, report the actual blocker, repository trust/fresh-session
117
110
setup and remaining checks as unverified. Do not silently install browser engines.
Copy file name to clipboardExpand all lines: starter/.agents/context-templates/DESIGN-SYSTEM.md
+1-2Lines changed: 1 addition & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -29,8 +29,7 @@ and tasks belong in [RESPONSIVE-DESIGN.md](./RESPONSIVE-DESIGN.md).
29
29
30
30
## Navigation primitives
31
31
32
-
Distinguish tabs, breadcrumbs, side navigation, and action menus. Verify link
33
-
versus button semantics, selection and focus behavior. Product owns destinations.
32
+
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.
Copy file name to clipboardExpand all lines: starter/.agents/skills/browser-canvas-validation/SKILL.md
+9-13Lines changed: 9 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -27,30 +27,26 @@ If a required companion or sibling skill is missing, stop and name its path
27
27
before checks. Do not auto-install dependencies.
28
28
29
29
Select the first existing root, `.agents/context/`, then `.github/contexts/`.
30
-
Read `PRODUCT-DESIGN.md`, `REPOSITORY.md` and `BROWSER-VALIDATION.md`
31
-
directly there. Read `DESIGN-SYSTEM.md` for component-specific assertions.
32
-
No manifest or canvas-specific pack file is required. Never mix roots.
30
+
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.
31
+
32
+
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.
33
+
34
+
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.
33
35
34
36
Missing required context stops validation. Report the selected root/file and
35
37
offer `setup-skills` to author or refresh context under the shared
36
38
resolution rules. Do not invoke it
37
-
automatically. Never read drafts as active context. Follow relevant owner links
38
-
and evidence anchors, preserve `proposed-default` labels and disclose conflicts.
39
-
Read current owner guidance on every run. Product context owns scenarios and
40
-
state policy. Browser context owns target URL, server, routes and recovery.
39
+
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.
41
40
42
41
Use only permitted sources. Do not research remotely or broaden exclusions
43
42
during validation. Request explicit refresh if required documentation is stale
44
43
or missing. A document with gaps does not prove runtime capabilities.
45
44
46
45
## Runtime contract
47
46
48
-
Discover the available canvas types. If `browser` or the necessary canvas tools
49
-
are absent, report the missing runtime and stop this path, not a pass or a silent
50
-
backend substitution. Use the explicit configured MCP handoff in
51
-
[WORKFLOW.md](./WORKFLOW.md) if available. Call `list_canvas_capabilities` for the actual browser
52
-
type before opening or acting. Use its advertised open input and action schemas.
53
-
No frozen action list in this skill overrides the runtime.
47
+
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.
48
+
49
+
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.
54
50
55
51
Keep the canvas type and caller-chosen `instanceId` handle distinct.
56
52
Address the panel with that handle through `invoke_canvas_action`. If the
Copy file name to clipboardExpand all lines: starter/.agents/skills/browser-canvas-validation/WORKFLOW.md
+8-17Lines changed: 8 additions & 17 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,11 +2,9 @@
2
2
3
3
## Browser selection
4
4
5
-
Use the browser canvas first for every agent-driven rendered check, interaction
6
-
test, screenshot and visual, responsive or accessibility review. Discover its
7
-
current capabilities rather than assuming an earlier host's limitations.
8
-
The Replica prototype canvas remains the preview and publishing surface;
9
-
discover the separate browser canvas for page inspection.
5
+
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.
6
+
7
+
The Replica prototype canvas remains the preview and publishing surface; use the separate browser canvas for page inspection.
10
8
11
9
Use configured Playwright MCP only when the canvas is unavailable for the
@@ -26,18 +24,13 @@ derive branch instance IDs from another repository's scripts. A missing running
26
24
target is a blocker unless starting the declared server is already authorized.
27
25
Never start a second infrastructure project to supply validation.
28
26
29
-
Read the requested outcome and product-design scenario/state owner. Establish
30
-
expected results before interacting. Use the smallest connected flow that proves
31
-
the request. Invalid-input submission, destination and reload-persistence checks
32
-
apply when the requested behavior needs them and test mutations are authorized.
33
-
Otherwise report those assertions untested. Do not submit real data to prove a
34
-
read-only audit, or treat a disabled button alone as proof of safe persistence.
27
+
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.
35
28
36
29
## Discover, read, act, assert
37
30
38
-
Inspect browser canvas capabilities and satisfy the actual schemas as described
39
-
in [SKILL.md](./SKILL.md). Call `open_canvas` with the declared type and a session
40
-
handle. Use `invoke_canvas_action` with that same handle to address the instance.
31
+
Use browser canvas capabilities and schemas as described in [SKILL.md](./SKILL.md).
32
+
Call `open_canvas` with the declared type and a session handle. Use
33
+
`invoke_canvas_action` with that same handle to address the instance.
41
34
Action inputs follow the discovered schema. When an action takes only the panel
42
35
handle and its advertised inputs, invoke it directly without page acquisition.
43
36
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
76
69
and relevant behavior. If content is missing, use supported reload and re-read
77
70
once before reporting stale rendering.
78
71
79
-
A read timeout can be retried once after checking the declared readiness signal.
80
-
Refocus the same owned panel, rediscover capabilities and retry inspection only
81
-
with valid required identifiers. Do not loop or create duplicate panels.
72
+
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.
82
73
For further failures use only the repository's authorized recovery procedure.
83
74
Do not replay a timed-out state-changing action, its effect may already have
84
75
occurred. Inspect resulting state first. Restarting servers, installing packages
| Clear new build, such as "build an offline inventory prototype" |[create](./workflows/create.md)|
24
24
| Change to an existing prototype, such as "add filtering to this page" |[iterate](./workflows/iterate.md)|
25
+
| Candidate narrow edit to an existing prototype |[iterate](./workflows/iterate.md), then apply the root instructions' narrow-edit path |
25
26
| Consequential missing information, including an unresolved target or create-versus-iterate choice |[clarify](./workflows/clarify.md), then the selected build or iteration workflow |
27
+
| Behavior-preserving test-only work | Use the root instructions' task-scope guidance; do not load a prototype workflow |
26
28
| Unrelated task or routine command | Stop using this skill and continue the original task |
27
29
28
30
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,
40
42
publish, delete or activate anything. Approved references are 1:1 requirements
41
43
except for the requested delta, not design inspiration.
42
44
43
-
The selected workflow reads the shared
44
-
[authoring reference](./references/authoring.md) before implementation.
45
+
The selected create or normal iteration workflow reads the shared
46
+
[authoring reference](./references/authoring.md) before implementation. A
47
+
candidate narrow edit follows the iteration workflow's classification step and,
48
+
when eligible, skips that reference and its context dependencies.
45
49
It owns context resolution, design evidence, data boundaries and completion.
46
50
It does not load another workflow. Install `product-design`, `setup-skills`
47
51
and the `context-templates` library alongside this skill.
Select the first existing root, `.agents/context/`, then `.github/contexts/`.
10
-
Read `DESIGN-SYSTEM.md`, `PRODUCT-DESIGN.md`, `REPOSITORY.md` and
11
-
`BROWSER-VALIDATION.md` directly there. No manifest or prototype-specific pack
12
-
file is required. Never mix roots or read drafts as active context.
13
-
Read `SEED-DATA.md` for new or changed fixtures, `RESPONSIVE-DESIGN.md` for
14
-
responsive decisions and `ACCESSIBILITY.md` for product accessibility environments.
10
+
For application work, read the applicable sections of these owners and follow relevant topic links:
11
+
12
+
-`REPOSITORY.md`: `Where UI lives`, `Commands` and `Constraints`.
13
+
-`DESIGN-SYSTEM.md`: shared defaults and task-relevant sections before component, token or pattern decisions.
14
+
-`PRODUCT-DESIGN.md`: when creating or changing behavior, states, flows, messaging or product decisions.
15
+
-`BROWSER-VALIDATION.md`: before starting a preview or performing rendered validation.
16
+
-`SEED-DATA.md`: for new or changed fixtures; `RESPONSIVE-DESIGN.md`: for responsive decisions; `ACCESSIBILITY.md`: for product accessibility environments.
17
+
18
+
If a consumer uses different headings, select the equivalent sections by owner rather than reading the entire file.
19
+
20
+
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.
15
21
16
22
Read shared defaults, safety rules, relevant headings and limitations.
17
23
Follow relevant owner links, evidence anchors and local documentation indexes
@@ -29,10 +35,7 @@ installed files, including this reference or
29
35
[product-design](../../product-design/SKILL.md), stop affected work with the
30
36
exact path. Do not install dependencies or invent fallback policy.
31
37
32
-
Use product-design's workflow for relevant UI decisions and convert its
33
-
context-backed behavior into implementation checks. Unrelated known gaps do
34
-
not block supported work. Consequential contradictions or missing rules remain
35
-
unresolved and return to the selected workflow's conditional clarification.
38
+
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.
36
39
37
40
## Task inputs, not setup requirements
38
41
@@ -78,6 +81,7 @@ named page or a catalog example is the target implementation.
78
81
79
82
Use the active design-system context's declared evidence sources, installed
80
83
APIs and fallback rules under context resolution's applied-guidance contract.
84
+
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.
81
85
When a named gap requires source inspection, read full relevant component,
82
86
token and pattern sections, including accessibility requirements, not whole catalogues.
83
87
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
96
100
from a token name or substitute another provider. Use existing supported
97
101
compositions rather than recreating primitives.
98
102
103
+
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.
104
+
99
105
Stop API discovery once the selected import, composition, required props, states,
100
106
narrow behavior and keyboard/focus contract are established for this task.
101
107
Evidence may combine approved guidance and installed source; implementation
0 commit comments