feat: xf-library reuse-advisor skill; libraries.md → tech-agnostic live discovery; release 0.5.0

.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
     {
       "name": "xf-architecture",
       "source": "./plugin",
-      "description": "Analyze a spec (SRS + ADRs to design), classify, specify, implement, scaffold, review, test, document, and explain code following the XF Architecture Model (CFAM). Supports TypeScript, Python, Swift, and Kotlin.",
+      "description": "Analyze a spec (SRS + ADRs to design), classify, specify, implement, scaffold, recommend reuse libraries, review, test, document, and explain code following the XF Architecture Model (CFAM). Supports TypeScript, Python, Swift, and Kotlin.",
       "homepage": "https://xfcfam.org",
       "license": "MIT",
       "keywords": ["architecture", "xf", "cfam", "code-generation", "compliance"]

README.md

@@ -7,16 +7,16 @@ questions about the XF spec.
 
 ## Status
 
-Working plugin, version **0.3.0**, tracking spec edition **XF-CFAM-001:2026**.
+Working plugin, version **0.5.0**, tracking spec edition **XF-CFAM-001:2026**.
 See [`plugin/CHANGELOG.md`](./plugin/CHANGELOG.md) for the release history and
 [`plugin/README.md`](./plugin/README.md) for install instructions.
 
 ## What's in scope
 
-- A Claude plugin (`plugin/.claude-plugin/plugin.json`) bundling eight skills.
+- A Claude plugin (`plugin/.claude-plugin/plugin.json`) bundling ten skills.
 - A library of **skills** that teach Claude to apply XF rules in conversation:
-  `xf-classify`, `xf-specify`, `xf-implement`, `xf-scaffold`, `xf-review`,
-  `xf-test`, `xf-document`, and `xf-explain`.
+  `xf-classify`, `xf-analyze`, `xf-specify`, `xf-implement`, `xf-scaffold`,
+  `xf-library`, `xf-review`, `xf-test`, `xf-document`, and `xf-explain`.
 - **Shared references** under `plugin/skills/_shared/`: the model `foundations`
   (philosophy & particularities), the `spec` clause map, the synced rule
   `catalogue` / `rules-detail`, and the `@xfcfam/*` `libraries` index.

plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "xf-architecture",
-  "version": "0.4.0",
-  "description": "Skills for generating and verifying code that follows the XF Architecture Model (Cross-Framework Architecture Model, CFAM). Analyze a specification (SRS + ADRs to design), classify, specify, implement, scaffold, review, test, document, and explain the L×T matrix system.",
+  "version": "0.5.0",
+  "description": "Skills for generating and verifying code that follows the XF Architecture Model (Cross-Framework Architecture Model, CFAM). Analyze a specification (SRS + ADRs to design), classify, specify, implement, scaffold, recommend reuse libraries, review, test, document, and explain the L×T matrix system.",
   "author": {
     "name": "XFArch Contributors",
     "url": "https://xfcfam.org"

plugin/CHANGELOG.md

@@ -7,6 +7,41 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [0.5.0] — 2026-07-23
+
+### Added
+
+- **New skill `xf-library` — reuse advisor.** Invocable directly with "what
+  library should I use for X?": frames the need as an XF capability + L×T cell
+  (or a plain dependency to encapsulate), resolves the best-fit package **live**
+  in the developer's ecosystem (npm / NuGet / PyPI / Maven) per the
+  `_shared/libraries.md` protocol, and recommends it (with the live version and
+  the base Generalization to extend) or concludes it should be hand-written.
+  Advice-only; the build skills (`xf-implement`, `xf-scaffold`, `xf-specify`)
+  delegate the reuse question to it. Brings the plugin to **ten skills**.
+
+### Changed
+
+- **`_shared/libraries.md` — technology-agnostic, dynamic discovery.** Replaced
+  the static, npm-only package table (a maintenance trap once XF spans npm /
+  NuGet / PyPI / Maven) with a stable, model-level **capability map** plus a
+  **live per-ecosystem resolution protocol**: detect the manifest, search the
+  official XF namespace in that registry, read the current version / status from
+  the registry itself, and hand-write only when no library exists. The
+  `@xfcfam/*` npm scope is reframed as *today's reference implementation, to
+  confirm live* — not a fixed list. The "Reuse before you build" callouts in
+  `xf-implement`, `xf-scaffold` and `xf-specify` were reworded to be
+  stack-agnostic and dynamic.
+- **`xf-implement` — reuse triage before writing.** Step 4 now opens with an
+  explicit triage that consults **`xf-library`** for the components where a
+  library plausibly exists (Access adapters, server transports, cross-cutting
+  Generalizations, general-purpose Utilities) to decide reuse-vs-ad-hoc, and
+  **skips** it for inherently bespoke parts (Business domain logicals, domain
+  operations, Transfers). Degrades gracefully offline.
+- Bumped the plugin and all **ten** skill versions to **0.5.0**.
+
+---
+
 ## [0.4.0] — 2026-06-13
 
 Validator integration, ambient XF awareness, operation-level planning, and a new

plugin/README.md

@@ -48,6 +48,7 @@ After pushing changes upstream, refresh with:
 | `xf-specify` | "specify this feature in XF", "what components do I need for…", "plan this user story" | Translates a **single** feature / user story into an L×T component plan **with operations** — design only. For a whole spec, use `xf-analyze`. |
 | `xf-implement` | "implement this feature in XF", "generate XF code for…", "build this following CFAM" | Generates XF-compliant components from a feature or requirement, wired through R/B/A. |
 | `xf-scaffold` | "scaffold an XF project", "generate XF structure", "add a UserBusiness" | Generates the canonical folder layout, R/B/A injection stubs, and component boilerplate. |
+| `xf-library` | "what library should I use for…", "is there an XF library for caching/Postgres/…", "build or reuse?" | Reuse advisor: frames the need as a capability + L×T cell, resolves the best-fit library **live** in your ecosystem (npm/NuGet/PyPI/Maven), or says hand-write it. Advice only. |
 | `xf-review` | "review for XF compliance", "check XF violations", "what conformity level is this?" | Runs the `@xfcfam/tools` validator (falls back to a manual catalogue walk) and audits layer / naming / folder / injection violations. Reports Λ=0..4. |
 | `xf-test` | "write tests for this XF component", "how do I test XF code", "mock the injection for testing" | Designs tests that respect layer isolation (mock through R/B/A), with coverage by L×T cell. |
 | `xf-document` | "document this XF artifact", "generate a component catalog / README" | Produces a component catalog by L×T cell, the injection map, the dependency view, and docs. |

plugin/skills/_shared/libraries.md

@@ -1,40 +1,67 @@
-# XF reference libraries (`@xfcfam/*`)
+# XF reference libraries — discovery (technology-agnostic)
 
-Before implementing a Utility, a Generalization, or a whole layer adapter from
-scratch, **check whether a published reference library already provides it** and
-extend or compose it instead of reinventing. These packages are the official
-TypeScript reference implementation of the XF model; each is published to npm and
-depends on the core `@xfcfam/xf`. Full catalog and docs: <https://xfcfam.org>.
+Before hand-writing a Utility, a Generalization, or a whole layer adapter, check
+whether a published **XF reference library for the developer's stack** already
+covers it, and extend / compose it instead of reinventing.
+
+**There is no static package list here, on purpose.** Across npm, NuGet, PyPI,
+Maven and others, the set of packages — their versions, status and
+correspondence to a given technology — changes constantly; a baked-in catalogue
+would be stale the day after it is written and would silently misadvise. So the
+existence and version of a concrete package is **resolved live** against the
+relevant registry (below). What this file holds is only the **stable, model-level
+map** of *what kinds of reusable building block to look for*.
 
 ## Reuse rule
 
-1. Need persistence, HTTP, a filesystem, SQL, a server transport, or
-   retry / cache / pagination / scheduling / a state machine? Reach for the
-   matching `@xfcfam/*` package **first**.
-2. Extend the library's base Generalization for your layer
-   (e.g. `class UserRepository extends StatelessRepository<…>`) — don't
-   re-derive the lifecycle/injection contract by hand.
-3. Only hand-write a component when no library covers the need, and keep it in
-   the canonical folder for its L×T cell.
+1. Need persistence, HTTP, a filesystem, SQL, a server transport, or a
+   cross-cutting policy (retry / cache / pagination / scheduling / a state
+   machine / observable state)? A reference library probably already provides the
+   matching Generalization or Utility — reach for it **first**.
+2. Extend the library's base Generalization for your layer (e.g. a
+   `…Repository` base) instead of re-deriving the lifecycle / injection contract.
+3. Hand-write a component only when no library covers the need — always valid,
+   since the libraries are *conveniences, not prescriptions* — and keep it in the
+   canonical folder for its L×T cell.
+
+## Capability map (stable — *what* to look for)
 
-## Packages
+The model anticipates these *kinds* of reusable building block. The concrete
+package name differs per ecosystem and is resolved live (next section):
 
-| Package | Layer · role | What it provides |
+| Capability | XF role | Building block to look for |
 |---|---|---|
-| `@xfcfam/xf` | Core | Abstract layer Generalizations — `Repository<T>`, `Business<T>`, `View<T>` / `Service` and their `Stateless` / `Observable` / `Cacheable` / `Retryable` / `Paginated` / `Schedule` / `Validated` / `StateMachine` / `EventSourced` variants — the Injection contracts `R` / `B` / `A`, and the `XF` lifecycle orchestrator. |
-| `@xfcfam/xf-rest` | Access | REST repository over `ky`: `RestRepository` + `RetryRestRepository`; `ParseUtils` / `ReviverUtils` for XML, CSV, custom content types, and date revival. |
-| `@xfcfam/xf-fs` | Access | Filesystem over `node:fs`: `FileRepository` + its `Cached` / `Audited` variants. |
-| `@xfcfam/xf-sql` | Access | SQL over the Kysely query builder (dialect-agnostic): `DatabaseRepository` + `TransactionalDatabaseRepository`. Pair with a dialect adapter. |
-| `@xfcfam/xf-sql-postgres` | Access | PostgreSQL dialect adapter for `xf-sql` (Kysely `PostgresDialect` + `pg`; maps Postgres `SQLSTATE` to typed Exceptions). |
-| `@xfcfam/xf-server` | Interaction + Business | Transport-agnostic inbound-server contract: the abstract `ServerBusiness` / `EntryService` (registry + lifecycle + request pipeline). No transport of its own. |
-| `@xfcfam/xf-server-http` | Interaction + Business | HTTP transport over Fastify — REST · WebSocket · SSE · GraphQL on one port: `HttpServerBusiness` + `RestService` / `ObjectRestService` / `WebSocketService` / `GraphQLService`. |
-| `@xfcfam/xf-server-grpc` · `-tcp` · `-udp` | Interaction + Business | Sketches — typed transport skeletons compiled against the `xf-server` contract (not production-ready). |
-
-**Install pattern:** every adapter needs the core —
-`pnpm add @xfcfam/xf @xfcfam/<pkg>`.
-
-> The library's base classes (e.g. `StatelessBusiness`, `StatelessService`) are
-> conveniences of the reference implementation, **not** prescriptions of the
-> model. The XF model prescribes only the L×T classification and the
-> descending-dependency direction; a component that achieves those with a
-> different mechanism is equally conformant.
+| Core abstractions | every layer | the layer Generalizations (`Repository` / `Business` / `Service` / `View`) and their stateless / observable / cacheable / retryable / paginated / scheduled / validated / state-machine variants; the `R` / `B` / `A` injection contracts; the `XF` lifecycle orchestrator |
+| HTTP / REST client | Access | a `RestRepository`-type Generalization (+ a retry variant) and content-type / date parse `*Utils` |
+| Filesystem | Access | a `FileRepository`-type Generalization (+ cached / audited variants) |
+| SQL / database | Access | a `DatabaseRepository`-type Generalization (+ a transactional variant) and per-dialect adapters |
+| Inbound server / transport | Interaction + Business | a transport-agnostic server contract + transport adapters (REST · WebSocket · SSE · GraphQL · gRPC · …) |
+| Cross-cutting policy | any layer (as a Generalization) | retry · cache · pagination · scheduling · observable state · validation · state machine |
+
+## Resolve concrete packages live (per ecosystem)
+
+1. **Detect the ecosystem** from the artefact's manifest: `package.json` → npm ·
+   `*.csproj` / `*.sln` → NuGet · `pyproject.toml` / `requirements.txt` → PyPI ·
+   `pom.xml` / `build.gradle` → Maven / Gradle.
+2. **Search the official XF namespace in that registry** for the capability, and
+   read the **current version and status from the registry itself** — never from
+   memory or from this file:
+   - **npm** — `npm search @xfcfam` · `npm view @xfcfam/<pkg> version` (scope `@xfcfam/*`)
+   - **NuGet** — `dotnet package search XFCFAM` (the official XF namespace, as/when published)
+   - **PyPI** — search / `pip index versions <pkg>` in the official `xfcfam` namespace
+   - **Maven Central** — search the `org.xfcfam` group
+3. **If a library exists**, prefer it and pin the version the registry reports.
+   **If none exists for that ecosystem yet**, hand-write the component per the
+   model (equally conformant) — do not block on a missing library.
+
+> **Reference implementation today:** the model's reference libraries are
+> TypeScript, published to **npm under the `@xfcfam/*` scope** (core + REST,
+> filesystem, SQL and server adapters). Treat even that as something to **confirm
+> live** (`npm search @xfcfam`) rather than a fixed list — the namespace grows,
+> and other ecosystems (NuGet / PyPI / Maven) come online over time. Full
+> ecosystem: <https://xfcfam.org>.
+
+> The library base classes are **conveniences** of a reference implementation,
+> **not** prescriptions of the model. XF prescribes only the L×T classification
+> and the descending-dependency direction; a component that achieves those by any
+> mechanism is equally conformant.

plugin/skills/xf-analyze/SKILL.md

@@ -14,7 +14,7 @@ description: >
   code. For a SINGLE feature or user story (not a whole spec), use `xf-specify`.
   To analyze EXISTING code, use `xf-classify` / `xf-review`.
 metadata:
-  version: "0.4.0"
+  version: "0.5.0"
 ---
 
 # XF Analyze — requirements to a verified XF design

plugin/skills/xf-classify/SKILL.md

@@ -7,7 +7,7 @@ description: >
   "how do I migrate this to XF structure?". Also use when the user provides
   existing code and wants to know its XF classification before refactoring.
 metadata:
-  version: "0.4.0"
+  version: "0.5.0"
 ---
 
 # XF Component Classifier

plugin/skills/xf-document/SKILL.md

@@ -9,7 +9,7 @@ description: >
   architecture docs, or a component inventory derived from an XF / CFAM
   codebase.
 metadata:
-  version: "0.4.0"
+  version: "0.5.0"
 ---
 
 # XF Documentation Generator

plugin/skills/xf-explain/SKILL.md

@@ -8,7 +8,7 @@ description: >
   "how do I use R, B, A?", or any question about understanding the XF
   Architecture Model concepts, principles, or decisions.
 metadata:
-  version: "0.4.0"
+  version: "0.5.0"
 ---
 
 # XF Explainer

plugin/skills/xf-implement/SKILL.md

@@ -8,7 +8,7 @@ description: >
   XF-compliant implementation. Use after a plan exists (or build the plan
   inline) — this skill produces real source files.
 metadata:
-  version: "0.4.0"
+  version: "0.5.0"
 ---
 
 # XF Implement
@@ -27,7 +27,7 @@ If the user only wants a design / component plan (no code yet), use
 Read **`../_shared/catalogue.md`** (rule overview + conformance model) and, for
 templates, **`../xf-scaffold/references/structure.md`** before writing.
 
-> **Reuse before you build.** Before writing a Utility, a Generalization, or a layer adapter, check the `@xfcfam/*` reference libraries ([`../_shared/libraries.md`](../_shared/libraries.md)) — persistence, HTTP, SQL, filesystem, server transports, retry/cache/pagination, scheduling and state machines already exist. Extend them instead of reinventing.
+> **Reuse before you build.** Before hand-writing a Utility, a Generalization, or a layer adapter, check whether a published **XF reference library for the developer's stack** already covers the need (persistence, HTTP, SQL, filesystem, server transports, retry / cache / pagination / scheduling / state machines). Resolve it **live** against the project's ecosystem registry (npm / NuGet / PyPI / Maven) per [`../_shared/libraries.md`](../_shared/libraries.md) — or ask the **`xf-library`** skill for a recommendation — and extend it rather than reinventing; hand-write only when none exists.
 
 ## The model in one screen
 
@@ -105,6 +105,18 @@ by technology — `UserRepository`, not `PostgresUserRepository`.
 
 ### 4. Implement each component honouring the contract
 
+**Reuse triage first — library or ad-hoc?** Before writing any component whose
+capability a published library plausibly covers — Access logicals /
+generalizations (DB, HTTP, filesystem, external protocols), server transports,
+cross-cutting Generalizations (retry / cache / pagination / scheduling /
+observable state), and general-purpose Utilities — run the **`xf-library`** reuse
+check (resolve live in the project's ecosystem). If a library fits, extend its
+base instead of writing from scratch; if none fits, implement ad-hoc per the
+model. **Skip the check for what is inherently bespoke:** Business domain
+logicals, domain-specific operations, and Transfers — no library implements your
+domain. If the registry is unreachable, fall back to the capability-level
+guidance and proceed (a missing library never blocks).
+
 Write each file. Hard rules to keep while generating:
 
 1. **Injection access** — to use a lower layer, go through its injection: