git:20260819.750951d to git:20260902.62a338e

- # AGENTS.md — rfxn Development Framework

-

- Cross-tool project instructions. Generated by `rdf generate agents-md`.

-

- Agent Skills (slash commands) live under `.agents/skills/` — generate

- them with `rdf generate agent-skills`. Codex and Antigravity read that

- directory natively.

-

- ## Project Context

-

- rfxn Development Framework (RDF) — convention governance, agent pipelines, and project orchestration for the rfxn ecosystem (APF, BFD, LMD, Sigforge, shared libraries). All projects are Bash 4.1+ targeting CentOS 6 through modern distros.

-

- ## Operating Primitives

-

- # CLAUDE.md — Operating Primitives

-

- ## Trust but Verify

- - Cite grep output, file path, or commit hash for every "done". Green lint is not correct code; green tests are not correct features

- - Every finding is a hypothesis until verified in source. Formulate a counter-hypothesis (why the code might be correct) before reporting. Runtime, log, and user-reported signals carry far higher false-positive rates than code review

- - Verify every function, import, path, and CLI flag via `<tool> help`, grep, or filesystem. Never from plausibility. Hallucinated references are the #1 AI failure mode

- - Read the target file before editing. Patterns inferred across siblings diverge from the real ones. Never forward-copy values from memory or state files; re-read source for current state

- - State uncertainty explicitly. "I believe X but haven't verified" beats a confident wrong answer. "Bounded blast radius" is an assertion, not a proof

-

- ## Scope Discipline

- - After any fix, grep the whole codebase for the same pattern. Fix the class, not the instance

- - No refactors, abstractions, or features beyond the task. Remove dead code encountered in-path; do not defer

- - Respect scope boundaries. If dispatched for Phase 3, do not touch Phase 5's files

- - After three failed attempts, stop and reconsider the approach. Do not layer workarounds

- - Three similar lines beat a premature abstraction. Do not design for hypothetical future requirements

- - Earn the surface: a new command, mode, or always-on rule must demonstrably change agent behavior, or it is ceremony. Default to the least machinery — serial over parallel unless the work is provably breadth-first (see `reference/simplicity-budget.md`)

-

- ## Adversarial Review

- - Every non-trivial spec or plan gets a pre-impl challenge pass before code is written. A challenge that turns up 10+ findings means the plan was the weak link

- - Probe externals before the plan crystallizes: scale, protocols, auth, proxying, binary paths. Assumptions become plan rewrites. Probes take minutes, rewrites take days

- - Every non-trivial change gets a post-impl sentinel review before merge. Challenges must be answered with a fix or documented rebuttal. Silence is unacceptable

- - Every behavior change ships a regression case. Install, deploy, and runtime paths need real execution. Docker-only CI misses environment-specific bugs

- - Re-check reviewer-suggested remedies against plan invariants before applying. A suggested fix can violate constraints cited elsewhere in the same review

-

- ## Context Preservation

- - Delegate open-ended exploration over three queries to subagents. Protect the main context window

- - Subagent payloads are self-contained. Subagents cannot prompt users or read the parent's task list. Prime serial successors with prior commit SHAs and judgment calls so they inherit calibration

- - Brief subagents like a colleague who just walked in: goal, constraints, prior attempts, expected output shape. Terse prompts yield shallow work

- - Batch independent tool calls in parallel. Use targeted reads. Do not re-read unchanged files. Prefer grep and glob over full-directory reads

- - CLAUDE.md is constitutional: HOW to work, not WHAT exists. Exclude any value derivable from code in under three seconds. Nothing lints CLAUDE.md against source, so grep every named identifier, command, and count before trusting it

-

- ## Comment Discipline

- - Comments explain why, not what. Identifiers describe what; restating them in prose drifts on rename and bloats every edit's context. Under AI-assisted development this is a first-class cost, not a style preference

- - One-line function headers only (`# name args — purpose`). Multi-line reserved for out-parameter contracts, side effects, or non-obvious caller preconditions

- - Delete signature restatement. `# x: the user id` above `def f(x: UserId)` is pure cruft. Same rule for docstrings, JSDoc, and Go doc comments; the declaration is the source of truth

- - No banner separators. No tombstones (`# removed`, `# was: foo()`). No prose catalogues of flags or config in file headers. Git blame and declaration sites cover history and inventory

- - Keep load-bearing comments: platform quirks, suppression justifications (same-line), ticket or CVE references, non-obvious invariants, compatibility floors. These encode knowledge the reader cannot derive from the code

-

- ## Safe Execution

- - Ask before irreversible actions: push, force-push, delete, shared-config edits. Cost of pausing is low; cost of an unwanted action is high

- - Stage files explicitly by name; never `git add -A`. One commit per logical unit. Verify HEAD with `git log --oneline -3` before any `--amend`

- - After dispatched, parallel, or worktree work, confirm expected artifacts (commits, files, outputs) actually landed. Agent summaries describe intent, not result

- - Investigate unexpected state before deleting. Unfamiliar files, branches, or locks may be the user's in-progress work. Fix root causes; never `--no-verify` or `--force` around safety checks as a shortcut

- - End every multi-step task with a concise summary of what changed and what verification was run

-

- ## Architecture Overview

-

-

- Six categories. Each artifact has a fixed location, format, lifecycle, and

- ownership.

-

- ### Category 1: Governance (stable)

-

- Constraints, conventions, and reference documentation. Changed only when

- the framework evolves. Never contains volatile data.

-

- | Artifact | Location | Owner |

- |----------|----------|-------|

- | Parent CLAUDE.md | `<workspace>/CLAUDE.md` | Human |

- | Project CLAUDE.md | `<project>/CLAUDE.md` | Human |

- | Governance index | `<project>/.rdf/governance/index.md` | `/r-init` |

- | Governance files | `<project>/.rdf/governance/*.md` | `/r-init`, `/r-refresh` |

- | `ignore.md` | `<project>/.rdf/governance/ignore.md` | `/r-init`, `/r-refresh` (agents consume: grep-exclude input) |

- | Shared reference | `<workspace>/reference/*.md` | Human |

- | Project reference | `<project>/reference/*.md` | Human |

- **Rules:**

- - Parent CLAUDE.md is authoritative; project CLAUDE.md inherits, never repeats

- - Governance index is always loaded (~50 lines, ~100-150 tokens)

- - Other governance files loaded just-in-time by agents via index pointers

- - All governance artifacts excluded from git via `.git/info/exclude`

- ### Category 2: State (volatile)

- Current project status, roadmaps, and audit findings. Updated after every

- commit, phase completion, or audit run.

- | Artifact | Location | Owner | Mandatory |

- |----------|----------|-------|-----------|

- | MEMORY.md | Auto-memory dir | `/r-save` | All projects |

- | Active plan | `docs/plans/{date}-{topic}-plan.md` (canonical); root `PLAN.md` (legacy fallback) — resolved via `rdf_active_plan_path` | `/r-plan`, `/r-save` | When active work |

- | AUDIT.md | `<project>/AUDIT.md` | `/r-audit`, `/r-save` | After audit run |

- | spec-progress-<SESSION_ID>.md | `.rdf/work-output/` | `/r-spec` | During design |

- | ship-progress-<SESSION_ID>.md | `.rdf/work-output/` | `/r-ship` | During release |

- | vpe-progress-<SESSION_ID>.md | `.rdf/work-output/` | `/r-vpe` | During VPE pipeline |

- | build-progress-<SESSION_ID>.md | `.rdf/work-output/` | `/r-build` | During parallel build |

- | session-log.jsonl | `.rdf/work-output/` | `/r-save` | When active work |

- ## Result File Artifacts

- ### Agent Pipeline

- The dispatcher orchestrates a sequential pipeline. Each transition is a

- structured file in `.rdf/work-output/`.

- ```

- dispatcher ──[phase context]──→ engineer ──[result]──→ dispatcher

- │

- ┌──────────────────────────┤

- ▼ ▼

- qa ──[verdict]──→ reviewer ──[findings]──→

- dispatcher dispatcher

- │

- ▼

- uat ──[verdict]──→ dispatcher

- ```

- **Verification depth** is managed by the dispatcher. It classifies each

- phase by change scope, derived automatically from the file list,

- description, and governance context:

- docs — changelog, README, comments

- focused — single file, config, one function

- multi-file — 2+ files, standard feature/refactor work

- cross-cutting — install, CLI, cross-OS, breaking changes

- sensitive — security, shared libs, data migration

- Higher scope = more verification. The dispatcher manages this

- automatically. See dispatcher.md for the full derivation logic.

-

- ## Commands

-

- Lifecycle: /r-{name} (e.g. /r-init, /r-plan, /r-build, /r-ship, /r-review). Utility: /r-util-{subject}-{verb} (e.g. /r-util-mem-compact, /r-util-chg-gen). Run /r-build N to execute phase N of the active PLAN.md.

-

- ## Constraints & Boundaries

-

- Bash 4.1+ floor (CentOS 6). No ${var,,}, mapfile -d, declare -n, $EPOCHSECONDS. No global declare -A. command cp/mv/rm in source (not bare, not /usr/bin/). Double-quote all variables. Guard all cd with || exit 1.

-