Conventions

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

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.