---
description: Authoring rules for the plans/ markdown backlog
globs:
  - plans/**/*.md
  - docs/templates/*.md
alwaysApply: false
---

# Markdown backlog (`plans/`)

This tree is the **source of truth for product work** and is parsed into `markdown_backlog_items` by [packages/database/src/markdown-backlog](mdc:packages/database/src/markdown-backlog). The parser depends on the layout — don't improvise.

## Layout (strict)

```
plans/
  Plan-<slug>/
    Plan-<slug>.md
    Epic-<slug>/
      Epic-<slug>.md
      Task-<slug>.md
```

- Slugs are lowercase-hyphenated and stable. Renaming a slug breaks Cursor sync — only do it deliberately.
- One Task per file. Tasks should be **bead-scale**: a single Cursor agent session can complete or materially advance the work.
- Use the templates in [docs/templates](mdc:docs/templates) ([plan](mdc:docs/templates/plan-template.md), [epic](mdc:docs/templates/epic-template.md), [task](mdc:docs/templates/task-template.md)).

## Frontmatter

Every Plan/Epic/Task file starts with YAML frontmatter. Required across all kinds:

- `kind` — `plan` | `epic` | `task`
- `slug` — matches the filename slug
- `title`
- `status` — `draft` | `ready` | `in_progress` | `blocked` | `done` | `cancelled`
- `priority` — `P0` | `P1` | `P2` | `P3`
- `tenant_id` — UUID or placeholder; scopes the row
- `updated_at` — ISO-8601

Plan adds `cursor_plan_id`. Epic adds `plan_slug`, `cursor_epic_id`. Task adds `plan_slug`, `epic_slug`, `owner`, `cursor_todo_id`.

## Conventions

- Don't reach across tenants. `tenant_id` scopes every record and every Cursor mapping.
- Don't put secrets, IPs, or homelab credentials in plans — these files are committed and synced.
- Cross-link with relative paths so links work both in the repo and in Cursor: tasks link to their epic and plan via `./Epic-<slug>.md` and `../Plan-<slug>.md`.
- Reference: [docs/Glossary.md](mdc:docs/Glossary.md) and [config/CursorSync.md](mdc:config/CursorSync.md).