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(ruflo-console): 0.24.0 — Start here steps on pages with an order, ADR-423

ruv9716a2e48326
diff --git a/plugins/ruflo-console/.claude-plugin/plugin.json b/plugins/ruflo-console/.claude-plugin/plugin.json
index a779baae7b..fbe12c232a 100644
--- a/plugins/ruflo-console/.claude-plugin/plugin.json
+++ b/plugins/ruflo-console/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "ruflo-console",
"description": "ruflo's cockpit inside Claude Code and the one /ruflo command for every ruflo mod (function hooks, early access). Views: overview with health alerts, swarm topology graph, claims flow with TTL rings, federation map, plugin health matrix, learning curve and pipeline, MetaHarness radar and audit trend, memory, cost gauge, agent timeline, approvals queue, event stream, a main menu, an x.ruv.io federation board, an AI terminal (codex, claude or both in remembered sessions, streamed), Skills (npx skills), a Hive-Mind view, a MetaHarness lab, agent drill-down; a command palette for confirm-gated actions through the ruflo CLI; a band above the prompt. Reads ruflo's files and the CLI's local JSON; anything not measured reads n/a; no network by default.",
- "version": "0.23.0",
+ "version": "0.24.0",
"author": {
"name": "ruvnet",
"url": "https://github.com/ruvnet"
diff --git a/plugins/ruflo-console/hooks/views/pane.ts b/plugins/ruflo-console/hooks/views/pane.ts
index fbce64675b..bfcf2cf5d6 100644
--- a/plugins/ruflo-console/hooks/views/pane.ts
+++ b/plugins/ruflo-console/hooks/views/pane.ts
@@ -11,6 +11,7 @@ import { launchRows } from './launch'
import { donated, newAttention, panelOf, wrapKit } from './attention'
import { CARD_COLUMNS, hasCards, withCards } from './card'
import { groupedTabs } from './nav'
+import { stepsRows } from './steps'
import { optimizerResult } from './optimizer'
import { isBooting, isCompactPane, NAV_STYLES, VIEWS, type ViewId } from '../state'
import { agentView } from './agent'
@@ -310,7 +311,10 @@ export function paneView(base: Ctx): RenderElement {
// a launch ask is placed under its own row when nothing above held the origin.
const launch = ctx.state.palette.isOpen || ctx.state.isHelp ? [] : launchRows(bodyCtx)
- if (launch.length > 0) body = col(ctx, [body, ...launch], 'body')
+ // A page with an order leads with its Start here card (views/steps.ts), in cards only.
+ const steps = cardsOn ? stepsRows(bodyCtx) : []
+
+ if (launch.length > 0 || steps.length > 0) body = col(ctx, [...steps, body, ...launch], 'body')
// Placed under what was clicked: not drawn again at the top.
const confirm = attention.placed ? null : confirmRow(ctx)
diff --git a/plugins/ruflo-console/hooks/views/steps.ts b/plugins/ruflo-console/hooks/views/steps.ts
new file mode 100644
index 0000000000..9159cbf58c
--- /dev/null
+++ b/plugins/ruflo-console/hooks/views/steps.ts
@@ -0,0 +1,137 @@
+/**
+ * "Start here": a short, ordered card at the top of a page whose job has a real order (a swarm needs ruflo set up, then a swarm,
+ * then agents). Each step says what it does, shows whether the disk already has it (✔), marks the next one to do (▶) and carries
+ * the button that does it: a one-click start or run (each asks first, with the exact command on the confirm row), a field to
+ * type in, or the page where it happens. Where the disk cannot say whether a step is done (a score, a read), the steps are a
+ * numbered menu in order, each one a click. The card is collapsible, and gone once every step the disk can check is done.
+ */
+import type { RenderElement } from 'claude-code'
+
+import type { Snapshot } from '../data/snapshot'
+import type { StartId } from '../starts'
+import type { ViewId } from '../state'
+import { clip, row, section, text, THEME, type Ctx } from './common'
+
+type Go = { start: StartId } | { run: string } | { focus: string } | { view: ViewId } | { claim: true }
+type Step = { label: string; why: string; go: Go; /** Whether the disk already has it; absent when it cannot say. */ done?: (snapshot: Snapshot) => boolean }
+
+/** The pages with an order, and their steps. */
+export const STEPS: Partial<Record<ViewId, { title: string; steps: readonly Step[] }>> = {
+ overview: {
+ title: 'Set ruflo up here',
+ steps: [
+ { label: 'Initialise ruflo in this project', why: 'creates .claude-flow and the mods', go: { start: 'init' }, done: s => s.isRufloProject },
+ { label: 'Start the daemon', why: 'background workers: map, audit, optimize, consolidate', go: { start: 'daemon' }, done: s => s.daemon?.running === true },
+ { label: 'Start a swarm', why: 'hierarchical, up to 8 agents', go: { start: 'swarm' }, done: s => s.swarm !== null },
+ ],
+ },
+ swarm: {
+ title: 'Get a swarm going',
+ steps: [
+ { label: 'Initialise ruflo in this project', why: 'creates .claude-flow and the mods', go: { start: 'init' }, done: s => s.isRufloProject },
+ { label: 'Start a swarm', why: 'hierarchical, specialized, up to 8 agents', go: { start: 'swarm' }, done: s => s.swarm !== null },
+ { label: 'Spawn a coder', why: 'writes the code', go: { start: 'spawn-coder' }, done: s => s.agents.some(agent => agent.type === 'coder') },
+ { label: 'Spawn a tester', why: 'checks it', go: { start: 'spawn-tester' }, done: s => s.agents.some(agent => agent.type === 'tester') },
+ { label: 'Spawn a reviewer', why: 'reviews it', go: { start: 'spawn-reviewer' }, done: s => s.agents.some(agent => agent.type === 'reviewer') },
+ { label: 'Watch them work', why: 'who is busy, and when', go: { view: 'timeline' } },
+ ],
+ },
+ hive: {
+ title: 'Start a hive-mind',
+ steps: [
+ { label: 'Initialise ruflo in this project', why: 'creates .claude-flow and the mods', go: { start: 'init' }, done: s => s.isRufloProject },
+ { label: 'Start a hive-mind', why: 'a queen and raft consensus', go: { start: 'hive' }, done: s => s.hive !== null },
+ { label: 'Spawn three workers', why: 'the voters', go: { start: 'hive-workers' }, done: s => s.hiveAgents.length > 0 || (s.hive?.workers.length ?? 0) > 0 },
+ { label: 'Propose a decision', why: 'the workers vote on it', go: { focus: 'hive-propose' }, done: s => (s.hive?.pending.length ?? 0) + (s.hive?.history.length ?? 0) > 0 },
+ { label: 'Cast votes', why: 'every vote and ask, in one place', go: { view: 'approvals' }, done: s => (s.hive?.history.length ?? 0) > 0 },
+ ],
+ },
+ claims: {
+ title: 'Put work on the board',
+ steps: [
+ { label: 'Create a task', why: 'one line says what must be done', go: { focus: 'start-field-task' }, done: s => s.tasks.length > 0 },
+ { label: 'Claim it', why: 'one owner per task, with a time limit', go: { claim: true }, done: s => s.claims.length > 0 },
+ ],
+ },
+ learning: {
+ title: 'Teach ruflo this repo',
+ steps: [
+ { label: 'Start the daemon', why: 'its workers do the learning', go: { start: 'daemon' }, done: s => s.daemon?.running === true },
+ { label: 'Pretrain on this repo', why: 'seeds the patterns the router uses', go: { start: 'pretrain' }, done: s => (s.neural?.patterns ?? 0) > 0 || (s.sona?.patterns ?? 0) > 0 },
+ { label: 'Open the Learning Lab', why: 'train, predict, search and store patterns', go: { view: 'neural' } },
+ ],
+ },
+ federation: {
+ title: 'Join the federation',
+ steps: [
+ { label: 'Join the federation', why: 'registers your own key (it asks first)', go: { start: 'federation-join' }, done: s => s.hasNostrKey === true },
+ { label: 'Read the public announcements', why: 'pub:announce, signed by the swarm', go: { start: 'channel-read' } },
+ { label: 'Open the x.ruv.io board', why: 'registry, roster, work claims, AgentBBS', go: { view: 'xruv' } },
+ ],
+ },
+ metaharness: {
+ title: 'Check your harness',
+ steps: [
+ { label: 'Score the harness', why: 'five readiness axes and the cost per run', go: { run: 'mh-score' } },
+ { label: 'Scan the MCP surface', why: 'static findings, by severity', go: { run: 'mh-mcp-scan' } },
+ { label: 'See the audit trend', why: 'the newest audit against the one before', go: { run: 'mh-trend' } },
+ ],
+ },
+ memory: {
+ title: 'Look at your memory',
+ steps: [
+ { label: 'See what is stored', why: 'entries, storage, oldest and newest', go: { run: 'mem-stats' } },
+ { label: 'Check AgentDB health', why: 'which controllers are on', go: { run: 'mem-health' } },
+ { label: 'Browse and search below', why: 'view, store and delete entries', go: { view: 'memory' } },
+ ],
+ },
+ plugins: {
+ title: 'Get the ruflo plugins',
+ steps: [
+ { label: 'Add the ruflo marketplace', why: 'so Claude Code can install its plugins', go: { start: 'marketplace' } },
+ { label: 'Open the Plugin Catalog', why: 'every plugin, mod and skill', go: { view: 'market' } },
+ ],
+ },
+}
+
+/** The "Start here" card for the page in front, or nothing: no steps for this page, every checkable step done, or no read yet. */
+export function stepsRows(ctx: Ctx): RenderElement[] {
+ const plan = STEPS[ctx.state.view]
+ const snapshot = ctx.state.snapshot
+
+ if (plan === undefined || snapshot === null || ctx.state.palette.isOpen || ctx.state.isHelp) return []
+
+ const done = plan.steps.map(step => step.done?.(snapshot) === true)
+ const checkable = plan.steps.filter(step => step.done !== undefined).length
+
+ // Every step the disk can check is done (and there is at least one): the card has done its job.
+ if (checkable > 0 && plan.steps.every((step, i) => step.done === undefined || done[i] === true)) return []
+
+ const next = done.findIndex((isDone, i) => !isDone && (plan.steps[i] as Step).done !== undefined)
+ const first = next >= 0 ? next : plan.steps.findIndex(step => step.done === undefined)
+ const count = done.filter(Boolean).length
+
+ const rows = plan.steps.map((step, i) => {
+ const isNext = i === first
+ const mark = done[i] === true ? '✔' : isNext ? '▶' : '○'
+ const press = () => {
+ if ('start' in step.go) ctx.act.start(step.go.start)
+ else if ('run' in step.go) void ctx.act.run(step.go.run)
+ else if ('focus' in step.go) ctx.act.focus(step.go.focus)
+ else if ('view' in step.go) ctx.act.view(step.go.view)
+ else ctx.act.claim()
+ }
+
+ return row(
+ ctx,
+ [
+ text(ctx, ` ${mark} ${i + 1}. ${step.label}`, { bold: isNext, ...(done[i] === true ? { color: THEME.ok } : isNext ? { color: THEME.head } : { dimColor: true }) }),
+ text(ctx, ` ${clip(step.why, Math.max(8, ctx.columns - step.label.length - 24))}`, { dimColor: true }),
+ ...(done[i] === true ? [] : [ctx.kit.Button({ key: `step-${ctx.state.view}-${i}`, label: isNext ? ' â–¸ do this ' : ' â–¸ ', ...(isNext ? { variant: 'primary' as const } : { plain: true as const }), onPress: press })]),
+ ],
+ `step-row-${i}`,
+ )
+ })
+
+ return [ctx.kit.Box({ key: 'steps', flexDirection: 'column', children: section(ctx, 'steps', `Start here: ${plan.title}`, checkable > 0 ? `${count} of ${checkable} done` : `${plan.steps.length} steps, in order`, rows) })]
+}
diff --git a/plugins/ruflo-console/scripts/smoke.sh b/plugins/ruflo-console/scripts/smoke.sh
index eed7bbfa46..16def4b759 100755
--- a/plugins/ruflo-console/scripts/smoke.sh
+++ b/plugins/ruflo-console/scripts/smoke.sh
@@ -11,9 +11,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 ruflo-console 0.23.0"
+step "1. plugin.json declares ruflo-console 0.24.0"
grep -q '"name": "ruflo-console"' "$ROOT/.claude-plugin/plugin.json" \
- && grep -q '"version": "0.23.0"' "$ROOT/.claude-plugin/plugin.json" && ok || bad "name/version"
+ && grep -q '"version": "0.24.0"' "$ROOT/.claude-plugin/plugin.json" && ok || bad "name/version"
step "2. hooks.json names exactly one module and no classic hook commands"
grep -q '"modules": \["./register.ts"\]' "$HOOKS/hooks.json" && ! grep -q '"command"' "$HOOKS/hooks.json" \
diff --git a/plugins/ruflo-console/tests/steps.spec.ts b/plugins/ruflo-console/tests/steps.spec.ts
new file mode 100644
index 0000000000..73c643a4e2
--- /dev/null
+++ b/plugins/ruflo-console/tests/steps.spec.ts
@@ -0,0 +1,57 @@
+/**
+ * "Start here" steps, pure: every step points at something that exists (a start, a run id, a page), the checks read the disk's
+ * facts the way they say, and the pages with an order are the ones that have steps. Run with
+ * npx vitest run plugins/ruflo-console/tests/steps.spec.ts
+ */
+import { describe, expect, it } from 'vitest'
+
+import { MEM_LAB } from '../hooks/memory-lab'
+import { LAB } from '../hooks/mh-lab'
+import { START_LABEL } from '../hooks/starts'
+import { VIEWS } from '../hooks/state'
+import { STEPS } from '../hooks/views/steps'
+
+const swarmSteps = STEPS.swarm?.steps ?? []
+const snapshot = (over: object) => ({ isRufloProject: true, swarm: null, agents: [], tasks: [], claims: [], hive: null, hiveAgents: [], daemon: null, neural: null, sona: null, hasNostrKey: null, ...over }) as never
+
+describe('start here steps', () => {
+ it('every step points at a start, a run, a field or a page that exists', () => {
+ const runs = new Set([...LAB.map(entry => entry.id), ...MEM_LAB.map(entry => entry.id)])
+ const views = new Set(VIEWS.map(view => view.id))
+
+ for (const [view, plan] of Object.entries(STEPS)) {
+ expect(views.has(view as never), view).toBe(true)
+ expect(plan?.steps.length, view).toBeGreaterThan(1)
+
+ for (const step of plan?.steps ?? []) {
+ const go = step.go
+
+ if ('start' in go) expect(START_LABEL[go.start], `${view}: ${step.label}`).toBeDefined()
+ else if ('run' in go) expect(runs.has(go.run), `${view}: ${go.run}`).toBe(true)
+ else if ('view' in go) expect(views.has(go.view), `${view}: ${go.view}`).toBe(true)
+ else if ('focus' in go) expect(go.focus, view).not.toBe('')
+ }
+ }
+ })
+
+ it('the swarm steps are done as the disk says: ruflo, a swarm, then each kind of agent', () => {
+ const done = (s: object) => swarmSteps.map(step => step.done?.(snapshot(s)) ?? null)
+
+ expect(done({ isRufloProject: false })).toEqual([false, false, false, false, false, null])
+ expect(done({ swarm: { id: 's' } })).toEqual([true, true, false, false, false, null])
+ expect(done({ swarm: { id: 's' }, agents: [{ type: 'coder' }, { type: 'tester' }] })).toEqual([true, true, true, true, false, null])
+ expect(done({ swarm: { id: 's' }, agents: [{ type: 'coder' }, { type: 'tester' }, { type: 'reviewer' }] })).toEqual([true, true, true, true, true, null])
+ })
+
+ it('the hive steps read the proposals and the decisions, and the claims steps the tasks and the claims', () => {
+ const hive = STEPS.hive?.steps ?? []
+ const claims = STEPS.claims?.steps ?? []
+
+ expect(hive.map(step => step.done?.(snapshot({ hive: { workers: [], pending: [{}], history: [] }, hiveAgents: [{}] })))).toEqual([true, true, true, true, false])
+ expect(claims.map(step => step.done?.(snapshot({ tasks: [{}], claims: [] })))).toEqual([true, false])
+ })
+
+ it('has steps for the pages with an order, and none for a page with no order of its own', () => {
+ expect(Object.keys(STEPS).sort()).toEqual(['claims', 'federation', 'hive', 'learning', 'memory', 'metaharness', 'overview', 'plugins', 'swarm'])
+ })
+})
diff --git a/plugins/ruflo-console/tests/steps.test.ts b/plugins/ruflo-console/tests/steps.test.ts
new file mode 100644
index 0000000000..760cec384f
--- /dev/null
+++ b/plugins/ruflo-console/tests/steps.test.ts
@@ -0,0 +1,55 @@
+/**
+ * The "Start here" card on a page with an order: in an empty project it leads the Swarm page with the first step marked next, the
+ * step's button asks before it runs anything (the confirm opens right under the step), and a project that already has everything
+ * the disk can check is not asked for again: its steps show done and the next one is marked.
+ */
+import { describe, expect, mock, test } from 'claude-code/testing'
+
+import { RUFLO_FILES } from './fixtures/ruflo-run'
+import { command, elementsOf, keyOf, paneAt, PLUGIN, SESSION, textOf, worldOf } from './fixtures/world'
+
+const keys = (tree: Parameters<typeof elementsOf>[0]) => elementsOf(tree, 'Button').map(keyOf)
+
+describe('start here', () => {
+ test('an empty project: the Swarm page leads with its steps, the first is next, and its button asks before it runs', { options: { boot: false } }, async ($, on) => {
+ const world = worldOf(on, {})
+
+ mock.clock(on)
+ await $.session.start(SESSION)
+ await $.command.run(command('swarm'))
+
+ const pane = await $.ui.mount({ ...paneAt(120), plugin: PLUGIN })
+ const first = await pane.drawn()
+ const text = textOf(first)
+
+ expect(text).toMatch(/START HERE: GET A SWARM GOING/i)
+ expect(text).toContain('â–¶ 1. Initialise ruflo in this project')
+ expect(text).toContain('0 of 5 done')
+ expect(text).toContain('â—‹ 2. Start a swarm')
+ expect(keys(first)).toEqual(expect.arrayContaining(['step-swarm-0', 'step-swarm-1', 'step-swarm-5']))
+
+ await pane.press({ key: 'step-swarm-0' })
+ expect(textOf(await pane.drawn())).toContain('Confirm: initialise ruflo in this project')
+ expect(world.runs.filter(argv => argv.includes('init'))).toEqual([])
+ await pane.press({ key: 'cancel' })
+ expect(world.runs.filter(argv => argv.includes('init'))).toEqual([])
+ await pane.unmount()
+ })
+
+ test('a project with ruflo and a swarm shows those steps done, and the next one marked', { options: { boot: false } }, async ($, on) => {
+ worldOf(on, RUFLO_FILES)
+ mock.clock(on)
+ await $.session.start(SESSION)
+ await $.command.run(command('swarm'))
+
+ const pane = await $.ui.mount({ ...paneAt(120), plugin: PLUGIN })
+
+ const text = textOf(await pane.drawn())
+
+ expect(text).toContain('✔ 1. Initialise ruflo in this project')
+ expect(text).toContain('✔ 2. Start a swarm')
+ expect(text).toMatch(/â–¶ [3-5]\. Spawn a/)
+ expect(text).toMatch(/[2-4] of 5 done/)
+ await pane.unmount()
+ })
+})
diff --git a/scripts/ci-test-baseline.txt b/scripts/ci-test-baseline.txt
index 04c34127e4..9e5322a7cb 100644
--- a/scripts/ci-test-baseline.txt
+++ b/scripts/ci-test-baseline.txt
@@ -179,3 +179,4 @@ plugins/ruflo-console/tests/evolve.test.ts
plugins/ruflo-console/tests/vector.test.ts
plugins/ruflo-console/tests/skills-secure.test.ts
plugins/ruflo-console/tests/xruv.test.ts
+plugins/ruflo-console/tests/steps.test.ts
diff --git a/v3/docs/adr/ADR-423-console-start-here-steps.md b/v3/docs/adr/ADR-423-console-start-here-steps.md
new file mode 100644
index 0000000000..b108a15b3c
--- /dev/null
+++ b/v3/docs/adr/ADR-423-console-start-here-steps.md
@@ -0,0 +1,42 @@
+# ADR 423: "Start here" steps on pages with an order
+
+Status: Accepted (ships in ruflo-console 0.24.0)
+
+Date: 2026 10 03
+
+Decision owner: Ruflo maintainers
+
+Scope: `plugins/ruflo-console`: `hooks/views/steps.ts`, `hooks/views/pane.ts`, `tests/steps.spec.ts`, `tests/steps.test.ts`.
+
+Extends: ADR 407, ADR 422 (cards). Companion to Mission Control's NEXT STEP box (ADR 409).
+
+## 1. Context
+
+Several pages are about a job with a real order: a swarm needs ruflo set up, then a swarm, then agents; a hive-mind needs a hive, then workers, then a proposal, then votes; learning needs the daemon and a pretrain. A page showed all of its parts at once, and the order lived in the person's head or in an empty-state sentence ("start a hierarchical one, then spawn agents into it"). Mission Control already answered this with a NEXT STEP to-do; the other pages had nothing like it.
+
+## 2. Decision
+
+A **Start here** card leads a page that has an order: a numbered list of steps, each with a status, a few words on why, and the button that does it.
+
+- **Status** is read from the disk the console already reads, not from a click: ✔ done, ▶ the next one (with a primary **do this** button), ○ later (a plain **▸** button, so any step can be done out of order). The header counts progress: "2 of 5 done".
+- **What a button does** is one of: a one-click start or run (each asks first, the confirm opens right under the step, and the exact command is on the confirm row), put the keys in the page's own field, open another page, or claim the selected task. Nothing runs without the confirm that ran before.
+- **Where the disk cannot say** whether a step is done (a score, a scan), the steps are a numbered menu in order, none marked done.
+- The card is a collapsible section like any other, and it **goes away once every step the disk can check is done**, so a set-up page is not cluttered by instructions it no longer needs.
+- Nine pages have steps: Overview (init, daemon, swarm), Swarm (init, swarm, coder, tester, reviewer, watch), Hive-Mind (init, hive, workers, propose, votes), Claims (task, claim), Learning (daemon, pretrain, the Learning Lab), Federation (join, read, the x.ruv.io board), MetaHarness (score, scan, trend), Memory Lab (stats, health, browse) and Plugins (the marketplace, the catalog). The steps are a table (`STEPS`), so another page is one entry.
+- Cards only: in a compact inline pane and in the plain-text dump the page is unchanged.
+
+## 3. Alternatives considered
+
+- **A wizard that walks the steps and hides the page.** Rejected: someone who knows ruflo must not be made to click through; the card is above the page, collapsible, and any step is open to any order.
+- **Steps from a click log.** Rejected: the disk is the truth (a swarm started in a terminal counts); a click log would be wrong the moment anything else touched the project.
+- **Steps on every page.** Rejected: most pages are a list to read or a lab with no order, and an invented order is noise.
+
+## 4. Consequences
+
+A first-time visitor of an empty project sees what to do and in what order, with one button for it. An established project sees no card on the pages whose steps are all done. The count and the marks cost nothing a page did not already read.
+
+## 5. Tests
+
+- `tests/steps.spec.ts` (pure): every step points at a start, a run, a field or a page that exists; the Swarm, Hive-Mind and Claims checks read the disk's facts as they say; only the pages with an order have steps.
+- `tests/steps.test.ts` (kit): in an empty project the Swarm page leads with its steps, the first marked next, its button asks before it runs and Cancel runs nothing; in a project with ruflo and a swarm those two steps show done and the next is marked.
+- The live smoke draws every page with its card.