Write your first spec

A spec is the first file in the loop. It says what you want to change, why, and how anyone can tell the change is done, before your agent plans or builds anything.

Before you start, install the CLI, set up the skills for your agent, and initialize the project. Install and set up OpenPlanr covers all three, or let your agent do it. Restart the agent after setup so it loads the new skills.

Ask for the spec

Open the project in your agent and invoke /spec with the change you want and the problem it solves. For example:

Add passwordless sign-in for existing accounts. Users drop off at the password step.

The Turn a rough idea into a spec prompt has this example ready to edit and copy for your agent.

What the skill does

• It reads your request, the repository instructions, ADRs, product docs, existing plans, the relevant code and tests, and current behavior. Anything the repository already answers, it infers.
• When a missing decision would change the scope or the behavior, it asks you: at most 3 short questions at a time, with the recommended option first.
• It writes one specification. Requirements and acceptance criteria are observable, each criterion has a stable ID, and non-goals go under out-of-scope boundaries.
• It validates the file before it returns.

What you get

The spec is saved in your repository:

.planr/specs/SPEC-001-<slug>/SPEC-001-<slug>.md

Its sections follow the specification contract the skill ships with: Context & Goal, Audience, Outcome & Measurement, Functional Requirements, Business Rules, Constraints, Evidence Expectations, Failure Modes, Rollback, Scope Boundaries, Acceptance Criteria, Declared Risk Specialists, and Notes for Decomposition.

The reply leads with what is ready and links the saved file. It lists the decisions the skill made and the checks it ran, names any open question that still changes the product, and ends with the exact command to plan the spec next.

Review it, then plan

Read the spec the way you would read code, and commit .planr/ with your project. When the spec says what you mean, break it into stories and tasks with /planr:plan. Plan and ship are separate steps, and the agent never chains them on its own.

Next: Plan a feature, or copy Break a spec into stories and tasks.