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-autopilot): v0.2.0 β€” adopt plugin contract (ADR-0001, namespace coordination, smoke as contract)

Reuven36a01c41061f
diff --git a/plugins/ruflo-autopilot/.claude-plugin/plugin.json b/plugins/ruflo-autopilot/.claude-plugin/plugin.json
index 7305099cf7..a22c5224d8 100644
--- a/plugins/ruflo-autopilot/.claude-plugin/plugin.json
+++ b/plugins/ruflo-autopilot/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "ruflo-autopilot",
- "description": "Autonomous /loop-driven task completion with learning, prediction, and progress tracking",
- "version": "0.1.0",
+ "description": "Autonomous /loop-driven task completion with learning, prediction, and progress tracking β€” wraps 10 autopilot_* MCP tools (status/enable/disable/config/reset/log/progress/learn/history/predict)",
+ "version": "0.2.0",
"author": {
"name": "ruvnet",
"url": "https://github.com/ruvnet"
@@ -13,6 +13,10 @@
"autopilot",
"loop",
"autonomous",
- "learning"
+ "learning",
+ "prediction",
+ "progress-tracking",
+ "cache-aware",
+ "mcp"
]
}
diff --git a/plugins/ruflo-autopilot/README.md b/plugins/ruflo-autopilot/README.md
index 2022931892..571ceafa8b 100644
--- a/plugins/ruflo-autopilot/README.md
+++ b/plugins/ruflo-autopilot/README.md
@@ -28,3 +28,49 @@ Combines Ruflo's 10 autopilot MCP tools with Claude Code's native `/loop` + `Sch
- `autopilot-loop` -- How to run an autopilot /loop iteration
- `autopilot-predict` -- Use learned patterns to pick the next task
+
+## MCP surface (10 tools)
+
+| Tool | Purpose |
+|------|---------|
+| `autopilot_status` | Current autopilot state + learning stats |
+| `autopilot_enable` | Turn autopilot on for the project |
+| `autopilot_disable` | Turn autopilot off |
+| `autopilot_config` | Read/update configuration |
+| `autopilot_reset` | Clear learned patterns and progress (testing) |
+| `autopilot_log` | Append a structured log entry |
+| `autopilot_progress` | Progress summary across team/swarm/file checklists |
+| `autopilot_learn` | Train on a completed task; writes to `autopilot-patterns` |
+| `autopilot_history` | Browse past iterations |
+| `autopilot_predict` | Predict the optimal next action from learned patterns |
+
+All 10 are wired in `v3/@claude-flow/cli/src/mcp-tools/autopilot-tools.ts`.
+
+## Compatibility
+
+- **CLI:** pinned to `@claude-flow/cli` v3.6 major+minor.
+- **MCP surface:** the 10 tools above.
+- **Verification:** `bash plugins/ruflo-autopilot/scripts/smoke.sh` is the contract.
+
+## Cache-aware /loop integration
+
+Autopilot pairs with Claude Code's native `/loop` + `ScheduleWakeup` skills. The recommended fallback heartbeat is **270 seconds** β€” under the 5-minute prompt-cache TTL so the next wake-up reads conversation context cached. Going past 300s pays a cache-miss; rounding to 5 minutes is the worst-of-both case.
+
+For event-driven loops, arm a `Monitor` and let the 270s wake be the safety net.
+
+## Namespace coordination
+
+This plugin owns the `autopilot-patterns` AgentDB namespace (kebab-case, follows the convention from [ruflo-agentdb ADR-0001 Β§"Namespace convention"](../ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md)). Reserved namespaces (`pattern`, `claude-memories`, `default`) MUST NOT be shadowed.
+
+`autopilot_learn` writes to this namespace via `agentdb_pattern-store` semantics β€” see [ruflo-intelligence ADR-0001](../ruflo-intelligence/docs/adrs/0001-intelligence-surface-completeness.md) for the 4-step pipeline this feeds (RETRIEVE β†’ JUDGE β†’ DISTILL β†’ CONSOLIDATE).
+
+## Verification
+
+```bash
+bash plugins/ruflo-autopilot/scripts/smoke.sh
+# Expected: "10 passed, 0 failed"
+```
+
+## Architecture Decisions
+
+- [`ADR-0001` β€” ruflo-autopilot plugin contract](./docs/adrs/0001-autopilot-contract.md)
diff --git a/plugins/ruflo-autopilot/docs/adrs/0001-autopilot-contract.md b/plugins/ruflo-autopilot/docs/adrs/0001-autopilot-contract.md
new file mode 100644
index 0000000000..cccccd2281
--- /dev/null
+++ b/plugins/ruflo-autopilot/docs/adrs/0001-autopilot-contract.md
@@ -0,0 +1,47 @@
+---
+id: ADR-0001
+title: ruflo-autopilot plugin contract β€” pinning, namespace coordination, /loop integration, smoke as contract
+status: Proposed
+date: 2026-05-04
+authors:
+ - reviewer (Claude Code)
+tags: [plugin, autopilot, loop, learning, mcp, smoke-test]
+---
+
+## Context
+
+`ruflo-autopilot` wraps the 10 `autopilot_*` MCP tools at `v3/@claude-flow/cli/src/mcp-tools/autopilot-tools.ts:27, 49, 65, 79, 107, 124, 141, 168, 186, 212` (`status`, `enable`, `disable`, `config`, `reset`, `log`, `progress`, `learn`, `history`, `predict`). Plugin is at v0.1.0 with two skills + two commands, integrates with Claude Code's native `/loop` + `ScheduleWakeup` (270s default to keep the prompt cache warm).
+
+Surface count is correct (the plugin claims "10 autopilot MCP tools" and the source confirms 10). What's missing is the contract pattern every other plugin updated this session has adopted.
+
+## Decision
+
+1. Add this ADR (Proposed).
+2. README augment with Compatibility (pin v3.6), Namespace coordination (defers to ruflo-agentdb ADR-0001 Β§"Namespace convention"; claims `autopilot-patterns` as the owned namespace), Verification + Architecture Decisions sections. Cross-reference to Claude Code's `/loop` skill semantics.
+3. Bump `0.1.0 β†’ 0.2.0`. Keywords add `prediction`, `progress-tracking`, `cache-aware`, `mcp`.
+4. `scripts/smoke.sh` β€” 10 structural checks: version + keywords; all 10 `autopilot_*` tools referenced; both skills present with valid frontmatter; both commands present (`/autopilot`, `/autopilot-status`); README pins to v3.6; namespace coordination block; ScheduleWakeup 270s cache-aware note retained; ADR Proposed; no wildcard tools; agent file references `autopilot-patterns`.
+
+## Consequences
+
+**Positive:** plugin joins the cadence. The cache-aware 270s ScheduleWakeup pattern is now contractually documented (every other plugin's loop guidance can reference it).
+
+**Negative:** none material β€” plugin behavior unchanged.
+
+**Neutral:** no new MCP tools, no new skills. Documentation + smoke.
+
+## Verification
+
+```bash
+bash plugins/ruflo-autopilot/scripts/smoke.sh
+# Expected: "10 passed, 0 failed"
+```
+
+## Related
+
+- `plugins/ruflo-ruvector/docs/adrs/0001-pin-ruvector-0.2.25.md`
+- `plugins/ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md` β€” namespace convention
+- `plugins/ruflo-browser/docs/adrs/0001-browser-skills-architecture.md`
+- `plugins/ruflo-intelligence/docs/adrs/0001-intelligence-surface-completeness.md`
+- `plugins/ruflo-adr/docs/adrs/0001-adr-plugin-pattern.md`
+- `plugins/ruflo-aidefence/docs/adrs/0001-aidefence-contract.md` β€” 3-gate pattern
+- `v3/@claude-flow/cli/src/mcp-tools/autopilot-tools.ts` β€” 10 `autopilot_*` tool definitions
diff --git a/plugins/ruflo-autopilot/scripts/smoke.sh b/plugins/ruflo-autopilot/scripts/smoke.sh
new file mode 100755
index 0000000000..35df8c8b5d
--- /dev/null
+++ b/plugins/ruflo-autopilot/scripts/smoke.sh
@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# Structural smoke test for ruflo-autopilot v0.2.0 (ADR-0001).
+set -u
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+PASS=0
+FAIL=0
+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.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.0" ]]; then
+ bad "expected 0.2.0, got '$v'"
+else
+ miss=""
+ for k in prediction progress-tracking cache-aware mcp; do
+ grep -q "\"$k\"" "$ROOT/.claude-plugin/plugin.json" || miss="$miss $k"
+ done
+ [[ -z "$miss" ]] && ok || bad "missing keywords:$miss"
+fi
+
+step "2. all 10 autopilot_* MCP tools referenced in plugin docs"
+miss=""
+for t in autopilot_status autopilot_enable autopilot_disable autopilot_config autopilot_reset autopilot_log autopilot_progress autopilot_learn autopilot_history autopilot_predict; do
+ grep -rq "$t" "$ROOT" --include='*.md' || miss="$miss $t"
+done
+[[ -z "$miss" ]] && ok || bad "undocumented:$miss"
+
+step "3. both skills present with valid frontmatter"
+miss=""
+for s in autopilot-loop autopilot-predict; do
+ f="$ROOT/skills/$s/SKILL.md"
+ [[ -f "$f" ]] || { miss="$miss missing-$s"; continue; }
+ for k in 'name:' 'description:' 'allowed-tools:'; do
+ grep -q "^$k" "$f" || miss="$miss $s-no-$k"
+ done
+done
+[[ -z "$miss" ]] && ok || bad "$miss"
+
+step "4. both commands present (/autopilot + /autopilot-status)"
+[[ -f "$ROOT/commands/autopilot.md" ]] && [[ -f "$ROOT/commands/autopilot-status.md" ]] \
+ && ok || bad "command files missing"
+
+step "5. README pins @claude-flow/cli to v3.6"
+grep -qE "@claude-flow/cli.*v3\.6|v3\.6.*claude-flow/cli" "$ROOT/README.md" \
+ && ok || bad "v3.6 pin missing"
+
+step "6. README defers to ruflo-agentdb namespace convention"
+grep -q "ruflo-agentdb" "$ROOT/README.md" \
+ && grep -q "Namespace convention" "$ROOT/README.md" \
+ && ok || bad "namespace coordination block incomplete"
+
+step "7. README documents 270s cache-aware ScheduleWakeup"
+grep -qE "270 ?s|270 second" "$ROOT/README.md" \
+ && grep -qE "cache|prompt cache" "$ROOT/README.md" \
+ && ok || bad "cache-aware 270s note missing"
+
+step "8. autopilot-patterns namespace claimed"
+grep -q "autopilot-patterns" "$ROOT/README.md" \
+ && ok || bad "autopilot-patterns namespace not claimed in README"
+
+step "9. ADR-0001 exists with status Proposed"
+ADR="$ROOT/docs/adrs/0001-autopilot-contract.md"
+[[ -f "$ADR" ]] && grep -qE "^status:[[:space:]]*Proposed" "$ADR" \
+ && ok || bad "ADR missing or status != Proposed"
+
+step "10. no wildcard tool grants in skills"
+bad_skills=""
+for f in "$ROOT"/skills/*/SKILL.md; do
+ grep -q '^allowed-tools:[[:space:]]*\*' "$f" && bad_skills="$bad_skills $(basename $(dirname "$f"))"
+done
+[[ -z "$bad_skills" ]] && ok || bad "wildcard:$bad_skills"
+
+printf "\n%s passed, %s failed\n" "$PASS" "$FAIL"
+[[ $FAIL -eq 0 ]] || exit 1