Write good requirements

The requirements doc is the only thing the swarm knows about what you want. A clear doc gets a better build in fewer iterations, which means lower cost. This guide covers the doc library and how to write a brief that builds well.

The doc library#

Requirements live in a library of named markdown docs on your phone. One doc is active at a time, and that's the one a run builds from.

• Open the library: on New Run → Requirements, tap the doc name at the top of the editor, or tap Open existing doc on the New Run launcher.
• In the library you can switch docs, rename or delete a doc (the icons on each row), create a New blank doc, and Import .md or Export .md through your phone's file picker. That can be local storage, Google Drive, iCloud Drive, and so on.
• Edits save automatically as you type. If the keyboard hides too much of the editor, see Phone keyboard tips.
• Tapping a starter project on the launcher loads that template. If the open doc hasn't been edited, it's reused, so picking the same project again, even after running it, doesn't pile up copies. A doc you've edited is never overwritten: the template opens as a new doc.
• The icon at the top right of the editor switches between the formatted preview and edit mode, where you edit the raw markdown.

Start from a template#

The 30 starter projects are complete, working briefs. Starting from the closest one and editing it is usually faster than writing from scratch. They also show the structure that works well:

# Tic-Tac-Toe

## Project Overview
A two-player Tic-Tac-Toe web app for a single device. Includes clear
win/draw detection and a one-tap restart.

## Stack
- Single-page HTML / vanilla JavaScript (no frameworks, no build step)
- Vanilla CSS for styling
- Files: `index.html`, `styles.css`, `game.js`

## Core Features
### Grid
- 3×3 grid of clickable cells, large enough to tap on a phone
- Clicking a filled cell does nothing

### Win / Draw Detection
- After every move, check all 8 winning lines
- On a win: highlight the winning three cells and freeze the board

## Acceptance Criteria
- All 8 winning lines correctly detect a win
- A full board with no winner is correctly detected as a draw
- Players cannot overwrite a filled cell
- `New Game` always resets state cleanly: board, status line and current player

Say what to build it with#

Name the stack and the files. Single-page HTML, CSS and vanilla JavaScript with no build step is the sweet spot. The generated app can then run directly in App Preview, and Visual QA and the acceptance tests can load it. Listing the files (index.html, styles.css, app.js) gives the Project Manager a clean way to split the work.

Describe features as behavior#

Write what the user does and what they should see, not how to implement it.

Quote exact on-screen text in backticks, such as New Game or Player O's turn. The developers use it verbatim, and the tests can check for it.

Write acceptance criteria that can be checked#

The Acceptance Criteria section matters most. The Analyst turns each line into a numbered criterion. QA gives each criterion a pass or fail, and the Test Author turns the functional ones into JavaScript tests that actually run. Criteria that can be answered yes or no give QA and the tests something real to measure, so the score moves for real reasons.

• Good: "Players cannot overwrite a filled cell." "Pressing Reset returns the display to 25:00."
• Weak: "The game works well." "The UI is intuitive."

Aim for 5 to 10 criteria for a small app. Cover the core rules, edge cases, and reset or empty states.

Keep scope honest#

The swarm builds what you describe, and every feature costs tokens. Start small, then add features with notes or by continuing the run. A tight brief that reaches Successful in two iterations beats a sprawling one still at 60 after ten.

Not sure what to write?#

Tap Discuss on the Requirements tab to have the Analyst interview you and draft the doc. See Refine requirements with the Analyst.