Create product specs from a codebase

Use a coding agent to read an existing repository and write product specs into OriginAI.

If your product already lives in code, use a coding agent to read the repository and turn it into product specs on OriginAI — capturing what the product is, who it's for, and its main flows and screens. You then confirm the result and publish it.

You do not need to create a project in the OriginAI app first. The CLI can create the project from the repo.

This path works best when the product exists in code but your team lacks a shared product description that everyone can point to.

Before you start

You'll need:

An OriginAI account.
The originai CLI available on your machine (run it with npx originai).
A local code repository.
A coding agent you already use, such as Claude Code, Cursor, or Codex.

The workflow

The steps below are a common order, but they aren't rigid — start from wherever you are.

1. Log in on this machine

You only need to do this once per machine:

npx originai login

Complete the authorization in your browser. Your credentials stay on your machine — never commit them to Git.

If you run your own development environment, point the CLI at your endpoints first:

npx originai config
npx originai config set api_url <API URL>
npx originai config set web_url <web URL>

2. Ask the coding agent to create the project and write specs

In the repository root, paste a prompt like this into your coding agent. It will create-project, write .origin.json, and index the codebase in one pass.

This git repository is existing product code. Create OriginAI product specs from it (repo → Origin). Do not invent UX the code does not clearly show.

Auth (human, once per machine): run `npx originai login` in this repo if you have not.

1. If `.origin.json` has no `project_id`, run `npx originai create-project --name "<product name from the repo>"` (it writes `.origin.json` when unbound). Then `npx originai link --project <id> --skill` if the skill files are missing. Commit `.origin.json` (no secrets).
2. If a project is already bound, skip create-project. Do not create a second project.
3. Browse the tree and main entry points. Summarize who the product serves, the problem, roles, and main flows.
4. Initialize fully in one pass. Write `README.rpml` first (`mode="doc"` product design doc). `validate --content` then `write-document`. No local `.rpml` files.
5. Immediately author one `.rpml` per page/route in that planning — do not stop after the README.
6. Read back with `list-documents --read-type workspace`. Confirm every planned page has a `.rpml`.
7. Tell the human: open OriginAI, review the specs, then publish a release.

The same prompt is on the create page under Existing codebase.

If you already have an OriginAI project you want to reuse, run npx originai link --project <id> first and skip create-project.

Linking writes a small metadata file (.origin.json) that contains the project ID and no secrets. Commit it so your teammates don't accidentally bind the repository to a different project.

3. Confirm the specs on the web

Open OriginAI, read the overview, review the canvas, and fix anything that's off. This step matters: good specs read like product documentation for a team, not like a dump of code comments.

4. Publish

When the specs look right, publish a release. From then on, you still edit in the workbench; coding-agent spec updates come back as change requests you apply, then a new release.

Once a project is linked, you can also work in the other direction — edit specs on the platform, publish, and have the agent implement against the latest release. That's the flow described in Share specs with your team or coding agent; this page is specifically about building the specs from code first.

Troubleshooting

Situation	What to try
Reads come back empty	Nothing is published yet — read from the workspace with `--read-type workspace`, or publish a release first.
The agent can't write the workspace	Check your login and project binding. If a release already exists, writes stage a change request.
Specs read like implementation notes	Emphasize users and scenarios in your prompt; fix the overview first, then align the screens.
Content was written but doesn't appear on the web	Double-check the project ID, refresh the page, and have the agent read the specs back.

Starting from an idea instead? See Create a project on OriginAI.
Ready to hand off? See Share specs with your team or coding agent.
After the first release, spec updates from agents: Review change requests.

Create product specs from a codebase

On this page