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-sparc): v0.2.0 β€” adopt plugin contract + phase-to-plugin alignment table (ADR-0001)

Reuvence37f98c51e0
diff --git a/plugins/ruflo-sparc/.claude-plugin/plugin.json b/plugins/ruflo-sparc/.claude-plugin/plugin.json
index eab1a70afd..c597ca8c85 100644
--- a/plugins/ruflo-sparc/.claude-plugin/plugin.json
+++ b/plugins/ruflo-sparc/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "ruflo-sparc",
"description": "SPARC methodology β€” Specification, Pseudocode, Architecture, Refinement, Completion phases with gate checks",
- "version": "0.1.0",
+ "version": "0.2.0",
"author": {
"name": "ruvnet",
"url": "https://github.com/ruvnet"
@@ -14,6 +14,9 @@
"methodology",
"specification",
"architecture",
- "refinement"
+ "refinement",
+ "mcp",
+ "phase-gates",
+ "quality-gates"
]
}
diff --git a/plugins/ruflo-sparc/README.md b/plugins/ruflo-sparc/README.md
index 68b9fe1385..82c1110108 100644
--- a/plugins/ruflo-sparc/README.md
+++ b/plugins/ruflo-sparc/README.md
@@ -55,10 +55,56 @@ sparc report # Generate full SPARC methodology report with trace
| `sparc-gates` | Gate check results and history |
| `patterns` | Learned SPARC execution patterns |
+## Compatibility
+
+- **CLI:** pinned to `@claude-flow/cli` v3.6 major+minor.
+- **Verification:** `bash plugins/ruflo-sparc/scripts/smoke.sh` is the contract.
+
+## Phase-to-plugin alignment
+
+Each SPARC phase has a canonical handoff plugin that owns its deeper tooling:
+
+| Phase | Owner | What it provides |
+|-------|-------|-----------------|
+| **Specification** | [ruflo-goals](../ruflo-goals/docs/adrs/0001-goals-contract.md) (deep-research) | Multi-source research orchestration to gather requirements |
+| **Pseudocode** | `ruflo-sparc` (this plugin) | Pseudocode generation + complexity annotation |
+| **Architecture** | [ruflo-adr](../ruflo-adr/docs/adrs/0001-adr-plugin-pattern.md) + [ruflo-ddd](../ruflo-ddd/docs/adrs/0001-ddd-contract.md) | ADR creation + bounded-context modeling |
+| **Refinement** | [ruflo-jujutsu](../ruflo-jujutsu/docs/adrs/0001-jujutsu-contract.md) + ruflo-testgen | Diff-aware refactor + test gap analysis |
+| **Completion** | [ruflo-docs](../ruflo-docs/docs/adrs/0001-docs-contract.md) | Auto-generated documentation |
+
+This plugin orchestrates the lifecycle; sibling plugins do the deep work per phase.
+
+## Namespace coordination
+
+This plugin owns four AgentDB namespaces, all kebab-case compliant per [ruflo-agentdb ADR-0001 Β§"Namespace convention"](../ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md):
+
+| Namespace | Purpose |
+|-----------|---------|
+| `sparc-state` | Current phase tracking per feature |
+| `sparc-phases` | Phase artifacts (specs, pseudocode, ADRs, reports) |
+| `sparc-gates` | Gate check results and history |
+
+The reserved `patterns` (plural) namespace is consumed for cross-feature SPARC pattern learning β€” note the pluralization (different from the singular `pattern` ReasoningBank target). Reserved namespaces (`pattern`, `claude-memories`, `default`) MUST NOT be shadowed.
+
+## Verification
+
+```bash
+bash plugins/ruflo-sparc/scripts/smoke.sh
+# Expected: "11 passed, 0 failed"
+```
+
+## Architecture Decisions
+
+- [`ADR-0001` β€” ruflo-sparc plugin contract (phase-to-plugin alignment, namespace coordination, smoke as contract)](./docs/adrs/0001-sparc-contract.md)
+
## Related Plugins
-- `ruflo-ddd` -- Architecture phase uses DDD bounded context patterns
+- `ruflo-agentdb` β€” namespace convention owner; backing store for sparc-state/-phases/-gates
+- `ruflo-goals` β€” Specification phase deep-research
- `ruflo-adr` -- Architecture decisions recorded as ADRs in Phase 3
+- `ruflo-ddd` -- Architecture phase uses DDD bounded context patterns
+- `ruflo-jujutsu` -- Refinement phase diff analysis
+- `ruflo-docs` -- Completion phase documentation generation
## License
diff --git a/plugins/ruflo-sparc/docs/adrs/0001-sparc-contract.md b/plugins/ruflo-sparc/docs/adrs/0001-sparc-contract.md
new file mode 100644
index 0000000000..d33d738a14
--- /dev/null
+++ b/plugins/ruflo-sparc/docs/adrs/0001-sparc-contract.md
@@ -0,0 +1,54 @@
+---
+id: ADR-0001
+title: ruflo-sparc plugin contract β€” pinning, namespace coordination, ADR/DDD/Docs phase cross-references, smoke as contract
+status: Proposed
+date: 2026-05-04
+authors:
+ - reviewer (Claude Code)
+tags: [plugin, sparc, methodology, namespace, smoke-test]
+---
+
+## Context
+
+`ruflo-sparc` (v0.1.0) β€” SPARC methodology orchestrator (Specification, Pseudocode, Architecture, Refinement, Completion). 1 agent (`sparc-orchestrator`), 3 skills (`sparc-spec`, `sparc-implement`, `sparc-refine`), 1 command (`/ruflo-sparc`).
+
+The 5 SPARC phases each have a natural sibling-plugin alignment:
+
+| Phase | Sibling plugin | Purpose |
+|-------|----------------|---------|
+| **Specification** | `ruflo-goals` (deep-research) | Multi-source research orchestration to gather requirements |
+| **Pseudocode** | `ruflo-sparc` itself | Owned by this plugin |
+| **Architecture** | [`ruflo-adr`](../../ruflo-adr/docs/adrs/0001-adr-plugin-pattern.md) + [`ruflo-ddd`](../../ruflo-ddd/docs/adrs/0001-ddd-contract.md) | Architecture decisions and bounded contexts |
+| **Refinement** | [`ruflo-jujutsu`](../../ruflo-jujutsu/docs/adrs/0001-jujutsu-contract.md) + [`ruflo-testgen`](../../ruflo-testgen/) | Diff-aware refactor + test gap analysis |
+| **Completion** | [`ruflo-docs`](../../ruflo-docs/docs/adrs/0001-docs-contract.md) | Auto-generated documentation |
+
+ADR-0001 makes these phase-to-plugin alignments contractually documented so SPARC consumers know which sibling plugin owns each phase's deeper tooling.
+
+## Decision
+
+1. Add this ADR (Proposed).
+2. README augment: Compatibility (pin v3.6); Phase-to-plugin alignment table; Namespace coordination (claims `sparc-state`); Verification + Architecture Decisions sections.
+3. Bump `0.1.0 β†’ 0.2.0`. Keywords add `mcp`, `phase-gates`, `quality-gates`.
+4. `scripts/smoke.sh` β€” 11 structural checks: version + keywords; all 3 skills + agent + command with valid frontmatter; 5 SPARC phase names documented (Specification/Pseudocode/Architecture/Refinement/Completion); v3.6 pin; namespace coordination; phase-to-plugin alignment table present (cross-references to adr/ddd/jujutsu/testgen/docs); ADR Proposed; no wildcard tools.
+
+## Consequences
+
+**Positive:** SPARC's role as the orchestrator across the methodology family is now contractually documented. Each phase has an explicit canonical handoff plugin.
+
+**Negative:** none material.
+
+## Verification
+
+```bash
+bash plugins/ruflo-sparc/scripts/smoke.sh
+# Expected: "11 passed, 0 failed"
+```
+
+## Related
+
+- `plugins/ruflo-adr/docs/adrs/0001-adr-plugin-pattern.md` β€” Architecture phase
+- `plugins/ruflo-ddd/docs/adrs/0001-ddd-contract.md` β€” Architecture phase (bounded contexts)
+- `plugins/ruflo-jujutsu/docs/adrs/0001-jujutsu-contract.md` β€” Refinement phase (diff analysis)
+- `plugins/ruflo-docs/docs/adrs/0001-docs-contract.md` β€” Completion phase (documentation)
+- `plugins/ruflo-goals/docs/adrs/0001-goals-contract.md` β€” Specification phase (deep-research)
+- `plugins/ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md` β€” namespace convention
diff --git a/plugins/ruflo-sparc/scripts/smoke.sh b/plugins/ruflo-sparc/scripts/smoke.sh
new file mode 100755
index 0000000000..3799c5a0c8
--- /dev/null
+++ b/plugins/ruflo-sparc/scripts/smoke.sh
@@ -0,0 +1,91 @@
+#!/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 phase-gates quality-gates; do
+ grep -q "\"$k\"" "$ROOT/.claude-plugin/plugin.json" || miss="$miss $k"
+ done
+ [[ -z "$miss" ]] && ok || bad "missing keywords:$miss"
+fi
+
+step "2. all 3 skills + agent + command present with valid frontmatter"
+miss=""
+for s in sparc-spec sparc-implement sparc-refine; do
+ f="$ROOT/skills/$s/SKILL.md"
+ [[ -f "$f" ]] || { miss="$miss missing-$s"; continue; }
+ for k in 'name:' 'description:'; do
+ grep -q "^$k" "$f" || miss="$miss $s-no-$k"
+ done
+done
+[[ -f "$ROOT/agents/sparc-orchestrator.md" ]] || miss="$miss missing-agent"
+[[ -f "$ROOT/commands/ruflo-sparc.md" ]] || miss="$miss missing-command"
+[[ -z "$miss" ]] && ok || bad "$miss"
+
+step "3. all 5 SPARC phase names documented (Specification/Pseudocode/Architecture/Refinement/Completion)"
+F="$ROOT/README.md"
+miss=""
+for phase in Specification Pseudocode Architecture Refinement Completion; do
+ grep -q "$phase" "$F" || miss="$miss $phase"
+done
+[[ -z "$miss" ]] && ok || bad "missing phases:$miss"
+
+step "4. /sparc command covers 5 subcommands"
+F="$ROOT/commands/ruflo-sparc.md"
+[[ -s "$F" ]] && ok || bad "command file empty/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. sparc-* namespaces claimed (state, phases, gates)"
+F="$ROOT/README.md"
+miss=""
+for ns in sparc-state sparc-phases sparc-gates; do
+ grep -q "$ns" "$F" || miss="$miss $ns"
+done
+[[ -z "$miss" ]] && ok || bad "missing namespaces:$miss"
+
+step "8. phase-to-plugin alignment table present (cross-references to adr/ddd/jujutsu/docs/goals)"
+F="$ROOT/README.md"
+miss=""
+for plugin in ruflo-adr ruflo-ddd ruflo-jujutsu ruflo-docs ruflo-goals; do
+ grep -q "$plugin" "$F" || miss="$miss $plugin"
+done
+[[ -z "$miss" ]] && ok || bad "missing plugin cross-references:$miss"
+
+step "9. ADR-0001 exists with status Proposed"
+ADR="$ROOT/docs/adrs/0001-sparc-contract.md"
+[[ -f "$ADR" ]] && grep -qE "^status:[[:space:]]*Proposed" "$ADR" \
+ && ok || bad "ADR missing or status != Proposed"
+
+step "10. 5 phase gate criteria documented"
+F="$ROOT/README.md"
+miss=""
+for gate in 'acceptance criteria' 'error paths' 'circular deps' 'coverage' 'deployment checklist'; do
+ grep -q "$gate" "$F" || miss="$miss '${gate}'"
+done
+[[ -z "$miss" ]] && ok || bad "$miss"
+
+step "11. 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