# Documentation

> How to drive Radial from the terminal, from your agent, and from your own code.

Radial is an issue tracker with a real command line, a remote MCP server and a
REST API. Nothing in the product calls a model on your behalf; the agent is
yours, and these pages are about pointing it at your issues.

## Start here

**[Agent skills](/docs/skills)**: eleven `rd-*` skills that teach Claude Code
and Codex the whole loop: plan a change into a parent and a few children, file
the tree, build it child by child leaving notes on each issue, and open a pull
request that does not auto-close the siblings. Install them in about a minute.

**[Install and update](/docs/skills/install)**: where the files go for each
client, global versus per-repo, and what to do when a skill does not show up in
the picker.

**[Extending a skill](/docs/skills/extending)**: add your team's rules to a
built-in without forking it, so you keep getting updates and we never overwrite
your conventions.

## The rest of the developer surface

The CLI reference, the MCP tool list and the REST API all live on
[developers](/developers) for now. The command you probably want first:

```bash
npm install -g radial.build && radial auth
```

<callout kind="note">

Every page here is also markdown. Add `.md` to any docs URL, or read
[llms.txt](/llms.txt) for the index and [llms-full.txt](/llms-full.txt) for the
whole corpus in one request.

</callout>

---

# Agent skills

> Eleven rd-* skills that teach Claude Code and Codex how to plan, file, build and ship work in Radial.

A skill is a folder with a `SKILL.md` in it. Your agent reads the description,
decides the skill applies, and follows the procedure inside. That is the whole
mechanism: no plugin, no runtime, no code executing on your machine that you
cannot read in a text editor.

The `rd-*` pack is eleven of them, covering the loop from "we should probably do
X" to an open pull request, plus four you run on their own to keep a backlog
honest. They are [MIT and public](https://github.com/BrainGridAI/radial/tree/main/skills):
read them, fork them, send a pull request.

## Install in 60 seconds

```bash
radial skills install
```

That writes the pack into `~/.claude/skills` and `~/.agents/skills`. Restart
your agent, then type `/rd-setup` in Claude Code or `$rd-setup` in Codex.

Working in one repo rather than everywhere?

```bash
radial skills install --project
```

Full detail, including the other two installers and what to do when nothing
shows up: [Install and update](/docs/skills/install).

## The workflow, in order

| Skill | What it does |
| --- | --- |
| `rd-setup` | CLI, sign-in, team, `.radial/config.json`, the agent instructions, the pack |
| `rd-plan` | An idea becomes one parent and two to four children with acceptance criteria |
| `rd-prototype` | One clickable HTML file, attached to the issue with a Preview URL |
| `rd-issues` | Files the tree, wires the `blocked-by` edges, reads every issue back |
| `rd-build` | Works the tree child by child: in progress, build, gate, notes, in review |
| `rd-verify` | Resolves and runs this repo's gate, then reads the summary line |
| `rd-pr` | Branch, base sync, commit, pull request with sibling ids scrubbed |

They chain, but nothing forces you through all seven. `/rd-plan` on its own is
useful. So is `/rd-verify`.

## Hygiene, any time

| Skill | What it does |
| --- | --- |
| `rd-triage` | Ranks open parents Now, Next, Later, Icebox from real signal |
| `rd-cleanup` | Open children under done parents, closed or promoted on evidence |
| `rd-changelog` | Completed issues become Feature, Improvement and Fix entries |
| `rd-retro` | Scores one finished build against the workflow, with evidence |

## Three things worth knowing before you start

### The description is the interface

Your agent picks a skill by reading its `description` frontmatter and nothing
else. That is why each one names Radial, the issue tracker, and the client it
runs in, and why you invoke a skill by describing your situation rather than by
memorising its name.

### They read and write through the `radial` CLI

Which means they respect your session, your scope and your team. A read-scoped
key stops `/rd-issues` at the first create with a clear message, rather than
half-filing a tree.

### A tree ends in review, never done

`/rd-build` moves each child to in review and stops. Closing is a human
decision, and a workflow that closes its own work hides the moment someone
should look at it.

## Change them without forking them

Every skill has named extension points. You write a small wrapper that adds your
rules at those points and keep receiving updates to the skill itself:

```bash
radial skills extend rd-build --name team-build
```

See [Extending a skill](/docs/skills/extending).

## Where the files live

| Path | What it is | Commit it? |
| --- | --- | --- |
| `.radial/config.json` | The team key for this repo | yes |
| `.radial/skills/<name>/` | Your wrappers | yes |
| `.radial/changelog.md` | What `rd-changelog` writes | yes |
| `.radial/plans/` | Plan bodies, scaffolding for `rd-issues` | no |
| `.radial/prototypes/` | Prototype HTML before it is attached | no |

`radial skills update` picks up new versions; `radial skills list` shows what
you have against what is published.

---

# Install and update

> Where the rd-* skills go for Claude Code and Codex, global versus per-repo, and what to do when one does not show up.

Both clients load skills from a directory. Installing is copying files into it.
The CLI does that, verifies each file against a published hash, and records what
it wrote so it can update or remove exactly those files later.

## Claude Code

<steps>

<step title="Install the CLI, if you have not">

```bash
npm install -g radial.build
```

Homebrew works too: `brew install BrainGridAI/radial/radial`.

</step>

<step title="Install the pack">

```bash
radial skills install --agent claude
```

Files land in `~/.claude/skills/rd-*`. Leave off `--agent` to install for every
client the CLI can see on this machine.

</step>

<step title="Restart Claude Code">

Both clients read the skills directory at startup, so a running session will not
see a skill that appeared underneath it.

</step>

<step title="Check">

Type `/rd-` and the eleven names should complete. `radial skills list` shows the
same thing from the terminal, with an arrow beside anything out of date.

</step>

</steps>

## Codex

<steps>

<step title="Install the pack">

```bash
radial skills install --agent codex
```

Files land in `~/.agents/skills/rd-*`. If this machine's Codex reads
`$CODEX_HOME/skills` instead (older builds default that to `~/.codex/skills`),
the installer detects it and writes there, recording the directory it chose in
the lock so `update` and `remove` go to the same place.

</step>

<step title="Restart Codex, then invoke a skill">

Type `$rd-setup`. `radial skills list` shows the same set from the terminal.

</step>

</steps>

## Global or per-repo

Global is the default and is usually right: the skills are generic, and you want
them wherever you work.

`--project` writes into `.claude/skills` and `.agents/skills` under the current
directory instead, and locks to `.radial/skills.json` beside them. Use it when
you want the pack committed with the repo so a teammate gets it by cloning, and
when the repo has wrappers: `--project` copies those alongside, so
`/team-build` is invocable directly.

```bash
radial skills install --project
```

## The team key

Every skill needs to know which Radial team to file into. It resolves in this
order, and stops at the first answer:

1. `.radial/config.json` → `{ "team": "RAD" }`
2. A `radial team` line in `CLAUDE.md` or `AGENTS.md`
3. `radial team list`, and exactly one team means use it, and write it down
4. Ask you once, then write it down

`/rd-setup` does all of this, including creating the team if you do not have
one.

## Updating and removing

```bash
radial skills update              # only what changed is rewritten
radial skills list                # installed vs published
radial skills remove rd-retro     # only the files the lock recorded
```

`update` reports one line per skill: `installed`, `updated` or `current`. It
deletes files a new version dropped, so a renamed reference file cannot linger
and get read as current. `remove` deletes only paths the lock recorded and tells
you about anything else it found in the folder rather than taking it with it.

## Other installers

The pack is a public repo with a plain `skills/` directory, so the generic
installers work with no extra hosting:

```bash
npx skills add BrainGridAI/radial
codex -- '$skill-installer --repo BrainGridAI/radial --path skills/rd-plan'
```

Both copy the same files. The CLI is the recommended door only because it ships
as a binary, verifies hashes, keeps a lock and can update and remove.

## When it does not work

| What you see | Why |
| --- | --- |
| The skill is not in the picker | The client was already running. Restart it. |
| `radial: command not found` | The CLI is not on PATH. `npm install -g radial.build`, or use the Homebrew formula. |
| Codex does not see skills that Claude Code does | Your Codex reads a different directory. `radial skills list --json` shows the directory the installer chose; compare it against `$CODEX_HOME`. |
| One skill says `failed` and the rest install | Its bytes did not match the published hash. That is the guard working: re-run, and if it persists, open an issue rather than forcing it. |
| `Refusing to fetch over plain http` | `RADIAL_SKILLS_URL` points at an `http://` origin. Use `https://`, or pass `--insecure` if it is your own mirror on a trusted network. |
| A directory is "skipped, symlink" | Your skills directory is a symlink. The installer will not write through one; point `--agent` elsewhere or replace the link. |
| Two machines disagree about what is installed | The lock is per home directory (or per repo with `--project`). Run `radial skills update` on the other one. |
| A wrapper is refused as "reserved" | `rd-*` names belong to the pack, so an update never fights your wrapper for a name. Rename it. |

<callout kind="tip">

`radial skills install --dry-run` prints exactly what it would write and touches
nothing. Useful the first time, and in a script.

</callout>

---

# From an idea to a pull request

> The seven workflow skills walked end to end on one real feature, with the commands and the tree they produced.

This is one real run, not an illustration. The feature is the skills pack you
are reading about: it was planned, prototyped, filed, built, verified and
shipped with these seven skills, against team `RAD` in a live workspace. The
excerpts below are trimmed for length; nothing is invented.

## The seven steps

<steps>

<step title="Set up, once per repo">

```bash
/rd-setup
```

Leaves `.radial/config.json` with your team key, a Radial block in `CLAUDE.md`
and `AGENTS.md`, and the pack installed. Re-running it changes nothing and says
so.

</step>

<step title="Plan: argue before you file">

```bash
/rd-plan "let users install our agent skills with one command, and document it"
```

Reads the repo, searches Radial for anything that already covers it, and writes
one parent plus a handful of children to `.radial/plans/<slug>.md`. Creates
nothing. What comes back in chat is a breakdown table and the open decisions.
This run had two, about where the pack should be sourced and how extensions
should be shaped, and both changed the plan.

</step>

<step title="Prototype: reject the design cheaply">

```bash
/rd-prototype
```

One self-contained HTML file with every screen and state, attached to the
parent. A reviewer clicks a Preview URL and says no in five minutes rather than
after the build.

</step>

<step title="File: the tree becomes real">

```bash
/rd-issues --start
```

Parent, children, the `blocked-by` edges, then a read-back of every issue. This
run produced six children under one parent with eight dependency edges: two
more than `rd-plan`'s usual two-to-four, because the tree spans two
repositories and each repo's half has to merge on its own.

</step>

<step title="Build, child by child">

```bash
/rd-build
```

Per child: in progress, build from the plan, check every acceptance line, run
the gate, drive that child's browse checks against the running app, post
implementation notes, move to in review.

</step>

<step title="Verify: read the summary line">

```bash
/rd-verify
```

Called per child by `rd-build` and again before the pull request. Runs each
command once to a log and quotes what it found.

</step>

<step title="Ship: one tree, one pull request">

```bash
/rd-pr
```

Branch named from the parent, base synced, commits, and a body whose sibling
issue ids are rewritten so the merge cannot close work nobody reviewed.

</step>

</steps>

## The tree it produced

```text
$ radial show RAD-374 --team RAD
RAD-374  Radial agent skills: open-source rd-* pack with extension hooks,
         radial skills CLI, and docs
  Status     In Review
  Labels     claude, Feature
  Sub-issues 6

  RAD-375  skill format, hook convention, manifest, guards, README
  RAD-376  workflow skills: setup, plan, prototype, issues, build, verify, pr
  RAD-377  hygiene skills: triage, cleanup, changelog, retro
  RAD-378  radial skills install|update|list|remove|extend + label flags
  RAD-379  /docs surface, agent twins, install + extending pages
  RAD-380  per-skill reference, walkthrough, issue body, conventions
```

Each child carries its own body with a goal, a file list and acceptance
criteria, each has an implementation-notes comment from the build, and the
whole tree ends in review. A human merges and closes.

## What you actually type

Only two of the seven take an argument. The rest read the state they need:

| Step | The whole command |
| --- | --- |
| Plan | `/rd-plan "<the idea, in a sentence>"` |
| File | `/rd-issues` or `/rd-issues --start` |
| Everything else | the skill name on its own |

<callout kind="note">

Nothing forces you through all seven. `/rd-plan` on its own is useful, and so
is `/rd-verify`. The chain is a default, not a contract.

</callout>

---

# rd-setup

> Get a repo and a machine ready for Radial. CLI, sign-in, team, config, agent instructions, and the skill pack.

`rd-setup` takes a repo from nothing to ready: the `radial` CLI on PATH, a
signed-in session, a chosen team, and the conventions written down where both
your agent and your teammates can see them. Every step is idempotent, so
running it on a repo that is already set up is the cheapest way to check.

> Set this repo and this machine up for Radial, the keyboard-first issue
> tracker, so the rest of the rd-* skills work in Claude Code and Codex.

## When to use it

First time in a repo, on a new machine, or when another skill stops because it
cannot resolve the team key. Not for filing or planning work: those are
`/rd-issues` and `/rd-plan`.

## What it asks you

As little as it can. If `radial team list` returns exactly one team it uses it
without asking. If it returns several it shows you the table and asks which one
this repo files into. If it returns none it asks for a name and a key. It asks
once more before adding the MCP server config, because MCP is optional: the
skills drive the CLI, and MCP only pays off for a hosted agent with no shell.

## What it writes

`.radial/config.json` with your team key, and `.radial/.gitignore` so plans and
prototypes stay out of git while wrappers and config stay in. A short Radial
block in `CLAUDE.md` and `AGENTS.md` naming the team and the two CLI rules that
bite. Then the skill pack, into your agent directories. It touches no issue in
Radial.

## Extension points

<hook-table skill="rd-setup">
</hook-table>

## A worked wrapper

```markdown
---
name: acme-setup
description: Acme's setup rules on top of rd-setup — SSO, the shared project, the on-call note.
extends: rd-setup
---

Read rd-setup first, then apply the sections below at their hooks.

## extra-checks

- Acme uses SSO. If `radial whoami` reports a credential from `RADIAL_KEY`,
  stop and say: personal keys are for CI only, sign in with `radial auth`.
- Refuse to continue on a scope below `write`; name the scope you saw.

## extra-config

- Write `"project": "Platform"` into `.radial/config.json` alongside the team.
- Add the on-call rota link to the Radial block in `CLAUDE.md`.

## after-setup

- Open a first issue titled "Set up <repo> in Radial" and close it, so the team
  shows up in the activity feed.
```

## What it never does

It never writes to `.env` or any secret file: a credential goes through
`radial auth` or `RADIAL_KEY`. It never creates a team without asking, and
never picks between several for you. It never rewrites an existing Radial block
in your `CLAUDE.md` beyond adding a line that is missing; your wording stays.

---

# rd-plan

> Turn an idea into one parent and two to four children with acceptance criteria, written to a file so you can argue with it before it becomes a tree.

`rd-plan` turns "we should probably do X" into a reviewable plan: one parent, a
small number of children that each merge on their own, and acceptance criteria
written as things you can observe. It writes one markdown file and creates
nothing in Radial, which is the point: a plan is cheap to argue with and a
filed tree is not.

> Turn an idea into a plan for Radial, the keyboard-first issue tracker: one
> parent issue plus two to four children, each with a goal, a file list and
> acceptance criteria anyone can check.

## When to use it

Before any change big enough that you would otherwise open five tabs and start
guessing. Not for a one-line fix: `radial create` and move on.

## What it asks you

Only what it cannot read out of the repo, and all at once. It opens the code
the idea touches before decomposing anything, so its questions are about
decisions rather than facts: which of two approaches you want, whether an
existing surface should change, what is deliberately out of scope. A plan that
names no real file is a guess, and it will tell you which files it read.

## What it writes

One file, `.radial/plans/<slug>.md`, holding the parent body and every child
body in full. Nothing else. In chat you get a breakdown table, the out-of-scope
list, and any open decision written as a default and an alternative.

The reads it does first are what keep it honest: `radial workspace show --json`
for the real status, label and priority names, and `radial search` per
candidate title so it does not file a second tree for work that already exists.

## The shape it produces

```text
P   Parent: the goal, the scope, the decisions
├── C1  merges alone
├── C2  merges alone            blocked-by C1
├── C3  merges alone            blocked-by C1
└── C4  merges alone            blocked-by C2, C3
```

One child is one merge. If a child cannot merge on its own without breaking the
default branch, it is not a child, and it gets folded into its neighbour.

## Extension points

<hook-table skill="rd-plan">
</hook-table>

## A worked wrapper

```markdown
---
name: payments-plan
description: Payments team rules on top of rd-plan, the questions we always forget and the bar we hold.
extends: rd-plan
---

Read rd-plan first, then apply the sections below at their hooks.

## extra-questions

- Does this touch money movement? If yes, ask which ledger accounts change and
  whether a reversal path exists.
- Ask which regulator-facing report this shows up in, or state that none does.

## extra-sections

- Every child body gets a `**Rollback:**` section naming the exact revert path.

## extra-checks

- No child may name a file under `src/ledger/` without also naming a test file.

## plan-bar

- Every child needs at least three acceptance criteria, one of which is an
  observable failure case.

## after-plan

- Post the breakdown table to #payments-eng before filing anything.
```

## What it never does

It never creates, updates or closes an issue. It never writes an acceptance
criterion that asserts an implementation detail, because a test bound to the
mechanism you chose becomes the bug's bodyguard after the rewrite. It never
puts the full bodies in chat, and it never invents a status, label or priority
name. It reads them from your workspace.

---

# rd-prototype

> Build one self-contained clickable HTML file from a plan or an issue, and attach it so reviewers click a Preview URL instead of reading a description.

`rd-prototype` builds one HTML file showing every screen and state a plan
names, opens it locally, and attaches it to the Radial parent so the Preview
URL can be shared. It is throwaway by design: real copy, fake data, no
dependencies, nothing that survives into production.

> Build one self-contained clickable HTML prototype from a plan or from a
> Radial issue, then attach it to the issue so reviewers click a Preview URL
> instead of reading a wireframe description.

## When to use it

A change with a visible surface, before anyone writes the real component. Also
on an existing issue, when a reviewer says they cannot picture it. Skip it for a
change with no screen, and say why rather than skipping silently.

## What it asks you

Almost nothing up front, and one thing at the end: a reaction. It reads the
plan or the issue for `**UX:**` lines and browse checks, then reads your repo
for the visual language it should copy: the theme file, the type scale, the
spacing rhythm, one shipped screen to take the chrome from. If the repo has no
visual language yet it picks one deliberately and tells you which.

## What it writes

`.radial/prototypes/<slug>.html`, one file. When the tree exists it attaches it
to the parent and adds a `**Prototype:**` line with the Preview URL to the
parent body, deleting the previous attachment first so the newest file is
unambiguous. When the tree does not exist yet it leaves the file for
`/rd-issues` to attach. It changes no status, assignee or label.

## The constraints, and why

The file has no external URL in it: no CDN, no web font, no image host. A
prototype that needs the network renders blank in a reviewer's sandbox, which
is exactly where Preview URLs are opened. Every screen the plan names is
reachable from an index at the top, because a reviewer who has to guess how to
reach screen four will review screens one to three. Every state is shown
(empty, loading, error, denied) because states are where designs actually fail,
and real copy is used, because placeholder text hides the hardest layout
problem, which is always the long string.

## Extension points

<hook-table skill="rd-prototype">
</hook-table>

## A worked wrapper

```markdown
---
name: design-system-prototype
description: Our design-system rules on top of rd-prototype.
extends: rd-prototype
---

Read rd-prototype first, then apply the sections below at their hooks.

## extra-craft

- Copy the tokens from `src/styles/tokens.css` verbatim into the `<style>`
  block. Never invent a colour.
- Controls are 36px tall and 8px-rounded, matching the shipped app.

## extra-screens

- Always include a 1280px screen and a 390px screen for every flow.
- Include a keyboard-focus state for every interactive element.

## save-bar

- Body text must clear 4.5:1 against its background; state the measured ratio.

## extra-notes

- Post the Preview URL in #design-review and paste the thread link into the
  issue as a comment.

## extra-checks

- Name the designer who has to react, and say the prototype is parked until
  they do.
```

## What it never does

It never fetches anything at runtime. Nothing in it is copied into `src/`
without being rewritten: it is a drawing, not a component. It never leaves two
attachments both claiming to be the current prototype, and it never touches an
issue's status, assignee or labels.

---

# rd-issues

> File a plan as a real tree (parent, children, blocked-by edges) and read every issue back to prove the fields landed.

`rd-issues` takes `.radial/plans/<slug>.md` and turns it into issues: the
parent, each child with its body and parent link, the dependency edges between
them, and then a verification pass that reads every issue back. A create that
returned 200 is not proof the field landed, and the read-back is what makes the
tree true rather than probable.

> File a plan as a real tree in Radial, the keyboard-first issue tracker: one
> parent, its children, the blocked-by edges between them, and a read-back that
> proves every field landed.

## When to use it

Right after `rd-plan`, once the plan has been argued with. Not for editing
issues that are already filed: `radial update` is faster and does not need a
skill.

## What it asks you

Which mode, if you have not said. The default files everything into the
backlog, unassigned, with no agent label: the plan exists, nobody is on it yet.
`--start` means you are building this now, so children land in progress,
assigned to you, carrying the label of the agent doing the work. It also stops
and asks if a search turns up an issue that already covers this. Two trees for
one change is the mess `/rd-cleanup` exists to undo.

## What it writes

The parent, then each child with `--parent`, then one `radial link <child>
blocked-by <other>` per edge, then status, assignee and label when `--start` is
on. If a prototype is sitting in `.radial/prototypes/` it attaches it and puts
the Preview URL in the parent body. Then it reads every issue back with
`radial show --json` and fixes anything that did not land.

## The two rules it carries

Calls run one at a time. Filing a tree is a burst of writes, and parallel
`radial` calls race the token refresh: the failure looks like a random 401
halfway through a half-created tree.

Labels are added with `--add-label`, never `-l`. Plain `-l` replaces the whole
set, which is how a type label disappears the moment an agent adds its own
attribution label.

Also, `-d` is inline text. Passing a file path to `-d` stores the literal path as
the description, so every body goes in through `--description-file`.

## Extension points

<hook-table skill="rd-issues">
</hook-table>

## A worked wrapper

```markdown
---
name: platform-issues
description: Platform team filing rules on top of rd-issues.
extends: rd-issues
---

Read rd-issues first, then apply the sections below at their hooks.

## extra-fields

- Every issue gets `--project Platform` and the current cycle.
- Every parent gets an estimate; ask if the plan does not imply one.

## file-bar

- A tree with any `[ui]` tag may not be considered filed until a prototype is
  attached to the parent and its Preview URL is in the body.

## after-file

- Post the parent URL to #platform with the child count and the first child to
  be picked up.
```

## What it never does

It never files a tree without reading every issue back. It never uses `-l` to
add a label, and never replaces a label set it did not author. It never creates
a second parent for a plan that already has one, and it never moves an issue to
done. Closing work is a human decision.

---

# rd-build

> Work a filed tree child by child (in progress, build, gate, browse checks, notes, in review), resuming from live statuses.

`rd-build` executes a filed plan and leaves a trail on the issues: a status
change when work starts, an implementation-notes comment when it finishes, and
a move to in review. It reads the live statuses first, so running it again
continues an interrupted build instead of rebuilding what already shipped.

> Work a filed tree in Radial, the keyboard-first issue tracker, child by child
> in dependency order: move each child to in progress, build it, check every
> acceptance line, run the repo's gate, drive the browse checks, post
> implementation notes as a comment, and move it to in review.

## When to use it

The tree is filed and you are ready to write code. Not when there is no tree
yet, and not when you only want the gate run: that is `/rd-verify` on its own.

## What it asks you

Nothing, once it starts. It is the one skill in the pack that runs long and
autonomously, so the questions happen before it: `rd-plan` argued about the
shape and `rd-issues` filed it. During the run it reports rather than asks, and
it stops rather than guessing when a child turns out to be infeasible.

## What it writes

On each child: a status change to in progress, an assignee if the field was
empty, the agent label, then an implementation-notes comment and a status
change to in review. On the parent: the same kind of notes and a move to in
review at the end. In the repo: the code, plus whatever the plan named. It
finishes with a delivery table: one row per issue with a determination it made
by re-reading the acceptance lines, not by trusting that code exists.

## Where a child actually gets stuck

Two rules do most of the work, and both exist because of the same failure: a
child that looks finished and is not.

**Name the surface, or it does not exist.** The service, the types and the
tests land, and nothing renders. Before a child may move, the skill answers in
writing, for every surface its UX and browse checks mention: which file renders
this, and which route reaches it? An exported constant is not a surface.

**A child reaches in review when its own browse checks are observed, not at the
end.** Run in a sweep at the end, every child is already marked done and
nothing can fail. So the checks run as part of finishing that child, against
the running app, and a passing unit test is never evidence for one. A child
whose checks cannot be driven yet stays in progress with the reason stated.

## Extension points

<hook-table skill="rd-build">
</hook-table>

## A worked wrapper

```markdown
---
name: team-build
description: Our build rules on top of rd-build. Clean trees, screenshots, and a push per child.
extends: rd-build
---

Read rd-build first, then apply the sections below at their hooks.

## before-child

- Refuse to start a child on a dirty working tree; print `commit or stash first`.
- Rebase onto `origin/dev` and say what moved.

## extra-checks

- Run `pnpm bundle:check` and quote its summary line.

## review-bar

- A child may not move to in review until a screenshot of every browse check is
  attached to the issue.

## after-child

- Push the branch after each child, so the work is never only on this machine.

## after-tree

- Draft the changelog entry with rd-changelog and paste it into the parent.
```

## What it never does

It never closes an issue or moves one to done; in review is where a build ends.
It never marks a child done from code alone. It never rebuilds a child that is
already complete, and it never drags an issue backward through the workflow,
with one exception: a child sitting in review whose promised surface is
provably missing, which goes back to in progress and gets finished.

---

# rd-verify

> Resolve this repo's real gate, run each command once to a log, and read the summary line instead of trusting the exit code.

`rd-verify` works out what green means in this repo, runs it once, and reads
the output rather than the exit code. Its report is a table with a quoted
summary line per gate, so "tests pass" is a quotation and not a claim.

> Find and run this repo's real verification gate, then read each command's
> summary line instead of trusting its exit code, and report one row per gate
> with the evidence.

## When to use it

Before a child moves to in review, before a pull request, and any time you are
about to tell someone the tree is green. `rd-build` calls it per child and
`rd-pr` calls it before opening. Not mid-edit: run the one test file that
covers what you are changing, and save this for checkpoints.

## What it asks you

Nothing, usually. It resolves the gate itself and tells you which source
answered, because "read from CLAUDE.md" and "inferred from package.json" are
different levels of confidence and you deserve to know which one you got. It
asks only when nothing resolves at all.

## What it writes

A log file per gate under `.radial/`, and a table in chat. It writes nothing to
Radial: it reports, and `rd-build` records.

## How it resolves the gate

<steps>

<step title="The gate-commands hook">

If a wrapper fills it, those are the commands. Nothing is inferred alongside
them: a team that has written its gate down does not want you guessing next to
it.

</step>

<step title="CLAUDE.md or AGENTS.md">

The verification section, in the order it names things.

</step>

<step title="The package manifest">

`package.json` scripts named `lint`, `typecheck`, `test`, `check`, `validate`,
`verify`; else a `Makefile`; else `pyproject.toml`, `go.mod`, `Cargo.toml`.

</step>

</steps>

## Why the summary line, not the exit code

Exit 0 is not proof the tier ran. A test runner that matched zero files exits
0. A type checker pointed at the wrong project exits 0. A script that skipped
its real work because a flag was unset exits 0. So each gate is green only when
there is a line that says what happened (`561 passed, 0 failed`, `Found 0
errors.`), and a gate with no summary line found is a red row, not a green one.

## Extension points

<hook-table skill="rd-verify">
</hook-table>

## A worked wrapper

```markdown
---
name: monorepo-verify
description: The real gate for this monorepo, and the bar we hold before calling it green.
extends: rd-verify
---

Read rd-verify first, then apply the sections below at their hooks.

## gate-commands

1. `pnpm lint`
2. `pnpm type-check`
3. `pnpm test -- --reporter=dot`
4. `pnpm --filter @acme/api test`

## extra-checks

- `pnpm coverage`: the gate is red below 80% lines; quote the measured number.

## green-bar

- The working tree must be clean. Uncommitted changes mean the gate tested
  something nobody else can see.
- The e2e tier must have run, or the report says green-with-no-e2e explicitly.
```

## What it never does

It never claims green from an exit code alone, and never re-runs a suite to
reshape its output: it greps the log it already has. It never substitutes a
smaller command for a gate it could not run; that gate is reported not run,
with the reason. And it never edits a test to make a gate pass.

---

# rd-pr

> Open one pull request for the tree, with every sibling issue id rewritten so merging cannot close work nobody reviewed.

`rd-pr` commits, pushes and opens one pull request for the whole tree, with a
body that describes the work without handing the forge a list of issues to
auto-close. After the merge it re-reads each issue it mentioned and repairs any
status that flipped.

> Open the pull request for a tree in Radial, the keyboard-first issue tracker
> with a branch named from the issue, the base synced, the gate green, and
> every issue id in the PR text rewritten except the branch's own.

## When to use it

Every child is in review and the gate is green. Not mid-build, and not when a
pull request already exists for this branch: push to that one.

## What it asks you

Nothing it can determine. It finds the integration branch (`dev` if the remote
has one, else the default branch), reads the last twenty commit subjects to
match your message convention, and checks whether a pull request is already
open before creating one. It stops and tells you, rather than asking, when the
gate is red or the branch is behind base.

## What it writes

Commits on the branch the parent id names, the pushed branch, and one pull
request. In Radial, only repairs: after a merge it restores any status a
closing keyword flipped, and names which ones it repaired.

## The scrub, and why it exists

A merged pull request whose body says `closes RAD-12` closes RAD-12. A body
that lists a whole tree therefore closes the whole tree on merge, including
children nobody reviewed. So in the title and body:

- The branch's own issue id appears bare, once.
- Every other `KEY-n` is rewritten so no automation can match it, using a
  non-breaking hyphen (`RAD‑34`) or the words (`issue 34`). The body says
  which convention was used, so a reader is not confused by the lookalike.
- No `closes`, `fixes` or `resolves` in front of any id.

Before creating the pull request it greps its own body for `KEY-` and confirms
every hit is either the branch's id or already rewritten. After the merge, the
read-back is what catches a scrub it got wrong.

## Extension points

<hook-table skill="rd-pr">
</hook-table>

## A worked wrapper

```markdown
---
name: release-pr
description: Our pull-request rules on top of rd-pr. The checklist, the approver, the announcement.
extends: rd-pr
---

Read rd-pr first, then apply the sections below at their hooks.

## extra-checks

- Every user-visible change needs a `.changeset/` entry before committing.

## extra-sections

- The body carries a `## Rollout` section: flag name, default, and who flips it.
- The body carries a `## Screenshots` section for any `[ui]` child, or the line
  "no visible change".

## merge-bar

- A pull request touching `src/billing/` needs an approval from @finance-eng
  before it leaves draft.

## after-pr

- Post the pull request URL to #releases with the parent issue link.
```

## What it never does

It never leaves a bare sibling issue id in the pull request text. It never
merges and never closes an issue. It never opens a second pull request for a
tree that already has one, and it never opens one from a branch that is behind
its base or on a red gate.

---

# Keeping a backlog honest

> The four standalone skills (triage, cleanup, changelog, retro), when to run each and what each one writes.

Four skills that are not part of the build loop. You run them on their own,
against a workspace rather than a plan, and all four show you what they intend
to do before they do it.

## What each one is for

`rd-triage` answers "what should we do next". It reads the whole open backlog,
ranks the parents into Now, Next, Later and Icebox from real signal, and writes
priorities only after you agree.

`rd-cleanup` answers "what did we lose". Open children under a parent that is
already done, and issues sitting in progress that nothing has touched in weeks.
Each one is decided on evidence: a merged pull request, a commit naming the id,
a notes comment. It never deletes.

`rd-changelog` answers "what shipped". Completed issues in a window, read as
Feature, Improvement and Fix entries in customer language, prepended to
`.radial/changelog.md`.

`rd-retro` answers "how did that go". One finished tree, scored against the
workflow from what Radial and git already hold, with three proposals phrased as
wrappers you can paste. It writes nothing at all.

## A rhythm that works

| When | Run | Why then |
| --- | --- | --- |
| Monday, before planning | `/rd-triage` | The ranking is the planning input, not a report about it |
| After a big tree merges | `/rd-retro`, then `/rd-cleanup` | The record is freshest, and the tree is where strays appear |
| At a release | `/rd-changelog --since <last tag>` | The tag is the window, so nothing is guessed |
| Monthly | `/rd-cleanup` | Strays accumulate slowly; a month is long enough to be worth a sweep |

Nothing enforces this. Two of the four on a regular cadence is already more
backlog hygiene than most teams manage.

## What they write

`rd-triage` writes priorities, one `radial update` per row you approved, and
reads one back. `rd-cleanup` closes or detaches the rows you approved, with the
evidence in the close message. `rd-changelog` writes one file,
`.radial/changelog.md`, preserving everything already in it. `rd-retro` writes
nothing.

All four stop before writing and show you a table. That is not politeness: a
skill that ranks a backlog or closes stranded work is making judgement calls on
incomplete information, and the table is where you catch the one it got wrong.

<callout kind="tip">

Start with `/rd-retro` on a tree that went badly. Its output is the fastest way
to get a first wrapper that is about something real, rather than a rule you
imagined you needed.

</callout>

---

# rd-triage

> Rank open parents Now, Next, Later and Icebox from real signal, show the table, and write priorities only after you say yes.

`rd-triage` reads the whole open backlog, ranks it from evidence rather than
vibes, shows you the table, and writes nothing until you agree. Then it applies
the priorities and reads one back to prove it landed.

> Rank the open work in Radial, the keyboard-first issue tracker, into Now,
> Next, Later and Icebox using real signal: how many issues each one blocks,
> how old it is, whether anything has happened on it lately.

## When to use it

Weekly, before planning, or when nobody can say what is next. Not to decide how
to do something: that is `/rd-plan`.

## What it asks you

One question, once: yes or no to the table it shows you. Everything before that
is reading, and it tells you how many issues it read, because ranking half a
backlog produces a confident, wrong answer. Its second mode steps through the
triage queue instead, proposing a status, priority and label per item and
applying only what you accept.

## What it writes

One `radial update <id> -p <priority>` per row you approved, using your
workspace's real priority names, followed by a `radial show --json` on one of
them quoted back to you. Nothing else, and nothing outside the team you gave it.

## The signals, in order of weight

How many issues it blocks is the strongest single signal, and the least
flattering to anyone's intuition: an issue that blocks three others is not a
"later" no matter how small it looks. Then whether it is already in progress,
then age with no activity (a year-old issue nobody has touched is evidence,
not an accusation), then its stated priority today, and whether it belongs to
work already underway.

It ranks parents. A child's priority is a detail of its parent's, and a backlog
ranked at child level is a list nobody can read.

## Extension points

<hook-table skill="rd-triage">
</hook-table>

## A worked wrapper

```markdown
---
name: support-triage
description: Support-driven triage rules on top of rd-triage.
extends: rd-triage
---

Read rd-triage first, then apply the sections below at their hooks.

## extra-signals

- An issue labelled `customer` outranks anything else of the same blocking
  weight; name the customer in the row's reason.
- Anything labelled `sev1` is Now regardless of every other signal.

## rank-bar

- Now holds at most five issues. If more qualify, re-rank and say what you cut.
- Every Now row names an owner, or the row moves to Next.

## after-rank

- Post the Now list to #standup as a checklist.
```

## What it never does

It never writes a priority before you say yes. It never ranks from titles
alone: every row cites something it read. It never touches issues outside the team
it was given, and it never closes, deletes or reassigns anything.

---

# rd-cleanup

> Find the work the workflow left behind (open children under done parents, stale in-progress issues) and decide each on evidence.

`rd-cleanup` sweeps for issues the workflow stranded and proposes one action
per issue, each backed by something it found in Radial or in git. It shows you
everything before it writes, and it never deletes.

> Find the stranded work in Radial, the keyboard-first issue tracker: open
> children under a parent that is already done, and issues sitting in progress
> with no activity for weeks. Decide each one on evidence.

## When to use it

After a large tree merges, monthly, or when the board has issues nobody can
explain. Not to reprioritise: that is `/rd-triage`.

## What it asks you

Yes or no to the table, and how many days counts as stale if you have a number
in mind (it defaults to 21). It asks per row only when the evidence points both
ways, and that row is a feature rather than a failure: a wrong close is worse
than a question.

## What it writes

For a child it decided to close: `radial close <id> -m "<the evidence>"`, with
the evidence in the message because the message is what the next person reads.
For one it decided to promote: a detach, verified with a read-back, falling back
to a `related` link if the detach does not take. For a stale in-progress issue:
a move back to the team's todo status with a comment saying why. Never a delete.

## The two sweeps

The first looks for issues whose parent is in a completed status while the child
is not, and asks git and Radial what actually happened: a merged pull request
naming the id, a commit naming it, an implementation-notes comment, an activity
trail that reached in review. Evidence means close it. No evidence means the
work was never done and is now hidden under a parent nobody will reopen, so it
gets detached and becomes visible again.

It never infers "done" from the parent being done. That inference is the bug
this sweep exists to undo.

The second looks for issues in a started status whose last real activity is
older than the cutoff. It reads `radial activity`, not `updatedAt`, because a
bulk label change bumps the timestamp without anything happening.

## Extension points

<hook-table skill="rd-cleanup">
</hook-table>

## A worked wrapper

```markdown
---
name: strict-cleanup
description: Stricter evidence rules on top of rd-cleanup.
extends: rd-cleanup
---

Read rd-cleanup first, then apply the sections below at their hooks.

## evidence-bar

- A commit naming the id is not enough on its own. Close only on a merged pull
  request, or on a notes comment that names an acceptance line.
- Anything labelled `customer` is never auto-closed; it goes in the ask column.

## extra-sweeps

- Sweep for open issues with no assignee older than 60 days and propose the
  team lead.
- Sweep for two open issues whose titles differ by fewer than three words and
  propose a duplicate link.

## after-sweep

- Post the counts to #eng-ops and open a follow-up issue for anything left in
  the ask column.
```

## What it never does

It never deletes an issue: closing is reversible and deleting is not. It never
closes on the parent's status alone; every close quotes its evidence. It never
writes before a yes, and never touches issues outside the team it was given.

---

# rd-changelog

> Turn the issues completed since a date or a tag into Feature, Improvement and Fix entries in customer language.

`rd-changelog` collects the work that reached a completed status in a window,
reads each issue's body rather than its title, and writes entries a customer
would understand. It asks about anything that looks internal instead of
inventing a user benefit for a refactor.

> Write the changelog from what actually shipped in Radial, the keyboard-first
> issue tracker: the issues completed since a date or a tag, read as Feature,
> Improvement and Fix entries in customer language rather than issue titles.

## When to use it

Cutting a release, or writing the weekly update. Not to find out what is left:
that is `/rd-triage`.

## What it asks you

The window, if you have not given one: a date, a tag, or nothing, in which
case it takes the date of the newest section already in the changelog and says
which date it chose. Then it asks about each issue it could not classify,
rather than guessing. An issue whose body does not say what changed for a user
becomes a question, never a sentence.

## What it writes

A dated section prepended to `.radial/changelog.md`, creating the file if it is
absent and preserving everything already in it: it reads the file, builds the
new content and writes it back whole, because appending to the end of a file
whose newest entry is at the top is how a changelog quietly becomes two
changelogs. The `output` hook sends it somewhere else instead. It writes
nothing to Radial.

## What an entry looks like

```markdown
## 2026-09-14

### Features
- Radial skills for Claude Code and Codex. `radial skills install` gives your
  agent the eleven rd-* workflows.

### Improvements
- Bare issue numbers now resolve in search.

### Fixes
- The comments panel opens only for files that have comments.
```

It says what a person can now do, in their words. "Search finds bare issue
numbers" beats "resolve numeric tokens in the search index". No issue key, no
internal component name, no branch name. One sentence, two at most: a third
sentence is a blog post.

Work with no user-visible effect gets no entry. A refactor, a test, a
dependency bump: listed under "Internal" only if you ask for that section, and
never given a manufactured benefit.

## Extension points

<hook-table skill="rd-changelog">
</hook-table>

## A worked wrapper

```markdown
---
name: public-changelog
description: Publish the changelog to the docs site in our house voice.
extends: rd-changelog
---

Read rd-changelog first, then apply the sections below at their hooks.

## extra-sources

- Include anything with a `shipped` label even if its status is not completed.
- Cross-check against `gh release list --limit 5`.

## entry-bar

- Second person, present tense. "You can now…" rather than "Users can now…".
- No entry over 20 words. Cut the clause, not the fact.
- Every Feature entry links to its docs page or is not a Feature.

## output

- Write to `content/changelog/<date>.mdx` with frontmatter `title` and `date`,
  instead of `.radial/changelog.md`.
```

## What it never does

It never invents a user-visible benefit for work that has none. It never
overwrites or truncates an existing changelog: prior sections survive byte for
byte. It never closes or edits an issue, and never puts an issue key or a
branch name in customer-facing text.

---

# rd-retro

> Score one finished build against the workflow using only what Radial and git already hold, and turn each finding into a wrapper you can paste.

`rd-retro` reconstructs what happened on one tree from the record it left,
scores the workflow rules with quoted evidence, and turns each finding into a
wrapper section you can install. It changes nothing, so it is safe to run on
anyone's tree.

> Audit one finished build against the rd-* workflow using only what Radial,
> the keyboard-first issue tracker, and git already hold: the tree, its
> activity, its comments, the pull request and the commits.

## When to use it

After a tree merges, or when a build felt worse than it should have and you
want to know where it actually went. Not mid-build: the record is not there yet.

## What it asks you

The parent id, and nothing else. It cannot ask you what happened, and that is
deliberate: a retro built on recollection scores the story rather than the
run. Everything it says cites a timestamp, an issue id or a commit.

## What it writes

Nothing. Not to Radial, not to git, not to a file. It reports a scorecard, a
list of where the time went, and up to three proposals, and it says so at the
end.

## What it scores

Whether the tree was filed before the first build commit. Whether each child
went in progress and then in review rather than jumping. Whether each child has
an implementation-notes comment, and whether that comment names the acceptance
lines. Whether a prototype was attached where the plan had a UX line. Whether
sibling ids were scrubbed in the pull request body. Whether the tree ended in
review rather than being closed by the merge. Whether writes ran serially.
Whether any child was skipped.

A rule it could not check is stated as "not checkable here", with the reason
and what would make it checkable. It is never silently a pass.

## Three proposals, no more

Each one is phrased as a wrapper section you can paste, which is how a lesson
survives the session it was learned in. Twelve proposals change nothing, so it
stops at three and says which file each goes in.

## Extension points

<hook-table skill="rd-retro">
</hook-table>

## A worked wrapper

```markdown
---
name: eng-retro
description: Our extra retro rules on top of rd-retro.
extends: rd-retro
---

Read rd-retro first, then apply the sections below at their hooks.

## extra-rules

- Score whether the branch name carries the parent id.
- Score whether every child was pushed before the session that built it ended.
- Score whether the pull request body names a reviewer.

## score-bar

- Every row cites a timestamp or an id. A row citing only a title is a fail.
- The verdict is one sentence and must be consistent with the rows.

## after-retro

- Post the scorecard as a comment on the parent issue so it is findable from
  the tree rather than from a chat log.
```

## What it never does

It never writes anything. It never scores a rule it could not check as a pass.
It never states a cause it cannot evidence from the record: "a 90-minute gap
with no events" is a finding; "the agent got stuck" is a guess. And it never
produces a fourth proposal.

---

# Extending a skill

> Add your team's rules to an rd-* skill at named extension points, without forking it.

Your rules do not replace ours. They are added at named places inside a
built-in, so you keep receiving updates to the skill and we never overwrite your
conventions. That is the whole idea; everything below is mechanism.

## What a wrapper is

An ordinary skill folder with one extra frontmatter field:

```markdown
---
name: team-build
description: Our extra rules on top of rd-build, for the payments repo.
extends: rd-build
---

Read rd-build first, then apply the sections below at their hooks.

## before-child

- Refuse to start a child on a dirty working tree.

## review-bar

- A child may not move to in review until a screenshot of every browse check is
  attached to its issue.
```

Save it at `.radial/skills/team-build/SKILL.md` to share it with the repo, or at
`~/.config/radial/skills/team-build/SKILL.md` to keep it to yourself.

Everything above the first `##` heading is the preamble: a standing instruction
for the whole run. Each `## <hook>` section is applied at the matching point in
the built-in.

## Build it in four steps

<steps>

<step title="Scaffold it">

```bash
radial skills extend rd-build --name team-build
```

You get the folder, the frontmatter, and one `## ` heading per extension point,
in the order they fire. Nobody has to memorise marker names.

</step>

<step title="Fill in the sections you want, delete the rest">

An empty section is noise in the agent's context. Two filled sections beat
eleven empty ones.

</step>

<step title="Make it invocable, if you want it by name">

```bash
radial skills install --project
```

That copies the repo's wrappers into `.claude/skills` and `.agents/skills`
alongside the pack, so `/team-build` works directly. Skip this and the wrapper
still applies: `rd-build` looks for it at the start of every run.

</step>

<step title="Check it fires">

Run the built-in and read the first few lines of the agent's output. A wrapper
that applied says so. If it did not, the symptom table below names why.

</step>

</steps>

## Why extension points are named, not numbered

A hook is a place in the procedure with a name and a job: `before-child` is
"before each child starts", `review-bar` is "the bar a child must clear to move
to in review". Because you attach to the name, we can rewrite the paragraph
underneath it and your rule still lands in the right place. A line number, or a
copy of the whole skill with your edits in it, would break the first time we
improved the sentence above yours.

Names ending in `-bar` are quality bars, and they are unique across the whole
pack: there is exactly one `review-bar`, so a rule you write for it means the
same thing in every repo you carry it to.

## What a wrapper can and cannot do

| Rule | Why |
| --- | --- |
| It adds rules and raises bars | An extension that could lower a bar would quietly disable the check that mattered |
| It cannot remove a step | The built-in is the contract; a team that wants a different contract wants a different skill |
| It cannot redirect output somewhere the built-in does not name | Otherwise reading the skill would stop telling you where your data goes |
| The nearest scope wins **whole**: project beats user, never merged | Two half-applied rule sets is the worst of both |
| Two wrappers in one scope extending one skill: neither applies | Silent precedence is worse than a loud refusal |
| `rd-*` names are reserved | So an update never fights your wrapper for a name |

When a section tries something it may not, the built-in follows its own
procedure and says so in its output. You find out in the run, not in a diff.

## Why isn't mine firing?

| What you see | Why |
| --- | --- |
| No mention of the wrapper at all | `extends` does not exactly match a skill name, or the file is not at `<dir>/SKILL.md` |
| The agent names two wrappers and applies neither | Two wrappers in one scope extend the same skill. Merge them, or move one to the other scope |
| Your user-scope wrapper stopped applying | A project wrapper appeared. Project scope wins whole, never merged |
| A section is ignored with a sentence about it | The heading is not one of that skill's hooks. `radial skills extend` scaffolds the valid ones |
| "not followed, and why" in the output | The section tried to remove a step or lower a bar |
| `radial skills install --project` refuses it | The name starts with `rd-`, or `extends` names a skill that is not in the pack |

## Where wrappers apply

The project scope (`.radial/skills/`) belongs in git. It is how a team's conventions
travel with the repo and get reviewed like anything else. User scope
(`~/.config/radial/skills/`) is for habits that are yours rather than the
team's.

A repo with no wrappers runs the built-ins exactly as published, which is the
right default and where everyone should start. Write a wrapper when you catch
yourself telling your agent the same thing twice.

<callout kind="tip">

`/rd-retro` phrases each of its proposals as a wrapper section you can paste
straight into a file. It is the cheapest way to get a first wrapper that is
about something that actually went wrong.

</callout>

---

# The issue body

> The schema rd-plan writes, rd-issues files, rd-build treats as done-or-not, and rd-retro scores against.

One schema, used by four skills. `rd-plan` writes it, `rd-issues` files it,
`rd-build` reads the acceptance lines as the definition of done, and `rd-retro`
scores a run against it. It is markdown, so it renders in the app, in `radial
show`, and in a diff.

Use the smallest version that carries the contract. A body padded with empty
headings teaches readers to skim, and the acceptance lines are the part nobody
can afford to skim.

## A parent

Three header lines first, nothing above them:

```markdown
**Type:** feature
**Agent:** Claude Code
**Session ID:** 9f2c1a44-0c3e-4a5d-8b21-6f0d7e2b1c88

**Goal:** One sentence a stakeholder would recognise, describing the world
after this ships.

**Scope:**
- In: everything this tree covers.
- Out: what a reasonable reader would expect and will not get, and why.

**Plan:** How the children fit, the decisions already made, and the reason for
each. This is where a reader learns why it is three children and not one.

**Acceptance:**
- [boot] The repo's gate is green.
- [behavioral] A named person can do a named thing.

**Tags:** [ui, api]
```

`Type` is `feature`, `fix`, `chore`, `refactor` or `docs`. `Session ID` makes
the planning conversation findable a month later, which is its only job;
`unknown` is an acceptable value and a missing line is not.

## A child

```markdown
**Goal:** One sentence. What exists after this child merges.

**Scope:**
- In: …
- Out: …

**Plan:** The approach, the key decision, the trap to avoid. Two to six
sentences. Name the pattern the repo already uses, so the builder follows it
instead of inventing a second one.

**Files:**
create: src/lib/skills/manifest.ts, src/lib/skills/manifest.test.ts
modify: src/app/developers/page.tsx

**UX:** The journey a person takes, including empty, loading and error states.
No human-visible surface? Write `n/a (no UI surface)` rather than deleting the
line, so a reader knows it was considered.

**Acceptance:**
- [integration] With the manifest unreachable, the page renders the degraded
  hook table and no 500.
- [integration] A page whose frontmatter omits `section` fails the content
  build, naming the file.

**Browse checks:**
1. Open `/docs/skills` → the sidebar shows the skills in two groups → click
   "Install and update" → a Claude Code section and a Codex section appear,
   each with a copy button.
2. At 390px wide → the sidebar is a disclosure above the article and nothing
   overflows horizontally.

**Tags:** [ui]
```

## The rules that actually matter

**An acceptance criterion is observable.** It names an input and a result
someone can see: a rendered string, a status code, a row in the database, an
exit code. Never a function you intend to call. The test is whether a reviewer
who has not read your diff could check the line. If not, rewrite it.

**A bracket tag says how it is checked.** `[boot]` the process starts and the
gate passes. `[integration]` two real parts meet. `[behavioral]` a person does
something and sees something. `[perf]` a number with a bound.

**Browse checks are walkthroughs, not intentions.** Each starts where the
reader starts, lists the clicks, and ends on a condition that is either on
screen or not. `rd-build` runs them verbatim before a child may move to in
review, so vagueness here becomes a false "done" later, which is the specific
failure the format exists to prevent.

**The Out list is load-bearing.** It records what you decided not to do, so
nobody re-litigates it in review and `rd-retro` can tell a deliberate omission
from a dropped ball. A plan that excludes nothing has not been thought about.

**Write it for the reader who arrives late.** The body is read by a teammate in
six months and by an agent with no memory of the conversation you are having
now. Neither has your context.

<callout kind="note">

`rd-plan` writes every body of one plan into a single file,
`.radial/plans/<slug>.md`, and `rd-issues` files each with
`radial create --description-file`. `-d` is inline text: passing it a path
stores the literal path as the description, which nobody notices until review.

</callout>

---

# Conventions

> The .radial directory, how the team key resolves, and the four rules every skill carries.

Everything the skills assume, in one place. Most of it you will never think
about; the last four are the ones that bite.

## The `.radial` directory

| Path | What it is | Commit it? |
| --- | --- | --- |
| `.radial/config.json` | The team key for this repo | yes |
| `.radial/skills/<name>/` | Your wrappers: how your team extends a skill | yes |
| `.radial/changelog.md` | What `rd-changelog` writes | yes |
| `.radial/skills.json` | The install lock, when you use `--project` | yes |
| `.radial/plans/` | Plan bodies, scaffolding for `rd-issues` | no |
| `.radial/prototypes/` | Prototype HTML before it is attached | no |

The split is between conventions and scaffolding. Conventions belong in git so
they travel with the repo and get reviewed. Plans and prototypes are working
material: once the tree is filed and the prototype attached, the record lives
in Radial. `rd-setup` writes the `.gitignore` that encodes this.

## How the team key resolves

In this order, stopping at the first answer:

1. `.radial/config.json` → `{ "team": "RAD" }`
2. A `radial team` line in `CLAUDE.md` or `AGENTS.md`
3. `radial team list`, and exactly one team means use it, and write it down
4. Ask you once, then write it down

Every skill resolves it the same way, and every one of them writes the answer
down, so it is asked at most once per repo. A skill that cannot resolve it
stops and points at `/rd-setup` rather than guessing.

## Four rules every skill carries

**Calls run one at a time.** Parallel `radial` calls race the token refresh,
and the failure mode is not a clean error: it is a random 401 in the middle of
a half-created tree. Filing a tree is a burst of writes, which is exactly where
the temptation to parallelise is strongest.

**`-l` replaces the whole label set.** To change one label, use `--add-label`
or `--remove-label`. This is how a type label disappears the moment an agent
adds its own attribution label, and the read-modify-write happens inside the
CLI so a skill never has to do it by hand.

**`-d` is inline text.** Passing a file path to `-d` stores the literal path as
the description. Bodies go in through `--description-file`.

**Statuses are per-team rows, so model on the category.** `In Progress` in your
workspace is `Doing` in someone else's. Skills read
`radial workspace show --json` and pick by category (`backlog`, `unstarted`,
`started`, `completed`, `canceled`), never by a remembered name.

## Ids in pull request text

A merged pull request whose body says `closes RAD-12` closes RAD-12, and
several trackers close on a bare id alone. A body that lists a whole tree
therefore closes the whole tree on merge. `rd-pr` leaves the branch's own id
bare and rewrites every other one, using a non-breaking hyphen or the words,
and says in the body which convention it used.

## A tree ends in review

`rd-build` moves each child to in review and stops. Nothing in the pack closes
an issue except `rd-cleanup`, and only on evidence and only after you say yes.
A workflow that closes its own work hides the moment a human should look at it,
which is the moment that makes review worth having.

<callout kind="note">

None of this is enforced by the product. Radial does not care how you name a
status or where you keep a plan. These are the conventions the skills share so
that eleven of them can be read as one workflow rather than eleven opinions.

</callout>