Knowns Task Management

AI-first CLI for task management and documentation. Link docs in tasks, AI reads context automatically. Built-in time tracking, knowledge base, and team collaboration.

What This Skill Does

This skill enables you to work with the Knowns CLI to manage tasks, documentation, and time tracking. You will follow strict rules about using CLI commands instead of direct file editing, understand the reference system, and maintain proper workflow from task creation through completion.

Critical Rules

The Golden Rule

**If you want to change ANYTHING in a task or doc, use CLI commands. NEVER edit .md files directly.**

Direct file editing breaks metadata synchronization, Git tracking, and relationships.

The -a Flag Confusion

The `-a` flag means DIFFERENT things in different commands:

**For acceptance criteria, ALWAYS use `--ac`:**

```bash

❌ WRONG

knowns task edit 35 -a "- [ ] Criterion" # Sets assignee to garbage!

✅ CORRECT

knowns task edit 35 --ac "Criterion one"

knowns task edit 35 --ac "Criterion two"

```

Core Principles

1. **CLI Only** - Use commands for ALL operations, never edit .md files directly

2. **Docs First** - Read project docs BEFORE planning or coding

3. **Time Tracking** - Always start timer when taking task, stop when done

4. **Plan Approval** - Share plan with user, WAIT for approval before coding

5. **Check AC After Work** - Only mark acceptance criteria done AFTER completing the work

The --plain Flag

ONLY use `--plain` for view/list/search commands (NOT create/edit):

```bash

✅ CORRECT

knowns task <id> --plain

knowns task list --plain

knowns doc "path" --plain --smart

❌ WRONG

knowns task create "Title" --plain # ERROR!

knowns task edit <id> -s done --plain # ERROR!

```

Reference System

**Writing (input):**

**Reading (output):**

Follow refs recursively until complete context gathered.

Task Workflow

1. Creating Tasks

Search for existing tasks first:

```bash

knowns search "keyword" --type task --plain

```

Create task with clear title and outcome-focused acceptance criteria:

```bash

knowns task create "Clear title (WHAT)" \

-d "Description (WHY)" \

--ac "Outcome 1" \

--ac "Outcome 2" \

--priority medium \

-l "labels"

```

**Quality guidelines:**

- ✅ Good: "User can login", "Passwords are hashed"

- ❌ Bad: "Add handleLogin() function", "Use bcrypt"

2. Taking a Task

```bash

knowns task edit <id> -s in-progress -a @me

knowns time start <id> # REQUIRED!

```

3. Research Phase

Read task and follow ALL references:

```bash

knowns task <id> --plain

Follow @.knowns/docs/xxx.md → knowns doc "xxx" --plain --smart

Follow @.knowns/tasks/task-YY → knowns task YY --plain

```

Search related docs:

```bash

knowns search "keyword" --type doc --plain

```

4. Planning (BEFORE Coding!)

Create implementation plan:

```bash

knowns task edit <id> --plan $'1. Research (see @doc/xxx)\n2. Implement\n3. Test\n4. Document'

```

**⚠️ CRITICAL: Share plan with user and WAIT for approval before coding.**

5. Implementation

Check acceptance criteria ONLY AFTER work is done:

```bash

knowns task edit <id> --check-ac 1

knowns task edit <id> --append-notes "✓ Done: feature X"

```

If scope changes during work:

6. Completion

Stop timer and mark task done:

```bash

knowns time stop

knowns task edit <id> -s done

```

**Definition of Done:**

Documentation Management

Reading Documents (Always Use --smart)

**ALWAYS use `--smart` when reading documents:**

```bash

knowns doc <path> --plain --smart

```

**Behavior:**

Creating Documents

```bash

knowns doc create <title> \

-d "Description" \

--tags "tag1,tag2" \

--folder "folder/path"

```

**Structure best practice:**

Editing Documents

Replace entire content:

```bash

knowns doc edit <name> -c "New content..."

```

Append content:

```bash

knowns doc edit <name> -a "Additional content..."

```

Edit specific section (context-efficient):

```bash

View TOC first

knowns doc <name> --toc --plain

Edit only that section

knowns doc edit <name> --section "2" -c "New content..."

```

Context Optimization

Best Practices

1. **Always use `--plain`** for output (never `--json` unless needed)

2. **Always use `--smart`** when reading docs

3. **Search before reading** - Don't read all docs hoping to find info

4. **Read selectively** - Use offset/limit for large files

5. **Write concise notes** - Bullet points, not paragraphs

6. **Don't repeat** - Reference context already loaded

Efficient Workflow

| Phase | Approach |

|-------|----------|

| Research | Search → Read only matches |

| Planning | Brief plan, not detailed prose |

| Coding | Read only files being modified |

| Notes | Bullet points, not paragraphs |

| Completion | Summary, not full log |

Time Tracking

Required commands:

```bash

knowns time start <id> # When taking task

knowns time stop # When completing

knowns time pause # Optional: during breaks

knowns time resume # Optional: after breaks

knowns time status # Check current timer

```

Manual time entry:

```bash

knowns time add <id> <duration> -n "Note" -d "2025-01-01"

```

Search

Search across tasks and docs:

```bash

knowns search "query" --plain

knowns search "auth" --type task --plain

knowns search "api" --type doc --plain

knowns search "bug" --type task --status in-progress --priority high --plain

```

Task Management Commands

Viewing Tasks

```bash

knowns task <id> --plain # View single task

knowns task list --plain # List all

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

knowns task list --assignee @me --plain

knowns task list --tree --plain # Tree hierarchy

```

Editing Tasks

```bash

knowns task edit <id> [options]

```

Common options:

Subtasks

```bash

knowns task create "Parent task"

knowns task create "Subtask" --parent <parent-id> # Use raw ID only!

```

Common Anti-Patterns to Avoid

❌ **Don't:**

✅ **Do:**

Task IDs

Knowns supports multiple ID formats:

**Always use raw ID for `--parent`:**

```bash

✅ CORRECT

knowns task create "Title" --parent 48

❌ WRONG

knowns task create "Title" --parent task-48

```

Status Values

Priority Values

Examples

**Create a well-structured task:**

```bash

knowns task create "Add user authentication" \

-d "Support JWT-based auth for API endpoints. See @doc/security-patterns" \

--ac "Users can login with email/password" \

--ac "Passwords are hashed with bcrypt" \

--ac "JWT tokens expire after 24h" \

--priority high \

-l "backend,security"

```

**Take and start working on a task:**

```bash

knowns task edit qkh5ne -s in-progress -a @me

knowns time start qkh5ne

knowns task qkh5ne --plain

Read referenced docs with --smart

knowns doc security-patterns --plain --smart

```

**Create and share implementation plan:**

```bash

knowns task edit qkh5ne --plan $'1. Research bcrypt library (see @doc/dependencies)\n2. Create auth middleware\n3. Add login/logout endpoints\n4. Write tests\n5. Update API docs'

Share plan with user and wait for approval

```

**Complete task:**

```bash

knowns task edit qkh5ne --check-ac 1

knowns task edit qkh5ne --check-ac 2

knowns task edit qkh5ne --check-ac 3

knowns task edit qkh5ne --append-notes "✓ All endpoints tested and documented"

knowns time stop

knowns task edit qkh5ne -s done

```

Constraints