A lightweight, file-based issue tracker. Your Agile board lives in your repo as
folders and markdown files, versioned with git — no server, no database, no
account.
A lightweight, file-based issue tracking system. Agile boards as folders and markdown.
2026-11-08
Estrelas
—
Ferramentas
—
Disponibilidade
—
Specifically designed for agentic workflows:
Ships with an MCP server and agent skills.
Integrated work queue that provides agents with optimized context on the tasks to perform.
Helps the human in the loop to review work, implement control gates and determine how the development pipeline gets executed.
Install
Requires Node 20+. The package is light-plan and the command it installs is
lpm:
npm install -g light-plan
lpm init
Or run it without installing anything:
npx light-plan init
npx light-plan ui
To get started:
cd my-project
lpm init # create the board in .lpm/
lpm ui # open it in your browser
lpm init writes the board into .lpm/ in the current folder. It uses the
Scrum template (--template kanban or --template blank for the others) and
takes the issue-id prefix from the folder name (--prefix LP to choose your
own). It also makes .lpm a git repository of its own and adds it to your
project's .gitignore, so the board keeps its own history (--no-git skips
that). On a template with a timeline it also creates a standing Omni Product
Increment holding an Omni Sprint, and every new issue lands in that sprint
until you create a period of your own, so a simple project never has to plan
sprints at all (the omni periods; --no-omni skips them).
A new board starts in queue mode. In queue mode, lpm task next, the agents
and the web app ignore every sprint and increment. They order the work by
priority and by dependencies. lpm init prints the mode, and lpm planning periods switches the board to sprint planning at any time
(planning by queue; --planning periods
starts the board in that mode).
lpm ui starts a local server on http://localhost:4571 and opens the editor
in your browser. When port 4571 is taken, the server uses the next free port, up
to 4590. What you change there is held as a draft until you press
Push, which writes it to .lpm/. Stop the server with Ctrl-C. To build a
board from the command line instead, see Quick start.
light-plan ships agents (a developer and a planner), skills and an MCP server
for AI coding hosts. If you manage agent configuration with
hcm
(harness-config-manager), register the light-plan bundle once, then install it
into any project:
npm install -g harness-config-manager # hcm itself, once per machine
lpm hcm init # register the bundle; again after each light-plan upgrade
# then, in each project
hcm install light-plan -t claude-code # developer and planner
hcm install light-plan -t copilot --flavor developer # the developer agent only
hcm update light-plan # after re-running lpm hcm init
-t names the harness (hcm targets lists them) and --flavor picks a role
(developer or pm). The MCP server starts as lpm mcp, so agents need lpm
on their PATH: install light-plan globally, not only through npx. Without hcm,
lpm agent installs the same files straight into a
project. The details are in
The same assets as an hcm bundle and
docs/hcm.md.
From a checkout
make setup # installs, builds, and puts `lpm` on your PATH
Requires GNU Make. Without Make:
npm install
npm run build
npm link # puts `lpm` on your PATH
make doctor checks your machine before you start, and make on its own lists
every target. See Development.
How a board is laid out
.lpm/
├── config.yml
├── INDEX.md every id, title and document, nested (generated)
├── board/ what gets built
│ └── LP-1/ program — Payments platform
│ ├── _issue.md
│ └── LP-2/ epic — Checkout revamp
│ ├── _issue.md
│ └── LP-3/ feature — Guest flow
│ ├── _issue.md
│ ├── LP-4/ user story — Guest checkout
│ └── LP-5/ bug — Cart total
├── timeline/ when it gets built
│ └── TL-1/ product increment — 2026 H2
│ ├── _period.md
│ ├── TL-2/ sprint 1
│ └── TL-3/ sprint 2
├── team/ who builds it
│ ├── RS-1/ a person — Alice Smith
│ │ └── _resource.md
│ └── RS-4/ a pool anyone can be drawn from — Jr. developer
│ └── _resource.md
├── library/ documents beside the plan: prompts, summaries, PRDs
│ ├── prd/payments.md library:prd/payments
│ └── prompts/code-review.md
└── templates/context/ what a developer is told to do it
├── default.md
└── user_story.md
Folder nesting is the hierarchy. Each folder is one document; its markdown
file holds YAML frontmatter (the structured fields) plus a body (the narrative).
Everything is plain text, so diffs, blame, branches, and pull requests work
exactly as they do for code.
A folder is named after its id and nothing else. Ids are short and never
change, so a path stays quotable, a title can be rewritten without moving
anything, and a board nested five levels deep does not run into the limits git
and Windows put on a path. The titles live in
.lpm/INDEX.md, which every
command that adds, removes, moves or renames a document rewrites for you.
There are three collections. board/ holds issues — what gets built, nested
by scope. timeline/ holds periods — sprints and increments, nested by
duration. team/ holds resources — the people who do the work and the
generic pools work can wait in. They are independent: an issue at any level can
be scheduled into a period at any level via its period: field, and assigned to
any resource via its assignee: field.
templates/context/ holds no documents. It is the one folder the engine never
walks: the layouts lpm instructions renders a working brief
with, so a team decides what a developer is handed when they pick an issue up.
library/ holds the board library: markdown documents
that belong beside the plan and are not a piece of it.
Keeping boards outside the project: the central store
A board can keep its documents in one folder on your computer, outside the
project folder. That folder is the central store. You name it once:
cd ~/boards && lpm set central_store # or: lpm set central_store --path ~/boards
The command writes the key central_store in settings.json of the user
folder (~/.light-plan, or the folder that LPM_HOME names). When another
folder is already the central store, it asks whether to move the boards there
(--move), to abandon the old store and keep its boards in place
(--abandon), or to cancel. When the key is
set, lpm init asks where to create each new board. --central and --local
answer without the question. Without a terminal, lpm init creates a local
board.
~/boards/
└── .lpm_central/
├── shop/ the board of ~/work/shop: config.yml, board/, ...
│ └── project.json { "project_path": "~/work/shop" }, never committed
└── shop-2/ the board of another folder called shop
~/work/shop/
└── .lpm/
└── config.yml store: "~/boards/.lpm_central/shop"
The central board folder holds the same files as a .lpm folder, and it is its
own git repository. The project keeps .lpm/config.yml with one key, store,
whose value is the absolute path of the central board folder. Every lpm
command run in the project follows it.
lpm store move --to central and --to local move an existing board, with
its git history. lpm store list lists the central boards.
Each move backs the board up first, into
<central_store>/.lpm_backups/<name>_backup. The move deletes the original
folder only after the copy has the same files, sizes and SHA-256 digests. Each
board has one backup. lpm store backup writes it, and replaces an existing
backup only with --replace. lpm store backups lists the backups.
lpm store restore --yes overwrites the board with its backup.
Each lpm command also records its project in projects.json of the user
folder, so lpm projects lists every board on the computer, local or central.
In the web app, File > "All projects…" shows the same list. Each row has the
buttons Open, Reveal, Move to central (or Move to project) and Back up. The
arrow before the name of a project opens a section with the views of its
board: the name and the description of each view. A click on a view name opens
the board on that view. A move
or a backup runs in the background, and the row shows a progress bar. The tab
Backups lists each backup with its date and its age in days, and Restore
overwrites the board. File ▸ Board configuration… has the same actions for
the open board, on the tab Storage. lpm ui in a folder without a board opens
the "All projects" page when a central store is set. docs/central-store.md
is the full guide, with the assumptions and the known issues.
Quick start
cd my-project
lpm init # creates .lpm/ from the scrum template
# What gets built
lpm new program -t "Payments platform" # -> LP-1
lpm new epic -t "Checkout revamp" -p LP-1 # -> LP-2
lpm new feature -t "Guest flow" -p LP-2 # -> LP-3
lpm new user_story -t "Payment gateway" -p LP-3 --set story_points=5
lpm new user_story -t "Guest checkout" -p LP-3 --set story_points=3
# When it gets built
lpm new increment -t "2026 H2" --starts 2026-07-01 --ends 2026-12-31 # -> TL-1
lpm new sprint -t "Sprint 1" --starts 2026-08-03 --ends 2026-08-14 -p TL-1
# Who builds it
lpm new person -t "Alice Smith" # -> RS-1
lpm new role -t "Jr. software developer" --capacity 3 # -> RS-2, a pool of three
lpm link RS-1 --covers RS-2 # Alice can pick up the pool's work
# Wire it together
lpm link LP-5 --depends-on LP-4 # LP-5 is blocked by LP-4
lpm move LP-4 --period TL-2 # schedule into Sprint 1
lpm move LP-4 --assignee RS-2 # park it in the junior pool
# Reuse what the team already worked out
lpm template list # the registry: reusable pieces of plan
lpm template apply TPL-3 --set name=Payments --under LP-4
# Work it
lpm me "Alice Smith" # this checkout is Alice's
lpm task next # what should I do?
lpm task start # claim it and start the clock
lpm task done
lpm queue simulate --user "Alice Smith" # her whole run, if she worked alone
lpm check # validate everything
lpm new <type> decides what to create from the type name: issue types land in
board/, period types in timeline/, resource types in team/. A name can't
mean two of those — the config rejects that.
A generated issue:
---
id: LP-5
type: user_story
title: Guest checkout
status: backlog
assignee: RS-1
period: TL-2
depends_on:
- LP-4
relates_to: []
related_files:
- docs/prd.md#L120-L164
- src/checkout/session.ts
created: 2026-07-31T15:02:27.576Z
updated: 2026-07-31T15:03:10.114Z
author: Jane Doe <[email protected]>
story_points: 3
priority: medium
labels: []
---
As a **<role>**, I want **<capability>**, so that **<benefit>**.
## Acceptance Criteria
- [ ] **Given** <context> **when** <action> **then** <outcome>
Dependencies
Two reserved fields on every issue:
Field
Meaning
depends_on
Issues that block this one. Directional, cycle-checked.
relates_to
Non-blocking association. No ordering implied.
lpm link LP-7 --depends-on LP-3
lpm link LP-7 --depends-on LP-3,LP-4 --relates-to LP-9
lpm link LP-7 --depends-on LP-3 --remove
lpm new user_story -t "Checkout" -p LP-3 --depends-on LP-4
depends_on is the only edge the engine acts on. There used to be a third,
informed_by, for the research an issue rested on — it gated the queue in
exactly the same way, which made it a second name for one relationship. It is
gone: why an issue is written the way it is belongs in its body and its
related files, and if work cannot start until a question is
answered, that is a dependency. A board still carrying the field is migrated by
lpm check --fix, which merges the ids into depends_on.
Only the forward edge is stored. The inverse — "what does this block?" — is
derived when the board loads and exposed as board.dependents. Storing both
sides would mean two files to keep in sync on every change, and a whole class of
reconciliation bugs for check --fix to chase.
A dependency is inherited by everything inside the issue. A story sits in a
feature, and a feature that waits on another feature waits on it with
everything in it — so you write the edge once, between the two features, and
the queue holds back every story under the second one. You do not have to wire
each story to each other story, and lpm task next will not hand somebody the
stories of a feature whose predecessor has not been started.
A dependency on a container is cleared by the work inside it, not by the
container's own status. Nobody moves a feature through the columns — the stories
under it are what get worked — so LP-7 --depends-on LP-3 is satisfied once
every open piece of work under LP-3 is finished, whatever column LP-3 itself
is sitting in. Closing LP-3 outright still answers for its contents, and
lpm task next names the dependency the way you wrote it (the feature, not the
five stories in it), because that is the document you would open to see where it
stands.
lpm link LP-4 --depends-on LP-3 # feature LP-4 after feature LP-3
lpm task next # ...and no story under LP-4 is offered yet
lpm queue simulate # the whole sequence, in dependency order
A dependency is reflected onto the containers above it, up to the one they
share. The inheritance above runs downward — an edge on a feature holds back
every story in it. This is the same fact read upward. A story in Guest flow
waiting on a story in Sign-up means Guest flow stands behind Sign-up, and
the two epics above them stand in the same order, and so on until the container
they both sit in, inside which there is nothing left to order. Write the edge
between the two pieces of work that actually have it; the levels above it are
read off the graph:
lpm link LP-4 --depends-on LP-7
# Linked LP-4 Guest checkout
# depends on + LP-7
# also orders LP-3 Guest flow after LP-6 Sign-up
# also orders LP-2 Checkout after LP-5 Accounts
lpm upstream LP-3 # ...and the feature reads it back
The reflection is never written onto those containers, and both halves of
that are deliberate. A depends_on on Guest flow would be inherited by every
story in it, so one story waiting on one story would hold back a dozen that are
waiting on nothing. And the reflection is not acyclic — two features that each
contain a story waiting on the other are an ordinary plan, and writing that down
would produce a loop lpm link has to refuse. So it is read, never gated: it
changes nothing about what the queue offers, and a loop in it is a fact about
the plan rather than a stall. It shows up in lpm link, in lpm upstream, in
the MCP get_document (rolledUpBlockedBy / rolledUpBlocks) and in the web
side panel, always naming the written dependency it comes from.
lpm link refuses an edge that would close a cycle, so bad state never reaches
the files. lpm check catches cycles introduced by hand-editing or by a merge,
along with references to issues that don't exist, self-references, and
duplicates. It also warns when a done issue is blocked by an unfinished one.
An edge pointing at one of the issue's own ancestors is ignored when work is
ranked rather than treated as a block — it could only stall the work on itself.
Related files
An issue is usually about some code. related_files says which:
lpm new user_story -t "Guest checkout" -p LP-3 \
--related "docs/prd.md#L120-L164" --related src/checkout/session.ts
lpm set LP-5 --related src/checkout/pay.ts # attach another
lpm set LP-5 --unrelated src/checkout/session.ts # detach one
Each entry is a path from the project root, optionally with a line range —
docs/prd.md#L120-L164 points at the paragraphs of the PRD the story was written
from, src/checkout/session.ts at the module it will change. It is plain text
and never checked against the filesystem: an issue naming a file that does
not exist yet is usually the point of the issue, and a board that failed check
because somebody renamed a module would teach people to stop filling this in.
Two things read it. A working brief prints the issue's own files under Files
this is about — the first thing to open — and, for each issue this one was
sequenced after, the files that work touched. And the web app shows them in the
side panel, where they can be edited as one path per line.
An entry that starts with library: names a document of the
board library instead of a file. The brief prints the
body of that document, and the side panel shows the entry as a button that
opens the document.
That second part is what makes the field worth the typing. A story that says
"depends on LP-4" tells you the order; a story that says "depends on LP-4, which
touched src/checkout/session.ts, and I am about to change the same file" tells
you to go and read what LP-4 did first.
The board library
The board library stores markdown documents in .lpm/library/<id>.md. The id
is the path below the folder without .md, for example prd/payments. Use the
library for prompts with instructions, summaries of developments and product
requirement documents.
lpm library new prd/payments -t "Payments PRD" -f ./prd.md # add a document
lpm set LP-4 --related library:prd/payments # reference it from an issue
lpm library # list the documents
lpm library show prd/payments # print the body
lpm library refs prd/payments # the issues that reference it
lpm library mv prd/payments requirements/payments # rename it, and rewrite the references
lpm library rm requirements/payments # delete it
lpm library mkdir archive/2026 # a folder, kept in git while it is empty
lpm library mv prompts archive/prompts # move a folder with everything inside it
lpm library tree # the folders and the documents, nested
An issue references a document with the related file library:<id>, or with a
link [label](library:<id>) in its body. The working brief of the issue prints
each document that the issue or one of its ancestors references, so
lpm instructions and lpm queue agent hand the document to whoever works the
issue. A registry template can hold the same references, and its placeholders
work in them. The MCP tools list_library, get_library_document,
create_library_document, update_library_document,
move_library_document, delete_library_document, create_library_folder
and delete_library_folder give an agent the same access. In the web app, the
button Library in the top row, or File ▸ Library…, opens the Library
page in its own window. The page shows the folders and the documents as a
tree, moves an item when it is dragged onto a folder, and edits a document
with the editor of the issue window. docs/library.md is the full guide.
Time hierarchy
Periods answer "when does this get built?". They are configured exactly like
issue types — their own hierarchy, their own attributes, their own body
templates — and live under .lpm/timeline with real files carrying their own
metadata:
---
id: TL-2
type: sprint
title: Sprint 1
starts: 2026-08-03
ends: 2026-08-14
created: 2026-07-31T16:52:14.421Z
author: Jane Doe <[email protected]>
goal: Guests can pay without an account
capacity: 34
committed_points: 31
completed_points: null
---
## Sprint Goal
One sentence the team can rally behind.
## Review
...
## Retrospective
...
starts and ends are reserved and required. Everything else — goal, capacity,
committed/completed points, PI objectives, retro notes — is configurable
per period type.
A project that does not plan by the calendar should not have to invent sprints
before it can work. So lpm init seeds one standing period per level of
period_hierarchy — TL-1 Omni Product Increment holding TL-2 Omni Sprint on
the Scrum template, CY-1 Omni Delivery Cycle on Kanban — each running for a
year from the day the board was made, and writes default_period: TL-2 into the
config. Every new issue nobody scheduled lands there, from the CLI, the web app
or an agent alike, so the running sprint holds the whole board.
The catch-all stops the moment you plan for real. As soon as the timeline holds
a period that is not part of the omni chain, new issues arrive unscheduled for
you to place, because ranking them beside your sprint would undo the plan. What
the chain already caught stays there until you move it. When you are done with
it, lpm rm TL-1 deletes the chain and unschedules what is left, and the
default_period line can go.
lpm new user_story -t "Fix login" -p LP-3 # scheduled in TL-2
lpm new user_story -t "Someday" -p LP-3 --period none # left unscheduled
lpm period TL-2 --start-now # a year on: renew it
A pull from a tracker never uses the catch-all: an issue the tracker holds
unscheduled arrives unscheduled. The full rules are in
docs/periods.md.
Planning by queue: lpm planning
Some teams plan in sprints and increments. Others work through the board in
order, and do not care which sprint a ticket is in. A board has a planning mode
for each way of working, and can switch between the two at any time.
The key planning in .lpm/config.yml stores the mode:
Value of planning
Mode
Who writes it
queue
Queue mode: the queue ignores every period
lpm init (the default for a new board), lpm planning queue, the switch in the web queue panel
periods, or the key is absent
Periods mode: sprints and increments order the work
lpm init --planning periods, lpm planning periods, the same switch
A new board starts in queue mode, because most projects start without a sprint
plan. A board that light-plan 0.1.2 or an earlier version created has no
planning key, so that board stays in periods mode until somebody switches it.
A board with no period types is always in queue mode.
lpm planning # which mode the board is in
lpm planning queue # work the board as one continuous queue
lpm planning periods # plan with sprints and increments again (also: pi)
In queue mode the whole board reads as one increment holding one sprint
holding everything. lpm task next, lpm queue simulate, lpm queue agent, the
MCP tools and the web queue ignore every period:
No sprint ranks ahead of another.
A switched-off period no longer holds its work back.
No squad owns a sprint, so anybody routed the work can take it.
The order is priority, then column, then the feature already under way, then how
much finishing a task unblocks. The web app stops drawing periods too: the
Periods and Gantt tabs, the period badges on the canvas, and the period field and
column all go away until you switch back.
Switching is non-destructive. No document changes. Every issue keeps its
period:, and every period keeps its dates and its switch. lpm planning periods removes the key planning and its two comment lines from
.lpm/config.yml, and lpm planning queue adds them again. The mode is board
config, so the team shares it, and a board shared through git commits and
pushes the change. The rules are in
docs/periods.md.
Which period is running
A period runs when today falls inside it, and that is all most boards ever need.
But plenty of teams do not plan by date, and every team occasionally needs to
reroute people mid-sprint — so there is a switch held over the calendar:
lpm period TL-2 # how it stands right now
lpm period TL-2 --on # run it whatever the dates say
lpm period TL-2 --off # park it
lpm period TL-2 --dates # take the switch off; the calendar decides again
lpm period TL-2 --start-now # move it to start today, keeping how long it runs
--on and --off write one optional reserved field, active, on the period
document; --dates removes it. Absent is the normal state — a board that
never touches the switch behaves exactly as it always did.
The two directions are deliberately not symmetric. Switching a period off
parks everything nested inside it: "not this quarter" would mean nothing if its
sprints kept running. Switching one on speaks for that timebox alone,
because a live quarter has never meant all six of its sprints are this week.
What it changes is what gets offered, never what is reachable. Work in a
switched-off period sinks below even unscheduled work in lpm task next, the
MCP next_tasks and the queue — which is what makes the switch a way to steer
a team at short notice. Nothing is hidden, and no document becomes unreadable.
--start-now is the other half: it rewrites dates rather than overriding them.
The period takes today and keeps how long it runs, every period nested inside it
moves by the same number of days so a restarted increment keeps its shape,
whatever else was running is closed yesterday, and the periods above stretch to
reach. In the web UI both live on every box in the Periods tab: a toggle, and a
"Start now" button that says what it is about to change before it changes it.
When a sprint overruns
A period whose end date has passed while work in it is still open is flagged in
red, on the CLI and in the Periods tab. There are exactly two honest answers,
and both are offered rather than one being chosen for you:
lpm period TL-2 --complete # move the open issues to the board's end state
lpm period TL-2 --carry-over # move them into the next period beside it
Completing records that the team stopped, not that the work happened. Carrying
over leaves what was finished where it was delivered — that is the record of the
sprint — and moves the rest one period along. Neither invents a period, so
carrying work down a run is what makes the last sprint's backlog grow, which is
the fact worth seeing. When there is no period after the one being corrected,
the command refuses rather than quietly unscheduling the work.
Both act only on issues scheduled directly in the period: an increment answers
for its own epics, and the sprints inside it answer for their own stories.
docs/periods.md is the full reference: how the dates and the
switch combine, exactly what each bucket of the work queue holds, and what
restarting or correcting a period moves.
Because the hierarchies are independent, a feature can sit in an increment while
its stories sit in individual sprints — the transversal cut. lpm check
validates that periods have real dates, that ends is not before starts, that
a child period fits inside its parent, that siblings don't overlap, and that
every issue's period points at a period that exists.
It also warns when an issue is scheduled before something it depends on:
warn scheduled in TL-2 (2026-08-03) but depends on LP-4,
scheduled later in TL-3 (2026-08-17)
That check is the reason both features earn their keep together.
Periods are opt-in. Drop period_prefix, period_hierarchy and period_types
from the config and the timeline disappears; the blank template ships without
them.
Team and resources
Resources answer "who does the work?". They live under .lpm/team, are
configured exactly like issue and period types, and come in two flavours:
What it is
Example
named
A person
Alice Smith
generic
A pool of interchangeable people
"a jr. software developer", "a data scientist, any level"
Which one a document is comes from its type, not from the document —
a resource type declared generic: true describes a pool:
resource_types:
person:
label: Person
role:
label: Role
generic: true
---
id: RS-4
type: role
title: Jr. software developer
capacity: 3
covers: []
created: 2026-07-31T16:12:02.104Z
author: Jane Doe <[email protected]>
discipline: backend
level: junior
skills: [typescript, sql]
---
## What this pool covers
capacity is full-time equivalents: 1 a full-timer, 0.5 someone part-time,
3 a pool of three. 0 means unavailable, and lpm check warns if you assign
work to them anyway.
lpm new person -t "Alice Smith" --set [email protected]
lpm new role -t "Jr. software developer" --capacity 3 --set level=junior
lpm new person -t "Bob Jones" --capacity 0.5
lpm move LP-4 --assignee RS-1 # to a person
lpm move LP-4 --assignee "Jr. soft" # by name, or a unique prefix of one
lpm move LP-4 --assignee none # back to nobody
Park work in a pool and anyone who covers that pool can pick it up:
lpm link RS-1 --covers RS-4 # Alice can work as a junior developer
lpm link RS-1 --covers RS-4 --remove
Coverage stores only the forward edge, exactly like depends_on; the inverse is
derived at load time into board.coveredBy. It is one hop and not transitive: a
pool covering a pool does not chain.
lpm team shows who is carrying what:
Roster
RS-1 Alice Smith person 1 FTE open 4 wip 1 done 2 story_points 13 covers RS-4
RS-2 Bob Jones person 0.5 FTE open 1 wip 0 done 0 story_points 3
Pools
RS-4 Jr. software developer pool 3 FTE open 7 wip 0 done 1 story_points 21 covered by RS-1
RS-5 Sr. data engineer pool 1 FTE open 3 wip 0 done 0 story_points 8 nobody covers this
-- (unassigned) open 2 wip 0 done 0 story_points 5
Total 5.5 FTE · 17 open · 1 in progress · 50 story_points · 9.1 per FTE
warn RS-5 (Sr. data engineer) holds open work but nobody covers it
warn 2 open issue(s) have no assignee
lpm team --period TL-2 scopes it to one sprint (and its child periods), which
is where over-commitment actually shows up. Only work units are counted, so a
feature does not double-count the stories under it, and a story marked
atomic does not double-count its own sub-tasks.
This is deliberately a load view, not a scheduler: it reports demand against
declared capacity, and names the two situations that mean work simply cannot
happen — a pool nobody covers, and open work nobody owns. What "too much" means
for your team stays your call.
The roster is opt-in the same way the timeline is: drop resource_prefix,
resource_hierarchy and resource_types and team/ disappears.
Squads
A squad is a named sub-team of resources — "Frontend", "Platform", "Data".
When a period is owned by a squad, only that squad's members are offered work
from it. This lets two teams run independent plans inside one board: one
increment per squad, sprints grouped under it, and lpm task next shows each
person their squad's work.
Squads are configured exactly like the rest, and opt-in the same way:
---
id: SP-1
type: squad
title: Frontend
members: [RS-1, RS-5, RS-8]
created: 2026-08-03T12:00:00.000Z
author: Alice Smith <[email protected]>
---
Assign a squad to a period (lpm set TL-1 --squad SP-1), and the period's work
is gated through the routing. A sprint with no squad inherits from its
increment, the same way the active switch cascades; a sprint can override with
its own.
The squad engine lives in src/core/board/query.ts (effectiveSquad),
board/tasks/ranking.ts (the candidatesFor gate), and board/load.ts
(periodSquadMembers). The web UI manages squads in the Team drawer.
Working as a team member
Tell light-plan who you are, then ask it what to do:
lpm me "Alice Smith" # or `lpm me RS-1`; `lpm me` alone prints it
lpm task next # what to work on, best first
lpm task start # claim the top one: assign it to you, start it
lpm task current # what you have in flight
lpm task done # move it to the board's end state
lpm task prev # what you finished most recently
$ lpm task next
Next up for RS-1 Alice Smith
LP-12 Guest checkout User Story · ready TL-2
LP-9 Cart totals User Story · backlog TL-2 · pool RS-4
Claim the first with lpm task start
lpm task next offers work units that are assigned to you, or parked in a
pool you cover, and that nothing unfinished is blocking. Add --unassigned to
include work nobody owns. Containers (an epic with children) are never offered —
the work units under them carry the work. Which issues are units is a config
question; see the unit of work.
Work in a period somebody has switched off is not
offered at all — off means "not this one", and ranking it last would only
delay it until the rest of the queue emptied. --parked considers it anyway,
and lpm open/lpm task start <id> reach it by id regardless: this is routing,
not permission.
The order of what remains is: the running or overdue period first, then
unscheduled work, then periods that have not started; within that, the board's
priority_attribute, then the column closest to done, then the part of the
plan that is already under way, then how much each issue unblocks, then age.
That middle step is what keeps a queue from handing out one story from every
feature in turn. When nothing a person set by hand separates two stories, the
one whose feature somebody is already inside comes first, then the one whose
feature is closest to finished, and work in an untouched feature comes last.
The question is asked of the outermost level the two do not share, so an epic
under way is preferred before its features are ever compared, and two stories
in the same feature are never separated by it.
lpm task start [id] assigns the issue to you and moves it to the first status
marked active: true; lpm task done [id] moves it to the first terminal: true
one. Both take an id, and both default to the obvious one — the top
recommendation for start, your single in-flight issue for done. Claiming
someone else's issue needs --force.
Claiming is atomic
lpm task next is a recommendation, and between reading it and acting on it
somebody else may have taken the same issue — another developer in the same
checkout, an agent, a lpm queue agent run. So start is not "write my name on
it". It takes the board's write lock, re-reads the board, checks the issue is
still free as it stands on disk, and only then writes:
$ lpm task start LP-12
error LP-12 is already being worked on by Bob Chen (RS-2)
It is "in_progress" on the board as it stands now, and Alice Smith (RS-1) is asking for it.
Force takes it off somebody who is part-way through it. Take something else instead.
The claim is recorded in the issue document itself, not only in its frontmatter:
## Activity
### 2026-08-16T09:14:02.104Z — Alice Smith (RS-1) — claimed
The frontmatter is what withholds the issue from everybody else's queue — work
in an active status is never offered, and the rest is routed by assignee — and
the activity line is how a person reading _issue.md in a file tree, or a diff
in the board's git history, finds out who took it and when. The same is true of
the MCP start_task and of every task lpm queue agent picks up.
A run that loses a claim is not a run that failed. lpm queue agent asks the
queue again and takes the next thing; the issue it lost is left completely
untouched — no flag, no comment, no status change. If it loses several in a row
it stops and says so, rather than spinning against whoever is out-claiming it.
This is one half of what makes a .lpm folder safe to share; the other half is
below.
A parent's status is derived
Nobody works a feature: the stories under it are what get worked, and the
feature is a name for them. So a container's status comes from its contents.
Finish the last open issue in a feature and the feature is finished too, and its
epic with it if that was its last open feature — as far up as it goes. Reopen
one and they reopen with it, and adding a new issue inside a finished container
reopens it as well.
terminal: true is the whole of what "finished" means here — nothing in
light-plan knows the word "done", it reads the flag. When a board declares more
than one end state, a parent closes into the one its children agree on, and into
the first one declared when they do not.
It happens wherever work is moved — lpm task done, lpm move --status, the
MCP finish_task and update_document, and pushing from the web app — because
it lives in the operation the three of them share. Each container it carries is
printed by the CLI, listed in rolledUp by the MCP tools, and recorded in the
parent's own activity section, so a status nobody typed always says where it
came from.
Two things follow. Anything waiting on a feature is offered the moment its last
story is closed, without anybody remembering to tick the feature off. And a
board where that never happened — frontmatter edited by hand, a merge that took
one side of a status, a board written before this existed — is repaired by
lpm check --fix, which reports every container out of step with its contents
and rolls it up.
Who you are is stored in .lpm/local.json, which lpm init adds to
.lpm/.gitignore: the board is shared, but who is at this keyboard is not.
LPM_USER=RS-2 lpm task next overrides it for one command.
Running the queue forward: lpm queue simulate
lpm task next answers "what now?" one step at a time. lpm queue simulate
answers the other question — if this one person were the only contributor,
what would they work on, and in what order? It takes the top of the queue,
marks it finished in memory, asks again, and keeps going until nothing is left
that they could pick up:
lpm queue simulate # you
lpm queue simulate --user "Alice Smith" # a person on the roster
lpm queue simulate --role "QA engineer" # a pool: anyone working out of it
lpm queue simulate --team # everybody: every open work unit, whoever holds it
lpm queue simulate --user alice --skipped --unassigned --limit 20
--team is the sequence the web queue panel numbers its cards by when it shows
everyone's queue.
$ lpm queue simulate --user alice
Queue simulation for RS-1 Alice Smith (person)
id title type effort total
1. LP-12 Guest checkout User Story 3 3 TL-2 · frees LP-14
2. LP-9 Cart totals User Story 2 5 TL-2 · pool RS-4
3. LP-14 Apply a promo code User Story 5 10 TL-2
Total 3 tasks · 10 story_points
2 open issues never reached — see them with lpm queue simulate --skipped
--user names a person and --role names a pool (a resource type declared
generic: true). They are separate flags on purpose: simulating a pool as
though it were a person answers a question nobody asked, so the command says
which one you gave it rather than guessing.
It is lpm task next in a loop, not a second opinion about it. Every rule
about what may be picked up — routing, pools, work units, blockers, your
profile's scope, switched-off periods — lives in the engine and reaches the run
only through nextTasks, against a board with the earlier steps marked
finished. A developer stepping through lpm task next by hand gets this
sequence, and runs out where this runs out. That is the point of the command, so
it is also what the tests pin down.
Two consequences worth knowing:
Work already in progress goes first — unless it is flagged. The queue does
not offer what has already been picked up, so a run that ignored it would
report everything waiting on it as blocked forever. A flag is where that stops:
it says the work has stopped and needs a person, and nobody else is in this
run to clear it, so starting from it would assume away the very thing holding
the queue up. Flagged work is listed under --skipped instead, and counted
under the run, which is what makes this agree with lpm task next and
lpm queue agent on a stalled board. lpm queue agent resumes in-flight work
by the same rule, so the prediction is of the run and not of a different
reading of the board.
Nothing is written and no clock moves. The board is untouched, and today
stays fixed for the whole run, so a period that has not started stays
unstarted. This reports an order, never a schedule: light-plan does not know
how long a task takes, so it adds up effort and stops there.
Parked sprints are left out and counted. Whatever the switch withholds
from lpm task next is withheld here too, and the total says how much, so a
short run is never a mystery. --parked includes it.
--skipped is the other half of the answer. Nobody else is contributing, so
work held by someone else is never finished and anything waiting on it waits
forever — which is usually the thing you opened the command to find out:
$ lpm queue simulate --user alice --skipped
...
Never reached
LP-20 Settlement report assigned to RS-2 (Bob Jones)
LP-21 Reconcile the ledger waiting on LP-20
LP-22 Refund flow already in progress under RS-4 (Web developer)
LP-23 Import legacy carts assigned to nobody — try --unassigned
LP-24 Audit the payment providers flagged by RS-1 (Alice Smith) — the work has stopped until somebody clears it
If you use a profile,
its scope narrows a simulation of you, because that is the queue you are
actually offered. Simulating somebody else uses the whole board: you do not hold
their profile.
Like lpm team, this reports — it never levels load, assigns anything or writes
a date.
Draining the queue with an agent: lpm queue agent
lpm queue simulate predicts the order; lpm queue agentworks it. It takes
the top of the queue, hands the issue's brief (the same one lpm instructions
prints) to an isolated pi coding-agent run with a fresh
context, reads back what the agent reports, and records the outcome the way a
person would — lpm task done on success, a flag on failure — then picks the
next task and repeats.
lpm queue agent --user alice --max-tasks 3 # do the next three, as Alice
lpm queue agent --model anthropic:claude-opus-4-5 --effort high
lpm queue agent --commit task # commit after each finished task
lpm queue agent --file agent.yml # take options from a YAML file
lpm queue agent --dry-run # show the next pick and its brief
Option
Meaning
--user <id|name>
Route the queue to this person (default: lpm me)
--max-tasks <n>
Stop after this many tasks are picked up
--model <spec>
Pi model, as provider:model
--effort <level>
Thinking level: off … max
--commit <mode>
none (default), task, or parent
--unassigned / --parked
Widen the queue, exactly as lpm task next does
--timeout <secs>
Per-task wall-clock cap
--command-timeout <secs>
Kill any single shell command after this long (default 300)
--plain
Log one line per event instead of drawing the live view
--file <path>
Read all of the above from YAML (CLI flags win)
--dry-run
Pick and brief the next task, but run and write nothing
It works the same queuelpm task next offers — routing, scope, work units,
blockers and parked periods all still apply — and it finishes every piece of work
under one parent before moving to the next, so a feature lands together. Each run
leaves a comment on the issue and a full JSON log under .lpm/runs/ (tools used
and in what order, timing, tokens and cost when the provider reports them). On
failure the issue is flagged for a human and the run moves on; a flagged task is
never retried.
Before it asks for anything new, a run carries on with what this person is
already holding: a task an earlier run claimed and did not finish — a crash, a
timeout, a run you interrupted — is left in progress, and the queue never offers
work in progress, so nothing else would ever return to it and everything waiting
on it would stay blocked. This is the same rule lpm queue simulate seeds its
prediction with, so the two commands cannot disagree about it.
A flag is where that stops, and because of it a run can stop with the board
apparently full of work: everything left is waiting on issues this person is
already holding, and those are flagged. The run says so rather than just
reporting an empty queue — it lists what they hold, marks which of it is flagged,
and points at the comments that explain why. Clearing the flag
(lpm flag clear <id> -m "...") hands the work back to the next run; finishing
it yourself does the same.
Watching a run
On a terminal the run draws a small pane at the bottom of the screen, on stderr,
and rewrites it in place:
LP-14 Guest checkout form validation task 2 · 4m 31s
agent working · bash npm test -- --run src/checkout 7 tools
───────────────────────────────────────────────────────────────────────────
── LP-14 Guest checkout form validation
Adding the validator and a test for it.
❯ bash npm test -- --run src/checkout
✓ src/checkout/validate.test.ts (4 tests)
Test Files 1 passed
↑↓ PgUp/PgDn scroll · Ctrl+C stop 12 lines back
The top two lines say which task, which stage of it (claiming, briefing, agent
working, recording, committing), and what the agent is running right now. Under
them is the tail of the run: what the agent is saying, the tools it calls and
what they print. ↑/↓ and PgUp/PgDn scroll back through it — the view
holds its place while new output arrives, and starts following again when you
reach the end. Ctrl+C stops the run; the task stays in progress and the next
run picks it back up.
The pane is a window, not a transcript. The whole story of a task is on the
issue: a comment when it ends, and the full JSON log under .lpm/runs/.
Redirect the output — or pass --plain — and there is no pane at all: one line
per event, no escape codes, which is what you want in CI or a log file. The
report at the end always goes to stdout, so lpm queue agent > run.txt is a
clean file either way.
A run nobody is watching
The point of the command is that it does not stop, so the agent's shell is set
up for a terminal with nobody at it:
Pagers print and exit and editors return immediately (PAGER,
GIT_PAGER, GIT_EDITOR, EDITOR, VISUAL, …), so git log, a git commit
with no -m, and lpm open LP-4 — which spawns $VISUAL/$EDITOR and waits
for the window to close — cannot sit there waiting for a keypress.
CI=true, which is how a test runner is told to run once instead of
starting in watch mode, and how most scaffolders are told not to ask
questions.
A command that would open a file in another program is refused — start,
open, xdg-open, code, explorer, less, man, vim, tail -f,
Start-Process, git add -p and their like. The agent gets an error saying
what was refused and what to do instead, and carries on.
Everything else is killed at --command-timeout (300s by default). A
command the agent gives its own timeout keeps that one; this only fills in a
cap where there was none.
This is a guard against a stuck run, not a sandbox: the agent still has a real
shell in your project, and an agent that wants to get around the refusal can. It
is there because one start report.md used to hold a whole queue open until
somebody noticed.
--commit decides what happens to the code the agent wrote in your project:
none leaves it in the working tree for you to review, task commits after each
finished task, and parent commits once all the work under a task's parent is
done. Commits are made in the project repo, not the .lpm board — commit the
board (statuses, comments, run logs) yourself.
lpm queue agent is experimental, so the pi agent it drives is not installed
with light-plan (it needs Node 22.19+). lpm experimental on installs it. To
install it yourself, put it beside light-plan — with -g when light-plan is
installed globally, without it in a project:
lpm experimental on
# or, by hand:
npm install -g @earendil-works/pi-coding-agent @earendil-works/pi-ai
# or, through npx:
npx -p light-plan -p @earendil-works/pi-coding-agent -p @earendil-works/pi-ai lpm queue agent
--model takes provider:model for any provider pi supports — Anthropic,
OpenAI, DeepSeek, Google, Groq, Mistral, xAI, and others. Set that provider's API
key in the environment and pi picks it up; omit --model to use pi's default.
(Exact model ids come from the installed pi version's catalog; the pi CLI or its
docs list what each provider offers.)
⚠️ The agent runs with real bash and write tools on your project. Running it
unattended is a decision you make; review what it produces, and prefer
--max-tasks and --dry-run while you learn how it behaves on your board.
When the work stops: flags
Sometimes work you have picked up cannot go on. A credential expired, a decision
has not been made, a question needs somebody who knows the area. Moving the issue
back to the backlog would be a lie — you are holding it — and leaving it in
progress is a quieter one, because the board goes on saying it is being worked.
A flag says the third thing:
lpm flag --comment "Sandbox credentials expired; asked ops on #infra"
lpm flag LP-12 --reason help --comment "Need a decision on the retry budget"
lpm flag list # everything stopped, across the board
# the plan owner's side:
lpm flag clear LP-12 --comment "New credentials in the vault; carry on"
Reason
Means
blocked (default)
something outside this issue has to happen first
paused
deliberately set down; the work is fine, the timing is not
help
a person is needed — a decision, a review, a pair of eyes
A flag is not a status. The issue keeps its column and its assignee: it is
still yours, still in progress, and the flag says it is not moving. That is a
different claim from "nobody has started this", and it is the only one that needs
somebody's attention today.
What it does change is what you are offered. lpm task next, lpm task start
and the agent queue all leave flagged work out, whatever column it sits in — so
"blocked, do not start this" on a backlog issue is heard rather than displayed
and ignored. Like a switched-off period, it steers the queue and hides nothing:
lpm open, lpm task start <id> and lpm flag list all still reach it.
A flag carries up the plan. Nobody scrolls to the bottom of an epic to find
out whether anything under it has stopped, so every container above a flagged
issue is marked inside ("Stopped inside") — and the mark comes off by itself
when the last stopped thing inside it starts moving again, whether you cleared
the flag or finished the work. It is the same roll-up a closed story does to its
feature, and it is written and cleared automatically:
lpm flag LP-42 -m "Sandbox credentials expired" # LP-42 blocked; the feature,
# epic and program say "Stopped inside"
lpm flag clear LP-42 -m "New credentials issued" # and all three go quiet again
inside is not a reason you can raise — lpm flag --reason inside is refused —
because it is what tells a container the roll-up may clear from one you paused
by hand. A flag you put on a feature yourself is never overwritten and never
cleared for you. lpm flag list shows the issues somebody actually stopped and
counts the containers standing in front of them separately, so the list stays
the short one you can act on.
The comment is required, both ways. A red box nobody can read is a round trip
to ask what it means, which is the trip the flag exists to save — so lpm flag
refuses without one and writes it into the issue's _comments.md in the same
call. Clearing needs one too: whoever raised the flag is the person who reads it.
And every flag change is written into the document itself, comment or not.
The flag lands in the frontmatter, and the raise or the clear lands as a dated,
attributed line in the issue's activity section:
## Activity
### 2026-08-16T09:14:02.104Z — Alice Smith (RS-1) — flagged: Blocked
**Flagged: Blocked**
Sandbox credentials expired
### 2026-08-16T14:41:55.881Z — Alice Smith (RS-1) — flag cleared
**Flag cleared** (was: Blocked)
New credentials issued
That matters most for the flag changes nobody typed a comment for, which on
a working board are the majority: the container that gained inside because a
story four levels down stopped, the same container going quiet again, the flag
that finishing the work answered, the one lpm check --fix wrote to repair a
container that had drifted. None of those writes a comment — _comments.md is
where a person explains a stall, and one derived entry per ancestor per flag
would bury the explanation the flag exists to carry — so the activity line is
the entire record. Without it a node turns red and back again with nothing in
_issue.md, and nothing in the board's git history, saying when or why:
$ git -C .lpm log -p -- board/LP-1/LP-2/LP-3/_issue.md
+flag: inside
+### 2026-08-16T09:14:02.104Z — Alice Smith (RS-1) — flagged: Stopped inside
+
+Work inside this has stopped — see LP-42.
Flagged issues are drawn in red on the canvas, a container standing in front
of one is drawn in a quieter red, and a collapsed node says how many are stuck
inside it — folding a feature must not hide a story that has stopped. Finishing an issue clears any flag on it automatically; the comment
trail keeps the history.
Clearing is the plan owner's call, by convention rather than by enforcement.
light-plan has no permissions anywhere — a profile routes work, it is not access
control — and inventing
them here would make that untrue. What the tooling does is record who did it.
Working briefs: the context to actually do it
lpm task next says what to work on. lpm instructions answers the question
straight after it — what do I need to know to start?
lpm instructions LP-12 # markdown on stdout, and nothing else
lpm instructions # the issue you have in progress
lpm instructions LP-12 > brief.md
A story on its own rarely explains itself. So the brief walks up the hierarchy
and lays out the title and body of every ancestor — the programme, the epic,
the feature — above the issue's own, then adds its breakdown, what it is blocked
by, the research it rests on, and its work log:
$ lpm instructions LP-12
# LP-12 — Pay as a guest
You are picking up a user story on the acme board. …
## Epic: Checkout (LP-4)
### Summary
Buy things without an account. …
## Feature: Guest flow (LP-9)
…
## The story: Pay as a guest
### Acceptance Criteria
- [ ] Given a signed-out shopper …
Everything about how the brief was made goes to stderr, so the brief itself
pipes cleanly into a prompt, a file or a clipboard.
Agents get the same text from the MCP tool get_instructions { id }, which is
what the shipped lpm-developer agent reads before writing any code.
Context templates
The layout is a board-level decision, like the statuses. Layouts live in
.lpm/templates/context/<issue type>.md, with default.md behind them and a
built-in layout behind that — so a board with no templates at all still gets the
ancestors' titles and bodies above the issue's own. lpm init writes starters
for the types your config declares:
lpm instructions --list # which layout each issue type resolves to
lpm instructions --init # write the starters (never overwrites)
lpm instructions --audit # read every layout for risky code
lpm instructions --template ./one-off.md LP-12
They are Eta templates — EJS syntax, ordinary JavaScript
between the tags:
Every issue type your board declares is a variable, resolving to the nearest
ancestor of that type — so one template can say "this story's epic" without
knowing how deep it sits. heading(n) re-levels a body so it nests under the
heading above it, leaving fenced code alone. Note that an empty array is truthy
in JavaScript: guard a list with .length, an optional document with the name
alone. The full reference, including every value and helper, is in
docs/context-templates.md and in
lpm instructions --help.
Templates are not board truth: they live under .lpm/templates, lpm check does
not know they exist, and no template can make a board invalid.
⚠ Context templates are code
Eta compiles a template into a JavaScript function and runs it. A .lpm
folder arrives over git pull from whoever wrote it, so rendering somebody
else's board can run somebody else's JavaScript, as you, with your filesystem and
your environment variables.
light-plan reads every template before compiling it and refuses the known
escapes — process, require, this, import(), a property reached by a
computed key, and Eta's own file-reading include. The check tokenizes with
Eta's own parser and parses the code with acorn,
so x["cons" + "tructor"] is caught as readily as require:
$ lpm instructions LP-12
error Refusing to render .lpm/templates/context/user_story.md: it can do more than lay out an issue
3:5 danger reaches outside the board (process) — process
4:5 danger `this` is the template engine itself, not the issue — this
lpm instructions --audit runs that check over the whole board and exits 1 on a
finding, so it drops into CI beside lpm check. --unsafe renders anyway, for a
template you wrote and meant; the MCP tool has no equivalent, because letting an
agent opt out is the whole hole.
This refuses the known escapes; it cannot make an untrusted template safe.
Read the templates that arrive with a board you did not write, the way you would
read a postinstall script. Use at your own risk.
Profiles: giving one developer one part of the board
A profile is a small YAML file you hand a developer — or an agent. It says
who they are and which part of the board they should be offered:
# alice.yml
user: Alice Smith
scope:
under: [LP-2] # only work at or below these documents
exclude: [LP-9] # never these, nor anything below them
types: [user_story] # only these issue types
periods: [TL-2] # only work scheduled here, or in a child period
Every key is optional, and every one of them narrows: under on its own scopes
someone to an epic, exclude on its own keeps them out of one, and the two
together read as "this programme, but not that feature". A period folds its
child periods in, so naming an increment includes its sprints. Write a starter
file and start using it in one command:
lpm profile --init ~/.lpm/alice.yml --user "Alice Smith"
lpm profile ./profiles/alice.yml # or point at one you were given
lpm profile # what is in force, resolved against this board
lpm profile --clear
$ lpm profile
Profile /home/alice/.lpm/alice.yml
.lpm/local.json
user Alice Smith
scope under LP-2 · not LP-9
offers 14 issues of 63
Only the path is remembered, in .lpm/local.json beside the current user and
git-ignored with it — the profile belongs to the developer, not to the board.
LPM_PROFILE=./profiles/bob.yml lpm task next points at a different one for one
shell, and lpm mcp --profile <file> does the same for one agent session.
Scope decides what the board offers you, never what is reachable. It
narrows lpm task next and lpm task start with no id, and the MCP tools
next_tasks and list_documents. It does not touch lpm open, lpm set,
get_document, or lpm task current — work you have already picked up stays
yours even if the scope it came from moves, and a dependency you cannot read is
worse than a recommendation you should ignore.
So this is routing, not access control: the board is a folder of markdown
that whoever holds the profile can read, and a profile decides what is handed to
them. Use it to keep a team of ten out of each other's epics, or to give five
agents five slices of one plan. Do not use it to keep a secret.
Whatever is in force is printed with the work it filters, so a short list is
never a mystery:
$ lpm task next
Next up for RS-1 Alice Smith
scope under LP-2 · not LP-9
LP-12 Guest checkout User Story · ready TL-2
If the file names something this board does not have, that is reported and the
rest still applies — except that a stale under offers nothing rather than
quietly widening to everything. A profile that does not parse at all is
reported too, and light-plan carries on unscoped. Unknown keys are an error:
excludes: would otherwise silently hand someone the whole board.
Where identity is concerned the most specific answer wins: LPM_USER, then the
profile's user:, then lpm me. lpm me says which one is talking.
docs/profiles.md is the full reference: every key, how the
file is found, what each surface does and does not filter, and how to set up a
team or a swarm of agents.
Working by hand
The CLI is a convenience, not a gatekeeper. You can create a folder and an
_issue.md (or _period.md, or _resource.md) yourself — even one containing
nothing but a heading — and then run:
lpm check --fix
which adopts it: allocates an id from the right counter, infers the type from
its depth (when that level has only one type), takes the title from the
# heading or the folder name, sets the default status, defaults a resource's
capacity to 1, fills in created (from the file's first commit, falling back
to its mtime) and author (from git config user.name/email), adds the
attributes its type declares, dedupes link and coverage lists, renames the
folder to the document's id, rolls every container's status up from the work
inside it (see a parent's status is derived),
and rewrites INDEX.md.
Anything --fix cannot decide for you is reported and left alone — an ambiguous
type, a duplicate id, a missing sprint date, an assignee who is not on the
roster, an attribute whose value has the wrong type. Without --fix, check
never writes anything.
INDEX.md: the board as a table of contents
A folder is named after its id, so the file tree says what is nested in what but
not what any of it is. .lpm/INDEX.md is where the titles are — every
document in the board, with a link to its file, nested exactly the way the
folders are:
# Board index
## Issues
- [LP-1](board/LP-1/_issue.md) — Payments platform
- [LP-2](board/LP-1/LP-2/_issue.md) — Checkout revamp
- [LP-3](board/LP-1/LP-2/LP-3/_issue.md) — Guest flow
## Timeline
- [TL-1](timeline/TL-1/_period.md) — 2026 H2
- [TL-2](timeline/TL-1/TL-2/_period.md) — Sprint 1
## Team
- [RS-1](team/RS-1/_resource.md) — Alice Smith
It is written by lpm init and rewritten by every command that adds, removes,
moves, reparents or retitles a document — from the CLI, from the web UI's Push,
and from an agent over MCP alike. Nothing has to be run to keep it current.
It is generated, not authored: the board is the documents, and the index is a
reading of them. Edit it and your edit is overwritten by the next change; delete
it and lpm check --fix puts it back. lpm check reports it when it has fallen
behind — which is what a badly resolved merge conflict inside .lpm looks like.
Because it is markdown with relative links, GitHub, GitLab and every editor's
preview render it as a clickable outline of the whole plan.
Configuration
.lpm/config.yml defines the board. lpm init copies one of the built-in
templates; edit it whenever the process changes and re-run lpm check.
version: 1
key_prefix: LP # issue ids: LP-1, LP-2, ...
statuses: # the kanban columns, in board order
- id: backlog
label: Backlog
- id: in_progress
label: In Progress
active: true # work in progress: where `lpm task start` moves an issue
- id: done
label: Done
terminal: true # an end state: where `lpm task done` moves it, and
# what a parent takes when everything inside it is
# there — see "a parent's status is derived"
default_status: backlog # optional; defaults to the first status
priority_attribute: priority # optional; an enum, most important value first
effort_attribute: story_points # optional; an int or float
hierarchy: # index = folder depth
- program
- epic
- feature
- [user_story, bug] # types on one line share a level
- sub_task
issue_types:
user_story:
label: User Story
atomic: true # the smallest unit the queue hands out
attributes:
story_points:
type: int
description: Relative size, Fibonacci
priority:
type: enum
values: [critical, high, medium, low]
default: medium
body: |
As a **<role>**, I want **<capability>**, so that **<benefit>**.
## Acceptance Criteria
- [ ] **Given** <context> **when** <action> **then** <outcome>
# --- time hierarchy (optional, same shape) ---
period_prefix: TL # period ids: TL-1, TL-2, ... must differ from key_prefix
default_period: TL-2 # optional: where unscheduled new issues land (lpm init writes it)
planning: queue # optional: queue | periods. lpm init writes queue; absent means periods
period_hierarchy:
- increment
- sprint
period_types:
sprint:
label: Sprint
attributes:
goal:
type: string
committed_points:
type: int
body: |
## Sprint Goal
# --- team roster (optional, same shape) ---
resource_prefix: RS # resource ids: RS-1, RS-2, ... distinct from the others
resource_hierarchy:
- [person, role] # one level is usually enough
resource_types:
person:
label: Person
attributes:
email:
type: string
role:
label: Role
generic: true # a pool, not a named person
attributes:
discipline:
type: string
# --- squads (optional, same shape) ---
squad_prefix: SP # squad ids: SP-1, SP-2, ...
squad_types:
squad:
label: Squad
attributes: {}
squad_hierarchy:
- squad
hierarchy is the single source of truth for parenting: a type's position in
the list is the folder depth it must sit at, so lpm new and lpm move can
reject invalid nesting without you declaring parent/child rules twice.
period_hierarchy and resource_hierarchy work identically.
priority_attribute and effort_attribute name issue attributes the engine
itself reads — the first to order lpm task next, the second to add up load in
lpm team. Both are optional, and both must name an attribute your issue types
actually declare, with a usable type (an enum, and an int or float).
body is the markdown scaffolding written into each new document of that type —
this is where the Agile practice lives (story format, acceptance criteria,
definition of done, repro steps, sprint goal, retro prompts).
The unit of work
atomic: true on an issue type says that work of that type is taken whole.
It is the answer to "what is one job for one person?", and it is the only thing
that decides what the queue offers.
Without it, only an issue with nothing nested inside it carries work. That reads
well until somebody breaks a story into sub-tasks: the story disappears from
lpm task next and three sub-tasks appear in its place, as if they were three
separate tickets for three separate people. Usually they are not — they are a
checklist, and the story is still the job.
So a type marked atomic is offered even when it has children, and nothing
nested inside it is offered separately:
epic container — not offered
feature container — not offered
user_story ** OFFERED (atomic)
sub_task inside the unit — never offered
sub_task inside the unit — never offered
The sub-tasks are not hidden, only un-assignable on their own: they are listed
in the brief lpm instructions renders, so whoever picks the story up reads them
with it. lpm team counts the same way — the story's story_points once, and
not the estimates on the sub-tasks underneath.
Where atomic types nest, the outermost one wins: mark feature as well and the
feature becomes the unit, with its stories inside it. A board that marks nothing
behaves exactly as it always has, so this changes nothing on an existing board
until you ask for it. The shipped scrum template marks the whole delivery level
(user_story, bug, test, review, research) and kanban marks story.
The flag is only meaningful on issue types; lpm check refuses it on a period or
resource type rather than ignoring it.
Attribute types
Type
Frontmatter value
--set input
string
text on one line
--set owner=jane
text
multi-line text
--set notes="..."
int
integer
--set story_points=3
float
number
--set estimate_hours=1.5
bool
true / false
--set blocked=yes
date
YYYY-MM-DD
--set due=2026-09-30
enum
one of values
--set priority=high
array
YAML list
--set labels=web,api
Every attribute also accepts description, required: true, and default.
Names must be lower_snake_case and cannot shadow the reserved fields:
Program › Epic › Feature › User Story ∥ Bug ∥ Test ∥ Review ∥ Research › Sub-task
Increment › Sprint
Person ∥ Role
kanban
Epic › Story › Task
Cycle
Person ∥ Role
blank
Task
—
—
lpm init --template kanban
lpm init --template ./my-process.yml # your own
lpm init --template team-flow # a template that you saved
You can save the config of a board as a template. In the web app, open
File ▸ Board configuration… and select the Templates tab. The command
Save as a template writes the file templates/<name>.yml in the user
folder. The user folder is ~/.light-plan, or the folder that the environment
variable LPM_HOME names.
The saved file holds every key of .lpm/config.yml except remotes,
remotes_off, git_sync, default_period and planning. Those five keys
describe one board. The template does not hold the issues, the template
registry or the context templates of the board.
lpm init without --template reads the key default_template in the file
settings.json of the user folder. The value is the name of a built-in
template or of a saved template. When the key is absent, lpm init uses
scrum. The Templates tab writes the key when you select a template under
Template for new boards.
Sharing the board through git
A board lives in .lpm, which is a git repository of its own. Git sync
makes git the board's remote. Every change made from the CLI, the web UI or an
agent pulls the latest board first, then commits and pushes it as one commit
(lpm: claim LP-12). A team, or a swarm of agents on several machines, can
then work one board, and nobody runs git by hand.
lpm git setup # this project's repository, on its own branch _lpm_board_remote
lpm git setup --url https://dev.azure.com/acme/plan/_git/board
lpm git join # a teammate: clone the shared board into this project
lpm git # where it stands; `lpm git sync` to sync now
A change that collides with one somebody else pushed first is refused, and
nothing is written, so two people cannot both claim one issue: the second is
told, and asking again says who holds it. Changes to different documents both
land. Any host works (GitHub, GitLab, Bitbucket, Azure DevOps, or any server
git can push to), with the credentials git already uses for your code.
light-plan stores none, and never waits on a prompt. With the board on the
project's own repository, the board branch shares no commit with the code, so
the two histories never mix. A board syncs through git or mirrors onto a
tracker (below), never both. Swapping one for the other keeps everything:
lpm git setup --turn-off-remotes turns the trackers off (not removed), and
lpm git off --turn-on-remotes turns them back on where they left off.
The full guide covers conflicts, offline work (LPM_GIT_OFFLINE=1), turning
it off and the design: docs/git-sync.md. For a step-by-step
walkthrough, CLI and web UI, see docs/git-sync-tutorial.md.
Remote boards
A remote is a mirror: light-plan keeps an external tracker — GitHub Issues,
Jira Cloud or Linear — in step with a .lpm board, in either direction. The
board stays the source of truth in your repo; the remote is a reflection of it,
in a tool the rest of the team already has.
It is git, and it is not git. The mental model is a git remote: you push
your branch out and pull other people's work back, and the .lpm folder is the
working tree. That analogy is load-bearing, so be clear-eyed about where it
stops. Git syncs files and knows nothing about what is in them, and when two
sides disagree it hands you the conflict together with a merge base you can
inspect and resolve by hand. A remote syncs issues, each with its own id, its
own workflow and its own rules about what a parent, a status or a label may be —
and there is no merge base you can inspect. The remote may renumber your
issues, rewrite their markdown, reorder their labels or silently refuse half a
write, and the only way light-plan can tell your edit from theirs is the
snapshot it recorded the last time the two sides agreed. That is why the sync
keeps a link store and a base snapshot per document, why a field the remote
cannot hold is encoded rather than dropped in silence, and why the first
write asks once — each is an answer to a question git never had to ask. The
full guide — the files a remote touches, every mapping block, credentials,
people, sprints and what happens to a board deeper than the platform — is
docs/remotes.md; the reasoning is recorded in
docs/remote-sync.md, and the per-platform audit is
docs/remote-capabilities.md.
A remote lives in .lpm/config.yml under remotes:. Each entry names a
provider plus that provider's own connection and mapping blocks. Set one up
without hand-writing the YAML — lpm remote add <name> --provider <provider> --<key> <value>… validates the connection against the provider's own schema and
writes the entry in place; lpm remote lists what is configured and
lpm remote rm <name> removes an entry (the per-remote state is kept unless
--purge).
lpm remote add drafts the mapping: for you — you do not write one by
hand, and you should not need to edit one. It reads this board's own types,
statuses and attributes and matches them against what the provider can hold
(src/remote/scaffold.ts). Where the words are the
board's own, it uses them. Where the words belong to the platform — a Jira
issue type, a Linear workflow state — it uses that platform's conventional
names, which the provider states for itself
(src/remote/vocabulary.ts): Jira's Epic / Story /
Task / Bug / Sub-task and `To Do
Ainda não há lista de ferramentas. Servidores remotos recebem uma após a primeira verificação de saúde.
Perguntas frequentes
Perguntas
Como instalo Light Plan?
Copie nesta página a configuração stdio para Cursor, Claude Desktop, Claude Code ou VS Code. Ela usa a instalação do publicador, não um proxy do PlugMCP.
Light Plan precisa de uma chave de API?
Este registro não lista nenhuma variável de ambiente obrigatória.
Qual transporte Light Plan usa?
Light Plan roda localmente via stdio.
Quando Light Plan foi verificado pela última vez?
Última verificação: 2026-11-08. A lightweight, file-based issue tracking system. Agile boards as folders and markdown.
