Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 10 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,17 +89,19 @@ You run both prompts inside your own Claude Code, against your own Qdrant. Nothi

## Publishing an Experience

A published experience is four files in a UUID-named directory (schema v3, 2026-04-27):
A published experience is its **own GitHub repo** (one repo per pack), containing four files:

```
experiences/<uuid>/
exp-<slug>/
├── meta.yaml # facts only: id, outcome label, duration, category tokens, license
├── trajectory.anonymized.yaml # raw ordered timeline of N steps, anonymized
├── README.md # human-readable face for the marketplace
├── README.md # human-readable face for the catalog
└── SKILL.md # Claude entry point — read first when skill is invoked
```

`meta.yaml` shape (abridged from seed `d49e0997`):
Each pack has its own repo so authors own their content (issues, license, versioning), and the engine repo stays focused on the runtime. See [`docs/publishing-a-pack.md`](docs/publishing-a-pack.md) for the author guide.

`meta.yaml` shape (abridged from the seed pack [`exp-inbound-acquisition-with-free-pilot`](https://github.com/anthroos/exp-inbound-acquisition-with-free-pilot)):

```yaml
pack:
Expand Down Expand Up @@ -137,7 +139,8 @@ Drop the pack into `~/.claude/skills/openexp:<author>:<slug>/` (rename the direc

```bash
# Install the seed pack as a skill
cp -r ~/openexp/experiences/d49e0997 \
git clone https://github.com/anthroos/exp-inbound-acquisition-with-free-pilot.git
ln -s "$PWD/exp-inbound-acquisition-with-free-pilot" \
~/.claude/skills/openexp:ivan-pasichnyk:inbound-acquisition-with-free-pilot
```

Expand All @@ -149,7 +152,7 @@ Two layers of identity:

See `docs/skill-architecture.md` for the full naming convention, install flow, and design rationale.

The `experiences/` directory in this repo is the seed of an eventual marketplace. The publication format works; seeds will accumulate. A directory of installable experiences is the eventual surface, not a built product today.
This engine repo is the runtime — it does not bundle packs. Each published pack lives in its own repo (see the [seed pack](https://github.com/anthroos/exp-inbound-acquisition-with-free-pilot) as the reference shape). A web catalog at `openexp.ai` aggregates published packs; an automated registry index is on the roadmap. A directory of installable experiences is the eventual surface, not a built product today.

## MCP Tools

Expand Down Expand Up @@ -221,7 +224,7 @@ Environment variables (`.env`):

## Status

**Pilot. Architecture freeze landed 2026-04-26.** First experience seed published: `experiences/d49e0997/` — a 57-day inbound acquisition that closed at grade 1.0 (author's own assessment), anonymized to category tokens.
**Pilot. Architecture freeze landed 2026-04-26.** First experience seed published as a standalone repo: [`exp-inbound-acquisition-with-free-pilot`](https://github.com/anthroos/exp-inbound-acquisition-with-free-pilot) — a 57-day inbound acquisition that closed at grade 1.0 (author's own assessment), anonymized to category tokens.

Honest about what isn't done:
- The marketplace UI is just a directory in this repo. No web surface yet.
Expand Down
80 changes: 80 additions & 0 deletions docs/publishing-a-pack.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
# Publishing an OpenExp Pack

> Each pack is its own GitHub repo. This guide is for authors who want to publish.

## TL;DR

```
github.com/<your-handle>/exp-<slug>/
├── meta.yaml # facts only — id, outcome, duration, category tokens
├── trajectory.anonymized.yaml # raw ordered timeline, anonymized
├── README.md # human-readable face for the catalog
└── SKILL.md # Claude entry point
```

That's the whole shape. Reference: [`anthroos/exp-inbound-acquisition-with-free-pilot`](https://github.com/anthroos/exp-inbound-acquisition-with-free-pilot).

## Why one repo per pack

The OpenExp engine (`anthroos/openexp`) is the **runtime**. It ships zero packs. Packs live in their own repos so:

1. **Authors own their content.** Issues, license, versioning, attribution — all on the author's repo, not negotiated through the engine.
2. **Lifecycles are independent.** A bug fix to a pack doesn't ship an engine release. An engine refactor doesn't churn pack repos.
3. **Discovery is by `exp-*` repo naming + `openexp.ai` catalog.** A future automated registry index will scan `exp-*` repos under known orgs and aggregate their `meta.yaml` summaries.

## Steps

### 1. Run the publishing pipeline

Inside your own Claude Code session, against your own Qdrant collection. Two prompts:

1. **`prompts/anonymize.md`** — replaces counterparty identity with category tokens (e.g. `<counterparty_cto>`, `<regulated_industry>`). Author identity stays public — it signs the pack.
2. **`prompts/extract_experience.md`** — produces `meta.yaml` (facts only) from the anonymized trajectory plus the terminal outcome label.

Output: four files matching the shape above.

### 2. Create the repo

Repo name: `exp-<slug>` where `<slug>` is the same slug that appears in the install skill name (`openexp:<author>:<slug>`). Public, MIT (or whatever license you declare in `meta.yaml`).

Suggested topics: `openexp`, `openexp-pack`, `experience-pack`, plus domain-specific tags (e.g. `b2b-sales`, `mlops`, `incident-response`).

Suggested description: one sentence — outcome label, duration, category. *"Inbound B2B acquisition trajectory — 57 days, closed_won. An OpenExp experience pack."*

Homepage: `https://openexp.ai/`.

### 3. Push the four files

```bash
git init -b main
git add meta.yaml trajectory.anonymized.yaml README.md SKILL.md
git commit -m "Initial commit — pack format v3"
git remote add origin git@github.com:<your-handle>/exp-<slug>.git
git push -u origin main
```

### 4. Announce

Open an issue on `anthroos/openexp` titled `pack: <your-handle>/<slug>` with a link. The catalog at `openexp.ai/use` is hand-maintained today; the issue is the request to add yours.

## Schema

See `README.md` (the engine repo's, you're reading it from there) section "Publishing an Experience" for the `meta.yaml` shape and the rationale behind shipping raw (no `applies_when`, no summary, no grade reason).

## Anonymization

The hard rule: **never name a real counterparty or platform.** Replace with category tokens:

- People: `<counterparty_cto>`, `<counterparty_pm>`, `<own_cto>`, `<founder>`
- Companies: by category, never by name — `<regulated_industry>`, `<foreign_corp_entity>`
- Tools/platforms: `<e_signing_platform_local>`, `<cloud_provider>`, `<crm_tool>`
- Money: `<local_currency>`, `<central_bank_rate>`
- Geography: `<local_jurisdiction>`, `<host_country>`

A reader with deep domain knowledge may still triangulate identity from the trajectory shape. That's an open problem; the `prompts/anonymize.md` reverse-identification rule (industry / role / geography too narrow → generalize) is the current best-effort defence.

Author identity is public on purpose — like authorship on a research paper. Counterparty identity stays anonymized.

## License

Pack content is under whatever license you declare in `meta.yaml` (default: MIT). Engine code is MIT.
16 changes: 10 additions & 6 deletions docs/roadmap.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,9 +49,10 @@ Legend:

| Capability | Status | Today |
|---|---|---|
| Public catalog | 🟡 | The catalog **is** the GitHub repo (`anthroos/openexp/experiences/`). Site `openexp.ai/use` lists currently published packs |
| Browsable filter UI ("show me sales packs that closed in <30 days") | ❌ | Today: read the file list, open `meta.yaml` to inspect tokens |
| Install one pack | ✅ | `cp -r openexp/experiences/<uuid> ~/.claude/skills/openexp:<author>:<slug>/` — auto-discovered by Claude Code |
| Public catalog | 🟡 | Each pack is its own GitHub repo named `exp-<slug>`. Site `openexp.ai/use` lists currently published packs. Reference seed: [`anthroos/exp-inbound-acquisition-with-free-pilot`](https://github.com/anthroos/exp-inbound-acquisition-with-free-pilot) |
| Browsable filter UI ("show me sales packs that closed in <30 days") | ❌ | Today: read the catalog list, open each pack's `meta.yaml` to inspect tokens |
| Automated catalog index (registry of all `exp-*` repos with `meta.yaml` summaries) | ❌ | Today: catalog is a hand-maintained list on `openexp.ai`. Future: a YAML index that `openexp-use` can read |
| Install one pack | ✅ | `git clone <pack-repo> && ln -s "$PWD/<pack-repo>" ~/.claude/skills/openexp:<author>:<slug>` — auto-discovered by Claude Code |
| Install the `openexp-use` skill that knows how to apply any pack | ✅ | `git clone anthroos/claude-skills` + symlink. One-time, applies to all packs |
| Search "is there a pack relevant to my situation?" | 🟡 | The `openexp-use` skill does this — discovers all installed packs and matches against the user's situation. Across-machines / public-marketplace search = ❌ |

Expand Down Expand Up @@ -128,11 +129,14 @@ If you want to see the project work right now, this is the path:

1. **Install:**
```
# One-time: the universal applier
git clone https://github.com/anthroos/claude-skills.git
ln -s ~/claude-skills/skills/core/openexp-use ~/.claude/skills/openexp-use
git clone https://github.com/anthroos/openexp.git
cp -r openexp/experiences/d49e0997 \
~/.claude/skills/openexp:ivan-pasichnyk:inbound-acquisition-with-free-pilot/

# Per pack: the pack itself
git clone https://github.com/anthroos/exp-inbound-acquisition-with-free-pilot.git
ln -s "$PWD/exp-inbound-acquisition-with-free-pilot" \
~/.claude/skills/openexp:ivan-pasichnyk:inbound-acquisition-with-free-pilot
```
2. **Restart Claude Code** — both the pack and the `openexp-use` skill auto-discover.
3. **Describe a situation** in your own words. The `openexp-use` skill discovers installed packs, reads each `meta.yaml` + `trajectory.anonymized.yaml`, judges fit, and replies with a cited `relative_day` from the matching trajectory.
Expand Down
28 changes: 13 additions & 15 deletions docs/skill-architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,38 +41,36 @@ openexp:<author>:<slug>/

**Why no `experience.yaml`?** Earlier schemas (v2) shipped a wrapper artifact with `applies_when`, `searchable_summary`, and `grade_reason`. Those fields baked the publisher's read of the timeline into the pack — one Claude's interpretation, frozen at publish time. Schema v3 (2026-04-27) drops that wrapper and ships **raw**: `meta.yaml` carries facts only (outcome label, category tokens, structural counts), and the reader's Claude derives `applies_when` on the fly against the reader's actual situation. Different readers, different contexts, different inferences from the same trajectory.

Inside the canonical OpenExp repo, packs live at `experiences/<uuid>/`. The UUID-only directory is the **storage** form. The skill-namespaced directory is the **install** form.
Each published pack is its own GitHub repo named `exp-<slug>` (e.g. [`exp-inbound-acquisition-with-free-pilot`](https://github.com/anthroos/exp-inbound-acquisition-with-free-pilot)). The repo is the **storage** form. The `~/.claude/skills/openexp:<author>:<slug>/` directory on the user's machine is the **install** form.

### Storage vs install

| Layer | Path | Purpose |
|-------|------|---------|
| **Storage** | `experiences/<uuid>/` (UUID-only, in repo) | Canonical artifact, version-controlled, anonymized |
| **Install** | `~/.claude/skills/openexp:<author>:<slug>/` | What a user copies into their Claude Code installation |
| **Storage** | `github.com/<owner>/exp-<slug>` (one repo per pack) | Canonical artifact, version-controlled, anonymized; carries its own `meta.yaml` UUID |
| **Install** | `~/.claude/skills/openexp:<author>:<slug>/` | What a user symlinks into their Claude Code installation |

Reasons for the split:
- UUID is stable and collision-free; it's the canonical ID across all systems.
- Each author owns their pack's lifecycle — issues, license, versioning — without coordinating with the engine repo.
- UUID inside `meta.yaml` is stable and collision-free; it's the canonical ID across all systems even if the slug changes.
- Skill-namespaced name is presentation — what users see in their skill list.
- Renaming the slug never breaks the canonical reference.
- The engine repo (`anthroos/openexp`) stays focused on the runtime and ships zero packs.

## Install flow

A user installs a published experience pack by copying the directory into their Claude Code skill directory under the skill-namespaced name:
A user installs a published experience pack by cloning its repo and symlinking it into their Claude Code skill directory under the skill-namespaced name:

```bash
# Example: Ivan publishes to a public mirror, user installs.
cd ~/.claude/skills/
git clone https://github.com/anthroos/openexp-experience-ivan-acquisition \
openexp:ivan-pasichnyk:inbound-acquisition-with-free-pilot
```

Or, if the canonical pack lives in this repo and the user wants the seed:
# Clone the pack repo
git clone https://github.com/anthroos/exp-inbound-acquisition-with-free-pilot.git

```bash
cp -r ~/openexp/experiences/d49e0997 \
# Symlink under the skill-namespaced name
ln -s "$PWD/exp-inbound-acquisition-with-free-pilot" \
~/.claude/skills/openexp:ivan-pasichnyk:inbound-acquisition-with-free-pilot
```

(`cp -r` works too if the user wants a copy detached from upstream updates.)

Claude Code auto-discovers the skill on next session start. No registration step.

## Invocation flow
Expand Down
35 changes: 0 additions & 35 deletions experiences/d49e0997/README.md

This file was deleted.

Loading
Loading