---
title: Plans are files
description: OpenPlanr keeps specs, stories, and tasks as files in your repository, so Claude Code, Codex, and Cursor read the same plan in every session.
url: https://openplanr.dev/docs/get-started/plans-are-files
updated: 2026-10-06
related:
  - https://openplanr.dev/docs/get-started/agent-setup.md
  - https://openplanr.dev/docs/get-started/first-spec.md
  - https://openplanr.dev/docs/get-started/troubleshooting.md
---

# Plans are files

OpenPlanr keeps the plan in your repository. Specifications, user stories, tasks, and provenance live under `.planr/`, reviewed and versioned like code.

A plan that exists only in a chat is gone when the session ends. A plan in the repository is there for the next session, the next teammate, and the next agent, and every change to it shows up in a diff.

## What the folder holds

Initializing a project creates the planning folder. This is the listing of an empty project after [`openplanr init`](https://openplanr.dev/docs/cli/init.md):

```text
.planr
.planr/ESTIMATION.md
.planr/adrs
.planr/backlog
.planr/checklists
.planr/checklists/AGILE-DEVELOPMENT-GUIDE.md
.planr/config.json
.planr/diagrams
.planr/epics
.planr/features
.planr/quick
.planr/specs
.planr/sprints
.planr/stories
.planr/tasks
```

Each spec gets its own folder under `.planr/specs/`, with the stories and tasks planned from it:

```text
.planr/specs/SPEC-NNN-<slug>/
  SPEC-NNN-<slug>.md
  stories/US-NNN-<slug>.md
  stories/US-NNN-gherkin.feature
  tasks/T-NNN-<slug>.md
```

## What a task carries

Every story keeps its acceptance criteria with stable IDs, starting at AC-001. Every task carries the context an agent needs to build it and a reviewer needs to check it:

| Field | What it holds |
| --- | --- |
| `rationale` | Why the task exists |
| `dependsOn` | Tasks whose output this task consumes |
| `preserve` | Files the task must leave unchanged |
| `reviewRisks` | What a reviewer should watch for, set from evidence in the repository |
| `browserSurfaces` | Browser surfaces the change touches, which pick the browser checks |
| `acceptanceRefs` | The acceptance criteria the task delivers |

The task body lists the files to create, modify, and preserve, then the technical spec, the test requirements, and the Definition of Done. Every acceptance criterion is referenced by at least one task, and that task's test requirements name the same ID with a check you can observe.

## How your agent uses the files

- `/spec` (Claude Code), `$spec` (Codex) or `@planr-spec` (Cursor) writes the spec, and `/planr:plan` (Claude Code), `$plan` (Codex) or `@planr-plan` (Cursor) writes the stories and tasks.
- `/ship` (Claude Code), `$ship` (Codex) or `@planr-ship` (Cursor) reads the task, its story, its acceptance criteria, and the spec before it changes code.
- `/planr:status` (Claude Code), `$status` (Codex) or `@planr-status` (Cursor) reads the files to report what is done, blocked, and next, without changing them.
- The `openplanr` CLI validates the planning files offline, never with a model, and [`openplanr sync`](https://openplanr.dev/docs/cli/sync.md) repairs cross-references between them.

## Review the plan like code

Commit `.planr/` with your code. A change to the plan then arrives as a diff in the same pull request flow as everything else, where your team can review it before an agent builds from it.

## Keep trackers in step

The CLI syncs planning files with GitHub Issues and Linear, so the plan in the repository and the tracker your team uses stay aligned. See the [`openplanr github`](https://openplanr.dev/docs/cli/github.md) and [`openplanr linear`](https://openplanr.dev/docs/cli/linear.md) references.