48 lines
1.9 KiB
Text
48 lines
1.9 KiB
Text
|
---
|
||
|
|
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).
|