creating plans

a plan (also called a task) is the unit of work in kasmos. it starts as a short description, gets expanded into a structured markdown document by a planner agent, and then drives one or more coder agents through wave-based implementation.

step 1 — describe the work

press n in the tui to open the new plan input. type a free-form description of what you want built:

add jwt authentication with refresh tokens and a /me endpoint

press enter (or ctrl+enter in multiline mode) to submit. kasmos registers the plan in the task store with status ready and a normalized filename derived from your description.

the plan content is not written to a checked-in markdown file. everything lives in the global task store at ~/.config/kasmos/taskstore.db. use kas task list to see all registered plans and their current status.

step 2 — start the planner

with the plan selected, press ↵ to open the context menu and choose start planning. kasmos transitions the plan to planning status and spawns a planner agent on the main branch.

the planner agent:

1. reads the task description from the store
2. writes a structured implementation plan (with ## Wave N headers and ### Task N: title sections)
3. stores the content back via mcp task_update_content
4. emits a planner_finished signal via mcp signal_create to notify the orchestration loop

the orchestration loop picks up the signal and transitions the plan to ready, making the implementation stages available.

lifecycle from new to ready

(new description)
      │
      ▼
    ready  ──── plan_start ────►  planning
                                      │
                                 (planner writes content)
                                      │
                               planner_finished
                                      │
                                      ▼
                                    ready  ◄─── ready to implement

see lifecycle for the full fsm and all available transitions.

inspecting plan content

while the planner runs, its output is visible in the center pane preview. once it finishes, press v or p to open the plan viewer and read the full document.

from the cli:

kas task show <task-file>
kas task list

modifying a plan

if the planner's output needs adjustment, open the context menu and choose start planning again. this respawns the planner with a "modify" prompt that includes the current plan content as context.

to write plan content directly from the cli:

kas task update-content <task-file>  # reads from stdin
echo "your new plan" | kas task update-content my-feature

topics

assign related plans to a topic to group them in the sidebar and prevent concurrent coder runs on the same codebase region. open the context menu and choose set topic, or type a new topic name in the picker.

see topics for how topics enforce scheduling constraints.

registering a plan from the cli

if you write your own plan markdown file outside kasmos, prefer mcp task_create with inline content. in cli-only environments, you can still register it manually:

kas task register my-feature.md
kas task update-content my-feature < my-feature.md

the store normalizes the filename: a trailing .md suffix is stripped, so my-feature.md and my-feature refer to the same task.