Architecture

RDF is a governance layer, not a runtime. Claude Code, Codex and Antigravity CLI do the work. RDF tells them how to behave.

  1. Design principles
  2. Philosophy
  3. Data flow
  4. Adapters
  5. Repository layout
  6. Scripts
  7. Diagrams

Design principles

Principle What it means
Canonical-first, adapter-delivered Content lives as tool-agnostic markdown in canonical/. Adapters generate tool-specific output
Governance-driven agents Universal agents are shaped by per-project governance, not baked-in domain knowledge. Same agent, different governance, different behavior
Profiles are expertise, modes are methodology Profiles define what the code is. Modes define how you work. They compose independently
Convention over configuration The most specific rule always wins

Philosophy

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

Agents are context buffers, not general-purpose. Narrow context produces deep review. See Agents.

Convention inheritance beats documentation. Projects inherit conventions from profiles and parent governance files, and the AI reads them automatically. Nobody has to remember to brief the model.

Trust is earned with evidence, not claims. Every gate requires specifics: grep output, test results, commit hashes. “I checked and it’s fine” is not acceptable.

Data flow

canonical/          Adapter            Tool deployment
  agents/*.md  -->  adapter.sh   -->   output/agents/*.md     -->  ~/.claude/agents/
  commands/*.md     (frontmatter       output/skills/<n>/          ~/.claude/skills/<n>/
                    injection)           SKILL.md                  (per-skill symlinks)
  scripts/*.sh                         output/scripts/*.sh         ~/.claude/scripts/
Path Steps
Normal Edit canonical/, run rdf generate, and symlinks pick up the change. New commands also need rdf deploy
Emergency Edit ~/.claude/, then rdf sync pulls it back to canonical
Drift check rdf doctor --scope content-drift compares .rdf-hash sidecars

Adapters

Write content once in tool-agnostic markdown and generate for each runtime:

Adapter Output Deploy target
Claude Code YAML-frontmattered agents plus skills/<cmd>/SKILL.md with intent descriptions ~/.claude/
Claude Plugin The same skills layout, with /r-X rewritten to /rdf:r-X and output committed Plugin install, which clones the repo
Agent Skills .agents/skills/<cmd>/SKILL.md, shared by Codex and Antigravity CLI Workspace root
AGENTS.md Cross-tool documentation, composed per project Project root
Gemini CLI (legacy) TOML commands, YAML agents and GEMINI.md ~/.gemini/

Codex and Antigravity CLI are served by the Agent Skills and AGENTS.md composite, not a bespoke adapter. rdf generate all builds all five adapters in one pass. See Multi-tool parity.

Repository layout

rdf/
|-- bin/rdf                             # CLI dispatcher
|-- lib/
|   |-- rdf_common.sh                   # Shared helpers, profile system
|   +-- cmd/                            # One file per rdf subcommand
|-- canonical/
|   |-- agents/                         # 7 universal agents (pure markdown)
|   |-- commands/                       # 38 commands (/r- namespace)
|   |-- scripts/                        # 16 hook and helper 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
|   +-- lite/                           # rdf-lite deploy source, not a registered profile
|-- modes/                              # 7 session-scoped overlays
|-- adapters/
|   |-- claude-code/                    # CC adapter, metadata and hooks
|   |-- claude-plugin/                  # Plugin adapter (namespaced, committed output)
|   |-- agent-skills/                   # Shared .agents/skills (Codex, Antigravity)
|   |-- gemini-cli/                     # Gemini CLI adapter (legacy tier)
|   +-- agents-md/                      # Cross-tool AGENTS.md composer
|-- state/
|   |-- rdf-state.sh                    # Project state as JSON
|   |-- rdf-tokens.sh                   # Local token usage report
|   |-- rdf-env.sh                      # Environment assessment
|   |-- context-audit.sh                # Context weight audit
|   +-- rotate-work-output.sh           # Age and size based rotation
+-- reference/                          # Diagrams and architecture docs

RDF.md has the file-level tree, the scope and the risk assessment.

Scripts

Sixteen scripts deploy to ~/.claude/scripts/.

Script Purpose
context-bar.sh Status line: project, branch, phase, model
session-start-inject.sh SessionStart hook: inject the lessons ID-index
session-start-context.sh SessionStart hook after compaction: re-inject the handoff
session-end-capture.sh SessionEnd hook: git snapshot to the session journal
precompact-snapshot.sh PreCompact hook: snapshot session state
state-bootstrap.sh SessionStart hook: deliver ~/.rdf/state helpers on plugin installs
subagent-stop.sh SubagentStop hook: capture agent completion events
pre-commit-validate.sh PreToolUse hook: pre-commit lint and anti-pattern greps
post-edit-lint.sh PostToolUse hook: bash -n syntax check on edited shell files
comment-metrics.sh Per-file comment cruft metrics for shell source
check-context.sh Context window utilization check
clone-conversation.sh Fork the current conversation to a new session
half-clone-conversation.sh Fork the recent half of a conversation
test-half-clone.sh Test harness for half-clone
setup.sh First-run environment setup
color-preview.sh Terminal color palette preview

Diagrams

reference/diagrams.md has Mermaid diagrams of the pipeline, architecture and ecosystem.