Built for AI agents and engineering teams

User stories with real acceptance criteria

Keep product intent in epics and implementation detail in user stories. linearstories preserves the hierarchy in Linear while giving agents testable acceptance criteria for every story they build.

Get started Download binary
$ linearstories import stories/*.md
Open source on GitHub MIT License Cross-platform binaries
The problem

AI agents fail when requirements are vague

Autonomous agents thrive on precision. When a task says "build the login page" with no acceptance criteria, agents guess — and they guess wrong. The result is wasted compute, broken deployments, and review cycles that defeat the purpose of automation.

  • Agents produce code that technically compiles but misses the intent
  • No definition of "done" means no reliable way to verify output
  • Vague Linear issues create ambiguity that compounds across sprints
  • Engineering managers lose visibility into what was actually built
Agent

What should I build for the login feature?

Linear issue

Build the login page. Make it nice.

Agent

I built something. I am not sure if it is correct. There were no acceptance criteria. Should I use OAuth? Email and password? SSO? I guessed email and password. Also I was not sure where to redirect after login so I redirected to /home. Let me know if this is wrong.

stories.md 
## Account access
labels: [Epic, Auth]

### Why is this needed?
Users need secure access to protected features.

## As a user, I want to log in
epic: Account access

### Acceptance Criteria

- [ ] User can enter email and password
- [ ] Invalid credentials show an error message
- [ ] Success redirects to /dashboard
The solution

High-level intent, linked to testable work

Write epics and user stories in one Markdown format, then import them into Linear as native parent issues and sub-issues. Epics explain the goal and rationale; stories give agents a precise definition of done.

  • Epics capture the goal, scope, and why the work matters
  • User stories carry machine-readable acceptance criteria
  • Linear parent and sub-issue links preserve the hierarchy
  • Agents verify their own output against a clear checklist
How it works

Three steps from goal to shipped

Define the goal, sharpen every story with an agentic review, and give coding agents a precise target to build toward.

1

Write epics and stories

Mark high-level issues with the Epic label, explain why they matter, and link focused user stories through the epic metadata field.

2

Review and improve

Run /rate-userstories. The agent grades every epic and story, hard-fails contradictions across the hierarchy, and proposes replacement Markdown for you to review.

3

Agents build with clarity

AI agents pick up stories with the epic rationale, focused scope, acceptance criteria, and definition of done. No guesswork. No wasted iterations.

Features

An opinionated system for better stories

Keep intent, implementation, and proof distinct. Then review the work, explore the plan, and sync it with the tools your team already uses.

Epic → user story → acceptance criteria

One opinionated structure keeps every layer honest: epics state the goal and why it matters, user stories define an implementable slice, and acceptance criteria make “done” observable and testable.

Goal Work Proof

Linear sync

Import Markdown into Linear or export existing issues back to files. Team-aware preflight validates projects, labels, people, and hierarchy before changes are written.

Rate, review, improve

Run /rate-userstories to grade issue quality, hard-fail contradictions across stories, and receive improved replacement Markdown for human review.

Local Project Atlas

Run linearstories visualize to explore hierarchy, filter stories by category label, and inspect status and acceptance-criteria completion in an interactive browser graph.

Multi-org contexts

Create named contexts with linearstories initctx, revise or remove one directly with updatectx <name> or deletectx <name>, then inspect them safely with linearstories ctx. Each context carries its own hidden API key, default team, and project.

Project atlas

See the whole delivery map, not another flat issue list

Turn any LinearStories Markdown file into Project Atlas: a local, interactive map of projects, epics, user stories, status, and acceptance-criteria progress. Explore the hierarchy before import, during delivery, or in review.

$ linearstories visualize stories/project.md
Navigate hierarchy Expand epics into their linked stories.
Filter the map Show or hide stories with exact category-label filters.
Inspect completion Read criteria and progress without leaving the graph.
Project Atlas visualization showing a GCP migration project connected to epics and user stories, with story-label filters and acceptance-criteria details.
01 Local by defaultNo Linear credentials or configuration required.
02 Source stays untouchedThe visualization never modifies your Markdown.
03 Built for reviewOpen the map, inspect the plan, and share the screen.
Claude Code skill

Grade epics and stories automatically

Run /rate-userstories in Claude Code to classify and evaluate every issue. Epics are scored on goal, scope, and rationale; stories are scored on testable acceptance criteria. Contradictions across the hierarchy hard-fail.

TYPE Classification Epic label selects the correct rubric
30% Epic rationale Why is this needed?
35% Story testability Can QA write a pass/fail test?
FAIL Contradictions Checked within and across issues
claude code
$ /rate-userstories stories/q1-2026.md
| Issue | Type | Score | Result | |------------------|-------|-------|--------| | Account access | Epic | 92% | PASS | | Login flow | Story | 88% | PASS | | Account recovery | Epic | 68% | FAIL |
Flagged: Missing "Why is this needed?" Rationale: 0/30 Replacement markdown proposed
Template format

One file, two levels of intent

A single Markdown file can define epics and their user stories. Frontmatter sets project defaults; per-issue metadata preserves hierarchy.

project Maps to an existing Linear project and is verified before import.
team Target Linear team. Used to scope labels and workflows.
priority 0 = None, 1 = Urgent, 2 = High, 3 = Normal, 4 = Low.
labels Team-aware exact matches; the Epic label identifies a top-level epic.
epic Parent Linear identifier or exact local epic title.
estimate Story points. Must match your team's estimation scale.
assignee Email address of the Linear workspace member.
status Maps to a Linear workflow state: Backlog, In Progress, Done, etc.
stories/q1-2026.md 
---
project: "Q1 2026 Release"
team: "Engineering"
---

## Account access

```yaml
linear_id:
linear_url:
priority: 2
labels: [Epic, Auth]
```

Secure account access and recovery.

### Why is this needed?

Users need secure access to protected features.

## As a user, I want to log in

```yaml
epic: Account access
labels: [Feature, Auth]
```

### Acceptance Criteria

- [ ] User can enter email and password
- [ ] Invalid credentials show a clear error
- [ ] Success redirects to the dashboard
Quick start

Three commands to your first import

Install once, let the guided setup store your Linear context, then point the CLI at your Markdown issues. No config paths or JSON editing required.

Linear API key Generate a personal API key at linear.app/settings/api. Paste it into linearstories initctx; the prompt masks it and writes a user-only config file. LINEAR_API_KEY remains available for CI.
Run it directly Install globally or place a release binary on your PATH, then use linearstories for regular work. Use bunx only for a one-off trial without installing.
Preflight first Use --dry-run for local Markdown checks and --preflight for read-only validation of Linear resources. Normal imports run remote preflight automatically.
bash
# 1. Install globally for regular use $ bun install -g linearstories + linearstories@1.5.0
# 2. Create a context with guided setup $ linearstories initctx Context name: work Saved "work" to ~/.config/linearstories/config.json
# 3. Import your Markdown issues into Linear $ linearstories import stories/*.md Parsing stories/*.md... Found 1 epic and 2 user stories Remote preflight passed: team, project, labels, and hierarchy verified Importing to project "Q1 2026 Release"... Done. 3 issues created, 2 sub-issues linked.
# Export existing issues back to Markdown $ linearstories export --project "Q1 2026 Release" Exported 3 issues to q1-2026-release.md
# Visualize the exported hierarchy locally $ linearstories visualize q1-2026-release.md Visualizing 1 epic and 2 user stories at http://127.0.0.1:4173
# Multi-org: import using a named context $ linearstories import --context orgB stories.md Done. 3 issues created with hierarchy (orgB).
Agent shortcut

Too busy to read all this?

Have your agent do it for you. Point it at the agent-ready guide, then ask it to install, configure, review, sync, or visualize your stories.

Give this URL to your agent
https://linearstories.com/llms.txt
One text file. Full CLI and format context.