@binance/ai-platform (installer)

A generic, team-agnostic installer for a shared AI platform (skills, prompts, rules, knowledge base). Published as the npm package @binance/ai-platform and the Maven artifact com.binance.ai:ai-platform.

It ships no content of its own. At install/build it git-clones a content repo you specify and drops it into the consumer's .claude/. Any team can use it by pointing it at their own ai-platform content repo — nothing here is tied to one team.

TL;DR

1. Have (or create) a content repo — a git repo with knowledge/ skills/ prompts/ rules/ at its root. This is your team's AI platform content.
2. In your consuming project, add this installer (@binance/ai-platform for npm, com.binance.ai:ai-platform for Maven) and tell it your content repo URL.
3. On install/build it clones your content repo into the project's .claude/ — skills become slash commands, the KB lands at .claude/_platform-kb/, and your own .claude/ files are never overwritten.

The content repo + version are parameters (nothing is baked in). Version = a git branch: none → master (latest); X → branch X (one branch per version).

Use in a Node / npm project

1. Configure the content repo once in your package.json (committed → works for every dev + CI, no per-install env):

{
  "name": "my-project",
  "aiPlatform": {
    "repo": "https://<git-host>/<team>/ai-platform.git",  // REQUIRED
    "ref": "master"                                        // optional git branch; default "master"
  }
}

2. Add the dependency (registry that hosts @binance — set it in your .npmrc):

yarn add @binance/ai-platform

That's it. postinstall clones your content repo and installs:

| From your content repo | Into your project | |------------------------|-------------------| | skills/*.md | .claude/commands/<name>.md (slash commands) | | rules/* | .claude/rules/_platform/ | | prompts/* + skill-prompts/* | .claude/prompts/_platform/ | | knowledge/ | .claude/_platform-kb/knowledge/ (referenced via .claude/platform-paths.json) |

Overriding via env (e.g. CI pinning a version without editing files):

PLATFORM_KB_REPO=https://<git-host>/<team>/ai-platform.git PLATFORM_KB_REF=1.4 yarn install

Resolution order: env var → package.json aiPlatform block → (repo has no default).

Managed paths (.claude/_platform-kb/, _platform-manifest.json, platform-paths.json) are auto-added to your .gitignore.

Use in a Java / Maven project

The jar is a content-free "door": it carries the fetch script, and your build runs it. Bind it to the initialize phase so the content is fetched on every mvn build (incl. install).

<properties>
  <!-- version of the INSTALLER (this jar). Content version is the fetch branch below. -->
  <ai-platform.version>[0.2,)</ai-platform.version>   <!-- range = latest; LATEST keyword is dead for deps on Maven 3.x -->
</properties>

<dependencies>
  <dependency>
    <groupId>com.binance.ai</groupId>
    <artifactId>ai-platform</artifactId>
    <version>${ai-platform.version}</version>
  </dependency>
</dependencies>

<build>
  <plugins>
    <!-- 1) unpack the door (fetch-content.sh) from the jar.
            unpack-dependencies (not unpack) so it accepts the resolved range version. -->
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-dependency-plugin</artifactId>
      <version>3.6.1</version>
      <executions>
        <execution>
          <id>unpack-ai-platform-door</id>
          <phase>initialize</phase>
          <goals><goal>unpack-dependencies</goal></goals>
          <configuration>
            <includeGroupIds>com.binance.ai</includeGroupIds>
            <includeArtifactIds>ai-platform</includeArtifactIds>
            <outputDirectory>${project.build.directory}/ai-platform-door</outputDirectory>
            <!-- always re-extract; otherwise a stale marker skips it and the exec below 127s -->
            <overWriteReleases>true</overWriteReleases>
            <overWriteSnapshots>true</overWriteSnapshots>
          </configuration>
        </execution>
      </executions>
    </plugin>

    <!-- 2) run the fetch script → clones your content repo into .claude/_platform-kb/ -->
    <plugin>
      <groupId>org.codehaus.mojo</groupId>
      <artifactId>exec-maven-plugin</artifactId>
      <version>3.5.0</version>
      <executions>
        <execution>
          <id>fetch-ai-platform-kb</id>
          <phase>initialize</phase>
          <goals><goal>exec</goal></goals>
          <configuration>
            <executable>bash</executable>
            <arguments>
              <argument>${project.build.directory}/ai-platform-door/ai-platform/scripts/fetch-content.sh</argument>
              <argument>https://<git-host>/<team>/ai-platform.git</argument>  <!-- REQUIRED: your content repo -->
              <argument>master</argument>                                     <!-- version = git branch; default master -->
              <argument>${project.basedir}/.claude/_platform-kb</argument>
            </arguments>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

Gitignore the fetched content:

.claude/_platform-kb/
target/ai-platform-door/

After any mvn phase ≥ initialize, the content is at .claude/_platform-kb/{knowledge,skills,prompts,rules}. (mvn validate runs before initialize and won't fetch — use initialize or later.)

Version semantics (both channels)

• No version → master (always latest). Version X → the branch named X. Versioning is one branch per version on the content repo.
• No content repo configured → graceful no-op (npm) / clear error (Maven). The installer never silently defaults to a specific team's repo.

Why the installer is separate from the content

Access control. The installer package is freely installable, but at install it git-clones the private content repo — so only people with git access to that repo receive the content; everyone else gets a graceful no-op. The gate is the git clone. Full rationale: docs/ARCHITECTURE.md.

What's in this repo

| Path | Purpose | |------|---------| | scripts/postinstall.mjs | npm install hook — clones the content repo, installs into .claude/ | | scripts/fetch-content.sh | Maven/consumer fetch — clones the content repo (repo + branch args) | | scripts/sync-version.mjs | enforce npm == Maven version parity (publish preflight) | | pom.xml / package.json | the two artifact definitions (installer, no content) |

Publishing (maintainers)

Full runbook: docs/PUBLISHING.md. In short:

• scripts/sync-version.mjs enforces npm/Maven version parity before publish.
• The jar is content-free (ships only fetch-content.sh); npm publishes scripts/ + docs. Neither contains the KB.
• Registry / Nexus / CI are configured at deploy time (CI-injected deploy.*.url for Maven; .npmrc registry for npm) — not hardcoded here.

Install safety (how the installer behaves in a consumer)

• local-customization-wins: a command the consumer authored themselves is never overwritten.
• SHA-256 manifest (.claude/_platform-manifest.json): only files the installer wrote are updated/removed; orphans cleaned up.
• Managed paths are auto-gitignored in the consumer.
• .claude/platform-paths.json records the resolved contentRepo / ref / fetchedSha (audit trail).