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

3.7 KB
Raw Blame

ruflo-adr β€” ADR Reference

Companion reference for adr-architect. The agent prompt deliberately stays lean per ADR-098 Part 2; this file collects the template, graph-storage recipes, and detection workflow the agent reads on-demand.

ADR template

Every ADR follows this structure:

# 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:

# Hierarchical tree β€” store each ADR under its typed memory key
mcp__plugin_ruflo-core_ruflo__agentdb_hierarchical-store \
  --key "mem:ADR-097" \
  --tier "semantic" \
  --value '{"status":"accepted","title":"Federation Budget Circuit Breaker","date":"2026-05-04"}'

# Causal edges for relationships
mcp__plugin_ruflo-core_ruflo__agentdb_causal-edge \
  --sourceId "mem:ADR-097" --targetId "mem:ADR-086" --relation "depends-on"
mcp__plugin_ruflo-core_ruflo__agentdb_causal-edge \
  --sourceId "mem:ADR-098" --targetId "mem:ADR-095" --relation "depends-on"
mcp__plugin_ruflo-core_ruflo__agentdb_causal-edge \
  --sourceId "mem:ADR-094" --targetId "mem: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:
    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:

| # | Title | Status | Date |
|---|---|---|---|
| ADR-097 | Federation Budget Circuit Breaker | accepted | 2026-05-04 |
| ADR-096 | Encryption at Rest | accepted | 2026-05-03 |