---

## kind: plan

slug: multitenant-cursor-sync
title: Multitenant backlog and Cursor synchronization
status: in_progress
priority: P0
tenant_id: global
cursor_plan_id: null
updated_at: "2026-04-26"

# Plan overview

Deliver a **multitenant** task application that treats **markdown plans, epics, and tasks** as a portable backlog, with a **data integration layer** that imports, exports, and keeps **Cursor** to-dos in sync. Work is **chunked** so Cursor agents and subagents can pick up single `Task-*.md` files without loading an entire program.

## Objectives and success criteria

- Every prioritized initiative has a **Plan** document and nested **Epic** / **Task** files under `plans/`.
- Tenants have **isolated** backlog trees and Cursor mappings (no cross-tenant leakage).
- Sync contract is documented in `config/CursorSync.md` and implementable as APIs + jobs.
- Templates in `docs/templates/` allow consistent authoring by humans and agents.

## Scope and boundaries

**In scope:** Directory layout, frontmatter conventions, glossary, sync config spec, example backlog slice.

**Out of scope (this plan):** Full Cursor API client, production webhook infrastructure, UI for conflict resolution (tracked as follow-up tasks).

## Cross-team collaborators


| Name / group          | Role                   |
| --------------------- | ---------------------- |
| Product / platform    | Tenant and sync policy |
| Application engineers | tRPC/DB mapping layer  |


## Epics


| Epic                       | Link                                                 |
| -------------------------- | ---------------------------------------------------- |
| Markdown backlog structure | `./Epic-markdown-backlog/Epic-markdown-backlog.md`   |
| Cursor sync layer          | `./Epic-cursor-sync-layer/Epic-cursor-sync-layer.md` |
| Multitenancy               | `./Epic-multitenancy/Epic-multitenancy.md`           |


## Metrics and milestones


| Milestone           | Target | Metric                                    |
| ------------------- | ------ | ----------------------------------------- |
| Repo-backed backlog | M1     | ≥1 full plan tree + templates merged      |
| Read path import    | M2     | Parser ingests frontmatter + body into DB |
| Cursor loop         | M3     | Push/pull job succeeds in staging         |


## Risks and mitigations


| Risk                   | Mitigation                                                                 |
| ---------------------- | -------------------------------------------------------------------------- |
| Cursor public API gaps | Start with file-based export + manual id paste; abstract `cursor`_* fields |
| Sync conflicts         | Default to explicit modes in `CursorSync.md`; add `content_hash` later     |


## Gastown alignment

Treat each **Task** as a **bead-scale** unit of work: one clear outcome, stable path, enough context in-file for a new agent session. **Epics** correspond to convoy-scale milestones; this **Plan** corresponds to a rig-level initiative.