π 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): 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.jsonindex 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.mdindex 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.shindex 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'"; elsemiss=""for k in mcp scaffolding contract-bootstrap; dogrep -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.mdindex 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 already1. **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:**```bashclaude plugin validate <dir> # lists hooked events, $ calls, env reads/writesclaude plugin test <dir> # tests/*.test.ts on the engine kitclaude -p --plugin-dir <dir> "/<name>-status" # writes .claude-plugin/types/ and proves a live loadnpx 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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')+ })+})