| name | kasmos-cli |
| description | Use when an agent needs exact `kas` command syntax, flags, lifecycle transitions, or troubleshooting for task/instance/skills/setup/check/serve workflows. |
kasmos-cli
Use this skill as the shared source for exact kas CLI syntax, lifecycle transitions, and task/instance workflows.
### command surface scope
The commands below are derived from current Cobra handlers and help output in this repo. Do not document legacy kas plan ... forms; use kas task ... equivalents.
| group | command | command syntax | key flags |
|---|
| task | kas task list | `kas task list [--status <ready | planning |
| task | kas task register | kas task register <plan-file> [--branch <name>] [--topic <topic>] [--description <text>] | --branch, --topic, --description |
| task | kas task create | kas task create <name> [--description <text>] [--branch <name>] [--topic <topic>] [--content <markdown>] | --description, --branch, --topic, --content |
| task | kas task set-status | kas task set-status <plan-file> <status> --force | --force |
| task | kas task transition | kas task transition <plan-file> <event> | none |
| task | kas task show | kas task show <plan-file> | none |
| task | kas task update-content | kas task update-content <plan-file> | none |
| task | kas task start | kas task start <plan-file> | none |
| task | kas task implement | kas task implement <plan-file> [--wave <n>] | --wave |
| task | kas task push | kas task push <plan-file> [--message <text>] | --message |
| task | kas task pr | kas task pr <plan-file> [--title <text>] | --title |
| task | kas task merge | kas task merge <plan-file> | none |
| task | kas task start-over | kas task start-over <plan-file> | none |
| task | kas task link-clickup | kas task link-clickup [--project <name>] | --project |
| instance | kas instance list | `kas instance list [--format text | json] [--status running |
| instance | kas instance kill | kas instance kill <title> | none |
| instance | kas instance pause | kas instance pause <title> | none |
| instance | kas instance resume | kas instance resume <title> | none |
| instance | kas instance send | kas instance send <title> <prompt> | none |
| instance | kas instance status | kas instance status | none |
| skills | kas skills list | kas skills list | none |
| skills | kas skills sync | kas skills sync | none |
| setup | kas setup | kas setup [--force] [--clean] | --force, --clean |
| setup | kas init | kas init [--force] [--clean] | --force, --clean |
| check | kas check | `kas check [-v | --verbose]` |
| serve | kas serve | kas serve [--bind <addr>] [--db <path>] [--port <n>] | --bind, --db, --port |
| signal | kas signal list | kas signal list | none |
| signal | kas signal process | kas signal process [--once] | --once |
| audit | kas audit list | kas audit list [--limit <n>] [--event <kind>] | --limit, --event |
| tmux | kas tmux list | kas tmux list | none |
| tmux | kas tmux adopt | kas tmux adopt <session> <title> | none |
| tmux | kas tmux kill | kas tmux kill <session> | none |
task lifecycle commands
kas task list
- Purpose: list task entries, optionally filtered by status.
- Output format is one line per task:
STATUS + FILE + BRANCH.
--status accepts ready, planning, implementing, reviewing, done, cancelled.
kas task create
- Creates an entry in the task store, not necessarily local file.
- Default branch is
plan/<name>.
- Optional fields:
--description, --branch, --topic, --content.
kas task register
- Registers a local plan file into the task store and sets status to
ready.
<plan-file> is resolved relative to current working dir.--branch defaults to plan/<slug> where slug is file basename without .md.- If no
--description, first # heading from file becomes description.
kas task set-status
- Force-overrides status and bypasses FSM.
- Requires
--force; otherwise it exits with --force required to override task status (this bypasses the FSM).
kas task transition
- Applies FSM event names only (no free-form status).
- Valid events:
plan_start, planner_finished, implement_start, implement_finished, review_approved, review_changes, request_review, start_over, reimplement, cancel, reopen, verify_approved, verify_failed.
- Note:
verify_approved and verify_failed are also accepted as gateway signals via kas signal emit. Agents should prefer kas signal emit verify_approved <planfile> over kas task transition for consistency with other signal-driven workflows. Legacy aliases readiness_approved and readiness_changes_requested are also accepted as gateway signals.
kas task show
- Prints stored task content.
- Fails with
task not found: <file> if entry missing.
- Fails with
no content stored for <file> if content is empty/whitespace.
kas task update-content
- Replaces task content in store.
- Reads updated content from stdin only (no
--file flag is supported).
- If stdin is a TTY (no piped or redirected input), the command exits with an error instead of waiting for input.
kas task start
- Transitions task to
implementing via FSM when needed.
- Sets up dedicated task branch and worktree.
- Prints
started: <plan-file> → implementing and the worktree path.
kas task implement
- Writes implementation signal file for branch/worktree orchestration.
--wave must be >= 1.- Invalid wave number returns
wave number must be >= 1, got <n>.
kas task push
- Commits dirty changes in task worktree and pushes branch.
--message defaults to update from kas.
kas task pr
- Push + opens a pull request via GitHub CLI.
- Uses description by default when
--title is missing; falls back to file stem.
kas task merge
- Merges task branch into current branch and transitions FSM to done.
- If task is not in
reviewing, it transitions via implement_finished or forces to reviewing before review_approved.
kas task start-over
- Resets branch from
HEAD (git.ResetTaskBranch).
- Uses FSM
start_over when valid; otherwise force-sets status to planning.
kas task link-clickup
- Scans stored plan content for
**Source:** ClickUp <ID> lines.
- Updates missing ClickUp IDs in store entries.
- Optional
--project overrides derived project name.
instance lifecycle commands
actions and state rules
validateStatusForAction logic:
kill: allowed from any state.pause: not allowed when already paused (instance is already paused).resume: allowed only from paused (can only resume paused instances (current status: <status>)).send: not allowed when paused (cannot send prompt to a paused instance).
| command | behavior |
|---|
kas instance list | list all instances; defaults text format |
kas instance list --format json | outputs JSON with title, status, branch, program, optional task_file |
kas instance list --status paused | filters list by lowercase status |
kas instance kill <title> | refuses dirty worktrees (shows changed-file summary), otherwise removes tmux session and worktree and marks paused (branch preserved); allowed from any state |
kas instance pause <title> | refuses dirty worktrees (shows changed-file summary), otherwise removes tmux session and worktree and marks paused; not allowed if already paused |
kas instance resume <title> | recreates worktree from preserved branch, restarts tmux session |
kas instance send <title> <prompt> | sends prompt into resumed tmux session |
kas instance status | shows aggregated counts (running, ready, paused, killed) |
signal commands
kas signal list
- Lists pending signals in
.kasmos/signals/ under the resolved repo root (cmd/signal.go:37, cmd/task.go:922).
- Includes FSM signals, wave signals, and elaboration signals.
- Formats one line per signal and prints
no pending signals when the directory is empty or missing (cmd/signal.go:108, cmd/signal_test.go:60).
kas signal process
- Processes FSM signals from
.kasmos/signals/ and consumes signal files after handling (cmd/signal.go:135).
--once: process one batch and exit, printing either processed N signal(s) or no signals to process (cmd/signal.go:79).- Default mode loops every 5 seconds and prints
watching for signals (ctrl-c to stop)... before polling (cmd/signal.go:91).
- Unknown plans and invalid transitions are consumed and logged, not returned as fatal errors (
cmd/signal.go:153, cmd/signal.go:160).
review_changes_requested also increments the stored review-cycle counter (cmd/signal.go:167, cmd/signal_test.go:313).- Wave and elaboration signals are consumed but not transitioned by the FSM (
cmd/signal.go:183).
verify_approved — emitted by the master agent after a successful readiness review in the verifying state; transitions the task to done.verify_failed — emitted by the master agent when the implementation needs further work; sends the task back to implementing.readiness_approved / readiness_changes_requested — deprecated aliases for verify_approved / verify_failed; accepted by the gateway for backward compatibility.
audit commands
kas audit list
- Queries audit events for the current project from the shared SQLite audit logger (
cmd/audit.go:26, cmd/audit.go:49).
--limit defaults to 50; values <= 0 fail with limit must be > 0 (cmd/audit.go:16, cmd/audit_test.go:108).--event filters by event kind string (for example agent_spawned) before rendering (cmd/audit.go:57, cmd/audit_test.go:93).- Output is a tabwriter table with
TIME, EVENT, and DETAILS columns (cmd/audit.go:74).
- Empty results print
no audit entries found (cmd/audit.go:67).
- DETAILS joins message/detail as
message | detail when both are present (cmd/audit.go:88).
tmux commands
kas tmux list
- Lists orphan
kas_ tmux sessions that are not already represented in persisted instance state (cmd/tmux.go:121).
- Output columns are
NAME, TITLE, WINDOWS, ATTACHED, and AGE (cmd/tmux.go:147).
- Returns
no orphan tmux sessions found when no unmanaged kas_ sessions exist (cmd/tmux.go:140, cmd/tmux_test.go:159).
kas tmux adopt
- Usage is exactly
kas tmux adopt <session> <title> (cmd/tmux.go:277).
- Validation order is fixed: non-empty title, unique title, then orphan session existence (
cmd/tmux.go:164).
- On success it appends a new instance record with
status=ready, program=unknown, and path=. because the cobra handler passes "." as repo root (cmd/tmux.go:171, cmd/tmux.go:285).
- Duplicate titles fail with
instance title already exists: <title> (cmd/tmux.go:183, cmd/tmux_test.go:190).
- Managed or missing sessions fail with
orphan tmux session not found: <session> (cmd/tmux.go:204).
kas tmux kill
- Usage is exactly
kas tmux kill <session> (cmd/tmux.go:293).
- Only orphan sessions are eligible; managed or missing sessions fail with
orphan tmux session not found: <session> (cmd/tmux.go:227, cmd/tmux_test.go:306).
- Executor failures wrap as
kill tmux session <name>: <cause> (cmd/tmux.go:225, cmd/tmux_test.go:262).
- This command is intentionally separate from
kas instance kill, which operates on managed instances.
skills commands
kas skills list
- Shows personal (
~/.agents/skills) and project (./.agents/skills) entries.
- Symlinks are printed with
-> <target> (external) when the listed entry is a symlink.
- This is the list used by harness sync + skill loading checks.
kas skills sync
- Syncs personal skills from
~/.agents/skills/ into harness global directories.
- Global targets are Claude and OpenCode skill directories (not project
.agents/skills).
- Output includes
OK, SKIP (not installed), and FAILED statuses.
setup commands
kas setup / kas init
- Alias pair:
setup and init are interchangeable.
--force: overwrite project scaffold files.--clean: ignore existing config and start from defaults.- Runs interactive initialization flow for harness detection, roles, hooks, and project scaffolding.
check command
kas check
- Health audit for global + project skill sync.
-v/--verbose prints per-skill detail rows.- Prints
Health: X/Y OK (N%).
- Exits non-zero when
N < 100 (even after useful output) because it returns an internal unhealthy sentinel.
serve command
kas serve
- Starts task store HTTP server (
taskstore.NewHandler).
- Defaults:
--bind: 0.0.0.0--db: resolved default sqlite path (usually under .kasmos/taskstore.db)--port: 7433
- Logs
task store listening on http://<bind>:<port> (db: <path>) and supports graceful SIGINT/SIGTERM shutdown.
workflows
workflow A: task file bootstrap + register/show/update
kas task create my-feature --description "Add search indexing support" --topic infra --branch plan/my-feature
kas task show my-feature.md
cat /tmp/my-feature.md | kas task update-content my-feature.md
kas task show my-feature.md
kas task register plans/my-feature.md --topic infra --branch plan/my-feature
kas task show my-feature.md
cat plans/my-feature.md | kas task update-content my-feature.md
workflow B: branch/worktree lifecycle
kas task start my-feature.md
kas task push my-feature.md --message "checkpoint from implementing"
kas task pr my-feature.md --title "My feature"
kas task merge my-feature.md
kas task start-over my-feature.md
workflow C: FSM-first flow vs override flow
kas task transition my-feature.md plan_start
kas task transition my-feature.md planner_finished
kas task transition my-feature.md implement_start
kas task transition my-feature.md implement_finished
kas task transition my-feature.md request_review
kas task set-status my-feature.md cancelled --force
workflow D: signal processing and orphan tmux cleanup
kas signal list
kas signal process --once
kas audit list --limit 20
kas tmux list
wave orchestration
kas task implement <plan-file> --wave <n> writes an implementation signal consumed by downstream automation.- Use FSM transitions for normal lifecycle movement, only reserve
set-status --force for manual recovery scenarios.
edge cases and troubleshooting
kas task set-status <plan-file> <status> without --force fails by design.kas task implement <plan-file> --wave 0 fails: wave number must be >= 1, got 0.kas task update-content <plan-file> reads from stdin only.kas task update-content <plan-file> with a TTY stdin fails fast with stdin is a tty; pipe plan content via stdin: cat plan.md | kas task update-content <plan>.kas task show <missing-file> errors as task not found.kas task show <file-with-empty-content> errors no content stored.kas check can print full health tables and still exit code 1 when health is below 100%.kas instance send returns cannot send prompt to a paused instance for paused targets.kas instance resume requires preserved worktree metadata (repo path + branch), else instance "<title>" has no stored worktree metadata; cannot resume.kas signal process without --once runs indefinitely until interrupted; kas tmux adopt rejects blank titles; kas tmux kill rejects managed sessions; kas audit list --limit 0 fails with limit must be > 0.
anti-patterns
- Using legacy
kas plan ... command forms (or docs that suggest it) instead of kas task ....
- Editing task store files directly when
kas task create/register/update-content/show/transition already owns state transitions.
- Using
kas task set-status for normal state movement (replace with kas task transition and valid events).
- Assuming
kas skills sync syncs project-level ./.agents/skills into harness globals; it only syncs personal ~/.agents/skills to harness global dirs.
- documenting bare
kas audit / kas signal / kas tmux as if they do useful work without subcommands; running kas signal process inside the TUI-managed flow where metadata ticks already consume orchestration signals; using kas tmux kill for managed instances instead of kas instance kill
verification checks
- Detect missing skill before implementation:
kas skills list | rg 'kasmos-cli'
- Verify skill is visible after adding this file:
kas skills list | rg 'kasmos-cli'
