The Lovelace Format

A Lovelace project is a directory named .lovelace/ at the root of a repository. Every ticket, document, session, and comment is a single Markdown file with YAML frontmatter. The format is documented so thoroughly that you could create a valid project by hand.

The directory

.lovelace/
  manifest.yaml       project identity and spec version
  schema.yaml         ticket types (with their fields), statuses, priorities
  actors.yaml         you plus named agent identities
  board-order.yaml    optional; manual per-column card order
  AGENTS.md           agent instructions, installed and regenerated by the agent integration
  documentation/      nested knowledge tree; index.md is where an agent starts reading
    architecture/
      decisions/      ADRs
  tickets/            flat; one file per ticket, e.g. T-0142.md
  comments/
    <ticket-id>/      one timestamped file per comment
  sessions/           one file per agent session, e.g. S-0031.md
  templates/          scaffolds for new tickets, ADRs and sessions
  state/              gitignored; active ticket, presence, counters
  index/
    index.json        generated, gitignored
    BOARD.md          generated, committed

Principles

Files are the single source of truth. Indexes, boards and digests are derived and can be regenerated at any time. If the index and the files disagree, the files win.
One entity per file. Comments and session records are append-only siblings, never edits to existing bodies.
Volatile data lives in frontmatter; stable structure lives in the tree. A ticket never changes directory because its status or parent changed.
Unknown keys degrade gracefully. A warning, never a crash.

Identifiers

Prefix	Entity	Example
`T-`	Ticket (task, bug, …)	`T-0142`
`E-`	Epic	`E-0003`
`S-`	Session	`S-0031`
`ADR-`	Architecture decision record	`ADR-0007`

A ticket

---
id: T-0142
type: task
status: in_progress
created: 2026-06-02T09:14:00Z
updated: 2026-06-04T11:30:00Z
title: Validate link integrity in the indexer
parent: E-0003
assignee: ada
priority: high
estimate: 3
---

## Description

Parents, depends_on and reference fields must resolve to existing IDs.

## Acceptance criteria

- [ ] Unknown parent raises a file+line error

Core fields (id, type, status, created, updated) are reserved and managed by the tooling. Everything else, including your own custom fields, is defined in schema.yaml. See custom fields & schema for the why.

Documents

The documentation/ tree holds plain Markdown documents. Nothing in it is required: index.md is scaffolded at init as the place an agent starts reading, and a directory’s index.md, when present, is its landing page. Any other file name is fine.

Wiki-links ([[T-0142]], [[ADR-0007]]) connect documents and tickets; the Graph view draws the connections between documents.
review_by is an optional frontmatter date. A document past it gets a validation warning and a stale badge in the tree; warnings never block.
Mermaid fences render as diagrams in the app, in both read mode and the editor.