61 lines
4.1 KiB
Markdown
61 lines
4.1 KiB
Markdown
|
# 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. |
|