Projects, lanes, and plans

Three nested ideas carry all of mcue's structure. Understanding what each one is for — and what it deliberately is not — makes the command surface obvious.

Projects

A project is a governed intent: the durable identity for a body of work whose continuity mcue governs. It has a stable id, a registry entry, and a state directory. From the CLI, it is usually created where the code lives:

mcue init payments-api --name "Payments API"        # register and scaffold
mcue attach payments-api      # anchor an existing project to this directory
mcue detach                   # remove the footprint, keep the state

The directory is an attachment, not the project. A project can have several repositories attached or none; one created in Hub with no CLI involved is the same kind of thing, and mcue attach joins a repository to it later. The project is the boundary for identity, ownership, membership, shared decisions, and portfolio visibility. It is not the smallest thing you resume — that is a lane.

The id is yours to choose and appears in every later command. Keep it short and stable; if you must change it, mcue project rename <old-id> <new-id> moves the id across all local state rather than leaving you to fix references by hand.

Projects have a lifecycle beyond deletion:

mcue project archive payments-api   # out of the active portfolio, state retained
mcue project delete payments-api    # hard delete: registry entry and state

Archiving is the one you usually want. mcue index stops showing archived projects without destroying anything.

Lanes

A lane is an independently resumable stream of work inside a project. It has its own objective, blockers, next action, resume pointer, plan, and checkpoint history — and its own freshness, trust, and drift signals. mcue closeout writes to a lane; mcue resume reads from one. The lane is the primary continuity unit.

mcue lane create payments-api refunds
mcue lane close payments-api
mcue lane delete payments-api

A lane is not a Git branch. The distinction matters:

• A branch partitions code. A lane partitions attention.
• A branch merges. A lane reconciles — and only when two perspectives on the same lane diverge.
• You can work one lane across several branches, or several lanes on one branch. mcue does not care what your VCS is doing.

Every project starts with a default lane, so you can ignore lanes entirely until you are genuinely running two strands of work and find their closeouts polluting each other.

Plans

A plan is the current intended sequence of steps on a lane. It is scoped to the lane, not the project, because two lanes have two different next actions.

mcue plan create payments-api
mcue plan show payments-api
mcue plan update payments-api      # change it outside a closeout
mcue plan close payments-api       # archive the active plan
mcue plan list payments-api        # active and archived

Plans are archived rather than deleted when closed, so "what did we think the sequence was in March" stays answerable.

How they compose

project  payments-api
├── lane  default
│   ├── plan (active)
│   └── checkpoints/
└── lane  refunds
    ├── plan (active)
    └── checkpoints/

mcue closeout writes to a lane. mcue resume reads from a lane. mcue index aggregates across projects. When a lane accumulates two unreconciled perspectives — usually because two machines wrote to it independently — mcue reconcile is how you resolve it.

Choosing a granularity

The failure mode at both ends is real:

• Too many projects. A project is one governed intent — the body of work you would describe as a single thing with one owner and one set of decisions. Often that maps to a repository; sometimes it spans several, or has none yet. One per feature means mcue index becomes noise and nothing is ever resumed.
• Too many lanes. Create a lane when two strands genuinely have different next actions and different blockers. Otherwise a single lane with good closeouts beats five with sparse ones.

When in doubt, fewer. Splitting later is cheap; merging a fragmented history is not.