kas task
Manage the full lifecycle of kasmos tasks — from registration through planning, implementation, review, and merge.
kas task <subcommand> [flags]
Alias: kas t
filename normalization
All subcommands that accept a <plan-file> argument automatically strip a trailing .md suffix. The stored identifier is always the extensionless slug (e.g. my-feature, not my-feature.md). This normalization also applies when ingesting content and when the SQLite store runs its migration.
subcommands
list
List all tasks with their status and branch.
kas task list [--status <status>]
# show all non-cancelled tasks
kas task list
# show only tasks in implementing state
kas task list --status implementing
| flag | description |
|---|---|
--status | filter by status: ready, planning, implementing, reviewing, verifying, done, cancelled |
When --status is omitted, cancelled tasks are hidden from the output.
register
Register a task file (markdown) into the task store and set its initial status to ready.
kas task register <plan-file> [--branch <branch>] [--topic <topic>] [--description <desc>]
# register with defaults — branch defaults to plan/<slug>
kas task register tasks/my-feature.md
# register with an explicit branch and topic
kas task register tasks/my-feature.md --branch feature/my-feature --topic backend
| flag | default | description |
|---|---|---|
--branch | plan/<slug> | git branch name for the task |
--topic | — | topic group (auto-created if needed) |
--description | first # heading in file | human-readable task description |
The filename is resolved relative to the working directory. The stored key is strings.TrimSuffix(filepath.Base(filePath), ".md").
create
Create a new task entry directly in the store without requiring a file on disk.
kas task create <name> [--description <desc>] [--branch <branch>] [--topic <topic>] [--content <markdown>]
# minimal creation
kas task create my-feature
# with description and topic
kas task create my-feature --description "Add feature X" --topic frontend
# with inline content
kas task create my-feature --content "# my-feature\n\n## Wave 1\n### Task 1: implement X"
| flag | default | description |
|---|---|---|
--description | — | task description |
--branch | plan/<name> | git branch name |
--topic | — | topic group |
--content | — | initial markdown content |
show
Print the full plan content stored in the task store.
kas task show <plan-file>
kas task show my-feature
Returns an error if the task has no stored content.
validate-architect-meta
Strictly validate .kasmos/cache/<plan-file>-architect.json before emitting the architect completion signal.
kas task validate-architect-meta <plan-file>
The validator decodes the complete Go metadata schema with unknown fields rejected, requires waves and each wave's tasks to be arrays, checks task and wave numbers, and validates the embedded decision audit against the task and project. Architect agents must not signal completion when this command fails.
update-content
Replace the plan content in the task store by reading from stdin.
kas task update-content <plan-file>
cat updated-plan.md | kas task update-content my-feature
Content must be piped via stdin — the command errors if stdin is a tty. The filename argument is normalized with strings.TrimSuffix(filename, ".md"). If content parse warnings occur (e.g. no wave headers), the content is still stored and a warning is printed to stderr but the command exits 0.
set-status
Force-override a task's status, bypassing the FSM transition rules.
kas task set-status <plan-file> <status> --force
kas task set-status my-feature ready --force
| flag | description |
|---|---|
--force | required; confirms intent to bypass FSM (safety guard) |
Valid statuses: ready, planning, implementing, reviewing, verifying, done, cancelled.
transition
Apply a named FSM event to a task, advancing or reversing its lifecycle state.
kas task transition <plan-file> <event>
kas task transition my-feature implement_start
| event | description |
|---|---|
plan_start | ready or planning → planning (start or restart planner) |
planner_finished | planning → ready (sets execution phase to planned) |
implement_start | ready (planned-ready only) → implementing |
implement_finished | implementing → reviewing |
request_review | done → reviewing (retrigger a reviewer without resetting) |
review_approved | reviewing → verifying (when auto_readiness_review = true) or reviewing → done |
review_changes_requested | reviewing → implementing (canonical event name) |
review_changes | alias for review_changes_requested accepted by the CLI only |
verify_approved | verifying → done |
verify_failed | verifying → implementing |
start_over | done → planning (full reset) |
reimplement | done → implementing (resume without resetting branch) |
cancel | cancel the task from any active status |
reopen | cancelled → planning |
When [linear.receipts] is enabled and the task has an explicit Linear link, transitions that match the configured event allowlist post a receipt comment to the linked Linear issue. The CLI waits for in-flight receipt deliveries to settle before returning. See linear receipts.
For lifecycle events with daemon work, task transition also emits the canonical gateway signal after applying the FSM change. The signal is marked as pre-applied so the daemon runs the downstream action, such as spawning planners or reviewers, without attempting the state transition a second time.
implement
Transition a task to implementing state and write a wave signal file for the TUI orchestrator.
kas task implement <plan-file> [--wave <n>]
kas task implement my-feature --wave 1
| flag | default | description |
|---|---|---|
--wave | 1 | wave number to trigger (must be ≥ 1) |
If the task is still in planning, the command first applies planner_finished (→ ready, setting execution phase to planned) then implement_start. If the task is ready but still in draft-ready state (execution phase is empty — the planner has not finished), the command returns an error. The wave signal file is written to .kasmos/signals/implement-wave-<n>-<plan-file>.
start
Transition a task to implementing and set up the git branch and worktree.
kas task start <plan-file>
kas task start my-feature
Walks planning → ready → implementing via the FSM if needed, then calls git worktree add using the stored branch name (defaulting to plan/<slug>). Prints the worktree path on success.
push
Commit any dirty changes in the task worktree and push to origin.
kas task push <plan-file> [--message <msg>]
kas task push my-feature --message "wip: implement first pass"
| flag | default | description |
|---|---|---|
--message | "update from kas" | commit message for dirty changes |
pr
Ensure the task has a GitHub pull request, adopting an existing PR when possible.
kas task pr <plan-file> [--title <title>]
kas task pr my-feature
kas task pr my-feature --title "feat: implement feature X"
| flag | default | description |
|---|---|---|
--title | task description | PR title |
On success the command prints the PR URL and persists it in the task store. A trailing .md in <plan-file> is normalized before lookup, and an idempotent call for a task with a recorded PR prints that existing URL. The PR body is generated from the plan content (goal, architecture, tech stack) and git log (commits, changed files, diff stats) using gh pr create.
The command exits non-zero when creation is blocked, including a dirty task worktree, a missing task branch, or an unauthenticated gh CLI. Clear the reported condition and run kas task pr <plan-file> again. The existing-PR preflight makes retries idempotent.
PR creation is gated by HEAD-bound verification. The task must be done, have a non-empty verified_sha, and that SHA must equal the branch's live HEAD. If HEAD drifted, kasmos reopens the task to verifying, stops the stale master, and starts fresh verification instead of creating the PR. Legacy done tasks without a verified_sha must be re-verified first.
merge
Merge the task branch into main and transition the task to done.
kas task merge <plan-file>
kas task merge my-feature
Before merging, the CLI requires done with a non-empty verified_sha equal to live branch HEAD. Drift reopens the task to verifying and starts fresh verification; no merge occurs. The TUI merge action applies the same gate. Legacy done tasks without a bound SHA must be re-verified first.
start-over
Remove the task worktree, reset the branch from HEAD, and transition back to planning.
kas task start-over <plan-file>
kas task start-over my-feature
recover
Manually emit a recovery signal to unstick a task that is in the wrong phase or state.
kas task recover <plan-file> --action <action> [--feedback <text>]
kas task recover my-feature --action implement-finished
kas task recover my-feature --action review-approved
kas task recover my-feature --action verify-approved
kas task recover my-feature --action verify-failed --feedback "spec section 3 is not addressed"
| flag | description |
|---|---|
--action | the recovery action to perform (see table below) |
--feedback | feedback text; required for review-changes, verify-failed, and advance-review-cycle |
| action | signal emitted | notes |
|---|---|---|
planner-finished | planner_finished | |
architect-finished | elaborator_finished | |
implement-finished | implement_finished | |
review-approved | review_approved | |
review-changes | review_changes_requested | requires --feedback |
advance-review-cycle | review_changes_requested | requires --feedback; alias for review-changes |
verify-approved | verify_approved | only valid while task is in verifying; resolves and submits both the live task HEAD and default-branch SHA |
verify-failed | verify_failed | only valid while task is in verifying status; requires --feedback |
advance-wave | advance_wave | advance a stuck multi-wave task to the next wave |
retry-wave | retry_wave | replace stale wave agents and re-run every unresolved task in the current wave; completed tasks stay complete |
verify-approved and verify-failed are the manual recovery path for the master agent gate. Use them when the master agent session ended before it could emit a signal. The kas status command shows these hints automatically when a task is stuck in the verifying status.
Unlike a raw master signal, recover --action verify-approved does not accept caller-supplied SHAs. It resolves the task HEAD and default-branch SHA locally, then submits the same two-SHA admission proof required from the master.
verify_failed is fail-closed: it always returns the task to implementing. Use max_review_fix_cycles to bound automatic fixer loops; reaching that limit requires operator recovery and never implies approval.
link-clickup
Scan all tasks in the project and backfill ClickUp task IDs by parsing **Source:** ClickUp <ID> lines from plan content.
kas task link-clickup [--project <project>]
| flag | description |
|---|---|
--project | override project name (default: derived from current directory) |
link-linear
link one task to a Linear issue by fetching the issue from Linear and storing its canonical identifiers in the task store.
kas task link-linear <plan-file> <issue> [--force] [--comment] [--message <body>] [--reason <text>] [--project <project>]
kas task link-linear my-feature KAS-123
kas task link-linear my-feature KAS-456 --force --reason "replanned scope"
kas task link-linear my-feature KAS-123 --comment --message "kasmos is now executing this task"
| flag | description |
|---|---|
--force | replace an existing Linear link on this task |
--comment | post an opt-in backlink comment to the Linear issue after the store write commits |
--message | comment body to use with --comment; defaults to a generated backlink |
--reason | operator reason recorded in audit metadata |
--project | override project name (default: derived from current directory) |
link-linear requires a Linear API key in KASMOS_LINEAR_API_KEY or LINEAR_API_KEY. kas loads <repo-root>/.env on startup without overriding already-exported variables, so the key can be project-local. set KASMOS_LINEAR_API_URL only when pointing at a non-default Linear-compatible GraphQL endpoint.
before writing the link, kasmos rejects duplicate active links to the same canonical Linear issue id within the same project. active duplicate detection covers tasks in planning, implementing, reviewing, and verifying; ready, done, and cancelled tasks do not block a new link. use --force only to replace the link on the same task. it does not override a duplicate link owned by another active task.
unlink-linear
clear the stored Linear issue link from one task.
kas task unlink-linear <plan-file> [--reason <text>] [--project <project>]
kas task unlink-linear my-feature --reason "issue moved back to planning"
| flag | description |
|---|---|
--reason | operator reason recorded in audit metadata |
--project | override project name (default: derived from current directory) |
unlinking updates only kasmos task metadata and audit history. it does not edit the Linear issue or drive any kasmos lifecycle transition.
PR creation resolves legacy tasks without a stored branch using the canonical plan/<task> branch, then applies the same HEAD-bound verification gate before creating or adopting a pull request.