# RelayWork — full description RelayWork is a work OS for teams whose first draft comes from an AI agent. It is built on one idea: when a model can write the code in minutes, the scarce thing is the decision — what we are building, how, and who stood behind it. RelayWork is the system of record for those decisions. Hosted at https://www.relaywork.app. Workspaces live at `.relaywork.app`. The API is at `https://api.relaywork.app/api/v3`. Free for the whole team while in beta; Pro is priced when the beta ends and beta teams keep their terms. ## The unit of work: a spec A spec holds two documents, and both are versioned: 1. **Requirements** — what and why. The house template asks seven questions, from "What's the problem?" to "Any hard rules?". 2. **Implementation** — how. Approach, data model, API, failure modes, test strategy, slices of two days or less, rollout. Around them sit the owner, the approvers, the tasks, the linked pull requests, the linked code, the linked specs, a done checklist, and a discussion thread. Limits are enforced on push, not suggested: requirements ≤ 900 words, implementation ≤ 1400, no paragraph-length bullets. A document missing most of its template sections is rejected with the expected template. The goal is text a human will actually read. ## The ladder: twelve stages, two gates `discovery` (shaping the problem) → `product_spec_draft` (requirements being written) → `product_review` (**approval gate**) → `product_approved` (explore next) → `implementation_spec_draft` (exploring: reading code, draft PR open) → `technical_review` (**approval gate**) → `implementation_ready` (pull tasks in) → `in_progress` → `validation` → `released` → `outcome_review` (did it work?) → `done`. Rules that hold: - An approval is bound to a document version. Editing an approved document supersedes its approvals and returns the spec to review. - Higher-risk specs require two distinct approvers. - The implementation document is locked until requirements are approved. - Moving forward several stages at once walks each gate in turn and audits every hop. Moving backward is a single audited step. - Every transition records who, from where, to where, and when. ## Code anchoring A spec's Code section holds GitHub permalinks — `github.com///blob//#L10-L20` — each stored as a record with the repo, path, line range, commit and a note. RelayWork reads that file at that commit through a GitHub app and renders the lines inline, so a reviewer reads the reasoning and the implementation together. - A ref is pinned to a commit, so it keeps showing the code the decision was made against. If the file is gone at that commit, the card says so rather than showing something else. - `kind: blast_radius` marks code the work could break but does not touch. - Opening a draft PR against a spec attaches the files it touches automatically. Re-syncing preserves notes a human rewrote. Draft PRs never advance a gate. - Agents attach refs with the `add_code_ref` MCP tool; each ref in a batch reports whether it was added, rejected or already present. ## GitHub RelayWork reads your repository through a GitHub app and never writes to your code. Opening a pull request moves the linked task to In Review; merging ships it. Branch names come off the spec reference, so `AC-24` in a branch name is enough to connect the work. ## Claude and MCP The MCP server is a streamable-HTTP JSON-RPC endpoint at `/api/v3/relay/mcp`, authenticated with a workspace API token (`rw_…`, hashed at rest, scoped read or write, revocable from settings). Tools — read: `list_specs`, `get_spec`, `pending_reviews`, `list_tasks`. Write: `create_spec`, `update_spec`, `push_spec`, `add_code_ref`, `request_review`, `create_task`, `update_task`. There is no approve tool. Not gated behind a permission — absent. Machine writes are attributed to `token:` rather than a person, and a document an agent edited is marked as such in the UI. ## Everything else in the product - **Docs** — a Notion-style editor: slash menu, nested pages, private-by-default notes, `[[wiki links]]` with backlinks, markdown storage, autosave with a conflict guard. - **Issues and tasks** — typed (feature, bug, tech debt, chore, request) with priorities; slices under a spec, or standalone work with no ceremony. - **Sprints** — plan in specs, not only tasks; writing requirements counts as the week's work. Pulling tasks past an unapproved gate is flagged. - **Products** — group specs by the product they belong to inside one workspace. - **Intake requests** — one queue for incoming ideas, promoted into specs or declined on the record. - **Ship review and delivery overview** — what shipped, what slipped, where the week went. - **Pending on me** — one page for every review, blocker and decision waiting on you, with its age. - **Roadmap** — Now, Next, Later, Shipped, over your specs, with a shareable customer view. - **Changelog** — a public page built from what you released. - **Accounts** — native Google and Microsoft sign-in on your own subdomain, invites, roles, admin protections that stop the last admin locking the team out, and scoped API tokens. ## Running it alone A solo developer gets the half of the value teams discuss least: durable memory across agent sessions. A model does not remember yesterday's reasoning; an approved spec with code refs pinned to commits is the context it needs to resume. You are the approver — which is simply the moment you read what you asked for before something builds it — and bugs and chores skip documents and gates entirely. When the second engineer arrives, the specs they need already exist and the approver stops being you. ## Who it is for Small and mid-sized product teams who use coding agents daily and need the decisions around that code to be reviewable: startups replacing a Linear-plus-Notion-plus-a-prompt-doc arrangement, and teams adopting spec-driven development who want the gates enforced rather than remembered. ## Plain-markdown copies - https://www.relaywork.app/learn.md — the practice, the loop, the failure modes. - https://www.relaywork.app/glossary.md — 21 definitions. ## What it is not Not a code host, not a CI system, not an agent runner. RelayWork holds the specs, the approvals and the links to the code; your repository, pipeline and models stay where they are.