Skip to content

Commit 051d70e

Browse 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
1 parent 8a74960 commit 051d70e

9 files changed

Lines changed: 109 additions & 107 deletions

File tree

‎starter/.agents/context-templates/BROWSER-VALIDATION.md‎

Lines changed: 4 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -30,10 +30,9 @@ alone does not prove application bootstrap or route readiness.
3030

3131
## Canvas host and identifiers
3232

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.
3736

3837
Keep `canvasId` and `instanceId` distinct. Actions addressed by the panel handle
3938
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.
105104
Link lifecycle policy in [REPOSITORY.md](./REPOSITORY.md). Do not install tools,
106105
repair daemons, create auth or start undeclared infrastructure during validation.
107106

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.
115108

116109
If MCP is unavailable, report the actual blocker, repository trust/fresh-session
117110
setup and remaining checks as unverified. Do not silently install browser engines.

‎starter/.agents/context-templates/DESIGN-SYSTEM.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -29,8 +29,7 @@ and tasks belong in [RESPONSIVE-DESIGN.md](./RESPONSIVE-DESIGN.md).
2929

3030
## Navigation primitives
3131

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.
3433

3534
## Forms
3635

‎starter/.agents/skills/browser-canvas-validation/SKILL.md‎

Lines changed: 9 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -27,30 +27,26 @@ If a required companion or sibling skill is missing, stop and name its path
2727
before checks. Do not auto-install dependencies.
2828

2929
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.
3335

3436
Missing required context stops validation. Report the selected root/file and
3537
offer `setup-skills` to author or refresh context under the shared
3638
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.
4140

4241
Use only permitted sources. Do not research remotely or broaden exclusions
4342
during validation. Request explicit refresh if required documentation is stale
4443
or missing. A document with gaps does not prove runtime capabilities.
4544

4645
## Runtime contract
4746

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.
5450

5551
Keep the canvas type and caller-chosen `instanceId` handle distinct.
5652
Address the panel with that handle through `invoke_canvas_action`. If the

‎starter/.agents/skills/browser-canvas-validation/WORKFLOW.md‎

Lines changed: 8 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,9 @@
22

33
## Browser selection
44

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.
108

119
Use configured Playwright MCP only when the canvas is unavailable for the
1210
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
2624
target is a blocker unless starting the declared server is already authorized.
2725
Never start a second infrastructure project to supply validation.
2826

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.
3528

3629
## Discover, read, act, assert
3730

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.
4134
Action inputs follow the discovered schema. When an action takes only the panel
4235
handle and its advertised inputs, invoke it directly without page acquisition.
4336
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
7669
and relevant behavior. If content is missing, use supported reload and re-read
7770
once before reporting stale rendering.
7871

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.
8273
For further failures use only the repository's authorized recovery procedure.
8374
Do not replay a timed-out state-changing action, its effect may already have
8475
occurred. Inspect resulting state first. Restarting servers, installing packages

‎starter/.agents/skills/create-prototype/SKILL.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,9 @@ prototype" is iteration.
2222
| ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
2323
| Clear new build, such as "build an offline inventory prototype" | [create](./workflows/create.md) |
2424
| 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 |
2526
| 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 |
2628
| Unrelated task or routine command | Stop using this skill and continue the original task |
2729

2830
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,
4042
publish, delete or activate anything. Approved references are 1:1 requirements
4143
except for the requested delta, not design inspiration.
4244

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.
4549
It owns context resolution, design evidence, data boundaries and completion.
4650
It does not load another workflow. Install `product-design`, `setup-skills`
4751
and the `context-templates` library alongside this skill.

‎starter/.agents/skills/create-prototype/references/authoring.md‎

Lines changed: 15 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -7,11 +7,17 @@ This reference does not dispatch or load workflow companions.
77

88
Read [context resolution](../../product-design/references/context-resolution.md).
99
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.
1521

1622
Read shared defaults, safety rules, relevant headings and limitations.
1723
Follow relevant owner links, evidence anchors and local documentation indexes
@@ -29,10 +35,7 @@ installed files, including this reference or
2935
[product-design](../../product-design/SKILL.md), stop affected work with the
3036
exact path. Do not install dependencies or invent fallback policy.
3137

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.
3639

3740
## Task inputs, not setup requirements
3841

@@ -78,6 +81,7 @@ named page or a catalog example is the target implementation.
7881

7982
Use the active design-system context's declared evidence sources, installed
8083
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.
8185
When a named gap requires source inspection, read full relevant component,
8286
token and pattern sections, including accessibility requirements, not whole catalogues.
8387
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
96100
from a token name or substitute another provider. Use existing supported
97101
compositions rather than recreating primitives.
98102

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+
99105
Stop API discovery once the selected import, composition, required props, states,
100106
narrow behavior and keyboard/focus contract are established for this task.
101107
Evidence may combine approved guidance and installed source; implementation

0 commit comments

Comments
 (0)