orfc

Getting started

Build the CLI, then run one command. Nothing to configure first — the CLI already points here. Once it's installed and you're on a team, orfc setup is the first command to run — before pushing or pulling anything.

Run it from the directory you want the team's folder to appear in, not inside a folder you made yourself — it creates one for you, named after the team, holding the binding, the agent instructions and the docs.

The folder is self-contained — move it, commit it, or hand it over whole. Run setup again from inside it and it stays put; every step is skipped when it's already done. Came through an invite? You're already in one team, so nothing is asked. No team at all? It makes one.

Teams

Every doc belongs to exactly one team, decided when it's created and fixed after that. The dashboard shows the team's docs, not just yours — so a doc doesn't disappear when the person who wrote it is on holiday. Permissions are flat: every member can read, edit, and invite.

The CLI works out which team without being told, first match wins: an explicit --team, then .orfc.json in the current directory or nearest ancestor, then sole membership. If none of those decide it, push errors and lists your teams. It never guesses — a doc can't move afterwards, so a wrong guess is permanent.

Two people at once

pull stamps the version it gave you into the file. When you push it back, that version comes too. If the doc moved on while you were editing, your work is stored beside the current version instead of over it — and the doc page shows it waiting.

No push is ever refused, so nothing is stranded on one laptop. There's no merge, no conflict markers, no resolving. You read both and choose: promote the stored version to latest, or dismiss it if you've already folded it in by hand.

Sync a whole team to disk

This is the part agents care about. sync pulls every published doc into the team folder, mirroring folders as real subdirectories — so an agent can grep the team's thinking instead of asking for it one document at a time. setup runs it for you the first time.

Pull-only and idempotent: files already at the right version are skipped, so re-running is cheap. Local files with no counterpart on the server are reported and left alone — a synced directory is your recovery path if a team is ever deleted, so sync can't quietly empty it. Nor does it overwrite your work: a doc you edited that the server has also moved past is reported and left exactly as it is.

Publishing a plan

Push any markdown or HTML file to get a shareable link. For markdown, the title is auto-detected from the first # heading; for HTML, from <title> or the first <h1>. HTML docs render the author's own theme — sanitized, but with inline SVG, charts, and styling preserved.

Pipe from stdin, set a custom title, organize with folders and tags, or update an existing plan:

Folders & tags

Group plans into folders for projects, releases, or teams. Add tags for cross-cutting categories (rfc, design, postmortem). The dashboard shows a folder tree on the left and a tag filter on top — both also editable per-row.

In-page navigation

Markdown plans render a sticky sub-nav built from their headings, scroll-tracked so reviewers can jump straight to the section they care about. Long RFCs stay readable.

Access control

By default, plans require sign-in to view. You can make them public or restrict to specific people.

Notifying reviewers

Send an email to reviewers when you publish, so they know to review.

Reviewing feedback

Reviewers open the link in their browser, highlight text, and leave inline comments. You can pull those comments back into your markdown.

Plain orfc pull xK7mQ2 updates the doc in your team folder instead — sync, for a single doc. Add --stdout to pipe it somewhere for revision:

Managing plans

The dashboard at /dashboard lists every doc the team has published with a folder tree, tag filter, and per-row controls to move or retag. The CLI mirrors the same primitives.

Editing & version history

Edit plans directly in the browser or from your terminal. Every update automatically preserves the previous version.

Agent workflow

Agents (Cursor, Claude Code, Windsurf) can use orfc to share implementation plans for human review before executing. This is the typical flow:

Agent prompt

orfc setup writes this into an AGENTS.md for you, read by Codex, Cursor and Claude Code alike. Here it is to paste into any other agent's rules.

Configuration

Config is stored at ~/.orfc/config.json. Set defaults so you don't have to repeat flags.

CLI reference