# Glossary

Vocabulary for the markdown backlog, multitenant product, and Cursor synchronization. Aligned with [Gas Town](https://github.com/gastownhall/gastown) ideas of **persistent, chunked work** agents can pick up without losing context.

## Backlog hierarchy


| Term                    | Meaning                                                                                                                                           |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Plan**                | Top-level initiative. One markdown tree root under `plans/`. Maps to a **Cursor plan** (or equivalent top-level container) when sync is enabled.  |
| **Epic**                | Coherent milestone under a plan. Groups related tasks; acceptable scope for a focused agent or subagent run.                                      |
| **Task** (working item) | Smallest tracked unit of work. Sized so a single Cursor agent session can usually complete or materially advance it. Prefer one concern per file. |


## Sync and tenancy


| Term               | Meaning                                                                                                                |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| **Tenant**         | Isolated customer or org boundary. All plans, epics, tasks, and **Cursor mappings** are scoped to a tenant.            |
| **Cursor mapping** | Stored association between app entities and Cursor artifacts (plan id, todo id, file path, or future API identifiers). |
| **Import**         | Creating or updating app records from markdown and/or Cursor state.                                                    |
| **Export**         | Writing or refreshing markdown (and optionally pushing state to Cursor).                                               |
| **Sync**           | Bidirectional reconciliation so neither side is silently stale.                                                        |


## Gastown-style chunking (conceptual)


| Gastown idea                  | Backlog analogue                                       |
| ----------------------------- | ------------------------------------------------------ |
| Beads / issues as durable ids | Stable task slugs + optional `id` in YAML frontmatter  |
| Convoys / epics               | **Epic** folders and epic docs                         |
| Rigs / town scope             | **Plan** per major initiative or product area          |
| Handoffs between agents       | Task doc **Owner**, **Status**, and **Links** sections |


## Document conventions

- **Frontmatter**: YAML at the top of Plan, Epic, and Task files for tooling (`status`, `priority`, `tenant_id`, `cursor_`* ids when known).
- **Status values** (suggested): `draft`, `ready`, `in_progress`, `blocked`, `done`, `cancelled`.
- **Priority** (suggested): `P0` … `P3` matching severity-style triage.

## Paths


| Path                                           | Role                                              |
| ---------------------------------------------- | ------------------------------------------------- |
| `plans/Plan-<slug>/`                           | Plan root directory.                              |
| `plans/Plan-<slug>/Plan-<slug>.md`             | Plan overview and epic index.                     |
| `plans/Plan-<slug>/Epic-<slug>/Epic-<slug>.md` | Epic definition and task index.                   |
| `plans/Plan-<slug>/Epic-<slug>/Task-<slug>.md` | Executable work item.                             |
| `config/CursorSync.md`                         | Sync behavior, limits, and per-environment notes. |

## Database tables (implementation)

| Table | Role |
| ----- | ---- |
| `markdown_backlog_items` | One row per imported markdown file under `plans/`, scoped by `workspace_id` (tenant). Stores parsed frontmatter, body, content hash, hierarchy (`parent_id`). |
| `cursor_sync_mappings` | At most one row per backlog item: Cursor plan/item ids and last push/pull timestamps. |