docs(plan): modern web guidance, Read-only skill, no routing row, sub-agent path
This commit is contained in:
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.
|
||||||
|
|
||||||
|
|||||||
Reference in new issue
Block a user