@thebassclef/lite 0.0.1 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (182) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +85 -4
  3. package/dist/cli.cjs +1610 -0
  4. package/dist/cli.js +1587 -0
  5. package/dist/index.cjs +4 -0
  6. package/dist/index.d.ts +2 -0
  7. package/dist/index.js +4 -0
  8. package/package.json +51 -3
  9. package/substrate/.bassclef/lite-manifest.json +1794 -0
  10. package/substrate/.claude/agents/architect.md +70 -0
  11. package/substrate/.claude/agents/builder.md +114 -0
  12. package/substrate/.claude/agents/designer.md +156 -0
  13. package/substrate/.claude/agents/reviewer.md +88 -0
  14. package/substrate/.claude/hooks/artifact-ingestion-gate.sh +357 -0
  15. package/substrate/.claude/hooks/assert-verify-steering.sh +77 -0
  16. package/substrate/.claude/hooks/bassclef-source-config-validate.sh +215 -0
  17. package/substrate/.claude/hooks/bassclef-sync.sh +634 -0
  18. package/substrate/.claude/hooks/compound-noun-scrub.sh +292 -0
  19. package/substrate/.claude/hooks/kiss-expansion-inject.sh +69 -0
  20. package/substrate/.claude/hooks/plain-english-steering.sh +156 -0
  21. package/substrate/.claude/hooks/post-skill-friction-check.sh +177 -0
  22. package/substrate/.claude/hooks/post-skill-telemetry.sh +62 -0
  23. package/substrate/.claude/hooks/pre-build-gate.sh +511 -0
  24. package/substrate/.claude/hooks/pre-commit-gate.sh +452 -0
  25. package/substrate/.claude/hooks/session-end.sh +433 -0
  26. package/substrate/.claude/hooks/session-reflection.sh +303 -0
  27. package/substrate/.claude/hooks/skill-body-grade-gate.sh +219 -0
  28. package/substrate/.claude/hooks/skill-body-intent-drift.sh +107 -0
  29. package/substrate/.claude/hooks/skill-step-list-check.sh +171 -0
  30. package/substrate/.claude/hooks/state-validate.sh +271 -0
  31. package/substrate/.claude/hooks/substrate-clarity-gate.sh +1110 -0
  32. package/substrate/.claude/hooks/temperance-gate.sh +147 -0
  33. package/substrate/.claude/hooks/testing-tier-enforce.sh +233 -0
  34. package/substrate/.claude/hooks/turn-prose-grade-measure.sh +219 -0
  35. package/substrate/.claude/hooks/turn-prose-kiss-check.sh +434 -0
  36. package/substrate/.claude/hooks/vocabulary-migration-check.sh +171 -0
  37. package/substrate/.claude/hooks/whereami-utc-gate.sh +142 -0
  38. package/substrate/.claude/luminaries/alan-cooper.md +170 -0
  39. package/substrate/.claude/luminaries/alistair-cockburn.md +140 -0
  40. package/substrate/.claude/luminaries/amazon-pr-faq.md +34 -0
  41. package/substrate/.claude/luminaries/ash-maurya.md +121 -0
  42. package/substrate/.claude/luminaries/bill-buxton.md +210 -0
  43. package/substrate/.claude/luminaries/charles-sanders-peirce.md +150 -0
  44. package/substrate/.claude/luminaries/david-ogilvy.md +192 -0
  45. package/substrate/.claude/luminaries/don-norman.md +173 -0
  46. package/substrate/.claude/luminaries/edward-tufte.md +179 -0
  47. package/substrate/.claude/luminaries/eric-evans.md +160 -0
  48. package/substrate/.claude/luminaries/frederick-brooks.md +50 -0
  49. package/substrate/.claude/luminaries/gang-of-four.md +157 -0
  50. package/substrate/.claude/luminaries/jason-fried-dhh.md +46 -0
  51. package/substrate/.claude/luminaries/jesse-james-garrett.md +154 -0
  52. package/substrate/.claude/luminaries/john-ousterhout.md +94 -0
  53. package/substrate/.claude/luminaries/karl-popper.md +132 -0
  54. package/substrate/.claude/luminaries/kent-beck.md +168 -0
  55. package/substrate/.claude/luminaries/linus-torvalds.md +218 -0
  56. package/substrate/.claude/luminaries/martin-fowler.md +164 -0
  57. package/substrate/.claude/luminaries/michael-feathers.md +125 -0
  58. package/substrate/.claude/luminaries/michael-nygard.md +118 -0
  59. package/substrate/.claude/luminaries/robert-c-martin.md +164 -0
  60. package/substrate/.claude/luminaries/saltzer-schroeder.md +194 -0
  61. package/substrate/.claude/luminaries/sophia-prater.md +193 -0
  62. package/substrate/.claude/luminaries/stephen-toulmin.md +131 -0
  63. package/substrate/.claude/rules/artifact-ingestion.md +179 -0
  64. package/substrate/.claude/rules/assert-only-after-verify.md +137 -0
  65. package/substrate/.claude/rules/blocked-items.md +146 -0
  66. package/substrate/.claude/rules/branching.md +28 -0
  67. package/substrate/.claude/rules/commit-conventions.md +22 -0
  68. package/substrate/.claude/rules/context-engineering.md +202 -0
  69. package/substrate/.claude/rules/context-management.md +85 -0
  70. package/substrate/.claude/rules/destructive-operations.md +69 -0
  71. package/substrate/.claude/rules/diagnosis.md +38 -0
  72. package/substrate/.claude/rules/guardrails.md +73 -0
  73. package/substrate/.claude/rules/identifier-leak-prevention.md +104 -0
  74. package/substrate/.claude/rules/lite-manifest-schema-change-discipline.md +98 -0
  75. package/substrate/.claude/rules/oo-ad-entry-point.md +117 -0
  76. package/substrate/.claude/rules/operator-facing-prose.md +196 -0
  77. package/substrate/.claude/rules/plain-english-discipline.md +154 -0
  78. package/substrate/.claude/rules/pr-body-shape.md +317 -0
  79. package/substrate/.claude/rules/pr-strategy.md +167 -0
  80. package/substrate/.claude/rules/sdlc-gates.md +149 -0
  81. package/substrate/.claude/rules/session-artifacts.md +236 -0
  82. package/substrate/.claude/rules/state-schema-validation.md +162 -0
  83. package/substrate/.claude/rules/whereami-load-bearing.md +202 -0
  84. package/substrate/.claude/rules/writing-craft-discipline.md +92 -0
  85. package/substrate/.claude/skills/build/SKILL.md +640 -0
  86. package/substrate/.claude/skills/decompose/SKILL.md +280 -0
  87. package/substrate/.claude/skills/diagnose/SKILL.md +297 -0
  88. package/substrate/.claude/skills/howdoi/SKILL.md +105 -0
  89. package/substrate/.claude/skills/ia-model/SKILL.md +108 -0
  90. package/substrate/.claude/skills/interaction-design/SKILL.md +112 -0
  91. package/substrate/.claude/skills/interpret-input/SKILL.md +180 -0
  92. package/substrate/.claude/skills/kiss/SKILL.md +449 -0
  93. package/substrate/.claude/skills/launch/SKILL.md +924 -0
  94. package/substrate/.claude/skills/lean-canvas/SKILL.md +332 -0
  95. package/substrate/.claude/skills/longrun/SKILL.md +426 -0
  96. package/substrate/.claude/skills/luminary/SKILL.md +481 -0
  97. package/substrate/.claude/skills/ogilvy-writing-audit/SKILL.md +177 -0
  98. package/substrate/.claude/skills/onboard-repo/SKILL.md +2190 -0
  99. package/substrate/.claude/skills/pattern-review/SKILL.md +99 -0
  100. package/substrate/.claude/skills/personas/SKILL.md +207 -0
  101. package/substrate/.claude/skills/promote/SKILL.md +283 -0
  102. package/substrate/.claude/skills/requirement/SKILL.md +98 -0
  103. package/substrate/.claude/skills/retro/SKILL.md +117 -0
  104. package/substrate/.claude/skills/riff/SKILL.md +114 -0
  105. package/substrate/.claude/skills/roadmap-reconcile/SKILL.md +163 -0
  106. package/substrate/.claude/skills/session-end/SKILL.md +309 -0
  107. package/substrate/.claude/skills/session-log/SKILL.md +299 -0
  108. package/substrate/.claude/skills/skills/SKILL.md +228 -0
  109. package/substrate/.claude/skills/spec/SKILL.md +105 -0
  110. package/substrate/.claude/skills/sprint/SKILL.md +392 -0
  111. package/substrate/.claude/skills/stage/SKILL.md +384 -0
  112. package/substrate/.claude/skills/state-a-problem/SKILL.md +185 -0
  113. package/substrate/.claude/skills/temperance/SKILL.md +108 -0
  114. package/substrate/.claude/skills/use-case/SKILL.md +417 -0
  115. package/substrate/.claude/skills/user-stories/SKILL.md +268 -0
  116. package/substrate/.claude/skills/value-prop/SKILL.md +251 -0
  117. package/substrate/.claude/skills/verify/SKILL.md +160 -0
  118. package/substrate/.claude/skills/whereami/SKILL.md +307 -0
  119. package/substrate/AGENTS.md +79 -0
  120. package/substrate/CLAUDE-lite.md +85 -0
  121. package/substrate/CODE_OF_CONDUCT.md +28 -0
  122. package/substrate/CONTRIBUTING.md +177 -0
  123. package/substrate/README.md +173 -0
  124. package/substrate/SECURITY.md +19 -0
  125. package/substrate/architecture/decisions/ADR-029-release-pipeline.md +79 -0
  126. package/substrate/architecture/decisions/ADR-031-non-breaking-changes-adopter-discipline.md +139 -0
  127. package/substrate/architecture/decisions/ADR-032-adopter-sync-dispatcher-architecture.md +192 -0
  128. package/substrate/architecture/decisions/ADR-039-release-tagging-scheme.md +145 -0
  129. package/substrate/architecture/decisions/ADR-040-planning-skill-vocabulary-and-lite-profile.md +155 -0
  130. package/substrate/architecture/decisions/ADR-044-unified-skill-body-template.md +162 -0
  131. package/substrate/lib/clean-artifacts-sweep.sh +112 -0
  132. package/substrate/lib/code-comment-discipline.sh +144 -0
  133. package/substrate/lib/composer-preflight.sh +459 -0
  134. package/substrate/lib/hook-inject.sh +255 -0
  135. package/substrate/lib/luminary-pick.sh +96 -0
  136. package/substrate/lib/output-discipline.sh +143 -0
  137. package/substrate/lib/rewrite-check.sh +214 -0
  138. package/substrate/lib/state.sh +1372 -0
  139. package/substrate/lib/telemetry.sh +205 -0
  140. package/substrate/lib/tier-check.sh +138 -0
  141. package/substrate/lib/tier-dependency-audit.sh +933 -0
  142. package/substrate/presence/install/bassclef-hook-connect.sh +178 -0
  143. package/substrate/presence/install/bassclef-sync.dispatcher.template.sh +841 -0
  144. package/substrate/presence/install/bassclef-sync.template.sh +2076 -0
  145. package/substrate/presence/install/schedule-auto-save.cron.sh +88 -0
  146. package/substrate/presence/install/schedule-auto-save.taskscheduler.md +122 -0
  147. package/substrate/scripts/aggregate-telemetry.sh +217 -0
  148. package/substrate/scripts/analyze-tier-dependencies.sh +239 -0
  149. package/substrate/scripts/generate-lite-manifest.sh +489 -0
  150. package/substrate/scripts/generate-tier-manifest.sh +28 -0
  151. package/substrate/scripts/intent-drift-check.sh +456 -0
  152. package/substrate/scripts/lite-manifest-drift-check.sh +146 -0
  153. package/substrate/scripts/render-lite-manifest-doc.sh +150 -0
  154. package/substrate/standards/bassclef-configs-schema.md +232 -0
  155. package/substrate/standards/bassclef-evolution.md +143 -0
  156. package/substrate/standards/bassclef-internal-jargon.md +244 -0
  157. package/substrate/standards/bassclef-managed-sentinel.md +96 -0
  158. package/substrate/standards/bassclef-source-config.md +228 -0
  159. package/substrate/standards/deferred-actions-schema.md +204 -0
  160. package/substrate/standards/docs-sync-allowlist.md +76 -0
  161. package/substrate/standards/graceful-exit.md +227 -0
  162. package/substrate/standards/hook-idempotency.md +102 -0
  163. package/substrate/standards/lite-manifest-schema-changes.md +75 -0
  164. package/substrate/standards/luminary-problem-patterns.md +481 -0
  165. package/substrate/standards/ogilvy-writing-rules.md +225 -0
  166. package/substrate/standards/opener-discipline.md +96 -0
  167. package/substrate/standards/operator-facing-prose-discipline.md +201 -0
  168. package/substrate/standards/project-directory-layout.md +276 -0
  169. package/substrate/standards/release-tagging.md +137 -0
  170. package/substrate/standards/sdlc-compliance.md +286 -0
  171. package/substrate/standards/secrets-lifecycle.md +210 -0
  172. package/substrate/standards/security-scanner-adapter.md +145 -0
  173. package/substrate/standards/skill-output-discipline.md +90 -0
  174. package/substrate/standards/state-spine.md +511 -0
  175. package/substrate/standards/tech-stack-config.md +109 -0
  176. package/substrate/standards/tier-dependency-analysis.md +167 -0
  177. package/substrate/standards/tier-runtime-deps/lite.md +57 -0
  178. package/substrate/standards/tier-tag-schema.md +155 -0
  179. package/substrate/standards/whereami-schema.md +301 -0
  180. package/substrate/standards/writing-guide.md +213 -0
  181. package/substrate/templates/deferred-action-template.md +45 -0
  182. package/substrate/templates/whereami-template.md +101 -0
@@ -0,0 +1,75 @@
1
+ ---
2
+ tier: lite
3
+ description: Chronological ledger of every lite-manifest schema change. Adopters read this before sync to know what shifted.
4
+ ---
5
+
6
+ # Lite-manifest schema changes
7
+
8
+ This ledger records every change to `standards/lite-manifest.schema.json` and to the shape of `<tier>-manifest.json` output. Adopters that consume the manifest read this file before every `bassclef-sync` run that crosses a version boundary. Each entry names the change type, the version bumps, the recommended downstream cure, and any retirement timeline.
9
+
10
+ Sister to `standards/file-renames.json` (which tracks file-level renames). Same discipline shape at a different surface. Per `.claude/rules/lite-manifest-schema-change-discipline.md`.
11
+
12
+ ## Format
13
+
14
+ Every entry follows this shape. Entries are newest-first for ease of scan.
15
+
16
+ ```
17
+ ### <SHORT TITLE> (<manifest_version bump>, <YYYY-MM-DD>)
18
+
19
+ - **Change type:** field-add | field-remove | field-rename | content-remove | content-add | policy-change
20
+ - **Fields:** <field names — comma-separated>
21
+ - **Version bump:** vX.Y.Z → vA.B.C (reason)
22
+ - **Rationale:** <link to issue / PR / body of the change>
23
+ - **Downstream cure:** <what adopters need to do — usually nothing if optional-add; sometimes a code change if content shape shifts>
24
+ - **Old shape retired:** <immediately | date | never (compat shim kept)>
25
+ ```
26
+
27
+ Adopters MAY grep for the change type they care about. Adopter tooling MAY parse the ledger as flat markdown.
28
+
29
+ ## Retention
30
+
31
+ Every entry stays in this file for the life of the manifest. Never pruned. When entries grow past ~30, split by year into archive files under `standards/lite-manifest-schema-changes-archive/YYYY.md` (not shipped yet — first split due when the year rolls over).
32
+
33
+ ---
34
+
35
+ ## Entries (newest first)
36
+
37
+ ### Content backfill: 96 skills gain problem + value + inputs + outputs (v1.5.0 → v1.5.1, 2026-09-07)
38
+
39
+ - **Change type:** content-add
40
+ - **Fields:** `problem`, `value`, `inputs`, `outputs` on 34 lite + 62 standard SKILL.md files (96 total; lite manifest ships 34 populated). Non-skill entries continue to omit these fields per Hoare H5 skill-surface guard.
41
+ - **Version bump:** v1.5.0 → v1.5.1 (patch; content-only change, no schema shape shift)
42
+ - **Rationale:** bassclef-web launches 2026-09-09 with a docs page that renders four new columns per skill card. Upstream fields shipped OPTIONAL in v0.37.0; this release ships the curated content. Extractor uses naive comma-split, so items avoid embedded commas by design (use "or"/"and" as connectors).
43
+ - **Downstream cure:** No adopter code change needed. Renderers that already project the 4 fields (bassclef-web PR #271) now see populated content. Renderers that ignore unknown keys continue working. This release does not shift the schema — schema stays v1.6.0 in title description; manifest content version 1.5.0 → 1.5.1.
44
+ - **Old shape retired:** Never. Non-skill entries continue to omit the 4 fields.
45
+ - **Related tickets:** bassclef-upstream#1544 (also fixed same PR — /substrate-check symlink→file rewrite for npm-copy reality), bassclef-web#268 + #269 (closed downstream via v0.37.0 refresh).
46
+
47
+ ### 4-field add: inputs + outputs + problem + value (v1.5.0 → v1.6.0, 2026-09-07)
48
+
49
+ - **Change type:** field-add
50
+ - **Fields:** `inputs`, `outputs`, `problem`, `value` (all on entry — skill surface only)
51
+ - **Version bump:** v1.5.0 → v1.6.0 (minor; adding OPTIONAL fields is backward-compatible per schema title description)
52
+ - **Rationale:** bassclef-web#268 acceptance (docs.bassclef.dev needs 4 scan-anchors per lite skill card). Extractor upgrade in goal 2026-09-07c per `docs/iteration-bets/2026-09-07c-lite-manifest-schema-plus-extractor-plus-backfill-plus-ledger.md`. Fields ship OPTIONAL per Hoare H2 pre-mortem cure.
53
+ - **Downstream cure:** No adopter code change needed. Parsers that ignore unknown keys continue working. Parsers that pin to exact `v1.5.0` string should loosen to a semver range like `>=1.5.0 <2.0.0` before v0.37.0 sync.
54
+ - **Old shape retired:** Never. All prior entries stay valid (fields are OPTIONAL, not required).
55
+
56
+ ### upstream_commit content removed (v1.4.x → v1.5.0, 2026-09-06)
57
+
58
+ - **Change type:** content-remove
59
+ - **Fields:** `upstream_commit` (was at manifest top level, alongside `manifest_version` + `generated_at`)
60
+ - **Version bump:** v1.4.x → v1.5.0 (minor; field removed at top level, not from entry shape)
61
+ - **Rationale:** upstream sunj-labs/bassclef-upstream#1508 removed the field from manifest content because the value drifted between release cascade steps. Fix at commit `d20c0652` on main.
62
+ - **Downstream cure:** bassclef-web scripts that read `upstream_commit` crashed at v0.36.0 sync (3 scripts). Cure at bassclef-web commit `c9a9da7` — derive the commit locally from `git -C <upstream> rev-parse HEAD` when the value is needed. bassclef-cli sync path had the same class; check for reads of `upstream_commit` before v0.37.0 pull.
63
+ - **Old shape retired:** Immediately (field was removed with no compat shim). This retroactive entry documents the class that motivated the ledger discipline (per bassclef-web#269).
64
+
65
+ ## Related files
66
+
67
+ - `standards/lite-manifest.schema.json` — the schema this ledger tracks
68
+ - `standards/file-renames.json` — sister ledger at the file-rename surface
69
+ - `.claude/rules/lite-manifest-schema-change-discipline.md` — methodology layer that enforces this ledger
70
+ - `.claude/rules/we-dont-break-adopters.md` — ADR-031 parent discipline
71
+ - `scripts/release-to-bassclef.sh` — release script that pre-flight-checks this ledger
72
+
73
+ ## Retirement condition
74
+
75
+ This ledger retires only if bassclef stops shipping a lite manifest. Adopter count and schema change cadence may evolve; the discipline of documenting every change persists.
@@ -0,0 +1,481 @@
1
+ ---
2
+ tier: lite
3
+ description: "Auto-generated. Do not hand-edit. Re-run via: bash scripts/luminary-problem-patterns-aggregate.sh"
4
+ ---
5
+
6
+ # Luminary problem-pattern catalog
7
+
8
+ **Auto-generated.** Do not hand-edit. Re-run via:
9
+ ```
10
+ bash scripts/luminary-problem-patterns-aggregate.sh
11
+ ```
12
+
13
+ This index reads every `.claude/luminaries/*.md` file's frontmatter and
14
+ extracts the `solves_problems_brownfield`, `solves_problems_greenfield`,
15
+ and `anti_patterns` arrays. The agent reads this index when running
16
+ `/luminary recommend` against a plain-English problem statement.
17
+
18
+ ## Coverage
19
+
20
+ - **20 / 77** luminaries have problem-pattern frontmatter
21
+ - Backfill tracker: `docs/luminary-problem-pattern-backfill.md`
22
+
23
+ ## Catalog (alphabetical by slug)
24
+
25
+ ### Aarron Walter (`aarron-walter`)
26
+
27
+ - **Domain:** ux | **Depth:** full
28
+
29
+ **Solves (brownfield — existing UI):**
30
+ - Existing product feels functional but cold — users complete tasks without engagement
31
+ - Microcopy is generic; brand voice doesn't come through
32
+ - Empty states, error states, and waiting states feel like dead ends instead of moments
33
+
34
+ **Solves (greenfield — 0→1 design):**
35
+ - Designing a new consumer product where personality should differentiate from day one
36
+ - Building microcopy + tone-of-voice as core design elements, not decoration
37
+ - Planning a product where emotional engagement matters as much as task completion
38
+ - Designing empty/error/waiting states as moments of brand expression in a fresh build
39
+
40
+ **Anti-patterns (when NOT to channel):**
41
+ - Regulated, clinical, or compliance-heavy surfaces — Walter is too playful
42
+ - Power-tool or data-dense surfaces where personality slows the user down
43
+
44
+ ---
45
+
46
+ ### Abby Covert (`abby-covert`)
47
+
48
+ - **Domain:** ux | **Depth:** stub
49
+
50
+ **Solves (brownfield — existing UI):**
51
+ - Content exists but users can't make sense of how it relates
52
+ - Labels are inconsistent across surfaces; same thing has different names
53
+ - Information architecture is a mess but team can't see it
54
+
55
+ **Solves (greenfield — 0→1 design):**
56
+ - Starting a content-heavy or knowledge-base product where taxonomy must precede screens
57
+ - Designing IA before any UI for a multi-domain app
58
+ - Building a sense-making system where labeling discipline is a first-class concern
59
+ - Designing a product where 'naming things consistently' will be a recurring discipline
60
+
61
+ **Anti-patterns (when NOT to channel):**
62
+ - Single-screen or single-task tools
63
+ - Pure visual or motion work
64
+
65
+ ---
66
+
67
+ ### Alan Cooper (`alan-cooper`)
68
+
69
+ - **Domain:** ux | **Depth:** full
70
+
71
+ **Solves (brownfield — existing UI):**
72
+ - Existing UI exposes the system's structure when users want their workflow
73
+ - Power users keep retracing the same multi-step path through the current UI
74
+ - Persona research surfaces a goal but the existing UI optimizes for novice exploration
75
+ - App is feature-rich but each user wants only one slice for their job
76
+
77
+ **Solves (greenfield — 0→1 design):**
78
+ - Designing a workflow-heavy app for returning users with named goals
79
+ - Building a product where personas + scenarios should drive the UI before any screen sketch
80
+ - Planning a tool for power users who need their job-specific slice surfaced from day one
81
+ - Mid-complexity product where personas keep early design decisions grounded in real users
82
+
83
+ **Anti-patterns (when NOT to channel):**
84
+ - Truly simple consumer apps — Cooper overweights workflow modeling
85
+ - First-launch novelty experiences — goal-directed assumes a returning user
86
+ - Pure marketing or storytelling surfaces
87
+
88
+ ---
89
+
90
+ ### Anthropic frontend-design skill — BASELINE COMPOSES-WITH, NOT A LUMINARY
91
+
92
+ Anthropic's `frontend-design` skill is the implicit baseline default adopters get from plain Claude. Bassclef's authoring skills (`/frontend-design`, `/riff-prototypes`, `/launch`, `/visual-review`) declare `composes_baseline: anthropic-frontend-design` in their frontmatter and extend the baseline with luminary-pair commitment, design tokens, and visual-review discipline.
93
+
94
+ This baseline is not a luminary catalog entry; it ships with the upstream skill catalog Anthropic publishes. Bassclef extends; bassclef does not author the baseline. Adopters firing plain Claude (no bassclef substrate) inherit the baseline's typography + color + motion + spatial-composition guidance for free.
95
+
96
+ See `.claude/skills/frontend-design/SKILL.md` for bassclef's baseline composition declaration and the specific extensions bassclef adds.
97
+
98
+ ---
99
+
100
+ ### Apple Human Interface Guidelines (HIG) (`apple-hig`)
101
+
102
+ - **Domain:** visual | **Depth:** stub
103
+
104
+ **Solves (brownfield — existing UI):**
105
+ - Existing app fights iOS / macOS conventions instead of feeling native
106
+ - Design has too many ideas competing for attention; restraint would clarify
107
+ - Brand identity is overpowering platform conventions in the current UI
108
+ - Polish is missing — corners, transitions, depth feel cheap
109
+
110
+ **Solves (greenfield — 0→1 design):**
111
+ - Designing an app for one specific Apple platform where native fit is a value
112
+ - Building a product where restraint and platform conventions matter more than expression
113
+ - Planning a polished consumer app on iOS / macOS / iPadOS
114
+ - Designing for a platform whose users expect HIG-shaped affordances by default
115
+
116
+ **Anti-patterns (when NOT to channel):**
117
+ - Cross-platform brand-led design where native fit isn't the goal
118
+ - Highly differentiated brand surfaces — Apple HIG forces convention over voice
119
+
120
+ ---
121
+
122
+ ### BJ Fogg (`bj-fogg`)
123
+
124
+ - **Domain:** ux | **Depth:** stub
125
+
126
+ **Solves (brownfield — existing UI):**
127
+ - Users sign up but don't return; existing onboarding doesn't form a habit
128
+ - Notifications fire but don't drive the right action
129
+ - Existing onboarding tour overwhelms instead of landing a tiny first success
130
+
131
+ **Solves (greenfield — 0→1 design):**
132
+ - Designing a behavior-change product (fitness, habit, learning) where motivation × ability × trigger must align
133
+ - Building an onboarding flow that lands a tiny first success on day one
134
+ - Planning a product whose retention will depend on habit formation
135
+ - Designing notification logic where the right trigger fires the right action from launch
136
+
137
+ **Anti-patterns (when NOT to channel):**
138
+ - Power-tool surfaces where the user already has motivation
139
+ - B2B or compliance-heavy surfaces where behavior change isn't the goal
140
+
141
+ ---
142
+
143
+ ### Brad Frost (`brad-frost`)
144
+
145
+ - **Domain:** visual | **Depth:** full
146
+
147
+ **Solves (brownfield — existing UI):**
148
+ - Existing component library is a flat dump with gaps in mid-level molecules and organisms
149
+ - Designers and engineers describe components inconsistently
150
+ - Pattern library exists but doesn't compose into actual pages
151
+
152
+ **Solves (greenfield — 0→1 design):**
153
+ - Designing a fresh design system from atoms upward
154
+ - Building a component hierarchy that will scale across many surfaces
155
+ - Planning a system where pattern composition is a first-class discipline from day one
156
+ - Designing a token + component + template + page taxonomy for a new product
157
+
158
+ **Anti-patterns (when NOT to channel):**
159
+ - Single-screen prototypes — atomic design is for systems
160
+ - Marketing one-offs or campaign pages
161
+
162
+ ---
163
+
164
+ ### Dieter Rams (`dieter-rams`)
165
+
166
+ - **Domain:** visual | **Depth:** full
167
+
168
+ **Solves (brownfield — existing UI):**
169
+ - Existing design has accumulated features and visual elements that don't earn their place
170
+ - Each component does too much; honest functional expression would simplify
171
+ - Aesthetic feels dated because of decoration, not because of underlying function
172
+
173
+ **Solves (greenfield — 0→1 design):**
174
+ - Designing a product where less-but-better is the explicit value
175
+ - Building a tool whose visual identity should follow function, not lead it
176
+ - Planning a long-lived product where ruthless reduction will be a recurring discipline
177
+ - Designing a fresh product where every element must justify its presence from day one
178
+
179
+ **Anti-patterns (when NOT to channel):**
180
+ - Maximalist or expressive brand surfaces
181
+ - Storytelling or narrative-driven surfaces
182
+
183
+ ---
184
+
185
+ ### Don Norman (`don-norman`)
186
+
187
+ - **Domain:** ux | **Depth:** full
188
+
189
+ **Solves (brownfield — existing UI):**
190
+ - Users keep clicking the wrong thing or missing a button; affordances are unclear
191
+ - Interface error messages punish the user rather than help them recover
192
+ - Mental model and system model have diverged — users predict wrong outcomes
193
+ - Mode visibility is missing; users don't know what state they're in
194
+
195
+ **Solves (greenfield — 0→1 design):**
196
+ - Designing a new control surface where affordance language must be self-evident from first encounter
197
+ - Building a tool whose error model should help users recover, not punish
198
+ - Planning a product where mappings between control and effect must feel natural from day one
199
+ - Designing a system where visibility of state is a first-class concern
200
+
201
+ **Anti-patterns (when NOT to channel):**
202
+ - Designs whose primary value is delight or emotional resonance — Norman optimizes for clarity, not joy
203
+ - Highly abstract or conceptual UIs where direct manipulation isn't the model
204
+
205
+ ---
206
+
207
+ ### Edward Tufte (`edward-tufte`)
208
+
209
+ - **Domain:** visual | **Depth:** full
210
+
211
+ **Solves (brownfield — existing UI):**
212
+ - UI shows many numbers or trends in compressed space and legibility is breaking down
213
+ - Dashboard has accumulated decoration and chart-junk; signal is buried
214
+ - Multi-dimensional data displays are letting one dimension drown out others
215
+ - Users decode the chart before understanding the message
216
+
217
+ **Solves (greenfield — 0→1 design):**
218
+ - Planning a dashboard, financial report, or analytics UI that must show dense data clearly from day one
219
+ - Designing a surface where multiple quantitative dimensions need to coexist without one drowning the others
220
+ - Building a tool for domain experts who read data faster than narrative
221
+ - Need small multiples or sparklines as the main display element in the new design
222
+
223
+ **Anti-patterns (when NOT to channel):**
224
+ - Sparse, narrative-heavy surfaces — Tufte over-compresses
225
+ - Consumer-emotional or marketing surfaces — Tufte reads as cold
226
+ - First-time onboarding flows — density assumes domain familiarity
227
+
228
+ ---
229
+
230
+ ### Ellen Lupton (`ellen-lupton`)
231
+
232
+ - **Domain:** visual | **Depth:** full
233
+
234
+ **Solves (brownfield — existing UI):**
235
+ - Page reads as a wall of undifferentiated text
236
+ - Visual hierarchy is broken — every element claims equal importance
237
+ - Typography is inconsistent across pages or feels chosen by accident
238
+ - Reading rhythm is broken by mis-set line height, measure, or contrast
239
+
240
+ **Solves (greenfield — 0→1 design):**
241
+ - Designing a content-heavy product where reading rhythm is core to the experience
242
+ - Setting type scale and hierarchy from scratch for a new brand or system
243
+ - Planning a long-form or editorial surface where typeface choice carries voice
244
+ - Building a fresh product where brand voice should come through in the typeface from day one
245
+
246
+ **Anti-patterns (when NOT to channel):**
247
+ - Pure data-density surfaces — Tufte is a better fit than Lupton
248
+ - Engineering-internal tools where readability beats voice
249
+
250
+ ---
251
+
252
+ ### Erika Hall (`erika-hall`)
253
+
254
+ - **Domain:** ux | **Depth:** full
255
+
256
+ **Solves (brownfield — existing UI):**
257
+ - Team is shipping based on assumptions, not evidence about users
258
+ - Research is happening but findings don't reach decisions
259
+ - Discovery work is being skipped because of velocity pressure
260
+
261
+ **Solves (greenfield — 0→1 design):**
262
+ - Starting a new product and need contextual inquiry to ground the thesis
263
+ - Designing discovery research before any UI is sketched
264
+ - Building a research practice into the team's discipline from day one
265
+ - Designing a product where 'we don't know what users actually do' is the first risk to retire
266
+
267
+ **Anti-patterns (when NOT to channel):**
268
+ - Late-stage refinement work where research is already done
269
+ - Engineering-only surfaces where users aren't directly relevant
270
+
271
+ ---
272
+
273
+ ### Google Material Design (`google-material`)
274
+
275
+ - **Domain:** visual | **Depth:** stub
276
+
277
+ **Solves (brownfield — existing UI):**
278
+ - Existing component library lacks systematic spacing, color, type tokens
279
+ - Cross-platform consistency is breaking; surfaces look like different products
280
+ - Theming and dynamic color aren't working across user preferences
281
+
282
+ **Solves (greenfield — 0→1 design):**
283
+ - Designing a multi-surface system where systematic tokens and density tiers are needed from the start
284
+ - Building cross-platform consistency without bespoke per-platform polish
285
+ - Planning a product where theming + accessibility are core, not retrofitted
286
+ - Designing component density tiers (compact / standard / comfortable) into the system from day one
287
+
288
+ **Anti-patterns (when NOT to channel):**
289
+ - Highly distinctive brand surfaces — Material genericizes
290
+ - Premium or differentiated visual identity work
291
+
292
+ ---
293
+
294
+ ### Jakob Nielsen (`jakob-nielsen`)
295
+
296
+ - **Domain:** ux | **Depth:** stub
297
+
298
+ **Solves (brownfield — existing UI):**
299
+ - Existing UI needs structured expert evaluation against usability heuristics
300
+ - Usability violations are happening but team has no checklist to catch them
301
+ - Standardization across the product matters but discipline is loose
302
+
303
+ **Solves (greenfield — 0→1 design):**
304
+ - Building a new product and want heuristic review baked into the design discipline
305
+ - Designing checkpoints where heuristic evaluation can fire before user testing
306
+ - Planning a product where standardization across surfaces will be a measurable goal
307
+ - Setting up an evaluation framework for a product about to launch
308
+
309
+ **Anti-patterns (when NOT to channel):**
310
+ - Generative or first-pass design — Nielsen evaluates, doesn't ideate
311
+ - Brand or emotional surfaces where heuristics miss the point
312
+
313
+ ---
314
+
315
+ ### Jenifer Tidwell (`jenifer-tidwell`)
316
+
317
+ - **Domain:** ux | **Depth:** full
318
+
319
+ **Solves (brownfield — existing UI):**
320
+ - Common interaction in current UI is being reinvented when proven patterns exist
321
+ - Designer is choosing novel solutions where well-known answers are better
322
+ - Existing design lacks shared vocabulary for interaction choices across team
323
+
324
+ **Solves (greenfield — 0→1 design):**
325
+ - Composing a new app from proven interaction patterns instead of inventing each one
326
+ - Need a vocabulary to communicate interaction choices to engineering on a fresh build
327
+ - Building complex flows; want to compose from named patterns first, novel last
328
+ - Designing a multi-flow product where interaction patterns must be consistent from day one
329
+
330
+ **Anti-patterns (when NOT to channel):**
331
+ - Bleeding-edge novel interactions — Tidwell catalogs proven patterns, not invents new ones
332
+ - Pure visual or brand-driven surfaces
333
+
334
+ ---
335
+
336
+ ### Jesse James Garrett (`jesse-james-garrett`)
337
+
338
+ - **Domain:** ux | **Depth:** full
339
+
340
+ **Solves (brownfield — existing UI):**
341
+ - Project mixes strategy, scope, structure, skeleton, and surface decisions in one conversation
342
+ - Surface decisions are over-determining structural choices in the existing UI
343
+ - Team can't agree on which decisions belong at which level
344
+
345
+ **Solves (greenfield — 0→1 design):**
346
+ - Starting a multi-surface product where the five planes should sequence design decisions
347
+ - Building a UX strategy that decomposes work into orderable layers from day one
348
+ - Planning a product where strategy precedes scope precedes structure precedes skeleton precedes surface
349
+ - Designing a multi-month product where UX governance needs explicit decision-tier vocabulary
350
+
351
+ **Anti-patterns (when NOT to channel):**
352
+ - Tactical UI fixes where the five planes is overhead
353
+ - Single-page or single-screen work
354
+ - - **Strategy** — user needs + product objectives. What success means.
355
+ - - **Scope** — functional specifications + content requirements. What
356
+ - - **Structure** — interaction design + information architecture. How
357
+ - - **Skeleton** — interface design, navigation design, information
358
+ - - **Surface** — sensory design (visual, auditory). How it looks and
359
+
360
+ ---
361
+
362
+ ### Luke Wroblewski (`luke-wroblewski`)
363
+
364
+ - **Domain:** ux | **Depth:** stub
365
+
366
+ **Solves (brownfield — existing UI):**
367
+ - Existing form has many fields and abandonment is high
368
+ - Mobile experience is desktop-first squeezed into small screens
369
+ - Input types, validation, and progressive disclosure aren't optimized for thumbs
370
+
371
+ **Solves (greenfield — 0→1 design):**
372
+ - Designing a mobile-first product where forms are core to the value
373
+ - Planning input surfaces where progressive disclosure must be designed from the start
374
+ - Building for mobile users where thumb-zone economy matters
375
+ - Designing form flows where staged input (now / later / never-asked) is a first-class concern
376
+
377
+ **Anti-patterns (when NOT to channel):**
378
+ - Read-only data display — Wroblewski is for input
379
+ - Desktop-power-tool surfaces where mobile isn't primary
380
+
381
+ ---
382
+
383
+ ### Peter Morville (`peter-morville`)
384
+
385
+ - **Domain:** ux | **Depth:** full
386
+
387
+ **Solves (brownfield — existing UI):**
388
+ - Users can't find content that exists in the product
389
+ - Information architecture has no consistent labeling or hierarchy
390
+ - Search returns results but not the RIGHT results
391
+ - Navigation grew organically and now no one knows the full structure
392
+
393
+ **Solves (greenfield — 0→1 design):**
394
+ - Designing a content-heavy product where findability will be core from day one
395
+ - Planning the IA before screens for a multi-section app
396
+ - Building search + browse surfaces where wayfinding is a first-class concern
397
+ - Designing a product for an audience where findability matters more than discoverability
398
+
399
+ **Anti-patterns (when NOT to channel):**
400
+ - Single-screen tools or focused workflows — Morville is for multi-page IA
401
+ - Brand or marketing surfaces where wayfinding isn't the job
402
+
403
+ ---
404
+
405
+ ### Sophia V. Prater (`sophia-prater`)
406
+
407
+ - **Domain:** ux | **Depth:** full
408
+
409
+ **Solves (brownfield — existing UI):**
410
+ - Existing multi-entity app where users mentally model objects but UI exposes screens or processes
411
+ - Same entity appears in many flows but isn't unified as a concept
412
+ - Navigation doesn't reflect the domain's noun structure
413
+
414
+ **Solves (greenfield — 0→1 design):**
415
+ - Designing a CRUD-heavy or domain-rich product where entity relationships should drive the UI
416
+ - Planning IA from the domain model first, not from process flows
417
+ - Building an app where users will mentally manipulate objects and the UI should match from day one
418
+ - Designing a multi-entity product where consistent entity expression matters across surfaces
419
+
420
+ **Anti-patterns (when NOT to channel):**
421
+ - Process-driven workflows where actions matter more than objects
422
+ - Single-entity tools or marketing surfaces
423
+
424
+ ---
425
+
426
+ ### Steve Krug (`steve-krug`)
427
+
428
+ - **Domain:** ux | **Depth:** stub
429
+
430
+ **Solves (brownfield — existing UI):**
431
+ - Existing interface forces users to read or think more than the task warrants
432
+ - User testing keeps surfacing the same friction points but team can't see them
433
+ - Self-evident affordances are missing in the current UI; users hesitate before every click
434
+ - Navigation, labels, and structure aren't immediately obvious
435
+
436
+ **Solves (greenfield — 0→1 design):**
437
+ - Designing a consumer or low-engagement product where 'don't make me think' is the bar
438
+ - Building a new public-facing surface where usability is the core differentiator
439
+ - Planning a tool that needs to be self-evident from first encounter
440
+ - Designing a product whose audience will not invest effort to learn the interface
441
+
442
+ **Anti-patterns (when NOT to channel):**
443
+ - Power-user tools where complexity is the value
444
+ - Domain-expert surfaces where 'don't make me think' undersells the user
445
+
446
+ ---
447
+
448
+ ## How `/luminary recommend` consumes this
449
+
450
+ The agent reads this aggregate as one of its signal sources when ranking
451
+ luminaries against an operator's plain-English problem statement. The
452
+ modality of the operator's input (brownfield refactor vs greenfield
453
+ concept) determines which array is matched:
454
+
455
+ - Operator input mentions "existing UI", "current product", "today's
456
+ app" → match against `solves_problems_brownfield` arrays
457
+ - Operator input mentions "designing", "planning", "building",
458
+ "0→1", "from scratch" → match against `solves_problems_greenfield`
459
+ arrays
460
+ - Ambiguous input → match against both, weighted by signal strength
461
+
462
+ `anti_patterns` always subtract from a luminary's score when the
463
+ operator's input matches an entry — regardless of modality.
464
+
465
+ ## Schema (per luminary file)
466
+
467
+ ```yaml
468
+ solves_problems_brownfield:
469
+ - "Plain-English symptom statement (~80 chars)"
470
+ - "..."
471
+ solves_problems_greenfield:
472
+ - "Plain-English opportunity statement (~80 chars)"
473
+ - "..."
474
+ anti_patterns:
475
+ - "When NOT to channel (Welch INSTEAD-block)"
476
+ - "..."
477
+ ```
478
+
479
+ All three fields are optional during backfill (LR6 onward). A luminary
480
+ with no problem-pattern frontmatter doesn't appear in this aggregate
481
+ but remains in the catalog for `/luminary` browsing.