⌘K
ChangelogSign inJoin waitlist
Docs/Projects/Overview
// PROJECTS

Projects

A project is a scoping workspace — a place to think through a larger piece of work before it becomes code. It pairs a planning thread with spec docs, and from that scope Leroy generates a set of tickets that ship the work together. Where a single ticket is one unit of work, a project is the shape of a whole effort.

01 What a project is

Most work doesn't arrive as one neat ticket. A feature, a migration, a refactor — they come as a fuzzy goal that has to be broken down. A project is where that breakdown happens:

  • A planning thread — a conversation with Leroy to scope the goal, talk through approach, and surface the open questions.
  • Spec docs — the written-down decisions and requirements the work should follow.
  • A generated set of tickets — the concrete units of work Leroy derives from the scope, ready to be planned and coded.

The thread and the spec docs are the input; the tickets are the output. As you refine the scope, the set of tickets it generates can be refined with it.

02 Project vs. a single ticket

Reach for a ticket when the work is already clear and self-contained. Reach for a project when the work needs to be scoped and split into pieces that depend on each other.

When to use it
Single ticket
One well-defined unit of work — a bug fix, a small feature, a tweak. Goes straight through triage → plan → code → review → ship.
Project
A larger effort that has to be scoped and broken down. Produces a set of related tickets that ship together against a shared branch.
i
Not just a folder.A project isn't a label for grouping loose tickets — it carries the scope (thread + specs) and the relationships between the tickets it generates, including which ones block which.

03 How a project comes together

  1. Start a planning thread. Describe the goal and talk it through with Leroy — the approach, the constraints, the unknowns.
  2. Write the spec docs. Capture the requirements and decisions the work should follow. These become the reference the tickets are built against.
  3. Generate tickets. Leroy turns the scope into a set of tickets and lays out how they depend on one another — a dependency graph, not a flat list.
  4. Leroy works them. It schedules the tickets as their blockers clear and integrates the results on a shared branch.

Decision and investigation work gets its own kind of ticket — a spike — that records an ADR instead of shipping a diff. See Decisions (ADRs).

04 The base branch

Tickets in a project ship against a shared integration branch rather than straight to your default branch, so the pieces come together in one place before they land. The base branch a ticket builds on is resolved by precedence, most specific first:

1
Request base branch
If the ticket itself names a base branch, that wins.
2
Project base branch
Otherwise the project's shared integration branch — where its tickets converge.
3
Repo default
If neither is set, the repository's default branch.
← Prev
Allowlist & trust