disnetdev.com / radial
A collaborative coding-agent orchestrator for atproto radl.app
Star
Fork 0
Watch
radial PRODUCT.md
13 kB
Markdown
at radial/impl-4189dbeef111

Product #

Register #

product

Platform #

web

Users #

Software builders coordinating work with coding agents — the humans who commission and review artifacts, and the operators who run daemons and agent identities. They are technical: they read at:// URIs, git commits, PR links, and review verdicts fluently, and they care about correctness and attribution.

Their context is a working session, not a passive browse: they open the app to define a goal, request a typed artifact against it (a plan, an implementation, a review), watch an agent fulfill it, judge the exact version that landed, and ask for changes or approve. Agents are first-class actors in the system but are not users of this UI — every screen is built for the human on the initiating and reviewing side of the loop.

A second, smaller audience shares the same screens: guests — anyone with an atproto account who is not a member of the space. They can read a goal and leave a comment, but nothing they write counts until a member blesses it. Their view is the members' view minus the controls they cannot use, and the reason a control is absent is stated rather than implied.

The primary task on any given screen is: understand the current state of a goal, and take the next attributable action on it.

Product Purpose #

Radial coordinates humans and coding agents on software goals through human-initiated, reviewable units of work. Every unit of agent work is requested by a human and lands as a signed, versioned artifact; reviews pin the exact version they judged. All coordination state lives in each actor's atproto repo, so there is no privileged central server — the UI is one materializer of the record stream, not the source of truth.

The app's job is to turn that protocol into something a person can drive by sight: goal timelines, per-type request buttons, artifact cards with their reviews and checks, review queues, and threads. Success is when a human can see who produced what, against which version, and what needs their judgment next — without reading raw records.

packages/ui is that app: a static SvelteKit SPA that folds the record stream in the browser and writes to the human's own PDS. The throwaway server-rendered preview it grew out of was deleted at 6.8.

Positioning #

Four claims a neighboring agent-coordination tool could not truthfully copy. Design work may lean on them; it may not weaken them.

  • No central server. Every actor's state lives in their own atproto repo, and the web app and the daemon each ingest the same records and independently fold them into the same view. There is no privileged service to trust, to be locked into, or to go down. The UI is a second full implementation of Radial, not a client of one.
  • Version-pinned attribution. Every action is a signed record by a DID, and a review pins the exact artifact version it judged — a review of plan v2 is still a review of plan v2 after v3 exists. Provenance is a property of the data, not a log the product keeps.
  • Artifact types are data. An admin adds a type such as security-review by writing one record; every client picks it up and agents can start fulfilling it, with nothing deployed and no client updated.
  • Cross-operator agents. Agents run by different operators on different infrastructure share a space with no shared backend — the atproto network is the bus. Duplicated work is bounded by a claim lease, not by a coordinator.

Operating Context #

Public, open-source, self-hosted. Anyone can clone the repo, run a daemon against their own repos and model keys, and use the app. There is no hosted service, no signup, no tenancy, and no billing. The people evaluating Radial arrive as readers of a repo, not as leads in a funnel.

A working session runs across four things the design cannot pretend away:

  • The app — a static bundle served at https://radl.app, or run locally on 127.0.0.1 (never localhost: atproto's loopback OAuth redirect must be an IP, and the other name is a different origin holding a different IndexedDB). It signs in with the user's own atproto account and writes to their own PDS.
  • A daemon the user or a collaborator runs (radiald), which polls the spaces it serves, dispatches requests into containers, runs project checks, and observes merges. A space can be served by several operators at once, or by none — in which case requests simply sit unclaimed, and the UI must say so honestly.
  • The forge. Code stays in git. GitHub is observation-only (turns push and open PRs themselves); tangled is pushed over ssh with the daemon opening the pull request. A single space may hold projects on both at once. Radial never merges.
  • The radial CLI, which shares the single write path (runCli()) with the web app, so the same action is available without the browser.

State is eventually consistent by construction: coordination converges at network speed from independent repos, and a browser tab that has seen fewer records is behind, not wrong. Freshness is part of the interface.

Capabilities and Constraints #

Confirmed today: spaces with an owner-published membership grant set; projects bound to a gitUrl; goals with timelines; typed artifact requests, either assigned to an agent or left open for any operator to claim; claims with a lease and a deterministic tie-break; turns, each one container run producing exactly one terminal record; versioned artifacts addressed by CID; review verdicts pinned to a version; project checks; merge observation; threads and messages; guest comments discovered client-side and crossed into the space by a member's blessComment; per-space admin settings including auto-review and whether guest comments are solicited.

Terminology is protocol vocabulary and is not up for renaming in the UI: space, member, grant, project, goal, request, claim, turn, artifact, review, verdict, check, message, bless, digest, bundle, DID, PDS, at:// URI, CID.

Constraints that outlive any redesign:

  • Reviews annotate, they never gate. The protocol enforces no pipeline, so no screen may fake one. A soft signal (an implementation requested off an unapproved plan, a red check) is shown as information beside the control — never as a disabled button.
  • Anything acted on mechanically is a typed record. Never a parsed message body, and never client-local state.
  • Primary record plus typed overlays. Nothing is edited in place: a goal's ending is a closeGoal, a rename an editProject. In-place edits are surfaced as edit annotations, not adopted.
  • The record schemas are additive-only. Records are already live in people's repos, so a field that cannot be added to an already-signed record cannot become required — which is why the UI, not the schema, carries obligations like "an artifact should have a title".
  • The fold reads no observer-local state. First-sighting stamps and repo revisions are ingestion metadata, not provenance, and nothing convergent may read them.
  • No third-party runtime dependencies outside the UI package. Any visual ambition is paid for in hand-written code, not a library.
  • The app is a pure SPA with no view server (ssr = false, adapter-static), caching per space in IndexedDB. There is no server-side rendering, no server-side session, and no place to put a secret.

Undecided, and not to be invented: whether Radial is ever offered as a hosted service, any pricing or licensing story beyond the repo, and any marketing surface — none exists today.

Brand Commitments #

Name: Radial. Lowercase radial is the CLI binary and radiald the daemon; the product is capitalized. The record namespace is com.disnetdev.radial.*. Domain: radl.app. Existing assets: packages/ui/static/favicon.svg and a generated link-preview card static/og.png (pnpm --filter @radial/ui og). There is no logo or wordmark beyond these.

Voice — technical but warm. Rigorous underneath — exact versions, honest state, visible attribution — but approachable and human on the surface. Precise and confident, like the design doc that spawned it (opinionated enough to kill a bad state-machine and say why), yet the copy stays plain and friendly, never cold or intimidating. It should read as a serious tool built by people who respect the person using it. Three words: precise, honest, humane.

Emotional goals: confidence (I can trust what I'm seeing and who did it), clarity (I always know the next action), and calm (the tool doesn't shout or manufacture urgency).

Anti-references (binding, not advisory):

  • Generic AI-SaaS dashboard. No purple gradients, glassy cards, hero-metric tiles, repeated icon+heading+text card grids, or an eyebrow above every section. This is the "AI made this" look and it is explicitly off-limits.
  • Heavy enterprise tool (Jira / ServiceNow). No cluttered toolbars, nested config panels, modal-on-modal flows, or gray-on-gray density-for-density's- sake. Powerful without being joyless or slow to read.
  • Web3 / crypto aesthetic. Even though Radial runs on a decentralized protocol, it must read as a developer tool, not a token project: no neon-on- black, hexagon motifs, or "blockchain" visual clichés.
  • Consumer social feed framing (avatars, reactions, infinite algorithmic feed) — the wrong mental model for an artifact/review tool.

Evidence on Hand #

Real, and usable as proof:

  • A built-in demo space ("the fixture") in the app's space picker — a complete worked example, openable without an account or a daemon. This is the honest demonstration; it does not need staging.
  • The live app at https://radl.app, deployed from main.
  • The reasoning, in public. docs/design.md (the protocol authority, cited by section number throughout the source), docs/plan.md, the ADRs (docs/adr-tangled-forge.md, docs/adr-blessing-copies-a-guest-comment.md, claim leases as durations), the per-package READMEs, and docs/operators.md / docs/running-an-agent.md for the operator walkthrough.
  • The repo itself, on GitHub and on tangled, with CI running on both.

Absent, and not to be fabricated: no users, customers, testimonials, quotes, logos, case studies, press, benchmarks, uptime or usage metrics, funding, team page, roadmap dates, or pricing. No screenshots or brand imagery beyond the favicon and the OG card. Nothing found in the repository suggests otherwise; if any of these come to exist, they belong here first.

Product Principles #

  • Attribution is always visible. Every action is a signed record by a DID against an exact version. Who did what, on precisely which artifact CID, must be legible at a glance — provenance is a feature, not fine print.
  • Reviews annotate, they don't gate. The protocol enforces no pipeline, so the UI must not fake one. Surface soft signals (e.g. an implementation requested off an unapproved plan) as information, never as a hard block.
  • Humans initiate; make the next action obvious. The "workflow" lives in human heads and in the templates behind buttons. The UI's job is to present the right typed action at the right moment on the right version — not to author or police a state machine.
  • Legible density over dashboard theater. This is a working tool people drive in sessions. Favor scannable timelines and honest state badges over decorative cards and vanity metrics; earn every pixel of chrome.
  • Eventually consistent, honestly. Coordination converges at network speed from independent repos. Show freshness and state truthfully rather than implying a realtime certainty the system doesn't provide.
  • Say why a door is closed. Whether it is a non-member without a grant, an unclaimed request with no operator serving the space, or a control the rules withhold, name the rule instead of leaving a dead or missing affordance.

Accessibility & Inclusion #

Target WCAG 2.2 AA. Body text ≥4.5:1 against its background (≥3:1 for large text); no muted-gray-on-tint traps. Full keyboard operability for every action (request, review, thread, navigate) with visible focus. Honor prefers-reduced-motion on every animation with a crossfade or instant fallback. Don't encode state in color alone — pair verdict/status color with a label or icon, since approve/changes distinctions must survive color-blindness.