@thebassclef/lite 1.1.0 → 1.2.0-alpha.1

package/dist/lite/standards/slack-notifications.md

@@ -0,0 +1,161 @@
+---
+tier: lite
+description: - .github/workflows/bassclef-s3-publish.yml — 🤖 auto URL-rotation notifications; routes to #bassclef-activity - .github/workflows/bassclef-template-sync.yml — 🙋 human-required template-sync PRs; routes to #bassclef-human-input - substrate.config.md…
+---
+
+## Sources read
+
+- `.github/workflows/bassclef-s3-publish.yml` — 🤖 auto URL-rotation notifications; routes to #bassclef-activity
+- `.github/workflows/bassclef-template-sync.yml` — 🙋 human-required template-sync PRs; routes to #bassclef-human-input
+- `substrate.config.md` §Slack notifications — webhook secret names (`slack_activity_webhook_name`, `slack_queue_webhook_name`)
+- `standards/substrate-config-schema.md` — typed-suffix convention for `*_webhook_name` fields
+- `.claude/rules/bassclef-workflow-parity.md` — sibling-grep discipline for patterns shared across both workflows
+
+## What I'm NOT reading (with reason)
+
+- Individual Slack channel configuration (member list, archive settings) — operator-owned; this standard is the routing convention, not the administration
+- Non-bassclef repo Slack notifications — out of scope; POA and other consumer repos may adopt the convention independently, but this standard governs bassclef's channels only
+
+# Slack Notifications Standard
+
+Bassclef uses **two channels** for workflow notifications — one for
+🤖 auto events, one for 🙋 human-required events. Separate channels
+separate signal from noise. Operator scans the human-input channel
+independently of the activity channel.
+
+## Channel routing
+
+| Channel | Emoji | Events | Expected operator action |
+|---------|-------|--------|-------------------------|
+| `#bassclef-activity` | 🤖 | URL rotation PRs opened + auto-merged; cron-triggered publishes; successful syncs | None required — ambient awareness only. Check when debugging. |
+| `#bassclef-human-input` | 🙋 | Template-sync PRs (privileged hook code changes); failed syncs; manual-review-required events | Review within 24h. Block mobile sessions until template-sync merged per `.claude/rules/bassclef-hook-drift-blocker.md`. |
+
+Events from bassclef workflows MUST route to exactly one channel.
+Ambiguous events (e.g., "automated but might need review") default to
+`#bassclef-human-input` — err on the side of operator visibility.
+
+## Message format
+
+Every message begins with an ISO 8601 UTC timestamp and the routing
+emoji:
+
+```
+[2026-04-22T00:12:34Z] 🤖 Bassclef URL sync PR #245 for sunj-labs/poa — auto-merge enabled
+https://github.com/sunj-labs/poa/pull/245
+Bassclef SHA: abc1234
+```
+
+Fields (in order):
+
+1. **Timestamp** — `[YYYY-MM-DDTHH:MM:SSZ]` in UTC. Prepended literal
+   string (not Slack's native timestamp — the native one is
+   message-time, timestamp in the body is event-time). Operators scan
+   by timestamp to understand event sequences across windows.
+2. **Emoji** — 🤖 or 🙋 per the routing table above.
+3. **Action phrase** — verb + object ("Bassclef URL sync PR opened",
+   "Bassclef template sync — review required"). First line summary.
+4. **Details** — PR URL, consumer repo, bassclef SHA, template
+   version as applicable. Multi-line OK.
+
+Messages MUST be built inside jq's filter (not `--arg text`) so
+`\n` renders as actual newlines, not literal characters. See
+`.claude/rules/bassclef-workflow-parity.md` for the historical
+incident (#167, #158).
+
+## Webhook secrets
+
+Configured per-repo via `substrate.config.md`:
+
+```
+slack_activity_webhook_name: SLACK_WEBHOOK_ACTIVITY
+slack_queue_webhook_name: SLACK_WEBHOOK_QUEUE
+```
+
+The values are the **names** of GitHub secrets (not the webhook URLs).
+Workflows reference them as `${{ secrets.SLACK_WEBHOOK_ACTIVITY }}` /
+`${{ secrets.SLACK_WEBHOOK_QUEUE }}`.
+
+Webhook URLs live in the repo's GitHub Actions secrets, not in
+`substrate.config.md`. The raw secret is never committed.
+
+## Legacy compatibility (rollout window)
+
+During the rollout of #227 (the initial split), workflows fall back to
+the legacy `SLACK_WEBHOOK` secret when the new names are unset:
+
+```yaml
+SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK_ACTIVITY || secrets.SLACK_WEBHOOK }}
+```
+
+Once both new secrets are configured in repo settings, the legacy
+fallback becomes dead code. Remove the `|| secrets.SLACK_WEBHOOK`
+fallback in a follow-up PR after operator confirms the new channels
+are receiving messages.
+
+Rollout steps (operator):
+
+1. Create Slack app / incoming webhooks for `#bassclef-activity` and
+   `#bassclef-human-input` in your Slack workspace
+2. Add secrets to bassclef repo:
+   `SLACK_WEBHOOK_ACTIVITY` + `SLACK_WEBHOOK_QUEUE`
+3. Trigger one test event per channel (e.g., manual `workflow_dispatch`
+   on `bassclef-s3-publish`) — confirm message arrives with timestamp
+4. Follow-up PR removes the `|| secrets.SLACK_WEBHOOK` fallback
+5. Retire `SLACK_WEBHOOK` secret after fallback removal confirmed
+
+## Adding new workflow notifications
+
+Any new bassclef workflow that sends Slack notifications MUST:
+
+1. Pick the correct channel per the routing table
+2. Use the correct webhook secret (`SLACK_WEBHOOK_ACTIVITY` or
+   `SLACK_WEBHOOK_QUEUE`)
+3. Follow the message format (timestamp + emoji + action phrase + details)
+4. Build the message inside jq's filter, not `--arg text`
+5. Document the event in this standard's routing table
+
+Workflow-parity discipline per `.claude/rules/bassclef-workflow-parity.md`:
+if the new workflow has patterns shared with existing workflows
+(message shape, secret names, timestamp format), sibling-grep before
+commit.
+
+## Why two channels
+
+Operator feedback 2026-04-18: single-channel Slack mixed 🤖 auto-merges
+(ambient) with 🙋 template-syncs (action-required). Operator scanned
+the whole channel to find the action items. The split separates the
+two concerns:
+
+- Activity: ambient awareness, check occasionally
+- Human-input: action-required, review within 24h
+
+Timestamp addition per #227: operators reviewing the human-input channel wanted to
+correlate template-sync events with iteration goal boundaries. Native
+Slack timestamps work for "when did this message arrive" but not for
+"when did the underlying event fire" — the latter matters for
+retro/chronicle correlation.
+
+## Evolution
+
+- **v1.0 (2026-04-22)** — initial two-channel split + timestamps per
+  bassclef #227. Legacy `SLACK_WEBHOOK` fallback retained during
+  rollout.
+
+## Open questions for future iteration
+
+- **Thread-reply → GitHub merge action** (bassclef #169): should
+  replying to a human-input-channel message trigger a merge? Orthogonal
+  to this standard; tracked separately.
+- **Per-repo channel routing**: consumer repos (POA, pruneguice, etc.)
+  currently receive no Slack notifications directly; they receive
+  bassclef-authored PRs in their repos. If consumer repos adopt a
+  similar split, they'll need their own secrets + channels. Defer
+  until first consumer requests it.
+- **Retention / archiving**: neither channel has explicit retention
+  policy today. If message volume grows, consider time-based channel
+  archives. Defer until measured volume warrants.
+
+## Closes
+
+- bassclef #227
+- WS-3 of iteration goal 2026-04-21b

package/dist/lite/standards/synthetic-user-testing.md

@@ -0,0 +1,173 @@
+---
+tier: lite
+description: Three-tier testing framework that uses personas to validate UX beyond what unit tests can catch.
+---
+
+# Synthetic User Testing Standard
+
+Three-tier testing framework that uses personas to validate UX beyond
+what unit tests can catch. Unit tests cover logic. Synthetic users test
+what a person sees, does, and fails to accomplish.
+
+**Origin:** POA PPP-Scale IA migration — 932 unit tests passed while
+track filter, search, and sortable contacts silently dropped. Unit tests
+verified scoring math; nobody verified users could still filter by 1031.
+
+---
+
+## The Three Tiers
+
+| Tier | What it catches | When to run | Requires |
+|------|----------------|-------------|----------|
+| 1 — Smoke | Blank pages, missing components, auth failures, console errors | Every PR (CI) | Playwright or browser |
+| 2 — Feature parity | Capabilities that silently drop during rewrites | After any migration or redesign | Capabilities inventory |
+| 3 — User journeys | Flows that break, friction that compounds, features nobody asked for | Before release, monthly, or after major UX changes | Personas + task scenarios |
+
+Each tier builds on the previous. Tier 1 is table stakes. Tier 3 is
+where synthetic users earn their keep by proposing features.
+
+---
+
+## Tier 1: Smoke Tests
+
+One test per route. The cheapest test that catches the worst failures.
+
+**For each page**:
+1. Navigate to the route
+2. Verify it loads without error
+3. Verify key elements are present (nav, primary content, expected headings)
+4. Check console for error-level messages
+5. Screenshot for the record
+
+**Pass criteria**: Page loads, key elements render, no console errors.
+
+**CI integration**: Run on every PR that touches `app/`, `components/`,
+or `pages/` directories. Block merge on failure.
+
+**Coverage target**: 100% of routes. No page should exist without a
+smoke test. When you add a route, add a smoke test.
+
+---
+
+## Tier 2: Feature Parity Tests
+
+Test that capabilities survive rewrites. This is the tier that would
+have caught the POA migration failures.
+
+### Capabilities inventory
+
+Before testing, build the inventory. For each surface, list what it DOES:
+
+| # | Surface | Capability | How to verify |
+|---|---------|-----------|---------------|
+| 1 | Pipeline | Text search filters results | Type in search, verify rows narrow |
+| 2 | Pipeline | Column headers sort | Click header, verify order changes |
+| 3 | Pipeline | Track filter (1031/Operating) | Click filter, verify results narrow |
+| 4 | Deal detail | Financial data renders | Inspect financial section, verify numbers |
+| 5 | Shortlist | Search filters contacts | Type in search, verify contacts narrow |
+
+### When to build the inventory
+
+- **Before any migration**: Inventory the OLD surface's capabilities.
+  The `/ux-migration` skill includes this as Step 1b.
+- **After the first build**: Test the NEW surface against the inventory.
+- **Ongoing**: Update the inventory when capabilities are added or intentionally removed.
+
+### Pass criteria
+
+100% of inventoried capabilities must be present and functional. There
+is no acceptable parity score below 100%. Missing capabilities are either:
+- **Bugs** — file as issues, label `feature-parity`, fix before release
+- **Intentional removals** — must be documented in the migration spec with rationale
+
+---
+
+## Tier 3: User Journey Tests
+
+Multi-page flows framed as persona tasks. The only tier that generates
+new backlog items.
+
+### Persona requirements
+
+Each persona needs:
+- Name, age, role, device, tech comfort level
+- Primary goal (what they come to accomplish)
+- Context (when/where/why they use the app)
+
+Store at `docs/design/personas/` in the app repo.
+
+### Journey structure
+
+A journey is a sequence of steps a persona takes to accomplish their goal:
+
+1. Start at their entry point (usually / or a bookmarked page)
+2. Navigate to the relevant surface
+3. Perform their task (search, filter, read, decide, act)
+4. Complete their goal or get blocked
+
+### Evaluation criteria
+
+At each step, evaluate:
+- **Comprehension**: Would this persona understand the labels, numbers, jargon?
+- **Navigation**: Can they find the next step without instructions?
+- **Completion**: Can they finish end-to-end?
+- **Friction**: What slowed them down?
+
+### JTBD proposals
+
+The distinctive output of Tier 3. For each friction point:
+
+> As [Persona], it would be great if I could [capability]
+> so I could [outcome].
+
+Proposals are auto-filed as GitHub issues with `synthetic-user` label.
+They enter the backlog alongside operator-filed issues, giving the PM
+a persona-driven signal for prioritization.
+
+### Quality bar for proposals
+
+Not every friction point deserves an issue. Proposals must be:
+- **Grounded** in an observed failure or friction (not speculative)
+- **Persona-specific** (framed from their perspective)
+- **Actionable** (specific enough to scope and build)
+- **Non-duplicate** (check existing issues before filing)
+
+---
+
+## Relationship to Other Standards and Skills
+
+| Standard/Skill | Relationship |
+|---------------|-------------|
+| `/ux-migration` | Step 1b (capabilities inventory) feeds Tier 2 |
+| `/jtbd-tasks` | Produces the task analysis that informs Tier 3 flows |
+| `/task-scenarios` | Produces user stories that become Tier 3 test cases |
+| `/visual-review` | Evaluates visual quality; synthetic users evaluate functional quality |
+| `/smoke-test` | Post-deploy smoke; synthetic users are pre-release and persona-aware |
+| `standards/testing.md` | Defines the three test layers (unit, integration, E2E); synthetic users are a fourth layer |
+
+---
+
+## Anti-Patterns
+
+- **Testing without personas**: Generic "click every button" tests miss
+  the comprehension and navigation failures that matter. Use personas.
+- **Skipping the capabilities inventory**: "I'll just test what I see"
+  can't catch what's missing. Inventory first, test against it.
+- **Filing every friction as an issue**: Not all friction is a bug.
+  Some is intentional complexity. Evaluate before filing.
+- **Replacing manual testing**: Synthetic users supplement human testing.
+  They catch structural failures; humans catch taste failures.
+- **Running Tier 3 without Tier 1**: If pages don't load, journey tests
+  waste time debugging infrastructure instead of evaluating UX.
+
+---
+
+## Output Artifacts
+
+| Artifact | Location | Frequency |
+|----------|----------|-----------|
+| Smoke results | `docs/synthetic-user-reports/YYYY-MM-DD.md` | Per run |
+| Capabilities inventory | `docs/specs/capabilities-[surface].md` | Per surface, updated on change |
+| Journey reports | `docs/synthetic-user-reports/YYYY-MM-DD.md` | Per run |
+| JTBD proposals | GitHub issues with `synthetic-user` label | Per finding |
+| Persona definitions | `docs/design/personas/[name].md` | Stable, updated on research |

package/dist/lite/standards/vendor-bindings.md

@@ -0,0 +1,165 @@
+---
+tier: lite
+description: The index of external services bassclef depends on.
+---
+
+# Vendor Bindings
+
+The index of external services bassclef depends on. For each: what bassclef uses it for, where in bassclef the binding lives, and **how portable** the usage is across enterprise vendors (GitHub vs Azure DevOps vs GitLab; AWS vs GCP vs Azure).
+
+This is the agent-native equivalent of GitHub's *Insights → Dependencies → Filter by ecosystem* — but for substrate-level service bindings, not code-package dependencies.
+
+## Sources read
+
+- `standards/bassclef-platform.md` — org-level infra surface (sibling concern; this catalog is the per-vendor breakdown)
+- `architecture/decisions/ADR-014-substrate-sync-strategy.md` — thin-pointer architecture (GitHub-specific implementation)
+- `architecture/decisions/ADR-018-bassclef-interaction-model.md` — Harness as a runtime object (Claude Code binding)
+- `standards/secrets-lifecycle.md` — secret storage adapters (1Password / GitHub Actions Secrets / AWS Secrets Manager)
+- `standards/deployment-topology.md` — deploy target adapter pattern (Amplify / EC2-Tailscale / others)
+- `substrate.config.md` schema — `production_hosting_platform` + `journal_doc_id` + similar adapter fields
+- `docs/bassclef-overview.md` — positioning doc; mentions "enterprise CI runners" but doesn't enumerate bindings
+- 2026-05-11 operator framing — surfaced during Phase IIIa Follow-on scope (b) discussion: clarity-check reusable workflow is GitHub-Actions-specific; ADO + GitLab + Bitbucket need explicit thinking
+
+## Portability tiers
+
+Each binding is classified by how hard it would be to swap the vendor:
+
+| Tier | Definition | Migration cost |
+|---|---|---|
+| **Agnostic** | No vendor-specific code; works on any provider in the category | None — runs everywhere |
+| **Adapter** | Vendor-specific code lives behind an interface; swap = new adapter | Days — new adapter per new vendor |
+| **Locked** | Code/logic only works with this vendor; swap = rewrite | Weeks-months — substantial re-architecture |
+| **Structural** | The vendor IS part of bassclef's identity; not realistically swappable | Out of scope — would define a new framework |
+
+## Vendor binding catalog
+
+### GitHub (code hosting + Issues/PRs/Projects)
+
+| Usage | Where it's bound | Tier |
+|---|---|---|
+| Repo hosting + remote operations | `gh` CLI throughout `.claude/skills/`, `.claude/hooks/` | **Locked** — `gh` is GitHub-specific |
+| Issues + PRs as tracking surface | `gh issue create`, `gh pr create`, `gh pr merge` in skills/hooks | **Locked** — issue model differs across providers |
+| Source distribution (tarball API) | `.bassclef-source.json` points at `api.github.com/repos/.../tarball/main`; `bassclef-sync.template.sh` fetches via that URL | **Adapter** — `.bassclef-source.json` has `source_url` field; could swap to ADO REST API or GitLab tarball |
+| GitHub Projects (board surface) | `design/object-model.md` `Task` object; referenced in `agent-choreography.md` | **Agnostic-ish** — not currently exercised; could swap to ADO Boards or Jira |
+
+**ADO/GitLab equivalents:**
+- gh CLI → `az repos` / `glab` / `bb` CLIs (different command shapes; would need adapter)
+- GitHub API tarball → ADO REST `GET /git/repositories/{id}/items?download=true&path=/&versionDescriptor.version=main` (different URL shape; same outcome)
+
+### GitHub Actions (CI runner + workflow orchestration)
+
+| Usage | Where it's bound | Tier |
+|---|---|---|
+| Workflow runs on PR open | `.github/workflows/bassclef-pr-ci.yml` | **Locked** — YAML schema differs; ADO Pipelines + GitLab CI + Bitbucket Pipelines all incompatible |
+| Reusable workflows (`uses:`) | `.github/workflows/clarity-check.reusable.yml` (bassclef#611 shipped 2026-05-11) | **Locked** — ADO has template includes; GitLab has includes/components; not source-compatible. Abstraction tracked at bassclef#629 |
+| Consumer-side reusable-workflow auto-wire | `presence/install/bassclef-sync.template.sh` section 3g-workflows writes consumer's `.github/workflows/clarity-check.yml` referencing bassclef#611's reusable workflow via `@main` | **Locked** — only GitHub consumers get the auto-wire; non-GitHub consumers skipped per `IS_GITHUB_CONSUMER` check |
+| Hook tests in CI | `.github/workflows/bassclef-pr-ci.yml` hook-tests job | **Locked** — YAML structure GH-specific |
+| Schema validation in CI | `.github/workflows/bassclef-pr-ci.yml` ajv-schema-validate job | **Adapter possible** — the validation logic itself is `npx ajv compile`; the WRAPPER is GH-specific |
+| Body-clarity advisory | `.github/workflows/clarity-check.reusable.yml` (refactored from bassclef-pr-ci.yml 2026-05-11) | **Locked at the YAML wrapper layer; logic is portable** — clarity-check shell logic could be extracted to `lib/ci/clarity-check.sh` with thin per-vendor wrappers; tracked at bassclef#629 |
+
+**Enterprise migration path:** the LOGIC (hook tests, schema validation, body clarity scan + comment) can each be extracted to vendor-agnostic shell scripts; per-vendor YAML wrappers (GH Actions / ADO Pipelines / GitLab CI / Bitbucket Pipes) call the shared scripts. Today bassclef hasn't done this extraction — the body-clarity logic is inline in the workflow YAML.
+
+### Anthropic — Claude API + Claude Code harness + community skills
+
+| Usage | Where it's bound | Tier |
+|---|---|---|
+| LLM calls (Haiku / Sonnet / Opus / Opus 4.6) | Every skill that calls Claude; agent definitions; `substrate.config.md` model routing | **Structural** — bassclef IS a Claude Code framework |
+| Claude Code as runtime harness | All hooks (PreToolUse, PostToolUse, SessionStart, Stop); `.claude/settings.json` schema | **Structural** — `Harness` is a named runtime object in ADR-018 |
+| Community skills (frontend-design, etc.) | `standards/vendor-plugins/frontend-design.md` | **Adapter** — community skills are adoption choices, not bindings |
+| Skill SDK / agent SDK conventions | `.claude/skills/*/SKILL.md` schema | **Structural** — would need to rewrite for OpenAI Assistants API or similar |
+
+**Structural binding rationale:** bassclef's value proposition is *agent-native SDLC for Claude Code consumers*. The Anthropic binding is the identity, not an implementation detail. Migration to another agent runtime would define a new framework.
+
+### AWS — account-level infra (parent of Amplify)
+
+| Usage | Where it's bound | Tier |
+|---|---|---|
+| AWS account + region | `bassclef-platform.yml` `aws.*` fields | **Adapter** — bassclef-platform.yml is multi-cloud-capable in schema; today only AWS shape implemented |
+| IAM roles for deploys | `/provision-deploy-host` skill | **Adapter** — provisioner has per-cloud adapter dispatch |
+
+**Migration path:** add GCP/Azure adapters to `/provision-deploy-host`; extend `bassclef-platform.yml` schema with `gcp.*` / `azure.*` sibling fields.
+
+### AWS Amplify (hosting adapter)
+
+| Usage | Where it's bound | Tier |
+|---|---|---|
+| Prototype + app hosting | `substrate.config.md` `production_hosting_platform: amplify` | **Adapter** — adapter selected by config field; `none` / `ec2-tailscale` / `amplify` / others |
+| Domain binding | `/bind-subdomain` skill; Amplify-specific API calls | **Adapter** — adapter dispatch per platform; new platform = new bind script |
+
+### Google Cloud — Docs / Drive APIs
+
+| Usage | Where it's bound | Tier |
+|---|---|---|
+| Journal-entry corpus push | `substrate.config.md` `journal_doc_id` (field renamed to `journal_doc_id` in bassclef#1019); `scripts/push-to-gdoc.ts` | **Adapter** — doc-ID-based; swap to Notion API / Confluence API by replacing the push script |
+| `gcloud auth` for service accounts | `secrets-bootstrap` skill | **Adapter** — secret-storage adapter |
+
+### Slack — notifications
+
+| Usage | Where it's bound | Tier |
+|---|---|---|
+| Webhook posts (build / merge / deploy) | `standards/slack-notifications.md`; relevant hooks | **Adapter** — webhook-based; swap to Discord / Teams / Telegram via env-configured URL |
+
+### DNS providers (Cloudflare / Route53 / others)
+
+| Usage | Where it's bound | Tier |
+|---|---|---|
+| Subdomain binding | `bassclef-platform.yml` `dns.*` fields; `/bind-subdomain` skill | **Adapter** — DNS provider selected per `bassclef-platform.yml` field; adapter dispatch per provider |
+
+### Secret storage (1Password / GitHub Actions Secrets / AWS Secrets Manager / .env)
+
+| Usage | Where it's bound | Tier |
+|---|---|---|
+| Credentials at runtime | `substrate.secrets.md` `storage.type` field; `/secrets-bootstrap` skill | **Agnostic** — full adapter dispatch; type field selects implementation |
+
+### NPM ecosystem (dev tooling)
+
+| Usage | Where it's bound | Tier |
+|---|---|---|
+| `ajv-cli` + `ajv-formats` for JSON Schema validation | `.github/workflows/bassclef-pr-ci.yml`; bassclef-pr-ci ajv-schema-validate job | **Agnostic** — Python `jsonschema` or other validators interchangeable; CI invocation swappable |
+| Other dev tools (gitleaks, eslint, etc.) | Various CI jobs in app repos | **Agnostic** — pick equivalent tools per stack |
+
+---
+
+## Summary by tier
+
+| Tier | Count | Examples |
+|---|---|---|
+| **Structural** | 1 | Anthropic (Claude API + Claude Code harness) |
+| **Locked** | 2 | GitHub (Issues/PRs/CLI), GitHub Actions (workflow YAML) |
+| **Adapter** | 7 | AWS, AWS Amplify, Google Cloud, Slack, DNS, secret storage, source distribution |
+| **Agnostic** | 1 | NPM ecosystem (dev tooling) |
+
+**11 vendor bindings total.** Only 2 are vendor-locked beyond the structural Anthropic binding. **Adapter pattern dominates** — bassclef's substrate is mostly portable across enterprise vendors; the GitHub binding is the main exception.
+
+## What this means for ADO / enterprise adoption
+
+Per the operator's framing 2026-05-11:
+
+The GitHub-locked bindings (Issues/PRs/CLI + Actions YAML) are real obstacles to bassclef running in ADO + GitLab + Bitbucket shops. Migration paths exist but require explicit per-vendor work:
+
+1. **gh CLI usage in skills/hooks** — every `gh issue ...` / `gh pr ...` call would need an adapter. Estimate: ~50 call sites in bassclef's substrate today (skills + hooks).
+2. **GitHub Actions workflows** — `.github/workflows/bassclef-pr-ci.yml` translates to ADO `azure-pipelines.yml`, GitLab `.gitlab-ci.yml`, Bitbucket `bitbucket-pipelines.yml`. Different YAML; same logic.
+3. **Source distribution tarball API** — swap `.bassclef-source.json` `source_url` field to point at the consumer's repo provider's tarball API.
+
+**Recommended sequencing for ADO support (when prioritized):**
+
+1. Extract shared logic from GH Actions YAML into vendor-agnostic shell scripts (callable from any CI)
+2. Add ADO Pipelines YAML wrapper that calls the same scripts
+3. Add `gh-cli-adapter` abstraction (shell function wrapping `gh issue/pr/release/api`); implement `ado-cli-adapter` calling `az repos pr` etc.
+4. Track migration in a Phase IIIc-ADO bet (separate from Phase IIIb-hardening)
+
+## When to update this catalog
+
+Add an entry when bassclef adds a new external service binding. Don't wait for an audit — surface the binding at the time of integration with:
+
+- Vendor name + category (CI runner / cloud / LLM / secret store / etc.)
+- Usage description (one sentence)
+- Binding paths (file paths + skill/hook names)
+- Portability tier classification
+- Adapter migration notes if known
+
+## Distinct from
+
+- **`standards/vendor-plugins/`** — *plugins bassclef adopts* (e.g., Anthropic community skills, third-party rules). Not the same as vendor bindings (bassclef's dependencies on external services).
+- **`standards/bassclef-platform.md`** — *org-level infra surface* declared in `bassclef-platform.yml`. Sibling to this; that file is the operator-facing declaration; this catalog is the implementation breakdown.
+- **`docs/bassclef-overview.md`** — *positioning doc*. References enterprise contexts; this catalog is the detailed mapping.

package/dist/lite/standards/vendor-plugins/frontend-design.md

@@ -0,0 +1,66 @@
+---
+tier: lite
+description: Anthropic community skill — FRONTEND-DESIGN-SKILL.md
+---
+
+# Vendor Plugin: Frontend Design Skill
+
+## Source
+Anthropic community skill — `FRONTEND-DESIGN-SKILL.md`
+
+## Purpose
+Design quality layer for frontend work. Ensures components are
+production-grade and visually intentional, not generic "AI slop."
+
+## How it fits our SDLC
+
+```
+Usability check (floor)  →  Design quality (ceiling)
+  - Correct                   - Distinctive
+  - Accessible                - Intentional typography
+  - Consistent                - Spatial composition
+  - No jargon                 - Motion & delight
+```
+
+Usability check must pass first. Design quality applies on top.
+
+## Guardrails for our context
+
+The raw skill optimizes for "unforgettable" and "bold." Our family app
+optimizes for "trustworthy" and "readable." Apply with these filters:
+
+### DO apply to:
+- Dashboard landing page (first impression, emotional job)
+- Call Prep brief (the family artifact — this IS the product)
+- Rubric/scoring explanation (educational, trust-building)
+- Marketing surfaces (if/when we have them)
+
+### DO NOT apply to:
+- Data tables and deal lists (predictable layout > distinctive layout)
+- Ops dashboard (utilitarian, operator-only)
+- Form inputs and filters (standard patterns win)
+
+### Adapt these principles:
+| Skill says | Our context |
+|-----------|-------------|
+| Avoid Inter, system fonts | Keep system fonts for body text (readability). Distinctive fonts OK for headings on landing/brief surfaces. |
+| Asymmetry, overlap, diagonal flow | Not for data layouts. OK for dashboard hero sections and empty states. |
+| Bold maximalism OR refined minimalism | We are "refined minimalism" — Lupton, not Sagmeister. Mom is 76. |
+| Unexpected, characterful choices | Channel into: card borders, score badges, chart styling, section dividers. Not into layout structure. |
+| Motion and micro-interactions | Subtle: hover states, transition-colors, page load fade-in. Not: parallax, staggered reveals, scroll-triggered. |
+| Gradient meshes, noise textures | Not for a data app. Clean backgrounds, solid badge colors, high contrast. |
+
+### Typography hierarchy (adapted)
+- Display/headings: Can be distinctive (brief title, dashboard welcome)
+- Body text: System fonts, 14px+, high contrast
+- Data values: Monospace or tabular numerals, bold, 16px+
+- Labels: Uppercase tracking, muted, 10-11px
+
+## When to invoke
+After the usability check passes and before final review of a
+family-facing surface. The designer (Claude) should ask:
+
+1. Is there a clear aesthetic direction for this surface?
+2. Does the typography serve the hierarchy?
+3. Is there one distinctive element someone will remember?
+4. Does it feel *designed* or *generated*?