docs(starter): streamline authoring and browser workflows (#29) · github/replica@051d70e · GitHub
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

‎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

0 commit comments

Comments
 (0)