Knowns Task Management

AI-first CLI for task management and documentation. Link docs in tasks, AI reads context automatically. Stop repeating patterns every session. Built-in time tracking, MCP Server, Web UI. Know what your team knows.

Core Rules (NON-NEGOTIABLE)

The Golden Rule

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

Quick Reference Rules

Reference System

Tasks, docs, and templates can reference each other:

| Type | Writing (Input) | Reading (Output) |

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

| Task | `@task-<id>` | `@.knowns/tasks/task-<id>` |

| Doc | `@doc/<path>` | `@.knowns/docs/<path>.md` |

| Template | `@template/<name>` | `@.knowns/templates/<name>` |

**Always follow refs recursively** to gather complete context before planning.

Task Creation Workflow

1. **Search for existing tasks first**:

```json

mcp__knowns__search_tasks({ "query": "keyword" })

```

2. **Create task with clear title and WHY**:

```json

mcp__knowns__create_task({

"title": "Clear title (WHAT)",

"description": "Description (WHY). Related: @doc/security-patterns",

"priority": "medium",

"labels": ["feature", "auth"]

})

```

3. **Add acceptance criteria** (outcomes, NOT implementation steps):

```json

mcp__knowns__update_task({

"taskId": "<id>",

"addAc": ["User can login", "Passwords are hashed"]

})

```

Task Execution Workflow

Step 1: Take Task

```json

// Update status and assignee

mcp__knowns__update_task({

"taskId": "<id>",

"status": "in-progress",

"assignee": "@me"

})

// Start timer (REQUIRED!)

mcp__knowns__start_time({ "taskId": "<id>" })

```

Step 2: Research

```json

// Read task and follow ALL refs

mcp__knowns__get_task({ "taskId": "<id>" })

// Read referenced docs with smart mode

mcp__knowns__get_doc({ "path": "xxx", "smart": true })

// Search related docs

mcp__knowns__search_docs({ "query": "keyword" })

```

Step 3: Plan (BEFORE coding!)

```json

mcp__knowns__update_task({

"taskId": "<id>",

"plan": "1. Research (see @doc/xxx)\n2. Implement\n3. Test\n4. Document"

})

```

**Share plan with user. WAIT for approval before coding.**

Step 4: Implement

```json

// Check AC only AFTER work is done

mcp__knowns__update_task({

"taskId": "<id>",

"checkAc": [1],

"appendNotes": "Done: feature X"

})

```

Task Completion Workflow

A task is **Done** when ALL requirements are met:

```json

// 1. Verify all AC are checked

mcp__knowns__get_task({ "taskId": "<id>" })

// 2. Add implementation notes

mcp__knowns__update_task({

"taskId": "<id>",

"notes": "## Summary\nWhat was done and key decisions."

})

// 3. Stop timer (REQUIRED!)

mcp__knowns__stop_time({ "taskId": "<id>" })

// 4. Mark done

mcp__knowns__update_task({

"taskId": "<id>",

"status": "done"

})

```

Context Optimization

Reading Documents

**ALWAYS use `smart: true`** - auto-handles both small and large docs:

```json

// Small doc (≤2000 tokens) → full content

// Large doc (>2000 tokens) → stats + TOC

mcp__knowns__get_doc({ "path": "readme", "smart": true })

// If large, read specific section:

mcp__knowns__get_doc({ "path": "readme", "section": "3" })

```

Search Before Read

```json

// Search first, then read only relevant docs

mcp__knowns__search_docs({ "query": "authentication" })

mcp__knowns__get_doc({ "path": "security-patterns", "smart": true })

```

Use Filters

```json

// Use filters in queries

mcp__knowns__list_tasks({

"status": "in-progress",

"assignee": "@me"

})

```

Key MCP Tools

Task Management

Document Management

Time Tracking

Templates

Common Mistakes to Avoid

| DON'T | DO |

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

| Edit .md files directly | Use MCP tools |

| Check AC before work done | Check AC AFTER work done |

| Code before plan approval | Wait for user approval |

| Code before reading docs | Read docs FIRST |

| Skip time tracking | Always start/stop timer |

| Ignore refs | Follow ALL `@task-xxx`, `@doc/xxx`, `@template/xxx` refs |

Acceptance Criteria Guidelines

**Write outcomes, NOT implementation steps:**

| Bad | Good |

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

| Add handleLogin() function | User can login |

| Use bcrypt | Passwords are hashed |

| Add try-catch | Errors return proper HTTP codes |

Subtasks

```json

// Create parent first

mcp__knowns__create_task({ "title": "Parent task" })

// Then create subtask with parent ID

mcp__knowns__create_task({

"title": "Subtask",

"parent": "parent-task-id"

})

```

Scope Changes

If new requirements emerge during work:

```json

// Small: Add to current task

mcp__knowns__update_task({

"taskId": "<id>",

"addAc": ["New requirement"],

"appendNotes": "Scope updated: reason"

})

// Large: Ask user first, then create follow-up

mcp__knowns__create_task({

"title": "Follow-up: feature",

"description": "From task <id>"

})

```

**Don't silently expand scope. Ask user first.**

Completion Checklist