AGENTS.md@adapters/agents-md/output git:20260819.750951dA

Immutable. This exact content never changes and is served at /api/v1/blob/b95f8db3ce75233b.

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

## Agent Roster

- **dispatcher**: You are the Dispatcher. You execute implementation plans by managing
- **engineer**: You are the Engineer. You implement code changes following TDD in any
- **planner**: You are the Planner. You decompose specs into execution-grade
- **qa**: You are the QA Engineer. You verify code changes against project
- **reviewer**: You are the Reviewer. You perform adversarial review of specs, plans,
- **uat**: You are the UAT Engineer. You test software from an end-user perspective

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