Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 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

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.json
index 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.md
index 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:
```bash
bash plugins/ruflo-plugin-creator/scripts/smoke.sh
-# Expected: "10 passed, 0 failed"
+# Expected: "11 passed, 0 failed"
```
## Architecture Decisions
diff --git a/plugins/ruflo-plugin-creator/scripts/smoke.sh b/plugins/ruflo-plugin-creator/scripts/smoke.sh
index 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'"; else
miss=""
for k in mcp scaffolding contract-bootstrap; do
grep -q "\"$k\"" "$ROOT/.claude-plugin/plugin.json" || miss="$miss $k"
@@ -79,5 +79,12 @@ for f in "$ROOT"/skills/*/SKILL.md; do
done
[[ -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 1
diff --git a/plugins/ruflo-plugin-creator/skills/create-mod/SKILL.md b/plugins/ruflo-plugin-creator/skills/create-mod/SKILL.md
new file mode 100644
index 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.json
new file mode 100644
index 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.cjs
new file mode 100644
index 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.json
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.json
new file mode 100644
index 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.txt
index 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.ts
plugins/ruflo-mods/tests/noun.test.ts
plugins/ruflo-mods/tests/register.test.ts
plugins/ruflo-mods/tests/trust.test.ts
+plugins/ruflo-plugin-creator/templates/mod/tests/register.test.ts
plugins/ruflo-workflows/scripts/gaia-audit.test.mjs
ruflo/src/ruvocal/src/lib/components/chat/MarkdownRenderer.svelte.test.ts
ruflo/src/ruvocal/src/lib/migrations/migrations.spec.ts