V48 (specification-implementation): Enforce nested packages for all generic-* families

Require packages/generic-* to be family folders (no root package.json) with
nested implementor packages, matching generic-agents/tools/pipelines. Split the
flat @bitcode/generic-llms package into generic-llms/{xAI,OpenAI,Anthropic,Google,defaults,registry},
keep @bitcode/generic-llms as the registry aggregator, and document the rule in
SOURCE_LAYOUT / FAMILIARIZATION / NOTES with workspace + tsconfig wiring.

Author: geraldarthurdavis

BITCODE_SPEC_V48_NOTES.md

@@ -1493,6 +1493,23 @@ SOURCE_LAYOUT:
 Navigation map: `FAMILIARIZATION.md`. Layout contract: `internal-docs/BITCODE_SOURCE_LAYOUT.md`.
 
 
+## generic-* nested-package rule (Garrett, 2026-07-13)
+
+Every `packages/generic-*` family is nested packages only (no family-root
+`package.json`), matching `generic-agents/*`, `generic-tools/*`,
+`generic-pipelines/*`.
+
+`packages/generic-llms/` was flattened into:
+
+```
+xAI/ OpenAI/ Anthropic/ Google/ defaults/ registry/
+```
+
+`@bitcode/generic-llms` remains the registry aggregator for compatibility;
+prefer `@bitcode/generic-llms-{xai|openai|anthropic|google|defaults}` when a
+single surface is enough. Workspace globs include `packages/generic-llms/*`
+and `packages/generic-doc-comment-plugins/*`.
+
 ## SDIVF base package (Garrett, 2026-07-13)
 
 Pipeline inheritance hierarchy is now explicit:

FAMILIARIZATION.md

@@ -165,11 +165,17 @@ Product UI says **Pipeline**. Low-level packages may still say `execution` /
 ### 3.4 LLMs
 
 ```
-@bitcode/llm-generics           Provider-agnostic LLM call primitives
+@bitcode/llm-generics                    Provider-agnostic LLM call primitives
         ↑
-@bitcode/generic-llms           xAI / other provider implementations + defaults
+@bitcode/generic-llms-{xai|openai|…}     Nested providers under packages/generic-llms/
+@bitcode/generic-llms-defaults           Env-resolved default provider/model
+        ↑
+@bitcode/generic-llms                    registry/ aggregator (all providers)
 ```
 
+`packages/generic-*` is always a **family of nested packages** (never a flat
+single package). Example: `packages/generic-llms/{xAI,OpenAI,Anthropic,Google,defaults,registry}/`.
+
 Deposit default model (V48 Gate 3): `grok-build-0.1` when `XAI_API_KEY` is set.
 Inference is **non-configurable** inside the pipeline (mock at the provider
 boundary in tests only).
@@ -247,10 +253,11 @@ Grouped by role. Names are `@bitcode/<name>` unless noted.
 
 | Package family | Responsibility |
 | --- | --- |
-| `generic-agents/*` | Base agents: VCS, danger-wall, code-editor, digester, web-research, read-comprehension, jira, figma, multimodal processors, … |
-| `generic-tools/*` | Base tools: editing, git, VCS, LSP, web-search, repository-setup, firecrawl, … |
-| `generic-llms` | Concrete providers (xAI, …) and model defaults |
-| `generic-doc-comment-plugins` | Doc-comment plugins |
+| `generic-agents/*` | Nested base agents: VCS, danger-wall, code-editor, digester, web-research, … |
+| `generic-tools/*` | Nested base tools: editing, git, VCS, LSP, web-search, repository-setup, … |
+| `generic-pipelines/*` | Nested base pipelines: SDIVF, … |
+| `generic-llms/*` | Nested providers (xAI, OpenAI, Anthropic, Google), defaults, registry aggregator |
+| `generic-doc-comment-plugins/*` | Nested doc-comment plugins |
 
 ### 5.3 Product domain (AssetPack / BTD / market)
 

internal-docs/BITCODE_SOURCE_LAYOUT.md

@@ -174,6 +174,31 @@ uapi/components/bitcode/
 Packages hold **framework-agnostic** domain logic. Prefer existing packages;
 add new packages when a domain is clearly shared and non-UI.
 
+### 6.1 Nested `generic-*` families (required)
+
+Every `packages/generic-*` path is a **family folder**, not a single package.
+
+```
+packages/generic-<family>/          # README only (no package.json)
+  <ImplementorA>/                   # nested package
+    package.json                    # @bitcode/generic-<family>-…
+    src/
+  <ImplementorB>/
+    ...
+```
+
+| Family | Nested examples | Package names |
+| --- | --- | --- |
+| `generic-agents/` | `vcs/`, `danger-wall/`, … | `@bitcode/generic-agents-*` |
+| `generic-tools/` | `web-search/`, `vcs/`, … | `@bitcode/generic-tools-*` |
+| `generic-pipelines/` | `SDIVF/` | `@bitcode/generic-pipelines-sdivf` |
+| `generic-llms/` | `xAI/`, `OpenAI/`, `Anthropic/`, `Google/`, `defaults/`, `registry/` | `@bitcode/generic-llms-*` (+ aggregator `@bitcode/generic-llms`) |
+| `generic-doc-comment-plugins/` | `doc-developing/` | `@bitcode/doc-comment-developing` |
+
+**Do not** put a root `package.json` on the family folder. Workspace globs are
+`packages/generic-<family>/*` (and deeper globs such as
+`packages/generic-tools/mcps-tools/*` when needed).
+
 ```
 packages/
   api/                         # route handlers, orchestration
@@ -194,6 +219,7 @@ packages/
   btd/                         # BTD measurement, journal, settlement, authority
   pipelines-generics/          # Pipeline / PhaseDelegator primitives
   generic-pipelines/SDIVF/     # SDIVF base Pipeline (extends pipelines-generics)
+  generic-llms/{xAI,OpenAI,…}/ # nested LLM providers + registry aggregator
   pipelines/asset-pack/        # SynthesizeAssetPacks (extends SDIVF base)
   agent-generics/              # PTRR agents (not product “Pipeline” UI)
   execution-generics/          # low-level executor primitives
@@ -252,6 +278,13 @@ bitcode/
 │   ├── pipelines-generics/            # Pipeline / PhaseDelegator primitives
 │   ├── generic-pipelines/
 │   │   └── SDIVF/                     # @bitcode/generic-pipelines-sdivf base
+│   ├── generic-llms/                  # nested LLM providers (no family package.json)
+│   │   ├── xAI/                       # @bitcode/generic-llms-xai
+│   │   ├── OpenAI/                    # @bitcode/generic-llms-openai
+│   │   ├── Anthropic/                 # @bitcode/generic-llms-anthropic
+│   │   ├── Google/                    # @bitcode/generic-llms-google
+│   │   ├── defaults/                  # @bitcode/generic-llms-defaults
+│   │   └── registry/                  # @bitcode/generic-llms (aggregator)
 │   ├── pipelines/
 │   │   └── asset-pack/                # SynthesizeAssetPacks (extends SDIVF)
 │   ├── agent-generics/

package.json

@@ -9,8 +9,11 @@
   "workspaces": [
     "packages/*",
     "packages/generic-tools/*",
+    "packages/generic-tools/mcps-tools/*",
     "packages/generic-agents/*",
     "packages/generic-pipelines/*",
+    "packages/generic-llms/*",
+    "packages/generic-doc-comment-plugins/*",
     "packages/pipelines/*",
     "uapi",
     "admin"

packages/agent-generics/jest.config.cjs

@@ -7,6 +7,14 @@ module.exports = {
   moduleNameMapper: {
     '^@bitcode/pipelines-generics$': '<rootDir>/../pipelines-generics/src/index.ts',
     '^@bitcode/pipelines-generics/(.*)$': '<rootDir>/../pipelines-generics/src/$1',
+    // nested generic-llms family (not packages/generic-llms/src)
+    '^@bitcode/generic-llms$': '<rootDir>/../generic-llms/registry/src/index.ts',
+    '^@bitcode/generic-llms/defaults$': '<rootDir>/../generic-llms/defaults/src/index.ts',
+    '^@bitcode/generic-llms-defaults$': '<rootDir>/../generic-llms/defaults/src/index.ts',
+    '^@bitcode/generic-llms-xai$': '<rootDir>/../generic-llms/xAI/src/index.ts',
+    '^@bitcode/generic-llms-openai$': '<rootDir>/../generic-llms/OpenAI/src/index.ts',
+    '^@bitcode/generic-llms-anthropic$': '<rootDir>/../generic-llms/Anthropic/src/index.ts',
+    '^@bitcode/generic-llms-google$': '<rootDir>/../generic-llms/Google/src/index.ts',
     '^@bitcode/logger$': '<rootDir>/../logger/src/index.ts',
     '^@bitcode/parsing$': '<rootDir>/../parsing/src/parsing.ts',
     '^@bitcode/streams$': '<rootDir>/../streams/src/index.ts',

packages/agent-generics/package.json

@@ -13,6 +13,7 @@
   },
   "dependencies": {
     "@bitcode/execution-generics": "workspace:*",
+    "@bitcode/generic-llms": "workspace:*",
     "@bitcode/prompts": "workspace:*",
     "@bitcode/tools-generics": "workspace:*",
     "@bitcode/pipelines-generics": "workspace:*",

packages/api/package.json

@@ -40,7 +40,8 @@
     "@supabase/supabase-js": "^2.0.0",
     "express": "^4.18.0",
     "zod": "^3.21.4",
-    "@bitcode/pipeline-hosts": "workspace:*"
+    "@bitcode/pipeline-hosts": "workspace:*",
+    "@bitcode/generic-llms": "workspace:*"
   },
   "devDependencies": {
     "@types/express": "^4.17.0",

packages/executions-mcp/src/mcp-server/jest.config.mcp.js

@@ -18,8 +18,13 @@ const explicitMapper = {
   '^@bitcode/pipelines/asset-pack$': '<rootDir>/../../../../packages/pipelines/asset-pack/src/index.ts',
   '^@bitcode/agent-generics$': '<rootDir>/../../../../packages/agent-generics/src/index.ts',
   '^@bitcode/agent-generics/(.*)$': '<rootDir>/../../../../packages/agent-generics/src/$1',
-  '^@bitcode/generic-llms$': '<rootDir>/../../../../packages/generic-llms/src/index.ts',
-  '^@bitcode/generic-llms/(.*)$': '<rootDir>/../../../../packages/generic-llms/src/$1',
+  '^@bitcode/generic-llms$': '<rootDir>/../../../../packages/generic-llms/registry/src/index.ts',
+  '^@bitcode/generic-llms/defaults$': '<rootDir>/../../../../packages/generic-llms/defaults/src/index.ts',
+  '^@bitcode/generic-llms-defaults$': '<rootDir>/../../../../packages/generic-llms/defaults/src/index.ts',
+  '^@bitcode/generic-llms-xai$': '<rootDir>/../../../../packages/generic-llms/xAI/src/index.ts',
+  '^@bitcode/generic-llms-openai$': '<rootDir>/../../../../packages/generic-llms/OpenAI/src/index.ts',
+  '^@bitcode/generic-llms-anthropic$': '<rootDir>/../../../../packages/generic-llms/Anthropic/src/index.ts',
+  '^@bitcode/generic-llms-google$': '<rootDir>/../../../../packages/generic-llms/Google/src/index.ts',
   '^@bitcode/llm-generics$': '<rootDir>/../../../../packages/llm-generics/src/index.ts',
   '^@bitcode/llm-generics/(.*)$': '<rootDir>/../../../../packages/llm-generics/src/$1',
   '^@bitcode/execution-generics$': '<rootDir>/../../../../packages/execution-generics/src/index.ts',

packages/generic-llms/Anthropic/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@bitcode/generic-llms-anthropic",
+  "version": "0.1.0",
+  "description": "Anthropic LLM provider for Bitcode (llm-generics)",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "pnpm exec jest --config jest.config.cjs --passWithNoTests"
+  },
+  "dependencies": {
+    "@bitcode/llm-generics": "workspace:*",
+    "@anthropic-ai/sdk": "0.15.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.0.0",
+    "@types/node": "^20.0.0",
+    "jest": "^29.0.0",
+    "ts-jest": "^29.0.0",
+    "typescript": "^5.0.0"
+  }
+}