Getting Started

Set up Storyline in your project and run your first collaborative review in under 10 minutes.

Install the Storyline skill

The skill teaches your coding assistant to create and maintain structured feature specs. It works with Cursor, Claude Code, Copilot, Codex, and any agent that supports skills.

npx skills add bjornno/skills --skill storyline

This installs the skill into .agents/skills/storyline/ in your workspace. It will create a specs/ folder and manage the file structure for you. View source on GitHub

Create specs

There are many ways to work with specs — pick what fits your workflow:

Generate from code

Already have a codebase? Ask your coding assistant to map it into specs.

"Run storyline on the whole codebase and create specs for every feature"

Spec first, then code

Planning a new feature? Write the spec, then let your coding assistant implement from it.

"Map our authentication feature using storyline, then implement it"

Write manually

Specs are just markdown files. Create them by hand if you prefer full control.

mkdir -p specs/auth && touch specs/auth/SPEC.md

Let them emerge

Vibe coding? The skill auto-creates and updates specs as you build, staying out of your way.

"Build a user profile page"

The skill will create specs alongside the code automatically.

See all spec file types

SPEC.md — Feature overview and index

problem.md — What problem are we solving?

actors.md — Who are the users?

journey.md — User flow from trigger to outcome

acceptance.md — Concrete acceptance criteria

systems.md — Architecture, components, dependencies

data.md — Data model and storage

api.md — API contracts and integrations

risks.md — What can go wrong? Mitigations

scope.md — In scope and out of scope

ui.md — UI/UX details and interaction notes

Set up the review CLI

# Log in (creates an API key for your machine):

npx storyline-review login

# Optional: point to a different server:

npx storyline-review config https://storyline-review.vercel.app

Create a review session

Run create from your project root. The CLI is interactive by default — just press Enter to accept the defaults (latest commit, guided review).

# Interactive (guided review of latest commit — just press Enter):

npx storyline-review create

# With explicit flags (skip prompts):

npx storyline-review create --branch feature/auth

npx storyline-review create --commit abc1234

npx storyline-review create --since 7d

# Force review even if the CLI thinks it's trivial:

npx storyline-review create --force

The CLI collects both spec files and code diffs, then analyzes them together. If the change looks trivial (typo, small fix), the CLI will suggest skipping. Otherwise it outputs:

Review URL — your view as the creator
Share link — send to your team (no sign-up needed)
Join code — a short code anyone can enter on the homepage

Automate with GitHub Actions optional

Get automatic reviews on every pull request. One command sets up the workflow file and walks you through adding the secret.

npx storyline-review setup-github

This creates .github/workflows/storyline-review.yml and helps you set the STORYLINE_API_KEY secret (auto-sets it if you have the gh CLI installed).

What does the workflow do?

On every non-draft PR, the action:

Checks out the code and reads your specs
Creates a product review — skips trivial changes
If non-trivial, also creates an architecture review
Posts a PR comment with review links and join codes

Reviews the full PR diff. Duplicate reviews for the same branch are reused automatically.

Review together

Everyone opens the share link or enters the join code, types their name, and starts the guided review.

Walkthrough first

Full-screen slides walk reviewers through the feature story, what changed, the user impact, and the primary tension found — so everyone starts with the same context.

Then discuss side by side

The review opens in a 50/50 split: feature context on the left, discussion steps on the right. Each step has its own prompt and response options tailored to the question.

Storyline drafts the outcome

When everyone has responded, Storyline synthesizes the discussion into a structured outcome. The owner edits and confirms the final decision.

Export and apply

When the review is done, export the results and let your coding assistant apply the agreed changes.