---
title: User stories your coding agent can build and check
description: How to write user stories, acceptance criteria, and tasks a coding agent can build from and verify, with a template in OpenPlanr's format.
url: https://openplanr.dev/docs/guides/user-stories-for-coding-agents
updated: 2026-10-06
related:
  - https://openplanr.dev/docs/guides/plan.md
  - https://openplanr.dev/docs/guides/plan-mode-vs-written-plan.md
---

# 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` (Claude Code), `$plan` (Codex) or `@planr-plan` (Cursor) writes. Replace the parts in angle brackets.

```markdown
---
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>
```

```markdown
---
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` (Claude Code), `$spec` (Codex) or `@planr-spec` (Cursor). The skill shapes vague intent into measurable requirements and asks only about decisions that change the scope. Then run `/planr:plan` (Claude Code), `$plan` (Codex) or `@planr-plan` (Cursor) 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` (Claude Code), `$plan` (Codex) or `@planr-plan` (Cursor) 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](https://openplanr.dev/docs/guides/plan.md).