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

Reuven0648218312bd
diff --git a/plugins/ruflo-docs/.claude-plugin/plugin.json b/plugins/ruflo-docs/.claude-plugin/plugin.json
index 23d780de23..9b7cd83a6f 100644
--- a/plugins/ruflo-docs/.claude-plugin/plugin.json
+++ b/plugins/ruflo-docs/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "ruflo-docs",
- "description": "Documentation generation, API docs, and drift detection",
- "version": "0.1.0",
+ "description": "Documentation generation, API docs (JSDoc/TSDoc/OpenAPI), and drift detection β€” drives the `document` background worker via hooks_worker-dispatch; uses Haiku model for cost-efficient docs work",
+ "version": "0.2.0",
"author": {
"name": "ruvnet",
"url": "https://github.com/ruvnet"
@@ -12,6 +12,9 @@
"ruflo",
"documentation",
"api-docs",
- "drift-detection"
+ "drift-detection",
+ "jsdoc",
+ "openapi",
+ "mcp"
]
}
diff --git a/plugins/ruflo-docs/README.md b/plugins/ruflo-docs/README.md
index 5b2f988f0f..4403cc104d 100644
--- a/plugins/ruflo-docs/README.md
+++ b/plugins/ruflo-docs/README.md
@@ -21,3 +21,52 @@ Documentation generation, drift detection, and API docs automation.
## Requires
- `ruflo-core` plugin (provides MCP server)
+
+## Compatibility
+
+- **CLI:** pinned to `@claude-flow/cli` v3.6 major+minor.
+- **Agent model:** Haiku (cost-efficient for docs work).
+- **Verification:** `bash plugins/ruflo-docs/scripts/smoke.sh` is the contract.
+
+## Document-worker contract
+
+Drives the `document` background worker (one of 12 workers in CLAUDE.md). Two invocation paths:
+
+```bash
+# CLI
+npx @claude-flow/cli@latest hooks worker dispatch --trigger document
+npx @claude-flow/cli@latest hooks worker dispatch --trigger document --scope api
+
+# MCP
+mcp tool call hooks_worker-dispatch --json -- '{"trigger": "document", "scope": "api"}'
+```
+
+| Scope | Output |
+|-------|--------|
+| (none) | Full project documentation pass |
+| `api` | API reference from JSDoc/TSDoc + OpenAPI 3.0 for HTTP endpoints |
+| `<file-path>` | Single-file doc generation |
+
+## Namespace coordination
+
+This plugin owns the `docs-drift` AgentDB namespace (kebab-case, follows the convention from [ruflo-agentdb ADR-0001 Β§"Namespace convention"](../ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md)). Used for drift-detection state (last-seen export hash per file). Reserved namespaces (`pattern`, `claude-memories`, `default`) MUST NOT be shadowed.
+
+`docs-drift` is accessed via `memory_*` tools (namespace-routed).
+
+## Verification
+
+```bash
+bash plugins/ruflo-docs/scripts/smoke.sh
+# Expected: "10 passed, 0 failed"
+```
+
+## Architecture Decisions
+
+- [`ADR-0001` β€” ruflo-docs plugin contract (document-worker integration, namespace coordination, smoke as contract)](./docs/adrs/0001-docs-contract.md)
+
+## Related Plugins
+
+- `ruflo-agentdb` β€” namespace convention owner
+- `ruflo-loop-workers` β€” defines the `document` background worker
+- `ruflo-adr` β€” ADRs trigger doc generation when status changes
+- `ruflo-sparc` β€” Documenter mode (Phase 5 Refinement) consumes this plugin
diff --git a/plugins/ruflo-docs/docs/adrs/0001-docs-contract.md b/plugins/ruflo-docs/docs/adrs/0001-docs-contract.md
new file mode 100644
index 0000000000..ff43a112a4
--- /dev/null
+++ b/plugins/ruflo-docs/docs/adrs/0001-docs-contract.md
@@ -0,0 +1,46 @@
+---
+id: ADR-0001
+title: ruflo-docs plugin contract β€” pinning, namespace coordination, document-worker integration, smoke as contract
+status: Proposed
+date: 2026-05-04
+authors:
+ - reviewer (Claude Code)
+tags: [plugin, docs, drift-detection, document-worker, namespace, smoke-test]
+---
+
+## Context
+
+`ruflo-docs` (v0.1.0): docs-writer agent (Haiku model β€” cost-efficient for docs work), 2 skills (`api-docs`, `doc-gen`), 1 command (`/ruflo-docs`). Drives the `document` background worker via `hooks_worker-dispatch`.
+
+Real surface used:
+- `mcp__claude-flow__hooks_worker-dispatch` with `trigger: "document"` (works; the `document` worker is one of the 12 background workers per CLAUDE.md)
+- `mcp__claude-flow__memory_store` for drift detection state
+- `Bash`, `Read`, `Write`, `Grep`, `Glob` for source/doc analysis
+
+Standard gaps: no plugin-level ADR, no smoke test, no Compatibility section, no namespace coordination.
+
+## Decision
+
+1. Add this ADR (Proposed).
+2. README augment: Compatibility (pin v3.6), Namespace coordination (claims `docs-drift`), document-worker contract (which trigger maps to which output), Verification + Architecture Decisions.
+3. Bump `0.1.0 β†’ 0.2.0`. Keywords add `jsdoc`, `openapi`, `mcp`.
+4. `scripts/smoke.sh` β€” 10 checks: version + keywords; both skills + agent + command with valid frontmatter; `hooks_worker-dispatch` referenced; `document` worker trigger documented; v3.6 pin; namespace coordination; ADR Proposed; no wildcard tools; agent uses Haiku model (cost-efficient cadence).
+
+## Consequences
+
+**Positive:** plugin joins the cadence. Document-worker integration becomes contractually documented.
+
+**Negative:** none.
+
+## Verification
+
+```bash
+bash plugins/ruflo-docs/scripts/smoke.sh
+# Expected: "10 passed, 0 failed"
+```
+
+## Related
+
+- `plugins/ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md`
+- `plugins/ruflo-adr/docs/adrs/0001-adr-plugin-pattern.md` β€” sibling docs cadence
+- `plugins/ruflo-loop-workers/...` β€” defines the `document` background worker
diff --git a/plugins/ruflo-docs/scripts/smoke.sh b/plugins/ruflo-docs/scripts/smoke.sh
new file mode 100755
index 0000000000..872aa1a694
--- /dev/null
+++ b/plugins/ruflo-docs/scripts/smoke.sh
@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+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 jsdoc openapi mcp; do
+ grep -q "\"$k\"" "$ROOT/.claude-plugin/plugin.json" || miss="$miss $k"
+ done
+ [[ -z "$miss" ]] && ok || bad "missing keywords:$miss"
+fi
+
+step "2. both skills present with valid frontmatter"
+miss=""
+for s in api-docs doc-gen; 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 "3. agent + command present"
+[[ -f "$ROOT/agents/docs-writer.md" ]] && [[ -f "$ROOT/commands/ruflo-docs.md" ]] \
+ && ok || bad "agent or command missing"
+
+step "4. hooks_worker-dispatch referenced for document trigger"
+miss=""
+grep -rq "hooks_worker-dispatch\|hooks worker dispatch" "$ROOT" --include='*.md' || miss="$miss dispatch-tool"
+grep -rqE 'trigger.+document|document.+trigger' "$ROOT" --include='*.md' || miss="$miss document-trigger"
+[[ -z "$miss" ]] && ok || bad "$miss"
+
+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. docs-drift namespace claimed"
+grep -q "docs-drift" "$ROOT/README.md" \
+ && ok || bad "docs-drift namespace not claimed"
+
+step "8. document-worker scope table documented"
+F="$ROOT/README.md"
+miss=""
+grep -q "Document-worker contract" "$F" || miss="$miss header"
+grep -qE 'scope.+api|api.+scope' "$F" || miss="$miss api-scope"
+[[ -z "$miss" ]] && ok || bad "$miss"
+
+step "9. ADR-0001 exists with status Proposed"
+ADR="$ROOT/docs/adrs/0001-docs-contract.md"
+[[ -f "$ADR" ]] && grep -qE "^status:[[:space:]]*Proposed" "$ADR" \
+ && ok || bad "ADR missing or status != Proposed"
+
+step "10. agent uses Haiku model (cost-efficient)"
+grep -qE "^model:[[:space:]]*haiku" "$ROOT/agents/docs-writer.md" \
+ && ok || bad "agent model is not Haiku"
+
+printf "\n%s passed, %s failed\n" "$PASS" "$FAIL"
+[[ $FAIL -eq 0 ]] || exit 1