AI-first CLI for task management and documentation. Link docs in tasks, AI reads context automatically. Built-in time tracking, structured workflows.
Use the Knowns CLI to manage tasks, documentation, and time tracking. Knowns provides structured task workflows with automatic context gathering through document references.
**CRITICAL RULES:**
1. **CLI/MCP Only**: Use `knowns` commands for ALL operations. NEVER edit `.md` files directly in `.knowns/` folder.
2. **Docs First**: Read project docs BEFORE planning or coding using `knowns doc` and `knowns search`.
3. **Time Tracking**: Always start timer with `knowns time start <id>` when taking a task, stop with `knowns time stop` when done.
4. **Plan Approval**: Share implementation plan with user, WAIT for approval before coding.
5. **Check AC After Work**: Only mark acceptance criteria done AFTER completing the work, not before.
**CRITICAL:** The `-a` flag means DIFFERENT things in different commands:
**For acceptance criteria, ALWAYS use `--ac`:**
```bash
knowns task create "Title" -a "Criterion" # Sets assignee to garbage!
knowns task create "Title" --ac "Criterion one" --ac "Criterion two"
knowns task edit 35 --ac "New criterion"
```
When working with tasks and docs, use proper reference formats:
Follow references recursively until complete context is gathered.
Task IDs come in different formats:
**CRITICAL:** Use raw ID for `--parent`:
```bash
knowns task create "Title" --parent 48
knowns task create "Title" --parent task-48
```
Always optimize context usage to work efficiently within token limits:
1. **Use `--plain` flag**: Always use `--plain` for compact output (never `--json` unless needed)
2. **Use `--smart` flag**: Always use `--smart` when reading docs (auto-handles small vs large docs)
3. **Search before read**: Use `knowns search` to find relevant docs/tasks before reading them all
4. **Selective reading**: Use `offset` and `limit` for large files
5. **Compact notes**: Write brief bullet points, not paragraphs
```bash
knowns search "keyword" --type task --plain
```
```bash
knowns task create "Clear title (WHAT)" \
-d "Description (WHY + context)" \
--ac "Outcome 1 (user-facing result)" \
--ac "Outcome 2 (user-facing result)" \
--priority medium \
-l "label1,label2"
```
**Title Guidelines:**
**Acceptance Criteria Guidelines:**
```bash
knowns task create "Parent task"
knowns task create "Subtask 1" --parent 48
knowns task create "Subtask 2" --parent 48
```
```bash
knowns task edit <id> -s in-progress -a @me
knowns time start <id> # REQUIRED!
```
```bash
knowns task <id> --plain
knowns search "keyword" --type doc --plain
knowns search "keyword" --type task --status done --plain
```
```bash
knowns task edit <id> --plan $'1. Research patterns (see @doc/xxx)\n2. Implement core feature\n3. Add tests\n4. Update documentation'
```
**⚠️ WAIT for user approval before proceeding to coding!**
Write code, then mark acceptance criteria as completed:
```bash
knowns task edit <id> --check-ac 1
knowns task edit <id> --append-notes "✓ Completed: feature X implemented"
knowns task edit <id> --check-ac 2
knowns task edit <id> --append-notes "✓ Completed: tests passing"
```
If new requirements emerge:
**Small changes:**
```bash
knowns task edit <id> --ac "New requirement"
knowns task edit <id> --append-notes "⚠️ Scope updated: added X because Y"
```
**Large changes:**
Ask user first, then create follow-up task:
```bash
knowns task create "Follow-up: new feature" -d "Split from task <id> due to scope"
```
Before marking task as done, verify:
1. ✅ All acceptance criteria checked
2. ✅ Code implemented and tested
3. ✅ Documentation updated
4. ✅ Time tracked and stopped
5. ✅ Notes summarize what was done
```bash
knowns time stop
knowns task edit <id> -s done
knowns task edit <id> --append-notes "✓ Completed: [brief summary of work]"
```
```bash
knowns doc create "Document Title" \
-d "Brief description" \
-t "tag1,tag2,tag3" \
-f "folder/path"
```
**Use structured headings for easy navigation:**
```markdown
Introduction...
Steps...
...
...
```
**ALWAYS use `--smart` flag:**
```bash
knowns doc <path> --plain --smart
knowns doc <path> --plain --section "2"
```
**Manual control (if needed):**
```bash
knowns doc <path> --info --plain # Check size
knowns doc <path> --toc --plain # View table of contents
knowns doc <path> --section "3" --plain # Read specific section
```
**Replace specific section (context-efficient):**
```bash
knowns doc readme --toc --plain
knowns doc edit readme --section "2. Installation" -c "New content here..."
```
**Other edit operations:**
```bash
knowns doc edit <name> -c "New content..."
knowns doc edit <name> -a "Additional content..."
knowns doc edit <name> -t "Document Title" -d "New description" --tags "new,tags"
```
Use search to find tasks or docs before reading:
```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
```
```bash
knowns time start <id> # Start timer (REQUIRED when taking task)
knowns time stop # Stop timer (REQUIRED when completing)
knowns time pause # Pause current timer
knowns time resume # Resume paused timer
knowns time status # Check current timer
knowns time add <id> <duration> -n "Manual entry note" -d "2025-01-01"
```
```bash
knowns task <id> --plain
knowns task list --plain
knowns task list --status in-progress --plain
knowns task list --assignee @me --plain
knowns task list --tree --plain # Hierarchical view
knowns task edit <id> -t "New title"
knowns task edit <id> -s done
knowns task edit <id> --priority high
knowns task edit <id> --ac "New acceptance criterion"
knowns task edit <id> --check-ac 2 # Mark 2nd AC as done
knowns task edit <id> --uncheck-ac 2 # Unmark 2nd AC
knowns task edit <id> --remove-ac 2 # Delete 2nd AC
knowns task edit <id> --append-notes "Additional note"
```
```bash
knowns doc <path> --plain --smart
knowns doc list --plain
knowns doc list --tag api --plain
```
**Status values:**
**Priority values:**
1. ❌ Editing `.md` files directly → Use `knowns` commands
2. ❌ Using `-a` for acceptance criteria → Use `--ac`
3. ❌ Reading all docs without searching → Use `knowns search` first
4. ❌ Marking AC done before work → Check AC only AFTER completion
5. ❌ Starting work without plan approval → Share plan and WAIT
6. ❌ Forgetting time tracking → Always `knowns time start` and `stop`
7. ❌ Too many AC in one task → Split into multiple tasks
8. ❌ Implementation steps as AC → Write user-facing outcomes
9. ❌ Silently expanding scope → Ask user first on scope changes
10. ❌ Using `--plain` on create/edit → Only use on view/list/search
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/knowns-task-and-doc-management/raw