From 187b82dc67df93bc9fa94f228292333ebf1f7807 Mon Sep 17 00:00:00 2001 From: Israel Sanjurjo Date: Thu, 23 Jul 2026 21:14:49 +0200 Subject: [PATCH] =?UTF-8?q?feat:=20xf-library=20reuse-advisor=20skill;=20l?= =?UTF-8?q?ibraries.md=20=E2=86=92=20tech-agnostic=20live=20discovery;=20r?= =?UTF-8?q?elease=200.5.0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .claude-plugin/marketplace.json | 2 +- README.md | 8 +- plugin/.claude-plugin/plugin.json | 4 +- plugin/CHANGELOG.md | 35 +++++++ plugin/README.md | 1 + plugin/skills/_shared/libraries.md | 93 ++++++++++++------- plugin/skills/xf-analyze/SKILL.md | 2 +- plugin/skills/xf-classify/SKILL.md | 2 +- plugin/skills/xf-document/SKILL.md | 2 +- plugin/skills/xf-explain/SKILL.md | 2 +- plugin/skills/xf-implement/SKILL.md | 16 +++- plugin/skills/xf-library/SKILL.md | 137 ++++++++++++++++++++++++++++ plugin/skills/xf-review/SKILL.md | 2 +- plugin/skills/xf-scaffold/SKILL.md | 4 +- plugin/skills/xf-specify/SKILL.md | 4 +- plugin/skills/xf-test/SKILL.md | 2 +- 16 files changed, 264 insertions(+), 52 deletions(-) create mode 100644 plugin/skills/xf-library/SKILL.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index f649bf4..0c341ac 100644 --- a/.claude-plugin/marketplace.json +++ b/.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"] diff --git a/README.md b/README.md index baef275..bc22a6e 100644 --- a/README.md +++ b/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. diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json index f683806..24a1c49 100644 --- a/plugin/.claude-plugin/plugin.json +++ b/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" diff --git a/plugin/CHANGELOG.md b/plugin/CHANGELOG.md index f80ac20..2777eae 100644 --- a/plugin/CHANGELOG.md +++ b/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 diff --git a/plugin/README.md b/plugin/README.md index 47b8211..728a188 100644 --- a/plugin/README.md +++ b/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. | diff --git a/plugin/skills/_shared/libraries.md b/plugin/skills/_shared/libraries.md index 9242b61..f3b8070 100644 --- a/plugin/skills/_shared/libraries.md +++ b/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: . +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`, `Business`, `View` / `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/`. - -> 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/ version` (scope `@xfcfam/*`) + - **NuGet** — `dotnet package search XFCFAM` (the official XF namespace, as/when published) + - **PyPI** — search / `pip index versions ` 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: . + +> 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. diff --git a/plugin/skills/xf-analyze/SKILL.md b/plugin/skills/xf-analyze/SKILL.md index 6b33eb3..1fb7a5a 100644 --- a/plugin/skills/xf-analyze/SKILL.md +++ b/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 diff --git a/plugin/skills/xf-classify/SKILL.md b/plugin/skills/xf-classify/SKILL.md index 313f3f3..8bf5fdf 100644 --- a/plugin/skills/xf-classify/SKILL.md +++ b/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 diff --git a/plugin/skills/xf-document/SKILL.md b/plugin/skills/xf-document/SKILL.md index c27efc6..3c2f765 100644 --- a/plugin/skills/xf-document/SKILL.md +++ b/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 diff --git a/plugin/skills/xf-explain/SKILL.md b/plugin/skills/xf-explain/SKILL.md index e240ba5..5edf8d4 100644 --- a/plugin/skills/xf-explain/SKILL.md +++ b/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 diff --git a/plugin/skills/xf-implement/SKILL.md b/plugin/skills/xf-implement/SKILL.md index c9d7d08..eb5f65c 100644 --- a/plugin/skills/xf-implement/SKILL.md +++ b/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: diff --git a/plugin/skills/xf-library/SKILL.md b/plugin/skills/xf-library/SKILL.md new file mode 100644 index 0000000..77230e8 --- /dev/null +++ b/plugin/skills/xf-library/SKILL.md @@ -0,0 +1,137 @@ +--- +name: xf-library +description: > + Use this skill when a developer asks which library to use for an + implementation need — "what library should I use for X?", "is there an XF + library for caching / Postgres / an HTTP client?", "recommend a package for + in my stack", "do I build this or is there a library?", "find me a + reusable component for ". It frames the need as an XF capability and L×T + cell, resolves the concrete package **live** in the developer's ecosystem + (npm / NuGet / PyPI / Maven), and recommends the best fit — or tells them to + hand-write it. Advice-only: it recommends and shows the wiring, it does not + generate the implementation (hand that to `xf-implement`). For conceptual + questions use `xf-explain`; to actually build, `xf-implement` / `xf-scaffold`. +metadata: + version: "0.5.0" +--- + +# XF Library — reuse advisor + +Recommend the **best-fit reusable library for an implementation need**, in the +developer's actual stack — or conclude that none fits and it should be +hand-written per the model. This is the front-end of the *reuse-before-you-build* +rule: the build skills (`xf-implement`, `xf-scaffold`, `xf-specify`) delegate the +"is there a library for this?" question here. + +**Advice-only.** This skill produces a recommendation and the wiring shape, not +the implementation. When the choice is made, hand off to `xf-implement` (to +build the component) or `xf-scaffold` (to lay down the skeleton). + +Read **[`../_shared/libraries.md`](../_shared/libraries.md)** first — it holds +the technology-agnostic **capability map** and the **live resolution protocol** +this skill executes. Do not duplicate it here; apply it. + +## Core principle — resolve live, never from memory + +The set of packages, their versions and their status change constantly across +ecosystems. **Never recommend a package or a version from memory or from a static +list.** Detect the ecosystem, query its registry, and report what the registry +says *now*. If you cannot reach the registry, say so and give the capability-level +recommendation (which base to extend, which L×T cell) without asserting a package +name or version. + +## Procedure + +### 1. Frame the need — capability, L×T cell, and "is it even an XF component?" + +Restate the need as a **capability** from the map in `libraries.md` (persistence, +HTTP/REST, filesystem, SQL, a server transport, a cross-cutting policy such as +retry / cache / pagination / scheduling / observable state / a state machine) and +the **L×T cell / role** it would occupy. Two distinctions to make up front: + +- **XF reference library vs. plain dependency.** Some needs are met by an *XF* + library (a base Generalization / Utility you extend — e.g. a + `DatabaseRepository` base). Others are a **low-level dependency** that is *not* + an XF component at all (a DB driver, a JSON parser, a crypto primitive) — those + are **encapsulated inside** the relevant Access (or layer-local Utility) + component, never exposed across layers. Name which kind the need is. +- **Which layer.** The capability fixes the layer: external I/O → Access; + cross-cutting policy → a Generalization in the layer that needs it; a pure + helper → a Utility. State it, because a library that would force the wrong cell + is the wrong library. + +### 2. 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. If unknown, ask the developer for the target stack. + +### 3. Resolve candidates live + +Run the registry search from `libraries.md` for the capability — e.g. +`npm search @xfcfam` and `npm view @xfcfam/ version` for npm; the equivalent +official XF namespace search for NuGet / PyPI / Maven. Read the **current version +and status** from the registry. Also consider any plain (non-XF) dependency the +component would wrap, and check that it is maintained. + +### 4. Recommend (or say "hand-write") + +- **If an XF library fits:** name it, with the **version the registry reports**, + the **base Generalization to extend**, and the **canonical folder** for its + L×T cell. Prefer the most specific fit (a Postgres dialect adapter over a + generic SQL base when the target is Postgres). If several fit, rank them and say + why (specificity, maintenance, transitive weight). +- **If no XF library exists for this stack yet:** say so plainly and recommend + **hand-writing the component per the model** — point to `xf-scaffold` / + `xf-implement` — and name the plain dependency to encapsulate inside it (with + its live version). Missing XF library ≠ blocked: hand-written is equally + conformant. +- **If the need is trivial** (a few lines), recommend writing it directly rather + than taking a dependency. + +### 5. Show the wiring + +Sketch how the recommendation slots into XF: the class extending the base, the +canonical folder, and the injection slot to register. Keep the dependency +**confined** to its component — a library detail must never leak across a layer +boundary (the whole point of the Access layer). + +## Guardrails + +- **Conveniences, not prescriptions.** XF prescribes only the L×T classification + and the descending-dependency direction; a library is one way to satisfy them, + never a requirement. Never imply a developer *must* use a given package. +- **Fit the cell, or reject it.** A library that would push domain logic into + Access, or force an upward dependency, or sit in the wrong layer, is the wrong + recommendation regardless of popularity. +- **Encapsulate.** A recommended dependency (XF or plain) lives inside one + component; it is not referenced across layers. +- **Honest about uncertainty.** If the registry is unreachable or the namespace + has nothing for the need, say "no XF library for this in today" + rather than guessing. + +## Worked example (compact) + +> "I need to read/write Postgres for a TypeScript service." + +1. **Capability / cell:** SQL persistence → **Access · Logical** (a + `*Repository`), extending an SQL **Generalization**; the Postgres driver is a + plain dependency encapsulated inside the Access component. +2. **Ecosystem:** `package.json` → npm. +3. **Resolve live:** `npm search @xfcfam` → look for the SQL base + a Postgres + dialect adapter; `npm view version` for the current versions. (Report + what the registry returns — do not assert a version here.) +4. **Recommend:** the SQL `DatabaseRepository` base + the Postgres dialect + adapter the registry reports (most specific fit), each at its current version; + or, if absent, hand-write a `DatabaseRepository` over the `pg` driver per the + model. +5. **Wiring:** `class UserRepository extends DatabaseRepository<…>` in + `repository/logic/remote/`, registered as a slot in `R`; the driver stays + inside it. + +## References + +- **Reuse map & live-resolution protocol:** [`../_shared/libraries.md`](../_shared/libraries.md) — the capability map and the per-ecosystem registry search this skill runs. +- **Foundations & particularities:** [`../_shared/foundations.md`](../_shared/foundations.md) — why a dependency must be encapsulated in its layer; effective vs contextual logic. +- **Normative spec:** — edition XF-CFAM-001:2026. Clause map in [`../_shared/spec.md`](../_shared/spec.md). +- **Rule catalog:** [`../_shared/catalogue.md`](../_shared/catalogue.md) · [`../_shared/rules-detail.md`](../_shared/rules-detail.md) — 9 groups, 71 rules, conformance level Λ=0..4. diff --git a/plugin/skills/xf-review/SKILL.md b/plugin/skills/xf-review/SKILL.md index eb15a73..96d0ee0 100644 --- a/plugin/skills/xf-review/SKILL.md +++ b/plugin/skills/xf-review/SKILL.md @@ -7,7 +7,7 @@ description: > "review my architecture". Also use when the user pastes code and asks if the structure is correct according to XF or CFAM. metadata: - version: "0.4.0" + version: "0.5.0" --- # XF Compliance Review diff --git a/plugin/skills/xf-scaffold/SKILL.md b/plugin/skills/xf-scaffold/SKILL.md index e374fff..95b0832 100644 --- a/plugin/skills/xf-scaffold/SKILL.md +++ b/plugin/skills/xf-scaffold/SKILL.md @@ -11,14 +11,14 @@ description: > backend", "set up a new service", "initialize a project") — in that case ASK whether they want XF structure before scaffolding, rather than assuming it. metadata: - version: "0.4.0" + version: "0.5.0" --- # XF Scaffold Generate XF-compliant project structure and component boilerplate. -> **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. ## Determine scope diff --git a/plugin/skills/xf-specify/SKILL.md b/plugin/skills/xf-specify/SKILL.md index 6cce7f8..f0a7028 100644 --- a/plugin/skills/xf-specify/SKILL.md +++ b/plugin/skills/xf-specify/SKILL.md @@ -12,7 +12,7 @@ description: > client requirement into an implementation plan / task list". This is design-only — no code is written. metadata: - version: "0.4.0" + version: "0.5.0" --- # XF Specify @@ -37,7 +37,7 @@ Read **`../_shared/catalogue.md`** (rule + conformance overview) and the `xf-classify` decision tree (`../xf-classify/references/decision-tree.md`) before decomposing. -> **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 diff --git a/plugin/skills/xf-test/SKILL.md b/plugin/skills/xf-test/SKILL.md index 25a0975..b84f06b 100644 --- a/plugin/skills/xf-test/SKILL.md +++ b/plugin/skills/xf-test/SKILL.md @@ -8,7 +8,7 @@ description: > Also trigger when the user wants help unit-testing XF / CFAM code while respecting layer isolation. metadata: - version: "0.4.0" + version: "0.5.0" --- # XF Test Designer