User stories your coding agent can build and check

A coding agent reads a story literally. Where the story leaves a gap, the agent fills it with a guess. This guide covers the parts of a story and a task that an agent can build from and a reviewer can check against, in the shape OpenPlanr's planning skills write them.

Why stories written for people fall short

A story written for a team leans on context the team already shares: the planning conversation, the design someone has in mind, the files everyone knows to leave alone. An agent has none of that unless the story or the task states it. A criterion such as "handles errors well" leaves the agent to decide what done means.

Write acceptance criteria an agent can check

Make each criterion observable: something a test, a browser check, or a reviewer can confirm without asking what you meant. The Given, When, Then form keeps it concrete:

Given an existing account, when the user requests a sign-in link, then an email with a single-use link arrives.

Give each criterion a stable ID, starting at AC-001, and keep one behavior per criterion, so a task can point at exactly the criteria it delivers.

Give every task its context

A task is where an agent starts work, so it carries what the agent and the reviewer need:

• Files. What to create, what to modify, and what to preserve. The Preserve list protects files the change must not touch.
• Dependencies. The tasks whose output this one consumes, and only those. Overlapping files and numbering are not dependencies.
• Rationale. Why the task exists.
• Review risks. The risk areas a reviewer should check: security, performance, migration, API contract, or data integrity.
• Acceptance references. The criteria the task delivers. The task's test requirements name each one again with an observable check.

Keep stories small. OpenPlanr's planning skill gives a story one Tech task, or one UI task and one Tech task when it has a design surface, and never more than 2.

A template you can copy

This story and task follow the files /planr:plan writes. Replace the parts in angle brackets.

---
id: "US-001"
title: "<what the user can do>"
specId: "SPEC-001"
slug: "<story-slug>"
schemaVersion: "1.7.0"
status: "pending"
created: "<YYYY-MM-DD>"
updated: "<YYYY-MM-DD>"
acceptanceCriteria:
  - id: "AC-001"
    statement: "Given <context>, when <action>, then <observable outcome>."
---

## User Story

As a <role>, I want <action>, so that <benefit>.

## Scope

<what this story covers>

## Acceptance Criteria

- **AC-001:** Given <context>, when <action>, then <observable outcome>.

## Task Breakdown

- T-001: <task title>

## Dependencies

<stories or tasks this one waits on, or none>

## Notes

<anything the agent needs that the criteria do not say>

---
id: "T-001"
title: "<task title>"
storyId: "US-001"
specId: "SPEC-001"
slug: "<task-slug>"
schemaVersion: "1.7.0"
type: "Tech"
agent: "backend-agent"
status: "pending"
created: "<YYYY-MM-DD>"
updated: "<YYYY-MM-DD>"
rationale: "<why this task exists>"
dependsOn: []
preserve:
  - { repositoryKey: "<repository>", path: "<file to leave unchanged>" }
reviewRisks: []
browserSurfaces: []
acceptanceRefs: ["AC-001"]
---

## Objective

<what this task accomplishes>

## Files

### Create

- <path>

### Modify

- <path>

### Preserve (do not touch)

- <file to leave unchanged>

## Technical Spec

<libraries, patterns, and integration points>

## Test Requirements

- **AC-001:** <the observable check that proves it>

## Definition of Done

- [ ] <the checks that must pass>

A checklist before an agent builds

• Each criterion is observable and has a stable ID.
• No criterion is left without a task that delivers it.
• Tasks list the files to create, modify, and preserve.
• A dependency points at a task whose output this task consumes, never at a file overlap.
• Test requirements name the criteria the task delivers, each with a check.
• The Definition of Done names the checks that must pass.

From a PRD to tasks

If you start from a PRD, turn it into a spec first with /spec. The skill shapes vague intent into measurable requirements and asks only about decisions that change the scope. Then run /planr:plan on the spec to get stories and tasks in the shape above. When a request is already clear and small, Plan can work from it directly.

Let your agent write them

/planr:plan writes stories and tasks in this shape, validates the frontmatter and the acceptance coverage, and stops before any code is written. Review them like code before anyone builds.

Next: Plan a feature.