π The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
feat(plugin-creator): scaffold governed Claude Code mods (create-mod + templates/mod, ADR-404)
ruv707977d2bcf6
diff --git a/plugins/ruflo-plugin-creator/.claude-plugin/plugin.json b/plugins/ruflo-plugin-creator/.claude-plugin/plugin.jsonindex 9a6ffd12bb..dcc382b892 100644--- a/plugins/ruflo-plugin-creator/.claude-plugin/plugin.json+++ b/plugins/ruflo-plugin-creator/.claude-plugin/plugin.json@@ -1,7 +1,7 @@{"name": "ruflo-plugin-creator",- "description": "Scaffold, validate, and publish new Claude Code plugins with the canonical plugin contract β ADR + smoke + Compatibility + namespace coordination + MCP-tool drift warnings",- "version": "0.2.1",+ "description": "Scaffold, validate, and publish new Claude Code plugins with the canonical plugin contract β now including governed Claude Code mods (function hooks), ADR + smoke + Compatibility + namespace coordination + MCP-tool drift warnings",+ "version": "0.3.0","author": {"name": "ruvnet","url": "https://github.com/ruvnet"@@ -16,6 +16,8 @@"developer-tools","mcp","scaffolding",- "contract-bootstrap"+ "contract-bootstrap",+ "mods",+ "function-hooks"]}diff --git a/plugins/ruflo-plugin-creator/README.md b/plugins/ruflo-plugin-creator/README.mdindex f3b9499ba0..f61bb0c7ec 100644--- a/plugins/ruflo-plugin-creator/README.md+++ b/plugins/ruflo-plugin-creator/README.md@@ -24,6 +24,7 @@ Scaffold, validate, and publish new Claude Code plugins with proper structure, M- `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+- `create-mod` -- Scaffold a Claude Code mod (function hooks) from `templates/mod/`: hybrid `hooks.json` with a classic fallback that stands down while the module runs, a host adapter over literal `$` calls, `userConfig`, engine-kit tests, tsconfig. Validated with `claude plugin validate` and `claude plugin test` (ruflo ADR-404)## Compatibility@@ -61,7 +62,7 @@ Lessons learned from sibling-ADR fixes β the scaffolder warns about these:```bashbash plugins/ruflo-plugin-creator/scripts/smoke.sh-# Expected: "10 passed, 0 failed"+# Expected: "11 passed, 0 failed"```## Architecture Decisionsdiff --git a/plugins/ruflo-plugin-creator/scripts/smoke.sh b/plugins/ruflo-plugin-creator/scripts/smoke.shindex a52ee8a1ea..10d0cb7097 100755--- a/plugins/ruflo-plugin-creator/scripts/smoke.sh+++ b/plugins/ruflo-plugin-creator/scripts/smoke.sh@@ -7,9 +7,9 @@ step() { printf "β %s ... " "$1"; }ok() { printf "PASS\n"; PASS=$((PASS+1)); }bad() { printf "FAIL: %s\n" "$1"; FAIL=$((FAIL+1)); }-step "1. plugin.json declares 0.2.1 with new keywords"+step "1. plugin.json declares 0.3.0 with new keywords"v=$(grep -E '"version"' "$ROOT/.claude-plugin/plugin.json" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)-if [[ "$v" != "0.2.1" ]]; then bad "expected 0.2.1, got '$v'"; else+if [[ "$v" != "0.3.0" ]]; then bad "expected 0.3.0, got '$v'"; elsemiss=""for k in mcp scaffolding contract-bootstrap; dogrep -q "\"$k\"" "$ROOT/.claude-plugin/plugin.json" || miss="$miss $k"@@ -79,5 +79,12 @@ for f in "$ROOT"/skills/*/SKILL.md; dodone[[ -z "$bad_skills" ]] && ok || bad "wildcard:$bad_skills"+step "11. the mod template is hybrid, refusal-tolerant and namespaced (ADR-404)"+T="$ROOT/templates/mod"+grep -q '"modules": \["./register.ts"\]' "$T/hooks/hooks.json" && grep -q '"UserPromptSubmit"' "$T/hooks/hooks.json" \+ && grep -q "MY_MOD_ACTIVE" "$T/hooks/classic.cjs" && grep -q "my-mod-status" "$T/hooks/register.ts" \+ && grep -q "claude-code/testing" "$T/tests/register.test.ts" && [[ -f "$ROOT/skills/create-mod/SKILL.md" ]] \+ && ! grep -qE '\$\[' "$T/hooks/register.ts" && ok || bad "templates/mod incomplete"+printf "\n%s passed, %s failed\n" "$PASS" "$FAIL"[[ $FAIL -eq 0 ]] || exit 1diff --git a/plugins/ruflo-plugin-creator/skills/create-mod/SKILL.md b/plugins/ruflo-plugin-creator/skills/create-mod/SKILL.mdnew file mode 100644index 0000000000..1726187c4b--- /dev/null+++ b/plugins/ruflo-plugin-creator/skills/create-mod/SKILL.md@@ -0,0 +1,32 @@+---+name: create-mod+description: Scaffold a Claude Code mod (a plugin with a function-hooks module) from ruflo's governed template β hybrid hooks.json with a classic fallback, a host adapter over literal $ calls, userConfig options, engine-kit tests and a tsconfig β then validate and test it. Use when the user asks for a mod, a function hook, or wants Claude Code to modify itself.+argument-hint: "<mod-name>"+allowed-tools: Bash Read Write Edit+---++# Create Mod++Scaffold a mod the governed way, instead of an ad-hoc one: the template already follows the rules ruflo's own mod (ADR-404) was reviewed against.++## Steps++1. **Name it.** kebab-case `<name>`. Commands it registers are namespaced `<name>-<verb>`; never register a built-in's name (`/diff`, `/help`) or another plugin's (`/ruos*`, `ruflo-*`).+2. **Copy the template** `plugins/ruflo-plugin-creator/templates/mod/` to the target folder. Replace `my-mod` everywhere (plugin.json `name`, the command, `MY_MOD_ACTIVE` β `<NAME>_ACTIVE` in both `hooks/register.ts` and `hooks/classic.cjs`).+3. **Write the behaviour** in pure functions taking the `Host` (see `hooks/host.ts`). In `register.ts`, build the host from literal `$.noun.method(...)` calls only β the engine reads a module's `$` uses off its source, and `claude plugin validate` refuses `$` passed around, computed (`$[noun]`), or deeper than `$.noun.method(input)`.+4. **Keep the rules:**+ - Observe with `const r = await next(e); β¦; return r`; rewrite with `next({ ...e, β¦ })`; answer (`{ deny }`) only when you mean to stop the chain.+ - On `tool.check`, only ever tighten (the stricter of `await next(e)` and yours); never answer `allow` of your own.+ - Wrap every `$` call so a refusal degrades instead of failing the turn (admins can withhold any `$` affordance).+ - No `$.process.run` / `$.http.fetch` built from event input. Nothing slow on the hot path (about 10 s per dispatch).+ - Anything that must survive a hot reload goes in `$.store` / `$.state`, not module variables.+ - Options come from `userConfig` in plugin.json, not environment variables.+5. **Keep the fallback honest.** `hooks.json` is hybrid: the classic command hook runs everywhere, the module only where function hooks are on (Claude Code >= 2.1.287; 2.1.277+ with `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1`). The module sets `<NAME>_ACTIVE` at `session.start`; the classic script exits early when it sees it, so nothing fires twice.+6. **Validate and test:**+ ```bash+ claude plugin validate <dir> # lists hooked events, $ calls, env reads/writes+ claude plugin test <dir> # tests/*.test.ts on the engine kit+ claude -p --plugin-dir <dir> "/<name>-status" # writes .claude-plugin/types/ and proves a live load+ npx tsc -p <dir> # against those generated types+ ```+7. **Ship it in a plugin marketplace** (`marketplace.json` entry), installed with `/plugin install <name>@<marketplace>` and picked up with `/reload-plugins`. If ruflo-mods is installed with `modTrust: refuse-risky`, a mod using `process.run`, `http.fetch`, `env.set` or hooking `tool.check`/`tool.call`/`*` is refused unless named in `modTrustAllow` β the template sets `env.set` (the fallback handshake), so allow it by name.diff --git a/plugins/ruflo-plugin-creator/templates/mod/.claude-plugin/plugin.json b/plugins/ruflo-plugin-creator/templates/mod/.claude-plugin/plugin.jsonnew file mode 100644index 0000000000..ab80002821--- /dev/null+++ b/plugins/ruflo-plugin-creator/templates/mod/.claude-plugin/plugin.json@@ -0,0 +1,17 @@+{+ "name": "my-mod",+ "description": "A Claude Code mod scaffolded by ruflo-plugin-creator: counts the session's tool calls in a status line, adds /my-mod-status, and keeps a classic hook as the fallback where function hooks are off.",+ "version": "0.1.0",+ "author": { "name": "you" },+ "license": "MIT",+ "keywords": ["mod", "function-hooks"],+ "userConfig": {+ "statusLine": {+ "type": "boolean",+ "title": "Status line",+ "description": "Show the tool-call count under the prompt.",+ "required": false,+ "default": true+ }+ }+}diff --git a/plugins/ruflo-plugin-creator/templates/mod/hooks/classic.cjs b/plugins/ruflo-plugin-creator/templates/mod/hooks/classic.cjsnew file mode 100644index 0000000000..519895900a--- /dev/null+++ b/plugins/ruflo-plugin-creator/templates/mod/hooks/classic.cjs@@ -0,0 +1,8 @@+// The classic fallback. It runs as a settings hook on every prompt; while the+// module is loaded (it sets MY_MOD_ACTIVE on the Claude Code process, which+// every hook started after inherits) it does nothing, so nothing fires twice.+'use strict';+if (process.env.MY_MOD_ACTIVE === '1') process.exit(0);+// Without function hooks: do the classic-path equivalent of the module's work+// here (this template has none to do), always exiting 0.+process.exit(0);diff --git a/plugins/ruflo-plugin-creator/templates/mod/hooks/hooks.json b/plugins/ruflo-plugin-creator/templates/mod/hooks/hooks.jsonnew file mode 100644index 0000000000..6906bbefb7--- /dev/null+++ b/plugins/ruflo-plugin-creator/templates/mod/hooks/hooks.json@@ -0,0 +1,16 @@+{+ "description": "Hybrid: the classic UserPromptSubmit hook runs everywhere; the module loads only where function hooks are on (Claude Code >= 2.1.287, or CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 from 2.1.277). While the module runs it sets MY_MOD_ACTIVE, and the classic hook does nothing, so no event fires twice.",+ "hooks": {+ "UserPromptSubmit": [+ {+ "hooks": [+ {+ "type": "command",+ "command": "node -e \"require(require('path').join(process.env.CLAUDE_PLUGIN_ROOT,'hooks','classic.cjs'))\""+ }+ ]+ }+ ]+ },+ "modules": ["./register.ts"]+}diff --git a/plugins/ruflo-plugin-creator/templates/mod/hooks/host.ts b/plugins/ruflo-plugin-creator/templates/mod/hooks/host.tsnew file mode 100644index 0000000000..93c2629f9c--- /dev/null+++ b/plugins/ruflo-plugin-creator/templates/mod/hooks/host.ts@@ -0,0 +1,22 @@+/**+ * What the pure logic needs from the engine, as plain functions. The engine+ * reads what a module calls off its source, so `$` never leaves a hook: the+ * hook builds this from literal `$.noun.method(...)` calls (register.ts).+ */+export type Host = {+ readonly status: (text: string | undefined) => void+}++/** The tool-call tally and the line it shows; pure, testable without the engine. */+export function statusLine(calls: number): string {+ return `my-mod Β· ${calls} tool call${calls === 1 ? '' : 's'}`+}++/** Draws through the host; a refused `ui.status` (an admin may withhold it) is ignored. */+export function show(host: Host, calls: number): void {+ try {+ host.status(statusLine(calls))+ } catch {+ // never fail a hook over the status line+ }+}diff --git a/plugins/ruflo-plugin-creator/templates/mod/hooks/register.ts b/plugins/ruflo-plugin-creator/templates/mod/hooks/register.tsnew file mode 100644index 0000000000..b5659f0094--- /dev/null+++ b/plugins/ruflo-plugin-creator/templates/mod/hooks/register.ts@@ -0,0 +1,33 @@+import type { Register } from 'claude-code'++import { show, statusLine, type Host } from './host'++/**+ * A mod scaffolded by ruflo-plugin-creator (ADR-404 patterns):+ * - observe: `const r = await next(e); β¦; return r` on tool.call;+ * - every `$` call literal, wrapped in a host adapter, refusal-tolerant;+ * - namespaced command (`my-mod-status`), never a built-in's name;+ * - the classic fallback handed over through MY_MOD_ACTIVE.+ * Hot reload re-runs register and session.start: keep anything that must+ * survive a reload in `$.store` or `$.state`, not in these variables.+ */+export const register: Register = (on, options) => {+ const showLine = options.statusLine !== false+ let calls = 0++ on('session.start', async ($, e, next) => {+ await $.env.set('MY_MOD_ACTIVE', '1').catch(() => undefined)+ await $.command.register({ name: 'my-mod-status', description: 'my-mod: tool calls this session' }).catch(() => undefined)+ return next(e)+ })++ on('tool.call', async ($, e, next) => {+ const result = await next(e)+ calls+++ const host: Host = { status: text => $.ui.status(text) }+ if (showLine) show(host, calls)+ return result+ })++ on('command.run', { command: 'my-mod-status' }, () => ({ text: statusLine(calls) }))+}diff --git a/plugins/ruflo-plugin-creator/templates/mod/tests/register.test.ts b/plugins/ruflo-plugin-creator/templates/mod/tests/register.test.tsnew file mode 100644index 0000000000..98ab56ea01--- /dev/null+++ b/plugins/ruflo-plugin-creator/templates/mod/tests/register.test.ts@@ -0,0 +1,31 @@+import { describe, expect, test, tier } from 'claude-code/testing'++tier('user')++describe('register', () => {+ test('counts tool calls in the status line and answers /my-mod-status', async ($, on) => {+ const env = new Map<string, string>()+ const statuses: (string | undefined)[] = []+ on('session.start', ($, e) => ({ cwd: e.cwd }))+ on('env.set', ($, e) => (e.value === undefined ? env.delete(e.name) : env.set(e.name, e.value), { value: undefined }))+ on('command.register', ($, e) => ({ value: { command: e.name } }))+ on('ui.status', ($, e) => (statuses.push(e.text), { value: undefined }))+ on('tool.call', () => ({ result: 'ok' }))+ on('command.run', () => ({ text: 'core' }))++ await $.session.start({ surface: 'terminal', isInteractive: true, cwd: '/work' })+ expect(env.get('MY_MOD_ACTIVE')).toBe('1')++ await $.tool.call({ tool: 'Bash', command: 'ls' })+ await $.tool.call({ tool: 'Bash', command: 'pwd' })+ expect(statuses.at(-1)).toBe('my-mod Β· 2 tool calls')++ const { text } = await $.command.run({+ command: 'my-mod-status',+ args: '',+ origin: { kind: 'composer' },+ presentation: { isFullscreen: false, columns: 100 },+ })+ expect(text).toBe('my-mod Β· 2 tool calls')+ })+})diff --git a/plugins/ruflo-plugin-creator/templates/mod/tsconfig.json b/plugins/ruflo-plugin-creator/templates/mod/tsconfig.jsonnew file mode 100644index 0000000000..90c6c0cf3c--- /dev/null+++ b/plugins/ruflo-plugin-creator/templates/mod/tsconfig.json@@ -0,0 +1,4 @@+{+ "//": "Claude Code (>= 2.1.287) writes its declarations and this base config into .claude-plugin/types/ when it loads or validates the plugin.",+ "extends": "./.claude-plugin/types/tsconfig.json"+}diff --git a/scripts/ci-test-baseline.txt b/scripts/ci-test-baseline.txtindex a2f1eb3c2b..ff712a3de8 100644--- a/scripts/ci-test-baseline.txt+++ b/scripts/ci-test-baseline.txt@@ -15,6 +15,7 @@ plugins/ruflo-mods/tests/cost.test.tsplugins/ruflo-mods/tests/noun.test.tsplugins/ruflo-mods/tests/register.test.tsplugins/ruflo-mods/tests/trust.test.ts+plugins/ruflo-plugin-creator/templates/mod/tests/register.test.tsplugins/ruflo-workflows/scripts/gaia-audit.test.mjsruflo/src/ruvocal/src/lib/components/chat/MarkdownRenderer.svelte.test.tsruflo/src/ruvocal/src/lib/migrations/migrations.spec.ts