🌊 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(ruflo-plugin-creator): function-hook mod (ADR-445)
ruv53563c63aeda
diff --git a/plugins/ruflo-plugin-creator/.claude-plugin/plugin.json b/plugins/ruflo-plugin-creator/.claude-plugin/plugin.jsonindex dcc382b892..c82aed086f 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 — now including governed Claude Code mods (function hooks), ADR + smoke + Compatibility + namespace coordination + MCP-tool drift warnings",- "version": "0.3.0",+ "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. As a mod (ADR-445): /creator-mod (status, reserved names, a plugin contract check) and a status file the console shows",+ "version": "0.4.0","author": {"name": "ruvnet","url": "https://github.com/ruvnet"@@ -18,6 +18,7 @@"scaffolding","contract-bootstrap","mods",- "function-hooks"+ "function-hooks",+ "mod"]}diff --git a/plugins/ruflo-plugin-creator/README.md b/plugins/ruflo-plugin-creator/README.mdindex f61bb0c7ec..4d41aba194 100644--- a/plugins/ruflo-plugin-creator/README.md+++ b/plugins/ruflo-plugin-creator/README.md@@ -74,3 +74,12 @@ bash plugins/ruflo-plugin-creator/scripts/smoke.sh- `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++## As a mod++Function-hook mod (ADR-445, pattern of `ruflo-agentdb`), loaded from `hooks/hooks.json` → `hooks/register.ts`. This plugin's own tools only search the plugin store, so there is no guard and no `userConfig`: the mod is a local command and a status file.++- **Command**: `/creator-mod` answers locally with no model call, read-only. Verbs: `status`; `reserved <plugin-dir>` lists the command and skill names a plugin already uses (a mod command must not reuse one); `check <plugin-dir>` summarises its manifest, `hooks.json` modules and `userConfig` options. Paths with `..` are refused.+- **Status file**: `.claude-flow/creator-mod/status.json` (`{version, updatedMs, checked, reserved, lastTarget}`).+- **Safety**: no network, no process spawning.+- **Test**: `claude plugin validate plugins/ruflo-plugin-creator`, `claude plugin test plugins/ruflo-plugin-creator`, `bash plugins/ruflo-plugin-creator/scripts/smoke.sh`. The runner sweeps in `templates/mod/tests` (the scaffold's own test, which only passes against the scaffold: `claude plugin test plugins/ruflo-plugin-creator/templates/mod`), so expect that one file to fail from the plugin root.diff --git a/plugins/ruflo-plugin-creator/hooks/command.ts b/plugins/ruflo-plugin-creator/hooks/command.tsnew file mode 100644index 0000000000..72897850bc--- /dev/null+++ b/plugins/ruflo-plugin-creator/hooks/command.ts@@ -0,0 +1,72 @@+import type { Stats } from './status'++/** `/creator-mod` is answered locally, read-only and takes no model turn. */+export type CommandDeps = {+ readonly stats: Stats+ readonly read: (path: string) => Promise<string>+ readonly list: (path: string) => Promise<readonly { readonly name: string; readonly kind: string }[]>+}++const HELP = ['/creator-mod status', '/creator-mod reserved <plugin-dir>', '/creator-mod check <plugin-dir>'].join('\n')++/** A plugin directory the user typed: relative or absolute, never a parent traversal. */+export const safeDir = (arg: string): string | undefined => {+ const dir = arg.trim().replace(/\/+$/, '')+ return dir === '' || dir.includes('\0') || dir.split('/').includes('..') ? undefined : dir+}++/** Names the plugin's markdown commands and skill directories already hold: a mod command may not reuse one. */+async function reservedIn(dir: string, deps: CommandDeps): Promise<string[]> {+ const names: string[] = []+ for (const [sub, want] of [['commands', 'file'], ['skills', 'dir']] as const) {+ try {+ for (const e of await deps.list(`${dir}/${sub}`)) {+ if (e.kind === want || e.kind === 'directory') names.push(e.name.replace(/\.md$/, ''))+ }+ } catch {+ /* no such folder */+ }+ }+ return [...new Set(names)].sort()+}++const readJson = async (deps: CommandDeps, path: string): Promise<Record<string, unknown> | undefined> => {+ try {+ const v: unknown = JSON.parse(await deps.read(path))+ return typeof v === 'object' && v !== null && !Array.isArray(v) ? (v as Record<string, unknown>) : undefined+ } catch {+ return undefined+ }+}++export async function answer(args: string, deps: CommandDeps): Promise<string> {+ const [verb = '', ...rest] = args.trim().split(/\s+/)+ const { stats } = deps++ if (verb === '' || verb === 'help') return HELP+ if (verb === 'status') return `checks run ${stats.checked} · reserved lookups ${stats.reserved}${stats.lastTarget ? ` · last ${stats.lastTarget}` : ''}`++ if (verb !== 'reserved' && verb !== 'check') return `Unknown: ${verb}\n${HELP}`+ const dir = safeDir(rest.join(' '))+ if (dir === undefined) return `usage: /creator-mod ${verb} <plugin-dir> (no .. segments)`+ stats.lastTarget = dir++ if (verb === 'reserved') {+ stats.reserved+++ const names = await reservedIn(dir, deps)+ return names.length ? `Names ${dir} already uses (a mod command must differ): ${names.join(', ')}` : `No commands or skills found under ${dir}.`+ }++ stats.checked+++ const manifest = await readJson(deps, `${dir}/.claude-plugin/plugin.json`)+ if (!manifest) return `${dir}: no readable .claude-plugin/plugin.json.`+ const hooks = await readJson(deps, `${dir}/hooks/hooks.json`)+ const modules = Array.isArray(hooks?.modules) ? (hooks.modules as unknown[]).length : 0+ const config = typeof manifest.userConfig === 'object' && manifest.userConfig !== null ? Object.keys(manifest.userConfig).length : 0+ const name = typeof manifest.name === 'string' ? manifest.name : '?'+ return [+ `${name} ${typeof manifest.version === 'string' ? manifest.version : '(no version)'}`,+ `hooks.json ${hooks ? 'present' : 'absent'} · mod modules ${modules} · userConfig options ${config}`,+ `reserved names: ${(await reservedIn(dir, deps)).join(', ') || 'none'}`,+ ].join('\n')+}diff --git a/plugins/ruflo-plugin-creator/hooks/hooks.json b/plugins/ruflo-plugin-creator/hooks/hooks.jsonnew file mode 100644index 0000000000..92326a668a--- /dev/null+++ b/plugins/ruflo-plugin-creator/hooks/hooks.json@@ -0,0 +1,4 @@+{+ "description": "Plugin creator as a mod (ADR-445): /creator-mod answers locally (status, reserved names, a plugin contract check) and a status file the console reads.",+ "modules": ["./register.ts"]+}diff --git a/plugins/ruflo-plugin-creator/hooks/register.ts b/plugins/ruflo-plugin-creator/hooks/register.tsnew file mode 100644index 0000000000..69ed442344--- /dev/null+++ b/plugins/ruflo-plugin-creator/hooks/register.ts@@ -0,0 +1,49 @@+import type { Hook, Register } from 'claude-code'++import { answer } from './command'+import { newStats, STATUS_PATH, statusText, type Stats } from './status'++type Dollar = Parameters<Hook<'session.start'>>[0]++/** Everything one session of the mod keeps: its counters and the project root. */+type Session = { readonly stats: Stats; root?: string }++async function flush($: Dollar, s: Session): Promise<void> {+ if (s.root === undefined) return+ try {+ await $.fs.write(`${s.root}/${STATUS_PATH}`, statusText(s.stats, await $.clock.now()))+ } catch {+ /* the status file is a courtesy */+ }+}++/**+ * The plugin creator as a mod (ADR-445): `/creator-mod` (status, reserved names, a contract check, all read-only and local) and a status file+ * the console reads. No guard: this plugin's tools only search the plugin store. No network, no process.+ */+export const register: Register = on => {+ const s: Session = { stats: newStats() }++ on('session.start', async ($, e, next) => {+ const result = await next(e)+ try {+ s.root = (await $.session.root()) as string | undefined+ } catch {+ /* no project root: the mod still answers, it just writes no status file */+ }+ try {+ await $.command.register({ name: 'creator-mod', description: 'Plugin creator mod: status, reserved <dir>, check <dir>' })+ } catch {+ /* a name taken by another plugin must not stop the mod */+ }+ await flush($, s)+ return result+ })++ /** `/creator-mod` (the plugin's `/create-plugin` is a prompt command, which no hook can answer). */+ on('command.run', { command: 'creator-mod' }, async ($, e) => {+ const text = await answer(typeof e.args === 'string' ? e.args : '', { stats: s.stats, read: p => $.fs.read(p), list: p => $.fs.list(p) })+ await flush($, s)+ return { text }+ })+}diff --git a/plugins/ruflo-plugin-creator/hooks/status.ts b/plugins/ruflo-plugin-creator/hooks/status.tsnew file mode 100644index 0000000000..39451b043c--- /dev/null+++ b/plugins/ruflo-plugin-creator/hooks/status.ts@@ -0,0 +1,9 @@+/** Counters the mod keeps for the session and writes to `.claude-flow/creator-mod/status.json`. */+export type Stats = { checked: number; reserved: number; lastTarget?: string }++export const newStats = (): Stats => ({ checked: 0, reserved: 0 })++export const STATUS_PATH = '.claude-flow/creator-mod/status.json'++/** The file's text; `version` lets a reader refuse a shape it does not know. */+export const statusText = (stats: Stats, nowMs: number): string => `${JSON.stringify({ version: 1, updatedMs: nowMs, ...stats }, null, 2)}\n`diff --git a/plugins/ruflo-plugin-creator/scripts/smoke.sh b/plugins/ruflo-plugin-creator/scripts/smoke.shindex 10d0cb7097..d46c6145de 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.3.0 with new keywords"+step "1. plugin.json declares 0.4.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.3.0" ]]; then bad "expected 0.3.0, got '$v'"; else+if [[ "$v" != "0.4.0" ]]; then bad "expected 0.4.0, got '$v'"; elsemiss=""for k in mcp scaffolding contract-bootstrap; dogrep -q "\"$k\"" "$ROOT/.claude-plugin/plugin.json" || miss="$miss $k"@@ -86,5 +86,23 @@ grep -q '"modules": \["./register.ts"\]' "$T/hooks/hooks.json" && grep -q '"User&& 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"+# M1. The mod (ADR-445): hooks module registered, files within the 500-line rule, no network or process access in the hooks+step "M1. mod: hooks.json names register.ts, every hook file is present and under 500 lines"+mod_ok=1+grep -q '"./register.ts"' "$ROOT/hooks/hooks.json" || mod_ok=0+for f in status command register; do+ [[ -f "$ROOT/hooks/$f.ts" ]] || mod_ok=0+ [[ $(wc -l < "$ROOT/hooks/$f.ts" 2>/dev/null || echo 9999) -le 500 ]] || mod_ok=0+done+[[ $mod_ok -eq 1 ]] && ok || bad "mod hooks incomplete or too long"++step "M2. mod: no userConfig needed (read-only local command)"+node -e '+process.exit(require(process.argv[1]).userConfig === undefined ? 0 : 1)+' "$ROOT/.claude-plugin/plugin.json" && ok || bad "unexpected userConfig"++step "M3. mod: hooks never touch the network or spawn a process"+if grep -nE '\$\.(http|process)\.|child_process|fetch\(' "$ROOT"/hooks/*.ts >/dev/null; then bad "network or process call in hooks"; else ok; fi+printf "\n%s passed, %s failed\n" "$PASS" "$FAIL"[[ $FAIL -eq 0 ]] || exit 1diff --git a/plugins/ruflo-plugin-creator/tests/creator.test.ts b/plugins/ruflo-plugin-creator/tests/creator.test.tsnew file mode 100644index 0000000000..5b747b4d63--- /dev/null+++ b/plugins/ruflo-plugin-creator/tests/creator.test.ts@@ -0,0 +1,85 @@+import type { On } from 'claude-code'+import { describe, expect, test, tier } from 'claude-code/testing'++tier('user')++const ROOT = '/work'+const START = { surface: 'terminal', isInteractive: true, cwd: ROOT } as const+const STATUS = `${ROOT}/.claude-flow/creator-mod/status.json`+const slash = (args: string) => ({ command: 'creator-mod', args, origin: { kind: 'composer' }, presentation: { isFullscreen: false, columns: 100 } }) as const++/** The engine resolves paths against the real cwd; the fixture is keyed on the part the mod typed. */+const rel = (p: string) => p.replace(/^.*\/plugins\/ruflo-plugin-creator\//, '')++/** A project root, a file map for writes, and a small read-only plugin tree. */+function world(on: On) {+ const files = new Map<string, string>()+ const tree: Record<string, string> = {+ 'demo/.claude-plugin/plugin.json': JSON.stringify({ name: 'demo', version: '1.2.0', userConfig: { guard: {} } }),+ 'demo/hooks/hooks.json': JSON.stringify({ modules: ['./register.ts'] }),+ }+ const dirs: Record<string, { name: string; kind: string; size: number; mtimeMs: number; isLink: boolean }[]> = {+ 'demo/commands': [{ name: 'demo.md', kind: 'file', size: 1, mtimeMs: 0, isLink: false }],+ 'demo/skills': [{ name: 'demo-skill', kind: 'directory', size: 0, mtimeMs: 0, isLink: false }],+ }+ on('session.start', ($, e) => ({ cwd: e.cwd }))+ on('session.root', () => ({ value: ROOT }))+ on('command.register', ($, e) => ({ value: { command: e.name } }))+ on('fs.write', ($, e) => (files.set(e.path, e.text), { value: undefined }))+ on('fs.read', ($, e) => {+ const text = tree[rel(e.path)]+ if (text === undefined) throw new Error('ENOENT')+ return { value: text }+ })+ on('fs.list', ($, e) => {+ const entries = dirs[rel(e.path ?? '')]+ if (entries === undefined) throw new Error('ENOENT')+ return { value: entries }+ })+ on('clock.now', () => ({ value: 5_000 }))+ return { status: () => JSON.parse(files.get(STATUS) ?? '{}') }+}++describe('status file', () => {+ test('written at session start, rewritten after a lookup', async ($, on) => {+ const w = world(on)+ await $.session.start(START)+ expect(w.status()).toMatchObject({ version: 1, updatedMs: 5000, checked: 0, reserved: 0 })+ await $.command.run(slash('check demo'))+ expect(w.status()).toMatchObject({ checked: 1, lastTarget: 'demo' })+ })+})++describe('/creator-mod', () => {+ test('status and help answer locally', async ($, on) => {+ world(on)+ await $.session.start(START)+ expect((await $.command.run(slash('status'))).text).toContain('checks run 0')+ expect((await $.command.run(slash(''))).text).toContain('/creator-mod reserved <plugin-dir>')+ expect((await $.command.run(slash('wat'))).text).toContain('Unknown: wat')+ })++ test('reserved lists the commands and skills a mod command must not reuse', async ($, on) => {+ world(on)+ await $.session.start(START)+ const text = (await $.command.run(slash('reserved demo/'))).text ?? ''+ expect(text).toContain('demo')+ expect(text).toContain('demo-skill')+ })++ test('check reports the manifest, hooks and options', async ($, on) => {+ world(on)+ await $.session.start(START)+ const text = (await $.command.run(slash('check demo'))).text ?? ''+ expect(text).toContain('demo 1.2.0')+ expect(text).toContain('mod modules 1 · userConfig options 1')+ })++ test('a missing plugin and a parent traversal are refused plainly', async ($, on) => {+ world(on)+ await $.session.start(START)+ expect((await $.command.run(slash('check nowhere'))).text).toContain('no readable')+ expect((await $.command.run(slash('check ../../etc'))).text).toContain('no .. segments')+ expect((await $.command.run(slash('check'))).text).toContain('usage')+ })+})diff --git a/plugins/ruflo-plugin-creator/tsconfig.json b/plugins/ruflo-plugin-creator/tsconfig.jsonnew file mode 100644index 0000000000..e4ba54993e--- /dev/null+++ b/plugins/ruflo-plugin-creator/tsconfig.json@@ -0,0 +1,19 @@+{+ "//": "Self-contained on purpose: bundlers (vite/esbuild in the root CI vitest) load this file for every module they transform, so it must not extend a file that only exists after Claude Code (>= 2.1.287) has loaded the plugin. Claude Code writes its declarations to .claude-plugin/types/ (gitignored) on load or validate; tsc -p . then reads them through typeRoots.",+ "compilerOptions": {+ "target": "es2023",+ "lib": ["es2023"],+ "module": "esnext",+ "moduleResolution": "bundler",+ "strict": true,+ "noUncheckedIndexedAccess": true,+ "noEmit": true,+ "skipLibCheck": true,+ "jsx": "react",+ "jsxFactory": "h",+ "jsxFragmentFactory": "Fragment",+ "typeRoots": ["./.claude-plugin/types"],+ "types": ["claude-code", "claude-code-tools", "claude-code-mcp"]+ },+ "include": ["hooks", "tests"]+}