Task Management

Tasks are the core of Knowns. They help you track work items with acceptance criteria, time tracking, and status management.

Use this page when you want to create better tasks, keep work moving through a consistent workflow, and write task content that AI or teammates can act on quickly.

Quick Start

knowns task create "Add user authentication" \
  -d "Implement JWT-based auth system" \
  --ac "User can register" \
  --ac "User can login" \
  --priority high \
  -l "auth,feature"

knowns task list --status in-progress --plain
knowns task edit 42 -s in-progress -a @me
knowns task edit 42 --check-ac 1

Creating Tasks

Create a task with the task create command:

knowns task create "Add user authentication" \
  -d "Implement JWT-based auth system" \
  --ac "User can register" \
  --ac "User can login" \
  --ac "User can logout" \
  --priority high \
  -l "auth,feature"

Options

Option	Short	Description
`--description`	`-d`	Task description
`--ac`		Acceptance criterion (repeatable)
`--priority`		low, medium, high
`--labels`	`-l`	Comma-separated labels
`--assignee`	`-a`	Assign to user (@me or @username)

Viewing Tasks

List all tasks

knowns task list --plain

Filter by status

knowns task list --status in-progress --plain

View single task

knowns task 42 --plain
knowns task view 42 --plain

Updating Tasks

Change status

knowns task edit 42 -s in-progress

Assign to yourself

knowns task edit 42 -a @me

Check acceptance criteria

knowns task edit 42 --check-ac 1 --check-ac 2

Add implementation plan

knowns task edit 42 --plan $'1. Design API\n2. Implement endpoints\n3. Add tests'

Add notes

knowns task edit 42 --notes "Completed implementation with 95% coverage"

Task Workflow

A typical task workflow:

Create the task with clear acceptance criteria
Assign to yourself and set status to in-progress
Start time tracking: knowns time start 42
Check acceptance criteria as you complete them
Add implementation notes
Stop timer: knowns time stop
Complete the task: knowns task edit 42 -s done

For the end-to-end AI workflow around those steps, see Workflow.

Status Values

Status	Description
`todo`	Not started (default)
`in-progress`	Currently working on
`in-review`	Submitted for review
`blocked`	Waiting on dependency
`done`	Completed

Best Practices

Good Acceptance Criteria

Write outcome-oriented criteria, not implementation steps:

# Good
--ac "User can login and receive JWT token"
--ac "Invalid credentials show error message"

# Bad
--ac "Add handleLogin function"
--ac "Use bcrypt for hashing"

Clear Titles

Use action-oriented titles that describe what needs to be done:

# Good
"Add password reset flow"
"Fix timeout on slow networks"

# Bad
"Auth stuff"
"Bug fix"

Workflow - Choose the right implementation flow
CLI Reference - Full task command reference
AI Agent Guide - How agents should work with tasks and docs

Task Management

On this page