Skip to content

feat!: extract vendor bridges to pharn-skills-* category modules (0.69.0) #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
PrzemekGalarowicz merged 1 commit into from
Jun 11, 2026
Merged

feat!: extract vendor bridges to pharn-skills-* category modules (0.69.0) #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,28 @@ Breaking changes for skills are tracked here so the CLI (`pharn-cli`) can warn u

## [Unreleased]

## [0.69.0] — 2026-06-11

### Changed (breaking for manifest consumers)

Vendor-bridge skills extracted from `pharn-stack-nextjs` into standalone, stack-agnostic category modules, so any stack pack (the forthcoming `pharn-stack-tanstack-router`, etc.) can compose them without duplication:

- `pharn-skills-db` — Neon (database hosts; Supabase uses its official vendor skill, no bridge).
- `pharn-skills-orm` — Drizzle, Prisma.
- `pharn-skills-auth` — Better Auth (stub), Clerk, Supabase Auth (stub).
- `pharn-skills-payments` — Stripe.
- `pharn-skills-email` — Resend.

`feature-module-layers` stays in `pharn-stack-nextjs/skills/` — it is Next.js-specific. The six moved bridges were relocated with `git mv` (history preserved), patch-bumped, repointed to their new `module:`, and each gained `rule_files_provided_by: "stack-pack"` plus a body note clarifying that referenced rule files (`database.md`, …) ship with the installed stack pack and resolve at install time.

`manifest.json` bumped to `schemaVersion: 2` — adds the `wizard` catalog (sections, questions, per-option `install` paths, `vendorSkill`/`comingSoon` flags, and dependency `rules`: hide / hideQuestion / relabel / warn) and `kind: "skill-category"` on the five new modules. The manifest JSON schema (`scripts/schemas/manifest.schema.json`) was extended — not loosened — with typed `$defs` for the wizard tree and the `kind` field; `schemaVersion` now accepts `1` or `2`. CLIs reading `schemaVersion: 1` manifests continue to work against pinned older commits.

**Existing installations are unaffected** — skills already copied into your `.claude/` stay in place. New installs pick skills individually through the wizard (the CLI performs selective installation: it copies only the chosen skill subfolder, e.g. `pharn-skills-orm/skills/drizzle/`, never the whole category module). `SKILLS_VERSION` `0.68.1` → `0.69.0`; `pharn-stack-nextjs` module `0.30.0` → `0.31.0`.

### Migration (for projects re-running the wizard)

`npx pharn@latest update` — the CLI re-resolves your `stackAnswers` against the new layout. The wizard-execution, selective-install, and `pharn add <category>:<skill>` work lives in the separate `pharn-cli` repo; this release ships the manifest data, schema, and the documented contract (see `docs/architecture.md`).

## [0.68.1] — 2026-06-11

**`pharn-stack-react` review fixes (license drift + frontmatter convention).** Closes the actionable findings from the stack-react-module review. Both fix-level, no breaking changes, no behavioural delta. `SKILLS_VERSION` `0.68.0` → `0.68.1`; `pharn-stack-react` module `0.1.1` → `0.1.2`.
Expand Down
40 changes: 29 additions & 11 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,21 @@ pharn-oss/
│ ├── module.json
│ ├── commands/ ← slash-command entry points for each audit skill
│ └── skills/ ← 8 audit skills: pharn-privacy-audit, pharn-security-review, pharn-a11y-audit, pharn-drift-check, pharn-posthog-masking-audit, pharn-logging-masking-audit, pharn-license-compliance-audit, pharn-supply-chain-audit
├── pharn-skills-db/ ← skill-category module: database-host vendor bridges (stack-agnostic)
│ ├── module.json
│ └── skills/ ← neon (db-host alt; Supabase uses its official vendor skill)
├── pharn-skills-orm/ ← skill-category module: ORM vendor bridges (stack-agnostic)
│ ├── module.json
│ └── skills/ ← drizzle (default), prisma (alt)
├── pharn-skills-auth/ ← skill-category module: auth vendor bridges (stack-agnostic)
│ ├── module.json
│ └── skills/ ← better-auth (default, stub), clerk (alt), supabase-auth (alt, stub)
├── pharn-skills-payments/ ← skill-category module: payments vendor bridges (stack-agnostic)
│ ├── module.json
│ └── skills/ ← stripe (default)
├── pharn-skills-email/ ← skill-category module: email vendor bridges (stack-agnostic)
│ ├── module.json
│ └── skills/ ← resend (default)
├── pharn-stack-react/ ← framework-agnostic React base (React 19 patterns, useEffect discipline)
│ ├── module.json
│ ├── skills/ ← avoid-react-use-effect
Expand All @@ -102,7 +117,7 @@ pharn-oss/
│ ├── security.md ← SEC: OWASP Top 10, secrets, input validation, headers
│ ├── testing.md ← TEST: Vitest units, Playwright E2E, tenant isolation
│ └── accessibility.md ← A11Y: WCAG 2.2, keyboard operability, semantic HTML
├── skills/ ← feature-module-layers; 6 vendor-bridge skills: drizzle (ORM default), prisma (ORM alt), stripe (payments default), resend (email default), neon (db-host alt), clerk (auth alt)
├── skills/ ← feature-module-layers (Next.js-specific; the only skill here — vendor bridges now live in the pharn-skills-* category modules above)
├── phase-variants/ ← stack-specific generation patterns (build-phase consumed; see §6)
│ 2 shipped: server-actions-pattern, next-safe-action-wrapping
├── grill-banks/ ← stack-specific grill question banks (grill-phase consumed; see §6)
Expand Down Expand Up @@ -143,7 +158,7 @@ pharn-oss/
| A stack-specific generation pattern (the code shape a build phase emits) | `pharn-stack-*/phase-variants/` |
| A stack-specific grill question bank (the questions the grill phase asks) | `pharn-stack-*/grill-banks/` |
| An architecture-mapping pattern for a divergent backend (MySQL, reactive, NoSQL) | `pharn-stack-*/combinations/` (distinct from bridges — maps methodology onto a different architecture, not wires a vendor into the default one) |
| A vendor-bridge skill (config + wiring, not API how-to) | the relevant stack pack's `skills/<vendor>/` (there is no `vendor-bridges/` folder; pinned API docs live in `ai_docs/`) |
| A vendor-bridge skill (config + wiring, not API how-to) | the matching skill-category module's `skills/<vendor>/` (`pharn-skills-{db,orm,auth,payments,email}`; there is no `vendor-bridges/` folder; pinned API docs live in the stack pack's `ai_docs/`) |
| A new `PreToolUse` / `UserPromptSubmit` hook (single-file `.cjs`, stdlib only) | `pharn-core/hooks/<name>/` |
| A new `Stop` hook specific to a module (single-file `.cjs`, stdlib only) | `<module>/hooks/<name>/` (e.g. `pharn-pipeline/hooks/`) |
| Wizard logic, dependency rules, post-install steps | **NOT HERE** — that belongs in `pharn-cli` |
Expand All @@ -159,6 +174,8 @@ pharn-oss/

- Supabase, Firebase, Better Auth, Convex, shadcn, Sentry, Vercel, Expo

**Exception — wiring-only coexistence.** A vendor that _has_ an official skill MAY still carry a thin `vendor-bridge` **stub** limited to PHARN-stack wiring the official skill does not cover (file locations, ORM-adapter choice, env wiring) — **never API how-to**. The wizard option for it must set `vendorSkill` to reference the official skill (so the official skill still does the teaching). This is why `pharn-skills-auth` ships `better-auth` and `supabase-auth` bridges alongside their official skills. A full how-to skill for these vendors is still forbidden; only the wiring stub is allowed.

**Vendors with no official skill yet (PHARN writes a _vendor-bridge_ skill):**

- Stripe, Resend, Drizzle, Prisma, Neon, Clerk
Expand Down Expand Up @@ -212,9 +229,9 @@ rule_files: []
---
```

### Vendor-bridge skill (inside the relevant stack pack's `skills/<vendor>/`)
### Vendor-bridge skill (inside a `pharn-skills-<category>/skills/<vendor>/` category module)

Bridges are PHARN-written config + wiring guides for vendors without an official Claude skill. They are **reference/setup skills** consumed by the wizard during init and by `/pharn-build` when a feature needs the vendor. They are **not** interactive slash-commands.
Bridges are PHARN-written config + wiring guides for vendors without an official Claude skill. They are **reference/setup skills** consumed by the wizard during init and by `/pharn-build` when a feature needs the vendor. They are **not** interactive slash-commands. As of v0.69.0 they live in stack-agnostic **skill-category modules** (`pharn-skills-db`, `pharn-skills-orm`, `pharn-skills-auth`, `pharn-skills-payments`, `pharn-skills-email`) — not inside any one stack pack — so every stack pack can compose them. The `rules/` and `ai_docs/` a bridge references still ship with the installed **stack pack** and resolve in the user's `.claude/` at install time (the bridge frontmatter declares `rule_files_provided_by: "stack-pack"`).

**Three-layer relationship:**

Expand Down Expand Up @@ -243,7 +260,7 @@ version: "0.1.0"
description: "Vendor-bridge for drizzle-orm. Config + wiring only. API how-to in ai_docs/drizzle-orm.md."
kind: pharn-owned # in-repo PHARN bridge; community-scaffolded bridges use kind: community
seal: "vendor-bridge" # NEVER "PHARN ✓ reviewed" on a bridge — that seal is forbidden here
module: pharn-stack-nextjs
module: pharn-skills-orm # the owning skill-category module (NOT a stack pack)
library: "drizzle-orm"
official_skill_available: false
model_tier: sonnet
Expand All @@ -253,9 +270,10 @@ category: "orm" # orm | payments | email | db-host | auth
role: "default" # default | alternative
alternative_to: null # set on alternative bridges (e.g. "drizzle" for prisma)
rule_files: ["database.md", "architecture.md"]
rule_files_provided_by: "stack-pack" # the rule files ship with the installed stack pack, not this module
reads: [".env.example", "drizzle.config.ts"]
writes: ["shared/lib/db/client.ts", "shared/lib/db/schema/", "drizzle.config.ts"]
pharn_version: "0.52.0"
pharn_version: "0.69.0"
---
```

Expand Down Expand Up @@ -642,10 +660,10 @@ The Memory Bank is **markdown-canonical**. It is readable, diffable, lives in gi

## 8. Versioning

Single source of truth: `SKILLS_VERSION` file at repo root (semver). Current value: `0.68.0`.
Single source of truth: `SKILLS_VERSION` file at repo root (semver). Current value: `0.69.0`.

```text
SKILLS_VERSION → 0.68.0
SKILLS_VERSION → 0.69.0
```

**Rules:**
Expand Down Expand Up @@ -747,8 +765,8 @@ Run through this every time a new skill, phase, lens, validator, command, audit,

### Step 2 — Vendor check (only for vendor-related additions)

- [ ] Does this vendor have an official Claude skill (Supabase, Firebase, Better Auth, Convex, shadcn, Sentry, Vercel, Expo)? → **Do not create a PHARN skill.** Reference the official one in `pharn.config.json` with a pinned commit hash.
- [ ] Is this a vendor without official skill (Stripe, Resend, Drizzle, Prisma, Neon, Clerk)? → Create a `vendor-bridge` skill in the relevant stack pack. Scope = wiring/config only. API how-to goes in `ai_docs/`.
- [ ] Does this vendor have an official Claude skill (Supabase, Firebase, Better Auth, Convex, shadcn, Sentry, Vercel, Expo)? → **Do not create a PHARN how-to skill.** Reference the official one in `pharn.config.json` with a pinned commit hash. (Exception: a thin wiring-only `vendor-bridge` stub may coexist with the official skill — see the §5 "wiring-only coexistence" note; the wizard option must set `vendorSkill`.)
- [ ] Is this a vendor without official skill (Stripe, Resend, Drizzle, Prisma, Neon, Clerk)? → Create a `vendor-bridge` skill in the matching skill-category module (`pharn-skills-{db,orm,auth,payments,email}/skills/<vendor>/`). Scope = wiring/config only. API how-to goes in the stack pack's `ai_docs/`.

### Step 3 — Banned-patterns check

Expand Down Expand Up @@ -820,4 +838,4 @@ If a feature request fits one of those, redirect the user before writing anythin

---

_Last updated: June 2026 (v0.68.0). This file is the source of truth for working on pharn-oss. If something in it conflicts with another doc in this repo, this file wins._
_Last updated: June 2026 (v0.69.0). This file is the source of truth for working on pharn-oss. If something in it conflicts with another doc in this repo, this file wins._
21 changes: 13 additions & 8 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -92,14 +92,19 @@ Alongside the pipeline: `/pharn-drift`, `/pharn-cost`, `/pharn-eval`, `/pharn-pr

Modules are **subfolders**, each fetched independently by the installer — not npm packages. `pharn-core` is required; everything else depends on it.

| Module | What it gives you |
| -------------------- | --------------------------------------------------------------------------------------------------- |
| `pharn-core` | Constitution, markdown memory bank, `privacy-shield` + `constitution-guard` hooks, 4 base skills |
| `pharn-pipeline` | The 6-stage pipeline plus `drift`, `cost`, `eval`, `pr` |
| `pharn-review` | `/pharn-review` with **13 context lenses** (architecture, security, privacy, a11y, …) |
| `pharn-audits` | **7 standalone audits** — privacy, security, a11y, PostHog + logging masking, license, supply-chain |
| `pharn-stack-react` | Framework-agnostic React 19 base (useEffect discipline, reused by every React stack pack) |
| `pharn-stack-nextjs` | Next.js + Supabase + Better Auth + Drizzle stack pack (19 rule files) |
| Module | What it gives you |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `pharn-core` | Constitution, markdown memory bank, `privacy-shield` + `constitution-guard` hooks, 4 base skills |
| `pharn-pipeline` | The 6-stage pipeline plus `drift`, `cost`, `eval`, `pr` |
| `pharn-review` | `/pharn-review` with **13 context lenses** (architecture, security, privacy, a11y, …) |
| `pharn-audits` | **7 standalone audits** — privacy, security, a11y, PostHog + logging masking, license, supply-chain |
| `pharn-skills-db` | Database-host vendor bridges (Neon) — stack-agnostic, composed by the wizard |
| `pharn-skills-orm` | ORM vendor bridges (Drizzle, Prisma) — stack-agnostic |
| `pharn-skills-auth` | Auth vendor bridges (Better Auth, Clerk, Supabase Auth) — stack-agnostic |
| `pharn-skills-payments` | Payments vendor bridges (Stripe) — stack-agnostic |
| `pharn-skills-email` | Email vendor bridges (Resend) — stack-agnostic |
| `pharn-stack-react` | Framework-agnostic React 19 base (useEffect discipline, reused by every React stack pack) |
| `pharn-stack-nextjs` | Next.js App Router stack pack — 19 rule files, ai_docs, phase-variants, grill-banks; pair with `pharn-skills-*` for vendor bridges |

---

Expand Down
2 changes: 1 addition & 1 deletion SKILLS_VERSION
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1 +1 @@
0.68.1
0.69.0
Loading
Loading