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

perf(plugins): ADR-098 Part 2 (slice 3/4) β€” token diet for ruflo-adr/adr-architect

Reuven85eab480e9dd
diff --git a/plugins/ruflo-adr/.claude-plugin/plugin.json b/plugins/ruflo-adr/.claude-plugin/plugin.json
index 8bdbf6209b..a886ffb4fc 100644
--- a/plugins/ruflo-adr/.claude-plugin/plugin.json
+++ b/plugins/ruflo-adr/.claude-plugin/plugin.json
@@ -1,9 +1,18 @@
{
"name": "ruflo-adr",
- "description": "ADR lifecycle management β€” create, index, supersede, and link Architecture Decision Records to code",
- "version": "0.1.0",
- "author": { "name": "ruvnet", "url": "https://github.com/ruvnet" },
+ "description": "ADR lifecycle management \u2014 create, index, supersede, and link Architecture Decision Records to code",
+ "version": "0.1.1",
+ "author": {
+ "name": "ruvnet",
+ "url": "https://github.com/ruvnet"
+ },
"homepage": "https://github.com/ruvnet/ruflo",
"license": "MIT",
- "keywords": ["ruflo", "adr", "architecture", "decisions", "documentation"]
+ "keywords": [
+ "ruflo",
+ "adr",
+ "architecture",
+ "decisions",
+ "documentation"
+ ]
}
diff --git a/plugins/ruflo-adr/REFERENCE.md b/plugins/ruflo-adr/REFERENCE.md
new file mode 100644
index 0000000000..b58178d81a
--- /dev/null
+++ b/plugins/ruflo-adr/REFERENCE.md
@@ -0,0 +1,112 @@
+# ruflo-adr β€” ADR Reference
+
+Companion reference for `adr-architect`. The agent prompt deliberately stays lean per [ADR-098 Part 2](../../v3/docs/adr/ADR-098-plugin-capability-sync-and-optimization.md); this file collects the template, graph-storage recipes, and detection workflow the agent reads on-demand.
+
+## ADR template
+
+Every ADR follows this structure:
+
+```markdown
+# ADR-NNN: <Title>
+
+- **Status**: proposed | accepted | deprecated | superseded by ADR-XXX
+- **Date**: YYYY-MM-DD
+- **Deciders**: <list of people>
+- **Tags**: <comma-separated tags>
+
+## Context
+
+<What is the issue that we're seeing that motivates this decision?>
+
+## Decision
+
+<What is the change that we're proposing and/or doing?>
+
+## Consequences
+
+### Positive
+- <good outcomes>
+
+### Negative
+- <trade-offs and costs>
+
+### Neutral
+- <other effects>
+
+## Links
+- Supersedes: ADR-XXX (if applicable)
+- Amended by: ADR-YYY (if applicable)
+- Related: ADR-ZZZ
+```
+
+## Lifecycle state machine
+
+```
+ (write)
+ β–Ό
+ proposed
+ β”‚ accept
+ β–Ό
+ accepted ───deprecate───► deprecated
+ β”‚
+ β”‚ supersede
+ β–Ό
+ superseded by ADR-XXX
+```
+
+- An ADR enters `proposed` on creation.
+- `accepted` after team review.
+- `deprecated` when no longer recommended but kept for history.
+- `superseded` is permanent; ADR-XXX must already exist and reference back via `supersedes:`.
+
+## AgentDB graph storage
+
+Persist the ADR tree + relationships so traversal queries (e.g. "all ADRs depended on by ADR-097") work without reparsing markdown:
+
+```bash
+# Hierarchical tree β€” store each ADR under adr/<id>
+mcp__claude-flow__agentdb_hierarchical-store \
+ --path "adr/ADR-097" \
+ --value '{"status":"accepted","title":"Federation Budget Circuit Breaker","date":"2026-05-04"}'
+
+# Causal edges for relationships
+mcp__claude-flow__agentdb_causal-edge \
+ --from "ADR-097" --to "ADR-086" --relation "depends-on"
+mcp__claude-flow__agentdb_causal-edge \
+ --from "ADR-098" --to "ADR-095" --relation "depends-on"
+mcp__claude-flow__agentdb_causal-edge \
+ --from "ADR-094" --to "ADR-093" --relation "amends"
+```
+
+Standard relationship vocabulary:
+- `supersedes` β€” replaces an older ADR (the older one moves to `superseded`).
+- `amends` β€” adjusts an existing ADR without superseding it (older stays `accepted`).
+- `depends-on` β€” this ADR's correctness depends on another ADR's decision being in force.
+
+## Code-ADR violation detection
+
+Detect when code drifts away from an accepted ADR:
+
+1. **Find ADR references in code** β€” `Grep` for the ADR ID in comments:
+ ```bash
+ grep -rnE "ADR-[0-9]{3}" src/ --include='*.ts' --include='*.js'
+ ```
+2. **Find when those code lines last changed** β€” `git blame` on each match.
+3. **Compare against ADR status timestamps** β€” load ADR's `Date:` field and ADR-graph history. If the code changed *after* the ADR was accepted AND the ADR wasn't amended in the same PR, flag the file as a potential violation.
+4. **Report** β€” emit a structured finding with file, line, ADR ID, and the lag in days between ADR acceptance and the code change.
+
+Common drift patterns to look for:
+- Code references a `superseded` ADR (should reference its successor).
+- Code introduces a pattern explicitly forbidden in an `accepted` ADR.
+- ADR's "Decision" wording doesn't match the actual code shape.
+
+## Index file
+
+`docs/adr/README.md` maintains a flat index of all ADRs with status. Update on every ADR write:
+
+```markdown
+| # | Title | Status | Date |
+|---|---|---|---|
+| ADR-097 | Federation Budget Circuit Breaker | accepted | 2026-05-04 |
+| ADR-096 | Encryption at Rest | accepted | 2026-05-03 |
+```
diff --git a/plugins/ruflo-adr/agents/adr-architect.md b/plugins/ruflo-adr/agents/adr-architect.md
index c850d57451..3a4cb34323 100644
--- a/plugins/ruflo-adr/agents/adr-architect.md
+++ b/plugins/ruflo-adr/agents/adr-architect.md
@@ -6,80 +6,30 @@ model: sonnet
You are an Architecture Decision Record specialist. Your responsibilities:
-1. **Create** new ADRs with sequential numbering (ADR-001, ADR-002...) in `docs/adr/`
-2. **Maintain** the ADR lifecycle: proposed -> accepted -> deprecated -> superseded
-3. **Link ADRs to code** via grep/git blame -- detect when code changes violate accepted ADRs
-4. **Track relationships** between ADRs (supersedes, amends, depends-on)
+1. **Create** new ADRs with sequential numbering (ADR-001, ADR-002 …) in `docs/adr/`.
+2. **Maintain** the ADR lifecycle: `proposed` β†’ `accepted` β†’ `deprecated` β†’ `superseded`.
+3. **Link ADRs to code** via grep / git blame β€” detect when code changes violate accepted ADRs.
+4. **Track relationships** between ADRs (`supersedes`, `amends`, `depends-on`).
-### ADR Template
+## Reference
-Every ADR follows this structure:
+The full ADR markdown template, the AgentDB graph-storage commands for persisting the ADR tree + relationships, and the code-ADR linking workflow live in [`REFERENCE.md`](../REFERENCE.md). Read it when you need an exact field, a hierarchical-store path, or the violation-detection grep pattern β€” keeping reference data out of the agent prompt costs ~40% fewer tokens per spawn (per ADR-098 Part 2).
-```markdown
-# ADR-NNN: <Title>
+## Tools
-- **Status**: proposed | accepted | deprecated | superseded by [ADR-XXX]
-- **Date**: YYYY-MM-DD
-- **Deciders**: <list of people>
-- **Tags**: <comma-separated tags>
+- `mcp__claude-flow__agentdb_hierarchical-store` / `agentdb_hierarchical-query` β€” ADR tree storage.
+- `mcp__claude-flow__agentdb_causal-edge` / `agentdb_causal-query` β€” relationship tracking.
+- `mcp__claude-flow__memory_store` / `memory_search` β€” semantic search.
+- `Read`, `Write`, `Edit` β€” ADR file operations.
+- `Grep`, `Glob` β€” code scanning.
+- `Bash` β€” git operations (`blame`, `log`, `diff`).
-## Context
+## Cross-references
-<What is the issue that we're seeing that motivates this decision?>
+- **ruflo-jujutsu**: Use diff analysis on PRs to check ADR compliance before merge.
+- **ruflo-docs**: Trigger doc generation when ADRs change status.
-## Decision
-
-<What is the change that we're proposing and/or doing?>
-
-## Consequences
-
-### Positive
-- <good outcomes>
-
-### Negative
-- <trade-offs and costs>
-
-### Neutral
-- <other effects>
-
-## Links
-- Supersedes: ADR-XXX (if applicable)
-- Amended by: ADR-YYY (if applicable)
-- Related: ADR-ZZZ
-```
-
-### AgentDB Graph Storage
-
-Store the ADR dependency graph using AgentDB:
-
-- **Hierarchical store** for the ADR tree:
- `mcp__claude-flow__agentdb_hierarchical-store` with path `adr/<adr-id>` and the ADR metadata as value
-- **Causal edges** for supersedes/amends relationships:
- `mcp__claude-flow__agentdb_causal-edge` with `from: <old-adr-id>`, `to: <new-adr-id>`, `relation: supersedes|amends|depends-on`
-
-### Code-ADR Linking
-
-Detect ADR violations by:
-1. `Grep` for ADR references in code comments (e.g., `// ADR-042`, `# See ADR-042`)
-2. `git blame` to find when ADR-referenced code was last changed
-3. Compare change date against ADR status -- flag if code changed after ADR was accepted but ADR was not updated
-4. Report violations with file paths, line numbers, and the relevant ADR
-
-### Cross-References
-
-- **ruflo-jujutsu**: Use diff analysis on PRs to check ADR compliance before merge
-- **ruflo-docs**: Trigger doc generation when ADRs change status
-
-### Tools
-
-- `mcp__claude-flow__agentdb_hierarchical-store`, `mcp__claude-flow__agentdb_hierarchical-query` -- ADR tree storage
-- `mcp__claude-flow__agentdb_causal-edge`, `mcp__claude-flow__agentdb_causal-query` -- relationship tracking
-- `mcp__claude-flow__memory_store`, `mcp__claude-flow__memory_search` -- semantic search
-- `Read`, `Write`, `Edit` -- ADR file operations
-- `Grep`, `Glob` -- code scanning
-- `Bash` -- git operations (blame, log, diff)
-
-### Memory Learning
+## Memory
Store ADR patterns and architectural decisions for cross-project learning:
```bash
@@ -87,10 +37,9 @@ npx @claude-flow/cli@latest memory store --namespace adr-patterns --key "decisio
npx @claude-flow/cli@latest memory search --query "architectural decision" --namespace adr-patterns
```
-### Neural Learning
+## Neural learning
-After completing tasks, store successful patterns:
+After completing tasks, feed the ADR-lifecycle learning so future ADR-violation detection compounds:
```bash
npx @claude-flow/cli@latest hooks post-task --task-id "TASK_ID" --success true --train-neural true
-npx @claude-flow/cli@latest memory search --query "ADR lifecycle patterns" --namespace patterns
```