SpecRider App Icon SpecRider
Download
Guides

Best practices

How to structure a plans folder so agents and humans can collaborate on specs without stepping on each other.

SpecRider doesn’t care how you organize your specs — it’ll happily render any folder of Markdown. But after a few months of running this loop ourselves, a fairly opinionated structure has emerged. This page is that structure, plus the conventions that make agent-assisted spec writing actually work.

The system, in a nutshell:

  • One Markdown spec per feature, broken into phases and groups of tasks.
  • A folder per lifecycle stage: active/, upcoming/, backlog/, archived/.
  • An INDEX.md that lists prioritized specs in order — what to build next.
  • Frontmatter on every spec for status, owner, iteration, last review, and tags.
  • An AGENTS.md at the repo root that tells agents how to work on the specs.

One spec per feature

A spec is a single Markdown file. It describes one feature end-to-end — the why, the shape, and the work — broken into phases and groups of tasks. Two specs per feature, three specs, “I’ll split this in half later” — these all turn into orphaned half-plans. Keep it one file.

A spec usually goes:

  1. Title (H1) and a one-paragraph elevator pitch directly under it.
  2. ## Why — the motivation. Reviewers read this first.
  3. ## Approach or ## Shape — what the feature looks like once it lands.
  4. ## Implementation — phases, then groups of tasks within each phase, as GFM checkboxes.

Phases split work that ships independently. A “Phase 1 — read-only” can land before “Phase 2 — editing,” and the spec stays a single document throughout.

## Implementation

### Phase 1 — Read-only browser

- [ ] List plans recursively from the workspace root
- [ ] Render the rail with folder grouping
- [ ] Wire ⌘O to swap the workspace root

### Phase 2 — Editing

- [ ] CodeMirror editor with the standard keymap
- [ ] Save on ⌘S, persist via Tauri command

Folder layout

The plans repo is organized by lifecycle:

plans/
├── INDEX.md
├── AGENTS.md
├── active/        ← currently being implemented
├── upcoming/      ← next in line, scoped but not started
├── backlog/       ← ideas with enough shape to be a file, not yet scheduled
└── archived/      ← shipped, superseded, or dropped

Specs move folders as their status changes. The folder is the source of truth for where in the pipeline a spec lives; the status: frontmatter mirrors it so search and chips work. Keep them in sync — when you drag workspace-trust.md from upcoming/ into active/, change the frontmatter in the same commit.

Filenames are slugs only — no dates, no status prefixes, no leading numbers. Lifecycle lives in the folder, not the filename.

INDEX.md

INDEX.md is the prioritized list of specs. It lives at the repo root and answers one question: what should we build next? Order matters; the top of active/ and the top of upcoming/ are the next things to ship.

A minimal INDEX.md:

# Plans index

## Active

1. [Workspace trust](active/workspace-trust.md) — security gate for new folders
2. [Editor polish](active/editor-polish.md) — split view and save-state cleanup

## Upcoming

1. [Search hotkeys](upcoming/search-hotkeys.md) — ⌘T, ⌘F in Read mode
2. [Bookmarks](upcoming/bookmarks.md) — cross-plan bookmark popover

## Backlog

- [Multi-workspace](backlog/multi-workspace.md)
- [Mobile reader](backlog/mobile-reader.md)

The Active and Upcoming lists are numbered so priority is unambiguous. Backlog is unordered — it’s a pool, not a queue.

When a spec ships, move the file to archived/, flip status: to shipped, and delete the line from INDEX.md. The archive is browsable in SpecRider; you don’t need it cluttering the index.

Frontmatter

Every spec gets the same five-field frontmatter:

---
status: in-progress
owner: jake
iteration: 2
last_review: claude · 2026-05-08
tags: [accessibility, keyboard]
---

This is the same contract SpecRider uses for sorting, filtering, search, and outline status glyphs. The full reference is in Frontmatter contract — the short version:

  • status: — draft, upcoming, in-progress, shipped, implemented, superseded, backlog. Match the folder.
  • owner: — single handle. Accountable for the spec, not necessarily the only contributor.
  • iteration: — integer. Bump on meaningful rewrites; a 3 is on its third pass.
  • last_review: — <reviewer> · <YYYY-MM-DD>. Use a real handle (jake, claude, codex) and update both fields together when you do a read-through.
  • tags: — flow-style list, lowercase, kebab-case. Grep before inventing a new one.

The iteration and last_review fields are what make multi-pass spec writing legible. After an agent edits the spec, it bumps iteration and writes its own handle into last_review. When you next open the file, you can see at a glance whether you’re reading a fresh draft or something that’s been through three review passes.

Many teams keep specs in a dedicated plans repo while the implementation lives in one or more sibling repos. Use linked repos when a spec needs review tabs for those code changes. The full workflow is in Link code repos to a spec .

Agents and humans, same files

The whole point of this structure is that an agent can pick up a spec, edit it, and hand it back without anything bespoke. Two practical pieces make that work.

Initiate the agent from your code repo

Open the agent terminal inside SpecRider with your code repo as the cwd — not the plans repo. The agent’s primary job is to write code; the specs are context it reads and revises. Worktrees fit this well: one worktree per spec, agent runs in the worktree, plans repo is read alongside.

Add the plans folder with /add-dir

If you’re running Claude Code, give it explicit read/write access to the plans folder:

/add-dir ~/specs

That’s it. The agent can now open ~/specs/active/workspace-trust.md, edit it, check off tasks, and bump the iteration counter. SpecRider’s filesystem watcher picks the change up within ~50ms — no reload needed.

The same pattern works for any agent that takes an explicit working-directory grant: Codex, Aider, etc.

AGENTS.md

The single best thing you can do to make agent-written specs consistent is to drop an AGENTS.md at the root of the plans repo. Both Claude Code and Codex read it on startup and treat it as standing instructions. Without one, every agent improvises its own house style; with one, you get convergent specs across models.

Here’s a starter AGENTS.md that covers the rules on this page:

# AGENTS.md

You are working in a SpecRider plans repository. Specs are Markdown files that
describe features. Humans and other agents will read what you write.

## Folder layout

- `active/` — specs currently being implemented
- `upcoming/` — scoped but not started
- `backlog/` — ideas, may never ship
- `archived/` — shipped, superseded, or dropped

When you move a spec between folders, update its `status:` frontmatter to match.

## Spec structure

Every spec is a single Markdown file. The skeleton:

1. H1 title and a one-paragraph elevator pitch.
2. `## Why` — motivation.
3. `## Approach` — what it looks like when it lands.
4. `## Implementation` — `### Phase N — …` subsections, each with GFM
   task checkboxes (`- [ ]`).

One task per checkbox. Keep tasks small enough to be reviewable as a unit —
if a checkbox is hiding three independent pieces of work, split it.

## Frontmatter

Every spec has:

```yaml
---
status: <draft|upcoming|in-progress|shipped|superseded|backlog>
owner: <handle>
iteration: <int>
last_review: <handle> · <YYYY-MM-DD>
tags: [<kebab-case>, ...]
---
```

When you edit a spec, bump `iteration` and rewrite `last_review` with your
own handle and today's date. Do not bump `iteration` for typo fixes.

## Reviewing a spec

When asked to review:

1. Re-read the spec end to end and flag tasks that are stale, ambiguous,
   or already done but unchecked.
2. Update `last_review:` with your handle and today's date. Don't bump
   `iteration` unless you also rewrote sections.

## Style

- Tags are lowercase kebab-case. Grep `tags:` across the repo before inventing
  a new one.
- Filenames are slugs — no dates, no status prefixes, no numbers.
- Cross-link other specs by relative path: `[Trust](../active/workspace-trust.md)`.
- Dates are ISO 8601.

Drop that at the root of the plans repo and commit it. Iterate on it the same way you’d iterate on a CLAUDE.md or .cursorrules — agents will follow what’s in there, so when something keeps going wrong, the fix is usually a new bullet in AGENTS.md.

Putting it together

A healthy plans repo, in practice:

specs/
├── AGENTS.md
├── INDEX.md
├── active/
│   ├── workspace-trust.md     ← status: in-progress
│   └── editor-polish.md       ← status: in-progress
├── upcoming/
│   ├── search-hotkeys.md      ← status: upcoming
│   └── bookmarks.md           ← status: upcoming
├── backlog/
│   ├── multi-workspace.md
│   └── mobile-reader.md
└── archived/
    ├── docs-portal.md         ← status: shipped
    └── download-page.md       ← status: shipped

Open it in SpecRider, point your agent at it with /add-dir, and the spec-driven loop — write spec, review spec, implement spec, archive spec — runs cleanly between you and the agent without either side guessing the rules.

Start from the example repo

Rather than build this from scratch, clone the example plans repo . It ships the full folder structure, a starter AGENTS.md, an INDEX.md, and a few sample specs with proper frontmatter — delete the samples, keep the scaffolding, and you have a working plans workspace.