### Marketplace Installation Commands

Source: https://github.com/enulus/openpackage/blob/main/specs/install/marketplace-installation.md

Examples of how to initiate marketplace installation using the `opkg install` command with different source types.

```bash
# GitHub shorthand
opkg install github:company/marketplace
```

```bash
# Full git URL
opkg install git:https://gitlab.com/company/plugins.git
```

```bash
# Local path (for development)
opkg install ./local-marketplace
```

--------------------------------

### Package Install Workflow Example

Source: https://github.com/enulus/openpackage/blob/main/specs/package-sources.md

Demonstrates the workflow for installing a package from a local path and subsequently installing it by name, showing how the source is persisted and reused.

```bash
# First install from local path
$ opkg install /path/to/my-package
# → Stores: path: /path/to/my-package in openpackage.yml

# Later, install by name - uses the path
$ opkg install my-package
# → Output: ✓ Using path source from openpackage.yml: /path/to/my-package
# → Installs from /path/to/my-package (not registry)

# To switch to registry version:
# 1. Edit openpackage.yml: remove 'path:', add 'version: ^1.0.0'
# 2. Run: opkg install my-package
```

--------------------------------

### Basic Save Workflow Example

Source: https://github.com/enulus/openpackage/blob/main/specs/save/README.md

This example demonstrates the complete cycle: installing a package, editing a file, saving the changes back to the source, and optionally re-installing to sync.

```bash
# 1. Install package
opkg install my-pkg

# 2. Edit files in workspace
vim .cursor/commands/deploy.md

# 3. Save changes back to source
opkg save my-pkg
# ✓ Updated 1 file(s) in my-pkg
#    Package: /path/to/.openpackage/packages/my-pkg
#    ├── .cursor/commands/deploy.md

# 4. Re-install to sync to other platforms (optional)
opkg install my-pkg
```

--------------------------------

### Marketplace Install Prompt

Source: https://github.com/enulus/openpackage/blob/main/specs/install/install-behavior.md

This is an example of the interactive prompt displayed when installing from a marketplace, allowing users to select plugins.

```bash
# Install from marketplace (prompts for selection)
opkg install github:anthropics/claude-code

📦 Marketplace: claude-code-plugins
   Example plugins demonstrating Claude Code plugin capabilities

3 plugins available:

❯ ◯ commit-commands
  ◯ pr-review-toolkit
  ◯ explanatory-output-style

Select plugins to install (space to select, enter to confirm):
```

--------------------------------

### Local Package Workflow Example

Source: https://github.com/enulus/openpackage/blob/main/specs/new/README.md

Outlines the typical workflow for creating and installing a local package. This includes creating the package, navigating to its directory, adding files, and then installing it to the workspace.

```bash
opkg new my-package               # Create package
cd .openpackage/packages/my-package/
# Add files (rules, commands, etc.)
opkg install my-package           # Install to workspace
# Edit package source directly, then re-install to sync changes
```

--------------------------------

### User Feedback: Global Installation

Source: https://github.com/enulus/openpackage/blob/main/specs/install/install-behavior.md

Example user feedback indicating a package is being installed to the home directory.

```text
📦 Installing to home directory: /Users/username

✓ Selected local @shared-rules@1.0.0
✓ Added files: 5
   ├── .cursor/rules/style.md
   ├── .claude/rules/testing.md
   └── ...
```

--------------------------------

### User Feedback Example

Source: https://github.com/enulus/openpackage/blob/main/specs/install/install-behavior.md

This is an example of user feedback during the installation process, indicating a package was found in global packages.

```text
✓ Found <name> in global packages
```

--------------------------------

### Flow Example with Key Transformation

Source: https://github.com/enulus/openpackage/blob/main/specs/uninstall/README.md

Illustrates a flow configuration where keys are transformed during installation, requiring the uninstaller to track the transformed keys for precise removal.

```jsonc
{
  "from": "mcp.jsonc",
  "to": ".opencode/opencode.json",
  "pipe": ["filter-comments"],
  "map": {
    "mcpServers.*": "mcp.*"  // Key transformation!
  },
  "merge": "deep"
}
```

--------------------------------

### Install Claude Plugin to Cursor

Source: https://github.com/enulus/openpackage/blob/main/specs/platforms/overview.md

Example command to install a Claude plugin to the Cursor platform. This demonstrates the cross-platform conversion process.

```bash
opkg install gh@user/claude-plugin --platforms cursor
```

--------------------------------

### Create Project Package and Install

Source: https://github.com/enulus/openpackage/blob/main/specs/new/SUMMARY.md

This demonstrates creating a project package and then running `opkg install`, which automatically installs the package and updates the workspace manifest.

```bash
# Create project package
opkg new my-pkg

# Workspace manifest updated automatically
opkg install  # Installs all deps including my-pkg
```

--------------------------------

### Multi-Platform Directory Setup

Source: https://github.com/enulus/openpackage/blob/main/specs/platforms/directory-layout.md

Example of a workspace containing independent directories for multiple platforms (Cursor, Claude, Windsurf) alongside universal and platform-specific root files.

```bash
workspace/
├── AGENTS.md        # Universal
├── CLAUDE.md        # Claude-specific
├── .cursor/
│   ├── rules/
│   └── mcp.json
├── .claude/
│   ├── agents/
│   └── skills/
└── .windsurf/
    └── rules/
```

--------------------------------

### Install a test plugin

Source: https://github.com/enulus/openpackage/blob/main/specs/claude-plugins-marketplace-creation.md

Install a test plugin from your marketplace using the `/plugin install` command to verify that the marketplace is loading correctly and plugins are accessible.

```shell
/plugin install test-plugin@marketplace-name
```

--------------------------------

### Multi-Package: Separate Subdirectories

Source: https://github.com/enulus/openpackage/blob/main/specs/platforms/directory-layout.md

Example of how different packages installing to the same platform are placed in separate subdirectories.

```text
Package A:
  rules/typescript.md → .cursor/rules/typescript.mdc

Package B:
  rules/python.md → .cursor/rules/python.mdc

Result:
  .cursor/rules/
    ├── typescript.mdc  (from A)
    └── python.mdc      (from B)
```

--------------------------------

### Installation Summary with Failures

Source: https://github.com/enulus/openpackage/blob/main/specs/install/plugin-installation.md

Illustrates how installation progress and a summary are displayed, including successful installations and failures with reasons.

```text
Installing 3 plugins...
✓ plugin-a installed successfully
✗ plugin-b failed: subdirectory not found
✓ plugin-c installed successfully

Installation Summary:
✓ Successfully installed (2):
  • plugin-a
  • plugin-c

✗ Failed to install (1):
  • plugin-b: subdirectory not found
```

--------------------------------

### Add New Content Workflow

Source: https://github.com/enulus/openpackage/blob/main/specs/add/README.md

This example demonstrates the workflow for adding new files to a package's source and then synchronizing those changes to the workspace. The 'add' command modifies the source, and 'install' updates the workspace.

```bash
opkg add ./new-files/ --to pkg   # Add to source
opkg install pkg                  # Sync to workspace
```

--------------------------------

### Install a plugin

Source: https://github.com/enulus/openpackage/blob/main/specs/claude-plugins-marketplace.md

Installs a plugin from a specified marketplace. Installs to user scope by default.

```shell
/plugin install plugin-name@marketplace-name
```

--------------------------------

### Example Enabled Plugins Configuration

Source: https://github.com/enulus/openpackage/blob/main/specs/claude-settings.md

An example of how to configure enabled plugins, specifying which plugins from which marketplaces should be active.

```json
{
  "enabledPlugins": {
    "code-formatter@team-tools": true,
    "deployment-tools@team-tools": true,
    "experimental-features@personal": false
  }
}
```

--------------------------------

### Install All Dependencies

Source: https://github.com/enulus/openpackage/blob/main/specs/new/README.md

Installs all dependencies, including shared-utils.

```bash
opkg install
```

--------------------------------

### Install Global Packages

Source: https://github.com/enulus/openpackage/blob/main/specs/new/scope-behavior.md

After manual integration, run 'opkg install' to install the globally available packages into the current workspace.

```bash
opkg install
# or
opkg install shared-utils
```

--------------------------------

### Best Practice: Document Custom Directories

Source: https://github.com/enulus/openpackage/blob/main/specs/platforms/detection.md

Provides an example of documenting the reason for using a custom root directory, such as for a monorepo setup, to maintain clarity.

```jsonc
{
  "cursor": {
    // Custom directory for monorepo setup
    "rootDir": ".cursor-workspace"
  }
}

```

--------------------------------

### Create Package with Interactive Scope Selection

Source: https://github.com/enulus/openpackage/blob/main/specs/new/README.md

Guides through creating a package interactively, prompting for scope, name, description, and keywords. This example shows the interactive prompts and the successful creation output.

```bash
$ opkg new my-tools
? Where should this package be created? › 
❯ Root (current directory) - Create openpackage.yml here - for standalone/distributable packages
  Project (workspace-scoped) - Create in .openpackage/packages/ - for project-specific packages
  Global (cross-workspace) - Create in ~/.openpackage/packages/ - shared across all workspaces on this machine

# User selects "Root"
? Package name: › my-tools
? Description: › My project tools
? Keywords (space-separated): › tools utils
? Private package? › No

✓ openpackage.yml created
  - Name: my-tools
  - Description: My project tools
  - Keywords: tools, utils

📍 Scope: Current directory (root package)
```

--------------------------------

### Install to Multiple Platforms (Mixed Strategies)

Source: https://github.com/enulus/openpackage/blob/main/specs/platforms/examples.md

Installs a plugin to multiple platforms (claude, cursor, opencode) using a mix of direct AS-IS installation and cross-platform conversion strategies.

```bash
opkg install github:user/claude-plugin --platforms claude,cursor,opencode
```

--------------------------------

### Simple Flow Configuration

Source: https://github.com/enulus/openpackage/blob/main/specs/platforms/configuration.md

Start with a basic flow configuration, specifying the source and destination patterns for files. This is useful for incremental setup.

```jsonc
{
  "flows": [
    { "from": "rules/*.md", "to": ".platform/rules/*.md" }
  ]
}
```

--------------------------------

### Install Package with Zero Configuration

Source: https://github.com/enulus/openpackage/blob/main/specs/platforms/examples.md

Install a package to automatically execute built-in flows. The CLI detects platforms, loads configurations, transforms content, and writes files to the workspace without requiring explicit setup.

```bash
# Install package - flows execute automatically
opkg install @username/cursor-rules
```

--------------------------------

### Install from Local Marketplace

Source: https://github.com/enulus/openpackage/blob/main/specs/install/install-behavior.md

Install plugins from a local directory that acts as a marketplace. This command will trigger an interactive selection prompt.

```bash
# Install from local marketplace (prompts for selection)
opkg install ./my-marketplace
```

--------------------------------

### Plugin Installation Progress

Source: https://github.com/enulus/openpackage/blob/main/specs/install/marketplace-installation.md

Observe the output during plugin installation to identify successful installations and failures.

```bash
📦 Installing plugin: code-formatter@company-tools...
✓ Successfully installed code-formatter@company-tools

📦 Installing plugin: deployment-tools@deploy-plugin...
✓ Successfully installed deployment-tools@deploy-plugin

📦 Installing plugin: security-scanner@company-tools...
✗ Failed to install security-scanner@company-tools: subdirectory not found
```

--------------------------------

### Install Plugin from Marketplace

Source: https://github.com/enulus/openpackage/blob/main/specs/install/install-behavior.md

Use this command to install plugins from a marketplace. The tool will prompt for interactive selection of available plugins.

```bash
# Install from marketplace (prompts for selection)
opkg install github:anthropics/claude-code
```

--------------------------------

### Preview Package Installation with Dry-Run

Source: https://github.com/enulus/openpackage/blob/main/specs/platforms/examples.md

Executes the 'opkg install' command with the '--dry-run' flag to preview changes without actually installing the package.

```bash
# Preview what would happen
opkg install @user/package --dry-run
```

--------------------------------

### Install Package from Registry

Source: https://github.com/enulus/openpackage/blob/main/specs/commands-overview.md

Installs a package from the registry with a specified version constraint. Supports partial installations via the `files:` option.

```bash
opkg install community-pkg@^1.0.0
```

--------------------------------

### Forcing AS-IS Installation

Source: https://github.com/enulus/openpackage/blob/main/specs/platforms/universal-converter.md

This bash command demonstrates how to force an AS-IS installation by targeting the same platform as the source package.

```bash
opkg install claude-plugin --platforms claude
```

--------------------------------

### Create Package then Install

Source: https://github.com/enulus/openpackage/blob/main/specs/new/SUMMARY.md

This snippet shows the sequence of creating a package and then installing it, which automatically updates the workspace manifest.

```bash
# Create → Add content → Install
opkg new my-pkg
# ... add files to package source ...
opkg install my-pkg
```

--------------------------------

### Install Package with Version and Registry Path

Source: https://github.com/enulus/openpackage/blob/main/specs/install/install-behavior.md

Installs a package with a specific version and registry path. The path must be an exact registry path.

```bash
opkg install <name>@<spec>/<registry-path>
```

--------------------------------

### Universal Content Install Mapping

Source: https://github.com/enulus/openpackage/blob/main/specs/package/universal-content.md

Demonstrates how universal content, identified by its registry path, is mapped to platform-specific installed paths.

```text
Registry Path | Installed Paths
--------------|-----------------
`commands/test.md` | `.cursor/commands/test.md`, `.opencode/commands/test.md`, etc.
`rules/auth.md` | `.cursor/rules/auth.mdc`, etc.
```

--------------------------------

### Install from GitLab with Tag

Source: https://github.com/enulus/openpackage/blob/main/specs/install/git-cache.md

Installs a package from a GitLab repository, specifying a version tag. The command clones the repository, resolves the commit, and caches it locally. Subsequent installs of the same commit reuse the cache.

```bash
opkg install git:https://gitlab.com/company/project.git#v1.0.0
```

--------------------------------

### Full Sandbox and Permissions Configuration Example

Source: https://github.com/enulus/openpackage/blob/main/specs/claude-settings.md

A comprehensive example demonstrating the configuration of sandbox settings including enabled state, auto-approval, excluded commands, network access for Unix sockets and local binding, alongside permission denials for specific files and paths.

```json
{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker"],
    "network": {
      "allowUnixSockets": [
        "/var/run/docker.sock"
      ],
      "allowLocalBinding": true
    }
  },
  "permissions": {
    "deny": [
      "Read(.envrc)",
      "Read(~/.aws/**)"
    ]
  }
}
```

--------------------------------

### List Installed Resources with OpenPackage

Source: https://github.com/enulus/openpackage/blob/main/README.md

Lists resources installed to the workspace or globally. Can show an overview of packages or individual files for a specified resource.

```bash
opkg list             # Lists resources installed to workspace at cwd
```

```bash
opkg list <package>   # Lists installed files for specified resource
```

--------------------------------

### Install Package from GitHub Repository

Source: https://github.com/enulus/openpackage/blob/main/specs/install/install-behavior.md

Shorthand for installing packages directly from GitHub repositories.

```bash
opkg install github:<owner>/<repo>[#ref]
```

--------------------------------

### Openpackage.index.yml After Registry Install

Source: https://github.com/enulus/openpackage/blob/main/specs/package-sources.md

Example of the `.openpackage/openpackage.index.yml` file, which is updated after installing a package from the registry. It records the resolved exact version, source path, and file mappings.

```yaml
# .openpackage/openpackage.index.yml (added/updated after install)
packages:
  community-pkg:
    version: 1.2.3  # Resolved exact (e.g., latest in range from local/remote)
    path: ~/.openpackage/registry/community-pkg/1.2.3/  # Resolved source
    files:
      rules/auth.md: [.cursor/rules/auth.md, .opencode/rules/auth.md]  # Mappings
      # ... more
```

--------------------------------

### Install Claude plugin to Claude platform (direct)

Source: https://github.com/enulus/openpackage/blob/main/specs/install/install-behavior.md

Installs a Claude plugin directly to the Claude platform when the source and target platforms match. This is the fastest installation method as files are copied without transformation.

```bash
opkg install github:user/my-claude-plugin --platforms claude
```

```text
🔌 Detected Claude Code plugin
📦 Installing plugin: my-plugin@1.0.0
✓ Installing my-plugin AS-IS for claude platform (matching format)
✓ Added files: 5
   ├── .claude/commands/review.md
   ├── .claude/commands/test.md
   └── ...
```

--------------------------------

### Example settings.json Configuration

Source: https://github.com/enulus/openpackage/blob/main/specs/claude-settings.md

This example demonstrates a typical `settings.json` file, including permission configurations for allowed and denied actions, environment variables for telemetry and metrics, and company announcements.

```json
{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test:*)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl:*)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp"
  },
  "companyAnnouncements": [
    "Welcome to Acme Corp! Review our code guidelines at docs.acme.com",
    "Reminder: Code reviews required for all PRs",
    "New security policy in effect"
  ]
}
```

--------------------------------

### Workspace Index Entry for Installed Plugins

Source: https://github.com/enulus/openpackage/blob/main/specs/install/plugin-installation.md

Example of a workspace index entry tracking an installed plugin, including its name, version, content path, and source details.

```yaml
packages:
  - name: "code-formatter@company-tools"
    version: "1.0.0"
    content: ".openpackage/opkg-content/code-formatter@company-tools"
    source:
      type: "git"
      url: "https://github.com/company/marketplace.git"
      ref: "main"
      subdirectory: "plugins/formatter"
```

--------------------------------

### Install Plugin from Local Path

Source: https://github.com/enulus/openpackage/blob/main/specs/install/install-behavior.md

Use this command to install a plugin directly from a local directory path. This is useful for development and testing.

```bash
# Install from local plugin directory
opkg install ./my-plugin
```

--------------------------------

### Set CLAUDE_ENV_FILE for Persistent Environment Setup

Source: https://github.com/enulus/openpackage/blob/main/specs/claude-settings.md

Export the path to a shell script containing your environment setup before starting Claude Code. This allows for persistent environment configuration across commands.

```bash
export CLAUDE_ENV_FILE=/path/to/env-setup.sh
claude
```

```bash
conda activate myenv
# or: source /path/to/venv/bin/activate

```

--------------------------------

### Platform Entry Configuration Example

Source: https://github.com/enulus/openpackage/blob/main/specs/platforms/configuration.md

Illustrates the configuration for a specific platform, including its ID, name, root directory, and optional fields like aliases and flows.

```jsonc
{
  "cursor": {                          // Platform ID (required, unique)
    "name": "Cursor",                  // Display name (required)
    "rootDir": ".cursor",              // Root directory (required)
    "rootFile": "CURSOR.md",           // Optional root file
    "aliases": ["cursorcli"],
    "enabled": true,                   // Optional (default: true)
    "export": [                        // Export flows (package → workspace)
      { "from": "...", "to": "..." }
    ],
    "import": [                        // Import flows (workspace → package)
      { "from": "...", "to": "..." }
    ]
  }
}
```

--------------------------------

### Install to multiple platforms (mixed strategies)

Source: https://github.com/enulus/openpackage/blob/main/specs/install/install-behavior.md

Installs a Claude plugin to multiple platforms simultaneously, potentially using a mix of direct installation for matching platforms and conversion for others. The output summarizes the total files added across all platforms.

```bash
opkg install github:user/my-claude-plugin --platforms claude,cursor,opencode
```

```text
🔌 Detected Claude Code plugin
📦 Installing plugin: my-plugin@1.0.0
✓ Installing AS-IS for claude platform (matching format)
🔄 Converting to cursor format
🔄 Converting to opencode format
✓ Added 15 files across 3 platforms
```

--------------------------------

### Install Package from Marketplace

Source: https://github.com/enulus/openpackage/blob/main/specs/commands-overview.md

Installs a package from a marketplace with interactive selection. Automatically detects and transforms plugins from git sources.

```bash
opkg install github:anthropics/claude-code
```

--------------------------------

### Use Installed Plugin Command

Source: https://github.com/enulus/openpackage/blob/main/specs/claude-plugins-marketplace.md

Execute a command provided by an installed plugin. Plugin commands are namespaced by the plugin name, e.g., '/commit-commands:commit'. This example stages changes, generates a commit message, and creates a commit.

```shell
/commit-commands:commit
```

--------------------------------

### Install from Generic Git URL with Ref and Path

Source: https://github.com/enulus/openpackage/blob/main/specs/install/git-sources.md

Use this syntax for any Git host, specifying a reference (branch, tag, commit SHA) and an optional subdirectory using the `path=` parameter in the hash fragment.

```bash
# Generic git URL with ref
opkg install https://gitlab.com/user/repo.git#main
```

```bash
# SSH git URL (with optional ref and path)
opkg install ssh://git@gitlab.com/user/repo.git#main
```

```bash
# Generic git URL with ref and subdirectory
opkg install https://gitlab.com/user/repo.git#main&path=packages/plugin-a
```

```bash
# Generic git URL with subdirectory only
opkg install https://example.com/repo.git#path=src/plugin
```

--------------------------------

### Absolute Path Prevention Examples

Source: https://github.com/enulus/openpackage/blob/main/specs/install/plugin-source-normalization.md

Absolute paths are rejected to ensure sources are relative to the marketplace root. Paths starting with '/' are blocked.

```typescript
// ❌ Blocked
"/absolute/path"
"/etc/passwd"
"/var/lib/plugin"
```

```typescript
// ✅ Allowed
"./relative/path"
"relative/path"
```

--------------------------------

### Example with Key Tracking for Merged Files

Source: https://github.com/enulus/openpackage/blob/main/specs/package/package-index-yml.md

Shows a complete `openpackage.index.yml` snippet demonstrating both simple and complex file mappings, including key tracking for merged files.

```yaml
packages:
  my-mcp-package:
    path: ~/.openpackage/packages/my-mcp-package/1.0.0/
    version: 1.0.0
    files:
      # Simple file mapping (no merge)
      rules/typescript.md:
        - .cursor/rules/typescript.md
      
      # Complex mapping with key tracking
      mcp.jsonc:
        - target: .opencode/opencode.json
          merge: deep
          keys:
            - mcp.server1
            - mcp.server2
```

--------------------------------

### Package Source for Key Transformation Example

Source: https://github.com/enulus/openpackage/blob/main/specs/uninstall/README.md

The source content of a package file ('mcp.jsonc') that undergoes key transformation when installed into a shared target file.

```json
{
  "mcpServers": {
    "server1": { "url": "http://localhost:3000" },
    "server2": { "url": "http://localhost:4000" }
  }
}
```

--------------------------------

### Console Output for Multiple Platform Installation

Source: https://github.com/enulus/openpackage/blob/main/specs/platforms/examples.md

Shows the aggregated console output for installing a plugin to multiple platforms, summarizing the strategies used for each.

```text
🔌 Detected Claude Code plugin
📦 Installing plugin: my-plugin@1.0.0
✓ Installing AS-IS for claude platform (matching format)
🔄 Converting to cursor format
🔄 Converting to opencode format
✓ Added 15 files across 3 platforms
```

--------------------------------

### Install from GitHub Shorthand

Source: https://github.com/enulus/openpackage/blob/main/specs/install/git-sources.md

Use this syntax for a quick way to install from GitHub repositories using the default branch. The optional path specifies a subdirectory.

```bash
# GitHub shorthand (uses default branch)
opkg install gh@anthropics/claude-code
```

```bash
# GitHub shorthand with subdirectory
opkg install gh@anthropics/claude-code/plugins/commit-commands
```

--------------------------------

### Set Package Homepage

Source: https://github.com/enulus/openpackage/blob/main/specs/set/README.md

Examples of setting the package homepage URL. The URL must be in a valid format, typically starting with http:// or https://.

```bash
opkg set --homepage https://example.com
```

```bash
opkg set --homepage https://github.com/user/repo
```

--------------------------------

### Add local marketplace and install plugin

Source: https://github.com/enulus/openpackage/blob/main/specs/claude-plugins-marketplace-creation.md

Use these commands to test your local marketplace before distribution. The first command adds your local marketplace, and the second installs a test plugin from it.

```shell
/plugin marketplace add ./my-local-marketplace
```

```shell
/plugin install test-plugin@my-local-marketplace
```

--------------------------------

### Create a Project Template

Source: https://github.com/enulus/openpackage/blob/main/specs/new/scope-behavior.md

Use 'opkg pack' to create a project template from a directory. This template can then be installed in new projects.

```bash
mkdir -p root/
echo "# Template README" > root/README.md
mkdir -p .cursor/rules
echo "# Template rule" > .cursor/rules/setup.md

opkg pack project-template
```

--------------------------------

### Universal Root File Example

Source: https://github.com/enulus/openpackage/blob/main/specs/platforms/detection.md

The AGENTS.md file is a universal root file, not specific to any platform. It's installed in the workspace root and typically defined in global flows.

```bash
project/
├── AGENTS.md      # Universal, not platform-specific
├── CLAUDE.md      # Claude-specific
└── .cursor/

```

```jsonc
{
  "global": {
    "flows": [
      { "from": "AGENTS.md", "to": "AGENTS.md" }
    ]
  }
}

```

--------------------------------

### OpenPackage dependency tracking

Source: https://github.com/enulus/openpackage/blob/main/specs/install/install-behavior.md

Example of how an installed package, specifically a plugin from a Git repository, is tracked in the `openpackage.yml` file. It includes the package name, Git URL, and an optional subdirectory.

```yaml
packages:
  - name: commit-commands
    git: https://github.com/anthropics/claude-code.git
    subdirectory: plugins/commit-commands  # If from subdirectory
```

--------------------------------

### Marketplace Plugin Not Found Error

Source: https://github.com/enulus/openpackage/blob/main/specs/install/plugin-installation.md

Example error message when attempting to install non-existent plugins from a marketplace using the `--plugins` flag. Lists available plugins for user guidance.

```text
Error: The following plugins were not found in marketplace 'company-tools':
  - invalid-plugin
  - typo-plugin

Available plugins: code-formatter, deployment-tools, commit-hooks
```

--------------------------------

### Error: Modifying Immutable Package

Source: https://github.com/enulus/openpackage/blob/main/specs/package-sources.md

Example of an error message when attempting to modify a package installed from an immutable source like the registry. It suggests a fix involving copying the package to a mutable directory.

```text
Error: Cannot save 'community-pkg' – from registry (immutable, v1.2.3).
Path: ~/.openpackage/registry/community-pkg/1.2.3/

Fix: Copy to ~/.openpackage/packages/, update path:, edit, then pack.
```

--------------------------------

### Plugin Installation Loop

Source: https://github.com/enulus/openpackage/blob/main/specs/install/marketplace-installation.md

Iterates through selected plugin names, finds their entries, normalizes their sources, and initiates installation based on source type (relative path or git).

```typescript
const results: Array<{ 
  name: string;
  scopedName: string;
  success: boolean;
  error?: string;
}> = [];

for (const pluginName of selectedNames) {
  // 1. Find plugin entry
  const pluginEntry = marketplace.plugins.find(p => p.name === pluginName);
  
  // 2. Normalize source
  const normalizedSource = normalizePluginSource(
    pluginEntry.source,
    pluginName
  );
  
  // 3. Install based on source type
  if (isRelativePathSource(normalizedSource)) {
    result = await installRelativePathPlugin(...);
  } else if (isGitSource(normalizedSource)) {
    result = await installGitPlugin(...);
  }
  
  // 4. Track result
  results.push({ name: pluginName, success: result.success, ... });
}
```

--------------------------------

### Add → Install Workflow

Source: https://github.com/enulus/openpackage/blob/main/specs/add/README.md

Demonstrates the typical workflow of adding new files to a package source and then installing the package to synchronize these changes to the workspace.

```bash
# 1. Add files to package source
opkg add ./docs/guide.md --to my-pkg

# 2. Install package to sync changes to workspace
opkg install my-pkg
```

--------------------------------

### Interactive Plugin Selection Prompt

Source: https://github.com/enulus/openpackage/blob/main/specs/install/git-sources.md

This is an example of the interactive prompt displayed when installing from a Claude Code plugin marketplace. It lists available plugins and allows the user to select multiple plugins using the spacebar before confirming with Enter.

```bash
📦 Marketplace: claude-code-plugins
   Example plugins demonstrating Claude Code plugin capabilities

3 plugins available:

❯ ◯ commit-commands
  ◯ pr-review-toolkit
  ◯ explanatory-output-style

Select plugins to install (space to select, enter to confirm):
```

--------------------------------

### Advanced Plugin Entry Configuration

Source: https://github.com/enulus/openpackage/blob/main/specs/claude-plugins-marketplace-creation.md

An example of a comprehensive plugin entry including optional fields like custom paths for commands, agents, hooks, and MCP servers. Note the use of `${CLAUDE_PLUGIN_ROOT}` for referencing files within the plugin's installation directory.

```json
{
  "name": "enterprise-tools",
  "source": {
    "source": "github",
    "repo": "company/enterprise-plugin"
  },
  "description": "Enterprise workflow automation tools",
  "version": "2.1.0",
  "author": {
    "name": "Enterprise Team",
    "email": "enterprise@example.com"
  },
  "homepage": "https://docs.example.com/plugins/enterprise-tools",
  "repository": "https://github.com/company/enterprise-plugin",
  "license": "MIT",
  "keywords": ["enterprise", "workflow", "automation"],
  "category": "productivity",
  "commands": [
    "./commands/core/",
    "./commands/enterprise/",
    "./commands/experimental/preview.md"
  ],
  "agents": ["./agents/security-reviewer.md", "./agents/compliance-checker.md"],
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
          }
        ]
      }
    ]
  },
  "mcpServers": {
    "enterprise-db": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
    }
  },
  "strict": false
}
```

--------------------------------

### Illustrative Example of Wave-Based BFS Resolution

Source: https://github.com/enulus/openpackage/blob/main/plans/wave-resolver.md

This example visually demonstrates the step-by-step process of dependency resolution using waves. It shows how packages are fetched, their dependencies discovered, and the queue is updated across multiple waves until resolution is complete.

```text
Start: read root openpackage.yml
  └─ Queue: [ react@^18, typescript@^5 ]

Wave 1 — fetch packuments for queued names:
  GET registry/react        → resolves to react@18.3.1
  GET registry/typescript   → resolves to typescript@5.7.3

  react@18.3.1 declares:
    dependencies: { "loose-envify": "^1.1.0" }

  typescript@5.7.3 declares:
    dependencies: {}    ← leaf, nothing to queue

  └─ Queue: [ loose-envify@^1.1.0 ]

Wave 2 — fetch packuments for newly discovered names:
  GET registry/loose-envify → resolves to loose-envify@1.4.0

  loose-envify@1.4.0 declares:
    dependencies: { "js-tokens": "^3.0.0 || ^4.0.0" }

  └─ Queue: [ js-tokens@^3.0.0||^4.0.0 ]

Wave 3:
  GET registry/js-tokens    → resolves to js-tokens@4.0.0

  js-tokens@4.0.0 declares:
    dependencies: {}    ← leaf

  └─ Queue empty → resolution complete
```

--------------------------------

### Integration Tests for Plugin Installation

Source: https://github.com/enulus/openpackage/blob/main/specs/platforms/universal-converter.md

These integration tests cover the installation of plugins across different platforms, including AS-IS installation, conversion scenarios, multi-platform installations, and Git-based installations.

```typescript
// tests/install-claude-plugin.test.ts
- Install Claude plugin to claude platform (AS-IS)
- Install Claude plugin to cursor platform (convert)
- Multi-platform installation
- Git-based plugin installation
```

--------------------------------

### Install using Legacy Syntax with Subdirectory

Source: https://github.com/enulus/openpackage/blob/main/specs/install/git-sources.md

Demonstrates the legacy syntax for specifying a subdirectory, which still works for backward compatibility. The `subdirectory=` parameter is supported alongside `path=`.

```bash
# Legacy with subdirectory (both path= and subdirectory= work)
opkg install github:user/repo#main&subdirectory=plugins/x  # Still works
opkg install gh@user/repo                                   # Recommended
```

--------------------------------

### Determine Overall Installation Success

Source: https://github.com/enulus/openpackage/blob/main/specs/install/marketplace-installation.md

Defines the success criteria for the overall marketplace installation. The installation is considered successful if at least one plugin installs without errors.

```typescript
return {
  success: results.some(r => r.success),
  error: results.every(r => !r.success)
    ? 'Failed to install any plugins from marketplace'
    : undefined
};
```

--------------------------------

### Step 2: Create Platform Directory

Source: https://github.com/enulus/openpackage/blob/main/specs/platforms/configuration.md

Create the directory specified by the 'rootDir' field for the custom platform.

```bash
mkdir .myplatform
```

--------------------------------

### Platform Configuration File Example

Source: https://github.com/enulus/openpackage/blob/main/specs/platforms/configuration.md

Defines the structure of the `platforms.jsonc` file, including global and platform-specific settings like export and import flows.

```jsonc
// platforms.jsonc
{
  "$schema": "./node_modules/opkg-cli/schemas/platforms-v1.json",
  
  "global": {
    "export": [ /* universal export flows */ ],
    "import": [ /* universal import flows */ ]
  },
  
  "cursor": {
    "name": "Cursor",
    "rootDir": ".cursor",
    "export": [ /* package → workspace flows */ ],
    "import": [ /* workspace → package flows */ ]
  }
}
```

--------------------------------

### Install Specific Package by Name

Source: https://github.com/enulus/openpackage/blob/main/specs/install/install-behavior.md

Installs a package by its name. If declared in `openpackage.yml`, it ensures the latest version satisfying the range is installed. If not declared, it performs a fresh install and adds it to `openpackage.yml`.

```bash
opkg install <name>
```

--------------------------------

### Local Publishing Output Example

Source: https://github.com/enulus/openpackage/blob/main/specs/publish/README.md

Example output when publishing a package to the local registry, detailing package name, version, source, and destination registry path.

```text
✓ Found my-package in workspace packages
✓ Published my-package@1.2.0
✓ Description: A helpful utility package
✓ Source: ~/.openpackage/packages/my-package
✓ Registry: ~/.openpackage/registry/my-package/1.2.0
✓ Files: 25
```

--------------------------------

### Validate and Test Platform Installation

Source: https://github.com/enulus/openpackage/blob/main/specs/platforms/configuration.md

Use the 'opkg' command-line tool to validate platform configurations and perform a dry-run installation to test changes without applying them.

```bash
# Validate configuration
opkg validate platforms

# Test with dry-run
opkg install @user/some-package --dry-run
```

--------------------------------

### Console Output for Direct Installation

Source: https://github.com/enulus/openpackage/blob/main/specs/platforms/examples.md

Shows the console output when a plugin is installed directly to a matching platform, indicating an AS-IS installation.

```text
🔌 Detected Claude Code plugin
📦 Installing plugin: my-plugin@1.0.0
✓ Installing my-plugin AS-IS for claude platform (matching format)
✓ Added files: 5
   ├── .claude/commands/review.md
   ├── .claude/commands/test.md
   └── ...
```

--------------------------------

### Create directory structure for a plugin marketplace

Source: https://github.com/enulus/openpackage/blob/main/specs/claude-plugins-marketplace-creation.md

Sets up the necessary directories for a local plugin marketplace and its plugins. Ensure these directories are created before proceeding with plugin development.

```bash
mkdir -p my-marketplace/.claude-plugin
mkdir -p my-marketplace/plugins/review-plugin/.claude-plugin
mkdir -p my-marketplace/plugins/review-plugin/commands
```

--------------------------------

### Error: Package Not Installed

Source: https://github.com/enulus/openpackage/blob/main/specs/save/README.md

Attempting to save changes for a package that has not been installed in the current workspace will result in an error, prompting you to install it first.

```bash
opkg save unknown-pkg
# ❌ Package 'unknown-pkg' is not installed in this workspace.
#    Run 'opkg install unknown-pkg' to install it first.
```

--------------------------------

### Example Plugin Configuration Result

Source: https://github.com/enulus/openpackage/blob/main/specs/platforms/examples.md

Illustrates the resulting structure when composing plugins from multiple packages, showing how package configurations are organized.

```json
{
  "packages": {
    "@user/plugin-a": { /* plugin A config */ },
    "@user/plugin-b": { /* plugin B config */ },
    "@user/plugin-c": { /* plugin C config */ }
  }
}
```

--------------------------------

### Run Install Tests Only

Source: https://github.com/enulus/openpackage/blob/main/packages/core/src/core/install/README.md

Execute only the integration tests specifically for the install flows. This is useful for focused testing after changes to the install module.

```bash
npm run test:install
```

--------------------------------

### Install from GitHub Web URL

Source: https://github.com/enulus/openpackage/blob/main/specs/install/git-sources.md

Install directly using GitHub URLs copied from a browser. Supports repository URLs, tree URLs with branches/tags, and tree URLs with subdirectories.

```bash
# GitHub web URL (copy from browser)
opkg install https://github.com/anthropics/claude-code
```

```bash
# GitHub web URL with branch
opkg install https://github.com/anthropics/claude-code/tree/main
```

```bash
# GitHub web URL with branch and subdirectory
opkg install https://github.com/anthropics/claude-code/tree/v1.0.0/plugins/commit-commands
```

--------------------------------

### Standard Universal Package Installation (Bash)

Source: https://github.com/enulus/openpackage/blob/main/specs/platforms/universal-converter.md

Installs a standard universal package to multiple platforms using the existing flow-based installation mechanism.

```bash
# Standard universal package installation
opkg install @user/package --platforms claude cursor
```

--------------------------------

### Temperature Setting Examples

Source: https://github.com/enulus/openpackage/blob/main/specs/agents-frontmatter.md

Illustrates how to set the `temperature` field to control LLM response creativity, with examples for deterministic analysis, balanced development, and creative exploration.

```yaml
temperature: 0.0    # Deterministic code analysis
```

```yaml
temperature: 0.3    # Balanced development
```

```yaml
temperature: 0.8    # Creative exploration
```

--------------------------------

### Migrate from opkg init to opkg new

Source: https://github.com/enulus/openpackage/blob/main/specs/new/SUMMARY.md

Compares the old `opkg init` commands with their new equivalents using `opkg new`. Use `opkg new --scope root` for root packages and `opkg new <package-name>` for global packages.

```bash
# Old way
opkg init              # Workspace + root package
opkg init my-package   # Project package

# New way
opkg new --scope root  # Just root package
opkg new my-package    # Defaults to global (use --scope project for workspace)
```

--------------------------------

### Install Claude Plugin to Multiple Platforms (Bash)

Source: https://github.com/enulus/openpackage/blob/main/specs/platforms/universal-converter.md

Installs a Claude plugin to multiple platforms, efficiently handling direct installation for some and conversion for others.

```bash
# Install to both Claude and Cursor
opkg install path/to/claude-plugin --platforms claude cursor
```

--------------------------------

### Configure Root File

Source: https://github.com/enulus/openpackage/blob/main/specs/platforms/detection.md

Example configuration for a platform specifying its root file.

```jsonc
{
  "claude": {
    "rootDir": ".claude",
    "rootFile": "CLAUDE.md"  // Checked for existence
  }
}
```

--------------------------------

### List Command Output Example

Source: https://github.com/enulus/openpackage/blob/main/specs/list/README.md

Shows the typical output format for the `opkg list` command, indicating package status (synced, modified, missing) and their paths.

```bash
✅ my-rules@1.0.0  synced    ./.openpackage/packages/my-rules/
⚠️ shared@1.2.3   modified  ~/.openpackage/packages/shared/
❌ community@1.0.0 missing   ~/.openpackage/registry/community/1.0.0/
```

--------------------------------

### Install Claude Plugin to Claude Platform (Bash)

Source: https://github.com/enulus/openpackage/blob/main/specs/platforms/universal-converter.md

Installs a Claude plugin to the Claude platform. This performs a direct installation, copying files without transformation.

```bash
# Install Claude plugin to Claude platform
opkg install path/to/claude-plugin --platforms claude
```

--------------------------------

### Traditional Static Subdirectory Mapping (Old Approach)

Source: https://github.com/enulus/openpackage/blob/main/specs/platforms/directory-layout.md

Demonstrates the outdated method of mapping universal directories to platform directories using static subdirectory configurations.

```jsonc
// ❌ Old: static subdirs mapping
{
  "cursor": {
    "subdirs": [
      {
        "universalDir": "rules",
        "platformDir": "rules",
        "exts": [".mdc", ".md"]
      }
    ]
  }
}
```

--------------------------------

### Registry-Path Install

Source: https://github.com/enulus/openpackage/blob/main/specs/install/install-behavior.md

Installs a specific file path from a registry dependency. For existing dependencies with a 'files' list, it re-installs the stored subset or prompts to switch to a full install. For dependencies without 'files', path-based installs are rejected unless 'files' is manually added to openpackage.yml.

```bash
opkg install <name>/<registry-path>
```

```bash
opkg install <name>/<registry-path>@<spec>
```

--------------------------------

### Conditional Installation Based on Target Directory

Source: https://github.com/enulus/openpackage/blob/main/specs/platforms/flow-reference.md

Installs flows conditionally based on the target directory. Installs to `.mcp.json` when not in the home directory (workspace) and to `.claude.json` when in the home directory (global).

```jsonc
{
  "from": ["mcp.jsonc", "mcp.json"],
  "to": ".mcp.json",
  "when": {
    "$ne": ["$$targetRoot", "~/"]
  },
  "merge": "deep"
},
{
  "from": ["mcp.jsonc", "mcp.json"],
  "to": ".claude.json",
  "when": {
    "$eq": ["$$targetRoot", "~/"]
  },
  "merge": "deep"
}
```

--------------------------------

### Add Context7 MCP server using CLI

Source: https://github.com/enulus/openpackage/blob/main/specs/codex-mcp.md

Example of adding the Context7 MCP server, which provides access to developer documentation, using the CLI.

```bash
codex mcp add context7 -- npx -y @upstash/context7-mcp
```

--------------------------------

### Import Flow Example

Source: https://github.com/enulus/openpackage/blob/main/specs/platforms/flows.md

Demonstrates an import flow configuration for mapping Markdown files from the workspace to the package.

```jsonc
{
  "cursor": {
    "import": [
      {
        "from": ".cursor/commands/**/*.md",
        "to": "commands/**/*.md"
      },
      {
        "from": ".cursor/rules/**/*.mdc",
        "to": "rules/**/*.md"
      }
    ]
  }
}
```

--------------------------------

### Bash Command for Dry Run Installation

Source: https://github.com/enulus/openpackage/blob/main/specs/platforms/map-pipeline.md

Installs a package in dry-run mode, allowing you to preview changes without actually modifying the system. Useful for testing package installations.

```bash
# Preview transformations
opkg install @user/package --dry-run
```

--------------------------------

### Global Flows Configuration Example

Source: https://github.com/enulus/openpackage/blob/main/specs/platforms/configuration.md

Shows how to define global flows that apply universally across all platforms for tasks like documentation or configuration file synchronization.

```jsonc
{
  "global": {
    "flows": [
      { "from": "AGENTS.md", "to": "AGENTS.md" },
      { "from": "README.md", "to": "README.md" }
    ]
  }
}
```

--------------------------------

### Legacy: Install plugin from dedicated repo

Source: https://github.com/enulus/openpackage/blob/main/specs/install/install-behavior.md

A legacy command to install an individual plugin directly from its dedicated Git repository. This is a simpler form of installation when the repository contains only the plugin.

```bash
opkg install github:user/my-claude-plugin
```

--------------------------------

### Create a New OpenPackage Package

Source: https://github.com/enulus/openpackage/blob/main/README.md

Use this command to initialize a new package. Specify the desired package name.

```bash
opkg new <package>
```

--------------------------------

### Install OpenPackage CLI

Source: https://github.com/enulus/openpackage/blob/main/README.md

Installs the OpenPackage CLI globally using npm.

```bash
npm install -g opkg
```

--------------------------------

### Workspace vs Package Paths Example

Source: https://github.com/enulus/openpackage/blob/main/specs/platforms/directory-layout.md

Contrasts the universal package path structure with platform-specific workspace path structures.

```tree
Package Paths (Universal):
@user/package/
├── rules/           # Standard name
├── agents/          # Standard name
└── mcp.jsonc        # Standard name

Workspace Paths (Platform-Specific):
workspace/
├── .cursor/
│   ├── rules/       # Cursor convention
│   └── mcp.json     # Cursor format
└── .claude/
    ├── agents/      # Claude convention
    └── config.json  # Claude format
```

--------------------------------

### Install Package from Custom Path

Source: https://github.com/enulus/openpackage/blob/main/specs/new/README.md

Install packages located in custom directories using the `--path` flag with `opkg install`. This treats custom path packages similarly to root-scoped packages.

```bash
opkg install --path ./custom-location/my-package
# or
opkg install /opt/packages/my-package
```

--------------------------------

### Global Installation Command

Source: https://github.com/enulus/openpackage/blob/main/specs/platforms/flow-reference.md

Installs a package globally, resulting in the configuration being written to `.claude.json`.

```bash
opkg install --global claude-mcp-plugin
```