plans and tasks
a task is a markdown document that kasmos parses to extract waves, task headers, and metadata. the cli command group is kas task ...; you may also see plan in older internal identifiers — both refer to the same concept.
required header fields
every task document must contain these bold key-value fields near the top:
**Goal:** one-line description of what this work achieves
**Architecture:** high-level design approach
**Tech Stack:** languages, frameworks, and tools involved
these fields are injected into every agent prompt, giving all coder agents full context about the overall goal.
wave headers
waves partition tasks into sequential groups. the parser accepts both level-2 and level-3 headers:
## Wave 1
## Wave 2
### Wave 3
at least one wave header is required. without it, parsing returns an error:
no wave headers found in plan; add ## Wave N sections before implementing
task headers
tasks live inside wave sections. the parser accepts level-3 and level-4 headers, with any of these separators after the task number: :, — (em-dash), – (en-dash), or - (hyphen):
### Task 1: short title
### Task 2 — another title
#### Task 3 – yet another
#### Task 4 - hyphen style
elaborator agents sometimes rewrite Task N: to Task N —; both forms parse identically.
full example skeleton
**Goal:** implement user authentication
**Architecture:** JWT-based stateless auth with refresh tokens
**Tech Stack:** Go 1.24, chi router, modernc.org/sqlite
## Wave 1
### Task 1: create user model and migration
implement the user struct and the sql migration...
### Task 2: implement JWT helpers
write sign, verify, and refresh functions...
## Wave 2
### Task 3: wire auth middleware
attach the middleware to protected routes...
the task store is the source of truth
the task content is authoritative in the task store. you may also keep markdown on disk for authoring or import/export, but status, branch, topic, timestamps, subtask state, and the canonical stored content live in the task store — a sqlite database at ~/.config/kasmos/taskstore.db (shared across all projects on the machine).
| operation | command |
|---|---|
| register a task file | kas task register <file> |
| view a task's current state | kas task show <file> |
| update task content from stdin | kas task update-content <file> |
| force a lifecycle transition | kas task transition <file> <event> |
| force a specific status | kas task set-status <file> <status> --force |
the store normalizes filenames: a trailing .md suffix is stripped, so my-feature.md and my-feature refer to the same task.
wave orchestration skipping
for very small tasks (configurable via blueprint_skip_threshold in .kasmos/config.toml), kasmos skips wave orchestration entirely and hands the whole task to a single coder agent. see waves for details.