mirror of https://github.com/ruvnet/ruflo.git synced 2026-09-14 14:01:28 +08:00

Files

T

Reuven 003624f740 feat(ruflo-plugin-creator): v0.2.0 — scaffold the canonical contract + MCP-drift warnings (ADR-0001)

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>

2026-05-04 20:29:01 -04:00

3.6 KiB

Raw Permalink Blame History

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 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)

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

3.6 KiB Raw Permalink Blame History