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): status contract in the create-mod template (0.4.1)

ruv22e883c43514
diff --git a/plugins/ruflo-plugin-creator/.claude-plugin/plugin.json b/plugins/ruflo-plugin-creator/.claude-plugin/plugin.json
index c82aed086f..385e4541b4 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. 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",
+ "version": "0.4.1",
"author": {
"name": "ruvnet",
"url": "https://github.com/ruvnet"
diff --git a/plugins/ruflo-plugin-creator/README.md b/plugins/ruflo-plugin-creator/README.md
index 4d41aba194..eae3156399 100644
--- a/plugins/ruflo-plugin-creator/README.md
+++ b/plugins/ruflo-plugin-creator/README.md
@@ -82,4 +82,5 @@ Function-hook mod (ADR-445, pattern of `ruflo-agentdb`), loaded from `hooks/hook
- **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.
+- **Scaffold status contract** (0.4.1): `/create-mod` scaffolds `hooks/status.ts`, which writes `.claude-flow/<name>-mod/status.json` with the fields the console's Mods section reads: `version: 1`, `summary`, `modVersion`, `guard`, `calls` (a number), `blocked`, `lastDenied` (only once the mod has refused something), plus `updatedMs`/`startedMs`. The scaffold's `tests/status.test.ts` asserts that shape; the steps are in `skills/create-mod/SKILL.md`.
- **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/scripts/smoke.sh b/plugins/ruflo-plugin-creator/scripts/smoke.sh
index d46c6145de..6987fc8dbd 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.4.0 with new keywords"
+step "1. plugin.json declares 0.4.1 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.4.0" ]]; then bad "expected 0.4.0, got '$v'"; else
+if [[ "$v" != "0.4.1" ]]; then bad "expected 0.4.1, got '$v'"; else
miss=""
for k in mcp scaffolding contract-bootstrap; do
grep -q "\"$k\"" "$ROOT/.claude-plugin/plugin.json" || miss="$miss $k"
diff --git a/plugins/ruflo-plugin-creator/skills/create-mod/SKILL.md b/plugins/ruflo-plugin-creator/skills/create-mod/SKILL.md
index df43f548a7..a6a45b1eb0 100644
--- a/plugins/ruflo-plugin-creator/skills/create-mod/SKILL.md
+++ b/plugins/ruflo-plugin-creator/skills/create-mod/SKILL.md
@@ -13,20 +13,21 @@ Scaffold a mod the governed way, instead of an ad-hoc one: the template already
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:**
+3. **Keep the status contract.** `hooks/status.ts` writes `.claude-flow/<name>-mod/status.json`, the file the console's Mods section reads. The folder must be `<name>-mod` (lowercase, digits, hyphens, at most 41 characters): replace `my-mod` in `STATUS_PATH` with `<name>-mod`. Fields: `version: 1` (required, anything else is ignored), `summary` (one line), `modVersion`, `guard` (boolean), `calls` (a **number**, not a per-tool object), `blocked` (number), `lastDenied` (a short reason, only once the mod has refused something), plus `updatedMs`/`startedMs`. Other fields are not shown. `tests/status.test.ts` asserts the shape.
+4. **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)`.
+5. **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:**
+6. **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.
+7. **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 `fs.write`, or hooking `tool.check`/`tool.call`/`*`, is refused unless its plugin id (`<name>@<marketplace>`) is in `modTrustAllow` β€” the template sets `env.set` (the fallback handshake), so allow-list it by id.
+8. **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 `fs.write`, or hooking `tool.check`/`tool.call`/`*`, is refused unless its plugin id (`<name>@<marketplace>`) is in `modTrustAllow` β€” the template sets `env.set` (the fallback handshake), so allow-list it by id.
diff --git a/plugins/ruflo-plugin-creator/templates/mod/hooks/register.ts b/plugins/ruflo-plugin-creator/templates/mod/hooks/register.ts
index b5659f0094..5b372c59a4 100644
--- a/plugins/ruflo-plugin-creator/templates/mod/hooks/register.ts
+++ b/plugins/ruflo-plugin-creator/templates/mod/hooks/register.ts
@@ -1,33 +1,61 @@
-import type { Register } from 'claude-code'
+import type { Hook, Register } from 'claude-code'
import { show, statusLine, type Host } from './host'
+import { newCounters, STATUS_PATH, statusText, type Counters } from './status'
+
+type Dollar = Parameters<Hook<'session.start'>>[0]
+
+/** What one session keeps: the counters for the status file, the project root and the start time. */
+type Session = { readonly counters: Counters; root?: string; startedMs: number }
+
+/** A top-level function declaration, so `import type { Hook, Register } from 'claude-code'
+
+import { show, statusLine, type Host } from './host'
+ may be passed to it; a refused write is ignored (the status file is a courtesy). */
+async function flush($: Dollar, s: Session): Promise<void> {
+ if (s.root === undefined) return
+ try {
+ await $.fs.write(`${s.root}/${STATUS_PATH}`, statusText(s.counters, await $.clock.now(), s.startedMs))
+ } catch {
+ // never fail a hook over the status file
+ }
+}
/**
* 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.
+ * - the classic fallback handed over through MY_MOD_ACTIVE;
+ * - a status file (status.ts) the console reads: keep `calls` a number.
* 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
+ const s: Session = { counters: newCounters(), startedMs: 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)
+ try {
+ s.root = (await $.session.root()) as string | undefined
+ s.startedMs = await $.clock.now()
+ } catch {
+ // no project root: the mod still runs, it just writes no status file
+ }
+ await flush($, s)
return next(e)
})
on('tool.call', async ($, e, next) => {
const result = await next(e)
- calls++
+ s.counters.calls++
const host: Host = { status: text => $.ui.status(text) }
- if (showLine) show(host, calls)
+ if (showLine) show(host, s.counters.calls)
+ await flush($, s)
return result
})
- on('command.run', { command: 'my-mod-status' }, () => ({ text: statusLine(calls) }))
+ on('command.run', { command: 'my-mod-status' }, () => ({ text: statusLine(s.counters.calls) }))
}
diff --git a/plugins/ruflo-plugin-creator/templates/mod/hooks/status.ts b/plugins/ruflo-plugin-creator/templates/mod/hooks/status.ts
new file mode 100644
index 0000000000..b65b7c60ee
--- /dev/null
+++ b/plugins/ruflo-plugin-creator/templates/mod/hooks/status.ts
@@ -0,0 +1,40 @@
+/**
+ * The status contract (ADR-446): the file the console's Mods section reads. It scans `.claude-flow` for `<name>-mod` folders (the folder name
+ * must match /^[a-z0-9][a-z0-9-]{0,40}-mod$/) and keeps a file only when `version` is 1. Anything else you write is ignored by the console.
+ */
+export const STATUS_PATH = '.claude-flow/my-mod/status.json'
+
+/** What the console reads; `calls` is a number (not a per-tool object), `lastDenied` is a short reason, left out until the mod refuses something. */
+export type ModStatus = {
+ version: 1
+ updatedMs: number
+ startedMs: number
+ modVersion: string
+ summary: string
+ guard: boolean
+ calls: number
+ blocked: number
+ lastDenied?: string
+}
+
+/** The counters the mod keeps for one session. This template guards nothing, so `blocked` stays 0 and `guard` is false. */
+export type Counters = { calls: number; blocked: number; lastDenied?: string }
+
+export const newCounters = (): Counters => ({ calls: 0, blocked: 0 })
+
+/** Builds the document; pure, so a test can assert the shape without the engine. */
+export function modStatus(c: Counters, nowMs: number, startedMs: number): ModStatus {
+ return {
+ version: 1,
+ updatedMs: nowMs,
+ startedMs,
+ modVersion: '0.1.0',
+ summary: 'counts tool calls; guards nothing',
+ guard: false,
+ calls: c.calls,
+ blocked: c.blocked,
+ ...(c.lastDenied !== undefined && { lastDenied: c.lastDenied }),
+ }
+}
+
+export const statusText = (c: Counters, nowMs: number, startedMs: number): string => `${JSON.stringify(modStatus(c, nowMs, startedMs), null, 2)}\n`
diff --git a/plugins/ruflo-plugin-creator/templates/mod/tests/register.test.ts b/plugins/ruflo-plugin-creator/templates/mod/tests/register.test.ts
index 98ab56ea01..8d50d181a2 100644
--- a/plugins/ruflo-plugin-creator/templates/mod/tests/register.test.ts
+++ b/plugins/ruflo-plugin-creator/templates/mod/tests/register.test.ts
@@ -1,15 +1,21 @@
import { describe, expect, test, tier } from 'claude-code/testing'
+import { STATUS_PATH, statusText } from '../hooks/status'
+
tier('user')
describe('register', () => {
- test('counts tool calls in the status line and answers /my-mod-status', async ($, on) => {
+ test('counts tool calls in the status line, writes the status file and answers /my-mod-status', async ($, on) => {
const env = new Map<string, string>()
+ const files = 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('session.root', () => ({ value: '/work' }))
+ on('fs.write', ($, e) => (files.set(e.path, e.text), { value: undefined }))
+ on('clock.now', () => ({ value: 5_000 }))
on('tool.call', () => ({ result: 'ok' }))
on('command.run', () => ({ text: 'core' }))
@@ -19,6 +25,7 @@ describe('register', () => {
await $.tool.call({ tool: 'Bash', command: 'ls' })
await $.tool.call({ tool: 'Bash', command: 'pwd' })
expect(statuses.at(-1)).toBe('my-mod Β· 2 tool calls')
+ expect(files.get(`/work/${STATUS_PATH}`)).toBe(statusText({ calls: 2, blocked: 0 }, 5_000, 5_000))
const { text } = await $.command.run({
command: 'my-mod-status',
diff --git a/plugins/ruflo-plugin-creator/templates/mod/tests/status.test.ts b/plugins/ruflo-plugin-creator/templates/mod/tests/status.test.ts
new file mode 100644
index 0000000000..3616a51a52
--- /dev/null
+++ b/plugins/ruflo-plugin-creator/templates/mod/tests/status.test.ts
@@ -0,0 +1,24 @@
+import { describe, expect, test, tier } from 'claude-code/testing'
+
+import { modStatus, STATUS_PATH } from '../hooks/status'
+
+tier('user')
+
+const FOLDER = /^[a-z0-9][a-z0-9-]{0,40}-mod$/
+
+describe('status contract', () => {
+ test('the path is .claude-flow/<name>-mod/status.json, a folder the console scans', () => {
+ const [dir, folder, file] = STATUS_PATH.split('/')
+ expect(dir).toBe('.claude-flow')
+ expect(folder).toMatch(FOLDER)
+ expect(file).toBe('status.json')
+ })
+
+ test('carries exactly the fields the console reads, calls as a number', () => {
+ const doc = modStatus({ calls: 3, blocked: 0 }, 9_000, 1_000)
+ expect(doc).toEqual({ version: 1, updatedMs: 9000, startedMs: 1000, modVersion: '0.1.0', summary: expect.any(String), guard: false, calls: 3, blocked: 0 })
+ expect(typeof doc.calls).toBe('number')
+ expect('lastDenied' in doc).toBe(false)
+ expect(modStatus({ calls: 1, blocked: 1, lastDenied: 'policy' }, 2, 1).lastDenied).toBe('policy')
+ })
+})