2 changed files with 972 additions and 0 deletions

No files matched your search

@@ -0,0 +1,839 @@
# Modern Web Guidance Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**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 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.
**Spec:** `docs/superpowers/specs/2026-11-21-modern-web-guidance-design.md`
**Contract:** `.claude/tasks/contracts/2026-11-21-modern-web-guidance-2314.md`
Out of this plan, done by `/ship-feature` itself: README / USAGE / CHANGELOG (STEP 8 doc sync) and the BDR recording the decisions, including the fixed pin as an exception to BDR-056 (STEP 7).
## Global Constraints
- 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`: 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/`.
- Vendored text is never edited (BDR-104/106).
- `CLAUDE.global.md`, `settings.json`, `CLAUDE.md` are not modified (BDR-028, 320-line budget).
- `rules/web-building.md`: the heading line `## Design work — full toolchain (tiered by scope)` and the line `- The vendored stack members route to \`reflect\` (high) through their` stay byte-identical (doctrine-citers and effort-routing locks, LRN-166).
- Tests run only through `make test suite=<file>` (hermetic git config).
- `VENDOR_BASE_URL` override is honored only when it starts with `file://` (same rule as `vendor_pinned_skills`).
## Review Focus
1. Fetch failure or a commit that is not the pin → rc 1, `skills-external/` unchanged (no half-swapped dest).
2. A pin bump that drops a guide upstream → the guide disappears locally after refresh (whole-dir swap, not file overwrite).
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.
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.
---
### Task 1: `vendor_pinned_tree` fetcher + hermetic suite
**Files:**
- Modify: `lib/vendor-skills.sh` (append after `vendor_pinned_skills`)
- Create: `lib/tests/vendor-tree.test.sh`
**Interfaces:**
- Produces: `vendor_pinned_tree <lock-key> [refresh]` (rc 0 ok/already at pin, rc 1 any failure, nothing changed); `_vendor_read_tree_lock <lockfile> <key>` (stdout lines: source, commit, tag, license, then `<dest>\t<target>\t<repo-path>`); lock entry shape:
`{"source","commit","tag","license","trees":{"<dest>":{"<target>|.":"<repo-path>"}},"managed_by":"git-tree","always_on":true}`.
- Writes per dest: `skills-external/<dest>/.vendored-commit` (the commit), `NOTICE.md`, and `INDEX.md` when the dest holds `guides/`.
- [ ] **Step 1: Write the failing test** — create `lib/tests/vendor-tree.test.sh`:
```bash
#!/usr/bin/env bash
# lib/tests/vendor-tree.test.sh — lib/vendor-skills.sh vendor_pinned_tree():
# pinned git fetch from a file:// fixture repo, allowlisted copy, INDEX /
# NOTICE / .vendored-commit generation, upstream SKILL.md never copied,
# commit mismatch refused with nothing written, refresh prunes a guide
# dropped upstream, refresh installs an absent copy, install mode skips a
# copy already at the pin, unsafe lock paths rejected before any fetch.
set -u
ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
LIB="$ROOT/lib/vendor-skills.sh"
pass=0; fail=0
check_bool() {
if [ "$2" = 1 ]; then pass=$((pass+1)); echo "PASS $1"
else fail=$((fail+1)); echo "FAIL $1"; fi
}
WORK="$(mktemp -d)"; trap 'rm -rf "$WORK"' EXIT
UP="$WORK/upstream"; REPO="$WORK/repo"
mkdir -p "$REPO/skills-external"
g() { git -C "$UP" -c user.email=t@t -c user.name=t "$@"; }
# Fixture upstream: modern-web-guidance layout (SKILL.md + guides/) and a
# chrome-extensions skill with a references/ file.
mkdir -p "$UP/skills/modern-web-guidance/guides/css" \
"$UP/skills/modern-web-guidance/guides/html" \
"$UP/skills/chrome-extensions/references/extensions"
printf 'npx -y modern-web-guidance@latest search\n' \
> "$UP/skills/modern-web-guidance/SKILL.md"
printf '# Animate to intrinsic sizes\nbody\n' \
> "$UP/skills/modern-web-guidance/guides/css/animate-to-intrinsic-sizes.md"
printf '# Dialog\nbody\n' > "$UP/skills/modern-web-guidance/guides/html/dialog.md"
printf '# Old guide\nbody\n' > "$UP/skills/modern-web-guidance/guides/html/old-guide.md"
printf -- '---\nname: chrome-extensions\n---\nbody\n' \
> "$UP/skills/chrome-extensions/SKILL.md"
printf 'ref\n' > "$UP/skills/chrome-extensions/references/extensions/api.md"
printf 'Apache License\n' > "$UP/LICENSE"
git init -q "$UP"; g add -A; g commit -qm one
SHA1="$(git -C "$UP" rev-parse HEAD)"
write_lock() { # write_lock <commit> [extra-tree-json]
cat > "$REPO/plugins.lock.json" <<JSON
{
"mwg-key": {
"source": "https://github.com/acme/mwg",
"commit": "$1",
"tag": "v1.0.1",
"license": "Apache-2.0 (code), CC-BY 4.0 (guides)",
"managed_by": "git-tree",
"trees": {
"mwg": {"guides": "skills/modern-web-guidance/guides", "LICENSE": "LICENSE"},
"chrome-extensions": {".": "skills/chrome-extensions"}${2:-}
}
}
}
JSON
}
# Same pattern as vendor-skills.test.sh: export once, source once (the lib
# reads VENDOR_SKILLS_REPO_OVERRIDE at source time), override per call.
export VENDOR_SKILLS_REPO_OVERRIDE="$REPO" VENDOR_BASE_URL="file://$UP"
# 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.
write_lock "$SHA1"; run mwg-key; rc=$?
M="$REPO/skills-external/mwg"; C="$REPO/skills-external/chrome-extensions"
check_bool T1-rc "$([ $rc -eq 0 ] && echo 1)"
check_bool T1-guide "$([ -f "$M/guides/html/dialog.md" ] && echo 1)"
check_bool T1-license "$([ -f "$M/LICENSE" ] && echo 1)"
check_bool T1-no-upstream-skill "$([ ! -e "$M/SKILL.md" ] && echo 1)"
check_bool T1-index-line "$(grep -qx -- '- dialog | html | Dialog' "$M/INDEX.md" && echo 1)"
check_bool T1-index-count "$([ "$(grep -c '^- ' "$M/INDEX.md")" -eq 3 ] && 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-ce-contents "$([ -f "$C/SKILL.md" ] && [ -f "$C/references/extensions/api.md" ] && 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).
VENDOR_BASE_URL="file://$WORK/nowhere" 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)"
# T3 refresh after an upstream drop: old-guide disappears locally.
g rm -q skills/modern-web-guidance/guides/html/old-guide.md; g commit -qm two
SHA2="$(git -C "$UP" rev-parse HEAD)"
write_lock "$SHA2"; run mwg-key refresh; rc=$?
check_bool T3-rc "$([ $rc -eq 0 ] && echo 1)"
check_bool T3-pruned "$([ ! -e "$M/guides/html/old-guide.md" ] && echo 1)"
check_bool T3-marker "$([ "$(cat "$M/.vendored-commit")" = "$SHA2" ] && echo 1)"
# T4 refresh installs an absent copy (never-installed machine).
rm -rf "$REPO/skills-external/chrome-extensions"
run mwg-key refresh; rc=$?
check_bool T4-installs-absent "$([ $rc -eq 0 ] && [ -f "$C/SKILL.md" ] && echo 1)"
# T5 commit not in upstream: rc 1, existing copy untouched.
BAD="0123456789abcdef0123456789abcdef01234567"
write_lock "$BAD"; run mwg-key refresh; rc=$?
check_bool T5-rc "$([ $rc -eq 1 ] && echo 1)"
check_bool T5-untouched "$([ "$(cat "$M/.vendored-commit")" = "$SHA2" ] && echo 1)"
# T6 unsafe repo path rejected before any fetch.
write_lock "$SHA2" ', "evil": {"x": "../etc"}'; run mwg-key; rc=$?
check_bool T6-traversal "$([ $rc -eq 1 ] && grep -q "rejected" "$WORK/out" && [ ! -e "$REPO/skills-external/evil" ] && echo 1)"
# T7 bad dest name rejected.
write_lock "$SHA2" ', "a/b": {"x": "LICENSE"}'; run mwg-key; rc=$?
check_bool T7-dest "$([ $rc -eq 1 ] && grep -q "rejected" "$WORK/out" && echo 1)"
# T8 a missing upstream path aborts with nothing swapped.
write_lock "$SHA2" ', "ghost": {"x": "no/such/path"}'; run mwg-key refresh; rc=$?
check_bool T8-missing-path "$([ $rc -eq 1 ] && [ ! -e "$REPO/skills-external/ghost" ] && [ "$(cat "$M/.vendored-commit")" = "$SHA2" ] && echo 1)"
# T9 a non-file:// VENDOR_BASE_URL is ignored with a warn.
write_lock "$SHA2"
VENDOR_BASE_URL="https://evil.example" vendor_pinned_tree mwg-key >"$WORK/out" 2>&1
check_bool T9-override-ignored "$(grep -q 'VENDOR_BASE_URL ignored' "$WORK/out" && echo 1)"
echo "vendor-tree: $pass pass, $fail fail"
[ "$fail" -eq 0 ]
```
T9 note: with the override ignored the source becomes the real `https://github.com/acme/mwg` URL; the copy is already at the pin, so install mode returns "already at pin" before any fetch. The warn is printed first only if the override check runs before the at-pin skip — the implementation below runs the override check first, on purpose.
- [ ] **Step 2: Run it to verify it fails**
Run: `make test suite=lib/tests/vendor-tree.test.sh`
Expected: FAIL lines (`vendor_pinned_tree: command not found` in `$WORK/out`), last line `1 suite(s) red: lib/tests/vendor-tree.test.sh`.
- [ ] **Step 3: Implement** — append to `lib/vendor-skills.sh`:
```bash
# ============================================================
# vendor_pinned_tree — whole upstream trees at one pinned commit, by git
# ============================================================
# Lock entry shape (plugins.lock.json, "managed_by": "git-tree"):
# "<key>": {
# "source": "https://github.com/<owner>/<repo>",
# "commit": "<40-hex sha>", "tag": "<tag name, informational>",
# "license": "<one-line license note>",
# "trees": { "<dest>": { "<target>" | ".": "<repo path>", ... }, ... }
# }
# Each <dest> becomes skills-external/<dest>/. "<target>": "<path>" copies
# the repo path as <dest>/<target>; ".": "<path>" copies the path's
# contents into <dest>/. Only listed paths are copied (allowlist). The
# fetch is one `git fetch --depth 1 <source> <commit>`; HEAD must equal
# the pin or nothing is written. Every dest is staged complete under
# skills-external/.vendor-stage.<pid>/, then swapped in whole, so a file
# dropped upstream disappears on a pin bump. Per dest it writes
# .vendored-commit, NOTICE.md, and INDEX.md when the dest holds guides/.
# Install mode skips when every dest is already at the pin; refresh
# re-fetches; both install a missing copy.
# _vendor_read_tree_lock <lockfile> <key> — prints source, commit, tag,
# license, then one "<dest>\t<target>\t<path>" line per item (sorted).
# rc 1 silent when the entry is absent or incomplete; rc 1 with one
# "INVALID\t<field>=<value>" or "INVALID\t<value>" line on a bad field.
_vendor_read_tree_lock() {
python3 - "$1" "$2" <<'PY'
import json, re, sys
SAFE = re.compile(r'^[A-Za-z0-9._/-]+$')
NAME = re.compile(r'^[A-Za-z0-9_-][A-Za-z0-9._-]*$')
COMMIT_RE = re.compile(r'^[0-9a-f]{40}$')
SOURCE_RE = re.compile(
r'^https://github\.com/[A-Za-z0-9._-]+/[A-Za-z0-9._-]+/?$')
NOTE_RE = re.compile(r'^[A-Za-z0-9 .,()/+-]*$')
def unsafe(value):
return ".." in value or value.startswith("/") or not SAFE.fullmatch(value)
def bad(text):
print(f"INVALID\t{text}")
sys.exit(1)
lockfile, key = sys.argv[1], sys.argv[2]
with open(lockfile) as f:
entry = json.load(f).get(key, {})
source, sha = entry.get("source", ""), entry.get("commit", "")
tag, note = entry.get("tag", ""), entry.get("license", "")
trees = entry.get("trees", {})
if not source or not sha or not isinstance(trees, dict) or not trees:
sys.exit(1)
if not COMMIT_RE.fullmatch(sha):
bad(f"commit={sha}")
if not SOURCE_RE.fullmatch(source):
bad(f"source={source}")
if tag and unsafe(tag):
bad(f"tag={tag}")
if not isinstance(note, str) or not NOTE_RE.fullmatch(note):
bad(f"license={note}")
rows = []
for dest, items in trees.items():
if not NAME.fullmatch(dest) or not isinstance(items, dict) or not items:
bad(f"dest={dest}")
for target, path in items.items():
if target != "." and not NAME.fullmatch(target):
bad(target)
if not isinstance(path, str) or unsafe(path):
bad(str(path))
rows.append((dest, target, path))
print(source)
print(sha)
print(tag)
print(note)
for dest, target, path in sorted(rows):
print(f"{dest}\t{target}\t{path}")
PY
}
# _vendor_tree_current <root> <sha> <dests> — rc 0 when every dest
# (newline-separated) holds a .vendored-commit equal to <sha>.
_vendor_tree_current() {
local root="$1" sha="$2" dest
while IFS= read -r dest; do
[ -n "$dest" ] || continue
[ "$(cat "$root/$dest/.vendored-commit" 2>/dev/null)" = "$sha" ] \
|| return 1
done <<<"$3"
}
# _vendor_tree_checkout <dir> <url> <sha> — shallow fetch of <sha> into a
# fresh repo at <dir>; rc 0 only when the checked-out HEAD is <sha>.
_vendor_tree_checkout() {
local dir="$1" url="$2" sha="$3"
git init -q "$dir" 2>/dev/null || return 1
GIT_TERMINAL_PROMPT=0 git -C "$dir" fetch -q --depth 1 -- "$url" "$sha" \
2>/dev/null || return 1
git -C "$dir" -c advice.detachedHead=false checkout -q FETCH_HEAD \
2>/dev/null || return 1
[ "$(git -C "$dir" rev-parse HEAD 2>/dev/null)" = "$sha" ]
}
# _vendor_tree_index <dest_dir> — writes <dest_dir>/INDEX.md, one
# "- <id> | <category> | <H1 title>" line per guides/<category>/<id>.md.
_vendor_tree_index() {
local dir="$1" f id category title
[ -d "$dir/guides" ] || return 0
{
cat <<'EOF'
# 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 \
| while IFS= read -r f; do
id="$(basename "$f" .md)"
category="$(basename "$(dirname "$f")")"
title="$(grep -m1 '^# ' "$f" | sed 's/^# //')"
printf -- '- %s | %s | %s\n' "$id" "$category" "${title:-$id}"
done
} > "$dir/INDEX.md"
}
# _vendor_tree_stage <src> <stage> <items> — copies every
# "<dest>\t<target>\t<path>" item from the checkout <src> into
# <stage>/<dest>/; rc 1 (err names the path) when a path is missing.
_vendor_tree_stage() {
local src="$1" stage="$2" dest target path
while IFS=$'\t' read -r dest target path; do
[ -n "$dest" ] || continue
mkdir -p "$stage/$dest"
if [ ! -e "$src/$path" ]; then
err "upstream path missing at the pin: $path"
return 1
fi
if [ "$target" = "." ]; then
cp -R "$src/$path/." "$stage/$dest/" || return 1
else
cp -R "$src/$path" "$stage/$dest/$target" || return 1
fi
done <<<"$3"
}
# _vendor_tree_finish <stage> <dests> <source> <sha> <tag> <note> —
# writes INDEX.md, NOTICE.md and .vendored-commit into each staged dest.
_vendor_tree_finish() {
local stage="$1" dest
while IFS= read -r dest; do
[ -n "$dest" ] || continue
_vendor_tree_index "$stage/$dest"
printf '# Vendored content\n\nSource: %s (tag %s, commit %s).\n' \
"$3" "${5:-none}" "$4" > "$stage/$dest/NOTICE.md"
printf 'Fetched by lib/vendor-skills.sh vendor_pinned_tree;' \
>> "$stage/$dest/NOTICE.md"
printf ' never edited here. License: %s.\n' "$6" >> "$stage/$dest/NOTICE.md"
printf '%s\n' "$4" > "$stage/$dest/.vendored-commit"
done <<<"$2"
}
# _vendor_tree_swap <root> <stage> <dests> — moves each staged dest into
# <root>/<dest>, the previous copy parked under <stage>/.old-<dest>.
_vendor_tree_swap() {
local root="$1" stage="$2" dest
while IFS= read -r dest; do
[ -n "$dest" ] || continue
if [ -e "$root/$dest" ]; then
mv "$root/$dest" "$stage/.old-$dest" || return 1
fi
mv "$stage/$dest" "$root/$dest" || return 1
done <<<"$3"
}
# vendor_pinned_tree <lock-key> [refresh] — see the block comment above.
vendor_pinned_tree() {
local key="$1" refresh="${2:-}" out root="$VENDOR_REPO/skills-external"
local base="${VENDOR_BASE_URL:-}"
if [ -n "$base" ] && [[ "$base" != file://* ]]; then
warn "VENDOR_BASE_URL ignored (must start with file://): $base"
base=""
fi
if ! out="$(_vendor_read_tree_lock "$VENDOR_REPO/plugins.lock.json" "$key")"; then
_vendor_report_lock_error "$key" "$out"
return 1
fi
local source sha tag note items dests
{ read -r source; read -r sha; read -r tag; read -r note; } <<<"$out"
items="$(tail -n +5 <<<"$out")"
dests="$(cut -f1 <<<"$items" | sort -u)"
if [ "$refresh" != "refresh" ] && _vendor_tree_current "$root" "$sha" "$dests"; then
ok "$key already at pin ${sha:0:7}"
return 0
fi
local tmp stage="$root/.vendor-stage.$$"
tmp="$(mktemp -d)" || return 1
mkdir -p "$stage" || { rm -rf "$tmp"; return 1; }
if _vendor_tree_checkout "$tmp/src" "${base:-$source}" "$sha" \
&& _vendor_tree_stage "$tmp/src" "$stage" "$items" \
&& _vendor_tree_finish "$stage" "$dests" "$source" "$sha" "$tag" "$note" \
&& _vendor_tree_swap "$root" "$stage" "$dests"; then
ok "$key vendored (pinned @ ${sha:0:7}): $(tr '\n' ' ' <<<"$dests")"
rm -rf "$tmp" "$stage"
return 0
fi
err "$key: fetch, stage or swap failed at ${sha:0:7} — see above; copies at the previous pin kept"
rm -rf "$tmp" "$stage"
return 1
}
```
Swap failure note: `_vendor_tree_swap` moves dests one by one; a failure after the first move leaves that dest updated and the others at the old pin (each dest self-consistent, `.vendored-commit` tells which). The error line says so; doctor reports the mismatch.
- [ ] **Step 4: Run the suite**
Run: `make test suite=lib/tests/vendor-tree.test.sh`
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 (simulated: clean).
Then the old suite still green: `make test suite=lib/tests/vendor-skills.test.sh` → `all suites green`.
- [ ] **Step 5: Commit**
```bash
git add lib/vendor-skills.sh lib/tests/vendor-tree.test.sh
git commit -m "feat(vendor): vendor_pinned_tree fetches whole upstream trees at a pinned commit"
```
---
### Task 2: Lock entry, install/update/link wiring, gitignore, doctor check
**Files:**
- Modify: `plugins.lock.json` (new key `modern-web-guidance`)
- Modify: `install-plugins.sh` Step 8e (≈ lines 913-940)
- Modify: `update-all.sh` 7.3 (≈ lines 369-383)
- Modify: `link.sh:78-81` (`EXTERNAL_SKILLS`)
- Modify: `.gitignore` (top flat-link block + a new vendored block)
- Modify: `lib/doctor-vendored.sh` (new `check_vendored_trees`), `doctor.sh:133`
- Test: `lib/tests/doctor-vendored.test.sh` (new cases)
**Interfaces:**
- Consumes: `vendor_pinned_tree <key> [refresh]` (Task 1).
- Produces: `check_vendored_trees <repo>` (doctor: pass/warn lines, never fail); lock key `modern-web-guidance`; dests `skills-external/mwg/`, `skills-external/chrome-extensions/`.
- [ ] **Step 1: Write the failing test** — append before the final summary of `lib/tests/doctor-vendored.test.sh` (reuse its `check`/`pass`/`fail` helpers; read the file first and follow its helper names exactly):
```bash
# ── check_vendored_trees: git-tree lock entries ──
TR="$(mktemp -d)"
mkdir -p "$TR/skills-external/at-pin" "$TR/skills-external/stale"
printf '%s\n' 1111111111111111111111111111111111111111 > "$TR/skills-external/at-pin/.vendored-commit"
printf '%s\n' 2222222222222222222222222222222222222222 > "$TR/skills-external/stale/.vendored-commit"
cat > "$TR/plugins.lock.json" <<'JSON'
{"t": {"managed_by": "git-tree", "commit": "1111111111111111111111111111111111111111",
"trees": {"at-pin": {"x": "a"}, "stale": {"x": "a"}, "absent": {"x": "a"}}},
"c": {"managed_by": "curl", "commit": "1111111111111111111111111111111111111111", "skills": ["s"]}}
JSON
out="$(source "$ROOT/lib/doctor-vendored.sh"; check_vendored_trees "$TR" 2>&1)"
printf '%s\n' "$out" | grep -q 't: at-pin at pin 1111111' && R1=1 || R1=0
printf '%s\n' "$out" | grep -q 't: skills-external/stale at 2222222, pin 1111111' && R2=1 || R2=0
printf '%s\n' "$out" | grep -q 't: skills-external/absent missing' && R3=1 || R3=0
printf '%s\n' "$out" | grep -q '✗' && R4=0 || R4=1
rm -rf "$TR"
```
Then, with the suite's own helper (`check_bool NAME 0|1`, lib/tests/doctor-vendored.test.sh:25):
```bash
check_bool TREES_AT_PIN "$R1"
check_bool TREES_STALE_WARN "$R2"
check_bool TREES_MISSING_WARN "$R3"
check_bool TREES_NEVER_FAIL "$R4"
```
The file ends with `echo "PASS=$pass FAIL=$fail"`; insert the block above that line.
- [ ] **Step 2: Run it to verify it fails**
Run: `make test suite=lib/tests/doctor-vendored.test.sh`
Expected: the four new checks FAIL (`check_vendored_trees: command not found`).
- [ ] **Step 3: Implement**
`lib/doctor-vendored.sh`, append:
```bash
# _dv_tree_expectations <lockfile> — prints "<key>\t<dest>\t<commit>" for
# every "managed_by": "git-tree" entry; dest and commit format-checked,
# an invalid one skipped. Lockfile via argv, stderr discarded.
_dv_tree_expectations() {
python3 - "$1" 2>/dev/null <<'PY'
import json, re, sys
NAME = re.compile(r'^[A-Za-z0-9_-][A-Za-z0-9._-]*$')
COMMIT = re.compile(r'^[0-9a-f]{40}$')
with open(sys.argv[1]) as f:
data = json.load(f)
for key, entry in sorted(data.items()):
if not isinstance(entry, dict) or entry.get("managed_by") != "git-tree":
continue
sha = entry.get("commit", "")
trees = entry.get("trees", {})
if not COMMIT.fullmatch(sha) or not isinstance(trees, dict):
continue
for dest in sorted(trees):
if NAME.fullmatch(dest):
print(f"{key}\t{dest}\t{sha}")
PY
}
# check_vendored_trees <repo> — every git-tree dest exists under
# skills-external/ with a .vendored-commit equal to its pin. Never fails:
# a missing or stale copy is a warn naming `make update`.
check_vendored_trees() {
local repo="$1" key dest sha got
while IFS=$'\t' read -r key dest sha; do
[ -n "$key" ] || continue
got="$(cat "$repo/skills-external/$dest/.vendored-commit" 2>/dev/null)"
if [ -z "$got" ]; then
warn "$key: skills-external/$dest missing — run: make update"
elif [ "$got" != "$sha" ]; then
warn "$key: skills-external/$dest at ${got:0:7}, pin ${sha:0:7} — run: make update"
else
pass "$key: $dest at pin ${sha:0:7}"
fi
done < <(_dv_tree_expectations "$repo/plugins.lock.json")
}
```
`doctor.sh` line 133, after `check_vendored_skills "$REPO" "$HOME/.claude"`:
```bash
check_vendored_trees "$REPO"
```
`plugins.lock.json`, new key (keep the file's existing key order; place it after `superpowers`):
```json
"modern-web-guidance": {
"source": "https://github.com/GoogleChrome/modern-web-guidance",
"commit": "64a6d708f5a43f2cd3fde5d4d7db3905ba1bdf65",
"tag": "v1.0.1",
"license": "Apache-2.0 (code), CC-BY 4.0 (guides)",
"managed_by": "git-tree",
"always_on": true,
"trees": {
"mwg": {"guides": "skills/modern-web-guidance/guides", "LICENSE": "LICENSE"},
"chrome-extensions": {".": "skills/chrome-extensions"}
},
"note": "Google Modern Web Guidance (Chrome, Edge, Firefox, MDN). Guides read locally by skills/modern-web-guidance; the upstream SKILL.md (npx @latest) is never copied. chrome-extensions linked as is by link.sh. Bump commit + tag deliberately."
}
```
`install-plugins.sh` Step 8e: after `vendor_pinned_skills superpowers` add
```bash
vendor_pinned_tree modern-web-guidance
```
and add `chrome-extensions` at the end of the `EXT_SKILL_NAMES=(…)` array.
`update-all.sh` 7.3: after `vendor_pinned_skills superpowers refresh` add
```bash
echo ""
echo "── Updating Modern Web Guidance (GoogleChrome/modern-web-guidance)..."
vendor_pinned_tree modern-web-guidance refresh
```
`link.sh:81`: append `chrome-extensions` inside `EXTERNAL_SKILLS=(…)` (last element, before `)`).
`.gitignore`: in the top flat-link block add `skills/chrome-extensions`; after the superpowers block add
```gitignore
# Modern Web Guidance, vendored (plugins.lock.json 'modern-web-guidance',
# managed_by git-tree) — machine-owned, fetched at the pinned commit by
# install-plugins.sh Step 8e and update-all.sh 7.3 through
# lib/vendor-skills.sh vendor_pinned_tree. Bump the commit deliberately.
skills-external/mwg/
skills-external/chrome-extensions/
skills-external/.vendor-stage.*/
```
- [ ] **Step 4: Run tests**
Run: `make test suite="lib/tests/doctor-vendored.test.sh lib/tests/vendor-skills.test.sh lib/tests/vendor-tree.test.sh lib/tests/curated-config-guard.test.sh"`
Expected: `all suites green`. Then `shellcheck lib/doctor-vendored.sh doctor.sh install-plugins.sh update-all.sh link.sh` → no new warning; `python3 -c "import json;json.load(open('plugins.lock.json'))"` → no output.
- [ ] **Step 5: Commit**
```bash
git add plugins.lock.json install-plugins.sh update-all.sh link.sh .gitignore lib/doctor-vendored.sh doctor.sh lib/tests/doctor-vendored.test.sh
git commit -m "feat(vendor): pin Modern Web Guidance v1.0.1 and chrome-extensions, doctor checks the pin"
```
---
### Task 3: Our `modern-web-guidance` skill (no routing row)
**Files:**
- 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`
- Modify: `lib/tests/effort-routing.test.sh:141` (`NO_ROW_SKILLS` gains `modern-web-guidance`)
- Test: `lib/tests/mwg-skill.test.sh`
**Interfaces:**
- Consumes: `skills-external/mwg/{guides,INDEX.md,NOTICE.md}` (Task 1/2 layout).
- Produces: skill name `modern-web-guidance`; disclosure line format `Modern Web Guidance: <id>, <id>` / `Modern Web Guidance: checked <topics>, none applied`.
- [ ] **Step 1: Write the failing test** — `lib/tests/mwg-skill.test.sh`:
```bash
#!/usr/bin/env bash
# lib/tests/mwg-skill.test.sh — skills/modern-web-guidance: Read is the
# only pre-approved tool, no effort pin and no routing.json row (a row
# reroutes the main loop on load), no npx or network command in a fenced
# block, the three relative links into skills-external/mwg, the
# disclosure format, a description within the listing budget.
set -u
ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
S="$ROOT/skills/modern-web-guidance"
pass=0; fail=0
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 tools "$(fm | grep -qx 'allowed-tools: Read' && echo 1)"
check no-effort "$(fm | grep -q '^effort:' || echo 1)"
desc_len="$(fm | awk '/^description:/{f=1; next} /^[a-z-]+:/{f=0} f' | tr -s ' \n' ' ' | wc -c)"
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 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)"
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)"
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 no-routing-row "$(grep -q '"modern-web-guidance"\|"chrome-extensions"' "$ROOT/mods/model-router/routing.json" || 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)"
echo "mwg-skill: $pass pass, $fail fail"
[ "$fail" -eq 0 ]
```
- [ ] **Step 2: Run it to verify it fails**
Run: `make test suite=lib/tests/mwg-skill.test.sh` → `FAIL exists` etc.
- [ ] **Step 3: Implement**
`skills/modern-web-guidance/SKILL.md`:
````markdown
---
name: modern-web-guidance
description: >-
Current web-platform practice from Google's Modern Web Guidance, read
from a pinned local copy. Use FIRST, before writing or changing
front-end code: HTML, CSS, client-side JS, UI components, forms,
dialogs, layout, motion, Core Web Vitals, images, accessibility. Not
for backend, infra, build tooling or tests.
allowed-tools: Read
---
# Modern Web Guidance (local, pinned)
This folder (`~/.claude/skills/modern-web-guidance/`) holds `INDEX.md`, one
line per guide (`- <id> | <category> | <title>`), and the guides at
`guides/<category>/<id>.md`. They are a copy of
GoogleChrome/modern-web-guidance pinned in `plugins.lock.json`; `NOTICE.md`
names the commit and the licenses. Read is the only tool needed, nothing
here touches the network.
## Steps
1. Pick: Read `INDEX.md` whole (about 210 short lines) and choose the
guides whose title matches a platform feature or UI pattern the task
uses (a modal is `dialog`, a tooltip a popover, a slow first paint
LCP). No title fits a feature: search the guide bodies under `guides/`
once with the text-search tool at hand, else go on without a guide.
2. Read each chosen guide, plus the discipline guide of each category
touched: the guide whose id equals its category (`html`, `css`, `js`,
`forms`, `accessibility`, `performance`, `security`, `privacy`).
3. Cross-references: a guide line `npx -y modern-web-guidance@latest
retrieve "<id>"` names another guide. Find `<id>` in `INDEX.md` for its
category and Read `guides/<category>/<id>.md`. Never run npx, the
guidance CLI or any network command for this skill.
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
`rules/web-building.md` disagree on how to use the platform, the guide
wins.
5. Disclose: end the answer that delivers the front-end change (a
sub-agent: its report) with one line, `Modern Web Guidance: <id>, <id>`.
Guides checked and none applied: `Modern Web Guidance: checked <topics>,
none applied`. No quotes.
## Missing copy
`INDEX.md` unreadable (the link dangles on a machine that never ran the
install): say once "Modern Web Guidance not installed, run `make update`"
and continue without it.
````
Symlinks (from the repo root):
```bash
ln -s ../../skills-external/mwg/guides skills/modern-web-guidance/guides
ln -s ../../skills-external/mwg/INDEX.md skills/modern-web-guidance/INDEX.md
ln -s ../../skills-external/mwg/NOTICE.md skills/modern-web-guidance/NOTICE.md
```
`skills/modern-web-guidance/test-prompts.json`:
```json
[
{"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": 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"}
]
```
`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**
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 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**
```bash
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"
```
---
### Task 4: Wiring in `rules/web-building.md` and `site-motion`
**Files:**
- Modify: `rules/web-building.md` (after line 5 title; lines 27-29 motion; § Design work Build bullet ≈ line 52-57)
- Modify: `skills/pack-design/skills/site-motion/SKILL.md` (intro paragraph ≈ line 24-27)
- Test: `lib/tests/mwg-skill.test.sh` (append wiring checks)
**Interfaces:**
- Consumes: skill name `modern-web-guidance` (Task 3).
- [ ] **Step 1: Write the failing test** — append before the summary line of `lib/tests/mwg-skill.test.sh`:
```bash
W="$ROOT/rules/web-building.md"
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-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-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-heading "$(grep -qx '## Design work — full toolchain (tiered by scope)' "$W" && echo 1)"
check locked-line "$(grep -qx '- The vendored stack members route to `reflect` (high) through their' "$W" && echo 1)"
check site-motion "$(grep -q '`modern-web-guidance`' "$ROOT/skills/pack-design/skills/site-motion/SKILL.md" && echo 1)"
```
- [ ] **Step 2: Run it to verify it fails** — `make test suite=lib/tests/mwg-skill.test.sh` → the new checks FAIL.
- [ ] **Step 3: Implement**
`rules/web-building.md`, insert after the line `# Web building — no default reflexes + done checklist` and its following blank line:
```markdown
## Modern Web Guidance first
Before writing or changing front-end code (markup, styles, client-side JS,
components), run the `modern-web-guidance` skill: it reads Google's pinned
guides locally. Without the Skill tool (a sub-agent), Read
`~/.claude/skills/modern-web-guidance/SKILL.md` and follow it. Where a
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.
```
Replace the three lines
```
- Motion: transform and opacity only; feedback under 200 ms, ease-out on
entrances, never from scale(0); `will-change` only during an active
animation; pause loops off-screen; honor `prefers-reduced-motion`.
```
with
```
- Motion: transform and opacity for continuous or scroll-linked motion,
other transitions per the Modern Web Guidance guides; feedback under
200 ms, ease-out on entrances, never from scale(0); `will-change` only
during an active animation; pause loops off-screen; honor
`prefers-reduced-motion`.
```
In § Design work, insert right after the Build bullet (after the line ` only for a one-off visual with no project context, not beside impeccable.`):
```
- Every Build step above (impeccable, ui-ux-pro-max, 21st, emil, motion,
design-html, site-motion) must consult `modern-web-guidance` first for
the platform features it uses.
```
`skills/pack-design/skills/site-motion/SKILL.md`: append to the intro paragraph ending `top of it.` a new paragraph:
```markdown
Platform features (scroll-driven animation, view transitions, animating to
intrinsic sizes, reduced motion) come from the `modern-web-guidance` skill
first: read its guide before choosing a library or a technique.
```
- [ ] **Step 4: Run tests**
Run: `make test suite="lib/tests/mwg-skill.test.sh lib/tests/doctrine-citers.test.sh lib/tests/effort-routing.test.sh lib/tests/project-rules.test.sh lib/tests/user-rules.test.sh"`
Expected: `all suites green`.
- [ ] **Step 5: Commit**
```bash
git add rules/web-building.md skills/pack-design/skills/site-motion/SKILL.md lib/tests/mwg-skill.test.sh
git commit -m "feat(rules): front-end work consults modern-web-guidance first"
```
---
### 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). 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`.
- `bash link.sh` → `chrome-extensions` linked.
- `ls skills/modern-web-guidance/INDEX.md` resolves; `grep -c '^- ' skills-external/mwg/INDEX.md` → 210.
- `make doctor` → no new error; `check_vendored_trees` passes both dests.
- Full `make test` (bun on PATH) → green.
@@ -0,0 +1,133 @@
# Modern Web Guidance in the kit — design
Date: 2026-11-21. Contract: `.claude/tasks/contracts/2026-11-21-modern-web-guidance-2314.md`
(all user decisions are in its CLARIFICATIONS). Branch: `feature/modern-web-guidance`.
## Goal
Every front-end task (HTML, CSS, client-side JS, components, in any flow and any profile)
consults Google's Modern Web Guidance before writing code, so the agent applies current
platform practice instead of patterns from its training data. The guidance is read from a
pinned local copy: no npx, no network and no remote code at use time.
## Upstream
`GoogleChrome/modern-web-guidance`, tag v1.0.1 = commit
`64a6d708f5a43f2cd3fde5d4d7db3905ba1bdf65` (2026-11-16). Stewarded by Chrome, Edge,
Firefox and MDN. Code Apache-2.0, guide content CC-BY 4.0.
- `skills/modern-web-guidance/`: `SKILL.md` (runs `npx -y modern-web-guidance@latest
search|retrieve`, never used here) and `guides/<17 categories>/<id>.md`, 210 files,
~2 MB, no frontmatter, id = basename (unique). 174 lines in 67 guides cross-reference
other guides as `npx -y modern-web-guidance@latest retrieve "<id>"`.
- `skills/chrome-extensions/`: `SKILL.md` + `references/` (24 files, no npx); it names the
`modern-web-guidance` skill and maintains a `CHROMEWEBSTORE.md` in extension projects.
## Components
### 1. Pinned fetch (`lib/vendor-skills.sh`, new function)
`vendor_pinned_tree <lock-key> [refresh]` reads a new `plugins.lock.json` entry:
```json
"modern-web-guidance": {
"source": "https://github.com/GoogleChrome/modern-web-guidance",
"tag": "v1.0.1",
"commit": "64a6d708f5a43f2cd3fde5d4d7db3905ba1bdf65",
"trees": {
"mwg": ["skills/modern-web-guidance/guides", "LICENSE"],
"chrome-extensions": ["skills/chrome-extensions"]
},
"always_on": true
}
```
- One `git init` + `git fetch --depth 1 <source> <commit>` in a `mktemp -d` path, checkout
`FETCH_HEAD`, then `git rev-parse HEAD` must equal `commit` (else refuse, nothing written).
- Copies only the listed repo paths into a staging dir per destination; the upstream
`skills/modern-web-guidance/SKILL.md` is never copied.
- For `mwg`: generates `INDEX.md` (one line per guide: `id | category | H1 title`) and an
attribution `NOTICE.md` (source, tag, commit, CC-BY 4.0 for guides, Apache-2.0 code).
- Swaps each staging dir into `skills-external/<dest>` (old dir removed after the new one is
complete), so guides dropped upstream disappear on a pin bump.
- Install mode skips a complete existing copy at the same commit (marker file
`.vendored-commit`); refresh re-fetches; both install a missing copy (fixes the
"refresh skips absent dirs" gap for this entry).
- Same validation as `vendor_pinned_skills`: `commit` 40 lowercase hex, `source`
`https://github.com/<o>/<r>`, paths `[A-Za-z0-9._/-]`, no `..`, no leading `/`. A
`VENDOR_BASE_URL=file://…` override serves the hermetic suite (same rule as the
existing helper).
- Both `skills-external/mwg/` and `skills-external/chrome-extensions/` are gitignored
(machine-owned, regenerated by the install step, LRN-086).
Callers: `install-plugins.sh` Step 8e (`vendor_pinned_tree modern-web-guidance`) and
`update-all.sh` 7.3 (`… refresh`). The pin moves only by editing the lock entry.
### 2. Our skill `skills/modern-web-guidance/` (tracked, ours, always on)
- `SKILL.md` with `name`, `description` (front-end triggers; not backend, infra, tooling;
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`,
`INDEX.md -> ../../skills-external/mwg/INDEX.md`, `NOTICE.md -> ../../skills-external/mwg/NOTICE.md`.
- Workflow in the body:
1. Read `INDEX.md` whole (210 lines, ~14 KB) and pick the guides by title (Grep and
Glob are absent in some sessions, Read always exists); a body search only when a
text-search tool is at hand.
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
`npx … retrieve "<id>"` means: find `<id>` in `INDEX.md`, Read
`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
platform, the guide wins.
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
applied`). No quotes.
- Guides missing (dangling links): say so, remedy `make update`; continue without them.
- `test-prompts.json` (darwin convention).
### 3. chrome-extensions (vendored, always on, as is)
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.
No routing row (untracked linked external; a row would reroute the main loop on load).
### 4. Wiring
- `rules/web-building.md`, new section right after the title: before writing or changing
front-end code, run the `modern-web-guidance` skill; the guide wins on platform usage;
end with its disclosure line. Motion line becomes: "transform and opacity for continuous
or scroll-linked motion; other transitions per the guides". Globs unchanged.
- `§ Design work` (heading kept byte-identical): one line, every step of the stack
(Build, polish, motion, scroll) consults `modern-web-guidance` for the platform
features it uses. This is the only durable route into the foreign design skills.
- `skills/pack-design/skills/site-motion/SKILL.md` (ours): the same line.
- `CLAUDE.global.md` unchanged (320/320); its design pointer already sends design work to
`web-building.md`.
- 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
- `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.
- `lib/tests/vendor-tree.test.sh` on a local git fixture: fetch at the pinned commit,
refuse a mismatching commit, whitelist only (no upstream SKILL.md), INDEX generation,
prune of a dropped guide on refresh, install of an absent copy in refresh mode, path
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
assumed exception to BDR-056.
## Out of scope
Audit skills (a11y, web-validate, guardrails, seo), agents' own briefs, a `.js/.ts` path
glob, a search CLI or embedding index, `legacy-scan`.