mirror of
https://github.com/ruvnet/ruflo.git
synced 2026-09-14 14:01:28 +08:00
Reuven
003624f740
The meta-plugin that creates new plugins now (a) follows the same
contract every other plugin adopted, and (b) propagates that contract
to every newly-scaffolded plugin. The retrofit work the loop is doing
right now becomes unnecessary for new plugins.
Drift fixed:
- create-plugin skill claimed "19 AgentDB controllers" (the same myth
ruflo-agentdb ADR-0001 killed). Replaced with "15 controller-bridge
tools; defer to agentdb_controllers runtime for canonical list".
Scaffolder updates (the create-plugin skill now generates):
- docs/adrs/0001-<name>-contract.md (Proposed)
- scripts/smoke.sh (≥8 structural checks)
- README sections: Compatibility (pin v3.6), Namespace coordination
(defers to ruflo-agentdb ADR-0001), Verification, Architecture Decisions
- "MCP-tool drift to avoid" section warning new authors about the four
real bugs found in sibling ADRs:
1. embeddings_embed does not exist (use embeddings_generate)
2. agentdb_hierarchical-* ignores namespace arg (use tier or memory_*)
3. agentdb_pattern-* ignores namespace arg (ReasoningBank routes;
fallback writes to pattern reserved)
4. pattern (singular) ≠ patterns (plural) — different reserved namespaces
Plugin contract additions:
- ADR-0001 (Proposed) at docs/adrs/0001-plugin-creator-contract.md
- README adds Compatibility (pin v3.6), Canonical plugin contract block
showing the scaffolded directory shape, MCP-tool drift table,
Verification + Architecture Decisions
- plugin.json bumps 0.1.0 → 0.2.0; description names the canonical
contract; keywords add mcp, scaffolding, contract-bootstrap
- scripts/smoke.sh — 10 structural checks: version + keywords, both
skills + agent + command, scaffolder generates ADR + smoke + Compat +
Namespace, scaffolder includes MCP-drift warnings, regression check
on "19 controllers", v3.6 pin, Architecture Decisions section,
ADR Proposed, validate-plugin present, no wildcard tools
Verification: bash plugins/ruflo-plugin-creator/scripts/smoke.sh → 10/10
Co-Authored-By: RuFlo <ruv@ruv.net>
76 lines
3.6 KiB
Markdown
76 lines
3.6 KiB
Markdown
# 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
|