# ruflo-plugin-creator

Scaffold, validate, and publish new Claude Code plugins with proper structure, MCP tool wiring, AND the canonical plugin contract (ADR + smoke + Compatibility + namespace coordination).

## Install

```
/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-plugin-creator@ruflo
```

## Features

- **Scaffold plugins**: Generate complete plugin directory structure in seconds, including the canonical contract (ADR-0001, scripts/smoke.sh, README contract sections)
- **Validate format**: Check plugin.json, SKILL.md frontmatter, and file references
- **MCP tool wiring**: Auto-discover and wire ruflo MCP tools into skills, with **drift warnings** for known-broken tool references (`embeddings_embed`, namespace passed to `agentdb_hierarchical-*` / `agentdb_pattern-*`)
- **Marketplace integration**: Update marketplace.json for distribution

## Commands

- `/create-plugin` -- Interactively scaffold a new Claude Code plugin

## Skills

- `create-plugin` -- Generate plugin structure with skills, commands, agents, ADR-0001, smoke test, and contract sections
- `validate-plugin` -- Validate plugin format and catch issues before publishing

## Compatibility

- **CLI:** pinned to `@claude-flow/cli` v3.6 major+minor.
- **Verification:** `bash plugins/ruflo-plugin-creator/scripts/smoke.sh` is the contract.

## Canonical plugin contract (what gets scaffolded)

Every plugin scaffolded by this plugin inherits the same shape every other plugin in the ruflo family adopted via its own ADR-0001:

```
plugins/<name>/
├── .claude-plugin/plugin.json     # version, keywords, mcp keyword
├── skills/<skill>/SKILL.md         # name + description + allowed-tools (no wildcards)
├── commands/<command>.md           # name + description + dispatch logic
├── agents/<agent>.md               # name + description + model
├── docs/adrs/0001-<name>-contract.md   # ADR (Proposed) — pinning, namespace, smoke scope
├── scripts/smoke.sh                # Structural contract, ≥8 checks
└── README.md                       # Compatibility + Namespace coordination + Verification + ADR
```

## MCP-tool drift to avoid

Lessons learned from sibling-ADR fixes — the scaffolder warns about these:

| Bug | Real tool / pattern |
|-----|---------------------|
| `embeddings_embed` referenced as a tool | Use `embeddings_generate` (the `_embed` name does not exist) |
| `namespace` arg passed to `agentdb_hierarchical-*` | Use `tier` (working/episodic/semantic), or use `memory_*` for namespaced reads/writes |
| `namespace` arg passed to `agentdb_pattern-*` | Don't pass it — ReasoningBank routes; fallback writes to `pattern` reserved |
| `pattern` and `patterns` confused | They are **different** reserved namespaces |
| Hard-coded "19 AgentDB controllers" | Defer to `agentdb_controllers` runtime; real count varies (~15 MCP tools, 29 controller names) |

## Verification

```bash
bash plugins/ruflo-plugin-creator/scripts/smoke.sh
# Expected: "10 passed, 0 failed"
```

## Architecture Decisions

- [`ADR-0001` — ruflo-plugin-creator plugin contract (scaffold-the-canonical-contract, MCP-drift warnings, smoke as contract)](./docs/adrs/0001-plugin-creator-contract.md)

## Related Plugins

- `ruflo-agentdb` — namespace convention owner; `agentdb_controllers` runtime is the canonical controller list
- `ruflo-cost-tracker`, `ruflo-market-data`, `ruflo-migrations`, `ruflo-observability` — each fixed namespace-routing bugs the scaffolder now warns about
- `ruflo-knowledge-graph`, `ruflo-market-data` — each fixed `embeddings_embed` references the scaffolder now warns about