---
title: openplanr spec
description: "openplanr spec: Spec-driven storage and validation for artifacts authored by the active host agent. Subcommands: init, create, shape, list, show, status."
url: https://openplanr.dev/docs/cli/spec
updated: 2026-10-06
related:
  - https://openplanr.dev/docs/cli/task.md
  - https://openplanr.dev/docs/cli/quick.md
  - https://openplanr.dev/docs/cli/checklist.md
---

# openplanr spec

Spec-driven storage and validation for artifacts authored by the active host agent.

```text
openplanr spec [options] [command]
```

## openplanr spec init

Activate spec-driven mode in this project (creates .planr/specs/ root)

```text
openplanr spec init [options]
```

## openplanr spec create

Create a new spec: a self-contained directory with stories/, tasks/, design/

```text
openplanr spec create [options] [title...]
```

Arguments:

- `title...` (optional): spec title (alternative to --title)

Options:

- `--title <title>`: spec title (required if not given as positional argument)
- `--slug <slug>`: explicit kebab-case slug; otherwise derived from title
- `--priority <priority>`: P0 / P1 / P2 (default: P1); default `"P1"`
- `--milestone <milestone>`: milestone label (e.g., v1.0)
- `--po <handle>`: Product Owner handle (e.g., @AsemDevs)

## openplanr spec shape

Author a decision-complete professional specification

```text
openplanr spec shape [options] <specId>
```

Arguments:

- `specId` (required): spec ID (e.g., SPEC-001)

Options:

- `--file <path|->`: read one bounded professional specification JSON object
- `--json`: emit one machine-readable result; default `false`

## openplanr spec list

List all specs in the project

```text
openplanr spec list [options]
```

## openplanr spec show

Print a spec + its decomposition tree (stories, tasks)

```text
openplanr spec show [options] <specId>
```

Arguments:

- `specId` (required): spec ID (e.g., SPEC-001)

## openplanr spec status

Decomposition state across all specs (or one spec if --spec specified)

```text
openplanr spec status [options] [specId]
```

Arguments:

- `specId` (optional): optional spec ID to scope output

## openplanr spec destroy

Remove a spec entirely (rm -rf of its self-contained directory)

```text
openplanr spec destroy [options] <specId>
```

Arguments:

- `specId` (required): spec ID (e.g., SPEC-001)

## openplanr spec attach-design

Copy PNG mockups into a spec's design/ directory and update ui_files frontmatter

```text
openplanr spec attach-design [options] <specId>
```

Arguments:

- `specId` (required): spec ID (e.g., SPEC-001)

Options:

- `--files <paths...>`: one or more PNG files to attach

## openplanr spec promote

Validate that a spec is ready and print the pipeline handoff command

```text
openplanr spec promote [options] <specId>
```

Arguments:

- `specId` (required): spec ID (e.g., SPEC-001)

## openplanr spec sync

Validate spec integrity (orphaned tasks, stories without tasks, missing specId frontmatter, schema drift)

```text
openplanr spec sync [options] [specId]
```

Arguments:

- `specId` (optional): optional spec ID to scope; otherwise scans all specs

Options:

- `--dry-run`: report findings without writing any fixes; default `false`