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