Imported from shortcuts/radin (AGENTS.md). Install upstream with npx skills add shortcuts/radin. Copyright stays with the author.

radin — Agent Reference

Read before touch any file here. radin be Claude Code plugin: skills, CLI, install glue. Bash, plus two C file (TUI and JSON helper). macOS and Linux.

Hard rules

• bash 3.2 (macOS ship it): no associative array, no mapfile, no ${var,,}. No uname branch — resolve through command -v / brew shellenv, branch only where tool differ (md5 vs md5sum). Call out every script edit explicitly.
• ~/.claude not ours. install.sh only cp radin own named files and mkdir -p. Never rm, never wildcard-delete, never overwrite file radin not ship. Two exception: the <!-- radin:begin -->…<!-- radin:end --> block in ~/.claude/CLAUDE.md, and lib/radin-cbm-config.sh snapshot/restore of settings.json + ~/.claude.json. Call out every install.sh edit explicitly.
• Companion install be advisory. Failure warn, run continue. Not optional, and nothing asked about them.

Where to edit what

install.sh go one way, repo to ~/.claude. New skill need cp -r line there, lib/radin-doctor.sh entry, README row and docs/architecture.md mention, or it ship nowhere.

New companion that ship own stats or gain command need bullet in skills/radin-stats/SKILL.md, or roundup never see it.

Storage

<repo-root>/.claude/.radin/ (outside repo, $PWD): backlog/ (index.jsonl + tasks/<id>.md), state/, plans/, reviews/. Format in docs/domain-models.md, schema in docs/schemas/backlog-entry.schema.json. Only thing radin write into consumer repo, and radin never touch their .gitignore.

Read and write it only through CLI (radin backlog …, radin state …). Nothing parse index.jsonl or completed.json, or grab task by line number. Data view need but no subcommand give mean add one.

Skills, agents, sub-agents

Every entry point be skill, because it run in user thread and can talk to them. Sub-agent cannot: no prose to user, no AskUserQuestion, no background-task notification — all three look like hang. Sub-agent be leaf worker skill dispatch, so before point prompt at skill check it ask user nothing and spawn no agent (constraints). Every prompt that name companion gate on command -v and carry escape clause: drop skill, never wait on it.

Writing prose for agents

• No-op test. Sentence that not change what model do versus its default pay load and say nothing. Delete whole sentence, never trim word out of it.
• Positive over prohibition. Ban drag banned behaviour into context and half-read as instruction to do it. State target behaviour. Keep prohibition only as hard guardrail with no positive phrasing, then pair it with target.
• Leading word. One word model already hold, repeated as token, replace restated triad or sentence that gesture at one idea.
• Completion criterion. Step end on bound model can check and that demand whole job ("every listed task", not "a report").

Rest live elsewhere: /mattpocock-skills:writing-for-agents full rule set, STE output style sentence craft, no-ai-slop human-facing prose, one rule, one file where rule live.

Delegation: one owner per job

If shipped tool do job, name it; never write radin own version. Each delegation named in exactly one file — second copy drift silent, and test pin every name.

Graph tool name live in four files only and must exist in upstream table — wrong one cost failed call in every sub-agent (which files, and the pointer rule).

Decisions that look like bugs

• No per-task verification in radin-execute, and FAILED task get Debug prompt once per session (why).
• What sub-agent learn stay on its task — a **Fact:** or **Root cause:** line, long form in state/facts/<id>.md. No shared note file, no cross-task memory.
• radin-execute worktree/branch answer never reach prompt; radin-state.sh prepare be only place they become git command. Model handed them eventually override a no.
• lib/radin-cbm-config.sh snapshot before upstream write, because that installer replace whole hook array instead of merge; drop it and machine lose hooks silent (limits).
• Two C file only: TUI (lib/radin-tui.c) and JSON helper (lib/radin-cbm-json.c). TUI draw and dispatch keys only — raw ANSI, termios, every mutation shell out to radin-backlog.sh. Helper hold every JSON rule radin cbm-config and radin cbm-hooks mcp need; those script keep none, and radin need no python of own. install.sh build both with cc, advisory: no compiler mean no radin tui, no radin cbm-config, and radin cbm-hooks mcp print entry to paste by hand, rest still install (rules).
• order move dependency UP, never dependent down. Human priority ranking survive as far as dep graph allow; Kahn with priority tie-break discard more of it.
• TUI load backlog list --order created, so mutation reorder nothing and row stay put. Shift-A/Shift-P/Shift-C/Shift-T be only reorder, session-only, active one in header. CLI default stay priority — that be ordering contract radin-prioritization.md read.

Before committing

• make lint and make test clean, and make test stay under 40s. Keep it there: one recorded install.sh run every tree-only test replay, live run only for install-time behaviour, mock command be tests/helpers/mock.c (one compiled binary, not a shell stub per command — /bin/sh startup cost 20ms a call), and no test make network request.
• Docs updated in same commit: docs/architecture.md (layout, namespace resolution), docs/domain-models.md (format), README (new skill or companion), CHANGELOG.md (user-facing change).

Details: architecture · domain models · constraints · contributing