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.

1. 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.

2. 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

3. Configuration

Environment Variables

Variable	Default	Purpose
`RDF_HOME`	resolved from `bin/rdf`	RDF install root (canonical/, lib/, bin/, state/)
`RDF_CANONICAL`	`$RDF_HOME/canonical`	Canonical content source tree
`RDF_TARGET`	`~/.claude`	Deploy target for claude-code adapter

Most users do not need to override these — bin/rdf resolves paths from its own location automatically. Overrides matter only for multi-install setups or CI runs against a fixture tree.

Per-Project Setup

cd /path/to/project
/r-init                               # auto-detects profiles, generates governance

rdf init creates (inside the target project):

Path	Purpose
`CLAUDE.md`	Project working instructions (typically excluded from commits)
`.rdf/governance/`	conventions, constraints, verification, anti-patterns, architecture
`.rdf/memory/MEMORY.md`	Session-persistent project facts
`.git/info/exclude` entries	Working-file exclusions (CLAUDE.md, PLAN*.md, .rdf/, etc.)

Convention Inheritance

The most specific rule wins:

project CLAUDE.md   >   workspace CLAUDE.md   >   profile defaults   >   core defaults

Agents read the chain at session start and apply it hierarchically. A project CLAUDE.md rule overrides a profile default; a workspace CLAUDE.md rule overrides core.

Deployment Model

Emergency edits (direct changes to ~/.claude/) are permitted but must be pulled back to canonical via rdf sync. Drift is detected by rdf doctor --scope content-drift using per-file .rdf-hash sidecars.

canonical edits  -->  rdf generate  -->  deployed (~/.claude/, ~/.gemini/, etc.)
deployed edits  <--   rdf sync     <--   (emergency path)

4. Usage

4.1. Session Lifecycle Commands

Command	Purpose
`/r-init`	Initialize governance for a new or existing project
`/r-start`	Session initialization -- reload context, display project health
`/r-save`	End-of-session state sync -- PLAN.md, MEMORY.md, session log
`/r-mode`	Switch operational mode (development, security, performance, migration, refactoring, debugging, documentation)
`/r-status`	Project health dashboard -- pipeline position, plan progress, warnings
`/r-refresh`	Re-scan codebase and update governance files
`/r-sync`	Pull emergency edits from deployed location back to canonical
`/r-context-audit`	Measure Claude Code context overhead; scored report + drift detection

4.2. Design → Ship Pipeline Commands

Command	Dispatches	Purpose
`/r-spec`	--	Design: discover -> brainstorm -> write spec -> challenge review
`/r-plan`	reviewer	Plan: read spec -> decompose into PLAN.md -> challenge review
`/r-build [N\|--parallel]`	dispatcher	Execute: TDD cycle per phase with quality gates, parallel batch dispatch
`/r-verify`	qa	QA verification against diff or scope
`/r-test`	uat	User acceptance testing from end-user persona
`/r-review`	reviewer	Adversarial review in challenge or sentinel mode
`/r-verify-claim`	--	Falsifiable claim verification (5 classes) — invoked by reviewer on MUST-FIX assertions
`/r-audit`	3x reviewer + qa	Full codebase audit across all domains
`/r-audit-slop`	3x engineer + sentinel	Discovery-first AI slop audit with FP calibration
`/r-ship`	qa + reviewer	Release: preflight -> verify -> prep -> publish -> report
`/r-vpe`	--	Optional end-to-end pipeline orchestrator (spec->plan->build->ship)
`/r-tasks`	--	Read-only task list status -- check progress of long-running commands

4.3. Utility Commands (15)

Command	Purpose
`/r-util-mem-compact`	Archive stale MEMORY.md entries
`/r-util-mem-audit`	Fact-check MEMORY.md against live state
`/r-util-chg-gen`	Generate changelog from diff/commits
`/r-util-chg-dedup`	Deduplicate changelog entries
`/r-util-rel-squash`	Release branch squash plan + execution
`/r-util-doc-gen`	Generate publication-ready documentation
`/r-util-ci-gen`	Generate GitHub Actions CI workflow
`/r-util-lib-sync`	Cross-project shared library drift detection
`/r-util-lib-release`	Shared library release lifecycle
`/r-util-proj-cross`	Cross-project convention drift analysis
`/r-util-code-scan`	Structured pattern-class bug finder
`/r-util-code-map`	AST-style structural map for large source files (context-efficient reads)
`/r-util-code-modernize`	Codebase modernization assessment
`/r-util-test-dedup`	Find duplicate/overlapping tests
`/r-util-test-scope`	Test tier recommendation + impact mapping

4.4. `rdf` CLI

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.

Command	Key Operations
`rdf generate <target>`	`claude-code`, `gemini-cli`, `codex`, `agents-md`, `all`
`rdf deploy <target>`	Symlink output to `~/.claude/`, `~/.gemini/`, etc.
`rdf profile list\|install\|remove\|status`	Manage active profiles with dependency resolution
`rdf init <path> [--type] [--tools] [--github]`	Project initialization with governance templates
`rdf doctor [--scope] [--all]`	7 checks: artifacts, drift, memory, plan, github, sync, content-drift
`rdf state [<path>]`	JSON snapshot in <1s -- no LLM calls
`rdf refresh [--scope]`	Re-scan codebase, update governance and state files
`rdf sync [--dry-run]`	Emergency: pull `~/.claude/` edits back to canonical
`rdf github setup\|sync-labels\|ecosystem-init\|ecosystem-add`	GitHub issue model + project boards

4.5. Exit Codes

Exit Code	Meaning
0	Success
1	Generic error — command failed, check failed, or FAIL findings reported
2	Invalid usage — bad arguments or unrecognized subcommand
3	Missing dependency — required binary (git, jq, sha256sum, etc.) not in PATH
4	File I/O error — expected file or directory not found / not readable
5	Drift or sync conflict — `rdf doctor` found divergence that requires user action

Run rdf <command> help for per-command exit semantics.

5. 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:

Adapter	Output	Deploy Target
Claude Code	YAML-frontmattered agents + markdown commands	`~/.claude/`
Gemini CLI	TOML commands + YAML agents + GEMINI.md	`~/.gemini/`
Codex	Consolidated AGENTS.md + config.toml	Project root
AGENTS.md	Cross-tool documentation	Project root

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

Profile	Depth	Security Coverage	Refs
core	Commit protocol, verification, AI agent discipline	Secrets, input validation, injection defense	3
shell	Quoting, portability, error handling, process management	Command injection, TOCTOU races, SUID confusion	3
python	Typing, packaging, fixtures, async patterns	Deserialization, SSRF, import hijacking	3
frontend	Components, a11y (WCAG 2.1 AA), CSS, performance	XSS, CSRF, CSP, auth token storage	4
database	Schema design, migration safety, query discipline	SQL injection, least privilege, RLS	4
go	Error handling, concurrency, interfaces, modules	Race conditions, TLS config, deserialization	3
rust	Ownership, error handling, unsafe discipline, cargo	Unsafe without invariants, yanked crates	3
typescript	Strict mode, async discipline, Node.js backend	Prototype pollution, dependency confusion	3
perl	strict/warnings, three-arg open, regex security, taint mode	Regex DoS, taint bypass, injection via open()	3
php	strict_types, PSR, parameterized queries, Laravel/Symfony	SQL injection, deserialization, SSRF, CSRF	3
infrastructure	Terraform, Kubernetes, Ansible, secrets, CI/CD	State file exposure, secret sprawl, RBAC drift	3

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.

Concurrent Session Safety

RDF is designed to be run in parallel against the same repository — different milestones in different terminals, partial work mid-flight in one session while another ships unrelated changes. As of 3.1.0 (Wave A), every session generates its own UUIDv7 RDF_SESSION_ID (inherited by all subagents), and all transient handoff files are scoped by it:

.rdf/work-output/
  phase-3-result-<SESSION_ID>.md
  vpe-progress-<SESSION_ID>.md
  build-progress-<SESSION_ID>.md
  sentinel-N-<SESSION_ID>.md

Three layers protect concurrent sessions from corrupting each other:

Layer	Mechanism	Where
Session-scoped state	UUIDv7 suffix on every transient file	`state/rdf-bus.sh` helpers
Worktree boundary	Pre-commit hook rejects out-of-scope commits	installed in every dispatched worktree
Pre-aggregation gate	Engineer dirty-check before build steps	`engineer.md` Setup

Plan authors can declare a **Tests-may-touch:** glob list (plan schema Rule 8) to pre-authorize trivial test-infra drift (≤30 lines, ≤3 files) without surfacing as out-of-scope. See docs/specs/2026-04-25-concurrent-sessions-design.md for the full 12-primitive design.

Adversarial Quality Gates

The dispatcher auto-derives verification depth from phase content:

Gate	Agent	Scope Trigger
G1	Self-report	All phases
G2	QA (rdf-qa)	scope:focused+
G3	Reviewer sentinel (rdf-reviewer)	scope:cross-cutting or scope:sensitive
G4	UAT (rdf-uat)	User-facing changes

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

6. The Pipeline

Design -> Plan -> Build -> Ship

Stage	Command	What Happens	Artifact
Design	`/r-spec`	Discover, brainstorm options, research, write spec, challenge review	`docs/specs/*.md`
Plan	`/r-plan`	Read spec, decompose into phases with TDD steps, challenge review	`PLAN.md`
Build	`/r-build [N\|--parallel]`	Dispatcher orchestrates: engineer implements, QA verifies, reviewer audits. Parallel dispatch for independent phases.	Committed code
Ship	`/r-ship`	Preflight checks, verification, release prep, publish, report	PR + git tag
VPE	`/r-vpe` (optional)	End-to-end pipeline orchestrator: intake -> spec -> plan -> build -> ship	All of the above

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
/r-audit-slop                         # 3x engineer discovery -> sentinel peer-review -> FP validation

Agent Roster

Agent	Model	Role	Tools
rdf-planner	opus	Design specs, implementation plans	Full read/write
rdf-dispatcher	sonnet	Phase orchestration, TDD cycles	Full read/write
rdf-engineer	opus*	Implementation via governance protocol	Full read/write
rdf-qa	sonnet	Verification gate (read-only)	Read + execute
rdf-reviewer	opus*	Adversarial review -- challenge + sentinel (read-only)	Read + execute
rdf-uat	sonnet	User acceptance from end-user persona (read-only)	Read + execute

*Dynamic model routing: dispatcher downgrades engineer to sonnet for scope:docs/scope:focused; challenge-mode reviewer dispatches on sonnet, sentinel stays opus.

Scripts (12)

Script	Purpose
context-bar.sh	Status line -- project, branch, phase, model
clone-conversation.sh	Fork current conversation to new session
half-clone-conversation.sh	Fork recent half of conversation
check-context.sh	Context window utilization check
setup.sh	First-run environment setup
color-preview.sh	Terminal color palette preview
test-half-clone.sh	Test harness for half-clone
subagent-stop.sh	Capture agent completion events
pre-commit-validate.sh	Pre-commit lint + anti-pattern greps
post-edit-lint.sh	Post-edit shellcheck on modified files
comment-metrics.sh	Per-file comment cruft metrics for shell source
comment-snapshot.sh	Comment metrics snapshot across shared library set

7. Architecture

Core Principles

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.
Governance-driven agents. Six universal agents shaped by per-project governance files, not baked-in domain knowledge. Same agent, different governance, different behavior.
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.
Not a runtime. Claude Code / Gemini CLI / Codex IS the runtime. RDF is the governance layer that tells the runtime how to behave.
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 content-drift -> detects divergence via .rdf-hash sidecars.

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/                      # 35 commands (/r- namespace)
|   |-- scripts/                       # 12 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, timeout-guarded)
|   |-- context-audit.sh               # Context weight audit -> JSON
|   +-- rotate-work-output.sh          # Age/size-based work-output rotation
+-- reference/                         # Diagrams, architecture docs

8. 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.

Metric	Value
Active servers	~350,000
Total commits (governed)	1,686
Production code	31,176 lines
Test code (BATS)	70,965 lines
Test cases	5,764
Governance framework	14,204 lines
Net code churn	+271K / -111K lines

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.

9. 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.

10. Extending RDF

Add a Command

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

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

Add an Agent

Create canonical/agents/<name>.md

Add metadata to adapters/claude-code/agent-meta.json:

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

rdf generate claude-code and verify frontmatter

Add a Profile

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

Add an Adapter

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

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

Onboard a Project

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.

11. Documentation

Document	Purpose
RDF.md	Architecture scope, risk analysis, directory structure
WORKFORCE.md	Agent workforce, pipeline diagrams, gate details
reference/diagrams.md	Mermaid diagrams: pipeline, architecture, ecosystem
CHANGELOG	Development history
CHANGELOG.RELEASE	Release notes (3.1.0)

License

RDF is released under the GNU General Public License v2.0 (GPL v2).

See LICENSE for the full text of the license.

6 agents -- 35 commands -- 12 scripts -- 11 profiles -- 4 adapters -- 7 modes

Name		Name	Last commit message	Last commit date
Latest commit History 327 Commits
.claude-plugin		.claude-plugin
.github/workflows		.github/workflows
adapters		adapters
assets		assets
bin		bin
canonical		canonical
docs		docs
lib		lib
modes		modes
profiles		profiles
reference		reference
schemas		schemas
state		state
tests		tests
.gitattributes		.gitattributes
.gitignore		.gitignore
CHANGELOG		CHANGELOG
CHANGELOG.RELEASE		CHANGELOG.RELEASE
CLAUDE.md		CLAUDE.md
CLAUDE.md.ref		CLAUDE.md.ref
RDF.md		RDF.md
README.md		README.md
VERSION		VERSION
WORKFORCE.md		WORKFORCE.md
context-bar.md		context-bar.md

Folders and files

Latest commit

History

Repository files navigation

RDF -- rfxn Development Framework

1. How It Works

2. Quick Start

3. Configuration

Environment Variables

Per-Project Setup

Convention Inheritance

Deployment Model

4. Usage

4.1. Session Lifecycle Commands

4.2. Design → Ship Pipeline Commands

4.3. Utility Commands (15)

4.4. rdf CLI

4.5. Exit Codes

5. What Makes RDF Different

Governance as Code

Multi-Adapter Delivery

Profiles + Modes

Concurrent Session Safety

Adversarial Quality Gates

6. The Pipeline

Design -> Plan -> Build -> Ship

Audit Pipeline

Agent Roster

Scripts (12)

7. Architecture

Core Principles

Data Flow

Directory Structure

8. Production Context

Project Ecosystem

9. Philosophy

10. Extending RDF

11. Documentation

License

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases 11

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

4.4. `rdf` CLI

Packages