Commands

/lucid:swarm#

/lucid:swarm <feature>

Splits a feature across parallel agents (subagents or Agent-Teams teammates) that share one plan, log and set of file claims. Use it when the work splits into parts that touch different files. The lead:

1. Runs lucid init if needed, then writes .lucid/plan.md: the goal, then tasks that each own a separate set of files (a glob). Tightly coupled work stays with one agent.
2. Makes the cross-cutting decisions itself before spawning anyone (interfaces, names, data shapes) and logs each with lucid note decision. Workers inherit them.
3. Spawns one worker per task, with Agent Teams if it’s enabled, otherwise as background subagents. Each brief is the task, its glob, what “done” means, and an instruction to claim the glob first. Briefs end with “.lucid/plan.md overrides this brief if the plan changes.” The lead doesn’t name workers, assign ids or paste the plan: lucid identifies every agent, and hooks inject the plan.
4. Keeps working on its own task while workers’ decisions, dead ends and blockers arrive as [lucid] notes. It acts on blockers and doesn’t poll.
5. Uses /lucid:replan if you change direction.
6. Verifies the result itself (tests, build) instead of trusting summaries, and checks lucid status for unresolved blockers.

/lucid:replan#

/lucid:replan <the change>

Applies a mid-build change of plan so every running agent picks it up before its next tool call:

1. Runs lucid init if .lucid/ doesn’t exist.
2. Edits .lucid/plan.md in place: changes tasks, strikes dropped ones as ~~task~~ (dropped: why), and gives each new task an owner and a file set.
3. Logs lucid note decision "replan: <one line> because <why>".
4. Running workers get the diff before their next tool call. If the change makes a worker’s claimed task obsolete or conflicting, the lead messages that worker directly (SendMessage) instead of waiting for it to finish.
5. Tells you what changed in one or two lines.

/lucid:dream#

/lucid:dream

Consolidates the log into a short digest. Use it when the log gets long, or before handing the project to a new session.

1. Reads every entry with lucid log.
2. Re-reads the code behind each ⚠stale entry, and retires entries that are no longer true with lucid supersede. Duplicates are superseded too, keeping the clearest one.
3. Writes .lucid/digest.md: at most about 40 lines of current decisions (with why), dead ends, and key facts with evidence. Its first line, <!-- lucid:upto=N -->, records which entries it covers; agents get newer entries raw.
4. Never edits log.jsonl, and never drops a dead end unless it has been disproven.
5. Lists up to 3 lessons that would help any future session, and asks you before adding them to CLAUDE.md.

The lucid protocol skill#

Besides the three commands, the plugin ships a lucid skill that teaches agents the protocol. Claude loads it on its own when it’s relevant: starting a multi-step feature, before spawning subagents or teammates, when you change the plan mid-build, or when you mention lucid.

What agents log#

Only what another agent would otherwise rediscover or get wrong:

• note decision "<what> because <why>": choices others must stay consistent with.
• note failed "<tried X, broke because Y>": dead ends, so nobody retries them.
• note fact "<non-obvious truth about the code>" -e path:line: always with evidence.
• note blocker "<what you need, from whom>": the lead sees it on its next turn.
• claim 'glob' --for "<task>" before editing, release when done. Subagents release automatically when they stop.

Rules agents follow#

• Every fact needs evidence (-e path:line). A ⚠stale entry cites code that has changed since it was written, so re-read the code before relying on it.
• Never edit .lucid/log.jsonl. To retire a wrong entry, use supersede <ids> --why "...".
• Edit the plan in place with the Edit tool; every running agent gets the diff automatically.
• A PLAN CHANGED note is the user’s latest intent and overrides the original brief. If it touches files the agent owns or claimed, it applies the change and logs a decision.
• Never invent ids or names for yourself or for workers.