# Plugin distribution

SoMi ships as a Claude Code plugin and as a GitHub Copilot extension. Both use the same
underlying markdown files — agents, commands, skills, rules, hooks — so there is no duplication.

> **The two hosts are not feature-equivalent.** The shared markdown is portable, but two layers are
> **Claude Code capabilities that don't carry to Copilot**: the deterministic **guardrail hooks**
> (they don't fire on Copilot — no blocking of dangerous bash / secret writes / protected paths, no
> dep-install gate, no audit log) and **concurrent multi-agent orchestration** (the loops and the
> `/review-panel` / `/code-parallel` fan-outs degrade to sequential where the host can't spawn
> sub-agents). Treat the Copilot extension as the **portable subset** — same prompts and judgment,
> without the enforcement and concurrency layers. See the parity caveat in the
> [`GitHub Copilot extension`](#github-copilot-extension) section below and [`HOOKS.md`](./HOOKS.md).

---

## Claude Code plugin

### How plugin install works

Claude Code's `/plugin` command speaks to a **marketplace** (a JSON manifest at a URL or repo)
that lists one or more **plugins**. Each plugin is a directory shaped like:

```
plugin-root/
├── .claude-plugin/
│   └── plugin.json           # plugin manifest (name, version, description, ...)
├── agents/                   # subagents (optional)
├── commands/                 # slash commands (optional)
├── skills/                   # skills (optional)
├── hooks/                    # hook scripts (optional)
└── CLAUDE.md                 # project-context (optional)
```

The SoMi repo is shaped that way: it is both a plugin and its own marketplace.

### Manifests

- [`.claude-plugin/plugin.json`](../.claude-plugin/plugin.json) — plugin manifest.
- [`.claude-plugin/marketplace.json`](../.claude-plugin/marketplace.json) — marketplace manifest
  (lists this plugin so `/plugin marketplace add` resolves it).

### Installing SoMi

```text
# 1. Add SoMi as a marketplace source.
/plugin marketplace add https://github.com/skathio/somi

# 2. Install the somi plugin.
/plugin install somi@somi

# 3. Check available updates.
/plugin update
```

### Hosting your own marketplace

Fork SoMi or wrap it in your own marketplace repo:

```
your-marketplace/
└── .claude-plugin/
    └── marketplace.json
```

Where `marketplace.json` lists SoMi (or your fork):

```json
{
  "name": "skathio-claude-tools",
  "description": "Internal Claude Code plugins for skathio.",
  "owner": { "name": "skathio", "url": "https://github.com/skathio" },
  "plugins": [
    {
      "name": "somi",
      "source": "github:skathio/somi",
      "version": "0.1.0",
      "description": "Plan / code / review workflow system.",
      "tags": ["workflow", "review", "security"]
    },
    {
      "name": "skathio-conventions",
      "source": "github:skathio/skathio-conventions",
      "version": "1.0.0",
      "description": "skathio-specific Claude conventions."
    }
  ]
}
```

Teams then run:

```text
/plugin marketplace add https://github.com/skathio/your-marketplace
/plugin install somi@skathio-claude-tools
/plugin install skathio-conventions@skathio-claude-tools
```

The two plugins compose at runtime.

### Plugin lifecycle commands

```text
/plugin list                  # shows installed plugins and versions
/plugin update                # update all
/plugin update somi
/plugin pin somi 0.1.0
/plugin unpin somi
/plugin uninstall somi
```

### What a plugin install doesn't do

- It does **not** write a `CLAUDE.md` at your project root. The plugin's `CLAUDE.md` is loaded as
  context but doesn't replace your project's own.
- It does **not** create `.somi/` or any artifacts — those appear when you run the workflows
  (`/plan` creates the first `.somi/plans/<slug>/` directory).
- It does **not** modify your project's `settings.json`. SoMi hooks are wired through the plugin's
  own settings.

### Verifying a plugin install

After `/plugin install somi@...`:

- `/discover`, `/plan`, `/code`, `/review` should appear in `/` autocomplete.
- `/agents` should list the SoMi agents.
- Try `/plan list a trivial change` — Claude should produce a plan.

---

## GitHub Copilot extension

SoMi is also a GitHub Copilot extension, distributed through the same marketplace pattern as
the Claude Code plugin.

> **Parity caveat.** Copilot gets the commands, agents, skills, rules, and templates — but **not** the
> hook-enforced guardrails (dangerous-bash / secret-write / protected-path blocks, dep-install
> gating, audit log are Claude Code `hooks` and simply don't run here) and **not** concurrent
> sub-agent orchestration (the loops and the `/review-panel` / `/code-parallel` parallel fan-outs run
> sequentially when the host can't spawn sub-agents). The judgment layer is identical; the
> enforcement and concurrency layers are Claude Code-only. Don't rely on the hard stops on Copilot.

### Manifests

- [`.copilot-extension/extension.json`](../.copilot-extension/extension.json) — extension manifest.
- [`.copilot-extension/marketplace.json`](../.copilot-extension/marketplace.json) — marketplace
  manifest (lists this extension so `copilot plugin marketplace add` resolves it).

### Installing

```text
# 1. Add SoMi as a marketplace source.
copilot plugin marketplace add https://github.com/skathio/somi

# 2. Install the somi extension.
copilot plugin install somi@somi

# 3. Check for updates.
copilot plugin update
```

### Available commands

| Command                          | Agent(s) used                                                                            |
|----------------------------------|------------------------------------------------------------------------------------------|
| `@somi /discover`             | `discovery-analyst` (greenfield: research + requirements & design → `.somi/rd/<slug>/`)  |
| `@somi /plan`                 | `planner`                                                                                |
| `@somi /plan-loop`            | `planner` + `reviewer` (bounded)                                                         |
| `@somi /code`                 | `coder`                                                                                  |
| `@somi /code-loop`            | `coder` + `reviewer` (bounded)                                                           |
| `@somi /review`               | `reviewer` (+ `security-reviewer` / `architecture-reviewer` / `test-strategist` auto-invoked) |
| `@somi /ship`                 | `planner` + (per iteration) `/code-loop`                                                 |
| `@somi /ship-loop`            | `/plan-loop` + (per iteration) `/code-loop`                                              |
| `@somi /security-review`      | `security-reviewer`                                                                      |
| `@somi /architecture-review`  | `architecture-reviewer` (+ `security-reviewer` when relevant)                            |
| `@somi /test-strategy`        | `test-strategist`                                                                        |
| `@somi /refactor`             | `refactorer`                                                                             |

> Plan-level review uses `@somi /review plan <slug>` — there is no separate `/plan-review`.

### Plugin lifecycle

```text
copilot plugin list
copilot plugin update somi
copilot plugin pin somi 0.1.0
copilot plugin uninstall somi
```

### Hosting your own Copilot marketplace

The pattern mirrors the Claude Code marketplace exactly. Add a `.copilot-extension/marketplace.json`
to your org's marketplace repo:

```json
{
  "name": "skathio-copilot-tools",
  "extensions": [
    {
      "name": "somi",
      "source": "github:skathio/somi",
      "version": "0.1.0"
    }
  ]
}
```

Then: `copilot plugin marketplace add https://github.com/skathio/your-marketplace`.

---

## Building your own plugin on top

The pattern for an org-specific plugin (e.g., `skathio-conventions`):

1. New repo with the plugin shape (`.claude-plugin/plugin.json` + agents/commands/skills/hooks).
2. Compose with SoMi — your skills can link to SoMi skills, your agents can call SoMi agents.
3. List both in your marketplace.

Don't fork SoMi for org conventions; **compose** SoMi with a sibling plugin. Forks rot.
Composition survives upgrades.