π 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
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
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.jsonindex 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.mdindex 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.mdnew file mode 100644index 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 specdiff --git a/plugins/ruflo-goals/scripts/smoke.sh b/plugins/ruflo-goals/scripts/smoke.shnew file mode 100755index 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