CLI Reference

Story maps

intent propose, map extract, map import, and map schema — planning changes and moving whole story maps in and out via JSON.

intent propose [name]

intent propose
intent propose add-dark-mode --from proposal.md

Plans a change before you start writing code. Interactively, it walks you through a change name, the problem, the solution, an activity, a priority, and one or more stories (each with a title, effort, and acceptance criteria); shows a summary; and on confirmation creates the stories on your map. It also saves a local copy to intent-changes/<slug>/proposal.md (and adds intent-changes/ to .gitignore if one exists) — so the plan is reviewable in your diff before anyone starts implementing.

--from <file> skips the prompts and parses a markdown file in this shape:

# Proposal: add-dark-mode
**Problem:** ...
**Solution:** ...
**Activity:** Appearance
**Priority:** should
 
## Add a theme toggle
**Effort:** M
- Toggle persists across sessions
- Respects prefers-color-scheme by default

Top-level **Problem:**, **Solution:**, **Activity:**, and **Priority:** fields set the change's metadata. Each ## Heading becomes a story title; **Effort:**, **Activity:**, and **Priority:** under it override the top-level values for that story; - bullets become its acceptance criteria.

intent map extract

intent map extract

Prints a long prompt — not a story map itself — designed to be handed to your AI coding agent. The prompt instructs the agent to reverse-engineer a story map from an existing codebase: investigate routes, auth, API endpoints, the data model, the stack, and billing tiers, then output a storymap.json file matching the schema (see intent map schema below). No network calls; it's pure text output. Once your agent produces the file, run intent map import ./storymap.json to load it.

intent map import <file>

intent map import storymap.json
intent map import storymap.json --yes

Reads and validates a storymap.json file against a strict schema before importing anything:

• Every story's user-story text must begin with "As a" or "As an."
• Every story needs evidence (a file path or description) and a confidence level (high, medium, or low).
• Activities may only contain activity and tasks fields — unknown fields are rejected.
• Open questions are capped at 50 items, 500 characters each.

Prints a summary — product summary, activity/task/story counts, confidence breakdown, open-question count — and asks for confirmation before importing (skip with --yes). Gated to the Builder plan (or BYOK). Returns the created counts on success.

intent map schema

intent map schema

Prints the JSON Schema for storymap.json to stdout — the authoritative reference for what intent map extract's agent prompt (or your own tooling) needs to produce for intent map import to accept it.