Run A Named Plan - alexherrero/crickets GitHub Wiki
Note
Goal: Drive a development-lifecycle phase (/plan, /work, /review, /release) against a named plan โ a numbered task, tasks/NNN-<verb-slug>/ with its plan.md, progress.md and tracker.md โ so several concurrent plans can share one project.
Prereqs: the development-lifecycle plugin installed (Install crickets plugins); agentm installed, since development-lifecycle keeps its plans through it; a chosen, slug-safe plan name.
Use a named plan when you want more than one plan in flight at once โ the wedge behind the coordinator-directed agent team. In a project that keeps tasks, a bare /work / /review asks which task, and a bare /plan proposes a name. For the full mapping of invocation โ files, see Named plans.
- The
development-lifecycleplugin installed on your host (Install crickets plugins). - agentm installed. It decides where a project's tasks live and numbers a new one; crickets composes no path itself. Without agentm there is no plan, and the commands say so.
- A slug-safe plan name (no path traversal; the resolver rejects unsafe names).
-
Author the named plan. Run
/plan --name <slug> <brief>. agentm places a new numbered task,tasks/NNN-<slug>/, and/planwrites itsplan.md, seeds itsprogress.md, and opens itstracker.mdatqueued. The--name <slug>flag selects the task; everything else in the arguments is the brief. -
Work the named plan. Run
/work --name <slug>to work the task's steps, appending to itsprogress.mdand rewriting the tracker's State and Next after each step; the last step closes the tracker with its Outcome. The--name <slug>flag and thestep Nselector (task Nstill works) are independent โ combine them (/work --name <slug> step N) to work a specific step./work's "Read state" step resolves the paths by passing the slug positionally topython3 "${CLAUDE_PLUGIN_ROOT}/scripts/resolve_plan.py" [<slug>]. A non-zero exit from the resolver is a hard stop:/worknever falls back to another plan on a dangling marker or unsafe slug. The step mark ([x]), the tracker write and the progress append all target the resolved paths. -
Review the named plan. Run
/review --name <slug>to run the adversarial pass against the task โ it reads the plan's status andplan.mdfor the step context, and logs the outcome and the status to the task'sprogress.md. With no other scope, a plan whose status is stillqueuedhas nothing to review yet, and/reviewsays so. Any remaining argument (a commit range, branch, orstep N) still scopes what is reviewed, independent of--name. -
Confirm what a name resolves to (when in doubt about which files a name maps to). The bridge takes the slug positionally โ this is a direct call to the resolver, not a slash command, so there's no
--nameflag here:python3 "${CLAUDE_PLUGIN_ROOT}/scripts/resolve_plan.py" <slug>
It prints one tab-separated line โ
<plan_path>\t<progress_path>\t<tracker_path>, with an empty tracker field when agentm names none โ or exits non-zero with a stderr message: 1 for no agentm, 2 for a dangling marker or unsafe slug, 4 for a bare call in a project that keeps tasks.
Use this flow when you want to author one or more tasks ahead of time without putting them in front of a worker. A queued task is inert until you activate it; its queued tracker is what keeps it so.
-
Stage the plan. Run
/plan --stage <slug> <brief>. The rest of the arguments after<slug>is the brief, exactly as for--name./planwrites the task's ownplan.mdat the pathpython3 "${CLAUDE_PLUGIN_ROOT}/scripts/stage_plan.py" path <slug>prints, and opens its tracker atqueued. -
Activate when a worker picks it up. Run
/plan --activate <slug>. Activation runs no interview and authors nothing new:python3 "${CLAUDE_PLUGIN_ROOT}/scripts/stage_plan.py" activate <slug>moves the task's tracker fromqueuedtoactive, and that move is the activation. It hard-stops (exit 2, writes nothing) if the task'splan.mdor tracker is missing, or the tracker isn'tqueued. -
Work it as a normal named plan. Once activated, drive it with
/work --name <slug>exactly as in the Steps above.
Only a task stages. In a repo with no vault, agentm keeps the repo's plans in its repo-local .harness/ (see Named plans ยง A repo with no vault); staging refuses there, and you write the plan with --name.
-
A bare
/workpicked up the wrong plan. A present-but-unresolvable.harness/active-planmarker surfaces a loud error + non-zero exit rather than silently running another plan. Resolve or remove the marker. See Named plans ยง Resolution. - The name was rejected. Names are slug-safe; traversal or unsafe characters are refused. Pick a plain name.
-
/plan --activate <slug>refused. Activation is guarded: the task'splan.mdor tracker is missing, its tracker isn'tqueued, or agentm answered a repo-local flat plan, which doesn't stage. See Named plans ยง--activateguard. -
A bare
/workasks which task. The project keeps its plans in numbered tasks, so the resolver exits 4 and/worklists the project's tasks for you to pick. Pass--name <task-name>. -
The commands say there is no plan. No agentm process seam was found: the resolver exits 1. Install agentm, or point
$AGENTM_SCRIPTS_DIRat itsscripts/. -
The tracker field is empty. agentm named no tracker for the plan, which an agentm from before the tracker does. The commands say so and run on the plan's
**Status:**line.
- Named plans โ the lookup: invocation โ files, the parse rule, the resolver, and a repo with no vault.
- Once a task is active, running
/workagainst it is enough to hand it to its own worktree โ withisolation.mode: worktree-per-planset in.harness/project.json(or an explicit operator instruction),/workauto-spawns the worktree via the host's own worktree primitive, binds it to the plan, and closes it out with an auto-merging pull request when the plan's final step lands. There's no separate spawn or integrate command to run. See Named plans ยง Spawning a worker worktree for the mechanism. - Development Lifecycle โ the phase-loop plugin these commands belong to.
-
Install crickets plugins โ get
development-lifecycleonto your host. - Why phase-gating โ why the loop is gated and state lives on disk.