mirror of
https://github.com/ruvnet/ruflo.git
synced 2026-09-14 14:01:28 +08:00
feat(ruflo-goals): adopt plugin contract — legacy-vs-canonical namespace mapping + ADR-099 anchor (ADR-0001)
Plugin already at v0.2.0 with 4 agents + 5 skills + 1 command. The contract pieces were missing, plus a real namespace audit finding: six namespaces predate ruflo-agentdb ADR-0001's <plugin-stem>-<intent> convention and are not compliant. Renaming risks breaking existing stored data. ADR-0001 documents the legacy-vs-canonical mapping: - adr → defer to canonical adr-patterns (owned by ruflo-adr) - dossier → documented base-name exception (cf. federation) - research → goals-research (legacy reads + new writes pending data portability ADR) - research-sources → goals-research-sources (same) - horizons → goals-horizons (same) - horizon-sessions → goals-horizon-sessions (same) New writes from this plugin SHOULD use the canonical kebab-case form; reads check both for backward compatibility. A future ADR will propose the rename + migration once the data-portability path is designed. - ADR-0001 (Proposed) at docs/adrs/0001-goals-contract.md - README adds Compatibility (pin v3.6), Namespace coordination with the legacy-vs-canonical mapping table, ADR-099 dossier-investigator block (seed-driven, graph output, budget caps, provenance per claim), Verification + Architecture Decisions sections - plugin.json keywords add mcp, evidence-grading, legacy-namespaces - scripts/smoke.sh — 10 structural checks: version + keywords, all 5 skills + 4 agents + command present, 4 task patterns in selection guide, ADR-099 cross-link, v3.6 pin, namespace coordination, legacy mapping entries, ADR Proposed, ADR-099 invariants documented, no wildcard tools Verification: bash plugins/ruflo-goals/scripts/smoke.sh → 10/10 Co-Authored-By: RuFlo <ruv@ruv.net>
This commit is contained in:
Reuven
@@ -18,6 +18,9 @@
|
||||
"long-horizon",
|
||||
"dossier",
|
||||
"investigation",
|
||||
"osint"
|
||||
"osint",
|
||||
"mcp",
|
||||
"evidence-grading",
|
||||
"legacy-namespaces"
|
||||
]
|
||||
}
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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
|
||||
Executable
+87
@@ -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
|
||||
Reference in New Issue
Block a user