\ -d "Description" \ --tags "tag1,tag2" \ --folder "folder/path" ``` **Structure best practice:** - Use H1 for title only - Use numbered H2 for main sections (`## 1. Overview`) - Use H3 for subsections - Keep sections self-contained ### 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: - `--title` / `-t`: Change title - `--description` / `-d`: Change description - `--status` / `-s`: Change status (todo/in-progress/in-review/blocked/done) - `--priority`: Change priority (low/medium/high) - `--assignee` / `-a`: Assign user ⚠️ - `--ac`: Add acceptance criterion - `--check-ac <number>`: Mark AC done (1-indexed) - `--uncheck-ac <number>`: Unmark AC - `--remove-ac <number>`: Delete AC - `--plan`: Set implementation plan - `--append-notes`: Add to notes ### 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:** - Edit .md files directly - Confuse `-a` flag meanings - Use `--plain` with create/edit commands - Start coding without plan approval - Check AC before doing the work - Create AC that are implementation steps - Expand scope silently - Skip time tracking - Read entire docs without `--smart` ✅ **Do:** - Use CLI commands for everything - Always use `--smart` when reading docs - Search before creating duplicate tasks - Write outcome-focused AC - Ask user before scope changes - Start/stop timers properly - Share plan and wait for approval - Follow doc references recursively ## Task IDs Knowns supports multiple ID formats: - Sequential: `48`, `49` (legacy) - Hierarchical: `48.1`, `48.2` (legacy subtasks) - Random: `qkh5ne` (current 6-char format) **Always use raw ID for `--parent`:** ```bash # ✅ CORRECT knowns task create "Title" --parent 48 # ❌ WRONG knowns task create "Title" --parent task-48 ``` ## Status Values - `todo`: Not started (default) - `in-progress`: Currently working - `in-review`: PR submitted - `blocked`: Waiting on dependency - `done`: All criteria met ## Priority Values - `low`: Nice-to-have - `medium`: Normal (default) - `high`: Urgent ## 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 - Never edit `.knowns/` directory files directly - Always follow the reference chain recursively - Time tracking is mandatory for task work - Plan approval is required before implementation - Use `--smart` flag when reading docs to handle large documents efficiently - Acceptance criteria must be outcome-focused, not implementation steps</article></body></html>

--- name: "Knowns Task Management" description: "AI-first task and documentation management with CLI. Link docs in tasks, track time, manage acceptance criteria, and maintain project knowledge." version: "1.0.0" runtimes: ["copilot"] category: "development" tags: ["task-management", "documentation", "time-tracking", "project-management", "workflow", "knowledge-base", "cli"] --- # 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: - `task create` / `task edit`: `-a` = `--assignee` (assign user), NOT acceptance criteria - `doc edit`: `-a` = `--append` (append content), NOT assignee **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 --plain knowns task list --plain knowns doc "path" --plain --smart # ❌ WRONG knowns task create "Title" --plain # ERROR! knowns task edit -s done --plain # ERROR! ``` ### Reference System **Writing (input):** - Tasks: `@task-` - Docs: `@doc/` **Reading (output):** - Tasks: `@.knowns/tasks/task-` - Docs: `@.knowns/docs/.md` 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:** - Title: Clear and specific (e.g., "Add JWT authentication", NOT "Do auth stuff") - Description: Explain WHY, include doc refs like `@doc/security-patterns` - Acceptance Criteria: Outcome-focused, NOT implementation steps - ✅ Good: "User can login", "Passwords are hashed" - ❌ Bad: "Add handleLogin() function", "Use bcrypt" ### 2. Taking a Task ```bash knowns task edit -s in-progress -a @me knowns time start # REQUIRED! ``` ### 3. Research Phase Read task and follow ALL references: ```bash knowns task --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 --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 --check-ac 1 knowns task edit --append-notes "✓ Done: feature X" ``` If scope changes during work: - **Small changes:** Add to current task with `--ac` and note the reason - **Large changes:** Ask user first, then create follow-up task ### 6. Completion Stop timer and mark task done: ```bash knowns time stop knowns task edit -s done ``` **Definition of Done:** - All acceptance criteria checked - Time tracking stopped - Code reviewed/tested - Documentation updated if needed ## Documentation Management ### Reading Documents (Always Use --smart) **ALWAYS use `--smart` when reading documents:** ```bash knowns doc --plain --smart ``` **Behavior:** - Small doc (≤2000 tokens): Returns full content automatically - Large doc (>2000 tokens): Returns stats + TOC, then use `--section` to read specific parts ### Creating Documents ```bash knowns doc create \ -d "Description" \ --tags "tag1,tag2" \ --folder "folder/path" ``` **Structure best practice:** - Use H1 for title only - Use numbered H2 for main sections (`## 1. Overview`) - Use H3 for subsections - Keep sections self-contained ### 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: - `--title` / `-t`: Change title - `--description` / `-d`: Change description - `--status` / `-s`: Change status (todo/in-progress/in-review/blocked/done) - `--priority`: Change priority (low/medium/high) - `--assignee` / `-a`: Assign user ⚠️ - `--ac`: Add acceptance criterion - `--check-ac <number>`: Mark AC done (1-indexed) - `--uncheck-ac <number>`: Unmark AC - `--remove-ac <number>`: Delete AC - `--plan`: Set implementation plan - `--append-notes`: Add to notes ### 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:** - Edit .md files directly - Confuse `-a` flag meanings - Use `--plain` with create/edit commands - Start coding without plan approval - Check AC before doing the work - Create AC that are implementation steps - Expand scope silently - Skip time tracking - Read entire docs without `--smart` ✅ **Do:** - Use CLI commands for everything - Always use `--smart` when reading docs - Search before creating duplicate tasks - Write outcome-focused AC - Ask user before scope changes - Start/stop timers properly - Share plan and wait for approval - Follow doc references recursively ## Task IDs Knowns supports multiple ID formats: - Sequential: `48`, `49` (legacy) - Hierarchical: `48.1`, `48.2` (legacy subtasks) - Random: `qkh5ne` (current 6-char format) **Always use raw ID for `--parent`:** ```bash # ✅ CORRECT knowns task create "Title" --parent 48 # ❌ WRONG knowns task create "Title" --parent task-48 ``` ## Status Values - `todo`: Not started (default) - `in-progress`: Currently working - `in-review`: PR submitted - `blocked`: Waiting on dependency - `done`: All criteria met ## Priority Values - `low`: Nice-to-have - `medium`: Normal (default) - `high`: Urgent ## 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 - Never edit `.knowns/` directory files directly - Always follow the reference chain recursively - Time tracking is mandatory for task work - Plan approval is required before implementation - Use `--smart` flag when reading docs to handle large documents efficiently - Acceptance criteria must be outcome-focused, not implementation steps</article></body></html>

Marketplace