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

Reuvendf49b51766ba
diff --git a/plugins/ruflo-adr/.claude-plugin/plugin.json b/plugins/ruflo-adr/.claude-plugin/plugin.json
index a886ffb4fc..4970514085 100644
--- a/plugins/ruflo-adr/.claude-plugin/plugin.json
+++ b/plugins/ruflo-adr/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "ruflo-adr",
- "description": "ADR lifecycle management \u2014 create, index, supersede, and link Architecture Decision Records to code",
- "version": "0.1.1",
+ "description": "ADR lifecycle management \u2014 create, index, supersede, check compliance, and link Architecture Decision Records to code via AgentDB hierarchical store + causal edges (supersedes/amends/depends-on/related)",
+ "version": "0.2.0",
"author": {
"name": "ruvnet",
"url": "https://github.com/ruvnet"
@@ -13,6 +13,10 @@
"adr",
"architecture",
"decisions",
- "documentation"
+ "documentation",
+ "lifecycle",
+ "compliance",
+ "causal-graph",
+ "mcp"
]
}
diff --git a/plugins/ruflo-adr/README.md b/plugins/ruflo-adr/README.md
index 3c9cb37b01..e63b7ce2a1 100644
--- a/plugins/ruflo-adr/README.md
+++ b/plugins/ruflo-adr/README.md
@@ -50,11 +50,36 @@ proposed --> accepted --> deprecated
Relationships tracked as causal edges: `supersedes`, `amends`, `depends-on`, `related`.
+## Compatibility
+
+- **CLI:** pinned to `@claude-flow/cli` v3.6 major+minor.
+- **Verification:** `bash plugins/ruflo-adr/scripts/smoke.sh` is the contract.
+
+## Namespace coordination
+
+This plugin owns the `adr-patterns` AgentDB namespace. It defers to [ruflo-agentdb ADR-0001 Β§"Namespace convention"](../ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md) for naming rules. Reserved namespaces (`pattern`, `claude-memories`, `default`) MUST NOT be shadowed.
+
+`adr-patterns` follows kebab-case `<plugin-stem>-<intent>` per the convention. The plugin uses it for semantic ADR search and for cross-project pattern transfer (via `hooks_transfer` in `ruflo-intelligence`).
+
+## Verification
+
+```bash
+bash plugins/ruflo-adr/scripts/smoke.sh
+# Expected: "10 passed, 0 failed"
+```
+
+## Architecture Decisions
+
+- [`ADR-0001` β€” ruflo-adr plugin contract (pinning, namespace coordination, smoke as contract)](./docs/adrs/0001-adr-plugin-pattern.md)
+
## Related Plugins
-- `ruflo-ddd` -- Document domain decisions as ADRs
-- `ruflo-sparc` -- Architecture phase (Phase 3) produces ADRs
-- `ruflo-migrations` -- Schema change decisions recorded as ADRs
+- `ruflo-agentdb` β€” namespace convention owner; backing store for the ADR graph
+- `ruflo-ddd` β€” document domain decisions as ADRs
+- `ruflo-sparc` β€” Architecture phase (Phase 3) produces ADRs
+- `ruflo-migrations` β€” schema change decisions recorded as ADRs
+- `ruflo-jujutsu` β€” ADR-aware diff analysis on PRs
+- `ruflo-intelligence` β€” `hooks_transfer` ships ADR patterns across projects
## License
diff --git a/plugins/ruflo-adr/docs/adrs/0001-adr-plugin-pattern.md b/plugins/ruflo-adr/docs/adrs/0001-adr-plugin-pattern.md
new file mode 100644
index 0000000000..ad9b17f54e
--- /dev/null
+++ b/plugins/ruflo-adr/docs/adrs/0001-adr-plugin-pattern.md
@@ -0,0 +1,94 @@
+---
+id: ADR-0001
+title: ruflo-adr plugin contract β€” pinning, namespace coordination, smoke as contract, REFERENCE.md token-optimization pattern
+status: Proposed
+date: 2026-05-04
+authors:
+ - reviewer (Claude Code)
+tags: [plugin, adr, agentdb, namespace, token-optimization, smoke-test]
+---
+
+## Context
+
+`ruflo-adr` is the meta-plugin that manages ADR lifecycle for projects (this one included β€” every other plugin in this repo is documenting itself with an ADR-0001 by the very contract this plugin proposes). The plugin already shipped four useful pieces:
+
+- `agents/adr-architect.md` β€” agent contract pointing at `REFERENCE.md` for the heavy template (per ADR-098 Part 2 token-diet)
+- `commands/adr.md` β€” 7-subcommand dispatcher (`create | list | status | supersede | check | graph | search`)
+- 3 skills: `adr-create`, `adr-index`, `adr-review`
+- `REFERENCE.md` containing the markdown template, AgentDB graph paths, code-ADR linking patterns
+
+Gaps observed against the pattern established by `ruflo-ruvector` ADR-0001, `ruflo-agentdb` ADR-0001, `ruflo-browser` ADR-0001, `ruflo-intelligence` ADR-0001:
+
+1. **No plugin-level ADR** of its own (the plugin that manages ADRs has no ADR β€” meta-irony worth fixing).
+2. **No smoke test.** Every other plugin updated this session has a `scripts/smoke.sh` enforcing the contract.
+3. **Free-form namespace usage.** The agent + skills write to `adr-patterns` (kebab-case, follows the convention) but never cite the convention from `ruflo-agentdb` ADR-0001.
+4. **No Compatibility section.** Plugin doesn't pin to `@claude-flow/cli` v3.6.
+5. **Version `0.1.1`.** Pre-pattern. Bump to `0.2.0` to align the cadence.
+
+## Decision
+
+Five plugin-local edits. No changes to CLI source or AgentDB internals.
+
+### 1. Add this ADR
+
+`docs/adrs/0001-adr-plugin-pattern.md` (this file). Status `Proposed`. Cross-links the four sibling ADRs.
+
+### 2. README augmentation (no rewrite)
+
+Append three sections, retain everything that's there:
+
+- **Compatibility** β€” pin to `@claude-flow/cli` v3.6 (matches the cadence).
+- **Namespace coordination** β€” explicit deferral to `ruflo-agentdb` ADR-0001 Β§"Namespace convention". `adr-patterns` is the canonical namespace this plugin owns; the reserved namespaces (`pattern`, `claude-memories`, `default`) MUST NOT be shadowed.
+- **Architecture Decisions** β€” link to this ADR.
+- **Verification** β€” pointer to `scripts/smoke.sh`.
+
+### 3. Plugin metadata bump
+
+`plugin.json` moves `0.1.1 β†’ 0.2.0`. New keywords: `lifecycle`, `compliance`, `causal-graph`, `mcp`. Description re-states the AgentDB graph backing.
+
+### 4. Smoke contract (`scripts/smoke.sh`)
+
+10 checks:
+
+1. `plugin.json` declares `0.2.0` with the new keywords.
+2. All 3 skills present (`adr-create`, `adr-index`, `adr-review`) with valid frontmatter (name + description + allowed-tools).
+3. `commands/adr.md` covers all 7 subcommands (`create | list | status | supersede | check | graph | search`).
+4. Agent references `REFERENCE.md` (the token-optimization pattern from ADR-098 Part 2).
+5. Agent + skills use the `adr-patterns` namespace consistently.
+6. README has Compatibility section pinning to `@claude-flow/cli` v3.6.
+7. README has Namespace coordination section deferring to `ruflo-agentdb` ADR-0001.
+8. ADR file exists with status `Proposed`.
+9. `REFERENCE.md` exists and is non-empty.
+10. No skill grants wildcard tool access.
+
+### 5. Agent file: keep the existing namespace contract, drop nothing
+
+The agent already writes to `adr-patterns` (correct kebab-case form per the namespace convention). No changes needed beyond the namespace coordination cross-reference, which lives in the README, not the agent.
+
+## Consequences
+
+**Positive:**
+- Plugin joins the same contract every other plugin updated this session follows: pin β†’ ADR β†’ smoke β†’ namespace coordination.
+- The `adr-patterns` namespace is now contractually owned by this plugin (anyone else writing there is on notice).
+- Drift in subcommand coverage / skill inventory is now catchable in CI.
+
+**Negative:**
+- Bump from `0.1.1` to `0.2.0` is a one-minor jump. Justified by the new contract, not by behavior change.
+
+**Neutral:**
+- No new MCP tools, no new skills, no new commands. Documentation + smoke only.
+
+## Verification
+
+```bash
+bash plugins/ruflo-adr/scripts/smoke.sh
+# Expected: "10 passed, 0 failed"
+```
+
+## Related
+
+- `plugins/ruflo-ruvector/docs/adrs/0001-pin-ruvector-0.2.25.md` β€” pinning + smoke-as-contract precedent
+- `plugins/ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md` β€” namespace convention this plugin defers to
+- `plugins/ruflo-browser/docs/adrs/0001-browser-skills-architecture.md` β€” session-as-skill precedent
+- `plugins/ruflo-intelligence/docs/adrs/0001-intelligence-surface-completeness.md` β€” surface-completeness precedent
+- `plugins/ruflo-adr/REFERENCE.md` β€” heavy reference data (template, AgentDB paths) per ADR-098 Part 2 token-diet
diff --git a/plugins/ruflo-adr/scripts/smoke.sh b/plugins/ruflo-adr/scripts/smoke.sh
new file mode 100755
index 0000000000..348c31ca09
--- /dev/null
+++ b/plugins/ruflo-adr/scripts/smoke.sh
@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+# Structural smoke test for ruflo-adr 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)); }
+
+# 1. plugin.json bump + new keywords
+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 lifecycle compliance causal-graph mcp; do
+ grep -q "\"$k\"" "$ROOT/.claude-plugin/plugin.json" || miss="$miss $k"
+ done
+ [[ -z "$miss" ]] && ok || bad "missing keywords:$miss"
+fi
+
+# 2. All 3 skills present with valid frontmatter
+step "2. skills (adr-create, adr-index, adr-review) present with name/description/allowed-tools"
+miss=""
+for s in adr-create adr-index adr-review; 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"
+
+# 3. command covers all 7 subcommands
+step "3. /adr command covers all 7 subcommands"
+F="$ROOT/commands/adr.md"
+miss=""
+for sub in 'adr create' 'adr list' 'adr status' 'adr supersede' 'adr check' 'adr graph' 'adr search'; do
+ grep -q "$sub" "$F" || miss="$miss '${sub#adr }'"
+done
+[[ -z "$miss" ]] && ok || bad "missing:$miss"
+
+# 4. Agent references REFERENCE.md (ADR-098 Part 2 token-diet pattern)
+step "4. agent references REFERENCE.md (token-optimization pattern)"
+grep -q "REFERENCE.md" "$ROOT/agents/adr-architect.md" \
+ && ok || bad "REFERENCE.md cross-reference missing"
+
+# 5. adr-patterns namespace used consistently
+step "5. adr-patterns namespace referenced in agent + skills"
+miss=""
+grep -q "adr-patterns" "$ROOT/agents/adr-architect.md" || miss="$miss agent"
+grep -q "adr-patterns" "$ROOT/skills/adr-create/SKILL.md" || miss="$miss adr-create"
+grep -q "adr-patterns" "$ROOT/skills/adr-index/SKILL.md" || miss="$miss adr-index"
+[[ -z "$miss" ]] && ok || bad "missing in:$miss"
+
+# 6. README pins to @claude-flow/cli v3.6
+step "6. 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 "Compatibility pin to v3.6 missing"
+
+# 7. README has namespace coordination section
+step "7. README defers to ruflo-agentdb ADR-0001 namespace convention"
+grep -q "Namespace coordination" "$ROOT/README.md" \
+ && grep -q "ruflo-agentdb" "$ROOT/README.md" \
+ && grep -q "Namespace convention" "$ROOT/README.md" \
+ && ok || bad "namespace coordination block incomplete"
+
+# 8. ADR file exists with status Proposed
+step "8. ADR-0001 exists with status Proposed"
+ADR="$ROOT/docs/adrs/0001-adr-plugin-pattern.md"
+[[ -f "$ADR" ]] && grep -qE "^status:[[:space:]]*Proposed" "$ADR" \
+ && ok || bad "ADR missing or status != Proposed"
+
+# 9. REFERENCE.md exists and is non-empty
+step "9. REFERENCE.md exists and is non-empty"
+[[ -s "$ROOT/REFERENCE.md" ]] && ok || bad "REFERENCE.md missing or empty"
+
+# 10. No wildcard tool grants
+step "10. no skill grants wildcard tool access"
+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