A hybrid agent framework for small teams. Enforces information boundary architecture, GSD-style wave execution, and event-recorded approval gates.
Built for teams of any size — works with a dedicated architect or with a developer playing both roles on smaller projects.
Under the hood, RAD is a deterministic harness (the rad CLI in harness/,
which folds an append-only event log into gate decisions) wrapped in a framework
shell of slash commands and agent boundaries. The harness owns authority and
state; the shell owns ergonomics. See docs/harness-and-framework.md.
── Gate 0 (optional) ──
/rad-epic-decompose [epic #] (architect)
Shapes a GitHub epic into per-child stories
Writes .agents/epics/ — no plans, no commit
ARCHITECT / TEAM TEAM
──────────────── ────
/rad-research [prd or issue] /rad-plan [feature]
Consume spec artifact Explore sub-agent researches codebase
Clarify team + platform Returns bounded RESEARCH_SUMMARY
Write .agents/research/[slug] Generate + lint plan file
Cut rad/[feature] work branch
/rad-design [slug] Commit plan to that branch (no PR)
Read research artifact
Draft agent hierarchy /rad-adopt [issue or description]
Write .agents/architecture/ Same as /rad-plan, sourced from
[architect reviews + approves] a pre-existing issue or description
Generate .claude/agents/ files
── Gate 1 ──
/rad-approve (architect)
Reviews plan, records an `approved` event in
the feature's event log on the rad/[feature]
branch tip and pushes it. No PR — approval
lives in the event log on the branch
/rad-deliver [plan-file]
Gates on the approved event (`rad gate`)
Runs on the existing rad/[feature] branch
Each wave → fresh sub-agent context
Orchestrator carries only WAVE_RESULT
Atomic commit per task
Execution log appended per step
Opens the single deliver PR
── Gate 2 ──
Architect reviews the deliver PR
(rad/[feature] → default branch)
Plan doc + code land together
Standard code review, then merge
Every feature lives on a single rad/[feature] work branch, cradle to grave.
/rad-plan cuts it from the default branch and commits the plan doc to it.
/rad-approve records an approved event in the feature's event log
(.agents/state/<feature>/events.jsonl) on that branch's tip — that event is the
gate authority. /rad-deliver runs on the same branch and opens the one deliver
PR. The plan doc and the code reach the default branch together through that
single reviewed PR, which keeps contributors off the protected default branch.
There is no plan PR.
The default branch is whatever you set as default_branch: in CLAUDE.md
(resolved by scripts/get-default-branch.sh) — it is never hardcoded.
Gate 1 — Plan approval (architect runs /rad-approve)
- One file:
.agents/plans/[feature].mdon therad/[feature]branch - Architect reviews the approach before code is written
/rad-approverecords anapprovedevent in the feature's event log on the branch tip and pushes that branch — no PR, no merge to the default branch. (It also mirrorsStatus: approvedinto the plan doc, but that header is display only — the event is the authority.)- Blocked:
/rad-delivergates on the approved event viarad gate <feature> approvedat the branch tip
Gate 2 — Deliver PR (rad/[feature] → default branch)
- Plan doc and all implementation changes, together
- Architect reviews the output after execution
- Standard code review workflow, then merge
RAD delegates heavy context work to sub-agents so main sessions stay lean:
| Phase | What runs in a sub-agent | What stays in main context |
|---|---|---|
/rad-research URL input |
Haiku sub-agent: fetches and summarizes spec URL | Bounded SPEC_SUMMARY block |
/rad-design file generation |
Parallel Haiku sub-agents: one per agent file | Completion confirmations |
/rad-plan research |
Explore sub-agent: searches codebase, returns RESEARCH_SUMMARY |
The summary block (~20 lines) |
/rad-deliver per wave |
Wave sub-agent: loads files, implements, validates, commits | WAVE_RESULT block per wave |
/rad-review |
quality-reviewer + accessibility-reviewer agents | Finding summaries |
The plan linter enforces a context budget on the Files in Scope table:
- Warn at >800 lines in scope — consider splitting
- Error at >1500 lines — must split before the plan can be approved
| Role | Commands | Responsibility |
|---|---|---|
| Architect | All commands (incl. /rad-design, /rad-approve, /rad-epic-decompose) |
Defines agent boundaries, decomposes epics, approves plans, merges PRs |
| Developer | /rad-research, /rad-plan, /rad-adopt, /rad-deliver, /rad-review |
Research, plan, and execute within boundaries |
| Designer | /rad-research, /rad-plan, /rad-adopt, /rad-deliver |
UI-scoped research, planning, and execution |
| All roles | /rad-status, /rad-insights, /kickoff, /wrap, /rpi-design |
Team dashboard, review pattern analysis, session start/end rituals, agent-architecture scaffolding |
All commands are committed to the project repo. The architect/ subdirectory
signals which commands carry architect-level responsibility — enforcement is via
branch protection and PR workflow, not command access control.
git clone https://github.com/torchcodelab/rad-framework /tmp/rad
bash /tmp/rad/install.sh --dir /path/to/your-projectThe installer handles directory structure, commands, scripts, and CLAUDE.md scaffolding in one step. See INSTALL.md for the full guide including upgrade and uninstall instructions.
your-project/
├── CLAUDE.md ← always-loaded project context + RAD config
├── .claude/
│ ├── agents/ ← auto-discovered by Claude Code
│ │ ├── orchestrator.md
│ │ ├── [domain]-orchestrator.md
│ │ ├── [tool-name].md
│ │ ├── accessibility-reviewer.md ← built-in reviewer (invoked by /rad-review)
│ │ └── quality-reviewer.md ← built-in reviewer (invoked by /rad-review)
│ └── commands/
│ ├── architect/
│ │ ├── rad-approve.md → /rad-approve (architect)
│ │ ├── rad-design.md → /rad-design (architect)
│ │ └── rad-epic-decompose.md → /rad-epic-decompose (architect, Gate 0)
│ ├── team/
│ │ ├── rad-research.md → /rad-research (team)
│ │ ├── rad-plan.md → /rad-plan (team)
│ │ ├── rad-adopt.md → /rad-adopt (team)
│ │ ├── rad-deliver.md → /rad-deliver (team)
│ │ ├── rad-review.md → /rad-review (team)
│ │ ├── accessibility-review.md → /accessibility-review (team)
│ │ └── quality-review.md → /quality-review (team)
│ └── shared/
│ ├── rad-status.md → /rad-status (shared)
│ └── rad-insights.md → /rad-insights (shared)
│ └── skills/
│ ├── kickoff/SKILL.md → /kickoff (session start ritual)
│ ├── wrap/SKILL.md → /wrap (session end ritual)
│ └── rpi-design/SKILL.md → /rpi-design (agent-architecture scaffolding)
├── .agents/
│ ├── research/ ← research artifacts (/rad-research output)
│ ├── architecture/ ← architecture drafts (/rad-design draft → approved)
│ ├── epics/ ← epic shaping stories (/rad-epic-decompose, runtime)
│ ├── plans/ ← plan artifacts (Gate 1)
│ ├── state/<feature>/events.jsonl ← append-only event log — the gate authority (runtime)
│ ├── logs/ ← execution logs per plan
│ ├── findings.jsonl ← append-only review findings log (written by /rad-review)
│ └── findings/README.md ← findings log schema and query reference
└── scripts/
├── detect-platform.sh ← detects git platform from remote
├── get-default-branch.sh ← resolves default_branch from CLAUDE.md
├── checkout-plan.sh ← checks out a plan's rad/[feature] branch
├── fetch-epic.sh ← fetches an epic + children for /rad-epic-decompose
├── rad-label.sh ← applies RAD labels to a PR
├── open-pr.sh ← platform-agnostic PR creation
├── check-plan-approved.sh ← gates on the approved event at the branch tip
├── check-role.sh ← validates contributor role vs. command
├── check-scope.sh ← validates file changes against agent scope
├── check-tests.sh ← checks for test coverage in deliver output
├── lint-plan.sh ← validates plan structure + context budget
├── worktree-lifecycle.sh ← optional git-worktree isolation for a deliver run
└── rad-status.sh ← powers /rad-status dashboard
| Doc | Read when |
|---|---|
INSTALL.md |
Installing or uninstalling RAD |
UPGRADE.md |
Upgrading an existing RAD project to the latest version |
docs/how-it-works.md |
The whole process explained — model, lifecycle, guardrails |
docs/harness-and-framework.md |
What RAD is — the harness core vs. the framework shell, grounded in code |
docs/rad-cli.md |
The rad CLI — gates, deliver, agent adapters, worktree/budget/hook config |
docs/rad-wave-contract.md |
The provider-neutral wave-execution contract adapters honor |
docs/harness-state-store.md |
The deterministic event-log StateStore at the harness core |
docs/framing-decisions.md |
How RAD positions itself on hooks, loops, context injection, and agent-to-agent orchestration |
docs/references.md |
Annotated log of external sources reviewed against RAD, the takeaways, and issues they generated |
docs/daily-workflow.md |
Getting started with the team workflow |
docs/architect-guide.md |
Setting up and maintaining the architecture |
docs/epic-decomposition.md |
When, why, and how to run the Gate-0 /rad-epic-decompose step |
docs/plan-pr-guide.md |
How plan approval works and what to review |
docs/wave-execution.md |
How /rad-deliver runs tasks in waves |
docs/platform-support.md |
Git platform configuration and fallbacks |
docs/onboarding.md |
Guide for new team members |
docs/apply-to-existing.md |
Applying RAD to an existing project (2–3 weeks) |
docs/12-factor-agents.md |
How RAD maps to 12-Factor Agent principles |
docs/maintaining-claude-md.md |
Keeping CLAUDE.md accurate over time |
.agents/findings/README.md |
Findings log schema, record types, and jq query reference |
- Dex Horthy — Advanced Context Engineering and 12-Factor Agents
- Cole Medin — PIV loop pattern
- GSD Framework — wave execution model
RAD is open source under the MIT License. Use it, fork it, build on it — commercially or otherwise. The only requirement is that the copyright notice and license text travel with substantial copies.