forked from bchanot/claude
chore: purge transient planning artifacts (BDR-065)
This commit is contained in:
1 parent
7e29279b24
commit
0dc0814d62
2 files changed
-1218
No files matched your search
File diff suppressed because it is too large.
Load diff
@@ -1,147 +0,0 @@
|
|||||||
# 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>` reads a new `plugins.lock.json` entry:
|
|
||||||
|
|
||||||
```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", "README.md": "README.md"},
|
|
||||||
"chrome-extensions": {".": "skills/chrome-extensions"}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
- 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 | summary`, the
|
|
||||||
summary from the upstream README description, else the guide's H1) 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, restored if the swap fails), so guides dropped upstream disappear on a pin bump.
|
|
||||||
- One mode: a dest whose `.vendored-commit` equals the pin and whose `.vendored-spec`
|
|
||||||
equals its allowlist is skipped; anything else (absent copy, older pin, edited
|
|
||||||
allowlist) is fetched. A dest that exists without `.vendored-commit` is never replaced.
|
|
||||||
A symlink in the fetched content, or a listed path resolving outside the checkout, is
|
|
||||||
refused with nothing swapped.
|
|
||||||
- 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 and `update-all.sh` 7.3, both
|
|
||||||
`if ! vendor_pinned_tree modern-web-guidance; then warn …; fi` (a fetch failure keeps
|
|
||||||
the previous copy and the script goes on). 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>`.
|
|
||||||
- One tracked relative symlink: `mwg -> ../../skills-external/mwg` (INDEX.md, NOTICE.md,
|
|
||||||
guides/ behind it).
|
|
||||||
- Workflow in the body:
|
|
||||||
1. Read `mwg/INDEX.md` whole (~210 lines, ~39 KB with descriptions) and pick the guides
|
|
||||||
by summary (Grep and Glob are absent in some sessions, Read always exists); a body
|
|
||||||
search under `~/.claude/skills/modern-web-guidance/mwg/guides/` only when no summary
|
|
||||||
fits and a text-search tool is at hand.
|
|
||||||
2. Read the matching guide(s). A discipline guide (id = category: html, css, js, forms,
|
|
||||||
accessibility, performance, security, privacy) only for a new component or page, or
|
|
||||||
when no specific guide matched: they are long.
|
|
||||||
3. A guide line `npx … retrieve "<id>"` means: find `<id>` in `mwg/INDEX.md`, Read
|
|
||||||
`mwg/guides/<category>/<id>.md`. Never run npx or any network command for this skill.
|
|
||||||
4. Apply them, keeping the guide's fallbacks and Baseline notes. Where a guide and a rule
|
|
||||||
of `rules/web-building.md` disagree on how to use the platform, the guide wins. An
|
|
||||||
executor whose closed plan contradicts a guide reports it as an open choice.
|
|
||||||
5. The answer that delivers the front-end change (a sub-agent: its report) ends with one
|
|
||||||
line: `Modern Web Guidance: <id>, <id>` (or `Modern Web Guidance: checked <topics>,
|
|
||||||
none applied`). No quotes.
|
|
||||||
- Copy missing (dangling link): say so, remedy `make update`; continue without it.
|
|
||||||
- `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).
|
|
||||||
- model-router: any main-loop Skill call opens the write guard for the session
|
|
||||||
(`st.skillRun`). A reference-skill list (`modern-web-guidance`, `find-docs`) never
|
|
||||||
opens it, so a direct front-end request still gets redirected to /hotfix or /feat
|
|
||||||
(user decision 2026-11-22).
|
|
||||||
|
|
||||||
### 5. Checks and docs
|
|
||||||
|
|
||||||
- `lib/doctor-vendored.sh` `check_vendored_trees`: each git-tree dest's `.vendored-commit`
|
|
||||||
equals the lock commit, else a warning naming `make plugin`; never an error, and doctor
|
|
||||||
survives `set -euo pipefail` when a vendored copy is missing.
|
|
||||||
- `lib/tests/vendor-tree.test.sh` on a local git fixture: fetch at the pinned commit,
|
|
||||||
refuse a commit not upstream, allowlist only (no upstream SKILL.md), INDEX generation,
|
|
||||||
prune of a dropped guide on a pin bump, install of an absent copy, path validation,
|
|
||||||
allowlist edit re-fetched, foreign dest kept, symlinks refused.
|
|
||||||
`lib/tests/mwg-skill.test.sh`: our `SKILL.md` contains no `npx` command to run, Read
|
|
||||||
only, no row, the `mwg` link, 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