Compare commits
3
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
79a48f76c1 | ||
|
|
ea1d5ab400 | ||
|
|
7cc1e6c42d |
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`.
|
||||
Reference in new issue
Block a user