docs(plan): modern web guidance, Read-only skill, no routing row, sub-agent path

This commit is contained in:
bchanot committed 2026-11-22 00:38:02 +01:00
1 parent ea1d5ab400
commit 79a48f76c1
2 files changed
+120 -83

No files matched your search

@@ -4,7 +4,7 @@
**Goal:** Vendor Google's Modern Web Guidance (guides + chrome-extensions) at a pinned commit and make every front-end task consult it through our own local, network-free skill. **Goal:** Vendor Google's Modern Web Guidance (guides + chrome-extensions) at a pinned commit and make every front-end task consult it through our own local, network-free skill.
**Architecture:** A new `vendor_pinned_tree` helper in `lib/vendor-skills.sh` fetches one pinned commit with git, copies an allowlist of upstream paths into `skills-external/<dest>/`, generates `INDEX.md` / `NOTICE.md` / `.vendored-commit`, and swaps the result in. Our tracked skill `skills/modern-web-guidance/` reaches the guides through relative symlinks and only uses Read/Grep/Glob. `rules/web-building.md` and `site-motion` send front-end work to the skill. **Architecture:** A new `vendor_pinned_tree` helper in `lib/vendor-skills.sh` fetches one pinned commit with git, copies an allowlist of upstream paths into `skills-external/<dest>/`, generates `INDEX.md` / `NOTICE.md` / `.vendored-commit`, and swaps the result in. Our tracked skill `skills/modern-web-guidance/` reaches the guides through relative symlinks and needs only Read (Grep and Glob are absent in some sessions). `rules/web-building.md` and `site-motion` send front-end work to the skill; a sub-agent without the Skill tool Reads its `SKILL.md` by path.
**Tech Stack:** bash, python3 (lock parsing, argv only), git, markdown. **Tech Stack:** bash, python3 (lock parsing, argv only), git, markdown.
@@ -16,7 +16,9 @@ Out of this plan, done by `/ship-feature` itself: README / USAGE / CHANGELOG (ST
## Global Constraints ## Global Constraints
- Pin: tag `v1.0.1`, commit `64a6d708f5a43f2cd3fde5d4d7db3905ba1bdf65`, source `https://github.com/GoogleChrome/modern-web-guidance`. - Pin: tag `v1.0.1`, commit `64a6d708f5a43f2cd3fde5d4d7db3905ba1bdf65`, source `https://github.com/GoogleChrome/modern-web-guidance`.
- No path of this feature runs `npx`, `pnpx` or the `modern-web-guidance` CLI; the skill's `allowed-tools` is `Read, Grep, Glob` only. - No path of this feature runs `npx`, `pnpx` or the `modern-web-guidance` CLI. The skill's `allowed-tools` is `Read`: it only pre-approves Read for the invoking turn, it does not restrict tools (Claude Code skills docs). The no-npx guarantee rests on the skill's "Never run npx" sentence, the absence of any command in it, and the settings soft-deny on undeclared `npx <pkg>`.
- No `routing.json` row and no `effort:` frontmatter for `modern-web-guidance` or `chrome-extensions`: a rowed skill reroutes the main loop on load ("last rowed skill wins", `mods/model-router/hooks/register.ts` onSkillLoad), which would pull design work off `reflect`. `modern-web-guidance` joins `NO_ROW_SKILLS` in `lib/tests/effort-routing.test.sh` (precedent: `find-docs`); `chrome-extensions` is an untracked linked external, the census does not ask for a row.
- Skill description at most 400 characters (listing budget `SLASH_COMMAND_TOOL_CHAR_BUDGET=50000`, ~34.5k already used by flat + pack descriptions).
- The upstream `skills/modern-web-guidance/SKILL.md` is never copied into `skills-external/`. - The upstream `skills/modern-web-guidance/SKILL.md` is never copied into `skills-external/`.
- Vendored text is never edited (BDR-104/106). - Vendored text is never edited (BDR-104/106).
- `CLAUDE.global.md`, `settings.json`, `CLAUDE.md` are not modified (BDR-028, 320-line budget). - `CLAUDE.global.md`, `settings.json`, `CLAUDE.md` are not modified (BDR-028, 320-line budget).
@@ -31,6 +33,18 @@ Out of this plan, done by `/ship-feature` itself: README / USAGE / CHANGELOG (ST
3. A machine that never ran `make plugin` → `make update` (refresh mode) installs the copy instead of skipping it. 3. A machine that never ran `make plugin` → `make update` (refresh mode) installs the copy instead of skipping it.
4. A lock entry with `..`, an absolute path or a bad dest name → rejected before any fetch. 4. A lock entry with `..`, an absolute path or a bad dest name → rejected before any fetch.
5. Fresh clone before install → our skill's symlinks dangle; the skill says "run `make update`" and doctor warns (no error). 5. Fresh clone before install → our skill's symlinks dangle; the skill says "run `make update`" and doctor warns (no error).
6. A sub-agent executor (feater, bugfixer, hotfixer: no Skill tool in their `tools:`) Reads a front file → the path rule tells it to Read `~/.claude/skills/modern-web-guidance/SKILL.md` and follow it; the relative links resolve through the `~/.claude/skills` link (checked on a fixture: kernel resolves `../..` from the link's real directory).
## Contract oracles (draft, written into the contract at STEP 3 with `- run-base:`)
1. Pin + install wiring + local copy at the pin, 210 guides, no upstream SKILL.md:
CHECK: `python3 -c "import json;e=json.load(open('plugins.lock.json'))['modern-web-guidance'];assert e['commit']=='64a6d708f5a43f2cd3fde5d4d7db3905ba1bdf65' and e['tag']=='v1.0.1'" && grep -q '^vendor_pinned_tree modern-web-guidance$' install-plugins.sh && grep -q '^vendor_pinned_tree modern-web-guidance refresh$' update-all.sh && [ "$(cat skills-external/mwg/.vendored-commit)" = 64a6d708f5a43f2cd3fde5d4d7db3905ba1bdf65 ] && [ "$(grep -c '^- ' skills-external/mwg/INDEX.md)" -eq 210 ] && [ -f skills-external/chrome-extensions/SKILL.md ] && [ ! -e skills-external/mwg/SKILL.md ] && make test suite=lib/tests/vendor-tree.test.sh 2>&1 | tail -1` → EXPECT `all suites green`
2. Our skill, local read only, disclosure: CHECK `make test suite=lib/tests/mwg-skill.test.sh 2>&1 | tail -1` → EXPECT `all suites green`
3. Rule wiring: CHECK `grep -qx '## Modern Web Guidance first' rules/web-building.md && grep -q '~/.claude/skills/modern-web-guidance/SKILL.md' rules/web-building.md && grep -q 'consult `modern-web-guidance` first' rules/web-building.md && echo WIRED` → EXPECT `WIRED`
4. Upstream SKILL.md not linked: CHECK `! grep -l 'modern-web-guidance@latest search' ~/.claude/skills/*/SKILL.md 2>/dev/null | grep -q . && [ -L ~/.claude/skills/chrome-extensions ] && echo NOT_LINKED` → EXPECT `NOT_LINKED`
5. Suite and doctor: CHECK `make test 2>&1 | tail -1` → EXPECT `all suites green`; CHECK `bash doctor.sh 2>&1 | grep -q 'No errors' && echo DOCTOR_OK` → EXPECT `DOCTOR_OK` (baseline 2026-11-22: "No errors, 2 warning(s)").
Oracles 1, 4 and 5 need the live copy: Task 5 runs after Task 4 and before the STEP 5 gates.
--- ---
@@ -103,11 +117,12 @@ write_lock() { # write_lock <commit> [extra-tree-json]
} }
JSON JSON
} }
run() { # run <args…> — sources the lib in a subshell against the fixture # Same pattern as vendor-skills.test.sh: export once, source once (the lib
( export VENDOR_SKILLS_REPO_OVERRIDE="$REPO" VENDOR_BASE_URL="file://$UP" # reads VENDOR_SKILLS_REPO_OVERRIDE at source time), override per call.
# shellcheck disable=SC1090 export VENDOR_SKILLS_REPO_OVERRIDE="$REPO" VENDOR_BASE_URL="file://$UP"
source "$LIB"; vendor_pinned_tree "$@" ) >"$WORK/out" 2>&1 # shellcheck source=../vendor-skills.sh disable=SC1091
} source "$LIB"
run() { vendor_pinned_tree "$@" >"$WORK/out" 2>&1; }
# T1 install: allowlisted copy, generated files, no upstream SKILL.md. # T1 install: allowlisted copy, generated files, no upstream SKILL.md.
write_lock "$SHA1"; run mwg-key; rc=$? write_lock "$SHA1"; run mwg-key; rc=$?
@@ -121,11 +136,10 @@ check_bool T1-index-count "$([ "$(grep -c '^- ' "$M/INDEX.md")" -eq 3 ] && echo
check_bool T1-notice "$(grep -q "$SHA1" "$M/NOTICE.md" && grep -q 'CC-BY 4.0' "$M/NOTICE.md" && echo 1)" check_bool T1-notice "$(grep -q "$SHA1" "$M/NOTICE.md" && grep -q 'CC-BY 4.0' "$M/NOTICE.md" && echo 1)"
check_bool T1-marker "$([ "$(cat "$M/.vendored-commit")" = "$SHA1" ] && echo 1)" check_bool T1-marker "$([ "$(cat "$M/.vendored-commit")" = "$SHA1" ] && echo 1)"
check_bool T1-ce-contents "$([ -f "$C/SKILL.md" ] && [ -f "$C/references/extensions/api.md" ] && echo 1)" check_bool T1-ce-contents "$([ -f "$C/SKILL.md" ] && [ -f "$C/references/extensions/api.md" ] && echo 1)"
check_bool T1-no-stage-left "$([ -z "$(ls -A "$REPO/skills-external" | grep '^\.vendor-stage')" ] && echo 1)" check_bool T1-no-stage-left "$(compgen -G "$REPO/skills-external/.vendor-stage.*" >/dev/null || echo 1)"
# T2 install mode at the pin: skip, no fetch (source made unreachable). # T2 install mode at the pin: skip, no fetch (source made unreachable).
( export VENDOR_SKILLS_REPO_OVERRIDE="$REPO" VENDOR_BASE_URL="file://$WORK/nowhere" VENDOR_BASE_URL="file://$WORK/nowhere" vendor_pinned_tree mwg-key >"$WORK/out" 2>&1; rc=$?
source "$LIB"; vendor_pinned_tree mwg-key ) >"$WORK/out" 2>&1; rc=$?
check_bool T2-skip-rc "$([ $rc -eq 0 ] && grep -q 'already at pin' "$WORK/out" && echo 1)" check_bool T2-skip-rc "$([ $rc -eq 0 ] && grep -q 'already at pin' "$WORK/out" && echo 1)"
# T3 refresh after an upstream drop: old-guide disappears locally. # T3 refresh after an upstream drop: old-guide disappears locally.
@@ -161,8 +175,7 @@ check_bool T8-missing-path "$([ $rc -eq 1 ] && [ ! -e "$REPO/skills-external/gho
# T9 a non-file:// VENDOR_BASE_URL is ignored with a warn. # T9 a non-file:// VENDOR_BASE_URL is ignored with a warn.
write_lock "$SHA2" write_lock "$SHA2"
( export VENDOR_SKILLS_REPO_OVERRIDE="$REPO" VENDOR_BASE_URL="https://evil.example" VENDOR_BASE_URL="https://evil.example" vendor_pinned_tree mwg-key >"$WORK/out" 2>&1
source "$LIB"; vendor_pinned_tree mwg-key ) >"$WORK/out" 2>&1
check_bool T9-override-ignored "$(grep -q 'VENDOR_BASE_URL ignored' "$WORK/out" && echo 1)" check_bool T9-override-ignored "$(grep -q 'VENDOR_BASE_URL ignored' "$WORK/out" && echo 1)"
echo "vendor-tree: $pass pass, $fail fail" echo "vendor-tree: $pass pass, $fail fail"
@@ -289,8 +302,12 @@ _vendor_tree_index() {
local dir="$1" f id category title local dir="$1" f id category title
[ -d "$dir/guides" ] || return 0 [ -d "$dir/guides" ] || return 0
{ {
printf '# Guide index\n\nOne line per guide: `id | category | title`.' cat <<'EOF'
printf ' Read `guides/<category>/<id>.md`.\n\n' # Guide index
One line per guide: `id | category | title`. Read `guides/<category>/<id>.md`.
EOF
find "$dir/guides" -type f -name '*.md' | LC_ALL=C sort \ find "$dir/guides" -type f -name '*.md' | LC_ALL=C sort \
| while IFS= read -r f; do | while IFS= read -r f; do
id="$(basename "$f" .md)" id="$(basename "$f" .md)"
@@ -392,8 +409,8 @@ Swap failure note: `_vendor_tree_swap` moves dests one by one; a failure after t
- [ ] **Step 4: Run the suite** - [ ] **Step 4: Run the suite**
Run: `make test suite=lib/tests/vendor-tree.test.sh` Run: `make test suite=lib/tests/vendor-tree.test.sh`
Expected: every line `PASS …`, `vendor-tree: 21 pass, 0 fail`, `all suites green`. Expected: every line `PASS …`, `vendor-tree: 21 pass, 0 fail`, `all suites green` (simulated on a scratch clone 2026-11-22: 21/21).
Then: `shellcheck lib/vendor-skills.sh lib/tests/vendor-tree.test.sh` → no output. Then: `shellcheck lib/vendor-skills.sh lib/tests/vendor-tree.test.sh` → no output (simulated: clean).
Then the old suite still green: `make test suite=lib/tests/vendor-skills.test.sh` → `all suites green`. Then the old suite still green: `make test suite=lib/tests/vendor-skills.test.sh` → `all suites green`.
- [ ] **Step 5: Commit** - [ ] **Step 5: Commit**
@@ -572,12 +589,12 @@ git commit -m "feat(vendor): pin Modern Web Guidance v1.0.1 and chrome-extension
--- ---
### Task 3: Our `modern-web-guidance` skill + routing rows ### Task 3: Our `modern-web-guidance` skill (no routing row)
**Files:** **Files:**
- Create: `skills/modern-web-guidance/SKILL.md`, `skills/modern-web-guidance/test-prompts.json` - Create: `skills/modern-web-guidance/SKILL.md`, `skills/modern-web-guidance/test-prompts.json`
- Create (tracked symlinks): `skills/modern-web-guidance/guides`, `skills/modern-web-guidance/INDEX.md`, `skills/modern-web-guidance/NOTICE.md` - Create (tracked symlinks): `skills/modern-web-guidance/guides`, `skills/modern-web-guidance/INDEX.md`, `skills/modern-web-guidance/NOTICE.md`
- Modify: `mods/model-router/routing.json` (`skills` object) - Modify: `lib/tests/effort-routing.test.sh:141` (`NO_ROW_SKILLS` gains `modern-web-guidance`)
- Test: `lib/tests/mwg-skill.test.sh` - Test: `lib/tests/mwg-skill.test.sh`
**Interfaces:** **Interfaces:**
@@ -588,28 +605,33 @@ git commit -m "feat(vendor): pin Modern Web Guidance v1.0.1 and chrome-extension
```bash ```bash
#!/usr/bin/env bash #!/usr/bin/env bash
# lib/tests/mwg-skill.test.sh — skills/modern-web-guidance: read-only # lib/tests/mwg-skill.test.sh — skills/modern-web-guidance: Read is the
# tools, no npx or network command anywhere in a fenced block, the three # only pre-approved tool, no effort pin and no routing.json row (a row
# relative links into skills-external/mwg, the disclosure format, and a # reroutes the main loop on load), no npx or network command in a fenced
# routing.json row. # block, the three relative links into skills-external/mwg, the
# disclosure format, a description within the listing budget.
set -u set -u
ROOT="$(cd "$(dirname "$0")/../.." && pwd)" ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
S="$ROOT/skills/modern-web-guidance" S="$ROOT/skills/modern-web-guidance"
pass=0; fail=0 pass=0; fail=0
check() { if [ "$2" = 1 ]; then pass=$((pass+1)); echo "PASS $1"; else fail=$((fail+1)); echo "FAIL $1"; fi; } check() { if [ "$2" = 1 ]; then pass=$((pass+1)); echo "PASS $1"; else fail=$((fail+1)); echo "FAIL $1"; fi; }
fm() { awk '/^---$/{n++; next} n==1' "$S/SKILL.md"; }
check exists "$([ -f "$S/SKILL.md" ] && echo 1)" check exists "$([ -f "$S/SKILL.md" ] && echo 1)"
check tools "$(grep -qx 'allowed-tools: Read, Grep, Glob' "$S/SKILL.md" && echo 1)" check tools "$(fm | grep -qx 'allowed-tools: Read' && echo 1)"
check no-bash "$(grep -q '^allowed-tools:.*Bash' "$S/SKILL.md" || echo 1)" check no-effort "$(fm | grep -q '^effort:' || echo 1)"
fenced_npx="$(awk '/^```/{f=!f; next} f' "$S/SKILL.md" | grep -c 'npx\|pnpx\|curl\|wget')" desc_len="$(fm | awk '/^description:/{f=1; next} /^[a-z-]+:/{f=0} f' | tr -s ' \n' ' ' | wc -c)"
check no-fenced-network "$([ "$fenced_npx" -eq 0 ] && echo 1)" check desc-budget "$([ "$desc_len" -gt 100 ] && [ "$desc_len" -le 400 ] && echo 1)"
fenced="$(awk '/^```/{f=!f; next} f' "$S/SKILL.md" | grep -c 'npx\|pnpx\|curl\|wget')"
check no-fenced-network "$([ "$fenced" -eq 0 ] && echo 1)"
check never-run "$(grep -q 'Never run npx' "$S/SKILL.md" && echo 1)" check never-run "$(grep -q 'Never run npx' "$S/SKILL.md" && echo 1)"
check read-index "$(grep -q 'Read `INDEX.md` whole' "$S/SKILL.md" && echo 1)"
check disclosure "$(grep -q '`Modern Web Guidance: <id>, <id>`' "$S/SKILL.md" && echo 1)" check disclosure "$(grep -q '`Modern Web Guidance: <id>, <id>`' "$S/SKILL.md" && echo 1)"
for l in guides:../../skills-external/mwg/guides INDEX.md:../../skills-external/mwg/INDEX.md NOTICE.md:../../skills-external/mwg/NOTICE.md; do for l in guides:../../skills-external/mwg/guides INDEX.md:../../skills-external/mwg/INDEX.md NOTICE.md:../../skills-external/mwg/NOTICE.md; do
check "link-${l%%:*}" "$([ -L "$S/${l%%:*}" ] && [ "$(readlink "$S/${l%%:*}")" = "${l#*:}" ] && echo 1)" check "link-${l%%:*}" "$([ -L "$S/${l%%:*}" ] && [ "$(readlink "$S/${l%%:*}")" = "${l#*:}" ] && echo 1)"
done done
check tracked-links "$([ "$(cd "$ROOT" && git ls-files skills/modern-web-guidance | grep -c 'guides$\|INDEX.md$\|NOTICE.md$')" -eq 3 ] && echo 1)" check tracked-links "$([ "$(cd "$ROOT" && git ls-files skills/modern-web-guidance | grep -c 'guides$\|INDEX.md$\|NOTICE.md$')" -eq 3 ] && echo 1)"
row="$(python3 -c "import json,sys;print(json.load(open(sys.argv[1]))['skills'].get('modern-web-guidance',''))" "$ROOT/mods/model-router/routing.json")" check no-routing-row "$(grep -q '"modern-web-guidance"\|"chrome-extensions"' "$ROOT/mods/model-router/routing.json" || echo 1)"
check routing-row "$([ "$row" = explore ] && echo 1)" check no-row-listed "$(grep -q '^NO_ROW_SKILLS=".* modern-web-guidance ' "$ROOT/lib/tests/effort-routing.test.sh" && echo 1)"
check prompts "$(python3 -c "import json,sys;d=json.load(open(sys.argv[1]));sys.exit(0 if len(d)>=3 else 1)" "$S/test-prompts.json" && echo 1)" check prompts "$(python3 -c "import json,sys;d=json.load(open(sys.argv[1]));sys.exit(0 if len(d)>=3 else 1)" "$S/test-prompts.json" && echo 1)"
echo "mwg-skill: $pass pass, $fail fail" echo "mwg-skill: $pass pass, $fail fail"
[ "$fail" -eq 0 ] [ "$fail" -eq 0 ]
@@ -626,49 +648,46 @@ Run: `make test suite=lib/tests/mwg-skill.test.sh` → `FAIL exists` etc.
````markdown ````markdown
--- ---
name: modern-web-guidance name: modern-web-guidance
effort: medium description: >-
description: | Current web-platform practice from Google's Modern Web Guidance, read
Current web-platform practice from Google's Modern Web Guidance (Chrome, from a pinned local copy. Use FIRST, before writing or changing
Edge, Firefox and MDN teams), read from a pinned local copy. Run it FIRST, front-end code: HTML, CSS, client-side JS, UI components, forms,
before writing or changing front-end code: HTML, CSS, client-side JS, UI dialogs, layout, motion, Core Web Vitals, images, accessibility. Not
components in any framework. Covers dialogs, popovers, forms and for backend, infra, build tooling or tests.
validation, tables, dark mode, container queries, anchor positioning, view allowed-tools: Read
transitions, scroll-driven animation, Core Web Vitals (LCP, INP, CLS),
images, passkeys, sanitization, web components, dates and time zones,
built-in AI. Not for backend, infra, build tooling or tests.
allowed-tools: Read, Grep, Glob
--- ---
# Modern Web Guidance (local, pinned) # Modern Web Guidance (local, pinned)
The guides sit in this skill's folder: `INDEX.md` (one line per guide, This folder (`~/.claude/skills/modern-web-guidance/`) holds `INDEX.md`, one
`id | category | title`) and `guides/<category>/<id>.md`. They are a copy line per guide (`- <id> | <category> | <title>`), and the guides at
of GoogleChrome/modern-web-guidance pinned in `plugins.lock.json` `guides/<category>/<id>.md`. They are a copy of
(`NOTICE.md` names the commit and the licenses). Nothing here touches the GoogleChrome/modern-web-guidance pinned in `plugins.lock.json`; `NOTICE.md`
network. names the commit and the licenses. Read is the only tool needed, nothing
here touches the network.
## Steps ## Steps
1. Search: Grep `INDEX.md`, case-insensitive, for one capability at a 1. Pick: Read `INDEX.md` whole (about 210 short lines) and choose the
time, in 1-3 words naming the UI pattern or platform feature guides whose title matches a platform feature or UI pattern the task
(`dialog`, `popover`, `table`, `validation`, `view transition`, `LCP`). uses (a modal is `dialog`, a tooltip a popover, a slow first paint
No hit: rephrase once with a synonym, then Grep the bodies under LCP). No title fits a feature: search the guide bodies under `guides/`
`guides/`. Nothing relevant: go on without a guide. once with the text-search tool at hand, else go on without a guide.
2. Read: open each matching guide, plus the discipline guide of the task 2. Read each chosen guide, plus the discipline guide of each category
when one exists (`html`, `css`, `forms`, `accessibility`, `performance`, touched: the guide whose id equals its category (`html`, `css`, `js`,
`security`). `forms`, `accessibility`, `performance`, `security`, `privacy`).
3. Cross-references: a guide line `npx -y modern-web-guidance@latest 3. Cross-references: a guide line `npx -y modern-web-guidance@latest
retrieve "<id>"` points at another guide. Glob `guides/*/<id>.md` and retrieve "<id>"` names another guide. Find `<id>` in `INDEX.md` for its
Read it instead. Never run npx, the guidance CLI or any network command category and Read `guides/<category>/<id>.md`. Never run npx, the
for this skill. guidance CLI or any network command for this skill.
4. Apply: follow the guide, its fallbacks and its Baseline notes, without 4. Apply: follow the guide, its fallbacks and its Baseline notes, without
adding features the task did not ask for. Where a guide and a rule of adding features the task did not ask for. Where a guide and a rule of
`rules/web-building.md` disagree on how to use the platform, the guide `rules/web-building.md` disagree on how to use the platform, the guide
wins. wins.
5. Disclose: end the answer that delivers the front-end change with one 5. Disclose: end the answer that delivers the front-end change (a
line, `Modern Web Guidance: <id>, <id>`. Guides checked and none sub-agent: its report) with one line, `Modern Web Guidance: <id>, <id>`.
applied: `Modern Web Guidance: checked <topics>, none applied`. No Guides checked and none applied: `Modern Web Guidance: checked <topics>,
quotes. none applied`. No quotes.
## Missing copy ## Missing copy
@@ -689,24 +708,30 @@ ln -s ../../skills-external/mwg/NOTICE.md skills/modern-web-guidance/NOTICE.md
```json ```json
[ [
{"id": 1, "prompt": "Add a confirmation modal before deleting an item", "expected": "Grep INDEX.md for dialog, Read the dialog guide (+ html/accessibility), build on <dialog> per the guide, end with `Modern Web Guidance: <ids>`"}, {"id": 1, "prompt": "Add a confirmation modal before deleting an item", "expected": "Read INDEX.md, pick dialog, Read the dialog guide (+ html/accessibility), build on <dialog> per the guide, end with `Modern Web Guidance: <ids>`"},
{"id": 2, "prompt": "Make this table usable on mobile", "expected": "Search table/responsive, Read the matching guide, apply its pattern and fallback, disclosure line"}, {"id": 2, "prompt": "Make this table usable on mobile", "expected": "Search table/responsive, Read the matching guide, apply its pattern and fallback, disclosure line"},
{"id": 3, "prompt": "Améliore le LCP de la page d'accueil", "expected": "FR trigger: search LCP, Read the performance guides, apply fetchpriority/image guidance, disclosure line"}, {"id": 3, "prompt": "Améliore le LCP de la page d'accueil", "expected": "FR trigger: search LCP, Read the performance guides, apply fetchpriority/image guidance, disclosure line"},
{"id": 4, "prompt": "Write a SQL migration for the orders table", "expected": "Does not trigger: backend task"} {"id": 4, "prompt": "Write a SQL migration for the orders table", "expected": "Does not trigger: backend task"}
] ]
``` ```
`mods/model-router/routing.json`, inside `"skills"`: add `"modern-web-guidance": "explore"` and `"chrome-extensions": "implement"` (keep the object's existing formatting; place them alphabetically if the object is sorted, else at the end). `lib/tests/effort-routing.test.sh:141`: the line becomes
```bash
NO_ROW_SKILLS=" find-docs graphify impeccable model-router modern-web-guidance "
```
No `routing.json` edit: neither `modern-web-guidance` nor `chrome-extensions` gets a row (Global Constraints).
- [ ] **Step 4: Run tests** - [ ] **Step 4: Run tests**
Run: `make test suite="lib/tests/mwg-skill.test.sh lib/tests/effort-routing.test.sh lib/tests/model-routing.test.sh lib/tests/pack-census.test.sh lib/tests/skill-routing-census.test.sh"` Run: `make test suite="lib/tests/mwg-skill.test.sh lib/tests/effort-routing.test.sh lib/tests/model-routing.test.sh lib/tests/pack-census.test.sh lib/tests/skill-routing-census.test.sh"`
Expected: `all suites green`. If `skill-routing-census` reports a pair ≥ 0.75 involving `modern-web-guidance`, reword the description's trigger list (keep the first sentence) and re-run; a WARN (≥ 0.50) is acceptable and is reported. Expected: `all suites green`. If `skill-routing-census` reports a pair ≥ 0.75 involving `modern-web-guidance`, reword the description's list of front-end areas (keep the first sentence, stay within 400 characters) and re-run; a WARN (≥ 0.50) is acceptable and is reported.
- [ ] **Step 5: Commit** - [ ] **Step 5: Commit**
```bash ```bash
git add skills/modern-web-guidance mods/model-router/routing.json lib/tests/mwg-skill.test.sh git add skills/modern-web-guidance lib/tests/effort-routing.test.sh lib/tests/mwg-skill.test.sh
git commit -m "feat(skills): modern-web-guidance reads the pinned guides locally" git commit -m "feat(skills): modern-web-guidance reads the pinned guides locally"
``` ```
@@ -729,6 +754,7 @@ W="$ROOT/rules/web-building.md"
check rule-section "$(grep -qx '## Modern Web Guidance first' "$W" && echo 1)" check rule-section "$(grep -qx '## Modern Web Guidance first' "$W" && echo 1)"
check rule-before-design "$([ "$(grep -n '^## Modern Web Guidance first' "$W" | cut -d: -f1)" -lt "$(grep -n '^## Design work' "$W" | cut -d: -f1)" ] && echo 1)" check rule-before-design "$([ "$(grep -n '^## Modern Web Guidance first' "$W" | cut -d: -f1)" -lt "$(grep -n '^## Design work' "$W" | cut -d: -f1)" ] && echo 1)"
check rule-guide-wins "$(grep -q 'platform, the guide wins' "$W" && echo 1)" check rule-guide-wins "$(grep -q 'platform, the guide wins' "$W" && echo 1)"
check rule-subagent-path "$(grep -q 'Read `~/.claude/skills/modern-web-guidance/SKILL.md`' "$W" && echo 1)"
check motion-line "$(grep -q '^- Motion: transform and opacity for continuous or scroll-linked motion,$' "$W" && echo 1)" check motion-line "$(grep -q '^- Motion: transform and opacity for continuous or scroll-linked motion,$' "$W" && echo 1)"
check motion-old-gone "$(grep -q 'transform and opacity only' "$W" || echo 1)" check motion-old-gone "$(grep -q 'transform and opacity only' "$W" || echo 1)"
check design-build "$(awk '/^## Design work/{p=1} /^## /&&!/Design work/{p=0} p' "$W" | grep -q 'consult `modern-web-guidance` first' && echo 1)" check design-build "$(awk '/^## Design work/{p=1} /^## /&&!/Design work/{p=0} p' "$W" | grep -q 'consult `modern-web-guidance` first' && echo 1)"
@@ -747,9 +773,10 @@ check site-motion "$(grep -q '`modern-web-guidance`' "$ROOT/skills/pack-design/s
## Modern Web Guidance first ## Modern Web Guidance first
Before writing or changing front-end code (markup, styles, client-side JS, Before writing or changing front-end code (markup, styles, client-side JS,
components), run the `modern-web-guidance` skill: it reads Google's pinned components), run the `modern-web-guidance` skill: it reads Google's pinned
guides locally. Where a guide and a line below disagree on how to use the guides locally. Without the Skill tool (a sub-agent), Read
platform, the guide wins. End the answer with the skill's one-line `~/.claude/skills/modern-web-guidance/SKILL.md` and follow it. Where a
disclosure. guide and a line below disagree on how to use the platform, the guide
wins. End the answer with the skill's one-line disclosure.
``` ```
@@ -801,9 +828,9 @@ git commit -m "feat(rules): front-end work consults modern-web-guidance first"
--- ---
### Task 5 (main loop, after the gates): live install and doctor ### Task 5 (main loop, after Task 4, before the STEP 5 gates): live install and doctor
Not an executor task (network fetch on this machine, link refresh): Not an executor task (network fetch on this machine, link refresh). Contract oracles 1, 4 and 5 read its result, so it runs before GATE 0:
- `source lib/vendor-skills.sh && vendor_pinned_tree modern-web-guidance` → `modern-web-guidance vendored (pinned @ 64a6d70): chrome-extensions mwg`. - `source lib/vendor-skills.sh && vendor_pinned_tree modern-web-guidance` → `modern-web-guidance vendored (pinned @ 64a6d70): chrome-extensions mwg`.
- `bash link.sh` → `chrome-extensions` linked. - `bash link.sh` → `chrome-extensions` linked.
@@ -65,32 +65,37 @@ Callers: `install-plugins.sh` Step 8e (`vendor_pinned_tree modern-web-guidance`)
### 2. Our skill `skills/modern-web-guidance/` (tracked, ours, always on) ### 2. Our skill `skills/modern-web-guidance/` (tracked, ours, always on)
- `SKILL.md` with `name`, `effort: medium` (the `explore` row floor), `description` (front-end triggers; not backend, - `SKILL.md` with `name`, `description` (front-end triggers; not backend, infra, tooling;
infra, tooling), `allowed-tools: Read, Grep, Glob`. at most 400 characters, listing budget), `allowed-tools: Read`. No `effort:` and no
`routing.json` row: a rowed skill reroutes the main loop on load ("last rowed skill
wins"), which would pull design work off `reflect`; listed in `NO_ROW_SKILLS` like
`find-docs`. `allowed-tools` only pre-approves Read for the invoking turn, it restricts
nothing (Claude Code skills docs); the no-npx guarantee rests on the skill's text and
the settings soft-deny on undeclared `npx <pkg>`.
- Tracked relative symlinks: `guides -> ../../skills-external/mwg/guides`, - Tracked relative symlinks: `guides -> ../../skills-external/mwg/guides`,
`INDEX.md -> ../../skills-external/mwg/INDEX.md`, `NOTICE.md -> ../../skills-external/mwg/NOTICE.md`. `INDEX.md -> ../../skills-external/mwg/INDEX.md`, `NOTICE.md -> ../../skills-external/mwg/NOTICE.md`.
- Workflow in the body: - Workflow in the body:
1. Grep `INDEX.md` for 1-3 terms of the capability (dialog, popover, table, form 1. Read `INDEX.md` whole (210 lines, ~14 KB) and pick the guides by title (Grep and
validation, view transition, LCP…); fall back to Grep over `guides/`. Glob are absent in some sessions, Read always exists); a body search only when a
2. Read the matching guide(s) and the discipline guide when one applies (html, css, text-search tool is at hand.
forms, accessibility, performance, security). 2. Read the matching guide(s) and the discipline guide of each category touched (id =
category: html, css, js, forms, accessibility, performance, security, privacy).
3. Apply them, keeping the guide's fallbacks and Baseline notes. A guide line 3. Apply them, keeping the guide's fallbacks and Baseline notes. A guide line
`npx … retrieve "<id>"` means: Read `guides/*/<id>.md` locally. Never run npx or any `npx … retrieve "<id>"` means: find `<id>` in `INDEX.md`, Read
network command for this skill. `guides/<category>/<id>.md`. Never run npx or any network command for this skill.
4. Where a guide and a rule of `rules/web-building.md` disagree on how to use the 4. Where a guide and a rule of `rules/web-building.md` disagree on how to use the
platform, the guide wins. platform, the guide wins.
5. End the answer that delivers the front-end change with one line: 5. End the answer that delivers the front-end change with one line:
`Modern Web Guidance: <id>, <id>` (or `Modern Web Guidance: checked <topics>, none `Modern Web Guidance: <id>, <id>` (or `Modern Web Guidance: checked <topics>, none
applied`). No quotes. applied`). No quotes.
- Guides missing (dangling links): say so, remedy `make update`; continue without them. - Guides missing (dangling links): say so, remedy `make update`; continue without them.
- `test-prompts.json` (darwin convention), a `routing.json` row (`modern-web-guidance`, - `test-prompts.json` (darwin convention).
phase `explore`).
### 3. chrome-extensions (vendored, always on, as is) ### 3. chrome-extensions (vendored, always on, as is)
Added to `link.sh` `EXTERNAL_SKILLS` (always-on flat link, the superpowers class; Added to `link.sh` `EXTERNAL_SKILLS` (always-on flat link, the superpowers class;
BDR-093 forbids only default-off packs there). Its `CHROMEWEBSTORE.md` behaviour is kept. BDR-093 forbids only default-off packs there). Its `CHROMEWEBSTORE.md` behaviour is kept.
A routing row is added if the effort-routing census requires one for linked externals. No routing row (untracked linked external; a row would reroute the main loop on load).
### 4. Wiring ### 4. Wiring
@@ -105,15 +110,20 @@ A routing row is added if the effort-routing census requires one for linked exte
- `CLAUDE.global.md` unchanged (320/320); its design pointer already sends design work to - `CLAUDE.global.md` unchanged (320/320); its design pointer already sends design work to
`web-building.md`. `web-building.md`.
- Known: the path rule also loads inside sub-agents (LRN-232), so front agents see it too. - Known: the path rule also loads inside sub-agents (LRN-232), so front agents see it too.
The executors (feater, bugfixer, hotfixer) have no Skill tool in their `tools:`, so the
rule adds: without the Skill tool, Read `~/.claude/skills/modern-web-guidance/SKILL.md`
and follow it. The relative links resolve through the `~/.claude/skills` link (checked
on a fixture). Limit: a Write of a new file loads no path rule (LRN-238).
### 5. Checks and docs ### 5. Checks and docs
- `lib/doctor-vendored.sh` (or `doctor.sh`): `skills-external/mwg/INDEX.md` present and - `lib/doctor-vendored.sh` (or `doctor.sh`): `skills-external/mwg/INDEX.md` present and
its `.vendored-commit` equals the lock commit; `chrome-extensions` link present. its `.vendored-commit` equals the lock commit; `chrome-extensions` link present.
- `lib/tests/mwg.test.sh` on a local git fixture: fetch at the pinned commit, refuse a - `lib/tests/vendor-tree.test.sh` on a local git fixture: fetch at the pinned commit,
mismatching commit, whitelist only (no upstream SKILL.md), INDEX generation, prune of a refuse a mismatching commit, whitelist only (no upstream SKILL.md), INDEX generation,
dropped guide on refresh, install of an absent copy in refresh mode, path validation, prune of a dropped guide on refresh, install of an absent copy in refresh mode, path
and our `SKILL.md` contains no `npx` command to run. validation. `lib/tests/mwg-skill.test.sh`: our `SKILL.md` contains no `npx` command to
run, Read only, no row, links, disclosure, and the rule wiring.
- README, USAGE, CHANGELOG; BDR recording the decisions, including the fixed pin as an - README, USAGE, CHANGELOG; BDR recording the decisions, including the fixed pin as an
assumed exception to BDR-056. assumed exception to BDR-056.