Create product specs from a codebase

If your product already lives in code, use a coding agent — Claude Code or Codex with a frontier model — to read the repository and write product specs on OriginAI. You then review the result and publish it.

You do not need to create a project in the OriginAI app first. The agent creates 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. A weaker harness or model will give you thin specs.

Before you start

You'll need:

• An OriginAI account.
• The originai CLI available on your machine (npx originai).
• A local code repository.
• A SOTA coding agent you already use. Prefer Claude Code or Codex with a frontier model.

The workflow

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

1. Install the Origin skill

In the product repo:

npx skills add 21stware/originai-context

Claude Code can also install the plugin from marketplace 21stware/originai-context. See Agent skills.

2. Log in on this machine

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>

3. Paste this prompt into the agent

In the repository root, paste the prompt below into Claude Code or Codex. It will create-project, write .origin.json, install the skill if needed, and write specs in one pass.

The same prompt is on the create page under Write specs from the repo.

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. Never commit `~/.origin/settings.json`. Prefer Origin MCP tools when connected; otherwise `npx originai` / `bunx originai`. Never raw curl.

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. Treat what you find as facts (who the code serves, roles, flows). Do not ask the human what the repo already answers.
4. If scope, device, or primary job is still ambiguous, **light grill** first: one round, at most 3 questions, each with a recommended answer. Infer the rest; close with "Reply go or adjust." Skip the grill when the brief/code already answers those. Do not write any `.rpml` until they say go or give the adjustment.
5. After alignment, initialize **fully** in one pass. Write `README.rpml` first (`mode="doc"` product design doc: overview, modules, page/route planning, flows, permissions). `validate --content` then `write-document --name "README.rpml" --content "<rpml>"`. No local `.rpml` files.
6. Immediately author one `.rpml` per page/route in that planning — do not stop after the README. Validate + write each.
7. Read back with `list-documents --read-type workspace` (default release reads are empty until publish). Confirm every planned page has a `.rpml`.
8. Tell the human: open OriginAI, review the specs, then **publish a release**. Until they publish, agents cannot read this content by default.

If a release already exists on the bound project, do not write the workspace directly — stage one Change Request for the whole pass (README + screens), then `describe-proposal` + `submit-proposal`. Never apply, dismiss, or record Ready / Not ready.

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.

4. 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.

5. 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

Related

• 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.