Rad Design

---
description: >
  ARCHITECT ONLY. Consume a research artifact and produce the project's agent
  architecture. Run after /rad-research: it designs the agent hierarchy, presents
  it for inline approval, and on approval generates the .claude/agents/ files and
  the CLAUDE.md scope map — all in one invocation. No separate re-run required.
---

# /rad-design

Consume a RAD research artifact and generate the agent architecture for the
project. This is the A in Research/Architect/Deliver.

**One invocation, inline approval.** The command designs the agent hierarchy,
shows it to you, and asks to approve / edit / cancel. On approval it flips the
artifact to `approved` and proceeds straight to generation in the same run — the
review gate is preserved (you always see the boundaries before any agent file is
written), but the old "edit Status, then re-type the command" ceremony is gone.

Two entry paths share the same generation logic:
- **Design & Approve** — no approved architecture yet: design → inline approve → generate
- **Generate** — an already-`approved` artifact exists: re-running just (re)generates,
  idempotently. Manual `Status: approved` edits still work via this path.

## Input

`$ARGUMENTS` is the project slug. Examples: `habit-tracker-api`, `e-commerce-platform`

If `$ARGUMENTS` is empty, list all files in `.agents/research/` and ask which
project to design.

---

## Mode Detection

Check for `.agents/architecture/[slug].md`:

- **File exists, Status: approved** → skip to **Generate** (idempotent re-run)
- **Otherwise** (file missing, or Status: draft) → run **Design & Approve**

Design & Approve flows directly into Generate once you approve — it is one
continuous run, not two commands.

---

## Design & Approve

### Step 1: Read the research artifact

Read `.agents/research/[slug].md` directly. This is a small structured file —
no sub-agent needed.

If the file does not exist, stop:

No research artifact found for '[slug]'. Run /rad-research first to produce one.

### Step 2: Design the agent hierarchy

From the research artifact, design the full agent hierarchy. Produce:

**Agent Hierarchy tree:**

Parent Orchestrator ├── [Domain] Orchestrator roles: [architect | developer | designer] │ ├── [Context Tool] reads: [scope], returns: [contract] │ └── [Context Tool] reads: [scope], returns: [contract] ├── [Domain] Orchestrator roles: [...] │ └── ...

**For each agent, determine:**
- Type: `parent-orchestrator` | `role-orchestrator` | `context-tool`
- Roles: who can invoke it (inherit from parent orchestrator for context tools)
- Model: `claude-sonnet-4-6` for orchestrators, `claude-haiku-4-5-20251001` for context tools
- Tools: `Task` for anything that delegates, `Read, Grep, Glob` for anything that reads
- Reads: exact directories/patterns, or "nothing — delegates only"
- Returns: the output contract (what format, what fields, what line budget)
- Description: what goes in the frontmatter `description:` field

**Role assignment rules:**
- Parent orchestrator → `architect` only
- Domain orchestrators for auth, payments, infra, database → `architect` only by default
- UI, frontend, content, styling orchestrators → `developer, designer`
- API, backend, data orchestrators → `developer`
- Context tools inherit their parent orchestrator's roles
- Override defaults if the research artifact says otherwise

**Description writing rules:**
- Context tools must start with "MUST BE USED by [parent] when [specific condition]"
  or "Use PROACTIVELY when [condition]" — vague descriptions cause Claude Code to ignore them
- Orchestrators: describe the domain and what triggers delegation

### Step 3: Write the architecture artifact

Save to `.agents/architecture/[slug].md`:

```markdown
# Architecture: [Project Name]
Created: [YYYY-MM-DD]
Status: draft
Research: .agents/research/[slug].md

## Agent Hierarchy

[hierarchy tree]

## Agent Definitions

[for each agent:]

### [agent-name]
- Type: [parent-orchestrator | role-orchestrator | context-tool]
- Roles: [architect | developer | designer — comma-separated]
- Model: [claude-sonnet-4-6 | claude-haiku-4-5-20251001]
- Tools: [Task | Read, Grep, Glob]
- Reads: [exact scope, or "nothing — delegates only"]
- Returns: [output contract: format, fields, line budget]
- Description: "[exact text for frontmatter description field]"

## Scope Map

| Agent | Type | Reads | Roles |
|-------|------|-------|-------|
| [name] | [type] | [scope or "nothing"] | [roles] |

## Notes
[anything the architect should consider before approving — gaps, risks, open questions]

Step 4: Present the design for inline approval

The artifact is written with Status: draft. Do not stop and ask the architect to re-run — present the design inline and gate here. Render the hierarchy tree, the Scope Map table, and the Notes section, then ask:

Architecture drafted: .agents/architecture/[slug].md

[Agent Hierarchy tree]

[Scope Map table]

[Notes]

Approve this agent architecture?
  approve → flip Status to approved and generate the .claude/agents/ files now
  edit    → tell me what to change (roles, scope, contracts, models); I revise and re-ask
  cancel  → leave it as draft and stop (re-run /rad-design [slug] later to resume)

This inline prompt is the review gate — the architect sees every boundary before any agent file exists. The judgment is preserved; only the re-run ceremony is removed.

• edit → apply the requested changes to .agents/architecture/[slug].md, then re-render Step 4 and ask again. Loop until approve or cancel.

• cancel → leave Status: draft untouched and stop. A later /rad-design [slug] re-enters Design & Approve from the existing draft.

• approve → set the artifact's Status: draft → Status: approved, then record the authority as a frozen audit event by running:

  node harness/cli.js architecture-approve [slug]
  

  In proxy mode (recording an approval t