Lite vs full
Two modes, side by side on every axis that decides between them. Built from measured facts — test counts counted, backends read from the enum, edge semantics read from the schema. The framing that matters: “lite is a usage profile, not a fork.”
| Issues-FS-lite | Issues-FS (full) | |
|---|---|---|
| Install | Nothing | pip install issues-fs-cli |
| Runtime | None. cat, mv, find | Python ≥ 3.12 |
| Storage | Markdown with YAML front-matter | JSON — one issue.json per node |
| States | open / blocked / done — they are folders | Per-type configurable statuses[] |
| Identity | NNN-kebab-slug.md, per-agent sequence | Node_Id — a 10-char GUID — plus a Bug-27-style label |
| Edges | source: and parent: in front-matter | Typed verb/inverse pairs, stored on both endpoints |
| Type system | None — convention only | 12 node types, 10 link types, domain/range constrained |
| Query | find and grep | Node__Service.traverse_graph, find_incoming_links |
| Backends | The filesystem | memory / local_disk / sqlite / zip |
| Agent output | Native — it is all text already | --for-agent forces JSON on all 14 commands |
| Multi-agent | The writer rule: read anyone's queue, write only your own | Not addressed |
| Tests | n/a — there is no implementation to test | 604 core + 94 CLI |
| Status | Specification only. No reference implementation, no validator | Shipping. issues-fs 0.7.0 on PyPI |
Which one
Use lite when
You are an agent with a filesystem and no guarantee of tooling. The work is a queue, not a graph. You want the state change to show up in a git diff as a rename. You have several agents and want each to own its own work plan. Or you simply have not decided yet — lite costs one mkdir to start and nothing to abandon.
Use full when
The relationships matter as much as the items: you want to ask what a change blocks, or what a phase contains, and get an answer rather than a grep result. You want typed relationships with domain and range constraints. You want more than one storage backend, or comments, or a machine-readable type registry. The 14 commands.
What does not travel between them
Three things, and it is worth being precise because the comparison table above makes them look closer than they are.
| Concept | Why it does not carry across |
|---|---|
| Identity | Lite's identity is a filename with a per-agent counter; full's is a GUID with a label derived from a per-type counter. Two agents each having an 001 is correct in lite and impossible in full. There is no mapping that survives a merge of two agents' queues |
| Edges | Lite has two relationships and both are strings pointing at a path: source and parent. Full has typed verbs with declared inverses and constrained endpoints, and stores each edge on both nodes. Going up, every lite parent could become a contains/contained-by pair; going down, nine of the ten link types have nowhere to live |
| Status | Lite has exactly three states because it has exactly three folders. Full's statuses are per-type and configurable — the shipped task type alone carries more than three. A round trip loses whichever ones lite has no folder for |
And there is no converter. Nothing reads issues/open/*.md and writes .issues/…/issue.json; nothing goes the other way. Moving from lite to full means re-creating the nodes through the CLI and accepting new labels. This is open question Q6 and it is published unresolved rather than implied away.
“A usage profile, not a fork”
The phrasing comes from the comparison document that sits beside the specification, and it is the correct expectation to set. Lite is not a cut-down implementation waiting to be finished, and it is not a competing product. It is a way of working that needs no implementation, published so that an agent with nothing installed can still keep a defensible record of what it is doing and why.
The same document explains why lite was specified inside a manual about email rather than on its own: “Issues-FS-lite integrated, not separate… since the two are inseparable in the manual workflow.” That reasoning is sound for a workflow manual and is exactly what made the specification undiscoverable — which is why this section exists.
For an agent
Default to lite unless you need typed relationships. Lite: no install, three folders, four mv operations, find to query. Full: pip install issues-fs-cli, then --for-agent on any command for JSON. Do not attempt to convert between them — there is no converter, identities do not correspond (per-agent filename sequence vs per-type GUID and label), and nine of the ten link types have no lite representation. If you started in lite and now need edges, re-create the nodes through the CLI and expect new labels.