# Task Management

Learn how to create, manage, and track tasks with Knowns CLI

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:

1. **Create** the task with clear acceptance criteria
2. **Assign** to yourself and set status to `in-progress`
3. **Start** time tracking: `knowns time start 42`
4. **Check** acceptance criteria as you complete them
5. **Add** implementation notes
6. **Stop** timer: `knowns time stop`
7. **Complete** the task: `knowns task edit 42 -s done`

For the end-to-end AI workflow around those steps, see [Workflow](https://knowns.sh/docs/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"
```