RDF -- rfxn Development Framework

Governance-driven AI development for teams that ship to production.

RDF is a convention governance layer for AI coding agents. It sits between the human and the AI runtime (Claude Code, Gemini CLI, Codex), encoding project conventions, quality gates, and domain expertise into typed agent personas -- so the AI writes code that actually follows your rules.

This is not a drop-in framework. RDF is purpose-built for the rfxn ecosystem and shared as a reference for what disciplined AI-assisted development looks like. The value is the pattern: governance-driven agents, adversarial quality gates, convention inheritance, and context window management.

How It Works

Six universal agents handle every project. Their behavior is shaped by governance files initialized per-project -- not baked into prompts. A QA agent reviewing a bash firewall tool and a QA agent reviewing a Python pipeline follow different rules because their governance files are different, not because they are different agents.

Quick Start

# 1. Clone
git clone https://github.com/rfxn/rdf.git && cd rdf

# 2. Generate adapter output for your AI tool
bin/rdf generate claude-code          # or: gemini-cli, codex, agents-md, all

# 3. Deploy (symlinks -- regeneration auto-updates)
bin/rdf deploy claude-code            # or: bin/rdf deploy gemini-cli

# 4. Initialize a project with governance
cd /path/to/your/project
/r-init                               # auto-detects project type, suggests profiles

That's it. Your AI agent now has project-specific governance, quality gates, and domain expertise.

Verify:

bin/rdf doctor                        # health check: artifacts, drift, sync

What Makes RDF Different

Governance as Code

Every project gets its own governance files -- conventions, verification checks, anti-patterns, and constraints -- generated from profiles matched to the codebase. The AI reads these before every task. No more re-explaining your rules each session.

Multi-Adapter Delivery

Write content once in tool-agnostic markdown. Generate for any runtime:

bin/rdf generate all                  # builds all four in one pass

Profiles + Modes

Profiles are the codebase's DNA -- auto-detected from project structure, permanent, seeded at rdf init time. Eleven full profiles provide governance templates and reference docs. Multiple profiles stack automatically for multi-domain projects (rdf init --type rust,infrastructure).

Full profiles (governance template + 3-4 reference docs):

Modes are session-scoped overlays -- they change how agents think without modifying governance files. Seven modes cover different workflows: development (default), security, performance, migration, refactoring, debugging, documentation.

Adversarial Quality Gates

The dispatcher auto-derives verification depth from phase content:

The reviewer runs 4 adversarial passes: anti-slop, regression, security, performance. Security findings are MUST-FIX in security mode.

The Pipeline

Design -> Plan -> Build -> Ship

Enter at any point. Have a spec already? Start with /r-plan. Have a plan? Start with /r-build. Each command tells you the next step.

Audit Pipeline

/r-audit                              # parallel: 3x reviewer + 1x qa -> AUDIT.md

Agent Roster

Scripts (10)

Command Reference

Session Lifecycle

Design -> Ship Pipeline

Utilities (14)

Architecture

Core Principles

1. Canonical-first, adapter-delivered. All content lives as tool-agnostic markdown in canonical/. Adapters generate tool-specific output. Develop in canonical, deploy via rdf generate.

2. Governance-driven agents. Six universal agents shaped by per-project governance files, not baked-in domain knowledge. Same agent, different governance, different behavior.

3. Profiles are expertise, modes are methodology. Profiles define what the code is (shell, Python, frontend). Modes define how you work (development, security assessment). They compose independently.

4. Not a runtime. Claude Code / Gemini CLI / Codex IS the runtime. RDF is the governance layer that tells the runtime how to behave.

5. Convention over configuration. Project CLAUDE.md > profile defaults > core defaults. The most specific rule always wins.

Data Flow

canonical/          Adapter            Tool Deployment
  agents/*.md  -->  adapter.sh  -->  output/agents/*.md  -->  ~/.claude/agents/
  commands/*.md     (frontmatter      output/commands/*       ~/.claude/commands/
  scripts/*.sh       injection)       output/scripts/*.sh     ~/.claude/scripts/
                                                            (symlinks)

Normal: Edit canonical/ -> rdf generate -> symlinks auto-update.
Emergency: Edit ~/.claude/ -> rdf sync -> back to canonical.
Drift check: rdf doctor --scope sync -> detects divergence.

Directory Structure

rdf/
|-- bin/rdf                             # CLI dispatcher
|-- lib/
|   |-- rdf_common.sh                  # Shared helpers, profile system
|   +-- cmd/                           # Subcommands: generate, profile, init, doctor,
|                                      #   state, refresh, sync, github, deploy, dispatch, migrate
|-- canonical/
|   |-- agents/                        # 6 universal agents (pure markdown)
|   |-- commands/                      # 31 commands (/r- namespace)
|   |-- scripts/                       # 10 hook scripts (bash)
|   +-- reference/                     # Framework docs
|-- profiles/
|   |-- registry.json                  # Machine-readable profile catalog
|   |-- registry.md                    # Human-readable profile catalog
|   |-- detection-rules.md            # Auto-detection signals per profile
|   |-- core/                          # Always active -- commit protocol, security hygiene
|   |-- shell/                         # Bash/shell -- quoting, portability, BATS
|   |-- python/                        # Python -- typing, pytest, packaging
|   |-- frontend/                      # Web -- a11y, performance, CSS methodology
|   |-- database/                      # DB -- schema, migrations, engine-specific refs
|   |-- go/                            # Go -- concurrency, error handling, modules
|   |-- rust/                          # Rust -- ownership, unsafe, cargo
|   |-- typescript/                    # TypeScript -- strict, Node.js, async
|   |-- perl/                          # Perl -- strict/warnings, taint mode
|   |-- php/                           # PHP -- strict_types, PSR
|   +-- infrastructure/                # Terraform, K8s, Ansible
|-- modes/
|   |-- development/                   # Default TDD workflow
|   |-- security-assessment/           # Threat-model-first assessment
|   |-- performance-audit/             # Profiling and optimization
|   |-- migration/                     # Version/platform migration
|   |-- refactoring/                   # Behavior preservation
|   |-- debugging/                     # Hypothesis-driven troubleshooting
|   +-- documentation/                 # Read-then-write accuracy review
|-- adapters/
|   |-- claude-code/                   # CC adapter + metadata + hooks
|   |-- gemini-cli/                    # Gemini CLI adapter (TOML)
|   |-- codex/                         # Codex adapter (AGENTS.md)
|   +-- agents-md/                     # Cross-tool AGENTS.md
|-- state/rdf-state.sh                 # Project state -> JSON (<1s)
+-- reference/                         # Diagrams, architecture docs

CLI Reference

Usage: rdf <command> [subcommand] [options]

Commands:
  generate   Build tool-specific output from canonical sources
  deploy     Symlink generated output to tool deployment target
  profile    Manage active domain profiles
  init       Initialize projects with governance
  doctor     Check project health and convention drift
  state      Deterministic project state snapshot (JSON)
  refresh    Agent-driven governance and state updates
  sync       Pull deployed edits back to canonical sources
  github     GitHub Issues + Projects integration

Run 'rdf <command> help' for details.

Production Context

RDF governs development of security infrastructure deployed across ~350,000 active servers:

• APF (Advanced Policy Firewall) -- network access control and rate limiting
• LMD (Linux Malware Detect) -- filesystem malware scanning with daily signature updates
• BFD (Brute Force Detection) -- real-time authentication attack detection

Daily check-ins from government (NIST, NOAA, NIH), defense (NATO CCDCOE), universities (Stanford, Harvard), telecom (Deutsche Telekom, Vodafone, Telefonica), and infrastructure providers (AWS, Hetzner, OVHcloud, DigitalOcean) across cPanel, Plesk, and bare-metal environments.

What goes wrong when code is wrong: A false positive in LMD quarantines legitimate files on every server that pulls the update. A regression in APF rule parsing locks administrators out of their own servers. A threshold change in BFD floods block lists or stops detecting real attacks. These are security tools -- a regression changes the security posture of hundreds of thousands of machines.

Project Ecosystem

PRODUCTS                    SHARED LIBRARIES
+-----------------+         +-------------+
| APF   2.0.2     |---------| tlog_lib    | structured logging
| BFD   2.0.2     |---------| alert_lib   | Slack/email alerts
| LMD   2.0.1     |---------| elog_lib    | event logging
+-----------------+         | pkg_lib     | package management
+-----------------+         | geoip_lib   | IP geolocation
| Sigforge  1.2.0 |         | batsman     | BATS test infra
| geoscope  1.1.0 |         +-------------+
+-----------------+

All projects share: batsman test infrastructure, parent CLAUDE.md conventions, RDF governance pipeline, GitHub label taxonomy.

Philosophy

Governance overhead is proportional to blast radius. Security tools running on 350,000 servers need more quality gates than a weekend project. RDF scales governance to risk.

Agents are context buffers, not general-purpose. A QA agent loaded with only the diff, test results, and verification protocol catches issues that a general-purpose agent with full context would miss. Narrow context, deep expertise.

Convention inheritance beats documentation. Projects inherit conventions from profiles and parent governance files. The AI reads them automatically. No one needs to remember to brief the model on project rules.

Trust is earned with evidence, not claims. Every quality gate requires specific evidence -- grep output, test results, commit hashes. "I checked and it's fine" is not acceptable.

Extending RDF

1. Create canonical/commands/<name>.md (pure markdown, no frontmatter)
2. rdf generate claude-code to deploy
3. Add to command table in README

Commands use /r-<name> (lifecycle) or /r-util-<subject> (utility).

1. Create canonical/agents/<name>.md
2. Add metadata to adapters/claude-code/agent-meta.json:

   "<name>": {
     "name": "rdf-<name>",
     "description": "...",
     "tools": ["Bash", "Read", "Glob", "Grep"],
     "model": "sonnet"
   }
   

3. rdf generate claude-code and verify frontmatter

1. Add entry to profiles/registry.json and profiles/registry.md
2. Create profiles/<name>/governance-template.md + reference/
3. Add detection rules to profiles/detection-rules.md
4. rdf profile install <name> then rdf generate claude-code

1. Create adapters/<tool>/adapter.sh implementing <prefix>_generate_all()
2. Add case branch in lib/cmd/generate.sh
3. Study adapters/claude-code/adapter.sh as reference

Contract: read from ${RDF_CANONICAL}, write to adapter output/. Never modify canonical.

rdf init /path/to/project --type shell --tools claude-code --github

Creates CLAUDE.md (from governance template), MEMORY.md, .git/info/exclude, and optionally GitHub labels + project board.

Documentation

6 agents -- 31 commands -- 10 scripts -- 11 profiles -- 4 adapters -- 7 modes

(C) 2026 R-fx Networks [email protected]