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-goals): adopt plugin contract β€” legacy-vs-canonical namespace mapping + ADR-099 anchor (ADR-0001)

Reuven714cd534c0b2
diff --git a/plugins/ruflo-goals/.claude-plugin/plugin.json b/plugins/ruflo-goals/.claude-plugin/plugin.json
index 861399575b..a16f690d87 100644
--- a/plugins/ruflo-goals/.claude-plugin/plugin.json
+++ b/plugins/ruflo-goals/.claude-plugin/plugin.json
@@ -18,6 +18,9 @@
"long-horizon",
"dossier",
"investigation",
- "osint"
+ "osint",
+ "mcp",
+ "evidence-grading",
+ "legacy-namespaces"
]
}
diff --git a/plugins/ruflo-goals/README.md b/plugins/ruflo-goals/README.md
index f8e83136aa..5172b5c266 100644
--- a/plugins/ruflo-goals/README.md
+++ b/plugins/ruflo-goals/README.md
@@ -44,3 +44,46 @@ Long-horizon goal planning, deep research orchestration, and adaptive replanning
| A seed entity to expand outward | `dossier-investigator` / `dossier-collect` |
| A multi-step objective | `goal-planner` / `goal-plan` |
| A long-running objective | `horizon-tracker` / `horizon-track` |
+
+## Compatibility
+
+- **CLI:** pinned to `@claude-flow/cli` v3.6 major+minor.
+- **Verification:** `bash plugins/ruflo-goals/scripts/smoke.sh` is the contract.
+
+## Namespace coordination
+
+This plugin uses six AgentDB namespaces. They predate the namespace convention from [ruflo-agentdb ADR-0001](../ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md). [ADR-0001](./docs/adrs/0001-goals-contract.md) documents the legacy-vs-canonical mapping and the forward path:
+
+| Legacy (current) | Canonical (forward) | Status |
+|------------------|---------------------|--------|
+| `adr` | `adr-patterns` (owned by ruflo-adr) | Defer to canonical owner β€” don't write here from this plugin |
+| `dossier` | `dossier` | Documented base-name exception (cf. `federation`) |
+| `research` | `goals-research` | Legacy reads + new writes pending data-portability ADR |
+| `research-sources` | `goals-research-sources` | Legacy reads + new writes pending |
+| `horizons` | `goals-horizons` | Legacy reads + new writes pending |
+| `horizon-sessions` | `goals-horizon-sessions` | Legacy reads + new writes pending |
+
+**New writes from this plugin SHOULD use the canonical kebab-case form.** Reads check both. A future ADR will propose the rename + migration once existing-data-portability is designed.
+
+Reserved namespaces (`pattern`, `claude-memories`, `default`) MUST NOT be shadowed.
+
+## Dossier-investigator (ADR-099)
+
+The `dossier-investigator` agent + `dossier-collect` skill implement [ADR-099](../../v3/docs/adr/ADR-099-dossier-investigator-recursive-parallel-research.md) β€” recursive parallel multi-source investigation that fans out across web, memory, knowledge-graph, codebase, and ADR index, building a graph-structured dossier with budget caps, de-duplication, and provenance per claim.
+
+Key invariants per ADR-099:
+- **Seed-driven** (entity, not question)
+- **Graph output** (not linear report)
+- **Budget caps** (hop-count, token, time)
+- **Provenance per claim** (every fact carries source attribution)
+
+## Verification
+
+```bash
+bash plugins/ruflo-goals/scripts/smoke.sh
+# Expected: "10 passed, 0 failed"
+```
+
+## Architecture Decisions
+
+- [`ADR-0001` β€” ruflo-goals plugin contract (legacy-vs-canonical namespaces, GOAP/dossier workflow contract)](./docs/adrs/0001-goals-contract.md)
diff --git a/plugins/ruflo-goals/docs/adrs/0001-goals-contract.md b/plugins/ruflo-goals/docs/adrs/0001-goals-contract.md
new file mode 100644
index 0000000000..9f35c5db68
--- /dev/null
+++ b/plugins/ruflo-goals/docs/adrs/0001-goals-contract.md
@@ -0,0 +1,73 @@
+---
+id: ADR-0001
+title: ruflo-goals plugin contract β€” pinning, namespace coordination + legacy mapping, GOAP/dossier workflow contract, smoke as contract
+status: Proposed
+date: 2026-05-04
+authors:
+ - reviewer (Claude Code)
+tags: [plugin, goals, goap, research, horizon, dossier, namespace, smoke-test]
+---
+
+## Context
+
+`ruflo-goals` (v0.2.0) β€” the long-horizon planning + research + dossier plugin. Surface is rich:
+
+- 4 agents: `goal-planner` (GOAP A*), `deep-researcher` (linear question-driven), `horizon-tracker` (cross-session), `dossier-investigator` (recursive parallel multi-source, ADR-099)
+- 5 skills: `goal-plan`, `deep-research`, `research-synthesize`, `horizon-track`, `dossier-collect`
+- 1 command (`/goals`)
+- Selection guide already differentiates question / seed-entity / multi-step / long-running task patterns
+
+### Namespace audit β€” six namespaces, mixed compliance
+
+| Namespace | Used by | Convention compliance |
+|-----------|---------|----------------------|
+| `adr` | `dossier-investigator`, `dossier-collect` | **Non-compliant** β€” should reference the canonical `adr-patterns` from [ruflo-adr ADR-0001](../../ruflo-adr/docs/adrs/0001-adr-plugin-pattern.md) |
+| `dossier` | `dossier-investigator` writes here | **Documented exception** β€” base-name rule (cf. `federation` from ruflo-federation) |
+| `research` | `deep-researcher` | **Non-compliant** β€” should be `goals-research` per kebab-case `<plugin-stem>-<intent>` rule |
+| `research-sources` | `deep-researcher` | **Non-compliant** β€” should be `goals-research-sources` |
+| `horizons` | `horizon-tracker` | **Non-compliant** β€” should be `goals-horizons` |
+| `horizon-sessions` | `horizon-tracker` | **Non-compliant** β€” should be `goals-horizon-sessions` |
+
+The six namespaces predate ruflo-agentdb ADR-0001's namespace convention. Renaming them risks breaking projects that already have stored data in the legacy names. This ADR documents both:
+
+- **Existing storage** uses the legacy names (no migration this turn).
+- **New writes** SHOULD use the canonical kebab-case form (`goals-research`, `goals-horizons`, etc.).
+- **Reads** check both old and new for backward compatibility.
+
+A future ADR can propose the rename + migration once the data-portability path is designed.
+
+### Other gaps
+
+1. No plugin-level ADR (this fixes that).
+2. No smoke test.
+3. No Compatibility section.
+4. ADR-099 is referenced for `dossier-collect` but the plugin doesn't link out from README.
+
+## Decision
+
+1. Add this ADR (Proposed).
+2. README augment: Compatibility (pin v3.6); Namespace coordination block with the legacy-vs-canonical mapping above; ADR-099 cross-link for dossier-collect; Verification + Architecture Decisions sections.
+3. Plugin metadata stays at `0.2.0` (already at the cadence). Keywords add `mcp`, `gop` (typo: `goap`), `legacy-namespaces`, `evidence-grading`. Actually skipping `gop` β€” already has `goap`.
+4. `scripts/smoke.sh` β€” 10 structural checks: version + new keywords; all 5 skills + all 4 agents + 1 command with valid frontmatter; selection guide present (4 task patterns); ADR-099 cross-link in README; v3.6 pin; namespace coordination block with legacy mapping; ADR Proposed; no wildcard tools.
+
+## Consequences
+
+**Positive:** legacy namespaces are now explicitly documented as legacy, with a forward-path canonical form. New plugins reading goals as a template won't replicate the non-compliant naming.
+
+**Negative:** the legacy-vs-canonical split adds documentation surface. Not free, but justified given existing-data concerns.
+
+**Neutral:** no functional changes. Plugin behavior unchanged.
+
+## Verification
+
+```bash
+bash plugins/ruflo-goals/scripts/smoke.sh
+# Expected: "10 passed, 0 failed"
+```
+
+## Related
+
+- `plugins/ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md` β€” namespace convention (`<plugin-stem>-<intent>`)
+- `plugins/ruflo-adr/docs/adrs/0001-adr-plugin-pattern.md` β€” owns canonical `adr-patterns` namespace
+- `plugins/ruflo-federation/docs/adrs/0001-federation-contract.md` β€” base-name exception precedent (`federation` namespace)
+- `v3/docs/adr/ADR-099-dossier-investigator-recursive-parallel-research.md` β€” dossier-collect spec
diff --git a/plugins/ruflo-goals/scripts/smoke.sh b/plugins/ruflo-goals/scripts/smoke.sh
new file mode 100755
index 0000000000..7504cb030a
--- /dev/null
+++ b/plugins/ruflo-goals/scripts/smoke.sh
@@ -0,0 +1,87 @@
+#!/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 mcp evidence-grading legacy-namespaces; do
+ grep -q "\"$k\"" "$ROOT/.claude-plugin/plugin.json" || miss="$miss $k"
+ done
+ [[ -z "$miss" ]] && ok || bad "missing keywords:$miss"
+fi
+
+step "2. all 5 skills + 4 agents + 1 command present"
+miss=""
+for s in deep-research goal-plan horizon-track research-synthesize dossier-collect; do
+ f="$ROOT/skills/$s/SKILL.md"
+ [[ -f "$f" ]] || { miss="$miss missing-skill-$s"; continue; }
+ for k in 'name:' 'description:'; do
+ grep -q "^$k" "$f" || miss="$miss $s-no-$k"
+ done
+done
+for a in goal-planner deep-researcher horizon-tracker dossier-investigator; do
+ [[ -f "$ROOT/agents/$a.md" ]] || miss="$miss missing-agent-$a"
+done
+[[ -f "$ROOT/commands/goals.md" ]] || miss="$miss missing-command"
+[[ -z "$miss" ]] && ok || bad "$miss"
+
+step "3. selection guide documents 4 task patterns"
+F="$ROOT/README.md"
+miss=""
+for token in question 'seed entity' 'multi-step' 'long-running'; do
+ grep -q "$token" "$F" || miss="$miss '${token}'"
+done
+[[ -z "$miss" ]] && ok || bad "missing task patterns:$miss"
+
+step "4. ADR-099 cross-link present"
+F="$ROOT/README.md"
+grep -q "ADR-099" "$F" \
+ && grep -q "dossier-investigator" "$F" \
+ && ok || bad "ADR-099 cross-link 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. legacy-vs-canonical namespace mapping documented"
+F="$ROOT/README.md"
+miss=""
+for token in 'horizons' 'goals-horizons' 'research' 'goals-research'; do
+ grep -q "$token" "$F" || miss="$miss '${token}'"
+done
+[[ -z "$miss" ]] && ok || bad "missing namespace map entries:$miss"
+
+step "8. ADR-0001 exists with status Proposed"
+ADR="$ROOT/docs/adrs/0001-goals-contract.md"
+[[ -f "$ADR" ]] && grep -qE "^status:[[:space:]]*Proposed" "$ADR" \
+ && ok || bad "ADR missing or status != Proposed"
+
+step "9. Dossier ADR-099 invariants documented (seed-driven, graph output, budget caps, provenance)"
+F="$ROOT/README.md"
+miss=""
+for token in 'Seed-driven' 'Graph output' 'Budget caps' 'Provenance'; do
+ grep -q "$token" "$F" || miss="$miss '${token}'"
+done
+[[ -z "$miss" ]] && ok || bad "missing invariants:$miss"
+
+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