ontotwin-library-adoption

name	ontotwin-library-adoption
description	Use when Claude Code is extracting, packaging, installing, or adopting the OntoTwin atlas as a reusable React library.

OntoTwin Library Adoption

Use this project skill when the task is to turn the local OntoTwin atlas into an installable React library or adopt that library in another Claude Code workspace.

Current repo state: the root package exposes a locally packable @ontotwin/atlas-react entrypoint with package metadata, public types, style export, and local pack/build scripts. Treat fresh-playground install, browser adoption proof, clean post-fix autoreview, and a user-confirmed publication license as required evidence before claiming external adoption complete.

Portability level: harness-specific. The package boundary and adapter checks are portable, but the invocation examples, .claude/skills/ location, and subagent names are Claude Code project conventions.

FPF Grounding

Before spec-sensitive work, check the active FPF runtime with get_fpf_index_status or the available FPF MCP equivalent. Stop and report the missing access if no FPF runtime or generated spec docs are available.

Prefer the local fpf-memory-mcp skill when that skill is explicitly part of the task, and use the current FPF Reference runtime label fpf_reference for spec lookup. Use available runtime tools such as get_fpf_index_status and query_fpf_spec; do not invent FPF selectors or canonical wording from memory.

Use these FPF selectors as the minimum frame:

• A.7 Strict Distinction: do not collapse role, method, work, status, description, and specification.
• A.15 Role-Method-Work Alignment: keep role, method, capability, plan, and actual work separate.
• E.10 LEX-BUNDLE: keep Service/Promise, Capability/Ability, and Work/Performance terminology distinct.
• E.10.D2 Intension-Description-Specification Discipline: keep the thing, description, and specification layers separate.
• F.18 Local-First Unification Naming Protocol: name the local context, reference plane, version, and mapping target explicitly.

Required Reading

Read these before editing:

• README.md
• docs/react-library-representation-strategy.md
• docs/atlas-adapter-contract.md
• docs/production-manifest-schema.md
• docs/adoption-decision-framework.md
• docs/claude-code-subagent-interest-model.md
• docs/atlas-configuration-boundaries.md
• package.json
• vite.lib.config.js
• src/index.js
• src/index.d.ts
• src/library.jsx
• src/adapters.js
• src/atlasManifest.js, src/atlasLookup.js, src/atlasInteraction.js, src/atlasLabels.js, and src/main.jsx

Claim Scope

Frame the task before editing:

Bounded context:
Promise:
Ability:
Performance:
Evidence:
Work scope:
Out of scope:
Stop/replan trigger:

Default boundaries:

• The adopting ontology remains the source of truth.
• The library owns React state, interaction, renderer contracts, adapter interfaces, UI slots, and default styles.
• The library does not own production vectorization, graph construction, projection jobs, tile generation, auth, disclosure policy, privacy review, or deployment approval.
• Synthetic demo data is demo evidence only.
• Public tiles use render-safe fields only.
• Counts must declare source and disclosure handling.
• Production manifests bind disclosure, auth, authorization, audit, cache, retention, source-field mapping, public tile schema, and deployment gates as schema fields, not prose-only assumptions.
• The package surface must be represented by package metadata, not only source files. The package package.json must declare name, version, type, license, exports, types, files, React peer dependencies, build scripts, and a CSS subpath export for ./styles.css.

Claude Code Route

Use Explore -> Shape -> Evidence -> Operate.

1. Explore the current repo and confirm whether the work is extraction, package API design, playground adoption, or production adapter binding.
2. Shape the package boundary in FPF terms. Separate promise, ability, performance, and evidence.
3. Invoke relevant subagents from .claude/agents/ before broad edits:
   • react-library-boundary-reviewer
   • atlas-adapter-contract-reviewer
   • qa-evidence-gate-reviewer
   • add health-privacy-disclosure-reviewer, security-audit-boundary-reviewer, and deployment-licensing-reviewer when tiles, counts, exports, auth, package publication, renderer choice, or deployment assumptions change.
4. Operate with the smallest reversible package step.
5. Validate with focused tests first, then build, browser checks, and autoreview when edits are non-trivial.

If Claude Code subagents are unavailable because of auth, quota, model, or tool limits, do not treat a local checklist as subagent approval. Record the blocker, perform a provisional local review by the same interests, and keep the readiness claim open until real subagent review can run.

If autoreview is unavailable because of auth, quota, model, or CLI limits, record the exact command and blocker. Do not claim autoreview clean.

Public API Target

Prefer this package surface unless the repo docs have been updated:

export {
  OntologyAtlas,
  AtlasProvider,
  useAtlasController,
  useAtlasSelection,
  createSyntheticDemoAdapter,
  createHttpAtlasAdapter,
  resolveCanvasActivation,
  clamp,
  hitTestLabelTargets,
  labelFontSize,
  makeLabelHitTarget
};

export type {
  AtlasAdapter,
  AtlasManifest,
  AtlasSessionAccess,
  TileRequest,
  DensityTile,
  PointTile,
  LabelTile,
  SearchRequest,
  SearchResult,
  RecordRequest,
  RecordDetail,
  RecordsBatchRequest,
  RecordsBatchResult,
  TableRequest,
  TableResult,
  LassoRequest,
  LassoResult,
  ExportRequest,
  ExportStatusRequest,
  ExportResult,
  SelectionTarget,
  CountSource,
  Point2D,
  LabelHitTarget,
  CanvasActivation
};

Required stylesheet export:

import "@ontotwin/atlas-react/styles.css";

Minimal adoption example for a Claude Code-generated playground:

import "@ontotwin/atlas-react/styles.css";
import { OntologyAtlas, createSyntheticDemoAdapter } from "@ontotwin/atlas-react";

const adapter = createSyntheticDemoAdapter();

export default function App() {
  return <OntologyAtlas adapter={adapter} />;
}

HTTP adapter example for a job app:

import "@ontotwin/atlas-react/styles.css";
import { OntologyAtlas, createHttpAtlasAdapter } from "@ontotwin/atlas-react";

const adapter = createHttpAtlasAdapter({
  baseUrl: "/api/atlas",
  atlasVersion: "atlas_2026_05_31"
});

export function App() {
  return <OntologyAtlas adapter={adapter} />;
}

Acceptance Checks

The work is not done until current evidence proves:

• A fresh React playground installs the package and imports only public exports.
• The synthetic adapter renders without production services.
• Search resolves a demo document ID and a configured group.
• Label click updates selection.
• The table drawer opens for the active selection.
• Missing disclosure_policy_id fails closed for counts, lasso, table, and export.
• Public point tiles exclude canonical IDs, member IDs, protected metadata, raw text, embeddings, PHI, and PII.
• Public point tiles use opaque render tokens for group, label, and style values unless the tile service is authenticated internal data with recorded approval.
• Count-returning production adapters use value, source, method, disclosure_policy_id, privacy_transform, and exactness_scope.
• Production deployment has hosting topology, data residency, observability, cost owner, support owner, and legal/security/privacy/operations approvals recorded.
• The extracted package build passes, and the fresh playground build passes while importing only public package exports.
• npm test and the relevant package/playground build commands pass in the changed workspace. A root Vite demo build alone is not enough after package extraction.
• Autoreview reports no accepted/actionable findings after non-trivial edits.
• Publication metadata includes license, and external publishing waits for the user's explicit license and access-policy decision.

Claude Code Prompt Example

/ontotwin-library-adoption

Task: extract the current Vite demo into @ontotwin/atlas-react and keep this repo as examples/playground.

Use active FPF selectors A.7, A.15, E.10, E.10.D2, and F.18.
Do not change the production ontology to fit the demo.
Keep library-owned behavior separate from production-owned data jobs, privacy policy, auth, and deployment.
Before broad edits, invoke react-library-boundary-reviewer, atlas-adapter-contract-reviewer, and qa-evidence-gate-reviewer.
Return claim scope, files changed, proof run, residual gaps, and stop/replan triggers.