knowns 0.8.3 → 0.8.5

package/dist/mcp/server.js

@@ -33128,19 +33128,22 @@ async function handleSearchDocs(args) {
 var core_rules_default = '# Core Rules\n\nYou MUST follow these rules. If you cannot follow any rule, stop and ask for guidance before proceeding.\n\n---\n\n## \u{1F3AF} The Golden Rule\n\n**If you want to change ANYTHING in a task or doc, use CLI commands or MCP tools. NEVER edit .md files directly.**\n\nWhy? Direct file editing breaks metadata synchronization, Git tracking, and relationships.\n\n---\n\n## \u26A0\uFE0F CRITICAL: The -a Flag Confusion\n\nThe `-a` flag means DIFFERENT things in different commands:\n\n| Command | `-a` Means | NOT This! |\n|---------|------------|-----------|\n| `task create` | `--assignee` (assign user) | ~~acceptance criteria~~ |\n| `task edit` | `--assignee` (assign user) | ~~acceptance criteria~~ |\n| `doc edit` | `--append` (append content) | ~~assignee~~ |\n\n### Acceptance Criteria: Use --ac\n\n```bash\n# \u274C WRONG: -a is assignee, NOT acceptance criteria!\nknowns task edit 35 -a "- [ ] Criterion"    # Sets assignee to garbage!\nknowns task create "Title" -a "Criterion"   # Sets assignee to garbage!\n\n# \u2705 CORRECT: Use --ac for acceptance criteria\nknowns task edit 35 --ac "Criterion one"\nknowns task edit 35 --ac "Criterion two"\nknowns task create "Title" --ac "Criterion one" --ac "Criterion two"\n```\n\n---\n\n## Core Principles\n\n| Rule | Description |\n|------|-------------|\n| **CLI/MCP Only** | Use commands for ALL operations. NEVER edit .md files directly |\n| **Docs First** | Read project docs BEFORE planning or coding |\n| **Time Tracking** | Always start timer when taking task, stop when done |\n| **Plan Approval** | Share plan with user, WAIT for approval before coding |\n| **Check AC After Work** | Only mark acceptance criteria done AFTER completing the work |\n\n---\n\n## The --plain Flag\n\n**ONLY for view/list/search commands (NOT create/edit):**\n\n```bash\n# \u2705 CORRECT\nknowns task <id> --plain\nknowns task list --plain\nknowns doc "path" --plain\nknowns doc list --plain\nknowns search "query" --plain\n\n# \u274C WRONG (create/edit don\'t support --plain)\nknowns task create "Title" --plain       # ERROR!\nknowns task edit <id> -s done --plain    # ERROR!\nknowns doc create "Title" --plain        # ERROR!\nknowns doc edit "name" -c "..." --plain  # ERROR!\n```\n\n---\n\n## Reference System\n\n| Context | Task Format | Doc Format |\n|---------|-------------|------------|\n| **Writing** (input) | `@task-<id>` | `@doc/<path>` |\n| **Reading** (output) | `@.knowns/tasks/task-<id>` | `@.knowns/docs/<path>.md` |\n\nFollow refs recursively until complete context gathered.\n\n---\n\n## Task IDs\n\n| Format | Example | Notes |\n|--------|---------|-------|\n| Sequential | `48`, `49` | Legacy numeric |\n| Hierarchical | `48.1`, `48.2` | Legacy subtasks |\n| Random | `qkh5ne` | Current (6-char) |\n\n**CRITICAL:** Use raw ID for `--parent`:\n```bash\n# \u2705 CORRECT\nknowns task create "Title" --parent 48\n\n# \u274C WRONG\nknowns task create "Title" --parent task-48\n```\n\n---\n\n## Status & Priority\n\n| Status | When |\n|--------|------|\n| `todo` | Not started (default) |\n| `in-progress` | Currently working |\n| `in-review` | PR submitted |\n| `blocked` | Waiting on dependency |\n| `done` | All criteria met |\n\n| Priority | Level |\n|----------|-------|\n| `low` | Nice-to-have |\n| `medium` | Normal (default) |\n| `high` | Urgent |\n';
 
 // src/templates/guidelines/commands-reference.md
-var commands_reference_default = '# CLI Commands Reference\n\nComplete reference for all Knowns CLI commands.\n\n---\n\n## Task Commands\n\n### task create\n\n```\nknowns task create <title> [options]\n```\n\n| Flag | Short | Purpose | Example |\n|------|-------|---------|---------|\n| `--description` | `-d` | Task description | `-d "Fix the login bug"` |\n| `--ac` | | Acceptance criterion (repeatable) | `--ac "User can login"` |\n| `--labels` | `-l` | Comma-separated labels | `-l "bug,urgent"` |\n| `--assignee` | `-a` | Assign to user | `-a @username` |\n| `--priority` | | low/medium/high | `--priority high` |\n| `--status` | `-s` | Initial status | `-s todo` |\n| `--parent` | | Parent task ID (raw ID only!) | `--parent 48` |\n\n**Example:**\n```bash\nknowns task create "Fix login timeout" \\\n  -d "Users experience timeout on slow networks" \\\n  --ac "Login works on 3G connection" \\\n  --ac "Timeout increased to 30s" \\\n  -l "bug,auth" \\\n  --priority high\n```\n\n---\n\n### task edit\n\n```\nknowns task edit <id> [options]\n```\n\n| Flag | Short | Purpose | Example |\n|------|-------|---------|---------|\n| `--title` | `-t` | Change title | `-t "New title"` |\n| `--description` | `-d` | Change description | `-d "New desc"` |\n| `--status` | `-s` | Change status | `-s in-progress` |\n| `--priority` | | Change priority | `--priority high` |\n| `--labels` | `-l` | Set labels | `-l "bug,urgent"` |\n| `--assignee` | `-a` | Assign user \u26A0\uFE0F | `-a @username` |\n| `--parent` | | Move to parent | `--parent 48` |\n| `--ac` | | Add acceptance criterion | `--ac "New criterion"` |\n| `--check-ac` | | Mark AC done (1-indexed) | `--check-ac 1` |\n| `--uncheck-ac` | | Unmark AC (1-indexed) | `--uncheck-ac 1` |\n| `--remove-ac` | | Delete AC (1-indexed) | `--remove-ac 3` |\n| `--plan` | | Set implementation plan | `--plan "1. Step one"` |\n| `--notes` | | Replace notes | `--notes "Summary"` |\n| `--append-notes` | | Add to notes | `--append-notes "\u2713 Done"` |\n\n**\u26A0\uFE0F WARNING:** `-a` is assignee, NOT acceptance criteria! Use `--ac` for AC.\n\n**Examples:**\n```bash\n# Take task\nknowns task edit abc123 -s in-progress -a @me\n\n# Add acceptance criteria (use --ac, NOT -a!)\nknowns task edit abc123 --ac "Feature works offline"\n\n# Check criteria as done (1-indexed)\nknowns task edit abc123 --check-ac 1 --check-ac 2\n\n# Add implementation plan\nknowns task edit abc123 --plan $\'1. Research\\n2. Implement\\n3. Test\'\n\n# Add progress notes\nknowns task edit abc123 --append-notes "\u2713 Completed research phase"\n\n# Complete task\nknowns task edit abc123 -s done\n```\n\n---\n\n### task view/list\n\n```bash\n# View single task (ALWAYS use --plain for AI)\nknowns task <id> --plain\nknowns task view <id> --plain\n\n# List tasks\nknowns task list --plain\nknowns task list --status in-progress --plain\nknowns task list --assignee @me --plain\nknowns task list --tree --plain\n```\n\n---\n\n## Doc Commands\n\n### doc create\n\n```\nknowns doc create <title> [options]\n```\n\n| Flag | Short | Purpose | Example |\n|------|-------|---------|---------|\n| `--description` | `-d` | Description | `-d "API reference"` |\n| `--tags` | `-t` | Comma-separated tags | `-t "api,reference"` |\n| `--folder` | `-f` | Folder path | `-f "guides"` |\n\n**Example:**\n```bash\nknowns doc create "API Reference" \\\n  -d "REST API documentation" \\\n  -t "api,docs" \\\n  -f "api"\n```\n\n---\n\n### doc edit\n\n```\nknowns doc edit <name> [options]\n```\n\n| Flag | Short | Purpose | Example |\n|------|-------|---------|---------|\n| `--title` | `-t` | Change title | `-t "New Title"` |\n| `--description` | `-d` | Change description | `-d "New desc"` |\n| `--tags` | | Set tags | `--tags "new,tags"` |\n| `--content` | `-c` | Replace content | `-c "New content"` |\n| `--append` | `-a` | Append content \u26A0\uFE0F | `-a "Added section"` |\n| `--content-file` | | Content from file | `--content-file ./content.md` |\n| `--append-file` | | Append from file | `--append-file ./more.md` |\n\n**\u26A0\uFE0F NOTE:** In doc edit, `-a` means append content, NOT assignee!\n\n**Examples:**\n```bash\n# Replace content\nknowns doc edit "readme" -c "# New Content"\n\n# Append content\nknowns doc edit "readme" -a "## New Section"\n```\n\n---\n\n### doc view/list\n\n```bash\n# View doc (ALWAYS use --plain for AI)\nknowns doc <path> --plain\nknowns doc view "<path>" --plain\n\n# List docs\nknowns doc list --plain\nknowns doc list --tag api --plain\nknowns doc list "guides/" --plain\n```\n\n---\n\n## Time Commands\n\n```bash\n# Start timer (REQUIRED when taking task)\nknowns time start <taskId>\n\n# Stop timer (REQUIRED when completing task)\nknowns time stop\n\n# Pause/resume\nknowns time pause\nknowns time resume\n\n# Check status\nknowns time status\n\n# Manual entry\nknowns time add <taskId> <duration> -n "Note" -d "2025-01-01"\n# duration: "2h", "30m", "1h30m"\n\n# Report\nknowns time report --from "2025-01-01" --to "2025-12-31"\n```\n\n---\n\n## Search Commands\n\n```bash\n# Search everything\nknowns search "query" --plain\n\n# Search by type\nknowns search "auth" --type task --plain\nknowns search "api" --type doc --plain\n\n# Filter by status/priority\nknowns search "bug" --type task --status in-progress --priority high --plain\n```\n\n---\n\n## Multi-line Input\n\nDifferent shells handle multi-line strings differently:\n\n**Bash/Zsh (ANSI-C quoting):**\n```bash\nknowns task edit <id> --plan $\'1. Step one\\n2. Step two\\n3. Step three\'\n```\n\n**PowerShell:**\n```powershell\nknowns task edit <id> --plan "1. Step one`n2. Step two`n3. Step three"\n```\n\n**Cross-platform (heredoc):**\n```bash\nknowns task edit <id> --plan "$(cat <<EOF\n1. Step one\n2. Step two\n3. Step three\nEOF\n)"\n```\n\n---\n\n## MCP Tools (Alternative to CLI)\n\n| Action | MCP Tool |\n|--------|----------|\n| List tasks | `list_tasks({})` |\n| Get task | `get_task({ taskId })` |\n| Create task | `create_task({ title, description, priority, labels })` |\n| Update task | `update_task({ taskId, status, assignee, plan, notes })` |\n| Search tasks | `search_tasks({ query })` |\n| List docs | `list_docs({})` |\n| Get doc | `get_doc({ path })` |\n| Create doc | `create_doc({ title, description, tags, folder })` |\n| Update doc | `update_doc({ path, content, appendContent })` |\n| Start timer | `start_time({ taskId })` |\n| Stop timer | `stop_time({ taskId })` |\n\n**Note:** MCP does NOT support acceptance criteria operations. Use CLI:\n```bash\nknowns task edit <id> --ac "criterion"\nknowns task edit <id> --check-ac 1\n```\n';
+var commands_reference_default = '# Commands Reference\n\n## task create\n\n```bash\nknowns task create <title> [options]\n```\n\n| Flag | Short | Purpose |\n|------|-------|---------|\n| `--description` | `-d` | Task description |\n| `--ac` | | Acceptance criterion (repeatable) |\n| `--labels` | `-l` | Comma-separated labels |\n| `--assignee` | `-a` | Assign to user \u26A0\uFE0F |\n| `--priority` | | low/medium/high |\n| `--status` | `-s` | Initial status |\n| `--parent` | | Parent task ID (raw ID only!) |\n\n**\u26A0\uFE0F `-a` = assignee, NOT acceptance criteria! Use `--ac` for AC.**\n\n---\n\n## task edit\n\n```bash\nknowns task edit <id> [options]\n```\n\n| Flag | Short | Purpose |\n|------|-------|---------|\n| `--title` | `-t` | Change title |\n| `--description` | `-d` | Change description |\n| `--status` | `-s` | Change status |\n| `--priority` | | Change priority |\n| `--labels` | `-l` | Set labels |\n| `--assignee` | `-a` | Assign user \u26A0\uFE0F |\n| `--parent` | | Move to parent |\n| `--ac` | | Add acceptance criterion |\n| `--check-ac` | | Mark AC done (1-indexed) |\n| `--uncheck-ac` | | Unmark AC (1-indexed) |\n| `--remove-ac` | | Delete AC (1-indexed) |\n| `--plan` | | Set implementation plan |\n| `--notes` | | Replace notes |\n| `--append-notes` | | Add to notes |\n\n**\u26A0\uFE0F `-a` = assignee, NOT acceptance criteria! Use `--ac` for AC.**\n\n---\n\n## task view/list\n\n```bash\nknowns task <id> --plain              # View single task\nknowns task list --plain              # List all\nknowns task list --status in-progress --plain\nknowns task list --assignee @me --plain\nknowns task list --tree --plain       # Tree hierarchy\n```\n\n---\n\n## doc create\n\n```bash\nknowns doc create <title> [options]\n```\n\n| Flag | Short | Purpose |\n|------|-------|---------|\n| `--description` | `-d` | Description |\n| `--tags` | `-t` | Comma-separated tags |\n| `--folder` | `-f` | Folder path |\n\n---\n\n## doc edit\n\n```bash\nknowns doc edit <name> [options]\n```\n\n| Flag | Short | Purpose |\n|------|-------|---------|\n| `--title` | `-t` | Change title |\n| `--description` | `-d` | Change description |\n| `--tags` | | Set tags |\n| `--content` | `-c` | Replace content |\n| `--append` | `-a` | Append content \u26A0\uFE0F |\n| `--content-file` | | Content from file |\n| `--append-file` | | Append from file |\n\n**\u26A0\uFE0F In doc edit, `-a` = append content, NOT assignee!**\n\n---\n\n## doc view/list\n\n```bash\nknowns doc <path> --plain             # View single doc\nknowns doc list --plain               # List all\nknowns doc list --tag api --plain     # Filter by tag\n```\n\n---\n\n## time\n\n```bash\nknowns time start <id>    # REQUIRED when taking task\nknowns time stop          # REQUIRED when completing\nknowns time pause\nknowns time resume\nknowns time status\nknowns time add <id> <duration> -n "Note" -d "2025-01-01"\n```\n\n---\n\n## search\n\n```bash\nknowns search "query" --plain\nknowns search "auth" --type task --plain\nknowns search "api" --type doc --plain\nknowns search "bug" --type task --status in-progress --priority high --plain\n```\n\n---\n\n## Multi-line Input (Bash/Zsh)\n\n```bash\nknowns task edit <id> --plan $\'1. Step\\n2. Step\\n3. Step\'\n```\n';
 
 // src/templates/guidelines/workflow-completion.md
-var workflow_completion_default = '# Task Completion Workflow\n\nGuide for properly completing tasks.\n\n---\n\n## Definition of Done\n\nA task is **Done** ONLY when **ALL** of the following are complete:\n\n### \u2705 Via CLI Commands\n\n| Requirement | Command | Status |\n|-------------|---------|--------|\n| All AC checked | `knowns task edit <id> --check-ac N` | Required |\n| Implementation notes added | `knowns task edit <id> --notes "..."` | Required |\n| Timer stopped | `knowns time stop` | Required |\n| Status set to done | `knowns task edit <id> -s done` | Required |\n\n### \u2705 Via Code/Testing\n\n| Requirement | Action | Status |\n|-------------|--------|--------|\n| Tests pass | Run test suite | Required |\n| No regressions | Verify existing functionality | Required |\n| Docs updated | Update relevant documentation | If applicable |\n| Code reviewed | Self-review changes | Required |\n\n---\n\n## Completion Steps\n\n### Step 1: Verify All Acceptance Criteria\n\n```bash\n# View the task to check AC status\nknowns task <id> --plain\n\n# Ensure ALL criteria are checked\n# If any are unchecked, complete the work first!\n```\n\n### Step 2: Add Implementation Notes\n\nWrite notes suitable for a PR description:\n\n```bash\nknowns task edit <id> --notes $\'## Summary\nImplemented JWT authentication using jsonwebtoken library.\n\n## Changes\n- Added auth middleware in src/middleware/auth.ts\n- Added /login and /refresh endpoints\n- Created JWT utility functions\n\n## Tests\n- Added 15 unit tests\n- Coverage: 94%\n\n## Notes\n- Chose HS256 algorithm for simplicity\n- Token expiry set to 1 hour as per requirements\'\n```\n\n**Good notes include:**\n- What was implemented\n- Key decisions and why\n- Files changed\n- Test coverage\n- Any follow-up needed\n\n### Step 3: Stop Timer\n\n```bash\nknowns time stop\n```\n\n**\u26A0\uFE0F CRITICAL:** Never forget to stop the timer!\n\nIf you forgot to stop earlier, add manual entry:\n```bash\nknowns time add <id> 2h -n "Forgot to stop timer"\n```\n\n### Step 4: Mark as Done\n\n```bash\nknowns task edit <id> -s done\n```\n\n---\n\n## Post-Completion Changes\n\nIf the user requests changes **AFTER** the task is marked done:\n\n```bash\n# 1. Reopen task\nknowns task edit <id> -s in-progress\n\n# 2. Restart timer\nknowns time start <id>\n\n# 3. Add AC for the changes\nknowns task edit <id> --ac "Post-completion fix: description"\n\n# 4. Document why reopened\nknowns task edit <id> --append-notes "\u{1F504} Reopened: User requested changes - reason"\n\n# 5. Complete the work, then follow completion steps again\n```\n\n---\n\n## Knowledge Extraction\n\nAfter completing a task, consider if any knowledge should be documented:\n\n```bash\n# Search if similar pattern already documented\nknowns search "pattern-name" --type doc --plain\n\n# If new reusable knowledge, create doc\nknowns doc create "Pattern: Name" \\\n  -d "Reusable pattern from task implementation" \\\n  -t "pattern" \\\n  -f "patterns"\n\n# Reference source task\nknowns doc edit "patterns/name" -a "Source: @task-<id>"\n```\n\n**Extract knowledge when:**\n- New patterns/conventions discovered\n- Common error solutions found\n- Reusable code approaches identified\n- Integration patterns documented\n\n**Don\'t extract:**\n- Task-specific details (those belong in implementation notes)\n- One-off solutions\n\n---\n\n## Common Mistakes\n\n### \u274C Marking done without all AC checked\n\n```bash\n# \u274C Wrong: AC not all checked\nknowns task edit <id> -s done\n\n# \u2705 Right: Check all AC first\nknowns task edit <id> --check-ac 1 --check-ac 2 --check-ac 3\nknowns task edit <id> -s done\n```\n\n### \u274C Forgetting to stop timer\n\nTimer keeps running! Always stop when done:\n```bash\nknowns time stop\n```\n\n### \u274C No implementation notes\n\nNotes are required for PR description:\n```bash\n# \u274C Wrong: No notes\nknowns task edit <id> -s done\n\n# \u2705 Right: Add notes first\nknowns task edit <id> --notes "Summary of what was done"\nknowns task edit <id> -s done\n```\n\n### \u274C Autonomously creating follow-up tasks\n\nAfter completing work, **present** follow-up ideas to the user. Don\'t automatically create new tasks without permission.\n\n---\n\n## Completion Checklist\n\nBefore marking done, verify:\n\n- [ ] All acceptance criteria are checked (`--check-ac`)\n- [ ] Implementation notes are added (`--notes`)\n- [ ] Implementation plan reflects final approach\n- [ ] Tests pass without regressions\n- [ ] Documentation updated if needed\n- [ ] Timer stopped (`knowns time stop`)\n- [ ] Status set to done (`-s done`)\n';
+var workflow_completion_default = '# Task Completion\n\n## Definition of Done\n\nA task is **Done** when ALL of these are complete:\n\n| Requirement | Command |\n|-------------|---------|\n| All AC checked | `knowns task edit <id> --check-ac N` |\n| Notes added | `knowns task edit <id> --notes "Summary"` |\n| Timer stopped | `knowns time stop` |\n| Status = done | `knowns task edit <id> -s done` |\n| Tests pass | Run test suite |\n\n---\n\n## Completion Steps\n\n```bash\n# 1. Verify all AC are checked\nknowns task <id> --plain\n\n# 2. Add implementation notes\nknowns task edit <id> --notes $\'## Summary\nWhat was done and key decisions.\'\n\n# 3. Stop timer (REQUIRED!)\nknowns time stop\n\n# 4. Mark done\nknowns task edit <id> -s done\n```\n\n---\n\n## Post-Completion Changes\n\nIf user requests changes after task is done:\n\n```bash\nknowns task edit <id> -s in-progress    # Reopen\nknowns time start <id>                   # Restart timer\nknowns task edit <id> --ac "Fix: description"\nknowns task edit <id> --append-notes "\u{1F504} Reopened: reason"\n# Complete work, then follow completion steps again\n```\n\n---\n\n## Checklist\n\n- [ ] All AC checked (`--check-ac`)\n- [ ] Notes added (`--notes`)\n- [ ] Timer stopped (`time stop`)\n- [ ] Tests pass\n- [ ] Status = done (`-s done`)\n';
 
 // src/templates/guidelines/workflow-creation.md
-var workflow_creation_default = '# Task Creation Workflow\n\nGuide for creating well-structured tasks.\n\n---\n\n## Step 1: Search First\n\nBefore creating a new task, check if similar work already exists:\n\n```bash\n# Search for existing tasks\nknowns search "keyword" --type task --plain\n\n# List tasks by status\nknowns task list --status todo --plain\nknowns task list --status in-progress --plain\n```\n\n**Why?** Avoid duplicate work and understand existing context.\n\n---\n\n## Step 2: Assess Scope\n\nAsk yourself:\n- Does this work fit in one PR?\n- Does it span multiple systems?\n- Are there natural breaking points?\n\n**Single task:** Work is focused, affects one area\n**Multiple tasks:** Work spans different subsystems or has phases\n\n---\n\n## Step 3: Create with Proper Structure\n\n### Basic Task Creation\n\n```bash\nknowns task create "Clear title describing what needs to be done" \\\n  -d "Description explaining WHY this is needed" \\\n  --ac "First acceptance criterion" \\\n  --ac "Second acceptance criterion" \\\n  --priority medium \\\n  -l "label1,label2"\n```\n\n### Creating Subtasks\n\n```bash\n# Create parent task first\nknowns task create "Parent feature"\n\n# Create subtasks (use raw ID, not task-XX)\nknowns task create "Subtask 1" --parent 48\nknowns task create "Subtask 2" --parent 48\n```\n\n---\n\n## Task Quality Guidelines\n\n### Title (The "what")\n\nClear, brief summary of the task.\n\n| \u274C Bad | \u2705 Good |\n|--------|---------|\n| Do auth stuff | Add JWT authentication |\n| Fix bug | Fix login timeout on slow networks |\n| Update docs | Document rate limiting in API.md |\n\n### Description (The "why")\n\nExplains context and purpose. Include doc references.\n\n```markdown\nWe need JWT authentication because sessions don\'t scale\nfor our microservices architecture.\n\nRelated: @doc/security-patterns, @doc/api-guidelines\n```\n\n### Acceptance Criteria (The "what" - outcomes)\n\n**Key Principles:**\n- **Outcome-oriented** - Focus on results, not implementation\n- **Testable** - Can be objectively verified\n- **User-focused** - Frame from end-user perspective\n\n| \u274C Bad (Implementation details) | \u2705 Good (Outcomes) |\n|--------------------------------|-------------------|\n| Add function handleLogin() in auth.ts | User can login and receive JWT token |\n| Use bcrypt for hashing | Passwords are securely hashed |\n| Add try-catch blocks | Errors return appropriate HTTP status codes |\n\n---\n\n## Anti-Patterns to Avoid\n\n### \u274C Don\'t create overly broad tasks\n\n```bash\n# \u274C Too broad - too many ACs\nknowns task create "Build entire auth system" \\\n  --ac "Login" --ac "Logout" --ac "Register" \\\n  --ac "Password reset" --ac "OAuth" --ac "2FA"\n\n# \u2705 Better - split into focused tasks\nknowns task create "Implement user login" --ac "User can login with email/password"\nknowns task create "Implement user registration" --ac "User can create account"\n```\n\n### \u274C Don\'t embed implementation steps in AC\n\n```bash\n# \u274C Implementation steps as AC\n--ac "Create auth.ts file"\n--ac "Add bcrypt dependency"\n--ac "Write handleLogin function"\n\n# \u2705 Outcome-focused AC\n--ac "User can login with valid credentials"\n--ac "Invalid credentials return 401 error"\n--ac "Successful login returns JWT token"\n```\n\n### \u274C Don\'t skip search\n\nAlways search for existing tasks first. You might find:\n- Duplicate task already exists\n- Related task with useful context\n- Completed task with reusable patterns\n\n---\n\n## Report Results\n\nAfter creating tasks, show the user:\n- Task ID\n- Title\n- Description summary\n- Acceptance criteria\n\nThis allows for feedback and corrections before work begins.\n';
+var workflow_creation_default = '# Task Creation\n\n## Before Creating\n\n```bash\n# Search for existing tasks first\nknowns search "keyword" --type task --plain\n```\n\n---\n\n## Create Task\n\n```bash\nknowns task create "Clear title (WHAT)" \\\n  -d "Description (WHY)" \\\n  --ac "Outcome 1" \\\n  --ac "Outcome 2" \\\n  --priority medium \\\n  -l "labels"\n```\n\n---\n\n## Quality Guidelines\n\n### Title\n| \u274C Bad | \u2705 Good |\n|--------|---------|\n| Do auth stuff | Add JWT authentication |\n| Fix bug | Fix login timeout |\n\n### Description\nExplain WHY. Include doc refs: `@doc/security-patterns`\n\n### Acceptance Criteria\n**Outcome-focused, NOT implementation steps:**\n\n| \u274C Bad | \u2705 Good |\n|--------|---------|\n| Add handleLogin() function | User can login |\n| Use bcrypt | Passwords are hashed |\n| Add try-catch | Errors return proper HTTP codes |\n\n---\n\n## Subtasks\n\n```bash\nknowns task create "Parent task"\nknowns task create "Subtask" --parent 48  # Raw ID only!\n```\n\n---\n\n## Anti-Patterns\n\n- \u274C Too many AC in one task \u2192 Split into multiple tasks\n- \u274C Implementation steps as AC \u2192 Write outcomes instead\n- \u274C Skip search \u2192 Always check existing tasks first\n';
 
 // src/templates/guidelines/workflow-execution.md
-var workflow_execution_default = '# Task Execution Workflow\n\nGuide for implementing tasks effectively.\n\n---\n\n## Step 1: Take the Task\n\nThe **first things** you must do when taking a task:\n\n```bash\n# Set status to in-progress and assign to yourself\nknowns task edit <id> -s in-progress -a @me\n\n# Start time tracking (REQUIRED!)\nknowns time start <id>\n```\n\n---\n\n## Step 2: Research & Understand\n\nBefore planning, gather complete context:\n\n```bash\n# Read the task details\nknowns task <id> --plain\n\n# Follow ALL refs in the task\n# @.knowns/docs/xxx.md \u2192 knowns doc "xxx" --plain\n# @.knowns/tasks/task-YY \u2192 knowns task YY --plain\n\n# Search for related documentation\nknowns search "keyword" --type doc --plain\n\n# Check similar completed tasks for patterns\nknowns search "keyword" --type task --status done --plain\n```\n\n**Why?** Understanding existing patterns prevents reinventing the wheel.\n\n---\n\n## Step 3: Create Implementation Plan\n\nCapture your plan in the task **BEFORE writing any code**.\n\n```bash\nknowns task edit <id> --plan $\'1. Research existing patterns (see @doc/xxx)\n2. Design approach\n3. Implement core functionality\n4. Add tests\n5. Update documentation\'\n```\n\n### \u26A0\uFE0F CRITICAL: Wait for Approval\n\n**Share the plan with the user and WAIT for explicit approval before coding.**\n\nDo not begin implementation until:\n- User approves the plan, OR\n- User explicitly tells you to skip review\n\n---\n\n## Step 4: Implement\n\nWork through your plan step by step:\n\n### Document Progress\n\n```bash\n# After completing each significant piece of work\nknowns task edit <id> --append-notes "\u2713 Completed: research phase"\nknowns task edit <id> --append-notes "\u2713 Completed: core implementation"\n```\n\n### Check Acceptance Criteria\n\nOnly mark AC as done **AFTER** the work is actually complete:\n\n```bash\n# After completing work for AC #1\nknowns task edit <id> --check-ac 1\n\n# After completing work for AC #2\nknowns task edit <id> --check-ac 2\n```\n\n**\u26A0\uFE0F CRITICAL:** Never check AC before the work is done. ACs represent completed outcomes.\n\n---\n\n## Scope Management\n\n### When New Requirements Emerge\n\nIf you discover additional work needed during implementation:\n\n**Option 1: Add to current task (if small)**\n```bash\nknowns task edit <id> --ac "New requirement discovered"\nknowns task edit <id> --append-notes "\u26A0\uFE0F Scope updated: Added requirement for X"\n```\n\n**Option 2: Create follow-up task (if significant)**\n```bash\nknowns task create "Follow-up: Additional feature" -d "Discovered during task <id>"\nknowns task edit <id> --append-notes "\u{1F4DD} Created follow-up task for X"\n```\n\n**\u26A0\uFE0F CRITICAL:** Stop and ask the user which option to use. Don\'t silently expand scope.\n\n---\n\n## Plan Updates\n\nIf your approach changes during implementation, update the plan:\n\n```bash\nknowns task edit <id> --plan $\'1. [DONE] Research\n2. [DONE] Original approach\n3. [CHANGED] New approach due to X\n4. Remaining work\'\n```\n\nThe plan should remain the **single source of truth** for how the task was solved.\n\n---\n\n## Handling Subtasks\n\n### When Assigned "Parent and All Subtasks"\n\nProceed sequentially without asking permission between each subtask:\n\n1. Complete subtask 1\n2. Complete subtask 2\n3. Continue until all done\n\n### When Assigned Single Subtask\n\nPresent progress and request guidance before advancing to the next subtask.\n\n---\n\n## Key Principles\n\n1. **Plan before code** - Always capture approach before implementation\n2. **Document decisions** - Record why you chose certain approaches\n3. **Update on changes** - Keep plan current if approach shifts\n4. **Ask on scope** - Don\'t silently expand work\n5. **Check AC after work** - Only mark done when truly complete\n';
+var workflow_execution_default = '# Task Execution\n\n## Step 1: Take Task\n\n```bash\nknowns task edit <id> -s in-progress -a @me\nknowns time start <id>    # REQUIRED!\n```\n\n---\n\n## Step 2: Research\n\n```bash\n# Read task and follow ALL refs\nknowns task <id> --plain\n# @.knowns/docs/xxx.md \u2192 knowns doc "xxx" --plain\n# @.knowns/tasks/task-YY \u2192 knowns task YY --plain\n\n# Search related docs\nknowns search "keyword" --type doc --plain\n\n# Check similar done tasks\nknowns search "keyword" --type task --status done --plain\n```\n\n---\n\n## Step 3: Plan (BEFORE coding!)\n\n```bash\nknowns task edit <id> --plan $\'1. Research (see @doc/xxx)\n2. Implement\n3. Test\n4. Document\'\n```\n\n**\u26A0\uFE0F Share plan with user. WAIT for approval before coding.**\n\n---\n\n## Step 4: Implement\n\n```bash\n# Check AC only AFTER work is done\nknowns task edit <id> --check-ac 1\nknowns task edit <id> --append-notes "\u2713 Done: feature X"\n```\n\n---\n\n## Scope Changes\n\nIf new requirements emerge during work:\n\n```bash\n# Small: Add to current task\nknowns task edit <id> --ac "New requirement"\nknowns task edit <id> --append-notes "\u26A0\uFE0F Scope updated: reason"\n\n# Large: Ask user first, then create follow-up\nknowns task create "Follow-up: feature" -d "From task <id>"\n```\n\n**\u26A0\uFE0F Don\'t silently expand scope. Ask user first.**\n\n---\n\n## Key Rules\n\n1. **Plan before code** - Capture approach first\n2. **Wait for approval** - Don\'t start without OK\n3. **Check AC after work** - Not before\n4. **Ask on scope changes** - Don\'t expand silently\n';
 
 // src/templates/guidelines/common-mistakes.md
-var common_mistakes_default = '# Common Mistakes\n\nAnti-patterns and common errors to avoid.\n\n---\n\n## \u26A0\uFE0F CRITICAL: Flag Confusion\n\n### The -a Flag Means Different Things!\n\n| Command | `-a` Flag Means | NOT This! |\n|---------|-----------------|-----------|\n| `task create` | `--assignee` (assign user) | ~~acceptance criteria~~ |\n| `task edit` | `--assignee` (assign user) | ~~acceptance criteria~~ |\n| `doc edit` | `--append` (append content) | ~~assignee~~ |\n\n### \u274C WRONG: Using -a for Acceptance Criteria\n\n```bash\n# \u274C WRONG: -a is assignee, sets assignee to garbage text!\nknowns task edit 35 -a "- [ ] Criterion"\nknowns task edit 35 -a "User can login"\nknowns task create "Title" -a "Criterion text"\n```\n\n### \u2705 CORRECT: Using --ac for Acceptance Criteria\n\n```bash\n# \u2705 CORRECT: Use --ac for acceptance criteria\nknowns task edit 35 --ac "Criterion one"\nknowns task edit 35 --ac "Criterion two"\nknowns task create "Title" --ac "Criterion one" --ac "Criterion two"\n```\n\n---\n\n## Quick Reference: DO vs DON\'T\n\n### File Operations\n\n| \u274C DON\'T | \u2705 DO |\n|----------|-------|\n| Edit .md files directly | Use CLI commands |\n| Change `- [ ]` to `- [x]` in file | `--check-ac <index>` |\n| Add notes directly to file | `--notes` or `--append-notes` |\n| Edit frontmatter manually | Use CLI flags |\n\n### Task Operations\n\n| \u274C DON\'T | \u2705 DO |\n|----------|-------|\n| `-a "criterion"` (assignee!) | `--ac "criterion"` |\n| `--parent task-48` | `--parent 48` (raw ID) |\n| Skip time tracking | Always `time start`/`time stop` |\n| Check AC before work done | Check AC AFTER completing work |\n| Code before plan approval | Wait for user approval |\n| Code before reading docs | Read ALL related docs first |\n\n### Flag Usage\n\n| \u274C DON\'T | \u2705 DO |\n|----------|-------|\n| `--plain` with create | `--plain` only for view/list/search |\n| `--plain` with edit | `--plain` only for view/list/search |\n| `--criteria "text"` | `--ac "text"` |\n| `-ac "text"` | `--ac "text"` (two dashes!) |\n\n---\n\n## Detailed Mistakes\n\n### 1. Direct File Editing\n\n```markdown\n# \u274C DON\'T DO THIS:\n1. Open backlog/tasks/task-7.md in editor\n2. Change "- [ ]" to "- [x]" manually\n3. Add notes directly to the file\n4. Save the file\n\n# \u2705 DO THIS INSTEAD:\nknowns task edit 7 --check-ac 1\nknowns task edit 7 --notes "Implementation complete"\n```\n\n**Why?** Direct editing breaks:\n- Metadata synchronization\n- Git tracking\n- Task relationships\n\n### 2. Wrong Flag for Acceptance Criteria\n\n```bash\n# \u274C WRONG: All these set assignee, NOT acceptance criteria\nknowns task edit 35 -a "Criterion"\nknowns task create "Title" -a "AC text"\nknowns task edit 35 --assignee "Criterion"  # Still wrong!\n\n# \u2705 CORRECT: Use --ac\nknowns task edit 35 --ac "Criterion"\nknowns task create "Title" --ac "AC text"\n```\n\n### 3. Wrong Task ID Format for Parent\n\n```bash\n# \u274C WRONG: Don\'t prefix with "task-"\nknowns task create "Title" --parent task-48\nknowns task edit 35 --parent task-48\n\n# \u2705 CORRECT: Use raw ID only\nknowns task create "Title" --parent 48\nknowns task edit 35 --parent qkh5ne\n```\n\n### 4. Using --plain with Create/Edit\n\n```bash\n# \u274C WRONG: create/edit don\'t support --plain\nknowns task create "Title" --plain       # ERROR!\nknowns task edit 35 -s done --plain      # ERROR!\nknowns doc create "Title" --plain        # ERROR!\nknowns doc edit "name" -c "..." --plain  # ERROR!\n\n# \u2705 CORRECT: --plain only for view/list/search\nknowns task 35 --plain                   # OK\nknowns task list --plain                 # OK\nknowns doc "readme" --plain              # OK\nknowns search "query" --plain            # OK\n```\n\n### 5. Skipping Time Tracking\n\n```bash\n# \u274C WRONG: No timer\nknowns task edit 35 -s in-progress\n# ... work ...\nknowns task edit 35 -s done\n\n# \u2705 CORRECT: Always track time\nknowns task edit 35 -s in-progress -a @me\nknowns time start 35\n# ... work ...\nknowns time stop\nknowns task edit 35 -s done\n```\n\n### 6. Checking AC Before Work is Done\n\n```bash\n# \u274C WRONG: Checking AC as a TODO list\nknowns task edit 35 --check-ac 1  # Haven\'t done the work yet!\n# ... then do the work ...\n\n# \u2705 CORRECT: Check AC AFTER completing work\n# ... do the work first ...\nknowns task edit 35 --check-ac 1  # Now it\'s actually done\n```\n\n### 7. Coding Before Plan Approval\n\n```bash\n# \u274C WRONG: Start coding immediately\nknowns task edit 35 -s in-progress\nknowns task edit 35 --plan "1. Do X\\n2. Do Y"\n# Immediately starts coding...\n\n# \u2705 CORRECT: Wait for approval\nknowns task edit 35 -s in-progress\nknowns task edit 35 --plan "1. Do X\\n2. Do Y"\n# STOP! Present plan to user\n# Wait for explicit approval\n# Then start coding\n```\n\n### 8. Ignoring Task References\n\n```bash\n# \u274C WRONG: Don\'t read refs\nknowns task 35 --plain\n# See "@.knowns/docs/api.md" but don\'t read it\n# Start implementing without context...\n\n# \u2705 CORRECT: Follow ALL refs\nknowns task 35 --plain\n# See "@.knowns/docs/api.md"\nknowns doc "api" --plain  # Read it!\n# See "@.knowns/tasks/task-30"\nknowns task 30 --plain    # Read it!\n# Now have full context\n```\n\n---\n\n## Error Recovery\n\n| Problem | Solution |\n|---------|----------|\n| Set assignee to AC text by mistake | `knowns task edit <id> -a @me` to fix |\n| Forgot to stop timer | `knowns time add <id> <duration> -n "Forgot to stop"` |\n| Checked AC too early | `knowns task edit <id> --uncheck-ac <index>` |\n| Task not found | `knowns task list --plain` to find correct ID |\n| AC index out of range | `knowns task <id> --plain` to see AC numbers |\n';
+var common_mistakes_default = '# Common Mistakes\n\n## \u26A0\uFE0F CRITICAL: The -a Flag\n\n| Command | `-a` Means | NOT This! |\n|---------|------------|-----------|\n| `task create/edit` | `--assignee` | ~~acceptance criteria~~ |\n| `doc edit` | `--append` | ~~assignee~~ |\n\n```bash\n# \u274C WRONG (sets assignee to garbage!)\nknowns task edit 35 -a "Criterion text"\n\n# \u2705 CORRECT (use --ac)\nknowns task edit 35 --ac "Criterion text"\n```\n\n---\n\n## Quick Reference\n\n| \u274C DON\'T | \u2705 DO |\n|----------|-------|\n| Edit .md files directly | Use CLI commands |\n| `-a "criterion"` | `--ac "criterion"` |\n| `--parent task-48` | `--parent 48` (raw ID) |\n| `--plain` with create/edit | `--plain` only for view/list |\n| Check AC before work done | Check AC AFTER work done |\n| Code before plan approval | Wait for user approval |\n| Code before reading docs | Read docs FIRST |\n| Skip time tracking | Always `time start`/`stop` |\n| Ignore task refs | Follow ALL `@.knowns/...` refs |\n\n---\n\n## Error Recovery\n\n| Problem | Solution |\n|---------|----------|\n| Set assignee to AC text | `knowns task edit <id> -a @me` |\n| Forgot to stop timer | `knowns time add <id> <duration>` |\n| Checked AC too early | `knowns task edit <id> --uncheck-ac N` |\n| Task not found | `knowns task list --plain` |\n';
+
+// src/templates/guidelines/context-optimization.md
+var context_optimization_default = '# Context Optimization\n\nOptimize your context usage to work more efficiently within token limits.\n\n---\n\n## Output Format\n\n```bash\n# \u274C Verbose output\nknowns task 42 --json\n\n# \u2705 Compact output (always use --plain)\nknowns task 42 --plain\n```\n\n---\n\n## Search Before Read\n\n```bash\n# \u274C Reading all docs to find info\nknowns doc "doc1" --plain\nknowns doc "doc2" --plain\nknowns doc "doc3" --plain\n\n# \u2705 Search first, then read only relevant docs\nknowns search "authentication" --type doc --plain\nknowns doc "security-patterns" --plain  # Only the relevant one\n```\n\n---\n\n## Selective File Reading\n\n```bash\n# \u274C Reading entire large file\nRead file (2000+ lines)\n\n# \u2705 Read specific sections\nRead file with offset=100 limit=50\n```\n\n---\n\n## Compact Notes\n\n```bash\n# \u274C Verbose notes\nknowns task edit 42 --append-notes "I have successfully completed the implementation of the authentication middleware which validates JWT tokens and handles refresh logic..."\n\n# \u2705 Compact notes\nknowns task edit 42 --append-notes "\u2713 Auth middleware + JWT validation done"\n```\n\n---\n\n## Avoid Redundant Operations\n\n| Don\'t | Do Instead |\n|-------|------------|\n| Re-read files already in context | Reference from memory |\n| List tasks/docs multiple times | List once, remember results |\n| Quote entire file contents | Summarize key points |\n| Repeat full error messages | Reference error briefly |\n\n---\n\n## Efficient Workflow\n\n| Phase | Context-Efficient Approach |\n|-------|---------------------------|\n| **Research** | Search \u2192 Read only matches |\n| **Planning** | Brief plan, not detailed prose |\n| **Coding** | Read only files being modified |\n| **Notes** | Bullet points, not paragraphs |\n| **Completion** | Summary, not full log |\n\n---\n\n## Quick Rules\n\n1. **Always `--plain`** - Never use `--json` unless specifically needed\n2. **Search first** - Don\'t read all docs hoping to find info\n3. **Read selectively** - Use offset/limit for large files\n4. **Write concise** - Compact notes, not essays\n5. **Don\'t repeat** - Reference context already loaded\n6. **Summarize** - Key points, not full quotes\n';
 
 // src/templates/guidelines/index.ts
 var CORE_RULES = core_rules_default.trim();
@@ -33149,6 +33152,7 @@ var WORKFLOW_CREATION = workflow_creation_default.trim();
 var WORKFLOW_EXECUTION = workflow_execution_default.trim();
 var WORKFLOW_COMPLETION = workflow_completion_default.trim();
 var COMMON_MISTAKES = common_mistakes_default.trim();
+var CONTEXT_OPTIMIZATION = context_optimization_default.trim();
 var Guidelines = {
   // Core rules - always needed
   core: CORE_RULES,
@@ -33162,6 +33166,8 @@ var Guidelines = {
   },
   // Common mistakes
   mistakes: COMMON_MISTAKES,
+  // Context optimization
+  contextOptimization: CONTEXT_OPTIMIZATION,
   /**
    * Get full guidelines (all sections combined)
    */
@@ -33169,6 +33175,8 @@ var Guidelines = {
     const content = [
       CORE_RULES,
       "---",
+      CONTEXT_OPTIMIZATION,
+      "---",
       COMMANDS_REFERENCE,
       "---",
       WORKFLOW_CREATION,
@@ -33187,16 +33195,16 @@ ${content}
     return content;
   },
   /**
-   * Get compact guidelines (core + mistakes only)
+   * Get compact guidelines (core + context optimization + mistakes only)
    */
   getCompact() {
-    return [CORE_RULES, "---", COMMON_MISTAKES].join("\n\n");
+    return [CORE_RULES, "---", CONTEXT_OPTIMIZATION, "---", COMMON_MISTAKES].join("\n\n");
   },
   /**
    * Get guidelines for specific workflow stage
    */
   getForStage(stage) {
-    const sections = [CORE_RULES, "---"];
+    const sections = [CORE_RULES, "---", CONTEXT_OPTIMIZATION, "---"];
     switch (stage) {
       case "creation":
         sections.push(WORKFLOW_CREATION);