Skip to content

docs(adr): record the five-layer config cascade - #6976

Merged
kyle-sexton merged 3 commits into
mainfrom
docs/adr-five-layer-config-cascade
Oct 11, 2026
Merged

kyle-sexton merged 3 commits into
mainfrom
docs/adr-five-layer-config-cascade

Conversation

@kyle-sexton

Copy link
Copy Markdown
Member

Refs: #6594

Summary

Records ADR 0061: a five-layer plugin config cascade (plugin defaults, userConfig scalar mirror, user-global ~/docs/conventions/<plugin>.*, project team <home>/<plugin>.*, project personal <home>/<plugin>.local.*) read through one shared resolver, lib/config-cascade.mjs. user-interface is the first adopter. The ADR is recorded before the resolver code (PR A) so reviewers have the rationale first.

Fix

Verification

  • ls docs/adr | grep -ci config-cascade → 1; grep -c 6594 → 5; grep -ci "what does not move" → 2 (Phase 1 sanity check).
  • markdownlint-cli2 on the file: 0 issues. typos: clean.
  • No other ADR uses number 0061. Duplicate numbers 0018, 0025, 0028 and 0039 already exist and are left as they are.

Related

PLAN.md

Brief

Restatement: CONFIRMED (user, 2026-10-10, "Confirmed.")

TLDR

  • New skill /user-interface:write-css: CSS techniques absorbed from good-css (MIT, pinned b645ab15b9fc), restructured by topic as the first source of a long-lived master CSS skill, with a read-only review mode
  • The project's design system and conventions override every shipped default; any stack is handled by a fixed four-step discovery process, never per-framework files
  • New /user-interface:setup skill and a five-layer config cascade (plugin defaults, userConfig scalar mirror, user-global, project team, project .local) read through one shared resolver; everything sensible is configurable
  • docs/upstream/good-css.md attribution record, design detector extension and routing row, presence-gated cross-references from prototype and visualization
  • Evals written before skill text; work split across separate worktrees and feature branches

Goal

Agents writing or reviewing CSS in any consuming project apply modern, self-adapting CSS techniques without fighting that project's own design system, stack, browser targets or conventions. The skill discovers each project's stack and styling setup, fills only the gaps the project leaves, says which of its own defaults it used, and lets teams and individuals reconfigure every behavior that a consumer could reasonably need to change.

Constraints

  • Absorb, do not depend: restructure freely (take verbatim, move, reword, drop) to fit this repo's philosophy and Anthropic skill best practices (C1, C9)
  • Long-lived master skill: content split by topic, not by source, so later CSS sources merge in; the name carries no source (C10, Q14, Q18)
  • Lives in the user-interface plugin; no new plugin (C7, Q2)
  • Project first: the project's design system, conventions, lint config and layer system beat every good-css default, including always-on rules, linter findings and CSS placement (C2, Q3, Q23-Q26)
  • Never enumerate frameworks or libraries; stacks are discovered per project through a fixed process (C11, C15, Q13, Q22)
  • Skills cross-reference only through public /plugin:skill names, presence-gated (C12, Q6, Q20)
  • Credits and provenance live in docs/upstream/good-css.md and the CHANGELOG, never in skill files; MIT notice travels with copies, and the bundled linter keeps a vendor/LICENSE (C4, C8, C13, Q5, Q21)
  • Volatile specifics are pointers with an as-of date and recheck trigger, not copies (C5, Q27)
  • An always-on instruction needs eval evidence; one without measurable improvement moves to the on-demand references (C6, Q19)
  • Config cascade: plugin defaults, userConfig scalar mirror, user-global, project team (checked in), project .local personal overlay; locations resolved through one shared resolver, docs/conventions only a default (C16, Q34, Q35, Q39, D14, R5)
  • Everything sensible is configurable; each fixed default is a stated assumption (C18)
  • All work on separate worktrees and feature branches (C14)
  • Mechanism decisions belong to /planning:plan (Q8)

Acceptance criteria

  • /user-interface:write-css exists in plugins/user-interface, passes /skill-quality:check, and its description triggers on CSS authoring and review requests without overlapping /user-interface:design
  • All 47 upstream techniques are present in topic-organized reference files, each with a one-line rationale and a Baseline status pointer; no upstream browser-version numbers are copied; the six techniques without upstream support lines have a pointer
  • Upstream "Left out on purpose" content appears as the skill's Gotchas; upstream "Next" is not carried
  • No skill file contains upstream credits, author names or source links; docs/upstream/good-css.md holds the pinned commit, recheck trigger (new commit to PRACTICES.md or a Baseline change for a used technique), per-technique credits and the MIT notice, and the CHANGELOG entry carries the notice
  • Before writing CSS, the skill runs the four-step process: detect stack-agnostic facts (browser targets, token sources, lint config, style file kinds), identify the stack and research unknowns (presence-gated /context7:lookup, /discovery:research, /discovery:explore, else official docs), answer the six-question checklist, and verify compiled output when scoping or a build step rewrites CSS
  • When the project states a convention, the skill follows it over any good-css rule; always-on rules apply only where the project is silent
  • The skill never invents a token value; when no token exists it follows the configured token_fallback (default ask)
  • Browser target resolves from skill argument, then project browserslist, then configured target, defaulting to Baseline widely available; a technique newer than the target gets an @supports fallback or is skipped with a stated reason
  • New CSS goes in a low-priority @layer only when the project has no layer system; otherwise it uses the project's mechanism; !important appears only with a stated reason
  • Review mode edits nothing, reports file:line findings, runs the bundled linter first, points at the project's Stylelint or @eslint/css rules when present, and lists findings that contradict project conventions under a suppressed heading rather than dropping them
  • Every setting in the Design's settings schema (## Design > Contracts, reference/team.schema.json) is configurable at the documented layers, read through one shared resolver with no hard-coded path in skill text; a written list names every fixed default and why it is fixed
  • /user-interface:setup supports check and apply, writes the team layer at the resolved convention home and the user-global layer with --user
  • design's detector reports browserslist, token sources and lint config; design's routing data has a css-authoring row pointing at the new skill
  • /prototype:explore-directions and /visualization:visualize reference the new skill presence-gated
  • Eval suite exists before the skill body and covers each always-on rule (with vs without), a scoped-styles case, an existing-token-set case and review mode; always-on rules lacking a measurable improvement are in references, not the body
  • IF a research tool is missing or unreachable, THEN the skill marks which checklist answers it could not verify instead of guessing
  • WHILE the project has no token sources, the skill uses its own defaults and names each default it used

Captured assumptions

Out-of-scope

  • Any check, record or dependency for is-agentic.com (Q7)
  • Per-framework or per-library reference files (Q13, Q16)
  • Repo-wide decision on config format and folder layout (Q38; tracked on feat(conventions): one setup lifecycle for where plugins store team conventions and settings #6594)
  • A review-criteria document for the review plugin to consume (Q17)
  • A copy of upstream files committed to the repo for drift diffing (Q29)
  • userConfig options beyond the four scalar css_* keys (Q37, revised by R5)

Deferred questions

  • Q31: How the work splits into pull requests and how each plugin's version or changelog fragment is bumped, defer until planning; arbiter: /planning:plan
  • Q32: Eval case count, runs per case, cost ceiling and pass thresholds, defer until planning; arbiter: /planning:plan
  • Q33: Bundle check-css.mjs unmodified behind a wrapper or modified, defer until planning; arbiter: /planning:plan

Design

Threads: design/design-threads.md (D1-D14, plan-review fixes R1-R9). Full contracts: design/contracts.md.

Module layout

lib/                                       (repo root, canonical, ADR 0019)
├── config-cascade.mjs                     five-layer resolver, provenance, legacy-file report; takes `home` as input
├── config-cascade.test.{mjs,sh}
├── yaml-subset.mjs                        promoted from plugins/user-experience/scripts/lib/yaml-subset.mjs
└── yaml-subset.test.{mjs,sh}              the only yaml-subset suite
docs/adr/NNNN-five-layer-config-cascade.md recorded before PR A (R8)
plugins/user-interface/
├── .claude-plugin/plugin.json             userConfig: css_browser_target, css_important, css_layer, css_token_fallback
├── lib/resolve-convention-home.sh         generated copy; spawned by detect.mjs (R1)
├── reference/
│   ├── defaults.yaml                      layer 1
│   ├── team.schema.json                   one schema; `routing` accepted in layer 4 only
│   ├── routing.json                       + css-authoring row
│   └── types/web.md                       concern list and fallback section point to write-css
├── scripts/
│   ├── detect.mjs                         + --config, --team FILE (seam), --user-config FILE; project.{browserslist,lint,style_files}
│   ├── check-good-css-drift.sh            --check, row in the weekly drift workflow
│   └── lib/config-cascade.mjs, lib/yaml-subset.mjs   generated copies
├── skills/
│   ├── design/                            routes css-authoring to write-css
│   ├── write-css/
│   │   ├── SKILL.md
│   │   ├── reference/{foundations,layout,spacing-and-shape,text-and-media,interaction,motion,show-and-hide,scroll-and-viewport,stack-discovery,review,configuration}.md
│   │   ├── scripts/review.mjs
│   │   ├── vendor/{check-css.mjs,LICENSE}  unmodified upstream (R7)
│   │   └── evals/
│   └── setup/{SKILL.md,evals/evals.json}  disable-model-invocation: true
├── tests/                                 *.test.sh -> node --test
└── README.md                              fixed-defaults list
docs/upstream/good-css.md                  pin, blob SHAs, recheck trigger, credits, MIT notice
plugins/prototype/skills/explore-directions, plugins/visualization/skills/visualize   presence-gated pointers

Dependency direction: skills -> scripts/detect.mjs -> {lib/resolve-convention-home.sh, scripts/lib/config-cascade.mjs -> scripts/lib/yaml-subset.mjs}; write-css review mode -> scripts/review.mjs -> vendor/check-css.mjs, with the resolved config passed in as JSON (R4). The shared lib spawns nothing (R1). No plugin depends on another plugin's files; cross-plugin references are public /plugin:skill names only.

Contracts

Config cascade, later wins per key:

1 plugin defaults            plugins/user-interface/reference/defaults.yaml            shipped
2 userConfig                 settings.json pluginConfigs, scalar keys only (css_*)      user, not committed
3 user-global file           ~/docs/conventions/user-interface.{yaml,md}              user, not committed
4 project team               <home>/user-interface.{yaml,md}  (<home> default docs/conventions)   committed
5 project personal           <home>/user-interface.local.{yaml,md}                     gitignored

Merge: scalars later-wins; *.disable lists union; invalid value rejected with a message, lower layer keeps the key; routing accepted only in layer 4, rejected in 2, 3 and 5 (R6); every value carries its source layer; prose layers 3-5 concatenate; the detected project design system outranks every configured default. Layers 3 and 5 deviate from docs/conventions/config-cascade/README.md "What does not move" (lines 30-36, 84-86); the deviation is recorded by the ADR in Phase 1 and the Implementers row (R8).

Settings schema (reference/team.schema.json, additionalProperties: false, block-style YAML; yaml-subset rejects {):

version: 1
css:
  browser_target: "baseline widely available"   # browserslist query
  techniques:
    disable: []                                 # upstream technique slugs
  rules:
    disable: []                                 # hover|logical|outline|ease-in|color|transition-all|motion|duration
  important: avoid                              # avoid | utilities-only | allow
  layer: null                                   # null = project's own layer order
  token_fallback: ask                           # ask | propose-token | literal
routing:                                        # layer 4 only (R6)
  version: 1
  rows: []
  disable: []
  deny: []

userConfig (layer 2, R5): css_browser_target (string), css_important (string, options avoid, utilities-only, allow), css_layer (string), css_token_fallback (string, options ask, propose-token, literal). Lists live only in files. The skill writes the ${user_config.css_*} values to a temp JSON file with the Write tool and passes --user-config FILE to detect.mjs; substituted text never reaches a shell parser.

Resolver:

resolve({ plugin, projectRoot, home, schema, defaults, userConfig, teamOnly }) ->
  { values, provenance: { "<key>": "<layer>" }, prose: [paths],
    layers: [{ name, path, state: loaded|absent|invalid, errors }],
    legacy: [{ path, kind }] }

home is resolved by the caller (R1); teamOnly lists keys accepted only in layer 4, so the lib holds no plugin key names.

Detector (R2, R3): --config adds top-level config (resolver output); --team FILE replaces the resolved team file (test seam, user-experience meaning); --user-config FILE supplies layer 2; project gains browserslist {query, source}, lint {stylelint, eslint_css, config_paths}, style_files [kinds].

Review output (scripts/review.mjs --config FILE|JSON <paths>; exit 0 clean, 1 findings, 2 usage or crash; never spawns detect.mjs):

## Findings     path:line [rule-id] message
## Suppressed   path:line [rule-id] message — reason (config: rules.disable | project convention: <evidence>)
## Judgment     items no linter checks

Setup: /user-interface:setup check|apply [--user|--local]; check reports values with provenance, invalid keys, duplicate layer-2/3 keys, legacy files with a migrate offer, .local ignore state, and warns when this worktree lacks <home>/user-interface.local.* while the main checkout has one; apply edits one key per layer, adds the gitignore entry, adds the user-global pointer after a yes (chezmoi source when managed), offers to save stack-checklist answers.

Vendored upstream (pin b645ab15b9fcd059c0227c21b6a144bb70639f1a, git hash-object blob SHAs): scripts/check-css.mjs 6fa72714ba18cf02f698fa8015f63df043b3af85 -> skills/write-css/vendor/check-css.mjs; LICENSE 66a325d82e56f2f41ebd14812517d6c50f5b66da -> skills/write-css/vendor/LICENSE; PRACTICES.md 7d746e65d56ee4910572b75738051482f4735f38 (drift source only). Local copies: .work/good-css/raw/.

Routing row (JSON, in routing.json): {"concern":"css-authoring","rank":1,"id":"/user-interface:write-css","kind":"skill","detect":"user-interface","account":"none","status":"confirmed","platforms":["windows","macos","linux"],"as_of":"2026-10-10"}.

Variation verdicts

  • Every css: setting: varies, through the five-layer cascade (D3, D5, D14); lists only through files (R5)
  • Config locations and format: varies, through the shared resolver only (D4); repo-wide shape decided on feat(conventions): one setup lifecycle for where plugins store team conventions and settings #6594
  • Stack and framework handling: varies, through the four-step discovery process, never per-framework files (C15)
  • Guidance sources: varies, through routing rows under concern: css-authoring, team layer only (D11, R6)
  • Browser target: varies, skill argument > project browserslist > configured target > default (Q4)
  • Linter run and suppressed-findings display: varies, per-run skill arguments
  • Held fixed, each listed with its reason in reference/configuration.md and the README: topic split of reference files (merge target for later sources), review output sections and exit codes (contract for callers), the four-step process order (step 3 depends on 1-2), project-first precedence (C2)

Conventions followed and deviations

  • docs/conventions/routing-as-data/README.md (team file <home>/<plugin>.yaml, routing rows)
  • docs/conventions/config-cascade/README.md: merge rules followed; layer locations deviate (user-global ~/docs/conventions/, overlay <home>/*.local.*, userConfig scalar mirror), recorded in the Phase 1 ADR and the Implementers row (R8)
  • docs/adr/0019-share-code-across-plugins-by-vendoring-with-a-sync-gate.md, scripts/shared-copies.txt, scripts/sync-shared-copies.sh
  • docs/adr/0044 (structured team config): deviation recorded in the Phase 1 ADR, pending feat(conventions): one setup lifecycle for where plugins store team conventions and settings #6594
  • plugins/user-experience/scripts/detect.mjs (home resolution at line 150, --team seam), plugins/user-experience/skills/setup/SKILL.md (team read and setup flow)
  • plugins/multi-agent/scripts/resolve-roles.sh (layer merge model)
  • plugins/playwright/skills/playwright/vendor/ (vendored third-party with LICENSE; typos exclusion plugins/*/skills/*/vendor/**)
  • .github/workflows/maintenance-check-upstream-drift.yml (one matrix row per vendored upstream)
  • plugins/source-control/skills/worktree/context/create.md "Create the worktree" (substituted text written with the Write tool, never parsed by a shell)
  • docs/upstream/humanlayer-skills.md, docs/conventions/upstream-drift/README.md (absorption record)
  • scripts/fragment-plugins.txt (changelog fragments for user-interface)
  • plugins/playbooks/skills/skill-authoring/reference/skill-criteria.md (skill standard)

Plan

Approval: approved by the user in session on 2026-10-10 ("sounds good, approved, go with recommendations"), covering review changes R1-R9 and the Q37 reconfirmation

Scale: Large (an ADR, a new shared repo-level library vendored into plugins, a new config surface, two new skills, five pull requests).

Goal

What: Record the five-layer cascade decision, then ship /user-interface:write-css (good-css techniques absorbed by topic, project-first, four-step stack discovery, read-only review mode), the /user-interface:setup skill and the layered config it manages, read through one shared resolver lib/config-cascade.mjs.
Why: Agents writing or reviewing CSS should apply modern techniques without overriding a project's design system, stack, browser targets or conventions, and teams and individuals must be able to reconfigure every behavior a consumer could reasonably change (Brief: Goal, C2, C18).
Done when: the ADR PR and PRs A-D are merged with ci-status green; every Brief acceptance criterion maps to a phase Sanity Check below that passed; the three-arm eval run is recorded on PR C; the follow-up issue exists.

Standards grounding

Surface Sections cited Layer provenance
Repo agent rules AGENTS.md: open as draft, Conventional Commits title, stop list, fragment changelog, scope test team
PR body contract .claude/rules/pr-body-contract.md: Closes/Refs:/No related issue: first line, Summary/Fix/Verification/Related team
Skill bodies .claude/rules/skill-bodies-state-current-rules.md: pointer + as-of date + recheck trigger for volatile specifics (Baseline status), ## Next section team
Eval cases .claude/rules/eval-case-transcripts.md: no raw transcripts in evals/** team
Cost claims .claude/rules/cost-claims.md: no prices; eval cost points at the evals plugin ceiling team
Skill standard plugins/playbooks/skills/skill-authoring/reference/skill-criteria.md: Frontmatter, Descriptions, Body, Reference files, History and provenance, Measurement team
Config cascade docs/conventions/config-cascade/README.md: The layers (30-36), What does not move (84-86), Merge semantics, Deviations, Implementers (+ generated "Semantics at a glance" via scripts/sync-config-cascade-semantics.py) team
ADRs /architecture:record-decision into docs/adr/ team
Routing as data docs/conventions/routing-as-data/README.md: team file <home>/<plugin>.yaml, Adopters table team
Shared code ADR 0019, scripts/shared-copies.txt, scripts/sync-shared-copies.sh (--check, --check-bump) team
Changelog scripts/fragment-plugins.txt: user-interface (line 86), prototype (70), visualization (88) are fragment mode; user-experience is not team
Upstream record and drift docs/upstream/humanlayer-skills.md shape; .github/workflows/maintenance-check-upstream-drift.yml matrix rows (skill, script, args, drift, unverifiable) team
Vendored code .github/workflows/pr-require-checks.yml:809-816 typos exclusion plugins/*/skills/*/vendor/** team
Setup precedent plugins/user-experience/skills/setup/SKILL.md (check/apply, per-key block YAML), plugins/developer-experience/skills/setup/SKILL.md (--user pointer flow, chezmoi check) team

Approach

The work ships as five pull requests, each on its own worktree and feature branch (C14), in dependency order. Q31 is resolved here. [EXEC-SHAPE]

PR Branch (own worktree) Title Phases Depends on Changelog
ADR docs/adr-five-layer-config-cascade docs(adr): record the five-layer config cascade 1 none none (no plugin files)
A feat/config-cascade-lib feat(lib): add shared config-cascade resolver and canonical yaml-subset 2-3 ADR merged (A may be drafted while the ADR is in review) user-experience: plugin.json version bump + CHANGELOG.md entry (not fragment mode; its yaml-subset.mjs becomes a generated copy and its yaml-subset suite moves to lib/)
B feat/user-interface-config feat(user-interface): add layered config and /user-interface:setup 4-5 A merged .changes/user-interface/ fragment
C feat/good-css-skill (this worktree) feat(user-interface): add /user-interface:write-css 6-8 B merged .changes/user-interface/ fragment carrying the MIT notice
D feat/write-css-pointers feat: point prototype and visualization at /user-interface:write-css 9 C merged one fragment each under .changes/prototype/ and .changes/visualization/
close-out none n/a 10 A merged none

Every PR opens as a draft and its body follows the PR body contract: Refs: #6594 for the ADR PR, A and B, whose config shape that issue may change; C and D open with a Refs: line to a tracking issue if a search finds one, else No related issue: <reason>; then ## Summary, ## Fix, ## Verification, ## Related. Ready-flip and merge follow AGENTS.md's stop list (ask the user). B and C each start from main after the previous PR merges, because sync-shared-copies.sh --check-bump <base> compares canonicals against the base [EXEC-SHAPE]; stacking on the previous branch is the fallback if a PR stalls in review [FALLBACK].

Q33 (bundle check-css.mjs unmodified or modified) is resolved by Design D6: unmodified vendored copy behind scripts/review.mjs, at skills/write-css/vendor/ (R7). Not re-decided.

Dependencies

  • Upstream: lib/resolve-convention-home.sh (existing canonical), user-experience scripts/lib/yaml-subset.mjs (promoted), upstream scripts/check-css.mjs and LICENSE at b645ab15b9fc (.work/good-css/raw/, data only).
  • Downstream: skills/design/SKILL.md, tests/detect.test.mjs (line 55 asserts the exact project key set), README.md, prerequisites.json mention detect.mjs; tests/routing.test.mjs and routing.schema.json read routing.json; user-experience scripts/detect.mjs and tests/yaml-subset.test.mjs import yaml-subset.mjs; CI runs sync-shared-copies.sh --check, run-plugin-tests.sh, sync-config-cascade-semantics.py --check, typos (vendor excluded) and the changelog-fragment checks; the weekly drift workflow gains one row.

Test strategy

Test-first (Red-Green-Refactor) for every script; evals before skill text (Brief AC). Test types per /testing:plan classification: script logic gets deterministic node --test suites behind *.test.sh wrappers (Design D10); skill behavior gets claude plugin eval cases. Every detector run in tests and sanity checks passes the fixture seams (--home <scratch>, --plugin-list-json plugins/user-interface/tests/fixtures/plugin-list.json, --mcp-list plugins/user-interface/tests/fixtures/mcp-list.txt), so no live claude call.

Test boundaries (approval settles them):

Boundary Status First failing test
lib/yaml-subset.mjs exported parse API existing (user-experience), relocated lib/yaml-subset.test.mjs moved from plugins/user-experience/tests/yaml-subset.test.mjs, red until the file exists; the user-experience suite is removed
lib/config-cascade.mjs resolve({plugin, projectRoot, home, schema, defaults, userConfig, teamOnly}) new five-layer later-wins, *.disable union, invalid value keeps lower layer with an error, teamOnly key rejected in layers 2, 3, 5, provenance per key, prose order 3-4-5, legacy[] report, absent layers state: absent, no spawn of any script
plugins/user-interface/reference/defaults.yaml new tests/defaults.test.mjs parses the shipped file with yaml-subset and validates it against team.schema.json
plugins/user-interface/scripts/detect.mjs CLI JSON existing, additive fields tests/detect.test.mjs: project.browserslist, project.lint, project.style_files; --config top-level config with per-key provenance across layers 1-5; --team FILE seam; --user-config FILE; line 55 key-set assertion updated
reference/team.schema.json new unknown key, bad enum and layer-5 routing rejected through the resolver tests
reference/routing.json existing tests/routing.test.mjs asserts a css-authoring rank-1 own-plugin row
skills/write-css/scripts/review.mjs CLI new stdout sections ## Findings / ## Suppressed / ## Judgment, rule ids, rules.disable suppression from --config JSON, exit 0 clean / 1 findings / 2 usage or crash (a missing path must exit 2, not 1)
scripts/check-good-css-drift.sh --check new tests/check-good-css-drift.test.sh with a stubbed fetch: same SHAs exit 0, changed SHA exit 1, fetch failure exit 2
claude plugin eval cases plugins/user-interface/evals/css-* new baseline run without the plugin before SKILL.md exists

Edge cases: empty and comment-only YAML layers; a key valid in layer 4 and invalid in layer 5; a symlinked or .claude/ convention home (FAIL, as in user-experience setup); a file with no <style> block; an uppercase .CSS suffix; browserslist in package.json versus .browserslistrc; a userConfig value containing shell metacharacters (reaches detect.mjs only as file content).

Eval sizing (Q32, resolved here) [EXEC-SHAPE]: 17 cases. Cases 1-8 run in three arms (body: the skill with the rule in SKILL.md; reference: a variant plugin copy under .work/good-css/arm-reference/ with that rule moved to its topic reference; without: no plugin) at runs: 5; cases 9-17 run with versus without at runs: 3, matching the existing ten cases (for example plugins/user-interface/evals/conflicting-request-project-wins/case.yaml).

# Case Checks
1-8 css-rule-hover, -logical, -outline, -ease-in, -color, -transition-all, -motion, -duration one per "In all CSS" rule, three arms; deterministic regex grader where the rule is lexical, model-graded otherwise
9 css-scoped-styles scoped or compiled styles: stack discovered, compiled output checked
10 css-existing-tokens uses the project's tokens, invents none
11 css-no-tokens uses its own defaults and names each
12 css-token-fallback-ask no matching token: asks (default token_fallback: ask)
13 css-project-convention-wins a stated convention beats a good-css rule
14 css-browser-target a technique newer than the browserslist target gets @supports or a stated skip
15 css-research-tool-missing marks unverified checklist answers
16 css-review-mode edits nothing, path:line findings, linter first, Suppressed heading
17 css-control-no-trigger non-CSS and pure design requests do not fire write-css

Keep-in-body threshold (R9): an always-on rule stays in SKILL.md only when the body arm passes at least 4 of 5 runs and beats the reference arm by at least 2 runs; otherwise it moves to its topic reference (C6). The with-versus-without delta is still recorded. Basis: judgment inside the deferred Q32. Cost: /evals:plugin-eval prints the estimate per arm and passes the evals plugin's configured max_cost_usd ceiling; if the estimate exceeds it, run by tag in batches instead of raising the ceiling unasked. If the CLI cannot point a run at the variant copy, run the reference arm from a temporary branch holding the variant. [FALLBACK]

Phase 1: Record the five-layer cascade decision (ADR PR, before PR A) [TODO]

Review: architecture

  • Run /architecture:record-decision for the target five-layer cascade: user-global ~/docs/conventions/<plugin>.{yaml,md}, project personal <home>/<plugin>.local.{yaml,md}, userConfig scalar mirror, one shared resolver lib/config-cascade.mjs that takes the resolved home as input; user-interface as first adopter; links feat(conventions): one setup lifecycle for where plugins store team conventions and settings #6594 (which may supersede it); states the deviation from docs/conventions/config-cascade/README.md "What does not move" (lines 30-36, 84-86) and from ADR 0044's structured team config. [EXEC-SHAPE]
  • Open the ADR PR as a draft (Refs: #6594).
  • Sanity Check: ls docs/adr | grep -ci "config-cascade" returns at least 1; grep -c "6594" docs/adr/*config-cascade*.md returns at least 1; grep -ci "what does not move" docs/adr/*config-cascade*.md returns at least 1.

Phase 2: Canonical yaml-subset (PR A, structural) [TODO]

Review: architecture

  • Pre-flight (FIRST): grep -rn "yaml-subset" plugins lib scripts and record every importer (known: user-experience scripts/detect.mjs, tests/yaml-subset.test.mjs); confirm none depends on a path other than scripts/lib/yaml-subset.mjs.
  • Red: move plugins/user-experience/tests/yaml-subset.test.{mjs,sh} to lib/yaml-subset.test.{mjs,sh} pointing at lib/yaml-subset.mjs; the tests live once.
  • Green: create lib/yaml-subset.mjs with the user-experience file's body unchanged; register lib/yaml-subset.mjs plugins/user-experience/scripts/lib/yaml-subset.mjs in scripts/shared-copies.txt; run scripts/sync-shared-copies.sh so the user-experience file becomes a generated copy (header only). Migrating user-experience onto the resolver stays a follow-up (Design D4). [EXEC-SHAPE]
  • Bump the user-experience plugin.json patch version and add a CHANGELOG.md entry.
  • Sanity Check: bash lib/yaml-subset.test.sh exits 0; test ! -e plugins/user-experience/tests/yaml-subset.test.mjs exits 0; bash scripts/sync-shared-copies.sh --check exits 0; diff <(git show main:plugins/user-experience/scripts/lib/yaml-subset.mjs) lib/yaml-subset.mjs exits 0.

Phase 3: Shared resolver lib/config-cascade.mjs (PR A) [TODO]

Review: architecture

  • Red: lib/config-cascade.test.mjs + .test.sh with fixtures under lib/fixtures/config-cascade/ covering every resolver edge case in the Test strategy table.
  • Green: implement resolve() per Design Contracts (five layers, merge rules, teamOnly, provenance, layers[] state, legacy[]); home is an input, never resolved inside the lib (R1); no plugin-specific key names.
  • Refactor; open PR A as a draft with the PR body contract, linking the ADR PR.
  • Sanity Check: bash lib/config-cascade.test.sh exits 0; grep -cwE "user-interface|css" lib/config-cascade.mjs returns 0; grep -cE "spawn|execFile|resolve-convention-home" lib/config-cascade.mjs returns 0; bash scripts/run-plugin-tests.sh --list | grep -c "lib/config-cascade.test.sh" returns 1.

Phase 4: user-interface config surface and detector (PR B) [TODO]

Review: code-design

  • Pre-flight (FIRST): grep -rn "detect.mjs\|routing.json" plugins/user-interface .github scripts and list each parser of the detector JSON (known: skills/design/SKILL.md, tests/detect.test.mjs line 55 exact key set, README.md, prerequisites.json).
  • Register copies in scripts/shared-copies.txt: lib/config-cascade.mjs and lib/yaml-subset.mjs into plugins/user-interface/scripts/lib/, lib/resolve-convention-home.sh into plugins/user-interface/lib/; run the sync script.
  • Red then green: reference/defaults.yaml (layer 1, block-style values from Design Contracts) with tests/defaults.test.mjs loading and validating it; reference/team.schema.json (additionalProperties: false, css plus the existing routing shape, routing team-only); detect.mjs resolves the home through lib/resolve-convention-home.sh (as user-experience detect.mjs:150) and passes it to resolve(), adds --config, --team FILE seam, --user-config FILE, and project.browserslist, project.lint, project.style_files; tests in tests/detect.test.mjs plus fixtures, line 55 updated.
  • .claude-plugin/plugin.json userConfig: css_browser_target, css_important (options), css_layer, css_token_fallback (options), per R5.
File Action Rationale
[ ] scripts/shared-copies.txt MODIFY three registrations
[ ] plugins/user-interface/scripts/lib/config-cascade.mjs CREATE generated copy
[ ] plugins/user-interface/scripts/lib/yaml-subset.mjs CREATE generated copy
[ ] plugins/user-interface/lib/resolve-convention-home.sh CREATE generated copy, spawned by detect.mjs
[ ] plugins/user-interface/reference/defaults.yaml CREATE layer 1
[ ] plugins/user-interface/reference/team.schema.json CREATE schema, routing team-only
[ ] plugins/user-interface/scripts/detect.mjs MODIFY --config, --team, --user-config, project fields
[ ] plugins/user-interface/tests/detect.test.mjs MODIFY new cases, line 55 key set
[ ] plugins/user-interface/tests/defaults.test.{mjs,sh} CREATE shipped defaults load and validate
[ ] plugins/user-interface/tests/fixtures/<new> CREATE browserslist, lint, five-layer config fixtures
[ ] plugins/user-interface/.claude-plugin/plugin.json MODIFY four scalar css_* userConfig keys
[ ] plugins/user-interface/skills/design/SKILL.md KEEP additive fields; audited
  • Sanity Check: bash plugins/user-interface/tests/detect.test.sh exits 0; bash plugins/user-interface/tests/defaults.test.sh exits 0; bash scripts/sync-shared-copies.sh --check exits 0; node plugins/user-interface/scripts/detect.mjs --project plugins/user-interface/tests/fixtures/with-ds --home "$(mktemp -d)" --plugin-list-json plugins/user-interface/tests/fixtures/plugin-list.json --mcp-list plugins/user-interface/tests/fixtures/mcp-list.txt --config | node -e 'const j=JSON.parse(require("fs").readFileSync(0));process.exit(["browserslist","lint","style_files"].every(k=>k in j.project)&&j.config&&"provenance" in j.config?0:1)' exits 0; node -e 'const u=require("./plugins/user-interface/.claude-plugin/plugin.json").userConfig;process.exit(Object.keys(u).filter(k=>k.startsWith("css_")).sort().join()==="css_browser_target,css_important,css_layer,css_token_fallback"?0:1)' exits 0.

Phase 5: /user-interface:setup and convention rows (PR B) [TODO]

  • plugins/user-interface/skills/setup/SKILL.md, disable-model-invocation: true, check|apply [--user|--local] per Design Contracts, modeled on /user-experience:setup and the /developer-experience:setup --user flow (edit the chezmoi source when the file is managed); writes userConfig values to a temp file with the Write tool, never into a shell command; check warns when this worktree has no <home>/user-interface.local.* while the main checkout (first entry of git worktree list --porcelain) has one.
  • plugins/user-interface/skills/setup/evals/evals.json: cases for check output showing provenance per key, the missing-.local-in-worktree warning, and apply writing one key.
  • docs/conventions/config-cascade/README.md Implementers row for user-interface recording the deviation from "What does not move" and citing the Phase 1 ADR; run scripts/sync-config-cascade-semantics.py.
  • docs/conventions/routing-as-data/README.md Adopters row for user-interface: team-layer implementer with css keys, routing team-only, and the structured personal-layer deviation.
  • README config section; a user-interface fragment via scripts/new-changelog-fragment.sh; open PR B as a draft.
  • Sanity Check: bash plugins/skill-quality/scripts/check-skill.sh --require-evals plugins/user-interface/skills exits 0; python3 scripts/sync-config-cascade-semantics.py --check exits 0; grep -c "plugins/user-interface" docs/conventions/config-cascade/README.md returns at least 1; grep -c "provenance" plugins/user-interface/skills/setup/evals/evals.json returns at least 1; ls .changes/user-interface/ | wc -l returns at least 1.

Phase 6: Eval suite before skill text (PR C) [TODO]

  • Create the 17 cases in the Test strategy table under plugins/user-interface/evals/css-*/ (case.yaml, scaffold.sh, graders/*.md, samples/*.json) and plugins/user-interface/skills/write-css/evals/evals.json; cases 1-8 at runs: 5, cases 9-17 at runs: 3; no raw transcripts (eval-case rule). [EXEC-SHAPE]
  • Baseline run without the plugin via /evals:plugin-eval; record per-case pass counts in the PR C body.
File Action Rationale
[ ] plugins/user-interface/evals/css-rule-{hover,logical,outline,ease-in,color,transition-all,motion,duration}/ CREATE one per always-on rule, three arms
[ ] plugins/user-interface/evals/css-scoped-styles/ CREATE scoped styles
[ ] plugins/user-interface/evals/css-existing-tokens/ CREATE token set
[ ] plugins/user-interface/evals/css-no-tokens/ CREATE defaults named
[ ] plugins/user-interface/evals/css-token-fallback-ask/ CREATE token_fallback
[ ] plugins/user-interface/evals/css-project-convention-wins/ CREATE C2
[ ] plugins/user-interface/evals/css-browser-target/ CREATE Q4 order
[ ] plugins/user-interface/evals/css-research-tool-missing/ CREATE IF/THEN AC
[ ] plugins/user-interface/evals/css-review-mode/ CREATE review AC
[ ] plugins/user-interface/evals/css-control-no-trigger/ CREATE trigger boundary
[ ] plugins/user-interface/skills/write-css/evals/evals.json CREATE skill-creator format
  • Sanity Check: python3 -I plugins/evals/skills/validate/scripts/validate-cases.py plugins/user-interface/evals exits 0; ls -d plugins/user-interface/evals/css-* | wc -l returns 17; grep -L "runs: 5" plugins/user-interface/evals/css-rule-*/case.yaml prints nothing; ls plugins/user-interface/evals/css-*/case.yaml | grep -v css-rule- | xargs grep -L "runs: 3" prints nothing.

Phase 7: Review script and vendored linter (PR C) [TODO]

Review: security

  • Copy upstream scripts/check-css.mjs and LICENSE unmodified from .work/good-css/raw/ to plugins/user-interface/skills/write-css/vendor/ (Design D6, R7, Q33).
  • Red: plugins/user-interface/tests/review.test.mjs + .test.sh with CSS and HTML fixtures and a config JSON fixture (each rule id, a rules.disable suppression, a missing path, a crash path).
  • Green: skills/write-css/scripts/review.mjs imports check()/checkFile() from ../vendor/check-css.mjs, expands globs, reads the resolved config from --config FILE|JSON (never spawns detect.mjs, R4), prints the three sections with rule ids, exits 0/1/2.
  • Sanity Check: bash plugins/user-interface/tests/review.test.sh exits 0; git hash-object plugins/user-interface/skills/write-css/vendor/check-css.mjs prints 6fa72714ba18cf02f698fa8015f63df043b3af85; git hash-object plugins/user-interface/skills/write-css/vendor/LICENSE prints 66a325d82e56f2f41ebd14812517d6c50f5b66da; node plugins/user-interface/skills/write-css/scripts/review.mjs --config '{}' does-not-exist.css; test $? -eq 2 exits 0; grep -cE "detect\.mjs|spawn" plugins/user-interface/skills/write-css/scripts/review.mjs returns 0.

Phase 8: write-css skill, references, routing, attribution and drift row (PR C) [TODO]

Review: code-design

  • Pre-flight (FIRST): grep -rn "concern" plugins/user-interface/tests/routing.test.mjs plugins/user-interface/reference/routing.schema.json to confirm the row shape the schema and tests accept.
  • SKILL.md: precedence, four-step process (config read through detect.mjs --config, userConfig values written to a temp file with the Write tool), six-question checklist, always-on rules (provisional until the eval result), Gotchas from upstream "Left out on purpose", review summary (detect.mjs --config then review.mjs --config), arguments (--no-lint, --show-suppressed, browser target), ## Next; no credits or source links.
  • Eleven reference files per the Design module layout; all 47 techniques, each marked with its upstream slug, a one-line rationale and a Baseline status pointer (as-of date + recheck trigger), including the six techniques without upstream support lines (oklch-color, fluid-sizes-with-clamp, content-grid-with-breakouts, stack-layers-with-grid, carousel-on-native-scroll, no-rubber-band-bounce-on-desktop); no browser-version numbers; upstream "Next" items not carried.
  • routing.json css-authoring row (Design Contracts) + a tests/routing.test.mjs case; reference/types/web.md concern list and "When nothing covers the concern" point at write-css; skills/design/SKILL.md routes css-authoring.
  • README fixed-defaults list (mirrors reference/configuration.md: topic split, review output sections and exit codes, four-step process order, project-first precedence); docs/upstream/good-css.md (pin, blob SHAs from Design Contracts, recheck trigger, per-technique credits, MIT notice, in the humanlayer record shape); a fragment carrying the MIT notice.
  • plugins/user-interface/scripts/check-good-css-drift.sh (--check; exit 0 none, 1 drift, 2 unverifiable; modeled on plugins/playwright/skills/playwright/scripts/update.sh) + tests/check-good-css-drift.test.sh; add its row to .github/workflows/maintenance-check-upstream-drift.yml (skill: user-interface:write-css, args: --check, drift: "exit:1", unverifiable: "exit:2") covering scripts/check-css.mjs, LICENSE and PRACTICES.md.
  • Run evals in all arms; apply the keep-in-body threshold; record the per-arm result on PR C; open PR C as a draft.
File Action Rationale
[ ] plugins/user-interface/skills/write-css/SKILL.md CREATE skill body
[ ] plugins/user-interface/skills/write-css/reference/{foundations,layout,spacing-and-shape,text-and-media,interaction,motion,show-and-hide,scroll-and-viewport}.md CREATE 47 techniques by topic
[ ] plugins/user-interface/skills/write-css/reference/{stack-discovery,review,configuration}.md CREATE process, review, fixed defaults
[ ] plugins/user-interface/reference/routing.json MODIFY css-authoring row
[ ] plugins/user-interface/tests/routing.test.mjs MODIFY row assertion
[ ] plugins/user-interface/reference/types/web.md MODIFY pointer
[ ] plugins/user-interface/skills/design/SKILL.md MODIFY route css-authoring
[ ] plugins/user-interface/README.md MODIFY fixed-defaults list, skill entry
[ ] plugins/user-interface/scripts/check-good-css-drift.sh CREATE weekly drift check
[ ] plugins/user-interface/tests/check-good-css-drift.test.sh CREATE exit-code contract
[ ] .github/workflows/maintenance-check-upstream-drift.yml MODIFY one matrix row
[ ] docs/upstream/good-css.md CREATE attribution record, blob SHAs
[ ] .changes/user-interface/<fragment>.md CREATE changelog + MIT notice
  • Sanity Check: with R=plugins/user-interface/skills/write-css/reference and U=plugins/user-interface:
    • bash plugins/skill-quality/scripts/check-skill.sh --require-evals plugins/user-interface/skills exits 0; bash $U/tests/routing.test.sh exits 0; bash $U/tests/check-good-css-drift.test.sh exits 0.
    • Slugs: awk -F'|' '/^\| [0-9]+ \|/{gsub(/ /,"",$3);print $3}' .work/good-css/upstream-map.md | wc -l returns 47, and awk -F'|' '/^\| [0-9]+ \|/{gsub(/ /,"",$3);print $3}' .work/good-css/upstream-map.md | while read -r s; do grep -rqwF -- "$s" $R || echo "MISSING $s"; done prints nothing.
    • Support pointers: for s in oklch-color fluid-sizes-with-clamp content-grid-with-breakouts stack-layers-with-grid carousel-on-native-scroll no-rubber-band-bounce-on-desktop; do grep -rhA40 -wF -- "$s" $R | grep -qi "baseline" || echo "NO POINTER $s"; done prints nothing.
    • No upstream Next: grep -rnE "^#+ Next\b" $R prints nothing; grep -rlE "animation-timeline: *view\(|base-select" plugins/user-interface/skills/write-css prints nothing.
    • Held-fixed list: for k in "topic split" "exit code" "four-step" "project-first"; do grep -qi -- "$k" $U/README.md && grep -qi -- "$k" $R/configuration.md || echo "MISSING $k"; done prints nothing.
    • Attribution: grep -rciE "vojta|holik|good-css\.com|github\.com/vojtaholik" plugins/user-interface/skills/write-css | grep -v ':0$' prints nothing; grep -rcE "(Chrome|Firefox|Safari) [0-9]+" $R | grep -v ':0$' prints nothing; grep -c "b645ab15b9fc" docs/upstream/good-css.md returns at least 1; grep -cE "6fa72714ba18cf02f698fa8015f63df043b3af85|66a325d82e56f2f41ebd14812517d6c50f5b66da" docs/upstream/good-css.md returns at least 2.
    • Listing budget (the script always exits 0, so assert on the report): bash plugins/skill-quality/scripts/check-listing-budget.sh plugins/user-interface/skills | grep -c "WARN" returns 0.
    • Drift row: grep -c "user-interface:write-css" .github/workflows/maintenance-check-upstream-drift.yml returns 1; bash $U/scripts/check-good-css-drift.sh --check exits 0 or 1 (2 means it could not verify).

Phase 9: Presence-gated pointers (PR D) [TODO]

  • One presence-gated /user-interface:write-css reference each in plugins/prototype/skills/explore-directions/SKILL.md and plugins/visualization/skills/visualize/SKILL.md; one fragment per plugin. One PR for both: the same one-line change, and each plugin keeps its own fragment. [EXEC-SHAPE]
  • Sanity Check: grep -c "/user-interface:write-css" plugins/prototype/skills/explore-directions/SKILL.md plugins/visualization/skills/visualize/SKILL.md returns at least 1 for each; bash plugins/skill-quality/scripts/check-skill.sh plugins/prototype/skills plugins/visualization/skills exits 0.

Phase 10: Follow-up issue (close-out after PR A merges) [TODO]

  • Phase-entry check (first): gh issue list --state all --search 'user-experience config-cascade resolver in:title,body' --json number,title,state.
  • If a match exists → pivot: record its number in PR A's ## Related and skip creation (comment on it only if this session opened it).
  • If empty → gh issue create --title 'refactor(user-experience): read team config through lib/config-cascade.mjs' --body '<scope, Refs: #6594, PR A link>'; the body also names the twin parsers plugins/code-metrics/scripts/yaml_subset.py and plugins/multi-agent/scripts/yaml-subset.awk as candidates to retire onto lib/yaml-subset.mjs or keep with a reason. [FALLBACK]
  • Other out-of-scope items already have an owner: the repo-wide format and migration of other plugins sit on feat(conventions): one setup lifecycle for where plugins store team conventions and settings #6594; no further issues.
  • Sanity Check: the issue number (created or found) is in PR A's body: gh pr view <A> --json body -q .body | grep -cE "#[0-9]+" returns at least 1; gh issue view <N> --json body -q .body | grep -cE "yaml_subset.py|yaml-subset.awk" returns at least 2.

Files affected

Listed per phase above. Totals: 1-2 files in the ADR PR; about 12 in PR A (lib, moved tests, registry, the user-experience copy, version, changelog); about 18 in PR B (adds defaults test and setup evals); about 85 in PR C (17 eval case directories of roughly four files each, 11 references, the skill, scripts, vendor, drift script and row, routing, docs); 4 in PR D.

Alternatives considered

Alternative Why rejected Switch condition
One PR for all work Unreviewable size; contradicts C14 Never for this scope
Merge PR A into PR B A touches user-experience and a repo-level gate; a separate PR keeps the structural change revertable alone (Tidy First) Reviewers ask for one PR and A stays under about 300 lines
Write the ADR at close-out after an admission test Code would ship ahead of the recorded deviation from config-cascade "What does not move"; reviewers of A and B would lack the rationale (R8) Never
Fold the ADR into PR A Mixes a decision review with a code review; the ADR stands without code Reviewers ask for one PR
Shared lib spawns resolve-convention-home.sh itself Generated copies sit at different relative paths per plugin, so a sibling-relative spawn breaks (R1) Never; the caller owns its plugin root
Reuse --team as the resolved-config output switch Breaks user-experience's meaning of --team FILE (R3) Never
review.mjs spawns detect.mjs Adds a second dependency direction and makes review.mjs untestable without a project (R4) Never
Mirror list keys (*.disable) in userConfig multiple options are hidden from /config, so the value would be invisible to the user (R5) Claude Code shows multiple options in /config
Accept routing in every layer Personal layers could reroute a team's agents unreviewed (R6) A routing-as-data update allows personal routing
Vendor under skills/write-css/scripts/vendor/ Outside the typos exclusion plugins/*/skills/*/vendor/**; diverges from playwright (R7) Never
Leave user-experience's yaml-subset.mjs unregistered (two hand copies) Two copies of one parser that drift apart is a silent second way; ADR 0019's Rule of Three is met The --check-bump cost on user-experience proves blocking; then move it to the follow-up issue
Keep the yaml-subset suite in both places Two suites for one file; the canonical owns its tests Never
Migrate user-experience onto the resolver in PR A Design D4 keeps it a follow-up; turns PR A into a behavior change The user asks to include it
One PR per plugin for PR D Two one-line changes; separate fragments already keep per-plugin release notes A plugin owner asks for separate review
Modified check-css.mjs Breaks clean drift diffs and the blob-SHA check (Design D6) Upstream adds rule ids and distinct exit codes, making the wrapper unnecessary
Two-arm (with versus without) evals for always-on rules Shows a rule helps, not that it must sit in the body (R9) Never for the keep-in-body decision
runs: 3 for the rule cases Cannot separate a 2-run margin between body and reference arms The ceiling estimate forces batches and the user prefers fewer runs

Risks and mitigations

Risk Likelihood Impact Mitigation
A registry or header mistake fails sync-shared-copies.sh --check for every PR Low High Phase 2 and 4 Sanity Checks run the gate locally before push
ADR review delays PR A's merge Med Low PR A is drafted while the ADR is in review; only its merge waits
Resolver semantics diverge from #6594's outcome Med Med The resolver hides paths (D4); legacy[] gives a migrate path; the ADR states #6594 may supersede it
Eval estimate exceeds the configured ceiling (three arms, runs: 5) Med Low Run by tag and arm in batches; never raise the ceiling unasked
Always-on rules show no body-over-reference margin and all move to references Med Low That is the Brief's intended outcome (C6); record it on PR C
B or C waits on the previous merge Med Med Stack on the previous branch as the fallback, rebase after merge
A detect.mjs consumer asserts the full key set Known Low tests/detect.test.mjs:55 updated in Phase 4; pre-flight lists any other
A userConfig value with shell metacharacters reaches a shell Low High Values travel only through a file written with the Write tool; edge-case test in Phase 4

Blast radius

Blast radius: MEDIUM. One ADR, a new repo-level canonical lib and four shared-copies.txt registrations under a repo-wide CI gate, one new row in the informational weekly drift workflow, and one other plugin (user-experience) gets a header-only change, a moved test suite and a version bump; every behavior change is additive inside user-interface, the resolver has no existing consumer, and each PR reverts on its own.

Execution shape

Dependency graph: 1 (ADR PR) → 2 → 3 (PR A) → 4 → 5 (PR B) → {6, 7} → 8 (PR C) → 9 (PR D); 10 after PR A merges. Phases 6 and 7 are file-disjoint (evals versus scripts, vendor and tests) and independent, so they run as Wave A in parallel; everything else is sequential. Cost note: two parallel workers roughly double token use for that wave versus sequential. [EXEC-SHAPE]

Agent Phase ALLOWED files LOC
W6 6 plugins/user-interface/evals/css-*/**, plugins/user-interface/skills/write-css/evals/evals.json ~950
W7 7 plugins/user-interface/skills/write-css/scripts/**, plugins/user-interface/skills/write-css/vendor/**, plugins/user-interface/tests/review.test.*, plugins/user-interface/tests/fixtures/review/** ~350

Each agent is FORBIDDEN any file outside its ALLOWED list, PLAN.md, and commit or push (the main session commits). Each brief carries the plan template's divergence-escalation clause verbatim. Sequential fallback: on a scope-fence violation or a cannot-complete report, abort that worker and run 6 → 7 in the main session.

Phase Surface Model Basis
1 main-session opus ADR wording, user interaction in record-decision
2 sub-agent worker sonnet Closed file list, byte-identical move, binary gate checks
3 sub-agent worker opus New shared contract; merge semantics need judgment
4 sub-agent worker opus Cross-module contract change (detector output, schema, userConfig)
5 main-session opus Setup skill text and convention-doc deviation wording
6 sub-agent worker opus Per-case grader design judgment, three-arm setup
7 sub-agent worker opus Wrapper handles untrusted file paths; crash versus finding semantics
8 main-session opus Skill authoring, eval-result decisions, attribution record
9 sub-agent worker sonnet Two one-line edits, grep checks
10 sub-agent worker sonnet Search-before-create, one issue

Decisions made (gate-passed)

Decision What it changes in the plan Basis (evidence) Source
Five PRs (ADR, A, B, C, D) in dependency order, each on its own worktree and branch Approach PR table; phase 1 → ADR, 2-3 → A, 4-5 → B, 6-8 → C, 9 → D C14; Design module layout dependency direction; R8 plan
ADR for the five-layer cascade recorded before PR A; late admission-test phase removed Phase 1; Conventions; Alternatives R8; docs/conventions/config-cascade/README.md:30-36, 84-86 design (R8)
B and C start from merged main; stacking only as fallback Approach; Risks row scripts/sync-shared-copies.sh:7-10: --check-bump <ref> compares canonicals against a base ref plan
resolve() takes home; detect.mjs resolves it through the plugin's lib/resolve-convention-home.sh Phases 3-4; Contracts R1; plugins/user-experience/scripts/detect.mjs:150; scripts/sync-shared-copies.sh:13-15 design (R1)
New detector fields under project, resolved config under top-level config Phase 4; Test strategy R2; plugins/user-interface/tests/detect.test.mjs:55 design (R2)
--team FILE stays a test seam; output switch is --config Phase 4; Contracts R3; plugins/user-experience/scripts/detect.mjs:150 design (R3)
review.mjs takes config JSON, never spawns detect.mjs Phase 7; Contracts R4 design (R4)
userConfig carries four scalar css_* keys; values travel through a Write-tool temp file; OQ1 and OQ2 closed, Brief Out-of-scope and AC lines revised Phase 4; Brief R5; manifest reference (design-threads facts, fetched 2026-10-10); plugins/source-control/skills/worktree/context/create.md "Create the worktree" design (R5)
routing accepted only in layer 4 Phase 4 schema and tests R6; docs/conventions/routing-as-data/README.md:105-108 design (R6)
Vendored linter at skills/write-css/vendor/ Phase 7 R7; .github/workflows/pr-require-checks.yml:809-816; playwright precedent design (R7)
Three-arm evals for the 8 rule cases at runs: 5; keep-in-body when body beats reference by ≥2 of 5 Test strategy; Phases 6, 8 R9; threshold numbers are judgment inside the deferred Q32 design (R9)
user-experience's yaml-subset.mjs becomes a generated copy and its suite moves to lib/ in PR A Phase 2; PR A changelog Design D4; explore.md §4 fact 4 (Rule of Three met) plan
user-experience gets a version bump + CHANGELOG, not a fragment PR A changelog cell scripts/fragment-plugins.txt has no user-experience line; user-interface (86), prototype (70), visualization (88) are listed plan
Canonical lib tests live at lib/<name>.test.{mjs,sh} Phases 2-3 files lib/installed.test.mjs precedent; scripts/run-plugin-tests.sh:5 runs lib/**/*.test.sh plan
Vendored files verified by upstream blob SHA Phase 7 Sanity Check; good-css.md gh api repos/vojtaholik/good-css/contents/<path>?ref=b645ab15... and git hash-object .work/good-css/raw/* agree (this session) plan
Weekly drift row via a plugin-level check-good-css-drift.sh --check Phase 8 .github/workflows/maintenance-check-upstream-drift.yml:11-15, 36-65 (rows name a script with an exit-code contract); skill files carry no source links (Brief AC) plan
Listing-budget check asserts on report text Phase 8 Sanity Check plugins/skill-quality/scripts/check-listing-budget.sh:41 (always exits 0 on a report) plan
Eval cost bounded by the evals plugin's max_cost_usd ceiling; batch by tag if exceeded Test strategy cost line plugins/evals/.claude-plugin/plugin.json max_cost_usd; plugins/evals/skills/plugin-eval/SKILL.md:186-194 plan
PR D covers both prototype and visualization Phase 9; PR D row Identical one-line pointer; per-plugin fragments keep release notes separate plan
Phases 6 and 7 run in parallel; all else sequential Execution shape File-overlap check: disjoint ALLOWED lists; no data dependency plan
Follow-up issue for the user-experience resolver migration names the twin parsers, search before create Phase 10 Design D4; plugins/code-metrics/scripts/yaml_subset.py, plugins/multi-agent/scripts/yaml-subset.awk plan

Open questions

None. OQ1 (userConfig keys) and OQ2 (acceptance-criterion wording) are resolved by R5.

Handoff to implementation

Surface for confirmation before executing: the [FALLBACK] items (stacking a PR on the previous branch, running the reference arm from a temporary branch, the follow-up issue create path), and any change to an acceptance criterion. Every ready-flip and merge asks the user.

🤖 Generated with Claude Code

ADR 0061: plugin defaults, a userConfig scalar mirror, user-global
~/docs/conventions, project team and project personal .local layers,
read through one shared resolver lib/config-cascade.mjs. Records the
deviation from the config-cascade convention's "What does not move"
and from ADR 0044. user-interface is the first adopter.

Refs: #6594

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kyle-sexton
kyle-sexton marked this pull request as ready for review October 11, 2026 04:10
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 11, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-11T04:14:56.552188Z 53d739d Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@github-actions

github-actions Bot commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

claude-security-review has reviewed this pull request through 3664d71; a later push is reviewed from there.

@claude

claude Bot commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

Claude finished @kyle-sexton's task in 4m 32s —— View job


Code review complete

Summary

This PR adds a single file, docs/adr/0061-adopt-a-five-layer-plugin-config-cascade-read-through-one-shared-resolver.md (127 lines, no code). I read it in full against the conventions it cites and checked its own stated verification.

Independently confirmed (author-claimed verification, re-run myself):

  • ls docs/adr | grep -ci config-cascade → 1 (unique ADR number, no collision)
  • grep -c 6594 → 5, grep -ci "what does not move" → 2, both inside the ADR file
  • ADR numbers 0018, 0025, 0028, 0039 are pre-existing duplicates in docs/adr/, unrelated to this PR, as the PR body states
  • The ADR's characterization of docs/conventions/config-cascade/README.md "What does not move" and of ADR 0044's fenced-block team config matches those files
  • The deferral of the config-cascade ## Implementers table update to the PR that ships the plugin's config (rather than this ADR) matches that table's own rule ("each row states the surface's conformance as it exists on main, never as a migration intends it to be" — README.md#L494)
  • Markdownlint/typos: I could not run markdownlint-cli2/typos myself in this sandbox (no network/npx access), so that part of the PR's Verification section is author-claimed and unverified by me

Candidate finding investigated and rejected: I considered whether the ADR's "Deviations" section should also record a deviation from docs/conventions/routing-as-data/README.md's "there is no structured personal layer" line, since the pasted PLAN.md explicitly flags that as a deviation needing recording. On independent adversarial review this doesn't hold up: that line sits in routing-as-data's "Team layer" section and, per that doc's own Boundary section, is scoped to the routing key's own data, not to general plugin config — and ADR 0061 already keeps routing team-only in layer 4, rejecting it from layers 2/3/5 (lines 55-57), which satisfies the rule routing-as-data actually states.

No other correctness or alignment issues found. This is a documentation-only ADR with no code; I have no findings to report.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 53d739dc30

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@github-actions

github-actions Bot commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

claude-review has reviewed this pull request through 3664d71; a later push is reviewed from there.

A *.disable list is a union with no single supplying layer; the
resolver reports every contributing layer for it, so the ADR now says so.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@claude

claude Bot commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

Claude finished @kyle-sexton's task in 46s —— View job


Code review complete

  • Gather context (incremental diff, prior review state)
  • Review the incremental change against CLAUDE.md/AGENTS.md and criteria
  • Adversarially validate candidate findings
  • Post findings

Summary

This incremental review covers only the diff since 53d739d, which is a one-line (now two-line) wording fix to docs/adr/0061-adopt-a-five-layer-plugin-config-cascade-read-through-one-shared-resolver.md at lines 58-59.

The change replaces "Every resolved value carries the layer that supplied it." with:

Every resolved value carries its provenance: the layer that supplied it, or for a *.disable list every layer that contributed to the union, in layer order.

This is exactly the fix both Codex's P2 finding and @kyle-sexton's own review comment on the prior commit asked for: the old wording promised single-layer provenance even though the merge rules two bullets above state *.disable lists are a cross-layer union, so a single "supplying layer" doesn't exist for those keys. The reworded bullet now states the two-shape contract (single layer for scalars, ordered layer list for list unions) that matches the merge rules immediately above it and stays consistent with the "per-key provenance" language later in the One shared resolver section (line 74). I checked the rest of the file for any other place that restates single-layer provenance and found none — this was the only spot.

No new issues introduced by this change; no further findings.

@kyle-sexton
kyle-sexton added this pull request to the merge queue Oct 11, 2026
Merged via the queue into main with commit ce619b3 Oct 11, 2026
18 checks passed
@kyle-sexton
kyle-sexton deleted the docs/adr-five-layer-config-cascade branch October 11, 2026 04:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant