# rosetta-deploy

The Phase 1B library of Rosetta knowledge for Salesforce Data 360 and the
Salesforce Well-Architected Framework (WAF). It holds context patterns,
architecture decision records (ADRs), the intents, platform facts and
terms they connect, and the source documents they rest on, as plain files
in Git, for people and Claude Code to read. It is mirrored to GitSoma
inside the Salesforce boundary.

## What is here today

- **166 context patterns** in `CP/` and **51 ADRs** in `ADR/`. Data 360
  has 20 validated patterns and 5 accepted ADRs. WAF has 146 draft
  patterns and 46 proposed ADRs, each marked "Draft — not SME-reviewed;
  advisory only."
- **The intents, platform facts and terms they connect:** 46 business
  intents in `BI/`, 84 engine functions in `EF/`, 29 platform objects in
  `PO/`, 43 semantic entities in `SE/` and 75 vocabulary terms in `VT/`.
  Pattern files link to them, and they link back.
- **Each ADR's rejected alternatives** in `anti-patterns/`, a catalog of
  the cited sources in `sources/`, and a routing index, facet pages and a
  catalog of every generated file in `indexes/`.
- Every generated file is projected from the Rosetta content snapshot
  `content-2026-10-16-v1.2.0`, and each generated folder has a
  `README.md` index.
- **86 source documents** in `docs/`, each with its right to be here
  recorded (`docs/_inventory.csv`), plus methodology, terminology and
  dependency material in the folders below.
- **Four Claude Code plugins** in this repo's plugin marketplace (see
  [Installing the plugins](#installing-the-plugins)).
  `rosetta-knowledge` answers from the library, citing a file for every
  claim. `rosetta-d360-builder` holds six draft Data 360 builder
  walkthroughs compiled from the library. `rosetta-archaeology-deploy`
  builds an engagement twin as files from a discovery dossier, and
  `engagement-codex-deploy` renders the Solution Thesis from it; both
  work inside an engagement repository.
- **The current published release is `v0.1.2`.** It distributes #41's
  binding-compatible projection from the unchanged
  `content-2026-10-16-v1.2.0` snapshot. Its annotated tag is the immutable
  library pin, and each tag's message holds its release notes.

## Folder map

| Path | Class | Holds |
|---|---|---|
| `CP/` | generated | One file per context pattern, plus an index |
| `ADR/` | generated | One file per ADR, plus an index |
| `BI/` | generated | One file per business intent, plus an index |
| `EF/` | generated | One file per engine function, plus an index |
| `PO/` | generated | One file per platform object, plus an index |
| `SE/` | generated | One file per semantic entity, plus an index |
| `VT/` | generated | One file per vocabulary term, plus an index |
| `anti-patterns/` | generated | Each ADR's rejected alternatives, one file per ADR, derived from it, plus an index |
| `sources/` | generated | The source catalog: each cited source, linked to its file in `docs/` or its public URL |
| `indexes/` | generated | The routing index, the facet pages and `catalog.json`, the catalog of every generated file |
| `release-manifest.json` | generated | The snapshot the generated files came from, and a sha256 per file |
| `docs/` | curated | Source documents, each with its origin, visibility, owner and right to be here (`docs/_inventory.csv`) |
| `methodology/` | curated | Methodology archives |
| `terminology/` | curated | Product naming and Data 360 terminology lists |
| `doc-dependencies/` | curated | The document dependency spreadsheet |
| `rosetta-generated/` | curated | Earlier Rosetta-generated material, under review |
| `.claude-plugin/marketplace.json`, `plugins/` | authored for now | The plugin marketplace and its plugins (decision trace) |
| `evals/` | authored | The question test and its runner, the install runbook, and their results |
| `decision-traces/` | authored | Decisions made in this repo |
| `skills/` | authored | Planned; Phase 1 skills arrive later (no folder yet) |
| `contributions/` | authored | How to propose a correction to a generated file |
| `customer/_template/` | authored | The layout each engagement repository fills; no engagement lives here |
| `schemas/` | authored | JSON Schemas for generated and source-document front matter |
| `rosetta.yaml` | authored | This map for tools, and the scope list for the library's skills |
| `rosetta-deploy.spec-manifest.md` | authored | The plan and the rules for this repo |
| `README.md`, `CLAUDE.md`, `MAINTAINING.md` | authored | Guides |
| `.github/` | authored | The CI workflow and its guard scripts, and the issue templates |

- **Generated** files are written by Rosetta's projection tool from one
  checksummed content snapshot. Nobody edits them by hand.
- **Curated** files are kept by the library's curators.
- **Authored** files change through reviewed pull requests.

`rosetta.yaml` holds the same map for tools: one class for every
top-level entry, including folders planned for later releases. Where
this table and `rosetta.yaml` differ, `rosetta.yaml` wins.

## Using it with Claude Code

Clone or fork the repo and open it in Claude Code. `CLAUDE.md` tells Claude
how to answer from the library: read the indexes first, cite the file and id
for every claim, and say when the library does not cover a question. Start
with `indexes/routing.md`.

To use the library without a clone, install the plugin instead (below).

## Installing the plugins

This repo is also a Claude Code plugin marketplace named
`rosetta-deploy`. Its plugin `rosetta-knowledge` answers Data 360 and
Well-Architected questions from the library: it reads the indexes first, opens at most
five files, cites the path and id for every claim, and says "not
covered by the library" when it is not. It needs no network, no API
key and no connection to Rosetta. Its `ask` skill only reads files; its
`give-feedback` skill writes one report, in your own folder, when you
ask it to (see [Reporting a problem](#reporting-a-problem)).

Installing copies `CP/`, `ADR/`, `BI/`, `EF/`, `PO/`, `SE/`, `VT/`,
`sources/`, `anti-patterns/`, `indexes/`, `docs/` and
`release-manifest.json` into the plugin, so it works on a
machine with no clone. Ask with `/rosetta-knowledge:ask`, or just ask a
Data 360 or Well-Architected question.

Its second plugin, `rosetta-d360-builder`, holds six step-by-step builder
walkthroughs for Data 360. They run on a Salesforce Data 360 MCP server's
tools, pair every create with a read-back, and never delete. Every one is
DRAFT and UNVERIFIED until a sandbox smoke passes, so run them against a
sandbox org only. See `plugins/rosetta-d360-builder/README.md`.

Two more plugins work inside an engagement repository, cut from a tag of
this one (see `customer/_template/README.md`), and write only to its
`customer/<customer>/` folder. `rosetta-archaeology-deploy` reads the
discovery dossier in `project-docs/` and the library at the repository
root, and writes the engagement twin as files: `archaeology/twin.json`,
its review notes, and draft context artifacts and decision traces in
`CP/` and `ADR/`. Its last phase lists proposed learnings you can send
back to the library; it sends nothing itself. `engagement-codex-deploy`
renders the Solution Thesis from that folder into `deliverables/`, in
four tones: audit, seller, customer and leadership. The SOW and Spec
Manifest are compiled by Rosetta. Neither plugin needs a network or a
connection to Rosetta.

**Pin to a tag, never to a branch.** A tag is a checked release. The
examples below use the published `v0.1.2`. The previous fallback is
`v0.1.1`; both carry all four plugins.
The first, `v0.1.0`, carries `rosetta-knowledge` and
`rosetta-d360-builder` only.

To test an install on a clean machine with Rosetta unreachable, one
check per plugin, follow [`evals/install-runbook.md`](evals/install-runbook.md).

### For yourself

In Claude Code:

```text
/plugin marketplace add vernonkeenan/rosetta-deploy@v0.1.2
/plugin install rosetta-knowledge@rosetta-deploy
/plugin install rosetta-d360-builder@rosetta-deploy
/plugin install rosetta-archaeology-deploy@rosetta-deploy
/plugin install engagement-codex-deploy@rosetta-deploy
```

From the GitSoma mirror, add the mirror's clone URL with the tag after
a `#`: `/plugin marketplace add <mirror clone URL>#v0.1.2`.

The repo is private, so Claude Code clones it with the git credentials
already on your machine. For GitHub, run `gh auth login` and then
`gh auth setup-git` once.

### For a team, through managed settings

An admin can register the marketplace and turn the plugin on for
everyone, pinned to a tag, in the managed settings file:

| OS | Managed settings file |
|---|---|
| macOS | `/Library/Application Support/ClaudeCode/managed-settings.json` |
| Linux and WSL | `/etc/claude-code/managed-settings.json` |
| Windows | `C:\Program Files\ClaudeCode\managed-settings.json` |

```json
{
  "extraKnownMarketplaces": {
    "rosetta-deploy": {
      "source": {
        "source": "github",
        "repo": "vernonkeenan/rosetta-deploy",
        "ref": "v0.1.2"
      }
    }
  },
  "enabledPlugins": {
    "rosetta-knowledge@rosetta-deploy": true
  }
}
```

- **From the GitSoma mirror**, use a git source instead:
  `"source": { "source": "git", "url": "<mirror clone URL>", "ref": "v0.1.2" }`.
- **To allow only this marketplace**, also set `strictKnownMarketplaces`
  to a list holding the same source. The `ref` must match exactly, so
  update both entries together.
- **To upgrade**, change `ref` to the next tag. Auto-update is off for
  marketplaces outside Anthropic's own, so nothing moves until you do.
- Each person still needs git credentials for the repo or the mirror.

### From a local clone

Set `ROSETTA_DEPLOY_ROOT` to the clone, and the plugin reads that tree
instead of its installed copy:

```bash
export ROSETTA_DEPLOY_ROOT="$HOME/src/rosetta-deploy"
```

To try a plugin straight from a clone without installing it, run
`claude --plugin-dir plugins/rosetta-knowledge`.

The plugin reaches the library through symlinks in `plugins/`. On
Windows, git needs symlinks enabled (`core.symlinks`); this is untested.
If the plugin reports that the library files are missing, set
`ROSETTA_DEPLOY_ROOT` to a clone.

Engagement work, simulations included, never goes in this repository.
Each engagement gets its own repository, cut from a tagged release of this
one, with this one as its `upstream` remote.

## How to read a file's status

Every generated file states its status in its front matter. A pattern marked
`validated` or an ADR marked `accepted` is in its live state in Rosetta.
Content still waiting for review carries the line "Draft — not SME-reviewed;
advisory only."

## Reporting a problem

Generated files are never edited here. If one is wrong, something is
missing, two files disagree, or a plugin skill broke its own rules, open
an issue from one of the four templates (wrong content, missing content,
conflicting content, skill bug), or propose a correction as
`contributions/README.md` describes. Either
way, name each file and its id, and leave out customer data. A
correction is made in Rosetta, through its review lane, and arrives in
the next release.

With the `rosetta-knowledge` plugin installed, run
`/rosetta-knowledge:give-feedback` after an answer that fell short. It
writes the report for you, with the files and ids the answer used, into
your own folder, in the template's layout. It sends nothing: you file it.

## Governance

The repo is governed by its Spec Manifest,
`rosetta-deploy.spec-manifest.md`
(`SM-RDEP-001`): ten rules, the work done, and the work planned to the Nov 6
field launch. Every change arrives by pull request. Maintainers read
`MAINTAINING.md`.